@fusedio/widget-sdk 0.1.0

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

@@ -0,0 +1,207 @@
+/**
+ * Reactively resolve `$param` and `{{udf}}` placeholders in a template.
+ *
+ * Pure-`$param` templates are handled in-SDK with a simple regex
+ * substitution. Templates that reference `{{udf}}` (potentially with
+ * `?overrides`, column/index access, or HTML template node recursion)
+ * delegate to `bridge.template.render` so the host can use its rich UDF
+ * machinery. The SDK orchestrates state, cancellation, and re-runs.
+ */
+import { useEffect, useMemo, useRef, useState, useSyncExternalStore, useCallback, } from "react";
+import { useFusedWidgetBridge } from "../bridge";
+import { useFormParams } from "../form";
+import { useCanvasParams } from "./use-canvas-params";
+const PARAM_TOKEN_RE = /\$([a-zA-Z_][a-zA-Z0-9_]*)/g;
+const UDF_PLACEHOLDER_RE = /\{\{[\s\S]*?\}\}/;
+// Mirrors `parseInlineUdfPlaceholders` for the purpose of finding which UDF
+// names a template references. We only need the leading identifier — full
+// access-path / override parsing is the host's concern.
+const UDF_NAME_EXTRACT_RE = /\{\{\s*([A-Za-z_][A-Za-z0-9_]*)\b/g;
+/**
+ * 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 function useParamSubstitution(template, options = {}) {
+    const safeTemplate = template ?? "";
+    const preserveMissingParams = options.preserveMissingParams ?? false;
+    const bridge = useFusedWidgetBridge();
+    const paramNames = useMemo(() => extractParamNames(safeTemplate), [safeTemplate]);
+    const canvasValues = useCanvasParams(paramNames);
+    const { inForm, values: formValues } = useFormParams(paramNames);
+    const paramValues = useMemo(() => (inForm ? { ...canvasValues, ...formValues } : canvasValues), [canvasValues, formValues, inForm]);
+    const hasUdfRefs = useMemo(() => UDF_PLACEHOLDER_RE.test(safeTemplate), [safeTemplate]);
+    // ── Fast path: no UDF refs ─────────────────────────────────────────────
+    const pureParamValue = useMemo(() => {
+        if (hasUdfRefs)
+            return "";
+        return substituteParams(safeTemplate, paramValues, preserveMissingParams);
+    }, [safeTemplate, paramValues, preserveMissingParams, hasUdfRefs]);
+    // ── Slow path: UDF refs ────────────────────────────────────────────────
+    // Extract referenced UDF names so we can subscribe to their outputs.
+    // When any of them re-executes we bump a tick and the effect below
+    // re-runs `bridge.template.render` with fresh data.
+    const referencedUdfNames = useMemo(() => {
+        if (!hasUdfRefs)
+            return [];
+        const seen = new Set();
+        const out = [];
+        UDF_NAME_EXTRACT_RE.lastIndex = 0;
+        let m;
+        while ((m = UDF_NAME_EXTRACT_RE.exec(safeTemplate)) !== null) {
+            if (!seen.has(m[1])) {
+                seen.add(m[1]);
+                out.push(m[1]);
+            }
+        }
+        return out;
+    }, [safeTemplate, hasUdfRefs]);
+    // Subscribe to host re-render triggers (UDF outputs + topology) so that
+    // the async render re-runs when an upstream UDF re-executes or edges shift.
+    const templateChangeKey = useTemplateBridgeChangeKey(bridge, referencedUdfNames);
+    const [resolved, setResolved] = useState(() => ({ key: "", value: "" }));
+    const [loading, setLoading] = useState(false);
+    // Render key includes template + paramValues + the host change ticker.
+    const renderKey = useMemo(() => {
+        return JSON.stringify({
+            template: safeTemplate,
+            paramValues,
+            preserveMissingParams,
+            tick: templateChangeKey,
+        });
+    }, [safeTemplate, paramValues, preserveMissingParams, templateChangeKey]);
+    useEffect(() => {
+        if (!hasUdfRefs) {
+            setLoading(false);
+            return;
+        }
+        let cancelled = false;
+        const controller = new AbortController();
+        setLoading(true);
+        bridge.template
+            .render(safeTemplate, paramValues, {
+            preserveMissingParams,
+            signal: controller.signal,
+        })
+            .then((result) => {
+            if (cancelled)
+                return;
+            setResolved((prev) => prev.key === renderKey && prev.value === result.value
+                ? prev
+                : { key: renderKey, value: result.value });
+            setLoading(result.loading);
+        }, (err) => {
+            if (cancelled)
+                return;
+            if (err?.name === "AbortError")
+                return;
+            setLoading(false);
+        });
+        return () => {
+            cancelled = true;
+            controller.abort();
+        };
+    }, [
+        bridge,
+        hasUdfRefs,
+        safeTemplate,
+        paramValues,
+        preserveMissingParams,
+        renderKey,
+    ]);
+    const value = useMemo(() => {
+        if (!hasUdfRefs)
+            return pureParamValue;
+        if (resolved.key === renderKey)
+            return resolved.value;
+        // Loading placeholder: ask host for best-effort sync render.
+        try {
+            return bridge.template.renderLoading(safeTemplate, paramValues, {
+                preserveMissingParams,
+            });
+        }
+        catch {
+            return safeTemplate;
+        }
+    }, [
+        bridge,
+        hasUdfRefs,
+        pureParamValue,
+        resolved,
+        renderKey,
+        safeTemplate,
+        paramValues,
+        preserveMissingParams,
+    ]);
+    return { value, loading: hasUdfRefs ? loading : false };
+}
+function extractParamNames(template) {
+    const names = [];
+    const seen = new Set();
+    for (const match of template.matchAll(PARAM_TOKEN_RE)) {
+        const name = match[1];
+        if (!seen.has(name)) {
+            seen.add(name);
+            names.push(name);
+        }
+    }
+    return names;
+}
+function substituteParams(template, values, preserveMissingParams) {
+    return template.replace(PARAM_TOKEN_RE, (match, name) => {
+        const v = values[name];
+        if (v === undefined || v === null) {
+            return preserveMissingParams ? match : "";
+        }
+        return stringifyParamValue(v);
+    });
+}
+function stringifyParamValue(value) {
+    if (value === undefined || value === null)
+        return "";
+    if (typeof value === "string")
+        return value;
+    if (typeof value === "number" || typeof value === "boolean")
+        return String(value);
+    const serialized = JSON.stringify(value);
+    return serialized ?? "";
+}
+/**
+ * Subscribe to the template bridge's change signal + every referenced UDF's
+ * output via `bridge.udfs.subscribeOutput`. The returned numeric key
+ * changes whenever a re-render could produce a different result.
+ */
+function useTemplateBridgeChangeKey(bridge, referencedUdfNames) {
+    const tickRef = useRef(0);
+    const namesKey = referencedUdfNames.slice().sort().join("|");
+    const subscribe = useCallback((cb) => {
+        const fire = () => {
+            tickRef.current += 1;
+            cb();
+        };
+        const unsubs = [bridge.template.subscribe(fire)];
+        for (const name of referencedUdfNames) {
+            unsubs.push(bridge.udfs.subscribeOutput(name, fire));
+        }
+        return () => unsubs.forEach((u) => u());
+    }, 
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [bridge, namesKey]);
+    const getSnapshot = useCallback(() => tickRef.current, []);
+    return useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+}

package/dist/hooks/use-udf-output.d.ts

@@ -0,0 +1,85 @@
+import { type UdfOutputSnapshot } from "../bridge";
+/**
+ * Subscribe to a UDF's output by name. Returns the current `UdfOutputSnapshot`
+ * (data + execution status + optional error + VFS filename) or `undefined`
+ * if the UDF is not present in the canvas.
+ *
+ * Re-renders when the UDF's results change (after re-execution) or when its
+ * execution status flips.
+ *
+ * @example
+ * const out = useUdfOutputByName("cities_udf");
+ * if (!out) return <div>UDF not found</div>;
+ * if (out.isExecutionInProgress) return <div>Loading…</div>;
+ * if (out.error) return <div>Error: {out.error}</div>;
+ */
+export declare function useUdfOutputByName(udfName: string | undefined): UdfOutputSnapshot | undefined;
+/**
+ * Request the workbench to re-execute a named UDF (e.g. after the user
+ * clicks a "Refresh" button). No-op in test harnesses without re-execution.
+ */
+export declare function useRequestUdfReexecute(): (udfName: string) => void;
+export type ParsedUdfQuery = {
+    udfName: string;
+    columnName: string;
+    index?: number;
+} | null;
+/**
+ * Fast check whether a string is `{{udf.col}}` or `{{udf.col[idx]}}`.
+ *
+ * @example
+ * isUdfQuery("{{my_udf.city}}")    // true
+ * isUdfQuery("{{my_udf.city[0]}}") // true
+ * isUdfQuery("not a query")        // false
+ */
+export declare function isUdfQuery(query?: string): boolean;
+/**
+ * Parse a UDF column query string. Returns `null` for unrecognised input.
+ *
+ * @example
+ * parseUdfColumnQuery("{{my_udf.city}}")    // { udfName: "my_udf", columnName: "city" }
+ * parseUdfColumnQuery("{{my_udf.city[0]}}") // { ..., index: 0 }
+ */
+export declare function parseUdfColumnQuery(query?: string): ParsedUdfQuery;
+export interface UseUdfDataFrameSampleOptions {
+    udfName?: string;
+    sampleSize?: number;
+}
+export interface UseUdfDataFrameSampleResult {
+    loading: boolean;
+    errorMessage: string | null;
+    isError: boolean;
+    columns: string[];
+    rows: Record<string, unknown>[];
+    requestReexecute: () => void;
+}
+/**
+ * Pull a small sample of rows from a UDF's DataFrame output and derive
+ * column names. Used by dropdowns and galleries that populate options
+ * from UDF data.
+ */
+export declare function useUdfDataFrameSample({ udfName, sampleSize, }: UseUdfDataFrameSampleOptions): UseUdfDataFrameSampleResult;
+export interface UseUdfColumnValuesResult {
+    values: unknown[];
+    loading: boolean;
+}
+/**
+ * Read all values from a UDF column using `{{udf.col}}` query syntax.
+ *
+ * @example
+ * const { values, loading } = useUdfColumnValues("{{my_udf.city}}");
+ * // values = ["NYC", "LA", "SF", ...]
+ */
+export declare function useUdfColumnValues(query?: string, sampleSize?: number): UseUdfColumnValuesResult;
+export interface UseUdfColumnValueResult {
+    value: unknown | null;
+    loading: boolean;
+}
+/**
+ * Read a single value from a UDF column at a specific index.
+ *
+ * @example
+ * const { value, loading } = useUdfColumnValue("{{my_udf.city[0]}}");
+ * // value = "NYC"
+ */
+export declare function useUdfColumnValue(query?: string, sampleSize?: number): UseUdfColumnValueResult;

package/dist/hooks/use-udf-output.js

@@ -0,0 +1,202 @@
+import { useCallback, useEffect, useMemo, useRef, useState, useSyncExternalStore, } from "react";
+import { useFusedWidgetBridge } from "../bridge";
+/**
+ * Subscribe to a UDF's output by name. Returns the current `UdfOutputSnapshot`
+ * (data + execution status + optional error + VFS filename) or `undefined`
+ * if the UDF is not present in the canvas.
+ *
+ * Re-renders when the UDF's results change (after re-execution) or when its
+ * execution status flips.
+ *
+ * @example
+ * const out = useUdfOutputByName("cities_udf");
+ * if (!out) return <div>UDF not found</div>;
+ * if (out.isExecutionInProgress) return <div>Loading…</div>;
+ * if (out.error) return <div>Error: {out.error}</div>;
+ */
+export function useUdfOutputByName(udfName) {
+    const bridge = useFusedWidgetBridge();
+    const subscribe = useCallback((cb) => {
+        if (!udfName)
+            return () => { };
+        return bridge.udfs.subscribeOutput(udfName, cb);
+    }, [bridge, udfName]);
+    const snapshotRef = useRef(undefined);
+    const getSnapshot = useCallback(() => {
+        if (!udfName)
+            return undefined;
+        const next = bridge.udfs.getOutputSnapshot(udfName);
+        const prev = snapshotRef.current;
+        if (snapshotsEqual(prev, next))
+            return prev;
+        snapshotRef.current = next;
+        return next;
+    }, [bridge, udfName]);
+    return useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+}
+/**
+ * Request the workbench to re-execute a named UDF (e.g. after the user
+ * clicks a "Refresh" button). No-op in test harnesses without re-execution.
+ */
+export function useRequestUdfReexecute() {
+    const bridge = useFusedWidgetBridge();
+    return useCallback((udfName) => bridge.udfs.requestReexecute(udfName), [bridge]);
+}
+function snapshotsEqual(a, b) {
+    if (a === b)
+        return true;
+    if (!a || !b)
+        return false;
+    return (a.data === b.data &&
+        a.isExecutionInProgress === b.isExecutionInProgress &&
+        a.error === b.error &&
+        a.vfsFilename === b.vfsFilename);
+}
+// ============================================================================
+// UDF column query convenience hooks
+// ============================================================================
+const UDF_QUERY_REGEX = /^\{\{(\w+)\.(\w+)(?:\[(\d+)\])?\}\}$/;
+/**
+ * Fast check whether a string is `{{udf.col}}` or `{{udf.col[idx]}}`.
+ *
+ * @example
+ * isUdfQuery("{{my_udf.city}}")    // true
+ * isUdfQuery("{{my_udf.city[0]}}") // true
+ * isUdfQuery("not a query")        // false
+ */
+export function isUdfQuery(query) {
+    if (!query || typeof query !== "string")
+        return false;
+    return UDF_QUERY_REGEX.test(query);
+}
+/**
+ * Parse a UDF column query string. Returns `null` for unrecognised input.
+ *
+ * @example
+ * parseUdfColumnQuery("{{my_udf.city}}")    // { udfName: "my_udf", columnName: "city" }
+ * parseUdfColumnQuery("{{my_udf.city[0]}}") // { ..., index: 0 }
+ */
+export function parseUdfColumnQuery(query) {
+    if (!isUdfQuery(query))
+        return null;
+    const match = query.match(UDF_QUERY_REGEX);
+    if (!match)
+        return null;
+    const [, udfName, columnName, indexStr] = match;
+    const index = indexStr !== undefined ? parseInt(indexStr, 10) : undefined;
+    return { udfName, columnName, index };
+}
+function isDataSourceLike(value) {
+    return (!!value &&
+        typeof value === "object" &&
+        typeof value.getRows === "function");
+}
+/**
+ * Pull a small sample of rows from a UDF's DataFrame output and derive
+ * column names. Used by dropdowns and galleries that populate options
+ * from UDF data.
+ */
+export function useUdfDataFrameSample({ udfName, sampleSize = 200, }) {
+    const snapshot = useUdfOutputByName(udfName);
+    const reexecute = useRequestUdfReexecute();
+    const [rows, setRows] = useState([]);
+    const [columns, setColumns] = useState([]);
+    useEffect(() => {
+        let cancelled = false;
+        const data = snapshot?.data;
+        if (!data || !isDataSourceLike(data)) {
+            setRows([]);
+            setColumns([]);
+            return;
+        }
+        (async () => {
+            try {
+                const rawRows = await data.getRows(0, Math.max(0, sampleSize));
+                if (cancelled)
+                    return;
+                const normalized = rawRows.map((r) => {
+                    const obj = r;
+                    if (obj &&
+                        typeof obj === "object" &&
+                        obj.properties &&
+                        typeof obj.properties === "object") {
+                        return obj.properties;
+                    }
+                    return r;
+                });
+                setRows(normalized);
+                const cols = Array.from(new Set(normalized.flatMap((r) => Object.keys(r ?? {}))));
+                setColumns(cols);
+            }
+            catch {
+                if (cancelled)
+                    return;
+                setRows([]);
+                setColumns([]);
+            }
+        })();
+        return () => {
+            cancelled = true;
+        };
+    }, [snapshot?.data, sampleSize]);
+    const requestReexecute = useCallback(() => {
+        if (udfName)
+            reexecute(udfName);
+    }, [reexecute, udfName]);
+    return {
+        loading: snapshot?.isExecutionInProgress ?? false,
+        errorMessage: snapshot?.error ?? null,
+        isError: Boolean(snapshot?.error),
+        columns,
+        rows,
+        requestReexecute,
+    };
+}
+/**
+ * Read all values from a UDF column using `{{udf.col}}` query syntax.
+ *
+ * @example
+ * const { values, loading } = useUdfColumnValues("{{my_udf.city}}");
+ * // values = ["NYC", "LA", "SF", ...]
+ */
+export function useUdfColumnValues(query, sampleSize = 200) {
+    const isValid = isUdfQuery(query);
+    const parsed = useMemo(() => (isValid ? parseUdfColumnQuery(query) : null), [isValid, query]);
+    const { rows, loading } = useUdfDataFrameSample({
+        udfName: parsed?.udfName,
+        sampleSize,
+    });
+    const values = useMemo(() => {
+        if (!parsed || !parsed.columnName)
+            return [];
+        return rows
+            .map((row) => row?.[parsed.columnName])
+            .filter((v) => v !== undefined && v !== null);
+    }, [rows, parsed]);
+    return { values, loading: isValid ? loading : false };
+}
+/**
+ * Read a single value from a UDF column at a specific index.
+ *
+ * @example
+ * const { value, loading } = useUdfColumnValue("{{my_udf.city[0]}}");
+ * // value = "NYC"
+ */
+export function useUdfColumnValue(query, sampleSize = 200) {
+    const isValid = isUdfQuery(query);
+    const parsed = useMemo(() => (isValid ? parseUdfColumnQuery(query) : null), [isValid, query]);
+    const { rows, loading } = useUdfDataFrameSample({
+        udfName: parsed?.udfName,
+        sampleSize,
+    });
+    const value = useMemo(() => {
+        if (!parsed || !parsed.columnName || parsed.index === undefined)
+            return null;
+        const row = rows[parsed.index];
+        if (!row)
+            return null;
+        const v = row[parsed.columnName];
+        return v !== undefined ? v : null;
+    }, [rows, parsed]);
+    return { value, loading: isValid ? loading : false };
+}

package/dist/hooks/use-upload-access-check.d.ts

@@ -0,0 +1,19 @@
+export type UploadAccessState = {
+    status: "idle";
+} | {
+    status: "checking";
+} | {
+    status: "allowed";
+} | {
+    status: "denied";
+    message: string;
+};
+/**
+ * Check whether the current user has write access to a destination path
+ * (S3, GCS, etc.). Used by the `file-upload` widget to surface a clear
+ * error before the user attempts to upload.
+ *
+ * Returns a state machine value `{ status: "idle" | "checking" | "allowed" |
+ * "denied" }` that you can branch on directly in render.
+ */
+export declare function useUploadAccessCheck(destinationPath: string | undefined, enabled: boolean): UploadAccessState;

package/dist/hooks/use-upload-access-check.js

@@ -0,0 +1,39 @@
+import { useEffect, useState } from "react";
+import { useFusedWidgetBridge } from "../bridge";
+/**
+ * Check whether the current user has write access to a destination path
+ * (S3, GCS, etc.). Used by the `file-upload` widget to surface a clear
+ * error before the user attempts to upload.
+ *
+ * Returns a state machine value `{ status: "idle" | "checking" | "allowed" |
+ * "denied" }` that you can branch on directly in render.
+ */
+export function useUploadAccessCheck(destinationPath, enabled) {
+    const bridge = useFusedWidgetBridge();
+    const [state, setState] = useState({ status: "idle" });
+    useEffect(() => {
+        if (!enabled || !destinationPath?.trim()) {
+            setState({ status: "idle" });
+            return;
+        }
+        let cancelled = false;
+        setState({ status: "checking" });
+        bridge.uploads.checkAccess(destinationPath).then((result) => {
+            if (cancelled)
+                return;
+            if (result.ok) {
+                setState({ status: "allowed" });
+            }
+            else {
+                setState({
+                    status: "denied",
+                    message: result.message ?? "Upload access denied.",
+                });
+            }
+        });
+        return () => {
+            cancelled = true;
+        };
+    }, [bridge, destinationPath, enabled]);
+    return state;
+}

package/dist/hooks/use-url-signing.d.ts

@@ -0,0 +1,42 @@
+import { type SignUrlResult } from "../bridge";
+/** URL schemes that require signing before fetch. */
+export declare const SIGNED_URL_SCHEMES: readonly ["s3://", "gs://", "fd://"];
+/**
+ * Manual URL signing — returns a stable `signUrl` callback you can call
+ * with any URL. Useful when your component needs to sign URLs imperatively
+ * (e.g. on user click). For reactive media src resolution, use `useMediaSrc`.
+ *
+ * @example
+ * const { signUrl } = useUrlSigning();
+ * const handleDownload = async () => {
+ *   const { signed } = await signUrl("s3://my-bucket/file.csv");
+ *   window.location.href = signed;
+ * };
+ */
+export declare function useUrlSigning(): {
+    signUrl: (url: string) => Promise<SignUrlResult>;
+};
+export interface UseMediaSrcResult {
+    /** The resolved `src` URL (signed if needed, with `$param`s substituted). */
+    src: string | null;
+    /** True while substitution or signing is in flight. */
+    loading: boolean;
+    error: string | null;
+    /** Re-sign — call to refresh an expired URL. */
+    refreshSignedUrl: () => Promise<string | null>;
+    /** The substituted source URL prior to signing (useful for diagnostics). */
+    resolvedSrc: string;
+    /** True if the resolved URL requires signing. */
+    needsSigning: boolean;
+}
+/**
+ * Reactively resolve a media `src` URL. Substitutes `$param` tokens first,
+ * then signs S3/GCS/FD URLs. Other URL schemes pass through unchanged.
+ *
+ * @example
+ * const { src, loading, error } = useMediaSrc(props.imageUrl);
+ * if (loading) return <Spinner />;
+ * if (error) return <div>Failed: {error}</div>;
+ * return <img src={src ?? ""} alt="" />;
+ */
+export declare function useMediaSrc(srcInput: string | undefined): UseMediaSrcResult;