@kahwee/sf-map-svg 1.0.0 → 1.2.0

package/dist/src/explorer.js

@@ -25,7 +25,7 @@ function svgElement(tag, attributes = {}) {
     return node;
 }
 /** Create an offline, browser-only neighborhood explorer. Call destroy() before disposal. */
-export function createNeighborhoodExplorer({ source = 'realtor', mode = 'neighborhoods', labels = true, neighborhood, year = 2022, theme = 'transit', interface: chrome = 'explorer', layers = {}, selectableNeighborhoods = true, labelSize = {}, fitPadding = 24, markers: initialMarkers = [], markerRadius = 6, markerHitSize = 44, markerColor = '#245b61', selectedMarkerColor = '#f04f32', onMarkerActivate, } = {}) {
+export function createNeighborhoodExplorer({ source = 'realtor', mode = 'neighborhoods', labels = true, neighborhood, year = 2022, theme = 'transit', interface: chrome = 'explorer', layers = {}, selectableNeighborhoods = true, labelSize = {}, fitPadding = 24, markers: initialMarkers = [], markerRadius = 6, markerHitSize = 44, markerColor = '#245b61', selectedMarkerColor = '#f04f32', onMarkerActivate, overlays: initialOverlays = [], onOverlayActivate, style: styleOptions = {}, strings = {}, controls = {}, } = {}) {
     if (!['neighborhoods', 'districts', 'basemap'].includes(mode))
         throw new RangeError(`Unknown map mode: ${mode}`);
     if (chrome !== 'explorer' && chrome !== 'map')
@@ -63,7 +63,7 @@ export function createNeighborhoodExplorer({ source = 'realtor', mode = 'neighbo
     root.setAttribute('aria-label', 'San Francisco neighborhood explorer');
     const style = element('style');
     style.textContent = `
-.sf-explorer{container:sf-neighborhood-explorer / inline-size;font:14px/1.5 system-ui,sans-serif;color:#18364f;background:#fff;border:1px solid #cedae3;border-radius:14px;overflow:hidden;max-width:1120px;margin:auto;box-shadow:0 8px 32px #18364f08}
+.sf-explorer{container:sf-neighborhood-explorer / inline-size;font:14px/1.5 var(--sf-map-font);color:var(--sf-map-ink);background:var(--sf-map-surface);border:1px solid var(--sf-map-border);border-radius:14px;overflow:hidden;max-width:1120px;margin:auto;box-shadow:0 8px 32px #18364f08}
 .sf-explorer *{box-sizing:border-box}
 .sf-explorer [hidden]{display:none!important}
 .sf-explorer h2,.sf-explorer p{margin:0}
@@ -72,8 +72,8 @@ export function createNeighborhoodExplorer({ source = 'realtor', mode = 'neighbo
 .sf-explorer button{cursor:pointer;transition:background .12s,border-color .12s}
 .sf-explorer button:hover{background:#f0f6fa;border-color:#8ba9c0}
 .sf-explorer button[aria-pressed=true]{color:#123d63;background:#e6f1f9;border-color:#5689b0;font-weight:650}
-.sf-explorer :focus-visible{outline:3px solid #1676b8;outline-offset:2px}
-.sf-explorer-header{padding:24px;border-top:4px solid #163d61;border-bottom:1px solid #dce5eb}
+.sf-explorer :focus-visible{outline:3px solid var(--sf-map-focus);outline-offset:2px}
+.sf-explorer-header{padding:24px;border-top:4px solid var(--sf-map-accent);border-bottom:1px solid var(--sf-map-border)}
 .sf-explorer-header h2{font-size:25px;line-height:1.25;font-weight:700;letter-spacing:-.7px}
 .sf-explorer-header p{color:#586f80;margin-top:8px;max-width:58ch}
 .sf-explorer-body{display:grid;grid-template-columns:280px minmax(0,1fr);grid-template-areas:"panel map" "detail map";grid-template-rows:auto 1fr}
@@ -92,7 +92,7 @@ export function createNeighborhoodExplorer({ source = 'realtor', mode = 'neighbo
 .sf-explorer-detail p{font-size:12px;margin-bottom:10px}
 .sf-explorer-download{display:block;margin:8px 0;color:#12649c;text-underline-offset:3px}
 .sf-explorer-map-column{grid-area:map;min-width:0;background:#e4f2f8}
-.sf-explorer-toolbar{display:flex;align-items:center;flex-wrap:wrap;gap:6px;padding:12px;background:#fff;border-bottom:1px solid #dce5eb}
+.sf-explorer-toolbar{display:flex;align-items:center;flex-wrap:wrap;gap:var(--sf-map-control-gap);padding:12px;background:var(--sf-map-surface);border-bottom:1px solid var(--sf-map-border)}
 .sf-explorer-control-group{display:flex;align-items:center;flex-wrap:wrap;gap:6px;max-width:100%}
 .sf-explorer-pan-controls{margin-left:auto}
 .sf-explorer-toolbar button{min-width:44px;padding:6px 10px}
@@ -136,13 +136,20 @@ export function createNeighborhoodExplorer({ source = 'realtor', mode = 'neighbo
 .sf-explorer-download{display:inline-block;margin:4px 14px 4px 0}
 }`;
     root.dataset.interface = chrome;
+    root.style.setProperty('--sf-map-ink', styleOptions.ink ?? '#18364f');
+    root.style.setProperty('--sf-map-surface', styleOptions.surface ?? '#fff');
+    root.style.setProperty('--sf-map-accent', styleOptions.accent ?? '#163d61');
+    root.style.setProperty('--sf-map-border', styleOptions.border ?? '#cedae3');
+    root.style.setProperty('--sf-map-focus', styleOptions.focus ?? '#1676b8');
+    root.style.setProperty('--sf-map-control-gap', styleOptions.controlGap ?? '6px');
+    root.style.setProperty('--sf-map-font', styleOptions.font ?? 'system-ui,sans-serif');
     root.append(style);
     const header = element('header', '', 'sf-explorer-header');
-    header.append(element('h2', 'Explore San Francisco'), element('p', 'Explore the city, from familiar names to the places in between.'));
+    header.append(element('h2', strings.title ?? 'Explore San Francisco'), element('p', 'Explore the city, from familiar names to the places in between.'));
     root.append(header);
     const body = element('div', '', 'sf-explorer-body');
     const panel = element('div', '', 'sf-explorer-panel');
-    const modeLabel = element('label', 'Map mode');
+    const modeLabel = element('label', strings.mode ?? 'Map mode');
     const modeSelect = element('select');
     for (const [value, title] of [
         ['neighborhoods', 'Neighborhoods'],
@@ -154,7 +161,7 @@ export function createNeighborhoodExplorer({ source = 'realtor', mode = 'neighbo
         modeSelect.append(option);
     }
     modeLabel.append(modeSelect);
-    const sourceLabel = element('label', 'Neighborhood definitions');
+    const sourceLabel = element('label', strings.source ?? 'Neighborhood definitions');
     const sourceSelect = element('select');
     for (const [value, title] of Object.entries(sourceNames)) {
         const option = element('option', title);
@@ -163,7 +170,7 @@ export function createNeighborhoodExplorer({ source = 'realtor', mode = 'neighbo
     }
     sourceSelect.value = source;
     sourceLabel.append(sourceSelect);
-    const searchLabel = element('label', 'Find a neighborhood');
+    const searchLabel = element('label', strings.search ?? 'Find a neighborhood');
     const search = element('input');
     search.type = 'search';
     search.placeholder = 'Try Mission, Outer Mission, or NoPa';
@@ -180,7 +187,8 @@ export function createNeighborhoodExplorer({ source = 'realtor', mode = 'neighbo
     const toolbar = element('div', '', 'sf-explorer-toolbar');
     toolbar.setAttribute('aria-label', 'Map controls');
     const canvas = element('div', '', 'sf-explorer-canvas');
-    const hint = element('p', 'Drag to pan · Ctrl/⌘ + scroll to zoom · Focus map: arrows pan, +/− zoom, Home resets. Touch: scroll the page, or enable Touch navigation to pan and pinch the map. Escape exits.', 'sf-explorer-hint');
+    const hint = element('p', strings.gestureHelp ??
+        'Drag to pan · Ctrl/⌘ + scroll to zoom · Focus map: arrows pan, +/− zoom, Home resets. Touch: scroll the page, or enable Touch navigation to pan and pinch the map. Escape exits.', 'sf-explorer-hint');
     const status = element('p', '', 'sf-explorer-status');
     status.setAttribute('aria-live', 'polite');
     const legend = element('div', '', 'sf-explorer-legend');
@@ -198,10 +206,10 @@ export function createNeighborhoodExplorer({ source = 'realtor', mode = 'neighbo
         legend.append(entry);
     }
     const featureControls = element('div', '', 'sf-explorer-feature-controls');
-    const neighborhoodLabel = element('label', 'Select neighborhood');
+    const neighborhoodLabel = element('label', strings.chooseNeighborhood ?? 'Select neighborhood');
     const neighborhoodSelect = element('select');
     neighborhoodLabel.append(neighborhoodSelect);
-    const markerLabel = element('label', 'Choose marker');
+    const markerLabel = element('label', strings.chooseMarker ?? 'Choose marker');
     const markerSelect = element('select');
     markerLabel.append(markerSelect);
     featureControls.append(neighborhoodLabel, markerLabel);
@@ -246,6 +254,7 @@ export function createNeighborhoodExplorer({ source = 'realtor', mode = 'neighbo
         kind: 'district',
     })));
     const markerLayer = svgElement('g', { 'data-layer': 'interactive-markers' });
+    const overlayLayer = svgElement('g', { 'data-layer': 'user-overlays' });
     const areas = svgElement('g', { 'data-layer': 'explorer-neighborhoods' });
     const stations = svgElement('g', { 'data-layer': 'explorer-bart' });
     const labelLayer = svgElement('g', {
@@ -253,7 +262,7 @@ export function createNeighborhoodExplorer({ source = 'realtor', mode = 'neighbo
         'aria-hidden': 'true',
         'font-family': 'system-ui,sans-serif',
     });
-    geography.append(areas, stations, labelLayer, markerLayer);
+    geography.append(areas, stations, labelLayer, overlayLayer, markerLayer);
     let view = [0, 0, 800];
     let selected;
     let items = [];
@@ -306,6 +315,51 @@ export function createNeighborhoodExplorer({ source = 'realtor', mode = 'neighbo
     legend.hidden = !legend.children.length;
     let markerItems = [];
     let selectedMarker = null;
+    function setOverlays(overlays) {
+        const ids = new Set();
+        const next = overlays.map((overlay) => {
+            if (!overlay.id || ids.has(overlay.id))
+                throw new RangeError('Overlays require unique nonempty IDs.');
+            ids.add(overlay.id);
+            const node = svgElement('path', {
+                'data-overlay-id': overlay.id,
+                d: geometryPath(overlay.geometry, map.project),
+                fill: overlay.fill ?? 'none',
+                'fill-opacity': overlay.fillOpacity ?? 1,
+                stroke: overlay.stroke ?? '#bd8b73',
+                'stroke-width': overlay.strokeWidth ?? 2,
+                'vector-effect': 'non-scaling-stroke',
+                display: overlay.visible === false ? 'none' : 'inline',
+                'pointer-events': 'none',
+                ...(overlay.label ? { 'aria-label': overlay.label } : {}),
+            });
+            if (overlay.label) {
+                node.setAttribute('role', 'img');
+                const title = svgElement('title');
+                title.textContent = overlay.label;
+                node.append(title);
+            }
+            if (onOverlayActivate) {
+                node.setAttribute('role', 'button');
+                node.setAttribute('tabindex', '0');
+                node.setAttribute('pointer-events', 'stroke');
+                node.setAttribute('aria-label', overlay.label ?? overlay.id);
+                const activate = () => {
+                    onOverlayActivate(overlay);
+                    root.dispatchEvent(new CustomEvent('overlayactivate', { bubbles: true, detail: { overlay } }));
+                };
+                node.addEventListener('click', activate, { signal: controller.signal });
+                node.addEventListener('keydown', (event) => {
+                    if (event.key === 'Enter' || event.key === ' ') {
+                        event.preventDefault();
+                        activate();
+                    }
+                }, { signal: controller.signal });
+            }
+            return node;
+        });
+        overlayLayer.replaceChildren(...next);
+    }
     const zoomControls = element('div', '', 'sf-explorer-control-group');
     const panControls = element('div', '', 'sf-explorer-control-group sf-explorer-pan-controls');
     toolbar.append(zoomControls, panControls);
@@ -321,7 +375,7 @@ export function createNeighborhoodExplorer({ source = 'realtor', mode = 'neighbo
     const zoomText = element('span', '100%', 'sf-explorer-zoom');
     zoomControls.append(zoomText);
     const zoomIn = button('+', 'Zoom in', () => zoomBy(1.5));
-    button('Reset', 'Reset map to city view', resetView);
+    button(strings.reset ?? 'Reset', strings.reset ?? 'Reset map to city view', resetView);
     const labelsButton = button('Labels', 'Show map labels', () => setLabels(!labels));
     for (const [symbol, label, dx, dy] of [
         ['←', 'Pan west', -1, 0],
@@ -541,7 +595,7 @@ export function createNeighborhoodExplorer({ source = 'realtor', mode = 'neighbo
                 node.focus({ preventScroll: true });
         }
         if (!matches.length)
-            results.append(element('p', 'No matches. Try another name or definition source.', 'sf-explorer-note'));
+            results.append(element('p', strings.emptyResults ?? 'No matches. Try another name or definition source.', 'sf-explorer-note'));
     }
     function getSelection() {
         return selected
@@ -784,6 +838,19 @@ export function createNeighborhoodExplorer({ source = 'realtor', mode = 'neighbo
             : (markers.find((marker) => marker.selected)?.id ?? null);
         selectMarker(nextSelection, { fit: false });
     }
+    if (controls.zoom === false)
+        zoomControls.hidden = true;
+    if (controls.pan === false)
+        panControls.hidden = true;
+    if (controls.reset === false) {
+        const reset = Array.from(toolbar.querySelectorAll('button')).find((node) => node.textContent === (strings.reset ?? 'Reset'));
+        if (reset)
+            reset.hidden = true;
+    }
+    if (controls.labels === false)
+        labelsButton.hidden = true;
+    if (controls.legend === false)
+        legend.hidden = true;
     function setMode(next) {
         if (destroyed)
             return;
@@ -852,7 +919,9 @@ export function createNeighborhoodExplorer({ source = 'realtor', mode = 'neighbo
         if (node?.dataset.neighborhoodResult)
             selectNeighborhood(node.dataset.neighborhoodResult);
     });
-    const touchButton = button('Touch navigation', 'Enable map touch navigation', () => setTouchNavigation(!touchNavigation));
+    const touchLabel = strings.touchNavigation ?? 'Touch navigation';
+    const touchButton = button(touchLabel, `Enable ${touchLabel.toLowerCase()}`, () => setTouchNavigation(!touchNavigation));
+    touchButton.hidden = controls.touch === false;
     let touchNavigation = false;
     const navigation = attachNavigation(svg, getViewport, setView, controller.signal, () => setTouchNavigation(false));
     function setTouchNavigation(enabled) {
@@ -863,8 +932,8 @@ export function createNeighborhoodExplorer({ source = 'realtor', mode = 'neighbo
         touchNavigation = enabled;
         navigation.setTouchNavigation(enabled);
         canvas.style.touchAction = enabled ? 'none' : 'pan-y pinch-zoom';
-        touchButton.textContent = enabled ? 'Done: page scrolling' : 'Touch navigation';
-        touchButton.setAttribute('aria-label', enabled ? 'Exit map touch navigation' : 'Enable map touch navigation');
+        touchButton.textContent = enabled ? 'Done: page scrolling' : touchLabel;
+        touchButton.setAttribute('aria-label', enabled ? `Exit ${touchLabel.toLowerCase()}` : `Enable ${touchLabel.toLowerCase()}`);
         touchButton.setAttribute('aria-pressed', String(enabled));
         root.dataset.touchNavigation = String(enabled);
     }
@@ -923,6 +992,7 @@ export function createNeighborhoodExplorer({ source = 'realtor', mode = 'neighbo
         panBy,
         setTouchNavigation,
         setMarkers,
+        setOverlays,
         selectMarker,
         getSelectedMarker,
         setSource,
@@ -938,18 +1008,25 @@ export function createNeighborhoodExplorer({ source = 'realtor', mode = 'neighbo
             releaseDownloads();
         },
     });
-    const initialMode = mode;
-    setSource(source);
-    if (neighborhood !== undefined)
-        selectNeighborhood(neighborhood);
-    setMode(initialMode);
-    if (initialMode === 'neighborhoods' && selected) {
-        const selectedItem = items.find((item) => item.feature === selected);
-        if (selectedItem)
-            setView(fitBounds(selectedItem.bounds));
+    try {
+        const initialMode = mode;
+        setSource(source);
+        if (neighborhood !== undefined)
+            selectNeighborhood(neighborhood);
+        setMode(initialMode);
+        if (initialMode === 'neighborhoods' && selected) {
+            const selectedItem = items.find((item) => item.feature === selected);
+            if (selectedItem)
+                setView(fitBounds(selectedItem.bounds));
+        }
+        setLabels(labels);
+        setTouchNavigation(false);
+        setMarkers(initialMarkers);
+        setOverlays(initialOverlays);
+    }
+    catch (error) {
+        explorer.destroy();
+        throw error;
     }
-    setLabels(labels);
-    setTouchNavigation(false);
-    setMarkers(initialMarkers);
     return explorer;
 }

package/dist/src/index.d.ts

@@ -1,13 +1,12 @@
-import type { Position } from '../data/types.js';
-import type { DistrictYear, SFMapOptions } from './types.js';
-export type { DistrictYear, MapMarker, SFMapOptions } from './types.js';
-export declare const districtYears: readonly DistrictYear[];
+import { districtColors, districtYears } from './map-core.js';
+import type { SFMapOptions } from './types.js';
+export type { DistrictYear, MapMarker, MapOverlay, SFMapOptions } from './types.js';
+export { districtColors, districtYears };
 export declare const neighborhoodNames: readonly string[];
-export declare const districtColors: readonly string[];
 /** Make an offline SVG and the matching longitude/latitude projection. */
 export declare function createSFMap(options?: SFMapOptions): {
     svg: string;
-    project: (coordinates: Position) => [number, number];
+    project: (coordinates: import("../data/types.js").Position) => [number, number];
     viewBox: [number, number, number, number];
 };
 export declare function renderSFMap(options?: SFMapOptions): string;

package/dist/src/index.js

@@ -1,124 +1,20 @@
 import data from './data.js';
-import { geometryPath, positions, rawProject } from './geometry.js';
-import * as layers from './layers.js';
-import { landmarks as landmarkData, keyRoads as roadData, bartStations as stationData, } from './overlays.js';
-import { escapeXml, stroke } from './svg.js';
-// The common coast is immutable: compute its Mercator bounds once per module.
-const coastPoints = positions(data.coast).map(rawProject);
-const bounds = 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]);
-export const districtYears = Object.freeze([2002, 2012, 2022]);
+import { createSFMapWithData, districtColors, districtYears } from './map-core.js';
+import { bartStations, keyRoads, landmarks } from './overlays.js';
+export { districtColors, districtYears };
 export const neighborhoodNames = Object.freeze(data.neighborhoods.map((item) => item.name));
-export const districtColors = Object.freeze([
-    '#c8dce5',
-    '#d5e4d6',
-    '#d1d6e8',
-    '#d0dfd7',
-    '#e4dcca',
-    '#d3dced',
-    '#d9d8e7',
-    '#c8dfdf',
-    '#e2d6ca',
-    '#cbdcd1',
-    '#dfddc9',
-]);
-const defaults = {
-    water: '#e7f0f3',
-    land: '#f1f3ee',
-    district: '#71838a',
-    neighborhood: '#8c9195',
-    highway: '#bd8b73',
-    road: '#bcc3c5',
-    park: '#b2cfaa',
-    landmark: '#3e6346',
-    bart: '#24789a',
-    label: '#304958',
-    marker: '#245b61',
-    selected: '#f04f32',
+const packagedData = {
+    coast: data.coast,
+    districts: data.districts,
+    neighborhoods: data.neighborhoods,
+    highways: data.highways,
+    landmarks,
+    keyRoads,
+    bartStations,
 };
-const transitColors = {
-    water: '#e4f2f8',
-    land: '#fcfcf8',
-    district: '#a7b8c0',
-    neighborhood: '#b2c0c7',
-    highway: '#b9a18a',
-    park: '#c6dfbd',
-    landmark: '#426641',
-    bart: '#0073ae',
-    label: '#183e58',
-    marker: '#0073ae',
-    selected: '#0073ae',
-};
-let sequence = 0;
 /** Make an offline SVG and the matching longitude/latitude projection. */
 export function createSFMap(options = {}) {
-    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;
-    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 [minX, minY, maxX, maxY] = bounds;
-    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);
-    const coastPath = path(data.coast);
-    const districts = data.districts[year];
-    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],
-        }))
-        : [];
-    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 nine 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"/>`,
-    ];
-    // Explicit drawing order keeps optional overlays and user markers predictable.
-    if (districtFills)
-        parts.push(layers.districtFills(districtPaths, context));
-    if (landmarks)
-        parts.push(layers.landmarks(landmarkData, context));
-    if (keyRoads)
-        parts.push(layers.keyRoads(roadData, context));
-    if (highways)
-        parts.push(layers.highways(data.highways, context));
-    if (neighborhoodLines)
-        parts.push(layers.neighborhoods(data.neighborhoods, context));
-    if (districtLines)
-        parts.push(layers.districtLines(districtPaths, context));
-    parts.push(`<path data-layer="coastline" d="${coastPath}" ${stroke(colors.district, 0.65)}/>`);
-    if (labels && districtLabels)
-        parts.push(layers.districtLabels(districts, context));
-    if (labels && landmarks)
-        parts.push(layers.landmarkLabels(landmarkData, context));
-    if (labels && keyRoads)
-        parts.push(layers.keyRoadLabels(roadData, context));
-    if (bartStations)
-        parts.push(layers.bartStations(stationData, context));
-    parts.push(layers.markers(markers, context), '</g></svg>');
-    return {
-        svg: parts.join(''),
-        project,
-        viewBox: [0, 0, width, height],
-    };
+    return createSFMapWithData(options, packagedData);
 }
 export function renderSFMap(options = {}) {
     return createSFMap(options).svg;

package/dist/src/interactive.d.ts

@@ -1,4 +1,4 @@
 import type { NeighborhoodExplorerOptions } from './types.js';
-export type { InteractiveLayers, MapPadding, MapViewport, NeighborhoodExplorerElement as InteractiveSFMapElement, NeighborhoodExplorerOptions as InteractiveSFMapOptions, NeighborhoodSelection, } from './types.js';
+export type { InteractiveLayers, MapOverlay, MapPadding, MapViewport, NeighborhoodExplorerElement as InteractiveSFMapElement, NeighborhoodExplorerOptions as InteractiveSFMapOptions, NeighborhoodSelection, } from './types.js';
 /** Reusable browser map; plain basemap by default, no editorial UI or URL changes. */
 export declare function createInteractiveSFMap(options?: NeighborhoodExplorerOptions): import("./types.js").NeighborhoodExplorerElement;

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

@@ -0,0 +1,54 @@
+import type { Geometry, Position } from '../data/types.js';
+import type { DistrictYear, SFMapOptions } from './types.js';
+export type { DistrictYear, MapMarker, MapOverlay, SFMapOptions } from './types.js';
+export interface SFMapData {
+    coast: Geometry;
+    districts?: Readonly<Partial<Record<DistrictYear, readonly DistrictRowData[]>>>;
+    neighborhoods?: readonly {
+        name: string;
+        geometry: Geometry;
+    }[];
+    highways?: readonly {
+        route: string;
+        geometry: Geometry;
+    }[];
+    landmarks?: readonly LandmarkData[];
+    keyRoads?: readonly KeyRoadData[];
+    bartStations?: readonly BartStationData[];
+}
+export interface DistrictRowData {
+    id: number;
+    label: Position;
+    labelPoints: readonly Position[];
+    geometry: Geometry;
+    extras: Geometry | null;
+}
+export interface LandmarkData {
+    id: string;
+    name: string;
+    label: Position;
+    offset: readonly [number, number];
+    anchor: 'middle' | 'start' | 'end';
+    geometry: Geometry;
+}
+export interface KeyRoadData {
+    id: string;
+    name: string;
+    sourceNames: readonly string[];
+    label: Position;
+    segmentIds: readonly string[];
+    geometry: Geometry;
+}
+export interface BartStationData {
+    id: string;
+    name: string;
+    coordinates: Position;
+}
+export declare const districtYears: readonly DistrictYear[];
+export declare const districtColors: readonly string[];
+/** Make an offline SVG and the matching longitude/latitude projection. */
+export declare function createSFMapWithData(options: SFMapOptions, data: SFMapData): {
+    svg: string;
+    project: (coordinates: Position) => [number, number];
+    viewBox: [number, number, number, number];
+};

package/dist/src/map-core.js

@@ -0,0 +1,125 @@
+import { geometryPath, positions, rawProject } from './geometry.js';
+import * as layers from './layers.js';
+import { escapeXml, stroke } from './svg.js';
+export const districtYears = Object.freeze([2002, 2012, 2022]);
+export const districtColors = Object.freeze([
+    '#c8dce5',
+    '#d5e4d6',
+    '#d1d6e8',
+    '#d0dfd7',
+    '#e4dcca',
+    '#d3dced',
+    '#d9d8e7',
+    '#c8dfdf',
+    '#e2d6ca',
+    '#cbdcd1',
+    '#dfddc9',
+]);
+const defaults = {
+    water: '#e7f0f3',
+    land: '#f1f3ee',
+    district: '#71838a',
+    neighborhood: '#8c9195',
+    highway: '#bd8b73',
+    road: '#bcc3c5',
+    park: '#b2cfaa',
+    landmark: '#3e6346',
+    bart: '#24789a',
+    label: '#304958',
+    marker: '#245b61',
+    selected: '#f04f32',
+};
+const transitColors = {
+    water: '#e4f2f8',
+    land: '#fcfcf8',
+    district: '#a7b8c0',
+    neighborhood: '#b2c0c7',
+    highway: '#b9a18a',
+    park: '#c6dfbd',
+    landmark: '#426641',
+    bart: '#0073ae',
+    label: '#183e58',
+    marker: '#0073ae',
+    selected: '#0073ae',
+};
+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;
+    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 path = (geometry) => geometryPath(geometry, project);
+    const coastPath = path(data.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],
+        }))
+        : [];
+    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 nine 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"/>`,
+    ];
+    // Explicit drawing order keeps optional overlays and user markers predictable.
+    if (districtFills)
+        parts.push(layers.districtFills(districtPaths, context));
+    if (landmarks)
+        parts.push(layers.landmarks(landmarkData, context));
+    if (keyRoads)
+        parts.push(layers.keyRoads(roadData, context));
+    if (highways)
+        parts.push(layers.highways(data.highways ?? [], context));
+    if (neighborhoodLines)
+        parts.push(layers.neighborhoods(data.neighborhoods ?? [], context));
+    if (districtLines)
+        parts.push(layers.districtLines(districtPaths, context));
+    parts.push(`<path data-layer="coastline" d="${coastPath}" ${stroke(colors.district, 0.65)}/>`);
+    if (labels && districtLabels)
+        parts.push(layers.districtLabels(districts, context));
+    if (labels && landmarks)
+        parts.push(layers.landmarkLabels(landmarkData, context));
+    if (labels && keyRoads)
+        parts.push(layers.keyRoadLabels(roadData, context));
+    if (bartStations)
+        parts.push(layers.bartStations(stationData, context));
+    for (const overlay of options.overlays ?? []) {
+        if (!overlay.id || !/^[A-Za-z0-9_-]+$/.test(overlay.id))
+            throw new TypeError('Overlay IDs must contain only letters, numbers, underscores, or hyphens.');
+        parts.push(`<path data-overlay-id="${escapeXml(overlay.id)}"${overlay.label ? ` aria-label="${escapeXml(overlay.label)}"` : ''} d="${path(overlay.geometry)}" fill="${escapeXml(overlay.fill ?? 'none')}" fill-opacity="${overlay.fillOpacity ?? 1}" stroke="${escapeXml(overlay.stroke ?? colors.road)}" stroke-width="${overlay.strokeWidth ?? 2}" vector-effect="non-scaling-stroke"${overlay.visible === false ? ' display="none"' : ''}/>`);
+    }
+    parts.push(layers.markers(markers, context), '</g></svg>');
+    return {
+        svg: parts.join(''),
+        project,
+        viewBox: [0, 0, width, height],
+    };
+}

package/dist/src/transit.d.ts

@@ -0,0 +1,3 @@
+import type { TransitAnimationElement } from './types.js';
+/** A deliberately schematic, offline station-to-station animation. Starts paused. */
+export declare function createTransitAnimation(): TransitAnimationElement;