@kahwee/sf-map-svg 4.0.0 → 4.1.0

package/dist/src/types.d.ts

@@ -55,6 +55,16 @@ export interface SFMapOptions {
     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>>;
 }
 /** Serializable viewport in the interactive map's fixed 800 × 800 projected space. */
@@ -104,6 +114,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;
@@ -207,6 +232,7 @@ export interface NeighborhoodExplorerElement extends HTMLElement {
     fitGeometry(geometry: Geometry, padding?: number | MapPadding, options?: CameraOptions): void;
     /** Explicitly engage map touch gestures; false restores page gestures. */
     setTouchNavigation(enabled: boolean): void;
+    /** Reconcile stable IDs; retained markers preserve nodes, focus, and entrance animations. */
     setMarkers(markers: readonly MapMarker[]): void;
     setOverlays(overlays: readonly MapOverlay[]): void;
     selectMarker(id: string | null, options?: {

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,33 @@
+# 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 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.

package/docs/api-audit.md

@@ -24,6 +24,8 @@ unbounded geographic data can never fail.
 | 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. |
 | Label metrics and camera movement | Reuse screen-space text measurements and nodes across frames. Font loading invalidates measurements; hidden or removed candidates do not remain in the visible layer. |
+| Marker replacement | Reconcile stable IDs, preserve retained nodes/picker options and entrance animations, cancel removed entrances, and restore focus after reordering. Identical ordered values do not mutate the DOM or restart work. |
+| Camera and label scheduling | A shared frame advances the camera before rendering dependent labels, marker sizes, and clusters. State/events remain synchronous; cancellation preserves pending layout, and destruction cancels both kinds of work. |
 | 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. |
 

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,137 @@
+# 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 })` |
+| 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 |
+
+`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, selection, or construction appearance. 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).

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) | 87.4 KB | 25.5 KB | — |
-| v3 static renderer | 15.3 KB | 5.0 KB | — |
-| Guide preset | 477.1 KB | 114.1 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.