@kahwee/sf-map-svg 4.3.0 → 4.3.2

package/dist/src/label-renderer.js

@@ -1,3 +1,4 @@
+import { setAttributeIfChanged } from './dom.js';
 import { layoutLabels } from './explorer-layout.js';
 /** Reuse text nodes and screen-space metrics throughout a camera animation. */
 export function createLabelRenderer(layer) {
@@ -14,7 +15,14 @@ export function createLabelRenderer(layer) {
         draw(labels, view, width, obstacles) {
             const unit = view[2] / width;
             const keys = new Set();
-            const pending = labels.map((label) => {
+            const pending = labels
+                .filter((label) => {
+                const y = (label.point[1] - view[1]) / unit;
+                // Labels are centered horizontally; an anchor outside vertically cannot fit.
+                const margin = label.fontSize * 1.25 + label.offset + 3;
+                return y >= -margin && y <= width + margin;
+            })
+                .map((label) => {
                 const key = JSON.stringify([
                     label.kind,
                     label.name,
@@ -34,11 +42,11 @@ export function createLabelRenderer(layer) {
                     entries.set(key, entry);
                 }
                 const { node } = entry;
-                node.setAttribute('font-size', String(label.fontSize * unit));
-                node.setAttribute('font-weight', String(label.fontWeight));
-                node.setAttribute('fill', label.fill);
-                node.setAttribute('stroke', label.halo);
-                node.setAttribute('stroke-width', String(3 * unit));
+                setAttributeIfChanged(node, 'font-size', label.fontSize * unit);
+                setAttributeIfChanged(node, 'font-weight', label.fontWeight);
+                setAttributeIfChanged(node, 'fill', label.fill);
+                setAttributeIfChanged(node, 'stroke', label.halo);
+                setAttributeIfChanged(node, 'stroke-width', 3 * unit);
                 // Batch writes before measuring new labels. Hidden candidates stay detached.
                 if (entry.width === undefined && !node.parentNode)
                     layer.append(node);
@@ -68,8 +76,8 @@ export function createLabelRenderer(layer) {
                     node.remove();
             let previous = null;
             for (const item of placed) {
-                item.node.setAttribute('x', String(view[0] + item.left * unit));
-                item.node.setAttribute('y', String(view[1] + (item.top + item.fontSize) * unit));
+                setAttributeIfChanged(item.node, 'x', view[0] + item.left * unit);
+                setAttributeIfChanged(item.node, 'y', view[1] + (item.top + item.fontSize) * unit);
                 const next = previous ? previous.nextSibling : layer.firstChild;
                 if (next !== item.node)
                     layer.insertBefore(item.node, next);

package/dist/src/map-core.js

@@ -105,7 +105,8 @@ const transitColors = {
     selected: '#0073ae',
 };
 export function resolveMapColors(theme, colors = {}) {
-    return { ...defaults, ...(theme === 'transit' ? transitColors : {}), ...colors };
+    const supplied = Object.fromEntries(Object.entries(colors).filter(([, value]) => value !== undefined));
+    return { ...defaults, ...(theme === 'transit' ? transitColors : {}), ...supplied };
 }
 let sequence = 0;
 /** Make an offline SVG and the matching longitude/latitude projection. */
@@ -143,8 +144,29 @@ export function createSFMapWithData(options, data) {
             };
         })
         : [];
+    const neighborhoodDescription = options.source === 'realtor'
+        ? 'SFAR realtor neighborhood areas, defined in August 2010'
+        : options.source === 'sf-find'
+            ? 'SF Find neighborhood areas'
+            : options.source === 'analysis'
+                ? 'DataSF analysis neighborhood areas'
+                : 'the supplied neighborhood areas';
+    const description = [
+        districts.length && (districtFills || districtLines || (labels && districtLabels))
+            ? `San Francisco district boundaries (${year}).`
+            : 'San Francisco map.',
+        neighborhoodLines && data.neighborhoods?.length
+            ? `Dashed lines show ${neighborhoodDescription}.`
+            : '',
+        landmarks && landmarkData.length ? `Park and landmark features: ${landmarkData.length}.` : '',
+        keyRoads && roadData.length ? 'Selected road corridors.' : '',
+        bartStations && stationData.length ? `BART stations: ${stationData.length}.` : '',
+        'See SOURCES.md for geographic sources.',
+    ]
+        .filter(Boolean)
+        .join(' ');
     const parts = [
-        `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ${width} ${height}" width="${width}" height="${height}" role="img" aria-labelledby="${idPrefix}-title" data-sf-map="" data-year="${year}"${animated ? ` data-sf-animate="${idPrefix}"` : ''} style="max-width:100%;height:auto"><title id="${idPrefix}-title">${escapeXml(title)}</title><desc>San Francisco supervisorial district boundaries (${year}).${neighborhoodLines ? ' Dashed lines show SFAR realtor neighborhood areas, defined in August 2010.' : ''}${landmarks ? ' Highlighted areas show six parks and landmarks.' : ''}${keyRoads ? ' Thin gray lines show selected road corridors.' : ''}${bartStations ? ' Rings mark the eight San Francisco BART stations.' : ''} Geometry from DataSF${bartStations ? ' and BART' : ''}. See package SOURCES.md.</desc>${animation ? staticAnimationStyle(idPrefix, animation) : ''}<defs><clipPath id="${idPrefix}-coast"><path d="${coastPath}" fill-rule="evenodd" clip-rule="evenodd"/></clipPath></defs><rect width="${width}" height="${height}" fill="${escapeXml(colors.water)}"/><g data-layer="geography"><path data-layer="coast" d="${coastPath}" fill="${escapeXml(colors.land)}" fill-rule="evenodd"/>`,
+        `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ${width} ${height}" width="${width}" height="${height}" role="img" aria-labelledby="${idPrefix}-title" data-sf-map="" data-year="${year}"${animated ? ` data-sf-animate="${idPrefix}"` : ''} style="max-width:100%;height:auto"><title id="${idPrefix}-title">${escapeXml(title)}</title><desc>${escapeXml(description)}</desc>${animation ? staticAnimationStyle(idPrefix, animation) : ''}<defs><clipPath id="${idPrefix}-coast"><path d="${coastPath}" fill-rule="evenodd" clip-rule="evenodd"/></clipPath></defs><rect width="${width}" height="${height}" fill="${escapeXml(colors.water)}"/><g data-layer="geography"><path data-layer="coast" d="${coastPath}" fill="${escapeXml(colors.land)}" fill-rule="evenodd"/>`,
     ];
     // Explicit drawing order keeps optional overlays and user markers predictable.
     if (districtFills)

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

@@ -0,0 +1,11 @@
+import type { createMarkerLayer, MarkerItem } from './marker-layer.js';
+import type { MapMarker } from './types.js';
+/** Own ordered records and picker reconciliation; prepare before committing DOM changes. */
+export declare function createMarkerCatalog(renderer: ReturnType<typeof createMarkerLayer>, picker: HTMLSelectElement, project: (point: [number, number]) => [number, number]): {
+    readonly items: MarkerItem[];
+    prepare(markers: readonly MapMarker[], selected: string | null): {
+        selection: string | null;
+        focused: string | undefined;
+        commit(): void;
+    } | undefined;
+};

package/dist/src/marker-catalog.js

@@ -0,0 +1,67 @@
+import { element } from './dom.js';
+import { validateMarkers } from './validation.js';
+/** Own ordered records and picker reconciliation; prepare before committing DOM changes. */
+export function createMarkerCatalog(renderer, picker, project) {
+    let items = [];
+    return {
+        get items() {
+            return items;
+        },
+        prepare(markers, selected) {
+            validateMarkers(markers);
+            const existing = new Map(items.map((item) => [item.marker.id, item]));
+            const ids = new Set();
+            const next = markers.map((marker) => {
+                ids.add(marker.id);
+                const previous = existing.get(marker.id);
+                const point = previous?.marker.lng === marker.lng && previous.marker.lat === marker.lat
+                    ? previous.point
+                    : project([marker.lng, marker.lat]);
+                return { marker: { ...marker }, point };
+            });
+            const selection = selected && ids.has(selected)
+                ? selected
+                : (markers.find((marker) => marker.selected)?.id ?? null);
+            const keys = ['id', 'lng', 'lat', 'label', 'selected', 'color', 'radius'];
+            if (picker.options.length > 0 &&
+                selection === selected &&
+                next.length === items.length &&
+                next.every(({ marker }, index) => keys.every((key) => marker[key] === items[index].marker[key])))
+                return undefined;
+            const focused = items.find((item) => item.visual?.node === document.activeElement)?.marker.id;
+            return {
+                selection,
+                focused,
+                commit() {
+                    const options = new Map([...picker.options].map((option) => [option.value, option]));
+                    for (const item of items) {
+                        if (!ids.has(item.marker.id)) {
+                            renderer.remove(item);
+                            options.get(item.marker.id)?.remove();
+                        }
+                    }
+                    if (!options.has('')) {
+                        const empty = element('option', 'No marker selected');
+                        empty.value = '';
+                        picker.prepend(empty);
+                    }
+                    items = next.map(({ marker, point }, index) => {
+                        const previous = existing.get(marker.id);
+                        const item = previous ?? renderer.add(marker, point, index);
+                        if (previous)
+                            renderer.update(item, marker, point, index);
+                        const option = options.get(marker.id) ?? element('option');
+                        const label = marker.label ?? marker.id;
+                        if (option.textContent !== label)
+                            option.textContent = label;
+                        if (option.value !== marker.id)
+                            option.value = marker.id;
+                        if (picker.children[index + 1] !== option)
+                            picker.insertBefore(option, picker.children[index + 1] ?? null);
+                        return item;
+                    });
+                },
+            };
+        },
+    };
+}

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

@@ -0,0 +1,6 @@
+import type { MapMarker } from './types.js';
+/** A modeless choice panel also available when compact embeds hide native pickers. */
+export declare function createMarkerChooser(canvas: HTMLElement, svg: SVGSVGElement, select: (id: string) => void): {
+    close: (restoreFocus?: boolean) => void;
+    open(markers: readonly MapMarker[], opener: SVGElement): void;
+};

package/dist/src/marker-chooser.js

@@ -0,0 +1,59 @@
+import { element } from './dom.js';
+/** A modeless choice panel also available when compact embeds hide native pickers. */
+export function createMarkerChooser(canvas, svg, select) {
+    let panel;
+    let events;
+    let origin;
+    function close(restoreFocus = true) {
+        const focused = panel?.contains(document.activeElement);
+        events?.abort();
+        panel?.remove();
+        panel = undefined;
+        if (focused && restoreFocus)
+            (origin?.isConnected && origin.getClientRects().length ? origin : svg).focus({
+                preventScroll: true,
+            });
+    }
+    return {
+        close,
+        open(markers, opener) {
+            close(false);
+            origin = opener;
+            events = new AbortController();
+            const signal = events.signal;
+            panel = element('div', '', 'sf-marker-chooser');
+            panel.setAttribute('role', 'dialog');
+            panel.setAttribute('aria-label', 'Choose a place at this location');
+            const title = element('strong', 'Choose a place');
+            const dismiss = element('button', 'Close');
+            dismiss.type = 'button';
+            dismiss.addEventListener('click', () => close(), { signal });
+            panel.append(title, dismiss);
+            for (const marker of markers) {
+                const button = element('button', marker.label ?? marker.id);
+                button.type = 'button';
+                button.dataset.markerChoice = marker.id;
+                button.addEventListener('click', () => {
+                    close(false);
+                    select(marker.id);
+                }, { signal });
+                panel.append(button);
+            }
+            panel.addEventListener('keydown', (event) => {
+                if (event.key === 'Escape') {
+                    event.preventDefault();
+                    event.stopPropagation();
+                    close();
+                }
+            }, { signal });
+            panel.addEventListener('focusout', (event) => {
+                if (event.relatedTarget instanceof Node && !panel?.contains(event.relatedTarget))
+                    close(false);
+            }, { signal });
+            canvas.append(panel);
+            panel
+                .querySelector('[data-marker-choice]')
+                ?.focus({ preventScroll: true });
+        },
+    };
+}

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

@@ -1,25 +1,30 @@
 import type { normalizeFeatures } from './features.js';
 import type { MapMarker } from './types.js';
-export interface MarkerItem {
-    marker: MapMarker;
-    point: [number, number];
+export interface MarkerVisual {
     node: SVGGElement;
     dot: SVGCircleElement;
     hit: SVGCircleElement;
     ring: SVGCircleElement;
     title: SVGTitleElement;
 }
+export interface MarkerItem {
+    marker: MapMarker;
+    point: [number, number];
+    index: number;
+    enter: boolean;
+    visual: MarkerVisual | undefined;
+}
 /** Own marker visuals and entrances; selection/events remain with the controller. */
-export declare function createMarkerLayer(layer: SVGGElement): {
+export declare function createMarkerLayer(): {
     cancelEntrances: () => void;
-    clear(): void;
     remove(item: MarkerItem): void;
     update(item: MarkerItem, marker: MapMarker, point: [number, number], index: number): void;
-    add(marker: MapMarker, point: [number, number], index: number, { features, markerColor, selectedMarkerColor, reducedMotion, enter, }: {
+    add(marker: MapMarker, point: [number, number], index: number): MarkerItem;
+    materialize(item: MarkerItem, { features, markerColor, selectedMarkerColor, reducedMotion, selected, }: {
         features: ReturnType<typeof normalizeFeatures>;
         markerColor: string;
         selectedMarkerColor: string;
         reducedMotion: boolean;
-        enter: boolean;
-    }): MarkerItem;
+        selected: boolean;
+    }): MarkerVisual;
 };

package/dist/src/marker-layer.js

@@ -1,48 +1,65 @@
 import { svgElement } from './dom.js';
 /** Own marker visuals and entrances; selection/events remain with the controller. */
-export function createMarkerLayer(layer) {
+export function createMarkerLayer() {
+    const records = new Set();
     const animations = new Map();
     function cancelEntrances() {
         for (const animation of animations.values())
             animation.cancel();
         animations.clear();
+        for (const item of records)
+            item.enter = false;
     }
     return {
         cancelEntrances,
-        clear() {
-            cancelEntrances();
-            layer.replaceChildren();
-        },
         remove(item) {
-            animations.get(item.node)?.cancel();
-            animations.delete(item.node);
-            item.node.remove();
+            const visual = item.visual;
+            if (visual) {
+                animations.get(visual.node)?.cancel();
+                animations.delete(visual.node);
+                visual.node.remove();
+            }
+            records.delete(item);
+            item.enter = false;
         },
         update(item, marker, point, index) {
-            if (item.point[0] !== point[0] || item.point[1] !== point[1])
-                item.node.setAttribute('transform', `translate(${point[0]},${point[1]})`);
-            const label = marker.label ?? marker.id;
-            if (item.title.textContent !== label) {
-                item.title.textContent = label;
-                item.node.setAttribute('aria-label', label);
+            const visual = item.visual;
+            if (visual) {
+                if (item.point[0] !== point[0] || item.point[1] !== point[1])
+                    visual.node.setAttribute('transform', `translate(${point[0]},${point[1]})`);
+                const label = marker.label ?? marker.id;
+                if (visual.title.textContent !== label) {
+                    visual.title.textContent = label;
+                    visual.node.setAttribute('aria-label', label);
+                }
+                if (item.index !== index)
+                    visual.node.style.setProperty('--sf-marker-index', String(index));
             }
-            if (item.node.style.getPropertyValue('--sf-marker-index') !== String(index))
-                item.node.style.setProperty('--sf-marker-index', String(index));
             item.marker = marker;
             item.point = point;
+            item.index = index;
+        },
+        add(marker, point, index) {
+            const item = { marker, point, index, enter: true, visual: undefined };
+            records.add(item);
+            return item;
         },
-        add(marker, point, index, { features, markerColor, selectedMarkerColor, reducedMotion, enter, }) {
+        materialize(item, { features, markerColor, selectedMarkerColor, reducedMotion, selected, }) {
+            if (item.visual)
+                return item.visual;
+            const { marker, point, index, enter } = item;
+            item.enter = false;
             const node = svgElement('g', {
                 transform: `translate(${point[0]},${point[1]})`,
                 'data-marker-id': marker.id,
                 role: 'button',
-                tabindex: 0,
+                tabindex: -1,
                 'aria-label': marker.label ?? marker.id,
-                'aria-pressed': 'false',
+                'aria-pressed': String(selected),
             });
             const hit = svgElement('circle', { fill: 'transparent', 'pointer-events': 'all' });
             const dot = svgElement('circle', {
-                fill: marker.color ?? markerColor,
+                fill: selected ? selectedMarkerColor : (marker.color ?? markerColor),
                 stroke: '#fff9e9',
                 'stroke-width': 2,
                 'vector-effect': 'non-scaling-stroke',
@@ -58,7 +75,7 @@ export function createMarkerLayer(layer) {
                 'stroke-width': features.selectedMarkerRing ? features.selectedMarkerRing.width : 2,
                 'vector-effect': 'non-scaling-stroke',
                 'pointer-events': 'none',
-                display: 'none',
+                display: selected && features.selectedMarkerRing ? 'inline' : 'none',
             });
             node.style.setProperty('--sf-marker-index', String(index));
             node.append(title, hit, ring, dot);
@@ -79,8 +96,9 @@ export function createMarkerLayer(layer) {
                 };
                 animation.finished.then(release, release);
             }
-            layer.append(node);
-            return { marker, point, node, dot, hit, ring, title };
+            const visual = { node, dot, hit, ring, title };
+            item.visual = visual;
+            return visual;
         },
     };
 }

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

@@ -0,0 +1,5 @@
+/** One tab stop for visible pins and clusters; bracket keys preserve arrow-key panning. */
+export declare function createMarkerNavigation(svg: SVGSVGElement, signal: AbortSignal): {
+    sync: (next?: SVGElement[]) => void;
+    recover(): boolean;
+};

package/dist/src/marker-navigation.js

@@ -0,0 +1,52 @@
+/** One tab stop for visible pins and clusters; bracket keys preserve arrow-key panning. */
+export function createMarkerNavigation(svg, signal) {
+    let nodes = [];
+    let activeKey = '';
+    let activeIndex = 0;
+    const key = (node) => node.dataset.markerId === undefined
+        ? `cluster:${node.dataset.clusterIds}`
+        : `marker:${node.dataset.markerId}`;
+    function sync(next = nodes) {
+        nodes = next.filter((node) => node.isConnected && node.style.display !== 'none');
+        const focusedNode = document.activeElement;
+        const focused = nodes.find((node) => node === focusedNode);
+        const active = focused ??
+            nodes.find((node) => key(node) === activeKey) ??
+            nodes[Math.min(activeIndex, nodes.length - 1)];
+        if (active) {
+            activeKey = key(active);
+            activeIndex = nodes.indexOf(active);
+        }
+        for (const node of next) {
+            const tabindex = node === active ? '0' : '-1';
+            if (node.getAttribute('tabindex') !== tabindex)
+                node.setAttribute('tabindex', tabindex);
+        }
+    }
+    svg.addEventListener('focusin', (event) => {
+        if (nodes.includes(event.target))
+            sync();
+    }, { signal });
+    svg.addEventListener('keydown', (event) => {
+        if (event.altKey ||
+            event.ctrlKey ||
+            event.metaKey ||
+            !nodes.includes(event.target))
+            return;
+        if (event.key !== '[' && event.key !== ']')
+            return;
+        event.preventDefault();
+        const index = nodes.indexOf(event.target);
+        nodes[(index + (event.key === ']' ? 1 : nodes.length - 1)) % nodes.length]?.focus({
+            preventScroll: true,
+        });
+    }, { signal });
+    return {
+        sync,
+        recover() {
+            const node = nodes.find((node) => key(node) === activeKey);
+            node?.focus({ preventScroll: true });
+            return !!node;
+        },
+    };
+}

package/dist/src/static.js

@@ -1,16 +1,18 @@
 import { prepareAppearance } from './appearance.js';
 import { validateSwitchPatch } from './features.js';
 import { createSFMapWithData, getLayerPathsWithData } from './map-core.js';
-import { assertOptions } from './validation.js';
+import { normalizeStaticAnimation } from './static-animation.js';
+import { assertOptions, validateMarkers, validateOverlays } from './validation.js';
 /** Server-safe SVG rendering with explicit data; returns SVG plus projection helpers. */
 export function renderMap(data, options = {}) {
     const prepared = expandStaticOptions(options);
-    return createSFMapWithData(prepared, staticInput(data, prepared));
+    const { map, source } = staticInput(data, prepared);
+    return createSFMapWithData({ ...prepared, source }, map);
 }
 /** Project canonical layer geometry without constructing an SVG string. */
 export function getLayerPaths(data, options = {}) {
     const prepared = expandStaticOptions(options);
-    return getLayerPathsWithData(prepared, staticInput(data, prepared));
+    return getLayerPathsWithData(prepared, staticInput(data, prepared).map);
 }
 /** Borrow immutable geometry, deriving only the renderer's lightweight neighborhood rows. */
 function staticInput(data, options) {
@@ -19,45 +21,79 @@ function staticInput(data, options) {
     if (!('map' in data)) {
         if (options.source !== undefined)
             throw new TypeError('source requires source-aware MapData; compact StaticMapData already chooses its geography.');
-        return data;
+        return { map: data, source: undefined };
     }
     const source = options.source ??
         ['realtor', 'sf-find', 'analysis'].find((candidate) => !!data.neighborhoods[candidate]);
     if (source === undefined)
-        return data.map;
+        return { map: data.map, source: undefined };
     const collection = data.neighborhoods[source];
     if (!collection)
         throw new RangeError(`No ${source} neighborhood dataset was supplied.`);
     return {
-        ...data.map,
-        neighborhoods: collection.features.map(({ geometry, properties }) => ({
-            name: properties.sourceName,
-            geometry,
-        })),
+        source,
+        map: {
+            ...data.map,
+            neighborhoods: collection.features.map(({ geometry, properties }) => ({
+                name: properties.sourceName,
+                geometry,
+            })),
+        },
     };
 }
+const staticLayerKeys = [
+    'districtFills',
+    'districtLines',
+    'districtLabels',
+    'neighborhoodLines',
+    'landmarks',
+    'bartStations',
+    'highways',
+    'keyRoads',
+    'roadLabels',
+];
 /** Grouped keys override flat compatibility keys; omitted keys preserve renderer defaults. */
 function expandStaticOptions(options) {
-    assertOptions(options, 'static map');
+    assertOptions(options, 'static map', [
+        ...staticLayerKeys,
+        'layers',
+        'appearance',
+        'theme',
+        'colors',
+        'districtStyle',
+        'width',
+        'height',
+        'padding',
+        'year',
+        'source',
+        'labels',
+        'markers',
+        'overlays',
+        'title',
+        'idPrefix',
+        'animation',
+    ]);
+    for (const key of [...staticLayerKeys, 'labels'])
+        if (options[key] !== undefined && typeof options[key] !== 'boolean')
+            throw new TypeError(`${key} must be boolean.`);
+    for (const key of ['title', 'idPrefix'])
+        if (options[key] !== undefined && typeof options[key] !== 'string')
+            throw new TypeError(`${key} must be a string.`);
+    if (options.markers !== undefined)
+        validateMarkers(options.markers);
+    if (options.overlays !== undefined)
+        validateOverlays(options.overlays);
+    normalizeStaticAnimation(options.animation);
     if (options.layers !== undefined)
-        validateSwitchPatch(options.layers, [
-            'districtFills',
-            'districtLines',
-            'districtLabels',
-            'neighborhoodLines',
-            'landmarks',
-            'bartStations',
-            'highways',
-            'keyRoads',
-            'roadLabels',
-        ]);
+        validateSwitchPatch(options.layers, staticLayerKeys);
     if (options.appearance !== undefined) {
         assertOptions(options.appearance, 'static appearance', ['theme', 'colors', 'districtStyle']);
     }
-    const { layers, appearance, ...flat } = options;
+    const { layers, appearance, theme, colors, districtStyle, ...flat } = options;
     const supplied = (group = {}) => Object.fromEntries(Object.entries(group).filter(([, value]) => value !== undefined));
     return {
         ...flat,
+        ...prepareAppearance({}, { theme, colors, districtStyle }),
         ...supplied(layers),
         ...supplied(appearance === undefined ? undefined : prepareAppearance({}, appearance)),
     };

package/dist/src/types.d.ts

@@ -240,7 +240,7 @@ export interface NeighborhoodExplorerElement extends HTMLElement {
     fitGeometry(geometry: Geometry, padding?: number | MapPadding, options?: CameraOptions): void;
     /** Explicitly engage map touch gestures; false restores page gestures. */
     setTouchNavigation(enabled: boolean): void;
-    /** Reconcile stable IDs; retained markers preserve nodes, focus, and entrance animations. */
+    /** Reconcile stable IDs; preserve existing nodes and focus. Pin visuals allocate on first visibility/selection. */
     setMarkers(markers: readonly MapMarker[]): void;
     setOverlays(overlays: readonly MapOverlay[]): void;
     selectMarker(id: string | null, options?: {

package/docs/API.md

@@ -19,12 +19,14 @@ const { svg } = renderMap(staticMapData, presentation);
 const map = createMap(fullMapData, presentation);
 ```
 
-Static `layers` supports every interactive layer switch except `neighborhoodLabels`. Static `appearance` supports `theme`, `colors`, and `districtStyle`; browser typography, area interaction styles, and screen-space marker sizing remain interactive settings. Unknown grouped keys are rejected. Supplied grouped keys override flat compatibility keys; omitted or `undefined` grouped keys preserve the flat value or renderer default. The two renderers retain their existing defaults. Marker arrays accept readonly inputs.
+Static `layers` supports every interactive layer switch except `neighborhoodLabels`. Static `appearance` supports `theme`, `colors`, and `districtStyle`; browser typography, area interaction styles, and screen-space marker sizing remain interactive settings. Unknown keys and invalid values are rejected for both flat and grouped options. Supplied grouped keys override flat compatibility keys; omitted or `undefined` grouped keys preserve the flat value or renderer default. Undefined color tokens use the theme default instead of entering SVG attributes. The two renderers retain their existing defaults. Marker arrays accept readonly inputs.
 
 Flat compatibility options include `theme`, `width`, `height`, `padding`, `year` (2002, 2012, 2022), `districtLines`, `districtFills`, `districtStyle`, `districtLabels`, `neighborhoodLines`, `labels`, `highways`, `keyRoads`, `roadLabels`, `landmarks`, `bartStations`, `markers`, `overlays`, `title`, `idPrefix`, `colors`, and `animation`. Each optional layer is independent. User-supplied text and attributes are escaped in SVG output.
 
 Custom district IDs must be finite numbers. An empty `labelPoints` array uses the district's primary `label` position.
 
+The SVG description names the selected neighborhood source for source-aware data and uses a generic description for compact inputs. It describes enabled layers only when their data is supplied, using actual park and station counts.
+
 `animation: true` (or `{ duration, delay }`) makes a static map draw itself with self-contained, scoped CSS: land fades in, the coast and lines draw, districts grow, then labels and points appear. It plays when the SVG is inserted into a page or loaded as an image, needs no JavaScript, and stays still under `prefers-reduced-motion`. Re-insert the markup to replay it. Default output is unchanged.
 
 ## Interactive maps
@@ -37,7 +39,13 @@ The controller also supports marker, neighborhood, and district selection; distr
 
 If a district callback destroys the map or selects a newer district, the interrupted activation stops without moving keyboard focus or sending a stale event.
 
-`setMarkers()` reconciles by stable marker `id`: retained markers keep their DOM nodes, focus, and in-progress entrance animations; only new IDs animate in. Identical ordered marker updates are a visual no-op. Camera state and `viewportchange` events remain synchronous, while animated camera steps and their dependent label/marker layout commit in the same browser frame.
+`setMarkers()` reconciles by stable marker `id`: retained markers keep any previously created nodes, focus, and in-progress entrance animations. New pin entrances start when the pin first becomes visible; a cached pin does not animate again merely because it returns to the viewport. Disabling entrances, reduced-motion changes, and destruction cancel pending and active entrances. Identical ordered marker updates are a visual no-op. Camera state and `viewportchange` events remain synchronous, while animated camera steps and their dependent label/marker layout commit in the same browser frame.
+
+Interactive maps create individual pin nodes only on first visibility or selection, then cache them for reuse. Record and style updates before first visibility apply to the eventual node. They mount only pins and cluster symbols intersecting a padded viewport; clustered member pins detach. All records remain in the native picker and selectable through the API. Selected and keyboard-focused pins stay mounted, even outside the viewport, and retained nodes return when panning back. Cluster membership uses the complete catalog and stays stable during pan at the same zoom. Static SVG exports are unaffected.
+
+Visible markers and clusters share one tab stop. Use `[` and `]` to move focus, Enter or Space to activate, and Tab to leave the group. Arrow keys retain map panning. Marker replacement preserves the focused ID when available and moves focus to a surviving marker when it is removed.
+
+Activating coincident pins opens a place chooser, including when compact embeds hide the native marker picker. Clusters zoom when their members can separate at maximum zoom; otherwise they open the chooser. Escape or Close returns focus to the originating pin or cluster when it remains visible. Choosing a place selects its marker; replacing markers or destroying the map closes the chooser. `clusteractivate` still reports the activated cluster's markers.
 
 For a small guide, import `guideMapData` from `/guide/data` and pass it to `createMap`. The optional `/guide` entry also provides `createGuideMap`, `mountGuideMap`, and detailed-data loading for existing guide layouts. `/transit` provides the standalone schematic transit animation. See [examples](EXAMPLES.md) and [consumer integration](consumer-integration.md).
 
@@ -94,6 +102,6 @@ Neighborhood IDs are exact source-scoped feature IDs, rather than display names
 
 ## Coordinates and units
 
-GeoJSON and static projection inputs use `[longitude, latitude]` in WGS84; markers use `{ lng, lat }`. Static `project` returns SVG units. `projectToScreen(lng, lat)` returns pixels relative to the mounted canvas. Camera viewports and pan deltas use the fixed 800 × 800 projected map space, independent of canvas size. Marker radius uses screen pixels in browser maps and SVG units in static output.
+GeoJSON and static projection inputs use `[longitude, latitude]` in WGS84; markers use `{ lng, lat }`. Static `project` returns SVG units. `projectToScreen(lng, lat)` returns pixels relative to the mounted canvas. Camera viewports use the fixed 800 × 800 projected map space, independent of canvas size. Pan deltas use screen pixels, converted using the mounted canvas width. Marker radius uses screen pixels in browser maps and SVG units in static output.
 
 Explore presentation options in the [live map design playground](https://kahwee.github.io/sf-map-svg/playground.html). The page identifies its package version; released builds use compatible options for that installed version.