@formality-ui/react 0.0.0 → 0.1.0

package/dist/index.d.cts

@@ -1,8 +1,9 @@
-import { FieldError, InputConfig, ValidatorsConfig, ErrorMessagesConfig, SelectValue, FormFieldsConfig, FormConfig, FormState, ConditionDescriptor, GroupConfig, ConditionResult } from '@formality-ui/core';
-export { ConditionDescriptor, ConditionResult, ErrorMessagesConfig, FieldConfig, FieldError, FieldState, FormConfig, FormFieldsConfig, FormState, FormalityProviderConfig, GroupConfig, InputConfig, SelectFunction, SelectValue, ValidationResult, ValidatorFunction, ValidatorSpec, ValidatorsConfig } from '@formality-ui/core';
+import { FieldError, InputConfig, FieldConfig, ValidatorsConfig, ErrorMessagesConfig, SelectValue, FormFieldsConfig, FormConfig, FormState, ConditionDescriptor, GroupConfig, ConditionResult } from '@formality-ui/core';
+export { ConditionDescriptor, ConditionResult, ErrorMessagesConfig, FieldConfig, FieldError, FieldState, FormConfig, FormFieldsConfig, FormState, FormalityProviderConfig, GroupConfig, InputConfig, SelectFunction, SelectValue, ValidationResult, ValidatorEntry, ValidatorFactory, ValidatorFunction, ValidatorSpec, ValidatorsConfig } from '@formality-ui/core';
 import * as react from 'react';
 import { ComponentType, ReactNode } from 'react';
-import { ControllerFieldState, UseFormStateReturn, FieldValues, UseFormReturn } from 'react-hook-form';
+import { ControllerFieldState, UseFormStateReturn, FieldValues, RegisterOptions, RefCallBack, UseFormReturn } from 'react-hook-form';
+export { FieldValues, RefCallBack, UseFormStateReturn } from 'react-hook-form';
 
 /**
  * Props passed to input template components
@@ -96,6 +97,154 @@ interface DebouncedFunction {
     pending: () => boolean;
 }
 
+/**
+ * `InputConfig` as seen by React consumers.
+ *
+ * Narrows core's framework-agnostic `component: unknown` /
+ * `template?: unknown` to real React component types. `TValue` is preserved so
+ * `defaultValue` / `parser` / `formatter` can share a single value type.
+ *
+ * @example
+ * ```tsx
+ * import type { ReactInputConfig } from "@formality-ui/react";
+ *
+ * const textField = {
+ *   component: TextField,
+ *   defaultValue: "",
+ * } satisfies ReactInputConfig<string>;
+ * ```
+ *
+ * Prefer this over the core `InputConfig` type whenever you are writing React
+ * code — it will give you a **compile error** if `component` is set to a
+ * non-component (e.g. `component: 42` or `component: "textField"`).
+ */
+interface ReactInputConfig<TValue = unknown> extends Omit<InputConfig<TValue>, "component" | "template"> {
+    /** The React component to render for this input type. */
+    component: ComponentType<any>;
+    /** Optional template wrapper (overrides provider/form defaults). */
+    template?: ComponentType<InputTemplateProps>;
+}
+/**
+ * `FieldConfig` as seen by React consumers.
+ *
+ * Narrows core's framework-agnostic `rules?: Record<string, unknown>` to
+ * react-hook-form's `RegisterOptions`, giving autocomplete and checking for
+ * `required`, `min`, `max`, `pattern`, `validate`, `valueAsNumber`, `deps`, …
+ *
+ * The generic `V` defaults to `FieldValues`; pass your form's values type for
+ * slightly tighter checking on path-based rules.
+ */
+interface ReactFieldConfig<V extends FieldValues = FieldValues> extends Omit<FieldConfig, "rules"> {
+    /** react-hook-form register options forwarded to the field's Controller. */
+    rules?: RegisterOptions<V>;
+}
+/**
+ * Map of field name → {@link ReactFieldConfig}. Used by `<Form>`'s `config`
+ * prop (via {@link ReactFormFieldsConfig}) so React consumers get RHF-typed
+ * `rules` on every field.
+ *
+ * The keys are narrowed to `Extract<keyof V, string>`. When `V` is left at
+ * its default (`FieldValues`) any string key is accepted — byte-for-byte
+ * identical to before. When `V` is narrowed to a concrete field-values type
+ * (e.g. via `<Form<ClientValues>>`), unknown `config` keys become a
+ * **compile error**, catching typos like `ofice` at compile time (PRD §C.4 /
+ * T2.1).
+ *
+ * @example
+ * ```tsx
+ * import type { ReactFormFieldsConfig } from "@formality-ui/react";
+ * import type { FieldValues } from "react-hook-form";
+ *
+ * // Default — any string key accepted (non-breaking).
+ * const a: ReactFormFieldsConfig<FieldValues> = { anything: { type: "text" } };
+ *
+ * // Narrowed — only known field names accepted.
+ * type ClientValues = { name: string; email: string };
+ * const b: ReactFormFieldsConfig<ClientValues> = {
+ *   name: { type: "text" },
+ *   email: { type: "text" },
+ * };
+ *
+ * // @ts-expect-error — typo `ofice` is rejected.
+ * const c: ReactFormFieldsConfig<ClientValues> = { ofice: { type: "text" } };
+ * ```
+ */
+type ReactFormFieldsConfig<V extends FieldValues = FieldValues> = Record<Extract<keyof V, string>, ReactFieldConfig<V>>;
+/**
+ * Identity helper that lets consumers derive a union of their input-type keys.
+ * Opt-in: wrap your provider inputs to get `keyof` checking on `Field` `type`
+ * and `FieldConfig.type`.
+ *
+ * This is a PURE IDENTITY function — it returns `inputs` unchanged with zero
+ * runtime effect, so bundlers (tsup/esbuild/rollup) tree-shake it to nothing.
+ * It exists purely so consumers can write `type InputType = keyof typeof inputs`.
+ *
+ * The existing non-generic `Field` and `FieldConfig.type` / `FieldProps.type`
+ * (which default to `type?: string`) are UNCHANGED — this helper is purely
+ * additive and opt-in. End-to-end wiring of `InputType` into those types is a
+ * follow-up (PRD §C.4 T2.2 step 3).
+ *
+ * @example
+ * ```tsx
+ * import { defineInputs } from "@formality-ui/react";
+ *
+ * const inputs = defineInputs({
+ *   textField: { component: TextField, defaultValue: "" },
+ *   switch:     { component: Switch,   defaultValue: false },
+ * });
+ * export type InputType = keyof typeof inputs;   // "textField" | "switch"
+ * ```
+ */
+declare function defineInputs<T extends Record<string, ReactInputConfig>>(inputs: T): T;
+/**
+ * Props Formality injects onto every field component.
+ *
+ * `<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 **intended injected-props contract**: `formState`
+ * today reaches templates and render-prop children; `state` (subscribed field
+ * state) and a top-level `forwardRef` key are part of the contract this type
+ * codifies ahead of the runtime wiring (see "Runtime caveat" below).
+ *
+ * **Destructure before forwarding.** Component authors MUST destructure
+ * `state`, `formState`, and `forwardRef` OUT of props before spreading the
+ * rest onto the underlying DOM `<input>` — otherwise these non-DOM props leak
+ * to the DOM and React warns. Recommended pattern:
+ *
+ * ```tsx
+ * const TextField: ComponentType<FormalityFieldComponentProps<TextFieldProps>> =
+ *   ({ state, formState, forwardRef, ...domProps }) => (
+ *     <input ref={forwardRef} {...domProps} />
+ *   );
+ * ```
+ *
+ * **Wiring `forwardRef` to the inner input.** `forwardRef` is RHF's
+ * `RefCallBack` (a function). For a plain `<input>` use `ref={forwardRef}`.
+ * For MUI v9 components that no longer accept a top-level `inputRef`, wire it
+ * via slots: `slotProps={{ input: { ref: forwardRef } }}` (PRD §5.3.8).
+ *
+ * **Runtime caveat (important).** Today `Field` delivers the RHF ref via the
+ * React-special `ref` key (not a top-level `forwardRef` prop). To receive it
+ * as `forwardRef` on a plain function component WITHOUT a `React.forwardRef`
+ * wrap, either (a) wrap your component with `React.forwardRef`, or (b) target
+ * React 19's ref-as-prop. Making Field deliver it as a top-level `forwardRef`
+ * key for bare components is a FUTURE runtime task (out of scope for this
+ * type-only change). The type ships the intended contract now so consumers
+ * stop hand-rolling a lossy `WithFormality<P>`.
+ *
+ * @template P - the field component's own props (e.g. TextFieldProps). Defaults
+ *   to `unknown` so existing `ComponentType<any>` casts remain valid.
+ */
+type FormalityFieldComponentProps<P = unknown> = P & {
+    /** Subscribed/own field state when `provideState`/`passSubscriptions` is on. */
+    state?: CustomFieldState | Record<string, CustomFieldState>;
+    /** React Hook Form form state threaded from `<Controller>`. */
+    formState?: UseFormStateReturn<FieldValues>;
+    /** RHF ref callback (`RefCallBack`); wire to the inner input (see JSDoc). */
+    forwardRef?: RefCallBack;
+};
+
 /**
  * ConfigContextValue - Global configuration provided by FormalityProvider
  *
@@ -104,7 +253,7 @@ interface DebouncedFunction {
  */
 interface ConfigContextValue {
     /** Input type definitions (e.g., textField, switch, autocomplete) */
-    inputs: Record<string, InputConfig>;
+    inputs: Record<string, ReactInputConfig>;
     /** Named formatters for value → display transformation */
     formatters: Record<string, (value: unknown) => unknown>;
     /** Named parsers for input → value transformation */
@@ -188,8 +337,9 @@ interface FormContextValue<TFieldValues extends FieldValues = FieldValues> {
      * Programmatically change a field's value
      * @param name - Field name
      * @param value - New value
+     * @param inputConfig - Optional input configuration for this field type
      */
-    changeField: (name: string, value: unknown) => void;
+    changeField: (name: string, value: unknown, inputConfig?: InputConfig) => void;
     /**
      * Set a field's validating state
      * @param name - Field name
@@ -299,8 +449,12 @@ interface FormalityProviderProps {
      *   switch: { component: Switch, defaultValue: false },
      * }}
      * ```
+     *
+     * `component` is type-checked as a real React component (a non-component
+     * value such as `42` or `"textField"` is a compile error). See
+     * `ReactInputConfig` for the precise shape.
      */
-    inputs: Record<string, InputConfig>;
+    inputs: Record<string, ReactInputConfig>;
     /**
      * Named formatters for value → display transformation
      *
@@ -418,7 +572,7 @@ interface FormProps<TFieldValues extends FieldValues = FieldValues> {
     /** Form content - can be static children or render function */
     children: ReactNode | ((api: FormRenderAPI<TFieldValues>) => ReactNode);
     /** Field configurations */
-    config: FormFieldsConfig;
+    config: ReactFormFieldsConfig<TFieldValues>;
     /** Form-level configuration (title, groups, input overrides) */
     formConfig?: FormConfig;
     /** Submit handler */
@@ -427,8 +581,8 @@ interface FormProps<TFieldValues extends FieldValues = FieldValues> {
     record?: Partial<TFieldValues>;
     /** Enable auto-save on field changes */
     autoSave?: boolean;
-    /** Debounce milliseconds for auto-save (default: 1000) */
-    debounce?: number;
+    /** Debounce milliseconds for auto-save. false = immediate submission, number = delay in milliseconds (default: 1000) */
+    debounce?: number | false;
     /** Form-level validation */
     validate?: (values: Partial<TFieldValues>) => Record<string, string> | Promise<Record<string, string>>;
 }
@@ -439,9 +593,19 @@ interface FormRenderAPI<TFieldValues extends FieldValues = FieldValues> {
     /** Fields in config but not rendered */
     unusedFields: string[];
     /** React Hook Form formState */
-    formState: UseFormReturn<TFieldValues>['formState'];
+    formState: UseFormReturn<TFieldValues>["formState"];
     /** React Hook Form methods */
     methods: UseFormReturn<TFieldValues>;
+    /**
+     * Submit handler that runs the full Formality submission pipeline.
+     *
+     * Use this in place of `methods.handleSubmit` to ensure form-level
+     * `validate` and `transformValuesForSubmit` (valueField extraction +
+     * getSubmitField rename) are applied before `onSubmit` receives the values.
+     * `methods.handleSubmit` remains available as a raw RHF escape hatch but
+     * bypasses those transforms.
+     */
+    handleSubmit: (onSubmit: (values: Partial<TFieldValues>) => void | Promise<void>) => (e?: React.BaseSyntheticEvent) => Promise<void>;
     /** Resolved form title (static or evaluated) */
     resolvedTitle?: string;
 }
@@ -473,11 +637,42 @@ interface FormRenderAPI<TFieldValues extends FieldValues = FieldValues> {
 declare function Form<TFieldValues extends FieldValues = FieldValues>({ children, config, formConfig, onSubmit, record, autoSave, debounce: debounceMs, validate, }: FormProps<TFieldValues>): JSX.Element;
 
 /**
- * Field component props
+ * Field component props.
+ *
+ * `FieldProps` is generic over the field `name`:
+ * `FieldProps<TName extends string = string>`. The default `TName = string`
+ * means `<Field name={anyString} />` compiles unchanged (no migration) and a
+ * bare `FieldProps` is identical to `FieldProps<string>`.
+ *
+ * To get compile-time checking of the field name, narrow `TName` explicitly —
+ * e.g. `FieldProps<"name" | "email">` or a wrapper that threads a
+ * `keyof ClientValues & string`. With a narrowed `TName`, a typo like
+ * `name="ofice"` is rejected at compile time instead of silently rendering
+ * nothing (the second half of PRD §C.4 / T2.1's "silent no-op" fix).
+ *
+ * Automatic per-form narrowing — where a `<Field>` automatically narrows its
+ * `name` against the enclosing `<Form<TFieldValues>>`'s key set — is a planned
+ * follow-up (PRD §C.4 T2.1) and is explicitly deferrable.
+ *
+ * @example
+ * ```tsx
+ * // Default usage — any string name compiles (unchanged behavior):
+ * <Field name="email" />;
+ *
+ * // Opt-in strict usage — typo names are compile errors:
+ * type Names = "name" | "email";
+ * const props: FieldProps<Names> = { name: "email" };
+ * ```
  */
-interface FieldProps {
-    /** Field name (must match a key in Form's config) */
-    name: string;
+interface FieldProps<TName extends string = string> {
+    /**
+     * Field name (must match a key in Form's config).
+     *
+     * When `FieldProps` is narrowed (e.g. `FieldProps<"name" | "email">`), the
+     * name is checked against `TName` at compile time. With the default
+     * (`FieldProps` / `FieldProps<string>`), any string is accepted.
+     */
+    name: TName;
     /** Override the input type from config */
     type?: string;
     /** Override disabled state */
@@ -488,6 +683,8 @@ interface FieldProps {
     children?: ReactNode | ((api: FieldRenderAPI) => ReactNode);
     /** Whether to register this field in Form's field registry (default: true) */
     shouldRegister?: boolean;
+    /** Override input config for this field (e.g., debounce setting) */
+    inputConfig?: Partial<InputConfig>;
     /** Additional props to pass to the input component */
     [key: string]: unknown;
 }
@@ -535,7 +732,7 @@ interface FieldRenderAPI {
  * </Field>
  * ```
  */
-declare function Field({ name, type: typeProp, disabled: disabledProp, hidden: hiddenProp, children, shouldRegister, ...restProps }: FieldProps): JSX.Element | null;
+declare function Field<TName extends string = string>({ name, type: typeProp, disabled: disabledProp, hidden: hiddenProp, children, shouldRegister, inputConfig: inputConfigProp, ...restProps }: FieldProps<TName>): JSX.Element | null;
 
 /**
  * FieldGroup component props
@@ -734,6 +931,8 @@ interface UseConditionsOptions {
     subscribesTo?: string[];
     /** Additional props for expression context */
     props?: Record<string, unknown>;
+    /** Optional: All field configs for computing disabled states in fieldStates */
+    allFieldsConfig?: FormFieldsConfig;
 }
 /**
  * Evaluates conditions against current field values
@@ -748,6 +947,11 @@ interface UseConditionsOptions {
  * - visible: AND logic (any false = hidden)
  * - setValue: last matching condition wins
  *
+ * Uses two-pass evaluation to populate the disabled property in field states:
+ * - Pass 1: Build base field states without disabled (prevents circular dependency)
+ * - Pass 2: Compute disabled for each field using Pass 1 states
+ * - Pass 3: Merge base states with disabled into final field states
+ *
  * @param options - Conditions and subscription config
  * @returns Evaluation result with disabled, visible, and setValue states
  *
@@ -765,16 +969,34 @@ interface UseConditionsOptions {
  */
 declare function useConditions(options: UseConditionsOptions): ConditionResult;
 
+/**
+ * Result of evaluating all three prop sources separately
+ *
+ * Each layer is evaluated independently so that mergeFieldProps
+ * can correctly apply the 8-layer priority order.
+ */
+interface EvaluatedPropsResult {
+    /** Evaluated provider-level selectDefaultFieldProps (layer 7 priority) */
+    providerSelectProps: Record<string, unknown>;
+    /** Evaluated form-level selectDefaultFieldProps (layer 5 priority) */
+    formSelectProps: Record<string, unknown>;
+    /** Evaluated field-level selectProps (layer 2 priority) */
+    fieldSelectProps: Record<string, unknown>;
+}
 interface UsePropsEvaluationOptions {
     /** Dynamic props descriptor to evaluate */
     selectProps?: SelectValue;
+    /** Dynamic default field props from Form config (higher priority) */
+    formDefaultFieldProps?: SelectValue;
+    /** Dynamic default field props from Provider config (lower priority) */
+    providerDefaultFieldProps?: SelectValue;
     /** Explicit field subscriptions */
     subscribesTo?: string[];
     /** Current field name */
     fieldName: string;
 }
 /**
- * Evaluates selectProps against current field values
+ * Evaluates dynamic props against current field values
  *
  * This hook:
  * 1. Infers which fields to watch from selectProps expressions
@@ -783,7 +1005,12 @@ interface UsePropsEvaluationOptions {
  *
  * Handles both expression-based selectProps and function-based selectProps.
  *
- * @param options - selectProps and subscription config
+ * @param options - Hook options including props to evaluate and subscription config
+ * @param {SelectValue} [options.selectProps] - Dynamic props descriptor to evaluate
+ * @param {SelectValue} [options.formDefaultFieldProps] - Dynamic default props from Form config (higher priority)
+ * @param {SelectValue} [options.providerDefaultFieldProps] - Dynamic default props from Provider config (lower priority)
+ * @param {string[]} [options.subscribesTo] - Explicit field subscriptions
+ * @param {string} options.fieldName - Current field name
  * @returns Evaluated props object
  *
  * @example
@@ -798,11 +1025,15 @@ interface UsePropsEvaluationOptions {
  * // props.options and props.disabled are evaluated against current state
  * ```
  */
-declare function usePropsEvaluation(options: UsePropsEvaluationOptions): Record<string, unknown>;
+declare function usePropsEvaluation(options: UsePropsEvaluationOptions): EvaluatedPropsResult;
 
 interface UseInferredInputsOptions {
     /** Dynamic props descriptor to analyze for field references */
     selectProps?: SelectValue;
+    /** Form-level default field props to analyze for field references */
+    formDefaultFieldProps?: SelectValue;
+    /** Provider-level default field props to analyze for field references */
+    providerDefaultFieldProps?: SelectValue;
     /** Conditions to analyze for field references */
     conditions?: ConditionDescriptor[];
     /** Explicit field subscriptions */
@@ -857,4 +1088,4 @@ 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, FormalityProvider, type FormalityProviderProps, GroupContext, type GroupContextValue, type GroupState, type InputTemplateProps, UnusedFields, type UnusedFieldsProps, type UseFormStateOptions, type WatcherSetterFn, makeDeepProxyState, makeProxyState, useConditions, useConfigContext, useFormContext, useFormState, useGroupContext, useInferredInputs, usePropsEvaluation, useSubscriptions };
+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 };