@formality-ui/react 0.0.0

package/dist/index.d.ts

@@ -0,0 +1,860 @@
+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 * as react from 'react';
+import { ComponentType, ReactNode } from 'react';
+import { ControllerFieldState, UseFormStateReturn, FieldValues, UseFormReturn } from 'react-hook-form';
+
+/**
+ * Props passed to input template components
+ *
+ * Templates wrap input components to provide consistent styling,
+ * labels, error display, etc.
+ */
+interface InputTemplateProps {
+    /** The input component to render */
+    Field: ComponentType<any>;
+    /** Merged props to pass to the component */
+    fieldProps: Record<string, unknown>;
+    /** Current field state from Controller */
+    fieldState: ControllerFieldState;
+    /** Current form state from RHF */
+    formState: UseFormStateReturn<FieldValues>;
+}
+/**
+ * Custom field state with proxy-optimized properties
+ *
+ * This is the Formality-enhanced field state that includes
+ * all necessary properties for expressions and conditions.
+ */
+interface CustomFieldState {
+    /** Current field value */
+    value: unknown;
+    /** Has the field been touched (focused then blurred) */
+    isTouched: boolean;
+    /** Has the value changed from default */
+    isDirty: boolean;
+    /** Is async validation currently running */
+    isValidating: boolean;
+    /** Current validation error (if any) */
+    error?: FieldError;
+    /** Inverse of valid state for convenience */
+    invalid: boolean;
+}
+/**
+ * Extended form state with Formality-specific additions
+ *
+ * Combines RHF's form state with proxy-wrapped field states
+ * and the original record for expression access.
+ */
+interface ExtendedFormState<TFieldValues extends FieldValues = FieldValues> extends UseFormStateReturn<TFieldValues> {
+    /** Proxy-wrapped field states for each field */
+    fields: Record<string, CustomFieldState>;
+    /** Original record passed to Form (for expression access) */
+    record: Record<string, unknown>;
+}
+/**
+ * Isolated form state for performance-critical subscriptions
+ *
+ * This is a lightweight version of ExtendedFormState that does NOT
+ * subscribe to the entire RHF form state. It only contains:
+ * - Fields you explicitly subscribed to
+ * - The record object
+ *
+ * Use this when you need to watch specific fields without causing
+ * re-renders when other fields change.
+ */
+interface IsolatedFormState {
+    /** Proxy-wrapped field states for watched fields only */
+    fields: Record<string, CustomFieldState>;
+    /** Original record passed to Form (for expression access) */
+    record: Record<string, unknown>;
+    /** Minimal form-level flags (not reactive) */
+    isDirty: boolean;
+    isTouched: boolean;
+    isValid: boolean;
+    isSubmitting: boolean;
+    errors: Record<string, unknown>;
+    touchedFields: Record<string, unknown>;
+    dirtyFields: Record<string, unknown>;
+    defaultValues: Record<string, unknown>;
+}
+/**
+ * Watcher setter function type
+ *
+ * Used by fields to receive updates about which other fields are watching them.
+ */
+type WatcherSetterFn = React.Dispatch<React.SetStateAction<Record<string, boolean>>>;
+/**
+ * Debounced function interface
+ *
+ * Used for debounced submission and validation.
+ */
+interface DebouncedFunction {
+    (): void;
+    cancel: () => void;
+    flush: () => void;
+    pending: () => boolean;
+}
+
+/**
+ * ConfigContextValue - Global configuration provided by FormalityProvider
+ *
+ * Contains all input types, transformers, validators, and global defaults
+ * that apply across all forms in the application.
+ */
+interface ConfigContextValue {
+    /** Input type definitions (e.g., textField, switch, autocomplete) */
+    inputs: Record<string, InputConfig>;
+    /** Named formatters for value → display transformation */
+    formatters: Record<string, (value: unknown) => unknown>;
+    /** Named parsers for input → value transformation */
+    parsers: Record<string, (value: unknown) => unknown>;
+    /** Named validators and validator factories */
+    validators: ValidatorsConfig;
+    /** Error message templates by type key */
+    errorMessages: ErrorMessagesConfig;
+    /** Default template component for all inputs */
+    defaultInputTemplate?: ComponentType<InputTemplateProps>;
+    /** Named template components for specific input types */
+    inputTemplates: Record<string, ComponentType<InputTemplateProps>>;
+    /** Default prop name for passSubscriptions (default: 'state') */
+    defaultSubscriptionPropName: string;
+    /** Static default props for all fields */
+    defaultFieldProps: Record<string, unknown>;
+    /** Dynamic default props evaluated per-field */
+    selectDefaultFieldProps?: SelectValue;
+}
+/**
+ * ConfigContext - React context for global Formality configuration
+ *
+ * Provides access to input types, transformers, validators, and
+ * global defaults to all forms and fields in the application.
+ */
+declare const ConfigContext: react.Context<ConfigContextValue>;
+/**
+ * useConfigContext - Hook to access global configuration
+ *
+ * @returns The current ConfigContextValue from the nearest FormalityProvider
+ */
+declare function useConfigContext(): ConfigContextValue;
+
+/**
+ * FormContextValue - Form-level configuration and operations
+ *
+ * Provides field registration, subscription management, and access
+ * to form state for all fields within a Form component.
+ */
+interface FormContextValue<TFieldValues extends FieldValues = FieldValues> {
+    /** Field configurations for this form */
+    config: FormFieldsConfig;
+    /** Form-level configuration (title, groups, input overrides) */
+    formConfig: FormConfig;
+    /** Original record passed to Form (for expression access) */
+    record?: Record<string, unknown>;
+    /**
+     * Register a field when it mounts
+     * @param name - Field name
+     */
+    registerField: (name: string) => void;
+    /**
+     * Unregister a field when it unmounts
+     * @param name - Field name
+     */
+    unregisterField: (name: string) => void;
+    /**
+     * Add a subscription from subscriber to target field
+     * @param target - The field being watched
+     * @param subscriber - The field watching
+     */
+    addSubscription: (target: string, subscriber: string) => void;
+    /**
+     * Remove a subscription from subscriber to target field
+     * @param target - The field being watched
+     * @param subscriber - The field watching
+     */
+    removeSubscription: (target: string, subscriber: string) => void;
+    /**
+     * Register a setter for a field's watchers state
+     * @param name - Field name
+     * @param setter - React state setter for watchers
+     */
+    registerWatcherSetter: (name: string, setter: WatcherSetterFn) => void;
+    /**
+     * Unregister a watcher setter when field unmounts
+     * @param name - Field name
+     */
+    unregisterWatcherSetter: (name: string) => void;
+    /**
+     * Programmatically change a field's value
+     * @param name - Field name
+     * @param value - New value
+     */
+    changeField: (name: string, value: unknown) => void;
+    /**
+     * Set a field's validating state
+     * @param name - Field name
+     * @param isValidating - Whether validation is in progress
+     */
+    setFieldValidating: (name: string, isValidating: boolean) => void;
+    /**
+     * Get the current complete form state
+     * Used for expression evaluation and condition checking
+     */
+    getFormState: () => FormState;
+    /** Optional submit handler passed to Form */
+    onSubmit?: (values: Partial<TFieldValues>) => void | Promise<void>;
+    /** Debounced submit for auto-save forms */
+    debouncedSubmit: DebouncedFunction;
+    /** Immediate submit bypassing debounce */
+    submitImmediate: () => void;
+    /** Fields in config but not rendered (for config-driven forms) */
+    unusedFields: string[];
+    /** React Hook Form methods passthrough */
+    methods: UseFormReturn<TFieldValues>;
+}
+/**
+ * FormContext - React context for form-level state and operations
+ *
+ * Must be provided by a Form component. No default value as
+ * fields cannot function without a parent Form.
+ */
+declare const FormContext: react.Context<FormContextValue<FieldValues> | null>;
+/**
+ * useFormContext - Hook to access form-level context
+ *
+ * @throws Error if used outside a Form component
+ * @returns The FormContextValue from the nearest Form component
+ */
+declare function useFormContext<TFieldValues extends FieldValues = FieldValues>(): FormContextValue<TFieldValues>;
+
+/**
+ * GroupState - Current computed state for a FieldGroup
+ *
+ * Contains the resolved disabled/visible states from condition
+ * evaluation and the conditions/subscriptions used.
+ */
+interface GroupState {
+    /** Is the group disabled (propagates to all child fields) */
+    isDisabled: boolean;
+    /** Is the group visible (propagates to all child fields) */
+    isVisible: boolean;
+    /** Whether the group has a setValue condition */
+    hasSetCondition: boolean;
+    /** Value to set on all child fields (from group-level set/selectSet) */
+    setValue: unknown;
+    /** Conditions from group configuration */
+    conditions: ConditionDescriptor[];
+    /** Fields this group subscribes to */
+    subscriptions: string[];
+}
+/**
+ * GroupContextValue - Group-level configuration and state
+ *
+ * Provides inherited disabled/visible state and subscription
+ * information to nested fields and groups.
+ */
+interface GroupContextValue {
+    /** Current computed state for the group */
+    state: GroupState;
+    /** Inherited subscriptions from parent groups */
+    subscriptions: string[];
+    /** Field names inferred from group conditions */
+    inferredInputs: string[];
+    /** Group configuration */
+    config: GroupConfig;
+}
+/**
+ * GroupContext - React context for group-level state
+ *
+ * Provides inherited disabled/visible state from parent groups
+ * to child fields and nested groups.
+ */
+declare const GroupContext: react.Context<GroupContextValue>;
+/**
+ * useGroupContext - Hook to access group-level context
+ *
+ * @returns The GroupContextValue from the nearest FieldGroup or default
+ */
+declare function useGroupContext(): GroupContextValue;
+
+/**
+ * FormalityProviderProps - Props for the FormalityProvider component
+ *
+ * Configures input types, transformers, validators, and global defaults
+ * for all forms in the application.
+ */
+interface FormalityProviderProps {
+    /** Child components */
+    children: ReactNode;
+    /**
+     * Input type definitions (REQUIRED)
+     *
+     * Defines how each input type (e.g., textField, switch, autocomplete)
+     * behaves across all forms.
+     *
+     * @example
+     * ```tsx
+     * inputs={{
+     *   textField: { component: TextField, defaultValue: '' },
+     *   switch: { component: Switch, defaultValue: false },
+     * }}
+     * ```
+     */
+    inputs: Record<string, InputConfig>;
+    /**
+     * Named formatters for value → display transformation
+     *
+     * Transform form values before displaying in inputs.
+     *
+     * @example
+     * ```tsx
+     * formatters={{
+     *   currency: (v) => `$${Number(v).toFixed(2)}`,
+     *   uppercase: (v) => String(v).toUpperCase(),
+     * }}
+     * ```
+     */
+    formatters?: Record<string, (value: unknown) => unknown>;
+    /**
+     * Named parsers for input → value transformation
+     *
+     * Transform user input before storing in form state.
+     *
+     * @example
+     * ```tsx
+     * parsers={{
+     *   number: (v) => Number(v) || 0,
+     *   trim: (v) => String(v).trim(),
+     * }}
+     * ```
+     */
+    parsers?: Record<string, (value: unknown) => unknown>;
+    /**
+     * Named validators and validator factories
+     *
+     * Define reusable validation logic across forms.
+     */
+    validators?: ValidatorsConfig;
+    /**
+     * Error message templates by type key
+     *
+     * Map validation error types to human-readable messages.
+     *
+     * @example
+     * ```tsx
+     * errorMessages={{
+     *   required: 'This field is required',
+     *   minLength: 'Must be at least {min} characters',
+     * }}
+     * ```
+     */
+    errorMessages?: ErrorMessagesConfig;
+    /**
+     * Default template component for all inputs
+     *
+     * Wraps all inputs for consistent styling, labels, error display.
+     */
+    defaultInputTemplate?: ComponentType<InputTemplateProps>;
+    /**
+     * Named template components for specific input types
+     *
+     * Override the default template for specific input types.
+     */
+    inputTemplates?: Record<string, ComponentType<InputTemplateProps>>;
+    /**
+     * Default prop name for passSubscriptions (default: 'state')
+     *
+     * When a field has passSubscriptions: true, subscribed field states
+     * are passed using this prop name.
+     */
+    defaultSubscriptionPropName?: string;
+    /**
+     * Static default props for all fields
+     *
+     * Props applied to every field unless overridden.
+     */
+    defaultFieldProps?: Record<string, unknown>;
+    /**
+     * Dynamic default props evaluated per-field
+     *
+     * Expression or function that computes default props.
+     */
+    selectDefaultFieldProps?: SelectValue;
+}
+/**
+ * FormalityProvider - Global configuration provider for Formality
+ *
+ * Wraps your application to provide input types, transformers, validators,
+ * and global defaults to all Formality forms.
+ *
+ * @example
+ * ```tsx
+ * import { FormalityProvider } from '@formality-ui/react';
+ *
+ * const inputs = {
+ *   textField: { component: TextInput, defaultValue: '' },
+ *   switch: { component: Toggle, defaultValue: false },
+ * };
+ *
+ * function App() {
+ *   return (
+ *     <FormalityProvider
+ *       inputs={inputs}
+ *       formatters={{ currency: (v) => `$${v}` }}
+ *       errorMessages={{ required: 'Required' }}
+ *     >
+ *       <MyApp />
+ *     </FormalityProvider>
+ *   );
+ * }
+ * ```
+ */
+declare function FormalityProvider({ children, inputs, formatters, parsers, validators, errorMessages, defaultInputTemplate, inputTemplates, defaultSubscriptionPropName, defaultFieldProps, selectDefaultFieldProps, }: FormalityProviderProps): JSX.Element;
+
+/**
+ * Form component props
+ */
+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;
+    /** Form-level configuration (title, groups, input overrides) */
+    formConfig?: FormConfig;
+    /** Submit handler */
+    onSubmit?: (values: Partial<TFieldValues>) => void | Promise<void>;
+    /** Initial record data */
+    record?: Partial<TFieldValues>;
+    /** Enable auto-save on field changes */
+    autoSave?: boolean;
+    /** Debounce milliseconds for auto-save (default: 1000) */
+    debounce?: number;
+    /** Form-level validation */
+    validate?: (values: Partial<TFieldValues>) => Record<string, string> | Promise<Record<string, string>>;
+}
+/**
+ * API passed to render function children
+ */
+interface FormRenderAPI<TFieldValues extends FieldValues = FieldValues> {
+    /** Fields in config but not rendered */
+    unusedFields: string[];
+    /** React Hook Form formState */
+    formState: UseFormReturn<TFieldValues>['formState'];
+    /** React Hook Form methods */
+    methods: UseFormReturn<TFieldValues>;
+    /** Resolved form title (static or evaluated) */
+    resolvedTitle?: string;
+}
+/**
+ * Form component - Core form wrapper with React Hook Form integration
+ *
+ * Provides:
+ * - FormContext for field registration and subscription management
+ * - React Hook Form integration with mode: 'onChange'
+ * - Auto-save with debounced submission
+ * - Config-driven default values
+ * - Unused fields tracking for config-driven rendering
+ *
+ * @example
+ * ```tsx
+ * <Form
+ *   config={{
+ *     name: { type: 'textField', label: 'Name' },
+ *     email: { type: 'textField', label: 'Email' },
+ *   }}
+ *   onSubmit={(values) => console.log(values)}
+ * >
+ *   <Field name="name" />
+ *   <Field name="email" />
+ *   <button type="submit">Submit</button>
+ * </Form>
+ * ```
+ */
+declare function Form<TFieldValues extends FieldValues = FieldValues>({ children, config, formConfig, onSubmit, record, autoSave, debounce: debounceMs, validate, }: FormProps<TFieldValues>): JSX.Element;
+
+/**
+ * Field component props
+ */
+interface FieldProps {
+    /** Field name (must match a key in Form's config) */
+    name: string;
+    /** Override the input type from config */
+    type?: string;
+    /** Override disabled state */
+    disabled?: boolean;
+    /** Override hidden state (inverse of visible) */
+    hidden?: boolean;
+    /** Custom render function for advanced use cases */
+    children?: ReactNode | ((api: FieldRenderAPI) => ReactNode);
+    /** Whether to register this field in Form's field registry (default: true) */
+    shouldRegister?: boolean;
+    /** Additional props to pass to the input component */
+    [key: string]: unknown;
+}
+/**
+ * API passed to render function children
+ */
+interface FieldRenderAPI {
+    /** React Hook Form field state */
+    fieldState: ControllerFieldState;
+    /** The rendered input component */
+    renderedField: ReactNode;
+    /** Final merged props passed to input */
+    fieldProps: Record<string, unknown>;
+    /** Map of fields watching this field */
+    watchers: Record<string, boolean>;
+    /** React Hook Form form state */
+    formState: UseFormStateReturn<FieldValues>;
+}
+/**
+ * Field component - Renders a form field with full Formality integration
+ *
+ * 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
+ *
+ * @example
+ * ```tsx
+ * // Basic usage
+ * <Field name="email" />
+ *
+ * // Override type
+ * <Field name="status" type="select" />
+ *
+ * // Custom render
+ * <Field name="name">
+ *   {({ renderedField, fieldState }) => (
+ *     <div className={fieldState.error ? 'has-error' : ''}>
+ *       {renderedField}
+ *     </div>
+ *   )}
+ * </Field>
+ * ```
+ */
+declare function Field({ name, type: typeProp, disabled: disabledProp, hidden: hiddenProp, children, shouldRegister, ...restProps }: FieldProps): JSX.Element | null;
+
+/**
+ * FieldGroup component props
+ */
+interface FieldGroupProps {
+    /** Group name (must match a key in FormConfig.groups) */
+    name: string;
+    /** Fields to render within this group */
+    children: ReactNode;
+}
+/**
+ * FieldGroup component - Groups fields with shared conditions
+ *
+ * Provides:
+ * - Group-level condition evaluation (disabled/visible)
+ * - State propagation to nested fields:
+ *   - disabled: OR logic (child || parent)
+ *   - visible: AND logic (child && parent)
+ * - Subscription accumulation from parent groups
+ *
+ * Groups can be nested, with state merging at each level.
+ *
+ * @example
+ * ```tsx
+ * // FormConfig
+ * formConfig={{
+ *   groups: {
+ *     clientSection: {
+ *       conditions: [
+ *         { when: 'hasClient', is: false, visible: false }
+ *       ]
+ *     }
+ *   }
+ * }}
+ *
+ * // Usage
+ * <Form config={config} formConfig={formConfig}>
+ *   <Field name="hasClient" />
+ *   <FieldGroup name="clientSection">
+ *     <Field name="clientName" />
+ *     <Field name="clientEmail" />
+ *   </FieldGroup>
+ * </Form>
+ * ```
+ */
+declare function FieldGroup({ name, children }: FieldGroupProps): JSX.Element;
+
+/**
+ * UnusedFields component props
+ */
+interface UnusedFieldsProps {
+    /** Custom render function for each unused field */
+    children?: (field: {
+        name: string;
+        component: ReactNode;
+    }) => ReactNode;
+}
+/**
+ * UnusedFields component - Renders config-driven fields
+ *
+ * Renders fields that are declared in the Form's config but have not
+ * been explicitly rendered using <Field> components. This enables
+ * config-driven forms where not all fields need to be declared in JSX.
+ *
+ * Fields are tracked via the Form's field registry. When a <Field>
+ * component mounts, it registers itself. UnusedFields renders all
+ * fields that haven't been registered.
+ *
+ * @example
+ * ```tsx
+ * // All fields from config rendered automatically
+ * <Form config={config}>
+ *   <UnusedFields />
+ * </Form>
+ *
+ * // Mix explicit and automatic fields
+ * <Form config={config}>
+ *   <Field name="name" /> {/* Explicit with custom props *\/}
+ *   <Field name="email" /> {/* Explicit with custom props *\/}
+ *   <UnusedFields /> {/* Renders remaining fields *\/}
+ * </Form>
+ *
+ * // Custom wrapper for unused fields
+ * <Form config={config}>
+ *   <UnusedFields>
+ *     {({ name, component }) => (
+ *       <div key={name} className="auto-field">
+ *         {component}
+ *       </div>
+ *     )}
+ *   </UnusedFields>
+ * </Form>
+ * ```
+ */
+declare function UnusedFields({ children }: UnusedFieldsProps): JSX.Element;
+
+/**
+ * Creates a proxy object with lazy property access via Object.defineProperty
+ *
+ * CRITICAL: This enables React's dependency tracking to only register
+ * dependencies on actually accessed properties, not the entire object.
+ *
+ * Without proxy: accessing fieldState.value creates dependency on entire fieldState
+ * With proxy: accessing fieldState.value only creates dependency on value property
+ *
+ * Performance Impact:
+ * - Reduces unnecessary re-renders in condition-heavy forms
+ * - Expression evaluation only subscribes to properties actually used
+ * - Field states can change without triggering re-renders in unrelated fields
+ *
+ * Implementation Note:
+ * Uses Object.defineProperty (NOT Proxy) because:
+ * - Better performance for simple property access
+ * - Works with Object.keys() iteration when enumerable: true
+ * - Simpler debugging and stack traces
+ *
+ * @param source - The object to wrap with lazy getters
+ * @returns A new object with getter properties that lazily access source
+ *
+ * @example
+ * ```typescript
+ * const source = { value: 5, isTouched: false };
+ * const proxy = makeProxyState(source);
+ *
+ * // Properties are accessed lazily
+ * console.log(proxy.value); // 5
+ *
+ * // Changes to source reflect in proxy (lazy access)
+ * source.value = 10;
+ * console.log(proxy.value); // 10
+ *
+ * // Object.keys still works
+ * console.log(Object.keys(proxy)); // ['value', 'isTouched']
+ * ```
+ */
+declare function makeProxyState<T extends object>(source: T): T;
+/**
+ * Creates a nested proxy state, recursively wrapping objects
+ *
+ * Use this for deeply nested state objects where you want
+ * lazy access at multiple levels.
+ *
+ * @param source - The object to wrap with lazy getters (recursively)
+ * @returns A new object with recursive getter properties
+ */
+declare function makeDeepProxyState<T extends object>(source: T): T;
+
+/**
+ * Options for useFormState hook
+ */
+interface UseFormStateOptions {
+    /**
+     * Specific field name(s) to watch.
+     * REQUIRED for performance - you must specify which fields you need.
+     * Watching all fields defeats the purpose of isolation.
+     */
+    name: string | string[];
+}
+/**
+ * Custom useFormState that provides ISOLATED field subscriptions
+ *
+ * CRITICAL PERFORMANCE REQUIREMENT:
+ * You MUST specify which fields to watch via the `name` option.
+ * This hook is designed to prevent the "subscribe to everything" anti-pattern.
+ *
+ * This hook provides:
+ * - Proxy-wrapped field states to prevent unnecessary re-renders
+ * - Record property access via lazy getter
+ * - Integration with Formality's FormContext
+ *
+ * Performance Benefits:
+ * - Only re-renders when specified fields change
+ * - Expression evaluation only creates dependencies on used properties
+ * - Field states can update independently without cross-field re-renders
+ *
+ * @example
+ * ```tsx
+ * function MyField() {
+ *   // Watch specific fields only
+ *   const formState = useFormState({ name: ['firstName', 'lastName'] });
+ *
+ *   // Only re-renders when firstName or lastName change
+ *   const value = formState.fields.firstName?.value;
+ *
+ *   // Access original record for expressions
+ *   const recordId = formState.record.id;
+ * }
+ * ```
+ */
+declare function useFormState<TFieldValues extends FieldValues = FieldValues>(options: UseFormStateOptions): IsolatedFormState;
+
+interface UseConditionsOptions {
+    /** Conditions to evaluate */
+    conditions: ConditionDescriptor[];
+    /** Explicit field subscriptions */
+    subscribesTo?: string[];
+    /** Additional props for expression context */
+    props?: Record<string, unknown>;
+}
+/**
+ * Evaluates conditions against current field values
+ *
+ * This hook:
+ * 1. Infers which fields to watch from conditions
+ * 2. Subscribes to those fields via useWatch
+ * 3. Evaluates conditions whenever watched values change
+ *
+ * Implements the condition evaluation rules:
+ * - disabled: OR logic (any true = disabled)
+ * - visible: AND logic (any false = hidden)
+ * - setValue: last matching condition wins
+ *
+ * @param options - Conditions and subscription config
+ * @returns Evaluation result with disabled, visible, and setValue states
+ *
+ * @example
+ * ```tsx
+ * const result = useConditions({
+ *   conditions: [
+ *     { when: 'signed', is: false, disabled: true },
+ *     { when: 'archived', truthy: true, visible: false },
+ *   ],
+ * });
+ * // result.disabled === true when signed is false
+ * // result.visible === false when archived is truthy
+ * ```
+ */
+declare function useConditions(options: UseConditionsOptions): ConditionResult;
+
+interface UsePropsEvaluationOptions {
+    /** Dynamic props descriptor to evaluate */
+    selectProps?: SelectValue;
+    /** Explicit field subscriptions */
+    subscribesTo?: string[];
+    /** Current field name */
+    fieldName: string;
+}
+/**
+ * Evaluates selectProps against current field values
+ *
+ * This hook:
+ * 1. Infers which fields to watch from selectProps expressions
+ * 2. Subscribes to those fields via useWatch
+ * 3. Evaluates selectProps whenever watched values change
+ *
+ * Handles both expression-based selectProps and function-based selectProps.
+ *
+ * @param options - selectProps and subscription config
+ * @returns Evaluated props object
+ *
+ * @example
+ * ```tsx
+ * const props = usePropsEvaluation({
+ *   selectProps: {
+ *     options: "client.id ? clientOptions : allOptions",
+ *     disabled: "!signed",
+ *   },
+ *   fieldName: 'contact',
+ * });
+ * // props.options and props.disabled are evaluated against current state
+ * ```
+ */
+declare function usePropsEvaluation(options: UsePropsEvaluationOptions): Record<string, unknown>;
+
+interface UseInferredInputsOptions {
+    /** Dynamic props descriptor to analyze for field references */
+    selectProps?: SelectValue;
+    /** Conditions to analyze for field references */
+    conditions?: ConditionDescriptor[];
+    /** Explicit field subscriptions */
+    subscribesTo?: string[];
+}
+/**
+ * Infers field dependencies from selectProps, conditions, and explicit subscriptions
+ *
+ * This hook analyzes:
+ * - selectProps expressions for field references
+ * - condition 'when' fields and 'selectWhen' expressions
+ * - explicit subscribesTo declarations
+ *
+ * Used to automatically determine which fields a Field or FieldGroup
+ * should subscribe to for reactive updates.
+ *
+ * @param options - Sources to analyze for field references
+ * @returns Array of unique field names to subscribe to
+ *
+ * @example
+ * ```tsx
+ * const subscriptions = useInferredInputs({
+ *   selectProps: "client.id",
+ *   conditions: [{ when: 'signed', disabled: true }],
+ *   subscribesTo: ['contact'],
+ * });
+ * // → ['client', 'signed', 'contact']
+ * ```
+ */
+declare function useInferredInputs(options: UseInferredInputsOptions): string[];
+
+/**
+ * Manages field subscriptions
+ *
+ * This hook registers the current field as a subscriber to the target fields,
+ * and cleans up subscriptions when the component unmounts or subscriptions change.
+ *
+ * Subscriptions are stored in the Form's inverted index (target → subscribers),
+ * which allows target fields to know who is watching them (for optimization).
+ *
+ * @param fieldName - The subscribing field's name
+ * @param subscriptions - Array of field names to subscribe to
+ *
+ * @example
+ * ```tsx
+ * // Contact field subscribes to client field
+ * useSubscriptions('contact', ['client']);
+ *
+ * // When client changes, its watchers can be notified
+ * // This enables features like passSubscriptions
+ * ```
+ */
+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 };