@kahwee/sf-map-svg 1.1.0 → 1.3.0

package/dist/src/guide.d.ts

@@ -0,0 +1,10 @@
+import type { InteractiveSFMapData } from './explorer-data.js';
+import type { InteractiveSFMapElement, InteractiveSFMapOptions } from './interactive-data.js';
+/** Compact, source-aware San Francisco guide data. Imports no district or alternate-neighborhood files. */
+export declare const guideMapData: InteractiveSFMapData;
+/** Guide map preset: SFAR neighborhoods, major parks, BART, and curated roads. */
+export declare function createGuideMap(options?: InteractiveSFMapOptions): InteractiveSFMapElement;
+/** Load the detailed versions of the guide's selected geography on explicit request. */
+export declare function loadGuideDetailedData(): Promise<InteractiveSFMapData>;
+export type { InteractiveSFMapData } from './explorer-data.js';
+export type { InteractiveSFMapElement, InteractiveSFMapOptions };

package/dist/src/guide.js

@@ -0,0 +1,107 @@
+import bart from '../data/guide/bart-stations.json' with { type: 'json' };
+import coast from '../data/guide/coast.json' with { type: 'json' };
+import highways from '../data/guide/highways.json' with { type: 'json' };
+import roads from '../data/guide/key-roads.json' with { type: 'json' };
+import landmarks from '../data/guide/landmarks.json' with { type: 'json' };
+import neighborhoods from '../data/guide/neighborhoods-realtor.json' with { type: 'json' };
+import { createInteractiveSFMapWithData } from './interactive-data.js';
+const neighborhoodData = neighborhoods;
+const highwayData = highways;
+const parkData = landmarks;
+const roadData = roads;
+const stationData = bart;
+/** Compact, source-aware San Francisco guide data. Imports no district or alternate-neighborhood files. */
+export const guideMapData = {
+    map: {
+        coast: coast.features[0].geometry,
+        neighborhoods: neighborhoodData.features.map((feature) => ({
+            name: feature.properties.canonicalName,
+            geometry: feature.geometry,
+        })),
+        highways: highwayData.features.map((feature) => ({
+            route: String(feature.properties.route),
+            geometry: feature.geometry,
+        })),
+        landmarks: parkData.features.map(({ id, properties, geometry }) => ({
+            id,
+            ...properties,
+            geometry,
+        })),
+        keyRoads: roadData.features.map(({ id, properties, geometry }) => ({
+            id,
+            ...properties,
+            sourceNames: properties.sourceNames ?? [],
+            segmentIds: properties.segmentIds ?? [],
+            geometry,
+        })),
+        bartStations: stationData.features.flatMap(({ id, properties, geometry }) => geometry.type === 'Point'
+            ? [{ id, name: properties.name, coordinates: geometry.coordinates }]
+            : []),
+    },
+    neighborhoods: { realtor: neighborhoodData },
+};
+/** Guide map preset: SFAR neighborhoods, major parks, BART, and curated roads. */
+export function createGuideMap(options = {}) {
+    return createInteractiveSFMapWithData(guideMapData, {
+        mode: 'neighborhoods',
+        ...options,
+        layers: {
+            districtFills: false,
+            districtLines: false,
+            districtLabels: false,
+            neighborhoodLines: true,
+            neighborhoodLabels: true,
+            landmarks: true,
+            bartStations: true,
+            highways: true,
+            keyRoads: true,
+            roadLabels: true,
+            ...options.layers,
+        },
+    });
+}
+/** Load the detailed versions of the guide's selected geography on explicit request. */
+export async function loadGuideDetailedData() {
+    const [coastData, neighborhoodData, parkData, highwayData, roadData, bartData] = await Promise.all([
+        import('../data/coast.json', { with: { type: 'json' } }),
+        import('../data/neighborhoods-realtor.json', { with: { type: 'json' } }),
+        import('../data/landmarks.json', { with: { type: 'json' } }),
+        import('../data/guide/highways-detailed.json', { with: { type: 'json' } }),
+        import('../data/key-roads.json', { with: { type: 'json' } }),
+        import('../data/bart-stations.json', { with: { type: 'json' } }),
+    ]);
+    const detailedNeighborhoods = neighborhoodData.default;
+    const detailedRoads = roadData.default;
+    const detailedHighways = highwayData.default;
+    const detailedParks = parkData.default;
+    const detailedStations = bartData.default;
+    return {
+        map: {
+            coast: coastData.default.features[0].geometry,
+            neighborhoods: detailedNeighborhoods.features.map((feature) => ({
+                name: feature.properties.canonicalName,
+                geometry: feature.geometry,
+            })),
+            highways: detailedHighways.features
+                .filter((feature) => ['1', '101', '280'].includes(String(feature.properties.route)))
+                .map((feature) => ({
+                route: String(feature.properties.route),
+                geometry: feature.geometry,
+            })),
+            landmarks: detailedParks.features.map(({ id, properties, geometry }) => ({
+                id,
+                ...properties,
+                geometry,
+            })),
+            keyRoads: detailedRoads.features.map(({ id, properties, geometry }) => ({
+                id,
+                ...properties,
+                geometry,
+            })),
+            bartStations: detailedStations.features.flatMap(({ id, properties, geometry }) => geometry.type === 'Point'
+                ? [{ id, name: properties.name, coordinates: geometry.coordinates }]
+                : []),
+        },
+        neighborhoods: { realtor: detailedNeighborhoods },
+    };
+}

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

@@ -0,0 +1,6 @@
+import type { InteractiveSFMapData } from './explorer-data.js';
+import type { NeighborhoodExplorerOptions } from './types.js';
+export type { InteractiveSFMapData } from './explorer-data.js';
+export type { InteractiveLayers, MapPadding, MapViewport, NeighborhoodExplorerElement as InteractiveSFMapElement, NeighborhoodExplorerOptions as InteractiveSFMapOptions, NeighborhoodSelection, } from './types.js';
+/** Browser map shell that bundles only the geography supplied by the caller. */
+export declare function createInteractiveSFMapWithData(data: InteractiveSFMapData, options?: NeighborhoodExplorerOptions): import("./types.js").NeighborhoodExplorerElement;

package/dist/src/interactive-data.js

@@ -0,0 +1,5 @@
+import { createNeighborhoodExplorerCore } from './explorer-core.js';
+/** Browser map shell that bundles only the geography supplied by the caller. */
+export function createInteractiveSFMapWithData(data, options = {}) {
+    return createNeighborhoodExplorerCore({ mode: 'basemap', ...options, interface: 'map' }, data);
+}

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/layers.js

@@ -52,7 +52,12 @@ export function markers(items, { project, colors }) {
         .join('')}</g>`;
 }
 export function keyRoads(items, { idPrefix, path, colors }) {
-    return `<g data-layer="key-roads" clip-path="url(#${idPrefix}-coast)">${items.map((road) => `<path data-key-road="${escapeXml(road.id)}" d="${path(road.geometry)}" ${stroke(colors.road, 1)}><title>${escapeXml(road.name)}</title></path>`).join('')}</g>`;
+    return `<g data-layer="key-roads" clip-path="url(#${idPrefix}-coast)">${items
+        .map((road) => {
+        const level = road.level === 'secondary' ? 'secondary' : 'primary';
+        return `<path data-key-road="${escapeXml(road.id)}" data-key-road-level="${level}" d="${path(road.geometry)}" ${stroke(colors.road, 1)}><title>${escapeXml(road.name)}</title></path>`;
+    })
+        .join('')}</g>`;
 }
 export function keyRoadLabels(items, { project }) {
     return `<g data-layer="key-road-labels" ${overlayLabel} fill="#77736b">${items

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

@@ -0,0 +1,55 @@
+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;
+    level?: 'primary' | 'secondary';
+    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,132 @@
+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;
+    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 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 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 && roadLabels)
+        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.');
+        if (overlay.strokeWidth !== undefined &&
+            (!Number.isFinite(overlay.strokeWidth) || overlay.strokeWidth < 0))
+            throw new RangeError('Overlay strokeWidth must be a finite nonnegative number.');
+        if (overlay.fillOpacity !== undefined &&
+            (!Number.isFinite(overlay.fillOpacity) || overlay.fillOpacity < 0 || overlay.fillOpacity > 1))
+            throw new RangeError('Overlay fillOpacity must be a finite number from 0 to 1.');
+        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/overlays.d.ts

@@ -16,6 +16,7 @@ export type Landmark = (typeof landmarks)[number];
 export type BartStation = (typeof bartStations)[number];
 export declare const keyRoads: {
     name: string;
+    level?: 'primary' | 'secondary';
     sourceNames: readonly string[];
     label: Position;
     segmentIds: readonly string[];

package/dist/src/types.d.ts

@@ -8,6 +8,18 @@ export interface MapMarker {
     selected?: boolean;
     color?: string;
 }
+export interface MapOverlay {
+    id: string;
+    geometry: Extract<Geometry, {
+        type: 'LineString' | 'MultiLineString' | 'Polygon' | 'MultiPolygon';
+    }>;
+    stroke?: string;
+    strokeWidth?: number;
+    fill?: string;
+    fillOpacity?: number;
+    visible?: boolean;
+    label?: string;
+}
 export interface SFMapOptions {
     theme?: 'districts' | 'transit';
     width?: number;
@@ -22,9 +34,11 @@ export interface SFMapOptions {
     labels?: boolean;
     highways?: boolean;
     keyRoads?: boolean;
+    roadLabels?: boolean;
     landmarks?: boolean;
     bartStations?: boolean;
     markers?: MapMarker[];
+    overlays?: readonly MapOverlay[];
     title?: string;
     idPrefix?: string;
     colors?: Partial<Record<'water' | 'land' | 'district' | 'neighborhood' | 'highway' | 'road' | 'park' | 'landmark' | 'bart' | 'label' | 'marker' | 'selected', string>>;
@@ -48,6 +62,7 @@ export interface InteractiveLayers {
     bartStations?: boolean;
     highways?: boolean;
     keyRoads?: boolean;
+    roadLabels?: boolean;
 }
 export interface NeighborhoodSelection {
     id: string;
@@ -81,6 +96,12 @@ export interface NeighborhoodExplorerOptions {
     markerColor?: string;
     selectedMarkerColor?: string;
     onMarkerActivate?: (marker: MapMarker) => void;
+    overlays?: readonly MapOverlay[];
+    onOverlayActivate?: (overlay: MapOverlay) => void;
+    /** Stable theme tokens consumed by the explorer chrome. */
+    style?: Partial<Record<'ink' | 'surface' | 'accent' | 'border' | 'focus' | 'controlGap' | 'font', string>>;
+    strings?: Partial<Record<'title' | 'mode' | 'source' | 'search' | 'chooseNeighborhood' | 'chooseMarker' | 'touchNavigation' | 'reset' | 'emptyResults' | 'gestureHelp', string>>;
+    controls?: Partial<Record<'zoom' | 'pan' | 'reset' | 'labels' | 'touch' | 'legend', boolean>>;
 }
 export interface NeighborhoodExplorerElement extends HTMLElement {
     selectNeighborhood(name: string | null, options?: {
@@ -100,6 +121,7 @@ export interface NeighborhoodExplorerElement extends HTMLElement {
     /** Explicitly engage map touch gestures; false restores page gestures. */
     setTouchNavigation(enabled: boolean): void;
     setMarkers(markers: readonly MapMarker[]): void;
+    setOverlays(overlays: readonly MapOverlay[]): void;
     selectMarker(id: string | null, options?: {
         fit?: boolean;
     }): boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kahwee/sf-map-svg",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "Offline SVG maps of San Francisco with district boundaries, parks, landmarks, and BART stations.",
   "type": "module",
   "main": "./dist/src/index.js",
@@ -10,6 +10,10 @@
       "types": "./dist/src/index.d.ts",
       "import": "./dist/src/index.js"
     },
+    "./custom-map": {
+      "types": "./dist/src/custom-map.d.ts",
+      "import": "./dist/src/custom-map.js"
+    },
     "./data": {
       "types": "./dist/data/index.d.ts",
       "import": "./dist/data/index.js"
@@ -27,6 +31,14 @@
       "types": "./dist/src/interactive.d.ts",
       "import": "./dist/src/interactive.js"
     },
+    "./interactive-data": {
+      "types": "./dist/src/interactive-data.d.ts",
+      "import": "./dist/src/interactive-data.js"
+    },
+    "./guide": {
+      "types": "./dist/src/guide.d.ts",
+      "import": "./dist/src/guide.js"
+    },
     "./transit": {
       "types": "./dist/src/transit.d.ts",
       "import": "./dist/src/transit.js"
@@ -84,9 +96,11 @@
     "data:check": "node scripts/build-data-catalog.mjs --check",
     "typecheck": "pnpm build && tsc -p tsconfig.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",
     "test:package": "node scripts/smoke-package.mjs",
     "build": "node scripts/build.mjs",
     "lint": "biome check .",
-    "build:pages": "pnpm demo && node scripts/build-pages.mjs"
+    "build:pages": "pnpm build && node scripts/build-pages.mjs"
   }
 }