@vantageos/mosaic 0.2.1 → 0.3.0-alpha.1

package/dist/preact/forms.d.ts

@@ -0,0 +1,875 @@
+import * as react_hook_form from 'react-hook-form';
+import { FieldValues, UseFormReturn, Path, ControllerRenderProps, ControllerFieldState, UseFormStateReturn, ArrayPath, FieldArrayWithId, FieldArray as FieldArray$1 } from 'react-hook-form';
+import { z, ZodSchema, ZodType } from 'zod';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode, ReactElement } from 'react';
+
+/**
+ * Validation timing modes. Mosaic default is "onBlur" — Chi co-validated decision
+ * (Day 102 DM). RHF's full Mode union supports more values; we narrow to the three
+ * timings that are safe and predictable for cross-runtime consumers.
+ */
+declare const MosaicFormModeSchema: z.ZodEnum<["onBlur", "onChange", "onSubmit"]>;
+type MosaicFormMode = z.infer<typeof MosaicFormModeSchema>;
+/**
+ * Options accepted by `useMosaicForm`. The Zod schema for the form payload is
+ * passed separately (not parsed inside this schema) because it carries runtime
+ * type information that the consumer's TSchema generic propagates through.
+ */
+declare const UseMosaicFormOptionsSchema: z.ZodObject<{
+    mode: z.ZodDefault<z.ZodEnum<["onBlur", "onChange", "onSubmit"]>>;
+}, "strip", z.ZodTypeAny, {
+    mode: "onBlur" | "onChange" | "onSubmit";
+}, {
+    mode?: "onBlur" | "onChange" | "onSubmit" | undefined;
+}>;
+
+/**
+ * Public options to {@link useMosaicForm}. The Zod `schema` is the runtime
+ * validator (and the source of truth for the form payload type). `mode`
+ * defaults to `"onBlur"` per Chi co-validated decision (Day 102).
+ */
+interface UseMosaicFormOptions<TSchema extends ZodType> {
+    schema: TSchema;
+    defaultValues: Partial<ReturnType<TSchema["parse"]>> | ReturnType<TSchema["parse"]>;
+    mode?: MosaicFormMode;
+}
+/**
+ * Return type — the standard RHF `UseFormReturn` extended with two Mosaic
+ * metadata fields so consumers (FormField, SubmitButton, FormProvider) can
+ * inspect the active schema + timing without re-deriving them.
+ */
+type UseMosaicFormReturn<TFieldValues extends FieldValues = FieldValues> = UseFormReturn<TFieldValues> & {
+    mosaicSchema: ZodSchema;
+    mosaicMode: MosaicFormMode;
+};
+/**
+ * Cross-runtime wrapper around `react-hook-form` + `@hookform/resolvers/zod`.
+ *
+ * - Validates options through Zod (`UseMosaicFormOptionsSchema`) so an invalid
+ *   `mode` fails loudly at hook-call time rather than silently degrading.
+ * - Attaches the schema + mode to the return object as `mosaicSchema` and
+ *   `mosaicMode` for downstream Mosaic consumers (FieldArray will read these).
+ *
+ * Compatible with FieldArray (T16) — the return shape extends RHF's, so
+ * `useFieldArray({ control: form.control, name: ... })` works verbatim.
+ */
+declare function useMosaicForm<TSchema extends ZodType>(options: UseMosaicFormOptions<TSchema>): UseMosaicFormReturn<ReturnType<TSchema["parse"]> & FieldValues>;
+
+interface FormProviderProps<TValues extends FieldValues = FieldValues> {
+    form: UseMosaicFormReturn<TValues>;
+    children: ReactNode;
+}
+/**
+ * Wraps `react-hook-form`'s native `<FormProvider>` AND a Mosaic-specific
+ * context that carries the extended metadata (`mosaicSchema`, `mosaicMode`).
+ * Consumer components read either context — Mosaic's own for metadata,
+ * RHF's for register/control/handleSubmit access.
+ */
+declare function FormProvider<TValues extends FieldValues = FieldValues>({ form, children, }: FormProviderProps<TValues>): react_jsx_runtime.JSX.Element;
+/**
+ * Read the Mosaic-extended form context. Throws if called outside a
+ * `<FormProvider>` so consumer bugs surface immediately.
+ *
+ * Generic `TValues` lets callers narrow back to their original form shape.
+ */
+declare function useMosaicFormContext<TValues extends FieldValues = FieldValues>(): UseMosaicFormReturn<TValues>;
+
+interface FormFieldRenderArgs<TValues extends FieldValues = FieldValues> {
+    field: ControllerRenderProps<TValues>;
+    fieldState: ControllerFieldState;
+    formState: UseFormStateReturn<TValues>;
+}
+interface FormFieldProps<TValues extends FieldValues = FieldValues> {
+    name: Path<TValues>;
+    children: (args: FormFieldRenderArgs<TValues>) => ReactElement;
+}
+/**
+ * Render-prop wrapper around RHF's `Controller`. Pulls `control` from the
+ * surrounding `<FormProvider>` so consumers never thread it manually.
+ */
+declare function FormField<TValues extends FieldValues = FieldValues>({ name, children, }: FormFieldProps<TValues>): react_jsx_runtime.JSX.Element;
+
+/**
+ * ErrorDisplay accepts an RHF-shaped field error plus an optional consumer
+ * message map for i18n. The structure mirrors RHF `FieldError`:
+ * `{ type: string, message?: string }`.
+ */
+declare const FieldErrorShapeSchema: z.ZodObject<{
+    type: z.ZodString;
+    message: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    type: string;
+    message?: string | undefined;
+}, {
+    type: string;
+    message?: string | undefined;
+}>;
+declare const ErrorDisplayPropsSchema: z.ZodObject<{
+    error: z.ZodOptional<z.ZodObject<{
+        type: z.ZodString;
+        message: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        type: string;
+        message?: string | undefined;
+    }, {
+        type: string;
+        message?: string | undefined;
+    }>>;
+    messageMap: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+}, "strip", z.ZodTypeAny, {
+    error?: {
+        type: string;
+        message?: string | undefined;
+    } | undefined;
+    messageMap?: Record<string, string> | undefined;
+}, {
+    error?: {
+        type: string;
+        message?: string | undefined;
+    } | undefined;
+    messageMap?: Record<string, string> | undefined;
+}>;
+type FieldErrorShape = z.infer<typeof FieldErrorShapeSchema>;
+
+interface ErrorDisplayProps {
+    error?: FieldErrorShape;
+    messageMap?: Record<string, string>;
+    className?: string;
+}
+/**
+ * Single-field error formatter. Renders nothing when `error` is undefined
+ * (no error to show), otherwise emits a `role="alert"` element with the
+ * resolved message. Message resolution is delegated to the pure
+ * `formatErrorMessage` helper so React and Preact runtimes share behavior.
+ */
+declare function ErrorDisplay({ error, messageMap, className }: ErrorDisplayProps): react_jsx_runtime.JSX.Element | null;
+
+interface SubmitButtonProps {
+    label?: string;
+    loadingLabel?: string;
+    className?: string;
+}
+/**
+ * Form submit button bound to the surrounding `<FormProvider>` form state.
+ * Disabled while `formState.isValid` is false OR `formState.isSubmitting`
+ * is true. While submitting, the loading label replaces the default label.
+ */
+declare function SubmitButton(props: SubmitButtonProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Input primitive props — bound to the surrounding `FormProvider` by `name`.
+ *
+ * - `name` selects a property on the form values (RHF path).
+ * - `type` covers the 5 baseline text-like HTML input types (T11 scope).
+ * - `placeholder` / `disabled` / `autoComplete` are passthrough DOM props.
+ * - `label` is consumer-driven i18n: the caller supplies the localized string,
+ *   the component never renders raw alphabetic text as JSXText children.
+ *
+ * Field primitives outside this 5-type baseline (checkbox/radio/file/etc.)
+ * land in dedicated T12-T20 components per `docs/v0.3.0-plan.md` §7.
+ */
+declare const InputTypeSchema: z.ZodEnum<["text", "email", "password", "number", "url"]>;
+declare const InputPropsSchema: z.ZodObject<{
+    name: z.ZodString;
+    type: z.ZodOptional<z.ZodDefault<z.ZodEnum<["text", "email", "password", "number", "url"]>>>;
+    placeholder: z.ZodOptional<z.ZodString>;
+    disabled: z.ZodOptional<z.ZodBoolean>;
+    autoComplete: z.ZodOptional<z.ZodString>;
+    label: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    label: string;
+    type?: "number" | "text" | "email" | "url" | "password" | undefined;
+    disabled?: boolean | undefined;
+    placeholder?: string | undefined;
+    autoComplete?: string | undefined;
+}, {
+    name: string;
+    label: string;
+    type?: "number" | "text" | "email" | "url" | "password" | undefined;
+    disabled?: boolean | undefined;
+    placeholder?: string | undefined;
+    autoComplete?: string | undefined;
+}>;
+type InputType = z.infer<typeof InputTypeSchema>;
+
+interface InputProps<TValues extends FieldValues = FieldValues> {
+    name: Path<TValues>;
+    /** HTML input type. Defaults to `"text"`. */
+    type?: InputType;
+    /** Consumer-driven i18n label. Wired via `<label htmlFor>` to the input. */
+    label: string;
+    placeholder?: string;
+    disabled?: boolean;
+    autoComplete?: string;
+    /** Optional consumer override for the wrapping element id. */
+    id?: string;
+    /** Optional error code → message map for i18n. */
+    messageMap?: Record<string, string>;
+    className?: string;
+    inputClassName?: string;
+    errorClassName?: string;
+}
+/**
+ * Cross-runtime Input primitive (forms category, T11). Binds an `<input>` to
+ * the surrounding `<FormProvider>` via `react-hook-form`'s `Controller`.
+ *
+ * Preact runtime — `react` / `react-dom` are aliased to `preact/compat` at
+ * tsup build time per Standard §18.2. JSX is identical to the React runtime;
+ * runtime-agnostic logic lives in `src/components/forms/Input.logic.ts`.
+ */
+declare function Input<TValues extends FieldValues = FieldValues>({ name, type, label, placeholder, disabled, autoComplete, id, messageMap, className, inputClassName, errorClassName, }: InputProps<TValues>): react_jsx_runtime.JSX.Element;
+
+/**
+ * Pure helpers for Textarea, shared by React + Preact runtimes.
+ *
+ * No DOM, no framework imports. Keeps the runtime surface a thin shell so
+ * Standard §18 cross-runtime parity holds by reference.
+ */
+declare const DEFAULT_TEXTAREA_ROWS = 3;
+/**
+ * Clamp an input value to `maxLength` characters. When `maxLength` is undefined
+ * (no cap), returns the value unchanged. When the input already fits, returns
+ * the value unchanged (identity — avoids needless state churn in RHF).
+ */
+declare function clampToMaxLength(value: string, maxLength: number | undefined): string;
+/**
+ * Resolve the effective `rows` attribute for the rendered <textarea>.
+ * Returns `DEFAULT_TEXTAREA_ROWS` when undefined or invalid (≤ 0).
+ */
+declare function resolveRows(rows: number | undefined): number;
+/**
+ * Compute the next height (in pixels) for an autoResize textarea given the
+ * `scrollHeight` reported by the DOM. Returned as a number; runtime applies it
+ * via `style.height = `${n}px``. Keeps the math testable without a DOM.
+ *
+ * Min height honored when scrollHeight is implausible (≤ 0 in jsdom).
+ */
+declare function computeAutoResizeHeight(scrollHeight: number, minHeightPx: number): number;
+
+/**
+ * Preact runtime mirror of `Textarea`. Identical JSX shape — tsup preactPass
+ * aliases `react`, `react-dom`, and JSX runtimes to `preact/compat` at build
+ * time per `mosaic-architecture-standard` §18.2.
+ *
+ * Shared with the React runtime via `Textarea.logic.ts` pure helpers
+ * (`resolveRows`, `clampToMaxLength`, `computeAutoResizeHeight`). The logic
+ * file is the parity contract; this file's JSX must remain byte-equivalent in
+ * structure to its React sibling for cross-runtime tests to pass.
+ */
+interface TextareaProps<TValues extends FieldValues = FieldValues> {
+    name: Path<TValues>;
+    rows?: number;
+    maxLength?: number;
+    autoResize?: boolean;
+    placeholder?: string;
+    disabled?: boolean;
+    label?: string;
+    className?: string;
+    errorMessageMap?: Record<string, string>;
+}
+declare function Textarea<TValues extends FieldValues = FieldValues>(props: TextareaProps<TValues>): react_jsx_runtime.JSX.Element;
+
+/**
+ * Pure helpers for FieldArray. Runtime-agnostic — covers ARIA id generation
+ * and aria-label conventions used by the React + Preact runtimes.
+ *
+ * `useFieldArray` itself is a thin wrapper around RHF's hook (live in the
+ * runtime layer) — these helpers are the cross-runtime contract that the
+ * wrapper and Storybook stories share.
+ */
+/** Default aria-label for the wrapping list element. */
+declare function buildListAriaLabel(name: string): string;
+/** Default aria-label for the per-item Remove button. */
+declare function buildRemoveAriaLabel(name: string, index: number): string;
+/** Default aria-label for the Add button (consumer-rendered). */
+declare function buildAddAriaLabel(name: string): string;
+/**
+ * After removing item at `removedIndex` from an array of `previousLength`
+ * items, return the index that should receive focus. Clamps to the last
+ * remaining index, or `-1` if the list became empty.
+ */
+declare function nextFocusIndexAfterRemove(previousLength: number, removedIndex: number): number;
+
+interface UseFieldArrayOptions<TValues extends FieldValues = FieldValues, TName extends ArrayPath<TValues> = ArrayPath<TValues>> {
+    name: TName;
+    control?: any;
+}
+declare function useFieldArray<TValues extends FieldValues = FieldValues, TName extends ArrayPath<TValues> = ArrayPath<TValues>>({ name, control }: UseFieldArrayOptions<TValues, TName>): react_hook_form.UseFieldArrayReturn<TValues, TName, "id">;
+interface FieldArrayRenderItemArgs<TValues extends FieldValues = FieldValues, TName extends ArrayPath<TValues> = ArrayPath<TValues>> {
+    field: FieldArrayWithId<TValues, TName, "id">;
+    index: number;
+}
+interface FieldArrayControls<TValues extends FieldValues = FieldValues, TName extends ArrayPath<TValues> = ArrayPath<TValues>> {
+    fields: ReadonlyArray<FieldArrayWithId<TValues, TName, "id">>;
+    append: (value: FieldArray$1<TValues, TName> | FieldArray$1<TValues, TName>[]) => void;
+    remove: (index?: number | number[]) => void;
+    move: (from: number, to: number) => void;
+    swap: (a: number, b: number) => void;
+}
+interface FieldArrayProps<TValues extends FieldValues = FieldValues, TName extends ArrayPath<TValues> = ArrayPath<TValues>> {
+    name: TName;
+    children: (args: FieldArrayRenderItemArgs<TValues, TName>, controls: FieldArrayControls<TValues, TName>) => ReactElement;
+    ariaLabel?: string;
+}
+/**
+ * Preact-runtime FieldArray. Identical JSX shape to the React variant —
+ * see `runtimes/react/components/forms/FieldArray.tsx` for full docs.
+ */
+declare function FieldArray<TValues extends FieldValues = FieldValues, TName extends ArrayPath<TValues> = ArrayPath<TValues>>({ name, children, ariaLabel }: FieldArrayProps<TValues, TName>): react_jsx_runtime.JSX.Element;
+
+/**
+ * Preact runtime mirror of `Checkbox`. Identical JSX shape — tsup preactPass
+ * aliases `react`, `react-dom`, and JSX runtimes to `preact/compat` at build
+ * time per `mosaic-architecture-standard` §18.2.
+ *
+ * Shared with the React runtime via `Checkbox.logic.ts` pure helpers
+ * (`resolveAriaChecked`, `resolveDescribedBy`). The logic file is the parity
+ * contract; this file's JSX must remain byte-equivalent in structure to its
+ * React sibling for cross-runtime tests to pass.
+ */
+interface CheckboxProps<TValues extends FieldValues = FieldValues> {
+    name: Path<TValues>;
+    label: string;
+    disabled?: boolean;
+    indeterminate?: boolean;
+    description?: string;
+    className?: string;
+    errorMessageMap?: Record<string, string>;
+}
+declare function Checkbox<TValues extends FieldValues = FieldValues>(props: CheckboxProps<TValues>): react_jsx_runtime.JSX.Element;
+
+/**
+ * MultiSelect props — multi-value dropdown with removable chip rendering for
+ * the currently selected items. The schema validates static, serializable
+ * props only. Runtime callbacks (RHF `field.onChange`, `field.onBlur`) are
+ * threaded by `FormField` and live on the React/Preact interface.
+ */
+declare const MultiSelectOptionSchema: z.ZodObject<{
+    value: z.ZodString;
+    label: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    value: string;
+    label: string;
+}, {
+    value: string;
+    label: string;
+}>;
+declare const MultiSelectPropsSchema: z.ZodObject<{
+    name: z.ZodString;
+    label: z.ZodString;
+    options: z.ZodArray<z.ZodObject<{
+        value: z.ZodString;
+        label: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        value: string;
+        label: string;
+    }, {
+        value: string;
+        label: string;
+    }>, "many">;
+    placeholder: z.ZodOptional<z.ZodString>;
+    disabled: z.ZodOptional<z.ZodBoolean>;
+    searchable: z.ZodOptional<z.ZodBoolean>;
+    maxItems: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    options: {
+        value: string;
+        label: string;
+    }[];
+    name: string;
+    label: string;
+    disabled?: boolean | undefined;
+    placeholder?: string | undefined;
+    searchable?: boolean | undefined;
+    maxItems?: number | undefined;
+}, {
+    options: {
+        value: string;
+        label: string;
+    }[];
+    name: string;
+    label: string;
+    disabled?: boolean | undefined;
+    placeholder?: string | undefined;
+    searchable?: boolean | undefined;
+    maxItems?: number | undefined;
+}>;
+type MultiSelectOption = z.infer<typeof MultiSelectOptionSchema>;
+
+interface MultiSelectProps {
+    name: string;
+    label: string;
+    options: MultiSelectOption[];
+    placeholder?: string;
+    disabled?: boolean;
+    searchable?: boolean;
+    maxItems?: number;
+    className?: string;
+}
+/**
+ * Multi-value dropdown. Bound to RHF via `FormField` — value lives at
+ * `form.values[name]` as `string[]`. Selected values render as removable
+ * chips; the dropdown lists only unselected options. WCAG-AA combobox
+ * pattern: `role=combobox aria-multiselectable=true`, chip removal via
+ * Backspace / Delete / per-chip close icon, Tab + Arrow nav.
+ */
+declare function MultiSelect(props: MultiSelectProps): react_jsx_runtime.JSX.Element;
+
+interface RadioGroupProps {
+    name: string;
+    label: string;
+    options: Array<{
+        value: string;
+        label: string;
+        description?: string;
+        disabled?: boolean;
+    }>;
+    orientation?: "vertical" | "horizontal";
+    disabled?: boolean;
+    className?: string;
+}
+/**
+ * Preact mirror of `runtimes/react/components/forms/RadioGroup.tsx`.
+ * The `react` import is aliased to `preact/compat` at tsup build time
+ * (Standard §18.2), so the body is identical by design.
+ *
+ * Uses native `<input type="radio">` elements + roving tabIndex.
+ * WAI-ARIA §3.10 radiogroup pattern: Arrow keys move focus AND select;
+ * Home/End jump to extremes; Space/Enter activate; disabled skipped.
+ */
+declare function RadioGroup(props: RadioGroupProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Select primitive — single-select dropdown with optional search.
+ *
+ * Combobox-pattern (APG): a trigger button (role=combobox) opens a listbox
+ * popup containing option rows. Optional in-popup search filters the visible
+ * options client-side. Cross-runtime (React 19 + Preact 10).
+ *
+ * The `name` is the react-hook-form field name used by the surrounding
+ * `<FormProvider>`. The render-prop wiring lives in FormField/Controller; this
+ * component is rendered INSIDE a FormField render prop and consumes the
+ * `field` callbacks directly (see Select.stories.tsx).
+ */
+declare const SelectOptionSchema: z.ZodObject<{
+    value: z.ZodString;
+    label: z.ZodString;
+    disabled: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+}, "strip", z.ZodTypeAny, {
+    value: string;
+    disabled: boolean;
+    label: string;
+}, {
+    value: string;
+    label: string;
+    disabled?: boolean | undefined;
+}>;
+type SelectOption = z.infer<typeof SelectOptionSchema>;
+declare const SelectPropsSchema: z.ZodObject<{
+    name: z.ZodString;
+    label: z.ZodString;
+    options: z.ZodArray<z.ZodObject<{
+        value: z.ZodString;
+        label: z.ZodString;
+        disabled: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    }, "strip", z.ZodTypeAny, {
+        value: string;
+        disabled: boolean;
+        label: string;
+    }, {
+        value: string;
+        label: string;
+        disabled?: boolean | undefined;
+    }>, "many">;
+    placeholder: z.ZodOptional<z.ZodString>;
+    disabled: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    searchable: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    locale: z.ZodDefault<z.ZodEnum<["en", "fr"]>>;
+}, "strip", z.ZodTypeAny, {
+    options: {
+        value: string;
+        disabled: boolean;
+        label: string;
+    }[];
+    disabled: boolean;
+    name: string;
+    label: string;
+    searchable: boolean;
+    locale: "en" | "fr";
+    placeholder?: string | undefined;
+}, {
+    options: {
+        value: string;
+        label: string;
+        disabled?: boolean | undefined;
+    }[];
+    name: string;
+    label: string;
+    disabled?: boolean | undefined;
+    placeholder?: string | undefined;
+    searchable?: boolean | undefined;
+    locale?: "en" | "fr" | undefined;
+}>;
+type SelectPropsValidated = z.infer<typeof SelectPropsSchema>;
+declare function validateSelectProps(raw: unknown): SelectPropsValidated;
+
+interface SelectProps<TValues extends FieldValues = FieldValues> {
+    name: Path<TValues>;
+    label: string;
+    options: SelectOption[];
+    placeholder?: string;
+    disabled?: boolean;
+    searchable?: boolean;
+    className?: string;
+    /** Optional i18n map passed through to `ErrorDisplay` for error type → message. */
+    errorMessageMap?: Record<string, string>;
+}
+/**
+ * Single-select dropdown primitive — combobox+listbox APG pattern.
+ * Preact 10 runtime. Wraps `FormField` (RHF Controller) and exposes error
+ * state via `ErrorDisplay`. WCAG-AA strict.
+ *
+ * The visible value-label is shown in the trigger button; the listbox popup
+ * uses `aria-activedescendant` to track keyboard focus without moving DOM focus
+ * (focus stays on the trigger or the search input).
+ */
+declare function Select<TValues extends FieldValues = FieldValues>({ name, label, options, placeholder, disabled, searchable, className, errorMessageMap, }: SelectProps<TValues>): react_jsx_runtime.JSX.Element;
+
+declare const SubmitButtonPropsSchema: z.ZodObject<{
+    label: z.ZodDefault<z.ZodString>;
+    loadingLabel: z.ZodDefault<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    label: string;
+    loadingLabel: string;
+}, {
+    label?: string | undefined;
+    loadingLabel?: string | undefined;
+}>;
+
+/**
+ * FormField props — the field `name` selects a property on the form values.
+ * Children are a render-prop receiving `field`, `fieldState`, `formState`
+ * from RHF Controller; that contract is enforced at the TypeScript layer.
+ */
+declare const FormFieldPropsSchema: z.ZodObject<{
+    name: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+}, {
+    name: string;
+}>;
+
+/**
+ * FormProvider props that need runtime validation are minimal — the `form`
+ * object comes from `useMosaicForm()` and carries its own typed contract,
+ * while `children` are framework JSX. This schema exists for future-proofing
+ * (e.g. optional `name` for nested form contexts).
+ */
+declare const FormProviderPropsSchema: z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    name?: string | undefined;
+}, {
+    name?: string | undefined;
+}>;
+
+/**
+ * Textarea — multi-line text input form primitive.
+ *
+ * Props contract (Zod-validated at boundary, mirrors React/Preact runtime types).
+ *
+ * - `name` — required, non-empty. Selects a property on the surrounding form values.
+ * - `rows` — default 3, integer ≥ 1. Maps to native textarea `rows` attribute.
+ * - `maxLength` — optional, integer ≥ 1. Caller-controlled length cap. Enforced by
+ *   pure logic helpers so React and Preact runtimes share gating semantics.
+ * - `autoResize` — default false. When true, runtime grows the textarea to fit
+ *   content (capped by CSS `max-height` if set by consumer).
+ * - `placeholder` — optional string.
+ * - `disabled` — optional boolean.
+ * - `label` — optional string (rendered above the textarea, bilingual-ready).
+ */
+declare const TextareaPropsSchema: z.ZodObject<{
+    name: z.ZodString;
+    rows: z.ZodDefault<z.ZodNumber>;
+    maxLength: z.ZodOptional<z.ZodNumber>;
+    autoResize: z.ZodDefault<z.ZodBoolean>;
+    placeholder: z.ZodOptional<z.ZodString>;
+    disabled: z.ZodOptional<z.ZodBoolean>;
+    label: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    rows: number;
+    autoResize: boolean;
+    disabled?: boolean | undefined;
+    maxLength?: number | undefined;
+    label?: string | undefined;
+    placeholder?: string | undefined;
+}, {
+    name: string;
+    disabled?: boolean | undefined;
+    maxLength?: number | undefined;
+    label?: string | undefined;
+    placeholder?: string | undefined;
+    rows?: number | undefined;
+    autoResize?: boolean | undefined;
+}>;
+type TextareaPropsValidated = z.infer<typeof TextareaPropsSchema>;
+declare function validateTextareaProps(raw: unknown): TextareaPropsValidated;
+
+/**
+ * FieldArray props — `name` selects the array path on the form values.
+ * `children` is a render-prop receiving `(field, index)` for each entry
+ * AND a third arg with the controls `{ append, remove, move, swap, fields }`.
+ * That contract is enforced at the TypeScript layer.
+ */
+declare const FieldArrayPropsSchema: z.ZodObject<{
+    name: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+}, {
+    name: string;
+}>;
+/**
+ * Options accepted by `useFieldArray` — thin re-export of the underlying
+ * RHF shape. We validate `name` here for parity with FieldArray.
+ */
+declare const UseFieldArrayOptionsSchema: z.ZodObject<{
+    name: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+}, {
+    name: string;
+}>;
+
+/**
+ * Checkbox — boolean form primitive with indeterminate state support.
+ *
+ * Props contract (Zod-validated at boundary, mirrors React/Preact runtime types).
+ *
+ * - `name` — required, non-empty. Selects a property on the surrounding form values.
+ * - `label` — required, non-empty. Rendered adjacent to the checkbox (bilingual-ready).
+ * - `disabled` — optional boolean. Maps to native `disabled` attribute.
+ * - `indeterminate` — optional boolean. When true, sets DOM `.indeterminate = true`
+ *   via ref and aria-checked="mixed". Controlled externally — the component does not
+ *   manage this state internally.
+ * - `description` — optional string. Wired via `aria-describedby` for screen readers.
+ */
+declare const CheckboxPropsSchema: z.ZodObject<{
+    name: z.ZodString;
+    label: z.ZodString;
+    disabled: z.ZodOptional<z.ZodBoolean>;
+    indeterminate: z.ZodOptional<z.ZodBoolean>;
+    description: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    label: string;
+    description?: string | undefined;
+    disabled?: boolean | undefined;
+    indeterminate?: boolean | undefined;
+}, {
+    name: string;
+    label: string;
+    description?: string | undefined;
+    disabled?: boolean | undefined;
+    indeterminate?: boolean | undefined;
+}>;
+type CheckboxPropsValidated = z.infer<typeof CheckboxPropsSchema>;
+declare function validateCheckboxProps(raw: unknown): CheckboxPropsValidated;
+
+/**
+ * Pure helpers for Checkbox, shared by React + Preact runtimes.
+ *
+ * No DOM, no framework imports. Keeps the runtime surface a thin shell so
+ * Standard §18 cross-runtime parity holds by reference.
+ */
+/**
+ * Resolve the effective `aria-checked` attribute value for the rendered
+ * `<input type="checkbox">`.
+ *
+ * - `indeterminate=true` → `"mixed"` (ARIA tri-state semantics).
+ * - `checked=true`       → `true`.
+ * - otherwise            → `false`.
+ *
+ * The DOM `.indeterminate` property must be set via a ref — it is not an HTML
+ * attribute and cannot be set declaratively. This helper only computes the
+ * ARIA value; the runtime is responsible for the DOM side-effect.
+ */
+declare function resolveAriaChecked(checked: boolean, indeterminate: boolean | undefined): boolean | "mixed";
+/**
+ * Compute the accessible description ID to wire into `aria-describedby`.
+ *
+ * Returns the `descriptionId` when a `description` string is provided,
+ * or `undefined` when no description is present so the attribute is omitted.
+ * A falsy description short-circuits to prevent empty `aria-describedby=""`.
+ */
+declare function resolveDescribedBy(descriptionId: string, description: string | undefined, hasError: boolean, errorId: string): string | undefined;
+
+/**
+ * RadioGroup — mutually exclusive single-choice form primitive.
+ *
+ * - `name`         RHF field name (must match `<FormField name="…">` parent).
+ * - `options`      Ordered list of radio descriptors. Each carries a stable
+ *                  `value` (the form value when selected), a visible `label`,
+ *                  and an optional `description` exposed via aria-describedby.
+ * - `orientation`  Visual layout — vertical (default) or horizontal. Controls
+ *                  Arrow key mapping (Up/Down vs Left/Right per WAI-ARIA).
+ * - `disabled`     Disables the whole group; individual options can also be
+ *                  disabled via `options[i].disabled`.
+ * - `label`        Visible group label rendered above the radios; wired to
+ *                  `role="radiogroup"` via `aria-labelledby`.
+ *
+ * WCAG-AA contract is asserted by the runtime layer:
+ *   - container has `role="radiogroup"` + `aria-labelledby` + `aria-orientation`.
+ *   - each radio has `role="radio"` + `aria-checked` + `tabIndex` roving.
+ *   - Arrow keys move focus AND selection (WAI-ARIA radiogroup pattern §3.10).
+ *   - Space/Enter activates the currently focused radio.
+ *   - Disabled radios are skipped during keyboard navigation.
+ */
+declare const RadioGroupOptionSchema: z.ZodObject<{
+    value: z.ZodString;
+    label: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    disabled: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+}, "strip", z.ZodTypeAny, {
+    value: string;
+    disabled: boolean;
+    label: string;
+    description?: string | undefined;
+}, {
+    value: string;
+    label: string;
+    description?: string | undefined;
+    disabled?: boolean | undefined;
+}>;
+type RadioGroupOption = z.infer<typeof RadioGroupOptionSchema>;
+declare const RadioGroupPropsSchema: z.ZodObject<{
+    name: z.ZodString;
+    label: z.ZodString;
+    options: z.ZodArray<z.ZodObject<{
+        value: z.ZodString;
+        label: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        disabled: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    }, "strip", z.ZodTypeAny, {
+        value: string;
+        disabled: boolean;
+        label: string;
+        description?: string | undefined;
+    }, {
+        value: string;
+        label: string;
+        description?: string | undefined;
+        disabled?: boolean | undefined;
+    }>, "many">;
+    orientation: z.ZodDefault<z.ZodEnum<["vertical", "horizontal"]>>;
+    disabled: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    locale: z.ZodDefault<z.ZodEnum<["en", "fr"]>>;
+}, "strip", z.ZodTypeAny, {
+    options: {
+        value: string;
+        disabled: boolean;
+        label: string;
+        description?: string | undefined;
+    }[];
+    disabled: boolean;
+    name: string;
+    label: string;
+    orientation: "vertical" | "horizontal";
+    locale: "en" | "fr";
+}, {
+    options: {
+        value: string;
+        label: string;
+        description?: string | undefined;
+        disabled?: boolean | undefined;
+    }[];
+    name: string;
+    label: string;
+    disabled?: boolean | undefined;
+    orientation?: "vertical" | "horizontal" | undefined;
+    locale?: "en" | "fr" | undefined;
+}>;
+type RadioGroupPropsValidated = z.infer<typeof RadioGroupPropsSchema>;
+declare function validateRadioGroupProps(raw: unknown): RadioGroupPropsValidated;
+
+/**
+ * RadioGroup.logic.ts — pure, framework-agnostic logic.
+ * No JSX here — shared between React 19 and Preact 10 runtimes.
+ *
+ * WCAG-AA ARIA + roving tabindex spec (WAI-ARIA Authoring Practices §3.10):
+ *
+ *   - role="radiogroup" on container
+ *   - role="radio" + aria-checked on each radio
+ *   - aria-labelledby on container points to the visible group label id
+ *   - aria-labelledby on each radio points to its own option label span id
+ *   - aria-describedby on a radio points to its description span id (if present)
+ *   - Roving tabindex:
+ *       * If a value is selected → the SELECTED radio has tabIndex 0, all
+ *         others tabIndex -1.
+ *       * If nothing is selected → the FIRST enabled radio has tabIndex 0,
+ *         all others tabIndex -1 (so Tab can enter the group).
+ *   - Arrow keys (Up/Down vertical, Left/Right horizontal) MOVE focus to the
+ *     next/previous enabled radio AND select it (focus + selection sync — this
+ *     is the radiogroup pattern, distinct from tabs).
+ *   - Home / End jump to first / last enabled radio AND select it.
+ *   - Space / Enter on a non-selected focused radio selects it (no-op when
+ *     already selected).
+ *   - Disabled radios are skipped during arrow nav (findNextEnabledIndex).
+ */
+
+type RadioOrientation = "vertical" | "horizontal";
+/**
+ * Returns the prev/next key pair for the given orientation.
+ *
+ * Vertical group → ArrowUp/ArrowDown.
+ * Horizontal group → ArrowLeft/ArrowRight.
+ *
+ * (Per WAI-ARIA radiogroup pattern, only one axis is used; the perpendicular
+ * arrow keys are NOT intercepted — they let the user move out of the group.)
+ */
+declare function getNavKeys(orientation: RadioOrientation): {
+    prev: string;
+    next: string;
+};
+/**
+ * Finds the next enabled (non-disabled) option index in `direction`,
+ * wrapping around at boundaries. Returns `currentIndex` if every option
+ * is disabled (defensive — Zod schema requires options.length ≥ 1 but does
+ * not forbid all-disabled).
+ */
+declare function findNextEnabledIndex(options: Array<Pick<RadioGroupOption, "disabled">>, currentIndex: number, direction: 1 | -1): number;
+/** First enabled option index, or 0 if all are disabled. */
+declare function findFirstEnabledIndex(options: Array<Pick<RadioGroupOption, "disabled">>): number;
+/** Last enabled option index, or `options.length - 1` if all are disabled. */
+declare function findLastEnabledIndex(options: Array<Pick<RadioGroupOption, "disabled">>): number;
+/**
+ * Returns the index of the option whose `value` matches `selectedValue`,
+ * or -1 if no option is selected (or the selected value points to a disabled
+ * option — selected-but-disabled is a valid state, so we DON'T filter here).
+ */
+declare function findSelectedIndex(options: Array<Pick<RadioGroupOption, "value">>, selectedValue: string | undefined): number;
+/**
+ * Roving tabindex resolver — returns the index that should carry tabIndex=0.
+ *
+ *   - If something is selected → the selected index (focus follows selection).
+ *   - Otherwise → the first enabled option (so Tab can enter the group).
+ */
+declare function getRovingTabIndex(options: Array<Pick<RadioGroupOption, "value" | "disabled">>, selectedValue: string | undefined): number;
+/** Stable DOM id for the group label (linked by container aria-labelledby). */
+declare function getGroupLabelId(instanceId: string, name: string): string;
+/** Stable DOM id for an option label span (linked by radio aria-labelledby). */
+declare function getOptionLabelId(instanceId: string, name: string, optionValue: string): string;
+/** Stable DOM id for an option description span (linked by radio aria-describedby). */
+declare function getOptionDescriptionId(instanceId: string, name: string, optionValue: string): string;
+/** Tailwind classes for the root radiogroup container. */
+declare function getGroupClasses(orientation: RadioOrientation): string;
+/** Tailwind classes for a single radio row (label + control + description). */
+declare function getOptionRowClasses(isDisabled: boolean, orientation: RadioOrientation): string;
+/** Tailwind classes for the visible radio control (the round dot). */
+declare function getRadioControlClasses(isSelected: boolean, isDisabled: boolean): string;
+/** Whether a keyboard event should activate the focused radio (Space / Enter). */
+declare function isActivationKey(key: string): boolean;
+
+export { Checkbox, type CheckboxProps, CheckboxPropsSchema, type CheckboxPropsValidated, DEFAULT_TEXTAREA_ROWS, ErrorDisplay, type ErrorDisplayProps, ErrorDisplayPropsSchema, FieldArray, type FieldArrayControls, type FieldArrayProps, FieldArrayPropsSchema, type FieldArrayRenderItemArgs, type FieldErrorShape, FieldErrorShapeSchema, FormField, type FormFieldProps, FormFieldPropsSchema, type FormFieldRenderArgs, FormProvider, type FormProviderProps, FormProviderPropsSchema, Input, type InputProps, InputPropsSchema, type InputType, InputTypeSchema, type MosaicFormMode, MosaicFormModeSchema, MultiSelect, type MultiSelectOption, MultiSelectOptionSchema, type MultiSelectProps, MultiSelectPropsSchema, RadioGroup, type RadioGroupOption, RadioGroupOptionSchema, type RadioGroupProps, RadioGroupPropsSchema, type RadioGroupPropsValidated, type RadioOrientation, Select, type SelectOption, SelectOptionSchema, type SelectProps, SelectPropsSchema, type SelectPropsValidated, SubmitButton, type SubmitButtonProps, SubmitButtonPropsSchema, Textarea, type TextareaProps, TextareaPropsSchema, type TextareaPropsValidated, type UseFieldArrayOptions, UseFieldArrayOptionsSchema, type UseMosaicFormOptions, UseMosaicFormOptionsSchema, type UseMosaicFormReturn, buildAddAriaLabel, buildListAriaLabel, buildRemoveAriaLabel, clampToMaxLength, computeAutoResizeHeight, findFirstEnabledIndex, findLastEnabledIndex, findNextEnabledIndex, findSelectedIndex, getGroupClasses, getGroupLabelId, getNavKeys, getOptionDescriptionId, getOptionLabelId, getOptionRowClasses, getRadioControlClasses, getRovingTabIndex, isActivationKey, nextFocusIndexAfterRemove, resolveAriaChecked, resolveDescribedBy, resolveRows, useFieldArray, useMosaicForm, useMosaicFormContext, validateCheckboxProps, validateRadioGroupProps, validateSelectProps, validateTextareaProps };