@classytic/formkit 1.3.1 → 1.5.0

package/dist/index.d.mts

@@ -8,7 +8,7 @@ import { ClassValue } from "clsx";
  * Field type identifier.
  * Can be built-in types or custom string identifiers.
  */
-type FieldType = "text" | "email" | "password" | "number" | "tel" | "url" | "textarea" | "select" | "checkbox" | "radio" | "switch" | "date" | "time" | "datetime" | "file" | "hidden" | "group" | "array" | "custom" | (string & {});
+type FieldType = "text" | "email" | "password" | "number" | "tel" | "phone" | "url" | "textarea" | "slug" | "select" | "combobox" | "multiselect" | "dependentSelect" | "checkbox" | "radio" | "switch" | "date" | "time" | "datetime" | "rich-text" | "color" | "rating" | "tags" | "json" | "file" | "hidden" | "group" | "array" | "custom" | (string & {});
 /**
  * Layout type identifier.
  */
@@ -70,12 +70,55 @@ interface FieldOptionGroup<TValue = string> {
   /** Whether group is disabled */
   disabled?: boolean;
 }
+/**
+ * Object form for length/range validation rules with a custom message.
+ */
+interface ValidationRuleObject<TValue = number> {
+  value: TValue;
+  message: string;
+}
+/**
+ * Object form for pattern validation with a custom message.
+ */
+interface PatternRuleObject {
+  /** Regex string (will be compiled with `new RegExp(regex)`) */
+  regex: string;
+  /** Custom error message */
+  message: string;
+}
+/**
+ * AI-friendly metadata attached to any field.
+ * Consumed by LLM coding assistants, documentation generators, and
+ * schema-introspection tools — never by the form renderer itself.
+ */
+interface FieldMeta {
+  /** Human-readable description of what this field collects */
+  description?: string;
+  /** Representative example value (for documentation / AI context) */
+  example?: unknown;
+  /** Logical category for grouping fields in documentation or tooling */
+  category?: string;
+  /** Arbitrary tags for filtering, search, or feature-flagging */
+  tags?: string[];
+  /** Whether this field is considered PII */
+  pii?: boolean;
+  /** Arbitrary extension point — anything extra you want to carry */
+  [key: string]: unknown;
+}
 /**
  * Base field configuration shared by all field types.
  * @template TFieldValues - Form field values type for type-safe field names
  */
 interface BaseField<TFieldValues extends FieldValues = FieldValues> {
-  /** Field name (must be a valid path in form values) */
+  /**
+   * Field name — a path into TFieldValues (e.g. `"email"`, `"address.street"`).
+   *
+   * Accepts any string so that:
+   * - Namespaced sections can use relative names (`"street"` → prefixed to `"address.street"`)
+   * - Group/array `itemFields` can use relative names (`"email"` → prefixed at render time)
+   *
+   * Use `field.for<T>()` builder for call-site enforcement that names are valid paths.
+   */
   name: Path<TFieldValues> | (string & {});
   /** Field type identifier */
   type: FieldType;
@@ -95,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;
   /**
@@ -106,18 +156,41 @@ interface BaseField<TFieldValues extends FieldValues = FieldValues> {
   defaultValue?: unknown;
   /** Options for select/radio/checkbox fields */
   options?: (FieldOption | FieldOptionGroup)[];
-  /** Minimum value (for number/date fields) */
-  min?: number | string;
-  /** Maximum value (for number/date fields) */
-  max?: number | string;
+  /**
+   * Minimum value (for number/date fields).
+   * Pass an object `{ value, message }` to provide a custom error message.
+   */
+  min?: number | string | ValidationRuleObject<number | string>;
+  /**
+   * Maximum value (for number/date fields).
+   * Pass an object `{ value, message }` to provide a custom error message.
+   */
+  max?: number | string | ValidationRuleObject<number | string>;
   /** Step value (for number fields) */
   step?: number;
-  /** Pattern for validation (regex string) */
-  pattern?: string;
-  /** Minimum length */
-  minLength?: number;
-  /** Maximum length */
-  maxLength?: number;
+  /**
+   * Pattern for validation.
+   * Pass a regex string or `{ regex, message }` for a custom error message.
+   *
+   * @example
+   * ```ts
+   * // simple
+   * pattern: "^[a-z]+$"
+   * // with custom message
+   * pattern: { regex: "^[a-z]+$", message: "Only lowercase letters allowed" }
+   * ```
+   */
+  pattern?: string | PatternRuleObject;
+  /**
+   * Minimum length.
+   * Pass an object `{ value, message }` to provide a custom error message.
+   */
+  minLength?: number | ValidationRuleObject<number>;
+  /**
+   * Maximum length.
+   * Pass an object `{ value, message }` to provide a custom error message.
+   */
+  maxLength?: number | ValidationRuleObject<number>;
   /** Number of rows (for textarea) */
   rows?: number;
   /** Multiple selection (for select/file) */
@@ -133,18 +206,41 @@ 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;
   /**
-   * Fields for array or object types.
-   * Useful for 'array' or 'group' field types that need a sub-schema.
+   * 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.
+   *
+   * These fields use **relative** names (`"street"`, `"email"`) — FormGenerator
+   * prefixes them with the parent field name at render time (`"address.street"`).
+   * They are intentionally untyped to TFieldValues for this reason.
    */
-  itemFields?: BaseField<TFieldValues>[];
+  itemFields?: BaseField[];
   /**
    * Custom render function to override the component registry for this specific field.
    * Completely bypasses the globally registered FieldComponent for this type.
@@ -153,15 +249,22 @@ interface BaseField<TFieldValues extends FieldValues = FieldValues> {
   /**
    * Cross-field validation function.
    * Receives the field value and all form values for cross-field checks.
-   * Return `true` for valid, or a string error message for invalid.
+   * Return `true` for valid, a string error message for invalid, or a Promise of either
+   * for async validation (e.g., checking server-side uniqueness).
    *
    * @example
    * ```ts
    * validate: (value, formValues) =>
    *   value > formValues.minPrice || "Must be greater than min price"
+   *
+   * // Async example
+   * validate: async (value) => {
+   *   const taken = await checkUsernameAvailability(value as string);
+   *   return taken ? "Username already taken" : true;
+   * }
    * ```
    */
-  validate?: (value: unknown, formValues: Partial<TFieldValues>) => string | true;
+  validate?: (value: unknown, formValues: Partial<TFieldValues>) => string | true | Promise<string | true>;
   /**
    * Dependencies for optimizing conditionally rendered fields.
    * Allows specifying specific field names to watch, preventing full form re-renders.
@@ -169,6 +272,32 @@ interface BaseField<TFieldValues extends FieldValues = FieldValues> {
   watchNames?: Path<TFieldValues> | Path<TFieldValues>[];
   /** Additional field-specific props for custom components */
   customProps?: Record<string, unknown>;
+  /**
+   * AI / agent-friendly metadata for this field.
+   *
+   * Provides hints that help LLM coding assistants generate correct field
+   * configs without needing to inspect the schema at runtime.
+   *
+   * @example
+   * ```ts
+   * field.text("companyName", "Company", {
+   *   meta: {
+   *     description: "Legal entity name of the organization",
+   *     example: "Acme Corp",
+   *     category: "identity",
+   *     tags: ["crm", "required-for-billing"],
+   *   }
+   * })
+   * ```
+   */
+  meta?: FieldMeta;
+  /**
+   * Escape hatch for adapter-specific or custom props.
+   * Allows passing arbitrary props directly on the field object so they
+   * flow through the adapter spread (`{...field}`) without needing `customProps`.
+   * Intentionally broad to support diverse UI component libraries.
+   */
+  [key: string]: unknown;
 }
 /**
  * Props passed to field components.
@@ -214,13 +343,68 @@ interface FieldComponentProps<TFieldValues extends FieldValues = FieldValues> ex
     invalid: boolean;
     isDirty: boolean;
     isTouched: boolean;
-    isValidating: boolean;
+    isValidating: boolean; /** True after the enclosing form's submit handler has been called at least once. */
+    isSubmitted: boolean;
     error?: FieldError;
   };
-  /** Generated field ID for label-input association (e.g. `formkit-field-email`) */
+  /**
+   * Generated field ID for label-input association (e.g. `formkit-field-email`).
+   * Use as `id` on the input element and `htmlFor` on the `<label>`.
+   */
   fieldId: string;
+  /**
+   * Generated error container ID for ARIA association (e.g. `formkit-field-email-error`).
+   * Use as `id` on the error message element and as the value for `aria-errormessage`
+   * (preferred) or `aria-describedby` (broader support) on the input.
+   *
+   * @example
+   * ```tsx
+   * <input
+   *   id={fieldId}
+   *   aria-invalid={shouldShowError || undefined}
+   *   aria-errormessage={shouldShowError ? errorId : undefined}
+   * />
+   * <p id={errorId} role="alert" aria-live="polite">
+   *   {shouldShowError ? error?.message : null}
+   * </p>
+   * ```
+   */
+  errorId: string;
+  /**
+   * Whether to display the field error right now.
+   *
+   * Aligns with the CSS `:user-invalid` timing model: `true` only after the
+   * user has interacted with the field (blur) **or** the form has been
+   * submitted. This prevents premature "required" errors on untouched fields.
+   *
+   * Use this — not `!!error` — to drive `aria-invalid`, error message
+   * visibility, and destructive ring/border styles.
+   *
+   * @example
+   * ```tsx
+   * <input aria-invalid={shouldShowError || undefined} />
+   * {shouldShowError && <p id={errorId} role="alert">{error?.message}</p>}
+   * ```
+   */
+  shouldShowError: boolean;
   /** Whether dynamic options are currently loading */
   isLoading?: boolean;
+  /**
+   * Pre-computed react-hook-form validation rules for this field.
+   * Equivalent to calling `buildValidationRules(field)` — provided here so
+   * adapter components can pass `rules={rules}` directly to `<Controller>`
+   * without importing or calling `buildValidationRules` themselves.
+   *
+   * @example
+   * ```tsx
+   * function TextInput({ field, control, rules }: FieldComponentProps) {
+   *   return (
+   *     <Controller name={field.name} control={control} rules={rules} render={...} />
+   *   );
+   * }
+   * ```
+   */
+  rules: ValidationRules;
 }
 /**
  * Field component type.
@@ -271,6 +455,17 @@ interface Section<TFieldValues extends FieldValues = FieldValues> {
   collapsible?: boolean;
   /** Default collapsed state */
   defaultCollapsed?: boolean;
+  /**
+   * Defer rendering of this section until it scrolls near the viewport.
+   * Applies `content-visibility: auto` + `contain-intrinsic-size` to the
+   * section container, skipping layout/paint work while off-screen.
+   *
+   * **Only use for sections that are below the initial fold.** Applying this
+   * to above-fold sections has no benefit and slightly increases overhead.
+   *
+   * @see https://developer.mozilla.org/en-US/docs/Web/CSS/content-visibility
+   */
+  deferRender?: boolean;
 }
 /**
  * Props passed to section render function.
@@ -298,6 +493,12 @@ interface SectionLayoutProps {
   collapsible?: boolean;
   /** Default collapsed state */
   defaultCollapsed?: boolean;
+  /**
+   * When true the section is below the initial fold and should defer
+   * browser layout/paint work until it nears the viewport.
+   * Layout components may apply `content-visibility: auto` here.
+   */
+  deferRender?: boolean;
   /** Children content */
   children: ReactNode;
 }
@@ -336,6 +537,12 @@ type LayoutComponent<TProps extends LayoutComponentProps = LayoutComponentProps>
  * @template TFieldValues - Form field values type for type-safe schemas
  */
 interface FormSchema<TFieldValues extends FieldValues = FieldValues> {
+  /** Optional schema identifier — useful for serialization, analytics, and AI context */
+  id?: string;
+  /** Human-readable form title (AI / documentation use) */
+  title?: string;
+  /** Human-readable description of the form's purpose */
+  description?: string;
   /** Form sections */
   sections: Section<TFieldValues>[];
 }
@@ -373,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.
@@ -382,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;
 }
@@ -462,10 +678,12 @@ interface SectionRendererProps<TFieldValues extends FieldValues = FieldValues> {
   disabled?: boolean;
   variant?: Variant;
 }
+declare function SectionRendererImpl<TFieldValues extends FieldValues = FieldValues>(props: SectionRendererProps<TFieldValues>): FormElement;
 /**
- * Renders a single section with its fields.
+ * Memoized section renderer. Re-renders only when section config or
+ * disabled/variant context changes — not on every form value change.
  */
-declare function SectionRenderer<TFieldValues extends FieldValues = FieldValues>(props: SectionRendererProps<TFieldValues>): FormElement;
+declare const SectionRenderer: typeof SectionRendererImpl;
 interface GridRendererProps<TFieldValues extends FieldValues = FieldValues> {
   fields?: BaseField<TFieldValues>[];
   cols?: number;
@@ -474,10 +692,7 @@ interface GridRendererProps<TFieldValues extends FieldValues = FieldValues> {
   disabled?: boolean;
   variant?: Variant;
 }
-/**
- * Renders a grid of fields with specified column layout.
- */
-declare function GridRenderer<TFieldValues extends FieldValues = FieldValues>({
+declare function GridRendererImpl<TFieldValues extends FieldValues = FieldValues>({
   fields,
   cols,
   gap,
@@ -485,18 +700,22 @@ declare function GridRenderer<TFieldValues extends FieldValues = FieldValues>({
   disabled,
   variant
 }: GridRendererProps<TFieldValues>): FormElement;
+/**
+ * Memoized grid renderer.
+ */
+declare const GridRenderer: typeof GridRendererImpl;
 interface FieldWrapperProps<TFieldValues extends FieldValues = FieldValues> {
   field: BaseField<TFieldValues>;
   control?: Control<TFieldValues>;
   disabled?: boolean;
   variant?: Variant;
 }
+declare function FieldWrapperImpl<TFieldValues extends FieldValues = FieldValues>(props: FieldWrapperProps<TFieldValues>): FormElement;
 /**
- * Wraps individual fields.
- * If the field requires conditional logic or dynamic options, it uses the Dynamic wrapper.
- * Otherwise, it uses the Static wrapper, vastly improving performance by skipping `useWatch`.
+ * Memoized field wrapper — the dispatch layer between schema fields and
+ * their renderer. Re-renders only when the field config itself changes.
  */
-declare function FieldWrapper<TFieldValues extends FieldValues = FieldValues>(props: FieldWrapperProps<TFieldValues>): FormElement;
+declare const FieldWrapper: typeof FieldWrapperImpl;
 //#endregion
 //#region src/FormSystemContext.d.ts
 /**
@@ -535,6 +754,7 @@ declare function FieldWrapper<TFieldValues extends FieldValues = FieldValues>(pr
 declare function FormSystemProvider({
   components,
   layouts,
+  onMissingComponent,
   children
 }: FormSystemProviderProps): FormElement;
 /**
@@ -556,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
  */
@@ -645,6 +870,7 @@ declare function defineSection<TFieldValues extends FieldValues = FieldValues>(s
 /**
  * Extracts default values from a form schema.
  * Walks all sections and fields, respecting nameSpace prefixes and group nesting.
+ * Array fields default to `[]` when no explicit `defaultValue` is provided.
  *
  * @example
  * ```ts
@@ -653,11 +879,78 @@ 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
+ * handle input events between chunks — keeping INP scores low.
+ *
+ * Use in `getDefaultValues` passed to `useForm` when the schema is known
+ * to be large:
+ *
+ * @example
+ * ```ts
+ * const form = useForm({
+ *   defaultValues: async () => extractDefaultValuesAsync(schema),
+ * });
+ * ```
+ */
+declare function extractDefaultValuesAsync<TFieldValues extends FieldValues = FieldValues>(schema: FormSchema<TFieldValues>): Promise<Partial<TFieldValues>>;
 /**
  * Generates react-hook-form `RegisterOptions`-compatible validation rules
  * from a field's schema props. Maps `required`, `min`, `max`, `minLength`,
  * `maxLength`, `pattern`, and `validate` to RHF rules.
  *
+ * Supports both shorthand scalars and `{ value, message }` objects for all
+ * numeric/length rules, and `{ regex, message }` for pattern.
+ *
  * @example
  * ```tsx
  * import { buildValidationRules } from '@classytic/formkit';
@@ -669,155 +962,174 @@ declare function extractDefaultValues<TFieldValues extends FieldValues = FieldVa
  * ```
  */
 declare function buildValidationRules<TFieldValues extends FieldValues = FieldValues>(field: BaseField<TFieldValues>): ValidationRules;
+/** Returns true for fields that carry an `options` array (select, radio, etc.) */
+declare function isChoiceField(field: BaseField): boolean;
+/** Returns true for free-text input fields */
+declare function isTextField(field: BaseField): boolean;
+/** Returns true for numeric input fields */
+declare function isNumericField(field: BaseField): boolean;
+/** Returns true for date / time fields */
+declare function isDateField(field: BaseField): boolean;
+/** Returns true for structural fields that contain sub-fields (`itemFields`) */
+declare function isContainerField(field: BaseField): boolean;
+/** Returns true for array fields that render a repeatable list */
+declare function isArrayField(field: BaseField): boolean;
+/** Returns true for fields that load options asynchronously */
+declare function isDynamicField(field: BaseField): boolean;
+/** Returns true for fields with conditional rendering */
+declare function isConditionalField(field: BaseField): boolean;
+/**
+ * Merge two or more schemas into one, concatenating their sections.
+ *
+ * @example
+ * ```ts
+ * const full = mergeSchemas(personalSchema, addressSchema, billingSchema);
+ * ```
+ */
+declare function mergeSchemas<TFieldValues extends FieldValues = FieldValues>(...schemas: FormSchema<TFieldValues>[]): FormSchema<TFieldValues>;
+/**
+ * Add fields to a section identified by `sectionId`.
+ * Returns a new schema — the original is not mutated.
+ *
+ * @example
+ * ```ts
+ * const extended = extendSection(schema, "personal", [
+ *   field.text("middleName", "Middle Name"),
+ * ]);
+ * ```
+ */
+declare function extendSection<TFieldValues extends FieldValues = FieldValues>(schema: FormSchema<TFieldValues>, sectionId: string, fields: BaseField<TFieldValues>[], position?: "start" | "end"): FormSchema<TFieldValues>;
+/**
+ * Create a new schema that includes only the named fields.
+ *
+ * @example
+ * ```ts
+ * const slim = pickFields(schema, ["email", "password"]);
+ * ```
+ */
+declare function pickFields<TFieldValues extends FieldValues = FieldValues>(schema: FormSchema<TFieldValues>, names: string[]): FormSchema<TFieldValues>;
+/**
+ * Create a new schema that excludes the named fields.
+ *
+ * @example
+ * ```ts
+ * const withoutInternal = omitFields(schema, ["__id", "__createdAt"]);
+ * ```
+ */
+declare function omitFields<TFieldValues extends FieldValues = FieldValues>(schema: FormSchema<TFieldValues>, names: string[]): FormSchema<TFieldValues>;
+/**
+ * Collect every field from every section into a flat array.
+ * Useful for validation, documentation, and AI schema introspection.
+ *
+ * @example
+ * ```ts
+ * const allFields = flattenSchema(schema);
+ * const required = allFields.filter(f => f.required);
+ * ```
+ */
+declare function flattenSchema<TFieldValues extends FieldValues = FieldValues>(schema: FormSchema<TFieldValues>): BaseField<TFieldValues>[];
+/**
+ * Maps a server error response to react-hook-form field errors.
+ *
+ * Call this in your `onError` / `catch` handler after a failed API submission
+ * to surface per-field server-side errors using the same UX as client validation.
+ *
+ * @param form - The `useForm` return value
+ * @param errors - Map of field path → error message (dot-notation paths supported)
+ *
+ * @example
+ * ```ts
+ * async function onSubmit(data: FormValues) {
+ *   try {
+ *     await api.save(data);
+ *   } catch (err) {
+ *     if (err.fieldErrors) {
+ *       applyServerErrors(form, err.fieldErrors);
+ *       // { email: "Already taken", "address.zip": "Invalid ZIP" }
+ *     }
+ *   }
+ * }
+ * ```
+ */
+declare function applyServerErrors<TFieldValues extends FieldValues = FieldValues>(form: UseFormReturn<TFieldValues>, errors: Record<string, string>): void;
 //#endregion
 //#region src/builders.d.ts
 /**
- * Additional field props for builder helpers.
+ * Additional field props accepted by builder helpers.
  * Accepts all BaseField properties except `name`, `type`, and `label`
- * which are set by the builder method.
+ * which are provided by the builder method directly.
  */
-type FieldProps<TFieldValues extends FieldValues = FieldValues> = Omit<BaseField<TFieldValues>, "name" | "type" | "label"> & {
-  /** Grid column class (e.g., "col-span-2") */gridColumn?: string; /** Icon for the left side of input */
-  iconLeft?: ReactNode; /** Icon for the right side of input */
-  iconRight?: ReactNode; /** Additional custom props */
-  [key: string]: unknown;
-};
+type FieldProps<TFieldValues extends FieldValues = FieldValues> = Omit<BaseField<TFieldValues>, "name" | "type" | "label">;
 /**
  * Section configuration props.
  */
 interface SectionProps<TFieldValues extends FieldValues = FieldValues> extends Omit<Section<TFieldValues>, "id" | "title" | "fields" | "cols"> {
   cols?: number;
 }
-/**
- * Render function for custom field types.
- */
-type CustomRenderFn = (props: {
-  control: Control<FieldValues>;
-  disabled?: boolean;
-  error?: FieldError;
-}) => ReactNode;
 /**
  * Type-safe field builder helpers for schema-driven forms.
  *
- * Provides shorthand methods for common field types with sensible defaults,
- * reducing boilerplate while maintaining full type safety.
+ * All methods are generic over TFieldValues, defaulting to FieldValues (any string)
+ * when no type argument is provided. Specify the generic to enforce that field
+ * names are valid paths in your form values type.
+ *
+ * For fully-typed schemas where every field name is checked, prefer
+ * `field.for<MyForm>()` which fixes the generic once for the whole schema:
  *
  * @example
  * ```ts
- * import { field, section } from '@classytic/formkit';
- *
- * const schema = {
- *   sections: [
- *     section("personal", "Personal Info", [
- *       field.text("firstName", "First Name", { required: true }),
- *       field.email("email", "Email"),
- *       field.select("role", "Role", [
- *         { label: "Admin", value: "admin" },
- *         { label: "User", value: "user" },
- *       ]),
- *     ], { cols: 2 }),
- *   ],
- * };
+ * // Untyped — any string accepted (backwards compatible)
+ * field.text("email", "Email")
+ *
+ * // Per-call generic — name is checked against MyForm
+ * field.text<MyForm>("email", "Email")
+ *
+ * // Typed factory — name checked on every call without repeating the generic
+ * const f = field.for<MyForm>()
+ * f.text("email", "Email")        // ✓
+ * f.text("typo", "Email")         // ✗ TypeScript error
  * ```
  */
 declare const field: {
-  /**
-   * Text input field.
-   */
-  text: (name: string, label: string, props?: FieldProps) => BaseField;
-  /**
-   * Email input field with default placeholder.
-   */
-  email: (name: string, label: string, props?: FieldProps) => BaseField;
-  /**
-   * URL input field with default placeholder.
-   */
-  url: (name: string, label: string, props?: FieldProps) => BaseField;
-  /**
-   * Phone/tel input field with default placeholder.
-   */
-  tel: (name: string, label: string, props?: FieldProps) => BaseField;
-  /**
-   * Password input field.
-   */
-  password: (name: string, label: string, props?: FieldProps) => BaseField;
-  /**
-   * Number input field with min: 0 default.
-   */
-  number: (name: string, label: string, props?: FieldProps) => BaseField;
-  /**
-   * Textarea field with default 3 rows.
-   */
-  textarea: (name: string, label: string, props?: FieldProps) => BaseField;
-  /**
-   * Select dropdown field.
-   */
-  select: (name: string, label: string, options: (FieldOption | FieldOptionGroup)[], props?: FieldProps) => BaseField;
-  /**
-   * Searchable combobox field.
-   */
-  combobox: (name: string, label: string, options: (FieldOption | FieldOptionGroup)[], props?: FieldProps) => BaseField;
-  /**
-   * Multi-select field (tag choice).
-   */
-  multiselect: (name: string, label: string, options: (FieldOption | FieldOptionGroup)[], props?: FieldProps) => BaseField;
-  /**
-   * Dependent select field that reacts to parent field changes.
-   */
-  dependentSelect: (name: string, label: string, props?: FieldProps) => BaseField;
-  /**
-   * Switch/toggle field.
-   */
-  switch: (name: string, label: string, props?: FieldProps) => BaseField;
-  /**
-   * Boolean field (alias for switch).
-   */
-  boolean: (name: string, label: string, props?: FieldProps) => BaseField;
-  /**
-   * Checkbox field.
-   */
-  checkbox: (name: string, label: string, props?: FieldProps) => BaseField;
-  /**
-   * Radio button group field.
-   */
-  radio: (name: string, label: string, options: FieldOption[], props?: FieldProps) => BaseField;
-  /**
-   * Date picker field.
-   */
-  date: (name: string, label: string, props?: FieldProps) => BaseField;
-  /**
-   * Tag input field with default placeholder.
-   */
-  tags: (name: string, label: string, props?: FieldProps) => BaseField;
-  /**
-   * Slug field with auto-generation from source value.
-   */
-  slug: (name: string, label: string, props?: FieldProps) => BaseField;
-  /**
-   * File upload field.
-   */
-  file: (name: string, label: string, props?: FieldProps) => BaseField;
-  /**
-   * Hidden field (no UI).
-   */
-  hidden: (name: string, props?: FieldProps) => BaseField;
+  /** Text input field. */text: <T extends FieldValues = FieldValues>(name: Path<T>, label: string, props?: FieldProps<T>) => BaseField<T>; /** Email input field with default placeholder. */
+  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. 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. */
+  combobox: <T extends FieldValues = FieldValues>(name: Path<T>, label: string, options: (FieldOption | FieldOptionGroup)[], props?: FieldProps<T>) => BaseField<T>; /** Multi-select field. */
+  multiselect: <T extends FieldValues = FieldValues>(name: Path<T>, label: string, options: (FieldOption | FieldOptionGroup)[], props?: FieldProps<T>) => BaseField<T>; /** Dependent select field that reacts to parent field changes. */
+  dependentSelect: <T extends FieldValues = FieldValues>(name: Path<T>, label: string, props?: FieldProps<T>) => BaseField<T>; /** Switch/toggle field. */
+  switch: <T extends FieldValues = FieldValues>(name: Path<T>, label: string, props?: FieldProps<T>) => BaseField<T>; /** Boolean field (alias for switch). */
+  boolean: <T extends FieldValues = FieldValues>(name: Path<T>, label: string, props?: FieldProps<T>) => BaseField<T>; /** Checkbox field. */
+  checkbox: <T extends FieldValues = FieldValues>(name: Path<T>, label: string, props?: FieldProps<T>) => BaseField<T>; /** Radio button group field. */
+  radio: <T extends FieldValues = FieldValues>(name: Path<T>, label: string, options: FieldOption[], props?: FieldProps<T>) => BaseField<T>; /** Date picker field. */
+  date: <T extends FieldValues = FieldValues>(name: Path<T>, label: string, props?: FieldProps<T>) => BaseField<T>; /** Tag input field. */
+  tags: <T extends FieldValues = FieldValues>(name: Path<T>, label: string, props?: FieldProps<T>) => BaseField<T>; /** Slug field. */
+  slug: <T extends FieldValues = FieldValues>(name: Path<T>, label: string, props?: FieldProps<T>) => BaseField<T>; /** File upload field. */
+  file: <T extends FieldValues = FieldValues>(name: Path<T>, label: string, props?: FieldProps<T>) => BaseField<T>; /** Hidden field (no UI). */
+  hidden: <T extends FieldValues = FieldValues>(name: Path<T>, props?: FieldProps<T>) => BaseField<T>;
   /**
    * Group field for nested objects.
-   * Renders itemFields as a sub-grid within the form.
+   * Renders itemFields as a sub-grid. Child names are relative (e.g. "street"),
+   * FormGenerator prefixes them with the group name at render time.
    *
    * @example
    * ```ts
    * field.group("address", "Address", [
    *   field.text("street", "Street"),
    *   field.text("city", "City"),
-   *   field.text("zip", "ZIP Code"),
-   * ], { cols: 3 })
+   * ], { cols: 2 })
    * ```
    */
-  group: (name: string, label: string, itemFields: BaseField[], props?: FieldProps) => BaseField;
+  group: <T extends FieldValues = FieldValues>(name: Path<T>, label: string, itemFields: BaseField[], props?: FieldProps<T>) => BaseField<T>;
   /**
-   * Array/repeatable field.
-   * Renders a dynamic list of sub-forms using react-hook-form's useFieldArray.
+   * Array/repeatable field backed by react-hook-form's useFieldArray.
    *
    * @example
    * ```ts
@@ -827,42 +1139,109 @@ declare const field: {
    * ])
    * ```
    */
-  array: (name: string, label: string, itemFields: BaseField[], props?: FieldProps) => BaseField;
+  array: <T extends FieldValues = FieldValues>(name: Path<T>, label: string, itemFields: BaseField[], props?: FieldProps<T>) => BaseField<T>;
   /**
    * Custom field with a render function.
-   * Bypasses the component registry entirely.
+   * Bypasses the component registry — full control over rendering.
+   *
+   * The render callback receives the complete `FieldComponentProps` including
+   * `fieldId`, `errorId`, `shouldShowError`, `error`, `rules`, and `control`.
+   *
+   * Use `shouldShowError` (not `!!error`) to drive `aria-invalid` and error
+   * visibility so timing mirrors the CSS `:user-invalid` pseudo-class.
    *
    * @example
-   * ```ts
-   * field.custom("skills", "Skills", ({ control, disabled }) => (
-   *   <SkillSelector control={control} disabled={disabled} />
+   * ```tsx
+   * field.custom("skills", "Skills", ({ control, shouldShowError, errorId, error, fieldId }) => (
+   *   <div>
+   *     <SkillSelector
+   *       id={fieldId}
+   *       control={control}
+   *       aria-invalid={shouldShowError || undefined}
+   *       aria-errormessage={shouldShowError ? errorId : undefined}
+   *     />
+   *     {shouldShowError && (
+   *       <p id={errorId} role="alert" className="text-sm text-destructive">
+   *         {error?.message}
+   *       </p>
+   *     )}
+   *   </div>
    * ))
    * ```
    */
-  custom: (name: string, label: string, render: CustomRenderFn, props?: FieldProps) => BaseField;
+  custom: <T extends FieldValues = FieldValues>(name: Path<T>, label: string, render: (props: FieldComponentProps<T>) => ReactNode, props?: FieldProps<T>) => BaseField<T>;
+  /**
+   * Returns a typed field builder with `TFieldValues` fixed.
+   * Every field name is validated against `Path<TFieldValues>` at the call site —
+   * no need to repeat the generic on each individual builder call.
+   *
+   * @example
+   * ```ts
+   * interface ContactForm {
+   *   firstName: string;
+   *   email: string;
+   *   address: { street: string; city: string };
+   * }
+   *
+   * const f = field.for<ContactForm>()
+   *
+   * const schema = defineSchema<ContactForm>({
+   *   sections: [{
+   *     fields: [
+   *       f.text("firstName", "First Name"),     // ✓
+   *       f.email("email", "Email"),              // ✓
+   *       f.text("typo", "Label"),                // ✗ TypeScript error
+   *     ],
+   *   }],
+   * })
+   * ```
+   */
+  for: <T extends FieldValues>() => {
+    text: (name: Path<T>, label: string, props?: FieldProps<T>) => BaseField<T>;
+    email: (name: Path<T>, label: string, props?: FieldProps<T>) => BaseField<T>;
+    url: (name: Path<T>, label: string, props?: FieldProps<T>) => BaseField<T>;
+    tel: (name: Path<T>, label: string, props?: FieldProps<T>) => BaseField<T>;
+    password: (name: Path<T>, label: string, props?: FieldProps<T>) => BaseField<T>;
+    number: (name: Path<T>, label: string, props?: FieldProps<T>) => BaseField<T>;
+    textarea: (name: Path<T>, label: string, props?: FieldProps<T>) => BaseField<T>;
+    select: (name: Path<T>, label: string, options: (FieldOption | FieldOptionGroup)[], props?: FieldProps<T>) => BaseField<T>;
+    combobox: (name: Path<T>, label: string, options: (FieldOption | FieldOptionGroup)[], props?: FieldProps<T>) => BaseField<T>;
+    multiselect: (name: Path<T>, label: string, options: (FieldOption | FieldOptionGroup)[], props?: FieldProps<T>) => BaseField<T>;
+    dependentSelect: (name: Path<T>, label: string, props?: FieldProps<T>) => BaseField<T>;
+    switch: (name: Path<T>, label: string, props?: FieldProps<T>) => BaseField<T>;
+    boolean: (name: Path<T>, label: string, props?: FieldProps<T>) => BaseField<T>;
+    checkbox: (name: Path<T>, label: string, props?: FieldProps<T>) => BaseField<T>;
+    radio: (name: Path<T>, label: string, options: FieldOption[], props?: FieldProps<T>) => BaseField<T>;
+    date: (name: Path<T>, label: string, props?: FieldProps<T>) => BaseField<T>;
+    tags: (name: Path<T>, label: string, props?: FieldProps<T>) => BaseField<T>;
+    slug: (name: Path<T>, label: string, props?: FieldProps<T>) => BaseField<T>;
+    file: (name: Path<T>, label: string, props?: FieldProps<T>) => BaseField<T>;
+    hidden: (name: Path<T>, props?: FieldProps<T>) => BaseField<T>;
+    group: (name: Path<T>, label: string, itemFields: BaseField[], props?: FieldProps<T>) => BaseField<T>;
+    array: (name: Path<T>, label: string, itemFields: BaseField[], props?: FieldProps<T>) => BaseField<T>;
+    custom: (name: Path<T>, label: string, render: (props: FieldComponentProps<T>) => ReactNode, builderProps?: FieldProps<T>) => BaseField<T>;
+  };
 };
 /**
  * Create a section definition with sensible defaults.
  *
- * @param id - Unique section identifier
- * @param title - Section title
- * @param fields - Array of field definitions
- * @param props - Additional section configuration
- *
  * @example
  * ```ts
  * section("personal", "Personal Info", [
  *   field.text("name", "Name", { required: true }),
  *   field.email("email", "Email"),
- * ], { cols: 2, variant: "card" })
+ * ], { cols: 2 })
  * ```
  */
 declare function section<TFieldValues extends FieldValues = FieldValues>(id: string, title: string, fields: BaseField<TFieldValues>[], props?: SectionProps<TFieldValues>): Section<TFieldValues>;
 /**
  * Create a section without a title (transparent section).
  * Useful for grouping fields without visual separation.
+ *
+ * Accepts `BaseField[]` (no generic) so mixed-type field arrays don't trigger
+ * conflicting type inference across different field name generics.
  */
-declare function sectionUntitled<TFieldValues extends FieldValues = FieldValues>(fields: BaseField<TFieldValues>[], props?: Omit<SectionProps<TFieldValues>, "variant">): Section<TFieldValues>;
+declare function sectionUntitled(fields: BaseField[], props?: Omit<SectionProps, "variant">): Section;
 //#endregion
 //#region src/useFormKit.d.ts
 /**
@@ -880,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.
@@ -910,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 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 SchemaFieldNames, type Section, type SectionLayoutProps, type SectionRenderProps, SectionRenderer, type SectionRendererProps, type UseFormKitOptions, type UseFormKitReturn, type ValidationRules, type Variant, buildValidationRules, cn, defineField, defineSchema, defineSection, evaluateCondition, extractDefaultValues, extractWatchNames, field, 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 };