@kahwee/sf-map-svg 4.0.0 → 4.1.0

package/dist/src/features.js

@@ -4,7 +4,7 @@ function objectOption(value, name) {
         return false;
     if (value === true)
         return {};
-    assertOptions(value, name, name === 'motion'
+    assertOptions(value, name, name === 'motion' || name === 'layerTransitions' || name === 'districtMorph'
         ? ['duration']
         : name === 'markerEntrance'
             ? ['duration', 'stagger']
@@ -36,6 +36,8 @@ export function normalizeFeatures(input = {}) {
         'selectedMarkerRing',
         'northArrow',
         'scaleBar',
+        'layerTransitions',
+        'districtMorph',
     ];
     for (const key of Object.keys(input))
         if (!keys.includes(key))
@@ -44,6 +46,8 @@ export function normalizeFeatures(input = {}) {
     const entrance = objectOption(input.markerEntrance, 'markerEntrance');
     const clustering = objectOption(input.clustering, 'clustering');
     const ring = objectOption(input.selectedMarkerRing, 'selectedMarkerRing');
+    const layerTransitions = objectOption(input.layerTransitions, 'layerTransitions');
+    const districtMorph = objectOption(input.districtMorph, 'districtMorph');
     if (ring && ring.color !== undefined && typeof ring.color !== 'string')
         throw new TypeError('Ring color must be a string.');
     return {
@@ -62,6 +66,12 @@ export function normalizeFeatures(input = {}) {
         },
         northArrow: flag(input.northArrow, 'northArrow'),
         scaleBar: flag(input.scaleBar, 'scaleBar'),
+        layerTransitions: layerTransitions && {
+            duration: numberOption(layerTransitions.duration, 360, 'Layer transition duration'),
+        },
+        districtMorph: districtMorph && {
+            duration: numberOption(districtMorph.duration, 1100, 'District morph duration', true),
+        },
     };
 }
 export const layerKeys = [

package/dist/src/frame-scheduler.d.ts

@@ -0,0 +1,11 @@
+/** One browser frame for camera advancement and the dependent screen-space rendering. */
+export declare function createFrameScheduler({ request, cancel, render, }: {
+    request: (callback: FrameRequestCallback) => number;
+    cancel: (id: number) => void;
+    render: () => void;
+}): {
+    request(callback: FrameRequestCallback): number;
+    cancel(id: number): void;
+    invalidate(): void;
+    destroy(): void;
+};

package/dist/src/frame-scheduler.js

@@ -0,0 +1,64 @@
+/** One browser frame for camera advancement and the dependent screen-space rendering. */
+export function createFrameScheduler({ request, cancel, render, }) {
+    let frame;
+    let pending;
+    let sequence = 0;
+    let dirty = false;
+    let flushing = false;
+    let destroyed = false;
+    function schedule() {
+        if (!destroyed && !flushing && frame === undefined && (pending || dirty))
+            frame = request(flush);
+    }
+    function flush(time) {
+        frame = undefined;
+        if (destroyed)
+            return;
+        flushing = true;
+        const next = pending;
+        pending = undefined;
+        try {
+            next?.callback(time);
+            if (!destroyed && dirty) {
+                dirty = false;
+                render();
+            }
+        }
+        finally {
+            flushing = false;
+            schedule();
+        }
+    }
+    return {
+        request(callback) {
+            const id = ++sequence;
+            if (!destroyed) {
+                pending = { id, callback };
+                schedule();
+            }
+            return id;
+        },
+        cancel(id) {
+            if (pending?.id === id)
+                pending = undefined;
+            if (!pending && !dirty && frame !== undefined) {
+                cancel(frame);
+                frame = undefined;
+            }
+        },
+        invalidate() {
+            if (destroyed)
+                return;
+            dirty = true;
+            schedule();
+        },
+        destroy() {
+            destroyed = true;
+            if (frame !== undefined)
+                cancel(frame);
+            frame = undefined;
+            pending = undefined;
+            dirty = false;
+        },
+    };
+}

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

@@ -0,0 +1,18 @@
+/**
+ * Opacity transitions for interactive layer switches and source swaps. `duration()` is read
+ * on every change, so reduced motion, construction, and runtime feature patches take effect
+ * immediately. All animations are owned here and settle synchronously on cancel.
+ */
+export declare function createLayerTransitions(duration: () => number): {
+    /** The active transition duration in milliseconds, or 0 when transitions are off. */
+    duration: () => number;
+    /** Show or hide a layer, fading when a transition duration is active. */
+    set(node: SVGElement | HTMLElement, visible: boolean): void;
+    /**
+     * Replace a visible layer's contents while an inert copy of the old contents fades out
+     * above the new ones as they fade in.
+     */
+    crossfade(node: SVGGElement, replace: () => void): void;
+    /** Jump every layer to its final state and remove all decorative copies. */
+    cancel(): void;
+};

package/dist/src/layer-transition.js

@@ -0,0 +1,102 @@
+/** Remove interaction and accessibility hooks from a decorative copy of a layer. */
+function makeInert(node) {
+    node.setAttribute('aria-hidden', 'true');
+    node.style.pointerEvents = 'none';
+    for (const item of [node, ...node.querySelectorAll('*')]) {
+        for (const name of ['id', 'tabindex', 'role', 'aria-label', 'aria-pressed'])
+            item.removeAttribute(name);
+    }
+}
+/**
+ * Opacity transitions for interactive layer switches and source swaps. `duration()` is read
+ * on every change, so reduced motion, construction, and runtime feature patches take effect
+ * immediately. All animations are owned here and settle synchronously on cancel.
+ */
+export function createLayerTransitions(duration) {
+    const fades = new Map();
+    const ghosts = new Set();
+    function settle(node) {
+        const running = fades.get(node);
+        if (!running)
+            return;
+        fades.delete(node);
+        running.animation.cancel();
+        if (running.hiding)
+            node.style.display = 'none';
+    }
+    return {
+        /** The active transition duration in milliseconds, or 0 when transitions are off. */
+        duration,
+        /** Show or hide a layer, fading when a transition duration is active. */
+        set(node, visible) {
+            const running = fades.get(node);
+            const shown = node.style.display !== 'none' && !running?.hiding;
+            if (running) {
+                fades.delete(node);
+                running.animation.cancel();
+            }
+            const ms = duration();
+            if (!ms || visible === shown || typeof node.animate !== 'function') {
+                node.style.display = visible ? '' : 'none';
+                return;
+            }
+            node.style.display = '';
+            const animation = node.animate(visible ? [{ opacity: 0 }, { opacity: 1 }] : [{ opacity: 1 }, { opacity: 0 }], { duration: ms, easing: visible ? 'ease-out' : 'ease-in', fill: 'forwards' });
+            const entry = { animation, hiding: !visible };
+            fades.set(node, entry);
+            animation.finished.then(() => {
+                if (fades.get(node) === entry)
+                    settle(node);
+            }, () => { });
+        },
+        /**
+         * Replace a visible layer's contents while an inert copy of the old contents fades out
+         * above the new ones as they fade in.
+         */
+        crossfade(node, replace) {
+            const ms = duration();
+            if (!ms || node.style.display === 'none' || typeof node.animate !== 'function') {
+                replace();
+                return;
+            }
+            const ghost = node.cloneNode(true);
+            makeInert(ghost);
+            ghost.dataset.layerTransition = '';
+            replace();
+            node.after(ghost);
+            const fadeOut = ghost.animate([{ opacity: 1 }, { opacity: 0 }], {
+                duration: ms,
+                easing: 'ease-out',
+                fill: 'forwards',
+            });
+            const entry = { animation: fadeOut, node: ghost };
+            ghosts.add(entry);
+            const remove = () => {
+                ghosts.delete(entry);
+                ghost.remove();
+            };
+            fadeOut.finished.then(remove, remove);
+            settle(node);
+            const fadeIn = node.animate([{ opacity: 0 }, { opacity: 1 }], {
+                duration: ms,
+                easing: 'ease-out',
+            });
+            const incoming = { animation: fadeIn, hiding: false };
+            fades.set(node, incoming);
+            fadeIn.finished.then(() => {
+                if (fades.get(node) === incoming)
+                    fades.delete(node);
+            }, () => { });
+        },
+        /** Jump every layer to its final state and remove all decorative copies. */
+        cancel() {
+            for (const node of [...fades.keys()])
+                settle(node);
+            for (const { animation, node } of [...ghosts]) {
+                animation.cancel();
+                node.remove();
+            }
+            ghosts.clear();
+        },
+    };
+}

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.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([
@@ -115,6 +116,8 @@ export function createSFMapWithData(options, data) {
     if (theme !== 'districts' && theme !== 'transit')
         throw new TypeError('Theme must be districts or transit.');
     const colors = { ...defaults, ...(theme === 'transit' ? transitColors : {}), ...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 +126,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 +141,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 +156,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 +166,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/marker-layer.d.ts

@@ -7,11 +7,14 @@ export interface MarkerItem {
     dot: SVGCircleElement;
     hit: SVGCircleElement;
     ring: SVGCircleElement;
+    title: SVGTitleElement;
 }
 /** Own marker visuals and entrances; selection/events remain with the controller. */
 export declare function createMarkerLayer(layer: SVGGElement): {
     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, }: {
         features: ReturnType<typeof normalizeFeatures>;
         markerColor: string;

package/dist/src/marker-layer.js

@@ -1,9 +1,9 @@
 import { svgElement } from './dom.js';
 /** Own marker visuals and entrances; selection/events remain with the controller. */
 export function createMarkerLayer(layer) {
-    const animations = new Set();
+    const animations = new Map();
     function cancelEntrances() {
-        for (const animation of animations)
+        for (const animation of animations.values())
             animation.cancel();
         animations.clear();
     }
@@ -13,6 +13,24 @@ export function createMarkerLayer(layer) {
             cancelEntrances();
             layer.replaceChildren();
         },
+        remove(item) {
+            animations.get(item.node)?.cancel();
+            animations.delete(item.node);
+            item.node.remove();
+        },
+        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);
+            }
+            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;
+        },
         add(marker, point, index, { features, markerColor, selectedMarkerColor, reducedMotion, enter, }) {
             const node = svgElement('g', {
                 transform: `translate(${point[0]},${point[1]})`,
@@ -54,11 +72,15 @@ export function createMarkerLayer(layer) {
                     easing: 'cubic-bezier(.2,.8,.2,1)',
                     fill: 'backwards',
                 });
-                animations.add(animation);
-                animation.finished.then(() => animations.delete(animation), () => animations.delete(animation));
+                animations.set(node, animation);
+                const release = () => {
+                    if (animations.get(node) === animation)
+                        animations.delete(node);
+                };
+                animation.finished.then(release, release);
             }
             layer.append(node);
-            return { marker, point, node, dot, hit, ring };
+            return { marker, point, node, dot, hit, ring, title };
         },
     };
 }

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/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');