@formality-ui/react 0.2.4 → 0.3.0

package/dist/index.d.cts

@@ -201,13 +201,14 @@ declare function defineInputs<T extends Record<string, ReactInputConfig>>(inputs
  *
  * `<Field>` renders your input component via React Hook Form's `<Controller>`.
  * At runtime Formality merges a `coreProps` bundle onto the component (name,
- * value, onChange, onBlur, and — as a React-special key — `ref`). The three
- * members below are the **injected-props contract**: `formState` always
- * reaches templates and render-prop children, and reaches plain components
- * that have opted into Formality state via `provideState` /
- * `passSubscriptions`; `state` (subscribed field state) and a top-level
- * `forwardRef` key are delivered at runtime by `<Field>` (see "Runtime
- * delivery" below).
+ * value, onChange, onBlur, and `forwardRef` — RHF's ref callback, delivered as
+ * a regular enumerable top-level prop, NOT React's special `ref` key; see §20.1
+ * and "Runtime delivery" below). The three members below are the
+ * **injected-props contract**: `formState` always reaches templates and
+ * render-prop children, and reaches plain components that have opted into
+ * Formality state via `provideState` / `passSubscriptions`; `state`
+ * (subscribed field state) and `forwardRef` are delivered at runtime by
+ * `<Field>` (see "Runtime delivery" below).
  *
  * **Destructure before forwarding.** Component authors MUST destructure
  * `state`, `formState`, and `forwardRef` OUT of props before spreading the
@@ -593,6 +594,14 @@ interface FormProps<TFieldValues extends FieldValues = FieldValues> {
      * (`false` for immediate, or a number for a per-field delay).
      */
     debounce?: number | false;
+    /**
+     * React Hook Form validation trigger `mode`, forwarded to `useForm({ mode })`.
+     * One of `'onChange'` (default) | `'onBlur'` | `'onSubmit'` | `'onTouched'` |
+     * `'all'`. Honored as-is — auto-save is mode-agnostic: its validity gates
+     * trigger validation of the touched fields themselves via `methods.trigger`
+     * (which ignores `mode`), so it works under any mode. See PRD §12.
+     */
+    mode?: "onChange" | "onBlur" | "onSubmit" | "onTouched" | "all";
     /** Form-level validation */
     validate?: (values: Partial<TFieldValues>) => Record<string, string> | Promise<Record<string, string>>;
 }
@@ -644,7 +653,7 @@ interface FormRenderAPI<TFieldValues extends FieldValues = FieldValues> {
  * </Form>
  * ```
  */
-declare function Form<TFieldValues extends FieldValues = FieldValues>({ children, config, formConfig, onSubmit, record, autoSave, debounce: debounceMs, validate, }: FormProps<TFieldValues>): JSX.Element;
+declare function Form<TFieldValues extends FieldValues = FieldValues>({ children, config, formConfig, onSubmit, record, autoSave, debounce: debounceMs, mode, validate, }: FormProps<TFieldValues>): JSX.Element;
 
 /**
  * Field component props.
@@ -714,15 +723,15 @@ interface FieldRenderAPI {
     formState: UseFormStateReturn<FieldValues>;
 }
 /**
- * Field component - Renders a form field with full Formality integration
+ * Field component - Thin wrapper over {@link useField}.
  *
- * Provides:
- * - React Hook Form Controller integration
- * - Props resolution (8-layer merge)
- * - Condition evaluation (disabled/visible/setValue)
- * - Value transformation (parse/format)
- * - Validation (field + type validators)
- * - Subscription management
+ * The RHF Controller integration (props resolution / 8-layer merge, conditions,
+ * parse/format, validation, forwardRef delivery, template/host rendering,
+ * render-prop `children` application) lives in the {@link useField} hook
+ * (PRD §1.3.3 / §5.3 / §20). This component owns ONLY:
+ * - the form-registry registration `useEffect` (`registerField`/
+ *   `unregisterField`, gated on `shouldRegister`) — contract bullet b; and
+ * - delegating to `useField(params)` and returning its `renderedField`.
  *
  * @example
  * ```tsx
@@ -735,7 +744,7 @@ interface FieldRenderAPI {
  * // Custom render
  * <Field name="name">
  *   {({ renderedField, fieldState }) => (
- *     <div className={fieldState.error ? 'has-error' : ''}>
+ *     <div className={fieldState.error ? "has-error" : ""}>
  *       {renderedField}
  *     </div>
  *   )}
@@ -1098,4 +1107,170 @@ declare function useInferredInputs(options: UseInferredInputsOptions): string[];
  */
 declare function useSubscriptions(fieldName: string, subscriptions: string[]): void;
 
-export { ConfigContext, type ConfigContextValue, type CustomFieldState, type DebouncedFunction, type ExtendedFormState, Field, FieldGroup, type FieldGroupProps, type FieldProps, type FieldRenderAPI, Form, FormContext, type FormContextValue, type FormProps, type FormRenderAPI, type FormalityFieldComponentProps, FormalityProvider, type FormalityProviderProps, GroupContext, type GroupContextValue, type GroupState, type InputTemplateProps, type ReactFieldConfig, type ReactFormFieldsConfig, type ReactInputConfig, UnusedFields, type UnusedFieldsProps, type UseFormStateOptions, type WatcherSetterFn, defineInputs, makeDeepProxyState, makeProxyState, useConditions, useConfigContext, useFormContext, useFormState, useGroupContext, useInferredInputs, usePropsEvaluation, useSubscriptions };
+/**
+ * Parameters for {@link useField}.
+ *
+ * Mirrors the subset of `FieldProps` (in `../components/Field`) that the hook
+ * consumes as the single seam for **RHF Controller integration** (gap_analysis.md
+ * **G6**; PRD §1.3.3).
+ *
+ * Per PRD §1.3.3, `hooks/useField` is the module that owns **RHF Controller
+ * integration** for a field — "Uses Core: transform/pipeline, validation/
+ * validate". This interface is the **input contract** for that module: it
+ * carries the field identity + the overrides + the passthrough props threaded
+ * into the parse/format pipeline (§5.3.5), change handler (§5.3.6), validation
+ * wiring (§5.3.7), forwardRef delivery (§20.1), and template/host rendering
+ * (§5.3.8).
+ *
+ * Generic over `TName` (default `string`) so a narrowed name type from
+ * `FieldProps<TName>` can be threaded straight through (PRD §C.4 / T2.1). The
+ * default keeps a bare `UseFieldParams` identical to `UseFieldParams<string>`.
+ *
+ * @template TName - Field name literal/union type (default `string`).
+ */
+interface UseFieldParams<TName extends string = string> {
+    /**
+     * Field name (must match a key in Form's config). When `TName` is narrowed,
+     * this is checked against `TName` at compile time.
+     */
+    name: TName;
+    /** Override the input type resolved from config. */
+    type?: string;
+    /**
+     * Override disabled state. Highest priority in the §5.3.4 disabled
+     * resolution (prop > condition > config).
+     */
+    disabled?: boolean;
+    /** Override hidden state (inverse of visible). */
+    hidden?: boolean;
+    /**
+     * Whether to register this field in Form's field registry (default `true`).
+     *
+     * NOTE: the registration `useEffect` itself is OWNED by the `<Field>`
+     * component (contract bullet b) — this flag is threaded through so a future
+     * direct-hook consumer can opt out. `useField` does NOT call
+     * `registerField`/`unregisterField`.
+     */
+    shouldRegister?: boolean;
+    /**
+     * Per-field input-config override. Merged at the highest-priority layer over
+     * provider/form config (e.g. per-field debounce). See `resolveInputConfig`.
+     */
+    inputConfig?: Partial<InputConfig>;
+    /**
+     * Optional render-prop. Applied INSIDE the hook's Controller render callback
+     * (§5.3.8) against {@link UseFieldReturn}, so the render-prop always sees the
+     * live `fieldState`/`formState`/`fieldProps` values.
+     */
+    children?: ReactNode | ((api: UseFieldReturn) => ReactNode);
+    /**
+     * Additional props forwarded to the input component (the 8-layer
+     * `componentProps` merge layer, §5.3.2). Captured by `mergeFieldProps`.
+     */
+    [key: string]: unknown;
+}
+/**
+ * Return value of {@link useField}.
+ *
+ * **Structurally identical** to `FieldRenderAPI` (in `../components/Field`) —
+ * the data the render layer (template / host / render-prop `children`) consumes.
+ * This equivalence is enforced bidirectionally by
+ * `__typechecks__/useField.test-d.ts`.
+ *
+ * Per PRD §1.3.3, the hook owns the RHF Controller integration, so the fields
+ * below are exactly the Controller-produced state the render layer needs:
+ * `fieldState` + `formState` come from the Controller render callback;
+ * `renderedField` is the RAW rendered input (template/component/host) when
+ * visible, `null` when hidden (the Controller mounts ONLY when visible, so
+ * hidden fields are not RHF-registered — §5.3.8 / §20);
+ * `fieldProps` is the final 8-layer-merged props (§5.3.2, via `mergeFieldProps`);
+ * `watchers` is the map of fields currently watching this field (§5.3.1 step 3).
+ */
+interface UseFieldReturn {
+    /**
+     * RHF field state from the Controller render callback
+     * (`invalid` / `isTouched` / `isDirty` / `error` / …).
+     */
+    fieldState: ControllerFieldState;
+    /**
+     * The RAW rendered input (template / component / host element), or `null`
+     * when the field is not visible. The render-prop `children` is applied
+     * INSIDE the Controller render callback that produces this element.
+     */
+    renderedField: ReactNode;
+    /**
+     * Final merged props passed to the input — the output of the 8-layer
+     * `mergeFieldProps` pipeline (§5.3.2).
+     */
+    fieldProps: Record<string, unknown>;
+    /**
+     * Map of fields watching this field (`true` = currently subscribed). Populated
+     * via the watcher-setter registered with `useSubscriptions` (§5.3.1 step 3).
+     */
+    watchers: Record<string, boolean>;
+    /**
+     * RHF form state from the Controller. Typed as `UseFormStateReturn<FieldValues>`
+     * to match `FieldRenderAPI` exactly (NOT bare `UseFormStateReturn`).
+     */
+    formState: UseFormStateReturn<FieldValues>;
+}
+/**
+ * useField — RHF Controller integration for a single Field (PRD §1.3.3 / §20).
+ *
+ * This hook owns the **entire** Controller lifecycle for one field: it reads
+ * the form/config/group contexts, resolves the input config, sets up watchers
+ * + subscriptions + conditions, builds the setValue effect (ref pattern,
+ * §7.1.1), resolves the disabled/visible/label state, builds the validation
+ * rules + change handler, mounts the `<Controller>` element with its full
+ * render callback (format → state injection → `mergeFieldProps` 8-layer merge →
+ * forwardRef delivery §20.1/§20.4 → template/host/component → render-prop
+ * `children`), and returns the {@link UseFieldReturn}.
+ *
+ * ## Responsibilities (PRD §1.3.3 + §5.3.x + §20)
+ *
+ * - **Controller integration** — wraps RHF's `<Controller>` render callback.
+ *   The `<Controller>` mounts ONLY when the field is visible (the
+ *   `renderedField` is `null` when hidden), preserving the
+ *   conditionally-hidden-field invariant (hidden fields are NOT RHF-registered).
+ * - **Parse/format pipeline (§5.3.5)** — Core `parse` / `format` from
+ *   `@formality-ui/core` (`transform/pipeline`).
+ * - **Change handler (§5.3.6)** — `changeField` + watcher fan-out.
+ * - **Validation (§5.3.7)** — Core `runValidator` / `resolveErrorMessage`
+ *   (`validation/validate`).
+ * - **forwardRef delivery (§20.1)** — delivers the input's ref via the merged
+ *   props' `forwardRef` key (the CURRENT implemented behavior — NOT the legacy
+ *   `ref` key shown in the stale §5.3.2 pseudo-code). The host-element path
+ *   (§20.4 narrow exception) translates `forwardRef` back into React's special
+ *   `ref` key for string components.
+ * - **Props merge (§5.3.2)** — `resolveInputConfig` + `resolveLabel` +
+ *   `mergeFieldProps` (the 8-layer merge).
+ * - **Template/host render (§5.3.8)** — produces the RAW `renderedField`.
+ *
+ * It consumes these context hooks (`useFormContext`, `useConfigContext`,
+ * `useGroupContext`) and composed hooks (`useConditions`, `usePropsEvaluation`,
+ * `useInferredInputs`, `useSubscriptions`), and the Core fns above.
+ *
+ * NOTE: field **registration** (`registerField`/`unregisterField`) is OWNED by
+ * the `<Field>` component (contract bullet b), NOT this hook. The hook reads
+ * `useFormContext()` for everything else (config, methods, changeField,
+ * setFieldValidating, register/unregisterWatcherSetter).
+ *
+ * @param params - Field parameters (see {@link UseFieldParams}).
+ * @returns The Controller-produced state + the RAW rendered input
+ *   (see {@link UseFieldReturn}).
+ *
+ * @example
+ * ```tsx
+ * // Direct hook usage (custom layout):
+ * function MyField() {
+ *   const { renderedField, fieldState } = useField({ name: "email" });
+ *   return <div className={fieldState.error ? "has-error" : ""}>{renderedField}</div>;
+ * }
+ *
+ * // Equivalent via the thin wrapper component:
+ * <Field name="email" />;
+ * ```
+ */
+declare function useField<TName extends string = string>({ name, type: typeProp, disabled: disabledProp, hidden: hiddenProp, children, inputConfig: inputConfigProp, ...restProps }: UseFieldParams<TName>): UseFieldReturn;
+
+export { ConfigContext, type ConfigContextValue, type CustomFieldState, type DebouncedFunction, type ExtendedFormState, Field, FieldGroup, type FieldGroupProps, type FieldProps, type FieldRenderAPI, Form, FormContext, type FormContextValue, type FormProps, type FormRenderAPI, type FormalityFieldComponentProps, FormalityProvider, type FormalityProviderProps, GroupContext, type GroupContextValue, type GroupState, type InputTemplateProps, type ReactFieldConfig, type ReactFormFieldsConfig, type ReactInputConfig, UnusedFields, type UnusedFieldsProps, type UseFieldParams, type UseFieldReturn, type UseFormStateOptions, type WatcherSetterFn, defineInputs, makeDeepProxyState, makeProxyState, useConditions, useConfigContext, useField, useFormContext, useFormState, useGroupContext, useInferredInputs, usePropsEvaluation, useSubscriptions };

package/dist/index.d.ts

@@ -201,13 +201,14 @@ declare function defineInputs<T extends Record<string, ReactInputConfig>>(inputs
  *
  * `<Field>` renders your input component via React Hook Form's `<Controller>`.
  * At runtime Formality merges a `coreProps` bundle onto the component (name,
- * value, onChange, onBlur, and — as a React-special key — `ref`). The three
- * members below are the **injected-props contract**: `formState` always
- * reaches templates and render-prop children, and reaches plain components
- * that have opted into Formality state via `provideState` /
- * `passSubscriptions`; `state` (subscribed field state) and a top-level
- * `forwardRef` key are delivered at runtime by `<Field>` (see "Runtime
- * delivery" below).
+ * value, onChange, onBlur, and `forwardRef` — RHF's ref callback, delivered as
+ * a regular enumerable top-level prop, NOT React's special `ref` key; see §20.1
+ * and "Runtime delivery" below). The three members below are the
+ * **injected-props contract**: `formState` always reaches templates and
+ * render-prop children, and reaches plain components that have opted into
+ * Formality state via `provideState` / `passSubscriptions`; `state`
+ * (subscribed field state) and `forwardRef` are delivered at runtime by
+ * `<Field>` (see "Runtime delivery" below).
  *
  * **Destructure before forwarding.** Component authors MUST destructure
  * `state`, `formState`, and `forwardRef` OUT of props before spreading the
@@ -593,6 +594,14 @@ interface FormProps<TFieldValues extends FieldValues = FieldValues> {
      * (`false` for immediate, or a number for a per-field delay).
      */
     debounce?: number | false;
+    /**
+     * React Hook Form validation trigger `mode`, forwarded to `useForm({ mode })`.
+     * One of `'onChange'` (default) | `'onBlur'` | `'onSubmit'` | `'onTouched'` |
+     * `'all'`. Honored as-is — auto-save is mode-agnostic: its validity gates
+     * trigger validation of the touched fields themselves via `methods.trigger`
+     * (which ignores `mode`), so it works under any mode. See PRD §12.
+     */
+    mode?: "onChange" | "onBlur" | "onSubmit" | "onTouched" | "all";
     /** Form-level validation */
     validate?: (values: Partial<TFieldValues>) => Record<string, string> | Promise<Record<string, string>>;
 }
@@ -644,7 +653,7 @@ interface FormRenderAPI<TFieldValues extends FieldValues = FieldValues> {
  * </Form>
  * ```
  */
-declare function Form<TFieldValues extends FieldValues = FieldValues>({ children, config, formConfig, onSubmit, record, autoSave, debounce: debounceMs, validate, }: FormProps<TFieldValues>): JSX.Element;
+declare function Form<TFieldValues extends FieldValues = FieldValues>({ children, config, formConfig, onSubmit, record, autoSave, debounce: debounceMs, mode, validate, }: FormProps<TFieldValues>): JSX.Element;
 
 /**
  * Field component props.
@@ -714,15 +723,15 @@ interface FieldRenderAPI {
     formState: UseFormStateReturn<FieldValues>;
 }
 /**
- * Field component - Renders a form field with full Formality integration
+ * Field component - Thin wrapper over {@link useField}.
  *
- * Provides:
- * - React Hook Form Controller integration
- * - Props resolution (8-layer merge)
- * - Condition evaluation (disabled/visible/setValue)
- * - Value transformation (parse/format)
- * - Validation (field + type validators)
- * - Subscription management
+ * The RHF Controller integration (props resolution / 8-layer merge, conditions,
+ * parse/format, validation, forwardRef delivery, template/host rendering,
+ * render-prop `children` application) lives in the {@link useField} hook
+ * (PRD §1.3.3 / §5.3 / §20). This component owns ONLY:
+ * - the form-registry registration `useEffect` (`registerField`/
+ *   `unregisterField`, gated on `shouldRegister`) — contract bullet b; and
+ * - delegating to `useField(params)` and returning its `renderedField`.
  *
  * @example
  * ```tsx
@@ -735,7 +744,7 @@ interface FieldRenderAPI {
  * // Custom render
  * <Field name="name">
  *   {({ renderedField, fieldState }) => (
- *     <div className={fieldState.error ? 'has-error' : ''}>
+ *     <div className={fieldState.error ? "has-error" : ""}>
  *       {renderedField}
  *     </div>
  *   )}
@@ -1098,4 +1107,170 @@ declare function useInferredInputs(options: UseInferredInputsOptions): string[];
  */
 declare function useSubscriptions(fieldName: string, subscriptions: string[]): void;
 
-export { ConfigContext, type ConfigContextValue, type CustomFieldState, type DebouncedFunction, type ExtendedFormState, Field, FieldGroup, type FieldGroupProps, type FieldProps, type FieldRenderAPI, Form, FormContext, type FormContextValue, type FormProps, type FormRenderAPI, type FormalityFieldComponentProps, FormalityProvider, type FormalityProviderProps, GroupContext, type GroupContextValue, type GroupState, type InputTemplateProps, type ReactFieldConfig, type ReactFormFieldsConfig, type ReactInputConfig, UnusedFields, type UnusedFieldsProps, type UseFormStateOptions, type WatcherSetterFn, defineInputs, makeDeepProxyState, makeProxyState, useConditions, useConfigContext, useFormContext, useFormState, useGroupContext, useInferredInputs, usePropsEvaluation, useSubscriptions };
+/**
+ * Parameters for {@link useField}.
+ *
+ * Mirrors the subset of `FieldProps` (in `../components/Field`) that the hook
+ * consumes as the single seam for **RHF Controller integration** (gap_analysis.md
+ * **G6**; PRD §1.3.3).
+ *
+ * Per PRD §1.3.3, `hooks/useField` is the module that owns **RHF Controller
+ * integration** for a field — "Uses Core: transform/pipeline, validation/
+ * validate". This interface is the **input contract** for that module: it
+ * carries the field identity + the overrides + the passthrough props threaded
+ * into the parse/format pipeline (§5.3.5), change handler (§5.3.6), validation
+ * wiring (§5.3.7), forwardRef delivery (§20.1), and template/host rendering
+ * (§5.3.8).
+ *
+ * Generic over `TName` (default `string`) so a narrowed name type from
+ * `FieldProps<TName>` can be threaded straight through (PRD §C.4 / T2.1). The
+ * default keeps a bare `UseFieldParams` identical to `UseFieldParams<string>`.
+ *
+ * @template TName - Field name literal/union type (default `string`).
+ */
+interface UseFieldParams<TName extends string = string> {
+    /**
+     * Field name (must match a key in Form's config). When `TName` is narrowed,
+     * this is checked against `TName` at compile time.
+     */
+    name: TName;
+    /** Override the input type resolved from config. */
+    type?: string;
+    /**
+     * Override disabled state. Highest priority in the §5.3.4 disabled
+     * resolution (prop > condition > config).
+     */
+    disabled?: boolean;
+    /** Override hidden state (inverse of visible). */
+    hidden?: boolean;
+    /**
+     * Whether to register this field in Form's field registry (default `true`).
+     *
+     * NOTE: the registration `useEffect` itself is OWNED by the `<Field>`
+     * component (contract bullet b) — this flag is threaded through so a future
+     * direct-hook consumer can opt out. `useField` does NOT call
+     * `registerField`/`unregisterField`.
+     */
+    shouldRegister?: boolean;
+    /**
+     * Per-field input-config override. Merged at the highest-priority layer over
+     * provider/form config (e.g. per-field debounce). See `resolveInputConfig`.
+     */
+    inputConfig?: Partial<InputConfig>;
+    /**
+     * Optional render-prop. Applied INSIDE the hook's Controller render callback
+     * (§5.3.8) against {@link UseFieldReturn}, so the render-prop always sees the
+     * live `fieldState`/`formState`/`fieldProps` values.
+     */
+    children?: ReactNode | ((api: UseFieldReturn) => ReactNode);
+    /**
+     * Additional props forwarded to the input component (the 8-layer
+     * `componentProps` merge layer, §5.3.2). Captured by `mergeFieldProps`.
+     */
+    [key: string]: unknown;
+}
+/**
+ * Return value of {@link useField}.
+ *
+ * **Structurally identical** to `FieldRenderAPI` (in `../components/Field`) —
+ * the data the render layer (template / host / render-prop `children`) consumes.
+ * This equivalence is enforced bidirectionally by
+ * `__typechecks__/useField.test-d.ts`.
+ *
+ * Per PRD §1.3.3, the hook owns the RHF Controller integration, so the fields
+ * below are exactly the Controller-produced state the render layer needs:
+ * `fieldState` + `formState` come from the Controller render callback;
+ * `renderedField` is the RAW rendered input (template/component/host) when
+ * visible, `null` when hidden (the Controller mounts ONLY when visible, so
+ * hidden fields are not RHF-registered — §5.3.8 / §20);
+ * `fieldProps` is the final 8-layer-merged props (§5.3.2, via `mergeFieldProps`);
+ * `watchers` is the map of fields currently watching this field (§5.3.1 step 3).
+ */
+interface UseFieldReturn {
+    /**
+     * RHF field state from the Controller render callback
+     * (`invalid` / `isTouched` / `isDirty` / `error` / …).
+     */
+    fieldState: ControllerFieldState;
+    /**
+     * The RAW rendered input (template / component / host element), or `null`
+     * when the field is not visible. The render-prop `children` is applied
+     * INSIDE the Controller render callback that produces this element.
+     */
+    renderedField: ReactNode;
+    /**
+     * Final merged props passed to the input — the output of the 8-layer
+     * `mergeFieldProps` pipeline (§5.3.2).
+     */
+    fieldProps: Record<string, unknown>;
+    /**
+     * Map of fields watching this field (`true` = currently subscribed). Populated
+     * via the watcher-setter registered with `useSubscriptions` (§5.3.1 step 3).
+     */
+    watchers: Record<string, boolean>;
+    /**
+     * RHF form state from the Controller. Typed as `UseFormStateReturn<FieldValues>`
+     * to match `FieldRenderAPI` exactly (NOT bare `UseFormStateReturn`).
+     */
+    formState: UseFormStateReturn<FieldValues>;
+}
+/**
+ * useField — RHF Controller integration for a single Field (PRD §1.3.3 / §20).
+ *
+ * This hook owns the **entire** Controller lifecycle for one field: it reads
+ * the form/config/group contexts, resolves the input config, sets up watchers
+ * + subscriptions + conditions, builds the setValue effect (ref pattern,
+ * §7.1.1), resolves the disabled/visible/label state, builds the validation
+ * rules + change handler, mounts the `<Controller>` element with its full
+ * render callback (format → state injection → `mergeFieldProps` 8-layer merge →
+ * forwardRef delivery §20.1/§20.4 → template/host/component → render-prop
+ * `children`), and returns the {@link UseFieldReturn}.
+ *
+ * ## Responsibilities (PRD §1.3.3 + §5.3.x + §20)
+ *
+ * - **Controller integration** — wraps RHF's `<Controller>` render callback.
+ *   The `<Controller>` mounts ONLY when the field is visible (the
+ *   `renderedField` is `null` when hidden), preserving the
+ *   conditionally-hidden-field invariant (hidden fields are NOT RHF-registered).
+ * - **Parse/format pipeline (§5.3.5)** — Core `parse` / `format` from
+ *   `@formality-ui/core` (`transform/pipeline`).
+ * - **Change handler (§5.3.6)** — `changeField` + watcher fan-out.
+ * - **Validation (§5.3.7)** — Core `runValidator` / `resolveErrorMessage`
+ *   (`validation/validate`).
+ * - **forwardRef delivery (§20.1)** — delivers the input's ref via the merged
+ *   props' `forwardRef` key (the CURRENT implemented behavior — NOT the legacy
+ *   `ref` key shown in the stale §5.3.2 pseudo-code). The host-element path
+ *   (§20.4 narrow exception) translates `forwardRef` back into React's special
+ *   `ref` key for string components.
+ * - **Props merge (§5.3.2)** — `resolveInputConfig` + `resolveLabel` +
+ *   `mergeFieldProps` (the 8-layer merge).
+ * - **Template/host render (§5.3.8)** — produces the RAW `renderedField`.
+ *
+ * It consumes these context hooks (`useFormContext`, `useConfigContext`,
+ * `useGroupContext`) and composed hooks (`useConditions`, `usePropsEvaluation`,
+ * `useInferredInputs`, `useSubscriptions`), and the Core fns above.
+ *
+ * NOTE: field **registration** (`registerField`/`unregisterField`) is OWNED by
+ * the `<Field>` component (contract bullet b), NOT this hook. The hook reads
+ * `useFormContext()` for everything else (config, methods, changeField,
+ * setFieldValidating, register/unregisterWatcherSetter).
+ *
+ * @param params - Field parameters (see {@link UseFieldParams}).
+ * @returns The Controller-produced state + the RAW rendered input
+ *   (see {@link UseFieldReturn}).
+ *
+ * @example
+ * ```tsx
+ * // Direct hook usage (custom layout):
+ * function MyField() {
+ *   const { renderedField, fieldState } = useField({ name: "email" });
+ *   return <div className={fieldState.error ? "has-error" : ""}>{renderedField}</div>;
+ * }
+ *
+ * // Equivalent via the thin wrapper component:
+ * <Field name="email" />;
+ * ```
+ */
+declare function useField<TName extends string = string>({ name, type: typeProp, disabled: disabledProp, hidden: hiddenProp, children, inputConfig: inputConfigProp, ...restProps }: UseFieldParams<TName>): UseFieldReturn;
+
+export { ConfigContext, type ConfigContextValue, type CustomFieldState, type DebouncedFunction, type ExtendedFormState, Field, FieldGroup, type FieldGroupProps, type FieldProps, type FieldRenderAPI, Form, FormContext, type FormContextValue, type FormProps, type FormRenderAPI, type FormalityFieldComponentProps, FormalityProvider, type FormalityProviderProps, GroupContext, type GroupContextValue, type GroupState, type InputTemplateProps, type ReactFieldConfig, type ReactFormFieldsConfig, type ReactInputConfig, UnusedFields, type UnusedFieldsProps, type UseFieldParams, type UseFieldReturn, type UseFormStateOptions, type WatcherSetterFn, defineInputs, makeDeepProxyState, makeProxyState, useConditions, useConfigContext, useField, useFormContext, useFormState, useGroupContext, useInferredInputs, usePropsEvaluation, useSubscriptions };