@buildnbuzz/buzzform 0.1.0

package/dist/adapter-BT9v2OVg.d.ts

@@ -0,0 +1,1136 @@
+import { ReactNode, ComponentType, FormEvent } from 'react';
+import { ZodSchema } from 'zod';
+
+/**
+ * Context passed to validation functions.
+ */
+interface ValidationContext<TData = Record<string, unknown>> {
+    /** Complete form data */
+    data: TData;
+    /** Sibling field data at the same level */
+    siblingData: Record<string, unknown>;
+    /** Path segments to this field */
+    path: string[];
+}
+/**
+ * Validation function return type.
+ * - `true` = valid
+ * - `string` = error message
+ */
+type ValidationResult = true | string | Promise<true | string>;
+/**
+ * Custom validation function.
+ */
+type ValidationFn<TValue = unknown, TData = Record<string, unknown>> = (value: TValue, context: ValidationContext<TData>) => ValidationResult;
+/**
+ * Context for conditional field display.
+ */
+interface ConditionContext {
+    /** Current operation */
+    operation: 'create' | 'update' | 'read';
+    /** Path segments to this field */
+    path: string[];
+}
+/**
+ * Condition function to control field visibility.
+ */
+type FieldCondition<TData = Record<string, unknown>> = (data: TData, siblingData: Record<string, unknown>, context: ConditionContext) => boolean;
+/**
+ * Props passed to a full custom field component.
+ * Use this when you want complete control over the field rendering.
+ */
+interface FieldComponentProps<TValue = unknown, TField = Field> {
+    /** The field configuration */
+    field: TField;
+    /** Field path (e.g., "email", "address.city") */
+    path: string;
+    /** Generated HTML id for the field input */
+    id: string;
+    /** Form adapter instance */
+    form: FormAdapter;
+    /** Current field value */
+    value: TValue;
+    /** Update the field value */
+    onChange: (value: TValue) => void;
+    /** Mark field as touched */
+    onBlur: () => void;
+    /** Whether the field is disabled */
+    disabled: boolean;
+    /** Whether the field is read-only */
+    readOnly: boolean;
+    /** First error message, if any */
+    error?: string;
+    /** Whether the field should auto-focus */
+    autoFocus?: boolean;
+}
+/**
+ * Props passed to a custom input component.
+ * Use this when you only want to customize the input, keeping the standard wrapper.
+ */
+interface FieldInputProps<TValue = unknown, TField = Field> {
+    /** The field configuration (access min, max, placeholder, etc.) */
+    field: TField;
+    /** Field path (e.g., "email", "address.city") */
+    path: string;
+    /** Generated HTML id (must be used for label association) */
+    id: string;
+    /** Field name for HTML form/autofill (e.g., "email", "password") */
+    name: string;
+    /** Current field value */
+    value: TValue;
+    /** Update the field value */
+    onChange: (value: TValue) => void;
+    /** Mark field as touched */
+    onBlur: () => void;
+    /** Whether the field is disabled */
+    disabled: boolean;
+    /** Whether the field is read-only */
+    readOnly: boolean;
+    /** First error message, if any */
+    error?: string;
+    /** Whether the field should auto-focus */
+    autoFocus?: boolean;
+    /** Live validation state (if enabled) */
+    validation?: {
+        /** Whether validation is currently running */
+        isChecking: boolean;
+        /** Whether the field passes validation */
+        isValid: boolean;
+        /** Validation message */
+        message?: string;
+    };
+}
+/**
+ * Custom input render function.
+ */
+type FieldInputRenderFn<TValue = unknown, TField = Field> = (props: FieldInputProps<TValue, TField>) => ReactNode;
+/**
+ * Styling options for a field.
+ */
+interface FieldStyle {
+    /** Additional CSS class for the field wrapper */
+    className?: string;
+    /** Field width (e.g., '50%', '200px', 200) */
+    width?: string | number;
+}
+/**
+ * Base field interface. All field types extend this.
+ */
+interface BaseField<TValue = unknown, TData = Record<string, unknown>> {
+    /** Field name - becomes the key in form data */
+    name: string;
+    /** Explicit HTML id override (defaults to path-based generation) */
+    id?: string;
+    /** Display label (false to hide, ReactNode for custom) */
+    label?: string | ReactNode | false;
+    /** Help text shown below the field */
+    description?: string | ReactNode;
+    /** Placeholder text */
+    placeholder?: string;
+    /** Whether the field is required */
+    required?: boolean;
+    /**
+     * Disable user interaction.
+     * Can be a boolean or a function for conditional disabling.
+     * @example disabled: (data) => !data.country // Disable until country is selected
+     */
+    disabled?: boolean | ((data: TData, siblingData: Record<string, unknown>) => boolean);
+    /** Hide the field from the form UI (static or conditional) */
+    hidden?: boolean | ((data: TData, siblingData: Record<string, unknown>) => boolean);
+    /**
+     * Make field read-only.
+     * Can be a boolean or a function for conditional read-only state.
+     * @example readOnly: (data) => data.status === 'published'
+     */
+    readOnly?: boolean | ((data: TData, siblingData: Record<string, unknown>) => boolean);
+    /** Default value (static only, async handled at form level) */
+    defaultValue?: TValue;
+    /** Direct Zod schema (overrides auto-generated) */
+    schema?: ZodSchema<TValue>;
+    /** Custom validation function */
+    validate?: ValidationFn<TValue, TData>;
+    /** Condition function to show/hide the field */
+    condition?: FieldCondition<TData>;
+    /** Styling options */
+    style?: FieldStyle;
+    /** Full custom component (replaces entire field) */
+    component?: ComponentType<FieldComponentProps<TValue>>;
+    /** Custom input only (library handles wrapper/label/error) */
+    input?: ComponentType<FieldInputProps<TValue>> | FieldInputRenderFn<TValue>;
+    /** HTML autocomplete attribute */
+    autoComplete?: string;
+    /** Custom metadata */
+    meta?: Record<string, unknown>;
+}
+/**
+ * Text field
+ */
+interface TextField extends BaseField<string> {
+    type: 'text';
+    /** Minimum length */
+    minLength?: number;
+    /** Maximum length */
+    maxLength?: number;
+    /** Pattern to match (string or RegExp) */
+    pattern?: string | RegExp;
+    /** Trim whitespace */
+    trim?: boolean;
+    /** UI options */
+    ui?: {
+        /** Show copy button to copy value to clipboard */
+        copyable?: boolean;
+    };
+}
+/**
+ * Email field
+ */
+interface EmailField extends BaseField<string> {
+    type: 'email';
+    /** Minimum length */
+    minLength?: number;
+    /** Maximum length */
+    maxLength?: number;
+    /** Pattern to match (string or RegExp) */
+    pattern?: string | RegExp;
+    /** Trim whitespace */
+    trim?: boolean;
+    /** UI options */
+    ui?: {
+        /** Show copy button to copy value to clipboard */
+        copyable?: boolean;
+    };
+}
+/**
+ * Password field
+ */
+interface PasswordField extends BaseField<string> {
+    type: 'password';
+    /** Minimum length (default: 8) */
+    minLength?: number;
+    /** Maximum length */
+    maxLength?: number;
+    /** Password strength criteria */
+    criteria?: {
+        requireUppercase?: boolean;
+        requireLowercase?: boolean;
+        requireNumber?: boolean;
+        requireSpecial?: boolean;
+    };
+    /** UI options */
+    ui?: {
+        /** Show strength indicator */
+        strengthIndicator?: boolean;
+        /** Show requirements checklist */
+        showRequirements?: boolean;
+        /** Allow password generation */
+        allowGenerate?: boolean;
+        /** Show copy button to copy value to clipboard */
+        copyable?: boolean;
+    };
+}
+/**
+ * Textarea field
+ */
+interface TextareaField extends BaseField<string> {
+    type: 'textarea';
+    /** Minimum length */
+    minLength?: number;
+    /** Maximum length */
+    maxLength?: number;
+    /** Number of visible rows */
+    rows?: number;
+    /** Auto-resize based on content */
+    autoResize?: boolean;
+    /** UI options */
+    ui?: {
+        /** Show copy button to copy value to clipboard */
+        copyable?: boolean;
+    };
+}
+/**
+ * Number field
+ */
+interface NumberField extends BaseField<number> {
+    type: 'number';
+    /** Minimum value */
+    min?: number;
+    /** Maximum value */
+    max?: number;
+    /** Decimal precision */
+    precision?: number;
+    /** UI options */
+    ui?: {
+        /** Step increment */
+        step?: number;
+        /** Visual variant */
+        variant?: 'default' | 'stacked' | 'pill' | 'plain';
+        /** Prefix (e.g., "$") */
+        prefix?: string;
+        /** Suffix (e.g., "%", "kg") */
+        suffix?: string;
+        /** Use thousand separator */
+        thousandSeparator?: boolean | string;
+        /** Hide stepper buttons */
+        hideSteppers?: boolean;
+        /** Show copy button to copy value to clipboard */
+        copyable?: boolean;
+    };
+}
+/**
+ * Date field
+ */
+interface DateField extends BaseField<Date> {
+    type: 'date';
+    /** Minimum date */
+    minDate?: Date | string;
+    /** Maximum date */
+    maxDate?: Date | string;
+    /** UI options */
+    ui?: {
+        /** Display format (date-fns format) */
+        format?: string;
+        /** Manual input format */
+        inputFormat?: string;
+        /** Quick date presets */
+        presets?: boolean | Array<{
+            label: string;
+            value: Date | (() => Date);
+        }>;
+    };
+}
+/**
+ * Datetime field
+ */
+interface DatetimeField extends BaseField<Date> {
+    type: 'datetime';
+    /** Minimum date */
+    minDate?: Date | string;
+    /** Maximum date */
+    maxDate?: Date | string;
+    /** UI options */
+    ui?: {
+        /** Display format (date-fns format) */
+        format?: string;
+        /** Manual input format */
+        inputFormat?: string;
+        /** Time picker config */
+        timePicker?: boolean | {
+            interval?: number;
+            use24hr?: boolean;
+            includeSeconds?: boolean;
+        };
+        /** Quick date presets */
+        presets?: boolean | Array<{
+            label: string;
+            value: Date | (() => Date);
+        }>;
+    };
+}
+/**
+ * Select option
+ */
+interface SelectOption {
+    /** Display label */
+    label: string | ReactNode;
+    /** Option value (supports string, number, or boolean for API compatibility) */
+    value: string | number | boolean;
+    /** Optional description */
+    description?: string | ReactNode;
+    /** Optional icon */
+    icon?: ReactNode;
+    /** Optional badge */
+    badge?: string;
+    /** Whether disabled */
+    disabled?: boolean;
+}
+/**
+ * Select field
+ */
+interface SelectField extends BaseField<string | string[] | number | number[] | boolean> {
+    type: 'select';
+    /** Options (static, string array, or async with context for dependent dropdowns) */
+    options: SelectOption[] | string[] | ((context: ValidationContext) => Promise<SelectOption[]>);
+    /**
+     * Field paths that trigger options refetch when changed.
+     * Required when using async options that depend on other field values.
+     * @example dependencies: ['country', 'state'] // Refetch when country or state changes
+     */
+    dependencies?: string[];
+    /** Allow multiple selections */
+    hasMany?: boolean;
+    /** UI options */
+    ui?: {
+        /** Enable search */
+        isSearchable?: boolean;
+        /** Show clear button */
+        isClearable?: boolean;
+        /** Max visible chips (for hasMany) */
+        maxVisibleChips?: number;
+        /** Empty state message */
+        emptyMessage?: string;
+        /** Loading message */
+        loadingMessage?: string;
+    };
+}
+/**
+ * Checkbox field
+ */
+interface CheckboxField extends BaseField<boolean> {
+    type: 'checkbox';
+}
+/**
+ * Switch field
+ */
+interface SwitchField extends BaseField<boolean> {
+    type: 'switch';
+    /** UI options */
+    ui?: {
+        /**
+         * Switch position relative to label.
+         * - 'between': Label on left, switch on right with full-width spacing (default)
+         * - 'start': Switch on left, label on right
+         * - 'end': Label on left, switch on right
+         */
+        alignment?: 'start' | 'end' | 'between';
+    };
+}
+/**
+ * Radio field - single selection from a group of options
+ */
+interface RadioField extends BaseField<string | number | boolean> {
+    type: 'radio';
+    /** Static array or async function for options */
+    options: SelectOption[] | string[] | ((context: ValidationContext) => Promise<SelectOption[]>);
+    /** Paths that trigger options refetch when changed */
+    dependencies?: string[];
+    ui?: {
+        /** Visual variant ('default' or 'card') */
+        variant?: 'default' | 'card';
+        /** Layout direction for 'default' variant */
+        direction?: 'vertical' | 'horizontal';
+        /** Grid columns (responsive, 1 on mobile) */
+        columns?: 1 | 2 | 3 | 4;
+        /** Card settings (for variant: 'card') */
+        card?: {
+            /** Size preset ('sm', 'md', 'lg') */
+            size?: 'sm' | 'md' | 'lg';
+            /** Show border around cards */
+            bordered?: boolean;
+        };
+    };
+}
+/**
+ * Tags field - chip-based multi-value string input
+ */
+interface TagsField extends BaseField<string[]> {
+    type: 'tags';
+    /** Minimum number of tags */
+    minTags?: number;
+    /** Maximum number of tags */
+    maxTags?: number;
+    /** Maximum character length per tag */
+    maxTagLength?: number;
+    /** Allow duplicate tag values (default: false) */
+    allowDuplicates?: boolean;
+    /** UI options */
+    ui?: {
+        /** Keys that create a new tag (default: ['enter']) */
+        delimiters?: ('enter' | 'comma' | 'space' | 'tab')[];
+        /** Visual variant */
+        variant?: 'chips' | 'pills' | 'inline';
+        /** Show copy button to copy all tags */
+        copyable?: boolean;
+    };
+}
+/**
+ * Upload field
+ */
+interface UploadField extends BaseField<File | File[] | string | string[]> {
+    type: 'upload';
+    /** Allow multiple files */
+    hasMany?: boolean;
+    /** Minimum files (when hasMany) */
+    minFiles?: number;
+    /** Maximum files (when hasMany) */
+    maxFiles?: number;
+    /** Maximum file size in bytes */
+    maxSize?: number;
+    /** UI options */
+    ui?: {
+        /** MIME type filter */
+        accept?: string;
+        /** Visual variant */
+        variant?: 'dropzone' | 'avatar' | 'inline' | 'gallery';
+        /** Shape (for avatar) */
+        shape?: 'circle' | 'square' | 'rounded';
+        /** Size preset */
+        size?: 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+        /** Enable cropping */
+        crop?: boolean | {
+            aspectRatio?: number;
+            circular?: boolean;
+        };
+        /** Show progress */
+        showProgress?: boolean;
+        /** Dropzone text */
+        dropzoneText?: string;
+    };
+}
+/**
+ * Group field - wraps fields in a named object
+ */
+interface GroupField extends BaseField<Record<string, unknown>> {
+    type: 'group';
+    /** Nested fields */
+    fields: Field[];
+    /** UI options */
+    ui?: {
+        /** Visual variant ('card', 'flat', 'ghost', 'bordered') */
+        variant?: 'card' | 'flat' | 'ghost' | 'bordered';
+        /** Spacing between fields ('sm', 'md', 'lg') */
+        spacing?: 'sm' | 'md' | 'lg';
+        /** Start in collapsed state */
+        collapsed?: boolean;
+        /** Show error badge */
+        showErrorBadge?: boolean;
+    };
+}
+/**
+ * Array field - repeatable fields
+ */
+interface ArrayField extends BaseField<unknown[]> {
+    type: 'array';
+    /** Fields for each array item */
+    fields: Field[];
+    /** Minimum items */
+    minRows?: number;
+    /** Maximum items */
+    maxRows?: number;
+    /** UI options */
+    ui?: {
+        /** Allow reordering via drag & drop (default: true) */
+        isSortable?: boolean;
+        /** Add button label (default: "Add Item") */
+        addLabel?: string;
+        /** Field name to use for row labels (falls back to first named field) */
+        rowLabelField?: string;
+        /** Start the array container collapsed */
+        collapsed?: boolean;
+        /** Start individual rows collapsed */
+        rowsCollapsed?: boolean;
+        /** Show confirmation dialog before deleting all items */
+        confirmDelete?: boolean;
+        /** Custom empty state message */
+        emptyMessage?: string;
+        /** Show error count badge in header (default: true) */
+        showErrorBadge?: boolean;
+    };
+}
+/**
+ * Row field - horizontal layout container
+ */
+interface RowField {
+    type: 'row';
+    /** Fields to display in a row */
+    fields: Field[];
+    /** Layout options */
+    ui?: {
+        /** Gap between fields (e.g., 4, '1rem', '16px') */
+        gap?: number | string;
+        /** Vertical alignment */
+        align?: 'start' | 'center' | 'end' | 'stretch';
+        /** Horizontal distribution */
+        justify?: 'start' | 'center' | 'end' | 'between';
+        /** Allow wrapping to next line */
+        wrap?: boolean;
+        /** Responsive behavior: 'stack' collapses to vertical on mobile */
+        responsive?: boolean | 'stack';
+    };
+}
+/**
+ * Tab configuration
+ */
+interface Tab {
+    /** Tab name (if provided, creates nested object) */
+    name?: string;
+    /** Tab label */
+    label: string | ReactNode;
+    /** Fields in this tab */
+    fields: Field[];
+    /** Tab description */
+    description?: string | ReactNode;
+    /** Tab icon */
+    icon?: ReactNode;
+    /** Whether this tab is disabled */
+    disabled?: boolean;
+}
+/**
+ * Tabs field - tabbed container
+ */
+interface TabsField {
+    type: 'tabs';
+    /** Tab definitions */
+    tabs: Tab[];
+    /** UI options */
+    ui?: {
+        /** Default active tab (index or name) */
+        defaultTab?: number | string;
+        /** Show error badge on tabs with validation errors */
+        showErrorBadge?: boolean;
+        /** Visual variant */
+        variant?: 'default' | 'line';
+        /** Spacing between fields within tabs */
+        spacing?: 'sm' | 'md' | 'lg';
+    };
+}
+/**
+ * Collapsible field - expandable container
+ */
+interface CollapsibleField {
+    type: 'collapsible';
+    /** Container label */
+    label: string;
+    /** Nested fields */
+    fields: Field[];
+    /** Start collapsed */
+    collapsed?: boolean;
+    /** UI options */
+    ui?: {
+        /** Visual variant ('card', 'flat', 'ghost', 'bordered') */
+        variant?: 'card' | 'flat' | 'ghost' | 'bordered';
+        /** Spacing between fields ('sm', 'md', 'lg') */
+        spacing?: 'sm' | 'md' | 'lg';
+        /** Show error badge */
+        showErrorBadge?: boolean;
+        /** Optional description */
+        description?: string;
+        /** Optional icon */
+        icon?: ReactNode;
+    };
+    /** Styling options */
+    style?: FieldStyle;
+}
+/**
+ * Union of all field types.
+ */
+type Field = TextField | EmailField | PasswordField | TextareaField | NumberField | DateField | DatetimeField | SelectField | CheckboxField | SwitchField | RadioField | TagsField | UploadField | GroupField | ArrayField | RowField | TabsField | CollapsibleField;
+/**
+ * Extract field type from a Field.
+ */
+type FieldType = Field['type'];
+/**
+ * Data fields (fields that hold values).
+ */
+type DataField = TextField | EmailField | PasswordField | TextareaField | NumberField | DateField | DatetimeField | SelectField | CheckboxField | SwitchField | RadioField | TagsField | UploadField | GroupField | ArrayField;
+/**
+ * Layout fields (fields that organize other fields).
+ */
+type LayoutField = RowField | TabsField | CollapsibleField;
+
+/**
+ * A Zod schema with field definitions attached.
+ * Created by `createSchema([...])` for type inference and field rendering.
+ */
+type BuzzFormSchema<TData = unknown, TFields extends readonly Field[] = Field[]> = ZodSchema<TData> & {
+    fields: TFields;
+};
+/**
+ * Form-level behavior settings.
+ * These control how the form behaves during user interaction.
+ */
+interface FormSettings {
+    /**
+     * Prevent submission when form has no changes.
+     * When true, handleSubmit is a no-op if formState.isDirty is false.
+     * @default false
+     */
+    submitOnlyWhenDirty?: boolean;
+    /**
+     * Auto-focus first visible, enabled field on mount.
+     * Note: This is a hint to the renderer component.
+     * @default false
+     */
+    autoFocus?: boolean;
+}
+/**
+ * Global form configuration set at the provider level.
+ * These defaults apply to all forms unless overridden.
+ *
+ * @example
+ * <FormProvider
+ *   adapter={useRhfAdapter}
+ *   resolver={zodResolver}
+ *   mode="onBlur"
+ * >
+ *   <App />
+ * </FormProvider>
+ */
+interface FormConfig {
+    /**
+     * Adapter factory function.
+     * Determines which form library handles state management.
+     *
+     * @example
+     * import { useRhfAdapter } from '@buildnbuzz/buzzform/rhf';
+     * adapter: useRhfAdapter
+     */
+    adapter: AdapterFactory;
+    /**
+     * Validation resolver factory.
+     * Converts a Zod schema into a form-compatible resolver.
+     * @default zodResolver
+     *
+     * @example
+     * import { zodResolver } from '@buildnbuzz/buzzform/resolvers/zod';
+     * resolver: zodResolver
+     */
+    resolver?: <T>(schema: ZodSchema<T>) => Resolver<T>;
+    /**
+     * Default validation mode for all forms.
+     * - 'onChange': Validate on every change (default)
+     * - 'onBlur': Validate when fields lose focus
+     * - 'onSubmit': Validate only on submit
+     * @default 'onChange'
+     */
+    mode?: 'onChange' | 'onBlur' | 'onSubmit';
+    /**
+     * When to re-validate after initial validation error.
+     * - 'onChange': Re-validate on every change (default)
+     * - 'onBlur': Re-validate when fields lose focus
+     * - 'onSubmit': Re-validate only on submit
+     * @default 'onChange'
+     */
+    reValidateMode?: 'onChange' | 'onBlur' | 'onSubmit';
+}
+/**
+ * Options passed to useForm hook.
+ *
+ * @example
+ * const loginSchema = createSchema([
+ *   { type: 'email', name: 'email', required: true },
+ *   { type: 'password', name: 'password', required: true },
+ * ]);
+ *
+ * const form = useForm({
+ *   schema: loginSchema,
+ *   onSubmit: async (data) => {
+ *     await auth.login(data);
+ *   },
+ * });
+ */
+interface UseFormOptions<TData = Record<string, unknown>> {
+    /**
+     * Zod schema for validation.
+     * - Use `createSchema([...])` for schema with fields attached (recommended)
+     * - Use raw Zod schema for validation-only (manual field rendering)
+     */
+    schema: ZodSchema<TData> | BuzzFormSchema<TData>;
+    /**
+     * Default values for the form.
+     * If not provided and schema has fields, extracted from field definitions.
+     * Can be static, sync function, or async function.
+     */
+    defaultValues?: TData | (() => TData) | (() => Promise<TData>);
+    /**
+     * Form submission handler.
+     * Called with validated data after all validation passes.
+     */
+    onSubmit?: (data: TData) => Promise<void> | void;
+    /**
+     * Override the adapter for this specific form.
+     * Uses provider's adapter if not specified.
+     */
+    adapter?: AdapterFactory;
+    /**
+     * Override the validation mode for this form.
+     * Uses provider's mode if not specified.
+     */
+    mode?: 'onChange' | 'onBlur' | 'onSubmit';
+    /**
+     * Override the re-validation mode for this form.
+     * Uses provider's reValidateMode if not specified.
+     */
+    reValidateMode?: 'onChange' | 'onBlur' | 'onSubmit';
+    /**
+     * Form behavior settings.
+     */
+    settings?: FormSettings;
+}
+
+/**
+ * Represents the current reactive state of a form.
+ * Adapters must ensure this triggers re-renders when values change.
+ *
+ * This is the MINIMUM state required for BuzzForm to work.
+ * Custom adapters must provide all these properties.
+ */
+interface FormState {
+    /** True while the form is being submitted */
+    isSubmitting: boolean;
+    /** True while validation is running (async validators) */
+    isValidating: boolean;
+    /** True if any field has been modified from its default value */
+    isDirty: boolean;
+    /** True if all validations pass (no errors) */
+    isValid: boolean;
+    /** True while async default values are being resolved */
+    isLoading: boolean;
+    /**
+     * Field-level errors.
+     * Key is the field path (e.g., "email", "address.city", "items.0.name")
+     * Value is the error message(s)
+     *
+     * NOTE: Path format uses dot notation. Array indices use numbers (items.0.name).
+     */
+    errors: Record<string, string | string[] | undefined>;
+    /** Map of field paths to whether they've been modified */
+    dirtyFields: Record<string, boolean>;
+    /** Map of field paths to whether they've been touched (blurred) */
+    touchedFields: Record<string, boolean>;
+    /** Number of times the form has been submitted */
+    submitCount: number;
+}
+/**
+ * Options when programmatically setting a field value.
+ */
+interface SetValueOptions {
+    /** Run validation after setting the value (default: adapter-specific) */
+    shouldValidate?: boolean;
+    /** Mark the field as dirty (default: true) */
+    shouldDirty?: boolean;
+    /** Mark the field as touched (default: false) */
+    shouldTouch?: boolean;
+}
+/**
+ * Represents a field-level error.
+ */
+interface FieldError {
+    /** Error type (e.g., 'required', 'pattern', 'server', 'custom') */
+    type?: string;
+    /** Human-readable error message */
+    message: string;
+}
+/**
+ * Result from a validation resolver.
+ */
+interface ResolverResult<TData> {
+    /** Parsed/transformed values (if validation passes) */
+    values?: TData;
+    /** Field errors (if validation fails) */
+    errors?: Record<string, FieldError>;
+}
+/**
+ * A validation resolver function.
+ * Adapters use this to validate form values against a schema.
+ *
+ * @example
+ * // Zod resolver
+ * const zodResolver = (schema) => async (values) => {
+ *   const result = schema.safeParse(values);
+ *   if (result.success) return { values: result.data };
+ *   return { errors: mapZodErrors(result.error) };
+ * };
+ */
+type Resolver<TData> = (values: TData) => Promise<ResolverResult<TData>> | ResolverResult<TData>;
+/**
+ * Helper methods for manipulating array fields.
+ * All methods operate on a field path (e.g., "items", "users.0.tags").
+ *
+ * This is REQUIRED for ArrayField to work. If your custom adapter doesn't
+ * support arrays, you can implement these as no-ops or throw errors.
+ */
+interface ArrayHelpers {
+    /**
+     * Get array items with stable IDs for React keys.
+     * @param path - Field path to the array
+     * @returns Array of items, each with an `id` property for React keys
+     */
+    fields: <T = unknown>(path: string) => Array<T & {
+        id: string;
+    }>;
+    /**
+     * Add an item to the end of the array.
+     */
+    append: (path: string, value: unknown) => void;
+    /**
+     * Add an item to the beginning of the array.
+     */
+    prepend: (path: string, value: unknown) => void;
+    /**
+     * Insert an item at a specific index.
+     */
+    insert: (path: string, index: number, value: unknown) => void;
+    /**
+     * Remove an item at a specific index.
+     */
+    remove: (path: string, index: number) => void;
+    /**
+     * Move an item from one index to another.
+     * Used for drag-and-drop reordering.
+     */
+    move: (path: string, from: number, to: number) => void;
+    /**
+     * Swap two items by their indices.
+     */
+    swap: (path: string, indexA: number, indexB: number) => void;
+    /**
+     * Replace the entire array with new values.
+     */
+    replace: (path: string, values: unknown[]) => void;
+    /**
+     * Update an item at a specific index.
+     */
+    update: (path: string, index: number, value: unknown) => void;
+}
+/**
+ * Base options passed to any adapter when creating a form instance.
+ * Adapters can extend this with library-specific options.
+ *
+ * @typeParam TData - The shape of form data
+ */
+interface AdapterOptions<TData = Record<string, unknown>> {
+    /**
+     * Initial values for the form.
+     * Can be:
+     * - A static object
+     * - A sync function returning values
+     * - An async function returning values (form shows loading state)
+     */
+    defaultValues?: TData | (() => TData) | (() => Promise<TData>);
+    /**
+     * Controlled values - when provided, form becomes controlled.
+     * Changes to this prop will update form values.
+     */
+    values?: TData;
+    /**
+     * Validation resolver.
+     * Called to validate form values before submission and optionally on change/blur.
+     */
+    resolver?: Resolver<TData>;
+    /**
+     * When to run validation.
+     * - 'onChange': Validate on every value change
+     * - 'onBlur': Validate when fields lose focus
+     * - 'onSubmit': Validate only on submit
+     * - 'all': Validate on all events
+     *
+     * NOTE: Not all adapters support all modes. Check adapter documentation.
+     */
+    mode?: 'onChange' | 'onBlur' | 'onSubmit' | 'all';
+    /**
+     * When to re-validate after initial error.
+     * NOTE: This is optional. Some form libraries don't have this concept.
+     */
+    reValidateMode?: 'onChange' | 'onBlur' | 'onSubmit';
+    /**
+     * Callback when form is submitted (after validation passes).
+     */
+    onSubmit?: (values: TData) => Promise<void> | void;
+}
+/**
+ * The contract any form adapter must fulfill.
+ *
+ * ## Required vs Optional
+ *
+ * **Required methods** are the building blocks that BuzzForm needs to function.
+ * If any are missing, forms will break.
+ *
+ * **Optional methods** (marked with `?`) provide enhanced functionality but
+ * are not required. BuzzForm will gracefully degrade without them.
+ *
+ * ## Creating a Custom Adapter
+ *
+ * To create a custom adapter (e.g., for useActionState, Formik, or vanilla React):
+ *
+ * 1. Implement all required properties and methods
+ * 2. Optionally implement enhanced features
+ * 3. Return the adapter from a hook (factory function)
+ *
+ * @example
+ * // Minimal custom adapter skeleton
+ * function useMyAdapter<T>(options: AdapterOptions<T>): FormAdapter<T> {
+ *   const [values, setValues] = useState(options.defaultValues ?? {});
+ *   const [errors, setErrors] = useState({});
+ *   const [isSubmitting, setIsSubmitting] = useState(false);
+ *
+ *   return {
+ *     control: null, // Your state/context
+ *     get formState() { return { ... } },
+ *     handleSubmit: async (e) => { ... },
+ *     getValues: () => values,
+ *     setValue: (name, value) => { ... },
+ *     reset: (vals) => setValues(vals ?? {}),
+ *     watch: (name) => name ? values[name] : values,
+ *     validate: async () => true,
+ *     setError: (name, error) => { ... },
+ *     clearErrors: () => setErrors({}),
+ *     array: createArrayHelpers(...),
+ *   };
+ * }
+ *
+ * @typeParam TData - The shape of form data
+ */
+interface FormAdapter<TData = Record<string, unknown>> {
+    /**
+     * Form-level behavior settings.
+     * Set by useForm after applying FormSettings.
+     */
+    settings?: FormSettings;
+    /**
+     * The underlying form library's control/instance.
+     *
+     * This is passed to field components that need direct access to the form
+     * library (e.g., for React Hook Form's Controller).
+     *
+     * For custom adapters, this can be:
+     * - Your state object
+     * - A context value
+     * - null (if not needed)
+     */
+    control: unknown;
+    /**
+     * Current form state.
+     * MUST be implemented as a getter to ensure reactivity.
+     *
+     * @example
+     * get formState() {
+     *   return {
+     *     isSubmitting: this._isSubmitting,
+     *     isValidating: false,
+     *     isDirty: Object.keys(this._touched).length > 0,
+     *     isValid: Object.keys(this._errors).length === 0,
+     *     isLoading: false,
+     *     errors: this._errors,
+     *     dirtyFields: this._dirty,
+     *     touchedFields: this._touched,
+     *     submitCount: this._submitCount,
+     *   };
+     * }
+     */
+    formState: FormState;
+    /**
+     * Submit handler to attach to a form element.
+     * Should prevent default, run validation, and call onSubmit if valid.
+     *
+     * @example
+     * <form onSubmit={adapter.handleSubmit}>
+     */
+    handleSubmit: (e?: FormEvent) => Promise<void> | void;
+    /**
+     * Get all current form values.
+     */
+    getValues: () => TData;
+    /**
+     * Set a single field's value.
+     *
+     * @param name - Field path (e.g., "email", "address.city", "items.0.name")
+     * @param value - New value
+     * @param options - Additional options
+     */
+    setValue: (name: string, value: unknown, options?: SetValueOptions) => void;
+    /**
+     * Reset form to default values or provided values.
+     *
+     * @param values - Optional new values to reset to
+     */
+    reset: (values?: Partial<TData>) => void;
+    /**
+     * Watch one or more field values reactively.
+     * Returns current value(s) and causes re-render when they change.
+     *
+     * @param name - Field path to watch, or undefined for all values
+     * @returns Current value(s)
+     */
+    watch: <T = unknown>(name?: string) => T;
+    /**
+     * Manually trigger validation.
+     *
+     * @param name - Field(s) to validate, or undefined for entire form
+     * @returns True if validation passes
+     */
+    validate: (name?: string | string[]) => Promise<boolean>;
+    /**
+     * Set a field error programmatically.
+     * Useful for server-side validation errors.
+     *
+     * @param name - Field path
+     * @param error - Error details
+     */
+    setError: (name: string, error: FieldError) => void;
+    /**
+     * Clear validation errors.
+     *
+     * @param name - Field(s) to clear, or undefined for all errors
+     */
+    clearErrors: (name?: string | string[]) => void;
+    /**
+     * Helpers for manipulating array fields.
+     * Required if you use ArrayField component.
+     */
+    array: ArrayHelpers;
+    /**
+     * Handle field blur event.
+     * Triggers validation if mode is 'onBlur'.
+     *
+     * If not provided, BuzzForm will not trigger blur-based validation.
+     *
+     * @param name - Field path
+     */
+    onBlur?: (name: string) => void;
+    /**
+     * Get the state of a specific field.
+     * More efficient than accessing the entire formState for single fields.
+     *
+     * @param name - Field path
+     */
+    getFieldState?: (name: string) => {
+        isDirty: boolean;
+        isTouched: boolean;
+        invalid: boolean;
+        error?: string;
+    };
+    /**
+     * Programmatically focus a field.
+     * Useful for accessibility and after adding array items.
+     *
+     * @param name - Field path
+     * @param options - Focus options
+     */
+    setFocus?: (name: string, options?: {
+        shouldSelect?: boolean;
+    }) => void;
+    /**
+     * Unregister a field from the form.
+     * Called when conditional fields are hidden.
+     *
+     * If not provided, hidden fields will retain their values.
+     *
+     * @param name - Field path(s) to unregister
+     */
+    unregister?: (name: string | string[]) => void;
+}
+/**
+ * Type for an adapter factory function (hook).
+ *
+ * @example
+ * // Using the adapter
+ * function MyApp() {
+ *   return (
+ *     <FormProvider adapter={useRhfAdapter}>
+ *       <MyForm />
+ *     </FormProvider>
+ *   );
+ * }
+ */
+type AdapterFactory<TData = Record<string, unknown>> = (options: AdapterOptions<TData>) => FormAdapter<TData>;
+/**
+ * Validates that a FormAdapter has all required methods.
+ * Call this in development to catch missing implementations early.
+ *
+ * @param adapter - The adapter to validate
+ * @param adapterName - Name for error messages
+ * @throws Error if required methods are missing
+ */
+declare function validateAdapter(adapter: FormAdapter, adapterName?: string): void;
+
+export { type ArrayHelpers as A, type BaseField as B, type ConditionContext as C, type DateField as D, type EmailField as E, type Field as F, type GroupField as G, type Tab as H, type TabsField as I, type CollapsibleField as J, type FieldType as K, type DataField as L, type LayoutField as M, type NumberField as N, type BuzzFormSchema as O, type PasswordField as P, type FormSettings as Q, type ResolverResult as R, type SetValueOptions as S, type TextField as T, type UseFormOptions as U, type ValidationContext as V, type FormConfig as a, type FormAdapter as b, type FormState as c, type FieldError as d, type Resolver as e, type AdapterOptions as f, type AdapterFactory as g, type ValidationResult as h, type ValidationFn as i, type FieldCondition as j, type FieldComponentProps as k, type FieldInputProps as l, type FieldInputRenderFn as m, type FieldStyle as n, type TextareaField as o, type DatetimeField as p, type SelectOption as q, type SelectField as r, type CheckboxField as s, type SwitchField as t, type RadioField as u, validateAdapter as v, type TagsField as w, type UploadField as x, type ArrayField as y, type RowField as z };