@kahwee/sf-map-svg 4.3.2 → 4.5.0

package/CHANGELOG.md

@@ -4,6 +4,28 @@ User-visible changes are recorded here. Unreleased entries describe changes on `
 
 ## Unreleased
 
+## 4.5.0 — 2026-10-14
+
+- Add the optional `/cards` entry with `bindMapCards()`: hover/focus previews a pin without changing selection or camera, native buttons select places, map selection reveals matching cards without stealing focus, and explicit cleanup restores owned DOM attributes.
+- Spread budgeted static labels across the map while favoring nearby-pin context and retaining a selected-place label when it fits. Keep collision avoidance, all pins, unbudgeted labels, and default output unchanged.
+
+- Add opt-in `mapPalettes.nightForest` and `mapPalettes.warmPaper` tokens for consistent static/interactive map colors, label halos, markers, and selection rings, with contrast checks.
+
+- Port YorkSF’s editorial map-preview pattern into static rendering: opt-in compact SVG label layouts, spatial label budgets, and configurable halos for dark palettes. Add a build-time field-guide example and light/dark Storybook preview without runtime dependencies or changes to default output.
+
+- Separate interactive neighborhood state, controls, sidebar downloads and overlays into lifecycle-owned modules; revoke neighborhood hover listeners when replacing sources and keep optional explorer sidebar code out of normal map bundles.
+- Build the package once during `pnpm check`, while keeping standalone test and typecheck commands self-contained.
+
+- Include compatible development-tool updates to Vite 8.3.4 and Playwright 1.64.0. Keep Storybook/addons 10.6.1 and aligned Vitest/browser/coverage 5.0.3; their newer 10.6.2 and 5.0.4 releases remain inside pnpm's release-age window. Make the consumer examples' custom touch-button accessible names include their visible text. Remove the obsolete Storybook 10.6.0 peer overrides; retain Node 24+ and zero runtime dependencies. These tooling changes were previously prepared as 4.4.1 but not published separately.
+
+## 4.4.0 — 2026-10-12
+
+- Add opt-in static `labelLayout: { width }` to `renderMap`, `createGuideSVG`, and `createGuideShell`. Static and interactive maps now share overview priorities, neighborhood anchors, font sizes, and collision rules; centered labels retain their anchors during enhancement.
+- Add static `neighborhoodLabels`, available flat or under `layers`, for the new layout. Guide SVGs and shells enable neighborhood names when opting in. Existing fixed-label output and interactive defaults remain unchanged; `labels: false` still hides text while preserving symbols and accessible titles.
+- Keep static layout server-safe and dependency-free. The width is a CSS canvas-width hint, not the SVG projection width; portable font estimates can produce a different visible label set from browser-measured fonts. Document matching data, markers, colors, and layers, plus responsive-width and custom-style limitations.
+- Keep server font estimation out of interactive-only imports and browser runtime code out of static imports. Refresh bundle reports and enforce bounded size budgets for the combined renderer and static-capable Pages tools.
+- Add desktop and phone enhancement stories, collision and input-validation regressions, an SVG example, and copyable integration documentation. Existing screenshot baselines remain unchanged.
+
 ## 4.3.2 — 2026-10-10
 
 - Update compatible development tooling and refresh dependency security fixes.

package/README.md

@@ -33,6 +33,23 @@ const { svg, project, viewBox } = renderMap(staticMapData, {
 
 See [map options and animations](docs/API.md#static-maps) for optional layers and static animation.
 
+## Labels before JavaScript loads
+
+Version 4.4 adds an opt-in overview layout for server-rendered guides:
+
+```ts
+import { createGuideShell } from '@kahwee/sf-map-svg/guide/static';
+
+const guideMarkup = createGuideShell({
+  title: 'Explore San Francisco',
+  labelLayout: { width: 390 },
+});
+```
+
+`width` is the expected canvas width in CSS pixels. The SVG keeps its 800 × 800 projection while labels share the interactive map's priorities, anchors, sizes and collision rules. Guide shells include neighborhood names in this layout; calls without `labelLayout` keep their previous output.
+
+Enhance the shell with `mountGuideController()` using the same data, colors, markers and layers. Static font widths are estimated, so browser fonts and resize can change which labels fit. See the [complete integration recipe and width guidance](docs/consumer-integration.md#keep-overview-labels-consistent). No migration is required from 4.3.
+
 ## Interactive map
 
 ```ts
@@ -165,7 +182,7 @@ pnpm benchmark:markers --counts=2000 --browsers=chromium,firefox,webkit \
 
 ### Cached label preparation and renderer components
 
-Neighborhood priority is sorted once per source. Styled label candidates are reused until selection, catalog, source, layers, appearance, or zoom/width eligibility changes. Overlay bounds are measured before marker and cluster SVG updates; secondary-road visibility and scale furniture skip unchanged writes. Marker catalog reconciliation and cluster rendering now have separate modules, reducing the explorer controller from 2,316 to 2,151 lines. The interactive renderer is 34.6 KiB gzip, up from 34.2 KiB, within the unchanged 35 KiB limit; static rendering remains 7.9 KiB.
+Neighborhood priority is sorted once per source. Styled label candidates are reused until selection, catalog, source, layers, appearance, or zoom/width eligibility changes. Overlay bounds are measured before marker and cluster SVG updates; secondary-road visibility and scale furniture skip unchanged writes. Marker catalog reconciliation and cluster rendering now have separate modules, reducing the explorer controller from 2,316 to 2,151 lines. At the 4.3.2 marker-performance baseline, the renderer was 34.6 KiB gzip and static rendering was 7.9 KiB. See the [current bundle report](docs/guide-bundle-report.md) for measurements including the opt-in static label layout.
 
 A fresh Chromium comparison against `e774fbd` used 2,000 labeled markers, 20 operation samples, both widths, and all six frame workloads in basemap and neighborhood modes. Neighborhood-mode frame interval p95 values (milliseconds):
 

package/dist/src/cards.d.ts

@@ -0,0 +1,15 @@
+import type { MapController } from './controller-types.js';
+import type { MapMarker } from './types.js';
+export interface MapCardsOptions {
+    markers: readonly MapMarker[];
+    highlightColor?: string;
+    /** Reveal selected cards with native scrolling, without moving keyboard focus. Default true. */
+    scrollOnSelect?: boolean;
+}
+/** Connect consumer-owned [data-map-marker] cards and [data-map-select] buttons to a map. */
+export declare function bindMapCards(map: MapController, root: HTMLElement, options: MapCardsOptions): {
+    /** Call after map.setMarkers() when your place catalog changes. */
+    setMarkers(next: readonly MapMarker[]): void;
+    /** Remove owned listeners/decoration and restore card attributes. Call before map.destroy(). */
+    destroy(): void;
+};

package/dist/src/cards.js

@@ -0,0 +1,138 @@
+import { validateMarkers } from './validation.js';
+/** Connect consumer-owned [data-map-marker] cards and [data-map-select] buttons to a map. */
+export function bindMapCards(map, root, options) {
+    if (map.destroyed)
+        throw new Error('Cannot bind cards to a destroyed map.');
+    validateMarkers(options.markers);
+    let markers = new Map(options.markers.map((marker) => [marker.id, { ...marker }]));
+    let disposed = false;
+    let hovered = null;
+    let focused = null;
+    let selecting = false;
+    const document = root.ownerDocument;
+    const ring = document.createElement('span');
+    ring.dataset.mapCardHighlight = '';
+    ring.setAttribute('aria-hidden', 'true');
+    ring.style.cssText =
+        'position:absolute;width:26px;height:26px;box-sizing:border-box;border:3px solid;border-radius:50%;transform:translate(-50%,-50%);pointer-events:none';
+    ring.style.borderColor = options.highlightColor ?? '#e4531b';
+    ring.hidden = true;
+    map.overlayElement.append(ring);
+    const originals = new Map();
+    function attribute(node, key, value) {
+        let saved = originals.get(node);
+        if (!saved) {
+            saved = new Map();
+            originals.set(node, saved);
+        }
+        if (!saved.has(key))
+            saved.set(key, node.getAttribute(key));
+        if (value === null)
+            node.removeAttribute(key);
+        else
+            node.setAttribute(key, value);
+    }
+    const cardAt = (target) => {
+        const card = target instanceof Element ? target.closest('[data-map-marker]') : null;
+        return card && root.contains(card) ? card : null;
+    };
+    function highlight() {
+        ring.hidden = true;
+        if (disposed || map.destroyed || !map.overlayElement.getBoundingClientRect().width)
+            return;
+        const card = focused ?? hovered;
+        const marker = card && root.contains(card) ? markers.get(card.dataset.mapMarker ?? '') : undefined;
+        if (!marker)
+            return;
+        const point = map.projectToScreen(marker.lng, marker.lat);
+        if (!point.visible)
+            return;
+        ring.style.left = `${point.x}px`;
+        ring.style.top = `${point.y}px`;
+        ring.hidden = false;
+    }
+    function selection(id, reveal) {
+        for (const card of root.querySelectorAll('[data-map-marker]')) {
+            const selected = id !== null && card.dataset.mapMarker === id;
+            attribute(card, 'data-map-selected', selected ? '' : null);
+            for (const button of card.querySelectorAll('button[data-map-select]'))
+                attribute(button, 'aria-pressed', String(selected));
+            if (selected && reveal && !selecting && options.scrollOnSelect !== false)
+                card.scrollIntoView({ block: 'nearest', inline: 'nearest', behavior: 'instant' });
+        }
+    }
+    const handlers = {
+        pointerover: (event) => {
+            if (event.pointerType !== 'touch') {
+                hovered = cardAt(event.target);
+                highlight();
+            }
+        },
+        pointerout: (event) => {
+            hovered = cardAt(event.relatedTarget);
+            highlight();
+        },
+        focusin: (event) => {
+            focused = cardAt(event.target);
+            highlight();
+        },
+        focusout: (event) => {
+            focused = cardAt(event.relatedTarget);
+            highlight();
+        },
+        click: (event) => {
+            if (disposed || map.destroyed)
+                return;
+            const target = event.target instanceof Element ? event.target.closest('button[data-map-select]') : null;
+            const card = cardAt(target);
+            const id = card?.dataset.mapMarker;
+            if (!target || !card || !id || !markers.has(id) || target.disabled)
+                return;
+            selecting = true;
+            try {
+                map.selectMarker(id, { fit: false });
+            }
+            finally {
+                selecting = false;
+            }
+        },
+    };
+    for (const [type, listener] of Object.entries(handlers))
+        root.addEventListener(type, listener);
+    const unsubscribers = [
+        map.on('markerchange', ({ id }) => selection(id, true)),
+        map.on('viewportchange', highlight),
+        map.on('mapresize', highlight),
+    ];
+    selection(map.getSelectedMarker()?.id ?? null, false);
+    return {
+        /** Call after map.setMarkers() when your place catalog changes. */
+        setMarkers(next) {
+            if (disposed)
+                return;
+            validateMarkers(next);
+            markers = new Map(next.map((marker) => [marker.id, { ...marker }]));
+            if (!map.destroyed)
+                selection(map.getSelectedMarker()?.id ?? null, false);
+            highlight();
+        },
+        /** Remove owned listeners/decoration and restore card attributes. Call before map.destroy(). */
+        destroy() {
+            if (disposed)
+                return;
+            disposed = true;
+            for (const [type, listener] of Object.entries(handlers))
+                root.removeEventListener(type, listener);
+            for (const unsubscribe of unsubscribers)
+                unsubscribe();
+            ring.remove();
+            for (const [node, saved] of originals)
+                for (const [key, value] of saved)
+                    if (value === null)
+                        node.removeAttribute(key);
+                    else
+                        node.setAttribute(key, value);
+            originals.clear();
+        },
+    };
+}

package/dist/src/cluster-layer.d.ts

@@ -0,0 +1,2 @@
+/** Lifecycle-owned cluster rendering, including lazy markers and viewport mounting. */
+export { createClusterRenderer as createClusterLayer } from './cluster-renderer.js';

package/dist/src/cluster-layer.js

@@ -0,0 +1,2 @@
+/** Lifecycle-owned cluster rendering, including lazy markers and viewport mounting. */
+export { createClusterRenderer as createClusterLayer } from './cluster-renderer.js';

package/dist/src/explorer-controls.d.ts

@@ -0,0 +1,26 @@
+import type { createExplorerShell } from './explorer-shell.js';
+import type { MapViewport, NeighborhoodExplorerElement, NeighborhoodExplorerOptions } from './types.js';
+type Controls = NonNullable<NeighborhoodExplorerOptions['controls']>;
+type Shell = Pick<ReturnType<typeof createExplorerShell>, 'root' | 'toolbar' | 'canvas' | 'hint' | 'status' | 'modeSelect' | 'sourceSelect' | 'search' | 'results' | 'neighborhoodSelect' | 'markerSelect'>;
+type Commands = Pick<NeighborhoodExplorerElement, 'getViewport' | 'zoomBy' | 'resetView' | 'setLabels' | 'stopAnimation' | 'setMode' | 'setSource' | 'selectNeighborhood' | 'selectMarker'> & {
+    svg: SVGSVGElement;
+    signal: AbortSignal;
+    strings: NonNullable<NeighborhoodExplorerOptions['strings']>;
+    isDestroyed(): boolean;
+    getLabels(): boolean;
+    moveView(view: MapViewport): void;
+    setView(view: MapViewport): void;
+    updateResults(): void;
+    search(query: string): string | undefined;
+};
+/** Own toolbar and form events, touch navigation and control visibility.
+ * Commands read current map state; all listeners share the map's disposal signal.
+ */
+export declare function createExplorerControls({ root, toolbar, canvas, hint, status, modeSelect, sourceSelect, search, results, neighborhoodSelect, markerSelect, }: Shell, { svg, signal, strings, isDestroyed, getLabels, getViewport, moveView, zoomBy, resetView, setLabels, stopAnimation, setView, setMode, setSource, selectNeighborhood, selectMarker, updateResults, search: findNeighborhood, }: Commands): {
+    setTouchNavigation: (enabled: boolean) => void;
+    cancelNavigation: () => void;
+    update(controls: Controls): void;
+    updateLabels(labels: boolean): void;
+    updateZoom(zoom: number): void;
+};
+export {};

package/dist/src/explorer-controls.js

@@ -0,0 +1,120 @@
+import { element } from './dom.js';
+import { attachNavigation } from './navigation.js';
+/** Own toolbar and form events, touch navigation and control visibility.
+ * Commands read current map state; all listeners share the map's disposal signal.
+ */
+export function createExplorerControls({ root, toolbar, canvas, hint, status, modeSelect, sourceSelect, search, results, neighborhoodSelect, markerSelect, }, { svg, signal, strings, isDestroyed, getLabels, getViewport, moveView, zoomBy, resetView, setLabels, stopAnimation, setView, setMode, setSource, selectNeighborhood, selectMarker, updateResults, search: findNeighborhood, }) {
+    function listen(node, event, handler) {
+        node.addEventListener(event, (incoming) => handler(incoming), { signal });
+    }
+    const zoomControls = element('div', '', 'sf-explorer-control-group');
+    const panControls = element('div', '', 'sf-explorer-control-group sf-explorer-pan-controls');
+    toolbar.append(zoomControls, panControls);
+    function button(text, label, action, group = zoomControls) {
+        const node = element('button', text);
+        node.type = 'button';
+        node.setAttribute('aria-label', label);
+        node.addEventListener('click', () => action(), { signal });
+        group.append(node);
+        return node;
+    }
+    const zoomOut = button('−', 'Zoom out', () => zoomBy(1 / 1.5));
+    const zoomText = element('span', '100%', 'sf-explorer-zoom');
+    zoomControls.append(zoomText);
+    const zoomIn = button('+', 'Zoom in', () => zoomBy(1.5));
+    const resetButton = button(strings.reset ?? 'Reset', strings.reset ?? 'Reset map to city view', resetView);
+    const labelsButton = button('Labels', 'Show map labels', () => setLabels(!getLabels()));
+    for (const [symbol, label, dx, dy] of [
+        ['←', 'Pan west', -1, 0],
+        ['↑', 'Pan north', 0, -1],
+        ['↓', 'Pan south', 0, 1],
+        ['→', 'Pan east', 1, 0],
+    ])
+        button(symbol, label, () => {
+            const view = getViewport();
+            moveView([view[0] + (dx * view[2]) / 4, view[1] + (dy * view[2]) / 4, view[2]]);
+        }, panControls);
+    const touchLabel = strings.touchNavigation ?? 'Touch navigation';
+    const touchButton = button(touchLabel, strings.touchNavigationLabel ?? `Enable ${touchLabel.toLowerCase()}`, () => setTouchNavigation(!touchNavigation));
+    let touchNavigation = false;
+    const navigation = attachNavigation(svg, getViewport, (next) => {
+        stopAnimation();
+        setView(next);
+    }, signal, () => setTouchNavigation(false));
+    function setTouchNavigation(enabled) {
+        if (isDestroyed())
+            return;
+        if (typeof enabled !== 'boolean')
+            throw new TypeError('Touch navigation must be a boolean.');
+        touchNavigation = enabled;
+        navigation.setTouchNavigation(enabled);
+        canvas.style.touchAction = enabled ? 'none' : 'pan-y pinch-zoom';
+        touchButton.textContent = enabled
+            ? (strings.touchNavigationDone ?? 'Done: page scrolling')
+            : touchLabel;
+        touchButton.setAttribute('aria-label', enabled
+            ? (strings.touchNavigationExitLabel ?? `Exit ${touchLabel.toLowerCase()}`)
+            : (strings.touchNavigationLabel ?? `Enable ${touchLabel.toLowerCase()}`));
+        touchButton.setAttribute('aria-pressed', String(enabled));
+        root.dataset.touchNavigation = String(enabled);
+    }
+    listen(modeSelect, 'change', () => {
+        const next = modeSelect.value;
+        if (next === 'neighborhoods' || next === 'districts' || next === 'basemap')
+            setMode(next);
+    });
+    listen(search, 'input', updateResults);
+    listen(search, 'keydown', (event) => {
+        if (event.key === 'Enter') {
+            const match = findNeighborhood(search.value);
+            if (match) {
+                event.preventDefault();
+                selectNeighborhood(match);
+            }
+        }
+    });
+    listen(sourceSelect, 'change', () => {
+        const next = sourceSelect.value;
+        if (next === 'realtor' || next === 'sf-find' || next === 'analysis')
+            setSource(next);
+    });
+    listen(results, 'click', (event) => {
+        const node = event.target instanceof Element
+            ? event.target.closest('[data-neighborhood-result]')
+            : null;
+        if (node?.dataset.neighborhoodResult)
+            selectNeighborhood(node.dataset.neighborhoodResult);
+    });
+    listen(neighborhoodSelect, 'change', () => selectNeighborhood(neighborhoodSelect.value || null));
+    listen(markerSelect, 'change', () => selectMarker(markerSelect.value || null));
+    return {
+        setTouchNavigation,
+        cancelNavigation: navigation.cancel,
+        update(controls) {
+            for (const node of [zoomIn, zoomOut, zoomText])
+                node.hidden = controls.zoom === false;
+            panControls.hidden = controls.pan === false;
+            resetButton.hidden = controls.reset === false;
+            labelsButton.hidden = controls.labels === false;
+            touchButton.hidden = controls.touch === false;
+            if (touchButton.hidden && touchNavigation)
+                setTouchNavigation(false);
+            zoomControls.hidden = [...zoomControls.children].every((node) => node.hidden);
+            toolbar.hidden = zoomControls.hidden && panControls.hidden;
+            hint.hidden = controls.help === false;
+            if (hint.hidden)
+                svg.setAttribute('aria-describedby', hint.id);
+            else
+                svg.removeAttribute('aria-describedby');
+            status.classList.toggle('sf-explorer-visually-hidden', controls.status === false);
+        },
+        updateLabels(labels) {
+            labelsButton.setAttribute('aria-pressed', String(labels));
+        },
+        updateZoom(zoom) {
+            zoomText.textContent = `${Math.round(zoom * 100)}%`;
+            zoomIn.disabled = zoom >= 12;
+            zoomOut.disabled = zoom <= 1;
+        },
+    };
+}

package/dist/src/explorer-core.d.ts

@@ -1,6 +1,8 @@
 import type { NeighborhoodSource } from '../data/types.js';
 import type { MapConfiguration } from './controller-types.js';
 import type { InteractiveSFMapData } from './explorer-data.js';
+import type { createMapShell } from './explorer-shell.js';
+import type { createExplorerSidebar } from './explorer-sidebar.js';
 import type { DistrictYear, ExplorerMode, NeighborhoodExplorerElement, NeighborhoodExplorerOptions } from './types.js';
 export type { ExplorerMode, NeighborhoodExplorerElement, NeighborhoodExplorerOptions, } from './types.js';
 /** Private bridge between the renderer and its public lifecycle controller. */
@@ -14,4 +16,7 @@ type MapEngineElement = NeighborhoodExplorerElement & {
     };
 };
 /** Create an offline, browser-only neighborhood explorer. Call destroy() before disposal. */
-export declare function createNeighborhoodExplorerCore(options: NeighborhoodExplorerOptions | undefined, data: InteractiveSFMapData): MapEngineElement;
+export declare function createNeighborhoodExplorerCore(options: NeighborhoodExplorerOptions | undefined, data: InteractiveSFMapData, ui: {
+    createShell: typeof createMapShell;
+    createSidebar?: typeof createExplorerSidebar;
+}): MapEngineElement;