Skip to content

Build your personal knowledge base with Trilium Notes

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.tsx
index 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, shapeUnd
on(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.ts
index 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, onCre
const 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.tsx
index 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.tsx
index 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 && <ActionButton
className="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.tsx
index 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.tsx
index 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.tsx
index 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.tsx
index 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.tsx
index 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.tsx
index 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 of
diff --git a/apps/client/src/widgets/collections/geomap/GpxTrack.spec.tsx b/apps/client/src/widgets/collections/geomap/GpxTrack.spec.tsx
index 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.tsx
index 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.tsx
index 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.tsx
index 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.tsx
index 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.tsx
index 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.ts
index 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.ts
index 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.css
index 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.ts
index 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.tsx
index 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 note
being 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" && <GhostPin
parentNote={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.ts
index 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.ts
index 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.css
index 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.ts
index 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.ts
index 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.ts
index 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