@kahwee/sf-map-svg 1.4.0 → 1.5.0

package/CHANGELOG.md

@@ -4,6 +4,16 @@ User-visible changes are recorded here. Unreleased entries describe changes on `
 
 ## Unreleased
 
+## 1.5.0 — 2026-09-26
+
+- Add `controls.neighborhoodPicker`, `controls.markerPicker`, `controls.help`, and `controls.status` so compact embeds can drop redundant chrome. Hidden help remains the map's accessible description; a hidden status line remains a polite live region; source attribution stays visible.
+- Keep a configured `strings.chooseMarker` label after `setMarkers()` updates instead of reverting to “Choose marker”.
+
+## 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
@@ -246,7 +255,19 @@ aliases. Import types including `InteractiveSFMapOptions`, `InteractiveSFMapElem
 | `overlays` | `[]` | GeoJSON line or polygon overlays with stable IDs and optional SVG styles |
 | `style` | Built-in tokens | Explorer CSS tokens: `ink`, `surface`, `accent`, `border`, `focus`, `controlGap`, `font` |
 | `strings` | English defaults | Replace visible map labels and gesture help for localization |
-| `controls` | All enabled | Independently hide `zoom`, `pan`, `reset`, `labels`, `touch`, or `legend`; source attribution remains visible |
+| `controls` | All enabled | Independently hide `zoom`, `pan`, `reset`, `labels`, `touch`, `legend`, `neighborhoodPicker`, `markerPicker`, `help`, or `status`; source attribution remains visible |
+
+For a compact embed, hide the native choosers only when the page already lists every
+marker or area as an accessible control. Hidden help remains the map's accessible
+description, and a hidden status line remains a polite live region:
+
+```js
+const map = createGuideMap({
+  interface: 'map',
+  controls: { labels: false, neighborhoodPicker: false, markerPicker: false, help: false, status: false },
+  strings: { chooseMarker: 'Place on map' }, // also used after setMarkers() updates
+});
+```
 
 Explicit layer options override mode defaults even after `setMode()`. District fills, outlines,
 and badges can therefore be composed with neighborhood names without requiring district

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/src/explorer-core.js

@@ -30,6 +30,7 @@ function svgElement(tag, attributes = {}) {
         node.setAttribute(key, String(value));
     return node;
 }
+let explorerCount = 0;
 /** Create an offline, browser-only neighborhood explorer. Call destroy() before disposal. */
 export function createNeighborhoodExplorerCore({ source = 'realtor', mode = 'neighborhoods', labels = true, neighborhood, year = 2022, theme = 'transit', interface: chrome = 'explorer', layers = {}, selectableNeighborhoods = true, labelSize = {}, fitPadding = 24, markers: initialMarkers = [], markerRadius = 6, markerHitSize = 44, markerColor = '#245b61', selectedMarkerColor = '#f04f32', onMarkerActivate, overlays: initialOverlays = [], onOverlayActivate, style: styleOptions = {}, strings = {}, controls = {}, } = {}, data) {
     if (!['neighborhoods', 'districts', 'basemap'].includes(mode))
@@ -141,6 +142,7 @@ export function createNeighborhoodExplorerCore({ source = 'realtor', mode = 'nei
 .sf-explorer-hint{padding:6px 16px 10px;font-size:12px;color:#586f80;background:#fff}
 .sf-explorer text{pointer-events:none}
 .sf-explorer-status{padding:0 16px 14px;font-size:12px;background:#fff;color:#496578}
+.sf-explorer-visually-hidden{position:absolute;width:1px;height:1px;margin:-1px;padding:0;overflow:hidden;clip-path:inset(50%);white-space:nowrap;border:0}
 .sf-explorer[data-interface=map] .sf-explorer-body{display:block}
 .sf-explorer[data-interface=map] .sf-explorer-header,.sf-explorer[data-interface=map] .sf-explorer-panel,.sf-explorer[data-interface=map] .sf-explorer-detail{display:none}
 .sf-explorer-feature-controls{display:flex;flex-wrap:wrap;gap:8px;padding:10px;background:#fff}
@@ -222,6 +224,7 @@ export function createNeighborhoodExplorerCore({ source = 'realtor', mode = 'nei
     const canvas = element('div', '', 'sf-explorer-canvas');
     const hint = element('p', strings.gestureHelp ??
         'Drag to pan · Ctrl/⌘ + scroll to zoom · Focus map: arrows pan, +/− zoom, Home resets. Touch: scroll the page, or enable Touch navigation to pan and pinch the map. Escape exits.', 'sf-explorer-hint');
+    hint.id = `sf-explorer-help-${++explorerCount}`;
     const status = element('p', '', 'sf-explorer-status');
     status.setAttribute('aria-live', 'polite');
     const legend = element('div', '', 'sf-explorer-legend');
@@ -764,12 +767,19 @@ export function createNeighborhoodExplorerCore({ source = 'realtor', mode = 'nei
                     ? `${year} supervisorial districts. Numbers identify each district.`
                     : `${formatSourceLabel(source)}. Select a neighborhood to begin.`;
     }
+    function syncFeatureControls() {
+        featureControls.hidden = neighborhoodLabel.hidden && markerLabel.hidden;
+    }
     function updateComposition() {
         const neighborhoodsVisible = enabled('neighborhoodLines') || (labels && enabled('neighborhoodLabels'));
         areas.style.display = neighborhoodsVisible ? '' : 'none';
         areas.style.pointerEvents = selectableNeighborhoods ? '' : 'none';
         neighborhoodLabel.hidden =
-            !neighborhoodsVisible || !selectableNeighborhoods || chrome === 'explorer';
+            !neighborhoodsVisible ||
+                !selectableNeighborhoods ||
+                chrome === 'explorer' ||
+                controls.neighborhoodPicker === false;
+        syncFeatureControls();
         for (const item of items) {
             item.node.setAttribute('stroke-width', item.feature === selected ? '2.2' : enabled('neighborhoodLines') ? '.55' : '0');
             item.node.setAttribute('tabindex', selectableNeighborhoods && item === items[0] ? '0' : '-1');
@@ -881,9 +891,10 @@ export function createNeighborhoodExplorerCore({ source = 'realtor', mode = 'nei
             markerSelect.append(option);
             return { marker, point, node, dot, hit };
         });
-        markerLabel.hidden = !markerItems.length;
+        markerLabel.hidden = !markerItems.length || controls.markerPicker === false;
         if (markerLabel.firstChild)
-            markerLabel.firstChild.textContent = `Choose marker (${markerItems.length})`;
+            markerLabel.firstChild.textContent = `${strings.chooseMarker ?? 'Choose marker'} (${markerItems.length})`;
+        syncFeatureControls();
         const nextSelection = previous && ids.has(previous)
             ? previous
             : (markers.find((marker) => marker.selected)?.id ?? null);
@@ -902,6 +913,13 @@ export function createNeighborhoodExplorerCore({ source = 'realtor', mode = 'nei
         labelsButton.hidden = true;
     if (controls.legend === false)
         legend.hidden = true;
+    if (controls.help === false) {
+        // The instructions stay available to assistive technology as the map's description.
+        hint.hidden = true;
+        svg.setAttribute('aria-describedby', hint.id);
+    }
+    if (controls.status === false)
+        status.classList.add('sf-explorer-visually-hidden');
     function setMode(next) {
         if (destroyed)
             return;

package/dist/src/types.d.ts

@@ -101,7 +101,12 @@ export interface NeighborhoodExplorerOptions {
     /** Stable theme tokens consumed by the explorer chrome. */
     style?: Partial<Record<'ink' | 'surface' | 'accent' | 'border' | 'focus' | 'controlGap' | 'font', string>>;
     strings?: Partial<Record<'title' | 'mode' | 'source' | 'search' | 'chooseNeighborhood' | 'chooseMarker' | 'touchNavigation' | 'reset' | 'emptyResults' | 'gestureHelp', string>>;
-    controls?: Partial<Record<'zoom' | 'pan' | 'reset' | 'labels' | 'touch' | 'legend', boolean>>;
+    /**
+     * 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<Record<'zoom' | 'pan' | 'reset' | 'labels' | 'touch' | 'legend' | 'neighborhoodPicker' | 'markerPicker' | 'help' | 'status', boolean>>;
 }
 export interface NeighborhoodExplorerElement extends HTMLElement {
     selectNeighborhood(name: string | null, options?: {

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.5.0",
   "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"