@honua/react 0.0.20-alpha.0

package/interactions/feature-state.js

@@ -0,0 +1,169 @@
+/**
+ * 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 { sourceFeatureSelectionTarget } from "../exploration/selection.js";
+// ── Core helpers ──────────────────────────────────────────────
+/**
+ * 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 function setFeatureState(map, source, id, state, sourceLayer) {
+    map.setFeatureState({ source, id, sourceLayer }, state);
+}
+/** Get current state for a feature. */
+export function getFeatureState(map, source, id, sourceLayer) {
+    return map.getFeatureState({ source, id, sourceLayer });
+}
+/** Remove a single state key (or all state) from a feature. */
+export function removeFeatureState(map, source, id, key, sourceLayer) {
+    map.removeFeatureState({ source, id, sourceLayer }, key);
+}
+/**
+ * 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 function createHoverHandler(map, options) {
+    const { source, layer, stateKey = "hover", sourceLayer } = options;
+    let hoveredId;
+    function onMouseMove(...args) {
+        const e = args[0];
+        const featureId = e?.features?.[0]?.id;
+        if (featureId === undefined || featureId === null)
+            return;
+        if (hoveredId !== undefined && hoveredId !== featureId) {
+            map.setFeatureState({ source, id: hoveredId, sourceLayer }, { [stateKey]: false });
+        }
+        hoveredId = featureId;
+        map.setFeatureState({ source, id: hoveredId, sourceLayer }, { [stateKey]: true });
+    }
+    function onMouseLeave() {
+        if (hoveredId !== undefined) {
+            map.setFeatureState({ source, id: hoveredId, sourceLayer }, { [stateKey]: false });
+            hoveredId = undefined;
+        }
+    }
+    map.on("mousemove", layer, onMouseMove);
+    map.on("mouseleave", layer, onMouseLeave);
+    return {
+        remove() {
+            onMouseLeave(); // clear any lingering state
+            map.off("mousemove", layer, onMouseMove);
+            map.off("mouseleave", layer, onMouseLeave);
+        },
+        get hoveredId() {
+            return hoveredId;
+        },
+    };
+}
+/**
+ * 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 function createSelectionHandler(map, options) {
+    const { source, layer, stateKey = "selected", multiSelect = false, sourceLayer, onChange, onSelectionTargetsChange, } = options;
+    const selected = new Set();
+    function clearAll() {
+        for (const id of selected) {
+            map.setFeatureState({ source, id, sourceLayer }, { [stateKey]: false });
+        }
+        selected.clear();
+    }
+    function notifyChange() {
+        onChange?.(selected);
+        onSelectionTargetsChange?.(selectionTargets());
+    }
+    function selectionTargets() {
+        return [...selected].map((id) => sourceFeatureSelectionTarget(source, id, { sourceLayer }));
+    }
+    function onClick(...args) {
+        const e = args[0];
+        const featureId = e?.features?.[0]?.id;
+        if (featureId === undefined || featureId === null)
+            return;
+        if (selected.has(featureId)) {
+            // Deselect
+            map.setFeatureState({ source, id: featureId, sourceLayer }, { [stateKey]: false });
+            selected.delete(featureId);
+        }
+        else {
+            // New selection
+            if (!multiSelect) {
+                clearAll();
+            }
+            map.setFeatureState({ source, id: featureId, sourceLayer }, { [stateKey]: true });
+            selected.add(featureId);
+        }
+        notifyChange();
+    }
+    map.on("click", layer, onClick);
+    return {
+        remove() {
+            clearAll();
+            map.off("click", layer, onClick);
+        },
+        get selectedIds() {
+            return selected;
+        },
+        get selectedTargets() {
+            return selectionTargets();
+        },
+        clearSelection() {
+            clearAll();
+            notifyChange();
+        },
+        select(id) {
+            if (!multiSelect) {
+                clearAll();
+            }
+            map.setFeatureState({ source, id, sourceLayer }, { [stateKey]: true });
+            selected.add(id);
+            notifyChange();
+        },
+        deselect(id) {
+            if (selected.has(id)) {
+                map.setFeatureState({ source, id, sourceLayer }, { [stateKey]: false });
+                selected.delete(id);
+                notifyChange();
+            }
+        },
+    };
+}

package/interactions/hit-test.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Renderer-neutral hit-test and pointer primitives.
+ *
+ * The helpers in this module normalize MapLibre-shaped rendered features into
+ * Honua source-qualified identities without importing a renderer package.
+ *
+ * @module
+ */
+import { type QueryTileFeatureIdentityTarget, type QueryTileSourceDescriptor, type Source } from "../contract/index.js";
+import type { FeatureId } from "../contract/types.js";
+import type { SourceQualifiedFeatureSelectionTarget } from "../exploration/types.js";
+export interface HonuaScreenPoint {
+    readonly x: number;
+    readonly y: number;
+}
+export interface HonuaLngLat {
+    readonly lng: number;
+    readonly lat: number;
+}
+export type HonuaPointerEventType = "click" | "dblclick" | "mousemove" | "mouseenter" | "mouseleave" | "pointer";
+export interface HonuaPointerInput {
+    readonly type?: HonuaPointerEventType | string;
+    readonly point?: HonuaScreenPoint | readonly [number, number];
+    readonly lngLat?: HonuaLngLat | readonly [number, number];
+    readonly originalEvent?: unknown;
+}
+export interface HonuaPointerEvent {
+    readonly type: HonuaPointerEventType | string;
+    readonly point: HonuaScreenPoint;
+    readonly lngLat?: readonly [number, number];
+    readonly originalEvent?: unknown;
+}
+export type HonuaHitTestDegradedReason = "renderer-unsupported" | "lnglat-unavailable" | "geometry-unavailable" | "feature-id-unavailable" | "source-binding-unavailable" | "raster-value-unavailable" | "detail-unavailable" | "detail-aborted" | "detail-failed";
+export interface HonuaHitTestDegradedState {
+    readonly reason: HonuaHitTestDegradedReason;
+    readonly message: string;
+    readonly layerId?: string;
+    readonly sourceId?: string;
+    readonly featureId?: FeatureId;
+    readonly cause?: unknown;
+}
+export interface HonuaHitTestRasterSample {
+    readonly value?: unknown;
+    readonly band?: number | string;
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
+export interface HonuaHitFeature {
+    readonly layerId?: string;
+    readonly sourceId?: string;
+    readonly sourceLayer?: string;
+    readonly featureId?: FeatureId;
+    readonly selectionTarget?: SourceQualifiedFeatureSelectionTarget;
+    readonly properties: Readonly<Record<string, unknown>>;
+    readonly geometry?: unknown;
+    readonly raster?: HonuaHitTestRasterSample;
+    readonly detail?: unknown;
+    readonly rawFeature: unknown;
+    readonly degraded: readonly HonuaHitTestDegradedState[];
+}
+export interface HonuaHitTestResult {
+    readonly point: HonuaScreenPoint;
+    readonly lngLat?: readonly [number, number];
+    readonly features: readonly HonuaHitFeature[];
+    readonly degraded: readonly HonuaHitTestDegradedState[];
+    readonly rawFeatures?: readonly unknown[];
+}
+export interface HonuaRenderedFeatureContext {
+    readonly layerId?: string;
+    readonly layerType?: string;
+    readonly sourceId?: string;
+    readonly sourceLayer?: string;
+    readonly protocol?: string;
+    readonly queryTileDescriptor?: QueryTileSourceDescriptor;
+}
+export interface HonuaHitTestFeatureOptions {
+    readonly featureIdProperty?: string;
+    readonly resolveFeatureId?: (feature: unknown, context: HonuaRenderedFeatureContext) => FeatureId | undefined;
+    readonly resolveFeatureContext?: (feature: unknown) => HonuaRenderedFeatureContext | undefined;
+    readonly queryTileSources?: Readonly<Record<string, QueryTileSourceDescriptor>>;
+}
+export interface HonuaHitTestOptions extends HonuaHitTestFeatureOptions {
+    readonly layers?: readonly string[];
+    readonly sourceIds?: readonly string[];
+    readonly sourceLayers?: readonly string[];
+    readonly tolerance?: number;
+    readonly maxResults?: number;
+    readonly loadDetails?: boolean;
+    readonly signal?: AbortSignal;
+}
+export interface HonuaHitTestMap {
+    queryRenderedFeatures?(geometry?: HonuaScreenPoint | readonly [HonuaScreenPoint, HonuaScreenPoint], options?: {
+        layers?: readonly string[];
+    }): readonly unknown[];
+    unproject?(point: HonuaScreenPoint | readonly [number, number]): HonuaLngLat | readonly [number, number];
+}
+export interface HonuaHitTestDetailContext extends HonuaRenderedFeatureContext {
+    readonly target: QueryTileFeatureIdentityTarget;
+    readonly hit: HonuaHitFeature;
+}
+export type HonuaHitTestDetailLoader = (context: HonuaHitTestDetailContext, options: {
+    readonly signal?: AbortSignal;
+}) => Promise<unknown>;
+export interface HonuaNormalizeHitTestOptions extends HonuaHitTestOptions {
+    readonly featureContexts?: Readonly<Record<string, HonuaRenderedFeatureContext>>;
+    readonly detailLoader?: HonuaHitTestDetailLoader;
+}
+export declare function hitTestMap(map: HonuaHitTestMap, input: HonuaPointerInput, options?: HonuaNormalizeHitTestOptions): Promise<HonuaHitTestResult>;
+export declare function normalizePointerEvent(input: HonuaPointerInput | unknown, map?: Pick<HonuaHitTestMap, "unproject">): HonuaPointerEvent;
+export declare function normalizeHitTestFeatures(features: readonly unknown[], options?: HonuaNormalizeHitTestOptions): HonuaHitFeature[];
+export declare function normalizeHitFeature(feature: unknown, context: HonuaRenderedFeatureContext, options?: HonuaHitTestFeatureOptions): HonuaHitFeature;
+export declare function createQueryTileDetailLoader(sources: Readonly<Record<string, Source>>, descriptors: Readonly<Record<string, QueryTileSourceDescriptor>>): HonuaHitTestDetailLoader;
+//# sourceMappingURL=hit-test.d.ts.map

package/interactions/hit-test.d.ts.map

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

package/interactions/hit-test.js

@@ -0,0 +1,291 @@
+/**
+ * Renderer-neutral hit-test and pointer primitives.
+ *
+ * The helpers in this module normalize MapLibre-shaped rendered features into
+ * Honua source-qualified identities without importing a renderer package.
+ *
+ * @module
+ */
+import { loadQueryTileFeatureDetail, mapQueryTileFeatureIdentity, } from "../contract/index.js";
+import { sourceFeatureSelectionTarget } from "../exploration/selection.js";
+export async function hitTestMap(map, input, options = {}) {
+    const pointer = normalizePointerEvent(input, map);
+    const degraded = pointer.lngLat
+        ? []
+        : [
+            {
+                reason: "lnglat-unavailable",
+                message: "The renderer did not provide lngLat and cannot unproject screen coordinates.",
+            },
+        ];
+    if (!map.queryRenderedFeatures) {
+        return {
+            point: pointer.point,
+            lngLat: pointer.lngLat,
+            features: [],
+            degraded: [
+                ...degraded,
+                { reason: "renderer-unsupported", message: "The renderer does not support queryRenderedFeatures." },
+            ],
+            rawFeatures: [],
+        };
+    }
+    const rawFeatures = map.queryRenderedFeatures(queryGeometry(pointer.point, options.tolerance), {
+        ...(options.layers ? { layers: options.layers } : {}),
+    });
+    const normalized = normalizeHitTestFeatures(rawFeatures, options);
+    const withDetails = options.loadDetails ? await loadHitDetails(normalized, options) : normalized;
+    return {
+        point: pointer.point,
+        lngLat: pointer.lngLat,
+        features: withDetails,
+        degraded,
+        rawFeatures,
+    };
+}
+export function normalizePointerEvent(input, map) {
+    const event = isRecord(input) ? input : {};
+    const point = normalizePoint(event.point) ?? normalizePoint(event) ?? clientPoint(event) ?? { x: 0, y: 0 };
+    const lngLat = normalizeLngLat(event.lngLat) ?? (map?.unproject ? normalizeLngLat(map.unproject(point)) : undefined);
+    return {
+        type: typeof event.type === "string" ? event.type : "pointer",
+        point,
+        ...(lngLat ? { lngLat } : {}),
+        originalEvent: input,
+    };
+}
+export function normalizeHitTestFeatures(features, options = {}) {
+    if (options.maxResults !== undefined && options.maxResults <= 0)
+        return [];
+    const out = [];
+    for (const feature of features) {
+        const context = featureContext(feature, options);
+        const hit = normalizeHitFeature(feature, context, options);
+        if (options.sourceIds && (!hit.sourceId || !options.sourceIds.includes(hit.sourceId)))
+            continue;
+        if (options.sourceLayers && (!hit.sourceLayer || !options.sourceLayers.includes(hit.sourceLayer)))
+            continue;
+        out.push(hit);
+        if (options.maxResults !== undefined && out.length >= options.maxResults)
+            break;
+    }
+    return out;
+}
+export function normalizeHitFeature(feature, context, options = {}) {
+    const properties = featureProperties(feature);
+    const queryTileDescriptor = context.queryTileDescriptor ?? queryTileDescriptorForContext(context, options);
+    const queryTileIdentity = queryTileDescriptor ? mapQueryTileFeatureIdentity(queryTileDescriptor, feature) : undefined;
+    const sourceId = queryTileIdentity?.sourceId ?? context.sourceId;
+    const sourceLayer = queryTileIdentity?.sourceLayer ?? context.sourceLayer;
+    const featureId = queryTileIdentity?.id ??
+        options.resolveFeatureId?.(feature, context) ??
+        featureIdFromFeature(feature, properties, options.featureIdProperty);
+    const geometry = featureGeometry(feature);
+    const raster = rasterSample(feature);
+    const degraded = [];
+    if (!sourceId) {
+        degraded.push({ reason: "source-binding-unavailable", message: "Rendered feature has no Honua source binding." });
+    }
+    if (featureId === undefined) {
+        degraded.push({
+            reason: "feature-id-unavailable",
+            message: "Rendered feature has no stable feature id.",
+            layerId: context.layerId,
+            sourceId,
+        });
+    }
+    if (geometry === undefined) {
+        degraded.push({
+            reason: "geometry-unavailable",
+            message: "Rendered feature did not include geometry.",
+            layerId: context.layerId,
+            sourceId,
+            featureId,
+        });
+    }
+    if (context.layerType === "raster" && raster?.value === undefined) {
+        degraded.push({
+            reason: "raster-value-unavailable",
+            message: "Rendered raster hit did not include a sample value.",
+            layerId: context.layerId,
+            sourceId,
+            featureId,
+        });
+    }
+    return {
+        layerId: context.layerId,
+        sourceId,
+        sourceLayer,
+        featureId,
+        ...(sourceId && featureId !== undefined
+            ? { selectionTarget: sourceFeatureSelectionTarget(sourceId, featureId, { sourceLayer }) }
+            : {}),
+        properties,
+        geometry,
+        raster,
+        rawFeature: feature,
+        degraded,
+    };
+}
+export function createQueryTileDetailLoader(sources, descriptors) {
+    return async (context, options) => {
+        const descriptor = descriptors[context.target.sourceId] ?? descriptors[context.sourceId ?? ""];
+        const source = sources[context.target.sourceId] ?? (context.sourceId ? sources[context.sourceId] : undefined);
+        if (!descriptor || !source)
+            return undefined;
+        return loadQueryTileFeatureDetail({
+            source,
+            descriptor,
+            target: context.target,
+            signal: options.signal,
+        });
+    };
+}
+async function loadHitDetails(features, options) {
+    if (!options.detailLoader) {
+        return features.map((hit) => ({
+            ...hit,
+            degraded: [
+                ...hit.degraded,
+                { reason: "detail-unavailable", message: "No hit-test detail loader was configured.", sourceId: hit.sourceId },
+            ],
+        }));
+    }
+    const out = [];
+    for (const hit of features) {
+        if (options.signal?.aborted) {
+            out.push(withDegraded(hit, "detail-aborted", "Hit-test detail loading was aborted."));
+            continue;
+        }
+        if (!hit.sourceId || hit.featureId === undefined) {
+            out.push(withDegraded(hit, "detail-unavailable", "Hit-test detail requires a source id and feature id."));
+            continue;
+        }
+        try {
+            const target = {
+                sourceId: hit.sourceId,
+                id: hit.featureId,
+                ...(hit.sourceLayer ? { sourceLayer: hit.sourceLayer } : {}),
+                properties: hit.properties,
+                feature: hit.rawFeature,
+            };
+            const detail = await options.detailLoader({ ...hit, target, hit }, { signal: options.signal });
+            out.push(detail === undefined ? withDegraded(hit, "detail-unavailable", "No detail was available.") : { ...hit, detail });
+        }
+        catch (cause) {
+            out.push(withDegraded(hit, options.signal?.aborted ? "detail-aborted" : "detail-failed", options.signal?.aborted ? "Hit-test detail loading was aborted." : "Hit-test detail loading failed.", cause));
+        }
+    }
+    return out;
+}
+function withDegraded(hit, reason, message, cause) {
+    return {
+        ...hit,
+        degraded: [
+            ...hit.degraded,
+            { reason, message, layerId: hit.layerId, sourceId: hit.sourceId, featureId: hit.featureId, cause },
+        ],
+    };
+}
+function queryGeometry(point, tolerance) {
+    const hitTolerance = tolerance ?? 0;
+    if (hitTolerance <= 0)
+        return point;
+    return [
+        { x: point.x - hitTolerance, y: point.y - hitTolerance },
+        { x: point.x + hitTolerance, y: point.y + hitTolerance },
+    ];
+}
+function featureContext(feature, options) {
+    const explicit = options.resolveFeatureContext?.(feature);
+    if (explicit)
+        return explicit;
+    const layerId = featureLayerId(feature);
+    return {
+        ...(layerId ? { layerId } : {}),
+        ...(layerId && options.featureContexts?.[layerId] ? options.featureContexts[layerId] : {}),
+        ...featureNativeSourceContext(feature),
+    };
+}
+function queryTileDescriptorForContext(context, options) {
+    if (!context.sourceId)
+        return undefined;
+    return options.queryTileSources?.[context.sourceId];
+}
+function normalizePoint(value) {
+    if (Array.isArray(value) && typeof value[0] === "number" && typeof value[1] === "number") {
+        return { x: value[0], y: value[1] };
+    }
+    if (isRecord(value) && typeof value.x === "number" && typeof value.y === "number") {
+        return { x: value.x, y: value.y };
+    }
+    return undefined;
+}
+function normalizeLngLat(value) {
+    if (Array.isArray(value) && typeof value[0] === "number" && typeof value[1] === "number")
+        return [value[0], value[1]];
+    if (isRecord(value) && typeof value.lng === "number" && typeof value.lat === "number")
+        return [value.lng, value.lat];
+    return undefined;
+}
+function clientPoint(value) {
+    return typeof value.clientX === "number" && typeof value.clientY === "number"
+        ? { x: value.clientX, y: value.clientY }
+        : undefined;
+}
+function featureIdFromFeature(feature, properties, featureIdProperty) {
+    if (isRecord(feature) && (typeof feature.id === "string" || typeof feature.id === "number"))
+        return feature.id;
+    const propertyId = (featureIdProperty ? properties[featureIdProperty] : undefined) ??
+        properties.OBJECTID ??
+        properties.objectid ??
+        properties.ObjectID ??
+        properties.id;
+    return typeof propertyId === "string" || typeof propertyId === "number" ? propertyId : undefined;
+}
+function featureProperties(feature) {
+    return isRecord(feature) && isRecord(feature.properties) ? feature.properties : {};
+}
+function featureGeometry(feature) {
+    return isRecord(feature) && "geometry" in feature ? feature.geometry : undefined;
+}
+function featureLayerId(feature) {
+    if (!isRecord(feature))
+        return undefined;
+    const layer = feature.layer;
+    return isRecord(layer) && typeof layer.id === "string" ? layer.id : undefined;
+}
+function featureNativeSourceContext(feature) {
+    if (!isRecord(feature))
+        return {};
+    const layer = isRecord(feature.layer) ? feature.layer : {};
+    const sourceId = typeof feature.source === "string" ? feature.source : typeof layer.source === "string" ? layer.source : undefined;
+    const sourceLayer = typeof feature.sourceLayer === "string"
+        ? feature.sourceLayer
+        : typeof feature.sourceLayer === "number"
+            ? String(feature.sourceLayer)
+            : typeof layer["source-layer"] === "string"
+                ? layer["source-layer"]
+                : undefined;
+    return {
+        ...(typeof layer.id === "string" ? { layerId: layer.id } : {}),
+        ...(typeof layer.type === "string" ? { layerType: layer.type } : {}),
+        ...(sourceId ? { sourceId } : {}),
+        ...(sourceLayer ? { sourceLayer } : {}),
+    };
+}
+function rasterSample(feature) {
+    if (!isRecord(feature))
+        return undefined;
+    const sample = feature.raster ?? feature.sample;
+    if (!isRecord(sample))
+        return undefined;
+    return {
+        value: sample.value,
+        band: typeof sample.band === "number" || typeof sample.band === "string" ? sample.band : undefined,
+        metadata: isRecord(sample.metadata) ? sample.metadata : undefined,
+    };
+}
+function isRecord(value) {
+    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}

package/interactions/index.d.ts

@@ -0,0 +1,31 @@
+/**
+ * `@honua/sdk-js/interactions` — hit-test, pointer normalization, and the
+ * binding primitives that wire chart / map / table widgets to an
+ * `ExplorationContext`.
+ *
+ * @example
+ * ```ts
+ * import { hitTestMap, bindMapSelectionToExploration } from "@honua/sdk-js/interactions";
+ *
+ * map.on("click", async (event) => {
+ *   const hit = await hitTestMap(map, event);
+ *   if (hit?.feature) ctx.dispatch({ type: "select", target: hit.feature });
+ * });
+ * bindMapSelectionToExploration({ map, context: ctx, sourceId: "parcels" });
+ * ```
+ *
+ * @packageDocumentation
+ */
+export { createQueryTileDetailLoader, hitTestMap, normalizeHitFeature, normalizeHitTestFeatures, normalizePointerEvent, } from "./hit-test.js";
+export { extentToSpatialFilter, selectLinkedViewQueryProjection, subscribeExplorationSelector, } from "../exploration/selectors.js";
+export { setFeatureState, getFeatureState, removeFeatureState, createHoverHandler, createSelectionHandler, } from "./feature-state.js";
+export { bindDetailToSelection, bindChartToExploration, bindFilterControlsToExploration, bindMapExtentToExploration, bindMapSelectionToExploration, bindQueryProjectionToExploration, bindTableSelectionToExploration, syncMapLayerFilterToExploration, syncFeatureStateSelection, } from "./exploration-bindings.js";
+export { preparePrimaryDetailModel, prepareSelectionDetailModels } from "./detail-model.js";
+export { interactionQueryParamNames, parseInteractionQueryState, parseSelection, serializeInteractionQueryState, serializeSelection, } from "./share-state.js";
+export type { HonuaHitFeature, HonuaHitTestDegradedReason, HonuaHitTestDegradedState, HonuaHitTestDetailContext, HonuaHitTestDetailLoader, HonuaHitTestFeatureOptions, HonuaHitTestMap, HonuaHitTestOptions, HonuaHitTestRasterSample, HonuaHitTestResult, HonuaLngLat, HonuaNormalizeHitTestOptions, HonuaPointerEvent, HonuaPointerEventType, HonuaPointerInput, HonuaRenderedFeatureContext, HonuaScreenPoint, } from "./hit-test.js";
+export type { FeatureStateMap, MapEventTarget, InteractiveMap, FeatureTarget, HoverHandlerOptions, HoverHandle, SelectionHandlerOptions, SelectionHandle, } from "./feature-state.js";
+export type { ExplorationSelector, ExplorationSelectorListener, ExplorationSelectorSubscribeOptions, LinkedViewQueryProjection, LinkedViewQueryProjectionOptions, LinkedViewSpatialMode, } from "../exploration/selectors.js";
+export type { FeatureStateSelectionSyncOptions, ChartBucketSelection, ChartBucketSelectionOptions, ChartExplorationBinding, FilterControlsExplorationBinding, InteractionBindingHandle, LinkedViewQueryBindingOptions, MapExtentExplorationBindingOptions, MapExtentExplorationSource, MapLayerFilterExplorationBindingOptions, MapLayerFilterTarget, MapSelectionExplorationBindingOptions, SelectionDetailListener, TableSelectionExplorationBinding, } from "./exploration-bindings.js";
+export type { DetailFeatureLike, DetailFieldDefinition, DetailFieldModel, DetailModel, DetailModelOptions, DetailSelectionStatus, } from "./detail-model.js";
+export type { ShareableInteractionQueryParams, ShareableInteractionQueryState } from "./share-state.js";
+//# sourceMappingURL=index.d.ts.map

package/interactions/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/interactions/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,EACL,2BAA2B,EAC3B,UAAU,EACV,mBAAmB,EACnB,wBAAwB,EACxB,qBAAqB,GACtB,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,qBAAqB,EACrB,+BAA+B,EAC/B,4BAA4B,GAC7B,MAAM,6BAA6B,CAAC;AACrC,OAAO,EACL,eAAe,EACf,eAAe,EACf,kBAAkB,EAClB,kBAAkB,EAClB,sBAAsB,GACvB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,qBAAqB,EACrB,sBAAsB,EACtB,+BAA+B,EAC/B,0BAA0B,EAC1B,6BAA6B,EAC7B,gCAAgC,EAChC,+BAA+B,EAC/B,+BAA+B,EAC/B,yBAAyB,GAC1B,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAE,yBAAyB,EAAE,4BAA4B,EAAE,MAAM,mBAAmB,CAAC;AAC5F,OAAO,EACL,0BAA0B,EAC1B,0BAA0B,EAC1B,cAAc,EACd,8BAA8B,EAC9B,kBAAkB,GACnB,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EACV,eAAe,EACf,0BAA0B,EAC1B,yBAAyB,EACzB,yBAAyB,EACzB,wBAAwB,EACxB,0BAA0B,EAC1B,eAAe,EACf,mBAAmB,EACnB,wBAAwB,EACxB,kBAAkB,EAClB,WAAW,EACX,4BAA4B,EAC5B,iBAAiB,EACjB,qBAAqB,EACrB,iBAAiB,EACjB,2BAA2B,EAC3B,gBAAgB,GACjB,MAAM,eAAe,CAAC;AACvB,YAAY,EACV,eAAe,EACf,cAAc,EACd,cAAc,EACd,aAAa,EACb,mBAAmB,EACnB,WAAW,EACX,uBAAuB,EACvB,eAAe,GAChB,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EACV,mBAAmB,EACnB,2BAA2B,EAC3B,mCAAmC,EACnC,yBAAyB,EACzB,gCAAgC,EAChC,qBAAqB,GACtB,MAAM,6BAA6B,CAAC;AACrC,YAAY,EACV,gCAAgC,EAChC,oBAAoB,EACpB,2BAA2B,EAC3B,uBAAuB,EACvB,gCAAgC,EAChC,wBAAwB,EACxB,6BAA6B,EAC7B,kCAAkC,EAClC,0BAA0B,EAC1B,uCAAuC,EACvC,oBAAoB,EACpB,qCAAqC,EACrC,uBAAuB,EACvB,gCAAgC,GACjC,MAAM,2BAA2B,CAAC;AACnC,YAAY,EACV,iBAAiB,EACjB,qBAAqB,EACrB,gBAAgB,EAChB,WAAW,EACX,kBAAkB,EAClB,qBAAqB,GACtB,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EAAE,+BAA+B,EAAE,8BAA8B,EAAE,MAAM,kBAAkB,CAAC"}

package/interactions/index.js

@@ -0,0 +1,24 @@
+/**
+ * `@honua/sdk-js/interactions` — hit-test, pointer normalization, and the
+ * binding primitives that wire chart / map / table widgets to an
+ * `ExplorationContext`.
+ *
+ * @example
+ * ```ts
+ * import { hitTestMap, bindMapSelectionToExploration } from "@honua/sdk-js/interactions";
+ *
+ * map.on("click", async (event) => {
+ *   const hit = await hitTestMap(map, event);
+ *   if (hit?.feature) ctx.dispatch({ type: "select", target: hit.feature });
+ * });
+ * bindMapSelectionToExploration({ map, context: ctx, sourceId: "parcels" });
+ * ```
+ *
+ * @packageDocumentation
+ */
+export { createQueryTileDetailLoader, hitTestMap, normalizeHitFeature, normalizeHitTestFeatures, normalizePointerEvent, } from "./hit-test.js";
+export { extentToSpatialFilter, selectLinkedViewQueryProjection, subscribeExplorationSelector, } from "../exploration/selectors.js";
+export { setFeatureState, getFeatureState, removeFeatureState, createHoverHandler, createSelectionHandler, } from "./feature-state.js";
+export { bindDetailToSelection, bindChartToExploration, bindFilterControlsToExploration, bindMapExtentToExploration, bindMapSelectionToExploration, bindQueryProjectionToExploration, bindTableSelectionToExploration, syncMapLayerFilterToExploration, syncFeatureStateSelection, } from "./exploration-bindings.js";
+export { preparePrimaryDetailModel, prepareSelectionDetailModels } from "./detail-model.js";
+export { interactionQueryParamNames, parseInteractionQueryState, parseSelection, serializeInteractionQueryState, serializeSelection, } from "./share-state.js";