@honua/react 0.0.20-alpha.0 → 0.1.1-beta.0

package/map/temporal-playback.js

@@ -0,0 +1,247 @@
+/**
+ * Temporal playback (issue #497 REQ-004): a renderer-neutral play/pause/
+ * scrub controller over a time extent, plus thin bindings that drive time
+ * filters through the data-to-map bridge (`MountedSource.setFilter`) or
+ * directly through MapLibre layer filters.
+ *
+ * Memory is bounded by construction: the controller keeps only the current
+ * window (two numbers). Filter application is coalesced — at most one
+ * request in flight and at most one pending window; intermediate windows
+ * are dropped, never queued. No window data is pre-fetched or cached by the
+ * controller itself (the issue's snapshot-plus-delta realtime vocabulary
+ * from #393 applies only when playback is layered over a realtime feed;
+ * playback over static data has no realtime dependency).
+ *
+ * @module
+ */
+import { HonuaSdkError } from "../core/error-envelope.js";
+/** Raised for invalid playback options. @experimental */
+export class HonuaTemporalPlaybackError extends HonuaSdkError {
+    constructor(message) {
+        super("map.temporal-playback.invalid-option", message);
+        this.name = "HonuaTemporalPlaybackError";
+    }
+}
+// ── Implementation ───────────────────────────────────────────────
+/**
+ * Create a temporal playback controller over a time extent.
+ *
+ * @example
+ * ```ts
+ * const playback = createTemporalPlayback({
+ *   handle: mounted, // from mountSource()
+ *   timeField: "event_time",
+ *   extent: ["2026-01-01T00:00:00Z", "2026-02-01T00:00:00Z"],
+ *   windowMs: 24 * 60 * 60 * 1000,
+ *   frameIntervalMs: 400,
+ * });
+ * playback.on("tick", ({ window, progress }) => updateSlider(progress));
+ * playback.play();
+ * ```
+ *
+ * @experimental
+ */
+export function createTemporalPlayback(options) {
+    const extentStart = toEpochMs(options.extent?.[0], "extent[0]");
+    const extentEnd = toEpochMs(options.extent?.[1], "extent[1]");
+    if (extentEnd <= extentStart) {
+        throw new HonuaTemporalPlaybackError("extent end must be after extent start.");
+    }
+    let windowMs = requirePositive(options.windowMs, "windowMs");
+    const frameIntervalMs = requirePositive(options.frameIntervalMs ?? 500, "frameIntervalMs");
+    const stepMs = requirePositive(options.stepMs ?? options.windowMs, "stepMs");
+    if ((options.handle || options.layer) && !options.timeField) {
+        throw new HonuaTemporalPlaybackError("timeField is required with the handle/layer bindings.");
+    }
+    if (!options.handle && !options.layer && !options.apply) {
+        throw new HonuaTemporalPlaybackError("Provide at least one sink: handle, layer, or apply.");
+    }
+    const sinks = buildSinks(options);
+    const extent = Object.freeze({ start: extentStart, end: extentEnd });
+    const listeners = new Map();
+    let windowStart = extentStart;
+    let timer;
+    let disposed = false;
+    // Coalesced application: at most one in-flight window and one pending
+    // window; intermediate windows are dropped (bounded memory, REQ-004).
+    let inFlight = false;
+    let pending;
+    const emit = (type, payload) => {
+        for (const listener of listeners.get(type) ?? []) {
+            try {
+                listener(payload);
+            }
+            catch {
+                /* listener errors must not break playback */
+            }
+        }
+    };
+    const currentWindow = () => Object.freeze({ start: windowStart, end: windowStart + windowMs });
+    const progress = () => {
+        const span = extent.end - extent.start;
+        return span <= 0 ? 1 : Math.min(1, Math.max(0, (windowStart - extent.start) / span));
+    };
+    const drainPending = () => {
+        if (pending === undefined)
+            return;
+        const next = pending;
+        pending = undefined;
+        applyWindow(next);
+    };
+    const applyWindow = (window) => {
+        if (disposed)
+            return;
+        if (inFlight) {
+            pending = window; // keep only the latest window
+            return;
+        }
+        inFlight = true;
+        void Promise.all(sinks.map((sink) => Promise.resolve().then(() => sink(window))))
+            .then(() => {
+            if (!disposed)
+                emit("tick", { window, progress: progress(), playing: timer !== undefined });
+        })
+            .catch((error) => {
+            if (!disposed)
+                emit("error", error);
+        })
+            .finally(() => {
+            inFlight = false;
+            if (!disposed)
+                drainPending();
+        });
+    };
+    const lastStart = () => Math.max(extent.start, extent.end - windowMs);
+    const advance = () => {
+        if (windowStart >= lastStart()) {
+            if (options.loop) {
+                windowStart = extent.start;
+                applyWindow(currentWindow());
+                return;
+            }
+            pause();
+            emit("end");
+            return;
+        }
+        windowStart = Math.min(windowStart + stepMs, lastStart());
+        applyWindow(currentWindow());
+    };
+    const play = () => {
+        if (disposed || timer !== undefined)
+            return;
+        if (windowStart >= lastStart() && !options.loop)
+            windowStart = extent.start;
+        timer = setInterval(advance, frameIntervalMs);
+        emit("play");
+        applyWindow(currentWindow());
+    };
+    const pause = () => {
+        if (timer === undefined)
+            return;
+        clearInterval(timer);
+        timer = undefined;
+        emit("pause");
+    };
+    return {
+        get playing() {
+            return timer !== undefined;
+        },
+        get window() {
+            return currentWindow();
+        },
+        extent,
+        play,
+        pause,
+        scrub(time) {
+            if (disposed)
+                return;
+            windowStart = Math.min(Math.max(toEpochMs(time, "scrub time"), extent.start), lastStart());
+            applyWindow(currentWindow());
+        },
+        setWindow(nextWindowMs) {
+            if (disposed)
+                return;
+            windowMs = requirePositive(nextWindowMs, "windowMs");
+            windowStart = Math.min(windowStart, lastStart());
+            applyWindow(currentWindow());
+        },
+        on(type, listener) {
+            const set = listeners.get(type) ?? new Set();
+            set.add(listener);
+            listeners.set(type, set);
+            return {
+                remove: () => {
+                    set.delete(listener);
+                },
+            };
+        },
+        dispose() {
+            if (disposed)
+                return;
+            disposed = true;
+            if (timer !== undefined)
+                clearInterval(timer);
+            timer = undefined;
+            pending = undefined;
+            listeners.clear();
+        },
+    };
+}
+function buildSinks(options) {
+    const sinks = [];
+    if (options.handle && options.timeField) {
+        sinks.push(createHandleSink(options.handle, options.timeField, options.baseQuery, options.formatWhere));
+    }
+    if (options.layer && options.timeField) {
+        sinks.push(createLayerSink(options.layer.map, options.layer.layerIds, options.timeField));
+    }
+    if (options.apply)
+        sinks.push(options.apply);
+    return sinks;
+}
+function createHandleSink(handle, timeField, baseQuery, formatWhere) {
+    return async (window) => {
+        const windowWhere = formatWhere
+            ? formatWhere(window, timeField)
+            : `${timeField} >= ${window.start} AND ${timeField} < ${window.end}`;
+        const where = baseQuery?.where ? `(${baseQuery.where}) AND (${windowWhere})` : windowWhere;
+        await handle.setFilter({ ...(baseQuery ?? {}), where });
+    };
+}
+function createLayerSink(map, layerIds, timeField) {
+    // Capture each layer's filter at bind time so the window range composes
+    // with (instead of replacing) bridge geometry filters.
+    const baseFilters = new Map();
+    for (const layerId of layerIds) {
+        baseFilters.set(layerId, typeof map.getFilter === "function" ? map.getFilter(layerId) : undefined);
+    }
+    return (window) => {
+        const range = [
+            [">=", ["get", timeField], window.start],
+            ["<", ["get", timeField], window.end],
+        ];
+        for (const layerId of layerIds) {
+            const base = baseFilters.get(layerId);
+            map.setFilter(layerId, base !== undefined && base !== null ? ["all", base, ...range] : ["all", ...range]);
+        }
+    };
+}
+// ── Time parsing ─────────────────────────────────────────────────
+function toEpochMs(value, label) {
+    if (typeof value === "number" && Number.isFinite(value))
+        return value;
+    if (value instanceof Date && !Number.isNaN(value.getTime()))
+        return value.getTime();
+    if (typeof value === "string") {
+        const parsed = Date.parse(value);
+        if (!Number.isNaN(parsed))
+            return parsed;
+    }
+    throw new HonuaTemporalPlaybackError(`${label} must be an epoch-ms number, Date, or ISO-8601 string.`);
+}
+function requirePositive(value, label) {
+    if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) {
+        throw new HonuaTemporalPlaybackError(`${label} must be a positive, finite number.`);
+    }
+    return value;
+}

package/package.json

@@ -1,8 +1,25 @@
 {
   "name": "@honua/react",
-  "version": "0.0.20-alpha.0",
+  "version": "0.1.1-beta.0",
   "description": "React bindings for the Honua SDK: provider, hooks, and map components",
+  "keywords": [
+    "gis",
+    "geospatial",
+    "maplibre",
+    "typescript",
+    "react",
+    "hooks",
+    "map",
+    "arcgis",
+    "ogc-api",
+    "geocoding"
+  ],
   "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/honua-io/honua-sdk-js.git",
+    "directory": "."
+  },
   "type": "module",
   "main": "./react/index.js",
   "types": "./react/index.d.ts",
@@ -16,6 +33,7 @@
     "@maplibre/maplibre-gl-style-spec": "^24.7.0"
   },
   "peerDependencies": {
+    "@honua/sdk": "0.1.1-beta.0",
     "react": "^18.2.0 || ^19.0.0",
     "react-dom": "^18.2.0 || ^19.0.0",
     "maplibre-gl": "^5.0.0"

package/query-planner/canonical.d.ts

@@ -0,0 +1,7 @@
+import type { JsonValue } from "./types.js";
+/** Deterministic JSON serialization with sorted object keys and strict values. */
+export declare function canonicalStringify(value: JsonValue): string;
+export declare function toJsonValue(value: unknown, path?: string): JsonValue;
+/** Portable synchronous SHA-256 over UTF-8 input (browser, worker, and Node). */
+export declare function sha256(value: string): `sha256:${string}`;
+//# sourceMappingURL=canonical.d.ts.map

package/query-planner/canonical.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"canonical.d.ts","sourceRoot":"","sources":["../../../src/query-planner/canonical.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE5C,kFAAkF;AAClF,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,SAAS,GAAG,MAAM,CAE3D;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,SAAM,GAAG,SAAS,CAEjE;AA6DD,iFAAiF;AACjF,wBAAgB,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,MAAM,EAAE,CA6DxD"}

package/query-planner/canonical.js

@@ -0,0 +1,145 @@
+/** Deterministic JSON serialization with sorted object keys and strict values. */
+export function canonicalStringify(value) {
+    return JSON.stringify(sortJson(value));
+}
+export function toJsonValue(value, path = "$") {
+    return convertJson(value, path, new WeakSet());
+}
+function convertJson(value, path, ancestors) {
+    if (value === null || typeof value === "string" || typeof value === "boolean")
+        return value;
+    if (typeof value === "number") {
+        if (!Number.isFinite(value))
+            throw new TypeError(`${path} must contain only finite numbers`);
+        return Object.is(value, -0) ? 0 : value;
+    }
+    if (Array.isArray(value)) {
+        if (ancestors.has(value))
+            throw new TypeError(`${path} must not contain cycles`);
+        ancestors.add(value);
+        const converted = value.map((entry, index) => {
+            if (entry === undefined)
+                throw new TypeError(`${path}[${index}] must not be undefined`);
+            return convertJson(entry, `${path}[${index}]`, ancestors);
+        });
+        ancestors.delete(value);
+        return converted;
+    }
+    if (typeof value === "object") {
+        if (ancestors.has(value))
+            throw new TypeError(`${path} must not contain cycles`);
+        const prototype = Object.getPrototypeOf(value);
+        if (prototype !== Object.prototype && prototype !== null) {
+            throw new TypeError(`${path} must contain only plain JSON objects`);
+        }
+        ancestors.add(value);
+        const converted = {};
+        for (const key of Object.keys(value).sort()) {
+            const entry = value[key];
+            if (entry !== undefined) {
+                Object.defineProperty(converted, key, {
+                    value: convertJson(entry, `${path}.${key}`, ancestors),
+                    enumerable: true,
+                    writable: true,
+                    configurable: true,
+                });
+            }
+        }
+        ancestors.delete(value);
+        return converted;
+    }
+    throw new TypeError(`${path} contains unsupported ${typeof value}`);
+}
+function sortJson(value) {
+    if (Array.isArray(value))
+        return value.map(sortJson);
+    if (value !== null && typeof value === "object") {
+        const object = value;
+        const sorted = {};
+        for (const key of Object.keys(object).sort()) {
+            Object.defineProperty(sorted, key, {
+                value: sortJson(object[key]),
+                enumerable: true,
+                writable: true,
+                configurable: true,
+            });
+        }
+        return sorted;
+    }
+    return value;
+}
+/** Portable synchronous SHA-256 over UTF-8 input (browser, worker, and Node). */
+export function sha256(value) {
+    const bytes = new TextEncoder().encode(value);
+    const bitLength = bytes.length * 8;
+    const paddedLength = Math.ceil((bytes.length + 9) / 64) * 64;
+    const padded = new Uint8Array(paddedLength);
+    padded.set(bytes);
+    padded[bytes.length] = 0x80;
+    const view = new DataView(padded.buffer);
+    const high = Math.floor(bitLength / 0x1_0000_0000);
+    const low = bitLength >>> 0;
+    view.setUint32(paddedLength - 8, high, false);
+    view.setUint32(paddedLength - 4, low, false);
+    const state = new Uint32Array([
+        0x6a09e667, 0xbb67ae85, 0x3c6ef372, 0xa54ff53a, 0x510e527f, 0x9b05688c, 0x1f83d9ab, 0x5be0cd19,
+    ]);
+    const words = new Uint32Array(64);
+    for (let offset = 0; offset < paddedLength; offset += 64) {
+        for (let index = 0; index < 16; index++)
+            words[index] = view.getUint32(offset + index * 4, false);
+        for (let index = 16; index < 64; index++) {
+            const before15 = words[index - 15] ?? 0;
+            const before2 = words[index - 2] ?? 0;
+            const s0 = rotateRight(before15, 7) ^ rotateRight(before15, 18) ^ (before15 >>> 3);
+            const s1 = rotateRight(before2, 17) ^ rotateRight(before2, 19) ^ (before2 >>> 10);
+            words[index] = ((words[index - 16] ?? 0) + s0 + (words[index - 7] ?? 0) + s1) >>> 0;
+        }
+        let a = state[0] ?? 0;
+        let b = state[1] ?? 0;
+        let c = state[2] ?? 0;
+        let d = state[3] ?? 0;
+        let e = state[4] ?? 0;
+        let f = state[5] ?? 0;
+        let g = state[6] ?? 0;
+        let h = state[7] ?? 0;
+        for (let index = 0; index < 64; index++) {
+            const upper1 = rotateRight(e, 6) ^ rotateRight(e, 11) ^ rotateRight(e, 25);
+            const choose = (e & f) ^ (~e & g);
+            const temp1 = (h + upper1 + choose + (SHA256_CONSTANTS[index] ?? 0) + (words[index] ?? 0)) >>> 0;
+            const upper0 = rotateRight(a, 2) ^ rotateRight(a, 13) ^ rotateRight(a, 22);
+            const majority = (a & b) ^ (a & c) ^ (b & c);
+            const temp2 = (upper0 + majority) >>> 0;
+            h = g;
+            g = f;
+            f = e;
+            e = (d + temp1) >>> 0;
+            d = c;
+            c = b;
+            b = a;
+            a = (temp1 + temp2) >>> 0;
+        }
+        state[0] = ((state[0] ?? 0) + a) >>> 0;
+        state[1] = ((state[1] ?? 0) + b) >>> 0;
+        state[2] = ((state[2] ?? 0) + c) >>> 0;
+        state[3] = ((state[3] ?? 0) + d) >>> 0;
+        state[4] = ((state[4] ?? 0) + e) >>> 0;
+        state[5] = ((state[5] ?? 0) + f) >>> 0;
+        state[6] = ((state[6] ?? 0) + g) >>> 0;
+        state[7] = ((state[7] ?? 0) + h) >>> 0;
+    }
+    return `sha256:${Array.from(state, (word) => word.toString(16).padStart(8, "0")).join("")}`;
+}
+function rotateRight(value, amount) {
+    return (value >>> amount) | (value << (32 - amount));
+}
+const SHA256_CONSTANTS = new Uint32Array([
+    0x428a2f98, 0x71374491, 0xb5c0fbcf, 0xe9b5dba5, 0x3956c25b, 0x59f111f1, 0x923f82a4, 0xab1c5ed5, 0xd807aa98,
+    0x12835b01, 0x243185be, 0x550c7dc3, 0x72be5d74, 0x80deb1fe, 0x9bdc06a7, 0xc19bf174, 0xe49b69c1, 0xefbe4786,
+    0x0fc19dc6, 0x240ca1cc, 0x2de92c6f, 0x4a7484aa, 0x5cb0a9dc, 0x76f988da, 0x983e5152, 0xa831c66d, 0xb00327c8,
+    0xbf597fc7, 0xc6e00bf3, 0xd5a79147, 0x06ca6351, 0x14292967, 0x27b70a85, 0x2e1b2138, 0x4d2c6dfc, 0x53380d13,
+    0x650a7354, 0x766a0abb, 0x81c2c92e, 0x92722c85, 0xa2bfe8a1, 0xa81a664b, 0xc24b8b70, 0xc76c51a3, 0xd192e819,
+    0xd6990624, 0xf40e3585, 0x106aa070, 0x19a4c116, 0x1e376c08, 0x2748774c, 0x34b0bcb5, 0x391c0cb3, 0x4ed8aa4a,
+    0x5b9cca4f, 0x682e6ff3, 0x748f82ee, 0x78a5636f, 0x84c87814, 0x8cc70208, 0x90befffa, 0xa4506ceb, 0xbef9a3f7,
+    0xc67178f2,
+]);

package/query-planner/cql2-json.d.ts

@@ -0,0 +1,17 @@
+import { type SourceProtocol } from "../contract/schema.js";
+import type { Cql2JsonExpression, Cql2JsonInterchangeOptions, QueryFilter, SourceSpatiality } from "./semantic-types.js";
+type RuntimeFilter = QueryFilter<Record<string, unknown>, SourceProtocol, SourceSpatiality>;
+/**
+ * Export the CQL2-representable semantic-filter subset. CQL2 carries spatial
+ * CRS outside the expression, so every spatial export requires `filterCrs`
+ * and verifies that each operand uses that exact executable binding.
+ */
+export declare function semanticFilterToCql2Json<TRecord, TProtocol extends SourceProtocol, TSpatiality extends SourceSpatiality>(filter: QueryFilter<TRecord, TProtocol, TSpatiality>, options?: Cql2JsonInterchangeOptions): Cql2JsonExpression;
+/**
+ * Import the strict CQL2 JSON subset into the same runtime-validated semantic
+ * AST used by builders. Unknown functions, property-property comparisons,
+ * distance extensions, and other non-representable constructs fail closed.
+ */
+export declare function semanticFilterFromCql2Json(value: string | unknown, options?: Cql2JsonInterchangeOptions): RuntimeFilter;
+export {};
+//# sourceMappingURL=cql2-json.d.ts.map

package/query-planner/cql2-json.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cql2-json.d.ts","sourceRoot":"","sources":["../../../src/query-planner/cql2-json.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,KAAK,cAAc,EAIpB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,KAAK,EACV,kBAAkB,EAClB,0BAA0B,EAC1B,WAAW,EAEX,gBAAgB,EAEjB,MAAM,qBAAqB,CAAC;AAI7B,KAAK,aAAa,GAAG,WAAW,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,EAAE,gBAAgB,CAAC,CAAC;AAuE5F;;;;GAIG;AACH,wBAAgB,wBAAwB,CACtC,OAAO,EACP,SAAS,SAAS,cAAc,EAChC,WAAW,SAAS,gBAAgB,EACpC,MAAM,EAAE,WAAW,CAAC,OAAO,EAAE,SAAS,EAAE,WAAW,CAAC,EAAE,OAAO,GAAE,0BAA+B,GAAG,kBAAkB,CAYpH;AAED;;;;GAIG;AACH,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,MAAM,GAAG,OAAO,EACvB,OAAO,GAAE,0BAA+B,GACvC,aAAa,CAaf"}