@kahwee/sf-map-svg 4.4.0 → 4.5.0

package/CHANGELOG.md

@@ -4,6 +4,20 @@ 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.

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;