@fuf-stack/uniform 1.4.2 → 1.5.1

package/dist/helpers/index.d.cts

@@ -1,3 +1,5 @@
+/** Key used to wrap flat array elements when converting to form format */
+declare const flatArrayKey = "__FLAT__";
 /**
  * Converts marker strings back to their original values when processing arrays
  */
@@ -8,17 +10,25 @@ declare const fromNullishString: (value: unknown) => unknown;
 declare const toNullishString: (value: unknown) => unknown;
 /**
  * Converts field values to a format suitable for forms by:
- * - Converting array values to their string markers to preserve null/falsy values
+ * - Wrapping arrays of primitives as objects using the flatArrayKey `__FLAT__`
+ *   to satisfy RHF's requirement that array fields contain objects
  * - Removing empty strings and null values from objects
  *
  * This conversion is required because React Hook Form does not support arrays with
  * flat values (string, number, boolean, null). Array fields must contain objects.
- * We work around this by converting array values to string markers.
+ * We work around this by wrapping primitive entries: `{ __FLAT__: <value> }`.
  *
  * @example
  * const fields = {
  *   name: 'John',
  *   scores: [0, null, 75, false],
+ *   scoresDetailed: [
+ *     { score: 1 },
+ *     { score: null },
+ *     { score: 0 },
+ *     { score: false },
+ *     { score: '' },
+ *   ],
  *   contact: {
  *     email: '',
  *     phone: null,
@@ -29,7 +39,20 @@ declare const toNullishString: (value: unknown) => unknown;
  * // Result:
  * {
  *   name: 'John',
- *   scores: ['__ZERO__', '__NULL__', 75, '__FALSE__'],
+ *   scores: [
+ *     { __FLAT__: 0 },
+ *     { __FLAT__: null },
+ *     { __FLAT__: 75 },
+ *     { __FLAT__: false }
+ *   ],
+ *   // Arrays of objects are left as objects; empty/null properties are removed
+ *   scoresDetailed: [
+ *     { score: 1 },
+ *     {}, // null score removed
+ *     { score: 0 },
+ *     { score: false },
+ *     {}, // empty string removed
+ *   ],
  *   contact: {
  *     address: '123 Main St'
  *   }
@@ -38,16 +61,28 @@ declare const toNullishString: (value: unknown) => unknown;
 declare const toFormFormat: (fields: Record<string, unknown>) => Record<string, unknown>;
 /**
  * Converts form state to a format suitable for validation by:
- * - Converting array string markers (__NULL__, __FALSE__, __ZERO__) back to their original values
- * - Converting _NULL__ to null
- * - Removing fields that contain empty strings, null, or any string markers representing null/empty values
+ * - Unwrapping flat array wrappers `{ __FLAT__: <value> }` back to primitives
+ * - Converting legacy string markers (__NULL__, __FALSE__, __ZERO__) back to their original values
+ * - Removing fields whose converted value is empty string or null
+ * - Removing empty arrays
  *
  * @example
  * const formState = {
  *   name: 'John',
- *   scores: [75, '__ZERO__', '_NULL__', '__FALSE__'],
- *   email: null,
- *   phone: '__NULL__',
+ *   scores: [
+ *     { __FLAT__: 75 },
+ *     { __FLAT__: 0 },
+ *     { __FLAT__: null },
+ *     { __FLAT__: false }
+ *   ],
+ *   emptyArray: [],
+ *   scoresDetailed: [
+ *     { score: 1 },
+ *     {},
+ *     { score: 0 },
+ *     { score: false },
+ *     {},
+ *   ],
  *   contact: {
  *     address: '123 Main St',
  *     fax: null
@@ -58,6 +93,15 @@ declare const toFormFormat: (fields: Record<string, unknown>) => Record<string,
  * {
  *   name: 'John',
  *   scores: [75, 0, null, false],
+ *   // emptyArray is removed
+ *   // Objects inside arrays remain objects; empty entries remain empty objects
+ *   scoresDetailed: [
+ *     { score: 1 },
+ *     {},
+ *     { score: 0 },
+ *     { score: false },
+ *     {},
+ *   ],
  *   contact: {
  *     address: '123 Main St'
  *   }
@@ -65,4 +109,4 @@ declare const toFormFormat: (fields: Record<string, unknown>) => Record<string,
  */
 declare const toValidationFormat: (formState: Record<string, unknown> | null | undefined) => Record<string, unknown> | null | undefined;
 
-export { fromNullishString, toFormFormat, toNullishString, toValidationFormat };
+export { flatArrayKey, fromNullishString, toFormFormat, toNullishString, toValidationFormat };

package/dist/helpers/index.d.ts

@@ -1,3 +1,5 @@
+/** Key used to wrap flat array elements when converting to form format */
+declare const flatArrayKey = "__FLAT__";
 /**
  * Converts marker strings back to their original values when processing arrays
  */
@@ -8,17 +10,25 @@ declare const fromNullishString: (value: unknown) => unknown;
 declare const toNullishString: (value: unknown) => unknown;
 /**
  * Converts field values to a format suitable for forms by:
- * - Converting array values to their string markers to preserve null/falsy values
+ * - Wrapping arrays of primitives as objects using the flatArrayKey `__FLAT__`
+ *   to satisfy RHF's requirement that array fields contain objects
  * - Removing empty strings and null values from objects
  *
  * This conversion is required because React Hook Form does not support arrays with
  * flat values (string, number, boolean, null). Array fields must contain objects.
- * We work around this by converting array values to string markers.
+ * We work around this by wrapping primitive entries: `{ __FLAT__: <value> }`.
  *
  * @example
  * const fields = {
  *   name: 'John',
  *   scores: [0, null, 75, false],
+ *   scoresDetailed: [
+ *     { score: 1 },
+ *     { score: null },
+ *     { score: 0 },
+ *     { score: false },
+ *     { score: '' },
+ *   ],
  *   contact: {
  *     email: '',
  *     phone: null,
@@ -29,7 +39,20 @@ declare const toNullishString: (value: unknown) => unknown;
  * // Result:
  * {
  *   name: 'John',
- *   scores: ['__ZERO__', '__NULL__', 75, '__FALSE__'],
+ *   scores: [
+ *     { __FLAT__: 0 },
+ *     { __FLAT__: null },
+ *     { __FLAT__: 75 },
+ *     { __FLAT__: false }
+ *   ],
+ *   // Arrays of objects are left as objects; empty/null properties are removed
+ *   scoresDetailed: [
+ *     { score: 1 },
+ *     {}, // null score removed
+ *     { score: 0 },
+ *     { score: false },
+ *     {}, // empty string removed
+ *   ],
  *   contact: {
  *     address: '123 Main St'
  *   }
@@ -38,16 +61,28 @@ declare const toNullishString: (value: unknown) => unknown;
 declare const toFormFormat: (fields: Record<string, unknown>) => Record<string, unknown>;
 /**
  * Converts form state to a format suitable for validation by:
- * - Converting array string markers (__NULL__, __FALSE__, __ZERO__) back to their original values
- * - Converting _NULL__ to null
- * - Removing fields that contain empty strings, null, or any string markers representing null/empty values
+ * - Unwrapping flat array wrappers `{ __FLAT__: <value> }` back to primitives
+ * - Converting legacy string markers (__NULL__, __FALSE__, __ZERO__) back to their original values
+ * - Removing fields whose converted value is empty string or null
+ * - Removing empty arrays
  *
  * @example
  * const formState = {
  *   name: 'John',
- *   scores: [75, '__ZERO__', '_NULL__', '__FALSE__'],
- *   email: null,
- *   phone: '__NULL__',
+ *   scores: [
+ *     { __FLAT__: 75 },
+ *     { __FLAT__: 0 },
+ *     { __FLAT__: null },
+ *     { __FLAT__: false }
+ *   ],
+ *   emptyArray: [],
+ *   scoresDetailed: [
+ *     { score: 1 },
+ *     {},
+ *     { score: 0 },
+ *     { score: false },
+ *     {},
+ *   ],
  *   contact: {
  *     address: '123 Main St',
  *     fax: null
@@ -58,6 +93,15 @@ declare const toFormFormat: (fields: Record<string, unknown>) => Record<string,
  * {
  *   name: 'John',
  *   scores: [75, 0, null, false],
+ *   // emptyArray is removed
+ *   // Objects inside arrays remain objects; empty entries remain empty objects
+ *   scoresDetailed: [
+ *     { score: 1 },
+ *     {},
+ *     { score: 0 },
+ *     { score: false },
+ *     {},
+ *   ],
  *   contact: {
  *     address: '123 Main St'
  *   }
@@ -65,4 +109,4 @@ declare const toFormFormat: (fields: Record<string, unknown>) => Record<string,
  */
 declare const toValidationFormat: (formState: Record<string, unknown> | null | undefined) => Record<string, unknown> | null | undefined;
 
-export { fromNullishString, toFormFormat, toNullishString, toValidationFormat };
+export { flatArrayKey, fromNullishString, toFormFormat, toNullishString, toValidationFormat };

package/dist/helpers/index.js

@@ -1,11 +1,13 @@
 import {
+  flatArrayKey,
   fromNullishString,
   toFormFormat,
   toNullishString,
   toValidationFormat
-} from "../chunk-KQN55PEW.js";
+} from "../chunk-76KOVUDN.js";
 import "../chunk-K2V4ULA2.js";
 export {
+  flatArrayKey,
   fromNullishString,
   toFormFormat,
   toNullishString,

package/dist/hooks/index.cjs

@@ -5,8 +5,11 @@
 
 
 
-var _chunk2GYFDVXXcjs = require('../chunk-2GYFDVXX.cjs');
-require('../chunk-YGNY6CKU.cjs');
+
+var _chunkJ5FFM7WGcjs = require('../chunk-J5FFM7WG.cjs');
+require('../chunk-OE5BOGGX.cjs');
+require('../chunk-NHEZXA4H.cjs');
+require('../chunk-Z353BLWI.cjs');
 
 
 var _chunkFLK6OPFYcjs = require('../chunk-FLK6OPFY.cjs');
@@ -23,5 +26,6 @@ require('../chunk-555JRYCS.cjs');
 
 
 
-exports.checkFieldIsRequired = _chunk2GYFDVXXcjs.checkFieldIsRequired; exports.useClientValidation = _chunk2GYFDVXXcjs.useClientValidation; exports.useController = _chunk2GYFDVXXcjs.useController; exports.useFieldArray = _chunk2GYFDVXXcjs.useFieldArray; exports.useFormContext = _chunk2GYFDVXXcjs.useFormContext; exports.useInput = _chunk2GYFDVXXcjs.useInput; exports.useInputValueDebounce = _chunkFLK6OPFYcjs.useInputValueDebounce; exports.useInputValueTransform = _chunkP6HJOG7Dcjs.useInputValueTransform;
+
+exports.checkFieldIsRequired = _chunkJ5FFM7WGcjs.checkFieldIsRequired; exports.useClientValidation = _chunkJ5FFM7WGcjs.useClientValidation; exports.useController = _chunkJ5FFM7WGcjs.useController; exports.useFieldArray = _chunkJ5FFM7WGcjs.useFieldArray; exports.useFormContext = _chunkJ5FFM7WGcjs.useFormContext; exports.useInput = _chunkJ5FFM7WGcjs.useInput; exports.useInputValueDebounce = _chunkFLK6OPFYcjs.useInputValueDebounce; exports.useInputValueTransform = _chunkP6HJOG7Dcjs.useInputValueTransform; exports.useUniformField = _chunkJ5FFM7WGcjs.useUniformField;
 //# sourceMappingURL=index.cjs.map

package/dist/hooks/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["/home/runner/work/pixels/pixels/packages/uniform/dist/hooks/index.cjs"],"names":[],"mappings":"AAAA;AACE;AACA;AACA;AACA;AACA;AACA;AACF,yDAA8B;AAC9B,iCAA8B;AAC9B;AACE;AACF,yDAA8B;AAC9B;AACE;AACF,yDAA8B;AAC9B,iCAA8B;AAC9B;AACE;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACF,2fAAC","file":"/home/runner/work/pixels/pixels/packages/uniform/dist/hooks/index.cjs"}
+{"version":3,"sources":["/home/runner/work/pixels/pixels/packages/uniform/dist/hooks/index.cjs"],"names":[],"mappings":"AAAA;AACE;AACA;AACA;AACA;AACA;AACA;AACA;AACF,yDAA8B;AAC9B,iCAA8B;AAC9B,iCAA8B;AAC9B,iCAA8B;AAC9B;AACE;AACF,yDAA8B;AAC9B;AACE;AACF,yDAA8B;AAC9B,iCAA8B;AAC9B;AACE;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACF,wjBAAC","file":"/home/runner/work/pixels/pixels/packages/uniform/dist/hooks/index.cjs"}

package/dist/hooks/index.d.cts

@@ -1,10 +1,12 @@
 import * as _fuf_stack_veto from '@fuf-stack/veto';
-import { VetoTypeAny, VetoInstance } from '@fuf-stack/veto';
+import { VetoTypeAny, VetoInstance, VetoFormattedError } from '@fuf-stack/veto';
 import * as react_hook_form from 'react-hook-form';
 import { UseControllerProps as UseControllerProps$1, ControllerRenderProps, UseFormStateReturn, ControllerFieldState, FieldValues, Path, FieldError } from 'react-hook-form';
 export { useFieldArray } from 'react-hook-form';
 import * as React from 'react';
+import { ReactNode } from 'react';
 import { D as DebugModeSettings } from '../FormContext-LRho0tno.cjs';
+import { useInput } from '@heroui/input';
 export { useInput } from '@heroui/input';
 export { UseInputValueDebounceOptions, UseInputValueDebounceReturn, useInputValueDebounce } from './useInputValueDebounce/index.cjs';
 export { InputValueTransform, UseInputValueTransformOptions, UseInputValueTransformReturn, useInputValueTransform } from './useInputValueTransform/index.cjs';
@@ -71,9 +73,9 @@ declare const useFormContext: <TFieldValues extends FieldValues = FieldValues, T
     formState: react_hook_form.FormState<TFieldValues>;
     getFieldState: (name: Path<TFieldValues>, testId?: string) => {
         error: FieldError[] | undefined;
+        invalid: boolean;
         required: boolean;
         testId: string;
-        invalid: boolean;
         isDirty: boolean;
         isTouched: boolean;
         isValidating: boolean;
@@ -88,7 +90,7 @@ declare const useFormContext: <TFieldValues extends FieldValues = FieldValues, T
     triggerSubmit: (e?: React.BaseSyntheticEvent) => Promise<void> | void;
     validation: {
         instance?: VetoInstance;
-        errors?: _fuf_stack_veto.VetoFormattedError;
+        errors?: VetoFormattedError;
         setClientValidationSchema: (key: string, schema: _fuf_stack_veto.VetoTypeAny | null) => void;
     };
     setError: react_hook_form.UseFormSetError<TFieldValues>;
@@ -104,4 +106,84 @@ declare const useFormContext: <TFieldValues extends FieldValues = FieldValues, T
     setFocus: react_hook_form.UseFormSetFocus<TFieldValues>;
 };
 
-export { type UseControllerProps, type UseControllerReturn, checkFieldIsRequired, useClientValidation, useController, useFormContext };
+interface UseUniformFieldParams<TFieldValues extends FieldValues = FieldValues> {
+    /** Form field name */
+    name: Path<TFieldValues> & string;
+    /** Disable the field */
+    disabled?: boolean;
+    /** Optional explicit test id used to build stable test ids */
+    testId?: string;
+    /** Optional label content; pass false to suppress label entirely */
+    label?: ReactNode | false;
+    /**
+     * When to show the invalid state to users.
+     * - 'touched': Only show errors after field is touched or form is submitted (default, good for text inputs)
+     * - 'immediate': Show errors as soon as they occur (good for checkboxes, radios, arrays)
+     */
+    showInvalidWhen?: 'touched' | 'immediate';
+}
+interface UseUniformFieldReturn<TFieldValues extends FieldValues = FieldValues> {
+    /** react-hook-form control instance for advanced integrations */
+    control: ReturnType<typeof useFormContext<TFieldValues>>['control'];
+    /** Debug mode from Uniform provider */
+    debugMode: ReturnType<typeof useFormContext<TFieldValues>>['debugMode'];
+    /** Current value used to initialize uncontrolled components */
+    defaultValue: unknown;
+    /** Whether the field is currently disabled (from RHF) */
+    disabled: boolean | undefined;
+    /** Validation error(s) for the field */
+    error: FieldError[] | undefined;
+    /** Pre-built errorMessage node to plug into components */
+    errorMessage: ReactNode | null;
+    /** RHF controller field with nullish conversions applied */
+    field: ReturnType<typeof useController<TFieldValues>>['field'];
+    /** Helper to spread standardized error message props to underlying components */
+    getErrorMessageProps: ReturnType<typeof useInput>['getErrorMessageProps'];
+    /** Helper to spread standardized helper wrapper props (for spacing/animation) */
+    getHelperWrapperProps: ReturnType<typeof useInput>['getHelperWrapperProps'];
+    /** Helper to spread standardized label props to underlying components */
+    getLabelProps: ReturnType<typeof useInput>['getLabelProps'];
+    /** Access current form values (converted to validation-friendly format) */
+    getValues: ReturnType<typeof useFormContext<TFieldValues>>['getValues'];
+    /** Whether the field is invalid (debounced for smoother exit animations) */
+    invalid: boolean;
+    /** Computed label node including optional test id copy button */
+    label: ReactNode | null;
+    /** onBlur handler from controller */
+    onBlur: ReturnType<typeof useController<TFieldValues>>['field']['onBlur'];
+    /** onChange handler from controller (with nullish handling) */
+    onChange: ReturnType<typeof useController<TFieldValues>>['field']['onChange'];
+    /** Ref to forward to underlying control */
+    ref: ReturnType<typeof useController<TFieldValues>>['field']['ref'];
+    /** Whether the field is required according to validation schema */
+    required: boolean;
+    /** Reset a specific field in the form */
+    resetField: ReturnType<typeof useFormContext<TFieldValues>>['resetField'];
+    /** Generated HTML data-testid for the field */
+    testId: string;
+}
+/**
+ * Combines frequently used form field logic into a single hook.
+ *
+ * Provides:
+ * - Enhanced form context (validation-aware state, `testId`, value transforms)
+ * - Controller field with nullish conversion handling
+ * - Debounced `invalid` state with smart timing:
+ *   • `true` (field becomes invalid): applies immediately so errors show right away
+ *   • `false` (field becomes valid): delayed 200ms to allow smooth exit animations
+ *   • Respects `prefers-reduced-motion` by skipping delays when user prefers reduced motion
+ * - Smart `invalid` visibility (via `showInvalid`), configurable via `showInvalidWhen`:
+ *   • 'touched' (default): Shows errors only after field touched OR form submitted
+ *   • 'immediate': Shows errors as soon as validation fails (for checkboxes/radios/arrays)
+ *   • Prevents showing errors on pristine fields for better UX
+ * - Prebuilt `errorMessage` React node using `FieldValidationError`
+ * - Computed `label` node which appends a `FieldCopyTestIdButton` in
+ *   `debug-testids` mode
+ * - `defaultValue` for uncontrolled defaults and all usual field handlers
+ * - Access to form utilities: `control`, `getValues`, `resetField`
+ * - Presentation helpers: `getLabelProps`, `getErrorMessageProps`,
+ *   `getHelperWrapperProps` for consistent wiring to underlying UI components
+ */
+declare function useUniformField<TFieldValues extends FieldValues = FieldValues>(params: UseUniformFieldParams<TFieldValues>): UseUniformFieldReturn<TFieldValues>;
+
+export { type UseControllerProps, type UseControllerReturn, type UseUniformFieldParams, type UseUniformFieldReturn, checkFieldIsRequired, useClientValidation, useController, useFormContext, useUniformField };

package/dist/hooks/index.d.ts

@@ -1,10 +1,12 @@
 import * as _fuf_stack_veto from '@fuf-stack/veto';
-import { VetoTypeAny, VetoInstance } from '@fuf-stack/veto';
+import { VetoTypeAny, VetoInstance, VetoFormattedError } from '@fuf-stack/veto';
 import * as react_hook_form from 'react-hook-form';
 import { UseControllerProps as UseControllerProps$1, ControllerRenderProps, UseFormStateReturn, ControllerFieldState, FieldValues, Path, FieldError } from 'react-hook-form';
 export { useFieldArray } from 'react-hook-form';
 import * as React from 'react';
+import { ReactNode } from 'react';
 import { D as DebugModeSettings } from '../FormContext-LRho0tno.js';
+import { useInput } from '@heroui/input';
 export { useInput } from '@heroui/input';
 export { UseInputValueDebounceOptions, UseInputValueDebounceReturn, useInputValueDebounce } from './useInputValueDebounce/index.js';
 export { InputValueTransform, UseInputValueTransformOptions, UseInputValueTransformReturn, useInputValueTransform } from './useInputValueTransform/index.js';
@@ -71,9 +73,9 @@ declare const useFormContext: <TFieldValues extends FieldValues = FieldValues, T
     formState: react_hook_form.FormState<TFieldValues>;
     getFieldState: (name: Path<TFieldValues>, testId?: string) => {
         error: FieldError[] | undefined;
+        invalid: boolean;
         required: boolean;
         testId: string;
-        invalid: boolean;
         isDirty: boolean;
         isTouched: boolean;
         isValidating: boolean;
@@ -88,7 +90,7 @@ declare const useFormContext: <TFieldValues extends FieldValues = FieldValues, T
     triggerSubmit: (e?: React.BaseSyntheticEvent) => Promise<void> | void;
     validation: {
         instance?: VetoInstance;
-        errors?: _fuf_stack_veto.VetoFormattedError;
+        errors?: VetoFormattedError;
         setClientValidationSchema: (key: string, schema: _fuf_stack_veto.VetoTypeAny | null) => void;
     };
     setError: react_hook_form.UseFormSetError<TFieldValues>;
@@ -104,4 +106,84 @@ declare const useFormContext: <TFieldValues extends FieldValues = FieldValues, T
     setFocus: react_hook_form.UseFormSetFocus<TFieldValues>;
 };
 
-export { type UseControllerProps, type UseControllerReturn, checkFieldIsRequired, useClientValidation, useController, useFormContext };
+interface UseUniformFieldParams<TFieldValues extends FieldValues = FieldValues> {
+    /** Form field name */
+    name: Path<TFieldValues> & string;
+    /** Disable the field */
+    disabled?: boolean;
+    /** Optional explicit test id used to build stable test ids */
+    testId?: string;
+    /** Optional label content; pass false to suppress label entirely */
+    label?: ReactNode | false;
+    /**
+     * When to show the invalid state to users.
+     * - 'touched': Only show errors after field is touched or form is submitted (default, good for text inputs)
+     * - 'immediate': Show errors as soon as they occur (good for checkboxes, radios, arrays)
+     */
+    showInvalidWhen?: 'touched' | 'immediate';
+}
+interface UseUniformFieldReturn<TFieldValues extends FieldValues = FieldValues> {
+    /** react-hook-form control instance for advanced integrations */
+    control: ReturnType<typeof useFormContext<TFieldValues>>['control'];
+    /** Debug mode from Uniform provider */
+    debugMode: ReturnType<typeof useFormContext<TFieldValues>>['debugMode'];
+    /** Current value used to initialize uncontrolled components */
+    defaultValue: unknown;
+    /** Whether the field is currently disabled (from RHF) */
+    disabled: boolean | undefined;
+    /** Validation error(s) for the field */
+    error: FieldError[] | undefined;
+    /** Pre-built errorMessage node to plug into components */
+    errorMessage: ReactNode | null;
+    /** RHF controller field with nullish conversions applied */
+    field: ReturnType<typeof useController<TFieldValues>>['field'];
+    /** Helper to spread standardized error message props to underlying components */
+    getErrorMessageProps: ReturnType<typeof useInput>['getErrorMessageProps'];
+    /** Helper to spread standardized helper wrapper props (for spacing/animation) */
+    getHelperWrapperProps: ReturnType<typeof useInput>['getHelperWrapperProps'];
+    /** Helper to spread standardized label props to underlying components */
+    getLabelProps: ReturnType<typeof useInput>['getLabelProps'];
+    /** Access current form values (converted to validation-friendly format) */
+    getValues: ReturnType<typeof useFormContext<TFieldValues>>['getValues'];
+    /** Whether the field is invalid (debounced for smoother exit animations) */
+    invalid: boolean;
+    /** Computed label node including optional test id copy button */
+    label: ReactNode | null;
+    /** onBlur handler from controller */
+    onBlur: ReturnType<typeof useController<TFieldValues>>['field']['onBlur'];
+    /** onChange handler from controller (with nullish handling) */
+    onChange: ReturnType<typeof useController<TFieldValues>>['field']['onChange'];
+    /** Ref to forward to underlying control */
+    ref: ReturnType<typeof useController<TFieldValues>>['field']['ref'];
+    /** Whether the field is required according to validation schema */
+    required: boolean;
+    /** Reset a specific field in the form */
+    resetField: ReturnType<typeof useFormContext<TFieldValues>>['resetField'];
+    /** Generated HTML data-testid for the field */
+    testId: string;
+}
+/**
+ * Combines frequently used form field logic into a single hook.
+ *
+ * Provides:
+ * - Enhanced form context (validation-aware state, `testId`, value transforms)
+ * - Controller field with nullish conversion handling
+ * - Debounced `invalid` state with smart timing:
+ *   • `true` (field becomes invalid): applies immediately so errors show right away
+ *   • `false` (field becomes valid): delayed 200ms to allow smooth exit animations
+ *   • Respects `prefers-reduced-motion` by skipping delays when user prefers reduced motion
+ * - Smart `invalid` visibility (via `showInvalid`), configurable via `showInvalidWhen`:
+ *   • 'touched' (default): Shows errors only after field touched OR form submitted
+ *   • 'immediate': Shows errors as soon as validation fails (for checkboxes/radios/arrays)
+ *   • Prevents showing errors on pristine fields for better UX
+ * - Prebuilt `errorMessage` React node using `FieldValidationError`
+ * - Computed `label` node which appends a `FieldCopyTestIdButton` in
+ *   `debug-testids` mode
+ * - `defaultValue` for uncontrolled defaults and all usual field handlers
+ * - Access to form utilities: `control`, `getValues`, `resetField`
+ * - Presentation helpers: `getLabelProps`, `getErrorMessageProps`,
+ *   `getHelperWrapperProps` for consistent wiring to underlying UI components
+ */
+declare function useUniformField<TFieldValues extends FieldValues = FieldValues>(params: UseUniformFieldParams<TFieldValues>): UseUniformFieldReturn<TFieldValues>;
+
+export { type UseControllerProps, type UseControllerReturn, type UseUniformFieldParams, type UseUniformFieldReturn, checkFieldIsRequired, useClientValidation, useController, useFormContext, useUniformField };

package/dist/hooks/index.js

@@ -4,9 +4,12 @@ import {
   useController,
   useFieldArray,
   useFormContext,
-  useInput
-} from "../chunk-IYDCKENI.js";
-import "../chunk-KQN55PEW.js";
+  useInput,
+  useUniformField
+} from "../chunk-CFH4VPJ4.js";
+import "../chunk-NTDKZW4E.js";
+import "../chunk-ELYGQTXB.js";
+import "../chunk-76KOVUDN.js";
 import {
   useInputValueDebounce
 } from "../chunk-6IU7IYYB.js";
@@ -22,6 +25,7 @@ export {
   useFormContext,
   useInput,
   useInputValueDebounce,
-  useInputValueTransform
+  useInputValueTransform,
+  useUniformField
 };
 //# sourceMappingURL=index.js.map

package/dist/index.cjs

@@ -1,59 +1,61 @@
 "use strict";Object.defineProperty(exports, "__esModule", {value: true});
 
-var _chunkYEKHVKS3cjs = require('./chunk-YEKHVKS3.cjs');
+var _chunkGVMEDVT5cjs = require('./chunk-GVMEDVT5.cjs');
 
 
-var _chunkAYNTZPKLcjs = require('./chunk-AYNTZPKL.cjs');
+var _chunk7NWHDCMEcjs = require('./chunk-7NWHDCME.cjs');
 
 
-var _chunkC64RKQEWcjs = require('./chunk-C64RKQEW.cjs');
+var _chunkKBUECB4Bcjs = require('./chunk-KBUECB4B.cjs');
 
 
-var _chunkUGCZORU3cjs = require('./chunk-UGCZORU3.cjs');
+var _chunk65BN4MRGcjs = require('./chunk-65BN4MRG.cjs');
 
 
-var _chunkRDBCJJI7cjs = require('./chunk-RDBCJJI7.cjs');
+var _chunkRTFM4VRYcjs = require('./chunk-RTFM4VRY.cjs');
 
 
-var _chunkN2EEOWEPcjs = require('./chunk-N2EEOWEP.cjs');
+var _chunkDHO4HSO7cjs = require('./chunk-DHO4HSO7.cjs');
 
 
-var _chunkJZF4HUYOcjs = require('./chunk-JZF4HUYO.cjs');
+var _chunk3YDAYNNBcjs = require('./chunk-3YDAYNNB.cjs');
 
 
-var _chunkFOVP54XPcjs = require('./chunk-FOVP54XP.cjs');
+var _chunkEO4A7QGMcjs = require('./chunk-EO4A7QGM.cjs');
 
 
 var _chunkTTD3KL6Ecjs = require('./chunk-TTD3KL6E.cjs');
 
 
-var _chunk77C6VN4Lcjs = require('./chunk-77C6VN4L.cjs');
+var _chunkEAJFV3ADcjs = require('./chunk-EAJFV3AD.cjs');
 
 
-var _chunkULR4573Wcjs = require('./chunk-ULR4573W.cjs');
+var _chunk4MMOSRT3cjs = require('./chunk-4MMOSRT3.cjs');
+
+
+var _chunkTFMVYQGNcjs = require('./chunk-TFMVYQGN.cjs');
 
 
-var _chunkEEBHFSBYcjs = require('./chunk-EEBHFSBY.cjs');
 
 
-var _chunkOE5BOGGXcjs = require('./chunk-OE5BOGGX.cjs');
 
 
-var _chunkY3AB4GV6cjs = require('./chunk-Y3AB4GV6.cjs');
 
 
+var _chunkJ5FFM7WGcjs = require('./chunk-J5FFM7WG.cjs');
 
 
+var _chunkOE5BOGGXcjs = require('./chunk-OE5BOGGX.cjs');
 
 
+var _chunkNHEZXA4Hcjs = require('./chunk-NHEZXA4H.cjs');
 
-var _chunk2GYFDVXXcjs = require('./chunk-2GYFDVXX.cjs');
 
 
 
 
 
-var _chunkYGNY6CKUcjs = require('./chunk-YGNY6CKU.cjs');
+var _chunkZ353BLWIcjs = require('./chunk-Z353BLWI.cjs');
 
 
 var _chunkFLK6OPFYcjs = require('./chunk-FLK6OPFY.cjs');
@@ -88,5 +90,7 @@ require('./chunk-555JRYCS.cjs');
 
 
 
-exports.CheckboxGroup = _chunkN2EEOWEPcjs.CheckboxGroup_default; exports.FieldArray = _chunkJZF4HUYOcjs.FieldArray_default; exports.FieldCopyTestIdButton = _chunkOE5BOGGXcjs.FieldCopyTestIdButton_default; exports.FieldValidationError = _chunkY3AB4GV6cjs.FieldValidationError_default; exports.Form = _chunkFOVP54XPcjs.Form_default; exports.Grid = _chunkTTD3KL6Ecjs.Grid_default; exports.Input = _chunk77C6VN4Lcjs.Input_default; exports.RadioBoxes = _chunkULR4573Wcjs.RadioBoxes_default; exports.RadioGroup = _chunkEEBHFSBYcjs.RadioGroup_default; exports.RadioTabs = _chunkYEKHVKS3cjs.RadioTabs_default; exports.Select = _chunkAYNTZPKLcjs.Select_default; exports.SubmitButton = _chunkC64RKQEWcjs.SubmitButton_default; exports.Switch = _chunkUGCZORU3cjs.Switch_default; exports.TextArea = _chunkRDBCJJI7cjs.TextArea_default; exports.checkFieldIsRequired = _chunk2GYFDVXXcjs.checkFieldIsRequired; exports.fromNullishString = _chunkYGNY6CKUcjs.fromNullishString; exports.toFormFormat = _chunkYGNY6CKUcjs.toFormFormat; exports.toNullishString = _chunkYGNY6CKUcjs.toNullishString; exports.toValidationFormat = _chunkYGNY6CKUcjs.toValidationFormat; exports.useClientValidation = _chunk2GYFDVXXcjs.useClientValidation; exports.useController = _chunk2GYFDVXXcjs.useController; exports.useFieldArray = _chunk2GYFDVXXcjs.useFieldArray; exports.useFormContext = _chunk2GYFDVXXcjs.useFormContext; exports.useInput = _chunk2GYFDVXXcjs.useInput; exports.useInputValueDebounce = _chunkFLK6OPFYcjs.useInputValueDebounce; exports.useInputValueTransform = _chunkP6HJOG7Dcjs.useInputValueTransform;
+
+
+exports.Checkboxes = _chunkDHO4HSO7cjs.Checkboxes_default; exports.FieldArray = _chunk3YDAYNNBcjs.FieldArray_default; exports.FieldCopyTestIdButton = _chunkOE5BOGGXcjs.FieldCopyTestIdButton_default; exports.FieldValidationError = _chunkNHEZXA4Hcjs.FieldValidationError_default; exports.Form = _chunkEO4A7QGMcjs.Form_default; exports.Grid = _chunkTTD3KL6Ecjs.Grid_default; exports.Input = _chunkEAJFV3ADcjs.Input_default; exports.RadioBoxes = _chunk4MMOSRT3cjs.RadioBoxes_default; exports.RadioTabs = _chunkTFMVYQGNcjs.RadioTabs_default; exports.Radios = _chunkGVMEDVT5cjs.Radios_default; exports.Select = _chunk7NWHDCMEcjs.Select_default; exports.SubmitButton = _chunkKBUECB4Bcjs.SubmitButton_default; exports.Switch = _chunk65BN4MRGcjs.Switch_default; exports.TextArea = _chunkRTFM4VRYcjs.TextArea_default; exports.checkFieldIsRequired = _chunkJ5FFM7WGcjs.checkFieldIsRequired; exports.flatArrayKey = _chunkZ353BLWIcjs.flatArrayKey; exports.fromNullishString = _chunkZ353BLWIcjs.fromNullishString; exports.toFormFormat = _chunkZ353BLWIcjs.toFormFormat; exports.toNullishString = _chunkZ353BLWIcjs.toNullishString; exports.toValidationFormat = _chunkZ353BLWIcjs.toValidationFormat; exports.useClientValidation = _chunkJ5FFM7WGcjs.useClientValidation; exports.useController = _chunkJ5FFM7WGcjs.useController; exports.useFieldArray = _chunkJ5FFM7WGcjs.useFieldArray; exports.useFormContext = _chunkJ5FFM7WGcjs.useFormContext; exports.useInput = _chunkJ5FFM7WGcjs.useInput; exports.useInputValueDebounce = _chunkFLK6OPFYcjs.useInputValueDebounce; exports.useInputValueTransform = _chunkP6HJOG7Dcjs.useInputValueTransform; exports.useUniformField = _chunkJ5FFM7WGcjs.useUniformField;
 //# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["/home/runner/work/pixels/pixels/packages/uniform/dist/index.cjs"],"names":[],"mappings":"AAAA;AACE;AACF,wDAA6B;AAC7B;AACE;AACF,wDAA6B;AAC7B;AACE;AACF,wDAA6B;AAC7B;AACE;AACF,wDAA6B;AAC7B;AACE;AACF,wDAA6B;AAC7B;AACE;AACF,wDAA6B;AAC7B;AACE;AACF,wDAA6B;AAC7B;AACE;AACF,wDAA6B;AAC7B;AACE;AACF,wDAA6B;AAC7B;AACE;AACF,wDAA6B;AAC7B;AACE;AACF,wDAA6B;AAC7B;AACE;AACF,wDAA6B;AAC7B;AACE;AACF,wDAA6B;AAC7B;AACE;AACF,wDAA6B;AAC7B;AACE;AACA;AACA;AACA;AACA;AACA;AACF,wDAA6B;AAC7B;AACE;AACA;AACA;AACA;AACF,wDAA6B;AAC7B;AACE;AACF,wDAA6B;AAC7B;AACE;AACF,wDAA6B;AAC7B,gCAA6B;AAC7B;AACE;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACF,yiDAAC","file":"/home/runner/work/pixels/pixels/packages/uniform/dist/index.cjs"}
+{"version":3,"sources":["/home/runner/work/pixels/pixels/packages/uniform/dist/index.cjs"],"names":[],"mappings":"AAAA;AACE;AACF,wDAA6B;AAC7B;AACE;AACF,wDAA6B;AAC7B;AACE;AACF,wDAA6B;AAC7B;AACE;AACF,wDAA6B;AAC7B;AACE;AACF,wDAA6B;AAC7B;AACE;AACF,wDAA6B;AAC7B;AACE;AACF,wDAA6B;AAC7B;AACE;AACF,wDAA6B;AAC7B;AACE;AACF,wDAA6B;AAC7B;AACE;AACF,wDAA6B;AAC7B;AACE;AACF,wDAA6B;AAC7B;AACE;AACF,wDAA6B;AAC7B;AACE;AACA;AACA;AACA;AACA;AACA;AACA;AACF,wDAA6B;AAC7B;AACE;AACF,wDAA6B;AAC7B;AACE;AACF,wDAA6B;AAC7B;AACE;AACA;AACA;AACA;AACA;AACF,wDAA6B;AAC7B;AACE;AACF,wDAA6B;AAC7B;AACE;AACF,wDAA6B;AAC7B,gCAA6B;AAC7B;AACE;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACF,+oDAAC","file":"/home/runner/work/pixels/pixels/packages/uniform/dist/index.cjs"}