, options?: MapViewUpdateOptions): void;
setLabels(visible: boolean): void;
setTouchNavigation(enabled: boolean): void;
projectToScreen(lng: number, lat: number): {
x: number;
y: number;
visible: boolean;
};
/** Idempotent; stops work and managed subscriptions. Does not remove host-owned DOM. */
destroy(): void;
}
export {};
```
### dist/data/types.d.ts
```ts
export type Position = readonly [number, number, ...number[]];
export type Bounds = readonly [number, number, number, number];
export type Geometry = {
readonly type: 'Point';
readonly coordinates: Position;
} | {
readonly type: 'LineString';
readonly coordinates: readonly Position[];
} | {
readonly type: 'MultiPoint';
readonly coordinates: readonly Position[];
} | {
readonly type: 'Polygon';
readonly coordinates: readonly (readonly Position[])[];
} | {
readonly type: 'MultiLineString';
readonly coordinates: readonly (readonly Position[])[];
} | {
readonly type: 'MultiPolygon';
readonly coordinates: readonly (readonly (readonly Position[])[])[];
} | {
readonly type: 'GeometryCollection';
readonly geometries: readonly Geometry[];
};
export interface Feature>> {
readonly type: 'Feature';
readonly id: string;
readonly bbox: Bounds;
readonly properties: P;
readonly geometry: Geometry;
}
export interface DataSource {
readonly id: string;
readonly title: string;
readonly url: string;
readonly retrievedAt: string;
readonly definitionYear?: number;
readonly licenseUrl: string;
}
export interface Definition {
readonly kind: string;
readonly year?: number;
readonly description: string;
}
export interface FeatureCollection
>> {
readonly type: 'FeatureCollection';
readonly schemaVersion: 1;
readonly id: string;
readonly title: string;
readonly coordinateSystem: string;
readonly definition: Definition;
readonly sources: readonly DataSource[];
readonly topology?: {
readonly policy: 'disjoint-interiors';
readonly sharedBoundariesAllowed: boolean;
readonly method: string;
readonly tool: string;
readonly processedAt: string;
readonly sourceOverlapPairs: number;
};
readonly features: readonly Feature
[];
}
export type PointFeatureCollection
>> = Omit, 'features'> & {
readonly features: readonly (Feature & {
readonly geometry: Extract;
})[];
};
export type NeighborhoodSource = 'sf-find' | 'analysis' | 'realtor';
export interface NeighborhoodProperties {
readonly name: string;
readonly canonicalName: string;
readonly sourceName: string;
readonly aliases: readonly string[];
readonly definitionSource: NeighborhoodSource;
readonly nameSources: readonly string[];
readonly note?: string;
readonly sourceCode?: string | null;
readonly realtorDistrict?: string;
}
export interface NeighborhoodEntry extends NeighborhoodProperties {
readonly id: string;
readonly source: NeighborhoodSource;
readonly file: string;
readonly bbox: Bounds;
}
export interface DistrictProperties {
readonly district: number;
readonly name: string;
readonly year: 2002 | 2012 | 2022;
readonly label: Position;
readonly labelPoints: readonly Position[];
readonly displayExtras: Geometry | null;
}
export interface Catalog {
readonly schemaVersion: 1;
readonly description: string;
readonly datasets: readonly {
readonly id: string;
readonly file: string;
readonly title: string;
readonly featureCount: number;
readonly definition: Definition;
readonly sources: readonly DataSource[];
}[];
readonly neighborhoods: readonly NeighborhoodEntry[];
}
export type NeighborhoodFeature = Feature;
export type PolygonGeometry = Extract;
export type MultiPolygonGeometry = Extract;
export interface LandmarkProperties {
readonly name: string;
readonly label: Position;
readonly offset: readonly [number, number];
readonly anchor: 'middle' | 'start' | 'end';
}
export interface KeyRoadProperties {
readonly name: string;
readonly level?: 'primary' | 'secondary';
readonly sourceNames: readonly string[];
readonly label: Position;
readonly segmentIds: readonly string[];
}
```
### dist/src/types.d.ts
```ts
import type { Geometry, NeighborhoodFeature, NeighborhoodSource } from '../data/types.js';
export type DistrictYear = 2002 | 2012 | 2022;
export interface DistrictSelection {
id: number;
year: DistrictYear;
district: import('./map-core.js').DistrictRowData;
}
export interface DistrictStyle {
fill?: string;
stroke?: string;
opacity?: number;
}
export interface MapMarker {
id: string;
lng: number;
lat: number;
label?: string;
selected?: boolean;
color?: string;
/** Visible radius in screen pixels (interactive), SVG units (static). */
radius?: number;
}
export interface MapOverlay {
id: string;
geometry: Extract;
stroke?: string;
strokeWidth?: number;
fill?: string;
fillOpacity?: number;
visible?: boolean;
label?: string;
}
export interface SFMapOptions {
/** Grouped presentation; supplied keys take precedence over flat compatibility options. */
layers?: StaticMapLayers;
appearance?: StaticMapAppearance;
theme?: 'districts' | 'transit';
width?: number;
height?: number;
padding?: number;
year?: DistrictYear;
/** Select a supplied neighborhood definition when rendering source-aware MapData. */
source?: NeighborhoodSource;
districtLines?: boolean;
neighborhoodLines?: boolean;
districtFills?: boolean;
/** Evaluated once per district at construction/style/year updates; call setDistrictStyle again when external data changes. */
districtStyle?: (district: import('./map-core.js').DistrictRowData) => DistrictStyle;
districtLabels?: boolean;
/** Hide all visible text labels while retaining geographic symbols and accessible titles. */
labels?: boolean;
highways?: boolean;
keyRoads?: boolean;
roadLabels?: boolean;
landmarks?: boolean;
bartStations?: boolean;
markers?: readonly MapMarker[];
overlays?: readonly MapOverlay[];
title?: string;
idPrefix?: string;
/**
* Opt-in, self-contained CSS choreography for static SVGs: land fades in, the coast and
* lines draw, districts grow, then labels and points appear. It plays when the SVG is
* inserted into a page or loaded as an image, and stays still under reduced motion.
* `duration` (default 2400 ms) scales the whole sequence; `delay` offsets it.
*/
animation?: boolean | {
duration?: number;
delay?: number;
};
colors?: Partial>;
}
/** Presentation supported by both the static and interactive renderers. */
export type StaticMapLayers = Omit;
export type StaticMapAppearance = Pick;
/** 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;
roadLabels?: boolean;
}
export interface NeighborhoodSelection {
id: string;
name: string;
source: NeighborhoodSource;
feature: NeighborhoodFeature;
}
export interface MapFeatures {
/** Opt-in camera motion; reduced-motion always takes precedence. */
motion?: boolean | {
duration?: number;
};
markerEntrance?: boolean | {
duration?: number;
stagger?: number;
};
selectedMarkerRing?: boolean | {
color?: string;
width?: number;
gap?: number;
};
/** Screen-space clustering. The selected marker and full chooser remain available. */
clustering?: boolean | {
radius?: number;
};
northArrow?: boolean;
scaleBar?: boolean;
/**
* Fade layers as `setLayers` and `setMode` switch them, crossfade neighborhood boundaries
* when `setSource` changes the definition, and crossfade district fills on
* `setDistrictStyle`. Reduced motion takes precedence.
*/
layerTransitions?: boolean | {
duration?: number;
};
/**
* Morph district outlines from one map year to the next on `setDistrictYear`; pass
* `{ animate: false }` for an instant change. Reduced motion takes precedence.
*/
districtMorph?: boolean | {
duration?: number;
};
}
export interface NeighborhoodExplorerOptions extends MapFeatures {
mode?: ExplorerMode;
labels?: boolean;
source?: NeighborhoodSource;
neighborhood?: string;
year?: DistrictYear;
theme?: SFMapOptions['theme'];
colors?: SFMapOptions['colors'];
labelStyle?: {
fontFamily?: string;
fontWeight?: number;
haloColor?: string;
};
areaStyle?: {
selectedFill?: string;
selectedStroke?: string;
hoverFill?: string;
hoverStroke?: string;
};
districtStyle?: SFMapOptions['districtStyle'];
legend?: {
builtins?: boolean;
hidden?: readonly ('bart' | 'park' | 'highway' | 'road')[];
items?: readonly {
label: string;
color: string;
}[];
};
attribution?: 'full' | 'compact';
/** 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;
overlays?: readonly MapOverlay[];
onOverlayActivate?: (overlay: MapOverlay) => void;
/** Stable theme tokens consumed by the explorer chrome. */
style?: Partial>;
strings?: Partial>;
/**
* Independently hide chrome. `neighborhoodPicker` and `markerPicker` hide the native
* choosers (supply your own accessible list); `help` keeps the gesture help as the map's
* accessible description; `status` keeps a visually hidden live region. Attribution stays.
*/
controls?: Partial>;
}
export interface CameraOptions {
animate?: boolean;
duration?: number;
}
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;
};
stopAnimation(): void;
/** Atomic patch; false disables, undefined resets a feature to its default. */
setFeatures(patch: MapFeatures): void;
getFeatures(): MapFeatures;
/** Layer overrides; undefined restores mode defaults. Preserves camera and selection. */
setLayers(patch: InteractiveLayers): void;
/** Chrome switches are independent. */
setControls(patch: NonNullable): void;
selectNeighborhood(name: string | null, options?: {
fit?: boolean;
} & CameraOptions): boolean;
getSelection(): NeighborhoodSelection | null;
selectDistrict(id: number | null, options?: {
fit?: boolean;
} & CameraOptions): boolean;
getSelectedDistrict(): DistrictSelection | null;
setDistrictYear(year: DistrictYear, options?: CameraOptions): void;
setDistrictStyle(style: SFMapOptions['districtStyle']): void;
setSource(source: NeighborhoodSource): void;
setMode(mode: ExplorerMode): void;
setLabels(visible: boolean): void;
resetView(options?: CameraOptions): void;
zoomBy(factor: number, options?: CameraOptions): void;
panBy(x: number, y: number, options?: CameraOptions): void;
getViewport(): MapViewport;
setViewport(view: MapViewport, options?: CameraOptions): void;
/** Fit WGS84 geometry, including Point, MultiPoint, or a GeometryCollection. */
fitGeometry(geometry: Geometry, padding?: number | MapPadding, options?: CameraOptions): void;
/** Explicitly engage map touch gestures; false restores page gestures. */
setTouchNavigation(enabled: boolean): void;
/** Reconcile stable IDs; retained markers preserve nodes, focus, and entrance animations. */
setMarkers(markers: readonly MapMarker[]): void;
setOverlays(overlays: readonly MapOverlay[]): void;
selectMarker(id: string | null, options?: {
fit?: boolean;
} & CameraOptions): boolean;
getSelectedMarker(): MapMarker | null;
destroy(): void;
}
/** Paused-by-default schematic BART animation with keyboard-operable controls. */
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';
```
### dist/src/explorer-data.d.ts
```ts
import type { DistrictProperties, FeatureCollection, NeighborhoodProperties, NeighborhoodSource } from '../data/types.js';
import type { SFMapData } from './map-core.js';
import type { DistrictYear } from './types.js';
/** Geographic inputs for the data-injected interactive map entry point. */
export interface InteractiveSFMapData {
map: SFMapData;
districts?: Partial>>>;
neighborhoods: Partial>>>;
}
```
### dist/src/map-core.d.ts
```ts
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>>;
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[];
/** Canonical geometry in the same fitted coordinate space used by renderMap. */
export declare function getLayerPathsWithData(options: SFMapOptions, data: SFMapData, complete?: boolean): {
year: DistrictYear;
viewBox: [number, number, number, number];
project: (coordinates: Position) => [number, number];
coast: string;
districts: {
id: number;
geometry: string;
extras: string;
path: string;
}[];
neighborhoods: {
name: string;
path: string;
}[];
highways: {
route: string;
path: string;
}[];
landmarks: {
id: string;
path: string;
}[];
keyRoads: {
id: string;
path: string;
}[];
bartStations: {
id: string;
point: [number, number];
}[];
};
export declare function resolveMapColors(theme: SFMapOptions['theme'], colors?: SFMapOptions['colors']): {
water: string;
land: string;
district: string;
neighborhood: string;
highway: string;
road: string;
park: string;
landmark: string;
bart: string;
label: string;
marker: string;
selected: 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];
};
```
### dist/src/static.d.ts
```ts
import type { InteractiveSFMapData } from './explorer-data.js';
import { type SFMapData } from './map-core.js';
import type { SFMapOptions } from './types.js';
/** Either compact static geography or the same source-aware geography used by createMap. */
export type StaticMapInput = SFMapData | InteractiveSFMapData;
export type { DistrictRowData, SFMapData as StaticMapData } from './map-core.js';
export type { DistrictStyle, DistrictYear, SFMapOptions as StaticMapOptions, StaticMapAppearance, StaticMapLayers, } from './types.js';
/** 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];
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];
coast: string;
districts: {
id: number;
geometry: string;
extras: string;
path: string;
}[];
neighborhoods: {
name: string;
path: string;
}[];
highways: {
route: string;
path: string;
}[];
landmarks: {
id: string;
path: string;
}[];
keyRoads: {
id: string;
path: string;
}[];
bartStations: {
id: string;
point: [number, number];
}[];
};
```
### ./dist/data/index.d.ts
```ts
export { catalog, searchNeighborhoods } from './catalog.js';
export { coast } from './coast.js';
export { districtMaps } from './districts.js';
export { highways } from './highways.js';
export { landmarks } from './landmarks.js';
export { getNeighborhood, neighborhoodCollections, neighborhoodSources } from './lookup.js';
export { getRealtorNeighborhood, neighborhoods } from './realtor.js';
export { keyRoads } from './roads.js';
export { bartStations } from './stations.js';
export type * from './types.js';
```
### dist/data/catalog.d.ts
```ts
import type { Catalog, NeighborhoodSource } from './types.js';
export declare const catalog: Catalog;
/** Search name metadata across sources without importing polygon geometry. */
export declare function searchNeighborhoods(query?: string, { source }?: {
source?: NeighborhoodSource;
}): import("./types.js").NeighborhoodEntry[];
```
### dist/data/coast.d.ts
```ts
import type { FeatureCollection } from './types.js';
export declare const coast: FeatureCollection<{
readonly name: string;
}>;
```
### dist/data/districts.d.ts
```ts
import type { DistrictProperties, FeatureCollection } from './types.js';
export declare const districtMaps: Readonly>>;
```
### dist/data/highways.d.ts
```ts
import type { FeatureCollection } from './types.js';
export declare const highways: FeatureCollection<{
readonly route: string;
}>;
```
### dist/data/landmarks.d.ts
```ts
import type { FeatureCollection, LandmarkProperties } from './types.js';
export declare const landmarks: FeatureCollection;
```
### dist/data/lookup.d.ts
```ts
import type { FeatureCollection, NeighborhoodProperties, NeighborhoodSource } from './types.js';
export declare const neighborhoodCollections: Readonly>>;
export declare const neighborhoodSources: readonly NeighborhoodSource[];
/** Exact ID, canonical name, source name, or alias lookup within one definition set. */
export declare function getNeighborhood(name: string, { source }?: {
source?: NeighborhoodSource;
}): import("./types.js").Feature | undefined;
```
### dist/data/realtor.d.ts
```ts
import type { FeatureCollection, NeighborhoodProperties } from './types.js';
export declare const neighborhoods: FeatureCollection;
/** Look up one SFAR area without importing the other neighborhood definitions. */
export declare function getRealtorNeighborhood(name: string): import("./types.js").Feature | undefined;
```
### dist/data/roads.d.ts
```ts
import type { FeatureCollection, KeyRoadProperties } from './types.js';
export declare const keyRoads: FeatureCollection;
```
### dist/data/stations.d.ts
```ts
import type { PointFeatureCollection } from './types.js';
export declare const bartStations: PointFeatureCollection<{
readonly name: string;
}>;
```
### ./dist/data/analysis.d.ts
```ts
import type { FeatureCollection, NeighborhoodProperties } from './types.js';
export declare const analysisNeighborhoods: FeatureCollection;
```
### ./dist/src/full-data.d.ts
```ts
import type { MapData } from './map.js';
/** Complete, explicit geographic preset. Import this only when all datasets are needed. */
export declare const fullMapData: MapData;
```
### ./dist/src/static-data.d.ts
```ts
import type { StaticMapData } from './static.js';
/** Complete data for static rendering, without interactive lookup collections. */
export declare const staticMapData: StaticMapData;
```
### ./dist/data/sf-find.d.ts
```ts
import type { FeatureCollection, NeighborhoodProperties } from './types.js';
export declare const sfFindNeighborhoods: FeatureCollection;
```
### ./dist/src/geometry.d.ts
```ts
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;
```
### ./dist/src/guide.d.ts
```ts
export type { MapController, MapOptions } from './controller-types.js';
export type { InteractiveSFMapData } from './explorer-data.js';
export { guideMapData } from './guide-data.js';
export { loadGuideDetailedData } from './guide-detailed.js';
export { createGuideController, createGuideMap, mountGuideController, mountGuideMap, } from './guide-map.js';
export type { CameraOptions, MapFeatures, MapMarker, NeighborhoodExplorerElement as InteractiveSFMapElement, NeighborhoodExplorerOptions as InteractiveSFMapOptions, } from './types.js';
```
### dist/src/guide-data.d.ts
```ts
import type { InteractiveSFMapData } from './explorer-data.js';
/** Compact, source-aware geography with no district or alternate-neighborhood files. */
export declare const guideMapData: InteractiveSFMapData;
```
### dist/src/guide-detailed.d.ts
```ts
import type { InteractiveSFMapData } from './explorer-data.js';
/** Load detailed selected geography only after the caller requests it. */
export declare function loadGuideDetailedData(): Promise;
```
### dist/src/guide-map.d.ts
```ts
import type { MapController, MapOptions } from './controller-types.js';
import type { NeighborhoodExplorerElement as InteractiveSFMapElement, NeighborhoodExplorerOptions as InteractiveSFMapOptions } from './types.js';
/** Preferred guide API: the same grouped options, events, camera and lifecycle as createMap. */
export declare function createGuideController(options?: MapOptions): MapController;
/** Enhance a static guide shell and return its owning controller. */
export declare function mountGuideController(shell: HTMLElement, options?: MapOptions): MapController;
/** Element-based compatibility API. Prefer createGuideController for new integrations. */
export declare function createGuideMap(options?: InteractiveSFMapOptions): InteractiveSFMapElement;
/** Enhance createGuideShell() in place with a fixed compact chrome layout.
* Keep an accessible external place list when hiding the native pickers.
*/
export declare function mountGuideMap(shell: HTMLElement, options?: InteractiveSFMapOptions): InteractiveSFMapElement;
```
### ./dist/src/transit.d.ts
```ts
import type { TransitAnimationElement } from './types.js';
/** A deliberately schematic, offline station-to-station animation. Starts paused. */
export declare function createTransitAnimation(): TransitAnimationElement;
```
### ./dist/src/guide-static.d.ts
```ts
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];
viewBox: [number, number, number, number];
};
/** Stable compact frame, progressively enhanced with mountGuideMap(). No browser globals. */
export declare function createGuideShell(options?: SFMapOptions): string;
```
### ./dist/src/presets.d.ts
```ts
import type { MapOptions } from './controller-types.js';
/** Configuration only: pair with guide/data or a compatible caller-supplied dataset. */
export declare const guideOptions: Readonly;
```