@kahwee/sf-map-svg 4.0.1 → 4.2.0

package/dist/src/layers.d.ts

@@ -5,6 +5,8 @@ import type { BartStation, KeyRoad, Landmark } from './overlays.js';
 import type { MapMarker, SFMapOptions } from './types.js';
 interface LayerContext {
     labels: boolean;
+    /** Animated static maps index items for staggering and measure lines for drawing. */
+    animated?: boolean;
     theme: NonNullable<SFMapOptions['theme']>;
     idPrefix: string;
     colors: Required<NonNullable<SFMapOptions['colors']>>;
@@ -18,21 +20,21 @@ interface DistrictPath {
     stroke?: string;
     opacity?: number;
 }
-export declare function districtFills(districts: readonly DistrictPath[], { idPrefix }: LayerContext): string;
-export declare function districtLines(districts: readonly DistrictPath[], { idPrefix, colors }: LayerContext): string;
+export declare function districtFills(districts: readonly DistrictPath[], { idPrefix, animated }: LayerContext): string;
+export declare function districtLines(districts: readonly DistrictPath[], { idPrefix, colors, animated }: LayerContext): string;
 export declare function landmarks(items: readonly Landmark[], { idPrefix, path, colors }: LayerContext): string;
 export declare function highways(items: readonly {
     route: string;
     geometry: Geometry;
-}[], { path, colors, theme }: LayerContext): string;
+}[], { path, colors, theme, animated }: LayerContext): string;
 export declare function neighborhoods(items: readonly {
     name: string;
     geometry: Geometry;
-}[], { idPrefix, path, colors }: LayerContext): string;
+}[], { idPrefix, path, colors, animated }: LayerContext): string;
 export declare function districtLabels(districts: readonly DistrictRow[], { project, colors }: LayerContext): string;
 export declare function landmarkLabels(items: readonly Landmark[], { project, colors }: LayerContext): string;
-export declare function bartStations(items: readonly BartStation[], { project, colors, labels }: LayerContext): string;
-export declare function markers(items: readonly MapMarker[], { project, colors }: LayerContext): string;
-export declare function keyRoads(items: readonly KeyRoad[], { idPrefix, path, colors }: LayerContext): string;
+export declare function bartStations(items: readonly BartStation[], { project, colors, labels, animated }: LayerContext): string;
+export declare function markers(items: readonly MapMarker[], { project, colors, animated }: LayerContext): string;
+export declare function keyRoads(items: readonly KeyRoad[], { idPrefix, path, colors, animated }: LayerContext): string;
 export declare function keyRoadLabels(items: readonly KeyRoad[], { project }: LayerContext): string;
 export {};

package/dist/src/layers.js

@@ -1,29 +1,39 @@
 import { escapeXml, number, overlayLabel, stroke } from './svg.js';
-export function districtFills(districts, { idPrefix }) {
-    return `<g data-layer="district-fills" clip-path="url(#${idPrefix}-coast)">${districts.map((d) => `<path data-district="${d.id}" d="${d.path}" fill="${escapeXml(d.color)}"${d.opacity === undefined ? '' : ` fill-opacity="${d.opacity}"`} fill-rule="evenodd"/>`).join('')}</g>`;
+/** Custom JavaScript/JSON rows must not introduce markup or CSS through numeric IDs. */
+function districtId(id) {
+    if (!Number.isFinite(id))
+        throw new TypeError('District IDs must be finite numbers.');
+    return id;
 }
-export function districtLines(districts, { idPrefix, colors }) {
-    return `<g data-layer="district-lines" clip-path="url(#${idPrefix}-coast)">${districts.map((d) => `<path data-district="${d.id}" d="${d.path}" ${stroke(d.stroke ?? colors.district, 1.1)}${d.opacity === undefined ? '' : ` stroke-opacity="${d.opacity}"`}/>`).join('')}</g>`;
+/** Stagger index for animated static maps. */
+const order = (animated, index) => animated ? ` style="--i:${index}"` : '';
+/** Normalized length so one dash can draw a line on. */
+const drawable = (animated) => (animated ? ' pathLength="1"' : '');
+export function districtFills(districts, { idPrefix, animated }) {
+    return `<g data-layer="district-fills" clip-path="url(#${idPrefix}-coast)">${districts.map((d) => `<path data-district="${districtId(d.id)}" d="${d.path}" fill="${escapeXml(d.color)}"${d.opacity === undefined ? '' : ` fill-opacity="${d.opacity}"`} fill-rule="evenodd"${order(animated, districtId(d.id))}/>`).join('')}</g>`;
+}
+export function districtLines(districts, { idPrefix, colors, animated }) {
+    return `<g data-layer="district-lines" clip-path="url(#${idPrefix}-coast)">${districts.map((d) => `<path data-district="${districtId(d.id)}" d="${d.path}" ${stroke(d.stroke ?? colors.district, 1.1)}${d.opacity === undefined ? '' : ` stroke-opacity="${d.opacity}"`}${drawable(animated)}${order(animated, districtId(d.id))}/>`).join('')}</g>`;
 }
 export function landmarks(items, { idPrefix, path, colors }) {
     return `<g data-layer="landmarks" clip-path="url(#${idPrefix}-coast)">${items.map((item) => `<path data-landmark="${escapeXml(item.id)}" d="${path(item.geometry)}" fill="${escapeXml(colors.park)}" fill-rule="evenodd"><title>${escapeXml(item.name)}</title></path>`).join('')}</g>`;
 }
-export function highways(items, { path, colors, theme }) {
-    return `<g data-layer="highways">${items.map((road) => `<path data-route="${escapeXml(road.route)}" d="${path(road.geometry)}" ${stroke(colors.highway, theme === 'transit' ? 2 : 1.4)}/>`).join('')}</g>`;
+export function highways(items, { path, colors, theme, animated }) {
+    return `<g data-layer="highways">${items.map((road) => `<path data-route="${escapeXml(road.route)}" d="${path(road.geometry)}" ${stroke(colors.highway, theme === 'transit' ? 2 : 1.4)}${drawable(animated)}/>`).join('')}</g>`;
 }
-export function neighborhoods(items, { idPrefix, path, colors }) {
-    return `<g data-layer="neighborhood-lines" clip-path="url(#${idPrefix}-coast)">${items.map((n) => `<path data-neighborhood="${escapeXml(n.name)}" d="${path(n.geometry)}" ${stroke(colors.neighborhood, 0.65)} stroke-dasharray="2 2"><title>${escapeXml(n.name)}</title></path>`).join('')}</g>`;
+export function neighborhoods(items, { idPrefix, path, colors, animated }) {
+    return `<g data-layer="neighborhood-lines" clip-path="url(#${idPrefix}-coast)">${items.map((n, index) => `<path data-neighborhood="${escapeXml(n.name)}" d="${path(n.geometry)}" ${stroke(colors.neighborhood, 0.65)} stroke-dasharray="2 2"${order(animated, index)}><title>${escapeXml(n.name)}</title></path>`).join('')}</g>`;
 }
 export function districtLabels(districts, { project, colors }) {
     // Primary badges first, then island badges, matching the original layer order.
     const labels = [
-        ...districts.map((d) => ({ id: d.id, label: d.labelPoints[0] })),
+        ...districts.map((d) => ({ id: d.id, label: d.labelPoints[0] ?? d.label })),
         ...districts.flatMap((d) => d.labelPoints.slice(1).map((label) => ({ id: d.id, label }))),
     ];
     return `<g data-layer="district-labels" font-family="system-ui,sans-serif" font-size="12" font-weight="600" text-anchor="middle" fill="${escapeXml(colors.label)}">${labels
         .map((d) => {
         const [x, y] = project(d.label).map(number);
-        return `<g transform="translate(${x},${y})"><circle r="10" fill="#ffffff" fill-opacity=".9"/><text dy=".35em">${d.id}</text></g>`;
+        return `<g transform="translate(${x},${y})"><circle r="10" fill="#ffffff" fill-opacity=".9"/><text dy=".35em">${districtId(d.id)}</text></g>`;
     })
         .join('')}</g>`;
 }
@@ -35,29 +45,29 @@ export function landmarkLabels(items, { project, colors }) {
     })
         .join('')}</g>`;
 }
-export function bartStations(items, { project, colors, labels }) {
+export function bartStations(items, { project, colors, labels, animated }) {
     return `<g data-layer="bart-stations">${items
-        .map((station) => {
+        .map((station, index) => {
         const [x, y] = project(station.coordinates).map(number);
-        return `<g data-bart-station="${escapeXml(station.id)}" transform="translate(${x},${y})"><title>${escapeXml(station.name)} BART station</title><circle r="5" fill="#fff" stroke="${escapeXml(colors.bart)}" stroke-width="2.5"/><circle r="1.5" fill="${escapeXml(colors.bart)}"/>${labels ? `<text x="10" y="4" ${overlayLabel} fill="${escapeXml(colors.bart)}">${escapeXml(station.name)}</text>` : ''}</g>`;
+        return `<g data-bart-station="${escapeXml(station.id)}" transform="translate(${x},${y})"${order(animated, index)}><title>${escapeXml(station.name)} BART station</title><circle r="5" fill="#fff" stroke="${escapeXml(colors.bart)}" stroke-width="2.5"/><circle r="1.5" fill="${escapeXml(colors.bart)}"/>${labels ? `<text x="10" y="4" ${overlayLabel} fill="${escapeXml(colors.bart)}">${escapeXml(station.name)}</text>` : ''}</g>`;
     })
         .join('')}</g>`;
 }
-export function markers(items, { project, colors }) {
+export function markers(items, { project, colors, animated }) {
     return `<g data-layer="markers">${items
-        .map((marker) => {
+        .map((marker, index) => {
         if (marker.radius !== undefined && (!Number.isFinite(marker.radius) || marker.radius <= 0))
             throw new RangeError('Marker radius must be positive and finite.');
         const [x, y] = project([marker.lng, marker.lat]).map(number);
-        return `<circle data-marker-id="${escapeXml(marker.id)}" cx="${x}" cy="${y}" r="${marker.radius ?? (marker.selected ? 8 : 5)}" fill="${escapeXml(marker.color ?? (marker.selected ? colors.selected : colors.marker))}" stroke="#fff9e9" stroke-width="2" vector-effect="non-scaling-stroke"><title>${escapeXml(marker.label ?? marker.id)}</title></circle>`;
+        return `<circle data-marker-id="${escapeXml(marker.id)}" cx="${x}" cy="${y}" r="${marker.radius ?? (marker.selected ? 8 : 5)}" fill="${escapeXml(marker.color ?? (marker.selected ? colors.selected : colors.marker))}" stroke="#fff9e9" stroke-width="2" vector-effect="non-scaling-stroke"${order(animated, index)}><title>${escapeXml(marker.label ?? marker.id)}</title></circle>`;
     })
         .join('')}</g>`;
 }
-export function keyRoads(items, { idPrefix, path, colors }) {
+export function keyRoads(items, { idPrefix, path, colors, animated }) {
     return `<g data-layer="key-roads" clip-path="url(#${idPrefix}-coast)">${items
         .map((road) => {
         const level = road.level === 'secondary' ? 'secondary' : 'primary';
-        return `<path data-key-road="${escapeXml(road.id)}" data-key-road-level="${level}" d="${path(road.geometry)}" ${stroke(colors.road, 1)}><title>${escapeXml(road.name)}</title></path>`;
+        return `<path data-key-road="${escapeXml(road.id)}" data-key-road-level="${level}" d="${path(road.geometry)}" ${stroke(colors.road, 1)}${drawable(animated)}><title>${escapeXml(road.name)}</title></path>`;
     })
         .join('')}</g>`;
 }

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

@@ -80,6 +80,20 @@ export declare function getLayerPathsWithData(options: SFMapOptions, data: SFMap
         point: [number, number];
     }[];
 };
+export declare function resolveMapColors(theme: SFMapOptions['theme'], colors?: SFMapOptions['colors']): {
+    water: string;
+    land: string;
+    district: string;
+    neighborhood: string;
+    highway: string;
+    road: string;
+    park: string;
+    landmark: string;
+    bart: string;
+    label: string;
+    marker: string;
+    selected: string;
+};
 /** Make an offline SVG and the matching longitude/latitude projection. */
 export declare function createSFMapWithData(options: SFMapOptions, data: SFMapData): {
     svg: string;

package/dist/src/map-core.js

@@ -2,6 +2,7 @@ import { validateMarkers, validateOverlays } from './validation.js';
 import { prepareDistrictStyles } from './district-style.js';
 import { geometryPath, positions, rawProject } from './geometry.js';
 import * as layers from './layers.js';
+import { normalizeStaticAnimation, staticAnimationStyle } from './static-animation.js';
 import { escapeXml, stroke } from './svg.js';
 export const districtYears = Object.freeze([2002, 2012, 2022]);
 export const districtColors = Object.freeze([
@@ -103,6 +104,9 @@ const transitColors = {
     marker: '#0073ae',
     selected: '#0073ae',
 };
+export function resolveMapColors(theme, colors = {}) {
+    return { ...defaults, ...(theme === 'transit' ? transitColors : {}), ...colors };
+}
 let sequence = 0;
 /** Make an offline SVG and the matching longitude/latitude projection. */
 export function createSFMapWithData(options, data) {
@@ -114,7 +118,9 @@ export function createSFMapWithData(options, data) {
         throw new TypeError('idPrefix must start with a letter and contain only letters, numbers, underscores, or hyphens.');
     if (theme !== 'districts' && theme !== 'transit')
         throw new TypeError('Theme must be districts or transit.');
-    const colors = { ...defaults, ...(theme === 'transit' ? transitColors : {}), ...options.colors };
+    const colors = resolveMapColors(theme, options.colors);
+    const animation = normalizeStaticAnimation(options.animation);
+    const animated = animation !== null;
     const geometry = getLayerPathsWithData(options, data, false);
     const { project } = geometry;
     const path = (geometry) => geometryPath(geometry, project);
@@ -123,7 +129,7 @@ export function createSFMapWithData(options, data) {
     const landmarkData = data.landmarks ?? [];
     const roadData = data.keyRoads ?? [];
     const stationData = data.bartStations ?? [];
-    const context = { project, path, colors, idPrefix, theme, labels };
+    const context = { project, path, colors, idPrefix, theme, labels, animated };
     const styles = prepareDistrictStyles(districtFills || districtLines ? districts : [], options.districtStyle);
     const districtPaths = districtFills || districtLines
         ? districts.map((d, index) => {
@@ -138,7 +144,7 @@ export function createSFMapWithData(options, data) {
         })
         : [];
     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}" 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><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>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"/>`,
     ];
     // Explicit drawing order keeps optional overlays and user markers predictable.
     if (districtFills)
@@ -153,7 +159,7 @@ export function createSFMapWithData(options, data) {
         parts.push(layers.neighborhoods(data.neighborhoods ?? [], context));
     if (districtLines)
         parts.push(layers.districtLines(districtPaths, context));
-    parts.push(`<path data-layer="coastline" d="${coastPath}" ${stroke(colors.district, 0.65)}/>`);
+    parts.push(`<path data-layer="coastline" d="${coastPath}" ${stroke(colors.district, 0.65)}${animated ? ' pathLength="1"' : ''}/>`);
     if (labels && districtLabels)
         parts.push(layers.districtLabels(districts, context));
     if (labels && landmarks)
@@ -163,7 +169,7 @@ export function createSFMapWithData(options, data) {
     if (bartStations)
         parts.push(layers.bartStations(stationData, context));
     for (const overlay of options.overlays ?? []) {
-        parts.push(`<path data-overlay-id="${escapeXml(overlay.id)}"${overlay.label ? ` aria-label="${escapeXml(overlay.label)}"` : ''} d="${path(overlay.geometry)}" fill="${escapeXml(overlay.fill ?? 'none')}" fill-opacity="${overlay.fillOpacity ?? 1}" stroke="${escapeXml(overlay.stroke ?? colors.road)}" stroke-width="${overlay.strokeWidth ?? 2}" vector-effect="non-scaling-stroke"${overlay.visible === false ? ' display="none"' : ''}/>`);
+        parts.push(`<path data-overlay-id="${escapeXml(overlay.id)}"${overlay.label ? ` aria-label="${escapeXml(overlay.label)}"` : ''} d="${path(overlay.geometry)}" fill="${escapeXml(overlay.fill ?? 'none')}" fill-opacity="${overlay.fillOpacity ?? 1}" stroke="${escapeXml(overlay.stroke ?? colors.road)}" stroke-width="${overlay.strokeWidth ?? 2}" vector-effect="non-scaling-stroke"${animated ? ' pathLength="1"' : ''}${overlay.visible === false ? ' display="none"' : ''}/>`);
     }
     parts.push(layers.markers(markers, context), '</g></svg>');
     return {

package/dist/src/map.js

@@ -1,3 +1,4 @@
+import { copyAppearance } from './appearance.js';
 import { validateCameraOptions } from './camera.js';
 import { expandMapOptions, prepareConfiguration } from './configuration.js';
 import { createNeighborhoodExplorerCore } from './explorer-core.js';
@@ -6,10 +7,11 @@ import { assertOptions } from './validation.js';
 /** No geography is imported. Supply a preset or your own immutable data. */
 export function createMap(data, options = {}) {
     const expanded = expandMapOptions(options);
-    let config = prepareConfiguration({ features: {}, layers: {}, controls: {} }, {
+    let config = prepareConfiguration({ features: {}, layers: {}, controls: {}, appearance: {} }, {
         features: options.features,
         layers: options.layers,
         controls: options.controls,
+        appearance: options.appearance,
     });
     const element = createNeighborhoodExplorerCore({
         mode: 'basemap',
@@ -18,6 +20,80 @@ export function createMap(data, options = {}) {
         onOverlayActivate: () => { },
     }, data);
     const subscriptions = new Set();
+    let configurationRevision = 0;
+    const sourceList = ['realtor', 'sf-find', 'analysis'].filter((source) => !!data.neighborhoods[source]);
+    const yearList = [2002, 2012, 2022].filter((year) => !!data.map.districts?.[year] && !!data.districts?.[year]);
+    const capabilities = () => ({
+        sources: [...sourceList],
+        years: [...yearList],
+        layers: Object.fromEntries(layerKeys.map((key) => [
+            key,
+            key.startsWith('district')
+                ? !!data.map.districts?.[element.getMapState().year]?.length &&
+                    yearList.includes(element.getMapState().year)
+                : key.startsWith('neighborhood')
+                    ? !!data.neighborhoods[element.getMapState().source]?.features.length
+                    : key === 'roadLabels'
+                        ? !!data.map.keyRoads?.length
+                        : !!data.map[key]?.length,
+        ])),
+    });
+    const snapshot = () => ({
+        ...structuredClone({
+            features: config.features,
+            layers: config.layers,
+            controls: config.controls,
+        }),
+        appearance: copyAppearance(config.appearance),
+    });
+    const resolved = () => {
+        const state = element.getMapState();
+        const supplied = capabilities().layers;
+        return {
+            ...snapshot(),
+            ...state,
+            layers: Object.fromEntries(layerKeys.map((key) => [
+                key,
+                supplied[key] &&
+                    (!key.endsWith('Labels') || state.labels) &&
+                    (config.layers[key] ??
+                        (key.startsWith('district')
+                            ? state.mode === 'districts'
+                            : key.startsWith('neighborhood')
+                                ? state.mode === 'neighborhoods'
+                                : true)),
+            ])),
+        };
+    };
+    let previousMarker = element.getSelectedMarker();
+    let previousNeighborhood = element.getSelection();
+    let previousDistrict = element.getSelectedDistrict();
+    const selectionListeners = [];
+    for (const type of ['markerchange', 'neighborhoodchange', 'districtchange']) {
+        const handle = (event) => {
+            if (event.target !== element)
+                return;
+            let detail;
+            if (type === 'markerchange') {
+                const current = element.getSelectedMarker();
+                detail = { kind: 'marker', current, previous: previousMarker };
+                previousMarker = current;
+            }
+            else if (type === 'neighborhoodchange') {
+                const current = element.getSelection();
+                detail = { kind: 'neighborhood', current, previous: previousNeighborhood };
+                previousNeighborhood = current;
+            }
+            else {
+                const current = element.getSelectedDistrict();
+                detail = { kind: 'district', current, previous: previousDistrict };
+                previousDistrict = current;
+            }
+            element.dispatchEvent(new CustomEvent('selectionchange', { detail: structuredClone(detail) }));
+        };
+        element.addEventListener(type, handle);
+        selectionListeners.push(() => element.removeEventListener(type, handle));
+    }
     let destroyed = false;
     function active() {
         if (destroyed)
@@ -41,6 +117,28 @@ export function createMap(data, options = {}) {
             element.fitGeometry(geometry, padding, motion);
         }),
     });
+    function configure(patch) {
+        const revision = ++configurationRevision;
+        const next = prepareConfiguration(config, patch);
+        const hasFeatures = 'features' in patch, hasLayers = 'layers' in patch, hasControls = 'controls' in patch;
+        const layers = Object.fromEntries(layerKeys.map((key) => [key, next.layers[key]]));
+        const controls = Object.fromEntries(controlKeys.map((key) => [key, next.controls[key]]));
+        const features = patch.features === undefined
+            ? next.features
+            : Object.fromEntries(Object.keys(patch.features).map((key) => [
+                key,
+                next.features[key],
+            ]));
+        element.applyPresentation({ ...patch, ...('appearance' in patch ? { appearance: next.appearance } : {}) }, () => {
+            config = next;
+            if (hasFeatures)
+                element.setFeatures(features);
+            if (hasLayers)
+                element.setLayers(layers);
+            if (hasControls)
+                element.setControls(controls);
+        }, () => !destroyed && revision === configurationRevision);
+    }
     return Object.freeze({
         element,
         overlayElement: element.overlayElement,
@@ -48,22 +146,13 @@ export function createMap(data, options = {}) {
         get destroyed() {
             return destroyed;
         },
-        configure: use((patch) => {
-            const next = prepareConfiguration(config, patch);
-            // Full switch patches are needed so removed overrides reset engine defaults.
-            const layers = Object.fromEntries(layerKeys.map((key) => [key, next.layers[key]]));
-            const controls = Object.fromEntries(controlKeys.map((key) => [key, next.controls[key]]));
-            if ('features' in patch)
-                element.setFeatures(patch.features ?? next.features);
-            if ('layers' in patch)
-                element.setLayers(layers);
-            if ('controls' in patch)
-                element.setControls(controls);
-            config = next;
-        }),
-        getConfiguration: use(() => structuredClone(config)),
+        configure: use(configure),
+        getConfiguration: use(snapshot),
+        getResolvedConfiguration: use(resolved),
+        getCapabilities: use(capabilities),
         on: use((type, listener) => {
             if (![
+                'selectionchange',
                 'markerchange',
                 'districtchange',
                 'districthover',
@@ -97,11 +186,25 @@ export function createMap(data, options = {}) {
         getSelectedNeighborhood: use(element.getSelection),
         selectDistrict: use(element.selectDistrict),
         getSelectedDistrict: use(element.getSelectedDistrict),
-        setDistrictYear: use(element.setDistrictYear),
-        setDistrictStyle: use(element.setDistrictStyle),
-        setSource: use(element.setSource),
-        setMode: use(element.setMode),
-        setLabels: use(element.setLabels),
+        setDistrictYear: use((...args) => {
+            configurationRevision++;
+            element.setDistrictYear(...args);
+        }),
+        setDistrictStyle: use((style) => {
+            configure({ appearance: { districtStyle: style } });
+        }),
+        setSource: use((...args) => {
+            configurationRevision++;
+            element.setSource(...args);
+        }),
+        setMode: use((...args) => {
+            configurationRevision++;
+            element.setMode(...args);
+        }),
+        setLabels: use((...args) => {
+            configurationRevision++;
+            element.setLabels(...args);
+        }),
         setTouchNavigation: use(element.setTouchNavigation),
         projectToScreen: use(element.projectToScreen),
         destroy() {
@@ -110,6 +213,8 @@ export function createMap(data, options = {}) {
             destroyed = true;
             for (const unsubscribe of subscriptions)
                 unsubscribe();
+            for (const unsubscribe of selectionListeners)
+                unsubscribe();
             element.destroy();
         },
     });

package/dist/src/overlays.d.ts

@@ -1,7 +1,6 @@
-import type { Position } from '../data/types.js';
 export declare const landmarks: {
     name: string;
-    label: Position;
+    label: import("../data/types.js").Position;
     offset: readonly [number, number];
     anchor: 'middle' | 'start' | 'end';
     id: string;
@@ -10,7 +9,7 @@ export declare const landmarks: {
 export declare const bartStations: {
     id: string;
     name: string;
-    coordinates: Position;
+    coordinates: import("../data/types.js").Position;
 }[];
 export type Landmark = (typeof landmarks)[number];
 export type BartStation = (typeof bartStations)[number];
@@ -18,7 +17,7 @@ export declare const keyRoads: {
     name: string;
     level?: 'primary' | 'secondary';
     sourceNames: readonly string[];
-    label: Position;
+    label: import("../data/types.js").Position;
     segmentIds: readonly string[];
     id: string;
     geometry: import("../data/types.js").Geometry;

package/dist/src/overlays.js

@@ -12,4 +12,8 @@ export const bartStations = deepFreeze(stationData.features.map(({ id, propertie
     name: properties.name,
     coordinates: geometry.coordinates,
 })));
-export const keyRoads = deepFreeze(roadData.features.map(({ id, properties, geometry }) => ({ id, ...properties, geometry })));
+export const keyRoads = deepFreeze(roadData.features.map(({ id, properties, geometry }) => ({
+    id,
+    ...properties,
+    geometry,
+})));

package/dist/src/static-animation.d.ts

@@ -0,0 +1,13 @@
+import type { SFMapOptions } from './types.js';
+export interface StaticAnimation {
+    duration: number;
+    delay: number;
+}
+/** Validate `animation` and return timings, or null when animation is off. */
+export declare function normalizeStaticAnimation(value: SFMapOptions['animation']): StaticAnimation | null;
+/**
+ * Scoped, self-contained CSS for an animated static map. It runs when the SVG is
+ * inserted into a page or loaded as an image, and stays still under reduced motion.
+ * Line layers carry `pathLength="1"` so a single dash can draw them on.
+ */
+export declare function staticAnimationStyle(idPrefix: string, { duration, delay }: StaticAnimation): string;

package/dist/src/static-animation.js

@@ -0,0 +1,36 @@
+import { assertOptions } from './validation.js';
+/** Reference choreography length; `duration` rescales every step proportionally. */
+const REFERENCE = 2400;
+/** Validate `animation` and return timings, or null when animation is off. */
+export function normalizeStaticAnimation(value) {
+    if (value === undefined || value === false)
+        return null;
+    if (value === true)
+        return { duration: REFERENCE, delay: 0 };
+    assertOptions(value, 'animation', ['duration', 'delay']);
+    const { duration = REFERENCE, delay = 0 } = value;
+    if (typeof duration !== 'number' || !Number.isFinite(duration) || duration <= 0)
+        throw new RangeError('Animation duration must be a positive finite number.');
+    if (typeof delay !== 'number' || !Number.isFinite(delay) || delay < 0)
+        throw new RangeError('Animation delay must be a nonnegative finite number.');
+    return { duration, delay };
+}
+/**
+ * Scoped, self-contained CSS for an animated static map. It runs when the SVG is
+ * inserted into a page or loaded as an image, and stays still under reduced motion.
+ * Line layers carry `pathLength="1"` so a single dash can draw them on.
+ */
+export function staticAnimationStyle(idPrefix, { duration, delay }) {
+    const scale = duration / REFERENCE;
+    const time = (ms) => `${Math.round(ms * scale)}ms`;
+    const at = (ms, step) => step === undefined
+        ? `${Math.round(delay + ms * scale)}ms`
+        : `calc(${Math.round(delay + ms * scale)}ms + var(--i,0) * ${Math.round(step * scale)}ms)`;
+    const scope = `[data-sf-animate="${idPrefix}"]`;
+    const out = 'cubic-bezier(.16,1,.3,1)';
+    const inOut = 'cubic-bezier(.65,0,.35,1)';
+    const fade = `${idPrefix}-fade`;
+    const draw = `${idPrefix}-draw`;
+    const grow = `${idPrefix}-grow`;
+    return `<style>@keyframes ${fade}{from{opacity:0}}@keyframes ${draw}{from{stroke-dashoffset:1}}@keyframes ${grow}{from{opacity:0;transform:scale(.86)}}${scope} [data-layer="coast"]{animation:${fade} ${time(700)} ${out} ${at(0)} both}${scope} [data-layer="coastline"],${scope} [data-layer="district-lines"] path,${scope} [data-layer="highways"] path,${scope} [data-layer="key-roads"] path,${scope} [data-overlay-id]{stroke-dasharray:1}${scope} [data-layer="coastline"]{animation:${draw} ${time(1500)} ${inOut} ${at(0)} both}${scope} [data-layer="district-fills"] path{transform-box:fill-box;transform-origin:center;animation:${grow} ${time(800)} ${out} ${at(300, 60)} both}${scope} [data-layer="landmarks"]{animation:${fade} ${time(700)} ${out} ${at(900)} both}${scope} [data-layer="key-roads"] path,${scope} [data-layer="highways"] path{animation:${draw} ${time(1100)} ${inOut} ${at(1000)} both}${scope} [data-layer="neighborhood-lines"] path{animation:${fade} ${time(500)} ${out} ${at(1100, 7)} both}${scope} [data-layer="district-lines"] path{animation:${draw} ${time(1000)} ${inOut} ${at(1150, 45)} both}${scope} [data-overlay-id]{animation:${draw} ${time(1000)} ${inOut} ${at(1500)} both}${scope} [data-layer$="-labels"]{animation:${fade} ${time(600)} ${out} ${at(1850)} both}${scope} [data-bart-station]>circle,${scope} [data-marker-id]{transform-box:fill-box;transform-origin:center;animation:${grow} ${time(500)} ${out} ${at(1900, 70)} both}${scope} [data-bart-station]>text{animation:${fade} ${time(500)} ${out} ${at(2000, 70)} both}@media (prefers-reduced-motion:reduce){${scope} *{animation:none!important}}</style>`;
+}

package/dist/src/static.d.ts

@@ -1,7 +1,7 @@
 import { type SFMapData } from './map-core.js';
 import type { SFMapOptions } from './types.js';
 export type { DistrictRowData, SFMapData as StaticMapData } from './map-core.js';
-export type { DistrictStyle, DistrictYear, SFMapOptions as StaticMapOptions } from './types.js';
+export type { DistrictStyle, DistrictYear, SFMapOptions as StaticMapOptions, StaticMapAppearance, StaticMapLayers, } from './types.js';
 /** Server-safe SVG rendering with explicit data; returns SVG plus projection helpers. */
 export declare function renderMap(data: SFMapData, options?: SFMapOptions): {
     svg: string;

package/dist/src/static.js

@@ -1,9 +1,38 @@
+import { prepareAppearance } from './appearance.js';
+import { validateSwitchPatch } from './features.js';
 import { createSFMapWithData, getLayerPathsWithData } from './map-core.js';
+import { assertOptions } from './validation.js';
 /** Server-safe SVG rendering with explicit data; returns SVG plus projection helpers. */
 export function renderMap(data, options = {}) {
-    return createSFMapWithData(options, data);
+    return createSFMapWithData(expandStaticOptions(options), data);
 }
 /** Project canonical layer geometry without constructing an SVG string. */
 export function getLayerPaths(data, options = {}) {
-    return getLayerPathsWithData(options, data);
+    return getLayerPathsWithData(expandStaticOptions(options), data);
+}
+/** Grouped keys override flat compatibility keys; omitted keys preserve renderer defaults. */
+function expandStaticOptions(options) {
+    assertOptions(options, 'static map');
+    if (options.layers !== undefined)
+        validateSwitchPatch(options.layers, [
+            'districtFills',
+            'districtLines',
+            'districtLabels',
+            'neighborhoodLines',
+            'landmarks',
+            'bartStations',
+            'highways',
+            'keyRoads',
+            'roadLabels',
+        ]);
+    if (options.appearance !== undefined) {
+        assertOptions(options.appearance, 'static appearance', ['theme', 'colors', 'districtStyle']);
+    }
+    const { layers, appearance, ...flat } = options;
+    const supplied = (group = {}) => Object.fromEntries(Object.entries(group).filter(([, value]) => value !== undefined));
+    return {
+        ...flat,
+        ...supplied(layers),
+        ...supplied(appearance === undefined ? undefined : prepareAppearance({}, appearance)),
+    };
 }

package/dist/src/transit.js

@@ -5,6 +5,7 @@ import parks from '../data/landmarks.json' with { type: 'json' };
 import { createSFMapWithData } from './map-core.js';
 const districtData = districts;
 const parkData = parks;
+const stationData = stations;
 const transitMapData = {
     coast: coast.features[0].geometry,
     districts: {
@@ -38,7 +39,7 @@ export function createTransitAnimation() {
   </style>${map.svg}<div class="controls"><button type="button">Play</button><label>Journey <input aria-label="Journey progress" type="range" min="0" max="1000" value="0"></label></div><output aria-live="off"></output><p>Schematic BART journey. Straight connections between official station locations; not track geometry, a timetable, or live trains. One loop takes 28 seconds.</p>`;
     const svg = root.querySelector('svg');
     const ns = 'http://www.w3.org/2000/svg';
-    const points = stations.features.map((station) => map.project(station.geometry.coordinates));
+    const points = stationData.features.map((station) => map.project(station.geometry.coordinates));
     const line = document.createElementNS(ns, 'polyline');
     line.setAttribute('points', points.map((point) => point.join(',')).join(' '));
     line.setAttribute('fill', 'none');