@kahwee/sf-map-svg 4.1.0 → 4.3.0

package/dist/src/static.js

@@ -1,9 +1,64 @@
+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);
+    const prepared = expandStaticOptions(options);
+    return createSFMapWithData(prepared, staticInput(data, prepared));
 }
 /** Project canonical layer geometry without constructing an SVG string. */
 export function getLayerPaths(data, options = {}) {
-    return getLayerPathsWithData(options, data);
+    const prepared = expandStaticOptions(options);
+    return getLayerPathsWithData(prepared, staticInput(data, prepared));
+}
+/** Borrow immutable geometry, deriving only the renderer's lightweight neighborhood rows. */
+function staticInput(data, options) {
+    if (options.source !== undefined && !['realtor', 'sf-find', 'analysis'].includes(options.source))
+        throw new RangeError('Unknown neighborhood source.');
+    if (!('map' in data)) {
+        if (options.source !== undefined)
+            throw new TypeError('source requires source-aware MapData; compact StaticMapData already chooses its geography.');
+        return data;
+    }
+    const source = options.source ??
+        ['realtor', 'sf-find', 'analysis'].find((candidate) => !!data.neighborhoods[candidate]);
+    if (source === undefined)
+        return data.map;
+    const collection = data.neighborhoods[source];
+    if (!collection)
+        throw new RangeError(`No ${source} neighborhood dataset was supplied.`);
+    return {
+        ...data.map,
+        neighborhoods: collection.features.map(({ geometry, properties }) => ({
+            name: properties.sourceName,
+            geometry,
+        })),
+    };
+}
+/** 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,11 +33,16 @@ 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;
     padding?: number;
     year?: DistrictYear;
+    /** Select a supplied neighborhood definition when rendering source-aware MapData. */
+    source?: NeighborhoodSource;
     districtLines?: boolean;
     neighborhoodLines?: boolean;
     districtFills?: boolean;
@@ -51,7 +56,7 @@ export interface SFMapOptions {
     roadLabels?: boolean;
     landmarks?: boolean;
     bartStations?: boolean;
-    markers?: MapMarker[];
+    markers?: readonly MapMarker[];
     overlays?: readonly MapOverlay[];
     title?: string;
     idPrefix?: string;
@@ -67,6 +72,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 +253,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, MapFeatureReference, MapOptions, MapSelectionChange, MapViewUpdateOptions, ResolvedMapConfiguration, } from './controller-types.js';

package/docs/API.md

@@ -6,7 +6,22 @@ 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 compact `StaticMapData` or the same source-aware `MapData` as interactive maps. With `MapData`, `source` selects a supplied neighborhood definition; SFAR realtor is preferred by default, followed by SF Find and analysis when available. A requested unavailable source throws before styling callbacks run. Compact `StaticMapData` already chooses its neighborhoods, so it rejects a `source` option. Both data shapes retain the static renderer defaults.
+
+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 +46,54 @@ 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; the `setMode(mode, { resetView: false })` and `setSource(source, { resetView: false })` convenience methods use the same atomic update path and preserve the camera. Omit the second argument to retain their existing reset behavior. Invalid view-update options fail before changing configuration. 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 the current mode, source, year and master labels, together with 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.
+
+## Source-aware feature selection
+
+`selectFeature(reference, options)` accepts one typed identity for each selectable kind:
+
+```ts
+map.selectFeature({ kind: 'marker', id: 'ferry' }, { fit: false });
+map.selectFeature({ kind: 'neighborhood', source: 'realtor', id: 'inner-mission' });
+map.selectFeature({ kind: 'district', year: 2022, id: 3 });
+```
+
+Neighborhood IDs are exact source-scoped feature IDs, rather than display names or aliases. District identity includes the boundary year. This operation returns `false` for a missing feature or a source/year other than the map's current supplied geography; it never silently switches definitions or years. Choose geography through `configure` first. An `id` of `null` clears that kind in the referenced current geography. Malformed references throw. Existing `selectMarker`, `selectNeighborhood`, and `selectDistrict` shortcuts 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

@@ -19,7 +19,8 @@ unbounded geographic data can never fail.
 | Clustering and selected/focused markers | Selected/focused pins remain individually reachable. Coincident alternatives remain available through the chooser. |
 | Marker entrance and reduced motion | Entrances are optional, independent of camera motion, and cancel on preference changes or disposal. Stable IDs avoid repeated entrances on filtering. |
 | Hiding touch control while gestures are enabled | Returns touch scrolling to the page. Other toolbar controls remain independent. |
-| Runtime patch omitted/false/undefined | Omitted retains; false disables; undefined resets to the default. Nested feature objects replace, rather than deep-merge. |
+| Convenience mode/source setters | Share the atomic configuration path. `{ resetView: false }` preserves the camera; omitted options retain the historic reset. Invalid options and unavailable geography leave state unchanged. |
+| Runtime patch omitted/false/undefined | Omitted retains; false disables boolean switches; undefined removes group/key overrides. Top-level mode/source/year/labels set to undefined retain their current values. Nested feature objects replace, rather than deep-merge. |
 | Compact shell and full attribution | Rejected before replacement. Use `createGuideController` for full attribution. Control overrides are honored and may deliberately alter layout. |
 | District style callbacks | Prepare and copy every style before committing. Hover/selection reuse the results; call `setDistrictStyle()` to refresh changed external data. Reentrant updates or destruction supersede pending work. |
 | Rapid district year changes | Both outgoing layers are tracked, inert, and removed on interruption, completion, reduced-motion changes, or destruction. Zero duration creates no transition copies. |
@@ -29,6 +30,8 @@ unbounded geographic data can never fail.
 | Guide controllers and compatibility factories | `createGuideController`/`mountGuideController` share grouped options and lifecycle with `createMap`. Existing element factories retain flat options and their return types. |
 | Layer hidden and bundle cost | Visibility never unloads imported geography. Use narrow entrypoints or data injection to save bytes. |
 
+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.
+
 ## Failure boundaries and regression evidence
 
 | Surface | Adversarial checks and behavior |
@@ -54,7 +57,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
@@ -70,9 +73,6 @@ Exercise enable/disable round trips and callbacks that synchronously request a
 second update. Add published-type and bundle regressions when the import graph or
 public types change. Update this matrix when introducing a new interaction.
 
-## Verification for version 3
+## Verification
 
-- `pnpm check` covers Node regressions, types, lint, catalog topology, and bundle budgets.
-- `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.
+Follow the [validation and release runbook](https://github.com/kahwee/sf-map-svg/blob/main/docs/maintenance.md#validation-by-change). The packed consumer also asserts that removed compatibility entry points remain absent.

package/docs/consumer-integration.md

@@ -1,23 +1,47 @@
-# Consumer integration
+# Embedding and progressive enhancement
 
-Use the root controller and import geographic data explicitly. The [migration guide](migration-v3.md) maps removed v2 imports to supported calls.
+For basic mounting, events and cleanup, start with the [developer guide](developer-guide.md). The root controller takes explicit geography; the guide entry offers a smaller preset with the same grouped `configure()`, `camera`, `on()`, and `destroy()` contract. See the [migration guide](migration-v3.md) for removed v2 imports.
 
-For a compact browser guide:
+## Render a guide before JavaScript loads
+
+On the server or in a build step, render a compact frame:
 
 ```ts
-import { createGuideController } from '@kahwee/sf-map-svg/guide';
+import { createGuideShell } from '@kahwee/sf-map-svg/guide/static';
+
+const markup = createGuideShell({ title: 'Explore San Francisco' });
+// Insert markup into your server-rendered HTML.
+```
+
+The shell uses an 800 × 800 projection with 28 units of padding, matching the interactive map. Use `createGuideSVG()` for custom dimensions. Rendering is offline, with zero runtime dependencies.
+
+## Enhance the existing frame
+
+In your browser entry, mount the controller into that shell:
 
-const map = createGuideController({
+```ts
+import { mountGuideController } from '@kahwee/sf-map-svg/guide';
+
+const shell = document.querySelector<HTMLElement>('.sf-guide-shell');
+if (!shell) throw new Error('Missing guide shell');
+const guide = mountGuideController(shell, {
+  attribution: 'compact',
   features: { motion: { duration: 400 }, markerEntrance: true },
   appearance: { theme: 'transit' },
 });
-document.querySelector('#map')?.append(map.element);
-// Dispose when the containing view unmounts.
-map.destroy();
+
+// Call before your application removes the containing view.
+function disposeGuide() {
+  guide.destroy();
+}
 ```
 
-The guide controller uses the same `configure()`, `camera`, `on()`, and `destroy()` contract as `createMap()`. Motion is opt-in and follows the user's reduced-motion preference. For explicit data composition, `createMap(guideMapData, guideOptions)` remains available using `/guide/data` and `/presets`.
+Compact attribution is required for an existing shell. Invalid configuration leaves its static frame intact. `destroy()` disposes listeners and animation work; your application owns removal of the containing view. Motion is opt-in and follows reduced-motion preferences.
+
+For a new browser-only guide, use `createGuideController()` and mount its `.element` as shown in the developer guide. Existing `createGuideMap()` and `mountGuideMap()` retain their augmented-element return types and flat options for compatibility.
+
+## Choose the data boundary
 
-To progressively enhance server-rendered `createGuideShell()` markup, use `mountGuideController(shell, options)` from `/guide`. It returns the controller and requires compact attribution. Invalid configuration leaves the static frame intact. Destroy the controller when unmounting. Existing `createGuideMap()` and `mountGuideMap()` return their original augmented elements and accept flat options for compatibility.
+`createMap(guideMapData, guideOptions)` remains available through `/guide/data` and `/presets`. For server rendering, pass `guideMapData.map` or `/data/static` to `renderMap()`. Use `/data/full` when interactive lookup collections are needed. The guide's detailed geography loads only on an explicit `loadGuideDetailedData()` call; enabling a layer does not download it.
 
-For server rendering, import `renderMap` from the root and pass `guideMapData.map`, `staticMapData` from `/data/static`, or another explicit `StaticMapData`. Import `/data/full` when interactive lookup collections are also required. All rendering stays offline and has zero runtime dependencies. The guide's detailed geography loads only when `loadGuideDetailedData()` is called.
+See the [exact API contract](API.md), [worked examples](EXAMPLES.md), and [bundle measurements](guide-bundle-report.md).

package/docs/developer-guide.md

@@ -80,7 +80,7 @@ function disposeMap() {
 | Visible labels | On | On, subject to zoom/collisions |
 | Motion features | Static animation off | Off; opt in via `features` |
 
-A layer switch does not download missing geography. `fullMapData` has `.map` for static rendering and separate lookup collections for interactive use. `staticMapData` is already a static data object. Use `renderMap(guideMapData.map, options)`, not `renderMap(guideMapData, options)`.
+A layer switch does not download missing geography. `fullMapData` has `.map` for static rendering and separate lookup collections for interactive use. `staticMapData` is already a static data object. Use `renderMap(guideMapData, options)` or `renderMap(fullMapData, { source: 'sf-find' })` to share source-aware geography with the browser controller. Passing `.map` remains supported as compact static geography; it already chooses its neighborhoods and does not accept a `source` option.
 
 SFAR realtor neighborhoods are the default when supplied. If only an alternative collection is supplied, the controller selects that available source. Choose `source` explicitly when comparing definitions. Sources retain separate identities; they are not interchangeable polygons.
 
@@ -88,13 +88,15 @@ SFAR realtor neighborhoods are the default when supplied. If only an alternative
 
 | Change | Call |
 | --- | --- |
-| Layers, controls, behaviors | `map.configure({ layers, controls, features })` |
+| Presentation, 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 |
+
+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).
 
 `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 +107,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 current mode/source/year/labels and a detached snapshot of the presentation groups, including explicit layer and appearance overrides. Camera and selection remain separate runtime state. 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. Convenience methods use the same atomic update path: pass `map.setMode(mode, { resetView: false })` or `map.setSource(source, { resetView: false })` to keep the camera. Their default still resets the view.
 
 ## Markers, routes and camera coordinates