@kahwee/sf-map-svg 1.4.1 → 1.5.1

package/CHANGELOG.md

@@ -4,6 +4,17 @@ User-visible changes are recorded here. Unreleased entries describe changes on `
 
 ## Unreleased
 
+## 1.5.1 — 2026-09-26
+
+- Run focused Storybook 10 browser interactions and accessibility checks in CI and before npm publishing, covering overlapping markers, route overlays, and keyboard selection.
+- Validate certified proposition district sums against city totals in the data test suite.
+- Keep Biome and the development dependency set current after an audit and outdated-package review.
+
+## 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.

package/README.md

@@ -255,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
@@ -370,10 +382,11 @@ pnpm install --frozen-lockfile
 pnpm check            # formatting, data catalog, types, and tests
 pnpm demo             # generated SVGs and example pages
 pnpm build-storybook  # static component documentation
+pnpm test:stories     # Storybook 10 browser checks in Chromium
 pnpm test:package     # install and check the packed package
 ```
 
-Use `pnpm format` to apply Biome formatting and safe lint fixes. Run `pnpm storybook` for interactive component examples at http://127.0.0.1:6006. CI runs checks on Node 22, 24, and 26. See [CONTRIBUTING.md](CONTRIBUTING.md) for source structure and release instructions.
+Use `pnpm format` to apply Biome formatting and safe lint fixes. Install Chromium once with `pnpm exec playwright install chromium` before local Storybook tests. Run `pnpm storybook` for interactive component examples at http://127.0.0.1:6006. CI runs package checks on Node 22, 24, and 26 plus Chromium Storybook checks on Node 24. See [CONTRIBUTING.md](CONTRIBUTING.md) for source structure and release instructions.
 
 ### Browser verification
 

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kahwee/sf-map-svg",
-  "version": "1.4.1",
+  "version": "1.5.1",
   "description": "Offline SVG maps of San Francisco with district boundaries, parks, landmarks, and BART stations.",
   "type": "module",
   "main": "./dist/src/index.js",
@@ -118,13 +118,20 @@
   },
   "devDependencies": {
     "@biomejs/biome": "2.5.14",
+    "@storybook/addon-a11y": "10.6.0",
     "@storybook/addon-docs": "^10.6.0",
+    "@storybook/addon-vitest": "10.6.0",
     "@storybook/html-vite": "^10.6.0",
+    "@vitest/browser-playwright": "^4.1.11",
     "@xmldom/xmldom": "^0.9.12",
+    "playwright": "^1.63.0",
     "polygon-clipping": "^0.15.7",
+    "react": "^19.3.0",
+    "react-dom": "^19.3.0",
     "storybook": "^10.6.0",
     "typescript": "^7.0.2",
-    "vite": "^8.3.1"
+    "vite": "^8.3.1",
+    "vitest": "^4.1.11"
   },
   "homepage": "https://kahwee.github.io/sf-map-svg/",
   "bugs": {
@@ -143,6 +150,7 @@
   },
   "scripts": {
     "test": "pnpm build && node --test",
+    "test:stories": "pnpm build && vitest run --project=storybook",
     "demo": "pnpm build && node examples/build.mjs",
     "format": "biome check --write .",
     "format:check": "biome format .",
@@ -158,6 +166,7 @@
     "test:package": "node scripts/smoke-package.mjs",
     "build": "node scripts/build.mjs",
     "lint": "biome check .",
+    "audit": "pnpm audit --audit-level high",
     "build:pages": "pnpm build && node scripts/build-pages.mjs"
   }
 }