@honua/react 0.0.20-alpha.0

package/interactions/detail-model.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Framework-neutral popup/detail data preparation helpers.
+ *
+ * These helpers consume selection targets and query results from the existing
+ * exploration surfaces. They do not own interaction state.
+ *
+ * @module
+ */
+import type { FeatureId, SourceId } from "../contract/types.js";
+import type { FeatureSelectionTarget } from "../exploration/types.js";
+export interface DetailFeatureLike {
+    readonly id?: FeatureId;
+    readonly sourceId?: SourceId;
+    readonly sourceLayer?: string;
+    readonly attributes?: Readonly<Record<string, unknown>>;
+    readonly properties?: Readonly<Record<string, unknown>>;
+    readonly geometry?: unknown;
+}
+export interface DetailFieldDefinition {
+    readonly name: string;
+    readonly label?: string;
+    readonly visible?: boolean;
+    readonly formatter?: (value: unknown, feature: DetailFeatureLike) => unknown;
+}
+export interface DetailModelOptions {
+    readonly selection: ReadonlyArray<FeatureSelectionTarget>;
+    readonly features?: ReadonlyArray<DetailFeatureLike>;
+    readonly sourceId?: SourceId;
+    readonly sourceLayer?: string;
+    readonly objectIdField?: string;
+    readonly titleField?: string;
+    readonly fields?: ReadonlyArray<DetailFieldDefinition | string>;
+    readonly includeHiddenFields?: boolean;
+}
+export type DetailSelectionStatus = "empty" | "ready" | "stale";
+export interface DetailFieldModel {
+    readonly name: string;
+    readonly label: string;
+    readonly value: unknown;
+}
+export interface DetailModel {
+    readonly status: DetailSelectionStatus;
+    readonly target?: FeatureSelectionTarget;
+    readonly feature?: DetailFeatureLike;
+    readonly title?: string;
+    readonly attributes: Readonly<Record<string, unknown>>;
+    readonly fields: ReadonlyArray<DetailFieldModel>;
+    readonly geometry?: unknown;
+}
+/** Build one detail model per selected target. */
+export declare function prepareSelectionDetailModels(options: DetailModelOptions): DetailModel[];
+/** Build the primary popup/detail model for the first selected target. */
+export declare function preparePrimaryDetailModel(options: DetailModelOptions): DetailModel;
+//# sourceMappingURL=detail-model.d.ts.map

package/interactions/detail-model.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"detail-model.d.ts","sourceRoot":"","sources":["../../../src/interactions/detail-model.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAMhE,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,yBAAyB,CAAC;AAEtE,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,EAAE,CAAC,EAAE,SAAS,CAAC;IACxB,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC;IAC7B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,UAAU,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACxD,QAAQ,CAAC,UAAU,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACxD,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,iBAAiB,KAAK,OAAO,CAAC;CAC9E;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,SAAS,EAAE,aAAa,CAAC,sBAAsB,CAAC,CAAC;IAC1D,QAAQ,CAAC,QAAQ,CAAC,EAAE,aAAa,CAAC,iBAAiB,CAAC,CAAC;IACrD,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC;IAC7B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,MAAM,CAAC,EAAE,aAAa,CAAC,qBAAqB,GAAG,MAAM,CAAC,CAAC;IAChE,QAAQ,CAAC,mBAAmB,CAAC,EAAE,OAAO,CAAC;CACxC;AAED,MAAM,MAAM,qBAAqB,GAAG,OAAO,GAAG,OAAO,GAAG,OAAO,CAAC;AAEhE,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CACzB;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,MAAM,EAAE,qBAAqB,CAAC;IACvC,QAAQ,CAAC,MAAM,CAAC,EAAE,sBAAsB,CAAC;IACzC,QAAQ,CAAC,OAAO,CAAC,EAAE,iBAAiB,CAAC;IACrC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,UAAU,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACvD,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC,gBAAgB,CAAC,CAAC;IACjD,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED,kDAAkD;AAClD,wBAAgB,4BAA4B,CAAC,OAAO,EAAE,kBAAkB,GAAG,WAAW,EAAE,CAgBvF;AAED,0EAA0E;AAC1E,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,kBAAkB,GAAG,WAAW,CAElF"}

package/interactions/detail-model.js

@@ -0,0 +1,105 @@
+/**
+ * Framework-neutral popup/detail data preparation helpers.
+ *
+ * These helpers consume selection targets and query results from the existing
+ * exploration surfaces. They do not own interaction state.
+ *
+ * @module
+ */
+import { featureSelectionKey, isSourceQualifiedSelectionTarget, sourceFeatureSelectionTarget, } from "../exploration/selection.js";
+/** Build one detail model per selected target. */
+export function prepareSelectionDetailModels(options) {
+    const selection = options.selection;
+    if (selection.length === 0)
+        return [emptyDetailModel()];
+    const features = options.features ?? [];
+    const bySelectionKey = new Map();
+    for (const feature of features) {
+        const target = featureToSelectionTarget(feature, options);
+        if (target)
+            bySelectionKey.set(featureSelectionKey(target), feature);
+    }
+    return selection.map((target) => {
+        const feature = bySelectionKey.get(featureSelectionKey(target));
+        if (!feature)
+            return staleDetailModel(target);
+        return readyDetailModel(target, feature, options);
+    });
+}
+/** Build the primary popup/detail model for the first selected target. */
+export function preparePrimaryDetailModel(options) {
+    return prepareSelectionDetailModels(options)[0] ?? emptyDetailModel();
+}
+function readyDetailModel(target, feature, options) {
+    const attributes = featureAttributes(feature);
+    return {
+        status: "ready",
+        target,
+        feature,
+        title: detailTitle(attributes, options.titleField, target),
+        attributes,
+        fields: detailFields(feature, attributes, options),
+        geometry: feature.geometry,
+    };
+}
+function emptyDetailModel() {
+    return {
+        status: "empty",
+        attributes: {},
+        fields: [],
+    };
+}
+function staleDetailModel(target) {
+    return {
+        status: "stale",
+        target,
+        attributes: {},
+        fields: [],
+    };
+}
+function featureToSelectionTarget(feature, options) {
+    const id = featureId(feature, options.objectIdField);
+    if (id === undefined)
+        return undefined;
+    const sourceId = feature.sourceId ?? options.sourceId;
+    if (!sourceId)
+        return id;
+    return sourceFeatureSelectionTarget(sourceId, id, { sourceLayer: feature.sourceLayer ?? options.sourceLayer });
+}
+function featureId(feature, objectIdField) {
+    if (feature.id !== undefined)
+        return feature.id;
+    const attributes = featureAttributes(feature);
+    const value = (objectIdField ? attributes[objectIdField] : undefined) ??
+        attributes.OBJECTID ??
+        attributes.objectid ??
+        attributes.ObjectID ??
+        attributes.id;
+    return typeof value === "string" || typeof value === "number" ? value : undefined;
+}
+function featureAttributes(feature) {
+    return feature.attributes ?? feature.properties ?? {};
+}
+function detailTitle(attributes, titleField, target) {
+    const title = titleField ? attributes[titleField] : undefined;
+    if (title !== undefined && title !== null && String(title).length > 0)
+        return String(title);
+    if (isSourceQualifiedSelectionTarget(target))
+        return `${target.sourceId} ${String(target.id)}`;
+    return String(target);
+}
+function detailFields(feature, attributes, options) {
+    const definitions = options.fields ?? Object.keys(attributes);
+    const out = [];
+    for (const definition of definitions) {
+        const field = typeof definition === "string" ? { name: definition } : definition;
+        if (field.visible === false && !options.includeHiddenFields)
+            continue;
+        out.push({
+            name: field.name,
+            label: field.label ?? field.name,
+            value: field.formatter ? field.formatter(attributes[field.name], feature) : attributes[field.name],
+        });
+    }
+    return out;
+}

package/interactions/exploration-bindings.d.ts

@@ -0,0 +1,120 @@
+/**
+ * Interaction bindings between map/table/detail surfaces and
+ * `ExplorationViewController`.
+ *
+ * These helpers keep component adapters small: maps publish source-qualified
+ * selection targets, tables publish the same targets, maps observe shared
+ * selection to update feature-state, and detail panels subscribe to the
+ * shared selection slice.
+ *
+ * @module
+ */
+import type { AggregationSpec } from "../contract/types.js";
+import type { HonuaExtent } from "../core/types.js";
+import type { ExplorationSelectorListener, ExplorationSelectorSubscribeOptions, LinkedViewQueryProjection, LinkedViewQueryProjectionOptions } from "../exploration/selectors.js";
+import type { ExplorationViewChangeEvent, ExplorationViewController, ExplorationViewSubscribeOptions, ExplorationViewSubscription, FeatureSelectionTarget, FilterClause, Unsubscribe } from "../exploration/types.js";
+import type { FeatureStateMap, InteractiveMap, SelectionHandle, SelectionHandlerOptions } from "./feature-state.js";
+export interface MapSelectionExplorationBindingOptions extends SelectionHandlerOptions {
+    /** Replace the exploration selection with the map selection. @default true */
+    readonly replaceSelection?: boolean;
+}
+/**
+ * Bind a MapLibre-style selection handler to an exploration view.
+ *
+ * The map handler already knows its source and source layer, so this publishes
+ * source-qualified targets into the shared exploration selection slice.
+ */
+export declare function bindMapSelectionToExploration(map: InteractiveMap, view: ExplorationViewController, options: MapSelectionExplorationBindingOptions): SelectionHandle;
+export interface FeatureStateSelectionSyncOptions {
+    readonly source: string;
+    readonly sourceLayer?: string;
+    readonly stateKey?: string;
+    /** Apply raw legacy ids to this source. @default true */
+    readonly includeRawIds?: boolean;
+    /** Apply current view state immediately. @default true */
+    readonly applyInitial?: boolean;
+    readonly subscribeOptions?: ExplorationViewSubscribeOptions;
+}
+export interface InteractionBindingHandle {
+    remove(): void;
+}
+export interface LinkedViewQueryBindingOptions extends LinkedViewQueryProjectionOptions, ExplorationViewSubscribeOptions {
+    /** Slices that should recompute the projection. */
+    readonly subscription?: ExplorationViewSubscription;
+    /** Emit the current projection before waiting for changes. @default true */
+    readonly applyInitial?: boolean;
+    /** Equality check used to suppress unchanged projections. @default deep value equality */
+    readonly equals?: (a: LinkedViewQueryProjection, b: LinkedViewQueryProjection) => boolean;
+}
+export interface MapExtentExplorationSource {
+    current?(): HonuaExtent | undefined;
+    subscribe(listener: (extent: HonuaExtent | undefined) => void): Unsubscribe | InteractionBindingHandle;
+}
+export interface MapExtentExplorationBindingOptions {
+    /** Publish the source's current extent on bind when available. @default true */
+    readonly applyInitial?: boolean;
+    /** Also mirror the extent into `spatialFilter`. @default false */
+    readonly publishSpatialFilter?: boolean;
+    /** Coalesce same-tick move events before dispatching. @default true */
+    readonly coalesce?: boolean;
+}
+export interface FilterControlsExplorationBinding {
+    setFilter(id: string, clause: FilterClause): void;
+    clearFilter(id: string): void;
+    subscribe(listener: ExplorationSelectorListener<Readonly<Record<string, FilterClause>>>, options?: ExplorationSelectorSubscribeOptions<Readonly<Record<string, FilterClause>>>): Unsubscribe;
+}
+export interface ChartBucketSelection {
+    readonly targets?: ReadonlyArray<FeatureSelectionTarget>;
+    readonly filters?: Readonly<Record<string, FilterClause>>;
+}
+export interface ChartBucketSelectionOptions {
+    /** Replace the current selection when the bucket supplies targets. @default true */
+    readonly replaceSelection?: boolean;
+}
+export interface ChartExplorationBinding {
+    setGrouping(grouping: ReadonlyArray<string>): void;
+    setAggregation(aggregation: AggregationSpec | undefined): void;
+    selectTargets(targets: ReadonlyArray<FeatureSelectionTarget>, options?: {
+        readonly replace?: boolean;
+    }): void;
+    selectBucket(bucket: ChartBucketSelection, options?: ChartBucketSelectionOptions): void;
+    subscribeQuery(listener: ExplorationSelectorListener<LinkedViewQueryProjection>, options?: LinkedViewQueryBindingOptions): Unsubscribe;
+}
+export interface MapLayerFilterTarget {
+    setFilter(layerId: string, filter: unknown): void;
+}
+export interface MapLayerFilterExplorationBindingOptions extends LinkedViewQueryBindingOptions {
+    readonly layerId: string;
+    readonly translate: (projection: LinkedViewQueryProjection) => unknown;
+}
+/**
+ * Reflect exploration selection into MapLibre feature-state.
+ *
+ * This is the table-to-map path: a table or detail panel can call
+ * `view.select(...)`; the map observes the shared selection slice and toggles
+ * feature-state for matching source-qualified targets.
+ */
+export declare function syncFeatureStateSelection(map: FeatureStateMap, view: ExplorationViewController, options: FeatureStateSelectionSyncOptions): InteractionBindingHandle;
+/** Publish viewport extent changes from a map adapter into an exploration view. */
+export declare function bindMapExtentToExploration(view: ExplorationViewController, source: MapExtentExplorationSource, options?: MapExtentExplorationBindingOptions): InteractionBindingHandle;
+/** Subscribe a table, chart, or result adapter to the shared query projection. */
+export declare function bindQueryProjectionToExploration(view: ExplorationViewController, listener: ExplorationSelectorListener<LinkedViewQueryProjection>, options?: LinkedViewQueryBindingOptions): Unsubscribe;
+/** Adapter for filter bars and query-builder controls. */
+export declare function bindFilterControlsToExploration(view: ExplorationViewController): FilterControlsExplorationBinding;
+/** Adapter for chart/grouped-result controls that publish grouping, aggregation, filters, and selection. */
+export declare function bindChartToExploration(view: ExplorationViewController): ChartExplorationBinding;
+/** Reflect linked filter/query state into a MapLibre-style layer filter. */
+export declare function syncMapLayerFilterToExploration(map: MapLayerFilterTarget, view: ExplorationViewController, options: MapLayerFilterExplorationBindingOptions): InteractionBindingHandle;
+export type SelectionDetailListener = (selection: ReadonlyArray<FeatureSelectionTarget>, event: ExplorationViewChangeEvent) => void;
+/** Subscribe a detail panel to the shared exploration selection. */
+export declare function bindDetailToSelection(view: ExplorationViewController, listener: SelectionDetailListener, options?: ExplorationViewSubscribeOptions): Unsubscribe;
+export interface TableSelectionExplorationBinding {
+    select(targets: ReadonlyArray<FeatureSelectionTarget>, options?: {
+        readonly replace?: boolean;
+    }): void;
+    clearSelection(): void;
+    subscribe(listener: SelectionDetailListener, options?: ExplorationViewSubscribeOptions): Unsubscribe;
+}
+/** Small adapter for table/grid components that publish and observe selection. */
+export declare function bindTableSelectionToExploration(view: ExplorationViewController): TableSelectionExplorationBinding;
+//# sourceMappingURL=exploration-bindings.d.ts.map

package/interactions/exploration-bindings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"exploration-bindings.d.ts","sourceRoot":"","sources":["../../../src/interactions/exploration-bindings.ts"],"names":[],"mappings":"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"}

package/interactions/exploration-bindings.js

@@ -0,0 +1,218 @@
+/**
+ * Interaction bindings between map/table/detail surfaces and
+ * `ExplorationViewController`.
+ *
+ * These helpers keep component adapters small: maps publish source-qualified
+ * selection targets, tables publish the same targets, maps observe shared
+ * selection to update feature-state, and detail panels subscribe to the
+ * shared selection slice.
+ *
+ * @module
+ */
+import { featureSelectionKey, isSourceQualifiedSelectionTarget, sourceFeatureSelectionTarget, } from "../exploration/selection.js";
+import { extentToSpatialFilter, selectLinkedViewQueryProjection, subscribeExplorationSelector, } from "../exploration/selectors.js";
+import { createSelectionHandler } from "./feature-state.js";
+/**
+ * Bind a MapLibre-style selection handler to an exploration view.
+ *
+ * The map handler already knows its source and source layer, so this publishes
+ * source-qualified targets into the shared exploration selection slice.
+ */
+export function bindMapSelectionToExploration(map, view, options) {
+    const { replaceSelection = true, onSelectionTargetsChange } = options;
+    return createSelectionHandler(map, {
+        ...options,
+        onSelectionTargetsChange(targets) {
+            view.select(targets, { replace: replaceSelection });
+            onSelectionTargetsChange?.(targets);
+        },
+    });
+}
+/**
+ * Reflect exploration selection into MapLibre feature-state.
+ *
+ * This is the table-to-map path: a table or detail panel can call
+ * `view.select(...)`; the map observes the shared selection slice and toggles
+ * feature-state for matching source-qualified targets.
+ */
+export function syncFeatureStateSelection(map, view, options) {
+    const { source, sourceLayer, stateKey = "selected", includeRawIds = true, applyInitial = true } = options;
+    let active = new Map();
+    function apply(selection) {
+        const next = new Map();
+        for (const target of selection) {
+            const featureTarget = toFeatureTarget(target, source, sourceLayer, includeRawIds);
+            if (!featureTarget)
+                continue;
+            next.set(featureTargetKey(featureTarget), featureTarget);
+        }
+        for (const [key, target] of active) {
+            if (!next.has(key))
+                map.setFeatureState(target, { [stateKey]: false });
+        }
+        for (const [key, target] of next) {
+            if (!active.has(key))
+                map.setFeatureState(target, { [stateKey]: true });
+        }
+        active = next;
+    }
+    const unsubscribe = view.subscribe("selection", (event) => apply(event.state.selection), options.subscribeOptions);
+    if (applyInitial)
+        apply(view.state.selection);
+    return {
+        remove() {
+            unsubscribe();
+            for (const target of active.values()) {
+                map.setFeatureState(target, { [stateKey]: false });
+            }
+            active.clear();
+        },
+    };
+}
+/** Publish viewport extent changes from a map adapter into an exploration view. */
+export function bindMapExtentToExploration(view, source, options = {}) {
+    const { applyInitial = true, publishSpatialFilter = false, coalesce = true } = options;
+    let active = true;
+    let pending = false;
+    let latest;
+    function publish(extent) {
+        if (!active)
+            return;
+        view.setExtent(extent);
+        if (publishSpatialFilter) {
+            view.setSpatialFilter(extent ? extentToSpatialFilter(extent) : undefined);
+        }
+    }
+    function enqueue(extent) {
+        latest = extent;
+        if (!coalesce) {
+            publish(latest);
+            return;
+        }
+        if (pending)
+            return;
+        pending = true;
+        queueMicrotask(() => {
+            pending = false;
+            publish(latest);
+        });
+    }
+    const handle = source.subscribe(enqueue);
+    if (applyInitial && source.current)
+        enqueue(source.current());
+    return {
+        remove() {
+            if (!active)
+                return;
+            active = false;
+            removeSourceHandle(handle);
+        },
+    };
+}
+/** Subscribe a table, chart, or result adapter to the shared query projection. */
+export function bindQueryProjectionToExploration(view, listener, options = {}) {
+    const { subscription = [
+        "filters",
+        "spatialFilter",
+        "extent",
+        "sort",
+        "page",
+        "visibleFields",
+        "grouping",
+        "aggregation",
+        "selection",
+    ], applyInitial = true, equals, includeSelf, sourceId, spatialMode, } = options;
+    return subscribeExplorationSelector(view, subscription, (state) => selectLinkedViewQueryProjection(state, { sourceId, spatialMode }), listener, { fireImmediately: applyInitial, equals, includeSelf });
+}
+/** Adapter for filter bars and query-builder controls. */
+export function bindFilterControlsToExploration(view) {
+    return {
+        setFilter(id, clause) {
+            view.setFilter(id, clause);
+        },
+        clearFilter(id) {
+            view.clearFilter(id);
+        },
+        subscribe(listener, options) {
+            return subscribeExplorationSelector(view, "filters", (state) => state.filters, listener, options);
+        },
+    };
+}
+/** Adapter for chart/grouped-result controls that publish grouping, aggregation, filters, and selection. */
+export function bindChartToExploration(view) {
+    return {
+        setGrouping(grouping) {
+            view.setGrouping(grouping);
+        },
+        setAggregation(aggregation) {
+            view.setAggregation(aggregation);
+        },
+        selectTargets(targets, options) {
+            view.select(targets, options);
+        },
+        selectBucket(bucket, options) {
+            for (const [id, clause] of Object.entries(bucket.filters ?? {})) {
+                view.setFilter(id, clause);
+            }
+            if (bucket.targets) {
+                view.select(bucket.targets, { replace: options?.replaceSelection ?? true });
+            }
+        },
+        subscribeQuery(listener, options) {
+            return bindQueryProjectionToExploration(view, listener, options);
+        },
+    };
+}
+/** Reflect linked filter/query state into a MapLibre-style layer filter. */
+export function syncMapLayerFilterToExploration(map, view, options) {
+    const unsubscribe = bindQueryProjectionToExploration(view, (projection) => map.setFilter(options.layerId, options.translate(projection)), {
+        ...options,
+        subscription: options.subscription ?? ["filters", "spatialFilter", "extent"],
+    });
+    return {
+        remove() {
+            unsubscribe();
+        },
+    };
+}
+/** Subscribe a detail panel to the shared exploration selection. */
+export function bindDetailToSelection(view, listener, options) {
+    return view.subscribe("selection", (event) => listener(event.state.selection, event), options);
+}
+/** Small adapter for table/grid components that publish and observe selection. */
+export function bindTableSelectionToExploration(view) {
+    return {
+        select(targets, options) {
+            view.select(targets, options);
+        },
+        clearSelection() {
+            view.deselect();
+        },
+        subscribe(listener, options) {
+            return bindDetailToSelection(view, listener, options);
+        },
+    };
+}
+function toFeatureTarget(target, source, sourceLayer, includeRawIds) {
+    if (isSourceQualifiedSelectionTarget(target)) {
+        if (target.sourceId !== source)
+            return undefined;
+        if ((target.sourceLayer ?? "") !== (sourceLayer ?? ""))
+            return undefined;
+        return { source, id: target.id, sourceLayer };
+    }
+    if (!includeRawIds)
+        return undefined;
+    return { source, id: target, sourceLayer };
+}
+function featureTargetKey(target) {
+    const selectionTarget = sourceFeatureSelectionTarget(target.source, target.id, { sourceLayer: target.sourceLayer });
+    return featureSelectionKey(selectionTarget);
+}
+function removeSourceHandle(handle) {
+    if (typeof handle === "function") {
+        handle();
+        return;
+    }
+    handle.remove();
+}

package/interactions/feature-state.d.ts

@@ -0,0 +1,144 @@
+/**
+ * Feature-state interaction helpers.
+ *
+ * These utilities wrap MapLibre GL JS's `setFeatureState` / `removeFeatureState`
+ * behind duck-typed interfaces so the SDK carries no hard runtime dependency on
+ * `maplibre-gl`.  Any object that implements {@link FeatureStateMap} works.
+ *
+ * @module
+ */
+import type { SourceQualifiedFeatureSelectionTarget } from "../exploration/types.js";
+/** Minimal subset of a MapLibre `Map` needed for feature-state operations. */
+export interface FeatureStateMap {
+    setFeatureState(target: {
+        source: string;
+        id: string | number;
+        sourceLayer?: string;
+    }, state: Record<string, unknown>): void;
+    getFeatureState(target: {
+        source: string;
+        id: string | number;
+        sourceLayer?: string;
+    }): Record<string, unknown>;
+    removeFeatureState(target: {
+        source: string;
+        id: string | number;
+        sourceLayer?: string;
+    }, key?: string): void;
+}
+/** Minimal subset of a MapLibre `Map` needed for event subscription. */
+export interface MapEventTarget {
+    on(event: string, layerOrHandler: string | ((...args: unknown[]) => void), handler?: (...args: unknown[]) => void): void;
+    off(event: string, layerOrHandler: string | ((...args: unknown[]) => void), handler?: (...args: unknown[]) => void): void;
+}
+/** A map that supports both feature state and events. */
+export type InteractiveMap = FeatureStateMap & MapEventTarget;
+/** Identifies a feature within a source for state operations. */
+export interface FeatureTarget {
+    source: string;
+    id: string | number;
+    sourceLayer?: string;
+}
+/**
+ * Set state on a feature.
+ *
+ * Thin wrapper that constructs the MapLibre target object. Prefer this over
+ * calling `map.setFeatureState()` directly when working with Honua source IDs
+ * and feature IDs from query results.
+ */
+export declare function setFeatureState(map: FeatureStateMap, source: string, id: string | number, state: Record<string, unknown>, sourceLayer?: string): void;
+/** Get current state for a feature. */
+export declare function getFeatureState(map: FeatureStateMap, source: string, id: string | number, sourceLayer?: string): Record<string, unknown>;
+/** Remove a single state key (or all state) from a feature. */
+export declare function removeFeatureState(map: FeatureStateMap, source: string, id: string | number, key?: string, sourceLayer?: string): void;
+/** Options for {@link createHoverHandler}. */
+export interface HoverHandlerOptions {
+    /** Source ID to set feature state on. */
+    source: string;
+    /** Layer ID to listen for mouse events on. */
+    layer: string;
+    /** Feature-state key to toggle. @default "hover" */
+    stateKey?: string;
+    /** Source layer (required for vector-tile sources). */
+    sourceLayer?: string;
+}
+/** Handle returned by {@link createHoverHandler} for cleanup. */
+export interface HoverHandle {
+    /** Remove all event listeners. Call this on component teardown. */
+    remove(): void;
+    /** The currently hovered feature ID, or `undefined`. */
+    readonly hoveredId: string | number | undefined;
+}
+/**
+ * Create a hover handler that manages `feature-state` hover state.
+ *
+ * Wires up `mousemove` / `mouseleave` events on the specified layer and
+ * toggles a boolean state key (default `"hover"`) on the underlying source.
+ * Pair with a paint expression like:
+ *
+ * ```ts
+ * import { expr } from "@honua/sdk";
+ * const opacity = expr.case([expr.featureState("hover"), 1.0], 0.5);
+ * ```
+ *
+ * @example
+ * ```ts
+ * const hover = createHoverHandler(map, {
+ *   source: "parcels",
+ *   layer: "parcel-fill",
+ * });
+ * // Later:
+ * hover.remove();
+ * ```
+ */
+export declare function createHoverHandler(map: InteractiveMap, options: HoverHandlerOptions): HoverHandle;
+/** Options for {@link createSelectionHandler}. */
+export interface SelectionHandlerOptions {
+    /** Source ID to set feature state on. */
+    source: string;
+    /** Layer ID to listen for click events on. */
+    layer: string;
+    /** Feature-state key to toggle. @default "selected" */
+    stateKey?: string;
+    /** Allow multiple features to be selected simultaneously. @default false */
+    multiSelect?: boolean;
+    /** Source layer (required for vector-tile sources). */
+    sourceLayer?: string;
+    /** Called whenever the selection changes. */
+    onChange?: (selectedIds: ReadonlySet<string | number>) => void;
+    /** Called whenever the source-qualified selection changes. */
+    onSelectionTargetsChange?: (selectedTargets: ReadonlyArray<SourceQualifiedFeatureSelectionTarget>) => void;
+}
+/** Handle returned by {@link createSelectionHandler} for cleanup. */
+export interface SelectionHandle {
+    /** Remove all event listeners and clear selection state. */
+    remove(): void;
+    /** The set of currently selected feature IDs. */
+    readonly selectedIds: ReadonlySet<string | number>;
+    /** The current source-qualified selection targets. */
+    readonly selectedTargets: ReadonlyArray<SourceQualifiedFeatureSelectionTarget>;
+    /** Programmatically clear the selection. */
+    clearSelection(): void;
+    /** Programmatically select a feature by ID. */
+    select(id: string | number): void;
+    /** Programmatically deselect a feature by ID. */
+    deselect(id: string | number): void;
+}
+/**
+ * Create a selection handler that manages `feature-state` selection.
+ *
+ * Wires up `click` events on the specified layer and toggles a boolean state
+ * key (default `"selected"`) on the underlying source. Supports single-select
+ * (default) and multi-select modes.
+ *
+ * @example
+ * ```ts
+ * const selection = createSelectionHandler(map, {
+ *   source: "parcels",
+ *   layer: "parcel-fill",
+ *   onChange: (ids) => updateSidebar(ids),
+ * });
+ * ```
+ */
+export declare function createSelectionHandler(map: InteractiveMap, options: SelectionHandlerOptions): SelectionHandle;
+//# sourceMappingURL=feature-state.d.ts.map

package/interactions/feature-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"feature-state.d.ts","sourceRoot":"","sources":["../../../src/interactions/feature-state.ts"],"names":[],"mappings":"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"}