@kahwee/sf-map-svg 4.1.0 → 4.3.0

package/CHANGELOG.md

@@ -2,6 +2,29 @@
 
 User-visible changes are recorded here. Unreleased entries describe changes on `main` that are not part of a tagged package release.
 
+## Unreleased
+
+## 4.3.0 — 2026-10-02
+
+- Add `selectFeature` with typed marker, neighborhood source/ID and district year/ID references. Missing or mismatched identities preserve current geography and selection.
+- Accept the same source-aware map data in static and interactive rendering. Static maps can explicitly select a supplied neighborhood definition without manually rebuilding renderer rows; compact static inputs remain supported.
+- Include current mode, source, year and labels in configuration snapshots. Route controller mode/source/label setters through atomic configuration and support explicit camera preservation with `{ resetView: false }`.
+- Refine the Pages atlas opening with concise copy, a map ahead of statistics on phones, coordinate captions and three direct paths into designing, exploring and building. Improve shared theme-button touch targets and stack API reference records on phones while retaining table semantics.
+
+- Clarify the documentation paths, progressive enhancement and cleanup examples; consolidate browser validation and release instructions into one maintenance runbook. Check README and integration recipes against the packed package.
+
+## 4.2.0 — 2026-10-01
+
+- Reuse one native dropdown treatment across Pages, with an inset chevron, a reserved end gutter, and preserved labels, keyboard behavior, and mobile pickers.
+- Strengthen the playground with strict TypeScript, checked JavaScript/TypeScript snippets, versioned design links, persistent explicit layer choices and independent static rendering. Keep mobile controls unobstructed and picker labels legible in dark mode.
+- Express explicit configuration resets for consumers using `exactOptionalPropertyTypes`, including nested appearance tokens. Make Pages API and guide references describe their actual package version without internal preview warnings.
+
+- Share grouped `layers` and supported `appearance` options between static and interactive maps, retaining flat static options and existing defaults; accept readonly static marker arrays.
+- Update interactive appearance, mode, source, district year and labels through `configure`, preserving camera and retained marker nodes. Merge appearance tokens by key and validate combined patches before commit.
+- Add `getResolvedConfiguration()` and `getCapabilities()` for effective layer switches and supplied geography, plus an additive `selectionchange` event with consistent current/previous snapshots.
+- Add a live Pages map design playground with six editable palettes, layers, typography, sample pins/routes, browser/static previews, undo/redo, shareable designs, copyable code and full-city SVG export. Keep released-package previews compatible with their installed API.
+- Refresh the Pages site: a new SF Map SVG mark traced from the real coastline, a reframed header with a release link, card-style reference tables that no longer collapse, a live filter for the API reference, an aligned playground with one-row-per-colour inks, and 12px minimum type for labels and badges.
+
 ## 4.1.0 — 2026-10-01
 
 - Validate canonical and generated GeoJSON during data checks, rejecting invalid WGS84 coordinates and malformed polygon rings before release.

package/README.md

@@ -2,7 +2,7 @@
 
 Offline, self-contained San Francisco SVG maps. The package has no runtime dependencies. Geography is always an explicit import; the root entry does not bundle data.
 
-[Live examples](https://kahwee.github.io/sf-map-svg/examples.html) · [Storybook source](stories/) · [Geographic sources](SOURCES.md) · [v3 migration](docs/migration-v3.md)
+[Getting started](docs/developer-guide.md) · [API reference](docs/API.md) · [Design playground](https://kahwee.github.io/sf-map-svg/playground.html) · [Live examples](https://kahwee.github.io/sf-map-svg/examples.html) · [Storybook source](stories/) · [Geographic sources](SOURCES.md) · [v3 migration](docs/migration-v3.md)
 
 ## Install
 
@@ -45,14 +45,19 @@ const map = createMap(fullMapData, {
   features: { motion: true },
   appearance: { theme: 'districts' },
 });
-document.querySelector('#map')?.append(map.element);
+const host = document.querySelector('#map');
+if (!host) throw new Error('Missing #map container');
+host.append(map.element);
 map.on('neighborhoodchange', ({ name }) => console.log(name));
 map.camera.zoom(1.5);
-// When the view is removed:
-map.destroy();
+// Call when your application removes this view.
+function disposeMap() {
+  map.destroy();
+  map.element.remove();
+}
 ```
 
-`createMap(data, options)` returns a controller. Use `map.element` for mounting, `map.configure({ features, layers, controls })` for runtime switches, `map.camera` for pan/zoom/fit/reset, and `map.on()` for typed events. Appearance is set at construction. SFAR realtor neighborhoods are the default when supplied; SF Find and analysis are explicit alternate sources. The `/data/full` preset includes all three collections and historical districts.
+`createMap(data, options)` returns a controller. Use `map.element` for mounting, `map.configure({ features, layers, controls, appearance, mode, source, year, labels })` for runtime switches, `map.camera` for pan/zoom/fit/reset, and `map.on()` for typed events. Appearance can change live while preserving camera, selection, and focus. `getResolvedConfiguration()` explains effective layers; `getCapabilities()` reports supplied geography. SFAR realtor neighborhoods are the default when supplied; SF Find and analysis are explicit alternate sources. The `/data/full` preset includes all three collections and historical districts.
 
 See [controller options, events, and lifecycle](docs/API.md#interactive-maps),
 [examples](docs/EXAMPLES.md), and [consumer integration](docs/consumer-integration.md).
@@ -66,13 +71,4 @@ Call `destroy()` when removing an interactive map.
 
 Canonical geography is in [`data/`](data/README.md), with provenance in [`SOURCES.md`](SOURCES.md). The public `/data` entry exposes lookup, catalog, district maps, and source-specific neighborhood collections. These are deeply frozen; clone before editing.
 
-```sh
-pnpm install --frozen-lockfile
-pnpm check
-pnpm demo
-pnpm build-storybook
-pnpm test:stories:coverage
-pnpm test:package
-```
-
-The [contributing guide](CONTRIBUTING.md) explains the geographic and release checks. If you are upgrading from v2, follow the [v3 migration guide](docs/migration-v3.md).
+Install with `pnpm install --frozen-lockfile`. See the [contributing guide](CONTRIBUTING.md) for architecture and the [validation and release runbook](https://github.com/kahwee/sf-map-svg/blob/main/docs/maintenance.md) for checks, browser inspection, and publishing. If you are upgrading from v2, follow the [v3 migration guide](docs/migration-v3.md).

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.d.ts

@@ -1,5 +1,7 @@
 import type { MapConfiguration, MapConfigurationSnapshot, MapOptions } from './controller-types.js';
 import type { NeighborhoodExplorerOptions } from './types.js';
 export declare function expandMapOptions(options: MapOptions): NeighborhoodExplorerOptions;
+type PresentationSnapshot = Pick<MapConfigurationSnapshot, 'features' | 'layers' | 'controls' | 'appearance'>;
 /** Prepare the entire configuration before any DOM mutation. */
-export declare function prepareConfiguration(current: MapConfigurationSnapshot, patch: MapConfiguration): MapConfigurationSnapshot;
+export declare function prepareConfiguration(current: PresentationSnapshot, patch: MapConfiguration): PresentationSnapshot;
+export {};

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',
@@ -48,18 +36,34 @@ export function expandMapOptions(options) {
                     ? `Use ${replacement} instead of the flat ${key} option.`
                     : 'interface is internal and is not a supported createMap option.');
         }
-    if (options.appearance !== undefined)
-        assertOptions(options.appearance, 'appearance', appearanceKeys);
+    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
             ? {}
@@ -78,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,84 @@
 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;
 }
+/** Current geographic choices and detached presentation overrides; excludes camera and selection. */
 export interface MapConfigurationSnapshot {
+    mode: NonNullable<MapOptions['mode']>;
+    source: NeighborhoodSource;
+    year: DistrictYear;
+    labels: boolean;
     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;
+};
+/** Dataset identity is explicit; selection never switches geography implicitly. */
+export type MapFeatureReference = {
+    kind: 'marker';
+    id: string | null;
+} | {
+    kind: 'neighborhood';
+    source: NeighborhoodSource;
+    id: string | null;
+} | {
+    kind: 'district';
+    year: DistrictYear;
+    id: number | null;
+};
 export interface MapEvents {
+    /** Common selection envelope; existing change events retain their payloads. */
+    selectionchange: MapSelectionChange;
     districtchange: DistrictSelection | {
         id: null;
         year: DistrictYear;
@@ -55,12 +115,18 @@ export interface MapEvents {
     };
     mapresize: undefined;
 }
+/** Convenience setters retain their historic reset default; false preserves the camera. */
+export interface MapViewUpdateOptions {
+    resetView?: boolean;
+}
 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,10 +140,16 @@ 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;
     setOverlays(overlays: readonly MapOverlay[]): void;
+    /** False for missing IDs or a source/year other than the current geography. */
+    selectFeature(reference: MapFeatureReference, options?: CameraOptions & {
+        fit?: boolean;
+    }): boolean;
     selectMarker(id: string | null, options?: CameraOptions & {
         fit?: boolean;
     }): boolean;
@@ -92,8 +164,8 @@ export interface MapController {
     getSelectedDistrict(): DistrictSelection | null;
     setDistrictYear(year: DistrictYear, options?: CameraOptions): void;
     setDistrictStyle(style: ((district: DistrictSelection['district']) => DistrictStyle) | undefined): void;
-    setSource(source: NeighborhoodSource): void;
-    setMode(mode: NonNullable<MapOptions['mode']>): void;
+    setSource(source: NeighborhoodSource, options?: MapViewUpdateOptions): void;
+    setMode(mode: NonNullable<MapOptions['mode']>, options?: MapViewUpdateOptions): void;
     setLabels(visible: boolean): void;
     setTouchNavigation(enabled: boolean): void;
     projectToScreen(lng: number, lat: number): {
@@ -104,3 +176,4 @@ export interface MapController {
     /** Idempotent; stops work and managed subscriptions. Does not remove host-owned DOM. */
     destroy(): void;
 }
+export {};

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;