@kahwee/sf-map-svg 5.1.0 → 5.1.2

package/dist/src/label-coordinator.d.ts

@@ -0,0 +1,54 @@
+import type { View } from './explorer-layout.js';
+import type { normalizeFeatures } from './features.js';
+import { type LabelItem } from './label-candidates.js';
+import type { createMarkerCatalog } from './marker-catalog.js';
+import type { createMarkerController } from './marker-controller.js';
+import type { MarkerItem, MarkerVisual } from './marker-layer.js';
+import type { createNeighborhoodLayer } from './neighborhood-layer.js';
+import type { ExplorerMode, InteractiveLayers, NeighborhoodExplorerOptions } from './types.js';
+interface LabelHost {
+    root: HTMLElement;
+    canvas: HTMLElement;
+    scale: HTMLElement;
+    overlayElement: HTMLElement;
+    secondaryRoads: NodeListOf<SVGPathElement>;
+    stationItems: (LabelItem & {
+        node: SVGCircleElement;
+    })[];
+    roadItems: LabelItem[];
+    parkItems: LabelItem[];
+    scaleUnitsPerMeter: number;
+    neighborhoods: ReturnType<typeof createNeighborhoodLayer>;
+    markerCatalog: ReturnType<typeof createMarkerCatalog>;
+    markers: ReturnType<typeof createMarkerController>;
+    labelLayer: SVGGElement;
+    invalidateFrame(): void;
+    get districtItems(): LabelItem[];
+    get layers(): InteractiveLayers;
+    get mode(): ExplorerMode;
+    get labelStyle(): NonNullable<NeighborhoodExplorerOptions['labelStyle']>;
+    get colors(): NonNullable<NeighborhoodExplorerOptions['colors']>;
+    get minLabelSize(): number;
+    get maxLabelSize(): number;
+    get markerRadius(): number;
+    get view(): View;
+    get destroyed(): boolean;
+    get labels(): boolean;
+    get features(): ReturnType<typeof normalizeFeatures>;
+    get renderedMarkers(): (MarkerItem & {
+        visual: MarkerVisual;
+    })[];
+    get renderedClusters(): {
+        point: [number, number];
+    }[];
+    enabled(layer: keyof InteractiveLayers): boolean;
+    drawClusters(unit: number): void;
+}
+/** Own candidate caching, screen-space collision layout and label metrics invalidation. */
+export declare function createLabelCoordinator(host: LabelHost): {
+    draw: () => void;
+    schedule(): void;
+    invalidateMetrics(): void;
+    clear(): void;
+};
+export {};

package/dist/src/label-coordinator.js

@@ -0,0 +1,157 @@
+import { setAttributeIfChanged } from './dom.js';
+import { labelCandidates, styleLabels, } from './label-candidates.js';
+import { createLabelRenderer } from './label-renderer.js';
+/** Own candidate caching, screen-space collision layout and label metrics invalidation. */
+export function createLabelCoordinator(host) {
+    const { root, canvas, scale, overlayElement, secondaryRoads, stationItems, roadItems, parkItems, scaleUnitsPerMeter, neighborhoods, markerCatalog, markers, enabled, drawClusters, } = host;
+    const labelRenderer = createLabelRenderer(host.labelLayer);
+    let secondaryRoadsVisible;
+    let labelInputs = [];
+    let preparedLabels = [];
+    function prepareLabels(width, zoom) {
+        // Only screen-space positioning changes during pan or within these zoom/width bands.
+        const inputs = [
+            neighborhoods.items,
+            neighborhoods.selected,
+            host.districtItems,
+            markers.revision,
+            host.layers,
+            host.mode,
+            host.labelStyle,
+            host.colors,
+            host.minLabelSize,
+            host.maxLabelSize,
+            host.markerRadius,
+            zoom >= 1.8,
+            width >= 550,
+        ];
+        if (inputs.every((value, index) => value === labelInputs[index]))
+            return preparedLabels;
+        labelInputs = inputs;
+        const selectedItem = neighborhoods.items.find((item) => item.feature === neighborhoods.selected);
+        const candidates = [];
+        const marker = markerCatalog.items.find((item) => item.marker.id === markers.selected);
+        if (marker)
+            candidates.push({
+                point: marker.point,
+                name: marker.marker.label ?? marker.marker.id,
+                kind: 'selected-marker',
+            });
+        if (selectedItem?.point && enabled('neighborhoodLabels'))
+            candidates.push({
+                point: selectedItem.point,
+                name: selectedItem.feature.properties.canonicalName,
+                kind: 'selected',
+            });
+        preparedLabels = styleLabels(labelCandidates({
+            selected: candidates,
+            districts: enabled('districtLabels') ? host.districtItems : [],
+            stations: enabled('bartStations') ? stationItems : [],
+            parks: enabled('landmarks') ? parkItems : [],
+            roads: enabled('roadLabels') ? roadItems : [],
+            neighborhoods: enabled('neighborhoodLabels')
+                ? neighborhoods.items
+                    .filter((item) => item.point !== undefined)
+                    .sort((a, b) => b.area - a.area || a.feature.id.localeCompare(b.feature.id))
+                    .flatMap((item) => item.feature !== neighborhoods.selected && item.point
+                    ? [
+                        {
+                            point: item.point,
+                            name: item.feature.properties.canonicalName,
+                            kind: 'neighborhood',
+                        },
+                    ]
+                    : [])
+                : [],
+        }, width, zoom), {
+            colors: host.colors,
+            labelStyle: host.labelStyle,
+            labelSize: { min: host.minLabelSize, max: host.maxLabelSize },
+            markerRadius: marker?.marker.radius ?? host.markerRadius,
+        });
+        return preparedLabels;
+    }
+    function drawLabels() {
+        if (host.destroyed)
+            return;
+        const canvasBox = canvas.getBoundingClientRect();
+        const width = canvasBox.width;
+        if (!width)
+            return;
+        const unit = host.view[2] / width, zoom = 800 / host.view[2];
+        if (host.features.scaleBar) {
+            const pixelsPerMeter = scaleUnitsPerMeter / unit;
+            const base = 10 ** Math.floor(Math.log10(100 / pixelsPerMeter));
+            const meters = [5, 2, 1].map((factor) => factor * base).find((value) => value * pixelsPerMeter <= 100) ??
+                base;
+            const scaleWidth = `${meters * pixelsPerMeter}px`;
+            const scaleText = meters >= 1000 ? `${meters / 1000} km` : `${meters} m`;
+            if (scale.style.width !== scaleWidth)
+                scale.style.width = scaleWidth;
+            if (scale.textContent !== scaleText)
+                scale.textContent = scaleText;
+        }
+        // Read overlay bounds before SVG writes; scale furniture above must have its current width.
+        const furnitureBounds = [...overlayElement.children]
+            .filter((node) => node.getClientRects().length > 0)
+            .map((node) => {
+            const box = node.getBoundingClientRect();
+            return [
+                box.left - canvasBox.left - 3,
+                box.top - canvasBox.top - 3,
+                box.right - canvasBox.left + 3,
+                box.bottom - canvasBox.top + 3,
+            ];
+        });
+        const showSecondaryRoads = zoom >= 1.8;
+        if (showSecondaryRoads !== secondaryRoadsVisible) {
+            for (const road of secondaryRoads)
+                road.style.display = showSecondaryRoads ? '' : 'none';
+            secondaryRoadsVisible = showSecondaryRoads;
+        }
+        for (const station of stationItems)
+            setAttributeIfChanged(station.node, 'r', 4.5 * unit);
+        drawClusters(unit);
+        if (!host.labels) {
+            labelRenderer.clear();
+            root.dataset.visibleLabels = '0';
+            return;
+        }
+        const labelCandidates = prepareLabels(width, zoom);
+        const stationBounds = (enabled('bartStations') ? stationItems : []).map(({ point }) => {
+            const x = (point[0] - host.view[0]) / unit;
+            const y = (point[1] - host.view[1]) / unit;
+            return [x - 6, y - 6, x + 6, y + 6];
+        });
+        const markerBounds = host.renderedMarkers.map(({ point, marker }) => {
+            const radius = marker.radius ?? host.markerRadius;
+            const x = (point[0] - host.view[0]) / unit, y = (point[1] - host.view[1]) / unit;
+            return [x - radius - 3, y - radius - 3, x + radius + 3, y + radius + 3];
+        });
+        root.dataset.visibleLabels = String(labelRenderer.draw(labelCandidates, host.view, width, [
+            ...stationBounds,
+            ...markerBounds,
+            ...furnitureBounds,
+            ...host.renderedClusters.map(({ point }) => {
+                const x = (point[0] - host.view[0]) / unit, y = (point[1] - host.view[1]) / unit;
+                return [x - 26, y - 26, x + 26, y + 26];
+            }),
+        ]));
+    }
+    return {
+        draw: drawLabels,
+        schedule() {
+            if (!host.destroyed)
+                host.invalidateFrame();
+        },
+        invalidateMetrics() {
+            labelRenderer.invalidateMetrics();
+            labelInputs = [];
+        },
+        clear() {
+            labelRenderer.clear();
+            labelInputs = [];
+            preparedLabels = [];
+        },
+    };
+}

package/dist/src/marker-controller.d.ts

@@ -0,0 +1,55 @@
+import type { Position } from '../data/types.js';
+import { type View } from './explorer-layout.js';
+import type { normalizeFeatures } from './features.js';
+import type { createMarkerCatalog } from './marker-catalog.js';
+import type { createMarkerChooser } from './marker-chooser.js';
+import type { MarkerItem, MarkerVisual } from './marker-layer.js';
+import type { createMarkerNavigation } from './marker-navigation.js';
+import type { CameraOptions, MapMarker, NeighborhoodExplorerOptions } from './types.js';
+interface MarkerHost {
+    root: HTMLElement;
+    canvas: HTMLElement;
+    svg: SVGSVGElement;
+    markerLayer: SVGGElement;
+    markerSelect: HTMLSelectElement;
+    markerLabel: HTMLElement;
+    markerCatalog: ReturnType<typeof createMarkerCatalog>;
+    markerNavigation: ReturnType<typeof createMarkerNavigation>;
+    get markerChooser(): ReturnType<typeof createMarkerChooser>;
+    get destroyed(): boolean;
+    get view(): View;
+    get features(): ReturnType<typeof normalizeFeatures>;
+    get markerColor(): string;
+    get selectedMarkerColor(): string;
+    get controls(): NonNullable<NeighborhoodExplorerOptions['controls']>;
+    strings: NonNullable<NeighborhoodExplorerOptions['strings']>;
+    fitPadding: NonNullable<NeighborhoodExplorerOptions['fitPadding']>;
+    onMarkerActivate: NeighborhoodExplorerOptions['onMarkerActivate'];
+    invalidateClusters(): void;
+    drawClusters(unit: number): void;
+    materializeMarker(item: MarkerItem): MarkerItem & {
+        visual: MarkerVisual;
+    };
+    scheduleLabels(): void;
+    syncFeatureControls(): void;
+    moveView(view: View, options?: CameraOptions): void;
+}
+/** Own selection revisions, activation and focus recovery independently of marker rendering. */
+export declare function createMarkerController(host: MarkerHost): {
+    getSelectedMarker: () => {
+        id: string;
+        label?: string;
+        selected?: boolean;
+        color?: string;
+        radius?: number;
+        position: Position;
+    } | null;
+    selectMarker: (id: string | null, options?: {
+        fit?: boolean;
+    } & CameraOptions) => boolean;
+    setMarkers: (markers: readonly MapMarker[]) => void;
+    activateMarker: (id: string, node: SVGElement) => void;
+    readonly selected: string | null;
+    readonly revision: number;
+};
+export {};

package/dist/src/marker-controller.js

@@ -0,0 +1,125 @@
+import { validateCameraOptions } from './camera.js';
+import { fitBounds } from './explorer-layout.js';
+import { fitViewport } from './viewport.js';
+/** Own selection revisions, activation and focus recovery independently of marker rendering. */
+export function createMarkerController(host) {
+    const { root, canvas, svg, markerLayer, markerSelect, markerLabel, markerCatalog, markerNavigation, strings, fitPadding, onMarkerActivate, invalidateClusters, drawClusters, materializeMarker, scheduleLabels, syncFeatureControls, moveView, } = host;
+    let selectedMarker = null;
+    let markerRevision = 0;
+    function getSelectedMarker() {
+        const marker = markerCatalog.items.find((item) => item.marker.id === selectedMarker)?.marker;
+        return marker ? { ...marker, position: [...marker.position] } : null;
+    }
+    function selectMarker(id, options = {}) {
+        if (host.destroyed)
+            return false;
+        const item = markerCatalog.items.find((item) => item.marker.id === id);
+        if (id !== null && !item)
+            return false;
+        validateCameraOptions(options);
+        const width = canvas.getBoundingClientRect().width;
+        const target = item && options.fit !== false
+            ? width
+                ? fitViewport([...item.point, ...item.point], width, fitPadding)
+                : fitBounds([...item.point, ...item.point])
+            : null;
+        const revision = ++markerRevision;
+        const changed = selectedMarker !== id;
+        selectedMarker = id;
+        if (changed)
+            invalidateClusters();
+        markerSelect.value = id ?? '';
+        for (const entry of markerCatalog.items) {
+            const active = entry.marker.id === id;
+            const visual = active ? materializeMarker(entry).visual : entry.visual;
+            if (!visual)
+                continue;
+            const pressed = String(active);
+            const ring = active && host.features.selectedMarkerRing ? 'inline' : 'none';
+            const fill = active ? host.selectedMarkerColor : (entry.marker.color ?? host.markerColor);
+            if (visual.node.getAttribute('aria-pressed') !== pressed)
+                visual.node.setAttribute('aria-pressed', pressed);
+            if (visual.ring.getAttribute('display') !== ring)
+                visual.ring.setAttribute('display', ring);
+            if (visual.dot.getAttribute('fill') !== fill)
+                visual.dot.setAttribute('fill', fill);
+            if (active && markerLayer.lastChild !== visual.node)
+                markerLayer.append(visual.node);
+        }
+        scheduleLabels();
+        if (width || !host.features.clustering)
+            drawClusters(width ? host.view[2] / width : 1);
+        const marker = getSelectedMarker();
+        if (changed)
+            root.dispatchEvent(new CustomEvent('markerchange', { bubbles: true, detail: { id, marker } }));
+        if (!host.destroyed &&
+            changed &&
+            marker &&
+            markerRevision === revision &&
+            selectedMarker === id)
+            onMarkerActivate?.({ ...marker });
+        if (!host.destroyed && markerRevision === revision && target)
+            moveView(target, options);
+        return true;
+    }
+    function setMarkers(markers) {
+        if (host.destroyed)
+            return;
+        const prepared = markerCatalog.prepare(markers, selectedMarker);
+        if (!prepared)
+            return;
+        const { selection: nextSelection, focused: focusedMarker } = prepared;
+        invalidateClusters();
+        prepared.commit();
+        markerLabel.hidden = !markerCatalog.items.length || host.controls.markerPicker === false;
+        if (markerLabel.firstChild)
+            markerLabel.firstChild.textContent = `${strings.chooseMarker ?? 'Choose marker'} (${markerCatalog.items.length})`;
+        syncFeatureControls();
+        const revision = markerRevision + 1;
+        selectMarker(nextSelection, { fit: false });
+        if (!host.destroyed && markerRevision === revision && focusedMarker) {
+            markerNavigation.sync(markerCatalog.items.flatMap((item) => (item.visual ? [item.visual.node] : [])));
+            if (!markerNavigation.recover()) {
+                const recovery = markerCatalog.items.find((item) => item.marker.id === focusedMarker) ??
+                    markerCatalog.items[0];
+                if (recovery) {
+                    const { node } = materializeMarker(recovery).visual;
+                    markerLayer.append(node);
+                    node.focus({ preventScroll: true });
+                    const width = canvas.getBoundingClientRect().width;
+                    if (width)
+                        drawClusters(host.view[2] / width);
+                }
+                else
+                    svg.focus({ preventScroll: true });
+            }
+        }
+    }
+    function activateMarker(id, node) {
+        const item = markerCatalog.items.find((item) => item.marker.id === id);
+        if (!item)
+            return;
+        const coincident = markerCatalog.items.filter((other) => other.point[0] === item.point[0] && other.point[1] === item.point[1]);
+        if (coincident.length > 1)
+            host.markerChooser.open(coincident.map((other) => other.marker), node);
+        else {
+            selectMarker(id);
+            if (!host.destroyed && selectedMarker === id)
+                markerCatalog.items
+                    .find((other) => other.marker.id === id)
+                    ?.visual?.node.focus({ preventScroll: true });
+        }
+    }
+    return {
+        getSelectedMarker,
+        selectMarker,
+        setMarkers,
+        activateMarker,
+        get selected() {
+            return selectedMarker;
+        },
+        get revision() {
+            return markerRevision;
+        },
+    };
+}

package/llms-full.txt

@@ -2,13 +2,13 @@
 
 > Offline San Francisco SVG maps with explicit geographic imports, no runtime dependencies, static rendering, and a browser controller.
 
-@kahwee/sf-map-svg 5.1.0 · local working tree. Node >=24.0.0 for server rendering; browsers need a DOM and a JSON-capable bundler.
+@kahwee/sf-map-svg 5.1.2 · local working tree. Node >=24.0.0 for server rendering; browsers need a DOM and a JSON-capable bundler.
 
 These are working-tree docs. Unreleased changelog entries may describe APIs absent from npm; verify the installed version before copying them.
 
 Use renderMap(data, options) for SVG strings; createMap(data, options) returns a controller. Mount map.element and destroy it on unmount. Choose mode explicitly: createMap defaults to basemap. Geography is separate; staticMapData and fullMapData have different shapes.
 
-<!-- Generated from README.md; @kahwee/sf-map-svg 5.1.0 · local working tree. -->
+<!-- Generated from README.md; @kahwee/sf-map-svg 5.1.2 · local working tree. -->
 
 # SF Map SVG
 
@@ -267,7 +267,7 @@ for raw samples, output-equivalence checks, and reproducible commands.
 
 ---
 
-<!-- Generated from docs/developer-guide.md; @kahwee/sf-map-svg 5.1.0 · local working tree. -->
+<!-- Generated from docs/developer-guide.md; @kahwee/sf-map-svg 5.1.2 · local working tree. -->
 
 # Developer guide
 
@@ -433,7 +433,7 @@ See [API options](https://github.com/kahwee/sf-map-svg/blob/main/docs/API.md), [
 
 ---
 
-<!-- Generated from docs/API.md; @kahwee/sf-map-svg 5.1.0 · local working tree. -->
+<!-- Generated from docs/API.md; @kahwee/sf-map-svg 5.1.2 · local working tree. -->
 
 # Map options and lifecycle
 
@@ -619,7 +619,7 @@ Call `binding.setMarkers(next)` after `map.setMarkers(next)` when the catalog ch
 
 ---
 
-<!-- Generated from docs/EXAMPLES.md; @kahwee/sf-map-svg 5.1.0 · local working tree. -->
+<!-- Generated from docs/EXAMPLES.md; @kahwee/sf-map-svg 5.1.2 · local working tree. -->
 
 # Examples
 
@@ -760,7 +760,7 @@ See [query semantics and limitations](https://github.com/kahwee/sf-map-svg/blob/
 
 ---
 
-<!-- Generated from docs/consumer-integration.md; @kahwee/sf-map-svg 5.1.0 · local working tree. -->
+<!-- Generated from docs/consumer-integration.md; @kahwee/sf-map-svg 5.1.2 · local working tree. -->
 
 # Embedding and progressive enhancement
 
@@ -938,7 +938,7 @@ keyboard, focus, and dismissal behavior. See [coordinates and units](https://git
 
 ---
 
-<!-- Generated from docs/migration-v5.md; @kahwee/sf-map-svg 5.1.0 · local working tree. -->
+<!-- Generated from docs/migration-v5.md; @kahwee/sf-map-svg 5.1.2 · local working tree. -->
 
 # Migrating to v5
 
@@ -1043,7 +1043,7 @@ collections. Shared edges can match more than one feature. See the
 
 ---
 
-<!-- Generated from docs/migration-v3.md; @kahwee/sf-map-svg 5.1.0 · local working tree. -->
+<!-- Generated from docs/migration-v3.md; @kahwee/sf-map-svg 5.1.2 · local working tree. -->
 
 # Migrate to version 3
 
@@ -1084,7 +1084,7 @@ District styles are now prepared once per district on construction and style/yea
 
 ---
 
-<!-- Generated from SOURCES.md; @kahwee/sf-map-svg 5.1.0 · local working tree. -->
+<!-- Generated from SOURCES.md; @kahwee/sf-map-svg 5.1.2 · local working tree. -->
 
 # Geometry and provenance
 
@@ -1321,7 +1321,7 @@ Report-history points preserve only actual validated source counts and their dis
 
 ---
 
-<!-- Generated from CHANGELOG.md; @kahwee/sf-map-svg 5.1.0 · local working tree. -->
+<!-- Generated from CHANGELOG.md; @kahwee/sf-map-svg 5.1.2 · local working tree. -->
 
 # Changelog
 
@@ -1329,6 +1329,16 @@ User-visible changes are recorded here. Unreleased entries describe changes on `
 
 ## Unreleased
 
+## 5.1.2 — 2026-11-05
+
+- Separate marker selection, activation and focus recovery into an internal controller; separate label candidate caching, screen-space collision layout and metrics invalidation into a label coordinator. Preserve the public API and shared animation frame scheduling.
+
+## 5.1.1 — 2026-11-05
+
+- Reserve precinct report controls and status space during loading to prevent phone layout shifts when multiple reports are available.
+
+- Isolate district selection, style revisions and cancellable motion in an internal controller while preserving public map behavior. Document interactive state ownership and verify district lifecycle callbacks.
+
 ## 5.1.0 — 2026-11-05
 
 - Add official November 2026 precinct aggregates (`data/elections/precincts-<report time>.json` with a time-ordered `precincts-index.json`) and the 2022 precinct boundaries (`data/precincts-2022.json`), reconciled with the department's summary report. Only aggregates are committed, never the ballot-level export. Export the boundaries as `precinctMaps` from `@kahwee/sf-map-svg/data` and `@kahwee/sf-map-svg/data/precincts`; results snapshots stay Pages data.
@@ -1711,7 +1721,7 @@ consistent home, and makes animation and subscription ownership predictable.
 
 # Published type contracts
 
-@kahwee/sf-map-svg 5.1.0 · local working tree. These declarations are generated by TypeScript. Use package export paths, not the internal filenames below. Imported relative contracts are included for context, not as additional public entry points.
+@kahwee/sf-map-svg 5.1.2 · local working tree. These declarations are generated by TypeScript. Use package export paths, not the internal filenames below. Imported relative contracts are included for context, not as additional public entry points.
 
 | Public import | Declaration |
 | --- | --- |

package/llms.txt

@@ -2,7 +2,7 @@
 
 > Offline San Francisco SVG maps with explicit geographic imports, no runtime dependencies, static rendering, and a browser controller.
 
-@kahwee/sf-map-svg 5.1.0 · local working tree. Node >=24.0.0 for server rendering; browsers need a DOM and a JSON-capable bundler.
+@kahwee/sf-map-svg 5.1.2 · local working tree. Node >=24.0.0 for server rendering; browsers need a DOM and a JSON-capable bundler.
 
 These are working-tree docs. Unreleased changelog entries may describe APIs absent from npm; verify the installed version before copying them.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kahwee/sf-map-svg",
-  "version": "5.1.0",
+  "version": "5.1.2",
   "description": "Offline SVG maps of San Francisco with district boundaries, parks, landmarks, and BART stations.",
   "type": "module",
   "main": "./dist/src/api.js",