@kahwee/sf-map-svg 2.0.0 → 2.2.0

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.0.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",
@@ -197,6 +199,7 @@
     "audit": "pnpm audit --audit-level high",
     "build:pages": "pnpm build && node scripts/build-pages.mjs",
     "test:bundle": "node scripts/report-guide-bundle.mjs --check",
+    "test:pages": "node scripts/check-pages.mjs",
     "release:notes": "node scripts/release-notes.mjs"
   }
 }