@kahwee/sf-map-svg 2.1.0 → 2.2.0

package/CHANGELOG.md

@@ -4,6 +4,14 @@ User-visible changes are recorded here. Unreleased entries describe changes on `
 
 ## Unreleased
 
+## 2.2.0 — 2026-09-27
+
+- Add “One spot, three San Franciscos” to Pages and Storybook, comparing the same location across district, neighborhood, and transit views.
+- Modernize the Storybook examples in TypeScript and gate map changes with reviewed desktop and 390 px visual snapshots on macOS and Linux.
+- Add first-class election choropleths: static and interactive `districtStyle`, live district year/style setters, district selection and activation events, keyboard interaction, and a reduced-motion-aware year crossfade.
+- Export `getLayerPaths` for canonical fitted layer geometry and `DistrictYear`, `DistrictRowData`, and `DistrictStyle` from the modern entrypoints.
+- Add an official-election Storybook example covering three boundary years, vote-share coloring, mobile layout, keyboard selection, year changes, and accessibility checks.
+
 ## 2.1.0 — 2026-09-27
 
 - Pages site: add motion and a dark theme. Cross-document View Transitions keep the header still and morph example titles into page titles; the home hero is an interactive dot map of the 2022 districts; entrances, count-ups, growing charts, and hover/focus micro-interactions respect reduced motion and print. The site adds no library.

package/README.md

@@ -70,6 +70,9 @@ function and disposal removes all its subscriptions. Operations after disposal t
 `renderMap(data, options)` from `/static` returns `{ svg, project, ... }` and needs only
 `StaticMapData` (for example, `guideMapData.map`). Static options retain their SVG-unit
 semantics; camera/motion/control options belong exclusively to the browser controller.
+`getLayerPaths(data, options)` returns the same fitted projection and canonical coast,
+district, neighborhood, highway, landmark, road, and station paths without making SVG markup.
+`DistrictYear`, `DistrictRowData`, and `DistrictStyle` are exported types from the root and `/static`.
 See [v2 migration and architecture](docs/migration-v2.md) for breaking changes,
 configuration resets, and bundle boundaries. Existing subpaths remain compatibility APIs.
 
@@ -179,6 +182,7 @@ Embed the returned SVG markup directly in a page; in Astro, use `<div set:html={
 | `neighborhoodLines` | `false` | Dashed SFAR realtor neighborhood outlines |
 | `theme` | `'districts'` | Use `'transit'` for pale blue water, ivory land, green parks, and blue BART symbols; custom `colors` still take precedence |
 | `districtFills` | `true` | Original Site’s eleven muted district colors |
+| `districtStyle` | — | Per-district callback returning optional `fill`, `stroke`, and `opacity` (0–1); applies to both static SVG and the interactive map |
 | `labels` | `true` | Master switch for visible map text; symbols and accessible titles remain |
 | `districtLabels` | `true` | District number badges |
 | `highways` | `false` | Original Site’s highway geometry |
@@ -197,6 +201,54 @@ For a plain outline map, set `districtFills: false`. Neighborhood areas are **Au
 
 `createSFMap(options)` returns `{ svg, project, viewBox }`. `project([longitude, latitude])` gives matching SVG coordinates for custom overlays. Named exports also include `districtYears`, `districtColors`, and `neighborhoodNames`.
 
+### Election district API
+
+Supply canonical district rows for each boundary year and return a style for each district:
+
+```ts
+import { createMap, getLayerPaths, renderMap, type StaticMapData } from '@kahwee/sf-map-svg';
+import { districtMaps } from '@kahwee/sf-map-svg/data/districts';
+import coast from '@kahwee/sf-map-svg/data/coast.json' with { type: 'json' };
+
+const districts = Object.fromEntries(
+  Object.entries(districtMaps).map(([year, collection]) => [year, collection.features.map(({ geometry, properties }) => ({
+    id: properties.district,
+    label: properties.label,
+    labelPoints: properties.labelPoints,
+    geometry,
+    extras: properties.displayExtras,
+  }))]),
+) as StaticMapData['districts'];
+const data: StaticMapData = { coast: coast.features[0].geometry as StaticMapData['coast'], districts };
+const shares = new Map([[1, 0.62], [2, 0.48]]); // Replace with your vote data.
+const districtStyle = (district: { id: number }) => ({
+  fill: (shares.get(district.id) ?? 0) >= 0.5 ? '#498c79' : '#cfdfd6',
+  stroke: '#49665f',
+});
+const { svg } = renderMap(data, { year: 2022, districtStyle });
+const paths = getLayerPaths(data, { year: 2022 }); // paths.districts[0].geometry / .extras / .path
+
+const map = createMap({ map: data, districts: districtMaps, neighborhoods: {} }, {
+  mode: 'districts', year: 2022, appearance: { districtStyle },
+});
+document.querySelector('#map')?.append(map.element);
+map.on('districtchange', ({ id, year }) => console.log(id, year));
+map.on('districtactivate', ({ id }) => console.log('activated', id));
+map.on('districthover', ({ id }) => console.log('hovered', id));
+map.setDistrictYear(2012, { animate: true }); // Crossfades; reduced motion disables the fade.
+map.selectDistrict(1, { fit: true });
+map.setDistrictStyle(districtStyle); // Recompute colors after your vote data changes.
+// On component disposal: map.destroy();
+```
+
+District paths are keyboard buttons: Tab enters the district layer, brackets move among districts,
+and Enter or Space selects and activates one. `getSelectedDistrict()` returns a detached
+`{ id, year, district }` snapshot. `setDistrictYear()` preserves the camera and an existing
+district selection, changes labels and paths in place, and emits `districtyearchange`.
+It requires both district rows and label features for the requested year; unavailable years
+throw without changing the map. The `animate` option crossfades boundary sets rather than
+morphing polygons with different topology.
+
 Use `theme: 'transit'` for pale water, ivory land, green parks, and blue BART symbols. Custom `colors` override the preset. Park and station overlays represent current source geography, independently of the district year; stations outside San Francisco, including Daly City, are excluded.
 
 `keyRoads: true` adds the six curated orientation streets using DataSF centerlines. These are orientation features, not routing guidance. The lightweight guide shows primary corridors at city scale and Lombard after zooming.
@@ -424,13 +476,15 @@ pnpm test:package     # install and check the packed package
 
 Use `pnpm format` to apply Biome formatting and safe lint fixes. Install Chromium once with `pnpm exec playwright install chromium` before local Storybook tests. Run `pnpm storybook` for interactive component examples at http://127.0.0.1:6006. The coverage command writes `coverage/storybook/coverage-summary.json` and `lcov.info` for `src/` TypeScript only. CI runs package and Chromium Storybook checks on Node 26 and uploads the coverage report. See [CONTRIBUTING.md](CONTRIBUTING.md) for source structure and release instructions.
 
+In Storybook, start with **Start here / V2 interactive map** and **Start here / V2 static SVG** for copyable public imports and live layer controls. The phone stories use a 390 px Storybook viewport; the toolbar also offers a 1280 px desktop viewport. **Maps** shows the guide and transit components, **Data** compares source definitions, **Legacy** documents compatibility entrypoints, and **Checks** contains deeper controller regressions. Accessibility violations fail Storybook browser tests by default.
+
 ### Browser verification
 
 
 Run `pnpm demo` and serve the repository root. `examples/generated/index.html` covers static
 maps, `explorer.html` covers the full explorer, and `interactive.html` covers independently
 controlled neighborhood selection, 36 overlapping sample markers, and fit/save/restore hooks.
-Storybook **Maps / Reusable interactive map** includes both themes, selectable neighborhoods,
+Storybook **Legacy / Interactive map** includes both themes, selectable neighborhoods,
 independent layers, dense markers, and a 390px example.
 
 With that server running, the browser regression checks can be run through the installed CLI:
@@ -451,6 +505,8 @@ synthetic pointer tests do not establish physical-device compatibility.
 
 ## GitHub Pages
 
+The [one spot, three San Franciscos map](https://kahwee.github.io/sf-map-svg/spot.html) lets visitors pick a point and compare its SFAR, SF Find, and analysis neighborhood definitions, then inspect its supervisorial district on the 2002, 2012, and 2022 display maps. The same comparison appears in Storybook under **Data / One spot, three San Franciscos**. A source outline is drawn from that source's polygon; clicking the map runs point-in-polygon lookup against the canonical geographic collections. The page makes no address or legal-boundary claim.
+
 The [civic atlas](https://kahwee.github.io/sf-map-svg/) leads with certified June 2026 ballot measure results. Visitors can select a measure and district, switch Yes/No shading, compare the official 2002, 2012, and 2022 district maps, and play a schematic BART journey. The boundary animation morphs matched district outlines between dated SVGs. Intermediate shapes illustrate the change; each completed year uses its exact published geometry. Playback is user initiated, pauses when the page is hidden, and switches instantly when reduced motion is requested. The lightweight neighborhood guide loads on demand. The full [ballot measures explorer](https://kahwee.github.io/sf-map-svg/measures.html) spans all three district map years with four separately sourced election snapshots.
 
 The [candidate vote explorer](https://kahwee.github.io/sf-map-svg/candidates.html) maps

package/dist/src/configuration.js

@@ -5,6 +5,7 @@ const appearanceKeys = [
     'colors',
     'labelStyle',
     'areaStyle',
+    'districtStyle',
     'labelSize',
     'style',
     'markerRadius',

package/dist/src/controller-types.d.ts

@@ -1,6 +1,6 @@
 import type { Geometry, NeighborhoodSource } from '../data/types.js';
-import type { CameraOptions, InteractiveLayers, MapFeatures, MapMarker, MapOverlay, MapPadding, MapViewport, NeighborhoodExplorerOptions, NeighborhoodSelection } from './types.js';
-export type MapAppearance = Pick<NeighborhoodExplorerOptions, 'theme' | 'colors' | 'labelStyle' | 'areaStyle' | 'labelSize' | 'style' | 'markerRadius' | 'markerHitSize' | 'markerColor' | 'selectedMarkerColor'>;
+import type { CameraOptions, DistrictSelection, DistrictStyle, DistrictYear, InteractiveLayers, MapFeatures, MapMarker, MapOverlay, MapPadding, MapViewport, NeighborhoodExplorerOptions, NeighborhoodSelection } from './types.js';
+export type MapAppearance = Pick<NeighborhoodExplorerOptions, 'theme' | 'colors' | 'labelStyle' | 'areaStyle' | 'districtStyle' | 'labelSize' | 'style' | 'markerRadius' | 'markerHitSize' | 'markerColor' | 'selectedMarkerColor'>;
 export type MapControls = NonNullable<NeighborhoodExplorerOptions['controls']>;
 /** Omitted groups/keys retain their values; undefined groups reset all keys in that group. */
 export interface MapConfiguration {
@@ -19,6 +19,21 @@ export interface MapConfigurationSnapshot {
     controls: MapControls;
 }
 export interface MapEvents {
+    districtchange: DistrictSelection | {
+        id: null;
+        year: DistrictYear;
+        district: null;
+    };
+    districthover: DistrictSelection | {
+        id: null;
+        year: DistrictYear;
+        district: null;
+    };
+    districtactivate: DistrictSelection;
+    districtyearchange: {
+        year: DistrictYear;
+        previousYear: DistrictYear;
+    };
     markerchange: {
         id: string | null;
         marker: MapMarker | null;
@@ -70,6 +85,12 @@ export interface MapController {
         fit?: boolean;
     }): boolean;
     getSelectedNeighborhood(): NeighborhoodSelection | null;
+    selectDistrict(id: number | null, options?: CameraOptions & {
+        fit?: boolean;
+    }): boolean;
+    getSelectedDistrict(): DistrictSelection | null;
+    setDistrictYear(year: DistrictYear, options?: CameraOptions): void;
+    setDistrictStyle(style: ((district: DistrictSelection['district']) => DistrictStyle) | undefined): void;
     setSource(source: NeighborhoodSource): void;
     setMode(mode: NonNullable<MapOptions['mode']>): void;
     setLabels(visible: boolean): void;

package/dist/src/explorer-core.js

@@ -3,7 +3,7 @@ import { clusterPoints } from './clusters.js';
 import { fitBounds, interiorAnchor, layoutLabels, projectedBounds } from './explorer-layout.js';
 import { controlKeys, layerKeys, normalizeFeatures, validateSwitchPatch } from './features.js';
 import { geometryPath } from './geometry.js';
-import { createSFMapWithData, districtColors } from './map-core.js';
+import { createSFMapWithData, districtColors, getLayerPathsWithData } from './map-core.js';
 import { attachNavigation } from './navigation.js';
 import { validateExplorerOptions, validateMarkers, validateOverlays } from './validation.js';
 import { fitViewport, validateViewport } from './viewport.js';
@@ -38,7 +38,7 @@ let explorerCount = 0;
 /** Create an offline, browser-only neighborhood explorer. Call destroy() before disposal. */
 export function createNeighborhoodExplorerCore(options = {}, data) {
     validateExplorerOptions(options);
-    let { source = 'realtor', mode = 'neighborhoods', labels = true, neighborhood, year = 2022, theme = 'transit', colors = {}, labelStyle = {}, areaStyle = {}, motion = false, markerEntrance = false, selectedMarkerRing, clustering = false, legend: legendOptions = {}, attribution: attributionMode = 'full', northArrow = false, scaleBar = false, interface: chrome = 'explorer', layers = {}, selectableNeighborhoods = true, labelSize = {}, fitPadding = 24, markers: initialMarkers = [], markerRadius = 6, markerHitSize = 44, markerColor = colors.marker ?? '#245b61', selectedMarkerColor = colors.selected ?? '#f04f32', onMarkerActivate, overlays: initialOverlays = [], onOverlayActivate, style: styleOptions = {}, strings = {}, controls = {}, } = options;
+    let { source = 'realtor', mode = 'neighborhoods', labels = true, neighborhood, year = 2022, theme = 'transit', colors = {}, labelStyle = {}, areaStyle = {}, districtStyle: initialDistrictStyle, motion = false, markerEntrance = false, selectedMarkerRing, clustering = false, legend: legendOptions = {}, attribution: attributionMode = 'full', northArrow = false, scaleBar = false, interface: chrome = 'explorer', layers = {}, selectableNeighborhoods = true, labelSize = {}, fitPadding = 24, markers: initialMarkers = [], markerRadius = 6, markerHitSize = 44, markerColor = colors.marker ?? '#245b61', selectedMarkerColor = colors.selected ?? '#f04f32', onMarkerActivate, overlays: initialOverlays = [], onOverlayActivate, style: styleOptions = {}, strings = {}, controls = {}, } = options;
     if (!['neighborhoods', 'districts', 'basemap'].includes(mode))
         throw new RangeError(`Unknown map mode: ${mode}`);
     if (chrome !== 'explorer' && chrome !== 'map')
@@ -314,6 +314,7 @@ export function createNeighborhoodExplorerCore(options = {}, data) {
         districtLabels: false,
         districtLines: true,
         districtFills: true,
+        districtStyle: initialDistrictStyle,
         highways: true,
         keyRoads: true,
         roadLabels: false,
@@ -365,7 +366,7 @@ export function createNeighborhoodExplorerCore(options = {}, data) {
         if (color)
             path.setAttribute('fill', color);
     }
-    const districtItems = (data.districts?.[year]?.features ?? []).flatMap((feature) => feature.properties.labelPoints.map((point) => ({
+    let districtItems = (data.districts?.[year]?.features ?? []).flatMap((feature) => feature.properties.labelPoints.map((point) => ({
         point: map.project(point),
         name: String(feature.properties.district),
         kind: 'district',
@@ -382,6 +383,171 @@ export function createNeighborhoodExplorerCore(options = {}, data) {
     geography.append(areas, stations, labelLayer, overlayLayer, markerLayer);
     let view = [0, 0, 800];
     let selected;
+    let selectedDistrict = null;
+    let hoveredDistrict = null;
+    let districtStyle = initialDistrictStyle;
+    let districtTransition;
+    root.dataset.year = String(year);
+    function districtRow(id) {
+        return data.map.districts?.[year]?.find((district) => district.id === id);
+    }
+    function districtSelection(id) {
+        const district = id === null ? undefined : districtRow(id);
+        return district
+            ? { id: district.id, year, district: structuredClone(district) }
+            : { id: null, year, district: null };
+    }
+    function getSelectedDistrict() {
+        return selectedDistrict === null
+            ? null
+            : districtSelection(selectedDistrict);
+    }
+    function updateDistrictAppearance() {
+        const rows = data.map.districts?.[year] ?? [];
+        for (const row of rows) {
+            const styled = districtStyle?.(row);
+            const active = selectedDistrict === row.id;
+            const hovered = hoveredDistrict === row.id;
+            const fill = svg.querySelector(`[data-layer="district-fills"] [data-district="${row.id}"]`);
+            const line = svg.querySelector(`[data-layer="district-lines"] [data-district="${row.id}"]`);
+            if (fill) {
+                fill.setAttribute('fill', styled?.fill ??
+                    (theme === 'transit' ? (colors.land ?? '#fcfcf8') : districtColors[row.id - 1]));
+                if (styled?.opacity === undefined)
+                    fill.removeAttribute('fill-opacity');
+                else
+                    fill.setAttribute('fill-opacity', String(styled.opacity));
+                fill.setAttribute('role', 'button');
+                fill.setAttribute('aria-label', `District ${row.id}, ${year}`);
+                fill.setAttribute('aria-pressed', String(active));
+                fill.setAttribute('tabindex', row.id === 1 ? '0' : '-1');
+                fill.style.cursor = 'pointer';
+            }
+            if (line) {
+                line.setAttribute('stroke', active
+                    ? (colors.selected ?? '#f04f32')
+                    : hovered
+                        ? '#163e56'
+                        : (styled?.stroke ?? colors.district ?? '#a7b8c0'));
+                line.setAttribute('stroke-width', active ? '3' : hovered ? '2.2' : '1.1');
+                const lineInteractive = !enabled('districtFills') && enabled('districtLines');
+                line.style.pointerEvents = lineInteractive ? 'stroke' : 'none';
+                if (lineInteractive) {
+                    line.setAttribute('role', 'button');
+                    line.setAttribute('aria-label', `District ${row.id}, ${year}`);
+                    line.setAttribute('aria-pressed', String(active));
+                    line.setAttribute('tabindex', row.id === 1 ? '0' : '-1');
+                    line.style.cursor = 'pointer';
+                }
+                else {
+                    line.removeAttribute('role');
+                    line.removeAttribute('aria-label');
+                    line.removeAttribute('aria-pressed');
+                    line.removeAttribute('tabindex');
+                }
+                if (styled?.opacity === undefined)
+                    line.removeAttribute('stroke-opacity');
+                else
+                    line.setAttribute('stroke-opacity', String(styled.opacity));
+            }
+        }
+    }
+    function selectDistrict(id, options = {}) {
+        if (destroyed)
+            return false;
+        validateCameraOptions(options);
+        if (id !== null && (!Number.isInteger(id) || !districtRow(id)))
+            return false;
+        const changed = selectedDistrict !== id;
+        selectedDistrict = id;
+        if (id === null)
+            delete root.dataset.selectedDistrict;
+        else
+            root.dataset.selectedDistrict = String(id);
+        updateDistrictAppearance();
+        const selectedRow = id === null ? undefined : districtRow(id);
+        if (selectedRow && options.fit)
+            fitGeometry(selectedRow.geometry, undefined, options);
+        status.textContent =
+            id === null ? 'District selection cleared.' : `District ${id} selected, ${year} boundaries.`;
+        if (changed)
+            root.dispatchEvent(new CustomEvent('districtchange', { bubbles: true, detail: districtSelection(id) }));
+        return true;
+    }
+    function setDistrictStyle(style) {
+        if (destroyed)
+            return;
+        if (style !== undefined && typeof style !== 'function')
+            throw new TypeError('districtStyle must be a function.');
+        createSFMapWithData({ year, districtStyle: style, districtLabels: false }, data.map);
+        districtStyle = style;
+        updateDistrictAppearance();
+    }
+    function setDistrictYear(next, options = {}) {
+        if (destroyed)
+            return;
+        validateCameraOptions(options);
+        if (![2002, 2012, 2022].includes(next))
+            throw new RangeError('District year must be 2002, 2012, or 2022.');
+        if (!data.map.districts?.[next] || !data.districts?.[next])
+            throw new RangeError(`No ${next} district dataset was supplied.`);
+        if (next === year)
+            return;
+        const geometry = getLayerPathsWithData({ year: next }, data.map);
+        createSFMapWithData({ year: next, districtStyle, districtLabels: false }, data.map);
+        const previousYear = year;
+        districtTransition?.cancel();
+        for (const layer of districtLayers) {
+            const old = options.animate && !reducedMotion.matches ? layer.cloneNode(true) : null;
+            if (old) {
+                old.setAttribute('aria-hidden', 'true');
+                old.style.pointerEvents = 'none';
+                for (const path of old.querySelectorAll('[data-district]')) {
+                    path.removeAttribute('tabindex');
+                    path.removeAttribute('role');
+                    path.removeAttribute('aria-label');
+                    path.removeAttribute('aria-pressed');
+                }
+                layer.after(old);
+                districtTransition = old.animate([{ opacity: 1 }, { opacity: 0 }], {
+                    duration: options.duration ?? 280,
+                    easing: 'ease-out',
+                });
+                districtTransition.finished.then(() => old.remove()).catch(() => old.remove());
+            }
+            layer.replaceChildren(...geometry.districts.map((district) => svgElement('path', {
+                'data-district': district.id,
+                d: district.path,
+                ...(layer.dataset.layer === 'district-fills'
+                    ? { 'fill-rule': 'evenodd' }
+                    : { fill: 'none', 'stroke-width': 1.1 }),
+            })));
+        }
+        year = next;
+        hoveredDistrict = null;
+        root.dataset.year = String(year);
+        svg.dataset.year = String(year);
+        districtItems = (data.districts[next]?.features ?? []).flatMap((feature) => feature.properties.labelPoints.map((point) => ({
+            point: map.project(point),
+            name: String(feature.properties.district),
+            kind: 'district',
+        })));
+        if (selectedDistrict !== null && !districtRow(selectedDistrict))
+            selectedDistrict = null;
+        if (selectedDistrict === null)
+            delete root.dataset.selectedDistrict;
+        updateDistrictAppearance();
+        updateComposition();
+        scheduleLabels();
+        status.textContent = `${year} supervisorial districts.`;
+        root.dispatchEvent(new CustomEvent('districtyearchange', { bubbles: true, detail: { year, previousYear } }));
+        if (selectedDistrict !== null)
+            root.dispatchEvent(new CustomEvent('districtchange', {
+                bubbles: true,
+                detail: districtSelection(selectedDistrict),
+            }));
+    }
+    updateDistrictAppearance();
     let items = [];
     let destroyed = false;
     let initialized = false;
@@ -1128,6 +1294,7 @@ export function createNeighborhoodExplorerCore(options = {}, data) {
             const key = layer.dataset.layer === 'district-fills' ? 'districtFills' : 'districtLines';
             layer.style.display = enabled(key) ? '' : 'none';
         }
+        updateDistrictAppearance();
         const districtsVisible = enabled('districtFills') || enabled('districtLines') || (labels && enabled('districtLabels'));
         const descriptions = ['San Francisco map.'];
         if (districtsVisible)
@@ -1151,7 +1318,7 @@ export function createNeighborhoodExplorerCore(options = {}, data) {
         const title = svg.querySelector('title');
         if (title)
             title.textContent = 'San Francisco map';
-        svg.setAttribute('aria-label', `${description} Arrow keys pan; plus and minus zoom; Home resets. Neighborhoods: brackets move focus; Enter selects. The neighborhood and marker menus include every supplied item.`);
+        svg.setAttribute('aria-label', `${description} Arrow keys pan; plus and minus zoom; Home resets. Districts and neighborhoods: brackets move focus; Enter selects. The neighborhood and marker menus include every supplied item.`);
         attribution.textContent = description;
         scheduleLabels();
     }
@@ -1409,6 +1576,31 @@ export function createNeighborhoodExplorerCore(options = {}, data) {
     listen(markerSelect, 'change', () => selectMarker(markerSelect.value || null));
     listen(svg, 'keydown', (event) => {
         const target = event.target instanceof SVGElement ? event.target : null;
+        const districtId = Number(target?.dataset.district);
+        if (target?.closest('[data-layer="district-fills"], [data-layer="district-lines"]') &&
+            districtRow(districtId)) {
+            if (event.key === 'Enter' || event.key === ' ') {
+                event.preventDefault();
+                selectDistrict(districtId);
+                root.dispatchEvent(new CustomEvent('districtactivate', {
+                    bubbles: true,
+                    detail: districtSelection(districtId),
+                }));
+                target.focus();
+            }
+            else if (event.key === '[' || event.key === ']') {
+                event.preventDefault();
+                const rows = data.map.districts?.[year] ?? [];
+                const index = rows.findIndex((row) => row.id === districtId);
+                const next = rows[(index + (event.key === ']' ? 1 : rows.length - 1)) % rows.length];
+                const activeLayer = enabled('districtFills') ? 'district-fills' : 'district-lines';
+                const nextNode = svg.querySelector(`[data-layer="${activeLayer}"] [data-district="${next.id}"]`);
+                target.setAttribute('tabindex', '-1');
+                nextNode?.setAttribute('tabindex', '0');
+                nextNode?.focus();
+            }
+            return;
+        }
         const id = target?.dataset.neighborhoodId;
         if (!id || !selectableNeighborhoods)
             return;
@@ -1441,12 +1633,42 @@ export function createNeighborhoodExplorerCore(options = {}, data) {
         }
     });
     listen(svg, 'click', (event) => {
+        const district = event.target instanceof Element
+            ? event.target.closest('[data-layer="district-fills"] [data-district], [data-layer="district-lines"] [data-district]')
+            : null;
+        if (district?.dataset.district) {
+            const id = Number(district.dataset.district);
+            selectDistrict(id);
+            root.dispatchEvent(new CustomEvent('districtactivate', { bubbles: true, detail: districtSelection(id) }));
+            return;
+        }
         const node = event.target instanceof Element
             ? event.target.closest('[data-neighborhood-id]')
             : null;
         if (selectableNeighborhoods && node?.dataset.neighborhoodId)
             selectNeighborhood(node.dataset.neighborhoodId);
     });
+    listen(svg, 'pointerover', (event) => {
+        const district = event.target instanceof Element
+            ? event.target.closest('[data-layer="district-fills"] [data-district], [data-layer="district-lines"] [data-district]')
+            : null;
+        const id = district?.dataset.district ? Number(district.dataset.district) : null;
+        if (id === hoveredDistrict)
+            return;
+        hoveredDistrict = id;
+        updateDistrictAppearance();
+        root.dispatchEvent(new CustomEvent('districthover', { bubbles: true, detail: districtSelection(id) }));
+    });
+    listen(svg, 'pointerout', (event) => {
+        if (event.relatedTarget instanceof Element &&
+            event.relatedTarget.closest('[data-layer="district-fills"] [data-district], [data-layer="district-lines"] [data-district]'))
+            return;
+        if (hoveredDistrict === null)
+            return;
+        hoveredDistrict = null;
+        updateDistrictAppearance();
+        root.dispatchEvent(new CustomEvent('districthover', { bubbles: true, detail: districtSelection(null) }));
+    });
     listen(svg, 'pointerdown', stopAnimation);
     let observer;
     const onResize = () => {
@@ -1457,6 +1679,10 @@ export function createNeighborhoodExplorerCore(options = {}, data) {
     const explorer = Object.assign(root, {
         selectNeighborhood,
         getSelection,
+        selectDistrict,
+        getSelectedDistrict,
+        setDistrictYear,
+        setDistrictStyle,
         getViewport,
         setViewport: moveView,
         stopAnimation,

package/dist/src/layers.d.ts

@@ -15,6 +15,8 @@ interface DistrictPath {
     id: number;
     path: string;
     color: string;
+    stroke?: string;
+    opacity?: number;
 }
 export declare function districtFills(districts: readonly DistrictPath[], { idPrefix }: LayerContext): string;
 export declare function districtLines(districts: readonly DistrictPath[], { idPrefix, colors }: LayerContext): string;

package/dist/src/layers.js

@@ -1,9 +1,9 @@
 import { escapeXml, number, overlayLabel, stroke } from './svg.js';
 export function districtFills(districts, { idPrefix }) {
-    return `<g data-layer="district-fills" clip-path="url(#${idPrefix}-coast)">${districts.map((d) => `<path data-district="${d.id}" d="${d.path}" fill="${escapeXml(d.color)}" fill-rule="evenodd"/>`).join('')}</g>`;
+    return `<g data-layer="district-fills" clip-path="url(#${idPrefix}-coast)">${districts.map((d) => `<path data-district="${d.id}" d="${d.path}" fill="${escapeXml(d.color)}"${d.opacity === undefined ? '' : ` fill-opacity="${d.opacity}"`} fill-rule="evenodd"/>`).join('')}</g>`;
 }
 export function districtLines(districts, { idPrefix, colors }) {
-    return `<g data-layer="district-lines" clip-path="url(#${idPrefix}-coast)">${districts.map((d) => `<path data-district="${d.id}" d="${d.path}" ${stroke(colors.district, 1.1)}/>`).join('')}</g>`;
+    return `<g data-layer="district-lines" clip-path="url(#${idPrefix}-coast)">${districts.map((d) => `<path data-district="${d.id}" d="${d.path}" ${stroke(d.stroke ?? colors.district, 1.1)}${d.opacity === undefined ? '' : ` stroke-opacity="${d.opacity}"`}/>`).join('')}</g>`;
 }
 export function landmarks(items, { idPrefix, path, colors }) {
     return `<g data-layer="landmarks" clip-path="url(#${idPrefix}-coast)">${items.map((item) => `<path data-landmark="${escapeXml(item.id)}" d="${path(item.geometry)}" fill="${escapeXml(colors.park)}" fill-rule="evenodd"><title>${escapeXml(item.name)}</title></path>`).join('')}</g>`;

package/dist/src/map-core.d.ts

@@ -47,6 +47,39 @@ export interface BartStationData {
 }
 export declare const districtYears: readonly DistrictYear[];
 export declare const districtColors: readonly string[];
+/** Canonical geometry in the same fitted coordinate space used by renderMap. */
+export declare function getLayerPathsWithData(options: SFMapOptions, data: SFMapData, complete?: boolean): {
+    year: DistrictYear;
+    viewBox: [number, number, number, number];
+    project: (coordinates: Position) => [number, number];
+    coast: string;
+    districts: {
+        id: number;
+        geometry: string;
+        extras: string;
+        path: string;
+    }[];
+    neighborhoods: {
+        name: string;
+        path: string;
+    }[];
+    highways: {
+        route: string;
+        path: string;
+    }[];
+    landmarks: {
+        id: string;
+        path: string;
+    }[];
+    keyRoads: {
+        id: string;
+        path: string;
+    }[];
+    bartStations: {
+        id: string;
+        point: [number, number];
+    }[];
+};
 /** Make an offline SVG and the matching longitude/latitude projection. */
 export declare function createSFMapWithData(options: SFMapOptions, data: SFMapData): {
     svg: string;

package/dist/src/map-core.js

@@ -16,6 +16,66 @@ export const districtColors = Object.freeze([
     '#cbdcd1',
     '#dfddc9',
 ]);
+/** Canonical geometry in the same fitted coordinate space used by renderMap. */
+export function getLayerPathsWithData(options, data, complete = true) {
+    const { width = 800, height = 800, padding = 28, year = 2022 } = options;
+    if (![width, height, padding].every(Number.isFinite) ||
+        width <= 0 ||
+        height <= 0 ||
+        padding < 0 ||
+        padding * 2 >= Math.min(width, height))
+        throw new RangeError('Use positive dimensions and padding smaller than half the map.');
+    if (!districtYears.includes(year))
+        throw new RangeError('District year must be 2002, 2012, or 2022.');
+    const coastPoints = positions(data.coast).map(rawProject);
+    const [minX, minY, maxX, maxY] = coastPoints.reduce((b, [x, y]) => [Math.min(b[0], x), Math.min(b[1], y), Math.max(b[2], x), Math.max(b[3], y)], [Infinity, Infinity, -Infinity, -Infinity]);
+    const scale = Math.min((width - padding * 2) / (maxX - minX), (height - padding * 2) / (maxY - minY));
+    const project = (coordinates) => {
+        const [x, y] = rawProject(coordinates);
+        const point = [
+            (x - (minX + maxX) / 2) * scale + width / 2,
+            (y - (minY + maxY) / 2) * scale + height / 2,
+        ];
+        if (!point.every(Number.isFinite))
+            throw new RangeError('Projected coordinates must be finite; use smaller map dimensions.');
+        return point;
+    };
+    const path = (geometry) => geometryPath(geometry, project);
+    return {
+        year,
+        viewBox: [0, 0, width, height],
+        project,
+        coast: path(data.coast),
+        districts: (complete || options.districtFills !== false || options.districtLines !== false
+            ? (data.districts?.[year] ?? [])
+            : []).map((district) => ({
+            id: district.id,
+            geometry: path(district.geometry),
+            extras: path(district.extras),
+            path: path(district.geometry) + path(district.extras),
+        })),
+        neighborhoods: (complete ? (data.neighborhoods ?? []) : []).map((item) => ({
+            name: item.name,
+            path: path(item.geometry),
+        })),
+        highways: (complete ? (data.highways ?? []) : []).map((item) => ({
+            route: item.route,
+            path: path(item.geometry),
+        })),
+        landmarks: (complete ? (data.landmarks ?? []) : []).map((item) => ({
+            id: item.id,
+            path: path(item.geometry),
+        })),
+        keyRoads: (complete ? (data.keyRoads ?? []) : []).map((item) => ({
+            id: item.id,
+            path: path(item.geometry),
+        })),
+        bartStations: (complete ? (data.bartStations ?? []) : []).map((item) => ({
+            id: item.id,
+            point: project(item.coordinates),
+        })),
+    };
+}
 const defaults = {
     water: '#e7f0f3',
     land: '#f1f3ee',
@@ -46,49 +106,35 @@ const transitColors = {
 let sequence = 0;
 /** Make an offline SVG and the matching longitude/latitude projection. */
 export function createSFMapWithData(options, data) {
-    const { theme = 'districts', width = 800, height = 800, padding = 28, year = 2022, districtLines = true, neighborhoodLines = false, districtFills = true, districtLabels = true, labels = true, highways = false, keyRoads = false, landmarks = false, bartStations = false, markers = [], title = 'San Francisco map', idPrefix = `sf-map-${++sequence}`, } = options;
+    const { theme = 'districts', width = 800, height = 800, year = 2022, districtLines = true, neighborhoodLines = false, districtFills = true, districtLabels = true, labels = true, highways = false, keyRoads = false, landmarks = false, bartStations = false, markers = [], title = 'San Francisco map', idPrefix = `sf-map-${++sequence}`, } = options;
     validateMarkers(markers);
     validateOverlays(options.overlays ?? []);
     const roadLabels = options.roadLabels ?? keyRoads;
-    if (![width, height, padding].every(Number.isFinite) ||
-        width <= 0 ||
-        height <= 0 ||
-        padding < 0 ||
-        padding * 2 >= Math.min(width, height))
-        throw new RangeError('Use positive dimensions and padding smaller than half the map.');
-    if (!districtYears.includes(year))
-        throw new RangeError('District year must be 2002, 2012, or 2022.');
     if (!/^[A-Za-z][A-Za-z0-9_-]*$/.test(idPrefix))
         throw new TypeError('idPrefix must start with a letter and contain only letters, numbers, underscores, or hyphens.');
     if (theme !== 'districts' && theme !== 'transit')
         throw new TypeError('Theme must be districts or transit.');
     const colors = { ...defaults, ...(theme === 'transit' ? transitColors : {}), ...options.colors };
-    const coastPoints = positions(data.coast).map(rawProject);
-    const [minX, minY, maxX, maxY] = coastPoints.reduce((b, [x, y]) => [Math.min(b[0], x), Math.min(b[1], y), Math.max(b[2], x), Math.max(b[3], y)], [Infinity, Infinity, -Infinity, -Infinity]);
-    const scale = Math.min((width - padding * 2) / (maxX - minX), (height - padding * 2) / (maxY - minY));
-    const project = (coordinates) => {
-        const [x, y] = rawProject(coordinates);
-        const point = [
-            (x - (minX + maxX) / 2) * scale + width / 2,
-            (y - (minY + maxY) / 2) * scale + height / 2,
-        ];
-        if (!point.every(Number.isFinite))
-            throw new RangeError('Projected coordinates must be finite; use smaller map dimensions.');
-        return point;
-    };
+    const geometry = getLayerPathsWithData(options, data, false);
+    const { project } = geometry;
     const path = (geometry) => geometryPath(geometry, project);
-    const coastPath = path(data.coast);
+    const coastPath = geometry.coast;
     const districts = data.districts?.[year] ?? [];
     const landmarkData = data.landmarks ?? [];
     const roadData = data.keyRoads ?? [];
     const stationData = data.bartStations ?? [];
     const context = { project, path, colors, idPrefix, theme, labels };
     const districtPaths = districtFills || districtLines
-        ? districts.map((d) => ({
-            id: d.id,
-            path: path(d.geometry) + path(d.extras),
-            color: theme === 'transit' ? colors.land : districtColors[d.id - 1],
-        }))
+        ? districts.map((d, index) => {
+            const style = validateDistrictStyle(options.districtStyle?.(d));
+            return {
+                id: d.id,
+                path: geometry.districts[index]?.path ?? '',
+                stroke: style.stroke,
+                opacity: style.opacity,
+                color: style.fill ?? (theme === 'transit' ? colors.land : districtColors[d.id - 1]),
+            };
+        })
         : [];
     const parts = [
         `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ${width} ${height}" width="${width}" height="${height}" role="img" aria-labelledby="${idPrefix}-title" data-sf-map="" data-year="${year}" style="max-width:100%;height:auto"><title id="${idPrefix}-title">${escapeXml(title)}</title><desc>San Francisco supervisorial district boundaries (${year}).${neighborhoodLines ? ' Dashed lines show SFAR realtor neighborhood areas, defined in August 2010.' : ''}${landmarks ? ' Highlighted areas show six parks and landmarks.' : ''}${keyRoads ? ' Thin gray lines show selected road corridors.' : ''}${bartStations ? ' Rings mark the eight San Francisco BART stations.' : ''} Geometry from DataSF${bartStations ? ' and BART' : ''}. See package SOURCES.md.</desc><defs><clipPath id="${idPrefix}-coast"><path d="${coastPath}" fill-rule="evenodd" clip-rule="evenodd"/></clipPath></defs><rect width="${width}" height="${height}" fill="${escapeXml(colors.water)}"/><g data-layer="geography"><path data-layer="coast" d="${coastPath}" fill="${escapeXml(colors.land)}" fill-rule="evenodd"/>`,
@@ -125,3 +171,19 @@ export function createSFMapWithData(options, data) {
         viewBox: [0, 0, width, height],
     };
 }
+function validateDistrictStyle(style) {
+    if (style === undefined)
+        return {};
+    if (!style || typeof style !== 'object' || Array.isArray(style))
+        throw new TypeError('districtStyle must return a style object.');
+    for (const key of Object.keys(style))
+        if (!['fill', 'stroke', 'opacity'].includes(key))
+            throw new TypeError(`Unknown district style: ${key}`);
+    for (const key of ['fill', 'stroke'])
+        if (style[key] !== undefined && typeof style[key] !== 'string')
+            throw new TypeError(`${key} must be a string.`);
+    if (style.opacity !== undefined &&
+        (!Number.isFinite(style.opacity) || style.opacity < 0 || style.opacity > 1))
+        throw new RangeError('District opacity must be between 0 and 1.');
+    return style;
+}

package/dist/src/map.d.ts

@@ -2,6 +2,6 @@ import type { MapController, MapOptions } from './controller-types.js';
 import { type InteractiveSFMapData } from './interactive-data.js';
 export type * from './controller-types.js';
 export type { InteractiveSFMapData as MapData } from './explorer-data.js';
-export type { CameraOptions, InteractiveLayers, MapFeatures, MapMarker, MapOverlay, MapPadding, MapViewport, NeighborhoodSelection, } from './types.js';
+export type { CameraOptions, DistrictSelection, DistrictStyle, DistrictYear, InteractiveLayers, MapFeatures, MapMarker, MapOverlay, MapPadding, MapViewport, NeighborhoodSelection, } from './types.js';
 /** No geography is imported. Supply a preset or your own immutable data. */
 export declare function createMap(data: InteractiveSFMapData, options?: MapOptions): MapController;

package/dist/src/map.js

@@ -63,6 +63,10 @@ export function createMap(data, options = {}) {
         on: use((type, listener) => {
             if (![
                 'markerchange',
+                'districtchange',
+                'districthover',
+                'districtactivate',
+                'districtyearchange',
                 'neighborhoodchange',
                 'overlayactivate',
                 'clusteractivate',
@@ -89,6 +93,10 @@ export function createMap(data, options = {}) {
         getSelectedMarker: use(element.getSelectedMarker),
         selectNeighborhood: use(element.selectNeighborhood),
         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),

package/dist/src/static.d.ts

@@ -1,10 +1,43 @@
 import { type SFMapData } from './map-core.js';
 import type { SFMapOptions } from './types.js';
-export type { SFMapData as StaticMapData } from './map-core.js';
-export type { SFMapOptions as StaticMapOptions } from './types.js';
+export type { DistrictRowData, SFMapData as StaticMapData } from './map-core.js';
+export type { DistrictStyle, DistrictYear, SFMapOptions as StaticMapOptions } 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;
     project: (coordinates: import("../data/types.js").Position) => [number, number];
     viewBox: [number, number, number, number];
 };
+/** Project canonical layer geometry without constructing an SVG string. */
+export declare function getLayerPaths(data: SFMapData, options?: SFMapOptions): {
+    year: import("./types.js").DistrictYear;
+    viewBox: [number, number, number, number];
+    project: (coordinates: import("../data/types.js").Position) => [number, number];
+    coast: string;
+    districts: {
+        id: number;
+        geometry: string;
+        extras: string;
+        path: string;
+    }[];
+    neighborhoods: {
+        name: string;
+        path: string;
+    }[];
+    highways: {
+        route: string;
+        path: string;
+    }[];
+    landmarks: {
+        id: string;
+        path: string;
+    }[];
+    keyRoads: {
+        id: string;
+        path: string;
+    }[];
+    bartStations: {
+        id: string;
+        point: [number, number];
+    }[];
+};

package/dist/src/static.js

@@ -1,5 +1,9 @@
-import { createSFMapWithData } from './map-core.js';
+import { createSFMapWithData, getLayerPathsWithData } from './map-core.js';
 /** Server-safe SVG rendering with explicit data; returns SVG plus projection helpers. */
 export function renderMap(data, options = {}) {
     return createSFMapWithData(options, data);
 }
+/** Project canonical layer geometry without constructing an SVG string. */
+export function getLayerPaths(data, options = {}) {
+    return getLayerPathsWithData(options, data);
+}

package/dist/src/types.d.ts

@@ -1,5 +1,15 @@
 import type { Geometry, NeighborhoodFeature, NeighborhoodSource } from '../data/types.js';
 export type DistrictYear = 2002 | 2012 | 2022;
+export interface DistrictSelection {
+    id: number;
+    year: DistrictYear;
+    district: import('./map-core.js').DistrictRowData;
+}
+export interface DistrictStyle {
+    fill?: string;
+    stroke?: string;
+    opacity?: number;
+}
 export interface MapMarker {
     id: string;
     lng: number;
@@ -31,6 +41,8 @@ export interface SFMapOptions {
     districtLines?: boolean;
     neighborhoodLines?: boolean;
     districtFills?: boolean;
+    /** Style each supervisorial district without taking over SVG rendering. */
+    districtStyle?: (district: import('./map-core.js').DistrictRowData) => DistrictStyle;
     districtLabels?: boolean;
     /** Hide all visible text labels while retaining geographic symbols and accessible titles. */
     labels?: boolean;
@@ -112,6 +124,7 @@ export interface NeighborhoodExplorerOptions extends MapFeatures {
         hoverFill?: string;
         hoverStroke?: string;
     };
+    districtStyle?: SFMapOptions['districtStyle'];
     legend?: {
         builtins?: boolean;
         hidden?: readonly ('bart' | 'park' | 'highway' | 'road')[];
@@ -176,6 +189,12 @@ export interface NeighborhoodExplorerElement extends HTMLElement {
         fit?: boolean;
     } & CameraOptions): boolean;
     getSelection(): NeighborhoodSelection | null;
+    selectDistrict(id: number | null, options?: {
+        fit?: boolean;
+    } & CameraOptions): boolean;
+    getSelectedDistrict(): DistrictSelection | null;
+    setDistrictYear(year: DistrictYear, options?: CameraOptions): void;
+    setDistrictStyle(style: SFMapOptions['districtStyle']): void;
     setSource(source: NeighborhoodSource): void;
     setMode(mode: ExplorerMode): void;
     setLabels(visible: boolean): void;

package/dist/src/validation.js

@@ -33,6 +33,7 @@ const optionKeys = [
     'colors',
     'labelStyle',
     'areaStyle',
+    'districtStyle',
     'motion',
     'markerEntrance',
     'selectedMarkerRing',
@@ -60,6 +61,8 @@ const optionKeys = [
 ];
 export function validateExplorerOptions(options) {
     assertOptions(options, 'map', optionKeys);
+    if (options.districtStyle !== undefined && typeof options.districtStyle !== 'function')
+        throw new TypeError('districtStyle must be a function.');
     for (const key of ['labels', 'selectableNeighborhoods'])
         if (options[key] !== undefined && typeof options[key] !== 'boolean')
             throw new TypeError(`${key} must be boolean.`);

package/docs/EXAMPLES.md

@@ -27,7 +27,14 @@ const svg = renderSFMap({
 await writeFile('districts.svg', svg);
 ```
 
-The root entry includes the built-in geography for convenience. See the [full option list](../README.md#static-options).
+The legacy entry includes built-in geography for convenience. The modern root and `/static` accept explicit geography. See the [full option list](../README.md#static-options).
+
+For an election choropleth, use `renderMap(data, { year, districtStyle })` or
+`createMap({ map: data, districts: districtMaps, neighborhoods: {} }, options)`.
+The controller exposes `setDistrictYear`, `setDistrictStyle`, `selectDistrict`, and typed
+district events; `getLayerPaths(data, { year })` returns fitted paths without SVG markup.
+See the [complete election recipe](../README.md#election-district-api) and the Storybook
+“Election choropleth” example.
 
 ## Lightweight interactive guide
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kahwee/sf-map-svg",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "Offline SVG maps of San Francisco with district boundaries, parks, landmarks, and BART stations.",
   "type": "module",
   "main": "./dist/src/api.js",
@@ -179,15 +179,17 @@
     "test": "pnpm build && node --test",
     "test:stories": "pnpm build && vitest run --project=storybook",
     "test:stories:coverage": "pnpm build && vitest run --project=storybook --coverage",
+    "test:visual": "playwright test --config=playwright.visual.config.mjs",
     "demo": "pnpm build && node examples/build.mjs",
     "format": "biome check --write .",
     "format:check": "biome format .",
-    "check": "pnpm peers check && pnpm lint && pnpm data:check && pnpm typecheck && pnpm test && pnpm test:bundle",
+    "check": "pnpm peers check && pnpm lint && pnpm data:check && pnpm typecheck && pnpm typecheck:stories && pnpm test && pnpm test:bundle",
     "storybook": "pnpm build && storybook dev -p 6006 --host 127.0.0.1 --no-open",
     "build-storybook": "pnpm build && storybook build",
     "data:catalog": "node scripts/build-data-catalog.mjs",
     "data:check": "node scripts/build-data-catalog.mjs --check",
     "typecheck": "pnpm build && tsc -p tsconfig.json",
+    "typecheck:stories": "tsc -p tsconfig.stories.json",
     "data:normalize-realtor": "node scripts/normalize-realtor.mjs",
     "data:guide": "node scripts/build-guide-data.mjs",
     "report:guide": "node scripts/report-guide-bundle.mjs",