@fusedio/widget-sdk 0.1.0

package/dist/define-component.d.ts

@@ -0,0 +1,93 @@
+import type * as React from "react";
+import type { z } from "zod";
+import type { ComponentRenderProps } from "./types";
+/**
+ * The shape a custom catalog registers per component type.
+ *
+ * Bundles default-export `{ "kebab-key": defineComponent({...}) }`. The
+ * workbench reads `component` into its rendering registry and reads
+ * `{ description, hasChildren, props }` into the **catalog schemas atom**
+ * so the AI surfaces (widget-builder, canvas main chat, auto-fix, inline
+ * edit) can see the type and the `get_json_ui_component_schemas` tool can
+ * resolve its propsSchema.
+ *
+ * The `props` Zod schema is constructed against the workbench's Zod
+ * instance at runtime: the catalog bundle marks `zod` as external, and the
+ * host's runtime import map resolves the bare `import { z } from "zod"`
+ * to its own already-loaded Zod. Your local devDependency on `zod` exists
+ * only so TypeScript can infer the prop type from the schema — no Zod
+ * code ships in your bundle.
+ *
+ * `props` must be a `z.ZodObject` (i.e. constructed with `z.object({...})`).
+ * The workbench's props linter calls `.strict().safeParse()` on it to
+ * validate widget JSON at the same fidelity as built-in components, and
+ * that method only exists on `ZodObject`. Bundles that pass `z.union`,
+ * `z.discriminatedUnion`, etc. are rejected at load time.
+ */
+export interface CatalogComponentDefinition<TProps extends Record<string, unknown> = Record<string, unknown>> {
+    /** React function component. Receives `{ element }` per the json-ui contract. */
+    component: React.ComponentType<ComponentRenderProps<TProps>>;
+    /**
+     * Zod schema for the component's props. Must be a `z.ZodObject` so the
+     * workbench's strict-mode linter can run; use `z.infer<typeof MySchema>`
+     * to derive the matching TS prop type and keep them in lockstep.
+     */
+    props: z.ZodObject<z.ZodRawShape>;
+    /**
+     * One-line description shown to the AI in the system prompt's custom-catalog
+     * section. The AI uses this to decide when your component is appropriate;
+     * keep it action-oriented (e.g. "A counter that writes a number to a param").
+     */
+    description?: string;
+    /**
+     * Whether this component accepts nested `children` in the json-ui tree.
+     * Defaults to `false` — most catalog components are leaves.
+     */
+    hasChildren?: boolean;
+}
+/**
+ * Typed helper for registering a catalog component.
+ *
+ * `TProps` is inferred from the React component's props only — never from
+ * the Zod schema — because Zod 4's type instantiation through
+ * `z.ZodType<T>` exceeds TypeScript's recursion budget for moderately
+ * complex schemas. The author writes `type Props = z.infer<typeof
+ * MySchema>` once and uses it on the component signature.
+ *
+ * Tradeoff: since `props` is typed as `z.ZodObject<z.ZodRawShape>` (not
+ * `z.ZodType<TProps>`), TypeScript will *not* catch drift between the
+ * Zod schema's shape and the component's `Props`. If you change one,
+ * change the other — the runtime linter and renderer will surface the
+ * mismatch, but the build won't.
+ *
+ * @example
+ * import { z } from "zod";
+ * import { defineComponent, useFusedParam, type ComponentRenderProps } from "@fusedio/widget-sdk";
+ *
+ * const CounterButtonProps = z.object({
+ *   param: z.string().describe("Canvas param key to read/write"),
+ *   label: z.string().optional().describe("Display label"),
+ *   step: z.number().optional().default(1),
+ * });
+ * type Props = z.infer<typeof CounterButtonProps>;
+ *
+ * function CounterButton({ element }: ComponentRenderProps<Props>) {
+ *   const { param, label = "Count", step = 1 } = element.props;
+ *   const { value, setValue } = useFusedParam({ param, defaultValue: 0 });
+ *   return <button onClick={() => setValue(value + step)}>{label}: {value}</button>;
+ * }
+ *
+ * export default {
+ *   "counter-button": defineComponent({
+ *     component: CounterButton,
+ *     props: CounterButtonProps,
+ *     description: "A counter with +/- buttons that writes a number to a param.",
+ *   }),
+ * };
+ */
+export declare function defineComponent<TProps extends Record<string, unknown>>(def: {
+    component: React.ComponentType<ComponentRenderProps<TProps>>;
+    props: z.ZodObject<z.ZodRawShape>;
+    description?: string;
+    hasChildren?: boolean;
+}): CatalogComponentDefinition<TProps>;

package/dist/define-component.js

@@ -0,0 +1,43 @@
+/**
+ * Typed helper for registering a catalog component.
+ *
+ * `TProps` is inferred from the React component's props only — never from
+ * the Zod schema — because Zod 4's type instantiation through
+ * `z.ZodType<T>` exceeds TypeScript's recursion budget for moderately
+ * complex schemas. The author writes `type Props = z.infer<typeof
+ * MySchema>` once and uses it on the component signature.
+ *
+ * Tradeoff: since `props` is typed as `z.ZodObject<z.ZodRawShape>` (not
+ * `z.ZodType<TProps>`), TypeScript will *not* catch drift between the
+ * Zod schema's shape and the component's `Props`. If you change one,
+ * change the other — the runtime linter and renderer will surface the
+ * mismatch, but the build won't.
+ *
+ * @example
+ * import { z } from "zod";
+ * import { defineComponent, useFusedParam, type ComponentRenderProps } from "@fusedio/widget-sdk";
+ *
+ * const CounterButtonProps = z.object({
+ *   param: z.string().describe("Canvas param key to read/write"),
+ *   label: z.string().optional().describe("Display label"),
+ *   step: z.number().optional().default(1),
+ * });
+ * type Props = z.infer<typeof CounterButtonProps>;
+ *
+ * function CounterButton({ element }: ComponentRenderProps<Props>) {
+ *   const { param, label = "Count", step = 1 } = element.props;
+ *   const { value, setValue } = useFusedParam({ param, defaultValue: 0 });
+ *   return <button onClick={() => setValue(value + step)}>{label}: {value}</button>;
+ * }
+ *
+ * export default {
+ *   "counter-button": defineComponent({
+ *     component: CounterButton,
+ *     props: CounterButtonProps,
+ *     description: "A counter with +/- buttons that writes a number to a param.",
+ *   }),
+ * };
+ */
+export function defineComponent(def) {
+    return def;
+}

package/dist/form.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Subscription-based store for form field values. Notifies only subscribers
+ * watching the changed key so that slider dragging doesn't re-render every
+ * sibling.
+ */
+export interface FormParamsStore {
+    /** Read the current value for a single field name. */
+    get: (name: string) => unknown;
+    /** Read a snapshot containing only the requested names. */
+    getSnapshot: (names: readonly string[]) => Record<string, unknown>;
+    /** Read all field values (used by form submit). */
+    getAll: () => Record<string, unknown>;
+    /** Set a field value; notifies subscribers watching this name. */
+    setField: (name: string, value: unknown) => void;
+    /** Remove a field; notifies subscribers watching this name. */
+    removeField: (name: string) => void;
+    /** Subscribe to changes on any of the given names. Returns an unsubscribe fn. */
+    subscribe: (names: readonly string[], cb: () => void) => () => void;
+}
+/** Create a fresh form params store. Called once per Form component instance. */
+export declare function createFormParamsStore(): FormParamsStore;
+export interface FormContextValue {
+    /** Store holding the current field values for this form, or null when outside any form. */
+    store: FormParamsStore | null;
+    /** True when this subtree is rendered inside a Form component. */
+    isInForm: boolean;
+}
+/**
+ * Provides form-scoped values to all descendants. Provided by the workbench's
+ * built-in Form component and by the catalog-template test harness.
+ */
+export declare const FormContext: import("react").Context<FormContextValue>;
+/** Read the form context — `{ store, isInForm }`. */
+export declare function useFormContext(): FormContextValue;
+/**
+ * Read live form-scoped values for the given param names.
+ *
+ * Returns `{ inForm: false, values: {} }` when used outside a form. Re-renders
+ * only when one of the watched names actually changes — not on every field
+ * update in the form.
+ *
+ * @example
+ * const { inForm, values } = useFormParams(["city", "country"]);
+ * if (inForm && values.city) console.log("city:", values.city);
+ */
+export declare function useFormParams(names: readonly string[]): {
+    inForm: boolean;
+    values: Record<string, unknown>;
+};

package/dist/form.js

@@ -0,0 +1,136 @@
+/**
+ * Form-scoped parameter context.
+ *
+ * Provides a subscription store that mirrors live values of form fields
+ * (slider, dropdown, text-input, …) so that sibling components inside the
+ * same form can react to those values without ever broadcasting them to
+ * the canvas. The submit action is the only event that leaks values out.
+ *
+ * Pure React — no Jotai, no workbench dependencies. The workbench's Form
+ * component and the catalog-template test harness both call
+ * `createFormParamsStore()` and provide it via `FormContext`.
+ */
+import { createContext, useCallback, useContext, useRef, useSyncExternalStore, } from "react";
+/** Create a fresh form params store. Called once per Form component instance. */
+export function createFormParamsStore() {
+    const values = new Map();
+    const subscribers = new Set();
+    const notify = (name) => {
+        subscribers.forEach((sub) => {
+            if (sub.names.has(name))
+                sub.cb();
+        });
+    };
+    return {
+        get(name) {
+            return values.get(name);
+        },
+        getSnapshot(names) {
+            const out = {};
+            for (const name of names) {
+                if (values.has(name))
+                    out[name] = values.get(name);
+            }
+            return out;
+        },
+        getAll() {
+            const out = {};
+            values.forEach((v, k) => {
+                out[k] = v;
+            });
+            return out;
+        },
+        setField(name, value) {
+            if (values.has(name) && Object.is(values.get(name), value))
+                return;
+            values.set(name, value);
+            notify(name);
+        },
+        removeField(name) {
+            if (!values.has(name))
+                return;
+            values.delete(name);
+            notify(name);
+        },
+        subscribe(names, cb) {
+            const sub = { names: new Set(names), cb };
+            subscribers.add(sub);
+            return () => {
+                subscribers.delete(sub);
+            };
+        },
+    };
+}
+/**
+ * Provides form-scoped values to all descendants. Provided by the workbench's
+ * built-in Form component and by the catalog-template test harness.
+ */
+export const FormContext = createContext({
+    store: null,
+    isInForm: false,
+});
+FormContext.displayName = "JsonUiFormContext";
+/** Read the form context — `{ store, isInForm }`. */
+export function useFormContext() {
+    return useContext(FormContext);
+}
+// ============================================================================
+// Hook: read form-scoped params
+// ============================================================================
+const EMPTY_PARAMS = Object.freeze({});
+/**
+ * Read live form-scoped values for the given param names.
+ *
+ * Returns `{ inForm: false, values: {} }` when used outside a form. Re-renders
+ * only when one of the watched names actually changes — not on every field
+ * update in the form.
+ *
+ * @example
+ * const { inForm, values } = useFormParams(["city", "country"]);
+ * if (inForm && values.city) console.log("city:", values.city);
+ */
+export function useFormParams(names) {
+    const { store, isInForm } = useFormContext();
+    const stableNames = useStableStringArray(names);
+    const subscribe = useCallback((cb) => {
+        if (!store)
+            return () => { };
+        return store.subscribe(stableNames, cb);
+    }, [store, stableNames]);
+    const snapshotRef = useRef(EMPTY_PARAMS);
+    const getSnapshot = useCallback(() => {
+        if (!store)
+            return EMPTY_PARAMS;
+        const next = store.getSnapshot(stableNames);
+        const prev = snapshotRef.current;
+        if (shallowEqualRecords(prev, next))
+            return prev;
+        snapshotRef.current = next;
+        return next;
+    }, [store, stableNames]);
+    const values = useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+    return { inForm: isInForm, values };
+}
+function shallowEqualRecords(a, b) {
+    if (a === b)
+        return true;
+    const keysA = Object.keys(a);
+    const keysB = Object.keys(b);
+    if (keysA.length !== keysB.length)
+        return false;
+    for (const k of keysA) {
+        if (!Object.is(a[k], b[k]))
+            return false;
+    }
+    return true;
+}
+/** Return a stable array reference when the string contents don't change. */
+function useStableStringArray(names) {
+    const ref = useRef(names);
+    const prev = ref.current;
+    if (prev !== names &&
+        (prev.length !== names.length || prev.some((n, i) => n !== names[i]))) {
+        ref.current = names;
+    }
+    return ref.current;
+}

package/dist/hooks/use-allowed-sources.d.ts

@@ -0,0 +1,20 @@
+import { type AllowedSource } from "../bridge";
+/**
+ * Returns the set of UDFs allowed to broadcast params to the current node,
+ * computed from canvas edges.
+ *
+ * Returns `{ allowedSources: null }` when no filtering is applied — typically
+ * because the node has no identity or runs in a shared/embed context where
+ * topology isn't available.
+ *
+ * The companion `isAllowedSource(originUdfId, originUdfName)` helper checks
+ * whether a specific source identity is permitted.
+ *
+ * @example
+ * const { allowedSources, isAllowedSource } = useAllowedSources();
+ * console.log("allowed:", allowedSources?.map(s => s.udfName));
+ */
+export declare function useAllowedSources(): {
+    allowedSources: ReadonlyArray<AllowedSource> | null;
+    isAllowedSource: (originUdfId?: string, originUdfName?: string) => boolean;
+};

package/dist/hooks/use-allowed-sources.js

@@ -0,0 +1,49 @@
+import { useCallback, useRef, useSyncExternalStore } from "react";
+import { useFusedWidgetBridge } from "../bridge";
+/**
+ * Returns the set of UDFs allowed to broadcast params to the current node,
+ * computed from canvas edges.
+ *
+ * Returns `{ allowedSources: null }` when no filtering is applied — typically
+ * because the node has no identity or runs in a shared/embed context where
+ * topology isn't available.
+ *
+ * The companion `isAllowedSource(originUdfId, originUdfName)` helper checks
+ * whether a specific source identity is permitted.
+ *
+ * @example
+ * const { allowedSources, isAllowedSource } = useAllowedSources();
+ * console.log("allowed:", allowedSources?.map(s => s.udfName));
+ */
+export function useAllowedSources() {
+    const bridge = useFusedWidgetBridge();
+    const subscribe = useCallback((cb) => bridge.routing.subscribeAllowedSources(cb), [bridge]);
+    const snapshotRef = useRef(null);
+    const getSnapshot = useCallback(() => {
+        const next = bridge.routing.getAllowedSources();
+        const prev = snapshotRef.current;
+        if (allowedSourcesEqual(prev, next))
+            return prev;
+        snapshotRef.current = next;
+        return next;
+    }, [bridge]);
+    const allowedSources = useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+    const isAllowedSource = useCallback((originUdfId, originUdfName) => {
+        if (!allowedSources || allowedSources.length === 0)
+            return true;
+        if (!originUdfId && !originUdfName)
+            return true;
+        return allowedSources.some((s) => (s.udfUniqueId && s.udfUniqueId === originUdfId) ||
+            (s.udfName && s.udfName === originUdfName));
+    }, [allowedSources]);
+    return { allowedSources, isAllowedSource };
+}
+function allowedSourcesEqual(a, b) {
+    if (a === b)
+        return true;
+    if (a === null || b === null)
+        return false;
+    if (a.length !== b.length)
+        return false;
+    return a.every((src, i) => src.udfUniqueId === b[i].udfUniqueId && src.udfName === b[i].udfName);
+}

package/dist/hooks/use-allowed-udf-names.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Returns the set of UDF names this node may reference (computed from
+ * incoming edges). Returns `null` when no filtering applies (e.g. node has
+ * no identity, or running in a shared widget context).
+ *
+ * Use this to gate AI suggestions or SQL queries to only reference
+ * connected UDFs — ensures consistency with the canvas's edge topology.
+ *
+ * @example
+ * const allowed = useAllowedUdfNames();
+ * if (allowed && !allowed.has(udfName)) {
+ *   return <div>UDF "{udfName}" is not reachable from this node.</div>;
+ * }
+ */
+export declare function useAllowedUdfNames(): Set<string> | null;

package/dist/hooks/use-allowed-udf-names.js

@@ -0,0 +1,42 @@
+import { useCallback, useRef, useSyncExternalStore } from "react";
+import { useFusedWidgetBridge } from "../bridge";
+/**
+ * Returns the set of UDF names this node may reference (computed from
+ * incoming edges). Returns `null` when no filtering applies (e.g. node has
+ * no identity, or running in a shared widget context).
+ *
+ * Use this to gate AI suggestions or SQL queries to only reference
+ * connected UDFs — ensures consistency with the canvas's edge topology.
+ *
+ * @example
+ * const allowed = useAllowedUdfNames();
+ * if (allowed && !allowed.has(udfName)) {
+ *   return <div>UDF "{udfName}" is not reachable from this node.</div>;
+ * }
+ */
+export function useAllowedUdfNames() {
+    const bridge = useFusedWidgetBridge();
+    const subscribe = useCallback((cb) => bridge.routing.subscribeAllowedSources(cb), [bridge]);
+    const snapshotRef = useRef(null);
+    const getSnapshot = useCallback(() => {
+        const next = bridge.routing.getAllowedUdfNames();
+        const prev = snapshotRef.current;
+        if (setsEqual(prev, next))
+            return prev;
+        snapshotRef.current = next;
+        return next;
+    }, [bridge]);
+    return useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+}
+function setsEqual(a, b) {
+    if (a === b)
+        return true;
+    if (a === null || b === null)
+        return false;
+    if (a.size !== b.size)
+        return false;
+    for (const x of a)
+        if (!b.has(x))
+            return false;
+    return true;
+}

package/dist/hooks/use-canvas-params.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Read filtered canvas parameter values for multiple param names at once.
+ *
+ * The returned values are filtered by the current node's incoming edges —
+ * only params broadcast by upstream-connected nodes are visible.
+ *
+ * Re-renders only when one of the watched params actually changes.
+ *
+ * @example
+ * const { city, year } = useCanvasParams(["city", "year"]);
+ * if (city) console.log("city is", city);
+ */
+export declare function useCanvasParams(paramNames: string[]): Record<string, unknown>;

package/dist/hooks/use-canvas-params.js

@@ -0,0 +1,58 @@
+import { useCallback, useRef, useSyncExternalStore } from "react";
+import { useFusedWidgetBridge } from "../bridge";
+const EMPTY_RECORD = Object.freeze({});
+/**
+ * Read filtered canvas parameter values for multiple param names at once.
+ *
+ * The returned values are filtered by the current node's incoming edges —
+ * only params broadcast by upstream-connected nodes are visible.
+ *
+ * Re-renders only when one of the watched params actually changes.
+ *
+ * @example
+ * const { city, year } = useCanvasParams(["city", "year"]);
+ * if (city) console.log("city is", city);
+ */
+export function useCanvasParams(paramNames) {
+    const bridge = useFusedWidgetBridge();
+    const stableNames = useStableStringArray(paramNames);
+    const subscribe = useCallback((cb) => {
+        if (stableNames.length === 0)
+            return () => { };
+        return bridge.params.subscribeMany(stableNames, cb);
+    }, [bridge, stableNames]);
+    const snapshotRef = useRef(EMPTY_RECORD);
+    const getSnapshot = useCallback(() => {
+        if (stableNames.length === 0)
+            return EMPTY_RECORD;
+        const next = bridge.params.getSnapshotMany(stableNames);
+        const prev = snapshotRef.current;
+        if (shallowEqualRecords(prev, next))
+            return prev;
+        snapshotRef.current = next;
+        return next;
+    }, [bridge, stableNames]);
+    return useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+}
+function shallowEqualRecords(a, b) {
+    if (a === b)
+        return true;
+    const keysA = Object.keys(a);
+    const keysB = Object.keys(b);
+    if (keysA.length !== keysB.length)
+        return false;
+    for (const k of keysA) {
+        if (!Object.is(a[k], b[k]))
+            return false;
+    }
+    return true;
+}
+function useStableStringArray(names) {
+    const ref = useRef(names);
+    const prev = ref.current;
+    if (prev !== names &&
+        (prev.length !== names.length || prev.some((n, i) => n !== names[i]))) {
+        ref.current = names;
+    }
+    return ref.current;
+}

package/dist/hooks/use-duckdb-sql.d.ts

@@ -0,0 +1,61 @@
+export interface UseDuckDbSqlQueryOptions {
+    /**
+     * SQL query with `{{udf_name}}` and `$param_name` placeholders.
+     * Example: `"SELECT DISTINCT city FROM {{my_udf}} ORDER BY city"`
+     */
+    sql?: string;
+    /** When false, skip preprocessing and execution. */
+    enabled?: boolean;
+    /**
+     * Safety LIMIT appended if the SQL doesn't include one. Defaults to 500;
+     * map widgets pass 100_000.
+     */
+    maxRows?: number;
+    /**
+     * Workbench-only: override `{{name}}` placeholders with in-memory
+     * relations (DuckDB tabs in sql-runner/code-editor). When `relationName`
+     * is provided, the placeholder is replaced with `"<relationName>"` rather
+     * than the VFS filename. Other hosts pass `undefined`.
+     */
+    sourceOverrides?: Record<string, {
+        relationName: string;
+        error?: string;
+        loading?: boolean;
+    }>;
+    /** @deprecated Use `maxRows` — kept temporarily for the SDK's existing surface. */
+    defaultLimit?: number;
+}
+export interface UseDuckDbSqlQueryResult {
+    rows: ReadonlyArray<Record<string, unknown>>;
+    columns: readonly string[];
+    loading: boolean;
+    /** Legacy: components expect `error: string | null`. */
+    error: string | null;
+    refetch: () => void;
+}
+export interface UseDuckDbSqlQueryPreprocessingResult {
+    processedSql: string;
+    loading: boolean;
+    error: string | null;
+    refetch: () => void;
+}
+/**
+ * Preprocess SQL: resolve placeholders, register UDFs via the bridge,
+ * substitute params, sign URLs, append LIMIT. Returns the prepared SQL.
+ */
+export declare function useDuckDbSqlQueryPreprocessing({ sql, enabled, maxRows, sourceOverrides, }: UseDuckDbSqlQueryOptions): UseDuckDbSqlQueryPreprocessingResult;
+/**
+ * Execute a DuckDB SQL query against UDF Parquet outputs. Uses
+ * `useDuckDbSqlQueryPreprocessing` to prepare the SQL string, then runs
+ * it via the bridge.
+ */
+export declare function useDuckDbSqlQuery({ sql, enabled, maxRows, sourceOverrides, }: UseDuckDbSqlQueryOptions): UseDuckDbSqlQueryResult;
+/**
+ * Resolve UDF names to VFS filenames, registering them in DuckDB if needed.
+ * Exposed for advanced use cases (e.g. building your own query string).
+ */
+export declare function useVfsRegistration(udfNames: readonly string[], enabled?: boolean): {
+    filenames: Map<string, string>;
+    loading: boolean;
+    error?: string;
+};