@kahwee/sf-map-svg 4.0.1 → 4.2.0

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,12 +54,25 @@ export interface SFMapOptions {
     roadLabels?: boolean;
     landmarks?: boolean;
     bartStations?: boolean;
-    markers?: MapMarker[];
+    markers?: readonly MapMarker[];
     overlays?: readonly MapOverlay[];
     title?: string;
     idPrefix?: string;
+    /**
+     * Opt-in, self-contained CSS choreography for static SVGs: land fades in, the coast and
+     * lines draw, districts grow, then labels and points appear. It plays when the SVG is
+     * inserted into a page or loaded as an image, and stays still under reduced motion.
+     * `duration` (default 2400 ms) scales the whole sequence; `delay` offsets it.
+     */
+    animation?: boolean | {
+        duration?: number;
+        delay?: number;
+    };
     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';
@@ -104,6 +120,21 @@ export interface MapFeatures {
     };
     northArrow?: boolean;
     scaleBar?: boolean;
+    /**
+     * Fade layers as `setLayers` and `setMode` switch them, crossfade neighborhood boundaries
+     * when `setSource` changes the definition, and crossfade district fills on
+     * `setDistrictStyle`. Reduced motion takes precedence.
+     */
+    layerTransitions?: boolean | {
+        duration?: number;
+    };
+    /**
+     * Morph district outlines from one map year to the next on `setDistrictYear`; pass
+     * `{ animate: false }` for an instant change. Reduced motion takes precedence.
+     */
+    districtMorph?: boolean | {
+        duration?: number;
+    };
 }
 export interface NeighborhoodExplorerOptions extends MapFeatures {
     mode?: ExplorerMode;
@@ -220,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/dist/src/validation.js

@@ -42,6 +42,8 @@ const optionKeys = [
     'attribution',
     'northArrow',
     'scaleBar',
+    'layerTransitions',
+    'districtMorph',
     'interface',
     'layers',
     'selectableNeighborhoods',

package/docs/API.md

@@ -0,0 +1,85 @@
+# Map options and lifecycle
+
+Start with the [static and interactive examples](../README.md). Exact option
+and event types are exported by [src/api.ts](../src/api.ts) and defined in
+[src/types.ts](../src/types.ts) and [src/controller-types.ts](../src/controller-types.ts).
+
+## Static maps
+
+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.
+
+`animation: true` (or `{ duration, delay }`) makes a static map draw itself with self-contained, scoped CSS: land fades in, the coast and lines draw, districts grow, then labels and points appear. It plays when the SVG is inserted into a page or loaded as an image, needs no JavaScript, and stays still under `prefers-reduced-motion`. Re-insert the markup to replay it. Default output is unchanged.
+
+## Interactive maps
+
+`createMap` defaults to `mode: 'basemap'` and `appearance.theme: 'transit'`. Set the mode explicitly for neighborhood or district exploration. District and neighborhood layer defaults follow the mode; other supplied layers default on. The [developer guide](developer-guide.md) compares static and interactive defaults and explains configuration resets, coordinates, and cleanup.
+
+Construction options include `mode` (`basemap`, `neighborhoods`, or `districts`), `source`, `neighborhood`, `year`, `labels`, `layers`, `controls`, `features`, `appearance`, `markers`, `overlays`, `legend`, `strings`, `attribution`, and `fitPadding`. Enable map touch gestures with the touch control or `map.setTouchNavigation(true)`. `features` holds motion, marker entrances, selected marker rings, clustering, north arrow, scale bar, layer transitions, and district morphs. `appearance` holds theme, color tokens, label and area styles, marker colors and sizes, and district styling. `layers` controls district fill/line/labels, neighborhood lines/labels, landmarks, BART, highways, key roads, and road labels. See the exported `MapOptions` type for exact values and the [Storybook examples](../stories/) for live controls.
+
+The controller also supports marker, neighborhood, and district selection; district year and style changes; source and mode changes; labels and touch navigation; screen projection; and typed `markerchange`, `neighborhoodchange`, `districtchange`, `districthover`, `districtactivate`, `districtyearchange`, `overlayactivate`, `clusteractivate`, `viewportchange`, and `mapresize` events. `destroy()` releases browser resources; operations after destruction throw.
+
+If a district callback destroys the map or selects a newer district, the interrupted activation stops without moving keyboard focus or sending a stale event.
+
+`setMarkers()` reconciles by stable marker `id`: retained markers keep their DOM nodes, focus, and in-progress entrance animations; only new IDs animate in. Identical ordered marker updates are a visual no-op. Camera state and `viewportchange` events remain synchronous, while animated camera steps and their dependent label/marker layout commit in the same browser frame.
+
+For a small guide, import `guideMapData` from `/guide/data` and pass it to `createMap`. The optional `/guide` entry also provides `createGuideMap`, `mountGuideMap`, and detailed-data loading for existing guide layouts. `/transit` provides the standalone schematic transit animation. See [examples](EXAMPLES.md) and [consumer integration](consumer-integration.md).
+
+For the guide preset with the same controller API, use `createGuideController(options)` from `/guide` (or `/guide/map`). It accepts grouped `MapOptions` and returns `MapController`; `mountGuideController(shell, options)` enhances a `createGuideShell()` container. Both use the lightweight guide geography. Existing `createGuideMap` and `mountGuideMap` calls retain their element-based API.
+
+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/consumer-integration.md

@@ -1,6 +1,6 @@
 # Consumer integration
 
-Use the version 3 root controller and explicit geographic data. The [migration guide](migration-v3.md) maps removed imports to supported calls.
+Use the root controller and import geographic data explicitly. The [migration guide](migration-v3.md) maps removed v2 imports to supported calls.
 
 For a compact browser guide:
 

package/docs/developer-guide.md

@@ -0,0 +1,139 @@
+# Developer guide
+
+Choose the renderer and geography separately. `renderMap` produces a string without a DOM; `createMap` produces a browser controller whose `.element` you mount. Neither root function imports geography for you.
+
+## Choose an entry point
+
+| Task | Renderer | Data |
+| --- | --- | --- |
+| Generate an SVG file or server-rendered image | `/static`: `renderMap` | `/data/static`: `staticMapData` |
+| Explore districts or several neighborhood definitions | `/map`: `createMap` | `/data/full`: `fullMapData` |
+| Embed a smaller neighborhood guide | `/guide/map`: `createGuideController` | Included lightweight guide geography |
+| Use the guide data with the general controller | `/map`: `createMap` | `/guide/data`: `guideMapData` |
+| Look up names without mounting a map | `/data/lookup` | Source-aware lookup helpers |
+
+Imports starting with `/` in this table are package suffixes, such as `@kahwee/sf-map-svg/static`. Node 24+ is required for server rendering. Browser examples need a DOM and a bundler that supports JSON modules. This is an ESM package.
+
+## Write a static SVG
+
+```ts
+import { writeFile } from 'node:fs/promises';
+import { renderMap } from '@kahwee/sf-map-svg/static';
+import { staticMapData } from '@kahwee/sf-map-svg/data/static';
+
+const { svg } = renderMap(staticMapData, {
+  year: 2022,
+  landmarks: true,
+  bartStations: true,
+  title: 'San Francisco districts, 2022',
+});
+await writeFile('san-francisco.svg', svg);
+```
+
+The SVG is self-contained. `project([lng, lat])` returns SVG coordinates; `viewBox` is `[0, 0, width, height]`. Use a different `idPrefix` for each inline SVG on the same page, or let the renderer generate one.
+
+## Mount and dispose an interactive map
+
+Provide a host such as `<div id="map"></div>` before running this code. Run browser construction after mounting, not during server rendering.
+
+```ts
+import { createMap } from '@kahwee/sf-map-svg/map';
+import { fullMapData } from '@kahwee/sf-map-svg/data/full';
+
+const host = document.querySelector<HTMLElement>('#map');
+if (!host) throw new Error('Missing #map host');
+
+const map = createMap(fullMapData, {
+  mode: 'neighborhoods',
+  source: 'realtor',
+  layers: { bartStations: true },
+  features: { motion: true },
+  appearance: { theme: 'districts' },
+});
+host.append(map.element);
+const unsubscribe = map.on('neighborhoodchange', ({ name }) => {
+  // name is null when the selection is cleared.
+  console.log(name);
+});
+
+// Call from your framework's unmount hook or when removing the view.
+function disposeMap() {
+  unsubscribe();
+  map.destroy();
+  map.element.remove();
+}
+```
+
+`destroy()` is idempotent, cancels owned work and subscriptions, and leaves host-owned DOM in place. Other controller operations after destruction throw. In React, construct inside an effect and return cleanup; in Vue or Svelte, use their mount/unmount hooks. Do not create a new map on every render: update the existing controller instead.
+
+## Know the defaults
+
+| Setting | `renderMap` | `createMap` |
+| --- | --- | --- |
+| Mode | No mode option | `basemap`; set `neighborhoods` or `districts` explicitly |
+| Theme | `districts` | `transit`; use `appearance.theme` |
+| District layers | On | Follow `districts` mode |
+| Neighborhood layers | Lines off | Follow `neighborhoods` mode |
+| Parks, highways, key roads | Off | On when supplied |
+| Road labels | Follow `keyRoads` | On when supplied, subject to zoom/collisions |
+| BART stations | Off | On when supplied |
+| 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)`.
+
+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.
+
+## Construction settings versus runtime updates
+
+| Change | Call |
+| --- | --- |
+| 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 | `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.
+
+```ts
+map.configure({ layers: { neighborhoodLabels: false } });
+map.configure({ layers: { neighborhoodLabels: undefined } }); // follow mode again
+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, 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
+
+Marker positions are `{ lng, lat }`. GeoJSON coordinates and the static projection use `[longitude, latitude]`, in WGS84. Camera viewports use `[x, y, size]` in the fixed 800 × 800 projected map space; they are not geographic bounds. `camera.pan` uses projected units. `projectToScreen(lng, lat)` returns pixels relative to the map canvas, plus visibility.
+
+Marker and overlay IDs must be unique. Keep marker IDs stable across updates so retained markers preserve DOM nodes, focus and entrance animations. Use `null` to clear a selection; selection methods return a boolean. Selection events can contain null values. `map.on()` returns an unsubscribe function.
+
+Reduced motion takes precedence over animations. Map touch gestures are opt-in; hiding a chooser requires an accessible alternative in your application.
+
+## Common integration errors
+
+| Symptom | Check |
+| --- | --- |
+| No neighborhoods or district fills | Set `mode` explicitly; the default is `basemap` |
+| An enabled layer does not appear | Supply its dataset; check master labels, zoom and collision filtering |
+| A theme or motion option throws | Put styling in `appearance` and behaviors in `features`; flat interactive options are rejected |
+| Source switch throws | Supply that source collection, or use `/data/full` |
+| A geographic coordinate produces a surprising camera view | Use `camera.fit(geometry)`; `camera.set` takes projected coordinates |
+| An event handler breaks after clearing selection | Handle null `id`, `name`, `marker`, or `district` |
+| Updates throw after navigating away | Dispose once and stop calling the destroyed controller |
+| An import from `/legacy`, `/custom-map`, `/explorer`, `/interactive` or `/interactive-data` fails | Those entries were removed in v3; follow the migration guide |
+
+## Versions and assistant-readable docs
+
+The package declarations are the exact type contract for your installed version. Check the changelog before using features shown on a local preview: its Unreleased section can include functionality absent from npm.
+
+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).

package/docs/guide-bundle-report.md

@@ -1,12 +1,12 @@
 # Guide bundle size report
 
-Generated 2026-09-28 by `pnpm report:guide` with Vite production minification and gzip compression. Each emitted JS chunk is compressed independently. The report measures the explicit-data v3 root and the optional `@kahwee/sf-map-svg/guide` preset.
+Generated 2026-10-01 by `pnpm report:guide` with Vite production minification and gzip compression. Each emitted JS chunk is compressed independently. The report measures the explicit-data root and the optional `@kahwee/sf-map-svg/guide` preset.
 
 | Entry | Initial JS, raw | Initial JS, gzip | Explicit detail JS, gzip |
 | --- | ---: | ---: | ---: |
-| v3 root (explicit data) | 89.7 KB | 26.3 KB | — |
-| v3 static renderer | 15.3 KB | 5.0 KB | — |
-| Guide preset | 479.5 KB | 114.9 KB | 473.7 KB |
+| Renderer root (explicit data) | 99.3 KB | 29.1 KB | — |
+| Static renderer | 18.2 KB | 5.8 KB | — |
+| Guide preset | 489.1 KB | 116.8 KB | 467.0 KB |
 
 **500 KB target:** met.