@honua/app-platform 0.0.20-alpha.0

package/geocoding/index.d.ts

@@ -0,0 +1,106 @@
+/**
+ * `@honua/sdk-js/geocoding` — `HonuaGeocodingClient` for forward / reverse
+ * geocoding and typeahead suggestions over a Honua-hosted GeocodeServer.
+ *
+ * @example
+ * ```ts
+ * import { HonuaGeocodingClient } from "@honua/sdk-js/geocoding";
+ *
+ * const geo = new HonuaGeocodingClient({
+ *   baseUrl: "https://your-honua-server.example",
+ *   locatorName: "world-geocoder",
+ * });
+ *
+ * const results = await geo.forwardGeocode("1 Honolulu Pl, HI");
+ * // reverseGeocode is latitude-first, then longitude.
+ * const here = await geo.reverseGeocode(21.30, -157.85);
+ * const hints = await geo.suggest("honol");
+ * ```
+ *
+ * @example Debounced typeahead
+ * ```ts
+ * let timer: ReturnType<typeof setTimeout> | undefined;
+ * input.addEventListener("input", (event) => {
+ *   clearTimeout(timer);
+ *   const text = (event.target as HTMLInputElement).value;
+ *   timer = setTimeout(async () => {
+ *     render(await geo.suggest(text));
+ *   }, 200);
+ * });
+ * ```
+ *
+ * @packageDocumentation
+ */
+export interface GeocodingClientOptions {
+    baseUrl: string;
+    locatorName?: string;
+    apiKey?: string;
+    bearerToken?: string;
+    fetchFn?: typeof fetch;
+    timeoutMs?: number;
+}
+export interface ForwardGeocodeOptions {
+    maxResults?: number;
+    countryCodes?: string;
+    spatialReferenceWkid?: number;
+}
+export interface ReverseGeocodeOptions {
+    spatialReferenceWkid?: number;
+}
+export interface SuggestOptions {
+    maxSuggestions?: number;
+    countryCodes?: string;
+}
+export interface GeocodeResult {
+    address: string;
+    latitude: number;
+    longitude: number;
+    score: number;
+    attributes: Record<string, string | null>;
+}
+export interface ReverseGeocodeResult {
+    address: string;
+    latitude: number;
+    longitude: number;
+    attributes: Record<string, string | null>;
+}
+export interface GeocodeSuggestion {
+    text: string;
+    magicKey: string;
+    isCollection: boolean;
+}
+export declare class HonuaGeocodingClient {
+    private readonly baseUrl;
+    private readonly locatorName;
+    private readonly fetchFn;
+    private readonly defaultHeaders;
+    private readonly timeoutMs;
+    constructor(options: GeocodingClientOptions);
+    /**
+     * Forward-geocode a single-line address string into one or more candidate
+     * locations.
+     */
+    forwardGeocode(address: string, options?: ForwardGeocodeOptions): Promise<GeocodeResult[]>;
+    /**
+     * Reverse-geocode a latitude/longitude pair to the nearest address.
+     * Returns `null` when the server cannot find an address for the given
+     * coordinates.
+     */
+    reverseGeocode(latitude: number, longitude: number, options?: ReverseGeocodeOptions): Promise<ReverseGeocodeResult | null>;
+    /**
+     * Retrieve type-ahead suggestions for a partial address string.
+     */
+    suggest(text: string, options?: SuggestOptions): Promise<GeocodeSuggestion[]>;
+    private serviceBasePath;
+    /**
+     * Fetch with `redirect: "manual"`, only following a redirect when its target
+     * stays on the configured base origin. The geocoding client attaches its API
+     * key as a custom `X-API-Key` header that the runtime does not strip across a
+     * cross-origin redirect, so auto-following one would leak the key to the
+     * redirect target's host. Cross-origin (or origin-unverifiable) redirects
+     * throw instead of replaying the credentialed request off-origin.
+     */
+    private fetchWithSafeRedirects;
+    private request;
+}
+//# sourceMappingURL=index.d.ts.map

package/geocoding/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/geocoding/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AASH,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,OAAO,KAAK,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,qBAAqB;IACpC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,oBAAoB,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,MAAM,WAAW,qBAAqB;IACpC,oBAAoB,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,MAAM,WAAW,cAAc;IAC7B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC,CAAC;CAC3C;AAED,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC,CAAC;CAC3C;AAED,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,OAAO,CAAC;CACvB;AA0ED,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAe;IACvC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAyB;IACxD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAqB;gBAE5B,OAAO,EAAE,sBAAsB;IAwBlD;;;OAGG;IACU,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,qBAAqB,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC;IA+BvG;;;;OAIG;IACU,cAAc,CACzB,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE,qBAAqB,GAC9B,OAAO,CAAC,oBAAoB,GAAG,IAAI,CAAC;IA8CvC;;OAEG;IACU,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,iBAAiB,EAAE,CAAC;IA8B1F,OAAO,CAAC,eAAe;IAIvB;;;;;;;OAOG;YACW,sBAAsB;YA0CtB,OAAO;CAiDtB"}

package/geocoding/index.js

@@ -0,0 +1,278 @@
+/**
+ * `@honua/sdk-js/geocoding` — `HonuaGeocodingClient` for forward / reverse
+ * geocoding and typeahead suggestions over a Honua-hosted GeocodeServer.
+ *
+ * @example
+ * ```ts
+ * import { HonuaGeocodingClient } from "@honua/sdk-js/geocoding";
+ *
+ * const geo = new HonuaGeocodingClient({
+ *   baseUrl: "https://your-honua-server.example",
+ *   locatorName: "world-geocoder",
+ * });
+ *
+ * const results = await geo.forwardGeocode("1 Honolulu Pl, HI");
+ * // reverseGeocode is latitude-first, then longitude.
+ * const here = await geo.reverseGeocode(21.30, -157.85);
+ * const hints = await geo.suggest("honol");
+ * ```
+ *
+ * @example Debounced typeahead
+ * ```ts
+ * let timer: ReturnType<typeof setTimeout> | undefined;
+ * input.addEventListener("input", (event) => {
+ *   clearTimeout(timer);
+ *   const text = (event.target as HTMLInputElement).value;
+ *   timer = setTimeout(async () => {
+ *     render(await geo.suggest(text));
+ *   }, 200);
+ * });
+ * ```
+ *
+ * @packageDocumentation
+ */
+import { HonuaAbortError, HonuaHttpError, HonuaNetworkError, HonuaTimeoutError } from "../core/errors.js";
+import { encodeServiceIdPath, trimTrailingSlashes } from "../core/path-utils.js";
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/** Redirect status codes that carry a `Location` header. */
+const GEOCODING_REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308]);
+/** Maximum number of redirects {@link HonuaGeocodingClient} will follow. */
+const GEOCODING_MAX_REDIRECTS = 20;
+function isAbsoluteHttpUrl(value) {
+    return value.startsWith("http://") || value.startsWith("https://");
+}
+function normalizeBaseUrl(url) {
+    return trimTrailingSlashes(url);
+}
+function stringifyAttributes(attrs) {
+    const result = {};
+    for (const [key, value] of Object.entries(attrs)) {
+        if (value === null || value === undefined) {
+            result[key] = null;
+        }
+        else {
+            result[key] = String(value);
+        }
+    }
+    return result;
+}
+// ---------------------------------------------------------------------------
+// Client
+// ---------------------------------------------------------------------------
+export class HonuaGeocodingClient {
+    baseUrl;
+    locatorName;
+    fetchFn;
+    defaultHeaders;
+    timeoutMs;
+    constructor(options) {
+        this.baseUrl = normalizeBaseUrl(options.baseUrl);
+        this.locatorName = options.locatorName ?? "World";
+        // Bind to `globalThis` at assignment: invoking an unbound `window.fetch`
+        // as `this.fetchFn(...)` throws "TypeError: Illegal invocation" in
+        // browsers. Binding is a no-op for Node's undici fetch and for
+        // caller-supplied wrappers.
+        this.fetchFn = (options.fetchFn ?? fetch).bind(globalThis);
+        this.timeoutMs = options.timeoutMs;
+        const headers = {};
+        if (options.apiKey) {
+            headers["X-API-Key"] = options.apiKey;
+        }
+        if (options.bearerToken) {
+            headers.Authorization = `Bearer ${options.bearerToken}`;
+        }
+        this.defaultHeaders = headers;
+    }
+    // -------------------------------------------------------------------------
+    // Public methods
+    // -------------------------------------------------------------------------
+    /**
+     * Forward-geocode a single-line address string into one or more candidate
+     * locations.
+     */
+    async forwardGeocode(address, options) {
+        const params = new URLSearchParams();
+        params.set("singleLine", address);
+        params.set("f", "json");
+        if (options?.maxResults !== undefined) {
+            params.set("maxLocations", String(options.maxResults));
+        }
+        if (options?.countryCodes !== undefined) {
+            params.set("countryCode", options.countryCodes);
+        }
+        if (options?.spatialReferenceWkid !== undefined) {
+            params.set("outSR", String(options.spatialReferenceWkid));
+        }
+        const url = `${this.serviceBasePath()}/findAddressCandidates?${params.toString()}`;
+        const data = await this.request(url);
+        if (data.error) {
+            throw new HonuaHttpError(data.error.code, `Geocode server error: ${data.error.message}`, data.error);
+        }
+        return (data.candidates ?? []).map((c) => ({
+            address: c.address,
+            longitude: c.location.x,
+            latitude: c.location.y,
+            score: c.score,
+            attributes: stringifyAttributes(c.attributes ?? {}),
+        }));
+    }
+    /**
+     * Reverse-geocode a latitude/longitude pair to the nearest address.
+     * Returns `null` when the server cannot find an address for the given
+     * coordinates.
+     */
+    async reverseGeocode(latitude, longitude, options) {
+        const params = new URLSearchParams();
+        params.set("location", `${longitude},${latitude}`);
+        params.set("f", "json");
+        if (options?.spatialReferenceWkid !== undefined) {
+            params.set("outSR", String(options.spatialReferenceWkid));
+        }
+        const url = `${this.serviceBasePath()}/reverseGeocode?${params.toString()}`;
+        let data;
+        try {
+            data = await this.request(url);
+        }
+        catch (err) {
+            // Some geocode servers return an HTTP error when no address is found.
+            if (err instanceof HonuaHttpError && err.statusCode === 400) {
+                return null;
+            }
+            throw err;
+        }
+        if (data.error) {
+            // Server-level "no result" errors are not exceptional.
+            if (data.error.code === 400) {
+                return null;
+            }
+            throw new HonuaHttpError(data.error.code, `Reverse geocode server error: ${data.error.message}`, data.error);
+        }
+        if (!data.address || !data.location) {
+            return null;
+        }
+        const { Match_addr, ...rest } = data.address;
+        return {
+            address: Match_addr ?? "",
+            longitude: data.location.x,
+            latitude: data.location.y,
+            attributes: stringifyAttributes(rest),
+        };
+    }
+    /**
+     * Retrieve type-ahead suggestions for a partial address string.
+     */
+    async suggest(text, options) {
+        const params = new URLSearchParams();
+        params.set("text", text);
+        params.set("f", "json");
+        if (options?.maxSuggestions !== undefined) {
+            params.set("maxSuggestions", String(options.maxSuggestions));
+        }
+        if (options?.countryCodes !== undefined) {
+            params.set("countryCode", options.countryCodes);
+        }
+        const url = `${this.serviceBasePath()}/suggest?${params.toString()}`;
+        const data = await this.request(url);
+        if (data.error) {
+            throw new HonuaHttpError(data.error.code, `Suggest server error: ${data.error.message}`, data.error);
+        }
+        return (data.suggestions ?? []).map((s) => ({
+            text: s.text,
+            magicKey: s.magicKey,
+            isCollection: s.isCollection,
+        }));
+    }
+    // -------------------------------------------------------------------------
+    // Internals
+    // -------------------------------------------------------------------------
+    serviceBasePath() {
+        return `${this.baseUrl}/rest/services/${encodeServiceIdPath(this.locatorName)}/GeocodeServer`;
+    }
+    /**
+     * Fetch with `redirect: "manual"`, only following a redirect when its target
+     * stays on the configured base origin. The geocoding client attaches its API
+     * key as a custom `X-API-Key` header that the runtime does not strip across a
+     * cross-origin redirect, so auto-following one would leak the key to the
+     * redirect target's host. Cross-origin (or origin-unverifiable) redirects
+     * throw instead of replaying the credentialed request off-origin.
+     */
+    async fetchWithSafeRedirects(url, init) {
+        const baseOrigin = isAbsoluteHttpUrl(this.baseUrl) ? new URL(this.baseUrl).origin : undefined;
+        let currentUrl = url;
+        for (let redirects = 0;; redirects += 1) {
+            const response = await this.fetchFn(currentUrl, { ...init, redirect: "manual" });
+            if (response.type === "opaqueredirect") {
+                throw new HonuaNetworkError("Refusing to follow an opaque cross-origin redirect; the geocoding API key would be leaked to the redirect target.", undefined);
+            }
+            if (!GEOCODING_REDIRECT_STATUSES.has(response.status)) {
+                return response;
+            }
+            if (redirects >= GEOCODING_MAX_REDIRECTS) {
+                throw new HonuaNetworkError(`Exceeded the maximum of ${GEOCODING_MAX_REDIRECTS} redirects.`, undefined);
+            }
+            const location = response.headers.get("location");
+            if (!location) {
+                throw new HonuaNetworkError("Redirect response is missing a Location header.", undefined);
+            }
+            let target;
+            try {
+                target = new URL(location, currentUrl);
+            }
+            catch {
+                throw new HonuaNetworkError(`Redirect response has an invalid Location header: ${location}`, undefined);
+            }
+            if (baseOrigin === undefined || target.origin !== baseOrigin) {
+                throw new HonuaNetworkError(`Refusing to follow a cross-origin redirect to ${target.origin}; the geocoding API key would be leaked.`, undefined);
+            }
+            currentUrl = target.toString();
+            await response.body?.cancel().catch(() => undefined);
+        }
+    }
+    async request(url) {
+        const controller = new AbortController();
+        let timeoutId;
+        if (this.timeoutMs !== undefined) {
+            timeoutId = setTimeout(() => controller.abort(), this.timeoutMs);
+        }
+        let response;
+        try {
+            response = await this.fetchWithSafeRedirects(url, {
+                method: "GET",
+                headers: this.defaultHeaders,
+                signal: controller.signal,
+            });
+        }
+        catch (err) {
+            if (timeoutId !== undefined) {
+                clearTimeout(timeoutId);
+            }
+            if (err instanceof DOMException && err.name === "AbortError") {
+                if (this.timeoutMs !== undefined) {
+                    throw new HonuaTimeoutError(this.timeoutMs);
+                }
+                throw new HonuaAbortError();
+            }
+            throw new HonuaNetworkError(err instanceof Error
+                ? `Geocoding request failed: ${err.message}`
+                : "Geocoding request failed due to a network error", err);
+        }
+        finally {
+            if (timeoutId !== undefined) {
+                clearTimeout(timeoutId);
+            }
+        }
+        if (!response.ok) {
+            let body;
+            try {
+                body = await response.json();
+            }
+            catch {
+                body = await response.text().catch(() => null);
+            }
+            throw new HonuaHttpError(response.status, `Geocoding request failed with status ${response.status}`, body);
+        }
+        return (await response.json());
+    }
+}

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