@kahwee/sf-map-svg 5.1.0 → 5.1.2

package/CHANGELOG.md

@@ -4,6 +4,16 @@ User-visible changes are recorded here. Unreleased entries describe changes on `
 
 ## Unreleased
 
+## 5.1.2 — 2026-11-05
+
+- Separate marker selection, activation and focus recovery into an internal controller; separate label candidate caching, screen-space collision layout and metrics invalidation into a label coordinator. Preserve the public API and shared animation frame scheduling.
+
+## 5.1.1 — 2026-11-05
+
+- Reserve precinct report controls and status space during loading to prevent phone layout shifts when multiple reports are available.
+
+- Isolate district selection, style revisions and cancellable motion in an internal controller while preserving public map behavior. Document interactive state ownership and verify district lifecycle callbacks.
+
 ## 5.1.0 — 2026-11-05
 
 - Add official November 2026 precinct aggregates (`data/elections/precincts-<report time>.json` with a time-ordered `precincts-index.json`) and the 2022 precinct boundaries (`data/precincts-2022.json`), reconciled with the department's summary report. Only aggregates are committed, never the ballot-level export. Export the boundaries as `precinctMaps` from `@kahwee/sf-map-svg/data` and `@kahwee/sf-map-svg/data/precincts`; results snapshots stay Pages data.

package/dist/src/district-controller.d.ts

@@ -0,0 +1,64 @@
+import type { Geometry, Position } from '../data/types.js';
+import { prepareDistrictStyles } from './district-style.js';
+import type { InteractiveSFMapData } from './explorer-data.js';
+import type { normalizeFeatures } from './features.js';
+import type { LabelItem } from './label-candidates.js';
+import type { CameraOptions, DistrictSelection, DistrictYear, NeighborhoodExplorerOptions } from './types.js';
+type Host = {
+    root: HTMLElement;
+    svg: SVGSVGElement;
+    status: HTMLElement;
+    data: InteractiveSFMapData;
+    districtLayers: SVGGElement[];
+    get year(): DistrictYear;
+    set year(value: DistrictYear);
+    get theme(): NeighborhoodExplorerOptions['theme'];
+    get colors(): NonNullable<NeighborhoodExplorerOptions['colors']>;
+    get features(): ReturnType<typeof normalizeFeatures>;
+    get destroyed(): boolean;
+    get initialized(): boolean;
+    reducedMotion: MediaQueryList;
+    enabled(layer: 'districtFills' | 'districtLines'): boolean;
+    fadeDuration(): number;
+    fitGeometry(geometry: Geometry, padding: undefined, options: CameraOptions): void;
+    project(point: Position): [number, number];
+    setLabels(items: LabelItem[]): void;
+    updateComposition(): void;
+    scheduleLabels(): void;
+};
+/** Owns district selection, styles, revisions and cancellable motion. */
+export declare function createDistrictController(host: Host, initialDistrictStyle: NeighborhoodExplorerOptions['districtStyle']): {
+    districtRow: (id: number) => import("./map-core.js").DistrictRowData | undefined;
+    districtSelection: (id: number | null) => DistrictSelection | {
+        id: null;
+        year: DistrictYear;
+        district: null;
+    };
+    getSelectedDistrict: () => DistrictSelection | null;
+    updateDistrictAppearance: () => void;
+    selectDistrict: (id: number | null, options?: {
+        fit?: boolean;
+    } & CameraOptions) => boolean;
+    activateDistrict: (id: number) => boolean;
+    setDistrictStyle: (style: ((district: import('./map-core.js').DistrictRowData) => import("./types.js").DistrictStyle) | undefined) => void;
+    setDistrictYear: (next: DistrictYear, options?: CameraOptions, preparedStyles?: ReturnType<typeof prepareDistrictStyles>) => void;
+    transition: {
+        cancel(): void;
+        fade(layer: SVGGElement, duration: number): void;
+    };
+    morph: {
+        stop: () => void;
+        start(layer: SVGGElement, previous: ReadonlyMap<string, string>, { duration, stroke }: {
+            duration: number;
+            stroke: string;
+        }): void;
+        readonly active: boolean;
+    };
+    readonly revision: number;
+    invalidate(): void;
+    readonly style: ((district: import('./map-core.js').DistrictRowData) => import("./types.js").DistrictStyle) | undefined;
+    readonly styles: ReadonlyMap<number, import("./types.js").DistrictStyle>;
+    commitStyles(style: ((district: import('./map-core.js').DistrictRowData) => import("./types.js").DistrictStyle) | undefined, styles: ReadonlyMap<number, import("./types.js").DistrictStyle>): void;
+    hovered: number | null;
+};
+export {};

package/dist/src/district-controller.js

@@ -0,0 +1,215 @@
+import { validateCameraOptions } from './camera.js';
+import { renderDistrictAppearance } from './district-layer.js';
+import { createDistrictMorph } from './district-morph.js';
+import { prepareDistrictStyles } from './district-style.js';
+import { createDistrictTransition } from './district-transition.js';
+import { svgElement } from './dom.js';
+import { getLayerPathsWithData } from './map-core.js';
+/** Owns district selection, styles, revisions and cancellable motion. */
+export function createDistrictController(host, initialDistrictStyle) {
+    const { root, svg, status, data, districtLayers, reducedMotion, enabled, fitGeometry, updateComposition, scheduleLabels, } = host;
+    const districtMorph = createDistrictMorph();
+    let selectedDistrict = null;
+    let hoveredDistrict = null;
+    let districtStyle = initialDistrictStyle;
+    let districtStyles = prepareDistrictStyles(data.map.districts?.[host.year] ?? [], districtStyle);
+    const districtTransition = createDistrictTransition();
+    let districtRevision = 0;
+    root.dataset.year = String(host.year);
+    function districtRow(id) {
+        return data.map.districts?.[host.year]?.find((district) => district.id === id);
+    }
+    function districtSelection(id) {
+        const district = id === null ? undefined : districtRow(id);
+        return district
+            ? { id: district.id, year: host.year, district: structuredClone(district) }
+            : { id: null, year: host.year, district: null };
+    }
+    function getSelectedDistrict() {
+        return selectedDistrict === null
+            ? null
+            : districtSelection(selectedDistrict);
+    }
+    function updateDistrictAppearance() {
+        renderDistrictAppearance({
+            svg,
+            rows: data.map.districts?.[host.year] ?? [],
+            styles: districtStyles,
+            selectedDistrict,
+            hoveredDistrict,
+            year: host.year,
+            theme: host.theme,
+            colors: host.colors,
+            fills: enabled('districtFills'),
+            lines: enabled('districtLines'),
+        });
+    }
+    function selectDistrict(id, options = {}) {
+        if (host.destroyed)
+            return false;
+        validateCameraOptions(options);
+        if (id !== null && (!Number.isInteger(id) || !districtRow(id)))
+            return false;
+        const changed = selectedDistrict !== id;
+        const revision = ++districtRevision;
+        selectedDistrict = id;
+        if (id === null)
+            delete root.dataset.selectedDistrict;
+        else
+            root.dataset.selectedDistrict = String(id);
+        updateDistrictAppearance();
+        const selectedRow = id === null ? undefined : districtRow(id);
+        if (selectedRow && options.fit)
+            fitGeometry(selectedRow.geometry, undefined, options);
+        if (host.destroyed || revision !== districtRevision)
+            return true;
+        status.textContent =
+            id === null
+                ? 'District selection cleared.'
+                : `District ${id} selected, ${host.year} boundaries.`;
+        if (changed)
+            root.dispatchEvent(new CustomEvent('districtchange', { bubbles: true, detail: districtSelection(id) }));
+        return true;
+    }
+    function activateDistrict(id) {
+        const revision = districtRevision + 1;
+        if (!selectDistrict(id) || host.destroyed || revision !== districtRevision)
+            return false;
+        root.dispatchEvent(new CustomEvent('districtactivate', { bubbles: true, detail: districtSelection(id) }));
+        return !host.destroyed && revision === districtRevision;
+    }
+    function setDistrictStyle(style) {
+        if (host.destroyed)
+            return;
+        const revision = districtRevision;
+        const prepared = prepareDistrictStyles(data.map.districts?.[host.year] ?? [], style);
+        if (host.destroyed || revision !== districtRevision)
+            return;
+        districtRevision++;
+        districtStyle = style;
+        districtStyles = prepared;
+        const fills = districtLayers.find((layer) => layer.dataset.layer === 'district-fills');
+        const fade = host.fadeDuration();
+        // A new style settles any fill crossfade still running from an earlier change.
+        districtTransition.cancel();
+        if (fills && fade && enabled('districtFills'))
+            districtTransition.fade(fills, fade);
+        updateDistrictAppearance();
+    }
+    function setDistrictYear(next, options = {}, preparedStyles) {
+        if (host.destroyed)
+            return;
+        validateCameraOptions(options);
+        if (![2002, 2012, 2022].includes(next))
+            throw new RangeError('District year must be 2002, 2012, or 2022.');
+        if (!data.map.districts?.[next] || !data.districts?.[next])
+            throw new RangeError(`No ${next} district dataset was supplied.`);
+        if (next === host.year)
+            return;
+        const revision = districtRevision;
+        const prepared = preparedStyles ?? prepareDistrictStyles(data.map.districts[next], districtStyle);
+        if (host.destroyed || revision !== districtRevision)
+            return;
+        const committedRevision = ++districtRevision;
+        const geometry = getLayerPathsWithData({ year: next }, data.map, false);
+        const previousYear = host.year;
+        districtTransition.cancel();
+        districtMorph.stop();
+        const lineLayer = districtLayers.find((layer) => layer.dataset.layer === 'district-lines');
+        const morph = host.features.districtMorph &&
+            options.animate !== false &&
+            host.initialized &&
+            !reducedMotion.matches &&
+            (enabled('districtLines') || enabled('districtFills'))
+            ? host.features.districtMorph
+            : false;
+        const previousOutlines = morph && lineLayer
+            ? new Map([...lineLayer.querySelectorAll('path[data-district]')].map((path) => [
+                path.dataset.district ?? '',
+                path.getAttribute('d') ?? '',
+            ]))
+            : undefined;
+        for (const layer of districtLayers) {
+            if (morph) {
+                // The morph replaces the line crossfade; fills fade across the whole morph.
+                if (layer !== lineLayer)
+                    districtTransition.fade(layer, morph.duration);
+            }
+            else if (options.animate && !reducedMotion.matches)
+                districtTransition.fade(layer, options.duration ?? 280);
+            layer.replaceChildren(...geometry.districts.map((district) => svgElement('path', {
+                'data-district': district.id,
+                d: district.path,
+                ...(layer.dataset.layer === 'district-fills'
+                    ? { 'fill-rule': 'evenodd' }
+                    : { fill: 'none', 'stroke-width': 1.1 }),
+            })));
+        }
+        host.year = next;
+        districtStyles = prepared;
+        hoveredDistrict = null;
+        root.dataset.year = String(host.year);
+        svg.dataset.year = String(host.year);
+        host.setLabels((data.districts[next]?.features ?? []).flatMap((feature) => feature.properties.labelPoints.map((point) => ({
+            point: host.project(point),
+            name: String(feature.properties.district),
+            kind: 'district',
+        }))));
+        if (selectedDistrict !== null && !districtRow(selectedDistrict))
+            selectedDistrict = null;
+        if (selectedDistrict === null)
+            delete root.dataset.selectedDistrict;
+        updateDistrictAppearance();
+        updateComposition();
+        if (morph && lineLayer && previousOutlines)
+            districtMorph.start(lineLayer, previousOutlines, {
+                duration: morph.duration,
+                stroke: host.colors.district ?? '#71838a',
+            });
+        scheduleLabels();
+        status.textContent = `${host.year} supervisorial districts.`;
+        root.dispatchEvent(new CustomEvent('districtyearchange', {
+            bubbles: true,
+            detail: { year: host.year, previousYear },
+        }));
+        if (!host.destroyed && committedRevision === districtRevision && selectedDistrict !== null)
+            root.dispatchEvent(new CustomEvent('districtchange', {
+                bubbles: true,
+                detail: districtSelection(selectedDistrict),
+            }));
+    }
+    return {
+        districtRow,
+        districtSelection,
+        getSelectedDistrict,
+        updateDistrictAppearance,
+        selectDistrict,
+        activateDistrict,
+        setDistrictStyle,
+        setDistrictYear,
+        transition: districtTransition,
+        morph: districtMorph,
+        get revision() {
+            return districtRevision;
+        },
+        invalidate() {
+            districtRevision++;
+        },
+        get style() {
+            return districtStyle;
+        },
+        get styles() {
+            return districtStyles;
+        },
+        commitStyles(style, styles) {
+            districtStyle = style;
+            districtStyles = styles;
+        },
+        get hovered() {
+            return hoveredDistrict;
+        },
+        set hovered(id) {
+            hoveredDistrict = id;
+        },
+    };
+}