@kahwee/sf-map-svg 0.3.0 → 1.0.0

package/dist/src/geometry.d.ts

@@ -0,0 +1,5 @@
+import type { Geometry, Position } from '../data/types.js';
+export type Project = (position: Position) => [number, number];
+export declare function rawProject([longitude, latitude]: Position): [number, number];
+export declare function positions(geometry: Geometry | null | undefined): Position[];
+export declare function geometryPath(geometry: Geometry | null | undefined, project: Project): string;

package/dist/src/geometry.js

@@ -0,0 +1,53 @@
+const number = (value) => Number(value.toFixed(2));
+export function rawProject([longitude, latitude]) {
+    if (!Number.isFinite(longitude) ||
+        Math.abs(longitude) > 180 ||
+        !Number.isFinite(latitude) ||
+        Math.abs(latitude) >= 90)
+        throw new RangeError('Coordinates must be finite [longitude, latitude], with longitude from -180 to 180 and latitude strictly between -90 and 90.');
+    const point = [
+        (longitude * Math.PI) / 180,
+        -Math.log(Math.tan(Math.PI / 4 + (latitude * Math.PI) / 360)),
+    ];
+    if (!point.every(Number.isFinite))
+        throw new RangeError('Coordinates are too close to a pole for Mercator projection.');
+    return point;
+}
+export function positions(geometry) {
+    if (!geometry)
+        return [];
+    switch (geometry.type) {
+        case 'Point':
+            return [geometry.coordinates];
+        case 'LineString':
+        case 'MultiPoint':
+            return [...geometry.coordinates];
+        case 'Polygon':
+        case 'MultiLineString':
+            return geometry.coordinates.flat();
+        case 'MultiPolygon':
+            return geometry.coordinates.flat(2);
+        case 'GeometryCollection':
+            return geometry.geometries.flatMap(positions);
+    }
+}
+export function geometryPath(geometry, project) {
+    if (!geometry)
+        return '';
+    const line = (ring) => ring.map((p, i) => `${i ? 'L' : 'M'}${project(p).map(number).join(',')}`).join('');
+    const polygon = (rings) => rings.map((ring) => `${line(ring)}Z`).join('');
+    switch (geometry.type) {
+        case 'Polygon':
+            return polygon(geometry.coordinates);
+        case 'MultiPolygon':
+            return geometry.coordinates.map(polygon).join('');
+        case 'LineString':
+            return line(geometry.coordinates);
+        case 'MultiLineString':
+            return geometry.coordinates.map(line).join('');
+        case 'GeometryCollection':
+            return geometry.geometries.map((g) => geometryPath(g, project)).join('');
+        default:
+            return '';
+    }
+}

package/dist/src/immutable.d.ts

@@ -0,0 +1,2 @@
+/** Freeze shared geographic objects so a consumer cannot change later renders. */
+export declare function deepFreeze<T>(value: T): T;

package/dist/src/immutable.js

@@ -0,0 +1,9 @@
+/** Freeze shared geographic objects so a consumer cannot change later renders. */
+export function deepFreeze(value) {
+    if (value && typeof value === 'object' && !Object.isFrozen(value)) {
+        for (const child of Object.values(value))
+            deepFreeze(child);
+        Object.freeze(value);
+    }
+    return value;
+}

package/dist/src/index.d.ts

@@ -0,0 +1,13 @@
+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[];
+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];
+    viewBox: [number, number, number, number];
+};
+export declare function renderSFMap(options?: SFMapOptions): string;

package/dist/src/index.js

@@ -0,0 +1,125 @@
+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]);
+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 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],
+    };
+}
+export function renderSFMap(options = {}) {
+    return createSFMap(options).svg;
+}

package/dist/src/interactive.d.ts

@@ -0,0 +1,4 @@
+import type { NeighborhoodExplorerOptions } from './types.js';
+export type { InteractiveLayers, 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/interactive.js

@@ -0,0 +1,5 @@
+import { createNeighborhoodExplorer } from './explorer.js';
+/** Reusable browser map; plain basemap by default, no editorial UI or URL changes. */
+export function createInteractiveSFMap(options = {}) {
+    return createNeighborhoodExplorer({ mode: 'basemap', ...options, interface: 'map' });
+}

package/dist/src/layers.d.ts

@@ -0,0 +1,36 @@
+import type { Geometry } from '../data/types.js';
+import type { DistrictRow } from './data.js';
+import type { Project } from './geometry.js';
+import type { BartStation, KeyRoad, Landmark } from './overlays.js';
+import type { MapMarker, SFMapOptions } from './types.js';
+interface LayerContext {
+    labels: boolean;
+    theme: NonNullable<SFMapOptions['theme']>;
+    idPrefix: string;
+    colors: Required<NonNullable<SFMapOptions['colors']>>;
+    project: Project;
+    path: (geometry: Geometry | null | undefined) => string;
+}
+interface DistrictPath {
+    id: number;
+    path: string;
+    color: string;
+}
+export declare function districtFills(districts: readonly DistrictPath[], { idPrefix }: LayerContext): string;
+export declare function districtLines(districts: readonly DistrictPath[], { idPrefix, colors }: LayerContext): string;
+export declare function landmarks(items: readonly Landmark[], { idPrefix, path, colors }: LayerContext): string;
+export declare function highways(items: readonly {
+    route: string;
+    geometry: Geometry;
+}[], { path, colors, theme }: LayerContext): string;
+export declare function neighborhoods(items: readonly {
+    name: string;
+    geometry: Geometry;
+}[], { idPrefix, path, colors }: LayerContext): string;
+export declare function districtLabels(districts: readonly DistrictRow[], { project, colors }: LayerContext): string;
+export declare function landmarkLabels(items: readonly Landmark[], { project, colors }: LayerContext): string;
+export declare function bartStations(items: readonly BartStation[], { project, colors, labels }: LayerContext): string;
+export declare function markers(items: readonly MapMarker[], { project, colors }: LayerContext): string;
+export declare function keyRoads(items: readonly KeyRoad[], { idPrefix, path, colors }: LayerContext): string;
+export declare function keyRoadLabels(items: readonly KeyRoad[], { project }: LayerContext): string;
+export {};

package/dist/src/layers.js

@@ -0,0 +1,64 @@
+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>`;
+}
+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>`;
+}
+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>`;
+}
+export function highways(items, { path, colors, theme }) {
+    return `<g data-layer="highways">${items.map((road) => `<path data-route="${escapeXml(road.route)}" d="${path(road.geometry)}" ${stroke(colors.highway, theme === 'transit' ? 2 : 1.4)}/>`).join('')}</g>`;
+}
+export function neighborhoods(items, { idPrefix, path, colors }) {
+    return `<g data-layer="neighborhood-lines" clip-path="url(#${idPrefix}-coast)">${items.map((n) => `<path data-neighborhood="${escapeXml(n.name)}" d="${path(n.geometry)}" ${stroke(colors.neighborhood, 0.65)} stroke-dasharray="2 2"><title>${escapeXml(n.name)}</title></path>`).join('')}</g>`;
+}
+export function districtLabels(districts, { project, colors }) {
+    // Primary badges first, then island badges, matching the original layer order.
+    const labels = [
+        ...districts.map((d) => ({ id: d.id, label: d.labelPoints[0] })),
+        ...districts.flatMap((d) => d.labelPoints.slice(1).map((label) => ({ id: d.id, label }))),
+    ];
+    return `<g data-layer="district-labels" font-family="system-ui,sans-serif" font-size="12" font-weight="600" text-anchor="middle" fill="${escapeXml(colors.label)}">${labels
+        .map((d) => {
+        const [x, y] = project(d.label).map(number);
+        return `<g transform="translate(${x},${y})"><circle r="10" fill="#ffffff" fill-opacity=".9"/><text dy=".35em">${d.id}</text></g>`;
+    })
+        .join('')}</g>`;
+}
+export function landmarkLabels(items, { project, colors }) {
+    return `<g data-layer="landmark-labels" ${overlayLabel} fill="${escapeXml(colors.landmark)}">${items
+        .map((item) => {
+        const [x, y] = project(item.label);
+        return `<text x="${number(x + item.offset[0])}" y="${number(y + item.offset[1])}" text-anchor="${escapeXml(item.anchor)}" dominant-baseline="middle">${escapeXml(item.name)}</text>`;
+    })
+        .join('')}</g>`;
+}
+export function bartStations(items, { project, colors, labels }) {
+    return `<g data-layer="bart-stations">${items
+        .map((station) => {
+        const [x, y] = project(station.coordinates).map(number);
+        return `<g data-bart-station="${escapeXml(station.id)}" transform="translate(${x},${y})"><title>${escapeXml(station.name)} BART station</title><circle r="5" fill="#fff" stroke="${escapeXml(colors.bart)}" stroke-width="2.5"/><circle r="1.5" fill="${escapeXml(colors.bart)}"/>${labels ? `<text x="10" y="4" ${overlayLabel} fill="${escapeXml(colors.bart)}">${escapeXml(station.name)}</text>` : ''}</g>`;
+    })
+        .join('')}</g>`;
+}
+export function markers(items, { project, colors }) {
+    return `<g data-layer="markers">${items
+        .map((marker) => {
+        const [x, y] = project([marker.lng, marker.lat]).map(number);
+        return `<circle data-marker-id="${escapeXml(marker.id)}" cx="${x}" cy="${y}" r="${marker.selected ? 8 : 5}" fill="${escapeXml(marker.color ?? (marker.selected ? colors.selected : colors.marker))}" stroke="#fff9e9" stroke-width="2" vector-effect="non-scaling-stroke"><title>${escapeXml(marker.label ?? marker.id)}</title></circle>`;
+    })
+        .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>`;
+}
+export function keyRoadLabels(items, { project }) {
+    return `<g data-layer="key-road-labels" ${overlayLabel} fill="#77736b">${items
+        .map((road) => {
+        const [x, y] = project(road.label);
+        return `<text x="${number(x)}" y="${number(y - 5)}" text-anchor="middle">${escapeXml(road.name)}</text>`;
+    })
+        .join('')}</g>`;
+}

package/dist/src/navigation.d.ts

@@ -0,0 +1,6 @@
+import type { MapViewport } from './types.js';
+/** DOM navigation owns no content, selection, history, or application controls. */
+export declare function attachNavigation(svg: SVGSVGElement, getView: () => MapViewport, setView: (view: MapViewport) => void, signal: AbortSignal, onExit: () => void): {
+    cancel: () => void;
+    setTouchNavigation(value: boolean): void;
+};

package/dist/src/navigation.js

@@ -0,0 +1,145 @@
+/** DOM navigation owns no content, selection, history, or application controls. */
+export function attachNavigation(svg, getView, setView, signal, onExit) {
+    let engaged = false;
+    let moved = false;
+    let skipClick = false;
+    const pointers = new Map();
+    let start;
+    const listen = (target, type, handler, options = {}) => target.addEventListener(type, handler, { ...options, signal });
+    function rebase() {
+        start = pointers.size ? { points: [...pointers.values()], view: getView() } : undefined;
+    }
+    function cancel() {
+        for (const id of pointers.keys()) {
+            if (svg.hasPointerCapture(id))
+                svg.releasePointerCapture(id);
+        }
+        pointers.clear();
+        start = undefined;
+        if (moved)
+            skipClick = true;
+        moved = false;
+    }
+    function zoom(factor) {
+        const [x, y, size] = getView();
+        const next = Math.max(800 / 12, Math.min(800, size / factor));
+        setView([x + (size - next) / 2, y + (size - next) / 2, next]);
+    }
+    listen(svg, 'pointerdown', (event) => {
+        if (event.button !== 0 || (event.pointerType === 'touch' && !engaged))
+            return;
+        if (!pointers.size) {
+            moved = false;
+            skipClick = false;
+        }
+        pointers.set(event.pointerId, { x: event.clientX, y: event.clientY });
+        rebase();
+    });
+    listen(window, 'pointermove', (event) => {
+        if (!pointers.has(event.pointerId) || !start)
+            return;
+        pointers.set(event.pointerId, { x: event.clientX, y: event.clientY });
+        const points = [...pointers.values()];
+        const midpoint = (p) => p.length > 1 ? { x: (p[0].x + p[1].x) / 2, y: (p[0].y + p[1].y) / 2 } : p[0];
+        const a = midpoint(start.points), b = midpoint(points);
+        const distance = (p) => Math.hypot(p[1].x - p[0].x, p[1].y - p[0].y);
+        const ratio = points.length > 1 && start.points.length > 1
+            ? distance(points) / Math.max(1, distance(start.points))
+            : 1;
+        if (Math.hypot(b.x - a.x, b.y - a.y) > 4 || Math.abs(ratio - 1) > 0.02)
+            moved = true;
+        if (!moved)
+            return;
+        if (!svg.hasPointerCapture(event.pointerId))
+            svg.setPointerCapture(event.pointerId);
+        const box = svg.getBoundingClientRect();
+        if (!box.width)
+            return;
+        const [x, y, size] = start.view;
+        const next = Math.max(800 / 12, Math.min(800, size / Math.max(0.01, ratio)));
+        setView([
+            x + ((a.x - box.left) * size) / box.width - ((b.x - box.left) * next) / box.width,
+            y + ((a.y - box.top) * size) / box.width - ((b.y - box.top) * next) / box.width,
+            next,
+        ]);
+    });
+    const release = (event) => {
+        if (!pointers.has(event.pointerId))
+            return;
+        pointers.delete(event.pointerId);
+        if (moved)
+            skipClick = true;
+        if (svg.hasPointerCapture(event.pointerId))
+            svg.releasePointerCapture(event.pointerId);
+        rebase();
+    };
+    listen(window, 'pointerup', release);
+    listen(window, 'pointercancel', (event) => {
+        if (pointers.has(event.pointerId))
+            cancel();
+    });
+    listen(svg, 'lostpointercapture', (event) => {
+        // Touch starts with implicit capture on the hit path. Its release during
+        // transfer to the SVG must not cancel the newly captured gesture.
+        if (event.target === svg)
+            release(event);
+    });
+    listen(window, 'blur', cancel);
+    listen(svg, 'click', (event) => {
+        if (skipClick && event.detail !== 0) {
+            skipClick = false;
+            event.preventDefault();
+            event.stopImmediatePropagation();
+        }
+    }, { capture: true });
+    listen(svg, 'keydown', (event) => {
+        if (event.altKey || event.ctrlKey || event.metaKey)
+            return;
+        const [x, y, size] = getView();
+        const step = size / 8;
+        switch (event.key) {
+            case 'ArrowLeft':
+                setView([x - step, y, size]);
+                break;
+            case 'ArrowRight':
+                setView([x + step, y, size]);
+                break;
+            case 'ArrowUp':
+                setView([x, y - step, size]);
+                break;
+            case 'ArrowDown':
+                setView([x, y + step, size]);
+                break;
+            case '+':
+            case '=':
+                zoom(1.5);
+                break;
+            case '-':
+                zoom(1 / 1.5);
+                break;
+            case 'Home':
+                setView([0, 0, 800]);
+                break;
+            case 'Escape':
+                onExit();
+                break;
+            default:
+                return;
+        }
+        event.preventDefault();
+    });
+    listen(svg, 'wheel', (event) => {
+        if (!event.ctrlKey && !event.metaKey)
+            return;
+        event.preventDefault();
+        zoom(Math.exp(-Math.max(-100, Math.min(100, event.deltaY)) / 300));
+    }, { passive: false });
+    signal.addEventListener('abort', cancel, { once: true });
+    return {
+        cancel,
+        setTouchNavigation(value) {
+            cancel();
+            engaged = value;
+        },
+    };
+}

package/dist/src/overlays.d.ts

@@ -0,0 +1,25 @@
+import type { Position } from '../data/types.js';
+export declare const landmarks: {
+    name: string;
+    label: Position;
+    offset: readonly [number, number];
+    anchor: 'middle' | 'start' | 'end';
+    id: string;
+    geometry: import("../data/types.js").Geometry;
+}[];
+export declare const bartStations: {
+    id: string;
+    name: string;
+    coordinates: Position;
+}[];
+export type Landmark = (typeof landmarks)[number];
+export type BartStation = (typeof bartStations)[number];
+export declare const keyRoads: {
+    name: string;
+    sourceNames: readonly string[];
+    label: Position;
+    segmentIds: readonly string[];
+    id: string;
+    geometry: import("../data/types.js").Geometry;
+}[];
+export type KeyRoad = (typeof keyRoads)[number];

package/dist/src/overlays.js

@@ -0,0 +1,15 @@
+import stationData from '../data/bart-stations.json' with { type: 'json' };
+import roadData from '../data/key-roads.json' with { type: 'json' };
+import parkData from '../data/landmarks.json' with { type: 'json' };
+import { deepFreeze } from './immutable.js';
+export const landmarks = deepFreeze(parkData.features.map(({ id, properties, geometry }) => ({
+    id,
+    ...properties,
+    geometry,
+})));
+export const bartStations = deepFreeze(stationData.features.map(({ id, properties, geometry }) => ({
+    id,
+    name: properties.name,
+    coordinates: geometry.coordinates,
+})));
+export const keyRoads = deepFreeze(roadData.features.map(({ id, properties, geometry }) => ({ id, ...properties, geometry })));

package/dist/src/svg.d.ts

@@ -0,0 +1,4 @@
+export declare const escapeXml: (value: unknown) => string;
+export declare const number: (value: number) => number;
+export declare const stroke: (color: string, weight: number) => string;
+export declare const overlayLabel = "font-family=\"system-ui,sans-serif\" font-size=\"12\" font-weight=\"600\" stroke=\"#f8faf4\" stroke-width=\"3\" stroke-linejoin=\"round\" paint-order=\"stroke\"";

package/dist/src/svg.js

@@ -0,0 +1,7 @@
+export const escapeXml = (value) => String(value)
+    // biome-ignore lint/suspicious/noControlCharactersInRegex: XML 1.0 forbids these control characters.
+    .replace(/[\u0000-\u0008\u000B\u000C\u000E-\u001F\uFFFE\uFFFF]/g, '')
+    .replace(/[&<>"']/g, (char) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[char] ?? char);
+export const number = (value) => Number(value.toFixed(2));
+export const stroke = (color, weight) => `fill="none" stroke="${escapeXml(color)}" stroke-width="${weight}" stroke-linejoin="round" stroke-linecap="round" vector-effect="non-scaling-stroke"`;
+export const overlayLabel = 'font-family="system-ui,sans-serif" font-size="12" font-weight="600" stroke="#f8faf4" stroke-width="3" stroke-linejoin="round" paint-order="stroke"';

package/dist/src/types.d.ts

@@ -0,0 +1,108 @@
+import type { Geometry, NeighborhoodFeature, NeighborhoodSource } from '../data/types.js';
+export type DistrictYear = 2002 | 2012 | 2022;
+export interface MapMarker {
+    id: string;
+    lng: number;
+    lat: number;
+    label?: string;
+    selected?: boolean;
+    color?: string;
+}
+export interface SFMapOptions {
+    theme?: 'districts' | 'transit';
+    width?: number;
+    height?: number;
+    padding?: number;
+    year?: DistrictYear;
+    districtLines?: boolean;
+    neighborhoodLines?: boolean;
+    districtFills?: boolean;
+    districtLabels?: boolean;
+    /** Hide all visible text labels while retaining geographic symbols and accessible titles. */
+    labels?: boolean;
+    highways?: boolean;
+    keyRoads?: boolean;
+    landmarks?: boolean;
+    bartStations?: boolean;
+    markers?: MapMarker[];
+    title?: string;
+    idPrefix?: string;
+    colors?: Partial<Record<'water' | 'land' | 'district' | 'neighborhood' | 'highway' | 'road' | 'park' | 'landmark' | 'bart' | 'label' | 'marker' | 'selected', string>>;
+}
+/** Serializable viewport in the interactive map's fixed 800 × 800 projected space. */
+export type MapViewport = readonly [x: number, y: number, size: number];
+export type ExplorerMode = 'neighborhoods' | 'districts' | 'basemap';
+export interface MapPadding {
+    top?: number;
+    right?: number;
+    bottom?: number;
+    left?: number;
+}
+export interface InteractiveLayers {
+    districtFills?: boolean;
+    districtLines?: boolean;
+    districtLabels?: boolean;
+    neighborhoodLines?: boolean;
+    neighborhoodLabels?: boolean;
+    landmarks?: boolean;
+    bartStations?: boolean;
+    highways?: boolean;
+    keyRoads?: boolean;
+}
+export interface NeighborhoodSelection {
+    id: string;
+    name: string;
+    source: NeighborhoodSource;
+    feature: NeighborhoodFeature;
+}
+export interface NeighborhoodExplorerOptions {
+    mode?: ExplorerMode;
+    labels?: boolean;
+    source?: NeighborhoodSource;
+    neighborhood?: string;
+    year?: DistrictYear;
+    theme?: SFMapOptions['theme'];
+    /** Explorer chrome or the reusable map with only controls and attribution. */
+    interface?: 'explorer' | 'map';
+    /** Independent overrides; omitted layers follow mode defaults. */
+    layers?: InteractiveLayers;
+    selectableNeighborhoods?: boolean;
+    /** Screen pixels; defaults preserve 11px roads / 12px other labels. */
+    labelSize?: {
+        min?: number;
+        max?: number;
+    };
+    /** Screen-pixel space reserved when fitting geometry. */
+    fitPadding?: number | MapPadding;
+    markers?: readonly MapMarker[];
+    /** Screen pixels, independent of zoom. */
+    markerRadius?: number;
+    markerHitSize?: number;
+    markerColor?: string;
+    selectedMarkerColor?: string;
+    onMarkerActivate?: (marker: MapMarker) => void;
+}
+export interface NeighborhoodExplorerElement extends HTMLElement {
+    selectNeighborhood(name: string | null, options?: {
+        fit?: boolean;
+    }): boolean;
+    getSelection(): NeighborhoodSelection | null;
+    setSource(source: NeighborhoodSource): void;
+    setMode(mode: ExplorerMode): void;
+    setLabels(visible: boolean): void;
+    resetView(): void;
+    zoomBy(factor: number): void;
+    panBy(x: number, y: number): void;
+    getViewport(): MapViewport;
+    setViewport(view: MapViewport): void;
+    /** Fit WGS84 geometry, including Point, MultiPoint, or a GeometryCollection. */
+    fitGeometry(geometry: Geometry, padding?: number | MapPadding): void;
+    /** Explicitly engage map touch gestures; false restores page gestures. */
+    setTouchNavigation(enabled: boolean): void;
+    setMarkers(markers: readonly MapMarker[]): void;
+    selectMarker(id: string | null, options?: {
+        fit?: boolean;
+    }): boolean;
+    getSelectedMarker(): MapMarker | null;
+    destroy(): void;
+}

package/dist/src/types.js

@@ -0,0 +1 @@
+export {};