@kahwee/sf-map-svg 4.3.0 → 4.3.1

package/CHANGELOG.md

@@ -4,6 +4,12 @@ User-visible changes are recorded here. Unreleased entries describe changes on `
 
 ## Unreleased
 
+## 4.3.1 — 2026-10-04
+
+- Reject unknown flat static options and invalid values before rendering or invoking district styling callbacks, matching grouped-option validation.
+- Ignore undefined static color overrides so SVG attributes retain the selected theme's defaults; preserve grouped-option precedence.
+- Describe the actual neighborhood source, enabled and supplied layers, and park and BART station counts in static SVG descriptions. Compact geography uses a source-neutral description.
+
 ## 4.3.0 — 2026-10-02
 
 - Add `selectFeature` with typed marker, neighborhood source/ID and district year/ID references. Missing or mismatched identities preserve current geography and selection.

package/dist/src/map-core.js

@@ -105,7 +105,8 @@ const transitColors = {
     selected: '#0073ae',
 };
 export function resolveMapColors(theme, colors = {}) {
-    return { ...defaults, ...(theme === 'transit' ? transitColors : {}), ...colors };
+    const supplied = Object.fromEntries(Object.entries(colors).filter(([, value]) => value !== undefined));
+    return { ...defaults, ...(theme === 'transit' ? transitColors : {}), ...supplied };
 }
 let sequence = 0;
 /** Make an offline SVG and the matching longitude/latitude projection. */
@@ -143,8 +144,29 @@ export function createSFMapWithData(options, data) {
             };
         })
         : [];
+    const neighborhoodDescription = options.source === 'realtor'
+        ? 'SFAR realtor neighborhood areas, defined in August 2010'
+        : options.source === 'sf-find'
+            ? 'SF Find neighborhood areas'
+            : options.source === 'analysis'
+                ? 'DataSF analysis neighborhood areas'
+                : 'the supplied neighborhood areas';
+    const description = [
+        districts.length && (districtFills || districtLines || (labels && districtLabels))
+            ? `San Francisco district boundaries (${year}).`
+            : 'San Francisco map.',
+        neighborhoodLines && data.neighborhoods?.length
+            ? `Dashed lines show ${neighborhoodDescription}.`
+            : '',
+        landmarks && landmarkData.length ? `Park and landmark features: ${landmarkData.length}.` : '',
+        keyRoads && roadData.length ? 'Selected road corridors.' : '',
+        bartStations && stationData.length ? `BART stations: ${stationData.length}.` : '',
+        'See SOURCES.md for geographic sources.',
+    ]
+        .filter(Boolean)
+        .join(' ');
     const parts = [
-        `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ${width} ${height}" width="${width}" height="${height}" role="img" aria-labelledby="${idPrefix}-title" data-sf-map="" data-year="${year}"${animated ? ` data-sf-animate="${idPrefix}"` : ''} style="max-width:100%;height:auto"><title id="${idPrefix}-title">${escapeXml(title)}</title><desc>San Francisco supervisorial district boundaries (${year}).${neighborhoodLines ? ' Dashed lines show SFAR realtor neighborhood areas, defined in August 2010.' : ''}${landmarks ? ' Highlighted areas show six parks and landmarks.' : ''}${keyRoads ? ' Thin gray lines show selected road corridors.' : ''}${bartStations ? ' Rings mark the eight San Francisco BART stations.' : ''} Geometry from DataSF${bartStations ? ' and BART' : ''}. See package SOURCES.md.</desc>${animation ? staticAnimationStyle(idPrefix, animation) : ''}<defs><clipPath id="${idPrefix}-coast"><path d="${coastPath}" fill-rule="evenodd" clip-rule="evenodd"/></clipPath></defs><rect width="${width}" height="${height}" fill="${escapeXml(colors.water)}"/><g data-layer="geography"><path data-layer="coast" d="${coastPath}" fill="${escapeXml(colors.land)}" fill-rule="evenodd"/>`,
+        `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ${width} ${height}" width="${width}" height="${height}" role="img" aria-labelledby="${idPrefix}-title" data-sf-map="" data-year="${year}"${animated ? ` data-sf-animate="${idPrefix}"` : ''} style="max-width:100%;height:auto"><title id="${idPrefix}-title">${escapeXml(title)}</title><desc>${escapeXml(description)}</desc>${animation ? staticAnimationStyle(idPrefix, animation) : ''}<defs><clipPath id="${idPrefix}-coast"><path d="${coastPath}" fill-rule="evenodd" clip-rule="evenodd"/></clipPath></defs><rect width="${width}" height="${height}" fill="${escapeXml(colors.water)}"/><g data-layer="geography"><path data-layer="coast" d="${coastPath}" fill="${escapeXml(colors.land)}" fill-rule="evenodd"/>`,
     ];
     // Explicit drawing order keeps optional overlays and user markers predictable.
     if (districtFills)

package/dist/src/static.js

@@ -1,16 +1,18 @@
 import { prepareAppearance } from './appearance.js';
 import { validateSwitchPatch } from './features.js';
 import { createSFMapWithData, getLayerPathsWithData } from './map-core.js';
-import { assertOptions } from './validation.js';
+import { normalizeStaticAnimation } from './static-animation.js';
+import { assertOptions, validateMarkers, validateOverlays } from './validation.js';
 /** Server-safe SVG rendering with explicit data; returns SVG plus projection helpers. */
 export function renderMap(data, options = {}) {
     const prepared = expandStaticOptions(options);
-    return createSFMapWithData(prepared, staticInput(data, prepared));
+    const { map, source } = staticInput(data, prepared);
+    return createSFMapWithData({ ...prepared, source }, map);
 }
 /** Project canonical layer geometry without constructing an SVG string. */
 export function getLayerPaths(data, options = {}) {
     const prepared = expandStaticOptions(options);
-    return getLayerPathsWithData(prepared, staticInput(data, prepared));
+    return getLayerPathsWithData(prepared, staticInput(data, prepared).map);
 }
 /** Borrow immutable geometry, deriving only the renderer's lightweight neighborhood rows. */
 function staticInput(data, options) {
@@ -19,45 +21,79 @@ function staticInput(data, options) {
     if (!('map' in data)) {
         if (options.source !== undefined)
             throw new TypeError('source requires source-aware MapData; compact StaticMapData already chooses its geography.');
-        return data;
+        return { map: data, source: undefined };
     }
     const source = options.source ??
         ['realtor', 'sf-find', 'analysis'].find((candidate) => !!data.neighborhoods[candidate]);
     if (source === undefined)
-        return data.map;
+        return { map: data.map, source: undefined };
     const collection = data.neighborhoods[source];
     if (!collection)
         throw new RangeError(`No ${source} neighborhood dataset was supplied.`);
     return {
-        ...data.map,
-        neighborhoods: collection.features.map(({ geometry, properties }) => ({
-            name: properties.sourceName,
-            geometry,
-        })),
+        source,
+        map: {
+            ...data.map,
+            neighborhoods: collection.features.map(({ geometry, properties }) => ({
+                name: properties.sourceName,
+                geometry,
+            })),
+        },
     };
 }
+const staticLayerKeys = [
+    'districtFills',
+    'districtLines',
+    'districtLabels',
+    'neighborhoodLines',
+    'landmarks',
+    'bartStations',
+    'highways',
+    'keyRoads',
+    'roadLabels',
+];
 /** Grouped keys override flat compatibility keys; omitted keys preserve renderer defaults. */
 function expandStaticOptions(options) {
-    assertOptions(options, 'static map');
+    assertOptions(options, 'static map', [
+        ...staticLayerKeys,
+        'layers',
+        'appearance',
+        'theme',
+        'colors',
+        'districtStyle',
+        'width',
+        'height',
+        'padding',
+        'year',
+        'source',
+        'labels',
+        'markers',
+        'overlays',
+        'title',
+        'idPrefix',
+        'animation',
+    ]);
+    for (const key of [...staticLayerKeys, 'labels'])
+        if (options[key] !== undefined && typeof options[key] !== 'boolean')
+            throw new TypeError(`${key} must be boolean.`);
+    for (const key of ['title', 'idPrefix'])
+        if (options[key] !== undefined && typeof options[key] !== 'string')
+            throw new TypeError(`${key} must be a string.`);
+    if (options.markers !== undefined)
+        validateMarkers(options.markers);
+    if (options.overlays !== undefined)
+        validateOverlays(options.overlays);
+    normalizeStaticAnimation(options.animation);
     if (options.layers !== undefined)
-        validateSwitchPatch(options.layers, [
-            'districtFills',
-            'districtLines',
-            'districtLabels',
-            'neighborhoodLines',
-            'landmarks',
-            'bartStations',
-            'highways',
-            'keyRoads',
-            'roadLabels',
-        ]);
+        validateSwitchPatch(options.layers, staticLayerKeys);
     if (options.appearance !== undefined) {
         assertOptions(options.appearance, 'static appearance', ['theme', 'colors', 'districtStyle']);
     }
-    const { layers, appearance, ...flat } = options;
+    const { layers, appearance, theme, colors, districtStyle, ...flat } = options;
     const supplied = (group = {}) => Object.fromEntries(Object.entries(group).filter(([, value]) => value !== undefined));
     return {
         ...flat,
+        ...prepareAppearance({}, { theme, colors, districtStyle }),
         ...supplied(layers),
         ...supplied(appearance === undefined ? undefined : prepareAppearance({}, appearance)),
     };

package/docs/API.md

@@ -19,12 +19,14 @@ const { svg } = renderMap(staticMapData, presentation);
 const map = createMap(fullMapData, presentation);
 ```
 
-Static `layers` supports every interactive layer switch except `neighborhoodLabels`. Static `appearance` supports `theme`, `colors`, and `districtStyle`; browser typography, area interaction styles, and screen-space marker sizing remain interactive settings. Unknown grouped keys are rejected. Supplied grouped keys override flat compatibility keys; omitted or `undefined` grouped keys preserve the flat value or renderer default. The two renderers retain their existing defaults. Marker arrays accept readonly inputs.
+Static `layers` supports every interactive layer switch except `neighborhoodLabels`. Static `appearance` supports `theme`, `colors`, and `districtStyle`; browser typography, area interaction styles, and screen-space marker sizing remain interactive settings. Unknown keys and invalid values are rejected for both flat and grouped options. Supplied grouped keys override flat compatibility keys; omitted or `undefined` grouped keys preserve the flat value or renderer default. Undefined color tokens use the theme default instead of entering SVG attributes. The two renderers retain their existing defaults. Marker arrays accept readonly inputs.
 
 Flat compatibility options include `theme`, `width`, `height`, `padding`, `year` (2002, 2012, 2022), `districtLines`, `districtFills`, `districtStyle`, `districtLabels`, `neighborhoodLines`, `labels`, `highways`, `keyRoads`, `roadLabels`, `landmarks`, `bartStations`, `markers`, `overlays`, `title`, `idPrefix`, `colors`, and `animation`. Each optional layer is independent. User-supplied text and attributes are escaped in SVG output.
 
 Custom district IDs must be finite numbers. An empty `labelPoints` array uses the district's primary `label` position.
 
+The SVG description names the selected neighborhood source for source-aware data and uses a generic description for compact inputs. It describes enabled layers only when their data is supplied, using actual park and station counts.
+
 `animation: true` (or `{ duration, delay }`) makes a static map draw itself with self-contained, scoped CSS: land fades in, the coast and lines draw, districts grow, then labels and points appear. It plays when the SVG is inserted into a page or loaded as an image, needs no JavaScript, and stays still under `prefers-reduced-motion`. Re-insert the markup to replay it. Default output is unchanged.
 
 ## Interactive maps

package/llms-full.txt

@@ -2,13 +2,13 @@
 
 > Offline San Francisco SVG maps with explicit geographic imports, no runtime dependencies, static rendering, and a browser controller.
 
-@kahwee/sf-map-svg 4.3.0 · local working tree. Node >=24.0.0 for server rendering; browsers need a DOM and a JSON-capable bundler.
+@kahwee/sf-map-svg 4.3.1 · local working tree. Node >=24.0.0 for server rendering; browsers need a DOM and a JSON-capable bundler.
 
 These are working-tree docs. Unreleased changelog entries may describe APIs absent from npm; verify the installed version before copying them.
 
 Use renderMap(data, options) for SVG strings; createMap(data, options) returns a controller. Mount map.element and destroy it on unmount. Choose mode explicitly: createMap defaults to basemap. Geography is separate; staticMapData and fullMapData have different shapes.
 
-<!-- Generated from README.md; @kahwee/sf-map-svg 4.3.0 · local working tree. -->
+<!-- Generated from README.md; @kahwee/sf-map-svg 4.3.1 · local working tree. -->
 
 # SF Map SVG
 
@@ -87,7 +87,7 @@ Install with `pnpm install --frozen-lockfile`. See the [contributing guide](http
 
 ---
 
-<!-- Generated from docs/developer-guide.md; @kahwee/sf-map-svg 4.3.0 · local working tree. -->
+<!-- Generated from docs/developer-guide.md; @kahwee/sf-map-svg 4.3.1 · local working tree. -->
 
 # Developer guide
 
@@ -231,7 +231,7 @@ See [API options](https://github.com/kahwee/sf-map-svg/blob/main/docs/API.md), [
 
 ---
 
-<!-- Generated from docs/API.md; @kahwee/sf-map-svg 4.3.0 · local working tree. -->
+<!-- Generated from docs/API.md; @kahwee/sf-map-svg 4.3.1 · local working tree. -->
 
 # Map options and lifecycle
 
@@ -254,12 +254,14 @@ const { svg } = renderMap(staticMapData, presentation);
 const map = createMap(fullMapData, presentation);
 ```
 
-Static `layers` supports every interactive layer switch except `neighborhoodLabels`. Static `appearance` supports `theme`, `colors`, and `districtStyle`; browser typography, area interaction styles, and screen-space marker sizing remain interactive settings. Unknown grouped keys are rejected. Supplied grouped keys override flat compatibility keys; omitted or `undefined` grouped keys preserve the flat value or renderer default. The two renderers retain their existing defaults. Marker arrays accept readonly inputs.
+Static `layers` supports every interactive layer switch except `neighborhoodLabels`. Static `appearance` supports `theme`, `colors`, and `districtStyle`; browser typography, area interaction styles, and screen-space marker sizing remain interactive settings. Unknown keys and invalid values are rejected for both flat and grouped options. Supplied grouped keys override flat compatibility keys; omitted or `undefined` grouped keys preserve the flat value or renderer default. Undefined color tokens use the theme default instead of entering SVG attributes. The two renderers retain their existing defaults. Marker arrays accept readonly inputs.
 
 Flat compatibility options include `theme`, `width`, `height`, `padding`, `year` (2002, 2012, 2022), `districtLines`, `districtFills`, `districtStyle`, `districtLabels`, `neighborhoodLines`, `labels`, `highways`, `keyRoads`, `roadLabels`, `landmarks`, `bartStations`, `markers`, `overlays`, `title`, `idPrefix`, `colors`, and `animation`. Each optional layer is independent. User-supplied text and attributes are escaped in SVG output.
 
 Custom district IDs must be finite numbers. An empty `labelPoints` array uses the district's primary `label` position.
 
+The SVG description names the selected neighborhood source for source-aware data and uses a generic description for compact inputs. It describes enabled layers only when their data is supplied, using actual park and station counts.
+
 `animation: true` (or `{ duration, delay }`) makes a static map draw itself with self-contained, scoped CSS: land fades in, the coast and lines draw, districts grow, then labels and points appear. It plays when the SVG is inserted into a page or loaded as an image, needs no JavaScript, and stays still under `prefers-reduced-motion`. Re-insert the markup to replay it. Default output is unchanged.
 
 ## Interactive maps
@@ -335,7 +337,7 @@ Explore presentation options in the [live map design playground](https://kahwee.
 
 ---
 
-<!-- Generated from docs/EXAMPLES.md; @kahwee/sf-map-svg 4.3.0 · local working tree. -->
+<!-- Generated from docs/EXAMPLES.md; @kahwee/sf-map-svg 4.3.1 · local working tree. -->
 
 # Examples
 
@@ -446,7 +448,7 @@ For the controller and explicit data imports, see [the v3 migration guide](https
 
 ---
 
-<!-- Generated from docs/consumer-integration.md; @kahwee/sf-map-svg 4.3.0 · local working tree. -->
+<!-- Generated from docs/consumer-integration.md; @kahwee/sf-map-svg 4.3.1 · local working tree. -->
 
 # Embedding and progressive enhancement
 
@@ -498,7 +500,7 @@ See the [exact API contract](https://github.com/kahwee/sf-map-svg/blob/main/docs
 
 ---
 
-<!-- Generated from docs/migration-v3.md; @kahwee/sf-map-svg 4.3.0 · local working tree. -->
+<!-- Generated from docs/migration-v3.md; @kahwee/sf-map-svg 4.3.1 · local working tree. -->
 
 # Migrate to version 3
 
@@ -539,7 +541,7 @@ District styles are now prepared once per district on construction and style/yea
 
 ---
 
-<!-- Generated from SOURCES.md; @kahwee/sf-map-svg 4.3.0 · local working tree. -->
+<!-- Generated from SOURCES.md; @kahwee/sf-map-svg 4.3.1 · local working tree. -->
 
 # Geometry and provenance
 
@@ -723,7 +725,7 @@ display geometry, and no precinct polygons or raw workbook data are shipped.
 
 ---
 
-<!-- Generated from CHANGELOG.md; @kahwee/sf-map-svg 4.3.0 · local working tree. -->
+<!-- Generated from CHANGELOG.md; @kahwee/sf-map-svg 4.3.1 · local working tree. -->
 
 # Changelog
 
@@ -731,6 +733,12 @@ User-visible changes are recorded here. Unreleased entries describe changes on `
 
 ## Unreleased
 
+## 4.3.1 — 2026-10-04
+
+- Reject unknown flat static options and invalid values before rendering or invoking district styling callbacks, matching grouped-option validation.
+- Ignore undefined static color overrides so SVG attributes retain the selected theme's defaults; preserve grouped-option precedence.
+- Describe the actual neighborhood source, enabled and supplied layers, and park and BART station counts in static SVG descriptions. Compact geography uses a source-neutral description.
+
 ## 4.3.0 — 2026-10-02
 
 - Add `selectFeature` with typed marker, neighborhood source/ID and district year/ID references. Missing or mismatched identities preserve current geography and selection.
@@ -1043,7 +1051,7 @@ consistent home, and makes animation and subscription ownership predictable.
 
 # Published type contracts
 
-@kahwee/sf-map-svg 4.3.0 · local working tree. These declarations are generated by TypeScript. Use package export paths, not the internal filenames below. Imported relative contracts are included for context, not as additional public entry points.
+@kahwee/sf-map-svg 4.3.1 · local working tree. These declarations are generated by TypeScript. Use package export paths, not the internal filenames below. Imported relative contracts are included for context, not as additional public entry points.
 
 | Public import | Declaration |
 | --- | --- |

package/llms.txt

@@ -2,7 +2,7 @@
 
 > Offline San Francisco SVG maps with explicit geographic imports, no runtime dependencies, static rendering, and a browser controller.
 
-@kahwee/sf-map-svg 4.3.0 · local working tree. Node >=24.0.0 for server rendering; browsers need a DOM and a JSON-capable bundler.
+@kahwee/sf-map-svg 4.3.1 · local working tree. Node >=24.0.0 for server rendering; browsers need a DOM and a JSON-capable bundler.
 
 These are working-tree docs. Unreleased changelog entries may describe APIs absent from npm; verify the installed version before copying them.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kahwee/sf-map-svg",
-  "version": "4.3.0",
+  "version": "4.3.1",
   "description": "Offline SVG maps of San Francisco with district boundaries, parks, landmarks, and BART stations.",
   "type": "module",
   "main": "./dist/src/api.js",