@vantageos/mosaic 0.2.2 → 0.3.0

package/dist/index-CwXVgtGb.d.cts

@@ -0,0 +1,917 @@
+import * as react_hook_form from 'react-hook-form';
+import { FieldValues, UseFormReturn, Path, ControllerRenderProps, ControllerFieldState, UseFormStateReturn, ArrayPath, FieldArrayWithId, FieldArray as FieldArray$1, useFieldArray as useFieldArray$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;
+}>;
+type UseMosaicFormOptions$1 = z.infer<typeof UseMosaicFormOptionsSchema>;
+declare function validateOptions(raw: unknown): UseMosaicFormOptions$1;
+
+/**
+ * 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>;
+type InputPropsValidated = z.infer<typeof InputPropsSchema>;
+
+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`.
+ *
+ * - Consumer-driven i18n: every user-visible string flows in as a prop.
+ * - a11y: `<label htmlFor>` pair, `aria-invalid` toggled by validation state,
+ *   `aria-describedby` linking the error element when present.
+ * - Validation timing inherits the form's `mode` (default `"onBlur"`, Day 102 DM).
+ */
+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;
+
+interface TextareaProps<TValues extends FieldValues = FieldValues> {
+    name: Path<TValues>;
+    rows?: number;
+    maxLength?: number;
+    autoResize?: boolean;
+    placeholder?: string;
+    disabled?: boolean;
+    label?: string;
+    className?: string;
+    /** Optional i18n map passed through to `ErrorDisplay` for error type → message. */
+    errorMessageMap?: Record<string, string>;
+}
+/**
+ * Multi-line text input form primitive.
+ *
+ * Wraps `FormField` (RHF Controller) and renders a native `<textarea>` with:
+ * - `rows` default 3 (see `resolveRows`).
+ * - `maxLength` enforcement at the onChange boundary via `clampToMaxLength`.
+ * - Optional `autoResize` — grows the element to fit content on each input event.
+ * - `aria-invalid` toggled when the field has a validation error.
+ * - `aria-describedby` wired to the `ErrorDisplay` element when an error exists.
+ * - Bilingual-ready: `label`, `placeholder`, and `errorMessageMap` are caller-supplied
+ *   strings — Mosaic does not bake locale-specific copy into the component.
+ */
+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;
+    /**
+     * Optional control override. When omitted, `useFieldArray` reads control
+     * from the surrounding `<FormProvider>`, mirroring `FormField`'s contract.
+     */
+    control?: any;
+}
+/**
+ * Public return type for `useFieldArray` — mirrors RHF's native return
+ * (`fields`, `append`, `remove`, `move`, `swap`, plus `insert`, `prepend`,
+ * `replace`, `update` for advanced cases).
+ */
+type UseFieldArrayReturn<TValues extends FieldValues = FieldValues, TName extends ArrayPath<TValues> = ArrayPath<TValues>> = ReturnType<typeof useFieldArray$1<TValues, TName, "id">>;
+/**
+ * Thin wrapper around RHF's `useFieldArray`. Reads `control` from the
+ * surrounding `<FormProvider>` when not provided, mirroring `FormField`.
+ * Exposes `{ fields, append, remove, move, swap }` and the rest of RHF's
+ * native return for advanced cases (insert, prepend, replace, update).
+ */
+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;
+    /**
+     * Render-prop called for each item. Receives the RHF field (with stable
+     * `.id`), the current index, and the controls bag for inline buttons.
+     */
+    children: (args: FieldArrayRenderItemArgs<TValues, TName>, controls: FieldArrayControls<TValues, TName>) => ReactElement;
+    /** Override the default `aria-label` on the list root. */
+    ariaLabel?: string;
+}
+/**
+ * Render-prop wrapper around RHF's `useFieldArray`. Reads control from the
+ * surrounding `<FormProvider>`. Emits an a11y-compliant `role="list"` shell
+ * with `role="listitem"` rows keyed by RHF's stable `field.id` (NOT array
+ * index — required for stable React reconciliation across move/remove).
+ */
+declare function FieldArray<TValues extends FieldValues = FieldValues, TName extends ArrayPath<TValues> = ArrayPath<TValues>>({ name, children, ariaLabel }: FieldArrayProps<TValues, TName>): react_jsx_runtime.JSX.Element;
+
+interface CheckboxProps<TValues extends FieldValues = FieldValues> {
+    name: Path<TValues>;
+    label: string;
+    disabled?: boolean;
+    indeterminate?: boolean;
+    description?: string;
+    className?: string;
+    /** Optional i18n map passed through to `ErrorDisplay` for error type → message. */
+    errorMessageMap?: Record<string, string>;
+}
+/**
+ * Boolean checkbox form primitive with indeterminate state support.
+ *
+ * Wraps `FormField` (RHF Controller) and renders a native `<input type="checkbox">` with:
+ * - `indeterminate` prop — sets DOM `.indeterminate = true` via ref + `aria-checked="mixed"`.
+ * - `description` — rendered in a `<span>` and wired via `aria-describedby`.
+ * - `aria-invalid` toggled when the field has a validation error.
+ * - `aria-describedby` includes the error ID when an error exists.
+ * - Bilingual-ready: `label`, `description`, and `errorMessageMap` are caller-supplied.
+ */
+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;
+}
+/**
+ * RadioGroup — mutually exclusive single-choice primitive, WCAG-AA compliant.
+ *
+ * Uses native `<input type="radio">` elements for browser-native semantics
+ * while implementing roving tabIndex + Arrow key selection sync per the
+ * WAI-ARIA radiogroup pattern (§3.10).
+ *
+ * ARIA contract:
+ *   - `role="radiogroup"` + `aria-labelledby` on the container (fieldset equivalent)
+ *   - Native `<input type="radio">` per option — browser provides role + aria-checked
+ *   - `aria-labelledby` per input → its `<label>` span id
+ *   - `aria-describedby` per input → its description span id (when present)
+ *   - Roving tabIndex — selected radio has tabIndex 0, all others -1
+ *   - Arrow keys move focus AND selection (WAI-ARIA §3.10)
+ *   - Home/End jump to first/last enabled option
+ *   - Space/Enter activate the focused radio
+ *   - Disabled radios are skipped during arrow navigation
+ */
+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.
+ * 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;
+
+/**
+ * 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;
+}>;
+
+/**
+ * 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;
+}>;
+
+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;
+}>;
+type SubmitButtonPropsValidated = z.infer<typeof SubmitButtonPropsSchema>;
+declare function validateSubmitButtonProps(raw: unknown): SubmitButtonPropsValidated;
+
+/**
+ * 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 { findSelectedIndex as $, SelectPropsSchema as A, type SelectPropsValidated as B, Checkbox as C, DEFAULT_TEXTAREA_ROWS as D, ErrorDisplay as E, type FieldErrorShape as F, SubmitButton as G, SubmitButtonPropsSchema as H, type InputType as I, TextareaPropsSchema as J, type TextareaPropsValidated as K, type UseMosaicFormOptions$1 as L, type MosaicFormMode as M, UseMosaicFormOptionsSchema as N, type UseMosaicFormReturn as O, buildAddAriaLabel as P, buildListAriaLabel as Q, RadioGroup as R, type SelectOption as S, Textarea as T, UseFieldArrayOptionsSchema as U, buildRemoveAriaLabel as V, clampToMaxLength as W, computeAutoResizeHeight as X, findFirstEnabledIndex as Y, findLastEnabledIndex as Z, findNextEnabledIndex as _, type MultiSelectOption as a, getGroupClasses as a0, getGroupLabelId as a1, getNavKeys as a2, getOptionDescriptionId as a3, getOptionLabelId as a4, getOptionRowClasses as a5, getRadioControlClasses as a6, getRovingTabIndex as a7, isActivationKey as a8, nextFocusIndexAfterRemove as a9, type UseFieldArrayOptions as aA, type UseFieldArrayReturn as aB, type UseMosaicFormOptions as aC, resolveAriaChecked as aa, resolveDescribedBy as ab, resolveRows as ac, useFieldArray as ad, useMosaicForm as ae, useMosaicFormContext as af, validateCheckboxProps as ag, validateOptions as ah, validateRadioGroupProps as ai, validateSelectProps as aj, validateSubmitButtonProps as ak, validateTextareaProps as al, type CheckboxProps as am, type ErrorDisplayProps as an, type FieldArrayControls as ao, type FieldArrayProps as ap, type FieldArrayRenderItemArgs as aq, type FormFieldProps as ar, type FormFieldRenderArgs as as, type FormProviderProps as at, type InputProps as au, type MultiSelectProps as av, type RadioGroupProps as aw, type SelectProps as ax, type SubmitButtonProps as ay, type TextareaProps as az, CheckboxPropsSchema as b, type CheckboxPropsValidated as c, ErrorDisplayPropsSchema as d, FieldArray as e, FieldArrayPropsSchema as f, FieldErrorShapeSchema as g, FormField as h, FormFieldPropsSchema as i, FormProvider as j, FormProviderPropsSchema as k, Input as l, InputPropsSchema as m, type InputPropsValidated as n, InputTypeSchema as o, MosaicFormModeSchema as p, MultiSelect as q, MultiSelectOptionSchema as r, MultiSelectPropsSchema as s, type RadioGroupOption as t, RadioGroupOptionSchema as u, RadioGroupPropsSchema as v, type RadioGroupPropsValidated as w, type RadioOrientation as x, Select as y, SelectOptionSchema as z };