@kahwee/sf-map-svg 4.5.0 → 5.1.0

package/dist/data/precincts.d.ts

@@ -0,0 +1,2 @@
+import type { FeatureCollection, PrecinctProperties } from './types.js';
+export declare const precinctMaps: Readonly<Record<2022, FeatureCollection<PrecinctProperties>>>;

package/dist/data/precincts.js

@@ -0,0 +1,5 @@
+import { deepFreeze } from '../src/immutable.js';
+import precincts2022 from './precincts-2022.json' with { type: 'json' };
+export const precinctMaps = deepFreeze({
+    2022: precincts2022,
+});

package/dist/data/types.d.ts

@@ -93,6 +93,11 @@ export interface DistrictProperties {
     readonly labelPoints: readonly Position[];
     readonly displayExtras: Geometry | null;
 }
+export interface PrecinctProperties {
+    /** Four-digit Department of Elections precinct number, such as "1101". */
+    readonly precinct: string;
+    readonly year: 2022;
+}
 export interface Catalog {
     readonly schemaVersion: 1;
     readonly description: string;

package/dist/src/cards.js

@@ -44,7 +44,7 @@ export function bindMapCards(map, root, options) {
         const marker = card && root.contains(card) ? markers.get(card.dataset.mapMarker ?? '') : undefined;
         if (!marker)
             return;
-        const point = map.projectToScreen(marker.lng, marker.lat);
+        const point = map.projectToScreen(marker.position);
         if (!point.visible)
             return;
         ring.style.left = `${point.x}px`;

package/dist/src/configuration.d.ts

@@ -2,6 +2,8 @@ import type { MapConfiguration, MapConfigurationSnapshot, MapOptions } from './c
 import type { NeighborhoodExplorerOptions } from './types.js';
 export declare function expandMapOptions(options: MapOptions): NeighborhoodExplorerOptions;
 type PresentationSnapshot = Pick<MapConfigurationSnapshot, 'features' | 'layers' | 'controls' | 'appearance'>;
+/** Public v5 patches consistently ignore undefined at every record depth. */
+export declare function configurationPatch(patch: MapConfiguration, current?: Partial<MapConfiguration>): MapConfiguration;
 /** Prepare the entire configuration before any DOM mutation. */
 export declare function prepareConfiguration(current: PresentationSnapshot, patch: MapConfiguration): PresentationSnapshot;
 export {};

package/dist/src/configuration.js

@@ -44,6 +44,36 @@ export function expandMapOptions(options) {
     validateExplorerOptions(expanded);
     return expanded;
 }
+/** Public v5 patches consistently ignore undefined at every record depth. */
+export function configurationPatch(patch, current = {}) {
+    assertOptions(patch, 'configuration', [
+        'features',
+        'layers',
+        'controls',
+        'appearance',
+        'mode',
+        'source',
+        'year',
+        'labels',
+    ]);
+    const clean = (value, previous, depth) => {
+        if (!value || typeof value !== 'object' || Array.isArray(value))
+            return value;
+        const prior = previous && typeof previous === 'object' && !Array.isArray(previous)
+            ? previous
+            : {};
+        return {
+            ...(depth >= 2 ? prior : {}),
+            ...Object.fromEntries(Object.entries(value)
+                .filter(([, entry]) => entry !== undefined || depth > 0)
+                .map(([key, entry]) => [
+                key,
+                clean(entry === undefined ? prior[key] : entry, prior[key], depth + 1),
+            ])),
+        };
+    };
+    return clean(patch, current, 0);
+}
 /** Prepare the entire configuration before any DOM mutation. */
 export function prepareConfiguration(current, patch) {
     assertOptions(patch, 'configuration', [

package/dist/src/controller-types.d.ts

@@ -1,6 +1,6 @@
 import type { Geometry, NeighborhoodSource } from '../data/types.js';
-import type { CameraOptions, DistrictSelection, DistrictStyle, DistrictYear, InteractiveLayers, MapFeatures, MapMarker, MapOverlay, MapPadding, MapViewport, NeighborhoodExplorerOptions, NeighborhoodSelection } from './types.js';
-/** Patch properties can explicitly remove overrides, including with exactOptionalPropertyTypes. */
+import type { CameraOptions, DistrictSelection, DistrictStyle, DistrictYear, InteractiveLayers, MapFeatures, MapMarker, MapOverlay, MapPadding, MapViewport, NeighborhoodExplorerOptions, NeighborhoodSelection, ProjectToScreen } from './types.js';
+/** Explicit undefined is accepted as a no-op, including with exactOptionalPropertyTypes. */
 type Resettable<T> = {
     [K in keyof T]?: T[K] | undefined;
 };
@@ -9,7 +9,7 @@ export type MapAppearance = {
     [K in keyof AppearanceOptions]?: K extends 'colors' | 'style' | 'labelStyle' | 'labelSize' | 'areaStyle' ? Resettable<NonNullable<AppearanceOptions[K]>> | undefined : AppearanceOptions[K] | undefined;
 };
 export type MapControls = NonNullable<NeighborhoodExplorerOptions['controls']>;
-/** Omitted keys retain values. Undefined presentation groups reset; undefined mode/source/year/labels retain their current value. */
+/** Omitted and undefined values retain current values. Use resetConfiguration to clear overrides. */
 export interface MapConfiguration {
     features?: Resettable<MapFeatures> | undefined;
     layers?: Resettable<InteractiveLayers> | undefined;
@@ -115,10 +115,7 @@ export interface MapEvents {
     };
     mapresize: undefined;
 }
-/** Convenience setters retain their historic reset default; false preserves the camera. */
-export interface MapViewUpdateOptions {
-    resetView?: boolean;
-}
+export type MapConfigurationGroup = 'features' | 'layers' | 'controls' | 'appearance';
 export interface MapCamera {
     /** Fixed 800 × 800 projected space, not longitude/latitude. */
     get(): MapViewport;
@@ -139,6 +136,8 @@ export interface MapController {
     readonly camera: MapCamera;
     readonly destroyed: boolean;
     configure(patch: MapConfiguration): void;
+    /** Clear presentation overrides to built-in defaults, preserving camera and geographic choices. */
+    resetConfiguration(groups?: readonly MapConfigurationGroup[]): void;
     getConfiguration(): MapConfigurationSnapshot;
     getResolvedConfiguration(): ResolvedMapConfiguration;
     getCapabilities(): MapCapabilities;
@@ -154,7 +153,7 @@ export interface MapController {
         fit?: boolean;
     }): boolean;
     getSelectedMarker(): MapMarker | null;
-    selectNeighborhood(name: string | null, options?: CameraOptions & {
+    selectNeighborhood(id: string | null, options?: CameraOptions & {
         fit?: boolean;
     }): boolean;
     getSelectedNeighborhood(): NeighborhoodSelection | null;
@@ -164,15 +163,12 @@ export interface MapController {
     getSelectedDistrict(): DistrictSelection | null;
     setDistrictYear(year: DistrictYear, options?: CameraOptions): void;
     setDistrictStyle(style: ((district: DistrictSelection['district']) => DistrictStyle) | undefined): void;
-    setSource(source: NeighborhoodSource, options?: MapViewUpdateOptions): void;
-    setMode(mode: NonNullable<MapOptions['mode']>, options?: MapViewUpdateOptions): void;
+    setSource(source: NeighborhoodSource): void;
+    setMode(mode: NonNullable<MapOptions['mode']>): void;
     setLabels(visible: boolean): void;
     setTouchNavigation(enabled: boolean): void;
-    projectToScreen(lng: number, lat: number): {
-        x: number;
-        y: number;
-        visible: boolean;
-    };
+    /** Accepts a GeoJSON position; returns canvas-relative CSS pixels. */
+    projectToScreen: ProjectToScreen;
     /** Idempotent; stops work and managed subscriptions. Does not remove host-owned DOM. */
     destroy(): void;
 }

package/dist/src/explorer-core.js

@@ -140,8 +140,10 @@ export function createNeighborhoodExplorerCore(options = {}, data, ui) {
         arrow.hidden = !features.northArrow;
     }
     syncFurniture();
-    function projectToScreen(lng, lat) {
-        const [x, y] = map.project([lng, lat]);
+    function projectToScreen(position) {
+        if (!Array.isArray(position) || position.length < 2)
+            throw new RangeError('Expected a [longitude, latitude] position.');
+        const [x, y] = map.project(position);
         const width = canvas.getBoundingClientRect().width;
         if (!width)
             throw new Error('Mount the map before projecting to screen.');
@@ -510,7 +512,10 @@ export function createNeighborhoodExplorerCore(options = {}, data, ui) {
     const clusters = createClusterLayer(svg, markerLayer, clusterLayer, markerNavigation, materializeMarker, (group, node, signal) => {
         if (destroyed || signal.aborted)
             return;
-        const markers = group.map((item) => ({ ...item.marker }));
+        const markers = group.map((item) => ({
+            ...item.marker,
+            position: [...item.marker.position],
+        }));
         const minimumUnit = 800 / 12 / Math.max(1, canvas.getBoundingClientRect().width);
         if (clusterPoints(group, minimumUnit, features.clustering ? features.clustering.radius : 36)
             .length === 1)
@@ -518,7 +523,7 @@ export function createNeighborhoodExplorerCore(options = {}, data, ui) {
         else
             fitGeometry({
                 type: 'MultiPoint',
-                coordinates: markers.map((marker) => [marker.lng, marker.lat]),
+                coordinates: markers.map((marker) => marker.position),
             });
         if (!destroyed && !signal.aborted)
             root.dispatchEvent(new CustomEvent('clusteractivate', { bubbles: true, detail: { markers } }));
@@ -866,7 +871,7 @@ export function createNeighborhoodExplorerCore(options = {}, data, ui) {
     }
     function getSelectedMarker() {
         const marker = markerCatalog.items.find((item) => item.marker.id === selectedMarker)?.marker;
-        return marker ? { ...marker } : null;
+        return marker ? { ...marker, position: [...marker.position] } : null;
     }
     function selectMarker(id, options = {}) {
         if (destroyed)

package/dist/src/geometry.d.ts

@@ -1,5 +1,10 @@
-import type { Geometry, Position } from '../data/types.js';
+import type { Bounds, Geometry, Position } from '../data/types.js';
+export type { Bounds, 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;
+/** Geographic [west, south, east, north], or null for empty geometry. */
+export declare function geometryBounds(geometry: Geometry | null | undefined): Bounds | null;
+/** Polygon hit testing in longitude/latitude; boundaries (including hole edges) count as hits. */
+export declare function geometryContainsPoint(geometry: Geometry | null | undefined, point: Position): boolean;

package/dist/src/geometry.js

@@ -51,3 +51,83 @@ export function geometryPath(geometry, project) {
             return '';
     }
 }
+function validatePosition(point) {
+    if (!Number.isFinite(point[0]) ||
+        !Number.isFinite(point[1]) ||
+        Math.abs(point[0]) > 180 ||
+        Math.abs(point[1]) > 90)
+        throw new RangeError('Expected finite longitude/latitude within [-180, 180] and [-90, 90].');
+}
+/** Geographic [west, south, east, north], or null for empty geometry. */
+export function geometryBounds(geometry) {
+    let west = Infinity;
+    let south = Infinity;
+    let east = -Infinity;
+    let north = -Infinity;
+    for (const point of positions(geometry)) {
+        validatePosition(point);
+        west = Math.min(west, point[0]);
+        south = Math.min(south, point[1]);
+        east = Math.max(east, point[0]);
+        north = Math.max(north, point[1]);
+    }
+    return west === Infinity ? null : [west, south, east, north];
+}
+// 0 outside, 1 inside, 2 on an edge. Rings may be explicitly or implicitly closed.
+function ringLocation(point, ring) {
+    if (ring.length < 3)
+        return 0;
+    let inside = false;
+    const [x, y] = point;
+    for (let i = 0, j = ring.length - 1; i < ring.length; j = i++) {
+        const [ax, ay] = ring[j];
+        const [bx, by] = ring[i];
+        const cross = (x - ax) * (by - ay) - (y - ay) * (bx - ax);
+        if (cross === 0 &&
+            x >= Math.min(ax, bx) &&
+            x <= Math.max(ax, bx) &&
+            y >= Math.min(ay, by) &&
+            y <= Math.max(ay, by))
+            return 2;
+        if (ay > y !== by > y && x < ((bx - ax) * (y - ay)) / (by - ay) + ax)
+            inside = !inside;
+    }
+    return inside ? 1 : 0;
+}
+/** Polygon hit testing in longitude/latitude; boundaries (including hole edges) count as hits. */
+export function geometryContainsPoint(geometry, point) {
+    validatePosition(point);
+    // Validate the entire input, including parts not reached by the hit test.
+    geometryBounds(geometry);
+    const polygonContains = (rings) => {
+        if (!rings.length)
+            return false;
+        const outer = ringLocation(point, rings[0]);
+        if (outer === 0)
+            return false;
+        if (outer === 2)
+            return true;
+        let inHole = false;
+        for (const ring of rings.slice(1)) {
+            const location = ringLocation(point, ring);
+            if (location === 2)
+                return true;
+            if (location === 1)
+                inHole = true;
+        }
+        return !inHole;
+    };
+    const contains = (part) => {
+        switch (part.type) {
+            case 'Polygon':
+                return polygonContains(part.coordinates);
+            case 'MultiPolygon':
+                return part.coordinates.some(polygonContains);
+            case 'GeometryCollection':
+                return part.geometries.some(contains);
+            default:
+                return false;
+        }
+    };
+    return geometry ? contains(geometry) : false;
+}

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

@@ -2,7 +2,7 @@ import type { SFMapOptions } from './types.js';
 /** Server-safe overview using exactly the guide browser geography. */
 export declare function createGuideSVG(options?: SFMapOptions): {
     svg: string;
-    project: (coordinates: import("../data/types.js").Position) => [number, number];
+    project: (coordinates: import("./geometry.js").Position) => [number, number];
     viewBox: [number, number, number, number];
 };
 /** Stable compact frame, progressively enhanced with mountGuideMap(). No browser globals. */

package/dist/src/layers.js

@@ -58,7 +58,7 @@ export function markers(items, { project, colors, animated }) {
         .map((marker, index) => {
         if (marker.radius !== undefined && (!Number.isFinite(marker.radius) || marker.radius <= 0))
             throw new RangeError('Marker radius must be positive and finite.');
-        const [x, y] = project([marker.lng, marker.lat]).map(number);
+        const [x, y] = project(marker.position).map(number);
         return `<circle data-marker-id="${escapeXml(marker.id)}" cx="${x}" cy="${y}" r="${marker.radius ?? (marker.selected ? 8 : 5)}" fill="${escapeXml(marker.color ?? (marker.selected ? colors.selected : colors.marker))}" stroke="#fff9e9" stroke-width="2" vector-effect="non-scaling-stroke"${order(animated, index)}><title>${escapeXml(marker.label ?? marker.id)}</title></circle>`;
     })
         .join('')}</g>`;

package/dist/src/map.d.ts

@@ -2,6 +2,6 @@ import type { MapController, MapOptions } from './controller-types.js';
 import type { InteractiveSFMapData } from './explorer-data.js';
 export type * from './controller-types.js';
 export type { InteractiveSFMapData as MapData } from './explorer-data.js';
-export type { CameraOptions, DistrictSelection, DistrictStyle, DistrictYear, InteractiveLayers, MapFeatures, MapMarker, MapOverlay, MapPadding, MapViewport, NeighborhoodSelection, } from './types.js';
+export type { CameraOptions, DistrictSelection, DistrictStyle, DistrictYear, InteractiveLayers, MapFeatures, MapMarker, MapOverlay, MapPadding, MapViewport, NeighborhoodSelection, ProjectToScreen, ScreenPoint, } from './types.js';
 /** No geography is imported. Supply a preset or your own immutable data. */
 export declare function createMap(data: InteractiveSFMapData, options?: MapOptions): MapController;

package/dist/src/map.js

@@ -1,6 +1,6 @@
 import { copyAppearance } from './appearance.js';
 import { validateCameraOptions } from './camera.js';
-import { expandMapOptions, prepareConfiguration } from './configuration.js';
+import { configurationPatch, expandMapOptions, prepareConfiguration } from './configuration.js';
 import { createNeighborhoodExplorerCore } from './explorer-core.js';
 import { createMapShell } from './explorer-shell.js';
 import { controlKeys, layerKeys } from './features.js';
@@ -144,13 +144,6 @@ export function createMap(data, options = {}) {
         }, () => !destroyed && revision === configurationRevision);
         return committed && !destroyed && revision === configurationRevision;
     }
-    function updateView(patch, options = {}) {
-        assertOptions(options, 'view update', ['resetView']);
-        if (options.resetView !== undefined && typeof options.resetView !== 'boolean')
-            throw new TypeError('resetView must be a boolean.');
-        if (configure(patch) && options.resetView !== false)
-            element.resetView();
-    }
     return Object.freeze({
         element,
         overlayElement: element.overlayElement,
@@ -159,7 +152,13 @@ export function createMap(data, options = {}) {
             return destroyed;
         },
         configure: use((patch) => {
-            configure(patch);
+            configure(configurationPatch(patch, config));
+        }),
+        resetConfiguration: use((groups = ['features', 'layers', 'controls', 'appearance']) => {
+            if (!Array.isArray(groups) ||
+                groups.some((key) => !['features', 'layers', 'controls', 'appearance'].includes(key)))
+                throw new TypeError('Unknown configuration reset group.');
+            configure(Object.fromEntries(groups.map((key) => [key, undefined])));
         }),
         getConfiguration: use(snapshot),
         getResolvedConfiguration: use(resolved),
@@ -231,7 +230,14 @@ export function createMap(data, options = {}) {
         }),
         selectMarker: use(element.selectMarker),
         getSelectedMarker: use(element.getSelectedMarker),
-        selectNeighborhood: use(element.selectNeighborhood),
+        selectNeighborhood: use((id, options) => {
+            const source = element.getMapState().source;
+            if (id !== null && (typeof id !== 'string' || !id))
+                throw new TypeError('Neighborhood IDs must be nonempty strings or null.');
+            if (id !== null && !data.neighborhoods[source]?.features.some((feature) => feature.id === id))
+                return false;
+            return element.selectNeighborhood(id, options);
+        }),
         getSelectedNeighborhood: use(element.getSelection),
         selectDistrict: use(element.selectDistrict),
         getSelectedDistrict: use(element.getSelectedDistrict),
@@ -242,8 +248,12 @@ export function createMap(data, options = {}) {
         setDistrictStyle: use((style) => {
             configure({ appearance: { districtStyle: style } });
         }),
-        setSource: use((source, options) => updateView({ source }, options)),
-        setMode: use((mode, options) => updateView({ mode }, options)),
+        setSource: use((source) => {
+            configure({ source });
+        }),
+        setMode: use((mode) => {
+            configure({ mode });
+        }),
         setLabels: use((labels) => {
             configure({ labels });
         }),

package/dist/src/marker-catalog.d.ts

@@ -1,7 +1,7 @@
 import type { createMarkerLayer, MarkerItem } from './marker-layer.js';
 import type { MapMarker } from './types.js';
 /** Own ordered records and picker reconciliation; prepare before committing DOM changes. */
-export declare function createMarkerCatalog(renderer: ReturnType<typeof createMarkerLayer>, picker: HTMLSelectElement, project: (point: [number, number]) => [number, number]): {
+export declare function createMarkerCatalog(renderer: ReturnType<typeof createMarkerLayer>, picker: HTMLSelectElement, project: (point: import('../data/types.js').Position) => [number, number]): {
     readonly items: MarkerItem[];
     prepare(markers: readonly MapMarker[], selected: string | null): {
         selection: string | null;

package/dist/src/marker-catalog.js

@@ -14,19 +14,25 @@ export function createMarkerCatalog(renderer, picker, project) {
             const next = markers.map((marker) => {
                 ids.add(marker.id);
                 const previous = existing.get(marker.id);
-                const point = previous?.marker.lng === marker.lng && previous.marker.lat === marker.lat
+                const point = previous?.marker.position[0] === marker.position[0] &&
+                    previous.marker.position[1] === marker.position[1]
                     ? previous.point
-                    : project([marker.lng, marker.lat]);
-                return { marker: { ...marker }, point };
+                    : project(marker.position);
+                return {
+                    marker: { ...marker, position: [...marker.position] },
+                    point,
+                };
             });
             const selection = selected && ids.has(selected)
                 ? selected
                 : (markers.find((marker) => marker.selected)?.id ?? null);
-            const keys = ['id', 'lng', 'lat', 'label', 'selected', 'color', 'radius'];
+            const keys = ['id', 'label', 'selected', 'color', 'radius'];
             if (picker.options.length > 0 &&
                 selection === selected &&
                 next.length === items.length &&
-                next.every(({ marker }, index) => keys.every((key) => marker[key] === items[index].marker[key])))
+                next.every(({ marker }, index) => marker.position.length === items[index].marker.position.length &&
+                    marker.position.every((value, offset) => value === items[index].marker.position[offset]) &&
+                    keys.every((key) => marker[key] === items[index].marker[key])))
                 return undefined;
             const focused = items.find((item) => item.visual?.node === document.activeElement)?.marker.id;
             return {

package/dist/src/static-labels.js

@@ -57,7 +57,7 @@ export function staticLabels(data, options, project) {
         selected: marker
             ? [
                 {
-                    point: point([marker.lng, marker.lat]),
+                    point: point(marker.position),
                     name: marker.label ?? marker.id,
                     kind: 'selected-marker',
                 },
@@ -96,7 +96,7 @@ export function staticLabels(data, options, project) {
             })
             : []),
         ...markers.map((item) => {
-            const [x, y] = point([item.lng, item.lat]);
+            const [x, y] = point(item.position);
             // Also cover the legacy SVG marker when it is larger than its interactive counterpart.
             const radius = Math.max(item.radius ?? 6, (item.radius ?? (item.selected ? 8 : 5)) / unit) + 3;
             return [x - radius, y - radius, x + radius, y + radius];
@@ -109,7 +109,7 @@ export function staticLabels(data, options, project) {
         textWidth: estimateLabelWidth(item.name, item.fontSize),
         textHeight: item.fontSize * 1.25,
     })), width, height, obstacles);
-    return `<g data-layer="overview-labels" font-family="system-ui,sans-serif">${spreadLabels(placed, options.labelLayout?.maxLabels, markers.map((marker) => point([marker.lng, marker.lat])), width, height)
+    return `<g data-layer="overview-labels" font-family="system-ui,sans-serif">${spreadLabels(placed, options.labelLayout?.maxLabels, markers.map((marker) => point(marker.position)), width, height)
         .map((item) => `<text data-label-kind="${escapeXml(item.kind)}" text-anchor="middle" x="${number((item.left + item.textWidth / 2) * unit)}" y="${number((item.top + item.fontSize) * unit)}" font-size="${number(item.fontSize * unit)}" font-weight="${item.fontWeight}" fill="${escapeXml(item.fill)}" stroke="${escapeXml(item.halo)}" stroke-width="${number(3 * unit)}" stroke-linejoin="round" paint-order="stroke">${escapeXml(item.name)}</text>`)
         .join('')}</g>`;
 }

package/dist/src/static.d.ts

@@ -8,14 +8,14 @@ export type { DistrictStyle, DistrictYear, SFMapOptions as StaticMapOptions, Sta
 /** Server-safe SVG rendering with explicit data; returns SVG plus projection helpers. */
 export declare function renderMap(data: StaticMapInput, options?: SFMapOptions): {
     svg: string;
-    project: (coordinates: import("../data/types.js").Position) => [number, number];
+    project: (coordinates: import("./geometry.js").Position) => [number, number];
     viewBox: [number, number, number, number];
 };
 /** Project canonical layer geometry without constructing an SVG string. */
 export declare function getLayerPaths(data: StaticMapInput, options?: SFMapOptions): {
     year: import("./types.js").DistrictYear;
     viewBox: [number, number, number, number];
-    project: (coordinates: import("../data/types.js").Position) => [number, number];
+    project: (coordinates: import("./geometry.js").Position) => [number, number];
     coast: string;
     districts: {
         id: number;

package/dist/src/types.d.ts

@@ -1,4 +1,12 @@
-import type { Geometry, NeighborhoodFeature, NeighborhoodSource } from '../data/types.js';
+import type { Geometry, NeighborhoodFeature, NeighborhoodSource, Position } from '../data/types.js';
+/** Canvas-relative CSS pixels; visibility means inside the current square map viewport. */
+export interface ScreenPoint {
+    x: number;
+    y: number;
+    visible: boolean;
+}
+/** WGS84 longitude/latitude; altitude, if supplied in a position, is ignored. */
+export type ProjectToScreen = (position: Position) => ScreenPoint;
 export type DistrictYear = 2002 | 2012 | 2022;
 export interface DistrictSelection {
     id: number;
@@ -12,8 +20,7 @@ export interface DistrictStyle {
 }
 export interface MapMarker {
     id: string;
-    lng: number;
-    lat: number;
+    position: Position;
     label?: string;
     selected?: boolean;
     color?: string;
@@ -220,11 +227,7 @@ export interface CameraOptions {
 export interface NeighborhoodExplorerElement extends HTMLElement {
     /** Append positioned HTML children here; coordinates are relative to this layer. */
     readonly overlayElement: HTMLDivElement;
-    projectToScreen(lng: number, lat: number): {
-        x: number;
-        y: number;
-        visible: boolean;
-    };
+    projectToScreen: ProjectToScreen;
     stopAnimation(): void;
     /** Atomic patch; false disables, undefined resets a feature to its default. */
     setFeatures(patch: MapFeatures): void;
@@ -268,4 +271,4 @@ export interface NeighborhoodExplorerElement extends HTMLElement {
 export interface TransitAnimationElement extends HTMLElement {
     destroy(): void;
 }
-export type { MapAppearance, MapCamera, MapCapabilities, MapConfiguration, MapConfigurationSnapshot, MapController, MapControls, MapEvents, MapFeatureReference, MapOptions, MapSelectionChange, MapViewUpdateOptions, ResolvedMapConfiguration, } from './controller-types.js';
+export type { MapAppearance, MapCamera, MapCapabilities, MapConfiguration, MapConfigurationGroup, MapConfigurationSnapshot, MapController, MapControls, MapEvents, MapFeatureReference, MapOptions, MapSelectionChange, ResolvedMapConfiguration, } from './controller-types.js';

package/dist/src/validation.js

@@ -155,14 +155,16 @@ export function validateMarkers(markers) {
         throw new TypeError('Markers must be an array.');
     const ids = new Set();
     for (const marker of markers) {
-        assertOptions(marker, 'marker');
+        assertOptions(marker, 'marker', ['id', 'position', 'label', 'selected', 'color', 'radius']);
         if (typeof marker.id !== 'string' || !marker.id || ids.has(marker.id))
             throw new RangeError('Markers require unique nonempty IDs.');
         ids.add(marker.id);
-        if (!Number.isFinite(marker.lng) ||
-            Math.abs(marker.lng) > 180 ||
-            !Number.isFinite(marker.lat) ||
-            Math.abs(marker.lat) >= 90)
+        if (!Array.isArray(marker.position) ||
+            marker.position.length < 2 ||
+            !Number.isFinite(marker.position[0]) ||
+            Math.abs(marker.position[0]) > 180 ||
+            !Number.isFinite(marker.position[1]) ||
+            Math.abs(marker.position[1]) >= 90)
             throw new RangeError('Marker coordinates require finite longitude from -180 to 180 and latitude strictly between -90 and 90.');
         if (marker.radius !== undefined && (!Number.isFinite(marker.radius) || marker.radius <= 0))
             throw new RangeError('Marker radius must be positive and finite.');

package/docs/API.md

@@ -4,6 +4,41 @@ Start with the [static and interactive examples](../README.md). Exact option
 and event types are exported by [src/api.ts](../src/api.ts) and defined in
 [src/types.ts](../src/types.ts) and [src/controller-types.ts](../src/controller-types.ts).
 
+## Geographic queries
+
+New in v5. See the [migration guide](migration-v5.md) for upgrade steps.
+
+The data-free `@kahwee/sf-map-svg/geometry` entry exports `geometryBounds(geometry)`
+and `geometryContainsPoint(geometry, [longitude, latitude])`. They work offline
+with the same readonly GeoJSON geometries used by the renderer, without a DOM.
+The same entry exports the `Geometry`, `Position`, and `Bounds` types, so geometry
+consumers need no second import path for their function input and result types.
+
+```ts
+import { geometryBounds, geometryContainsPoint } from '@kahwee/sf-map-svg/geometry';
+import { neighborhoods } from '@kahwee/sf-map-svg/data/realtor';
+
+const location = [-122.42, 37.76] as const;
+const matches = neighborhoods.features.filter((feature) =>
+  geometryContainsPoint(feature.geometry, location),
+);
+const bounds = matches[0] ? geometryBounds(matches[0].geometry) : null;
+```
+
+Bounds are `[west, south, east, north]` in degrees, computed from coordinates,
+not cached feature metadata. Empty or absent geometry returns `null`.
+Hit testing includes Polygon, MultiPolygon, and polygon members of nested
+GeometryCollections. Hole interiors are excluded; outer and hole boundaries
+are included, so a shared boundary may match multiple features. Ring winding
+does not matter; open rings are closed implicitly. Other geometry types do
+not produce polygon hits. Empty or absent geometry returns `false`.
+
+Both helpers reject nonfinite or out-of-range longitude/latitude with
+`RangeError`; altitude is ignored. They assume valid planar GeoJSON topology
+and straight segments in longitude/latitude, suitable for these SF datasets.
+They do not repair polygons, apply a boundary tolerance, or unwrap antimeridian
+crossings. A bounds match alone does not establish polygon containment.
+
 ## Static maps
 
 Static maps accept compact `StaticMapData` or the same source-aware `MapData` as interactive maps. With `MapData`, `source` selects a supplied neighborhood definition; SFAR realtor is preferred by default, followed by SF Find and analysis when available. A requested unavailable source throws before styling callbacks run. Compact `StaticMapData` already chooses its neighborhoods, so it rejects a `source` option. Both data shapes retain the static renderer defaults.
@@ -85,16 +120,16 @@ District style callbacks are evaluated once per district at construction and on
 
 ## Live configuration and inspection
 
-`map.configure({ appearance, mode, source, year, labels, layers, features, controls })` updates an existing map. Appearance updates preserve the camera, selections, retained marker nodes, and keyboard focus. Mode/source changes through `configure` preserve the camera; the `setMode(mode, { resetView: false })` and `setSource(source, { resetView: false })` convenience methods use the same atomic update path and preserve the camera. Omit the second argument to retain their existing reset behavior. Invalid view-update options fail before changing configuration. Switching neighborhood source clears the neighborhood selection. Changing district year retains a selected district when it exists in the new year. Unsupported datasets, invalid appearance values, and invalid district-style callback results fail during preparation before commit. A reentrant styling callback can supersede the pending patch.
+`map.configure({ appearance, mode, source, year, labels, layers, features, controls })` updates an existing map. Appearance updates preserve the camera, selections, retained marker nodes, and keyboard focus. Mode/source changes through `configure`, `setMode(mode)`, and `setSource(source)` preserve the camera. Use `map.camera.reset()` or `map.camera.fit(geometry)` when movement is intended. The former `{ resetView }` setter argument is removed in v5. Switching neighborhood source clears the neighborhood selection. Changing district year retains a selected district when it exists in the new year. Unsupported datasets, invalid appearance values, and invalid district-style callback results fail during preparation before commit. A reentrant styling callback can supersede the pending patch.
 
-Appearance token objects (`colors`, `style`, `labelStyle`, `labelSize`, `areaStyle`) merge supplied keys; other appearance properties replace. Omitted keys retain their value, an explicit `undefined` property removes that override, and `appearance: undefined` resets the whole appearance group. Feature objects retain their existing replacement semantics. Mode/source/year/labels ignore `undefined`; reset them with an explicit value. Patch types explicitly permit these resets with TypeScript’s `exactOptionalPropertyTypes` enabled.
+Controller patches merge nested token and feature records. Omitted and `undefined` values retain current values at every depth; `false` disables boolean switches. Use `resetConfiguration(groups?)` to remove presentation overrides explicitly. The supported groups are `features`, `layers`, `controls`, and `appearance`; omitting the argument resets all four. Resets restore built-in defaults, preserve mode/source/year/labels and camera, and do not restore constructor overrides. Unknown groups fail before changing state. Static construction options and low-level element methods retain their separately documented contracts.
 
 ```ts
 map.configure({
   appearance: { colors: { water: '#142d45' }, labelStyle: { fontFamily: 'Georgia,serif' } },
   layers: { bartStations: false },
 });
-map.configure({ appearance: undefined }); // restore construction defaults, not initial overrides
+map.resetConfiguration(['appearance']); // restore built-in defaults
 
 const overrides = map.getConfiguration();
 const effective = map.getResolvedConfiguration();
@@ -126,11 +161,14 @@ map.selectFeature({ kind: 'neighborhood', source: 'realtor', id: 'inner-mission'
 map.selectFeature({ kind: 'district', year: 2022, id: 3 });
 ```
 
-Neighborhood IDs are exact source-scoped feature IDs, rather than display names or aliases. District identity includes the boundary year. This operation returns `false` for a missing feature or a source/year other than the map's current supplied geography; it never silently switches definitions or years. Choose geography through `configure` first. An `id` of `null` clears that kind in the referenced current geography. Malformed references throw. Existing `selectMarker`, `selectNeighborhood`, and `selectDistrict` shortcuts remain supported.
+Neighborhood IDs are exact source-scoped feature IDs, rather than display names or aliases. District identity includes the boundary year. This operation returns `false` for a missing feature or a source/year other than the map's current supplied geography; it never silently switches definitions or years. Choose geography through `configure` first. An `id` of `null` clears that kind in the referenced current geography. Malformed references throw. The `selectMarker`, `selectNeighborhood`, and `selectDistrict` shortcuts select exact IDs in the current geography. Controller `selectNeighborhood` no longer resolves display names or aliases; resolve those with a source-specific data lookup first.
 
 ## Coordinates and units
 
-GeoJSON and static projection inputs use `[longitude, latitude]` in WGS84; markers use `{ lng, lat }`. Static `project` returns SVG units. `projectToScreen(lng, lat)` returns pixels relative to the mounted canvas. Camera viewports use the fixed 800 × 800 projected map space, independent of canvas size. Pan deltas use screen pixels, converted using the mounted canvas width. Marker radius uses screen pixels in browser maps and SVG units in static output.
+Version 5 uses tuple inputs and exports the named `ScreenPoint` /
+`ProjectToScreen` types. The former two-number call is removed.
+
+GeoJSON and static projection inputs use `[longitude, latitude]` in WGS84; markers use `{ position: [longitude, latitude] }`. Static `project` returns SVG units. `projectToScreen([longitude, latitude])` accepts the same readonly GeoJSON position as static `project` and returns `ScreenPoint` (`{ x, y, visible }`) in CSS pixels relative to the mounted canvas. Altitude is ignored. Mount the map before calling; invalid Mercator coordinates throw, and calls after controller destruction throw. `visible` indicates viewport inclusion, not whether another element covers the point. Camera viewports use the fixed 800 × 800 projected map space, independent of canvas size. Pan deltas use screen pixels, converted using the mounted canvas width. Marker radius uses screen pixels in browser maps and SVG units in static output.
 
 Explore presentation options in the [live map design playground](https://kahwee.github.io/sf-map-svg/playground.html). The page identifies its package version; released builds use compatible options for that installed version.