@fusedio/widget-sdk 0.1.0

package/dist/hooks/use-fused-param.js

@@ -0,0 +1,283 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { useFusedWidgetBridge, useJsonUiNode } from "../bridge";
+import { useFormParams } from "../form";
+import { ParameterMessageType } from "../protocol";
+/**
+ * Two-way bind a component to a named canvas parameter.
+ *
+ * When another node broadcasts a param value (e.g. a map click, a dropdown
+ * selection from upstream), this hook receives it and updates `value`. When
+ * the user interacts locally, `setValue()` debounces and broadcasts back so
+ * connected UDF nodes re-run with the new value.
+ *
+ * Form integration: when this component is rendered inside a built-in Form,
+ * the live form-field value shadows the canvas value so siblings react
+ * before the form is submitted (form values are never broadcast to the
+ * canvas until submit).
+ *
+ * Works as plain local state if `param` is undefined or empty.
+ *
+ * Requires: a `FusedWidgetBridgeContext.Provider` ancestor. The workbench's
+ * `JsonUiProvider` provides one; tests use `createTestBridge()`.
+ *
+ * @example — number counter
+ * const { value, setValue } = useFusedParam({ param: "count", defaultValue: 0 });
+ * return <button onClick={() => setValue(value + 1)}>{value}</button>;
+ *
+ * @example — typed array param
+ * const { value, setValue } = useFusedParam({
+ *   param: "bounds",
+ *   defaultValue: [-74, 40, -73, 41] as [number, number, number, number],
+ *   validate: (v): v is [number, number, number, number] =>
+ *     Array.isArray(v) && v.length === 4 && v.every(n => typeof n === "number"),
+ * });
+ *
+ * @example — broadcast immediately on mouseup (bypass debounce)
+ * const { setValue, broadcastNow } = useFusedParam({ param: "hue", defaultValue: 0 });
+ * <input type="range" onChange={e => setValue(+e.target.value)} onMouseUp={broadcastNow} />
+ *
+ * @example — clear button
+ * const { clearValue } = useFusedParam({ param: "selection", defaultValue: null });
+ * <button onClick={() => clearValue(null)}>Reset</button>
+ */
+export function useFusedParam({ param, debounceMs = 300, readOnly = false, defaultValue, broadcastDefaultValue = true, validate, preprocess, }) {
+    const bridge = useFusedWidgetBridge();
+    const { configHash } = useJsonUiNode();
+    const enabled = !!param;
+    // Stable log helper — entries appear in the workbench's runtime logs panel.
+    // configHash is passed through so nested JsonUiConfigHashOverride subtrees
+    // tag entries correctly without requiring a bridge rebuild.
+    const logPreview = (action, raw) => {
+        if (!param)
+            return;
+        if (action === "Cleared") {
+            bridge.log.log(`Cleared param "${param}"`, "info", configHash);
+            return;
+        }
+        const preview = JSON.stringify(raw);
+        const trimmed = preview && preview.length > 100 ? preview.slice(0, 100) + "…" : preview;
+        bridge.log.log(`${action} param "${param}" = ${trimmed}`, "info", configHash);
+    };
+    // Stable validator and preprocessor. We deliberately omit `defaultValue`
+    // from the deps so a parent re-render passing a new defaultValue literal
+    // doesn't churn these. The type semantics only depend on the original.
+    const preprocessor = useMemo(() => preprocess ?? createDefaultPreprocessor(defaultValue), 
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [preprocess]);
+    const validator = useMemo(() => validate ?? createDefaultValidator(defaultValue), 
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [validate]);
+    // Form-scoped value shadows canvas value when inside a form.
+    const paramNamesForForm = useMemo(() => (param ? [param] : []), [param]);
+    const { inForm, values: formParams } = useFormParams(paramNamesForForm);
+    const formValue = param ? formParams[param] : undefined;
+    // ── Initial value resolution ────────────────────────────────────────────
+    // Read snapshot once to seed local state — subsequent updates come via the
+    // sync effect below. Reading the bridge here is safe (synchronous).
+    const initialCanvasValue = useMemo(() => {
+        if (!enabled || !param)
+            return undefined;
+        return bridge.params.getSnapshot(param);
+    }, [bridge, enabled, param]);
+    const computeInitialValue = () => {
+        const raw = inForm && formValue !== undefined ? formValue : initialCanvasValue;
+        if (raw === undefined || raw === null)
+            return defaultValue;
+        const processed = preprocessor(raw);
+        return validator(processed) ? processed : defaultValue;
+    };
+    const [value, setValueState] = useState(computeInitialValue);
+    const valueRef = useRef(value);
+    valueRef.current = value;
+    const debounceRef = useRef(null);
+    const isLocalChangeRef = useRef(false);
+    const didBroadcastOnMountRef = useRef(false);
+    // Stable closure over the latest binding for the unmount cleanup.
+    // bridge is captured by ref too so the cleanup effect's deps can stay `[]`
+    // — otherwise any bridge identity flip would re-run the effect and
+    // broadcast a stray CLEAR for every bound input, cascading through the
+    // canvas-param listener fan-out.
+    const latestBindingRef = useRef({ enabled, param });
+    latestBindingRef.current = { enabled, param };
+    const bridgeRef = useRef(bridge);
+    bridgeRef.current = bridge;
+    // ── Clear bound param when name changes (carry-over avoidance) ──────────
+    const prevParamRef = useRef(param);
+    useEffect(() => {
+        const prev = prevParamRef.current;
+        prevParamRef.current = param;
+        if (prev && prev !== param) {
+            bridge.params.clear(prev);
+        }
+    }, [bridge, param]);
+    // ── Subscribe to canvas (and form) updates ──────────────────────────────
+    useEffect(() => {
+        if (!enabled || !param)
+            return;
+        if (isLocalChangeRef.current)
+            return;
+        const raw = inForm && formValue !== undefined
+            ? formValue
+            : bridge.params.getSnapshot(param);
+        // Do not reset to defaultValue on transient null/undefined — would wipe
+        // the user's local selection during share-mode filtering or fast clicks.
+        if (raw === undefined || raw === null)
+            return;
+        const processed = preprocessor(raw);
+        if (processed !== valueRef.current && validator(processed)) {
+            setValueState(processed);
+            logPreview("Received", raw);
+        }
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [bridge, param, enabled, inForm, formValue, preprocessor, validator]);
+    // Subscribe to bridge canvas updates so changes from other nodes flow in.
+    useEffect(() => {
+        if (!enabled || !param)
+            return;
+        const unsub = bridge.params.subscribe(param, () => {
+            if (isLocalChangeRef.current)
+                return;
+            const raw = bridge.params.getSnapshot(param);
+            if (raw === undefined || raw === null)
+                return;
+            const processed = preprocessor(raw);
+            if (processed !== valueRef.current && validator(processed)) {
+                setValueState(processed);
+                logPreview("Received", raw);
+            }
+        });
+        return unsub;
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [bridge, param, enabled, preprocessor, validator]);
+    // ── Broadcast plumbing ──────────────────────────────────────────────────
+    const broadcast = useCallback((newValue) => {
+        if (!enabled || !param)
+            return;
+        bridge.params.set(param, newValue, ParameterMessageType.PARAM);
+        bridge.edges.stopLoading();
+        logPreview("Broadcast", newValue);
+    }, 
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [bridge, enabled, param]);
+    const broadcastNow = useCallback(() => {
+        if (!enabled || readOnly)
+            return;
+        if (debounceRef.current) {
+            clearTimeout(debounceRef.current);
+            debounceRef.current = null;
+        }
+        bridge.edges.startLoading();
+        broadcast(valueRef.current);
+        isLocalChangeRef.current = false;
+    }, [bridge, broadcast, enabled, readOnly]);
+    const clearValue = useCallback((newValue) => {
+        if (debounceRef.current) {
+            clearTimeout(debounceRef.current);
+            debounceRef.current = null;
+        }
+        setValueState(newValue);
+        valueRef.current = newValue;
+        isLocalChangeRef.current = false;
+        if (!enabled || !param || readOnly)
+            return;
+        bridge.params.clear(param);
+        bridge.edges.stopLoading();
+        logPreview("Cleared", null);
+    }, 
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [bridge, enabled, param, readOnly]);
+    // Reset one-time mount broadcast guard when binding changes.
+    useEffect(() => {
+        didBroadcastOnMountRef.current = false;
+    }, [param, enabled]);
+    // Broadcast default value on mount when no canvas value exists.
+    useEffect(() => {
+        if (!enabled || !param || readOnly)
+            return;
+        if (!broadcastDefaultValue)
+            return;
+        if (didBroadcastOnMountRef.current)
+            return;
+        const canvasValue = bridge.params.getSnapshot(param);
+        if (canvasValue !== undefined && canvasValue !== null) {
+            didBroadcastOnMountRef.current = true;
+            return;
+        }
+        // Empty-string defaults are noisy — skip.
+        if (valueRef.current === "") {
+            didBroadcastOnMountRef.current = true;
+            return;
+        }
+        broadcast(valueRef.current);
+        didBroadcastOnMountRef.current = true;
+    }, [bridge, enabled, param, readOnly, broadcastDefaultValue, broadcast]);
+    const setValue = useCallback((newValue) => {
+        setValueState(newValue);
+        if (!enabled || readOnly)
+            return;
+        isLocalChangeRef.current = true;
+        bridge.edges.startLoading();
+        if (debounceRef.current)
+            clearTimeout(debounceRef.current);
+        debounceRef.current = setTimeout(() => {
+            broadcast(newValue);
+            isLocalChangeRef.current = false;
+        }, debounceMs);
+    }, [bridge, broadcast, debounceMs, enabled, readOnly]);
+    // Cleanup: cancel pending debounce, and clear the bound param so preset
+    // type-swaps don't leave stale canvas state behind. Deps are `[]` so this
+    // runs on unmount only — never on bridge identity flips. bridge is read
+    // from the ref at cleanup time.
+    useEffect(() => {
+        return () => {
+            if (debounceRef.current)
+                clearTimeout(debounceRef.current);
+            const { enabled, param } = latestBindingRef.current;
+            if (!enabled || !param)
+                return;
+            bridgeRef.current.params.clear(param);
+        };
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, []);
+    return { value, setValue, broadcastNow, clearValue };
+}
+// ============================================================================
+// Default validator + preprocessor
+// ============================================================================
+function createDefaultValidator(defaultValue) {
+    if (typeof defaultValue === "string") {
+        return ((v) => typeof v === "string");
+    }
+    if (typeof defaultValue === "number") {
+        return ((v) => typeof v === "number");
+    }
+    if (typeof defaultValue === "boolean") {
+        return ((v) => typeof v === "boolean");
+    }
+    if (Array.isArray(defaultValue)) {
+        return ((v) => Array.isArray(v));
+    }
+    if (defaultValue !== null && typeof defaultValue === "object") {
+        return ((v) => v !== null && typeof v === "object" && !Array.isArray(v));
+    }
+    return ((_v) => true);
+}
+/**
+ * Coerces raw canvas values to T before validation. For string T this
+ * prevents the strict type guard from silently dropping numbers/booleans/
+ * arrays/objects that arrive as the param value. For other types, passthrough.
+ */
+function createDefaultPreprocessor(defaultValue) {
+    if (typeof defaultValue === "string") {
+        return (v) => {
+            if (typeof v === "string")
+                return v;
+            if (Array.isArray(v))
+                return v.join(",");
+            if (v !== null && typeof v === "object")
+                return JSON.stringify(v);
+            return String(v);
+        };
+    }
+    return (v) => v;
+}

package/dist/hooks/use-json-ui-edge-animation.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Controls the edge-animation pellet for the current canvas node.
+ *
+ * Call `startLoading()` when beginning async work and `stopLoading()` on
+ * completion — the `true → false` transition is what fires the visual
+ * pellet on connected outgoing canvas edges.
+ *
+ * `useFusedParam` calls these automatically around each broadcast, so use
+ * this hook only when you need to animate edges for non-param async work
+ * (e.g. a `fetch()` your component runs directly).
+ *
+ * @example
+ * const { startLoading, stopLoading } = useJsonUiEdgeAnimation();
+ * async function fetchData() {
+ *   startLoading();
+ *   try { await heavyCompute(); } finally { stopLoading(); }
+ * }
+ */
+export declare function useJsonUiEdgeAnimation(): {
+    startLoading: () => void;
+    stopLoading: () => void;
+};

package/dist/hooks/use-json-ui-edge-animation.js

@@ -0,0 +1,26 @@
+import { useFusedWidgetBridge } from "../bridge";
+/**
+ * Controls the edge-animation pellet for the current canvas node.
+ *
+ * Call `startLoading()` when beginning async work and `stopLoading()` on
+ * completion — the `true → false` transition is what fires the visual
+ * pellet on connected outgoing canvas edges.
+ *
+ * `useFusedParam` calls these automatically around each broadcast, so use
+ * this hook only when you need to animate edges for non-param async work
+ * (e.g. a `fetch()` your component runs directly).
+ *
+ * @example
+ * const { startLoading, stopLoading } = useJsonUiEdgeAnimation();
+ * async function fetchData() {
+ *   startLoading();
+ *   try { await heavyCompute(); } finally { stopLoading(); }
+ * }
+ */
+export function useJsonUiEdgeAnimation() {
+    const bridge = useFusedWidgetBridge();
+    return {
+        startLoading: bridge.edges.startLoading,
+        stopLoading: bridge.edges.stopLoading,
+    };
+}

package/dist/hooks/use-json-ui-log.d.ts

@@ -0,0 +1,33 @@
+import { type JsonUiLogLevel, type LogEntry } from "../bridge";
+/**
+ * Logging hook for json-ui components. Entries appear in the workbench's
+ * runtime logs panel for the current node.
+ *
+ * Entries are automatically tagged with the current widget's `configHash`
+ * (resolved through `JsonUiNodeOverrideContext` so nested
+ * `JsonUiConfigHashOverride` subtrees emit correctly-scoped entries),
+ * which lets the workbench discard stale entries when a widget's JSON is
+ * edited.
+ *
+ * @example
+ * const { log } = useJsonUiLog();
+ * log("Selected city: " + city);
+ * log("Failed to load chart data", "error");
+ */
+export declare function useJsonUiLog(): {
+    log: (message: string, level?: JsonUiLogLevel) => void;
+};
+/**
+ * Read-only hook returning the current log entries for a given node.
+ * Returns an empty array if `nodeId` is undefined or the node has no logs.
+ *
+ * Primarily used by the workbench's runtime logs panel — catalog components
+ * rarely need to read logs they wrote, but the hook is exposed for
+ * completeness (e.g. building a debug view component).
+ */
+export declare function useJsonUiLogs(nodeId: string | undefined): readonly LogEntry[];
+/**
+ * Returns a stable callback that clears all log entries for the given node.
+ * Returns a no-op function when `nodeId` is undefined.
+ */
+export declare function useJsonUiLogClear(nodeId: string | undefined): () => void;

package/dist/hooks/use-json-ui-log.js

@@ -0,0 +1,74 @@
+import { useCallback, useMemo, useRef, useSyncExternalStore } from "react";
+import { useFusedWidgetBridge, useJsonUiNode, } from "../bridge";
+const EMPTY_LOGS = Object.freeze([]);
+/**
+ * Logging hook for json-ui components. Entries appear in the workbench's
+ * runtime logs panel for the current node.
+ *
+ * Entries are automatically tagged with the current widget's `configHash`
+ * (resolved through `JsonUiNodeOverrideContext` so nested
+ * `JsonUiConfigHashOverride` subtrees emit correctly-scoped entries),
+ * which lets the workbench discard stale entries when a widget's JSON is
+ * edited.
+ *
+ * @example
+ * const { log } = useJsonUiLog();
+ * log("Selected city: " + city);
+ * log("Failed to load chart data", "error");
+ */
+export function useJsonUiLog() {
+    const bridge = useFusedWidgetBridge();
+    const { configHash } = useJsonUiNode();
+    // bridge and configHash are read from refs so the returned `log` callback
+    // identity is stable across re-renders. Downstream effects with `log` in
+    // their deps (e.g. use-duckdb-sql.ts's preprocessing effect) would
+    // otherwise re-fire on every bridge flip / configHash change and cascade
+    // setState across every SQL widget in the dashboard.
+    const bridgeRef = useRef(bridge);
+    bridgeRef.current = bridge;
+    const configHashRef = useRef(configHash);
+    configHashRef.current = configHash;
+    const log = useCallback((message, level = "info") => {
+        bridgeRef.current.log.log(message, level, configHashRef.current);
+    }, []);
+    return useMemo(() => ({ log }), [log]);
+}
+/**
+ * Read-only hook returning the current log entries for a given node.
+ * Returns an empty array if `nodeId` is undefined or the node has no logs.
+ *
+ * Primarily used by the workbench's runtime logs panel — catalog components
+ * rarely need to read logs they wrote, but the hook is exposed for
+ * completeness (e.g. building a debug view component).
+ */
+export function useJsonUiLogs(nodeId) {
+    const bridge = useFusedWidgetBridge();
+    const subscribe = useCallback((cb) => {
+        if (!nodeId)
+            return () => { };
+        return bridge.log.subscribeLogs(nodeId, cb);
+    }, [bridge, nodeId]);
+    const snapshotRef = useRef(EMPTY_LOGS);
+    const getSnapshot = useCallback(() => {
+        if (!nodeId)
+            return EMPTY_LOGS;
+        const next = bridge.log.getLogsSnapshot(nodeId);
+        if (next === snapshotRef.current)
+            return snapshotRef.current;
+        snapshotRef.current = next;
+        return next;
+    }, [bridge, nodeId]);
+    return useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+}
+/**
+ * Returns a stable callback that clears all log entries for the given node.
+ * Returns a no-op function when `nodeId` is undefined.
+ */
+export function useJsonUiLogClear(nodeId) {
+    const bridge = useFusedWidgetBridge();
+    return useCallback(() => {
+        if (!nodeId)
+            return;
+        bridge.log.clearLogs(nodeId);
+    }, [bridge, nodeId]);
+}

package/dist/hooks/use-json-ui-udf-info.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Returns the identity of the current canvas node.
+ *
+ * `udfUniqueId` and `udfName` are used internally by `useFusedParam` for
+ * edge-based param routing. Catalog components rarely need to read these
+ * directly — they're surfaced primarily so logs and debugging can be
+ * scoped to a node.
+ *
+ * Reads from `JsonUiNodeOverrideContext` first (so nested
+ * `JsonUiConfigHashOverride` subtrees see their override), falling back to
+ * the bridge's node identity.
+ *
+ * Returns `{ udfUniqueId: undefined, udfName: undefined, configHash: undefined }`
+ * when the surrounding bridge has not populated them.
+ *
+ * @example
+ * const { udfName } = useJsonUiUdfInfo();
+ * console.log("I am node:", udfName);
+ */
+export declare function useJsonUiUdfInfo(): {
+    udfUniqueId: string | undefined;
+    udfName: string | undefined;
+    configHash: string | undefined;
+};

package/dist/hooks/use-json-ui-udf-info.js

@@ -0,0 +1,23 @@
+import { useJsonUiNode } from "../bridge";
+/**
+ * Returns the identity of the current canvas node.
+ *
+ * `udfUniqueId` and `udfName` are used internally by `useFusedParam` for
+ * edge-based param routing. Catalog components rarely need to read these
+ * directly — they're surfaced primarily so logs and debugging can be
+ * scoped to a node.
+ *
+ * Reads from `JsonUiNodeOverrideContext` first (so nested
+ * `JsonUiConfigHashOverride` subtrees see their override), falling back to
+ * the bridge's node identity.
+ *
+ * Returns `{ udfUniqueId: undefined, udfName: undefined, configHash: undefined }`
+ * when the surrounding bridge has not populated them.
+ *
+ * @example
+ * const { udfName } = useJsonUiUdfInfo();
+ * console.log("I am node:", udfName);
+ */
+export function useJsonUiUdfInfo() {
+    return useJsonUiNode();
+}

package/dist/hooks/use-param-substitution.d.ts

@@ -0,0 +1,22 @@
+import type { ParamSubstitutionOptions, ParamSubstitutionResult } from "../types";
+/**
+ * Reactively resolve `$param_name` and `{{udf_name}}` placeholders.
+ *
+ * - `$param_name` is substituted from canvas params (edge-filtered) and
+ *   form-scoped values when inside a form.
+ * - `{{udf_name}}` (and variants like `{{udf_name.col}}`, `{{udf_name?k=v}}`,
+ *   HTML template node refs) is resolved by the host via the template bridge.
+ *
+ * Returns `{ value, loading }`. `loading` is `true` only while `{{udf}}`
+ * data is being fetched; pure `$param` templates never trigger loading.
+ *
+ * @example — dynamic label
+ * const { value } = useParamSubstitution("Selected region: $region");
+ *
+ * @example — SQL fragment with missing-param preservation
+ * const { value: where } = useParamSubstitution(
+ *   "WHERE city = '$city'",
+ *   { preserveMissingParams: true }
+ * );
+ */
+export declare function useParamSubstitution(template: string | undefined, options?: ParamSubstitutionOptions): ParamSubstitutionResult;