@flikk/ui 1.0.0-beta.31 → 1.0.0-beta.33

package/dist/components/forms/forms.theme.js

@@ -3,19 +3,34 @@
  * This file defines shared styling patterns used across all form components
  * Individual component themes should extend these base styles
  */
+/**
+ * The inset-shadow field edge on its own — radius, resting border, hover edge and
+ * focus border+ring — with NO layout/paint extras (no `flex`, no fill, no
+ * `transition-all`).
+ *
+ * Split out of `inputGroupBaseStyle` (which is just this plus those extras) for the
+ * one control that cannot take `transition-all`: `InputCounter`'s root is a
+ * motion element carrying `layout`, and a CSS transition covering `transform`
+ * re-interpolates motion's per-frame writes (§12). It needs the same edge as every
+ * other control, but has to name its own transitioned properties — so the edge is
+ * defined once here and both consumers compose it.
+ */
+const inputGroupBorderStyle = "rounded-[var(--form-radius)] outline-none shadow-[inset_0_0_0_1px_var(--color-border)] " +
+    "focus-within:shadow-[inset_0_0_0_1px_var(--color-primary-600)] " +
+    "focus-within:ring-4 focus-within:ring-[var(--color-primary)]/10 " +
+    // Hover edge: strengthen the border to --color-border-secondary on hover. Scoped with
+    // not-focus-within so focus (primary border) always wins; the token flips for dark mode.
+    "not-focus-within:hover:shadow-[inset_0_0_0_1px_var(--color-border-secondary)] " +
+    // Dark focus mirror (fill comes from --color-surface, which flips automatically)
+    "dark:focus-within:shadow-[inset_0_0_0_1px_var(--color-primary-500)] dark:focus-within:ring-[var(--color-primary-500)]/20";
 // Common form theme configuration
 const formsBaseTheme = {
     // Common wrapper style
     wrapperStyle: "relative w-full",
+    /** The field edge alone — for controls that must supply their own transition/fill. */
+    inputGroupBorderStyle,
     // Common input group style with focus, hover, and state variations
-    inputGroupBaseStyle: "relative flex rounded-[var(--form-radius)] outline-none shadow-[inset_0_0_0_1px_var(--color-border)] " +
-        "focus-within:shadow-[inset_0_0_0_1px_var(--color-primary-600)] " +
-        "focus-within:ring-4 focus-within:ring-[var(--color-primary)]/10 bg-[var(--field-fill)] transition-all " +
-        // Hover edge: strengthen the border to --color-border-secondary on hover. Scoped with
-        // not-focus-within so focus (primary border) always wins; the token flips for dark mode.
-        "not-focus-within:hover:shadow-[inset_0_0_0_1px_var(--color-border-secondary)] " +
-        // Dark focus mirror (fill comes from --color-surface, which flips automatically)
-        "dark:focus-within:shadow-[inset_0_0_0_1px_var(--color-primary-500)] dark:focus-within:ring-[var(--color-primary-500)]/20",
+    inputGroupBaseStyle: `relative flex bg-[var(--field-fill)] transition-all ${inputGroupBorderStyle}`,
     // Common base input/control style
     controlBaseStyle: "w-full bg-transparent text-sm text-[var(--color-text-primary)] " +
         "placeholder:text-[var(--color-text-placeholder)] focus:outline-none",
@@ -103,6 +118,11 @@ const formsBaseTheme = {
     helperText: "text-xs text-[var(--color-text-muted)] mt-1.5 [.state-disabled_&]:text-[var(--color-text-disabled)] [.state-invalid_&]:text-[var(--color-danger-500)] " +
         "dark:[.state-invalid_&]:text-[var(--color-danger-400)]",
     // Common icon styles
+    //
+    // `left`/`right`/`padding` are the size-BLIND originals (flat pr-3 / pr-10 at
+    // every size); the `*Sizes` maps below are the size-aware replacements. Adopt
+    // the maps in new work — Select already has — and treat the flat keys as the
+    // not-yet-migrated path for Input/Combobox/DatePicker/DateRangePicker/TimePicker.
     iconStyles: {
         left: "absolute inset-y-0 left-0 flex items-center pl-3 pointer-events-none text-[var(--color-text-muted)]",
         right: "absolute inset-y-0 right-0 flex items-center pr-3 pointer-events-none text-[var(--color-text-muted)]",
@@ -110,6 +130,61 @@ const formsBaseTheme = {
             left: "pl-10",
             right: "pr-10",
         },
+        /**
+         * The leading-icon slot, inset by the control's own horizontal padding —
+         * EXACTLY, not the trailing slot's `− 4px`. A leading icon stands where the
+         * text would have started, so matching `--form-px-*` keeps one constant left
+         * edge for a field's contents whether or not it has an icon. The trailing
+         * slot is chrome rather than content, which is why it insets tighter.
+         */
+        leftSizes: {
+            sm: "absolute inset-y-0 left-0 flex items-center pl-[var(--form-px-sm)] pointer-events-none text-[var(--color-text-muted)]",
+            md: "absolute inset-y-0 left-0 flex items-center pl-[var(--form-px-md)] pointer-events-none text-[var(--color-text-muted)]",
+            lg: "absolute inset-y-0 left-0 flex items-center pl-[var(--form-px-lg)] pointer-events-none text-[var(--color-text-muted)]",
+        },
+        /** Text runway for the leading slot: inset + icon + an 8px gap (32/36/40). */
+        paddingLeftSizes: {
+            sm: "pl-[calc(var(--form-px-sm)_+_20px)]",
+            md: "pl-[calc(var(--form-px-md)_+_22px)]",
+            lg: "pl-[calc(var(--form-px-lg)_+_24px)]",
+        },
+        /**
+         * The trailing-icon slot, inset from the right edge by the control's own
+         * horizontal padding MINUS 4px (8 / 10 / 12 at the default theme). Tighter
+         * than the text inset on purpose: a chevron is mostly whitespace, so at the
+         * same metric distance it reads as further from the edge than a glyph does.
+         * Derived from `--form-px-*` rather than a literal, so retuning a theme's
+         * control padding moves the icon with it.
+         */
+        rightSizes: {
+            sm: "absolute inset-y-0 right-0 flex items-center pr-[calc(var(--form-px-sm)_-_4px)] pointer-events-none text-[var(--color-text-muted)]",
+            md: "absolute inset-y-0 right-0 flex items-center pr-[calc(var(--form-px-md)_-_4px)] pointer-events-none text-[var(--color-text-muted)]",
+            lg: "absolute inset-y-0 right-0 flex items-center pr-[calc(var(--form-px-lg)_-_4px)] pointer-events-none text-[var(--color-text-muted)]",
+        },
+        /**
+         * Text runway reserved for that slot: inset + icon + an 8px gap, i.e.
+         * `--form-px-*` + 16/18/20 (28 / 32 / 36). It replaces a flat `pr-10` that
+         * over-reserved at every size.
+         */
+        paddingRightSizes: {
+            sm: "pr-[calc(var(--form-px-sm)_+_16px)]",
+            md: "pr-[calc(var(--form-px-md)_+_18px)]",
+            lg: "pr-[calc(var(--form-px-lg)_+_20px)]",
+        },
+        /**
+         * The glyph itself, ramping with the control (12 / 14 / 16px) instead of a
+         * flat 16 — at `sm` a 16px icon out-weighed the 14px text beside it.
+         *
+         * 🔴 Reads --form-icon-size-*, not a Tailwind literal: icon size was the one
+         * axis of a field's geometry a theme could not retune, so a preset that
+         * scaled height/padding/type left every decorator at its hardcoded size.
+         * Not to be confused with --button-icon-square-*, which is a BUTTON's box.
+         */
+        sizes: {
+            sm: "size-[var(--form-icon-size-sm)]",
+            md: "size-[var(--form-icon-size-md)]",
+            lg: "size-[var(--form-icon-size-lg)]",
+        },
     },
     // Dropdown/listbox styles for Select, Combobox, and similar components
     dropdownStyles: {
@@ -130,13 +205,19 @@ const formsBaseTheme = {
             // (utilities layer ⟶ win over that base-layer rule) suppress it here; scroll still works via
             // wheel/trackpad/keyboard. Scoped to the dropdown panel only — app scrollbars are untouched.
             "[scrollbar-width:none] [&::-webkit-scrollbar]:hidden " +
-            // p-1 (never py-1): the rows are rounded (see `option`), so they must inset evenly on
-            // ALL sides — with vertical-only padding a row's rounded corners and its hover ring run
+            // Padding on ALL sides (never py-only): the rows are rounded (see `option`), so they must
+            // inset evenly — with vertical-only padding a row's rounded corners and its hover ring run
             // flush into the panel's own edge and the radius reads as a rendering glitch. This lives
             // here rather than at each call site because every consumer needs it and, when it was a
             // call-site decision, two of four got it wrong.
-            "p-1 " +
-            "rounded-[var(--form-radius)] backdrop-blur-md text-sm border border-[var(--color-border)] " +
+            // 🔴 --form-dropdown-padding, not a literal p-1: it also feeds
+            // --form-dropdown-inner-radius, which rounds the first/last row to match this panel's
+            // curve. A literal survives a themed radius change and silently breaks that.
+            "p-[var(--form-dropdown-padding)] " +
+            // --form-dropdown-radius, NOT --form-radius: this is a padded content container, so it
+            // needs a capped token. --form-radius is `var(--radius-base)` — the uncapped CONTROL
+            // radius — which on `ember` (base 24px) curved this panel 24px against 4px of padding.
+            "rounded-[var(--form-dropdown-radius)] backdrop-blur-md text-sm border border-[var(--color-border)] " +
             "ring-1 ring-[var(--color-border)] focus:outline-none",
         // Base option style — hover uses the shared `--color-surface-hover` interaction tint
         // (§3): a translucent shade that composites over the dropdown's surface, darkening in
@@ -145,8 +226,16 @@ const formsBaseTheme = {
         // The radius belongs here, not per-consumer: `container`'s gap-0.5 and this row's inset
         // hover ring only read correctly on a rounded, inset row, so the base already assumes
         // this treatment — withholding the radius just let call sites drift out of it.
+        // Radius mirrors the menu rows (MenuItem): interior rows are a flat 4px, and the two rows
+        // that MEET the panel's corners take --form-dropdown-inner-radius (the panel's radius minus
+        // its border and padding) so their curve is concentric with the panel's instead of bulging
+        // past it. It was a flat --radius-base on every row, which equalled the panel's own radius.
+        // 🔴 first:/last: resolve against DOM SIBLINGS — every consumer here renders its options as
+        // direct children of the panel (verified for Select/Combobox/InputTag/Mention). Wrapping
+        // them in a group element would make a row both first and last of its own subtree and round
+        // all four corners; see ContextMenuSub, which renders no element for exactly that reason.
         option: "relative cursor-pointer select-none py-2 px-3 text-[var(--color-text-primary)] " +
-            "rounded-[var(--radius-base)] " +
+            "rounded-[4px] first:rounded-t-[var(--form-dropdown-inner-radius)] last:rounded-b-[var(--form-dropdown-inner-radius)] " +
             "hover:bg-[var(--color-surface-hover)] hover:shadow-[inset_0_0_0_1px_var(--color-border)]",
         // Selected option modifier
         optionSelected: "text-[var(--color-text-primary)] bg-[var(--color-surface-hover)] shadow-[inset_0_0_0_1px_var(--color-border)]",

package/dist/components/forms/index.js

@@ -40,6 +40,7 @@ export { sliderTheme } from './Slider/Slider.theme.js';
 export { Signature } from './Signature/Signature.js';
 export { signatureTheme } from './Signature/Signature.theme.js';
 export { RichTextEditor } from './RichTextEditor/RichTextEditor.js';
+import './RichTextEditor/RichTextToolbar.js';
 export { richTextEditorTheme } from './RichTextEditor/RichTextEditor.theme.js';
 export { InputOTP } from './InputOTP/InputOTP.js';
 export { inputOTPTheme } from './InputOTP/InputOTP.theme.js';

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

@@ -0,0 +1,22 @@
+import React from "react";
+import { FormValues } from "./formScope";
+export interface FormShellProps {
+    formId: string;
+    title?: React.ReactNode;
+    description?: React.ReactNode;
+    /** Label for the auto-rendered submit button. @default "Submit" */
+    submitLabel?: string;
+    /** Heading for the blocked-submit error summary. */
+    errorSummaryTitle?: string;
+    values?: FormValues;
+    defaultValues?: FormValues;
+    onValuesChange?: (values: FormValues) => void;
+    onSubmit: (values: FormValues) => void;
+    children?: React.ReactNode;
+}
+/**
+ * Generative-only form shell — the runtime half of the `Form` spec container.
+ * Sibling in spirit to `CardShell` in registry.tsx: it exists to serve the
+ * engine and is deliberately NOT a public library component.
+ */
+export declare function FormShell({ formId, title, description, submitLabel, errorSummaryTitle, values, defaultValues, onValuesChange, onSubmit, children, }: FormShellProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/generative/FormShell.js

@@ -0,0 +1,102 @@
+"use client";
+import { jsx, jsxs } from 'react/jsx-runtime';
+import React__default from 'react';
+import { WarningCircle } from '@phosphor-icons/react';
+import { Button } from '../core/Button/Button.js';
+import { cn } from '../../utils/cn.js';
+import { useFormScopeState, FormScopeContext } from './formScope.js';
+
+// SSR-safe layout effect (house shim — see src/hooks/useScaleBackground.ts):
+// `useLayoutEffect` warns during server rendering, so it must not be called
+// bare in an SSR-safe library (CLAUDE.md §6/§11).
+const useIsomorphicLayoutEffect = typeof window !== "undefined" ? React__default.useLayoutEffect : React__default.useEffect;
+/**
+ * Error-summary copy. Kept as props (not trapped strings) per CLAUDE.md §6:
+ * every built-in visible string must be overridable.
+ */
+const DEFAULT_ERROR_SUMMARY_TITLE = "Please fix the following before continuing:";
+/**
+ * Generative-only form shell — the runtime half of the `Form` spec container.
+ * Sibling in spirit to `CardShell` in registry.tsx: it exists to serve the
+ * engine and is deliberately NOT a public library component.
+ */
+function FormShell({ formId, title, description, submitLabel = "Submit", errorSummaryTitle = DEFAULT_ERROR_SUMMARY_TITLE, values, defaultValues, onValuesChange, onSubmit, children, }) {
+    const formRef = React__default.useRef(null);
+    const summaryRef = React__default.useRef(null);
+    const titleId = React__default.useId();
+    const summaryTitleId = React__default.useId();
+    // A blocked submit moves focus HERE, to the form-level summary — not to the
+    // first invalid control. That is a deliberate supersession of a per-field
+    // focus approach, and it is about coverage, not preference: only six of the
+    // thirteen curated controls even render a focusable primary element such a
+    // hook could target. Select/TimePicker spread no rest props onto one, and
+    // Combobox/Switch/Slider/InputOTP/InputTag land their root on a
+    // non-focusable wrapper `<div>`, where `.focus()` is a silent no-op.
+    // Closing that gap means changing those six core form components to
+    // forward a ref/rest props to their focusable element — a separate,
+    // dedicated pass, deferred and not yet started. Worse, the per-field
+    // *message* is thinner still: Switch and Rating render no error text and
+    // set no `aria-invalid` at all, so a required Switch ("accept the terms")
+    // produced a form whose Submit button did nothing, forever, with no
+    // programmatic state a screen reader could reach — a WCAG 3.3.1 failure.
+    // One summary covers all thirteen identically today and needs nothing from
+    // them. The per-field `state="invalid"` / `errorMessage` treatment still
+    // applies wherever a control declares those props (see FIELD_PROP_SUPPORT
+    // in GenerativeView.tsx); the summary is additive, not a replacement for it.
+    const [focusToken, setFocusToken] = React__default.useState(0);
+    const handleInvalid = React__default.useCallback(() => setFocusToken((t) => t + 1), []);
+    const scope = useFormScopeState({
+        formId,
+        values,
+        defaultValues,
+        onValuesChange,
+        onSubmit,
+        onInvalid: handleInvalid,
+    });
+    // Derived from `scope.errors` rather than held as its own state, so the
+    // summary clears itself the moment a user fixes a field (`setValue` drops
+    // that field's error) without a second source of truth to keep in sync.
+    const invalidNames = Object.keys(scope.errors);
+    // Focus after the summary has actually rendered: `onInvalid` fires inside
+    // `scope.submit()`, one React state update BEFORE `scope.errors` — and
+    // therefore the summary element — exists. A layout effect keyed on the token
+    // (not on `invalidNames`, which is unchanged when a second submit is blocked
+    // by the very same fields) re-focuses on every blocked attempt.
+    useIsomorphicLayoutEffect(() => {
+        var _a;
+        if (focusToken > 0)
+            (_a = summaryRef.current) === null || _a === void 0 ? void 0 : _a.focus();
+    }, [focusToken]);
+    // A child submit button suppresses the auto-rendered one. Checked on the
+    // rendered DOM rather than by inspecting children, so it works for buttons
+    // nested inside container nodes the model wrapped them in. The query
+    // excludes the auto-rendered button itself (via its marker attribute) —
+    // otherwise the very button this effect renders would be picked up as
+    // "a child submit button" and immediately hide itself.
+    //
+    // Runs in a LAYOUT effect (not a passive one) so the correction lands
+    // before the browser paints: a passive effect fires after paint, so a
+    // caller supplying a real child submit button would flash both buttons
+    // for one frame before the auto one is hidden (the same mount-then-correct
+    // anti-pattern already documented for chart container measurement).
+    const [hasChildSubmit, setHasChildSubmit] = React__default.useState(false);
+    useIsomorphicLayoutEffect(() => {
+        var _a;
+        const found = (_a = formRef.current) === null || _a === void 0 ? void 0 : _a.querySelector('button[type="submit"]:not([data-generative-auto-submit])');
+        setHasChildSubmit(!!found);
+    }, [children]);
+    return (jsx(FormScopeContext.Provider, { value: scope, children: jsxs("form", { ref: formRef, noValidate: true, "aria-labelledby": title ? titleId : undefined, className: "flex flex-col gap-4", onSubmit: (e) => {
+                e.preventDefault();
+                scope.submit();
+            }, children: [title && (jsx("h3", { id: titleId, className: "text-base font-semibold text-[var(--color-text-primary)]", children: title })), description && (jsx("p", { className: "text-sm text-[var(--color-text-secondary)]", children: description })), invalidNames.length > 0 && (jsxs("div", { ref: summaryRef, 
+                    // `role="alert"` is an implicit assertive live region, so the list
+                    // is announced even when focus does not land here (e.g. a consumer
+                    // re-rendering the form). `tabIndex={-1}` makes it a programmatic
+                    // focus target without adding a Tab stop.
+                    role: "alert", tabIndex: -1, "aria-labelledby": summaryTitleId, className: cn("flex flex-col gap-1 rounded-[var(--alert-radius)] p-3 text-sm", "border border-[var(--color-danger-600)] dark:border-[var(--color-danger-400)]", "bg-[var(--color-danger-50)] dark:bg-[var(--color-danger-900)]/30", "text-[var(--color-danger-700)] dark:text-[var(--color-danger-300)]", "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[var(--color-danger)]"), children: [jsxs("p", { id: summaryTitleId, className: "flex items-center gap-2 font-medium", children: [jsx(WarningCircle, { className: "size-4 shrink-0", "aria-hidden": "true" }), errorSummaryTitle] }), jsx("ul", { className: "list-disc pl-9", children: invalidNames.map((name) => {
+                                var _a;
+                                return (jsxs("li", { children: [(_a = scope.getLabel(name)) !== null && _a !== void 0 ? _a : name, ": ", scope.errors[name]] }, name));
+                            }) })] })), children, !hasChildSubmit && (jsx(Button, { type: "submit", variant: "filled", color: "primary", "data-generative-auto-submit": "", className: cn("self-start"), children: submitLabel }))] }) }));
+}
+
+export { FormShell };

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

@@ -1,6 +1,7 @@
 import { UISpec } from "./types";
 import { GenerativeRegistry } from "./registry";
 import { ActionHandler } from "./actions";
+import { GenerativeValues } from "./formScope";
 export interface GenerativeViewProps {
     /** The serializable spec tree (one root or top-level siblings). */
     spec: UISpec;
@@ -13,9 +14,59 @@ export interface GenerativeViewProps {
      */
     onAction?: ActionHandler;
     className?: string;
+    /** Controlled form values, keyed by form id then field name. */
+    values?: GenerativeValues;
+    /** Uncontrolled seed for form values. */
+    defaultValues?: GenerativeValues;
+    /** Fires with the complete next values bag whenever any field changes. */
+    onValuesChange?: (values: GenerativeValues) => void;
 }
+/**
+ * Which props each curated field component actually DECLARES, and may
+ * therefore be handed. NOT every FIELD_BINDINGS entry supports all three —
+ * hand-verified against each component's OWN Props interface, not a sibling's
+ * (mirrors the same "don't infer from the name" caution as `fieldBinding.ts`'s
+ * own table):
+ *   - Select/Combobox/Switch/Slider/TimePicker/InputTag accept `state` (for
+ *     border styling) but declare NO `errorMessage` prop at all.
+ *   - Checkbox accepts `state` but NOT `errorMessage` — `errorMessage` exists
+ *     only on the separate `CheckboxGroupProps` (`Checkbox.Group`), not on
+ *     `CheckboxProps` (what's actually registered/rendered here). Checkbox.tsx
+ *     destructures known props and spreads the rest onto the native `<input>`
+ *     (Checkbox.tsx:35,115), so this one is a real, reproducible DOM leak if
+ *     gotten wrong, not a hypothetical — verified by reverting this row and
+ *     confirming GenerativeView.test.tsx's Checkbox pinning test fails.
+ *   - Rating has none of the three: it's a Core rating widget, not a
+ *     FORMS_STANDARDS component.
+ * Forwarding a prop a component doesn't declare reaches the DOM as an
+ * unrecognized attribute (most of these spread unknown rest props onto
+ * their root element) and React logs it — see GenerativeView.test.tsx's
+ * "does not forward errorMessage/state to a control that doesn't declare
+ * them" tests (Switch and Checkbox each get their own).
+ *
+ * 🔴 `required` is on this table for FORWARDING ONLY. It is separately an
+ * ENGINE-SEMANTIC prop: `node.props.required` is read below to register the
+ * field's required-ness with the FormScope, which is what blocks submit —
+ * that happens for all 13 regardless of this table, and is why all 13 must
+ * declare `required` in the generated schema (see `REQUIRED_PROP` in
+ * packages/mcp/scripts/generativeManifest.ts). The four that decline it here
+ * (InputOTP/InputCounter/InputTag/Rating) extend
+ * `HTMLAttributes<HTMLDivElement>` and declare no `required` of their own, so
+ * forwarding would paint an invalid `required` attribute onto a `<div>` and
+ * buy nothing. Their required-ness is still enforced, and surfaced to the
+ * user by `FormShell`'s error summary rather than a per-field indicator.
+ * 🔴 The forwarding strip below is UNCONDITIONAL — it runs for every node,
+ * not only ones with a `name`/binding. A `required` prop with no `name` at
+ * all never registers with the scope, but it still rides along in `hydrated`
+ * and would otherwise reach a component's root element untouched.
+ */
+export declare const FIELD_PROP_SUPPORT: Record<string, {
+    state: boolean;
+    errorMessage: boolean;
+    required: boolean;
+}>;
 /**
  * Render a serializable UINode spec with the given registry.
  * Render-only in P1 — streaming (P3) and action dispatch (P4) layer on top.
  */
-export declare function GenerativeView({ spec, registry, onAction, className, }: GenerativeViewProps): import("react/jsx-runtime").JSX.Element;
+export declare function GenerativeView({ spec, registry, onAction, className, values, defaultValues, onValuesChange, }: GenerativeViewProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/generative/GenerativeView.js

@@ -6,7 +6,63 @@ import { defaultRegistry, CardShell } from './registry.js';
 import { applyResolvers } from './resolvers.js';
 import { SKELETON_NODE } from './streaming.js';
 import { bindActionProps } from './actions.js';
+import { getFieldBinding } from './fieldBinding.js';
+import { useFormScope } from './formScope.js';
 
+/**
+ * Which props each curated field component actually DECLARES, and may
+ * therefore be handed. NOT every FIELD_BINDINGS entry supports all three —
+ * hand-verified against each component's OWN Props interface, not a sibling's
+ * (mirrors the same "don't infer from the name" caution as `fieldBinding.ts`'s
+ * own table):
+ *   - Select/Combobox/Switch/Slider/TimePicker/InputTag accept `state` (for
+ *     border styling) but declare NO `errorMessage` prop at all.
+ *   - Checkbox accepts `state` but NOT `errorMessage` — `errorMessage` exists
+ *     only on the separate `CheckboxGroupProps` (`Checkbox.Group`), not on
+ *     `CheckboxProps` (what's actually registered/rendered here). Checkbox.tsx
+ *     destructures known props and spreads the rest onto the native `<input>`
+ *     (Checkbox.tsx:35,115), so this one is a real, reproducible DOM leak if
+ *     gotten wrong, not a hypothetical — verified by reverting this row and
+ *     confirming GenerativeView.test.tsx's Checkbox pinning test fails.
+ *   - Rating has none of the three: it's a Core rating widget, not a
+ *     FORMS_STANDARDS component.
+ * Forwarding a prop a component doesn't declare reaches the DOM as an
+ * unrecognized attribute (most of these spread unknown rest props onto
+ * their root element) and React logs it — see GenerativeView.test.tsx's
+ * "does not forward errorMessage/state to a control that doesn't declare
+ * them" tests (Switch and Checkbox each get their own).
+ *
+ * 🔴 `required` is on this table for FORWARDING ONLY. It is separately an
+ * ENGINE-SEMANTIC prop: `node.props.required` is read below to register the
+ * field's required-ness with the FormScope, which is what blocks submit —
+ * that happens for all 13 regardless of this table, and is why all 13 must
+ * declare `required` in the generated schema (see `REQUIRED_PROP` in
+ * packages/mcp/scripts/generativeManifest.ts). The four that decline it here
+ * (InputOTP/InputCounter/InputTag/Rating) extend
+ * `HTMLAttributes<HTMLDivElement>` and declare no `required` of their own, so
+ * forwarding would paint an invalid `required` attribute onto a `<div>` and
+ * buy nothing. Their required-ness is still enforced, and surfaced to the
+ * user by `FormShell`'s error summary rather than a per-field indicator.
+ * 🔴 The forwarding strip below is UNCONDITIONAL — it runs for every node,
+ * not only ones with a `name`/binding. A `required` prop with no `name` at
+ * all never registers with the scope, but it still rides along in `hydrated`
+ * and would otherwise reach a component's root element untouched.
+ */
+const FIELD_PROP_SUPPORT = {
+    Input: { state: true, errorMessage: true, required: true },
+    Textarea: { state: true, errorMessage: true, required: true },
+    Select: { state: true, errorMessage: false, required: true },
+    Combobox: { state: true, errorMessage: false, required: true },
+    Checkbox: { state: true, errorMessage: false, required: true },
+    Switch: { state: true, errorMessage: false, required: true },
+    Slider: { state: true, errorMessage: false, required: true },
+    InputOTP: { state: true, errorMessage: true, required: false },
+    TimePicker: { state: true, errorMessage: false, required: true },
+    InputDate: { state: true, errorMessage: true, required: true },
+    InputCounter: { state: true, errorMessage: true, required: false },
+    InputTag: { state: true, errorMessage: false, required: false },
+    Rating: { state: false, errorMessage: false, required: false },
+};
 const placeholderStyle = "rounded-lg border border-dashed border-[var(--color-border-secondary)] " +
     "bg-[var(--color-surface-sunken)] p-3 text-xs text-[var(--color-text-muted)]";
 /** The model asked for a component we didn't register — render, don't throw. */
@@ -43,23 +99,56 @@ class NodeBoundary extends React__default.Component {
         return this.props.children;
     }
 }
-function NodeRenderer({ node, registry, inShell, dispatch, }) {
-    var _a, _b, _c;
+function NodeRenderer({ node, registry, inShell, dispatch, path, values, defaultValues, onFormValuesChange, }) {
+    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m;
+    const scope = useFormScope();
+    const fieldName = typeof ((_a = node.props) === null || _a === void 0 ? void 0 : _a.name) === "string" ? node.props.name : undefined;
+    const binding = fieldName ? getFieldBinding(node.component) : undefined;
+    const specSeed = binding
+        ? ((_c = (_b = node.props) === null || _b === void 0 ? void 0 : _b[binding.valueProp]) !== null && _c !== void 0 ? _c : (binding.defaultValueProp
+            ? (_d = node.props) === null || _d === void 0 ? void 0 : _d[binding.defaultValueProp]
+            : undefined))
+        : undefined;
+    // Registration is an effect, not a render side effect: a field that
+    // disappears when the model re-emits a different spec must stop
+    // contributing its stale value to the next submit. The seed (spec value,
+    // or the binding's "empty") is handed to the scope rather than committed
+    // here via `setValue` — `formScope`'s `register` commits it internally
+    // without notifying `onValuesChange`, since mounting a field isn't a
+    // user-driven change (see formScope.tsx).
+    const required = ((_e = node.props) === null || _e === void 0 ? void 0 : _e.required) === true;
+    // The field's own label, handed to the scope purely so `FormShell`'s error
+    // summary can name a blocked field the way the user sees it rather than by
+    // its submission key ("Email address", not "email_address").
+    const fieldLabel = typeof ((_f = node.props) === null || _f === void 0 ? void 0 : _f.label) === "string" ? node.props.label : undefined;
+    React__default.useEffect(() => {
+        if (!scope || !fieldName || !binding)
+            return;
+        scope.register(fieldName, { required, binding, label: fieldLabel, seed: specSeed !== null && specSeed !== void 0 ? specSeed : binding.empty });
+        return () => scope.unregister(fieldName);
+        // `specSeed` is intentionally omitted from the deps: it's read straight
+        // from `node.props` for this same field/binding pair, so it's already
+        // implied by `fieldName`/`binding` being unchanged — and `register`
+        // itself only ever applies a seed once (it no-ops once the scope holds
+        // a value for the name), so re-deriving it on an unrelated re-render
+        // would be a no-op anyway.
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [scope, fieldName, binding, required, fieldLabel]);
     if (node.component === SKELETON_NODE)
         return jsx(SkeletonPlaceholder, { props: node.props });
     const entry = registry.components[node.component];
     if (!entry)
         return jsx(UnknownNode, { name: node.component });
-    const hydrated = applyResolvers(((_a = node.props) !== null && _a !== void 0 ? _a : {}), registry.resolvers, { icons: registry.icons, node });
+    const hydrated = applyResolvers(((_g = node.props) !== null && _g !== void 0 ? _g : {}), registry.resolvers, { icons: registry.icons, node });
     const isContainer = entry.kind === "container";
-    if (process.env.NODE_ENV !== "production" && !isContainer && ((_b = node.children) === null || _b === void 0 ? void 0 : _b.length)) {
+    if (process.env.NODE_ENV !== "production" && !isContainer && ((_h = node.children) === null || _h === void 0 ? void 0 : _h.length)) {
         console.warn(`[GenerativeView]: "${node.component}" is not a container — its children are ignored`);
     }
     const childInShell = entry.providesShell ? true : inShell;
-    const children = isContainer && ((_c = node.children) === null || _c === void 0 ? void 0 : _c.length)
+    const children = isContainer && ((_j = node.children) === null || _j === void 0 ? void 0 : _j.length)
         ? node.children.map((child, index) => {
-            var _a;
-            return (jsx(NodeBoundary, { name: child.component, children: jsx(NodeRenderer, { node: child, registry: registry, inShell: childInShell, dispatch: dispatch }) }, (_a = child.id) !== null && _a !== void 0 ? _a : index));
+            var _a, _b;
+            return (jsx(NodeBoundary, { name: child.component, children: jsx(NodeRenderer, { node: child, registry: registry, inShell: childInShell, dispatch: dispatch, path: `${path}.${(_a = child.id) !== null && _a !== void 0 ? _a : index}`, values: values, defaultValues: defaultValues, onFormValuesChange: onFormValuesChange }) }, (_b = child.id) !== null && _b !== void 0 ? _b : index));
         })
         : undefined;
     // Shell-wrapped leaves: title/subtitle belong to the shell, not the component.
@@ -78,6 +167,89 @@ function NodeRenderer({ node, registry, inShell, dispatch, }) {
         componentProps = bound.props;
         unboundClick = bound.unboundClick;
     }
+    // `required` is forwarded ONLY to a component whose FIELD_PROP_SUPPORT
+    // entry declares it — those need it for their own native `required`
+    // attribute and their FormLabel asterisk/"(required)" indicator (WCAG
+    // 3.3.2 — a required field must be identifiable before submit, not just
+    // after a rejected one). `FormShell` renders `<form noValidate>`, so the
+    // native attribute never interferes with `scope.submit()`'s own required
+    // check. This strip is UNCONDITIONAL — it must run whether or not this
+    // node has a `name`/`binding` at all: a node can carry `required` with no
+    // `name` (the field never registers, but `required` still rode along in
+    // `hydrated`) or a `name` for a component with no binding, and either way
+    // the component's own root element (e.g. Rating's `<div role="slider">`)
+    // must never receive an attribute it doesn't declare. Enforcement is
+    // unaffected either way: `node.props.required` was already read above and
+    // registered with the scope regardless of whether it survives forwarding.
+    if (!((_k = FIELD_PROP_SUPPORT[node.component]) === null || _k === void 0 ? void 0 : _k.required))
+        delete componentProps.required;
+    if (scope && fieldName && binding) {
+        const held = scope.getValue(fieldName);
+        const value = held !== undefined ? held : specSeed;
+        const existingChange = componentProps[binding.changeProp];
+        const support = FIELD_PROP_SUPPORT[node.component];
+        const next = { ...componentProps };
+        delete next.name; // consumed for registration; never forwarded
+        if (binding.defaultValueProp)
+            delete next[binding.defaultValueProp];
+        next[binding.valueProp] = value !== null && value !== void 0 ? value : binding.empty;
+        next[binding.changeProp] = (...args) => {
+            scope.setValue(fieldName, args[0]);
+            existingChange === null || existingChange === void 0 ? void 0 : existingChange(...args);
+        };
+        if (scope.errors[fieldName]) {
+            if (support === null || support === void 0 ? void 0 : support.state)
+                next.state = "invalid";
+            if (support === null || support === void 0 ? void 0 : support.errorMessage)
+                next.errorMessage = (_l = next.errorMessage) !== null && _l !== void 0 ? _l : scope.errors[fieldName];
+        }
+        componentProps = next;
+    }
+    else if (fieldName && binding) {
+        // A named FIELD-BINDING component outside a Form still renders; `name`
+        // is simply inert there. Strip it so it never reaches the DOM. A
+        // component with NO binding (e.g. `Avatar.name`, a person's display
+        // name) never entered this branch's condition for the wrong reason —
+        // `binding` here confirms it actually IS a field component, so its
+        // `name` prop is left alone and forwarded untouched.
+        const { name: _unused, ...rest } = componentProps;
+        componentProps = rest;
+    }
+    // Design spec §3.5: a `Button` inside a Form that declares no `actions` of
+    // its own IS that form's submit button. Core `Button` renders `type="button"`
+    // ahead of its rest-prop spread (Button.tsx:170), so injecting `type` here
+    // overrides it — and `FormShell`'s
+    // `button[type="submit"]:not([data-generative-auto-submit])` probe then finds
+    // it and suppresses the auto-rendered one, leaving exactly one button.
+    // `type` is deliberately NOT in the generative schema: the rule is the
+    // engine's to apply, not a knob the model can set (or forget to set).
+    // A Button WITH actions keeps its own click behaviour and never submits.
+    const declaresOwnActions = !!node.actions && Object.keys(node.actions).length > 0;
+    if (node.component === "Button" && scope && !declaresOwnActions) {
+        componentProps = { ...componentProps, type: "submit" };
+    }
+    if (entry.isForm) {
+        const formId = (_m = node.id) !== null && _m !== void 0 ? _m : `form-${path}`;
+        componentProps = {
+            ...componentProps,
+            formId,
+            // `Object.hasOwn`, not `values?.[formId]`: `formId` comes from the spec's
+            // own `node.id`. `validate()` now rejects unsafe ids (see validate.ts),
+            // but `GenerativeView` also accepts RAW specs, where a plain-object bag
+            // would resolve `id: "toString"` to an inherited function instead of
+            // `undefined` — and hand `FormShell` a function as its `values` prop.
+            values: values && Object.hasOwn(values, formId) ? values[formId] : undefined,
+            defaultValues: defaultValues && Object.hasOwn(defaultValues, formId) ? defaultValues[formId] : undefined,
+            onValuesChange: (formValues) => onFormValuesChange === null || onFormValuesChange === void 0 ? void 0 : onFormValuesChange(formId, formValues),
+            onSubmit: (formValues) => {
+                var _a;
+                const descriptor = (_a = node.actions) === null || _a === void 0 ? void 0 : _a.submit;
+                if (!descriptor || !dispatch)
+                    return;
+                dispatch(descriptor, { component: "Form", nodeId: node.id, values: formValues });
+            },
+        };
+    }
     const Component = entry.component;
     let inner;
     if (entry.render)
@@ -106,12 +278,32 @@ function NodeRenderer({ node, registry, inShell, dispatch, }) {
  * Render a serializable UINode spec with the given registry.
  * Render-only in P1 — streaming (P3) and action dispatch (P4) layer on top.
  */
-function GenerativeView({ spec, registry = defaultRegistry, onAction, className, }) {
+function GenerativeView({ spec, registry = defaultRegistry, onAction, className, values, defaultValues, onValuesChange, }) {
     const nodes = Array.isArray(spec) ? spec : [spec];
+    const isControlled = values !== undefined;
+    // `onValuesChange` is documented to fire with the COMPLETE next values bag,
+    // across every form in the spec. Controlled mode gets that for free: the
+    // consumer's `values` is the live bag, so merging onto it is correct.
+    // Uncontrolled mode does not — `defaultValues` is a static seed that never
+    // reflects what the user has since typed, so merging each form's callback
+    // onto it erased every OTHER form's live state (type in form A, then form B,
+    // and A's value vanished from the payload). This ref carries the last bag we
+    // emitted so the merge base stays current between forms.
+    const lastEmittedRef = React__default.useRef(defaultValues !== null && defaultValues !== void 0 ? defaultValues : {});
+    const handleFormValuesChange = React__default.useCallback((formId, formValues) => {
+        const base = isControlled ? (values !== null && values !== void 0 ? values : {}) : lastEmittedRef.current;
+        // A computed key in an object literal is a data-property definition, not
+        // an assignment, so a hostile `formId` cannot reach a prototype setter
+        // here even on a raw (unvalidated) spec.
+        const next = { ...base, [formId]: formValues };
+        if (!isControlled)
+            lastEmittedRef.current = next;
+        onValuesChange === null || onValuesChange === void 0 ? void 0 : onValuesChange(next);
+    }, [isControlled, values, onValuesChange]);
     return (jsx("div", { className: className, children: nodes.map((node, index) => {
-            var _a;
-            return (jsx(NodeBoundary, { name: node.component, children: jsx(NodeRenderer, { node: node, registry: registry, inShell: false, dispatch: onAction }) }, (_a = node.id) !== null && _a !== void 0 ? _a : index));
+            var _a, _b;
+            return (jsx(NodeBoundary, { name: node.component, children: jsx(NodeRenderer, { node: node, registry: registry, inShell: false, dispatch: onAction, path: `${(_a = node.id) !== null && _a !== void 0 ? _a : index}`, values: values, defaultValues: defaultValues, onFormValuesChange: handleFormValuesChange }) }, (_b = node.id) !== null && _b !== void 0 ? _b : index));
         }) }));
 }
 
-export { GenerativeView };
+export { FIELD_PROP_SUPPORT, GenerativeView };

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

@@ -7,6 +7,11 @@ export interface ActionContext {
     nodeId?: string;
     /** Serializable callback payload (e.g. the clicked Table row). Never a DOM event. */
     data?: JSONValue;
+    /**
+     * Present only on a Form's submit action: every registered field value,
+     * collected in one bag. Built with a null prototype.
+     */
+    values?: Record<string, JSONValue>;
 }
 /** Consumer handler: first arg is the EXACT descriptor from the spec. */
 export type ActionHandler = (action: ActionDescriptor, context: ActionContext) => void;

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

@@ -0,0 +1 @@
+export { useGenerativeChat, type UseGenerativeChatOptions, type UseGenerativeChatReturn, } from "./useGenerativeChat";