@kahwee/sf-map-svg 0.3.0 → 1.1.0

package/dist/src/types.d.ts

@@ -0,0 +1,112 @@
+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;
+}
+/** Paused-by-default schematic BART animation with keyboard-operable controls. */
+export interface TransitAnimationElement extends HTMLElement {
+    destroy(): void;
+}

package/dist/src/types.js

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

package/dist/src/viewport.d.ts

@@ -0,0 +1,5 @@
+import type { Bounds } from '../data/types.js';
+import type { MapPadding, MapViewport } from './types.js';
+export declare function validateViewport(view: MapViewport): import("./explorer-layout.js").View;
+/** Fit bounds in the unobscured screen area, then constrain to the city extent. */
+export declare function fitViewport(bounds: Bounds, width: number, padding?: number | MapPadding): import("./explorer-layout.js").View;

package/dist/src/viewport.js

@@ -0,0 +1,27 @@
+import { clampView } from './explorer-layout.js';
+export function validateViewport(view) {
+    if (view.length !== 3 || !view.every(Number.isFinite) || view[2] <= 0)
+        throw new RangeError('Viewport must contain finite x, y, and a positive size.');
+    return clampView([...view]);
+}
+/** Fit bounds in the unobscured screen area, then constrain to the city extent. */
+export function fitViewport(bounds, width, padding = 24) {
+    const p = typeof padding === 'number'
+        ? { top: padding, right: padding, bottom: padding, left: padding }
+        : padding;
+    const { top = 0, right = 0, bottom = 0, left = 0 } = p;
+    if (![width, top, right, bottom, left, ...bounds].every(Number.isFinite) ||
+        Math.min(top, right, bottom, left) < 0 ||
+        width <= left + right ||
+        width <= top + bottom ||
+        bounds[0] > bounds[2] ||
+        bounds[1] > bounds[3])
+        throw new RangeError('Fit requires nonempty finite geometry and padding smaller than the viewport.');
+    const size = Math.max(800 / 12, Math.min(800, ((bounds[2] - bounds[0]) * width) / (width - left - right)));
+    const fittedSize = Math.max(size, Math.min(800, ((bounds[3] - bounds[1]) * width) / (width - top - bottom)));
+    return clampView([
+        (bounds[0] + bounds[2]) / 2 - fittedSize / 2 - ((left - right) * fittedSize) / width / 2,
+        (bounds[1] + bounds[3]) / 2 - fittedSize / 2 - ((top - bottom) * fittedSize) / width / 2,
+        fittedSize,
+    ]);
+}

package/package.json

@@ -1,52 +1,63 @@
 {
   "name": "@kahwee/sf-map-svg",
-  "version": "0.3.0",
+  "version": "1.1.0",
   "description": "Offline SVG maps of San Francisco with district boundaries, parks, landmarks, and BART stations.",
   "type": "module",
-  "main": "./src/index.js",
-  "types": "./src/index.d.ts",
+  "main": "./dist/src/index.js",
+  "types": "./dist/src/index.d.ts",
   "exports": {
     ".": {
-      "types": "./src/index.d.ts",
-      "import": "./src/index.js"
+      "types": "./dist/src/index.d.ts",
+      "import": "./dist/src/index.js"
     },
     "./data": {
-      "types": "./data/index.d.ts",
-      "import": "./data/index.js"
+      "types": "./dist/data/index.d.ts",
+      "import": "./dist/data/index.js"
     },
-    "./data/*.json": "./data/*.json",
+    "./data/*.json": "./dist/data/*.json",
     "./geometry": {
-      "types": "./src/geometry.d.ts",
-      "import": "./src/geometry.js"
+      "types": "./dist/src/geometry.d.ts",
+      "import": "./dist/src/geometry.js"
+    },
+    "./explorer": {
+      "types": "./dist/src/explorer.d.ts",
+      "import": "./dist/src/explorer.js"
+    },
+    "./interactive": {
+      "types": "./dist/src/interactive.d.ts",
+      "import": "./dist/src/interactive.js"
+    },
+    "./transit": {
+      "types": "./dist/src/transit.d.ts",
+      "import": "./dist/src/transit.js"
     }
   },
   "files": [
-    "src",
+    "dist",
     "README.md",
     "SOURCES.md",
-    "LICENSE",
-    "data"
+    "LICENSE"
   ],
   "sideEffects": false,
   "repository": {
     "type": "git",
     "url": "git+https://github.com/kahwee/sf-map-svg.git"
   },
-  "license": "UNLICENSED",
+  "license": "MIT",
   "engines": {
     "node": ">=22.12.0"
   },
   "devDependencies": {
+    "@biomejs/biome": "2.5.14",
     "@storybook/addon-docs": "^10.6.0",
     "@storybook/html-vite": "^10.6.0",
     "@xmldom/xmldom": "^0.9.12",
     "polygon-clipping": "^0.15.7",
-    "prettier": "^3.9.9",
     "storybook": "^10.6.0",
     "typescript": "^7.0.2",
     "vite": "^8.3.1"
   },
-  "homepage": "https://github.com/kahwee/sf-map-svg#readme",
+  "homepage": "https://kahwee.github.io/sf-map-svg/",
   "bugs": {
     "url": "https://github.com/kahwee/sf-map-svg/issues"
   },
@@ -62,16 +73,20 @@
     "registry": "https://registry.npmjs.org/"
   },
   "scripts": {
-    "test": "node --test",
-    "demo": "node examples/build.mjs",
-    "format": "prettier --write .",
-    "format:check": "prettier --check .",
-    "check": "pnpm format:check && pnpm data:check && pnpm typecheck && pnpm test",
-    "storybook": "storybook dev -p 6006 --host 127.0.0.1 --no-open",
-    "build-storybook": "storybook build",
+    "test": "pnpm build && node --test",
+    "demo": "pnpm build && node examples/build.mjs",
+    "format": "biome check --write .",
+    "format:check": "biome format .",
+    "check": "pnpm lint && pnpm data:check && pnpm typecheck && pnpm test",
+    "storybook": "pnpm build && storybook dev -p 6006 --host 127.0.0.1 --no-open",
+    "build-storybook": "pnpm build && storybook build",
     "data:catalog": "node scripts/build-data-catalog.mjs",
     "data:check": "node scripts/build-data-catalog.mjs --check",
-    "typecheck": "tsc",
-    "data:normalize-realtor": "node scripts/normalize-realtor.mjs"
+    "typecheck": "pnpm build && tsc -p tsconfig.json",
+    "data:normalize-realtor": "node scripts/normalize-realtor.mjs",
+    "test:package": "node scripts/smoke-package.mjs",
+    "build": "node scripts/build.mjs",
+    "lint": "biome check .",
+    "build:pages": "pnpm demo && node scripts/build-pages.mjs"
   }
 }

package/data/bart-stations.json

@@ -1,134 +0,0 @@
-{
-  "type": "FeatureCollection",
-  "schemaVersion": 1,
-  "id": "bart-stations",
-  "title": "San Francisco BART stations",
-  "coordinateSystem": "WGS84 longitude, latitude (EPSG:4326)",
-  "definition": {
-    "kind": "station-centroids",
-    "description": "Eight station centroids within San Francisco. Entrances, tracks, and other cities are excluded."
-  },
-  "sources": [
-    {
-      "id": "bart-stations",
-      "title": "BART official geospatial data",
-      "url": "https://www.bart.gov/sites/default/files/2025-12/BART-Stations-tracks-entrances-121025.kmz_.zip",
-      "retrievedAt": "2026-09-25",
-      "licenseUrl": "https://www.bart.gov/schedules/developers/geo"
-    }
-  ],
-  "features": [
-    {
-      "type": "Feature",
-      "id": "embarcadero",
-      "bbox": [
-        -122.3969009943399,
-        37.79285391372556,
-        -122.3969009943399,
-        37.79285391372556
-      ],
-      "properties": {
-        "name": "Embarcadero"
-      },
-      "geometry": {"type":"Point","coordinates":[-122.3969009943399,37.79285391372556]}
-    },
-    {
-      "type": "Feature",
-      "id": "montgomery-st",
-      "bbox": [
-        -122.4011747105981,
-        37.78944952039284,
-        -122.4011747105981,
-        37.78944952039284
-      ],
-      "properties": {
-        "name": "Montgomery St"
-      },
-      "geometry": {"type":"Point","coordinates":[-122.4011747105981,37.78944952039284]}
-    },
-    {
-      "type": "Feature",
-      "id": "powell-st",
-      "bbox": [
-        -122.4070176588271,
-        37.78487089662774,
-        -122.4070176588271,
-        37.78487089662774
-      ],
-      "properties": {
-        "name": "Powell St"
-      },
-      "geometry": {"type":"Point","coordinates":[-122.4070176588271,37.78487089662774]}
-    },
-    {
-      "type": "Feature",
-      "id": "civic-center-un-plaza",
-      "bbox": [
-        -122.4139364152156,
-        37.77939386076284,
-        -122.4139364152156,
-        37.77939386076284
-      ],
-      "properties": {
-        "name": "Civic Center/UN Plaza"
-      },
-      "geometry": {"type":"Point","coordinates":[-122.4139364152156,37.77939386076284]}
-    },
-    {
-      "type": "Feature",
-      "id": "16th-st-mission",
-      "bbox": [
-        -122.4197081435103,
-        37.76505423932072,
-        -122.4197081435103,
-        37.76505423932072
-      ],
-      "properties": {
-        "name": "16th St/Mission"
-      },
-      "geometry": {"type":"Point","coordinates":[-122.4197081435103,37.76505423932072]}
-    },
-    {
-      "type": "Feature",
-      "id": "24th-st-mission",
-      "bbox": [
-        -122.4184678760468,
-        37.75223145165559,
-        -122.4184678760468,
-        37.75223145165559
-      ],
-      "properties": {
-        "name": "24th St/Mission"
-      },
-      "geometry": {"type":"Point","coordinates":[-122.4184678760468,37.75223145165559]}
-    },
-    {
-      "type": "Feature",
-      "id": "glen-park",
-      "bbox": [
-        -122.4337900883829,
-        37.73311239451952,
-        -122.4337900883829,
-        37.73311239451952
-      ],
-      "properties": {
-        "name": "Glen Park"
-      },
-      "geometry": {"type":"Point","coordinates":[-122.4337900883829,37.73311239451952]}
-    },
-    {
-      "type": "Feature",
-      "id": "balboa-park",
-      "bbox": [
-        -122.4475873574919,
-        37.72135058802738,
-        -122.4475873574919,
-        37.72135058802738
-      ],
-      "properties": {
-        "name": "Balboa Park"
-      },
-      "geometry": {"type":"Point","coordinates":[-122.4475873574919,37.72135058802738]}
-    }
-  ]
-}