@kahwee/sf-map-svg 4.1.0 → 4.2.0

package/dist/src/map.js

@@ -1,3 +1,4 @@
+import { copyAppearance } from './appearance.js';
 import { validateCameraOptions } from './camera.js';
 import { expandMapOptions, prepareConfiguration } from './configuration.js';
 import { createNeighborhoodExplorerCore } from './explorer-core.js';
@@ -6,10 +7,11 @@ import { assertOptions } from './validation.js';
 /** No geography is imported. Supply a preset or your own immutable data. */
 export function createMap(data, options = {}) {
     const expanded = expandMapOptions(options);
-    let config = prepareConfiguration({ features: {}, layers: {}, controls: {} }, {
+    let config = prepareConfiguration({ features: {}, layers: {}, controls: {}, appearance: {} }, {
         features: options.features,
         layers: options.layers,
         controls: options.controls,
+        appearance: options.appearance,
     });
     const element = createNeighborhoodExplorerCore({
         mode: 'basemap',
@@ -18,6 +20,80 @@ export function createMap(data, options = {}) {
         onOverlayActivate: () => { },
     }, data);
     const subscriptions = new Set();
+    let configurationRevision = 0;
+    const sourceList = ['realtor', 'sf-find', 'analysis'].filter((source) => !!data.neighborhoods[source]);
+    const yearList = [2002, 2012, 2022].filter((year) => !!data.map.districts?.[year] && !!data.districts?.[year]);
+    const capabilities = () => ({
+        sources: [...sourceList],
+        years: [...yearList],
+        layers: Object.fromEntries(layerKeys.map((key) => [
+            key,
+            key.startsWith('district')
+                ? !!data.map.districts?.[element.getMapState().year]?.length &&
+                    yearList.includes(element.getMapState().year)
+                : key.startsWith('neighborhood')
+                    ? !!data.neighborhoods[element.getMapState().source]?.features.length
+                    : key === 'roadLabels'
+                        ? !!data.map.keyRoads?.length
+                        : !!data.map[key]?.length,
+        ])),
+    });
+    const snapshot = () => ({
+        ...structuredClone({
+            features: config.features,
+            layers: config.layers,
+            controls: config.controls,
+        }),
+        appearance: copyAppearance(config.appearance),
+    });
+    const resolved = () => {
+        const state = element.getMapState();
+        const supplied = capabilities().layers;
+        return {
+            ...snapshot(),
+            ...state,
+            layers: Object.fromEntries(layerKeys.map((key) => [
+                key,
+                supplied[key] &&
+                    (!key.endsWith('Labels') || state.labels) &&
+                    (config.layers[key] ??
+                        (key.startsWith('district')
+                            ? state.mode === 'districts'
+                            : key.startsWith('neighborhood')
+                                ? state.mode === 'neighborhoods'
+                                : true)),
+            ])),
+        };
+    };
+    let previousMarker = element.getSelectedMarker();
+    let previousNeighborhood = element.getSelection();
+    let previousDistrict = element.getSelectedDistrict();
+    const selectionListeners = [];
+    for (const type of ['markerchange', 'neighborhoodchange', 'districtchange']) {
+        const handle = (event) => {
+            if (event.target !== element)
+                return;
+            let detail;
+            if (type === 'markerchange') {
+                const current = element.getSelectedMarker();
+                detail = { kind: 'marker', current, previous: previousMarker };
+                previousMarker = current;
+            }
+            else if (type === 'neighborhoodchange') {
+                const current = element.getSelection();
+                detail = { kind: 'neighborhood', current, previous: previousNeighborhood };
+                previousNeighborhood = current;
+            }
+            else {
+                const current = element.getSelectedDistrict();
+                detail = { kind: 'district', current, previous: previousDistrict };
+                previousDistrict = current;
+            }
+            element.dispatchEvent(new CustomEvent('selectionchange', { detail: structuredClone(detail) }));
+        };
+        element.addEventListener(type, handle);
+        selectionListeners.push(() => element.removeEventListener(type, handle));
+    }
     let destroyed = false;
     function active() {
         if (destroyed)
@@ -41,6 +117,28 @@ export function createMap(data, options = {}) {
             element.fitGeometry(geometry, padding, motion);
         }),
     });
+    function configure(patch) {
+        const revision = ++configurationRevision;
+        const next = prepareConfiguration(config, patch);
+        const hasFeatures = 'features' in patch, hasLayers = 'layers' in patch, hasControls = 'controls' in patch;
+        const layers = Object.fromEntries(layerKeys.map((key) => [key, next.layers[key]]));
+        const controls = Object.fromEntries(controlKeys.map((key) => [key, next.controls[key]]));
+        const features = patch.features === undefined
+            ? next.features
+            : Object.fromEntries(Object.keys(patch.features).map((key) => [
+                key,
+                next.features[key],
+            ]));
+        element.applyPresentation({ ...patch, ...('appearance' in patch ? { appearance: next.appearance } : {}) }, () => {
+            config = next;
+            if (hasFeatures)
+                element.setFeatures(features);
+            if (hasLayers)
+                element.setLayers(layers);
+            if (hasControls)
+                element.setControls(controls);
+        }, () => !destroyed && revision === configurationRevision);
+    }
     return Object.freeze({
         element,
         overlayElement: element.overlayElement,
@@ -48,22 +146,13 @@ export function createMap(data, options = {}) {
         get destroyed() {
             return destroyed;
         },
-        configure: use((patch) => {
-            const next = prepareConfiguration(config, patch);
-            // Full switch patches are needed so removed overrides reset engine defaults.
-            const layers = Object.fromEntries(layerKeys.map((key) => [key, next.layers[key]]));
-            const controls = Object.fromEntries(controlKeys.map((key) => [key, next.controls[key]]));
-            if ('features' in patch)
-                element.setFeatures(patch.features ?? next.features);
-            if ('layers' in patch)
-                element.setLayers(layers);
-            if ('controls' in patch)
-                element.setControls(controls);
-            config = next;
-        }),
-        getConfiguration: use(() => structuredClone(config)),
+        configure: use(configure),
+        getConfiguration: use(snapshot),
+        getResolvedConfiguration: use(resolved),
+        getCapabilities: use(capabilities),
         on: use((type, listener) => {
             if (![
+                'selectionchange',
                 'markerchange',
                 'districtchange',
                 'districthover',
@@ -97,11 +186,25 @@ export function createMap(data, options = {}) {
         getSelectedNeighborhood: use(element.getSelection),
         selectDistrict: use(element.selectDistrict),
         getSelectedDistrict: use(element.getSelectedDistrict),
-        setDistrictYear: use(element.setDistrictYear),
-        setDistrictStyle: use(element.setDistrictStyle),
-        setSource: use(element.setSource),
-        setMode: use(element.setMode),
-        setLabels: use(element.setLabels),
+        setDistrictYear: use((...args) => {
+            configurationRevision++;
+            element.setDistrictYear(...args);
+        }),
+        setDistrictStyle: use((style) => {
+            configure({ appearance: { districtStyle: style } });
+        }),
+        setSource: use((...args) => {
+            configurationRevision++;
+            element.setSource(...args);
+        }),
+        setMode: use((...args) => {
+            configurationRevision++;
+            element.setMode(...args);
+        }),
+        setLabels: use((...args) => {
+            configurationRevision++;
+            element.setLabels(...args);
+        }),
         setTouchNavigation: use(element.setTouchNavigation),
         projectToScreen: use(element.projectToScreen),
         destroy() {
@@ -110,6 +213,8 @@ export function createMap(data, options = {}) {
             destroyed = true;
             for (const unsubscribe of subscriptions)
                 unsubscribe();
+            for (const unsubscribe of selectionListeners)
+                unsubscribe();
             element.destroy();
         },
     });

package/dist/src/static.d.ts

@@ -1,7 +1,7 @@
 import { type SFMapData } from './map-core.js';
 import type { SFMapOptions } from './types.js';
 export type { DistrictRowData, SFMapData as StaticMapData } from './map-core.js';
-export type { DistrictStyle, DistrictYear, SFMapOptions as StaticMapOptions } from './types.js';
+export type { DistrictStyle, DistrictYear, SFMapOptions as StaticMapOptions, StaticMapAppearance, StaticMapLayers, } from './types.js';
 /** Server-safe SVG rendering with explicit data; returns SVG plus projection helpers. */
 export declare function renderMap(data: SFMapData, options?: SFMapOptions): {
     svg: string;

package/dist/src/static.js

@@ -1,9 +1,38 @@
+import { prepareAppearance } from './appearance.js';
+import { validateSwitchPatch } from './features.js';
 import { createSFMapWithData, getLayerPathsWithData } from './map-core.js';
+import { assertOptions } from './validation.js';
 /** Server-safe SVG rendering with explicit data; returns SVG plus projection helpers. */
 export function renderMap(data, options = {}) {
-    return createSFMapWithData(options, data);
+    return createSFMapWithData(expandStaticOptions(options), data);
 }
 /** Project canonical layer geometry without constructing an SVG string. */
 export function getLayerPaths(data, options = {}) {
-    return getLayerPathsWithData(options, data);
+    return getLayerPathsWithData(expandStaticOptions(options), data);
+}
+/** Grouped keys override flat compatibility keys; omitted keys preserve renderer defaults. */
+function expandStaticOptions(options) {
+    assertOptions(options, 'static map');
+    if (options.layers !== undefined)
+        validateSwitchPatch(options.layers, [
+            'districtFills',
+            'districtLines',
+            'districtLabels',
+            'neighborhoodLines',
+            'landmarks',
+            'bartStations',
+            'highways',
+            'keyRoads',
+            'roadLabels',
+        ]);
+    if (options.appearance !== undefined) {
+        assertOptions(options.appearance, 'static appearance', ['theme', 'colors', 'districtStyle']);
+    }
+    const { layers, appearance, ...flat } = options;
+    const supplied = (group = {}) => Object.fromEntries(Object.entries(group).filter(([, value]) => value !== undefined));
+    return {
+        ...flat,
+        ...supplied(layers),
+        ...supplied(appearance === undefined ? undefined : prepareAppearance({}, appearance)),
+    };
 }

package/dist/src/types.d.ts

@@ -33,6 +33,9 @@ export interface MapOverlay {
     label?: string;
 }
 export interface SFMapOptions {
+    /** Grouped presentation; supplied keys take precedence over flat compatibility options. */
+    layers?: StaticMapLayers;
+    appearance?: StaticMapAppearance;
     theme?: 'districts' | 'transit';
     width?: number;
     height?: number;
@@ -51,7 +54,7 @@ export interface SFMapOptions {
     roadLabels?: boolean;
     landmarks?: boolean;
     bartStations?: boolean;
-    markers?: MapMarker[];
+    markers?: readonly MapMarker[];
     overlays?: readonly MapOverlay[];
     title?: string;
     idPrefix?: string;
@@ -67,6 +70,9 @@ export interface SFMapOptions {
     };
     colors?: Partial<Record<'water' | 'land' | 'district' | 'neighborhood' | 'highway' | 'road' | 'park' | 'landmark' | 'bart' | 'label' | 'marker' | 'selected', string>>;
 }
+/** Presentation supported by both the static and interactive renderers. */
+export type StaticMapLayers = Omit<InteractiveLayers, 'neighborhoodLabels'>;
+export type StaticMapAppearance = Pick<SFMapOptions, 'theme' | 'colors' | 'districtStyle'>;
 /** Serializable viewport in the interactive map's fixed 800 × 800 projected space. */
 export type MapViewport = readonly [x: number, y: number, size: number];
 export type ExplorerMode = 'neighborhoods' | 'districts' | 'basemap';
@@ -245,4 +251,4 @@ export interface NeighborhoodExplorerElement extends HTMLElement {
 export interface TransitAnimationElement extends HTMLElement {
     destroy(): void;
 }
-export type { MapAppearance, MapCamera, MapConfiguration, MapController, MapEvents, MapOptions, } from './controller-types.js';
+export type { MapAppearance, MapCamera, MapCapabilities, MapConfiguration, MapConfigurationSnapshot, MapController, MapControls, MapEvents, MapOptions, MapSelectionChange, ResolvedMapConfiguration, } from './controller-types.js';

package/docs/API.md

@@ -6,7 +6,20 @@ and event types are exported by [src/api.ts](../src/api.ts) and defined in
 
 ## 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.
+Static maps accept the same grouped presentation vocabulary as interactive maps:
+
+```ts
+const presentation = {
+  layers: { landmarks: true, bartStations: true },
+  appearance: { theme: 'districts' as const, colors: { water: '#e7f0f3' } },
+};
+const { svg } = renderMap(staticMapData, presentation);
+const map = createMap(fullMapData, presentation);
+```
+
+Static `layers` supports every interactive layer switch except `neighborhoodLabels`. Static `appearance` supports `theme`, `colors`, and `districtStyle`; browser typography, area interaction styles, and screen-space marker sizing remain interactive settings. Unknown grouped keys are rejected. Supplied grouped keys override flat compatibility keys; omitted or `undefined` grouped keys preserve the flat value or renderer default. The two renderers retain their existing defaults. Marker arrays accept readonly inputs.
+
+Flat compatibility 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.
 
@@ -31,3 +44,42 @@ For the guide preset with the same controller API, use `createGuideController(op
 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.
+
+## Live configuration and inspection
+
+`map.configure({ appearance, mode, source, year, labels, layers, features, controls })` updates an existing map. Appearance updates preserve the camera, selections, retained marker nodes, and keyboard focus. Mode/source changes through `configure` preserve the camera; existing `setMode` and `setSource` convenience methods retain their reset behavior. Switching neighborhood source clears the neighborhood selection. Changing district year retains a selected district when it exists in the new year. Unsupported datasets, invalid appearance values, and invalid district-style callback results fail during preparation before commit. A reentrant styling callback can supersede the pending patch.
+
+Appearance token objects (`colors`, `style`, `labelStyle`, `labelSize`, `areaStyle`) merge supplied keys; other appearance properties replace. Omitted keys retain their value, an explicit `undefined` property removes that override, and `appearance: undefined` resets the whole appearance group. Feature objects retain their existing replacement semantics. Mode/source/year/labels ignore `undefined`; reset them with an explicit value. Patch types explicitly permit these resets with TypeScript’s `exactOptionalPropertyTypes` enabled.
+
+```ts
+map.configure({
+  appearance: { colors: { water: '#142d45' }, labelStyle: { fontFamily: 'Georgia,serif' } },
+  layers: { bartStations: false },
+});
+map.configure({ appearance: undefined }); // restore construction defaults, not initial overrides
+
+const overrides = map.getConfiguration();
+const effective = map.getResolvedConfiguration();
+const available = map.getCapabilities();
+```
+
+`getConfiguration()` returns detached feature, layer, control, and appearance overrides; district style callbacks retain their function identity. `getResolvedConfiguration()` adds the current mode, source, year and master labels and resolves **layer switches** through mode defaults, available data, and the master label switch. Appearance/control fields remain overrides. It does not claim that every label is visible: zoom and collision filtering still apply. `getCapabilities()` returns supplied `sources`, usable district `years`, and layer data availability for the current source/year, independent of visibility overrides. These reads throw after destruction.
+
+## Common selection event
+
+`selectionchange` adds a consistent envelope without changing existing event payloads:
+
+```ts
+map.on('selectionchange', (event) => {
+  // kind narrows current and previous to the corresponding selection type.
+  if (event.kind === 'marker') console.log(event.current?.id, event.previous?.id);
+});
+```
+
+`kind` is `marker`, `neighborhood`, or `district`. `current` and `previous` are detached selection snapshots or `null`. The event follows committed selection changes, including clearing and a changed district vintage; it does not represent every activation. Existing `markerchange`, `neighborhoodchange`, and `districtchange` events remain supported.
+
+## Coordinates and units
+
+GeoJSON and static projection inputs use `[longitude, latitude]` in WGS84; markers use `{ lng, lat }`. Static `project` returns SVG units. `projectToScreen(lng, lat)` returns pixels relative to the mounted canvas. Camera viewports and pan deltas use the fixed 800 × 800 projected map space, independent of canvas size. Marker radius uses screen pixels in browser maps and SVG units in static output.
+
+Explore presentation options in the [live map design playground](https://kahwee.github.io/sf-map-svg/playground.html). The page identifies its package version; released builds use compatible options for that installed version.

package/docs/api-audit.md

@@ -54,7 +54,7 @@ exceptions are not transactional validation errors and do not roll back an alrea
 committed change. Direct mutation of the returned DOM can invalidate invariants;
 use the public methods and `overlayElement` extension point.
 
-The generic static renderer retains its existing broader option surface; strict
+Static grouped layers and appearance reject unknown keys, while flat compatibility options retain their existing surface; strict
 interactive option-key validation is not a claim that all static options share the
 same schema. Host layout, delayed images, fonts, and application cards need their
 own CLS tests. The scale bar is an approximate local Mercator scale, not survey
@@ -76,3 +76,5 @@ public types change. Update this matrix when introducing a new interaction.
 - `pnpm test:stories:coverage` runs Chromium stories and reports browser coverage.
 - `pnpm demo`, `pnpm build-storybook`, `pnpm test:package`, and `pnpm test:visual` cover examples, rendered stories, packed consumer imports, and reviewed map screenshots.
 - The packed consumer asserts removed compatibility entry points are absent.
+
+Live appearance patches prepare values, district styles and source replacement before committing; token objects merge by key. Styling callbacks that issue a newer presentation update supersede the pending patch. Resolved layer reads distinguish visibility settings from data availability and from zoom/collision label filtering. The additive selection envelope preserves existing event contracts.

package/docs/developer-guide.md

@@ -88,13 +88,13 @@ SFAR realtor neighborhoods are the default when supplied. If only an alternative
 
 | Change | Call |
 | --- | --- |
-| Layers, controls, behaviors | `map.configure({ layers, controls, features })` |
+| Layers, controls, behaviors | `map.configure({ layers, controls, features, appearance, mode, source, year, labels })` |
 | 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 |
+| Palette, typography, control styling | `map.configure({ appearance })`; retains camera, selection and focus |
 
 `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.
 
@@ -105,7 +105,7 @@ 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.
+`getConfiguration()` returns a detached snapshot of these groups, including explicit layer overrides. It is not a full serialization of mode, source, year, camera, or selection. Appearance overrides are included. Use `getResolvedConfiguration()` for current mode/source/year/labels and effective layer switches, and `getCapabilities()` for supplied geography. Invalid configuration patches leave the current map unchanged.
 
 ## Markers, routes and camera coordinates
 
@@ -135,3 +135,5 @@ The package declarations are the exact type contract for your installed version.
 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).
+
+Appearance token objects merge by key; `undefined` removes an override and `appearance: undefined` resets the group. Static maps accept grouped `layers` and the shared `appearance` keys (`theme`, `colors`, `districtStyle`) too. See [the API contract](API.md#live-configuration-and-inspection) and [the design playground](https://kahwee.github.io/sf-map-svg/playground.html).