@kahwee/sf-map-svg 1.3.8 → 1.4.1

package/CHANGELOG.md

@@ -4,6 +4,18 @@ User-visible changes are recorded here. Unreleased entries describe changes on `
 
 ## Unreleased
 
+## 1.4.1 — 2026-09-26
+
+- Add a task-based example gallery and code recipes, with clearer routes among the Pages atlas, local measures, district history, transit, and lightweight map.
+- Add a California proposition explorer using certified November 2024 Yes and No votes for all eleven San Francisco supervisorial districts; publish its sourced JSON and reproducible import script.
+
+## 1.4.0 — 2026-09-26
+
+- Split geographic convenience exports into independent data modules, so metadata search and SFAR-only lookup avoid unrelated JSON.
+- Separate the guide's detailed loader from overview geography; keep the existing `/guide` exports and add explicit `/guide/detailed`, `/guide/data`, and `/guide/map` paths.
+- Make the optional transit animation include only its 2022 map geography, preserving the rendered route while cutting its consumer bundle size.
+- Publish a before-and-after tree-shaking report for representative consumer imports.
+
 ## 1.3.8 — 2026-09-26
 
 - Give the district map a clear, dedicated viewing area on mobile by shrinking the election and measure controls and moving the map legend below the map.

package/README.md

@@ -2,12 +2,21 @@
 
 [![npm version](https://img.shields.io/npm/v/@kahwee/sf-map-svg)](https://www.npmjs.com/package/@kahwee/sf-map-svg)
 
-[Explore the live map](https://kahwee.github.io/sf-map-svg/) · [Data guide](data/README.md) · [Geographic sources](SOURCES.md) · [Contributing](CONTRIBUTING.md)
+[Live atlas](https://kahwee.github.io/sf-map-svg/) · [Example gallery](https://kahwee.github.io/sf-map-svg/examples.html) · [Code recipes](docs/EXAMPLES.md) · [Data guide](data/README.md) · [Sources](SOURCES.md) · [Contributing](CONTRIBUTING.md)
 
 Self-contained SVG maps of San Francisco, with precise coastlines, soft district colors, parks, roads, BART stations, and searchable neighborhoods. Render static SVGs in Node or add an interactive map to a browser. All geometry is bundled; there are no runtime dependencies, map tiles, API keys, or external data requests.
 
 ![San Francisco district maps with optional neighborhood boundaries](docs/map-preview.png)
 
+## Choose a starting point
+
+| Goal | Example | API |
+| --- | --- | --- |
+| Explore real election data | [California propositions by SF district](https://kahwee.github.io/sf-map-svg/propositions.html) or [local measures](https://kahwee.github.io/sf-map-svg/measures.html) | `custom-map` |
+| Make a small interactive city map | [Neighborhood guide](https://kahwee.github.io/sf-map-svg/#explore-more-title) | `/guide` |
+| Render a static or custom SVG | [Code recipes](docs/EXAMPLES.md) | Root or `/custom-map` |
+| Animate a route | [BART journey](https://kahwee.github.io/sf-map-svg/transit.html) | `/transit` or overlays |
+
 ## Install
 
 ```sh
@@ -26,6 +35,8 @@ Use Node 22.12+ for server-side rendering. Browser components need a DOM and a b
 | Lightweight guide map | `@kahwee/sf-map-svg/guide` | Curated overview geography, with detailed data loaded explicitly |
 | Animated transit demo | `@kahwee/sf-map-svg/transit` | Optional, schematic BART journey with playback controls |
 | Geographic data | `@kahwee/sf-map-svg/data` | Source-aware lookup and canonical GeoJSON |
+| Metadata search | `@kahwee/sf-map-svg/data/catalog` | Search names without polygon geometry |
+| SFAR lookup | `@kahwee/sf-map-svg/data/realtor` | Default neighborhoods without alternative sources |
 
 ## Render a static map
 
@@ -53,6 +64,14 @@ road, park, and station arrays. Use the canonical JSON subpaths documented in
 corresponding `SFMapData` records. The root entry remains convenient and includes the
 built-in datasets for backward compatibility.
 
+In tree-shaking bundlers, importing a single symbol from `/data` retains only the
+modules that symbol uses.
+`searchNeighborhoods` needs catalog metadata but no polygon geometry. The synchronous
+source-switching `getNeighborhood` still needs all three neighborhood collections;
+use `/data/realtor` when only the default SFAR definitions are needed. Optional coast,
+district, road, park, and station collections also have independent `/data/*` entries.
+See [the measured bundle report](docs/module-bundle-report.md).
+
 The same split is available for browser controls with
 `@kahwee/sf-map-svg/interactive-data`. Pass an `InteractiveSFMapData` object containing
 `map` (the `SFMapData` used by the static renderer) and only the neighborhood collections
@@ -69,7 +88,8 @@ have independent `layers.keyRoads` and `layers.roadLabels` controls. Lombard geo
 label appear after 1.8× zoom; major street labels can appear at city scale in a smaller type size.
 
 ```ts
-import { createGuideMap, loadGuideDetailedData } from '@kahwee/sf-map-svg/guide';
+import { createGuideMap } from '@kahwee/sf-map-svg/guide';
+import { loadGuideDetailedData } from '@kahwee/sf-map-svg/guide/detailed';
 import { createInteractiveSFMapWithData } from '@kahwee/sf-map-svg/interactive-data';
 
 const map = createGuideMap({ layers: { roadLabels: false } });
@@ -85,6 +105,8 @@ const detailedMap = createInteractiveSFMapWithData(detailedData, {
 
 Run `pnpm data:guide` to rebuild the subpixel overview geometries from canonical files.
 `docs/guide-bundle-report.md` records compressed bundle sizes and verifies the included data.
+The detailed loader is also re-exported from `/guide` for compatibility; importing only
+that function no longer puts overview geography in the initial bundle.
 
 ```js
 import coast from '@kahwee/sf-map-svg/data/coast.json' with { type: 'json' };
@@ -328,13 +350,12 @@ chooser to reach obscured markers. Automated clustering is not included in this
 All map geometry is available through stable JSON package exports. There are three district files (2002, 2012, 2022), the full 117 SF Find neighborhoods, 41 analysis neighborhoods, 92 realtor-defined areas, and separate coastline, highway, landmark, and BART files. Neighborhood records include a canonical display name, exact source name, stable ID, aliases where documented, source definition, and full polygon geometry.
 
 ```js
-import neighborhoods from '@kahwee/sf-map-svg/data/neighborhoods-realtor.json' with { type: 'json' };
-import districts2022 from '@kahwee/sf-map-svg/data/districts-2022.json' with { type: 'json' };
-import { getNeighborhood, searchNeighborhoods } from '@kahwee/sf-map-svg/data';
+import { getRealtorNeighborhood } from '@kahwee/sf-map-svg/data/realtor';
+import { searchNeighborhoods } from '@kahwee/sf-map-svg/data/catalog';
 
-const mission = getNeighborhood('Inner Mission');
-const outerMission = getNeighborhood('Outer Mission');
-const nopa = getNeighborhood('NoPa', { source: 'realtor' });
+const mission = getRealtorNeighborhood('Inner Mission');
+const outerMission = getRealtorNeighborhood('Outer Mission');
+const nopa = getRealtorNeighborhood('NoPa');
 const matchingDefinitions = searchNeighborhoods('mission');
 ```
 

package/SOURCES.md

@@ -1,5 +1,15 @@
 # Geometry and provenance
 
+## California propositions in San Francisco
+
+Downloaded September 26, 2026 from the San Francisco Department of Elections' [final November 5, 2024 results](https://sfelections.org/results/20241105w/detail.html):
+
+- [Certified district statement of vote workbook](https://www.sfelections.org/results/20241105/data/20241203/dsov.xlsx), SHA-256 `9bf9c7d767273e73b3cdf5b98086412cbe354b0928ee6abb0e379deb0353c403`
+- [Certification letter](https://www.sfelections.org/results/20241105/data/20241203/CertificationLetterNov52024.pdf)
+- [California Secretary of State statewide Statement of Vote](https://www.sos.ca.gov/elections/prior-elections/statewide-election-results/general-election-nov-5-2024/statement-vote) for statewide context
+
+`data/propositions/2024-11-05.json` contains Yes and No counts for all ten state propositions, grouped by San Francisco supervisorial district. The short titles are editorial navigation labels. `scripts/import-2024-propositions.py` reads the final workbook's proposition sheets and checks that all eleven district totals sum exactly to its San Francisco citywide totals. Yes share divides Yes by Yes plus No, excluding undervotes and overvotes. The data describes where ballots were cast within San Francisco, not individual voters or statewide outcomes. Its 2022 district geography matches the election's district vintage.
+
 ## Map extraction
 
 District geometry, coast, label anchors, highway geometry, and the pastel district palette were extracted from the San Francisco District Map on September 25, 2026. Only map rendering and public geographic data are distributed. Site account identifiers, original application code, and ballot overlays are excluded.

package/dist/data/README.md

@@ -33,7 +33,28 @@ const mission = neighborhoods.features.find((f) => f.id === 'inner-mission');
 console.log(mission.properties.canonicalName, mission.geometry);
 ```
 
-Node 22.12+ supports this syntax. Bundlers may also support JSON imports without the import attribute. Files are included in the package archive; non-JavaScript consumers can parse the same JSON files directly. These are package entry points, not a hosted API. The public repository and GitHub Pages explorer also provide access to the source data. Consumers who need only one dataset should import its JSON subpath rather than the convenience module, which loads all collections.
+Node 22.12+ supports this syntax. Bundlers may also support JSON imports without the import attribute. Files are included in the package archive; non-JavaScript consumers can parse the same JSON files directly. These are package entry points, not a hosted API. The public repository and GitHub Pages explorer also provide access to the source data. Consumers who need only one dataset can import its JSON subpath or a typed, frozen leaf module.
+
+## Import only the data you need
+
+```js
+import { searchNeighborhoods } from '@kahwee/sf-map-svg/data/catalog';
+import { getRealtorNeighborhood } from '@kahwee/sf-map-svg/data/realtor';
+import { coast } from '@kahwee/sf-map-svg/data/coast';
+
+const candidates = searchNeighborhoods('mission'); // metadata, no polygons
+const mission = getRealtorNeighborhood('Inner Mission'); // SFAR only
+const coastline = coast.features[0].geometry;
+```
+
+The `/data` entry remains compatible and re-exports these helpers and collections.
+Its `getNeighborhood(name, { source })` imports all three neighborhood definitions
+because source switching is synchronous. Importing only `searchNeighborhoods` from
+`/data` now includes catalog metadata only in tree-shaking bundles. Other independent modules are
+`/data/sf-find`, `/data/analysis`, `/data/districts`, `/data/highways`,
+`/data/landmarks`, `/data/roads`, and `/data/stations`. Districts still groups all
+three supported years; import `districts-2022.json` directly when only one year is
+needed. See [the consumer bundle report](../docs/module-bundle-report.md).
 
 ## Names and definitions
 
@@ -69,7 +90,7 @@ const allAnalysisPolygons = neighborhoodCollections.analysis;
 const historicalDistricts = districtMaps[2012];
 ```
 
-Lookup is exact after case/punctuation normalization, returns `undefined` for an unknown name, and throws for an unknown source. Search matches substrings and preserves every source-specific result. The convenience module's shared data is deeply frozen; use `structuredClone(feature)` if you need an editable copy. Do not mutate imported datasets used by the renderer.
+Lookup is exact after case/punctuation normalization, returns `undefined` for an unknown name, and throws for an unknown source. Search matches substrings and preserves every source-specific result. The convenience and leaf modules' shared data is deeply frozen; use `structuredClone(feature)` if you need an editable copy. Do not mutate imported datasets used by the renderer.
 
 ## Draw a neighborhood with the existing projection
 

package/dist/data/analysis.d.ts

@@ -0,0 +1,2 @@
+import type { FeatureCollection, NeighborhoodProperties } from './types.js';
+export declare const analysisNeighborhoods: FeatureCollection<NeighborhoodProperties>;

package/dist/data/analysis.js

@@ -0,0 +1,3 @@
+import { deepFreeze } from '../src/immutable.js';
+import analysisData from './neighborhoods-analysis.json' with { type: 'json' };
+export const analysisNeighborhoods = deepFreeze(analysisData);

package/dist/data/catalog.d.ts

@@ -0,0 +1,6 @@
+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[];

package/dist/data/catalog.js

@@ -0,0 +1,14 @@
+import { deepFreeze } from '../src/immutable.js';
+import catalogData from './catalog.json' with { type: 'json' };
+import { normalizeNeighborhoodName } from './lookup-utils.js';
+export const catalog = deepFreeze(catalogData);
+/** Search name metadata across sources without importing polygon geometry. */
+export function searchNeighborhoods(query = '', { source } = {}) {
+    if (source !== undefined && !['sf-find', 'analysis', 'realtor'].includes(source))
+        throw new RangeError(`Unknown neighborhood source: ${source}`);
+    if (typeof query !== 'string')
+        throw new TypeError('Neighborhood query must be a string.');
+    const term = normalizeNeighborhoodName(query);
+    return catalog.neighborhoods.filter((entry) => (source === undefined || entry.source === source) &&
+        [entry.id, entry.canonicalName, entry.sourceName, ...entry.aliases].some((value) => normalizeNeighborhoodName(value).includes(term)));
+}

package/dist/data/coast.d.ts

@@ -0,0 +1,4 @@
+import type { FeatureCollection } from './types.js';
+export declare const coast: FeatureCollection<{
+    readonly name: string;
+}>;

package/dist/data/coast.js

@@ -0,0 +1,3 @@
+import { deepFreeze } from '../src/immutable.js';
+import coastData from './coast.json' with { type: 'json' };
+export const coast = deepFreeze(coastData);

package/dist/data/districts.d.ts

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

package/dist/data/districts.js

@@ -0,0 +1,9 @@
+import { deepFreeze } from '../src/immutable.js';
+import districts2002 from './districts-2002.json' with { type: 'json' };
+import districts2012 from './districts-2012.json' with { type: 'json' };
+import districts2022 from './districts-2022.json' with { type: 'json' };
+export const districtMaps = deepFreeze({
+    2002: districts2002,
+    2012: districts2012,
+    2022: districts2022,
+});

package/dist/data/highways.d.ts

@@ -0,0 +1,4 @@
+import type { FeatureCollection } from './types.js';
+export declare const highways: FeatureCollection<{
+    readonly route: string;
+}>;

package/dist/data/highways.js

@@ -0,0 +1,3 @@
+import { deepFreeze } from '../src/immutable.js';
+import highwayData from './highways.json' with { type: 'json' };
+export const highways = deepFreeze(highwayData);

package/dist/data/index.d.ts

@@ -1,26 +1,10 @@
+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';
-import type { Catalog, DistrictProperties, Feature, FeatureCollection, KeyRoadProperties, LandmarkProperties, NeighborhoodProperties, NeighborhoodSource } from './types.js';
-export declare const coast: FeatureCollection<{
-    readonly name: string;
-}>;
-export declare const districtMaps: Readonly<Record<2002 | 2012 | 2022, FeatureCollection<DistrictProperties>>>;
-export declare const neighborhoods: FeatureCollection<NeighborhoodProperties>;
-export declare const neighborhoodCollections: Readonly<Record<NeighborhoodSource, FeatureCollection<NeighborhoodProperties>>>;
-export declare const neighborhoodSources: readonly NeighborhoodSource[];
-export declare const highways: FeatureCollection<{
-    readonly route: string;
-}>;
-export declare const landmarks: FeatureCollection<LandmarkProperties>;
-export declare const bartStations: FeatureCollection<{
-    readonly name: string;
-}>;
-export declare const catalog: Catalog;
-/** Exact ID, canonical name, source name, or alias lookup within one definition set. */
-export declare function getNeighborhood(name: string, { source }?: {
-    source?: NeighborhoodSource;
-}): Feature<NeighborhoodProperties> | undefined;
-/** Search names across sources; results keep their source identity and omit geometry. */
-export declare function searchNeighborhoods(query?: string, { source }?: {
-    source?: NeighborhoodSource;
-}): import("./types.js").NeighborhoodEntry[];
-export declare const keyRoads: FeatureCollection<KeyRoadProperties>;

package/dist/data/index.js

@@ -1,67 +1,9 @@
-import { deepFreeze } from '../src/immutable.js';
-import stationData from './bart-stations.json' with { type: 'json' };
-import catalogData from './catalog.json' with { type: 'json' };
-import coastData from './coast.json' with { type: 'json' };
-import districts2002 from './districts-2002.json' with { type: 'json' };
-import districts2012 from './districts-2012.json' with { type: 'json' };
-import districts2022 from './districts-2022.json' with { type: 'json' };
-import highwayData from './highways.json' with { type: 'json' };
-import roadData from './key-roads.json' with { type: 'json' };
-import landmarkData from './landmarks.json' with { type: 'json' };
-import sfFind from './neighborhoods.json' with { type: 'json' };
-import analysis from './neighborhoods-analysis.json' with { type: 'json' };
-import realtor from './neighborhoods-realtor.json' with { type: 'json' };
-export const coast = deepFreeze(coastData);
-export const districtMaps = deepFreeze({
-    2002: districts2002,
-    2012: districts2012,
-    2022: districts2022,
-});
-export const neighborhoods = deepFreeze(realtor);
-export const neighborhoodCollections = deepFreeze({
-    'sf-find': sfFind,
-    analysis,
-    realtor,
-});
-export const neighborhoodSources = Object.freeze(Object.keys(neighborhoodCollections));
-export const highways = deepFreeze(highwayData);
-export const landmarks = deepFreeze(landmarkData);
-export const bartStations = deepFreeze(stationData);
-export const catalog = deepFreeze(catalogData);
-const normalize = (value) => value
-    .normalize('NFKD')
-    .toLowerCase()
-    .replace(/[\u0300-\u036f'’]/g, '')
-    .replace(/[^a-z0-9]+/g, ' ')
-    .trim();
-function checkSource(source) {
-    if (!Object.hasOwn(neighborhoodCollections, source))
-        throw new RangeError(`Unknown neighborhood source: ${source}`);
-}
-const names = (feature) => [
-    feature.id,
-    feature.properties.canonicalName,
-    feature.properties.sourceName,
-    ...feature.properties.aliases,
-];
-/** Exact ID, canonical name, source name, or alias lookup within one definition set. */
-export function getNeighborhood(name, { source = 'realtor' } = {}) {
-    checkSource(source);
-    if (typeof name !== 'string')
-        throw new TypeError('Neighborhood name must be a string.');
-    const query = normalize(name);
-    if (!query)
-        return undefined;
-    return neighborhoodCollections[source].features.find((feature) => names(feature).some((value) => normalize(value) === query));
-}
-/** Search names across sources; results keep their source identity and omit geometry. */
-export function searchNeighborhoods(query = '', { source } = {}) {
-    if (source !== undefined)
-        checkSource(source);
-    if (typeof query !== 'string')
-        throw new TypeError('Neighborhood query must be a string.');
-    const term = normalize(query);
-    return catalog.neighborhoods.filter((entry) => (source === undefined || entry.source === source) &&
-        [entry.id, entry.canonicalName, entry.sourceName, ...entry.aliases].some((value) => normalize(value).includes(term)));
-}
-export const keyRoads = deepFreeze(roadData);
+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';

package/dist/data/landmarks.d.ts

@@ -0,0 +1,2 @@
+import type { FeatureCollection, LandmarkProperties } from './types.js';
+export declare const landmarks: FeatureCollection<LandmarkProperties>;

package/dist/data/landmarks.js

@@ -0,0 +1,3 @@
+import { deepFreeze } from '../src/immutable.js';
+import landmarkData from './landmarks.json' with { type: 'json' };
+export const landmarks = deepFreeze(landmarkData);

package/dist/data/lookup-utils.d.ts

@@ -0,0 +1,3 @@
+import type { Feature, FeatureCollection, NeighborhoodProperties } from './types.js';
+export declare const normalizeNeighborhoodName: (value: string) => string;
+export declare function findNeighborhood(name: string, collection: FeatureCollection<NeighborhoodProperties>): Feature<NeighborhoodProperties> | undefined;

package/dist/data/lookup-utils.js

@@ -0,0 +1,14 @@
+export const normalizeNeighborhoodName = (value) => value
+    .normalize('NFKD')
+    .toLowerCase()
+    .replace(/[\u0300-\u036f'’]/g, '')
+    .replace(/[^a-z0-9]+/g, ' ')
+    .trim();
+export function findNeighborhood(name, collection) {
+    if (typeof name !== 'string')
+        throw new TypeError('Neighborhood name must be a string.');
+    const query = normalizeNeighborhoodName(name);
+    if (!query)
+        return undefined;
+    return collection.features.find(({ id, properties }) => [id, properties.canonicalName, properties.sourceName, ...properties.aliases].some((value) => normalizeNeighborhoodName(value) === query));
+}

package/dist/data/lookup.d.ts

@@ -0,0 +1,7 @@
+import type { FeatureCollection, NeighborhoodProperties, NeighborhoodSource } from './types.js';
+export declare const neighborhoodCollections: Readonly<Record<NeighborhoodSource, FeatureCollection<NeighborhoodProperties>>>;
+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<NeighborhoodProperties> | undefined;

package/dist/data/lookup.js

@@ -0,0 +1,16 @@
+import { analysisNeighborhoods } from './analysis.js';
+import { findNeighborhood } from './lookup-utils.js';
+import { neighborhoods } from './realtor.js';
+import { sfFindNeighborhoods } from './sf-find.js';
+export const neighborhoodCollections = Object.freeze({
+    'sf-find': sfFindNeighborhoods,
+    analysis: analysisNeighborhoods,
+    realtor: neighborhoods,
+});
+export const neighborhoodSources = Object.freeze(Object.keys(neighborhoodCollections));
+/** Exact ID, canonical name, source name, or alias lookup within one definition set. */
+export function getNeighborhood(name, { source = 'realtor' } = {}) {
+    if (!Object.hasOwn(neighborhoodCollections, source))
+        throw new RangeError(`Unknown neighborhood source: ${source}`);
+    return findNeighborhood(name, neighborhoodCollections[source]);
+}

package/dist/data/realtor.d.ts

@@ -0,0 +1,4 @@
+import type { FeatureCollection, NeighborhoodProperties } from './types.js';
+export declare const neighborhoods: FeatureCollection<NeighborhoodProperties>;
+/** Look up one SFAR area without importing the other neighborhood definitions. */
+export declare function getRealtorNeighborhood(name: string): import("./types.js").Feature<NeighborhoodProperties> | undefined;

package/dist/data/realtor.js

@@ -0,0 +1,8 @@
+import { deepFreeze } from '../src/immutable.js';
+import { findNeighborhood } from './lookup-utils.js';
+import realtorData from './neighborhoods-realtor.json' with { type: 'json' };
+export const neighborhoods = deepFreeze(realtorData);
+/** Look up one SFAR area without importing the other neighborhood definitions. */
+export function getRealtorNeighborhood(name) {
+    return findNeighborhood(name, neighborhoods);
+}

package/dist/data/roads.d.ts

@@ -0,0 +1,2 @@
+import type { FeatureCollection, KeyRoadProperties } from './types.js';
+export declare const keyRoads: FeatureCollection<KeyRoadProperties>;

package/dist/data/roads.js

@@ -0,0 +1,3 @@
+import { deepFreeze } from '../src/immutable.js';
+import roadData from './key-roads.json' with { type: 'json' };
+export const keyRoads = deepFreeze(roadData);

package/dist/data/sf-find.d.ts

@@ -0,0 +1,2 @@
+import type { FeatureCollection, NeighborhoodProperties } from './types.js';
+export declare const sfFindNeighborhoods: FeatureCollection<NeighborhoodProperties>;

package/dist/data/sf-find.js

@@ -0,0 +1,3 @@
+import { deepFreeze } from '../src/immutable.js';
+import sfFindData from './neighborhoods.json' with { type: 'json' };
+export const sfFindNeighborhoods = deepFreeze(sfFindData);

package/dist/data/stations.d.ts

@@ -0,0 +1,4 @@
+import type { FeatureCollection } from './types.js';
+export declare const bartStations: FeatureCollection<{
+    readonly name: string;
+}>;

package/dist/data/stations.js

@@ -0,0 +1,3 @@
+import { deepFreeze } from '../src/immutable.js';
+import stationData from './bart-stations.json' with { type: 'json' };
+export const bartStations = deepFreeze(stationData);

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

@@ -0,0 +1,3 @@
+import type { InteractiveSFMapData } from './explorer-data.js';
+/** Compact, source-aware geography with no district or alternate-neighborhood files. */
+export declare const guideMapData: InteractiveSFMapData;

package/dist/src/guide-data.js

@@ -0,0 +1,41 @@
+import bart from '../data/guide/bart-stations.json' with { type: 'json' };
+import coast from '../data/guide/coast.json' with { type: 'json' };
+import highways from '../data/guide/highways.json' with { type: 'json' };
+import roads from '../data/guide/key-roads.json' with { type: 'json' };
+import landmarks from '../data/guide/landmarks.json' with { type: 'json' };
+import neighborhoods from '../data/guide/neighborhoods-realtor.json' with { type: 'json' };
+const neighborhoodData = neighborhoods;
+const highwayData = highways;
+const parkData = landmarks;
+const roadData = roads;
+const stationData = bart;
+/** Compact, source-aware geography with no district or alternate-neighborhood files. */
+export const guideMapData = {
+    map: {
+        coast: coast.features[0].geometry,
+        neighborhoods: neighborhoodData.features.map((feature) => ({
+            name: feature.properties.canonicalName,
+            geometry: feature.geometry,
+        })),
+        highways: highwayData.features.map((feature) => ({
+            route: String(feature.properties.route),
+            geometry: feature.geometry,
+        })),
+        landmarks: parkData.features.map(({ id, properties, geometry }) => ({
+            id,
+            ...properties,
+            geometry,
+        })),
+        keyRoads: roadData.features.map(({ id, properties, geometry }) => ({
+            id,
+            ...properties,
+            sourceNames: properties.sourceNames ?? [],
+            segmentIds: properties.segmentIds ?? [],
+            geometry,
+        })),
+        bartStations: stationData.features.flatMap(({ id, properties, geometry }) => geometry.type === 'Point'
+            ? [{ id, name: properties.name, coordinates: geometry.coordinates }]
+            : []),
+    },
+    neighborhoods: { realtor: neighborhoodData },
+};

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

@@ -0,0 +1,3 @@
+import type { InteractiveSFMapData } from './explorer-data.js';
+/** Load detailed selected geography only after the caller requests it. */
+export declare function loadGuideDetailedData(): Promise<InteractiveSFMapData>;

package/dist/src/guide-detailed.js

@@ -0,0 +1,45 @@
+/** Load detailed selected geography only after the caller requests it. */
+export async function loadGuideDetailedData() {
+    const [coastData, neighborhoodData, parkData, highwayData, roadData, bartData] = await Promise.all([
+        import('../data/coast.json', { with: { type: 'json' } }),
+        import('../data/neighborhoods-realtor.json', { with: { type: 'json' } }),
+        import('../data/landmarks.json', { with: { type: 'json' } }),
+        import('../data/guide/highways-detailed.json', { with: { type: 'json' } }),
+        import('../data/key-roads.json', { with: { type: 'json' } }),
+        import('../data/bart-stations.json', { with: { type: 'json' } }),
+    ]);
+    const detailedNeighborhoods = neighborhoodData.default;
+    const detailedRoads = roadData.default;
+    const detailedHighways = highwayData.default;
+    const detailedParks = parkData.default;
+    const detailedStations = bartData.default;
+    return {
+        map: {
+            coast: coastData.default.features[0].geometry,
+            neighborhoods: detailedNeighborhoods.features.map((feature) => ({
+                name: feature.properties.canonicalName,
+                geometry: feature.geometry,
+            })),
+            highways: detailedHighways.features
+                .filter((feature) => ['1', '101', '280'].includes(String(feature.properties.route)))
+                .map((feature) => ({
+                route: String(feature.properties.route),
+                geometry: feature.geometry,
+            })),
+            landmarks: detailedParks.features.map(({ id, properties, geometry }) => ({
+                id,
+                ...properties,
+                geometry,
+            })),
+            keyRoads: detailedRoads.features.map(({ id, properties, geometry }) => ({
+                id,
+                ...properties,
+                geometry,
+            })),
+            bartStations: detailedStations.features.flatMap(({ id, properties, geometry }) => geometry.type === 'Point'
+                ? [{ id, name: properties.name, coordinates: geometry.coordinates }]
+                : []),
+        },
+        neighborhoods: { realtor: detailedNeighborhoods },
+    };
+}

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

@@ -0,0 +1,3 @@
+import type { InteractiveSFMapElement, InteractiveSFMapOptions } from './interactive-data.js';
+/** Guide map preset: SFAR neighborhoods, major parks, BART, and curated roads. */
+export declare function createGuideMap(options?: InteractiveSFMapOptions): InteractiveSFMapElement;

package/dist/src/guide-map.js

@@ -0,0 +1,22 @@
+import { guideMapData } from './guide-data.js';
+import { createInteractiveSFMapWithData } from './interactive-data.js';
+/** Guide map preset: SFAR neighborhoods, major parks, BART, and curated roads. */
+export function createGuideMap(options = {}) {
+    return createInteractiveSFMapWithData(guideMapData, {
+        mode: 'neighborhoods',
+        ...options,
+        layers: {
+            districtFills: false,
+            districtLines: false,
+            districtLabels: false,
+            neighborhoodLines: true,
+            neighborhoodLabels: true,
+            landmarks: true,
+            bartStations: true,
+            highways: true,
+            keyRoads: true,
+            roadLabels: true,
+            ...options.layers,
+        },
+    });
+}

package/dist/src/guide.d.ts

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

package/dist/src/guide.js

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

package/dist/src/transit.js

@@ -1,12 +1,34 @@
 import stations from '../data/bart-stations.json' with { type: 'json' };
-import { createSFMap } from './index.js';
+import coast from '../data/coast.json' with { type: 'json' };
+import districts from '../data/districts-2022.json' with { type: 'json' };
+import parks from '../data/landmarks.json' with { type: 'json' };
+import { createSFMapWithData } from './map-core.js';
+const districtData = districts;
+const parkData = parks;
+const transitMapData = {
+    coast: coast.features[0].geometry,
+    districts: {
+        2022: districtData.features.map(({ geometry, properties }) => ({
+            id: properties.district,
+            label: properties.label,
+            labelPoints: properties.labelPoints,
+            geometry,
+            extras: properties.displayExtras,
+        })),
+    },
+    landmarks: parkData.features.map(({ id, properties, geometry }) => ({
+        id,
+        ...properties,
+        geometry,
+    })),
+};
 /** A deliberately schematic, offline station-to-station animation. Starts paused. */
 export function createTransitAnimation() {
     const host = Object.assign(document.createElement('div'), {
         destroy: () => { },
     });
     const root = host.attachShadow({ mode: 'open' });
-    const map = createSFMap({ districtLabels: false, landmarks: true, labels: false });
+    const map = createSFMapWithData({ districtLabels: false, landmarks: true, labels: false }, transitMapData);
     root.innerHTML = `<style>
     :host{display:block;font:14px system-ui;color:#244747;max-width:800px}
     svg{display:block;width:100%;height:auto} .controls{display:flex;gap:12px;align-items:center;padding:12px;flex-wrap:wrap}

package/docs/EXAMPLES.md

@@ -0,0 +1,87 @@
+# Examples
+
+[Live example gallery](https://kahwee.github.io/sf-map-svg/examples.html) · [California propositions](https://kahwee.github.io/sf-map-svg/propositions.html) · [Local measures](https://kahwee.github.io/sf-map-svg/measures.html) · [Source data](../SOURCES.md)
+
+Choose by task. All snippets use the public package API; browser examples need a DOM and a bundler that supports JSON imports.
+
+| I want to… | Start here |
+| --- | --- |
+| Render an SVG on a server | [Static map](#static-svg) |
+| Add a small map to a browser | [Lightweight guide](#lightweight-interactive-guide) |
+| Bundle only selected geography | [Selected data](#selected-geography) |
+| Draw a route over the city | [Route overlay](#route-overlay) |
+| Explore real election votes | [California propositions](#california-propositions-by-sf-district) |
+
+## Static SVG
+
+```ts
+import { writeFile } from 'node:fs/promises';
+import { renderSFMap } from '@kahwee/sf-map-svg';
+
+const svg = renderSFMap({
+  year: 2022,
+  landmarks: true,
+  bartStations: true,
+  idPrefix: 'example',
+});
+await writeFile('districts.svg', svg);
+```
+
+The root entry includes the built-in geography for convenience. See the [full option list](../README.md#static-options).
+
+## Lightweight interactive guide
+
+```ts
+import { createGuideMap } from '@kahwee/sf-map-svg/guide';
+
+const map = createGuideMap({ layers: { roadLabels: false } });
+document.querySelector('#map')?.append(map);
+```
+
+The guide includes selected coast, SFAR neighborhoods, parks, roads, and stations. Detailed geography loads only when explicitly requested; see the [guide recipe](../README.md#render-a-static-map).
+
+## Selected geography
+
+```ts
+import { createInteractiveSFMapWithData } from '@kahwee/sf-map-svg/interactive-data';
+import coast from '@kahwee/sf-map-svg/data/coast.json' with { type: 'json' };
+import realtor from '@kahwee/sf-map-svg/data/neighborhoods-realtor.json' with { type: 'json' };
+
+const map = createInteractiveSFMapWithData(
+  {
+    map: { coast: coast.features[0].geometry },
+    neighborhoods: { realtor },
+  },
+  { mode: 'neighborhoods', layers: { highways: false, keyRoads: false } },
+);
+document.querySelector('#map')?.append(map);
+```
+
+This imports one neighborhood definition source. To omit its geometry too, import catalog metadata alone from `/data/catalog`.
+
+## Route overlay
+
+```ts
+import { createGuideMap } from '@kahwee/sf-map-svg/guide';
+
+const map = createGuideMap();
+document.querySelector('#map')?.append(map);
+map.setOverlays([{
+  id: 'trip',
+  label: 'Example route',
+  geometry: {
+    type: 'LineString',
+    coordinates: [[-122.4194, 37.7749], [-122.3981, 37.7936]],
+  },
+  stroke: '#a85036',
+  strokeWidth: 3,
+}]);
+```
+
+Coordinates are WGS84 `[longitude, latitude]`. The overlay follows pan and zoom. The [BART journey](https://kahwee.github.io/sf-map-svg/transit.html) is a separate schematic motion example.
+
+## California propositions by SF district
+
+[Open the interactive explorer](https://kahwee.github.io/sf-map-svg/propositions.html). It uses the public `custom-map` renderer with only the 2022 district and coast datasets and colors each district from the [certified results JSON](../data/propositions/2024-11-05.json). The JSON includes all ten statewide propositions on the November 2024 ballot, with Yes and No counts for each of San Francisco's eleven supervisorial districts. Its scope is SF votes, not statewide totals or voter demographics.
+
+The [import script](../scripts/import-2024-propositions.py) checks each district sum against the official citywide count. [Geographic and election sources](../SOURCES.md) explain the provenance.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kahwee/sf-map-svg",
-  "version": "1.3.8",
+  "version": "1.4.1",
   "description": "Offline SVG maps of San Francisco with district boundaries, parks, landmarks, and BART stations.",
   "type": "module",
   "main": "./dist/src/index.js",
@@ -18,6 +18,50 @@
       "types": "./dist/data/index.d.ts",
       "import": "./dist/data/index.js"
     },
+    "./data/analysis": {
+      "types": "./dist/data/analysis.d.ts",
+      "import": "./dist/data/analysis.js"
+    },
+    "./data/catalog": {
+      "types": "./dist/data/catalog.d.ts",
+      "import": "./dist/data/catalog.js"
+    },
+    "./data/coast": {
+      "types": "./dist/data/coast.d.ts",
+      "import": "./dist/data/coast.js"
+    },
+    "./data/districts": {
+      "types": "./dist/data/districts.d.ts",
+      "import": "./dist/data/districts.js"
+    },
+    "./data/highways": {
+      "types": "./dist/data/highways.d.ts",
+      "import": "./dist/data/highways.js"
+    },
+    "./data/landmarks": {
+      "types": "./dist/data/landmarks.d.ts",
+      "import": "./dist/data/landmarks.js"
+    },
+    "./data/lookup": {
+      "types": "./dist/data/lookup.d.ts",
+      "import": "./dist/data/lookup.js"
+    },
+    "./data/realtor": {
+      "types": "./dist/data/realtor.d.ts",
+      "import": "./dist/data/realtor.js"
+    },
+    "./data/roads": {
+      "types": "./dist/data/roads.d.ts",
+      "import": "./dist/data/roads.js"
+    },
+    "./data/sf-find": {
+      "types": "./dist/data/sf-find.d.ts",
+      "import": "./dist/data/sf-find.js"
+    },
+    "./data/stations": {
+      "types": "./dist/data/stations.d.ts",
+      "import": "./dist/data/stations.js"
+    },
     "./data/*.json": "./dist/data/*.json",
     "./geometry": {
       "types": "./dist/src/geometry.d.ts",
@@ -39,6 +83,18 @@
       "types": "./dist/src/guide.d.ts",
       "import": "./dist/src/guide.js"
     },
+    "./guide/data": {
+      "types": "./dist/src/guide-data.d.ts",
+      "import": "./dist/src/guide-data.js"
+    },
+    "./guide/detailed": {
+      "types": "./dist/src/guide-detailed.d.ts",
+      "import": "./dist/src/guide-detailed.js"
+    },
+    "./guide/map": {
+      "types": "./dist/src/guide-map.d.ts",
+      "import": "./dist/src/guide-map.js"
+    },
     "./transit": {
       "types": "./dist/src/transit.d.ts",
       "import": "./dist/src/transit.js"
@@ -46,6 +102,7 @@
   },
   "files": [
     "dist",
+    "docs/EXAMPLES.md",
     "README.md",
     "SOURCES.md",
     "LICENSE"