@flikk/ui 1.0.0-beta.30 → 1.0.0-beta.32

package/dist/components/generative/ai-sdk/useGenerativeChat.d.ts

@@ -0,0 +1,52 @@
+import { useChat } from "@ai-sdk/react";
+import { ActionContext } from "../actions";
+import { ActionDescriptor, UISpec } from "../types";
+export interface UseGenerativeChatOptions {
+    /** Chat endpoint. Passed straight to the AI SDK's transport. @default "/api/chat" */
+    api?: string;
+    /** Tool name the model calls to render UI. @default GENERATIVE_TOOL.name */
+    toolName?: string;
+}
+export interface UseGenerativeChatReturn {
+    /** The validated spec from the most recent render tool call. Empty array while nothing has streamed in yet. */
+    spec: UISpec;
+    /** Route this into <GenerativeView onAction={…} /> to close the loop. */
+    onAction: (action: ActionDescriptor, ctx: ActionContext) => void;
+    /**
+     * True while the render tool's arguments are still arriving — either the
+     * matched tool-call part's own `state` is `"input-streaming"`, or the chat
+     * as a whole is still streaming (`chat.status === "streaming"`, e.g. the
+     * tool call hasn't started yet but a response is in flight). False at rest
+     * (no messages, nothing in flight) and once the matched part has settled.
+     *
+     * NOT derived from `useGenerativeStream`'s own `complete` flag — see the
+     * note on `useGenerativeChat` below for why that signal is unusable here.
+     */
+    streaming: boolean;
+    messages: ReturnType<typeof useChat>["messages"];
+    sendMessage: ReturnType<typeof useChat>["sendMessage"];
+    status: ReturnType<typeof useChat>["status"];
+}
+/**
+ * Wires the AI SDK's chat loop to the generative engine: feeds the render
+ * tool's arguments through `useGenerativeStream`, validates the result, and
+ * routes user interactions back to the model as a tool result.
+ *
+ * 🔴 Skeleton placeholders do NOT apply on this path. `useGenerativeStream` /
+ * `parseStreamingSpec` detect "still arriving" content by finding an unclosed
+ * bracket in raw, truncated JSON text — that's how `GenerativeView` gets to
+ * render `__skeleton__` placeholders mid-stream. But `@ai-sdk/react` never
+ * exposes that raw text: a streaming tool-call part's `input` is already a
+ * parsed `DeepPartial` snapshot, and `JSON.stringify`-ing it (the only way to
+ * satisfy `useGenerativeStream`'s string contract) always yields syntactically
+ * COMPLETE JSON, at every step. So `pending` is always `0` here, and content
+ * pops in whole as fields complete rather than reserving skeleton space for
+ * fields that haven't started. This is a real, accepted trade-off of the
+ * installed SDK's surface — not a bug — which is also why `streaming` below
+ * is derived from the tool-call part's own `state` / `chat.status`, and NOT
+ * from `useGenerativeStream`'s `complete` flag (which is always `true` here
+ * for the same reason `pending` is always `0`).
+ *
+ * Requires the optional peers `ai` and `@ai-sdk/react`.
+ */
+export declare function useGenerativeChat({ api, toolName, }?: UseGenerativeChatOptions): UseGenerativeChatReturn;

package/dist/components/generative/ai-sdk/useGenerativeChat.js

@@ -0,0 +1,73 @@
+"use client";
+import React__default from 'react';
+import { useChat } from '@ai-sdk/react';
+import { DefaultChatTransport } from 'ai';
+import { GENERATIVE_TOOL } from '../tools.js';
+import { toToolResult } from '../toToolResult.js';
+import { useGenerativeStream } from '../useGenerativeStream.js';
+import { validate } from '../validate.js';
+
+/**
+ * Wires the AI SDK's chat loop to the generative engine: feeds the render
+ * tool's arguments through `useGenerativeStream`, validates the result, and
+ * routes user interactions back to the model as a tool result.
+ *
+ * 🔴 Skeleton placeholders do NOT apply on this path. `useGenerativeStream` /
+ * `parseStreamingSpec` detect "still arriving" content by finding an unclosed
+ * bracket in raw, truncated JSON text — that's how `GenerativeView` gets to
+ * render `__skeleton__` placeholders mid-stream. But `@ai-sdk/react` never
+ * exposes that raw text: a streaming tool-call part's `input` is already a
+ * parsed `DeepPartial` snapshot, and `JSON.stringify`-ing it (the only way to
+ * satisfy `useGenerativeStream`'s string contract) always yields syntactically
+ * COMPLETE JSON, at every step. So `pending` is always `0` here, and content
+ * pops in whole as fields complete rather than reserving skeleton space for
+ * fields that haven't started. This is a real, accepted trade-off of the
+ * installed SDK's surface — not a bug — which is also why `streaming` below
+ * is derived from the tool-call part's own `state` / `chat.status`, and NOT
+ * from `useGenerativeStream`'s `complete` flag (which is always `true` here
+ * for the same reason `pending` is always `0`).
+ *
+ * Requires the optional peers `ai` and `@ai-sdk/react`.
+ */
+function useGenerativeChat({ api = "/api/chat", toolName = GENERATIVE_TOOL.name, } = {}) {
+    const transport = React__default.useMemo(() => new DefaultChatTransport({ api }), [api]);
+    const chat = useChat({ transport });
+    // Most recent render tool call across the transcript, streaming or settled.
+    const match = React__default.useMemo(() => {
+        var _a, _b;
+        const staticType = `tool-${toolName}`;
+        for (let i = chat.messages.length - 1; i >= 0; i--) {
+            const parts = (_a = chat.messages[i].parts) !== null && _a !== void 0 ? _a : [];
+            for (let j = parts.length - 1; j >= 0; j--) {
+                const part = parts[j];
+                const isMatch = part.type === staticType || (part.type === "dynamic-tool" && part.toolName === toolName);
+                if (isMatch) {
+                    return {
+                        text: typeof part.input === "string" ? part.input : JSON.stringify((_b = part.input) !== null && _b !== void 0 ? _b : {}),
+                        isStreaming: part.state === "input-streaming",
+                    };
+                }
+            }
+        }
+        return { text: "", isStreaming: false };
+    }, [chat.messages, toolName]);
+    const stream = useGenerativeStream({ text: match.text });
+    const spec = React__default.useMemo(() => {
+        if (!stream.spec)
+            return [];
+        return validate(stream.spec).spec;
+    }, [stream.spec]);
+    const onAction = React__default.useCallback((action, ctx) => {
+        chat.sendMessage({ text: JSON.stringify(toToolResult(action, ctx)) });
+    }, [chat.sendMessage]);
+    return {
+        spec,
+        onAction,
+        streaming: match.isStreaming || chat.status === "streaming",
+        messages: chat.messages,
+        sendMessage: chat.sendMessage,
+        status: chat.status,
+    };
+}
+
+export { useGenerativeChat };

package/dist/components/generative/ai-sdk/useGenerativeChat.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/components/generative/fieldBinding.d.ts

@@ -0,0 +1,31 @@
+import { JSONValue } from "./types";
+/**
+ * How one curated control exposes its value to the form scope.
+ *
+ * Hand-verified against each component's `.types.ts` — these contracts are NOT
+ * uniform and must never be inferred from the component name:
+ *   - `Checkbox.value` / `Switch.value` are the HTML *value attribute*
+ *     (Checkbox.types.ts:23 declares it REQUIRED); the state is `checked`.
+ *   - `Input`/`Textarea` fire `onValueChange`; everything else fires `onChange`.
+ *   - `Input`/`Textarea` inherit `value`/`defaultValue` from the native
+ *     HTML attribute interfaces rather than declaring them.
+ */
+export interface FieldBinding {
+    /** Prop carrying the field's current value in controlled use. */
+    valueProp: string;
+    /** Prop carrying the seed value in uncontrolled use, when the control has one. */
+    defaultValueProp?: string;
+    /** Callback prop fired on change. Its first argument is the new value. */
+    changeProp: string;
+    /** The value this control considers "blank" for the `required` check. */
+    empty: JSONValue;
+}
+export declare const FIELD_BINDINGS: Record<string, FieldBinding>;
+/**
+ * Look up a binding. Uses `Object.hasOwn` so inherited Object.prototype members
+ * ("constructor", "toString") resolve to undefined rather than a function —
+ * the same guard `validate.ts`'s `safeLookup` applies.
+ */
+export declare function getFieldBinding(component: string): FieldBinding | undefined;
+/** Is this value "blank" for the purposes of a `required` check? */
+export declare function isEmptyValue(binding: FieldBinding, value: JSONValue | undefined): boolean;

package/dist/components/generative/fieldBinding.js

@@ -0,0 +1,33 @@
+const FIELD_BINDINGS = {
+    Input: { valueProp: "value", defaultValueProp: "defaultValue", changeProp: "onValueChange", empty: "" },
+    Textarea: { valueProp: "value", defaultValueProp: "defaultValue", changeProp: "onValueChange", empty: "" },
+    Select: { valueProp: "value", changeProp: "onChange", empty: "" },
+    Combobox: { valueProp: "value", changeProp: "onChange", empty: "" },
+    Checkbox: { valueProp: "checked", defaultValueProp: "defaultChecked", changeProp: "onChange", empty: false },
+    Switch: { valueProp: "checked", defaultValueProp: "defaultChecked", changeProp: "onChange", empty: false },
+    Slider: { valueProp: "value", defaultValueProp: "defaultValue", changeProp: "onChange", empty: null },
+    InputOTP: { valueProp: "value", defaultValueProp: "defaultValue", changeProp: "onChange", empty: "" },
+    TimePicker: { valueProp: "value", defaultValueProp: "defaultValue", changeProp: "onChange", empty: "" },
+    InputDate: { valueProp: "value", changeProp: "onChange", empty: "" },
+    InputCounter: { valueProp: "value", changeProp: "onChange", empty: null },
+    InputTag: { valueProp: "value", defaultValueProp: "defaultValue", changeProp: "onChange", empty: [] },
+    Rating: { valueProp: "value", defaultValueProp: "defaultValue", changeProp: "onChange", empty: 0 },
+};
+/**
+ * Look up a binding. Uses `Object.hasOwn` so inherited Object.prototype members
+ * ("constructor", "toString") resolve to undefined rather than a function —
+ * the same guard `validate.ts`'s `safeLookup` applies.
+ */
+function getFieldBinding(component) {
+    return Object.hasOwn(FIELD_BINDINGS, component) ? FIELD_BINDINGS[component] : undefined;
+}
+/** Is this value "blank" for the purposes of a `required` check? */
+function isEmptyValue(binding, value) {
+    if (value === undefined || value === null)
+        return true;
+    if (Array.isArray(binding.empty))
+        return Array.isArray(value) && value.length === 0;
+    return value === binding.empty;
+}
+
+export { FIELD_BINDINGS, getFieldBinding, isEmptyValue };

package/dist/components/generative/fieldBinding.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/components/generative/formScope.d.ts

@@ -0,0 +1,71 @@
+import React from "react";
+import { FieldBinding } from "./fieldBinding";
+import { JSONValue } from "./types";
+/** One form's field values, keyed by field name. */
+export type FormValues = Record<string, JSONValue>;
+/** Every form in a spec, keyed by form id. */
+export type GenerativeValues = Record<string, FormValues>;
+export declare const REQUIRED_MESSAGE = "This field is required.";
+interface FieldRegistration {
+    required?: boolean;
+    binding: FieldBinding;
+    /**
+     * The field's visible label, if it has one. Used only by `FormShell`'s error
+     * summary, so a blocked field is named the way the user sees it rather than
+     * by its submission key.
+     */
+    label?: string;
+    /**
+     * The field's initial value (spec seed or the binding's "empty"), committed
+     * to the scope on registration if nothing is held for this name yet. Kept
+     * separate from `setValue` so mounting a field doesn't fire `onValuesChange`
+     * before any user interaction — seeding is not a user-driven change.
+     */
+    seed?: JSONValue;
+}
+export interface FormScopeValue {
+    formId: string;
+    getValue(name: string): JSONValue | undefined;
+    setValue(name: string, value: JSONValue): void;
+    /**
+     * The registered label for a field, if any. Read at render time by the
+     * error summary; safe because the scope's identity changes whenever
+     * `errors` does, so the summary always re-reads after a blocked submit.
+     */
+    getLabel(name: string): string | undefined;
+    register(name: string, opts: FieldRegistration): void;
+    /** Drop a field that has unmounted, so its stale value never submits. */
+    unregister(name: string): void;
+    errors: Record<string, string>;
+    submit(): void;
+}
+export declare const FormScopeContext: React.Context<FormScopeValue | undefined>;
+/** Nearest enclosing form scope, or undefined outside a Form. */
+export declare function useFormScope(): FormScopeValue | undefined;
+export interface UseFormScopeStateOptions {
+    formId: string;
+    /** Controlled values for THIS form. Presence switches to controlled mode. */
+    values?: FormValues;
+    /** Uncontrolled seed for THIS form. */
+    defaultValues?: FormValues;
+    onValuesChange?: (values: FormValues) => void;
+    onSubmit: (values: FormValues) => void;
+    /**
+     * Called with EVERY invalid field name, in registration order, when submit
+     * is blocked. Deliberately the whole list rather than just the first: the
+     * per-field invalid treatment reaches only some controls (six of the
+     * thirteen render no focusable primary element at all — per-field focus
+     * isn't viable without a core-component change, a deferred follow-up, see
+     * FormShell.tsx — and Switch/Rating render no error text at all), so
+     * `FormShell` needs the full set to build the form-level error summary
+     * that covers all of them.
+     */
+    onInvalid?: (invalidNames: string[]) => void;
+}
+/**
+ * The form state machine. Controlled when `values` is passed; otherwise it owns
+ * state seeded from `defaultValues`. Mode is derived per render and never
+ * stored (CLAUDE.md §9).
+ */
+export declare function useFormScopeState({ formId, values, defaultValues, onValuesChange, onSubmit, onInvalid, }: UseFormScopeStateOptions): FormScopeValue;
+export {};

package/dist/components/generative/formScope.js

@@ -0,0 +1,135 @@
+"use client";
+import React__default from 'react';
+import { isEmptyValue } from './fieldBinding.js';
+
+const REQUIRED_MESSAGE = "This field is required.";
+/**
+ * Defense in depth for the values/errors bags below. `validate()` is the
+ * primary boundary (it rejects any field `name` that collides with
+ * `Object.prototype` before a spec ever reaches this scope), but a bag keyed
+ * by arbitrary field names is still one bad path away from resolving
+ * "toString"/"hasOwnProperty"/etc. to an INHERITED function instead of
+ * `undefined` for a key nobody ever set. A null-prototype object has no such
+ * chain — an unset key is always exactly `undefined`. Every bag update below
+ * goes through this rather than an object spread (`{ ...prev }` recreates a
+ * normal-prototype object, silently undoing the protection).
+ */
+function nullProtoBag(...sources) {
+    return Object.assign(Object.create(null), ...sources);
+}
+const FormScopeContext = React__default.createContext(undefined);
+/** Nearest enclosing form scope, or undefined outside a Form. */
+function useFormScope() {
+    return React__default.useContext(FormScopeContext);
+}
+/**
+ * The form state machine. Controlled when `values` is passed; otherwise it owns
+ * state seeded from `defaultValues`. Mode is derived per render and never
+ * stored (CLAUDE.md §9).
+ */
+function useFormScopeState({ formId, values, defaultValues, onValuesChange, onSubmit, onInvalid, }) {
+    const isControlled = values !== undefined;
+    const [internal, setInternal] = React__default.useState(() => nullProtoBag(defaultValues));
+    const [errors, setErrors] = React__default.useState(() => nullProtoBag());
+    const fields = React__default.useRef(new Map());
+    if (process.env.NODE_ENV !== "production") {
+        if (values !== undefined && defaultValues !== undefined) {
+            console.warn("[GenerativeView]: both `values` and `defaultValues` were provided — `values` wins.");
+        }
+        if (values !== undefined && !onValuesChange) {
+            console.warn("[GenerativeView]: `values` was provided without `onValuesChange` — fields will not update.");
+        }
+    }
+    // In controlled mode `values` is adopted VERBATIM — the consumer's own
+    // object, trusted as-given, never copied or re-prototyped. Copying it every
+    // render to null-proto it would break the referential equality the
+    // controlled contract depends on (a consumer diffing `values` between
+    // renders). `nullProtoBag` below therefore only ever touches the
+    // UNCONTROLLED bag this scope itself builds (`internal`/`errors`); it is
+    // NOT a defense against a hostile key in a controlled `values` object.
+    // `validate()` is the only boundary standing between a spec's field
+    // `name`s and a controlled consumer's bag — see CLAUDE.md §22 / the
+    // "limits of the defense-in-depth layer" note in the Task 6 report.
+    const current = isControlled ? values : internal;
+    // `current` is read during render; keep a ref so the stable callbacks below
+    // always see the latest bag without re-creating themselves every keystroke.
+    const currentRef = React__default.useRef(current);
+    currentRef.current = current;
+    const getValue = React__default.useCallback((name) => currentRef.current[name], []);
+    const getLabel = React__default.useCallback((name) => { var _a; return (_a = fields.current.get(name)) === null || _a === void 0 ? void 0 : _a.label; }, []);
+    const setValue = React__default.useCallback((name, value) => {
+        const next = nullProtoBag(currentRef.current, { [name]: value });
+        if (!isControlled) {
+            // Update the ref immediately (not just on the next render): React
+            // batches the setInternal below, so a second setValue call in the
+            // same synchronous block (e.g. two fields committed in one `act`)
+            // would otherwise read the pre-update snapshot and clobber this one.
+            currentRef.current = next;
+            setInternal(next);
+        }
+        onValuesChange === null || onValuesChange === void 0 ? void 0 : onValuesChange(next);
+        setErrors((prev) => {
+            if (prev[name] === undefined)
+                return prev;
+            const nextErrors = nullProtoBag();
+            for (const [k, v] of Object.entries(prev)) {
+                if (k !== name)
+                    nextErrors[k] = v;
+            }
+            return nextErrors;
+        });
+    }, [isControlled, onValuesChange]);
+    const register = React__default.useCallback((name, opts) => {
+        fields.current.set(name, opts);
+        // Commit the seed directly into internal state — never through
+        // `setValue` — so an untouched field still contributes to the
+        // submitted bag without ever notifying the consumer at mount. In
+        // controlled mode the consumer owns the complete bag already (or
+        // doesn't; either way it isn't this scope's place to inject a default
+        // behind their back), so this is a no-op there: `currentRef.current`
+        // is overwritten from `values` again on the very next render.
+        if (!isControlled && opts.seed !== undefined && currentRef.current[name] === undefined) {
+            const next = nullProtoBag(currentRef.current, { [name]: opts.seed });
+            currentRef.current = next;
+            setInternal(next);
+        }
+    }, [isControlled]);
+    const unregister = React__default.useCallback((name) => {
+        fields.current.delete(name);
+    }, []);
+    const submit = React__default.useCallback(() => {
+        const bag = nullProtoBag();
+        const nextErrors = nullProtoBag();
+        const invalid = [];
+        for (const [name, reg] of fields.current) {
+            const value = currentRef.current[name];
+            if (reg.required && isEmptyValue(reg.binding, value)) {
+                nextErrors[name] = REQUIRED_MESSAGE;
+                invalid.push(name);
+                continue;
+            }
+            if (value !== undefined)
+                bag[name] = value;
+        }
+        setErrors(nextErrors);
+        if (invalid.length) {
+            onInvalid === null || onInvalid === void 0 ? void 0 : onInvalid(invalid);
+            return;
+        }
+        onSubmit(bag);
+    }, [onSubmit, onInvalid]);
+    return React__default.useMemo(
+    // `current` is otherwise not a dependency of any memoized callback below
+    // (they all close over `currentRef`, not `current` itself), so without
+    // it here the returned object's identity never changes on a plain value
+    // update — and an unchanged Context value never re-renders consumers,
+    // regardless of how many times this component itself re-renders. Every
+    // field's own `NodeRenderer` reads the scope's value at render time via
+    // `getValue`; it needs a reason to be asked to render again, and this is
+    // that reason.
+    () => ({ formId, getValue, setValue, getLabel, register, unregister, errors, submit }), 
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [formId, getValue, setValue, getLabel, register, unregister, errors, submit, current]);
+}
+
+export { FormScopeContext, REQUIRED_MESSAGE, useFormScope, useFormScopeState };

package/dist/components/generative/index.d.ts

@@ -9,3 +9,7 @@ export { bindActionProps, extractActionData, type ActionContext, type ActionHand
 export { buildToolDefinition, GENERATIVE_TOOL, type GenerativeToolDefinition } from "./tools";
 export { GENERATIVE_SCHEMA } from "./schema.generated";
 export type { GenerativeSchemaDoc, ComponentSchema, SchemaProp, SchemaPropKind } from "./schemaTypes";
+export { toToolResult, type GenerativeToolResult } from "./toToolResult";
+export { FormShell, type FormShellProps } from "./FormShell";
+export { useFormScope, REQUIRED_MESSAGE, type FormValues, type GenerativeValues, type FormScopeValue, } from "./formScope";
+export { FIELD_BINDINGS, getFieldBinding, type FieldBinding } from "./fieldBinding";

package/dist/components/generative/index.js

@@ -7,3 +7,7 @@ export { useGenerativeStream } from './useGenerativeStream.js';
 export { bindActionProps, extractActionData } from './actions.js';
 export { GENERATIVE_TOOL, buildToolDefinition } from './tools.js';
 export { GENERATIVE_SCHEMA } from './schema.generated.js';
+export { toToolResult } from './toToolResult.js';
+export { FormShell } from './FormShell.js';
+export { REQUIRED_MESSAGE, useFormScope } from './formScope.js';
+export { FIELD_BINDINGS, getFieldBinding } from './fieldBinding.js';

package/dist/components/generative/registry.d.ts

@@ -12,6 +12,8 @@ export interface RegistryEntry {
     render?: (props: Record<string, unknown>, children?: React.ReactNode) => React.ReactNode;
     /** Map spec action keys to component callback props, e.g. { click: "onClick" }. */
     actionProps?: Record<string, string>;
+    /** Marks the container that hosts a FormScope. Only `Form` sets this. */
+    isForm?: boolean;
 }
 export interface GenerativeRegistry {
     components: Record<string, RegistryEntry>;