import type { Ref } from '@stacksjs/stx';
/**
 * Reactive form primitive with schema validation + submit orchestration.
 *
 * @example
 * ```ts
 * const form = useForm({
 *   initialValues: { email: '', password: '' },
 *   schema: {
 *     email: schema.string().email().required(),
 *     password: schema.string().min(6).required(),
 *   },
 *   onSubmit: async (values) => {
 *     const r = await authStore.login(values)
 *     if (!r.ok) form.setError('form', r.error)
 *   },
 * })
 * ```
 */
export declare function useForm<TValues extends Record<string, unknown>>(opts: UseFormOptions<TValues>): UseFormResult<TValues>;
/**
 * useForm (stacksjs/stacks#1940 — Phase 1).
 *
 * Per-field state + schema validation + submit orchestration.
 * Builds on `@stacksjs/validation`'s ts-validation surface — pass any
 * field-keyed bag of `schema.string()...` etc. and the composable
 * runs `.validate(value)` to surface the first message.
 *
 * Phase 1 deliberately ships the primitive only; the `<Field>` /
 * `<SubmitButton>` / `<ErrorMessage>` companion components, field
 * arrays, server-error auto-surfacing on 422, and progressive HTML
 * fallback are scoped to Phases 2-5 of the issue.
 *
 * ---
 *
 * THERE IS A SECOND `useForm`, in stx
 * (packages/stx/src/composables/use-form.ts, called `defineForm` before
 * stacksjs/stx#1843). It is not this one, and the two are not interchangeable —
 * they were written independently because neither side could find the other's,
 * which is stx#1843's adoption problem happening to the framework itself.
 *
 *   this one                        stx
 *   useForm({ initialValues,        useForm(schema, initialValues)
 *             onSubmit })
 *   form.values.value.email         form.values.email
 *   form.field('email')             form.getFieldState('email')
 *   schema.string().email()         v.required().email()  (stx's own builder)
 *   validate() -> { valid, errors } validate() -> Promise<string[]>
 *   has: isSubmitting, isValid,     has: validating, validateField
 *        isDirty, setErrors (422),
 *        clearErrors,
 *        submitButtonProps,
 *        firstErrorField,
 *        aria inputProps
 *
 * stx's is the one that reaches a `<script client>` block via the demand
 * bundler; this one is delivered through the browser vendors re-export.
 *
 * Before adding a feature here, check whether it exists there — and say so in
 * the PR either way. Unifying them is a breaking change to one side's public
 * API, not a re-export, so it needs a deliberate decision rather than drift.
 */
/** Minimal Validator surface this composable depends on. */
export declare interface FormValidator {
  validate: (value: unknown) => { valid: boolean, errors: Array<{ message: string }> | Record<string, Array<{ message: string }>> }
}
export declare interface UseFormOptions<TValues extends Record<string, unknown>> {
  initialValues: TValues
  schema?: Partial<Record<keyof TValues, FormValidator>>
  onSubmit: (values: TValues) => Promise<void> | void
  onError?: (error: Error | Record<string, string>) => void
  validateOn?: ValidationMode
}
/**
 * A ready-to-spread bag of input attributes + handlers for one field
 * (stacksjs/stacks#1940 Phase 2). Encodes the a11y wiring a `<Field>`
 * component would otherwise re-derive by hand: `aria-invalid` flips on a
 * surfaced error, and `aria-describedby` points at the error element's
 * stable id so screen readers announce the message.
 */
export declare interface FieldInputProps<T> {
  name: string
  value: T
  onInput: (eventOrValue: unknown) => void
  onBlur: () => void
  'aria-invalid': boolean
  'aria-describedby': string | undefined
}
export declare interface FormFieldAccessor<T> {
  value: T
  error: string
  touched: boolean
  dirty: boolean
  errorId: string
  setValue: (next: T) => void
  onBlur: () => void
  validate: () => boolean
  inputProps: () => FieldInputProps<T>
}
export declare interface UseFormResult<TValues extends Record<string, unknown>> {
  values: Ref<TValues>
  errors: Ref<Record<string, string>>
  touched: Ref<Record<string, boolean>>
  dirty: Ref<Record<string, boolean>>
  isSubmitting: Ref<boolean>
  isValid: Ref<boolean>
  isDirty: Ref<boolean>
  field: <K extends keyof TValues>(name: K) => FormFieldAccessor<TValues[K]>
  setValue: <K extends keyof TValues>(name: K, value: TValues[K]) => void
  setError: (name: keyof TValues | 'form', message: string) => void
  setErrors: (errorMap: Partial<Record<keyof TValues | 'form', string | string[]>>) => void
  clearErrors: (name?: keyof TValues | 'form') => void
  setTouched: (name: keyof TValues, touched?: boolean) => void
  validate: () => boolean
  handleSubmit: () => Promise<void>
  reset: () => void
  submitButtonProps: () => { type: 'submit', disabled: boolean, 'aria-busy': boolean }
  firstErrorField: () => keyof TValues | null
}
/**
 * Trigger that causes a field to validate.
 * - 'change' — every time the value changes (eager — best for password strength meters)
 * - 'blur'   — when the user moves focus away from the field (default — most natural)
 * - 'submit' — only at submit time (lazy — best for short forms with required-only checks)
 */
export type ValidationMode = 'change' | 'blur' | 'submit';