Build your personal knowledge base with Trilium Notes
TypeScript electronelectron-appknowledge-baseknowledge-graphknowledge-managementknowledge-management-graphlocal-firstnote-managmentnote-takernote-takingnotebooknotesnotes-apppersonal-knowledge-basepersonal-wikiscriptableself-hostedself-hostingwiki
refactor(geomap): clean up some comments
Elian Doran21066d44849c
diff --git a/apps/client/src/widgets/collections/geomap/ContextMenus.spec.tsx b/apps/client/src/widgets/collections/geomap/ContextMenus.spec.tsxindex 651be039a4..3f3dd8a1fa 100644--- a/apps/client/src/widgets/collections/geomap/ContextMenus.spec.tsx+++ b/apps/client/src/widgets/collections/geomap/ContextMenus.spec.tsx@@ -36,8 +36,8 @@ vi.mock("../../../menus/custom-items/NoteColorPicker", () => ({ default: () => n/** A map that reports what is under a click and delegates its own, which is all this component asks. */function fakeMap(markerUnderPointer?: FNote, trackUnderPointer?: FNote, shapeUnderPointer?: FNote) {const listeners = new Set<(e: unknown) => void>();- // The layers a track and a shape offer to be pointed at by, each named after its note (see- // `trackHitLayers` and `shapeHitLayers`).+ // The hit layers a track and a shape add, each named after its note (see `trackHitLayers`+ // and `shapeHitLayers`).const trackLayer = trackUnderPointer && `gpx-hit-${trackUnderPointer.noteId}`;const shapeLayer = shapeUnderPointer && `shape-hit-${shapeUnderPointer.noteId}`;@@ -45,9 +45,9 @@ function fakeMap(markerUnderPointer?: FNote, trackUnderPointer?: FNote, shapeUndon(event: string, fn: (e: unknown) => void) { if (event === "contextmenu") listeners.add(fn); },off(event: string, fn: (e: unknown) => void) { if (event === "contextmenu") listeners.delete(fn); },getLayersOrder: () => [ trackLayer, shapeLayer ].filter((id) => id !== undefined),- // Answered in the map's drawing order rather than in the order of `layers`, which is how- // MapLibre answers: the shapes go on last and so are drawn above the pins standing on them.- // A single query naming both would therefore hand back the shape.+ // Answered in drawing order rather than in the order of `layers`, as MapLibre does: the+ // shapes are added last and draw above the pins, so one query naming both returns the+ // shape.queryRenderedFeatures: (_point: unknown, options: { layers: string[] }) => [...(shapeUnderPointer && shapeLayer && options.layers.includes(shapeLayer)? [ { properties: { id: shapeUnderPointer.noteId } } ]@@ -193,9 +193,9 @@ describe("ContextMenus", () => {});/**- * A drawn shape is one of the map's notes like any other, so right-clicking it opens that note's- * menu rather than the bare map's. Taking it off the map clears its geometry and leaves the note- * behind, which is the plain removal a marker is offered and not a track's deletion.+ * A drawn shape is one of the map's notes, so right-clicking it opens that note's menu rather+ * than the map's. Taking it off clears its geometry and keeps the note, which is the plain+ * removal a marker is offered rather than a track's deletion.*/it("opens the note of a drawn shape that was right-clicked", async () => {const shape = buildNote({ title: "The lot", "#geoShape": LOT_SHAPE });@@ -206,7 +206,7 @@ describe("ContextMenus", () => {expect(items).not.toContainEqual(expect.objectContaining({ title: "geo-map-context.delete-note" }));});- /** A shape has no marker to put somewhere else either: moving one means drawing it again. */+ /** A shape has no marker to move either: moving one means drawing it again. */it("does not offer to move a drawn shape", async () => {const shape = buildNote({ title: "The lot", "#geoShape": LOT_SHAPE });const { items } = await openMenu(fakeMap(undefined, undefined, shape));@@ -215,9 +215,9 @@ describe("ContextMenus", () => {});/**- * An area's fill covers its whole inside and is drawn above the pins standing on it, so asking- * for both at once would hand back the polygon for every point within it. The shapes are asked- * about only where the markers and the tracks were missed.+ * An area's fill covers its inside and draws above the pins, so one query for both would return+ * the polygon for every point within it. The shapes are queried only where the markers and the+ * tracks were missed.*/it("prefers a marker standing inside a shape to the shape", async () => {const marker = buildNote({ title: "The well", "#geolocation": "1,2" });diff --git a/apps/client/src/widgets/collections/geomap/ContextMenus.ts b/apps/client/src/widgets/collections/geomap/ContextMenus.tsindex 4ba41ec9bb..5930ba2252 100644--- a/apps/client/src/widgets/collections/geomap/ContextMenus.ts+++ b/apps/client/src/widgets/collections/geomap/ContextMenus.ts@@ -41,8 +41,8 @@ export default function ContextMenus({ parentNote, isReadOnly, onRelocate, onCreconst onContextMenu = useCallback((e: GeoMouseEvent) => {if (!map) return;- // Whichever of the map's notes the pointer landed on — a marker, a track or a drawn shape,- // the order between them being the hit test's own business (see featureAt).+ // Whichever of the map's notes the click landed on. featureAt() decides the order+ // between a marker, a track and a drawn shape.const feature = featureAt(map, e.point);if (feature) {@@ -149,11 +149,10 @@ export function openMapContextMenu(e: GeoMouseEvent, isEditable: boolean, onCrea* The marker is moved by being placed again rather than dragged: the notes are drawn into one symbol* layer, not an element apiece, so there is nothing on the map to take hold of.*- * Neither a GPX track nor a drawn shape is offered anything, which is why this is a list and not an- * item. Each is on the map by the figure it draws across it, which no click can pick up, and what- * the offer did was write a location onto the note — planting a stray pin somewhere else while the- * line or the shape stayed exactly where it was. The detail pane leaves the button out for the same- * reason.+ * Neither a GPX track nor a drawn shape is offered anything, which is why this returns a list and+ * not an item. Each is on the map by the figure it draws, which no click can pick up, and the offer+ * only wrote a location onto the note, planting a stray pin while the figure stayed where it was.+ * DetailPane leaves the button out for the same reason.*/function buildRelocateItem(noteId: string, onRelocate: (noteId: string) => void): MenuItem<keyof CommandMappings>[] {const note = froca.getNoteFromCache(noteId);diff --git a/apps/client/src/widgets/collections/geomap/DetailPane.spec.tsx b/apps/client/src/widgets/collections/geomap/DetailPane.spec.tsxindex 00ef12eb91..2914f03cbc 100644--- a/apps/client/src/widgets/collections/geomap/DetailPane.spec.tsx+++ b/apps/client/src/widgets/collections/geomap/DetailPane.spec.tsx@@ -133,9 +133,9 @@ function fakeMap({ width = MAP_WIDTH, features = [] as unknown[] } = {}) {listeners.get(fn ? `${event}:${fnOrLayer}` : event)?.delete((fn ?? fnOrLayer) as Listener);},/**- * What was hit, in the map's drawing order rather than the order of `layers`, which is how- * MapLibre answers and the reason the pane queries twice. The shapes go on last and so draw- * above the markers, meaning a query naming both returns the shape first.+ * What was hit, in drawing order rather than in the order of `layers`, as MapLibre answers+ * and the reason the pane queries twice. The shapes are added last and draw above the+ * markers, so a query naming both returns the shape first.*/queryRenderedFeatures(_point: unknown, { layers }: { layers: string[] }) {const shapes = shapeLayers.some((id) => layers.includes(id)) ? underShapes : [];diff --git a/apps/client/src/widgets/collections/geomap/DetailPane.tsx b/apps/client/src/widgets/collections/geomap/DetailPane.tsxindex f2a55239dd..c0c680c227 100644--- a/apps/client/src/widgets/collections/geomap/DetailPane.tsx+++ b/apps/client/src/widgets/collections/geomap/DetailPane.tsx@@ -152,7 +152,7 @@ export default function DetailPane({ notes, parentNote, placing, isReadOnly, sel// A marker, a GPX track or a drawn shape selects, anywhere else clears. Read off the rendered// layers rather than bound to them (`map.on("click", MARKER_LAYER, ...)`) so one handler answers- // all, the order between the three being the hit test's own business (see featureAt).+ // all; featureAt() decides the order between the three.useEffect(() => {if (!map || placing) return;@@ -175,9 +175,9 @@ export default function DetailPane({ notes, parentNote, placing, isReadOnly, sel// created — is held clear of the pane the same way as one that was clicked; and off the// location too, so a marker that has just been put somewhere else is followed there.//- // A GPX track and a drawn shape are not points but extents, so they are fitted rather than- // centred: panned and zoomed until they stand in the part of the map the pane leaves uncovered- // — the whole file, or only what the click named where it named more (see PaneFocus).+ // A GPX track and a drawn shape are extents rather than points, so they are fitted rather+ // than centred: panned and zoomed until they stand in the part of the map the pane leaves+ // uncovered, the whole file or only what the click named where it named more (see PaneFocus).useEffect(() => {if (!map || !note) return;// Nothing is aimed at behind a surface that covers the map: the camera would be moving to a@@ -190,8 +190,8 @@ export default function DetailPane({ notes, parentNote, placing, isReadOnly, sel// camera has nothing to do there at all, and what it did was pan the map behind a sheet.if (maximized || isMobile()) return;- // A shape is measured off its own label, which holds every point the map draws from and- // holds them at once, so there is no source to wait for as a track's file needs.+ // A shape is measured off its own label, which holds every point at once, so there is+ // no source to wait for as a track's file needs.if (shape) {const bounds = geoShapeBounds(shape);if (bounds) {@@ -344,7 +344,7 @@ const FIT_MAX_ZOOM = 16;** Three kinds of note reach the map three ways: a marker through `LOCATION_ATTRIBUTE`, a drawn* shape through `SHAPE_ATTRIBUTE` (see shapes.ts), and a GPX track through its mime, its line- * coming from the note's own file rather than from anything written on it.+ * coming from the note's own file rather than from a label.*/function standsOnMap(note: FNote) {return note.mime === GPX_MIME@@ -570,7 +570,8 @@ const PANE_NTX_ID = "_geo-detail-pane";*/function MarkerActions({ note, parentNote, isReadOnly, onRelocate }: { note: FNote; parentNote: FNote; isReadOnly: boolean; onRelocate(): void }) {const [ location ] = useNoteLabel(note, LOCATION_ATTRIBUTE);- // Read so the row is rebuilt when the geometry is edited away, the note ceasing to be a shape.+ // Read so the row is rebuilt when the geometry is edited away and the note stops being a+ // shape.useNoteLabel(note, SHAPE_ATTRIBUTE);const latLng = parseLocation(location);const isShape = isShapeNote(note);@@ -595,8 +596,8 @@ function MarkerActions({ note, parentNote, isReadOnly, onRelocate }: { note: FNo<NoteColorAction note={note} title={t("geo-map.marker-color")} />{/* Not offered for a track or a drawn shape: neither has a location label to- rewrite, and moving one means drawing it again. The right-click menu leaves it- out for a track for the same reason. */}+ rewrite, and moving one means drawing it again. ContextMenus leaves it out for+ the same reason. */}{note.mime !== GPX_MIME && !isShape && <ActionButtonclassName="geo-detail-pane-move"icon="bx bx-move"diff --git a/apps/client/src/widgets/collections/geomap/DrawShape.spec.tsx b/apps/client/src/widgets/collections/geomap/DrawShape.spec.tsxindex 2d776a42dc..c0a6d93917 100644--- a/apps/client/src/widgets/collections/geomap/DrawShape.spec.tsx+++ b/apps/client/src/widgets/collections/geomap/DrawShape.spec.tsx@@ -1,7 +1,7 @@/**- * The drawing session (see DrawShape.tsx): that mounting it arms Terra Draw with the tool's own- * mode and unmounting stands it down, that a finished shape reaches the caller converted to what- * its note will carry, and that anything else Terra Draw announces is left alone.+ * The drawing session (see DrawShape.tsx): that mounting it arms Terra Draw with the tool's mode+ * and unmounting stops it, that a finished shape reaches the caller as what its note will carry,+ * and that anything else Terra Draw reports is ignored.*/import { render } from "preact";import { act } from "preact/test-utils";@@ -32,7 +32,7 @@ vi.mock("terra-draw", () => {setMode(name: string) { this.modeName = name; }getSnapshotFeature(id: string) { return this.features.get(id); }- /** A shape being finished, as the real library would announce it. */+ /** A shape being finished, as the real library would report it. */finish(id: string, action: string, feature: unknown) {this.features.set(id, feature);this.listeners.get("finish")?.(id, { action });@@ -128,10 +128,10 @@ describe("DrawShape", () => {});/**- * A circle and a rectangle are two positions, and Terra Draw reads the second one from pointer+ * A circle and a rectangle are two positions, and Terra Draw reads the second from pointer* movement between two clicks unless told otherwise. A finger makes no such movement, so on a- * touchscreen the tap that placed the first position left nothing able to size the shape.- * Asking for the drag as well is what lets a finger draw one.+ * touchscreen nothing could size the shape. Accepting the drag as well is what lets a finger+ * draw one.*/it("lets the two-corner tools be drawn by dragging, which is all a finger can do", () => {for (const tool of [ "circle", "rectangle" ] as const) {diff --git a/apps/client/src/widgets/collections/geomap/DrawShape.tsx b/apps/client/src/widgets/collections/geomap/DrawShape.tsxindex a7e0f8eb74..52c628fbb3 100644--- a/apps/client/src/widgets/collections/geomap/DrawShape.tsx+++ b/apps/client/src/widgets/collections/geomap/DrawShape.tsx@@ -5,25 +5,21 @@ import { TerraDrawMapLibreGLAdapter } from "terra-draw-maplibre-gl-adapter";import { MapStyleLoaded, ParentMap } from "./map";import { type GeoShape, polygonFromRing, ringCenter } from "./shapes";-/** The drawing tools on offer, each arming Terra Draw with a mode of its own. */+/** The drawing tools, each backed by a Terra Draw mode of its own. */export type DrawTool = "line" | "polygon" | "rectangle" | "circle";interface DrawShapeProps {tool: DrawTool;- /** Handed the finished shape. Standing the session down again is the caller's move — the- * component draws for as long as it is mounted, like GhostPin haunts. */+ /** Receives the finished shape. The component keeps drawing until the caller unmounts it. */onFinish: (shape: GeoShape) => void;}/**- * A drawing session: mounted while the map is armed to draw, gone when it is not.+ * A drawing session, mounted while the map is armed to draw.*- * Terra Draw is the pencil here and nothing more. It owns the map only while this is mounted —- * click by click, the growing shape and its vertex handles are its own ephemeral layers — and the- * moment a shape is finished, it is handed to the caller to become a note and the session's- * rendering is thrown away. What the reader sees from then on is {@link ShapeLayer}, drawing the- * note's label the way every persisted thing on this map is drawn. Keeping the library inside- * these brackets is the point: nothing persisted ever depends on it.+ * Terra Draw owns the map only while this is mounted, and the layers it adds for the growing shape+ * and its vertex handles go with it. A finished shape is handed to `onFinish` to become a note,+ * which {@link ShapeLayer} then draws. Nothing persisted depends on Terra Draw.*/export default function DrawShape({ tool, onFinish }: DrawShapeProps) {const parentMap = useContext(ParentMap);@@ -34,8 +30,8 @@ export default function DrawShape({ tool, onFinish }: DrawShapeProps) {onFinishRef.current = onFinish;useEffect(() => {- // The adapter puts its working layers on the style, so it must wait for one to be there —- // the same wait every layer-adding child of the map keeps (see MapStyleLoaded).+ // The adapter adds its layers to the style, so it waits for one to load, as every+ // layer-adding child of the map does (see MapStyleLoaded).if (!parentMap || !styleLoaded) return;const mode = buildMode(tool);@@ -70,22 +66,14 @@ export default function DrawShape({ tool, onFinish }: DrawShapeProps) {}/**- * How the two-corner tools are drawn, which is both ways rather than Terra Draw's default of- * `click-move` alone.- *- * A circle and a rectangle are made of two positions, and under `click-move` the second one is- * only ever read from pointer movement *between* two clicks. A finger produces no such movement:- * it is either down or it is not, and the moves it does make while down are reported as a drag,- * which that setting ignores. So on a touchscreen the first tap placed a centre and nothing could- * ever size the shape. Allowing the drag as well leaves the mouse exactly as it was and gives- * touch the press-and-drag it can actually perform.- *- * The tools that take a position per click — the line and the polygon — need nothing here: every- * tap is a vertex, and movement only previews the next one.+ * How the circle and rectangle tools read their second corner. Terra Draw's default, `click-move`,+ * reads it from pointer movement between two clicks, which a finger never produces: its movement+ * while down is reported as a drag. Accepting the drag as well leaves the mouse unchanged and lets+ * touch size the shape.*/const TWO_CORNER_INTERACTION = "click-move-or-drag";-/** The Terra Draw mode a tool draws with — each knows its own name for `setMode`. */+/** The Terra Draw mode a tool draws with. */function buildMode(tool: DrawTool) {switch (tool) {case "line":@@ -100,14 +88,13 @@ function buildMode(tool: DrawTool) {}/**- * The finished feature as the shape its note will carry, or null for one that is not the kind the- * tool draws — nothing to make a note of then, and the session simply stays armed.+ * The finished feature as the shape its note carries, or null where the feature is not the kind the+ * tool draws, which leaves the session armed.*- * Every area tool comes through the polygon branch: whatever hand movement made it, what was made- * is a ring, and a ring is a polygon note (with its closing repeat left behind — the label does- * not spell it; see shapes.ts). The circle alone is read back out of its ring: Terra Draw draws- * one as a many-cornered polygon carrying its radius in the properties, and the note stores what- * the drawing meant — a centre and a reach — rather than the ring that approximated it.+ * Every area tool produces a ring, so all of them go through the polygon branch, dropping the+ * closing repeat the label does not spell (see shapes.ts). A circle is the exception: Terra Draw+ * draws it as a many-cornered polygon carrying `radiusKilometers`, and the note stores the centre+ * and the radius instead of the ring that approximates them.*/export function shapeFromFeature(tool: DrawTool, feature: GeoJSONStoreFeatures): GeoShape | null {if (tool === "line") {diff --git a/apps/client/src/widgets/collections/geomap/DrawToolbar.spec.tsx b/apps/client/src/widgets/collections/geomap/DrawToolbar.spec.tsxindex 9da5a67a70..9018a476db 100644--- a/apps/client/src/widgets/collections/geomap/DrawToolbar.spec.tsx+++ b/apps/client/src/widgets/collections/geomap/DrawToolbar.spec.tsx@@ -1,8 +1,7 @@/**- * The drawing tools over a geo map (see DrawToolbar.tsx). What is checked is that every tool is- * offered, that a press arms the map and a press on an armed one stands it down, that the armed tool- * is worn held down, that the width of the map settles where they stand, and that a map that may not- * be edited carries none of them at all.+ * The drawing tools over a geo map (see DrawToolbar.tsx): that every tool is offered, that a press+ * arms the map and a press on an armed one disarms it, that the armed tool's button is shown+ * active, that the map's width decides where they stand, and that a read-only map carries none.*/import { act } from "preact/test-utils";import { describe, expect, it, vi } from "vitest";@@ -12,14 +11,14 @@ import type { DrawTool } from "./DrawShape";import DrawToolbar from "./DrawToolbar";import { ParentMap } from "./map";-/** A map of a given width, which is all the tools ask of one: where they stand follows from it. */+/** A map of a given width, which is all the tools read of one. */function fakeMap(width: number) {const container = document.createElement("div");Object.defineProperty(container, "clientWidth", { value: width, configurable: true });return { getContainer: () => container } as never;}-/** A map with no room at its head, which is where the tools stand in a column down its side. */+/** A map with no room at its head, where the tools stand in a column down its side. */const NARROW = 400;/** A map roomy enough for the tools to stand across its head, clear of the search bar and the pane. */@@ -47,7 +46,7 @@ function renderTools({ map = fakeMap(NARROW), isReadOnly = false, drawingTool =};}-/** Every drawing tool, by the icon its button wears. */+/** Every drawing tool, by the icon on its button. */const DRAW_TOOL_ICONS: { tool: DrawTool; icon: string }[] = [{ tool: "line", icon: "bx-vector" },{ tool: "polygon", icon: "bx-shape-polygon" },@@ -91,8 +90,8 @@ describe("geo map DrawToolbar", () => {});/**- * Drawing is all the group offers, so a map that may not be edited would carry four dead buttons- * and nothing else. The editing bar shows its own refused, having somewhere to stand either way.+ * Every button draws, so a read-only map would carry four disabled buttons and nothing else.+ * EditToolbar shows its own disabled rather than hiding the group.*/it("comes off a map that may not be edited rather than standing there refused", () => {const { group, buttons } = renderTools({ isReadOnly: true });diff --git a/apps/client/src/widgets/collections/geomap/DrawToolbar.tsx b/apps/client/src/widgets/collections/geomap/DrawToolbar.tsxindex 49480dcdf9..fea1ae4e3e 100644--- a/apps/client/src/widgets/collections/geomap/DrawToolbar.tsx+++ b/apps/client/src/widgets/collections/geomap/DrawToolbar.tsx@@ -7,33 +7,31 @@ import type { DrawTool } from "./DrawShape";import { ParentMap } from "./map";interface DrawToolbarProps {- /** The map may not be edited, which takes the rail off it entirely. */+ /** Whether the map can be edited. A read-only map carries no drawing tools at all. */isReadOnly: boolean;- /** The tool the map is armed to draw with, if any — its button worn held down. */+ /** The tool the map is armed to draw with, whose button is shown active. */drawingTool: DrawTool | null;- /** Arms the map to draw with the tool, or stands it down again (see index.tsx). */+ /** Arms the map to draw with the tool, or disarms it (see index.tsx). */onToggleDrawing: (tool: DrawTool) => void;}/**- * The drawing tools, across the head of the map where there is room for them and in a column down- * its leading edge where there is not.+ * The drawing tools, across the head of the map where there is room and in a column down its+ * leading edge where there is not.*- * A group of their own rather than four more buttons on {@link EditToolbar}, because the foot of the- * map is full: the scale holds one corner and {@link MapToolbar} the other, and what is left in the- * middle at phone width fits about three buttons. The head is clear on a roomy map; on a narrow one- * the leading edge is, and a column grows into the map's height rather than towards either corner.+ * A group of its own rather than four more buttons on {@link EditToolbar}: the scale control holds+ * one foot corner and {@link MapToolbar} the other, leaving room for about three buttons between+ * them at phone width. A column grows into the map's height instead of towards either corner.*- * Each button wears the shape its tool draws and no words, the shapes being what there is to say.- * The armed tool is shown held down, and its tooltip says what a second press does, as the marker- * button's does.+ * Each button shows the shape its tool draws. The armed tool's button is shown active, and its+ * tooltip says what a second press does, as the marker button's does.*/export default function DrawToolbar({ isReadOnly, drawingTool, onToggleDrawing }: DrawToolbarProps) {const map = useContext(ParentMap);const acrossTheHead = useRoomAcrossTheHead(map);- // No tools over a map that could not be drawn (see the WebGL fallback in map.tsx), and none- // over one that may not be edited: every button draws, so all four would be disabled at once.+ // No tools where there is no map to draw on (see the WebGL fallback in map.tsx), and none on+ // a read-only map, where all four buttons would be disabled.if (!map || isReadOnly) return null;return (@@ -56,17 +54,16 @@ export default function DrawToolbar({ isReadOnly, drawingTool, onToggleDrawing });}-/** How wide the map must be for the tools to clear the search bar and the detail pane at its head,- * a group centred between the insets keeping half of what it does not take on either side. */+/** How wide the map must be for the centred tools to clear the search bar and the detail pane. */const HEAD_BAR_MIN_WIDTH = 920;/**- * Whether the map has room for the tools across its head, followed as the map is resized. Measured- * rather than asked of the device: a map sharing a desktop screen with another note is as narrow as- * a phone's, and the search bar and the detail pane stand at the head of it either way.+ * Whether the map has room for the tools across its head, tracked as it is resized. Measured rather+ * than read off the device: a map sharing a desktop screen with another note is as narrow as a+ * phone's, and carries the same search bar and detail pane at its head.*- * Measured before the paint, since the map arrives a render after the group does and the column is- * what a group with nothing measured yet would be drawn as.+ * Measured in a layout effect, since the map arrives a render after the toolbar and an unmeasured+ * toolbar draws as the column.*/function useRoomAcrossTheHead(map: MapLibreGLMap | null) {const [ hasRoom, setHasRoom ] = useState(false);@@ -88,7 +85,7 @@ function useRoomAcrossTheHead(map: MapLibreGLMap | null) {return hasRoom;}-/** The tools in the order they stand, each wearing the shape it draws. */+/** The tools in the order they appear, each with the icon of the shape it draws. */const DRAW_TOOLS: { tool: DrawTool; icon: string; title: () => string }[] = [{ tool: "line", icon: "bx-vector", title: () => t("geo-map.draw-line") },{ tool: "polygon", icon: "bx-shape-polygon", title: () => t("geo-map.draw-polygon") },diff --git a/apps/client/src/widgets/collections/geomap/EditToolbar.spec.tsx b/apps/client/src/widgets/collections/geomap/EditToolbar.spec.tsxindex 1f354a6fb2..e1070e096d 100644--- a/apps/client/src/widgets/collections/geomap/EditToolbar.spec.tsx+++ b/apps/client/src/widgets/collections/geomap/EditToolbar.spec.tsx@@ -1,8 +1,8 @@/**- * The bar of editing actions over a geo map (see EditToolbar.tsx). What is checked of each button- * is that a press arms the map and a press on an armed one stands it down, that an armed mode is- * worn as held down, and that a map that may not be edited refuses them all. The drawing tools are- * on a rail of their own and checked there (see DrawToolbar.spec.tsx).+ * The bar of editing actions over a geo map (see EditToolbar.tsx): that a press on each button arms+ * the map and a press on an armed one disarms it, that an armed mode is shown active, and that a+ * read-only map disables them all. The drawing tools have a group of their own, checked in+ * DrawToolbar.spec.tsx.*/import { act } from "preact/test-utils";import { describe, expect, it, vi } from "vitest";diff --git a/apps/client/src/widgets/collections/geomap/EditToolbar.tsx b/apps/client/src/widgets/collections/geomap/EditToolbar.tsxindex aef1320c0a..f2ed406002 100644--- a/apps/client/src/widgets/collections/geomap/EditToolbar.tsx+++ b/apps/client/src/widgets/collections/geomap/EditToolbar.tsx@@ -22,7 +22,7 @@ interface EditToolbarProps {/*** The editing actions, standing in the middle of the map's foot on an {@link OverlayControlGroup} of* their own — the surface every group over this map stands on: adding a marker and bringing in a- * GPX track. The drawing tools stand apart, on a rail of their own (see {@link DrawToolbar}).+ * GPX track. The drawing tools have a group of their own (see {@link DrawToolbar}).** A group of its own rather than more buttons on {@link MapToolbar}: that one is the camera — how* close in the map is drawn, how much screen it gets — and what changes the map is another kind ofdiff --git a/apps/client/src/widgets/collections/geomap/GpxTrack.spec.tsx b/apps/client/src/widgets/collections/geomap/GpxTrack.spec.tsxindex a02079fa77..deecf60a22 100644--- a/apps/client/src/widgets/collections/geomap/GpxTrack.spec.tsx+++ b/apps/client/src/widgets/collections/geomap/GpxTrack.spec.tsx@@ -114,8 +114,8 @@ const TWO_SEGMENT_GPX = `<?xml version="1.0" encoding="UTF-8"?>/** The note the track belongs to, which every one of its layers is named after. */const NOTE_ID = "gpxNoteId1";-/** The note's colour: the line is drawn in it and the marks' pins are filled with it, under the ids- * the shared rasterizer files pins by (see Markers). */+/** The note's color, which the line is drawn in and the marks' pins filled with, under the ids+ * the shared rasterizer stores pins by (see Markers). */const NOTE_COLOR = "purple";const NOTE_ICON = "bx bx-cycling";const START_IMAGE = markerImageId(NOTE_COLOR, NOTE_ICON);diff --git a/apps/client/src/widgets/collections/geomap/GpxTrack.tsx b/apps/client/src/widgets/collections/geomap/GpxTrack.tsxindex f9d2125aad..4bc31d6320 100644--- a/apps/client/src/widgets/collections/geomap/GpxTrack.tsx+++ b/apps/client/src/widgets/collections/geomap/GpxTrack.tsx@@ -16,11 +16,7 @@ export interface GpxTrackProps {/** What the line is named along its length, and what the start mark wears under its pin. */title: string;gpxXmlString: string;- /**- * The note's own colour, as its marker would wear it: the line is drawn in it and the marks'- * pins are filled with it. One colour rather than one per layer, a note having one colour —- * the line and its own start pin used to be given different ones and so disagreed.- */+ /** The note's own color, which both the line and the marks' pins are drawn in. */color: string;/** The note's icon, which the start mark wears; the end and the waypoints have icons of their own. */iconClass: string;diff --git a/apps/client/src/widgets/collections/geomap/Pois.spec.tsx b/apps/client/src/widgets/collections/geomap/Pois.spec.tsxindex 40e0b27552..ae3e472366 100644--- a/apps/client/src/widgets/collections/geomap/Pois.spec.tsx+++ b/apps/client/src/widgets/collections/geomap/Pois.spec.tsx@@ -54,7 +54,7 @@ function tooltipText() {type Listener = (e?: unknown) => void;-/** The layers a drawn shape offers to be pointed at by, named after its note (see ShapeLayer). */+/** The hit layers a drawn shape adds, named after its note (see ShapeLayer). */const SHAPE_FILL_LAYER = "shape-fill-note1";const SHAPE_HIT_LAYER = "shape-hit-note1";@@ -262,8 +262,8 @@ describe("geo map Pois", () => {});/**- * A drawn shape is one of the map's own, and an area covers every place standing inside it. Left- * out of the hit test, the click opened the place alongside the pane the shape had just opened.+ * A drawn shape is one of the map's own, and an area covers every place inside it. Left out of+ * the hit test, a click opened the place alongside the pane the shape had just opened.*/it("leaves a click that landed inside a drawn shape to the shape", async () => {const map = fakeMap({ ownLayerIds: [ SHAPE_FILL_LAYER, SHAPE_HIT_LAYER ] });@@ -382,7 +382,7 @@ describe("geo map Pois", () => {expect(map.cursor).toBe("pointer");});- /** An area covers every place inside it, so its own name is what a rest there asks for. */+ /** An area covers every place inside it, so a hover there names the shape. */it("leaves the pointer to a drawn shape the place stands inside", async () => {const map = fakeMap({ ownLayerIds: [ SHAPE_FILL_LAYER, SHAPE_HIT_LAYER ] });await renderPois(map);diff --git a/apps/client/src/widgets/collections/geomap/Pois.tsx b/apps/client/src/widgets/collections/geomap/Pois.tsxindex 0271839bda..0317be5bd5 100644--- a/apps/client/src/widgets/collections/geomap/Pois.tsx+++ b/apps/client/src/widgets/collections/geomap/Pois.tsx@@ -240,8 +240,8 @@ export function poiLayers(map: MapLibreGLMap) {* Whether the map has something of its own under the pointer — a marker, a cluster, a track, a drawn* shape, or the pin of a place already in hand. Those stand above the base map and answer for it.*- * A shape counts over its whole area rather than along its boundary, which is what `shapeHitLayers`- * gives: the fill covers every place standing inside it, and those belong to the shape.+ * A shape counts over its whole area rather than along its boundary, `shapeHitLayers` including+ * the fill: a place standing inside a shape belongs to the shape.*/function isOwnUnderPointer(map: MapLibreGLMap, point: MapMouseEvent["point"]) {const own = [ MARKER_LAYER, PLACE_LAYER, ...CLUSTER_LAYERS, ...trackHitLayers(map), ...shapeHitLayers(map) ]diff --git a/apps/client/src/widgets/collections/geomap/ShapeLayer.spec.tsx b/apps/client/src/widgets/collections/geomap/ShapeLayer.spec.tsxindex c557064038..4dcaebfee8 100644--- a/apps/client/src/widgets/collections/geomap/ShapeLayer.spec.tsx+++ b/apps/client/src/widgets/collections/geomap/ShapeLayer.spec.tsx@@ -1,8 +1,8 @@/*** The hand-drawn shape (see ShapeLayer.tsx): that it goes onto a loaded style and not before, that- * a line is a stroke alone while an area wears a wash under the same stroke, that it is put back+ * a line is a stroke alone while an area adds a fill under the same stroke, that it is re-added* after a style switch wipes the map, and that it leaves nothing behind when it goes. Then the name- * a shape answers a hover with, which is the only thing on the map that says what it is.+ * a shape answers a hover with, the only thing on the map that names it.*/import { render } from "preact";import { act } from "preact/test-utils";@@ -84,14 +84,14 @@ function fakeMap() {return [ ...layers.keys() ];},- /** The style finishing, which is what `style.load` announces. */+ /** The style finishing, which is what `style.load` reports. */loadStyle() {loaded = true;for (const listener of listeners.get("style.load") ?? []) {listener();}},- /** A style switch as the shape experiences one: everything wiped, then `style.load` again. */+ /** A style switch: everything wiped, then `style.load` again. */switchStyle() {sources.clear();layers.clear();@@ -141,12 +141,12 @@ describe("ShapeLayer", () => {};expect(source.data.geometry.type).toBe("LineString");expect(source.data.geometry.coordinates).toEqual(LINE.coordinates);- // The note the shape stands for rides in the feature, for whatever comes to hit-test it.+ // The note the shape belongs to is carried in the feature, for the hit test to read.expect(source.data.properties.id).toBe(NOTE_ID);const stroke = map.layers.get(`shape-stroke-${NOTE_ID}`) as { paint: Record<string, unknown> };expect(stroke.paint["line-color"]).toBe("purple");- // No wash under a line: it encloses nothing.+ // No fill under a line, which encloses nothing.expect(map.layers.has(`shape-fill-${NOTE_ID}`)).toBe(false);act(() => render(null, container));@@ -162,7 +162,7 @@ describe("ShapeLayer", () => {data: { geometry: { type: string; coordinates: [number, number][][] } };};expect(source.data.geometry.type).toBe("Polygon");- // The label leaves the closing point unwritten; GeoJSON wants the ring ended where it began.+ // The label leaves the closing point unwritten, and GeoJSON ends the ring where it began.expect(source.data.geometry.coordinates[0]).toEqual([ ...POLYGON.coordinates, POLYGON.coordinates[0] ]);const fill = map.layers.get(`shape-fill-${NOTE_ID}`) as { paint: Record<string, unknown> };@@ -215,12 +215,12 @@ describe("ShapeLayer", () => {});it("waits for the style, and is put back when a style switch wipes the map", () => {- // Mounted before the style has loaded — as a shape whose note arrives early always is —- // nothing can go on yet.+ // Mounted before the style has loaded, as a shape whose note arrives early is, so nothing+ // can go on yet.renderShape(LINE, { styleLoaded: false });expect(map.sources.size).toBe(0);- // MapStyleLoaded flipping true is a new render; the style itself also announces itself.+ // MapStyleLoaded turning true is a new render, and the style reports itself as well.act(() => map.loadStyle());renderShape(LINE, { styleLoaded: true });expect(map.sources.has(shapeSourceId(NOTE_ID))).toBe(true);@@ -249,14 +249,14 @@ function hoverMap(shapeLayers = [ `shape-hit-${NOTE_ID}` ]) {return {get cursor() { return canvas.style.cursor; },- /** The pointer another layer's own hover has set, which this one must not clear. */+ /** The cursor another layer's hover has set, which this one must not clear. */setCursor(cursor: string) { canvas.style.cursor = cursor; },/** Which of the map's notes the pointer is really over, the marker being the smaller target. */setUnderPointer({ markerNoteId = null as string | null, shapeNoteId = null as string | null }) {marker = markerNoteId;shape = shapeNoteId;},- /** A shape drawn while the map is up, which MapLibre announces as a change to the style. */+ /** A shape drawn while the map is up, which MapLibre reports as a change to the style. */addShapeLayer(id: string) {layers = [ ...layers, id ];fire("styledata");@@ -296,7 +296,7 @@ function hoverMap(shapeLayers = [ `shape-hit-${NOTE_ID}` ]) {}describe("ShapeNames", () => {- /** Long enough for the rest the name is held back for, whatever that rest is set to. */+ /** Long enough for the delay the name is held back by, whatever it is set to. */const RESTED = 500;let container: HTMLElement;@@ -342,14 +342,14 @@ describe("ShapeNames", () => {expect(nameText()).toBe("The lot");expect(map.cursor).toBe("pointer");- // A click is always something being done, whose result the name would otherwise stand over.+ // The name would otherwise stand over whatever the click opened.act(() => map.click());expect(nameText()).toBeNull();});/**- * A pin standing inside a polygon is the smaller target and the one a click means, and it sets- * a pointer of its own — so the shape neither names itself nor clears what the marker has set.+ * A pin inside a polygon is the smaller target and the one a click means, and it sets its own+ * cursor, so the shape neither names itself nor clears what the marker set.*/it("says nothing while a marker standing on the shape is what the pointer is on", () => {buildNote({ id: NOTE_ID, title: "The lot", "#geoShape": "polygon:45.79,24.13 45.81,24.16 45.89,24.08" });@@ -357,7 +357,7 @@ describe("ShapeNames", () => {const map = hoverMap();renderNames(map);map.setUnderPointer({ markerNoteId: "markerNoteId1", shapeNoteId: NOTE_ID });- // The pointer the marker's own hover has just set (see Markers).+ // The cursor the marker's own hover has just set (see Markers).map.setCursor("pointer");map.hover();@@ -368,7 +368,7 @@ describe("ShapeNames", () => {expect(map.cursor).toBe("pointer");});- /** A shape drawn while the map is up adds a layer, which nothing was watching until now. */+ /** A shape drawn while the map is up adds a layer nothing was watching. */it("watches a shape drawn after it was bound", () => {const map = hoverMap();renderNames(map);diff --git a/apps/client/src/widgets/collections/geomap/ShapeLayer.tsx b/apps/client/src/widgets/collections/geomap/ShapeLayer.tsxindex a8ed3eedc8..cd4691a08a 100644--- a/apps/client/src/widgets/collections/geomap/ShapeLayer.tsx+++ b/apps/client/src/widgets/collections/geomap/ShapeLayer.tsx@@ -20,31 +20,27 @@ const HIT_LAYER_PREFIX = "shape-hit-";const HIT_WIDTH = 20;interface ShapeLayerProps {- /** The note the shape belongs to, which is what its source and layers are named after. */+ /** The note the shape belongs to. Its source and layers are named after it. */noteId: string;- /** The shape off the note's label, as {@link parseGeoShape} hands it over. */+ /** The shape read off the note's label by {@link parseGeoShape}. */shape: GeoShape;- /** What the shape is drawn in — the note's own colour, as a track's would be. */+ /** The note's own color, which the shape is drawn in, as a track is. */color: string;}/*** A shape drawn onto the map by hand, read back off its note's `#geoShape` label (see shapes.ts).*- * The GPX track's little sibling: the same source-and-layers arrangement, the same put-it-back-on-- * every-style-load dance, without the file, the flags or the name written along it. A line is its- * stroke alone; an area wears a wash of its colour under the same stroke, which is its boundary- * drawn the way the line is. A transparent wide line over the boundary takes the pointer hits that- * select the shape (see {@link shapeHitLayers}). What a track has that this does not yet: the label- * layer and the marks. Each is a straight lift from {@link GpxTrack} when its turn comes.+ * Built like {@link GpxTrack}: one source per note, with its layers re-added on every style load. A+ * line is drawn as its stroke alone, an area as a fill under the same stroke. A wide transparent+ * line over the boundary takes the pointer hits that select the shape (see {@link shapeHitLayers}).*/export function ShapeLayer({ noteId, shape, color }: ShapeLayerProps) {const parentMap = useContext(ParentMap);const styleLoaded = useContext(MapStyleLoaded);- // The shape as a dependency the effect can compare: the object is rebuilt on every parse of- // the label, so handing it over as-is would tear the layers down and put them back per render.- // Its label spelling is exactly such a comparison — one string, stable across parses.+ // parseGeoShape() rebuilds the object on every render, so the effect compares the label+ // spelling instead, which is stable across parses.const shapeKey = serializeGeoShape(shape);useEffect(() => {@@ -57,9 +53,8 @@ export function ShapeLayer({ noteId, shape, color }: ShapeLayerProps) {const hitLayerId = `${HIT_LAYER_PREFIX}${noteId}`;const hasArea = shape.type !== "line";- // The shape lives in the map style, which setStyle() wipes for a URL-named vector style- // (keepAdditions cannot carry what it never saw; see map.tsx) — so it is put back on every- // style load, and each piece only if it is missing, exactly as a track is.+ // setStyle() wipes the shape for a URL-named vector style (keepAdditions cannot carry+ // what it never saw; see map.tsx), so every missing piece is re-added on each style load.function addShapeLayers() {try {if (!map.getSource(sourceId)) {@@ -67,13 +62,12 @@ export function ShapeLayer({ noteId, shape, color }: ShapeLayerProps) {type: "geojson",data: {type: "Feature",- // The note the shape stands for, carried in the feature the way a- // track's is, for whatever comes to hit-test shapes.+ // The note the shape belongs to, which featureAt() reads back.properties: { id: noteId },geometry: shape.type === "line"? { type: "LineString", coordinates: shape.coordinates }- // An area is its ring closed back up — the ring the label spells- // for a polygon, or the one walked out of a circle's two numbers.+ // An area is its ring closed back up: a polygon's own points,+ // or the ring walked out of a circle's centre and radius.: { type: "Polygon", coordinates: [ closeRing(shape.type === "circle"? circleRing(shape.center, shape.radiusMeters)@@ -83,7 +77,7 @@ export function ShapeLayer({ noteId, shape, color }: ShapeLayerProps) {});}- // The wash before the stroke, so the boundary is drawn over it rather than under.+ // Added before the stroke, so the boundary draws over the fill rather than under.if (hasArea && !map.getLayer(fillLayerId)) {map.addLayer({id: fillLayerId,@@ -102,7 +96,7 @@ export function ShapeLayer({ noteId, shape, color }: ShapeLayerProps) {type: "line",source: sourceId,layout: {- // Otherwise a line doubling back meets its own corners as spikes,+ // Otherwise a line doubling back meets its own corners as spikes// and ends in a flat stub."line-join": "round","line-cap": "round"@@ -114,9 +108,10 @@ export function ShapeLayer({ noteId, shape, color }: ShapeLayerProps) {});}- // Takes the pointer hits on the boundary, the 3px stroke being too thin to click- // reliably. Drawn at zero opacity rather than hidden: MapLibre drops a layer from- // queryRenderedFeatures() for `visibility: none` but not for being invisible.+ // Takes the pointer hits on the boundary, the 3px stroke being too thin to+ // click reliably. Drawn at zero opacity rather than hidden, since MapLibre drops a+ // layer from queryRenderedFeatures() for `visibility: none` but not for being+ // invisible.if (!map.getLayer(hitLayerId)) {map.addLayer({id: hitLayerId,@@ -130,7 +125,7 @@ export function ShapeLayer({ noteId, shape, color }: ShapeLayerProps) {});}} catch (e) {- // Only worth a word if the style was ready and it still would not take the shape.+ // Only worth reporting if the style was ready and still would not take the shape.if (styleLoaded) {console.warn("Geo map: could not draw a shape —", e);}@@ -145,7 +140,7 @@ export function ShapeLayer({ noteId, shape, color }: ShapeLayerProps) {return () => {map.off("style.load", addShapeLayers);try {- // Every layer before the source they draw from: one still in use cannot be removed.+ // Layers before the source they draw from: a source still in use cannot be removed.for (const layer of [ hitLayerId, strokeLayerId, fillLayerId ]) {if (map.getLayer(layer)) {map.removeLayer(layer);@@ -166,14 +161,11 @@ export function ShapeLayer({ noteId, shape, color }: ShapeLayerProps) {/*** The name of the drawn shape under the pointer, shown once the pointer has rested on it.*- * A shape carries nothing on the map to say what it is: a marker's title hangs under its pin and a- * track's is written along its line, but a shape is drawn bare. Named on hover rather than labelled- * outright, which is how the base map's places are named as well (see Pois) — a title written across- * every shape would set the stock name of each unnamed one against the map, and a name over an area- * covers the very thing it names.+ * A shape carries no name on the map, unlike a marker's title under its pin or a track's along its+ * line. Shown on hover rather than drawn on the map, as the base map's places are (see Pois): a+ * shape starts out titled "New note", and a name over an area covers what it names.*- * Mounted once for the whole map rather than once per shape, every shape's layers being watched in- * the one binding.+ * Mounted once for the whole map, one binding watching every shape's layers.*/export function ShapeNames() {const map = useContext(ParentMap);@@ -183,9 +175,8 @@ export function ShapeNames() {answer: (e) => {if (!map) return null;- // A marker or a track standing on the shape is the smaller target and the one a click- // means (see featureAt), and it sets a pointer of its own — so the shape says nothing- // while one of them is what the pointer is really on.+ // A marker or track over the shape is the smaller target and the one a click means+ // (see featureAt), and it sets its own cursor, so the shape defers to it.const feature = featureAt(map, e.point);if (!feature) return null;if (!isShapeFeature(feature)) return "deferred";@@ -195,8 +186,8 @@ export function ShapeNames() {return {id: note.noteId,- // Where the pointer came to rest, an area having no one point to stand at. Held- // there while the pointer stays on the same shape rather than following it.+ // Where the pointer came to rest, an area having no single point to anchor to.+ // The name stays there while the pointer remains on the same shape.lngLat: [ e.lngLat.lng, e.lngLat.lat ],icon: note.getIcon(),text: note.title@@ -207,10 +198,8 @@ export function ShapeNames() {return null;}-/**- * The one source a shape's layers draw from, named for whoever needs to read the shape back off- * the map — as a track's is (see `trackSourceId`).- */+/** The single source a shape's layers draw from, named so callers can read the shape back off+ * the map, as `trackSourceId` is. */export function shapeSourceId(noteId: string) {return `shape-source-${noteId}`;}@@ -240,7 +229,7 @@ export function featureAt(map: MapLibreGLMap, point: Point): MapGeoJSONFeature |?? map.queryRenderedFeatures(point, { layers: shapeHitLayers(map) })[0];}-/** Whether {@link featureAt} answered with a shape rather than with a marker or a track. */+/** Whether {@link featureAt} returned a shape rather than a marker or a track. */function isShapeFeature(feature: MapGeoJSONFeature) {return feature.layer.id.startsWith(HIT_LAYER_PREFIX) || feature.layer.id.startsWith(FILL_LAYER_PREFIX);}diff --git a/apps/client/src/widgets/collections/geomap/api.spec.ts b/apps/client/src/widgets/collections/geomap/api.spec.tsindex 313c46fe81..e0d338b5cc 100644--- a/apps/client/src/widgets/collections/geomap/api.spec.ts+++ b/apps/client/src/widgets/collections/geomap/api.spec.ts@@ -122,9 +122,9 @@ describe("geo map api", () => {expect(created).toEqual({ noteId: "created" });expect(createNote).toHaveBeenCalledWith(parent.noteId, expect.objectContaining({type: "text",- // Named and iconed by exactly the rules a placed marker is named and iconed by: no- // title, so a `#titleTemplate` on the map applies, and no icon, so getNoteIcon draws- // the shape the label names and `#child:iconClass` or a template can override it.+ // Named and iconed by the rules a placed marker is: no title, so a `#titleTemplate`+ // on the map applies, and no icon, so getNoteIcon draws the shape the label names and+ // `#child:iconClass` or a template can override it.title: undefined,activate: false,attributes: [diff --git a/apps/client/src/widgets/collections/geomap/api.ts b/apps/client/src/widgets/collections/geomap/api.tsindex b224afbe12..16abe8aa89 100644--- a/apps/client/src/widgets/collections/geomap/api.ts+++ b/apps/client/src/widgets/collections/geomap/api.ts@@ -164,11 +164,10 @@ async function createNoteAt(}/**- * Makes a note of a shape drawn on the map, and hands it back for the pane to open on.+ * Creates the note for a shape drawn on the map, and returns it for the pane to open on.*- * A marker note in every way but the label: the whole shape in `#geoShape` where a marker keeps its- * point in `#geolocation` (see shapes.ts). The note is the shape the way a marker note is its pin,- * so it is named and iconed by the same rules, and the content stays the user's to write.+ * A marker note but for the label, which holds the whole shape in `#geoShape` where a marker keeps+ * its point in `#geolocation` (see shapes.ts). Naming and icons follow the same rules.*/export async function createShapeNote(parentNote: FNote, shape: GeoShape) {return createMapNote(parentNote, [@@ -177,12 +176,12 @@ export async function createShapeNote(parentNote: FNote, shape: GeoShape) {}/**- * Creates a note of the map's own, carrying whatever puts it on the map.+ * Creates one of the map's own notes, carrying whatever puts it on the map.*- * No title is sent unless the caller has one worth keeping, which leaves the naming where every- * other new note's is: the server's, and so a `#titleTemplate` on the map's if it carries one. No- * `#iconClass` either, `getNoteIcon` drawing a note by the geo label it carries (see commons), so- * an icon the map hands down through `#child:iconClass` or a template still applies.+ * A title is sent only where the caller has one, so naming falls to the server and to a+ * `#titleTemplate` on the map note where it carries one. No `#iconClass` is sent either, since+ * `getNoteIcon` draws a note by the geo label it carries (see commons), leaving an icon the map+ * hands down through `#child:iconClass` or a template to apply.*/async function createMapNote(parentNote: FNote, attributes: Omit<AttributeRow, "noteId" | "attributeId">[], title?: string) {diff --git a/apps/client/src/widgets/collections/geomap/hover_name.css b/apps/client/src/widgets/collections/geomap/hover_name.cssindex ebfb70551f..bf67269afd 100644--- a/apps/client/src/widgets/collections/geomap/hover_name.css+++ b/apps/client/src/widgets/collections/geomap/hover_name.css@@ -1,7 +1,7 @@-/* The name of whatever the pointer is resting on — a place of the base map, a drawn shape (see- hover_name.ts). MapLibre puts its popups inside the map's own container, so these are scoped as- everything else over the map is; the box is MapLibre's, dressed in the same tokens the app's own- tooltips wear, with what the older themes can be asked for. */+/* The name of whatever the pointer rests on: a place of the base map, or a drawn shape (see+ hover_name.ts). MapLibre puts its popups inside the map's own container, so these are scoped like+ everything else over the map. The box is MapLibre's, dressed in the tokens the app's own tooltips+ use, with fallbacks for the themes that do not define them. */.geo-map-container .geo-hover-name .maplibregl-popup-content {padding: var(--tooltip-padding, 4px 9px);border-radius: var(--tooltip-border-radius, 5px);@@ -11,12 +11,11 @@color: var(--tooltip-foreground-color, var(--main-text-color));font-family: var(--main-font-family);font-size: var(--tooltip-font-size, 0.9rem);- /* A name is read, not reached: left under the pointer it would take the click of the very- thing it names. */+ /* The name would otherwise take the click meant for the thing it names. */pointer-events: none;}-/* Drawn in a hard white by MapLibre, which is not the colour of the box above it on every theme. */+/* MapLibre draws the tip a hard white, which does not match the box on every theme. */.geo-map-container .geo-hover-name .maplibregl-popup-tip {display: none;}diff --git a/apps/client/src/widgets/collections/geomap/hover_name.ts b/apps/client/src/widgets/collections/geomap/hover_name.tsindex bfe2a43db4..f52e9faf3c 100644--- a/apps/client/src/widgets/collections/geomap/hover_name.ts+++ b/apps/client/src/widgets/collections/geomap/hover_name.ts@@ -5,61 +5,52 @@ import {} from "maplibre-gl";import { useEffect, useRef } from "preact/hooks";-/**- * How long the pointer has to rest on something before its name is shown.- *- * Shorter than the wait a marker's preview sits out, that one reading a note from the server while- * these names are already in hand — but long enough that sweeping the pointer across a crowded- * map does not name everything on the way past.- */+/** How long the pointer rests on something before its name appears. Shorter than the wait in+ * Tooltips, which fetches the note, but long enough not to name what the pointer sweeps past. */const REST_DELAY = 200;-/** How far the name stands off what it names, be that a place's icon or the pointer itself. */+/** Distance in pixels between the popup and the point it is anchored to. */const NAME_OFFSET = 10;-/** A name to show, and with it the pointer saying the thing under it answers a click. */+/** A name to show, which also sets the cursor to `pointer`. */export interface HoverName {- /** Tells one thing from the next, so the pointer crossing between them replaces the name. */+ /** Distinguishes one feature from the next, so moving between them replaces the name. */id: string;- /** Where the name stands. */+ /** Where the popup is anchored. */lngLat: [number, number];- /** The boxicons classes of the mark beside the name, where the thing wears one. */+ /** Boxicons classes for the icon beside the name, where the feature has one. */icon?: string | null;text: string;}/**- * What the pointer is resting on: a name to show, nothing at all, or something drawn above that- * answers for it. The last is not the same as nothing — whatever stands above has set its own- * cursor, so this leaves the cursor alone rather than clearing what that has just set.+ * What the pointer is over: a name to show, nothing, or `"deferred"` for a feature another layer+ * owns. `"deferred"` differs from nothing in that it leaves the cursor alone, the layer that owns+ * the feature having just set it.*/export type HoverAnswer = HoverName | null | "deferred";interface HoverNameOptions {- /** The layers the pointer is watched on, read afresh whenever the style changes. */+ /** The layers to watch, read again whenever the style changes. */layers: (map: MapLibreGLMap) => string[];- /** What the pointer is resting on, given the features those layers reported under it. */+ /** What the pointer is over, given the features those layers report under it. */answer: (e: MapMouseEvent & { features?: MapGeoJSONFeature[] }) => HoverAnswer;- /** Held off entirely, for a map busy with something the pointer means instead. */+ /** Binds nothing, for a map where the pointer means something else. */disabled?: boolean;}/**- * The name of the thing under the pointer, shown in a small popup once the pointer has rested.+ * Shows the name of the feature under the pointer in a small popup, once the pointer has rested.*- * What every hovered name over this map has in common, the caller saying only which layers to watch- * and what it finds there: the base map's places (see Pois) and the shapes drawn onto it (see- * ShapeLayer). Both are named from something already in hand, so neither waits on the server the- * way a marker's preview does (see Tooltips).+ * Shared by Pois and ShapeLayer, which supply only the layers to watch and the name to show. Both+ * name a feature from data already loaded, unlike Tooltips, which fetches the note.*- * The name is put away on a click, whatever the click was for, and does not come back until the- * pointer has left and returned — a click is always something being done, whose result the name- * would otherwise stand over.+ * A click hides the name, and it does not return until the pointer leaves the feature and comes+ * back, so it never covers what the click opened.*/export function useHoverName(parentMap: MapLibreGLMap | null, { layers, answer, disabled }: HoverNameOptions) {- // Read through a ref so a caller can hand over plain arrows without the handlers being bound- // again on every render.+ // Read through a ref so inline callbacks do not rebind the handlers on every render.const latest = useRef({ layers, answer });latest.current = { layers, answer };@@ -71,15 +62,14 @@ export function useHoverName(const popup = new Popup({closeButton: false,closeOnClick: false,- // Otherwise MapLibre puts the caret in the popup as it opens, taking the focus out of- // whatever the user was typing in (see Tooltips).+ // MapLibre otherwise focuses the popup as it opens, taking focus out of the search box.focusAfterOpen: false,offset: NAME_OFFSET,className: "geo-hover-name"});let bound: string[] = [];- /** What the name belongs to, or what the last click was on until the pointer leaves it. */+ /** The feature the name belongs to, or the one last clicked until the pointer leaves it. */let named: string | null = null;let showTimer: ReturnType<typeof setTimeout> | undefined;@@ -107,9 +97,8 @@ export function useHoverName(}setCursor("pointer");- // Watched by the move rather than by `mouseenter`, which fires on entering the layer- // rather than the thing: the pointer crossing from one to the next never leaves the- // layer, and the first name would stay up over the second.+ // Tracked on "mousemove" rather than "mouseenter", which fires on entering the layer:+ // moving from one feature to the next never leaves it, so the first name would stay up.if (answered.id === named) return;named = answered.id;@@ -146,15 +135,13 @@ export function useHoverName(}bind();- // Two ways the layers under the pointer change: a style switch replaces every one of them,- // and a layer added or taken away within a style, a shape drawn or removed, changes which- // of them there are. `bind` does nothing where they turn out to be the same, so the second,- // which MapLibre reports freely, costs a comparison.+ // "style.load" covers a style switch, which replaces every layer; "styledata" covers a+ // layer added or removed within one, such as a shape being drawn. bind() returns early when+ // the list is unchanged, so the frequent "styledata" costs only a comparison.map.on("style.load", bind);map.on("styledata", bind);- // `named` is left standing rather than cleared, which is what keeps the name from coming- // back over whatever the click has just opened: the thing under the pointer stays the one- // already named until the pointer leaves it.+ // hide() leaves `named` set, so the name does not reappear over what the click opened+ // until the pointer moves to another feature.map.on("click", hide);return () => {@@ -163,14 +150,14 @@ export function useHoverName(map.off("click", hide);unbind();hide();- // The pointer is put back by hand, since this can be torn down while it sits on- // something and the `mouseleave` that would have cleared it is no longer listened for.+ // Reset by hand: this can be torn down while the pointer rests on a feature, and the+ // "mouseleave" that would have cleared the cursor is no longer bound.setCursor("");};}, [ parentMap, disabled ]);}-/** The name as it is shown: the mark the thing wears, where it wears one, and what it is called. */+/** The popup contents: the feature's icon, where it has one, and its name. */function nameLabel({ icon, text }: HoverName) {const label = document.createElement("span");label.className = "geo-hover-name-label";@@ -182,8 +169,8 @@ function nameLabel({ icon, text }: HoverName) {}const name = document.createElement("span");- // A place is named by whatever OpenStreetMap holds and a shape by its note's title, neither of- // which is ours to read as markup.+ // A place's name comes from OpenStreetMap and a shape's from its note title, neither of which+ // is markup.name.textContent = text;label.appendChild(name);diff --git a/apps/client/src/widgets/collections/geomap/index.tsx b/apps/client/src/widgets/collections/geomap/index.tsxindex 4dc671e0dc..c40dd7a2b5 100644--- a/apps/client/src/widgets/collections/geomap/index.tsx+++ b/apps/client/src/widgets/collections/geomap/index.tsx@@ -72,14 +72,13 @@ interface MapData {/*** What the next click on the map is for, where it is for anything at all: a new note is to be created- * there, the marker of the note named here is to be moved there, or a line is being drawn point by+ * there, the marker of the note named here is to be moved there, or a shape is being drawn point by* point. `undefined` is a map that is only being looked at, which is every map most of the time.*- * The three are one state rather than three because they are alternatives — a click cannot mean two- * of them — and because the note being moved has nowhere else to be kept where it could not go- * missing. Drawing differs from the other two in taking many clicks rather than one, which is why- * the map's own click handler leaves it alone (see onClick): the clicks belong to the drawing- * session (see DrawLine) until it finishes or is stood down.+ * One state rather than three because they are alternatives, a click meaning only one of them, and+ * because the note being moved has nowhere else to be kept where it could not go missing. Drawing+ * takes many clicks rather than one, so the map's own click handler leaves it alone (see onClick)+ * and the clicks belong to {@link DrawShape} until the session finishes or is disarmed.*/type Placement =| { mode: "new" }@@ -254,15 +253,15 @@ export default function GeoView({ note, noteIds, viewConfig, saveConfig }: ViewM}, []);const startMarkerRelocation = useCallback((noteId: string) => setPlacement({ mode: "move", noteId }), []);const toggleDrawing = useCallback((tool: DrawTool) => {- // A press on the armed tool stands the map down; a press on another switches to it, the- // way + takes over a map armed to move a marker.+ // A press on the armed tool disarms the map, and a press on another switches to it, as+ // the marker button takes over a map armed to move a marker.setPlacement((current) => current?.mode === "draw" && current.tool === tool ? undefined : { mode: "draw", tool });}, []);/**- * Makes a note of a finished shape and opens the pane on it, title selected, exactly as a- * placed marker is offered for naming (see createNoteAt). Disarming comes first so a failure- * to create the note does not leave the map drawing a shape nobody is looking at any more.+ * Creates the note for a finished shape and opens the pane on it, title selected, as a placed+ * marker is offered for naming (see createNoteAt). Disarming comes first, so a failure to+ * create the note does not leave the map still drawing.*/const finishShape = useCallback(async (shape: GeoShape) => {setPlacement(undefined);@@ -351,8 +350,8 @@ export default function GeoView({ note, noteIds, viewConfig, saveConfig }: ViewM}, [ placement ]);const onClick = useCallback(async (e: GeoMouseEvent) => {- // A drawing session's clicks are its vertices, one by one — not this handler's to spend,- // and above all not to disarm on: the session runs until it finishes or is stood down.+ // A drawing session's clicks are its vertices, so this handler neither consumes them nor+ // disarms on them: the session runs until it finishes or is disarmed.if (!placement || placement.mode === "draw") return;// Leaving placement mode closes the instruction toast via the effect's cleanup. The state is@@ -452,8 +451,7 @@ export default function GeoView({ note, noteIds, viewConfig, saveConfig }: ViewM<Tooltips selectedNoteId={selection?.noteId ?? null} paneMaximized={paneMaximized} />{/* The preview under the pointer while a click is armed to mean a place — the notebeing moved wearing its own pin, a note to be created wearing the one the map- would give it (see GhostPin). A drawing session previews itself, so no ghost- then. */}+ would give it (see GhostPin). Terra Draw previews a drawing session itself. */}{placement && placement.mode !== "draw" && <GhostPinparentNote={note}note={placement.mode === "move"@@ -608,10 +606,9 @@ function NoteGpxTrack({ note, hideLabels, isDarkTheme }: { note: FNote, hideLabe}/**- * A note's drawn shape, where the note carries one — a shape written into its `#geoShape` label- * (see shapes.ts). A label the shape cannot be read from draws nothing, the same nothing a note- * with no shape at all draws: the label is user-editable like any other, and a map is no place to- * report a parse error.+ * A note's drawn shape, read from its `#geoShape` label (see shapes.ts). A label that cannot be+ * parsed draws nothing, as a note with no shape does: the label is user-editable like any other,+ * and a map is no place to report a parse error.*/function NoteShapeWrapper({ note }: { note: FNote }) {const [ shapeValue ] = useNoteLabel(note, SHAPE_ATTRIBUTE);diff --git a/apps/client/src/widgets/collections/geomap/shapes.spec.ts b/apps/client/src/widgets/collections/geomap/shapes.spec.tsindex 7fecaed1f0..50ed3172a5 100644--- a/apps/client/src/widgets/collections/geomap/shapes.spec.ts+++ b/apps/client/src/widgets/collections/geomap/shapes.spec.ts@@ -60,7 +60,7 @@ describe("parseGeoShape", () => {});it("refuses what is not a shape", () => {- // An unknown kind, no kind at all, and plain junk alike.+ // An unknown kind, no kind at all, and plain junk.expect(parseGeoShape("blob:1,2 3,4 5,6")).toBeNull();expect(parseGeoShape("1,2 3,4")).toBeNull();expect(parseGeoShape("")).toBeNull();@@ -83,7 +83,7 @@ describe("parseGeoShape", () => {center: [ 2.29, 48.85 ],radiusMeters: 500});- // No radius, two centres, a reach of nothing, and one of nonsense.+ // No radius, two centers, a radius of nothing, and one of nonsense.expect(parseGeoShape("circle:48.85,2.29")).toBeNull();expect(parseGeoShape("circle:48.85,2.29 48.86,2.35 500")).toBeNull();expect(parseGeoShape("circle:48.85,2.29 0")).toBeNull();@@ -113,21 +113,21 @@ describe("rings", () => {const ring = circleRing(center, radiusMeters);expect(ring).toHaveLength(64);- // Not closed — the closing repeat is closeRing's to add, as for any other ring.+ // Not closed: the closing repeat is closeRing's to add, as for any other ring.expect(ring[0]).not.toEqual(ring[ring.length - 1]);- // Every point stands the same distance out, give or take the arithmetic.+ // Every point is the same distance out, give or take the arithmetic.for (const point of ring) {expect(haversineMeters(center, point)).toBeCloseTo(radiusMeters, 0);}- // And the ring stands around where it was asked to.+ // And the ring is centered where it was asked to be.const [ lng, lat ] = ringCenter(ring) ?? [ NaN, NaN ];expect(lng).toBeCloseTo(center[0], 4);expect(lat).toBeCloseTo(center[1], 4);});});-/** How the box itself is measured is `boundsOf`'s own business (see coordinates.spec); what these- * pin down is which points of a shape are handed to it. */+/** How the box is measured is `boundsOf`'s business (see coordinates.spec); these pin down which+ * points of a shape are handed to it. */describe("bounds", () => {it("boxes a line and a polygon by their own points", () => {expect(geoShapeBounds({@@ -141,14 +141,14 @@ describe("bounds", () => {})).toEqual([ [ 24.08, 45.79 ], [ 24.16, 45.96 ] ]);});- /** A circle is stored as a centre and a radius, so the box has to cover the radius. */+ /** A circle is stored as a center and a radius, so the box has to cover the radius. */it("boxes a circle across the ring its radius walks out", () => {const circle: GeoShape = { type: "circle", center: [ 2.29, 48.85 ], radiusMeters: 1000 };const bounds = geoShapeBounds(circle);const [ [ west, south ], [ east, north ] ] = bounds ?? [ [ NaN, NaN ], [ NaN, NaN ] ];- // A kilometre spans about 0.018° of latitude, and more of longitude at this latitude. The- // centre sits in the middle of both.+ // A kilometer spans about 0.018° of latitude, and more of longitude at this latitude.+ // The center sits in the middle of both.expect((south + north) / 2).toBeCloseTo(48.85, 4);expect((west + east) / 2).toBeCloseTo(2.29, 4);expect(north - south).toBeCloseTo(0.018, 3);@@ -164,7 +164,7 @@ describe("bounds", () => {});});-/** The distance between two points the way the ring generator must honour it: over the sphere. */+/** The distance between two points as the ring generator measures it: over the sphere. */function haversineMeters([ lng1, lat1 ]: [number, number], [ lng2, lat2 ]: [number, number]): number {const toRad = (d: number) => (d * Math.PI) / 180;const dLat = toRad(lat2 - lat1);diff --git a/apps/client/src/widgets/collections/geomap/shapes.ts b/apps/client/src/widgets/collections/geomap/shapes.tsindex 9d819a766b..89d6c9db85 100644--- a/apps/client/src/widgets/collections/geomap/shapes.ts+++ b/apps/client/src/widgets/collections/geomap/shapes.ts@@ -1,67 +1,67 @@/*** How a drawn shape is written onto its note, and read back off it.*- * A shape lives in a label the way a marker's location does (see `LOCATION_ATTRIBUTE` in Markers):- * the same `lat,lng` atom, pluralized — a prefix naming what the points make, then the points.- * `#geoShape=line:48.858093,2.294694 48.860294,2.338629` is the marker format anyone has already- * read, walked along a path; a polygon is the same walk closed at the end (the closing point is- * not written — it is the first one again, and writing it twice would only invite the two copies- * to disagree).+ * A shape lives in a label, like a marker's location (see `LOCATION_ATTRIBUTE` in Markers): the+ * same `lat,lng` pair, repeated, behind a prefix naming what the points make, as in+ * `#geoShape=line:48.858093,2.294694 48.860294,2.338629`. A polygon is a line closed at the end,+ * and the closing point is left out, since writing the first point twice only lets the two copies+ * disagree.*- * A label rather than the note's content so the shape rides the attribute payload the way- * `#geolocation` does: the map draws every shape the moment its children load, with no fetch per- * shape. The trade is a bounded size — a label is no home for a thousand points, which is why the- * drawing tools are the deliberate, click-a-vertex kind rather than freehand (and why an imported- * track keeps its own file-note form; see GpxTrack).+ * A label rather than the note's content, so a shape travels in the attribute payload as+ * `#geolocation` does and the map draws every shape as soon as its children load, with no fetch per+ * shape. The+ * cost is a bounded size, which is why the drawing tools place one vertex per click rather than+ * following a freehand stroke, and why an imported track keeps its file-note form (see GpxTrack).*/import { GEO_SHAPE_ATTRIBUTE } from "@triliumnext/commons";import { type Bounds, boundsOf } from "./coordinates";-/** The label a shape note carries its geometry in. Named in commons because `getNoteIcon` reads it- * to draw a shape note under the shape it draws, as `GEO_LOCATION_ATTRIBUTE` is. */+/** The label a shape note carries its geometry in. Declared in commons because `getNoteIcon`+ * reads it to give a shape note the icon of the shape it draws, as it does+ * `GEO_LOCATION_ATTRIBUTE`. */export { GEO_SHAPE_ATTRIBUTE as SHAPE_ATTRIBUTE } from "@triliumnext/commons";-/** How many decimal places a coordinate keeps: six is about a tenth of a metre, which is already- * more than a hand-placed vertex means. */+/** How many decimal places a coordinate keeps. Six is about a tenth of a meter, which is finer+ * than a hand-placed vertex. */const COORDINATE_DECIMALS = 6;export interface GeoShapeLine {type: "line";- /** `[lng, lat]` pairs — GeoJSON's order, ready for a MapLibre source or a Terra Draw feature. */+ /** `[lng, lat]` pairs, GeoJSON's order, ready for a MapLibre source or a Terra Draw feature. */coordinates: [number, number][];}export interface GeoShapePolygon {type: "polygon";- /** `[lng, lat]` corners of the ring, without the closing repeat of the first — see- * {@link closeRing} for the ring as GeoJSON wants it. */+ /** `[lng, lat]` corners of the ring, without the closing repeat of the first. See+ * {@link closeRing} for the ring in the form GeoJSON expects. */coordinates: [number, number][];}export interface GeoShapeCircle {type: "circle";- /** `[lng, lat]` of the centre. */+ /** `[lng, lat]` of the center. */center: [number, number];- /** How far the circle reaches, in metres — the one number the points would only approximate. */+ /** The circle's radius in meters, which a ring of points would only approximate. */radiusMeters: number;}/** Every kind of shape a note can carry. */export type GeoShape = GeoShapeLine | GeoShapePolygon | GeoShapeCircle;-/** The fewest points each point-list kind is a shape at all with: one point is no line, and two- * no area. A circle is not among them — it is a centre and a reach, not a walk. */+/** The fewest points each point-list kind needs: one point is no line, and two no area. A circle+ * is not listed, being a center and a radius rather than a list of points. */const MINIMUM_POINTS = { line: 2, polygon: 3 } as const;/**- * A shape as its label value: the kind, a colon, and each point as `lat,lng` — the order the- * reader of a `#geolocation` label expects, however the coordinates are held in memory. A circle- * is its centre and then its radius in metres, `circle:48.85,2.29 500`, rather than the ring of- * points a drawing library holds it as: the ring is an approximation regenerated at whatever- * fineness the reader wants (see {@link circleRing}), and sixty-odd points would swell the label- * for less information than two numbers carry.+ * A shape as its label value: the kind, a colon, then each point as `lat,lng`, the order a+ * `#geolocation` label is read in however the coordinates are held in memory.+ *+ * A circle is written as its center and its radius in meters, `circle:48.85,2.29 500`, rather than+ * as the ring a drawing library holds it as. The ring only approximates the circle and is rebuilt+ * at whatever fineness the reader wants (see {@link circleRing}).*/export function serializeGeoShape(shape: GeoShape): string {if (shape.type === "circle") {@@ -75,10 +75,10 @@ export function serializeGeoShape(shape: GeoShape): string {/*** The shape a label value spells, or null where it spells none.*- * Null rather than a throw, whatever is wrong with it — the value is user-editable like any label,- * and a shape that cannot be read is a shape the map does not draw, not an error the map falls- * over on. The rules are only what the geometry itself demands: every point a finite `lat,lng`- * pair, and enough of them for the kind (see {@link MINIMUM_POINTS}).+ * Null rather than a throw: the value is user-editable like any label, so a shape that cannot be+ * read is one the map does not draw rather than an error it falls over on. The rules are only what+ * the geometry demands: every point a finite `lat,lng` pair, and enough of them for the kind (see+ * {@link MINIMUM_POINTS}).*/export function parseGeoShape(value: string): GeoShape | null {const divide = value.indexOf(":");@@ -100,9 +100,9 @@ export function parseGeoShape(value: string): GeoShape | null {}/**- * Whether the note is drawn on the map as a shape, which is what carrying a readable geometry label- * means. Asked wherever a shape is offered something different from a marker — it has no pin to put- * somewhere else, for one (see the detail pane and the context menu).+ * Whether the note is drawn on the map as a shape, which is what a readable geometry label means.+ * Asked wherever a shape is offered something different from a marker, such as having no pin to+ * move (see DetailPane and ContextMenus).*/export function isShapeNote(note: { getLabelValue(name: string): string | null }): boolean {return !!parseGeoShape(note.getLabelValue(GEO_SHAPE_ATTRIBUTE) ?? "");@@ -122,8 +122,8 @@ function parseCircle(rest: string): GeoShapeCircle | null {}/**- * A polygon from the ring a drawing tool hands over, which spells the closing point out — GeoJSON- * rings end where they began, and the label does not (see the module note).+ * A polygon from the ring a drawing tool produces, which spells the closing point out: GeoJSON+ * rings end where they began and the label does not (see the module note).*/export function polygonFromRing(ring: [number, number][]): GeoShapePolygon {const [ firstLng, firstLat ] = ring[0] ?? [];@@ -132,20 +132,20 @@ export function polygonFromRing(ring: [number, number][]): GeoShapePolygon {return { type: "polygon", coordinates: closed ? ring.slice(0, -1) : ring };}-/** The ring as GeoJSON wants it back: ended where it began. */+/** The ring as GeoJSON expects it: ended where it began. */export function closeRing(coordinates: [number, number][]): [number, number][] {return [ ...coordinates, coordinates[0] ];}-/** The mean of the earth's radii, as MapLibre also takes it. */+/** The mean of the earth's radii, the value MapLibre uses as well. */const EARTH_RADIUS_METERS = 6371008.8;-/** How many corners a circle's ring is drawn with — enough that nobody sees them. */+/** How many corners a circle's ring is drawn with, enough that none of them show. */const CIRCLE_SEGMENTS = 64;/**- * A circle's reach walked out as a ring, one point per bearing, without the closing repeat — the- * ring a circle label is drawn from (see {@link serializeGeoShape} for why it is not stored).+ * A circle's radius walked out as a ring, one point per bearing, without the closing repeat. This+ * is the ring a circle label is drawn from, and is not stored (see {@link serializeGeoShape}).* Great-circle rather than flat arithmetic, so a wide circle far from the equator keeps its shape.*/export function circleRing(center: [number, number], radiusMeters: number, segments = CIRCLE_SEGMENTS): [number, number][] {@@ -172,9 +172,8 @@ export function circleRing(center: [number, number], radiusMeters: number, segme}/**- * Where a ring stands: the mean of its points. Exact for the regular ring a circle tool hands- * over, which is all it is asked about — this is how the centre a circle label stores is read- * back off the ring Terra Draw drew (see `shapeFromFeature`).+ * The mean of a ring's points. Exact for the regular ring a circle tool produces, which is the only+ * one it is asked about: this is how `shapeFromFeature` recovers the center a circle label stores.*/export function ringCenter(ring: [number, number][]): [number, number] | null {if (ring.length === 0) return null;@@ -189,9 +188,9 @@ export function ringCenter(ring: [number, number][]): [number, number] | null {}/**- * The corners of a shape, which `DetailPane` frames the shape it opens on by. A circle is measured- * across {@link circleRing} rather than at its centre, so the box covers the whole radius; the seam- * at ±180° is {@link boundsOf}'s to deal with, as it is for a track.+ * The bounding box `DetailPane` frames a shape by. A circle is measured across {@link circleRing}+ * rather than at its center, so the box covers the whole radius. The seam at ±180° is+ * {@link boundsOf}'s to deal with, as it is for a track.*/export function geoShapeBounds(shape: GeoShape): Bounds | null {return boundsOf(shape.type === "circle"diff --git a/apps/client/src/widgets/react/OverlayControlGroup.css b/apps/client/src/widgets/react/OverlayControlGroup.cssindex 92d7c1cfcd..4883376906 100644--- a/apps/client/src/widgets/react/OverlayControlGroup.css+++ b/apps/client/src/widgets/react/OverlayControlGroup.css@@ -111,8 +111,8 @@.tn-overlay-control-group[data-orientation="vertical"] {flex-direction: column;- /* The ends of the run are the top and the bottom now, so the rounding moves with them. The- group's own attribute is named as well as the child, to out-specify the row form above. */+ /* The ends of the run are the top and the bottom, so the rounding follows them. The group's+ attribute is named alongside the child, to outweigh the row form above. */:where(button):first-child,:where(button):last-child {border-radius: var(--_start-border-radius, 0) var(--_start-border-radius, 0) var(--_end-border-radius, 0) var(--_end-border-radius, 0);@@ -148,8 +148,8 @@width: fit-content;}-/* The middle of a side edge, reckoned the way `-center` reckons the middle of a top or bottom one:- stretched from one inset to the other, with the margins sharing what the group does not take. */+/* The middle of a side edge, measured as `-center` measures the middle of a top or bottom one:+ stretched between the two insets, with the margins sharing what the group does not take. */.tn-overlay-control-group[data-placement^="middle-"] {inset-block: var(--overlay-group-inset-top, var(--overlay-group-inset)) var(--overlay-group-inset-bottom, var(--overlay-group-inset));margin-block: auto;diff --git a/packages/commons/src/lib/builtin_attributes.ts b/packages/commons/src/lib/builtin_attributes.tsindex db2bbac444..b81b42c3a7 100644--- a/packages/commons/src/lib/builtin_attributes.ts+++ b/packages/commons/src/lib/builtin_attributes.ts@@ -300,8 +300,8 @@ const BUILTIN_ATTRIBUTES = [{ type: "label", name: "endTime", valueType: "time", hasUserValue: true },{ type: "label", name: "recurrence", valueType: "text", hasUserValue: true },{ type: "label", name: "geolocation", valueType: "text", hasUserValue: true },- // A shape drawn onto a geo map, held as `kind:` and then a `lat,lng` per vertex — the- // geolocation format walked along a path (see the client's geomap/shapes.ts).+ // A shape drawn onto a geo map: a kind, a colon, then a `lat,lng` per vertex (see the+ // client's geomap/shapes.ts).{ type: "label", name: "geoShape", valueType: "text", hasUserValue: true },// Which note map a note map note draws; anything but `tree` is read as `link`.{ type: "label", name: "mapType", valueType: "select", hasUserValue: true, selectOptions: [diff --git a/packages/commons/src/lib/notes.spec.ts b/packages/commons/src/lib/notes.spec.tsindex 5c2c11465a..e74b9ad734 100644--- a/packages/commons/src/lib/notes.spec.ts+++ b/packages/commons/src/lib/notes.spec.ts@@ -119,13 +119,13 @@ describe("getNoteIcon", () => {.toBe("bx bx-shape-polygon");expect(getNoteIcon(buildArgs({ getLabelValue: drawn("circle:48.85,2.29 500") }))).toBe("bx bx-shape-circle");- // Nothing is written onto a shape note either, so the map's own icon still wins — and the- // icon follows a shape redrawn as another kind rather than staying what it was created as.+ // Nothing is written onto a shape note either, so the map's own icon still wins, and the+ // icon follows a shape redrawn as another kind.expect(getNoteIcon(buildArgs({getLabelValue: drawn("circle:48.85,2.29 500"), iconClass: "bx bx-store"}))).toBe("bx bx-store");- // A label nobody can read draws no shape on the map, but the note is still one that carries- // a shape; the line's icon is the least it could be.+ // A label nobody can read draws no shape on the map, but the note still carries one, so+ // the line icon is the fallback.expect(getNoteIcon(buildArgs({ getLabelValue: drawn("nonsense") }))).toBe("bx bx-vector");expect(getNoteIcon(buildArgs({ getLabelValue: drawn("") }))).toBe("bx bx-note");});diff --git a/packages/commons/src/lib/notes.ts b/packages/commons/src/lib/notes.tsindex c9b75d13c8..0dcaf4be5b 100644--- a/packages/commons/src/lib/notes.ts+++ b/packages/commons/src/lib/notes.ts@@ -103,9 +103,8 @@ export const GEO_SHAPE_ATTRIBUTE = "geoShape";export const GEO_MARKER_ICON = "bx bx-pin";/**- * The icon a drawn shape is worn under, by the kind its `#geoShape` label names (see the client's- * geomap/shapes.ts for the format). An unreadable label falls back to the line's icon, a shape- * being a line before it is anything else.+ * The icon for a drawn shape, keyed by the kind its `#geoShape` label names (see the client's+ * geomap/shapes.ts for the format). An unreadable label falls back to the line icon.*/export const GEO_SHAPE_ICONS: Record<string, string> = {line: "bx bx-vector",@@ -118,11 +117,11 @@ export const GEO_SHAPE_ICONS: Record<string, string> = {* what the note is otherwise.** A note carrying a non-empty `#geolocation` is drawn as a pin, and one carrying a `#geoShape` as- * the shape it draws, where either has nothing more specific. So the geo map writes no `#iconClass`- * onto a marker or a shape it creates: an icon the map hands down through `#child:iconClass` or a- * template still applies, and redrawing a shape as another kind changes the icon with it rather- * than leaving the one it was created under. `iconClass` stays an argument rather than being read- * here because the share tree narrows it to the prefixes an icon pack supplies.+ * the shape it names, where neither has anything more specific. The geo map therefore writes no+ * `#iconClass` onto a marker or a shape it creates, so an icon it hands down through+ * `#child:iconClass` or a template still applies, and redrawing a shape as another kind changes the+ * icon with it. `iconClass` stays an argument rather than being read here because the share tree+ * narrows it to the prefixes an icon pack supplies.*/export function getNoteIcon({noteId, type, mime, iconClass, workspaceIconClass, isFolder, getLabelValue