@kahwee/sf-map-svg 2.1.0 → 3.0.0

package/dist/data/README.md

@@ -99,11 +99,12 @@ Lookup is exact after case/punctuation normalization, returns `undefined` for an
 ## Draw a neighborhood with the existing projection
 
 ```js
-import { createSFMap } from '@kahwee/sf-map-svg/legacy';
+import { renderMap } from '@kahwee/sf-map-svg';
+import { fullMapData } from '@kahwee/sf-map-svg/data/full';
 import { getNeighborhood } from '@kahwee/sf-map-svg/data';
 import { geometryPath } from '@kahwee/sf-map-svg/geometry';
 
-const map = createSFMap({ districtFills: false });
+const map = renderMap(fullMapData.map, { districtFills: false });
 const mission = getNeighborhood('Inner Mission');
 const pathData = geometryPath(mission.geometry, map.project);
 // Use pathData as an SVG <path d="..."> over map.svg.

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/full-data.d.ts

@@ -0,0 +1,3 @@
+import type { MapData } from './map.js';
+/** Complete, explicit geographic preset. Import this only when all datasets are needed. */
+export declare const fullMapData: MapData;

package/dist/src/full-data.js

@@ -0,0 +1,9 @@
+import { districtMaps, neighborhoodCollections } from '../data/index.js';
+import { deepFreeze } from './immutable.js';
+import { staticMapData } from './static-data.js';
+/** Complete, explicit geographic preset. Import this only when all datasets are needed. */
+export const fullMapData = deepFreeze({
+    map: staticMapData,
+    neighborhoods: neighborhoodCollections,
+    districts: districtMaps,
+});

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

@@ -1,4 +1,4 @@
-import type { InteractiveSFMapElement, InteractiveSFMapOptions } from './interactive-data.js';
+import type { NeighborhoodExplorerElement as InteractiveSFMapElement, NeighborhoodExplorerOptions as InteractiveSFMapOptions } from './types.js';
 /** Guide map preset: SFAR neighborhoods, major parks, BART, and curated roads. */
 export declare function createGuideMap(options?: InteractiveSFMapOptions): InteractiveSFMapElement;
 /** Enhance createGuideShell() in place with a fixed compact chrome layout.

package/dist/src/guide-map.js

@@ -1,18 +1,19 @@
+import { createNeighborhoodExplorerCore } from './explorer-core.js';
 import { guideMapData } from './guide-data.js';
-import { createInteractiveSFMapWithData } from './interactive-data.js';
 import { guideOptions } from './presets.js';
 import { validateExplorerOptions } from './validation.js';
 /** Guide map preset: SFAR neighborhoods, major parks, BART, and curated roads. */
 export function createGuideMap(options = {}) {
     validateExplorerOptions(options);
-    return createInteractiveSFMapWithData(guideMapData, {
+    return createNeighborhoodExplorerCore({
         mode: 'neighborhoods',
         ...options,
         layers: {
             ...guideOptions.layers,
             ...options.layers,
         },
-    });
+        interface: 'map',
+    }, guideMapData);
 }
 /** Enhance createGuideShell() in place with a fixed compact chrome layout.
  * Keep an accessible external place list when hiding the native pickers.

package/dist/src/guide.d.ts

@@ -2,5 +2,4 @@ export type { InteractiveSFMapData } from './explorer-data.js';
 export { guideMapData } from './guide-data.js';
 export { loadGuideDetailedData } from './guide-detailed.js';
 export { createGuideMap, mountGuideMap } from './guide-map.js';
-export type { InteractiveSFMapElement, InteractiveSFMapOptions } from './interactive-data.js';
-export type { CameraOptions, MapFeatures, MapMarker } from './types.js';
+export type { CameraOptions, MapFeatures, MapMarker, NeighborhoodExplorerElement as InteractiveSFMapElement, NeighborhoodExplorerOptions as InteractiveSFMapOptions, } from './types.js';

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;
+}