@kahwee/sf-map-svg 1.4.0 → 1.4.1

package/CHANGELOG.md

@@ -4,6 +4,11 @@ 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.

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

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/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.4.0",
+  "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",
@@ -102,6 +102,7 @@
   },
   "files": [
     "dist",
+    "docs/EXAMPLES.md",
     "README.md",
     "SOURCES.md",
     "LICENSE"