@kahwee/sf-map-svg 4.0.1 → 4.2.0

package/dist/src/explorer-core.js

@@ -1,6 +1,8 @@
+import { copyAppearance } from './appearance.js';
 import { createCamera, validateCameraOptions } from './camera.js';
 import { clusterPoints } from './clusters.js';
 import { renderDistrictAppearance } from './district-layer.js';
+import { createDistrictMorph } from './district-morph.js';
 import { prepareDistrictStyles } from './district-style.js';
 import { createDistrictTransition } from './district-transition.js';
 import { element, svgElement } from './dom.js';
@@ -9,7 +11,8 @@ import { controlKeys, layerKeys, normalizeFeatures, validateSwitchPatch } from '
 import { createFrameScheduler } from './frame-scheduler.js';
 import { geometryPath } from './geometry.js';
 import { createLabelRenderer } from './label-renderer.js';
-import { createSFMapWithData, districtColors, getLayerPathsWithData } from './map-core.js';
+import { createLayerTransitions } from './layer-transition.js';
+import { createSFMapWithData, districtColors, getLayerPathsWithData, resolveMapColors, } from './map-core.js';
 import { createMarkerLayer } from './marker-layer.js';
 import { attachNavigation } from './navigation.js';
 import { validateExplorerOptions, validateMarkers, validateOverlays } from './validation.js';
@@ -30,12 +33,12 @@ let explorerCount = 0;
 /** Create an offline, browser-only neighborhood explorer. Call destroy() before disposal. */
 export function createNeighborhoodExplorerCore(options = {}, data) {
     validateExplorerOptions(options);
-    let { source = 'realtor', mode = 'neighborhoods', labels = true, neighborhood, year = 2022, theme = 'transit', colors = {}, labelStyle = {}, areaStyle = {}, districtStyle: initialDistrictStyle, motion = false, markerEntrance = false, selectedMarkerRing, clustering = false, legend: legendOptions = {}, attribution: attributionMode = 'full', northArrow = false, scaleBar = false, interface: chrome = 'explorer', layers = {}, selectableNeighborhoods = true, labelSize = {}, fitPadding = 24, markers: initialMarkers = [], markerRadius = 6, markerHitSize = 44, markerColor = colors.marker ?? '#245b61', selectedMarkerColor = colors.selected ?? '#f04f32', onMarkerActivate, overlays: initialOverlays = [], onOverlayActivate, style: styleOptions = {}, strings = {}, controls = {}, } = options;
+    let { source = 'realtor', mode = 'neighborhoods', labels = true, neighborhood, year = 2022, theme = 'transit', colors = {}, labelStyle = {}, areaStyle = {}, districtStyle: initialDistrictStyle, motion = false, markerEntrance = false, selectedMarkerRing, clustering = false, legend: legendOptions = {}, attribution: attributionMode = 'full', northArrow = false, scaleBar = false, layerTransitions = false, districtMorph: districtMorphOption = false, interface: chrome = 'explorer', layers = {}, selectableNeighborhoods = true, labelSize = {}, fitPadding = 24, markers: initialMarkers = [], markerRadius = 6, markerHitSize = 44, markerColor = colors.marker ?? '#245b61', selectedMarkerColor = colors.selected ?? '#f04f32', onMarkerActivate, overlays: initialOverlays = [], onOverlayActivate, style: styleOptions = {}, strings = {}, controls = {}, } = options;
     if (!['neighborhoods', 'districts', 'basemap'].includes(mode))
         throw new RangeError(`Unknown map mode: ${mode}`);
     if (chrome !== 'explorer' && chrome !== 'map')
         throw new RangeError('Unknown interface.');
-    const minLabelSize = labelSize.min ?? 11, maxLabelSize = labelSize.max ?? 12;
+    let minLabelSize = labelSize.min ?? 11, maxLabelSize = labelSize.max ?? 12;
     if (![minLabelSize, maxLabelSize, markerRadius, markerHitSize].every(Number.isFinite) ||
         minLabelSize < 8 ||
         maxLabelSize < minLabelSize ||
@@ -50,6 +53,8 @@ export function createNeighborhoodExplorerCore(options = {}, data) {
         selectedMarkerRing,
         northArrow,
         scaleBar,
+        layerTransitions,
+        districtMorph: districtMorphOption,
     });
     if (labelStyle.fontWeight !== undefined &&
         (!Number.isFinite(labelStyle.fontWeight) ||
@@ -435,6 +440,13 @@ export function createNeighborhoodExplorerCore(options = {}, data) {
             root.dispatchEvent(new CustomEvent('districtchange', { bubbles: true, detail: districtSelection(id) }));
         return true;
     }
+    function activateDistrict(id) {
+        const revision = districtRevision + 1;
+        if (!selectDistrict(id) || destroyed || revision !== districtRevision)
+            return false;
+        root.dispatchEvent(new CustomEvent('districtactivate', { bubbles: true, detail: districtSelection(id) }));
+        return !destroyed && revision === districtRevision;
+    }
     function setDistrictStyle(style) {
         if (destroyed)
             return;
@@ -445,9 +457,15 @@ export function createNeighborhoodExplorerCore(options = {}, data) {
         districtRevision++;
         districtStyle = style;
         districtStyles = prepared;
+        const fills = districtLayers.find((layer) => layer.dataset.layer === 'district-fills');
+        const fade = layerFades.duration();
+        // A new style settles any fill crossfade still running from an earlier change.
+        districtTransition.cancel();
+        if (fills && fade && enabled('districtFills'))
+            districtTransition.fade(fills, fade);
         updateDistrictAppearance();
     }
-    function setDistrictYear(next, options = {}) {
+    function setDistrictYear(next, options = {}, preparedStyles) {
         if (destroyed)
             return;
         validateCameraOptions(options);
@@ -458,15 +476,35 @@ export function createNeighborhoodExplorerCore(options = {}, data) {
         if (next === year)
             return;
         const revision = districtRevision;
-        const prepared = prepareDistrictStyles(data.map.districts[next], districtStyle);
+        const prepared = preparedStyles ?? prepareDistrictStyles(data.map.districts[next], districtStyle);
         if (destroyed || revision !== districtRevision)
             return;
         const committedRevision = ++districtRevision;
         const geometry = getLayerPathsWithData({ year: next }, data.map, false);
         const previousYear = year;
         districtTransition.cancel();
+        districtMorph.stop();
+        const lineLayer = districtLayers.find((layer) => layer.dataset.layer === 'district-lines');
+        const morph = features.districtMorph &&
+            options.animate !== false &&
+            initialized &&
+            !reducedMotion.matches &&
+            (enabled('districtLines') || enabled('districtFills'))
+            ? features.districtMorph
+            : false;
+        const previousOutlines = morph && lineLayer
+            ? new Map([...lineLayer.querySelectorAll('path[data-district]')].map((path) => [
+                path.dataset.district ?? '',
+                path.getAttribute('d') ?? '',
+            ]))
+            : undefined;
         for (const layer of districtLayers) {
-            if (options.animate && !reducedMotion.matches)
+            if (morph) {
+                // The morph replaces the line crossfade; fills fade across the whole morph.
+                if (layer !== lineLayer)
+                    districtTransition.fade(layer, morph.duration);
+            }
+            else if (options.animate && !reducedMotion.matches)
                 districtTransition.fade(layer, options.duration ?? 280);
             layer.replaceChildren(...geometry.districts.map((district) => svgElement('path', {
                 'data-district': district.id,
@@ -492,6 +530,11 @@ export function createNeighborhoodExplorerCore(options = {}, data) {
             delete root.dataset.selectedDistrict;
         updateDistrictAppearance();
         updateComposition();
+        if (morph && lineLayer && previousOutlines)
+            districtMorph.start(lineLayer, previousOutlines, {
+                duration: morph.duration,
+                stroke: colors.district ?? '#71838a',
+            });
         scheduleLabels();
         status.textContent = `${year} supervisorial districts.`;
         root.dispatchEvent(new CustomEvent('districtyearchange', { bubbles: true, detail: { year, previousYear } }));
@@ -505,6 +548,10 @@ export function createNeighborhoodExplorerCore(options = {}, data) {
     let items = [];
     let destroyed = false;
     let initialized = false;
+    const layerFades = createLayerTransitions(() => initialized && features.layerTransitions && !reducedMotion.matches
+        ? features.layerTransitions.duration
+        : 0);
+    const districtMorph = createDistrictMorph();
     const frames = createFrameScheduler({
         request: (callback) => requestAnimationFrame(callback),
         cancel: (id) => cancelAnimationFrame(id),
@@ -537,6 +584,12 @@ export function createNeighborhoodExplorerCore(options = {}, data) {
             stopAnimation();
         if (Object.hasOwn(patch, 'markerEntrance'))
             cancelEntrances();
+        if (Object.hasOwn(patch, 'layerTransitions')) {
+            layerFades.cancel();
+            districtTransition.cancel();
+        }
+        if (Object.hasOwn(patch, 'districtMorph'))
+            districtMorph.stop();
         if (Object.hasOwn(patch, 'clustering'))
             invalidateClusters();
         syncFurniture();
@@ -1066,9 +1119,7 @@ export function createNeighborhoodExplorerCore(options = {}, data) {
             moveView(target, options);
         return true;
     }
-    function setSource(next) {
-        if (destroyed)
-            return;
+    function prepareSource(next, reset = true) {
         if (!Object.hasOwn(collections, next))
             throw new RangeError(`Unknown neighborhood source: ${next}`);
         const collection = collections[next];
@@ -1139,36 +1190,42 @@ export function createNeighborhoodExplorerCore(options = {}, data) {
                 area: (bounds[2] - bounds[0]) * (bounds[3] - bounds[1]),
             };
         });
-        const hadSelection = !!selected;
-        source = next;
-        sourceSelect.value = source;
-        selected = undefined;
-        const revision = ++neighborhoodRevision;
-        delete root.dataset.selectedNeighborhood;
-        root.dataset.source = source;
-        areas.replaceChildren(...nextItems.map((item) => item.node));
-        neighborhoodSelect.replaceChildren(element('option', 'No neighborhood selected'));
-        neighborhoodSelect.options[0].value = '';
-        neighborhoodSelect.append(...nextOptions);
-        items = nextItems;
-        if (items[0])
-            items[0].node.setAttribute('tabindex', '0');
-        updateResults();
-        updateDetail();
-        updateComposition();
-        status.textContent =
-            mode === 'basemap'
-                ? 'San Francisco basemap.'
-                : mode === 'districts'
-                    ? `${year} supervisorial districts. Numbers identify each district.`
-                    : `${formatSourceLabel(source)}. Select a neighborhood to begin.`;
-        if (hadSelection)
-            root.dispatchEvent(new CustomEvent('neighborhoodchange', {
-                bubbles: true,
-                detail: { feature: null, source, id: null, name: null },
-            }));
-        if (!destroyed && neighborhoodRevision === revision)
-            resetView();
+        return () => {
+            const hadSelection = !!selected;
+            source = next;
+            sourceSelect.value = source;
+            selected = undefined;
+            const revision = ++neighborhoodRevision;
+            delete root.dataset.selectedNeighborhood;
+            root.dataset.source = source;
+            layerFades.crossfade(areas, () => areas.replaceChildren(...nextItems.map((item) => item.node)));
+            neighborhoodSelect.replaceChildren(element('option', 'No neighborhood selected'));
+            neighborhoodSelect.options[0].value = '';
+            neighborhoodSelect.append(...nextOptions);
+            items = nextItems;
+            if (items[0])
+                items[0].node.setAttribute('tabindex', '0');
+            updateResults();
+            updateDetail();
+            updateComposition();
+            status.textContent =
+                mode === 'basemap'
+                    ? 'San Francisco basemap.'
+                    : mode === 'districts'
+                        ? `${year} supervisorial districts. Numbers identify each district.`
+                        : `${formatSourceLabel(source)}. Select a neighborhood to begin.`;
+            if (hadSelection)
+                root.dispatchEvent(new CustomEvent('neighborhoodchange', {
+                    bubbles: true,
+                    detail: { feature: null, source, id: null, name: null },
+                }));
+            if (reset && !destroyed && neighborhoodRevision === revision)
+                resetView();
+        };
+    }
+    function setSource(next) {
+        if (!destroyed)
+            prepareSource(next)();
     }
     function syncFeatureControls() {
         featureControls.hidden = neighborhoodLabel.hidden && markerLabel.hidden;
@@ -1189,9 +1246,9 @@ export function createNeighborhoodExplorerCore(options = {}, data) {
         ]) {
             const layer = svg.querySelector(`[data-layer="${name}"]`);
             if (layer)
-                layer.style.display = enabled(key) ? '' : 'none';
+                layerFades.set(layer, enabled(key));
         }
-        stations.style.display = enabled('bartStations') ? '' : 'none';
+        layerFades.set(stations, enabled('bartStations'));
         for (const [kind, key] of [
             ['bart', 'bartStations'],
             ['park', 'landmarks'],
@@ -1206,7 +1263,7 @@ export function createNeighborhoodExplorerCore(options = {}, data) {
             controls.legend === false ||
                 ![...legend.children].some((node) => !node.hidden);
         const neighborhoodsVisible = enabled('neighborhoodLines') || (labels && enabled('neighborhoodLabels'));
-        areas.style.display = neighborhoodsVisible ? '' : 'none';
+        layerFades.set(areas, neighborhoodsVisible);
         areas.style.pointerEvents = selectableNeighborhoods ? '' : 'none';
         neighborhoodLabel.hidden =
             !neighborhoodsVisible ||
@@ -1223,7 +1280,7 @@ export function createNeighborhoodExplorerCore(options = {}, data) {
         }
         for (const layer of districtLayers) {
             const key = layer.dataset.layer === 'district-fills' ? 'districtFills' : 'districtLines';
-            layer.style.display = enabled(key) ? '' : 'none';
+            layerFades.set(layer, enabled(key));
         }
         updateDistrictAppearance();
         const districtsVisible = enabled('districtFills') || enabled('districtLines') || (labels && enabled('districtLabels'));
@@ -1512,12 +1569,8 @@ export function createNeighborhoodExplorerCore(options = {}, data) {
             districtRow(districtId)) {
             if (event.key === 'Enter' || event.key === ' ') {
                 event.preventDefault();
-                selectDistrict(districtId);
-                root.dispatchEvent(new CustomEvent('districtactivate', {
-                    bubbles: true,
-                    detail: districtSelection(districtId),
-                }));
-                target.focus();
+                if (activateDistrict(districtId))
+                    target.focus();
             }
             else if (event.key === '[' || event.key === ']') {
                 event.preventDefault();
@@ -1568,9 +1621,7 @@ export function createNeighborhoodExplorerCore(options = {}, data) {
             ? event.target.closest('[data-layer="district-fills"] [data-district], [data-layer="district-lines"] [data-district]')
             : null;
         if (district?.dataset.district) {
-            const id = Number(district.dataset.district);
-            selectDistrict(id);
-            root.dispatchEvent(new CustomEvent('districtactivate', { bubbles: true, detail: districtSelection(id) }));
+            activateDistrict(Number(district.dataset.district));
             return;
         }
         const node = event.target instanceof Element
@@ -1607,7 +1658,133 @@ export function createNeighborhoodExplorerCore(options = {}, data) {
         scheduleLabels();
         root.dispatchEvent(new CustomEvent('mapresize', { bubbles: true }));
     };
+    let presentationRevision = 0;
+    function applyPresentation(patch, onCommit, isCurrent = () => true) {
+        const revision = ++presentationRevision;
+        const nextYear = patch.year ?? year;
+        const nextMode = patch.mode ?? mode;
+        if ((patch.year !== undefined || nextMode === 'districts') &&
+            (!data.map.districts?.[nextYear] || !data.districts?.[nextYear]))
+            throw new RangeError(`No ${nextYear} district dataset was supplied.`);
+        if (nextMode === 'neighborhoods' && !sources.length)
+            throw new RangeError('No neighborhood dataset was supplied.');
+        const commitSource = patch.source !== undefined && patch.source !== source
+            ? prepareSource(patch.source, false)
+            : undefined;
+        const appearance = patch.appearance;
+        const nextStyle = appearance ? appearance.districtStyle : districtStyle;
+        const districtVersion = districtRevision;
+        const prepared = appearance || nextYear !== year
+            ? prepareDistrictStyles(data.map.districts?.[nextYear] ?? [], nextStyle)
+            : districtStyles;
+        if (destroyed ||
+            !isCurrent() ||
+            revision !== presentationRevision ||
+            districtVersion !== districtRevision)
+            return false;
+        if (nextYear !== year) {
+            // Validate target paths and label coordinates before any presentation group commits.
+            getLayerPathsWithData({ year: nextYear }, data.map, false);
+            for (const feature of data.districts?.[nextYear]?.features ?? [])
+                for (const point of feature.properties.labelPoints)
+                    map.project(point);
+        }
+        onCommit?.();
+        if (appearance) {
+            districtRevision++;
+            const next = copyAppearance(appearance);
+            theme = next.theme ?? 'transit';
+            colors = next.colors ?? {};
+            labelStyle = next.labelStyle ?? {};
+            areaStyle = next.areaStyle ?? {};
+            styleOptions = next.style ?? {};
+            minLabelSize = next.labelSize?.min ?? 11;
+            maxLabelSize = next.labelSize?.max ?? 12;
+            markerRadius = next.markerRadius ?? 6;
+            markerHitSize = next.markerHitSize ?? 44;
+            markerColor = next.markerColor ?? colors.marker ?? '#245b61';
+            selectedMarkerColor = next.selectedMarkerColor ?? colors.selected ?? '#f04f32';
+            districtTransition.cancel();
+            const fills = districtLayers.find((layer) => layer.dataset.layer === 'district-fills');
+            const fade = layerFades.duration();
+            const stylesChanged = nextStyle !== districtStyle ||
+                [...prepared].some(([id, value]) => ['fill', 'stroke', 'opacity'].some((key) => value[key] !== districtStyles.get(id)?.[key]));
+            if (fills && fade && enabled('districtFills') && nextYear === year && stylesChanged)
+                districtTransition.fade(fills, fade);
+            districtStyle = nextStyle;
+            districtStyles = prepared;
+            const palette = resolveMapColors(theme, colors);
+            svg.querySelector('rect')?.setAttribute('fill', palette.water);
+            svg.querySelector('[data-layer="coast"]')?.setAttribute('fill', palette.land);
+            svg.querySelector('[data-layer="coastline"]')?.setAttribute('stroke', palette.district);
+            for (const [layer, color] of [
+                ['landmarks', palette.park],
+                ['highways', palette.highway],
+                ['key-roads', palette.road],
+            ])
+                for (const node of svg.querySelectorAll(`[data-layer="${layer}"] path`)) {
+                    node.setAttribute(layer === 'landmarks' ? 'fill' : 'stroke', color);
+                    if (layer === 'highways')
+                        node.setAttribute('stroke-width', theme === 'transit' ? '2' : '1.4');
+                }
+            for (const [token, fallback, name] of [
+                ['ink', '#18364f', 'ink'],
+                ['surface', '#fff', 'surface'],
+                ['accent', '#163d61', 'accent'],
+                ['border', '#cedae3', 'border'],
+                ['focus', '#1676b8', 'focus'],
+                ['controlGap', '6px', 'control-gap'],
+                ['font', 'system-ui,sans-serif', 'font'],
+            ])
+                root.style.setProperty(`--sf-map-${name}`, styleOptions[token] ?? fallback);
+            labelLayer.setAttribute('font-family', labelStyle.fontFamily ?? styleOptions.font ?? 'system-ui,sans-serif');
+            labelRenderer.invalidateMetrics();
+            for (const station of stationItems)
+                station.node.setAttribute('stroke', colors.bart ?? '#0073ae');
+            for (const kind of ['bart', 'park', 'highway', 'road']) {
+                const symbol = legend.querySelector(`.sf-explorer-legend-${kind}`);
+                if (symbol) {
+                    symbol.style.removeProperty(kind === 'bart' ? 'border-color' : 'background-color');
+                    if (colors[kind])
+                        symbol.style.setProperty(kind === 'bart' ? 'border-color' : 'background-color', colors[kind]);
+                }
+            }
+            for (const item of items) {
+                const active = item.feature === selected;
+                item.node.setAttribute('fill', active ? (areaStyle.selectedFill ?? '#408dbe') : 'transparent');
+                item.node.setAttribute('stroke', active ? (areaStyle.selectedStroke ?? '#176ba2') : (colors.neighborhood ?? '#9caebc'));
+            }
+            for (const item of markerItems) {
+                item.dot.setAttribute('fill', item.marker.id === selectedMarker
+                    ? selectedMarkerColor
+                    : (item.marker.color ?? markerColor));
+                item.ring.setAttribute('stroke', features.selectedMarkerRing
+                    ? (features.selectedMarkerRing.color ?? selectedMarkerColor)
+                    : selectedMarkerColor);
+            }
+            invalidateClusters();
+            updateDistrictAppearance();
+        }
+        if (nextYear !== year)
+            setDistrictYear(nextYear, {}, prepared);
+        if (destroyed || revision !== presentationRevision || !isCurrent())
+            return false;
+        commitSource?.();
+        if (destroyed || revision !== presentationRevision || !isCurrent())
+            return false;
+        if (commitSource && appearance)
+            for (const item of items)
+                item.node.setAttribute('stroke', colors.neighborhood ?? '#9caebc');
+        if (patch.mode !== undefined)
+            setMode(patch.mode, false);
+        if (patch.labels !== undefined)
+            setLabels(patch.labels);
+        scheduleLabels();
+        return true;
+    }
     const explorer = Object.assign(root, {
+        applyPresentation,
+        getMapState: () => ({ mode, source, year, labels }),
         selectNeighborhood,
         getSelection,
         selectDistrict,
@@ -1639,6 +1816,8 @@ export function createNeighborhoodExplorerCore(options = {}, data) {
             destroyed = true;
             camera.destroy();
             districtTransition.cancel();
+            layerFades.cancel();
+            districtMorph.stop();
             cancelEntrances();
             controller.abort();
             overlayEvents.abort();
@@ -1661,6 +1840,8 @@ export function createNeighborhoodExplorerCore(options = {}, data) {
             if (reducedMotion.matches) {
                 stopAnimation();
                 districtTransition.cancel();
+                layerFades.cancel();
+                districtMorph.stop();
                 cancelEntrances();
             }
         }, { signal: controller.signal });

package/dist/src/features.d.ts

@@ -18,6 +18,12 @@ export declare function normalizeFeatures(input?: MapFeatures): {
     };
     northArrow: boolean;
     scaleBar: boolean;
+    layerTransitions: false | {
+        duration: number;
+    };
+    districtMorph: false | {
+        duration: number;
+    };
 };
 export declare const layerKeys: readonly ['districtFills', 'districtLines', 'districtLabels', 'neighborhoodLines', 'neighborhoodLabels', 'landmarks', 'bartStations', 'highways', 'keyRoads', 'roadLabels'];
 export declare const controlKeys: readonly ['zoom', 'pan', 'reset', 'labels', 'touch', 'legend', 'neighborhoodPicker', 'markerPicker', 'help', 'status'];

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/guide-map.js

@@ -6,7 +6,7 @@ import { guideOptions } from './presets.js';
 import { validateExplorerOptions } from './validation.js';
 function controllerOptions(options) {
     expandMapOptions(options);
-    const config = prepareConfiguration({ features: {}, layers: guideOptions.layers ?? {}, controls: {} }, {
+    const config = prepareConfiguration({ features: {}, layers: guideOptions.layers ?? {}, controls: {}, appearance: {} }, {
         features: options.features,
         layers: options.layers === undefined ? {} : options.layers,
         controls: options.controls,

package/dist/src/guide-static.js

@@ -1,9 +1,9 @@
 import { guideMapData } from './guide-data.js';
 import { guideShellCSS } from './guide-shell.js';
-import { createSFMapWithData } from './map-core.js';
+import { renderMap } from './static.js';
 /** Server-safe overview using exactly the guide browser geography. */
 export function createGuideSVG(options = {}) {
-    return createSFMapWithData({
+    return renderMap(guideMapData.map, {
         theme: 'transit',
         districtFills: false,
         districtLines: false,
@@ -14,7 +14,7 @@ export function createGuideSVG(options = {}) {
         keyRoads: true,
         bartStations: true,
         ...options,
-    }, guideMapData.map);
+    });
 }
 /** Stable compact frame, progressively enhanced with mountGuideMap(). No browser globals. */
 export function createGuideShell(options = {}) {

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();
+        },
+    };
+}