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

Merged opened this

Check · Review · Land · Live done — Landed and live in production.

Merged

scout/forge:scout/13383-a-kml-file-opens-as-its-placemarks-name → main 6 commits fork 2 threads · 2 unresolved

  • Merged. scout/13383-a-kml-file-opens-as-its-placemarks-name was merged into main as fd02895.

Review

Sign in to review this change.
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).
274274 - [GeoJSON (.geojson) as an outline and a properties table](geojson.md)
275275 - [GPS tracks (.gpx) as a route outline](gpx.md)
276276 - [HTML preview](html-preview.md)
277 - [KML maps (.kml) as a placemark table](kml.md)
277278 - [A half-written tell is kept](kept-tell.md)
278279 - [Jupyter notebooks](notebook.md)
279280 - [Markdown relative images and links](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 /**

Both doors: the screen exists, but its how-to docs/features/kml.md and the README.md index row are missing. Add both.

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";
5757 import { detectLanguage, highlightLines } from "../../web/highlight.ts";
5858 import { MAX_COLUMNS, parseCsv, type Table } from "../../text/csv.ts";
5959 import { parseGeoJson, propertyRows } from "../../web/render/geojson.ts";
60 import { isKmlPath, kmlTable } from "./kml.ts";
6061 import { gcodeFacts, parseGcode } from "../../web/render/gcode.ts";
6162 import { readStep, stepFacts } from "../../web/render/step.ts";
6263 import { parseOtio } from "../../web/render/otio.ts";
@@ -1015,6 +1016,9 @@ class Tab {
10151016 } else if (isGeoJsonPath(this.path)) {
10161017 this.table = geoJsonTable(new TextDecoder().decode(source));
10171018 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);
10181022 } else if (isTablePath(this.path)) {
10191023 // The decoded source, not `plain`: `expandTabs` has eaten every tab there.
10201024 const delimiter = /\.tsv$/i.test(this.path) ? "\t" : undefined;
src/web/render/kinds.ts +3
@@ -39,6 +39,7 @@ export type FileKind =
3939 | "gpx"
4040 | "har"
4141 | "geojson"
42 | "kml"
4243 | "calendar"
4344 | "otio"
4445 | "edl"
@@ -109,6 +110,7 @@ export const RENDER_CAP: Readonly<Record<FileKind, number>> = {
109110 gpx: 20 * MB,
110111 har: 5 * MB,
111112 geojson: 5 * MB,
113 kml: 5 * MB,
112114 calendar: 5 * MB,
113115 // 1 MB is the render cap for a timeline: a larger .otio or .edl is shown as its source,
114116 // not drawn.
@@ -253,6 +255,7 @@ const TEXTUAL: Readonly<Record<string, FileKind>> = {
253255 gpx: "gpx",
254256 har: "har",
255257 geojson: "geojson",
258 kml: "kml",
256259 ics: "calendar",
257260 otio: "otio",
258261 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, "&amp;").replace(/</g, "&lt;");
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";
1616 import { eml } from "./eml.ts";
1717 import { csv } from "./csv.ts";
1818 import { geojson } from "./geojson.ts";
19 import { kml } from "./kml.ts";
1920 import { dxf } from "./dxf.ts";
2021 import { drawio, excalidraw, mermaid } from "./diagram.ts";
2122 import { step } from "./step.ts";
@@ -129,6 +130,7 @@ export const RENDERERS: Partial<Readonly<Record<FileKind, Renderer>>> = {
129130 excalidraw,
130131 step,
131132 geojson,
133 kml,
132134 calendar: ics,
133135 otio,
134136 edl,
test/render-kinds.test.ts +1
@@ -84,6 +84,7 @@ const SAMPLES: Record<string, [Uint8Array, FileKind, string]> = {
8484 vcard: [enc("BEGIN:VCARD\nEND:VCARD\n"), "contacts", "application/octet-stream"],
8585 eml: [enc("From: [email protected]\n\nhi\n"), "mail", "application/octet-stream"],
8686 geojson: [enc('{"type":"FeatureCollection","features":[]}'), "geojson", "application/octet-stream"],
87 kml: [enc("<kml><Placemark><name>a</name></Placemark></kml>"), "kml", "application/octet-stream"],
8788 ics: [enc("BEGIN:VCALENDAR\nEND:VCALENDAR\n"), "calendar", "application/octet-stream"],
8889 otio: [enc('{"OTIO_SCHEMA":"Timeline.1"}'), "otio", "application/octet-stream"],
8990 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 &amp; 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 &amp; Bar</td>");
25 expect(out).toContain("&lt;script&gt;alert(1)&lt;/script&gt; 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("&amp;b; &amp;a; &amp;lol;");
52 });
53 });
test/tui-workspace-formats.test.ts +19
@@ -317,6 +317,25 @@ describe("the terminal workspace, by file type", () => {
317317 }
318318 });
319319
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
320339 test("a .sarif opens as its findings, sharing the web parser, and s flips to the source", async () => {
321340 const made = await createRepo(forge, alice, { name: "scans", visibility: "public", description: "findings" });
322341 if (!made.ok) throw new Error("repo failed");

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs