@kahwee/sf-map-svg 4.0.1 → 4.1.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.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/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');

package/dist/src/types.d.ts

@@ -55,6 +55,16 @@ export interface SFMapOptions {
     overlays?: readonly MapOverlay[];
     title?: string;
     idPrefix?: string;
+    /**
+     * Opt-in, self-contained CSS choreography for static SVGs: land fades in, the coast and
+     * lines draw, districts grow, then labels and points appear. It plays when the SVG is
+     * inserted into a page or loaded as an image, and stays still under reduced motion.
+     * `duration` (default 2400 ms) scales the whole sequence; `delay` offsets it.
+     */
+    animation?: boolean | {
+        duration?: number;
+        delay?: number;
+    };
     colors?: Partial<Record<'water' | 'land' | 'district' | 'neighborhood' | 'highway' | 'road' | 'park' | 'landmark' | 'bart' | 'label' | 'marker' | 'selected', string>>;
 }
 /** Serializable viewport in the interactive map's fixed 800 × 800 projected space. */
@@ -104,6 +114,21 @@ export interface MapFeatures {
     };
     northArrow?: boolean;
     scaleBar?: boolean;
+    /**
+     * Fade layers as `setLayers` and `setMode` switch them, crossfade neighborhood boundaries
+     * when `setSource` changes the definition, and crossfade district fills on
+     * `setDistrictStyle`. Reduced motion takes precedence.
+     */
+    layerTransitions?: boolean | {
+        duration?: number;
+    };
+    /**
+     * Morph district outlines from one map year to the next on `setDistrictYear`; pass
+     * `{ animate: false }` for an instant change. Reduced motion takes precedence.
+     */
+    districtMorph?: boolean | {
+        duration?: number;
+    };
 }
 export interface NeighborhoodExplorerOptions extends MapFeatures {
     mode?: ExplorerMode;

package/dist/src/validation.js

@@ -42,6 +42,8 @@ const optionKeys = [
     'attribution',
     'northArrow',
     'scaleBar',
+    'layerTransitions',
+    'districtMorph',
     'interface',
     'layers',
     'selectableNeighborhoods',

package/docs/API.md

@@ -0,0 +1,33 @@
+# Map options and lifecycle
+
+Start with the [static and interactive examples](../README.md). Exact option
+and event types are exported by [src/api.ts](../src/api.ts) and defined in
+[src/types.ts](../src/types.ts) and [src/controller-types.ts](../src/controller-types.ts).
+
+## Static maps
+
+Static options include `theme`, `width`, `height`, `padding`, `year` (2002, 2012, 2022), `districtLines`, `districtFills`, `districtStyle`, `districtLabels`, `neighborhoodLines`, `labels`, `highways`, `keyRoads`, `roadLabels`, `landmarks`, `bartStations`, `markers`, `overlays`, `title`, `idPrefix`, `colors`, and `animation`. Each optional layer is independent. User-supplied text and attributes are escaped in SVG output.
+
+Custom district IDs must be finite numbers. An empty `labelPoints` array uses the district's primary `label` position.
+
+`animation: true` (or `{ duration, delay }`) makes a static map draw itself with self-contained, scoped CSS: land fades in, the coast and lines draw, districts grow, then labels and points appear. It plays when the SVG is inserted into a page or loaded as an image, needs no JavaScript, and stays still under `prefers-reduced-motion`. Re-insert the markup to replay it. Default output is unchanged.
+
+## Interactive maps
+
+`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.
+
+Construction options include `mode` (`basemap`, `neighborhoods`, or `districts`), `source`, `neighborhood`, `year`, `labels`, `layers`, `controls`, `features`, `appearance`, `markers`, `overlays`, `legend`, `strings`, `attribution`, and `fitPadding`. Enable map touch gestures with the touch control or `map.setTouchNavigation(true)`. `features` holds motion, marker entrances, selected marker rings, clustering, north arrow, scale bar, layer transitions, and district morphs. `appearance` holds theme, color tokens, label and area styles, marker colors and sizes, and district styling. `layers` controls district fill/line/labels, neighborhood lines/labels, landmarks, BART, highways, key roads, and road labels. See the exported `MapOptions` type for exact values and the [Storybook examples](../stories/) for live controls.
+
+The controller also supports marker, neighborhood, and district selection; district year and style changes; source and mode changes; labels and touch navigation; screen projection; and typed `markerchange`, `neighborhoodchange`, `districtchange`, `districthover`, `districtactivate`, `districtyearchange`, `overlayactivate`, `clusteractivate`, `viewportchange`, and `mapresize` events. `destroy()` releases browser resources; operations after destruction throw.
+
+If a district callback destroys the map or selects a newer district, the interrupted activation stops without moving keyboard focus or sending a stale event.
+
+`setMarkers()` reconciles by stable marker `id`: retained markers keep their DOM nodes, focus, and in-progress entrance animations; only new IDs animate in. Identical ordered marker updates are a visual no-op. Camera state and `viewportchange` events remain synchronous, while animated camera steps and their dependent label/marker layout commit in the same browser frame.
+
+For a small guide, import `guideMapData` from `/guide/data` and pass it to `createMap`. The optional `/guide` entry also provides `createGuideMap`, `mountGuideMap`, and detailed-data loading for existing guide layouts. `/transit` provides the standalone schematic transit animation. See [examples](EXAMPLES.md) and [consumer integration](consumer-integration.md).
+
+For the guide preset with the same controller API, use `createGuideController(options)` from `/guide` (or `/guide/map`). It accepts grouped `MapOptions` and returns `MapController`; `mountGuideController(shell, options)` enhances a `createGuideShell()` container. Both use the lightweight guide geography. Existing `createGuideMap` and `mountGuideMap` calls retain their element-based API.
+
+Two opt-in features animate the map's lines and layers. `features.layerTransitions` fades layers as `configure({ layers })` and `setMode()` switch them, crossfades neighborhood boundaries when `setSource()` changes the definition, and crossfades district fills on `setDistrictStyle()`. `features.districtMorph` moves district outlines from one map year to the next on `setDistrictYear()`, then settles on the exact published geometry; pass `{ animate: false }` for an instant change. Both default off, own and cancel their animations, and yield to reduced motion.
+
+District style callbacks are evaluated once per district at construction and on style or year updates. Hover, selection, and layer toggles reuse the prepared styles; call `setDistrictStyle()` again when external styling data changes. Invalid styles leave the current map unchanged. District fades respect reduced motion and are removed on interruption or destruction.

package/docs/consumer-integration.md

@@ -1,6 +1,6 @@
 # Consumer integration
 
-Use the version 3 root controller and explicit geographic data. The [migration guide](migration-v3.md) maps removed imports to supported calls.
+Use the root controller and import geographic data explicitly. The [migration guide](migration-v3.md) maps removed v2 imports to supported calls.
 
 For a compact browser guide:
 

package/docs/developer-guide.md

@@ -0,0 +1,137 @@
+# Developer guide
+
+Choose the renderer and geography separately. `renderMap` produces a string without a DOM; `createMap` produces a browser controller whose `.element` you mount. Neither root function imports geography for you.
+
+## Choose an entry point
+
+| Task | Renderer | Data |
+| --- | --- | --- |
+| Generate an SVG file or server-rendered image | `/static`: `renderMap` | `/data/static`: `staticMapData` |
+| Explore districts or several neighborhood definitions | `/map`: `createMap` | `/data/full`: `fullMapData` |
+| Embed a smaller neighborhood guide | `/guide/map`: `createGuideController` | Included lightweight guide geography |
+| Use the guide data with the general controller | `/map`: `createMap` | `/guide/data`: `guideMapData` |
+| Look up names without mounting a map | `/data/lookup` | Source-aware lookup helpers |
+
+Imports starting with `/` in this table are package suffixes, such as `@kahwee/sf-map-svg/static`. Node 24+ is required for server rendering. Browser examples need a DOM and a bundler that supports JSON modules. This is an ESM package.
+
+## Write a static SVG
+
+```ts
+import { writeFile } from 'node:fs/promises';
+import { renderMap } from '@kahwee/sf-map-svg/static';
+import { staticMapData } from '@kahwee/sf-map-svg/data/static';
+
+const { svg } = renderMap(staticMapData, {
+  year: 2022,
+  landmarks: true,
+  bartStations: true,
+  title: 'San Francisco districts, 2022',
+});
+await writeFile('san-francisco.svg', svg);
+```
+
+The SVG is self-contained. `project([lng, lat])` returns SVG coordinates; `viewBox` is `[0, 0, width, height]`. Use a different `idPrefix` for each inline SVG on the same page, or let the renderer generate one.
+
+## Mount and dispose an interactive map
+
+Provide a host such as `<div id="map"></div>` before running this code. Run browser construction after mounting, not during server rendering.
+
+```ts
+import { createMap } from '@kahwee/sf-map-svg/map';
+import { fullMapData } from '@kahwee/sf-map-svg/data/full';
+
+const host = document.querySelector<HTMLElement>('#map');
+if (!host) throw new Error('Missing #map host');
+
+const map = createMap(fullMapData, {
+  mode: 'neighborhoods',
+  source: 'realtor',
+  layers: { bartStations: true },
+  features: { motion: true },
+  appearance: { theme: 'districts' },
+});
+host.append(map.element);
+const unsubscribe = map.on('neighborhoodchange', ({ name }) => {
+  // name is null when the selection is cleared.
+  console.log(name);
+});
+
+// Call from your framework's unmount hook or when removing the view.
+function disposeMap() {
+  unsubscribe();
+  map.destroy();
+  map.element.remove();
+}
+```
+
+`destroy()` is idempotent, cancels owned work and subscriptions, and leaves host-owned DOM in place. Other controller operations after destruction throw. In React, construct inside an effect and return cleanup; in Vue or Svelte, use their mount/unmount hooks. Do not create a new map on every render: update the existing controller instead.
+
+## Know the defaults
+
+| Setting | `renderMap` | `createMap` |
+| --- | --- | --- |
+| Mode | No mode option | `basemap`; set `neighborhoods` or `districts` explicitly |
+| Theme | `districts` | `transit`; use `appearance.theme` |
+| District layers | On | Follow `districts` mode |
+| Neighborhood layers | Lines off | Follow `neighborhoods` mode |
+| Parks, highways, key roads | Off | On when supplied |
+| Road labels | Follow `keyRoads` | On when supplied, subject to zoom/collisions |
+| BART stations | Off | On when supplied |
+| Visible labels | On | On, subject to zoom/collisions |
+| Motion features | Static animation off | Off; opt in via `features` |
+
+A layer switch does not download missing geography. `fullMapData` has `.map` for static rendering and separate lookup collections for interactive use. `staticMapData` is already a static data object. Use `renderMap(guideMapData.map, options)`, not `renderMap(guideMapData, options)`.
+
+SFAR realtor neighborhoods are the default when supplied. If only an alternative collection is supplied, the controller selects that available source. Choose `source` explicitly when comparing definitions. Sources retain separate identities; they are not interchangeable polygons.
+
+## Construction settings versus runtime updates
+
+| Change | Call |
+| --- | --- |
+| Layers, controls, behaviors | `map.configure({ layers, controls, features })` |
+| Map mode or neighborhood source | `map.setMode(mode)`, `map.setSource(source)` |
+| District boundaries or choropleth | `map.setDistrictYear(year)`, `map.setDistrictStyle(callback)` |
+| Master text visibility | `map.setLabels(visible)` |
+| Markers or route overlays | `map.setMarkers(items)`, `map.setOverlays(items)` |
+| Camera | `map.camera.set/pan/zoom/fit/reset(...)` |
+| Palette, typography, control styling | Construction-only `appearance`; recreate the map to change it |
+
+`configure` merges supplied keys; omitted keys keep their existing values. Set a layer or control key to `undefined` to remove its override. Set a whole group to `undefined` to reset that group. Set a feature to `false` to disable it. Explicit layer overrides keep winning after mode changes.
+
+```ts
+map.configure({ layers: { neighborhoodLabels: false } });
+map.configure({ layers: { neighborhoodLabels: undefined } }); // follow mode again
+map.configure({ features: { motion: false } });
+map.configure({ layers: undefined }); // clear all explicit layer overrides
+```
+
+`getConfiguration()` returns a detached snapshot of these groups, including explicit layer overrides. It is not a full serialization of mode, source, year, camera, selection, or construction appearance. Invalid configuration patches leave the current map unchanged.
+
+## Markers, routes and camera coordinates
+
+Marker positions are `{ lng, lat }`. GeoJSON coordinates and the static projection use `[longitude, latitude]`, in WGS84. Camera viewports use `[x, y, size]` in the fixed 800 × 800 projected map space; they are not geographic bounds. `camera.pan` uses projected units. `projectToScreen(lng, lat)` returns pixels relative to the map canvas, plus visibility.
+
+Marker and overlay IDs must be unique. Keep marker IDs stable across updates so retained markers preserve DOM nodes, focus and entrance animations. Use `null` to clear a selection; selection methods return a boolean. Selection events can contain null values. `map.on()` returns an unsubscribe function.
+
+Reduced motion takes precedence over animations. Map touch gestures are opt-in; hiding a chooser requires an accessible alternative in your application.
+
+## Common integration errors
+
+| Symptom | Check |
+| --- | --- |
+| No neighborhoods or district fills | Set `mode` explicitly; the default is `basemap` |
+| An enabled layer does not appear | Supply its dataset; check master labels, zoom and collision filtering |
+| A theme or motion option throws | Put styling in `appearance` and behaviors in `features`; flat interactive options are rejected |
+| Source switch throws | Supply that source collection, or use `/data/full` |
+| A geographic coordinate produces a surprising camera view | Use `camera.fit(geometry)`; `camera.set` takes projected coordinates |
+| An event handler breaks after clearing selection | Handle null `id`, `name`, `marker`, or `district` |
+| Updates throw after navigating away | Dispose once and stop calling the destroyed controller |
+| An import from `/legacy`, `/custom-map`, `/explorer`, `/interactive` or `/interactive-data` fails | Those entries were removed in v3; follow the migration guide |
+
+## Versions and assistant-readable docs
+
+The package declarations are the exact type contract for your installed version. Check the changelog before using features shown on a local preview: its Unreleased section can include functionality absent from npm.
+
+The generated `llms.txt` index links to Markdown documentation; `llms-full.txt` combines the guides and type contracts into one file. Both are built from the same package selected for the site. Local previews are labeled as working-tree docs. Released builds use the installed npm package's docs and declarations.
+
+See [API options](API.md), [worked examples](EXAMPLES.md), [consumer integration](consumer-integration.md), and [v3 migration](migration-v3.md).

package/docs/guide-bundle-report.md

@@ -1,12 +1,12 @@
 # Guide bundle size report
 
-Generated 2026-09-28 by `pnpm report:guide` with Vite production minification and gzip compression. Each emitted JS chunk is compressed independently. The report measures the explicit-data v3 root and the optional `@kahwee/sf-map-svg/guide` preset.
+Generated 2026-10-01 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 |
 | --- | ---: | ---: | ---: |
-| v3 root (explicit data) | 89.7 KB | 26.3 KB | — |
-| v3 static renderer | 15.3 KB | 5.0 KB | — |
-| Guide preset | 479.5 KB | 114.9 KB | 473.7 KB |
+| Renderer root (explicit data) | 99.3 KB | 29.1 KB | — |
+| Static renderer | 18.2 KB | 5.8 KB | — |
+| Guide preset | 489.1 KB | 116.8 KB | 467.0 KB |
 
 **500 KB target:** met.