@kahwee/sf-map-svg 4.0.1 → 4.2.0

package/dist/data/stations.d.ts

@@ -1,4 +1,4 @@
-import type { FeatureCollection } from './types.js';
-export declare const bartStations: FeatureCollection<{
+import type { PointFeatureCollection } from './types.js';
+export declare const bartStations: PointFeatureCollection<{
     readonly name: string;
 }>;

package/dist/data/types.d.ts

@@ -60,6 +60,13 @@ export interface FeatureCollection<P = Readonly<Record<string, unknown>>> {
     };
     readonly features: readonly Feature<P>[];
 }
+export type PointFeatureCollection<P = Readonly<Record<string, unknown>>> = Omit<FeatureCollection<P>, 'features'> & {
+    readonly features: readonly (Feature<P> & {
+        readonly geometry: Extract<Geometry, {
+            readonly type: 'Point';
+        }>;
+    })[];
+};
 export type NeighborhoodSource = 'sf-find' | 'analysis' | 'realtor';
 export interface NeighborhoodProperties {
     readonly name: string;
@@ -69,7 +76,7 @@ export interface NeighborhoodProperties {
     readonly definitionSource: NeighborhoodSource;
     readonly nameSources: readonly string[];
     readonly note?: string;
-    readonly sourceCode?: string;
+    readonly sourceCode?: string | null;
     readonly realtorDistrict?: string;
 }
 export interface NeighborhoodEntry extends NeighborhoodProperties {

package/dist/src/api.d.ts

@@ -1,3 +1,3 @@
-/** v2 root: runtime and types only. Geography is always an explicit import. */
+/** Runtime and types only. Geography is always an explicit import. */
 export * from './map.js';
 export * from './static.js';

package/dist/src/api.js

@@ -1,3 +1,3 @@
-/** v2 root: runtime and types only. Geography is always an explicit import. */
+/** Runtime and types only. Geography is always an explicit import. */
 export * from './map.js';
 export * from './static.js';

package/dist/src/appearance.d.ts

@@ -0,0 +1,5 @@
+import type { MapAppearance } from './controller-types.js';
+export declare const appearanceKeys: readonly ['theme', 'colors', 'labelStyle', 'areaStyle', 'districtStyle', 'labelSize', 'style', 'markerRadius', 'markerHitSize', 'markerColor', 'selectedMarkerColor'];
+/** Copy configuration records without cloning or invoking styling callbacks. */
+export declare function copyAppearance(value?: MapAppearance): MapAppearance;
+export declare function prepareAppearance(current: MapAppearance, patch: MapAppearance | undefined): MapAppearance;

package/dist/src/appearance.js

@@ -0,0 +1,54 @@
+import { assertOptions, validateExplorerOptions } from './validation.js';
+export const appearanceKeys = [
+    'theme',
+    'colors',
+    'labelStyle',
+    'areaStyle',
+    'districtStyle',
+    'labelSize',
+    'style',
+    'markerRadius',
+    'markerHitSize',
+    'markerColor',
+    'selectedMarkerColor',
+];
+/** Copy configuration records without cloning or invoking styling callbacks. */
+export function copyAppearance(value = {}) {
+    const { districtStyle, ...rest } = value;
+    return { ...structuredClone(rest), ...(districtStyle ? { districtStyle } : {}) };
+}
+export function prepareAppearance(current, patch) {
+    if (patch === undefined)
+        return {};
+    assertOptions(patch, 'appearance', appearanceKeys);
+    const next = { ...current, ...patch };
+    for (const key of ['colors', 'labelStyle', 'areaStyle', 'labelSize', 'style']) {
+        if (Object.hasOwn(patch, key) && patch[key] !== undefined) {
+            assertOptions(patch[key], key);
+            const tokens = { ...current[key], ...patch[key] };
+            for (const name of Object.keys(tokens))
+                if (tokens[name] === undefined)
+                    delete tokens[name];
+            Object.assign(next, { [key]: tokens });
+        }
+    }
+    for (const key of appearanceKeys)
+        if (next[key] === undefined)
+            delete next[key];
+    validateExplorerOptions(next);
+    if (next.theme !== undefined && !['districts', 'transit'].includes(next.theme))
+        throw new TypeError('Theme must be districts or transit.');
+    const min = next.labelSize?.min ?? 11, max = next.labelSize?.max ?? 12;
+    const radius = next.markerRadius ?? 6, hit = next.markerHitSize ?? 44;
+    if (![min, max, radius, hit].every(Number.isFinite) ||
+        min < 8 ||
+        max < min ||
+        max > 32 ||
+        radius <= 0 ||
+        hit < radius * 2)
+        throw new RangeError('Use label sizes from 8–32px and a positive marker radius inside its hit target.');
+    const weight = next.labelStyle?.fontWeight;
+    if (weight !== undefined && (!Number.isFinite(weight) || weight < 1 || weight > 1000))
+        throw new RangeError('Label font weight must be finite and between 1 and 1000.');
+    return copyAppearance(next);
+}

package/dist/src/configuration.js

@@ -1,18 +1,6 @@
+import { appearanceKeys, copyAppearance, prepareAppearance } from './appearance.js';
 import { controlKeys, layerKeys, normalizeFeatures, validateSwitchPatch } from './features.js';
 import { assertOptions, validateExplorerOptions } from './validation.js';
-const appearanceKeys = [
-    'theme',
-    'colors',
-    'labelStyle',
-    'areaStyle',
-    'districtStyle',
-    'labelSize',
-    'style',
-    'markerRadius',
-    'markerHitSize',
-    'markerColor',
-    'selectedMarkerColor',
-];
 const featureKeys = [
     'motion',
     'markerEntrance',
@@ -20,6 +8,8 @@ const featureKeys = [
     'clustering',
     'northArrow',
     'scaleBar',
+    'layerTransitions',
+    'districtMorph',
 ];
 export function expandMapOptions(options) {
     const record = assertOptions(options, 'map');
@@ -30,20 +20,50 @@ export function expandMapOptions(options) {
         'onMarkerActivate',
         'onOverlayActivate',
     ])
-        if (key in record)
-            throw new TypeError(`Use the v2 grouped options or map.on() instead of ${key}.`);
-    if (options.appearance !== undefined)
-        assertOptions(options.appearance, 'appearance', appearanceKeys);
+        if (key in record) {
+            const replacement = appearanceKeys.includes(key)
+                ? `appearance.${key}`
+                : featureKeys.includes(key)
+                    ? `features.${key}`
+                    : key === 'onMarkerActivate'
+                        ? "map.on('markerchange', listener)"
+                        : key === 'onOverlayActivate'
+                            ? "map.on('overlayactivate', listener)"
+                            : null;
+            throw new TypeError(key === 'onMarkerActivate'
+                ? `Marker activation callbacks are not supported; use ${replacement} for selection changes.`
+                : replacement
+                    ? `Use ${replacement} instead of the flat ${key} option.`
+                    : 'interface is internal and is not a supported createMap option.');
+        }
+    const preparedAppearance = options.appearance === undefined ? undefined : prepareAppearance({}, options.appearance);
     if (options.features !== undefined)
         normalizeFeatures(options.features);
-    const { features, appearance, ...rest } = options;
-    const expanded = { ...rest, ...appearance, ...features };
+    const { features, appearance: _appearance, ...rest } = options;
+    const expanded = { ...rest, ...preparedAppearance, ...features };
     validateExplorerOptions(expanded);
     return expanded;
 }
 /** Prepare the entire configuration before any DOM mutation. */
 export function prepareConfiguration(current, patch) {
-    assertOptions(patch, 'configuration', ['features', 'layers', 'controls']);
+    assertOptions(patch, 'configuration', [
+        'features',
+        'layers',
+        'controls',
+        'appearance',
+        'mode',
+        'source',
+        'year',
+        'labels',
+    ]);
+    if (patch.mode !== undefined && !['basemap', 'neighborhoods', 'districts'].includes(patch.mode))
+        throw new RangeError('Unknown map mode.');
+    if (patch.source !== undefined && !['realtor', 'sf-find', 'analysis'].includes(patch.source))
+        throw new RangeError('Unknown neighborhood source.');
+    if (patch.year !== undefined && ![2002, 2012, 2022].includes(patch.year))
+        throw new RangeError('District year must be 2002, 2012, or 2022.');
+    if (patch.labels !== undefined && typeof patch.labels !== 'boolean')
+        throw new TypeError('Labels must be a boolean.');
     const features = 'features' in patch
         ? normalizeFeatures(patch.features === undefined
             ? {}
@@ -62,11 +82,16 @@ export function prepareConfiguration(current, patch) {
                 delete next[property];
         return next;
     };
-    return structuredClone({
-        features,
-        layers: switches('layers', current.layers, layerKeys),
-        controls: switches('controls', current.controls, controlKeys),
-    });
+    return {
+        ...structuredClone({
+            features,
+            layers: switches('layers', current.layers, layerKeys),
+            controls: switches('controls', current.controls, controlKeys),
+        }),
+        appearance: 'appearance' in patch
+            ? prepareAppearance(current.appearance ?? {}, patch.appearance)
+            : copyAppearance(current.appearance),
+    };
 }
 function checkedFeatures(value) {
     normalizeFeatures(value);

package/dist/src/controller-types.d.ts

@@ -1,24 +1,66 @@
 import type { Geometry, NeighborhoodSource } from '../data/types.js';
 import type { CameraOptions, DistrictSelection, DistrictStyle, DistrictYear, InteractiveLayers, MapFeatures, MapMarker, MapOverlay, MapPadding, MapViewport, NeighborhoodExplorerOptions, NeighborhoodSelection } from './types.js';
-export type MapAppearance = Pick<NeighborhoodExplorerOptions, 'theme' | 'colors' | 'labelStyle' | 'areaStyle' | 'districtStyle' | 'labelSize' | 'style' | 'markerRadius' | 'markerHitSize' | 'markerColor' | 'selectedMarkerColor'>;
+/** Patch properties can explicitly remove overrides, including with exactOptionalPropertyTypes. */
+type Resettable<T> = {
+    [K in keyof T]?: T[K] | undefined;
+};
+type AppearanceOptions = Pick<NeighborhoodExplorerOptions, 'theme' | 'colors' | 'labelStyle' | 'areaStyle' | 'districtStyle' | 'labelSize' | 'style' | 'markerRadius' | 'markerHitSize' | 'markerColor' | 'selectedMarkerColor'>;
+export type MapAppearance = {
+    [K in keyof AppearanceOptions]?: K extends 'colors' | 'style' | 'labelStyle' | 'labelSize' | 'areaStyle' ? Resettable<NonNullable<AppearanceOptions[K]>> | undefined : AppearanceOptions[K] | undefined;
+};
 export type MapControls = NonNullable<NeighborhoodExplorerOptions['controls']>;
-/** Omitted groups/keys retain their values; undefined groups reset all keys in that group. */
+/** Omitted keys retain values. Undefined presentation groups reset; undefined mode/source/year/labels retain their current value. */
 export interface MapConfiguration {
-    features?: MapFeatures;
-    layers?: InteractiveLayers;
-    controls?: MapControls;
+    features?: Resettable<MapFeatures> | undefined;
+    layers?: Resettable<InteractiveLayers> | undefined;
+    controls?: Resettable<MapControls> | undefined;
+    appearance?: MapAppearance | undefined;
+    mode?: NonNullable<NeighborhoodExplorerOptions['mode']> | undefined;
+    source?: NeighborhoodSource | undefined;
+    year?: DistrictYear | undefined;
+    labels?: boolean | undefined;
 }
 export interface MapOptions extends Omit<NeighborhoodExplorerOptions, keyof MapFeatures | keyof MapAppearance | 'interface' | 'onMarkerActivate' | 'onOverlayActivate'> {
     features?: MapFeatures;
-    appearance?: MapAppearance;
+    appearance?: MapAppearance | undefined;
 }
 export interface MapConfigurationSnapshot {
     features: MapFeatures;
     /** Explicit overrides; absent values continue to follow the current mode. */
     layers: InteractiveLayers;
     controls: MapControls;
+    appearance: MapAppearance;
+}
+export interface MapCapabilities {
+    sources: readonly NeighborhoodSource[];
+    years: readonly DistrictYear[];
+    /** Data availability, independent of requested layer visibility. */
+    layers: Readonly<Record<keyof InteractiveLayers, boolean>>;
+}
+export interface ResolvedMapConfiguration extends MapConfigurationSnapshot {
+    mode: NonNullable<MapOptions['mode']>;
+    source: NeighborhoodSource;
+    year: DistrictYear;
+    labels: boolean;
+    /** Effective switches after mode defaults and data availability; label switches honor labels. */
+    layers: Record<keyof InteractiveLayers, boolean>;
 }
+export type MapSelectionChange = {
+    kind: 'marker';
+    current: MapMarker | null;
+    previous: MapMarker | null;
+} | {
+    kind: 'neighborhood';
+    current: NeighborhoodSelection | null;
+    previous: NeighborhoodSelection | null;
+} | {
+    kind: 'district';
+    current: DistrictSelection | null;
+    previous: DistrictSelection | null;
+};
 export interface MapEvents {
+    /** Common selection envelope; existing change events retain their payloads. */
+    selectionchange: MapSelectionChange;
     districtchange: DistrictSelection | {
         id: null;
         year: DistrictYear;
@@ -56,11 +98,13 @@ export interface MapEvents {
     mapresize: undefined;
 }
 export interface MapCamera {
+    /** Fixed 800 × 800 projected space, not longitude/latitude. */
     get(): MapViewport;
     set(view: MapViewport, options?: CameraOptions): void;
     fit(geometry: Geometry, options?: CameraOptions & {
         padding?: number | MapPadding;
     }): void;
+    /** Delta in projected map units. */
     pan(x: number, y: number, options?: CameraOptions): void;
     zoom(factor: number, options?: CameraOptions): void;
     reset(options?: CameraOptions): void;
@@ -74,6 +118,8 @@ export interface MapController {
     readonly destroyed: boolean;
     configure(patch: MapConfiguration): void;
     getConfiguration(): MapConfigurationSnapshot;
+    getResolvedConfiguration(): ResolvedMapConfiguration;
+    getCapabilities(): MapCapabilities;
     on<K extends keyof MapEvents>(type: K, listener: (detail: MapEvents[K]) => void): () => void;
     /** Reconcile stable IDs; retained markers preserve nodes, focus, and entrance animations. */
     setMarkers(markers: readonly MapMarker[]): void;
@@ -104,3 +150,4 @@ export interface MapController {
     /** Idempotent; stops work and managed subscriptions. Does not remove host-owned DOM. */
     destroy(): void;
 }
+export {};

package/dist/src/district-morph.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Morph district outlines between two map years. Matching rings are resampled and aligned;
+ * a ring without a partner grows from, or shrinks into, its partner's center. The real
+ * district layers stay the exact year snapshots; this only draws a decorative overlay.
+ */
+export declare function createDistrictMorph(): {
+    stop: () => void;
+    /**
+     * `previous` maps district id to its old outline path; the new outlines are read from
+     * `layer`, which stays hidden until the morph settles into it.
+     */
+    start(layer: SVGGElement, previous: ReadonlyMap<string, string>, { duration, stroke }: {
+        duration: number;
+        stroke: string;
+    }): void;
+    readonly active: boolean;
+};

package/dist/src/district-morph.js

@@ -0,0 +1,148 @@
+const svgNamespace = 'http://www.w3.org/2000/svg';
+function rings(d) {
+    return (d.match(/M[^M]*/g) ?? [])
+        .map((piece) => {
+        const node = document.createElementNS(svgNamespace, 'path');
+        node.setAttribute('d', piece);
+        const length = node.getTotalLength();
+        const middle = node.getPointAtLength(length / 2);
+        return { length, center: [middle.x, middle.y], node };
+    })
+        .filter((ring) => ring.length > 0)
+        .sort((a, b) => b.length - a.length);
+}
+function sample(ring, count) {
+    return Array.from({ length: count }, (_, index) => {
+        const point = ring.node.getPointAtLength((ring.length * index) / count);
+        return [point.x, point.y];
+    });
+}
+/** Rotate and orient `to` so each point travels the shortest total distance. */
+function align(from, to) {
+    const count = from.length;
+    let best = Number.POSITIVE_INFINITY;
+    let bestOffset = 0;
+    let bestDirection = 1;
+    for (const direction of [1, -1]) {
+        for (let offset = 0; offset < count; offset++) {
+            let score = 0;
+            for (let index = 0; index < count; index += 4) {
+                const a = from[index];
+                const b = to[(offset + direction * index + count * 2) % count];
+                score += (a[0] - b[0]) ** 2 + (a[1] - b[1]) ** 2;
+            }
+            if (score < best) {
+                best = score;
+                bestOffset = offset;
+                bestDirection = direction;
+            }
+        }
+    }
+    return from.map((_, index) => to[(bestOffset + bestDirection * index + count * 2) % count]);
+}
+const ease = (t) => (t < 0.5 ? 4 * t ** 3 : 1 - (-2 * t + 2) ** 3 / 2);
+/**
+ * Morph district outlines between two map years. Matching rings are resampled and aligned;
+ * a ring without a partner grows from, or shrinks into, its partner's center. The real
+ * district layers stay the exact year snapshots; this only draws a decorative overlay.
+ */
+export function createDistrictMorph() {
+    let frame = 0;
+    let overlay;
+    let lines;
+    function stop() {
+        cancelAnimationFrame(frame);
+        frame = 0;
+        overlay?.remove();
+        overlay = undefined;
+        lines?.style.removeProperty('opacity');
+        lines = undefined;
+    }
+    return {
+        stop,
+        /**
+         * `previous` maps district id to its old outline path; the new outlines are read from
+         * `layer`, which stays hidden until the morph settles into it.
+         */
+        start(layer, previous, { duration, stroke }) {
+            stop();
+            const next = new Map([...layer.querySelectorAll('path[data-district]')].map((path) => [
+                path.dataset.district ?? '',
+                path.getAttribute('d') ?? '',
+            ]));
+            const group = document.createElementNS(svgNamespace, 'g');
+            group.dataset.layer = 'district-morph';
+            group.setAttribute('aria-hidden', 'true');
+            group.style.pointerEvents = 'none';
+            const clip = layer.getAttribute('clip-path');
+            if (clip)
+                group.setAttribute('clip-path', clip);
+            const tracks = [];
+            for (const id of new Set([...previous.keys(), ...next.keys()])) {
+                const before = rings(previous.get(id) ?? '');
+                const after = rings(next.get(id) ?? '');
+                for (let index = 0; index < Math.max(before.length, after.length); index++) {
+                    const start = before[index];
+                    const end = after[index];
+                    if (!start && !end)
+                        continue;
+                    const count = Math.min(360, Math.max(48, Math.ceil(Math.max(start?.length ?? 0, end?.length ?? 0) / 3)));
+                    const from = start
+                        ? sample(start, count)
+                        : Array.from({ length: count }, () => end.center);
+                    const target = end
+                        ? sample(end, count)
+                        : Array.from({ length: count }, () => start.center);
+                    const node = document.createElementNS(svgNamespace, 'path');
+                    for (const [name, value] of Object.entries({
+                        fill: 'none',
+                        stroke,
+                        'stroke-width': '1.6',
+                        'stroke-linejoin': 'round',
+                        'vector-effect': 'non-scaling-stroke',
+                    }))
+                        node.setAttribute(name, value);
+                    group.append(node);
+                    tracks.push({ node, from, to: start && end ? align(from, target) : target });
+                }
+            }
+            if (!tracks.length)
+                return;
+            overlay = group;
+            lines = layer;
+            layer.after(group);
+            layer.style.opacity = '0';
+            let begin;
+            const draw = (progress) => {
+                const t = ease(progress);
+                for (const track of tracks) {
+                    let d = '';
+                    for (let index = 0; index < track.from.length; index++) {
+                        const [ax, ay] = track.from[index];
+                        const [bx, by] = track.to[index];
+                        d += `${index ? 'L' : 'M'}${(ax + (bx - ax) * t).toFixed(2)},${(ay + (by - ay) * t).toFixed(2)}`;
+                    }
+                    track.node.setAttribute('d', `${d}Z`);
+                }
+                // The morph hands over to the exact outlines in its final quarter.
+                const settle = Math.max(0, (progress - 0.75) / 0.25);
+                group.style.opacity = String(1 - settle);
+                layer.style.opacity = String(settle);
+            };
+            draw(0);
+            const tick = (time) => {
+                begin ??= time;
+                const progress = Math.min(1, (time - begin) / duration);
+                draw(progress);
+                if (progress < 1)
+                    frame = requestAnimationFrame(tick);
+                else
+                    stop();
+            };
+            frame = requestAnimationFrame(tick);
+        },
+        get active() {
+            return overlay !== undefined;
+        },
+    };
+}

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

@@ -1,5 +1,17 @@
+import type { NeighborhoodSource } from '../data/types.js';
+import type { MapConfiguration } from './controller-types.js';
 import type { InteractiveSFMapData } from './explorer-data.js';
-import type { NeighborhoodExplorerElement, NeighborhoodExplorerOptions } from './types.js';
+import type { DistrictYear, ExplorerMode, NeighborhoodExplorerElement, NeighborhoodExplorerOptions } from './types.js';
 export type { ExplorerMode, NeighborhoodExplorerElement, NeighborhoodExplorerOptions, } from './types.js';
+/** Private bridge between the renderer and its public lifecycle controller. */
+type MapEngineElement = NeighborhoodExplorerElement & {
+    applyPresentation(patch: MapConfiguration, onCommit?: () => void, isCurrent?: () => boolean): boolean;
+    getMapState(): {
+        mode: ExplorerMode;
+        source: NeighborhoodSource;
+        year: DistrictYear;
+        labels: boolean;
+    };
+};
 /** Create an offline, browser-only neighborhood explorer. Call destroy() before disposal. */
-export declare function createNeighborhoodExplorerCore(options: NeighborhoodExplorerOptions | undefined, data: InteractiveSFMapData): NeighborhoodExplorerElement;
+export declare function createNeighborhoodExplorerCore(options: NeighborhoodExplorerOptions | undefined, data: InteractiveSFMapData): MapEngineElement;