@kahwee/sf-map-svg 4.4.0 → 4.5.0

package/dist/src/neighborhood-layer.js

@@ -0,0 +1,256 @@
+import { validateCameraOptions } from './camera.js';
+import { element, svgElement } from './dom.js';
+import { fitBounds, interiorAnchor, projectedBounds } from './explorer-layout.js';
+import { geometryPath } from './geometry.js';
+import { fitViewport } from './viewport.js';
+export const sourceNames = {
+    realtor: 'SFAR realtor · 92 areas',
+    'sf-find': 'SF Find · 117 areas',
+    analysis: 'City analysis · 41 areas',
+};
+const normalizeName = (value) => value
+    .normalize('NFKD')
+    .toLowerCase()
+    .replace(/[\u0300-\u036f'’]/g, '')
+    .replace(/[^a-z0-9]+/g, ' ')
+    .trim();
+export const formatSourceLabel = (source) => sourceNames[source] ?? `${source} neighborhoods`;
+/** Source-scoped names and aliases; same-name polygons never cross source boundaries. */
+export function createNeighborhoodLookup(collections) {
+    const getNeighborhood = (name, selectedSource) => {
+        const term = normalizeName(name);
+        if (!term)
+            return undefined;
+        return collections[selectedSource]?.features.find((feature) => [
+            feature.id,
+            feature.properties.canonicalName,
+            feature.properties.sourceName,
+            ...feature.properties.aliases,
+        ].some((value) => normalizeName(value) === term));
+    };
+    const searchNeighborhoods = (query, selectedSource) => {
+        const term = normalizeName(query);
+        return (collections[selectedSource]?.features ?? [])
+            .filter((feature) => [
+            feature.id,
+            feature.properties.canonicalName,
+            feature.properties.sourceName,
+            ...feature.properties.aliases,
+        ].some((value) => normalizeName(value).includes(term)))
+            .map((feature) => ({ id: feature.id, canonicalName: feature.properties.canonicalName }));
+    };
+    return { getNeighborhood, searchNeighborhoods };
+}
+/** Own neighborhood identity, prepared geometry, selection revisions and hover listeners.
+ * Preparation is detached: only the returned commit can replace the active source.
+ */
+export function createNeighborhoodLayer({ collections, initialSource, project, root, areas, canvas, sourceSelect, neighborhoodSelect, status, readPresentation, isDestroyed, ensureVisible, refresh, moveView, resetView, crossfade, }) {
+    let source = initialSource;
+    let selected;
+    let items = [];
+    let neighborhoodRevision = 0;
+    let sourceEvents = new AbortController();
+    const { getNeighborhood } = createNeighborhoodLookup(collections);
+    function getSelection() {
+        return selected
+            ? {
+                id: selected.id,
+                name: selected.properties.canonicalName,
+                source,
+                feature: structuredClone(selected),
+            }
+            : null;
+    }
+    function selectNeighborhood(name, options = {}) {
+        if (isDestroyed())
+            return false;
+        const feature = name === null
+            ? undefined
+            : (collections[source]?.features.find((entry) => entry.id === name) ??
+                getNeighborhood(name, source));
+        if (name !== null && !feature)
+            return false;
+        validateCameraOptions(options);
+        const { fitPadding } = readPresentation();
+        const selectedItem = items.find((item) => item.feature === feature);
+        const width = canvas.getBoundingClientRect().width;
+        const target = selectedItem && options.fit !== false
+            ? width
+                ? fitViewport(selectedItem.bounds, width, fitPadding)
+                : fitBounds(selectedItem.bounds)
+            : null;
+        if (feature)
+            ensureVisible();
+        const { areaStyle, colors, selectableNeighborhoods, lines } = readPresentation();
+        const revision = ++neighborhoodRevision;
+        const changed = selected !== feature;
+        selected = feature;
+        for (const item of items) {
+            const active = item.feature === selected;
+            item.node.setAttribute('fill', active ? (areaStyle.selectedFill ?? '#408dbe') : 'transparent');
+            item.node.setAttribute('fill-opacity', active ? '.16' : '1');
+            item.node.setAttribute('stroke', active ? (areaStyle.selectedStroke ?? '#176ba2') : (colors.neighborhood ?? '#9caebc'));
+            item.node.setAttribute('stroke-width', active ? '2.2' : lines ? '.55' : '0');
+            if (selectableNeighborhoods)
+                item.node.setAttribute('aria-pressed', String(active));
+            if (active)
+                areas.append(item.node);
+        }
+        if (feature)
+            root.dataset.selectedNeighborhood = feature.id;
+        else
+            delete root.dataset.selectedNeighborhood;
+        neighborhoodSelect.value = feature?.id ?? '';
+        refresh.selection();
+        status.textContent = feature
+            ? `${feature.properties.canonicalName} selected. ${formatSourceLabel(source)}.`
+            : 'Neighborhood selection cleared.';
+        if (changed)
+            root.dispatchEvent(new CustomEvent('neighborhoodchange', {
+                bubbles: true,
+                detail: {
+                    feature: feature ? structuredClone(feature) : null,
+                    source,
+                    id: feature?.id ?? null,
+                    name: feature?.properties.canonicalName ?? null,
+                },
+            }));
+        if (!isDestroyed() && neighborhoodRevision === revision && target)
+            moveView(target, options);
+        return true;
+    }
+    function prepareSource(next, reset = true) {
+        const { colors } = readPresentation();
+        const events = new AbortController();
+        if (!Object.hasOwn(collections, next))
+            throw new RangeError(`Unknown neighborhood source: ${next}`);
+        const collection = collections[next];
+        if (!collection ||
+            !Array.isArray(collection.features) ||
+            typeof collection.title !== 'string' ||
+            typeof collection.definition?.description !== 'string')
+            throw new TypeError('Neighborhood collections require features, title and definition description.');
+        const ids = new Set();
+        const nextOptions = [];
+        const nextItems = collection.features.map((feature) => {
+            if (!feature ||
+                typeof feature.id !== 'string' ||
+                !feature.id ||
+                ids.has(feature.id) ||
+                !feature.properties ||
+                typeof feature.properties.canonicalName !== 'string' ||
+                typeof feature.properties.sourceName !== 'string' ||
+                !Array.isArray(feature.properties.aliases) ||
+                Array.from(feature.properties.aliases).some((alias) => typeof alias !== 'string') ||
+                !['Polygon', 'MultiPolygon'].includes(feature.geometry?.type))
+                throw new TypeError('Neighborhood features require unique IDs, names, aliases and polygon geometry.');
+            ids.add(feature.id);
+            const bounds = projectedBounds(feature.geometry, project);
+            if (!bounds.every(Number.isFinite))
+                throw new RangeError('Neighborhood geometry must be nonempty and finite.');
+            const node = svgElement('path', {
+                d: geometryPath(feature.geometry, project),
+                'data-neighborhood-id': feature.id,
+                fill: 'transparent',
+                'fill-rule': 'evenodd',
+                stroke: colors.neighborhood ?? '#9caebc',
+                'stroke-width': '.55',
+                'vector-effect': 'non-scaling-stroke',
+                role: 'button',
+                tabindex: -1,
+                'aria-label': feature.properties.canonicalName,
+                'aria-pressed': 'false',
+            });
+            const option = element('option', feature.properties.canonicalName);
+            option.value = feature.id;
+            nextOptions.push(option);
+            const title = svgElement('title');
+            title.textContent = feature.properties.canonicalName;
+            node.append(title);
+            node.addEventListener('pointerenter', () => {
+                const { selectableNeighborhoods, areaStyle, colors } = readPresentation();
+                if (isDestroyed() ||
+                    !selectableNeighborhoods ||
+                    selected?.id === feature.id ||
+                    (!areaStyle.hoverFill && !areaStyle.hoverStroke))
+                    return;
+                node.setAttribute('fill', areaStyle.hoverFill ?? '#408dbe');
+                node.setAttribute('fill-opacity', '.12');
+                node.setAttribute('stroke', areaStyle.hoverStroke ?? colors.neighborhood ?? '#176ba2');
+            }, { signal: events.signal });
+            node.addEventListener('pointerleave', () => {
+                if (isDestroyed() || selected?.id === feature.id)
+                    return;
+                node.setAttribute('fill', 'transparent');
+                node.setAttribute('fill-opacity', '1');
+                node.setAttribute('stroke', readPresentation().colors.neighborhood ?? '#9caebc');
+            }, { signal: events.signal });
+            return {
+                feature,
+                node,
+                bounds,
+                point: interiorAnchor(feature.geometry, project),
+                area: (bounds[2] - bounds[0]) * (bounds[3] - bounds[1]),
+            };
+        });
+        return () => {
+            if (isDestroyed()) {
+                events.abort();
+                return;
+            }
+            sourceEvents.abort();
+            sourceEvents = events;
+            const { mode, year } = readPresentation();
+            const hadSelection = !!selected;
+            source = next;
+            sourceSelect.value = source;
+            selected = undefined;
+            const revision = ++neighborhoodRevision;
+            delete root.dataset.selectedNeighborhood;
+            root.dataset.source = source;
+            crossfade(areas, () => areas.replaceChildren(...nextItems.map((item) => item.node)));
+            neighborhoodSelect.replaceChildren(element('option', 'No neighborhood selected'));
+            neighborhoodSelect.options[0].value = '';
+            neighborhoodSelect.append(...nextOptions);
+            items = nextItems;
+            if (items[0])
+                items[0].node.setAttribute('tabindex', '0');
+            refresh.source();
+            status.textContent =
+                mode === 'basemap'
+                    ? 'San Francisco basemap.'
+                    : mode === 'districts'
+                        ? `${year} supervisorial districts. Numbers identify each district.`
+                        : `${formatSourceLabel(source)}. Select a neighborhood to begin.`;
+            if (hadSelection)
+                root.dispatchEvent(new CustomEvent('neighborhoodchange', {
+                    bubbles: true,
+                    detail: { feature: null, source, id: null, name: null },
+                }));
+            if (reset && !isDestroyed() && neighborhoodRevision === revision)
+                resetView();
+        };
+    }
+    function setSource(next) {
+        if (!isDestroyed())
+            prepareSource(next)();
+    }
+    return {
+        get source() {
+            return source;
+        },
+        get selected() {
+            return selected;
+        },
+        get items() {
+            return items;
+        },
+        getSelection,
+        selectNeighborhood,
+        prepareSource,
+        setSource,
+        destroy() {
+            sourceEvents.abort();
+        },
+    };
+}

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

@@ -0,0 +1,13 @@
+import { type Project } from './geometry.js';
+import type { MapOverlay } from './types.js';
+/** Prepare overlays before replacing live nodes; each replacement owns an abortable event scope. */
+export declare function createOverlayLayer({ layer: overlayLayer, root, project, onOverlayActivate, isDestroyed, }: {
+    layer: SVGGElement;
+    root: HTMLElement;
+    project: Project;
+    onOverlayActivate: ((overlay: MapOverlay) => void) | undefined;
+    isDestroyed(): boolean;
+}): {
+    set: (overlays: readonly MapOverlay[]) => void;
+    destroy(): void;
+};

package/dist/src/overlay-layer.js

@@ -0,0 +1,68 @@
+import { svgElement } from './dom.js';
+import { geometryPath } from './geometry.js';
+import { validateOverlays } from './validation.js';
+/** Prepare overlays before replacing live nodes; each replacement owns an abortable event scope. */
+export function createOverlayLayer({ layer: overlayLayer, root, project, onOverlayActivate, isDestroyed, }) {
+    let overlayEvents = new AbortController();
+    function setOverlays(overlays) {
+        if (isDestroyed())
+            return;
+        validateOverlays(overlays);
+        const events = new AbortController();
+        const next = overlays.map((input) => {
+            const overlay = structuredClone(input);
+            const node = svgElement('path', {
+                'data-overlay-id': overlay.id,
+                d: geometryPath(overlay.geometry, project),
+                fill: overlay.fill ?? 'none',
+                'fill-opacity': overlay.fillOpacity ?? 1,
+                stroke: overlay.stroke ?? '#bd8b73',
+                'stroke-width': overlay.strokeWidth ?? 2,
+                'vector-effect': 'non-scaling-stroke',
+                display: overlay.visible === false ? 'none' : 'inline',
+                'pointer-events': 'none',
+                ...(overlay.label ? { 'aria-label': overlay.label } : {}),
+            });
+            if (overlay.label) {
+                node.setAttribute('role', 'img');
+                const title = svgElement('title');
+                title.textContent = overlay.label;
+                node.append(title);
+            }
+            if (onOverlayActivate) {
+                node.setAttribute('role', 'button');
+                node.setAttribute('tabindex', overlay.visible === false ? '-1' : '0');
+                node.setAttribute('pointer-events', overlay.fill && overlay.fill !== 'none' ? 'visiblePainted' : 'stroke');
+                node.setAttribute('aria-label', overlay.label ?? overlay.id);
+                const activate = () => {
+                    if (isDestroyed() || events.signal.aborted)
+                        return;
+                    onOverlayActivate(structuredClone(overlay));
+                    if (isDestroyed() || events.signal.aborted)
+                        return;
+                    root.dispatchEvent(new CustomEvent('overlayactivate', {
+                        bubbles: true,
+                        detail: { overlay: structuredClone(overlay) },
+                    }));
+                };
+                node.addEventListener('click', activate, { signal: events.signal });
+                node.addEventListener('keydown', (event) => {
+                    if (event.key === 'Enter' || event.key === ' ') {
+                        event.preventDefault();
+                        activate();
+                    }
+                }, { signal: events.signal });
+            }
+            return node;
+        });
+        overlayEvents.abort();
+        overlayEvents = events;
+        overlayLayer.replaceChildren(...next);
+    }
+    return {
+        set: setOverlays,
+        destroy() {
+            overlayEvents.abort();
+        },
+    };
+}

package/dist/src/palettes.d.ts

@@ -0,0 +1,48 @@
+import type { SFMapOptions } from './types.js';
+/** Shared tokens for static SVGs, interactive maps, and consumer-owned place cards. */
+export interface MapPalette {
+    readonly colors: NonNullable<SFMapOptions['colors']>;
+    readonly haloColor: string;
+    readonly markerColor: string;
+    readonly selectedMarkerColor: string;
+    readonly selectedMarkerRingColor: string;
+}
+/** Opt-in editorial palettes inspired by YorkSF. Existing renderer themes stay unchanged. */
+export declare const mapPalettes: {
+    nightForest: {
+        colors: {
+            water: string;
+            land: string;
+            park: string;
+            neighborhood: string;
+            district: string;
+            road: string;
+            highway: string;
+            landmark: string;
+            bart: string;
+            label: string;
+        };
+        haloColor: string;
+        markerColor: string;
+        selectedMarkerColor: string;
+        selectedMarkerRingColor: string;
+    };
+    warmPaper: {
+        colors: {
+            water: string;
+            land: string;
+            park: string;
+            neighborhood: string;
+            district: string;
+            road: string;
+            highway: string;
+            landmark: string;
+            bart: string;
+            label: string;
+        };
+        haloColor: string;
+        markerColor: string;
+        selectedMarkerColor: string;
+        selectedMarkerRingColor: string;
+    };
+};

package/dist/src/palettes.js

@@ -0,0 +1,40 @@
+import { deepFreeze } from './immutable.js';
+/** Opt-in editorial palettes inspired by YorkSF. Existing renderer themes stay unchanged. */
+export const mapPalettes = /* @__PURE__ */ deepFreeze({
+    nightForest: {
+        colors: {
+            water: '#0a1412',
+            land: '#1b2c28',
+            park: '#1f3d33',
+            neighborhood: '#3b554e',
+            district: '#3b554e',
+            road: '#2f4943',
+            highway: '#5a4d40',
+            landmark: '#8fcbb4',
+            bart: '#8ea4ae',
+            label: '#d5e3e8',
+        },
+        haloColor: '#1b2c28',
+        markerColor: '#f2845f',
+        selectedMarkerColor: '#fff9e9',
+        selectedMarkerRingColor: '#ff957d',
+    },
+    warmPaper: {
+        colors: {
+            water: '#dce8ea',
+            land: '#f4efe4',
+            park: '#dcebe2',
+            neighborhood: '#88998e',
+            district: '#566b60',
+            road: '#c6bca9',
+            highway: '#987859',
+            landmark: '#315d48',
+            bart: '#365b68',
+            label: '#243d32',
+        },
+        haloColor: '#f4efe4',
+        markerColor: '#b23b10',
+        selectedMarkerColor: '#183a2f',
+        selectedMarkerRingColor: '#b23b10',
+    },
+});

package/dist/src/presets.d.ts

@@ -1,3 +1,4 @@
 import type { MapOptions } from './controller-types.js';
 /** Configuration only: pair with guide/data or a compatible caller-supplied dataset. */
 export declare const guideOptions: Readonly<MapOptions>;
+export { type MapPalette, mapPalettes } from './palettes.js';

package/dist/src/presets.js

@@ -15,3 +15,4 @@ export const guideOptions = deepFreeze({
         roadLabels: true,
     },
 });
+export { mapPalettes } from './palettes.js';

package/dist/src/static-labels.js

@@ -1,5 +1,6 @@
 import { interiorAnchor, layoutLabels, projectedBounds } from './explorer-layout.js';
 import { labelCandidates, styleLabels } from './label-candidates.js';
+import { spreadLabels } from './label-spread.js';
 import { escapeXml, number } from './svg.js';
 /** Conservative portable metrics; the browser refines these with its actual font. */
 export function estimateLabelWidth(text, fontSize) {
@@ -19,6 +20,14 @@ export function estimateLabelWidth(text, fontSize) {
 }
 /** Interactive overview rules, expressed entirely in screen pixels before serialization. */
 export function staticLabels(data, options, project) {
+    if (options.labelLayout?.compact) {
+        const { compact, ...layout } = options.labelLayout;
+        const wide = staticLabels(data, { ...options, labelLayout: layout }, project);
+        const narrow = staticLabels(data, { ...options, labelLayout: { ...layout, ...compact } }, project);
+        // Width-specific selectors prevent different breakpoints in inline maps interfering.
+        const key = compact.width;
+        return `<style>[data-label-layout="compact-${key}"]{display:none}@media(max-width:${key}px){[data-label-layout="wide-${key}"]{display:none}[data-label-layout="compact-${key}"]{display:inline}}</style><g data-label-layout="wide-${key}">${wide}</g><g data-label-layout="compact-${key}">${narrow}</g>`;
+    }
     const width = options.labelLayout?.width ?? options.width ?? 800;
     const unit = (options.width ?? 800) / width;
     const height = (options.height ?? 800) / unit;
@@ -74,7 +83,11 @@ export function staticLabels(data, options, project) {
             }))
             : [],
         neighborhoods: neighborhoods.flatMap((item) => item.point ? [{ point: item.point, name: item.name, kind: 'neighborhood' }] : []),
-    }, width, 1), { colors: options.colors, markerRadius: marker?.radius ?? 6 });
+    }, width, 1), {
+        colors: options.colors,
+        markerRadius: marker?.radius ?? 6,
+        labelStyle: { haloColor: options.labelLayout?.haloColor },
+    });
     const obstacles = [
         ...(options.bartStations
             ? (data.bartStations ?? []).map((item) => {
@@ -96,5 +109,7 @@ export function staticLabels(data, options, project) {
         textWidth: estimateLabelWidth(item.name, item.fontSize),
         textHeight: item.fontSize * 1.25,
     })), width, height, obstacles);
-    return `<g data-layer="overview-labels" font-family="system-ui,sans-serif">${placed.map((item) => `<text data-label-kind="${escapeXml(item.kind)}" text-anchor="middle" x="${number((item.left + item.textWidth / 2) * unit)}" y="${number((item.top + item.fontSize) * unit)}" font-size="${number(item.fontSize * unit)}" font-weight="${item.fontWeight}" fill="${escapeXml(item.fill)}" stroke="${escapeXml(item.halo)}" stroke-width="${number(3 * unit)}" stroke-linejoin="round" paint-order="stroke">${escapeXml(item.name)}</text>`).join('')}</g>`;
+    return `<g data-layer="overview-labels" font-family="system-ui,sans-serif">${spreadLabels(placed, options.labelLayout?.maxLabels, markers.map((marker) => point([marker.lng, marker.lat])), width, height)
+        .map((item) => `<text data-label-kind="${escapeXml(item.kind)}" text-anchor="middle" x="${number((item.left + item.textWidth / 2) * unit)}" y="${number((item.top + item.fontSize) * unit)}" font-size="${number(item.fontSize * unit)}" font-weight="${item.fontWeight}" fill="${escapeXml(item.fill)}" stroke="${escapeXml(item.halo)}" stroke-width="${number(3 * unit)}" stroke-linejoin="round" paint-order="stroke">${escapeXml(item.name)}</text>`)
+        .join('')}</g>`;
 }

package/dist/src/static.js

@@ -84,9 +84,28 @@ function expandStaticOptions(options) {
         if (options[key] !== undefined && typeof options[key] !== 'string')
             throw new TypeError(`${key} must be a string.`);
     if (options.labelLayout !== undefined) {
-        assertOptions(options.labelLayout, 'label layout', ['width']);
+        assertOptions(options.labelLayout, 'label layout', [
+            'width',
+            'maxLabels',
+            'haloColor',
+            'compact',
+        ]);
         if (!Number.isFinite(options.labelLayout.width) || options.labelLayout.width <= 0)
-            throw new RangeError('Label layout width must be positive and finite.');
+            throw new RangeError('Invalid label layout width.');
+        const { maxLabels, haloColor, compact } = options.labelLayout;
+        if (maxLabels !== undefined && (!Number.isSafeInteger(maxLabels) || maxLabels < 0))
+            throw new RangeError('Invalid maxLabels.');
+        if (haloColor !== undefined && typeof haloColor !== 'string')
+            throw new TypeError('haloColor must be a string.');
+        if (compact !== undefined) {
+            assertOptions(compact, 'compact label layout', ['width', 'maxLabels']);
+            if (!Number.isFinite(compact.width) ||
+                compact.width <= 0 ||
+                compact.width >= options.labelLayout.width)
+                throw new RangeError('Invalid compact width.');
+            if (!Number.isSafeInteger(compact.maxLabels) || compact.maxLabels < 0)
+                throw new RangeError('Invalid maxLabels.');
+        }
     }
     if (options.markers !== undefined)
         validateMarkers(options.markers);

package/dist/src/types.d.ts

@@ -56,6 +56,15 @@ export interface SFMapOptions {
     /** Opt into interactive overview label priorities/collisions at this CSS display width. Uses estimated system-font metrics without a DOM. */
     labelLayout?: {
         width: number;
+        /** Maximum placed labels, spread across the map with nearby-pin context; zero hides text only. */
+        maxLabels?: number;
+        /** Label outline color, for example the land color on a dark map. */
+        haloColor?: string;
+        /** Alternate layout below this SVG viewport width, without browser JavaScript. */
+        compact?: {
+            width: number;
+            maxLabels: number;
+        };
     };
     highways?: boolean;
     keyRoads?: boolean;

package/docs/API.md

@@ -31,8 +31,32 @@ The SVG description names the selected neighborhood source for source-aware data
 
 Static `labelLayout: { width: 390 }` opts into shared interactive **overview** label priorities, sizes, anchors and collision rules. `width` must be a positive finite CSS canvas width; it does not alter the SVG viewBox. Set `neighborhoodLabels: true` (flat or under `layers`) to add area names in this layout. Guide SVGs and shells enable neighborhood names by default only when opting into `labelLayout`. `labels: false` remains the master switch. Default static output is unchanged.
 
+For editorial previews, `labelLayout` also accepts `maxLabels` (a nonnegative safe integer), `haloColor` (an SVG color string), and `compact: { width, maxLabels }`. The compact width must be positive, finite, and smaller than the main layout width. Each layout places labels around pins independently, then chooses up to its budget for spatial coverage and nearby-pin context (selected marker first when it fits). Without a budget the existing overview order is unchanged. Equal spatial scores retain the original priority order. A zero budget hides text, never pins. The default halo remains white; use the land color for a quieter dark map.
+
+Compact mode embeds two label groups and a media query in the same SVG. At or below the compact width it shows the compact group; above it shows the main group. In an `<img>` or standalone SVG, the breakpoint follows the SVG viewport. In inline SVG it follows the document viewport, so use `<img>` for cards whose width differs from the page. No JavaScript, duplicated geometry, external fonts, or extra image requests are needed. The compact width is also its font-layout hint; very narrow images still scale the text. The interactive renderer continues to use its live collision layout after enhancement.
+
+```js
+createGuideSVG({
+  labelLayout: {
+    width: 800,
+    haloColor: '#1b2c28',
+    compact: { width: 480, maxLabels: 4 },
+  },
+  colors: { water: '#0a1412', land: '#1b2c28', label: '#d5e3e8' },
+  markers: places,
+});
+```
+
+See the [field-guide preview recipe](consumer-integration.md#editorial-map-previews) for a complete build-time example.
+
 Static placement uses estimated system-font metrics without browser globals. Interactive placement measures actual fonts and includes live selection and HTML furniture, so exact glyph positions and the visible label set can differ. See the [integration recipe](consumer-integration.md#keep-overview-labels-consistent) for width and progressive-enhancement guidance.
 
+## Editorial palettes
+
+Import `mapPalettes` from `@kahwee/sf-map-svg/presets`. `nightForest` and `warmPaper` are deeply frozen, opt-in token sets. Each supplies `colors`, `haloColor`, `markerColor`, `selectedMarkerColor`, and `selectedMarkerRingColor`. They work with any supplied geography and do not change the existing themes. Text clears 4.5:1 and pins/rings clear 3:1 against the palette's land, park, and water surfaces; consumers must check their own overrides and surrounding UI.
+
+For static maps pass `colors: palette.colors`, `labelLayout: { width: 800, haloColor: palette.haloColor }`, and the marker color on each marker. For interactive maps pass `appearance: { colors: palette.colors, labelStyle: { haloColor: palette.haloColor }, markerColor: palette.markerColor, selectedMarkerColor: palette.selectedMarkerColor }` and `features: { selectedMarkerRing: { color: palette.selectedMarkerRingColor } }`. Choose the palette in the consuming application; these tokens do not read system preferences or install global CSS.
+
 ## Interactive maps
 
 `createMap` defaults to `mode: 'basemap'` and `appearance.theme: 'transit'`. Set the mode explicitly for neighborhood or district exploration. District and neighborhood layer defaults follow the mode; other supplied layers default on. The [developer guide](developer-guide.md) compares static and interactive defaults and explains configuration resets, coordinates, and cleanup.
@@ -109,3 +133,11 @@ Neighborhood IDs are exact source-scoped feature IDs, rather than display names
 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.
+
+## Linked place cards
+
+`bindMapCards(map, root, options)` from `@kahwee/sf-map-svg/cards` connects consumer-owned cards to a `MapController`. Each card uses `data-map-marker="stable-marker-id"`; native `<button type="button" data-map-select>` controls select that place without panning. Article links keep their ordinary navigation. `options.markers` is the same catalog supplied to the map; `highlightColor` optionally changes the preview ring and `scrollOnSelect: false` disables automatic card reveal.
+
+Pointer hover and keyboard focus draw a temporary ring through `projectToScreen()`. They do not call `selectMarker`, change the camera, or emit selection events. Focused cards take precedence over hovered cards. Offscreen points do not draw a ring. Touch users use the selection button. Selected cards receive `data-map-selected` and their buttons receive `aria-pressed`; style the card attribute in your own CSS. Selecting a pin reveals its card with immediate native scrolling, without moving focus. Filtering/reordering/removing cards is safe; IDs are compared directly, not inserted into CSS selectors.
+
+Call `binding.setMarkers(next)` after `map.setMarkers(next)` when the catalog changes. Call `binding.destroy()` before `map.destroy()` on unmount; cleanup is idempotent and restores attributes that the binding owned. The module does not create cards, fetch data, change URLs, install global CSS, or import geography. See the [linked-card recipe](consumer-integration.md#link-place-cards-to-pins).

package/docs/consumer-integration.md

@@ -51,7 +51,7 @@ const labeledPlacesMarkup = createGuideShell({
 
 After inserting that markup, pass `markers: guideMarkers`, `layers: guideLayers`, and `appearance: { colors: guideColors }` to `mountGuideController()` as shown below. The static-only `labelLayout` option is not a browser option: the controller measures the actual canvas and font. The shell border is outside the canvas, so a default shell with a 390 px outer width has a 388 px canvas.
 
-For responsive layouts whose canvas width is unknown at build time, choose a representative width and accept text scaling until enhancement, or serve independently rendered SVG variants through your application's responsive markup. The package does not detect a device on the server. Keep `labels: false` if your design requires no visible text change at enhancement.
+For responsive layouts whose canvas width is unknown at build time, use `labelLayout.compact` for an embedded image with two static label layouts (see [editorial previews](#editorial-map-previews)), choose a representative width and accept text scaling until enhancement, or serve independently rendered SVG variants through your application's responsive markup. The package does not detect a device on the server. Keep `labels: false` if your design requires no visible text change at enhancement.
 
 For `renderMap()`, also enable `neighborhoodLabels` explicitly; it defaults off outside the guide preset. `labels: false` hides all text in either layout while preserving symbols and accessible titles.
 
@@ -87,3 +87,41 @@ For a new browser-only guide, use `createGuideController()` and mount its `.elem
 `createMap(guideMapData, guideOptions)` remains available through `/guide/data` and `/presets`. For server rendering, pass `guideMapData.map` or `/data/static` to `renderMap()`. Use `/data/full` when interactive lookup collections are needed. The guide's detailed geography loads only on an explicit `loadGuideDetailedData()` call; enabling a layer does not download it.
 
 See the [exact API contract](API.md), [worked examples](EXAMPLES.md), and [bundle measurements](guide-bundle-report.md).
+
+
+## Editorial map previews
+
+YorkSF uses one city overview to connect its field notes and compact locator maps to orient individual articles. These patterns work for any local guide: keep the place catalog in the consuming application, generate SVG images at build time, and link each preview to the application's map or article route.
+
+Run `pnpm demo` and open `examples/generated/field-guide.html` for a self-contained light/dark example. Its overview uses `labelLayout.compact` to limit mobile text without removing pins, and `haloColor` to match the night palette. The locator cards share those colors but omit labels at small sizes. Images reserve their aspect ratio and load lazily; the links work without JavaScript. The example derives its sample park coordinates from the package's existing landmark data rather than maintaining another geographic dataset.
+
+Use stable marker IDs for deep links. Keep addresses, visit dates, historical-status caveats, and editorial descriptions in your own content model. The package supplies map graphics; it does not imply that a place is currently open or that an author visited it. Keep a visible list beside the overview so the image is not the only way to find a place. SVG alt text should describe its purpose; link text should name the destination.
+
+For an image card, `compact.width` follows the image's rendered viewport. For inline SVG it follows the outer document viewport; do not assume it behaves like a container query. Avoid embedding scripts in exported images. Interactive maps remain a separate progressive enhancement.
+
+## Link place cards to pins
+
+Keep ordinary article links and add a separate map-selection button. Native buttons give keyboard and touch users the same action as pointer users:
+
+```html
+<article data-map-marker="park">
+  <h2><a href="/places/park/">A place in the park</a></h2>
+  <button type="button" data-map-select>Show on map</button>
+</article>
+```
+
+```js
+import { bindMapCards } from '@kahwee/sf-map-svg/cards';
+import { mapPalettes } from '@kahwee/sf-map-svg/presets';
+
+const binding = bindMapCards(map, document.querySelector('#place-cards'), {
+  markers: places,
+  highlightColor: mapPalettes.nightForest.selectedMarkerRingColor,
+});
+// On catalog change: map.setMarkers(next); binding.setMarkers(next);
+// On unmount: binding.destroy(); map.destroy();
+```
+
+Style `[data-map-selected]` with an outline or background change that remains legible in both themes. Use a visible focus outline on card buttons and links. Hover/focus only previews the location: it preserves selection and camera. Map selection reveals the card without shifting keyboard focus; set `scrollOnSelect: false` if your application owns scrolling. Match cards and markers by stable IDs, and keep hidden/filtered places out of both catalogs when that is your intended filter behavior.
+
+Run `pnpm demo` and open `examples/generated/linked-cards.html` for the complete pattern. Storybook **Maps / Linked place cards** checks hover, keyboard selection, card reveal, both palettes, and disposal.

package/docs/guide-bundle-report.md

@@ -1,12 +1,12 @@
 # Guide bundle size report
 
-Generated 2026-10-13 by `pnpm report:guide` with Vite production minification and gzip compression. Each emitted JS chunk is compressed independently. The report measures the explicit-data root and the optional `@kahwee/sf-map-svg/guide` preset.
+Generated 2026-10-14 by `pnpm report:guide` with Vite production minification and gzip compression. Each emitted JS chunk is compressed independently. The report measures the explicit-data root and the optional `@kahwee/sf-map-svg/guide` preset.
 
 | Entry | Initial JS, raw | Initial JS, gzip | Explicit detail JS, gzip |
 | --- | ---: | ---: | ---: |
-| Renderer root (explicit data) | 122.2 KB | 35.7 KB | — |
-| Static renderer | 31.4 KB | 9.7 KB | — |
-| Guide preset | 508.3 KB | 122.1 KB | 467.0 KB |
+| Renderer root (explicit data) | 122.8 KB | 36.3 KB | — |
+| Static renderer | 33.2 KB | 10.2 KB | — |
+| Guide preset | 507.0 KB | 122.1 KB | 467.0 KB |
 
 **500 KB target:** met.