@classytic/formkit 1.4.0 → 1.5.0

package/CHANGELOG.md

@@ -5,6 +5,67 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.5.0] - 2026-07-02
+
+Stability / hardening release. Two intentional **behavioral changes** are called
+out below — read them before upgrading.
+
+### Behavioral changes
+
+- **`field.number()` no longer injects `min: 0`.** The builder previously added
+  an implicit non-negative constraint; forms relying on it must now pass
+  `{ min: 0 }` explicitly. Signed quantities (deltas, temperatures) are valid by
+  default.
+- **Missing components render a visible placeholder in production** (previously
+  a silent null). The wrong-widget `text` fallback for unregistered types was
+  removed entirely. Use the new `onMissingComponent` provider callback for
+  telemetry. Exception: `hidden` fields with no registered component render
+  nothing by design.
+
+### Added
+
+- `validateSchema(schema)` — structural schema linting (missing name/type,
+  duplicate names, `itemFields` on non-containers, unknown DSL operators),
+  exported from both entries and auto-run in dev by `FormGenerator`.
+- `focusFirstError(root?)` — focuses the first visibly-invalid field in layout
+  order; retries across two animation frames so it works from
+  `handleSubmit(onValid, () => focusFirstError())` on the very first submit.
+- `loadOptions` now receives `{ signal: AbortSignal }` as a second argument;
+  superseded/unmounted loads are aborted. New opt-in `cacheOptions` memoizes
+  results per watched-value signature (bounded).
+- `onMissingComponent` callback on `FormSystemProvider`.
+- `colSpan` field prop (surfaced as `data-col-span`; `fullWidth` now also emits
+  an inline `grid-column: 1 / -1` so full-width layout works without scanning
+  the package with Tailwind).
+- `resetOnSchemaChange` option on `useFormKit` for DB-loaded schema swaps.
+- Dev warning when `loadOptions` is used without `watchNames` (whole-form
+  refetch storms).
+- `buildFieldDefaults` exported; array-item seeds are now type-aware (`false`
+  for checkbox/switch, `[]` for multiselect/tags, `undefined` for number).
+- `mergeDefaultValues(base, override)` exported (both entries) — the exact
+  Date-safe deep merge `useFormKit` applies between schema defaults and caller
+  `defaultValues`, for wrappers that re-seed via `form.reset(...)`.
+
+### Fixed
+
+- **Rules-of-hooks crash**: `useFieldComponent` and the field-props memo are
+  hoisted above the group/array fallback returns, so a registry that changes
+  after mount (code-split adapters) can no longer change the hook count.
+  `eslint-plugin-react-hooks` is now enforced in CI-lint.
+- **Date / class-instance defaults survive merging**: `useFormKit`'s deep-merge
+  now replaces non-plain objects (Date, File, class instances) wholesale
+  instead of spread-merging them into `{}`.
+- Function conditions with `watchNames` receive properly **nested** watched
+  values (`(v) => v.address.city` works; previously flat `"address.city"` keys
+  made them throw and hide the field).
+- `extractDefaultValues` recurses into nested groups (deep defaults were
+  dropped beyond one level); shares one walker with the async variant.
+- Fallback UI (array items, error boundary, missing-component placeholder) uses
+  structural inline styles + `currentColor` instead of Tailwind classes that
+  don't exist in consumer builds; `formkit-*` classes remain as theming hooks.
+- `process.env` reads are guarded (`isDev()` helper), so bundler-less ESM
+  environments no longer throw `ReferenceError`.
+
 ## [1.4.0] - 2026-05-26
 
 ### Added

package/README.md

@@ -8,8 +8,12 @@ Headless, type-safe form generation engine for React 19. Schema-driven with full
 
 ## Features
 
-- **Minimal boilerplate** - `useFormKit` hook: 5 lines to set up a complete form
-- **Headless** - Bring your own UI components (Shadcn, MUI, Chakra, etc.)
+- **Headless** - Bring your own UI components (Shadcn, MUI, Chakra, etc.) via a
+  one-time component/layout adapter. Already using shadcn? Skip the adapter
+  entirely with the prebuilt one in **[`@classytic/fluid/formkit`](https://www.npmjs.com/package/@classytic/fluid)** —
+  its `SchemaForm` is genuinely a schema + `onSubmit` away.
+- **Minimal boilerplate** - once an adapter is registered, `useFormKit` wires a
+  full form (defaults + RHF + generator props) in a few lines
 - **Schema-driven** - Define forms with JSON/TypeScript schemas, defaults extracted automatically
 - **Type-safe** - Full TypeScript support with generics
 - **React Hook Form** - Built on top of the best form library, referentially stable return values
@@ -20,7 +24,7 @@ Headless, type-safe form generation engine for React 19. Schema-driven with full
 - **Responsive layouts** - Multi-column grid layouts
 - **Accessibility** - Auto-generated `fieldId`, `error`, and `fieldState` props
 - **Validation helpers** - `buildValidationRules` generates RHF rules from schema props
-- **Lightweight** - ~12KB gzipped (peer deps excluded), tree-shakeable
+- **Lightweight** - ~17KB gzipped (peer deps excluded, everything included), tree-shakeable
 
 ## Requirements
 
@@ -127,9 +131,16 @@ const layouts: LayoutRegistry = {
       {children}
     </div>
   ),
-  grid: ({ children, cols = 1 }) => (
-    <div className={`grid grid-cols-${cols} gap-4`}>{children}</div>
-  ),
+  grid: ({ children, cols = 1 }) => {
+    // Map to STATIC class names. A template like `grid-cols-${cols}` is never
+    // generated by Tailwind's JIT (it only sees whole class strings in source).
+    const COLS: Record<number, string> = {
+      1: "grid-cols-1",
+      2: "grid-cols-1 md:grid-cols-2",
+      3: "grid-cols-1 md:grid-cols-2 lg:grid-cols-3",
+    };
+    return <div className={`grid gap-4 ${COLS[cols] ?? "grid-cols-1"}`}>{children}</div>;
+  },
 };
 
 export function FormProvider({ children }: { children: React.ReactNode }) {
@@ -198,6 +209,26 @@ export default function SignupPage() {
 }
 ```
 
+## Type safety
+
+Field **names** are enforced against your form type at *authoring* time by the
+builders. Use `field.for<T>()`, `defineField<T>()`, or `section<T>()` and a typo
+is a compile error:
+
+```ts
+const f = field.for<SignupData>();
+f.text("emial", "Email"); // ✗ compile error — "emial" is not a key of SignupData
+f.text("email", "Email"); // ✓
+```
+
+The `<FormGenerator schema>` / `useFormKit({ schema })` props themselves accept
+`FormSchema<any>` **by design**: a schema's condition functions (`(values) => …`)
+make `FormSchema<T>` contravariant in `T`, so pinning the prop to the form's `T`
+would force a cast at every call site. Author with the typed builders for name
+safety; the generator stays permissive so any built schema drops in without
+ceremony. `itemFields` (group/array children) use relative names and are
+resolved at render time, so they are typed loosely on purpose.
+
 ## API Reference
 
 ### useFormKit
@@ -216,6 +247,7 @@ const form = useFormKit({
   disabled: false,                          // optional
   variant: "compact",                       // optional
   className: "my-form",                     // optional
+  resetOnSchemaChange: true,                // optional — re-seed on schema swap
   mode: "onBlur",                           // any useForm option
 });
 
@@ -234,7 +266,9 @@ return (
 );
 ```
 
-Schema `defaultValue` fields are automatically extracted and merged with any explicit `defaultValues` you provide (explicit values take priority).
+Schema `defaultValue` fields are automatically extracted and merged with any explicit `defaultValues` you provide (explicit values take priority). Nested/namespaced defaults are extracted as a nested object (`{ address: { city } }`), so react-hook-form's dot-path resolution applies them correctly.
+
+Pass `resetOnSchemaChange: true` to re-seed the form when the `schema` identity changes at runtime (e.g. a schema loaded from a DB is swapped in). It's off by default because a reset discards in-progress edits.
 
 `generatorProps` is memoized — it only recomputes when `schema`, `control`, `disabled`, `variant`, or `className` change.
 
@@ -361,9 +395,14 @@ interface FieldComponentProps<T extends FieldValues = FieldValues>
     isDirty: boolean;
     isTouched: boolean;
     isValidating: boolean;
+    isSubmitted: boolean;
     error?: FieldError;
   };
   fieldId: string;              // Generated ID for label-input association (e.g. "formkit-field-email")
+  errorId: string;              // ID for the error node — set as aria-errormessage on the input
+  shouldShowError: boolean;     // true only after touch/submit (mirrors :user-invalid timing)
+  rules: RegisterOptions;       // Pre-computed RHF rules from schema (required/min/max/pattern…)
+  isLoading?: boolean;          // true while async loadOptions is in flight
 }
 ```
 
@@ -466,6 +505,64 @@ function FormInput({ field, control, error, fieldId }: FieldComponentProps) {
 
 Maps `required`, `min`, `max`, `minLength`, `maxLength`, and `pattern` from the field schema to RHF-compatible rules with auto-generated error messages.
 
+## Validation & helpers
+
+### validateSchema
+
+Structurally validate a schema (great for DB-loaded / `resetOnSchemaChange`
+schemas). Server-safe; returns `SchemaIssue[]` (empty ⇒ OK). `FormGenerator`
+also runs it automatically in dev and `console.warn`s any issues.
+
+```ts
+import { validateSchema } from "@classytic/formkit"; // or /server
+
+for (const issue of validateSchema(schema)) {
+  console.warn(`${issue.severity} ${issue.path}: ${issue.message}`);
+}
+// Detects: missing name/type, duplicate names (namespace-aware),
+// itemFields on a non-container, empty containers, unknown DSL operators.
+```
+
+It validates **shape**, not your component registry — an unregistered field
+`type` is a rendering concern, surfaced separately (see `onMissingComponent`).
+
+### focusFirstError
+
+Focus + scroll to the first visibly-invalid field, in layout order. Wire it into
+the submit's invalid handler:
+
+```tsx
+import { focusFirstError } from "@classytic/formkit";
+
+<form onSubmit={handleSubmit(onValid, () => focusFirstError())}>
+```
+
+React Hook Form calls the invalid handler *before* React commits the re-render
+that marks fields invalid, so if the immediate query finds nothing,
+`focusFirstError` automatically retries on the next two animation frames — the
+plain wiring above works on the very first submit. It returns `true` when a
+field was focused immediately, `false` when the attempt was deferred.
+
+### onMissingComponent
+
+If a field's `type` has no registered component, the form renders a **visible
+placeholder** (dev and prod — never a silent drop or a wrong-widget text input)
+and notifies this callback so you can log the gap. `hidden` fields are the one
+exception: with no registered component they render nothing by design (the
+value still lives in form state); register a `hidden` component to override.
+
+```tsx
+<FormSystemProvider
+  components={components}
+  layouts={layouts}
+  onMissingComponent={(type) => reportToTelemetry("formkit_missing_component", { type })}
+>
+```
+
+> **Security note:** `buildValidationRules` compiles a field's `pattern` into a
+> `new RegExp(...)`. If your schemas are ever authored by untrusted users, treat
+> `pattern` as a ReDoS surface — validate/limit it before persisting.
+
 ## Server Components
 
 The `@classytic/formkit/server` entry point exports server-safe utilities with no React hooks or client-side code:
@@ -494,6 +591,24 @@ import type {
 
 Use this entry point in React Server Components to define schemas, evaluate conditions, or use `cn` without pulling in client-side code.
 
+### Passing a schema across the RSC → Client boundary
+
+`FormGenerator` is a Client Component (it drives react-hook-form). If you build
+a schema in a Server Component and pass it as a prop into the client, React
+requires that prop to be **serializable** — so **function** members won't cross
+the boundary:
+
+- ❌ function `condition: (values) => …`, custom `render`, and `loadOptions`
+  (functions aren't serializable)
+- ✅ **DSL** conditions (`{ watch, operator, value }`), and all the plain data
+  fields (`name`, `type`, `label`, `options`, `required`, `min`/`max`, …)
+
+For fully static, server-defined schemas use DSL conditions. If a schema needs
+function conditions / custom renders / async options, define it **inside the
+Client Component** (e.g. the file that renders `FormGenerator`) rather than
+passing it down from an RSC. This is a general Next.js constraint, not specific
+to formkit.
+
 ## Advanced Features
 
 ### Conditional Fields (Function)
@@ -507,6 +622,12 @@ Use this entry point in React Server Components to define schemas, evaluate cond
 }
 ```
 
+> **Performance:** a function condition can't be statically analyzed, so the
+> field subscribes to the **whole form** and re-evaluates on every change. For
+> large forms prefer a DSL rule (below, whose watched paths are auto-scoped), or
+> add `watchNames` to scope the subscription yourself:
+> `{ condition: (v) => v.accountType === "business", watchNames: ["accountType"] }`.
+
 ### Conditional Fields (DSL Rules)
 
 ```ts
@@ -604,14 +725,20 @@ const components = {
   name: "city",
   type: "select",
   watchNames: ["country"],
-  loadOptions: async (values) => {
-    const cities = await fetchCities(values.country);
+  loadOptions: async (values, { signal }) => {
+    // Forward `signal` so a superseded/unmounted load is cancelled.
+    const cities = await fetchCities(values.country, { signal });
     return cities.map(c => ({ label: c.name, value: c.id }));
   },
   debounceMs: 300,
+  cacheOptions: true, // reuse the last fetch when a dependency is re-selected
 }
 ```
 
+> `cacheOptions` (default `false`) memoizes results per watched-value signature
+> for the field's lifetime, so toggling `country` back and forth doesn't re-hit
+> the API. Leave it off when the options can change server-side between loads.
+
 ### Custom Section Render
 
 ```ts

package/dist/index.d.mts

@@ -138,6 +138,13 @@ interface BaseField<TFieldValues extends FieldValues = FieldValues> {
   variant?: Variant;
   /** Whether field should span full width in grid */
   fullWidth?: boolean;
+  /**
+   * Span N columns of the section grid (e.g. `2` of a 3-col section). `1` (or
+   * unset) is the default single cell; `fullWidth` still means "span the whole
+   * row" and takes precedence. Applied as an inline `grid-column: span N` so it
+   * works regardless of the host's Tailwind content scan.
+   */
+  colSpan?: number;
   /** Custom CSS class name */
   className?: string;
   /**
@@ -199,13 +206,33 @@ interface BaseField<TFieldValues extends FieldValues = FieldValues> {
   /**
    * Dynamic options loaded based on current form values.
    * Useful for dependent selects (e.g., state depends on country).
+   *
+   * Receives an `AbortSignal` in the second arg — forward it to `fetch` (or
+   * abort your own request on it) so a superseded / unmounted load is cancelled
+   * instead of racing to completion:
+   *
+   * ```ts
+   * loadOptions: (values, { signal }) =>
+   *   fetch(`/api/cities?country=${values.country}`, { signal }).then(r => r.json())
+   * ```
    */
-  loadOptions?: (formValues: Partial<TFieldValues>) => Promise<(FieldOption | FieldOptionGroup)[]> | (FieldOption | FieldOptionGroup)[];
+  loadOptions?: (formValues: Partial<TFieldValues>, options?: {
+    signal: AbortSignal;
+  }) => Promise<(FieldOption | FieldOptionGroup)[]> | (FieldOption | FieldOptionGroup)[];
   /**
    * Error callback for loadOptions failures.
    * Called when loadOptions rejects. Defaults to console.error.
    */
   onLoadError?: (error: unknown) => void;
+  /**
+   * Memoize async `loadOptions` results per set of watched values, so toggling
+   * a dependency back and forth (e.g. re-selecting a country) reuses the last
+   * fetch instead of hitting the API again. Off by default — enable only when
+   * the options are stable for a given input, since the cache lives for the
+   * field's lifetime and won't see server-side changes. Bounded (LRU-ish) so it
+   * can't grow without limit.
+   */
+  cacheOptions?: boolean;
   /**
    * Sub-fields for `group` and `array` field types.
    *
@@ -553,6 +580,8 @@ interface FormSystemContextValue {
   components: ComponentRegistry;
   /** Registered layout components */
   layouts: LayoutRegistry;
+  /** Notified when a field type has no registered component (see provider). */
+  onMissingComponent?: (type: string, variant?: string) => void;
 }
 /**
  * Form system provider props.
@@ -562,6 +591,13 @@ interface FormSystemProviderProps {
   components?: ComponentRegistry;
   /** Layout component registry */
   layouts?: LayoutRegistry;
+  /**
+   * Called (once per type) when a field's `type` has no registered component
+   * and the visible placeholder is shown instead. Use it to log/report the
+   * missing registration to your telemetry — the form still renders a
+   * placeholder rather than silently dropping the field.
+   */
+  onMissingComponent?: (type: string, variant?: string) => void;
   /** Children content */
   children: ReactNode;
 }
@@ -718,6 +754,7 @@ declare const FieldWrapper: typeof FieldWrapperImpl;
 declare function FormSystemProvider({
   components,
   layouts,
+  onMissingComponent,
   children
 }: FormSystemProviderProps): FormElement;
 /**
@@ -739,11 +776,16 @@ declare function useFormSystem(): FormSystemContextValue;
  * 1. Variant-specific component: `components[variant][type]`
  * 2. Type-specific component: `components[type]`
  * 3. Default component: `components["default"]`
- * 4. Text fallback: `components["text"]`
+ *
+ * There is intentionally NO "text" fallback: rendering a text input for an
+ * unregistered `date`/`switch`/etc. is a silent wrong-widget bug. A missing
+ * registration instead renders a visible placeholder (`MissingFieldComponent`)
+ * — in production too — and notifies `onMissingComponent`, so the gap is
+ * observable rather than a mystery empty box.
  *
  * @param type - Field type identifier
  * @param variant - Optional variant name
- * @returns Field component or fallback
+ * @returns Field component or the visible placeholder
  *
  * @internal
  */
@@ -837,6 +879,54 @@ declare function defineSection<TFieldValues extends FieldValues = FieldValues>(s
  * ```
  */
 declare function extractDefaultValues<TFieldValues extends FieldValues = FieldValues>(schema: FormSchema<TFieldValues>): Partial<TFieldValues>;
+interface SchemaIssue {
+  /** Where the issue is, e.g. `sections[0].fields[2]` or `sections[1]`. */
+  path: string;
+  code: "missing-name" | "missing-type" | "duplicate-name" | "itemfields-on-noncontainer" | "empty-container" | "unknown-operator";
+  /** `error` = will misbehave at runtime; `warning` = suspicious but tolerated. */
+  severity: "error" | "warning";
+  message: string;
+}
+/**
+ * Structurally validate a form schema and return a list of issues (empty ⇒ OK).
+ * Server-safe (no hooks/DOM), so you can run it when a schema is loaded from a
+ * DB, in a test, or in a dev boot check. It validates SHAPE, not your component
+ * registry — an unknown field `type` is a registry concern, not a schema error.
+ *
+ * Checks: missing `name`/`type`, duplicate names (namespace-aware), `itemFields`
+ * on a non-container type, containers with no `itemFields`, and unknown DSL
+ * condition operators.
+ */
+declare function validateSchema(schema: FormSchema): SchemaIssue[];
+/**
+ * Build a default-value object for a flat list of fields — used to seed a new
+ * array item (or a group) from its `itemFields`.
+ *
+ * Recurses into nested `group` children (→ nested object) and seeds nested
+ * `array` children as `[]`, so appending an item never leaves a deep sub-field
+ * `undefined`. That matters because a missing deep field can trip a resolver
+ * (zod et al.) into a spurious "required" error the moment the row is added.
+ * Leaf fields without an explicit `defaultValue` seed to `""` (a controlled
+ * empty value RHF is happy with).
+ */
+declare function buildFieldDefaults(fields: BaseField[] | undefined): Record<string, unknown>;
+/**
+ * Deep-merge `override` onto `base` with default-values semantics: nested
+ * plain objects merge recursively; arrays, primitives, and class instances
+ * (Date, File, …) from `override` replace wholesale.
+ *
+ * This is the merge `useFormKit` applies between schema-extracted defaults and
+ * caller-provided `defaultValues`. Exported so wrappers that re-seed a form at
+ * runtime (e.g. an edit sheet swapping entities) can reproduce the exact same
+ * merge for `form.reset(...)`:
+ *
+ * @example
+ * ```ts
+ * const merged = mergeDefaultValues(extractDefaultValues(schema), entity);
+ * form.reset(merged);
+ * ```
+ */
+declare function mergeDefaultValues(base: Record<string, unknown>, override: Record<string, unknown>): Record<string, unknown>;
 /**
  * Async version of `extractDefaultValues` for large schemas (50+ fields).
  * Yields to the main thread after each section so that the browser can
@@ -1005,7 +1095,10 @@ declare const field: {
   email: <T extends FieldValues = FieldValues>(name: Path<T>, label: string, props?: FieldProps<T>) => BaseField<T>; /** URL input field with default placeholder. */
   url: <T extends FieldValues = FieldValues>(name: Path<T>, label: string, props?: FieldProps<T>) => BaseField<T>; /** Phone/tel input field with default placeholder. */
   tel: <T extends FieldValues = FieldValues>(name: Path<T>, label: string, props?: FieldProps<T>) => BaseField<T>; /** Password input field. */
-  password: <T extends FieldValues = FieldValues>(name: Path<T>, label: string, props?: FieldProps<T>) => BaseField<T>; /** Number input field with min: 0 default (overrideable via props). */
+  password: <T extends FieldValues = FieldValues>(name: Path<T>, label: string, props?: FieldProps<T>) => BaseField<T>;
+  /** Number input field. No implicit `min` — pass `{ min }` to add one, so the
+   *  builder never injects validation the author didn't write (signed
+   *  quantities like deltas / temperatures stay valid). */
   number: <T extends FieldValues = FieldValues>(name: Path<T>, label: string, props?: FieldProps<T>) => BaseField<T>; /** Textarea field with default 3 rows. */
   textarea: <T extends FieldValues = FieldValues>(name: Path<T>, label: string, props?: FieldProps<T>) => BaseField<T>; /** Select dropdown field. */
   select: <T extends FieldValues = FieldValues>(name: Path<T>, label: string, options: (FieldOption | FieldOptionGroup)[], props?: FieldProps<T>) => BaseField<T>; /** Searchable combobox field. */
@@ -1166,6 +1259,14 @@ interface UseFormKitOptions<TFieldValues extends FieldValues = FieldValues> exte
   variant?: Variant;
   /** Root element className */
   className?: string;
+  /**
+   * Re-seed the form with the schema's freshly-extracted defaults whenever the
+   * `schema` identity changes (e.g. a schema fetched from a DB is swapped in).
+   * Off by default because a reset discards in-progress edits — enable it only
+   * when a schema swap should intentionally re-initialise the form. Skipped when
+   * `defaultValues` is an async factory (the caller owns that reset).
+   */
+  resetOnSchemaChange?: boolean;
 }
 /**
  * Return value from useFormKit.
@@ -1196,4 +1297,30 @@ interface UseFormKitReturn<TFieldValues extends FieldValues = FieldValues> exten
  */
 declare function useFormKit<TFieldValues extends FieldValues = FieldValues>(options: UseFormKitOptions<TFieldValues>): UseFormKitReturn<TFieldValues>;
 //#endregion
-export { type BaseField, type ClassValue, type ComponentRegistry, type Condition, type ConditionConfig, type ConditionRule, type DefaultLayoutProps, type DefineField, type FieldComponent, type FieldComponentProps, type FieldMeta, type FieldOption, type FieldOptionGroup, type FieldType, FieldWrapper, type FieldWrapperProps, type FormElement, FormGenerator, type FormGeneratorProps, type FormSchema, type FormSystemContextValue, FormSystemProvider, type FormSystemProviderProps, type GridLayoutProps, GridRenderer, type GridRendererProps, type InferSchemaValues, type LayoutComponent, type LayoutComponentProps, type LayoutRegistry, type LayoutType, type PatternRuleObject, type SchemaFieldNames, type Section, type SectionLayoutProps, type SectionRenderProps, SectionRenderer, type SectionRendererProps, type UseFormKitOptions, type UseFormKitReturn, type ValidationRuleObject, type ValidationRules, type Variant, applyServerErrors, buildValidationRules, cn, defineField, defineSchema, defineSection, evaluateCondition, extendSection, extractDefaultValues, extractDefaultValuesAsync, extractWatchNames, field, flattenSchema, isArrayField, isChoiceField, isConditionalField, isContainerField, isDateField, isDynamicField, isNumericField, isTextField, mergeSchemas, omitFields, pickFields, section, sectionUntitled, shallowEqual, useFieldComponent, useFormKit, useFormSystem, useLayoutComponent };
+//#region src/focus.d.ts
+/**
+ * Focus (and scroll to) the first field currently shown as invalid.
+ *
+ * It queries the rendered `[data-formkit-field][data-invalid]` wrapper — which
+ * `FormGenerator` marks once errors are visible (after touch / submit) — so it
+ * targets the first error in **visual order**, not react-hook-form's error-key
+ * order (which isn't guaranteed to match the layout). Wire it into your submit's
+ * invalid handler:
+ *
+ * ```ts
+ * form.handleSubmit(onValid, () => focusFirstError());
+ * ```
+ *
+ * **Timing:** react-hook-form calls the invalid handler *before* React commits
+ * the re-render that sets `data-invalid` on the wrappers, so on the very first
+ * invalid submit a synchronous query finds nothing. When the immediate attempt
+ * misses, this retries on the next two animation frames (the commit lands
+ * before the next paint), so the plain wiring above Just Works.
+ *
+ * @param root  Optional container to search within (defaults to `document`).
+ * @returns `true` if a field was focused immediately; `false` if not found yet
+ *          (a deferred retry may still focus it on the next frame).
+ */
+declare function focusFirstError(root?: HTMLElement | Document | null): boolean;
+//#endregion
+export { type BaseField, type ClassValue, type ComponentRegistry, type Condition, type ConditionConfig, type ConditionRule, type DefaultLayoutProps, type DefineField, type FieldComponent, type FieldComponentProps, type FieldMeta, type FieldOption, type FieldOptionGroup, type FieldType, FieldWrapper, type FieldWrapperProps, type FormElement, FormGenerator, type FormGeneratorProps, type FormSchema, type FormSystemContextValue, FormSystemProvider, type FormSystemProviderProps, type GridLayoutProps, GridRenderer, type GridRendererProps, type InferSchemaValues, type LayoutComponent, type LayoutComponentProps, type LayoutRegistry, type LayoutType, type PatternRuleObject, type SchemaFieldNames, type SchemaIssue, type Section, type SectionLayoutProps, type SectionRenderProps, SectionRenderer, type SectionRendererProps, type UseFormKitOptions, type UseFormKitReturn, type ValidationRuleObject, type ValidationRules, type Variant, applyServerErrors, buildFieldDefaults, buildValidationRules, cn, defineField, defineSchema, defineSection, evaluateCondition, extendSection, extractDefaultValues, extractDefaultValuesAsync, extractWatchNames, field, flattenSchema, focusFirstError, isArrayField, isChoiceField, isConditionalField, isContainerField, isDateField, isDynamicField, isNumericField, isTextField, mergeDefaultValues, mergeSchemas, omitFields, pickFields, section, sectionUntitled, shallowEqual, useFieldComponent, useFormKit, useFormSystem, useLayoutComponent, validateSchema };