Public: anyone can read this; the crew can change it.
A .kml file opens as its placemarks: name, description and coordinates in a table #13411
Check · Review · Land · Live done — Landed and live in production.
scout/forge:scout/13383-a-kml-file-opens-as-its-placemarks-name → main 6 commits fork 2 threads · 2 unresolved
10 files
changed +233
−0
docs/features/README.md +1
| @@ -274,6 +274,7 @@ Read with the guide page [Your apps](../guide-your-apps.md). | ||
| 274 | 274 | - [](geojson.md) |
| 275 | 275 | - [](gpx.md) |
| 276 | 276 | - [](html-preview.md) |
| 277 | - [](kml.md) | |
| 277 | 278 | - [](kept-tell.md) |
| 278 | 279 | - [](notebook.md) |
| 279 | 280 | - [](markdown-relative.md) |
docs/features/kml.md added +11
| @@ -0,0 +1,11 @@ | ||
| 1 | # KML maps (.kml) as a placemark table | |
| 2 | ||
| 3 | Open a `.kml` file in a repository and see its placemarks as a table: name, description, longitude, latitude. | |
| 4 | ||
| 5 | - **Web:** the blob page renders a table on the server (`src/web/render/kml.ts`, sharing gpx's tag scanner). The table sits in the `.gj-table` region: focusable, labelled "Placemarks", and it scrolls sideways inside the column (`overflow-x: auto; max-width: 100%`), so it never widens a 360px phone page; long words wrap. `?view=source`, Raw and Download work as for any file. | |
| 6 | - **Terminal:** the workspace opens a `.kml` as a Name / Description / Longitude / Latitude table (`src/tui/screens/kml.ts`, same parser); `s` flips to the source, and the status line counts the rows left out. | |
| 7 | - At most 500 placemarks are listed (`PLACEMARK_CAP`); the rest are counted in a "Showing the first 500 of N placemarks." line. | |
| 8 | - Descriptions are text, never markup: tags are shown, not applied. The web clips a description at 300 characters, the terminal at 80 (whitespace folded). | |
| 9 | - **Only the first coordinate of a placemark is shown.** A Point shows its position; a LineString or Polygon shows its first vertex only, and nothing in the table says more follows. A placemark with no readable coordinate leaves both cells empty. Altitude is ignored. | |
| 10 | - A file that is not well-formed KML (tags that do not nest, a root other than `kml`, no placemark) keeps the source view, with a one-line reason on the web. DOCTYPE entities are never expanded; all text is escaped. | |
| 11 | - No map tiles, no network, no dependency. |
src/tui/screens/kml.ts added +19
| @@ -0,0 +1,19 @@ | ||
| 1 | /** | |
| 2 | * `.kml` in the terminal: placemarks as a table of name, description and coordinates, from the | |
| 3 | * web's parser. | |
| 4 | */ | |
| 5 | ||
| 6 | import { parseKml } from "../../web/render/kml.ts"; | |
| 7 | import type { Table } from "../../text/csv.ts"; | |
| 8 | ||
| 9 | export function isKmlPath(path: string): boolean { | |
| 10 | return /\.kml$/i.test(path); | |
| 11 | } | |
| 12 | ||
| 13 | /** The placemark table of a KML file; null when it is not KML. */ | |
| 14 | export function kmlTable(source: string): Table | null { | |
| 15 | const parsed = parseKml(source); | |
| 16 | if (parsed === undefined) return null; | |
| 17 | const rows = parsed.placemarks.map((p) => [p.name, p.description.replace(/\s+/g, " ").slice(0, 80), String(p.lon ?? ""), String(p.lat ?? "")]); | |
| 18 | return { header: ["Name", "Description", "Longitude", "Latitude"], rows, more: parsed.total - rows.length, delimiter: ",", columns: 4 }; | |
| 19 | } |
src/tui/screens/workspace.ts +4
| @@ -57,6 +57,7 @@ import type { RepoFacts, RepoSource } from "../../view/source.ts"; | ||
| 57 | 57 | import { detectLanguage, highlightLines } from "../../web/highlight.ts"; |
| 58 | 58 | import { MAX_COLUMNS, parseCsv, type Table } from "../../text/csv.ts"; |
| 59 | 59 | import { parseGeoJson, propertyRows } from "../../web/render/geojson.ts"; |
| 60 | import { isKmlPath, kmlTable } from "./kml.ts"; | |
| 60 | 61 | import { gcodeFacts, parseGcode } from "../../web/render/gcode.ts"; |
| 61 | 62 | import { readStep, stepFacts } from "../../web/render/step.ts"; |
| 62 | 63 | import { parseOtio } from "../../web/render/otio.ts"; |
| @@ -1015,6 +1016,9 @@ class Tab { | ||
| 1015 | 1016 | } else if (isGeoJsonPath(this.path)) { |
| 1016 | 1017 | this.table = geoJsonTable(new TextDecoder().decode(source)); |
| 1017 | 1018 | if (this.table !== null) this.grid = layoutTable(this.table); |
| 1019 | } else if (isKmlPath(this.path)) { | |
| 1020 | this.table = kmlTable(new TextDecoder().decode(source)); | |
| 1021 | if (this.table !== null) this.grid = layoutTable(this.table); | |
| 1018 | 1022 | } else if (isTablePath(this.path)) { |
| 1019 | 1023 | // The decoded source, not `plain`: `expandTabs` has eaten every tab there. |
| 1020 | 1024 | const delimiter = /\.tsv$/i.test(this.path) ? "\t" : undefined; |
src/web/render/kinds.ts +3
| @@ -39,6 +39,7 @@ export type FileKind = | ||
| 39 | 39 | | "gpx" |
| 40 | 40 | | "har" |
| 41 | 41 | | "geojson" |
| 42 | | "kml" | |
| 42 | 43 | | "calendar" |
| 43 | 44 | | "otio" |
| 44 | 45 | | "edl" |
| @@ -109,6 +110,7 @@ export const RENDER_CAP: Readonly<Record<FileKind, number>> = { | ||
| 109 | 110 | gpx: 20 * MB, |
| 110 | 111 | har: 5 * MB, |
| 111 | 112 | geojson: 5 * MB, |
| 113 | kml: 5 * MB, | |
| 112 | 114 | calendar: 5 * MB, |
| 113 | 115 | // 1 MB is the render cap for a timeline: a larger .otio or .edl is shown as its source, |
| 114 | 116 | // not drawn. |
| @@ -253,6 +255,7 @@ const TEXTUAL: Readonly<Record<string, FileKind>> = { | ||
| 253 | 255 | gpx: "gpx", |
| 254 | 256 | har: "har", |
| 255 | 257 | geojson: "geojson", |
| 258 | kml: "kml", | |
| 256 | 259 | ics: "calendar", |
| 257 | 260 | otio: "otio", |
| 258 | 261 | edl: "edl", |
src/web/render/kml.ts added +120
| @@ -0,0 +1,120 @@ | ||
| 1 | /** | |
| 2 | * A KML map (`.kml`) opened as its placemarks: a table of name, description | |
| 3 | * and longitude/latitude, the first FEATURE_CAP of them. | |
| 4 | * | |
| 5 | * It shares the tag scanner of `gpx.ts`, which is not an XML engine: it reads | |
| 6 | * the five predefined entities and numeric references and nothing else, and a | |
| 7 | * DOCTYPE is skipped, so no entity or DTD is ever expanded. A description is | |
| 8 | * text, never markup: its tags are shown, not applied. A file whose tags do | |
| 9 | * not nest, whose root is not `kml`, or that holds no placemark keeps the | |
| 10 | * source view (the caller's `fallback`). | |
| 11 | */ | |
| 12 | ||
| 13 | import { html } from "../html.ts"; | |
| 14 | import { TAG, decode, local } from "./gpx.ts"; | |
| 15 | import type { Rendered, RenderInput } from "./renderers.ts"; | |
| 16 | ||
| 17 | /** Placemarks listed; more are counted and left out. */ | |
| 18 | export const PLACEMARK_CAP = 500; | |
| 19 | /** Characters of one description shown. */ | |
| 20 | const TEXT_CAP = 300; | |
| 21 | ||
| 22 | export interface Placemark { | |
| 23 | readonly name: string; | |
| 24 | readonly description: string; | |
| 25 | readonly lon?: number; | |
| 26 | readonly lat?: number; | |
| 27 | } | |
| 28 | export interface Kml { | |
| 29 | /** The first PLACEMARK_CAP. */ | |
| 30 | readonly placemarks: Placemark[]; | |
| 31 | /** All of them in the file. */ | |
| 32 | readonly total: number; | |
| 33 | } | |
| 34 | ||
| 35 | /** First "lon,lat[,alt]" tuple of a coordinates text, when it is in range. */ | |
| 36 | export function firstCoordinate(text: string): { lon: number; lat: number } | undefined { | |
| 37 | const tuple = text.trim().split(/\s+/)[0] ?? ""; | |
| 38 | const [a, b] = tuple.split(","); | |
| 39 | if (!/^[+-]?\d+(\.\d+)?$/.test(a ?? "") || !/^[+-]?\d+(\.\d+)?$/.test(b ?? "")) return undefined; | |
| 40 | const lon = Number(a); | |
| 41 | const lat = Number(b); | |
| 42 | return Math.abs(lon) <= 180 && Math.abs(lat) <= 90 ? { lon, lat } : undefined; | |
| 43 | } | |
| 44 | ||
| 45 | /** Parse KML text. Pure. Undefined when it is not well-formed KML with a placemark. */ | |
| 46 | export function parseKml(source: string): Kml | undefined { | |
| 47 | const stack: string[] = []; | |
| 48 | const placemarks: Placemark[] = []; | |
| 49 | let total = 0; | |
| 50 | let sawRoot = false; | |
| 51 | let text = ""; | |
| 52 | let cur: { name: string; description: string; at?: { lon: number; lat: number } | undefined } | undefined; | |
| 53 | ||
| 54 | const close = (tag: string): void => { | |
| 55 | if (cur === undefined) return; | |
| 56 | const parent = stack[stack.length - 1]; | |
| 57 | if (tag === "name" && parent === "placemark") cur.name = decode(text.trim()); | |
| 58 | else if (tag === "description" && parent === "placemark") cur.description = decode(text.trim()); | |
| 59 | else if (tag === "coordinates" && cur.at === undefined) cur.at = firstCoordinate(text); | |
| 60 | else if (tag === "placemark") { | |
| 61 | total++; | |
| 62 | if (placemarks.length < PLACEMARK_CAP) placemarks.push({ ...cur, ...cur.at }); | |
| 63 | cur = undefined; | |
| 64 | } | |
| 65 | }; | |
| 66 | const open = (tag: string): void => { | |
| 67 | if (stack.length === 0) { | |
| 68 | if (tag !== "kml") throw new Error("root"); | |
| 69 | sawRoot = true; | |
| 70 | } | |
| 71 | if (tag === "placemark" && cur === undefined) cur = { name: "", description: "" }; | |
| 72 | text = ""; | |
| 73 | }; | |
| 74 | ||
| 75 | try { | |
| 76 | for (const m of source.replace(/^/, "").matchAll(TAG)) { | |
| 77 | const [, cdata, closing, rawTag, , selfClose, chars] = m; | |
| 78 | if (cdata !== undefined) text += cdata.replace(/&/g, "&").replace(/</g, "<"); | |
| 79 | else if (chars !== undefined) { | |
| 80 | if (stack.length === 0 && chars.trim() !== "") throw new Error("text outside root"); | |
| 81 | text += chars; | |
| 82 | } else if (rawTag !== undefined) { | |
| 83 | const tag = local(rawTag); | |
| 84 | if (closing === "/") { | |
| 85 | if (stack.pop() !== tag) throw new Error("mismatch"); | |
| 86 | close(tag); | |
| 87 | } else { | |
| 88 | if (stack.length === 0 && sawRoot) throw new Error("two roots"); | |
| 89 | open(tag); | |
| 90 | if (selfClose === "/") close(tag); | |
| 91 | else stack.push(tag); | |
| 92 | } | |
| 93 | } | |
| 94 | } | |
| 95 | } catch { | |
| 96 | return undefined; | |
| 97 | } | |
| 98 | if (!sawRoot || stack.length > 0 || total === 0) return undefined; | |
| 99 | return { placemarks, total }; | |
| 100 | } | |
| 101 | ||
| 102 | const clip = (s: string): string => (s.length > TEXT_CAP ? `${s.slice(0, TEXT_CAP)}…` : s); | |
| 103 | const deg = (n: number | undefined): string => (n === undefined ? "" : String(n)); | |
| 104 | ||
| 105 | export function kml(input: RenderInput): Rendered { | |
| 106 | const parsed = parseKml(new TextDecoder().decode(input.body)); | |
| 107 | if (parsed === undefined) return { content: html``, lines: 0, fallback: "This file is not a readable KML map." }; | |
| 108 | const { placemarks, total } = parsed; | |
| 109 | const label = `${total.toLocaleString("en")} placemark${total === 1 ? "" : "s"}`; | |
| 110 | const note = | |
| 111 | total > placemarks.length | |
| 112 | ? html`<p class="muted small">Showing the first ${PLACEMARK_CAP.toLocaleString("en")} of ${label}.</p>` | |
| 113 | : html``; | |
| 114 | const content = html`<div class="gj-table" tabindex="0" role="region" aria-label="Placemarks"><table> | |
| 115 | <caption class="sr-only">${label}</caption> | |
| 116 | <thead><tr><th scope="col">Name</th><th scope="col">Description</th><th scope="col">Longitude</th><th scope="col">Latitude</th></tr></thead> | |
| 117 | <tbody>${placemarks.map((p) => html`<tr><td>${p.name}</td><td>${clip(p.description)}</td><td>${deg(p.lon)}</td><td>${deg(p.lat)}</td></tr>`)}</tbody> | |
| 118 | </table></div>${note}`; | |
Principle 8/keyboard: region is focusable and labelled, good. Please state in docs/features/kml.md that only the first coordinate of a placemark is shown; the table gives a reader no hint of that. |
||
| 119 | return { content, lines: 0, summary: label }; | |
| 120 | } |
src/web/render/renderers.ts +2
| @@ -16,6 +16,7 @@ import { graphql } from "./graphql.ts"; | ||
| 16 | 16 | import { eml } from "./eml.ts"; |
| 17 | 17 | import { csv } from "./csv.ts"; |
| 18 | 18 | import { geojson } from "./geojson.ts"; |
| 19 | import { kml } from "./kml.ts"; | |
| 19 | 20 | import { dxf } from "./dxf.ts"; |
| 20 | 21 | import { drawio, excalidraw, mermaid } from "./diagram.ts"; |
| 21 | 22 | import { step } from "./step.ts"; |
| @@ -129,6 +130,7 @@ export const RENDERERS: Partial<Readonly<Record<FileKind, Renderer>>> = { | ||
| 129 | 130 | excalidraw, |
| 130 | 131 | step, |
| 131 | 132 | geojson, |
| 133 | kml, | |
| 132 | 134 | calendar: ics, |
| 133 | 135 | otio, |
| 134 | 136 | edl, |
test/render-kinds.test.ts +1
| @@ -84,6 +84,7 @@ const SAMPLES: Record<string, [Uint8Array, FileKind, string]> = { | ||
| 84 | 84 | vcard: [enc("BEGIN:VCARD\nEND:VCARD\n"), "contacts", "application/octet-stream"], |
| 85 | 85 | eml: [enc("From: [email protected]\n\nhi\n"), "mail", "application/octet-stream"], |
| 86 | 86 | geojson: [enc('{"type":"FeatureCollection","features":[]}'), "geojson", "application/octet-stream"], |
| 87 | kml: [enc("<kml><Placemark><name>a</name></Placemark></kml>"), "kml", "application/octet-stream"], | |
| 87 | 88 | ics: [enc("BEGIN:VCALENDAR\nEND:VCALENDAR\n"), "calendar", "application/octet-stream"], |
| 88 | 89 | otio: [enc('{"OTIO_SCHEMA":"Timeline.1"}'), "otio", "application/octet-stream"], |
| 89 | 90 | edl: [enc("TITLE: a\n"), "edl", "application/octet-stream"], |
test/render-kml.test.ts added +53
| @@ -0,0 +1,53 @@ | ||
| 1 | /** KML files as a placemark table: a good file, a malformed one, a hostile entity. */ | |
| 2 | import { describe, expect, test } from "bun:test"; | |
| 3 | import { kml, parseKml, PLACEMARK_CAP } from "../src/web/render/kml.ts"; | |
| 4 | import { fileKind } from "../src/web/render/kinds.ts"; | |
| 5 | import { RENDERERS } from "../src/web/render/renderers.ts"; | |
| 6 | ||
| 7 | const enc = (s: string): Uint8Array => new TextEncoder().encode(s); | |
| 8 | const draw = (text: string) => kml({ path: "m/a.kml", size: text.length, body: enc(text), media: "/m", download: "/d" }); | |
| 9 | ||
| 10 | const GOOD = `<?xml version="1.0"?><kml xmlns="http://www.opengis.net/kml/2.2"><Document> | |
| 11 | <Placemark><name>Cafe & Bar</name><description><![CDATA[<script>alert(1)</script> hi]]></description> | |
| 12 | <Point><coordinates>-122.08,37.42,0</coordinates></Point></Placemark> | |
| 13 | <Placemark><name>Line</name><LineString><coordinates>1,2 3,4</coordinates></LineString></Placemark> | |
| 14 | </Document></kml>`; | |
| 15 | ||
| 16 | describe("kml", () => { | |
| 17 | test("registered by extension", () => { | |
| 18 | expect(fileKind("a.kml", enc(GOOD))).toBe("kml"); | |
| 19 | expect(RENDERERS.kml).toBe(kml); | |
| 20 | }); | |
| 21 | ||
| 22 | test("a good file shows name, escaped description, lon and lat", () => { | |
| 23 | const out = String(draw(GOOD).content); | |
| 24 | expect(out).toContain("<td>Cafe & Bar</td>"); | |
| 25 | expect(out).toContain("<script>alert(1)</script> hi"); | |
| 26 | expect(out).not.toContain("<script>"); | |
| 27 | expect(out).toContain("<td>-122.08</td><td>37.42</td>"); | |
| 28 | expect(out).toContain("<td>1</td><td>2</td>"); | |
| 29 | }); | |
| 30 | ||
| 31 | test("rows are capped at 500 and the rest counted", () => { | |
| 32 | const many = `<kml>${"<Placemark><name>p</name></Placemark>".repeat(PLACEMARK_CAP + 5)}</kml>`; | |
| 33 | const k = parseKml(many)!; | |
| 34 | expect(k.placemarks.length).toBe(PLACEMARK_CAP); | |
| 35 | expect(k.total).toBe(PLACEMARK_CAP + 5); | |
| 36 | expect(String(draw(many).content)).toContain("first 500 of 505 placemarks"); | |
| 37 | }); | |
| 38 | ||
| 39 | test("a malformed file keeps the source view", () => { | |
| 40 | for (const bad of ["<kml><Placemark><name>x</Placemark></kml>", "<kml><Document/></kml>", "<gpx/>", "not xml", "<kml><Placemark>"]) { | |
| 41 | expect(parseKml(bad)).toBeUndefined(); | |
| 42 | expect(draw(bad).fallback).toBeDefined(); | |
| 43 | } | |
| 44 | }); | |
| 45 | ||
| 46 | test("no DTD or entity is expanded", () => { | |
| 47 | const evil = `<?xml version="1.0"?><!DOCTYPE kml [<!ENTITY a "AAAA"><!ENTITY b "&a;&a;&a;&a;">]> | |
| 48 | <kml><Placemark><name>&b; &a; &lol;</name></Placemark></kml>`; | |
| 49 | const out = String(draw(evil).content); | |
| 50 | expect(out).not.toContain("AAAA"); | |
| 51 | expect(out).toContain("&b; &a; &lol;"); | |
| 52 | }); | |
| 53 | }); |
test/tui-workspace-formats.test.ts +19
| @@ -317,6 +317,25 @@ describe("the terminal workspace, by file type", () => { | ||
| 317 | 317 | } |
| 318 | 318 | }); |
| 319 | 319 | |
| 320 | test("a .kml opens as its placemarks, sharing the web parser, and s flips to the source", async () => { | |
| 321 | const made = await createRepo(forge, alice, { name: "maps", visibility: "public", description: "places" }); | |
| 322 | if (!made.ok) throw new Error("repo failed"); | |
| 323 | const kml = "<kml><Placemark><name>Harbour</name><Point><coordinates>-122.08,37.42</coordinates></Point></Placemark></kml>"; | |
| 324 | await commitToBranch(forge, alice, made.value, { message: "seed", files: [{ path: "places.kml", content: kml }] }); | |
| 325 | const h = boot(); | |
| 326 | try { | |
| 327 | await h.settle(); | |
| 328 | await open(h, "maps"); | |
| 329 | await openFile(h, "places.kml"); | |
| 330 | expect(h.text()).toContain("Harbour"); | |
| 331 | expect(h.text()).toContain("37.42"); | |
| 332 | await h.press("s"); | |
| 333 | expect(h.text()).toContain("<Placemark>"); | |
| 334 | } finally { | |
| 335 | h.stop(); | |
| 336 | } | |
| 337 | }); | |
| 338 | ||
| 320 | 339 | test("a .sarif opens as its findings, sharing the web parser, and s flips to the source", async () => { |
| 321 | 340 | const made = await createRepo(forge, alice, { name: "scans", visibility: "public", description: "findings" }); |
| 322 | 341 | if (!made.ok) throw new Error("repo failed"); |
new above
offline
Both doors: the screen exists, but its how-to docs/features/kml.md and the README.md index row are missing. Add both.