@foormjs/vue 0.2.3 → 0.2.5

package/dist/index.d.ts

@@ -1,180 +1,488 @@
-import { TAtscriptAnnotatedType } from '@atscript/typescript/utils';
-import { TAtscriptTypeObject } from '@atscript/typescript/utils';
-import { TFoormEntryOptions } from 'foorm';
-import { TFoormField } from 'foorm';
+import { AllowedComponentProps } from 'vue';
+import { Component } from 'vue';
+import { ComponentCustomProps } from 'vue';
+import { ComponentOptionsMixin } from 'vue';
+import { ComponentProvideOptions } from 'vue';
+import { ComputedRef } from 'vue';
+import { DefineComponent } from 'vue';
+import { PublicProps } from 'vue';
+import { Ref } from 'vue';
+import { ShallowUnwrapRef } from 'vue';
+import { TAtscriptAnnotatedType } from '@atscript/typescript';
+import { TAtscriptDataType } from '@atscript/typescript';
+import { UnwrapRef } from 'vue';
+import { VNode } from 'vue';
+import { VNodeProps } from 'vue';
 
-export declare const OoField: <TFormData = any, TFormContext = any>(__VLS_props: any, __VLS_ctx?: {
-    attrs: any;
-    emit: any;
-    slots: {
-        default?(_: {
-            onBlur: any;
-            error: any;
-            model: any;
-            formData: any;
-            formContext: any;
-            label: any;
-            description: any;
-            hint: any;
-            placeholder: any;
-            classes: any;
-            styles: any;
-            optional: any;
-            disabled: any;
-            hidden: any;
-            readonly: any;
-            type: any;
-            altAction: any;
-            component: any;
-            vName: any;
-            field: any;
-            options: any;
-            maxLength: any;
-            required: any;
-            autocomplete: any;
-            attrs: any;
-        }): any;
-    };
-}, __VLS_expose?: (exposed: any) => void, __VLS_setup?: Promise<{
-    props: any;
-    expose(exposed: any): void;
+declare type __VLS_PrettifyLocal<T> = {
+    [K in keyof T]: T[K];
+} & {};
+
+declare type __VLS_PrettifyLocal_2<T> = {
+    [K in keyof T]: T[K];
+} & {};
+
+declare type __VLS_Props = {
+    def: FoormDef;
+    pathPrefix?: string;
+    onRemove?: () => void;
+    canRemove?: boolean;
+    removeLabel?: string;
+};
+
+declare type __VLS_Props_10 = TFoormComponentProps;
+
+declare type __VLS_Props_11 = TFoormComponentProps;
+
+declare type __VLS_Props_2 = TFoormComponentProps;
+
+declare type __VLS_Props_3 = TFoormComponentProps;
+
+declare type __VLS_Props_4 = TFoormComponentProps;
+
+declare type __VLS_Props_5 = TFoormComponentProps;
+
+declare type __VLS_Props_6 = TFoormComponentProps;
+
+declare type __VLS_Props_7 = TFoormComponentProps;
+
+declare type __VLS_Props_8 = TFoormComponentProps;
+
+declare type __VLS_Props_9 = TFoormComponentProps;
+
+/**
+ * Returns a fresh type-to-component map pre-filled with all built-in defaults.
+ *
+ * Spread or assign additional entries to extend with custom field types:
+ * ```ts
+ * const types = { ...createDefaultTypes(), rating: MyRatingComponent }
+ * ```
+ */
+export declare function createDefaultTypes(): TFoormTypeComponents;
+
+/** Extended field def for array-typed fields. */
+declare interface FoormArrayFieldDef extends FoormFieldDef {
+    /** ATScript annotated type of array items (from TAtscriptTypeArray.of) */
+    itemType: TAtscriptAnnotatedType;
+    /** Pre-built template field def for items (path=''). Clone with path/name override per index. */
+    itemField: FoormFieldDef;
+}
+
+/**
+ * Complete form definition — produced by createFoormDef().
+ * Form-level metadata (title, submit) resolved on demand via resolveFormProp.
+ */
+declare interface FoormDef {
+    type: TAtscriptAnnotatedType;
+    /** Root field representing the entire form. For interface types this is `type='object'`; for single-type forms it is a leaf field (e.g. `type='text'`). */
+    rootField: FoormFieldDef;
+    fields: FoormFieldDef[];
+    flatMap: Map<string, TAtscriptAnnotatedType>;
+}
+
+/**
+ * A single form field definition — thin pointer to the ATScript prop.
+ *
+ * All metadata (label, disabled, options, etc.) lives in `prop.metadata`
+ * and is resolved on demand via resolve utilities.
+ */
+declare interface FoormFieldDef {
+    /** Dot-separated path relative to the parent data context. `''` = root (value IS the data at the path prefix level, e.g. primitive array items). */
+    path: string;
+    prop: TAtscriptAnnotatedType;
+    type: string;
+    phantom: boolean;
+    name: string;
+    /** True when no foorm.fn.* metadata keys exist. Vue perf flag. */
+    allStatic: boolean;
+}
+
+/** Extended field def for union fields — standalone union props and union array items. */
+declare interface FoormUnionFieldDef extends FoormFieldDef {
+    /** Available union branches. */
+    unionVariants: FoormUnionVariant[];
+}
+
+/** One branch of a union type — used by union fields and union array items. */
+declare interface FoormUnionVariant {
+    /** Display label — from @meta.label or auto-generated (e.g. "1. String") */
+    label: string;
+    /** The annotated type for this variant */
+    type: TAtscriptAnnotatedType;
+    /** Pre-built FoormDef for object variants (undefined for primitives) */
+    def?: FoormDef;
+    /** Pre-built field def for primitive variants (undefined for objects) */
+    itemField?: FoormFieldDef;
+    /** Design type for primitive variants ('string', 'number', 'boolean') */
+    designType?: string;
+}
+
+/**
+ * Format a label/title with an array-index prefix.
+ *
+ * When `arrayIndex` is defined, prepends `#<index+1>` to the label.
+ * Used by field-shell (label) and object (title) components for array items.
+ */
+export declare function formatIndexedLabel(label: string | undefined, arrayIndex: number | undefined): string | undefined;
+
+export declare const OoAction: DefineComponent<__VLS_Props_7, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {} & {
+action: (name: string) => any;
+}, string, PublicProps, Readonly<__VLS_Props_7> & Readonly<{
+onAction?: ((name: string) => any) | undefined;
+}>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {}, HTMLDivElement>;
+
+export declare const OoArray: DefineComponent<__VLS_Props_9, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<__VLS_Props_9> & Readonly<{}>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {
+addDropdownRef: HTMLDivElement;
+}, HTMLDivElement>;
+
+export declare const OoCheckbox: DefineComponent<__VLS_Props_5, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<__VLS_Props_5> & Readonly<{}>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {}, HTMLDivElement>;
+
+export declare const OoField: <TFormData = any, TFormContext = any>(__VLS_props: NonNullable<Awaited<typeof __VLS_setup>>["props"], __VLS_ctx?: __VLS_PrettifyLocal_2<Pick<NonNullable<Awaited<typeof __VLS_setup>>, "attrs" | "emit" | "slots">>, __VLS_expose?: NonNullable<Awaited<typeof __VLS_setup>>["expose"], __VLS_setup?: Promise<{
+    props: __VLS_PrettifyLocal_2<Pick<Partial<{}> & Omit<{} & VNodeProps & AllowedComponentProps & ComponentCustomProps, never>, never> & {
+        field: FoormFieldDef;
+        error?: string;
+        onRemove?: () => void;
+        canRemove?: boolean;
+        removeLabel?: string;
+        arrayIndex?: number;
+    } & Partial<{}>> & PublicProps;
+    expose(exposed: ShallowUnwrapRef<    {}>): void;
     attrs: any;
-    slots: {
-        default?(_: {
-            onBlur: any;
-            error: any;
-            model: any;
-            formData: any;
-            formContext: any;
-            label: any;
-            description: any;
-            hint: any;
-            placeholder: any;
-            classes: any;
-            styles: any;
-            optional: any;
-            disabled: any;
-            hidden: any;
-            readonly: any;
-            type: any;
-            altAction: any;
-            component: any;
-            vName: any;
-            field: any;
-            options: any;
-            maxLength: any;
-            required: any;
-            autocomplete: any;
-            attrs: any;
-        }): any;
-    };
-    emit: any;
-}>) => any;
+    slots: {};
+    emit: {};
+}>) => VNode & {
+    __ctx?: Awaited<typeof __VLS_setup>;
+};
 
-export declare const OoForm: <TFormData = any, TFormContext = any>(__VLS_props: any, __VLS_ctx?: {
+export declare const OoForm: <TFormData = any, TFormContext = any>(__VLS_props: NonNullable<Awaited<typeof __VLS_setup>>["props"], __VLS_ctx?: __VLS_PrettifyLocal<Pick<NonNullable<Awaited<typeof __VLS_setup>>, "attrs" | "emit" | "slots">>, __VLS_expose?: NonNullable<Awaited<typeof __VLS_setup>>["expose"], __VLS_setup?: Promise<{
+    props: __VLS_PrettifyLocal<Pick<Partial<{}> & Omit<{
+        readonly onAction?: ((name: string, data: TFormData) => any) | undefined;
+        readonly onError?: ((errors: {
+            path: string;
+            message: string;
+        }[]) => any) | undefined;
+        readonly onSubmit?: ((data: TFormData) => any) | undefined;
+        readonly "onUnsupported-action"?: ((name: string, data: TFormData) => any) | undefined;
+        readonly onChange?: ((type: TFoormChangeType, path: string, value: unknown, formData: TFormData) => any) | undefined;
+    } & VNodeProps & AllowedComponentProps & ComponentCustomProps, never>, "onAction" | "onChange" | "onSubmit" | "onError" | "onUnsupported-action"> & Props<TFormData, TFormContext> & Partial<{}>> & PublicProps;
+    expose(exposed: ShallowUnwrapRef<    {}>): void;
     attrs: any;
-    emit: any;
-    slots: Partial<Record<`field:${any}`, (_: any) => any>> & {
-        "form.header"?(_: {
-            clearErrors: any;
-            reset: any;
-            title: any;
-            formContext: any;
-            disabled: any;
+    slots: {
+        'form.header'?(_: {
+            clearErrors: () => void;
+            reset: () => Promise<void>;
+            setErrors: (errors: Record<string, string>) => void;
+            formContext: TFormContext | undefined;
+            disabled: boolean;
         }): any;
-        "form.before"?(_: {
-            clearErrors: any;
-            reset: any;
+        'form.before'?(_: {
+            clearErrors: () => void;
+            reset: () => Promise<void>;
+            setErrors: (errors: Record<string, string>) => void;
         }): any;
-        "form.after"?(_: {
-            clearErrors: any;
-            reset: any;
-            disabled: any;
-            formContext: any;
+        'form.after'?(_: {
+            clearErrors: () => void;
+            reset: () => Promise<void>;
+            setErrors: (errors: Record<string, string>) => void;
+            disabled: boolean;
+            formContext: TFormContext | undefined;
         }): any;
-        "form.submit"?(_: {
-            disabled: any;
-            text: any;
-            clearErrors: any;
-            reset: any;
-            formContext: any;
+        'form.submit'?(_: {
+            disabled: boolean;
+            text: string;
+            clearErrors: () => void;
+            reset: () => Promise<void>;
+            setErrors: (errors: Record<string, string>) => void;
+            formContext: TFormContext | undefined;
         }): any;
-        "form.footer"?(_: {
-            disabled: any;
-            clearErrors: any;
-            reset: any;
-            formContext: any;
+        'form.footer'?(_: {
+            disabled: boolean;
+            clearErrors: () => void;
+            reset: () => Promise<void>;
+            setErrors: (errors: Record<string, string>) => void;
+            formContext: TFormContext | undefined;
         }): any;
     };
-}, __VLS_expose?: (exposed: any) => void, __VLS_setup?: Promise<{
-    props: any;
-    expose(exposed: any): void;
-    attrs: any;
-    slots: Partial<Record<`field:${any}`, (_: any) => any>> & {
-        "form.header"?(_: {
-            clearErrors: any;
-            reset: any;
-            title: any;
-            formContext: any;
-            disabled: any;
-        }): any;
-        "form.before"?(_: {
-            clearErrors: any;
-            reset: any;
-        }): any;
-        "form.after"?(_: {
-            clearErrors: any;
-            reset: any;
-            disabled: any;
-            formContext: any;
-        }): any;
-        "form.submit"?(_: {
-            disabled: any;
-            text: any;
-            clearErrors: any;
-            reset: any;
-            formContext: any;
-        }): any;
-        "form.footer"?(_: {
-            disabled: any;
-            clearErrors: any;
-            reset: any;
-            formContext: any;
-        }): any;
+    emit: {
+        (e: "submit", data: TFormData): void;
+        (e: "error", errors: {
+            path: string;
+            message: string;
+        }[]): void;
+        (e: "action", name: string, data: TFormData): void;
+        (e: "unsupported-action", name: string, data: TFormData): void;
+        (e: "change", type: TFoormChangeType, path: string, value: unknown, formData: TFormData): void;
     };
-    emit: any;
-}>) => any;
+}>) => VNode & {
+    __ctx?: Awaited<typeof __VLS_setup>;
+};
+
+export declare const OoInput: DefineComponent<__VLS_Props_2, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<__VLS_Props_2> & Readonly<{}>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {}, HTMLDivElement>;
+
+export declare const OoIterator: DefineComponent<__VLS_Props, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {}, any>;
+
+export declare const OoObject: DefineComponent<__VLS_Props_8, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<__VLS_Props_8> & Readonly<{}>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {}, HTMLDivElement>;
+
+export declare const OoParagraph: DefineComponent<__VLS_Props_6, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<__VLS_Props_6> & Readonly<{}>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {}, HTMLParagraphElement>;
+
+export declare const OoRadio: DefineComponent<__VLS_Props_4, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<__VLS_Props_4> & Readonly<{}>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {}, HTMLDivElement>;
+
+export declare const OoSelect: DefineComponent<__VLS_Props_3, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<__VLS_Props_3> & Readonly<{}>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {}, HTMLDivElement>;
+
+export declare const OoTuple: DefineComponent<__VLS_Props_11, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<__VLS_Props_11> & Readonly<{}>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {}, HTMLDivElement>;
+
+export declare const OoUnion: DefineComponent<__VLS_Props_10, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<__VLS_Props_10> & Readonly<{}>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {
+dropdownRef: HTMLDivElement;
+}, HTMLDivElement>;
+
+declare interface Props<TF, TC> {
+    def: FoormDef;
+    formData?: TF;
+    formContext?: TC;
+    firstValidation?: TFoormState['firstValidation'];
+    components?: Record<string, Component<TFoormComponentProps>>;
+    /**
+     * Type-to-component map for field rendering. Maps field types to Vue components.
+     * Must include entries for all built-in field types. Use `createDefaultTypes()`
+     * for a pre-filled map, or supply your own.
+     */
+    types: TFoormTypeComponents;
+    errors?: Record<string, string | undefined>;
+}
+
+/** Alt-action metadata — the action id and display label. */
+declare interface TFoormAltAction {
+    id: string;
+    label: string;
+}
 
-export declare interface TFoormComponentProps<V, TFormData, TFormContext> {
-    onBlur: Function;
+/**
+ * Shared base props available to all custom foorm components.
+ */
+export declare interface TFoormBaseComponentProps {
+    /** Whether this component is disabled. */
+    disabled?: boolean;
+    /** Whether this component is hidden. */
+    hidden?: boolean;
+}
+
+/**
+ * Discriminated type for the `change` event emitted by `OoForm`.
+ *
+ * - `'update'` — leaf field value committed (blur)
+ * - `'array-add'` — array item added
+ * - `'array-remove'` — array item removed
+ * - `'union-switch'` — union variant switched
+ */
+export declare type TFoormChangeType = 'update' | 'array-add' | 'array-remove' | 'union-switch';
+
+/**
+ * Props contract for custom field components used with `OoForm` / `OoField`.
+ *
+ * Implement this interface in your UI components so that `OoField` can pass
+ * all resolved field state (value, label, validation errors, etc.) as props.
+ *
+ * @typeParam V - The field value type
+ * @typeParam TFormData - The full form data object type
+ * @typeParam TFormContext - The external context object type
+ */
+export declare interface TFoormComponentProps<V = unknown> extends TFoormBaseComponentProps {
+    /** Called on field blur — triggers validation. */
+    onBlur: () => void;
+    /** Validation error message for this field, if any. */
     error?: string;
+    /** Reactive model wrapping the field value. Bind with `v-model="model.value"`. */
     model: {
         value: V;
     };
-    formData: TFormData;
-    formContext?: TFormContext;
+    /** Phantom field display value from `@foorm.value` / `@foorm.fn.value` (paragraphs, actions). `undefined` for data fields. */
+    value?: unknown;
+    /** Resolved field label from `@label` or `@foorm.fn.label`. */
     label?: string;
+    /** Resolved field description from `@description` or `@foorm.fn.description`. */
     description?: string;
+    /** Resolved hint text from `@foorm.hint` or `@foorm.fn.hint`. */
     hint?: string;
+    /** Resolved placeholder from `@foorm.placeholder` or `@foorm.fn.placeholder`. */
     placeholder?: string;
+    /** CSS class(es) from `@foorm.class` or `@foorm.fn.class`. */
     class?: Record<string, boolean> | string;
+    /** Inline styles from `@foorm.style` or `@foorm.fn.style`. */
     style?: Record<string, string> | string;
+    /** Whether the field is optional (not required). */
     optional?: boolean | undefined;
+    /** Toggle an optional field on/off. `true` sets default value; `false` sets `undefined`. Only present when `optional` is true. */
+    onToggleOptional?: (enabled: boolean) => void;
+    /** Whether the field is required (inverse of optional). */
     required?: boolean | undefined;
-    disabled?: boolean | undefined;
-    hidden?: boolean | undefined;
+    /** Whether the field is read-only. */
+    readonly?: boolean | undefined;
+    /** The resolved field input type (e.g., `'text'`, `'select'`, `'checkbox'`). */
     type: string;
-    altAction?: string;
+    /** Alternate action from `@foorm.altAction`. Contains the action id and display label. */
+    altAction?: TFoormAltAction;
+    /** The field name (last segment of the dot-separated path). */
     name?: string;
-    field?: TFoormField;
+    /** The full FoormFieldDef for advanced use cases. */
+    field?: FoormFieldDef;
+    /** Resolved options for select/radio/checkbox fields. */
     options?: TFoormEntryOptions[];
+    /** Max length constraint from `@expect.maxLength`. */
     maxLength?: number;
+    /** Autocomplete hint from `@foorm.autocomplete`. */
     autocomplete?: string;
+    /** Resolved title from `@foorm.title` / `@foorm.fn.title` / `@meta.label` for structure/array fields. */
+    title?: string;
+    /** Nesting level for structure/array fields. Root structure is 0, each nested structure/array increments by 1. */
+    level?: number;
+    /** Callback to remove this item from its parent array. Present when rendered inside an array. */
+    onRemove?: () => void;
+    /** Whether removal is allowed (respects minLength constraints). */
+    canRemove?: boolean;
+    /** Label for the remove button (from `@foorm.array.remove.label`). */
+    removeLabel?: string;
+    /** Zero-based index when rendered as a direct array item. `undefined` otherwise. */
+    arrayIndex?: number;
+}
+
+/** An option for select/radio fields — either a plain string or a `{ key, label }` pair. */
+declare type TFoormEntryOptions = {
+    key: string;
+    label: string;
+} | string;
+
+declare interface TFoormFieldCallbacks {
+    validate: () => boolean | string;
+    clearErrors: () => void;
+    reset: () => void;
+    setExternalError: (msg?: string) => void;
+}
+
+declare interface TFoormFieldRegistration {
+    path: () => string;
+    callbacks: TFoormFieldCallbacks;
+}
+
+declare interface TFoormState {
+    firstSubmitHappened: boolean;
+    firstValidation: 'on-change' | 'touched-on-blur' | 'on-blur' | 'on-submit' | 'none';
+    register: (id: symbol, registration: TFoormFieldRegistration) => void;
+    unregister: (id: symbol) => void;
 }
 
-export declare function useFoorm<T extends TAtscriptAnnotatedType<TAtscriptTypeObject<any, any>>>(type: T): {
-    form: any;
-    formData: any;
+/**
+ * Union context provided by `OoUnion` via `__foorm_union` inject key.
+ * Consumed by header components (OoStructuredHeader, OoFieldShell) to render
+ * the variant picker inline with the item's own header.
+ */
+/**
+ * Type-to-component map for `OoForm`. Lists all built-in field types as
+ * required keys and accepts additional custom types via index signature.
+ *
+ * Use {@link createDefaultTypes} to get a pre-built map with all defaults.
+ */
+export declare type TFoormTypeComponents = {
+    text: Component;
+    select: Component;
+    radio: Component;
+    checkbox: Component;
+    paragraph: Component;
+    action: Component;
+    object: Component;
+    array: Component;
+    union: Component;
+    tuple: Component;
+} & Record<string, Component>;
+
+export declare interface TFoormUnionContext {
+    /** All available union variant branches. */
+    variants: FoormUnionVariant[];
+    /** Reactive index of the currently selected variant. */
+    currentIndex: Ref<number>;
+    /** Switch to a different variant (rewrites model data). */
+    changeVariant: (index: number) => void;
+}
+
+/**
+ * Consume and clear the `__foorm_union` injection.
+ *
+ * Structured components (object, tuple, array, field-shell) call this to
+ * read the union context provided by `OoUnion` and immediately clear it
+ * so nested children don't inherit it.
+ */
+export declare function useConsumeUnionContext(): TFoormUnionContext | undefined;
+
+/**
+ * Creates a reactive form definition and data object from an ATScript annotated type.
+ *
+ * @param type - An ATScript annotated type (imported from a `.as` file via `@atscript/typescript`).
+ *   Accepts any type shape: interface/object, primitive, array, union, etc.
+ *   For non-object types, the data is wrapped in `{ value: ... }`.
+ * @param context - Optional context object passed to `foorm.fn.value` functions during data creation
+ * @returns `{ def, formData }` — the FoormDef and a Vue reactive data object with defaults applied
+ *
+ * @example
+ * ```vue
+ * <script setup lang="ts">
+ * import { useFoorm } from '@foormjs/vue'
+ * import { MyForm } from './my-form.as'
+ *
+ * const { def, formData } = useFoorm(MyForm)
+ * </script>
+ *
+ * <template>
+ *   <OoForm :def="def" :data="formData" />
+ * </template>
+ * ```
+ */
+export declare function useFoorm<T extends TAtscriptAnnotatedType>(type: T, context?: Record<string, unknown>): {
+    def: FoormDef;
+    formData: {
+        value: UnwrapRef<TAtscriptDataType<T>>;
+    };
+};
+
+/**
+ * Composable for managing array field state.
+ *
+ * Manages stable keys, add/remove with constraints, and item field resolution.
+ * Union item types are handled transparently — OoUnion manages variant state locally.
+ * Used by the default `OoArray` component and available for custom array components.
+ */
+export declare function useFoormArray(field: FoormArrayFieldDef, disabled?: ComputedRef<boolean>): {
+    arrayValue: ComputedRef<unknown[]>;
+    itemKeys: string[];
+    isUnion: boolean;
+    unionVariants: FoormUnionVariant[];
+    getItemField: (index: number) => FoormFieldDef;
+    addItem: (variantIndex?: number) => void;
+    removeItem: (index: number) => void;
+    canAdd: ComputedRef<boolean>;
+    canRemove: ComputedRef<boolean>;
+    addLabel: string;
+    removeLabel: string;
+};
+
+/**
+ * Composable for managing union field state.
+ *
+ * Manages variant switching with data stashing — switching away from a variant
+ * saves its data, and switching back restores it instead of creating fresh defaults.
+ * Used by the default `OoUnion` component and available for custom union components.
+ */
+export declare function useFoormUnion(props: TFoormComponentProps): {
+    unionField: ComputedRef<FoormUnionFieldDef | undefined>;
+    hasMultipleVariants: ComputedRef<boolean>;
+    localUnionIndex: Ref<number, number>;
+    currentVariant: ComputedRef<FoormUnionVariant | undefined>;
+    innerField: ComputedRef<FoormFieldDef | undefined>;
+    changeVariant: (newIndex: number) => void;
+    optionalEnabled: ComputedRef<boolean>;
+    dropdownRef: Ref<HTMLElement | null, HTMLElement | null>;
+    isOpen: Ref<boolean, boolean>;
+    toggle: () => void;
+    select: (callback: () => void) => void;
+    handleNaClick: () => void;
 };
 
 export { }