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

package/dist/components/forms/Select/Select.types.d.ts

@@ -26,7 +26,7 @@ export interface SelectBaseProps {
  * Select component props
  * @template T The type of the select value
  */
-export interface SelectProps<T = unknown> extends SelectBaseProps {
+export interface SelectCommonProps<T = unknown> extends SelectBaseProps {
     /** ID for the select component */
     id?: string;
     /** Name for the select component */
@@ -35,8 +35,6 @@ export interface SelectProps<T = unknown> extends SelectBaseProps {
     size?: SelectSize;
     /** Current state of the select component */
     state?: SelectState;
-    /** Currently selected option */
-    value?: T;
     /** Custom display value to show in trigger (overrides selected option label) */
     displayValue?: React.ReactNode;
     /** Placeholder text when no option is selected */
@@ -51,12 +49,8 @@ export interface SelectProps<T = unknown> extends SelectBaseProps {
     label?: React.ReactNode;
     /** Helper text below the select — pass a string for default styling, or a ReactNode for full control */
     helperText?: React.ReactNode;
-    /** Enable multi-select mode — value becomes T[] and chips are rendered in trigger */
-    multiple?: boolean;
     /** Maximum number of chips to display before showing "+N more" (default: 3) */
     maxDisplayedChips?: number;
-    /** Called when the selection changes */
-    onChange?: (value: T) => void;
     /** Called when the select receives focus */
     onFocus?: (event: React.FocusEvent<HTMLButtonElement>) => void;
     /** Called when the select loses focus */
@@ -113,7 +107,74 @@ export interface SelectProps<T = unknown> extends SelectBaseProps {
     elevation?: SurfaceElevation;
     /** `false` opts out of the relative lift — paints at the listbox's base rung. */
     lift?: boolean;
+    /**
+     * Accessible name for a Select with no visible `label` — e.g. a control sitting
+     * in a toolbar. `aria-labelledby` wins over this when both are present.
+     *
+     * 🔴 Declared explicitly because TypeScript does NOT check hyphenated JSX
+     * attributes against a component's props type: before this existed,
+     * `<Select aria-label="…" />` typechecked cleanly and was then dropped at
+     * runtime, leaving the trigger with no accessible name at all.
+     */
+    "aria-label"?: string;
+}
+/**
+ * Single-select props — the default mode.
+ * `value` is one `T` and `onChange` receives one `T`.
+ */
+export interface SelectSingleProps<T = unknown> extends SelectCommonProps<T> {
+    /** Enable multi-select mode. Omit or pass `false` for single-select. */
+    multiple?: false;
+    /**
+     * Currently selected option.
+     * 🔴 `NoInfer` matters: without it TS treats this as an inference site for `T`,
+     * so `<Select multiple value={["a"]} />` infers `T = string[]` from THIS branch
+     * and then demands `SelectOption<string[]>[]` for `options`. Inference must come
+     * from `options` alone; the value/onChange shapes follow from it.
+     */
+    value?: NoInfer<T>;
+    /** Called when the selection changes */
+    onChange?: (value: NoInfer<T>) => void;
 }
+/**
+ * Multi-select props — `multiple` is `true`, so `value` is an ARRAY and
+ * `onChange` receives the full next array (not the toggled item).
+ */
+export interface SelectMultipleProps<T = unknown> extends SelectCommonProps<T> {
+    /** Enable multi-select mode — chips are rendered in the trigger. */
+    multiple: true;
+    /** Currently selected options. `NoInfer` for the reason given on the single variant. */
+    value?: NoInfer<T>[];
+    /** Called with the complete next selection whenever it changes */
+    onChange?: (value: NoInfer<T>[]) => void;
+}
+/**
+ * Select component props — a discriminated union on `multiple`.
+ *
+ * 🔴 `value`/`onChange` change shape with the mode, which a single
+ * `value?: T` could not express: multi-select genuinely hands back a `T[]`.
+ * The implementation always did this and lied about it with
+ * `onChange?.(updated as unknown as T)`, so `<Select multiple value={["a"]} />`
+ * — correct usage, and what the JSDoc documented — failed to type-check while
+ * `onChange` handlers were silently typed as the element type instead of the
+ * array. Narrow with `multiple` to get the right shape on both.
+ *
+ * @template T The type of an individual option value (NOT the array)
+ */
+export type SelectProps<T = unknown> = SelectSingleProps<T> | SelectMultipleProps<T>;
+/**
+ * @internal Widened shape the implementation destructures. A union cannot be
+ * destructured and then called (`onChange` would be a union of incompatible
+ * signatures), so the mode-dependent members are widened exactly once, here,
+ * and the public `Select` export casts back to the precise union. This is the
+ * single sanctioned cast — it replaces three `as unknown as T` casts that
+ * previously misreported the runtime contract to consumers.
+ */
+export type SelectInternalProps<T = unknown> = SelectCommonProps<T> & {
+    multiple?: boolean;
+    value?: T | T[];
+    onChange?: (value: T | T[]) => void;
+};
 /**
  * Select button props
  */
@@ -148,6 +209,8 @@ export interface SelectButtonProps extends SelectBaseProps {
     "aria-describedby"?: string;
     /** ID of the element that labels this button (e.g. form label) */
     "aria-labelledby"?: string;
+    /** Accessible name for a Select with no visible `label` (e.g. a toolbar control) */
+    "aria-label"?: string;
     /** Structural content rendered before iconStart */
     contentStart?: React.ReactNode;
     /** Structural content rendered after iconEnd */

package/dist/components/forms/Select/useSelectState.d.ts

@@ -5,10 +5,16 @@ import type { SelectOption } from "./Select.types";
 export interface UseSelectStateProps<T = any> {
     /** Array of available options */
     options: SelectOption<T>[];
-    /** Currently selected value (controlled) */
-    value?: T;
+    /** Currently selected value (controlled). `T[]` when `multiple` is set. */
+    value?: T | T[];
     /** Callback when selection changes */
-    onChange?: (value: T) => void;
+    /**
+     * Called when the selection changes. In `multiple` mode the payload is the
+     * complete next `T[]`, not the toggled item — which is why this is widened
+     * rather than `(value: T) => void`. The public `SelectProps` union narrows it
+     * back to the exact shape per mode.
+     */
+    onChange?: (value: T | T[]) => void;
     /** Whether filtering/search is enabled */
     searchable?: boolean;
     /** Whether new options can be created */

package/dist/components/forms/Select/useSelectState.js

@@ -23,7 +23,10 @@ import { useState, useRef, useEffect, useCallback, useMemo } from 'react';
 function useSelectState({ options = [], value, onChange, searchable = false, creatable = false, onCreateOption, createLabel, enableTypeahead = true, multiple = false, }) {
     // Core state
     const [isOpen, setIsOpen] = useState(false);
-    const [selectedValue, setSelectedValue] = useState(value);
+    // `value` is widened to `T | T[]` because multi-select hands back an array;
+    // this single-value slot only ever holds the non-array branch (the array lives
+    // in `selectedValues` below), matching the Array.isArray idiom used throughout.
+    const [selectedValue, setSelectedValue] = useState(Array.isArray(value) ? undefined : value);
     const [highlightedIndex, setHighlightedIndex] = useState(-1);
     const [searchValue, setSearchValue] = useState("");
     // Multi-select state

package/dist/components/forms/SelectableCard/SelectableCard.js

@@ -5,6 +5,7 @@ import { useReducedMotion, motion } from 'motion/react';
 import { cn } from '../../../utils/cn.js';
 import { Radio } from '../Radio/Radio.js';
 import { Checkbox } from '../Checkbox/Checkbox.js';
+import { Ripple } from '../../core/shared/Ripple.js';
 import { useOptionalSelectableCardContext } from './SelectableCardContext.js';
 import { selectableCardTheme } from './SelectableCard.theme.js';
 import { SelectableCardGroup } from './SelectableCardGroup.js';
@@ -63,7 +64,7 @@ const SelectableCardRoot = React__default.forwardRef(({ value, disabled: cardDis
         ? { variants: cardVariants, animate: "rest", whileTap: "press" }
         : {};
     const indicatorNode = resolvedIndicator !== "none" && (jsx("div", { className: cn(theme.indicator, "pointer-events-none"), "aria-hidden": "true", children: resolvedIndicator === "radio" ? (jsx(Radio, { value: value, checked: isSelected, onChange: () => { }, state: isDisabled ? "disabled" : "default", size: indicatorSize })) : (jsx(Checkbox, { value: value, checked: isSelected, onChange: () => { }, state: isDisabled ? "disabled" : "default", size: indicatorSize })) }));
-    return (jsxs(motion.div, { ref: ref, role: role, "aria-checked": isSelected, "aria-disabled": isDisabled || undefined, tabIndex: isDisabled ? -1 : 0, "data-selected": isSelected, "data-disabled": isDisabled || undefined, className: cn(theme.card, (_a = theme.cardSizes) === null || _a === void 0 ? void 0 : _a[resolvedSize], isSelected && theme.selectedCard, isDisabled && theme.disabledCard, className), onClick: handleClick, onKeyDown: handleKeyDown, ...motionProps, ...props, children: [jsx("input", { type: inputType, id: inputId, name: isStandalone ? undefined : ctx === null || ctx === void 0 ? void 0 : ctx.name, value: value, checked: isSelected, disabled: isDisabled, onChange: () => { }, className: "sr-only", tabIndex: -1, "aria-hidden": true }), resolvedIndicatorPosition === "start" && indicatorNode, jsx("div", { className: theme.contentWrapper, children: children }), resolvedIndicatorPosition === "end" && indicatorNode] }));
+    return (jsxs(motion.div, { ref: ref, role: role, "aria-checked": isSelected, "aria-disabled": isDisabled || undefined, tabIndex: isDisabled ? -1 : 0, "data-selected": isSelected, "data-disabled": isDisabled || undefined, className: cn(theme.card, (_a = theme.cardSizes) === null || _a === void 0 ? void 0 : _a[resolvedSize], isSelected && theme.selectedCard, isDisabled && theme.disabledCard, className), onClick: handleClick, onKeyDown: handleKeyDown, ...motionProps, ...props, children: [jsx("input", { type: inputType, id: inputId, name: isStandalone ? undefined : ctx === null || ctx === void 0 ? void 0 : ctx.name, value: value, checked: isSelected, disabled: isDisabled, onChange: () => { }, className: "sr-only", tabIndex: -1, "aria-hidden": true }), resolvedIndicatorPosition === "start" && indicatorNode, jsx("div", { className: theme.contentWrapper, children: children }), resolvedIndicatorPosition === "end" && indicatorNode, jsx(Ripple, { disabled: isDisabled })] }));
 });
 SelectableCardRoot.displayName = "SelectableCard";
 // ─── Compound Export ─────────────────────────────────────────────────────────

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

@@ -2,7 +2,7 @@ const selectableCardTheme = {
     group: "flex flex-col gap-3",
     card: 
     // Base layout — no justify-between; indicator position handled by render order
-    "relative flex items-start gap-3 rounded-[var(--radius-base)] cursor-pointer transition-[border-color,background-color,box-shadow,outline] duration-200 " +
+    "relative flex items-start gap-3 rounded-[var(--radius-base)] cursor-pointer transition-[border-color,background-color,box-shadow,outline] duration-[var(--motion-duration-base)] " +
         // Default state
         "border border-[var(--color-border)] bg-[var(--color-surface)] " +
         "dark:bg-[var(--color-background)] " +

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

@@ -12,7 +12,7 @@
 const switchTheme = {
     container: "flex w-full justify-between items-center gap-4",
     // Structural base only — no state colors (those live in `trackStates`)
-    track: "group rounded-full cursor-pointer shadow-inner-real-sm transition-colors duration-500 motion-reduce:transition-none outline-1 outline-[var(--color-border)] peer-focus-visible:outline-2 peer-focus-visible:outline-offset-2 peer-focus-visible:outline-[var(--color-primary-600)]",
+    track: "group rounded-full cursor-pointer shadow-inner-real-sm transition-colors duration-[var(--motion-duration-slowest)] motion-reduce:transition-none outline-1 outline-[var(--color-border)] peer-focus-visible:outline-2 peer-focus-visible:outline-offset-2 peer-focus-visible:outline-[var(--color-primary-600)]",
     // Resolved in JS and layered via cn() so later keys win (tailwind-merge dedupes bg-*).
     // No `invalid` key: a switch is binary — on and off are both valid values, so there is
     // nothing to validate. (See §9 carve-out: invalid only applies to controls with a value.)
@@ -25,7 +25,7 @@ const switchTheme = {
     // off-track, which is never white). ON state: Switch.tsx swaps the fill to
     // --color-primary-contrast so the knob stays visible on any primary track — white
     // on a dark primary, dark on a light primary (the near-white-primary case).
-    thumb: "rounded-full bg-gradient-to-b from-neutral-200 via-neutral-50 to-white shadow-real-lg border-t border-white/80 dark:border-white/20 transition-shadow duration-300 motion-reduce:transition-none",
+    thumb: "rounded-full bg-gradient-to-b from-neutral-200 via-neutral-50 to-white shadow-real-lg border-t border-white/80 dark:border-white/20 transition-shadow duration-[var(--motion-duration-slow)] motion-reduce:transition-none",
     description: "text-sm text-[var(--color-text-muted)] -mt-1.5",
     trackSizes: {
         sm: "w-9 h-5",

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

@@ -35,7 +35,7 @@ const timePickerTheme = {
     // Selected value text style
     valueTextStyle: "text-[var(--color-text-primary)]",
     // Clear button styles (positioned between left content and right icon)
-    clearButtonStyle: "absolute right-8 top-1/2 -translate-y-1/2 p-1 rounded text-[var(--color-text-muted)] hover:text-[var(--color-text-primary)] hover:bg-[var(--color-background-secondary)] transition-colors z-10",
+    clearButtonStyle: "absolute right-8 top-1/2 -translate-y-1/2 p-1 rounded text-[var(--color-text-muted)] hover:text-[var(--color-text-primary)] hover:bg-[var(--color-surface)] transition-colors z-10",
     // Dropdown container styles (TimePicker-specific)
     // Width is controlled by trigger size via estimatedWidth parameter
     dropdownStyle: "fixed z-[1000] backdrop-blur-md border border-[var(--color-border)] rounded-[var(--form-radius)] shadow-lg overflow-hidden",

package/dist/components/forms/TimePicker/TimePickerTrigger.js

@@ -48,7 +48,7 @@ const TimePickerTrigger = ({ id, disabled, isOpen, state = 'default', size = 'md
             ), children: [jsxs("div", { className: "relative flex-1", children: [jsx("input", { ref: inputRef, id: id, type: "text", inputMode: "numeric", value: inputValue, onChange: (e) => onInputChange(e.target.value), onFocus: onInputFocus, onKeyDown: onInputKeyDown, placeholder: placeholder, maxLength: 5, disabled: disabled, className: cn(inputStyle, sizeStyle, hasStartIcon && iconStartPadding), role: "combobox", "aria-expanded": isOpen, "aria-haspopup": "dialog", "aria-controls": dialogId, "aria-label": "Enter time", "aria-invalid": ariaInvalid, "aria-describedby": ariaDescribedby, autoComplete: "off" }), iconStart !== undefined ? (iconStart && jsx("div", { className: iconStartStyle, children: iconStart })) : (jsx("div", { className: iconStartStyle, children: jsx(Clock, { className: "h-4 w-4" }) }))] }), format === '12h' && (jsx("button", { type: "button", onClick: onPeriodToggle, disabled: disabled, className: cn(periodToggleStyle, "shrink-0"), "aria-label": `Toggle AM/PM, current: ${period}`, tabIndex: -1, children: period || 'AM' })), clearable && hasValue && !disabled && (jsx("button", { type: "button", onClick: (e) => {
                         e.stopPropagation();
                         onClear === null || onClear === void 0 ? void 0 : onClear();
-                    }, className: "shrink-0 p-0.5 rounded text-[var(--color-text-muted)] hover:text-[var(--color-text-primary)] hover:bg-[var(--color-background-secondary)] transition-colors", "aria-label": "Clear time", tabIndex: -1, children: jsx(X, { className: "w-4 h-4" }) })), iconEnd !== undefined ? (iconEnd && (jsx("span", { className: "shrink-0 flex items-center pr-3 pointer-events-none text-[var(--color-text-muted)]", children: iconEnd }))) : (jsx("span", { className: "shrink-0 flex items-center pr-3 pointer-events-none text-[var(--color-text-muted)]", children: jsx(CaretUpDown, { className: "h-4 w-4" }) }))] }) }));
+                    }, className: "shrink-0 p-0.5 rounded text-[var(--color-text-muted)] hover:text-[var(--color-text-primary)] hover:bg-[var(--color-surface)] transition-colors", "aria-label": "Clear time", tabIndex: -1, children: jsx(X, { className: "w-4 h-4" }) })), iconEnd !== undefined ? (iconEnd && (jsx("span", { className: "shrink-0 flex items-center pr-3 pointer-events-none text-[var(--color-text-muted)]", children: iconEnd }))) : (jsx("span", { className: "shrink-0 flex items-center pr-3 pointer-events-none text-[var(--color-text-muted)]", children: jsx(CaretUpDown, { className: "h-4 w-4" }) }))] }) }));
 };
 
 export { TimePickerTrigger };

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

@@ -130,13 +130,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 +151,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;