@fuf-stack/uniform 1.20.16 → 1.20.18

package/dist/helpers/index.d.ts

@@ -1,2 +1,224 @@
-import { a as toFormFormat, c as toValidationFormat, i as nameToTestId, l as createOptionValueConverter, n as fromNullishString, o as toNullishString, r as isValueEmpty, s as toSubmitFormat, t as flatArrayKey } from "../index-DVGo3QuA.js";
-export { createOptionValueConverter, flatArrayKey, fromNullishString, isValueEmpty, nameToTestId, toFormFormat, toNullishString, toSubmitFormat, toValidationFormat };
+//#region src/helpers/createOptionValueConverter/createOptionValueConverter.d.ts
+/**
+ * Creates a converter function that preserves the original type (string, number, or boolean)
+ * of option values when converting from string keys back to their original type.
+ *
+ * This is useful for radio/select components where the underlying UI library
+ * uses string keys internally, but we want to preserve number/boolean values in the form state.
+ *
+ * @param options - Array of options with a value property that can be string, number, or boolean
+ * @returns An object with:
+ *   - `convertToOriginalType`: Function to convert a string key back to its original type
+ *   - `numberValueKeys`: Set of string representations of number values (for internal use)
+ *   - `booleanValueKeys`: Map of string representations to boolean values (for internal use)
+ */
+declare const createOptionValueConverter: <T extends {
+  value: string | number | boolean;
+}>(options: T[]) => {
+  booleanValueKeys: Map<string, boolean>;
+  convertToOriginalType: (key: string | number | boolean) => string | number | boolean;
+  numberValueKeys: Set<string>;
+};
+//#endregion
+//#region src/helpers/nullishFields/nullishFields.d.ts
+/** Key used to wrap flat array elements when converting to form format */
+declare const flatArrayKey = "__FLAT__";
+/**
+ * Checks if a value is considered "empty" for validation display purposes.
+ *
+ * Used by useUniformField to determine when to show validation errors.
+ * Empty values don't trigger immediate error display (user must interact first).
+ *
+ * Handles:
+ * - Primitives: null, undefined, ''
+ * - Marker strings: __NULL__, __FALSE__, __ZERO__ (converted via fromNullishString)
+ * - Empty arrays: []
+ * - Objects with all empty values: {a: null, b: ''}
+ * - Flat array wrappers: {__FLAT__: null} or {__FLAT__: ''}
+ *
+ * @param value - The value to check (will be converted via fromNullishString first)
+ * @returns true if the value is empty
+ *
+ * @example
+ * isValueEmpty(null)                    // true
+ * isValueEmpty('')                      // true
+ * isValueEmpty('__NULL__')              // true (marker string)
+ * isValueEmpty([])                      // true (empty array)
+ * isValueEmpty({a: null})               // true (object with all empty values)
+ * isValueEmpty({__FLAT__: null})        // true (flat array wrapper with empty value)
+ * isValueEmpty({__FLAT__: ''})          // true
+ * isValueEmpty('hello')                 // false
+ * isValueEmpty([1, 2])                  // false
+ * isValueEmpty({a: 'value'})            // false
+ * isValueEmpty({__FLAT__: 'value'})     // false
+ */
+declare const isValueEmpty: (value: unknown) => boolean;
+/**
+ * Converts marker strings back to their original values when processing arrays
+ */
+declare const fromNullishString: (value: unknown) => unknown;
+/**
+ * Converts null/falsy values to marker strings for JSON processing
+ */
+declare const toNullishString: (value: unknown) => unknown;
+/**
+ * Converts field values to a format suitable for forms by:
+ * - 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 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,
+ *     address: '123 Main St'
+ *   }
+ * };
+ *
+ * // Result:
+ * {
+ *   name: 'John',
+ *   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'
+ *   }
+ * }
+ */
+declare const toFormFormat: (fields: Record<string, unknown>) => Record<string, unknown>;
+/**
+ * Converts form state to a format suitable for validation by:
+ * - 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: [
+ *     { __FLAT__: 75 },
+ *     { __FLAT__: 0 },
+ *     { __FLAT__: null },
+ *     { __FLAT__: false }
+ *   ],
+ *   emptyArray: [],
+ *   scoresDetailed: [
+ *     { score: 1 },
+ *     {},
+ *     { score: 0 },
+ *     { score: false },
+ *     {},
+ *   ],
+ *   contact: {
+ *     address: '123 Main St',
+ *     fax: null
+ *   }
+ * };
+ *
+ * // Result:
+ * {
+ *   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'
+ *   }
+ * }
+ */
+declare const toValidationFormat: (formState: Record<string, unknown> | null | undefined) => Record<string, unknown> | null | undefined;
+/**
+ * Converts form state to a format suitable for submission by:
+ * - Applying all transformations from toValidationFormat
+ * - Additionally removing empty objects from the result
+ * - Filtering empty objects from arrays
+ * - Recursively cleaning nested structures
+ *
+ * **Why separate from toValidationFormat?**
+ *
+ * Empty objects must be preserved during validation so that custom refinements
+ * can run. For example, a FieldCard with "at least email or phone required"
+ * validation needs the object to exist (even if empty) for the refine to execute.
+ *
+ * However, for submission, empty objects are meaningless and should be removed
+ * to produce clean data for APIs.
+ *
+ * @example
+ * const formState = {
+ *   name: 'John',
+ *   contact: {},           // Empty FieldCard - will be removed
+ *   tags: [{}, {}, {}],    // All empty - array will be removed
+ *   items: [
+ *     { value: 'a' },
+ *     {},                  // Empty entry - will be filtered out
+ *     { value: 'b' }
+ *   ],
+ *   nested: {
+ *     deep: {}             // Nested empty - will be removed recursively
+ *   }
+ * };
+ *
+ * // Result:
+ * {
+ *   name: 'John',
+ *   items: [{ value: 'a' }, { value: 'b' }]
+ * }
+ */
+declare const toSubmitFormat: (formState: Record<string, unknown> | null | undefined) => Record<string, unknown> | null | undefined;
+/**
+ * Converts a field name to a testId by removing flat array key segments and slugifying.
+ * Removes all occurrences of `flatArrayKey` from the field name and applies slugify transformation.
+ *
+ * This is used to generate stable testIds for form fields that don't include
+ * the internal `__FLAT__` marker used for flat arrays.
+ *
+ * @param name - The field name as a string (e.g., 'tags.0.__FLAT__') or array path (e.g., ['tags', '0', '__FLAT__'])
+ * @returns The slugified field name with all flat array key segments removed (e.g., 'tags_0')
+ *
+ * @example
+ * ```ts
+ * nameToTestId('tags.0.__FLAT__') // => 'tags_0'
+ * nameToTestId('array.0.__FLAT__') // => 'array_0'
+ * nameToTestId('nested.array.0.__FLAT__.field') // => 'nested_array_0_field'
+ * nameToTestId('simple.field') // => 'simple_field'
+ * nameToTestId(['tags', '0', '__FLAT__']) // => 'tags_0'
+ * ```
+ */
+declare const nameToTestId: (name: string | readonly string[]) => string;
+//#endregion
+export { createOptionValueConverter, flatArrayKey, fromNullishString, isValueEmpty, nameToTestId, toFormFormat, toNullishString, toSubmitFormat, toValidationFormat };
+//# sourceMappingURL=index.d.ts.map

package/dist/helpers/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/helpers/createOptionValueConverter/createOptionValueConverter.ts","../../src/helpers/nullishFields/nullishFields.ts"],"mappings":";;AAeA;;;;;;;;;;;;cAAa,0BAAA;EACC,KAAA;AAAA,GAEZ,OAAA,EAAS,CAAA;;;;;;;;cCfE,YAAA;;;;;;;;;;;;;;;;;;;;;;;AAAb;;;;AAAyB;AAsCzB;;cAAa,YAAA,GAAgB,KAAc;;AAAA;AA0B3C;cAAa,iBAAA,GAAqB,KAAc;;;AAAA;cAsCnC,eAAA,GAAmB,KAAc;;;;AAAA;AA6E9C;;;;;;;;AAwB6C;AAmD7C;;;;;;;;AAES;AAuKT;;;;;;;;AAES;AA2BT;;;;AAA6D;;;;;;;;;;;;;;;cAjRhD,YAAA,GAAgB,MAAA,EAAQ,MAAA,sBAwBE,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cAmDhC,kBAAA,GACX,SAAA,EAAW,MAAA,yCACV,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cAuKI,cAAA,GACX,SAAA,EAAW,MAAA,yCACV,MAAM;;;;;;;;;;;;;;;;;;;;cA2BI,YAAA,GAAgB,IAAgC"}

package/dist/hooks/useClientValidation/index.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_useClientValidation = require("../../useClientValidation-_GEt49og.cjs");
+const require_useClientValidation = require("../../useClientValidation-BdchY9gA.cjs");
 //#region src/hooks/useClientValidation/index.ts
 /* v8 ignore stop */
 //#endregion

package/dist/hooks/useClientValidation/index.d.cts

@@ -1,2 +1,2 @@
-import { n as useClientValidation, t as clientValidationSchemaByName } from "../../useClientValidation-DtnfCE5T.cjs";
+import { n as useClientValidation, t as clientValidationSchemaByName } from "../../useClientValidation-BMzOi3DZ.cjs";
 export { clientValidationSchemaByName, useClientValidation };

package/dist/hooks/useClientValidation/index.d.ts

@@ -1,2 +1,2 @@
-import { n as useClientValidation, t as clientValidationSchemaByName } from "../../useClientValidation-BWElhQ91.js";
+import { n as useClientValidation, t as clientValidationSchemaByName } from "../../useClientValidation-BTbGUViN.js";
 export { clientValidationSchemaByName, useClientValidation };

package/dist/hooks/useClientValidation/index.js

@@ -1,4 +1,4 @@
-import { n as useClientValidation, t as clientValidationSchemaByName } from "../../useClientValidation-7iy9lEfO.js";
+import { n as useClientValidation, t as clientValidationSchemaByName } from "../../useClientValidation-yI5G3jqT.js";
 //#region src/hooks/useClientValidation/index.ts
 /* v8 ignore stop */
 //#endregion

package/dist/hooks/useController/index.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_useController = require("../../useController-lNSzBL-i.cjs");
+const require_useController = require("../../useController-BCvnjoe0.cjs");
 //#region src/hooks/useController/index.ts
 /* v8 ignore stop */
 //#endregion

package/dist/hooks/useController/index.d.cts

@@ -1,2 +1,2 @@
-import { n as UseControllerReturn, r as useController, t as UseControllerProps } from "../../useController-CNiqy_2D.cjs";
+import { n as UseControllerReturn, r as useController, t as UseControllerProps } from "../../useController-kxcnnsXy.cjs";
 export { UseControllerProps, UseControllerReturn, useController };

package/dist/hooks/useController/index.d.ts

@@ -1,2 +1,2 @@
-import { n as UseControllerReturn, r as useController, t as UseControllerProps } from "../../useController-Cc0UNQMm.js";
+import { n as UseControllerReturn, r as useController, t as UseControllerProps } from "../../useController-BK2AeY9L.js";
 export { UseControllerProps, UseControllerReturn, useController };

package/dist/hooks/useController/index.js

@@ -1,4 +1,4 @@
-import { t as useController } from "../../useController-BQ4LoFBd.js";
+import { t as useController } from "../../useController-DVF2y3O3.js";
 //#region src/hooks/useController/index.ts
 /* v8 ignore stop */
 //#endregion

package/dist/hooks/useFormContext/index.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_useFormContext = require("../../useFormContext-CNGE9heQ.cjs");
+const require_useFormContext = require("../../useFormContext-C_EQr8dV.cjs");
 //#region src/hooks/useFormContext/index.ts
 /* v8 ignore stop */
 //#endregion

package/dist/hooks/useFormContext/index.js

@@ -1,4 +1,4 @@
-import { n as useFormContext, t as checkFieldIsRequired } from "../../useFormContext-2vyVWpUJ.js";
+import { n as useFormContext, t as checkFieldIsRequired } from "../../useFormContext-DJ-9hs8X.js";
 //#region src/hooks/useFormContext/index.ts
 /* v8 ignore stop */
 //#endregion

package/dist/hooks/useInput/index.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-require("../../FormContext-Djp8wTG8.cjs");
+require("../../FormContext-CjDd8Zej.cjs");
 let _heroui_input = require("@heroui/input");
 //#region src/hooks/useInput/index.ts
 /* v8 ignore stop */

package/dist/hooks/useInputValueDebounce/index.cjs

@@ -1,6 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-require("../../FormContext-Djp8wTG8.cjs");
-const require_useFormContext = require("../../useFormContext-CNGE9heQ.cjs");
+require("../../FormContext-CjDd8Zej.cjs");
+const require_useFormContext = require("../../useFormContext-C_EQr8dV.cjs");
 let react = require("react");
 //#region src/hooks/useInputValueDebounce/useInputValueDebounce.ts
 /**

package/dist/hooks/useInputValueDebounce/index.js

@@ -1,4 +1,4 @@
-import { n as useFormContext } from "../../useFormContext-2vyVWpUJ.js";
+import { n as useFormContext } from "../../useFormContext-DJ-9hs8X.js";
 import { useCallback, useEffect, useRef, useState } from "react";
 //#region src/hooks/useInputValueDebounce/useInputValueDebounce.ts
 /**

package/dist/hooks/useInputValueTransform/index.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_useInputValueTransform = require("../../useInputValueTransform-5jjQVowe.cjs");
+const require_useInputValueTransform = require("../../useInputValueTransform-f50WxOkF.cjs");
 //#region src/hooks/useInputValueTransform/index.ts
 /* v8 ignore stop */
 //#endregion

package/dist/hooks/useUniformField/index.cjs

@@ -1,11 +1,11 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_FormContext = require("../../FormContext-Djp8wTG8.cjs");
+const require_FormContext = require("../../FormContext-CjDd8Zej.cjs");
 const require_helpers_index = require("../../helpers/index.cjs");
-const require_FieldCopyTestIdButton = require("../../FieldCopyTestIdButton-_5kpA4ii.cjs");
-const require_FieldValidationError = require("../../FieldValidationError-D40HtO_l.cjs");
-const require_useController = require("../../useController-lNSzBL-i.cjs");
-const require_useFormContext = require("../../useFormContext-CNGE9heQ.cjs");
-const require_useInputValueTransform = require("../../useInputValueTransform-5jjQVowe.cjs");
+const require_FieldCopyTestIdButton = require("../../FieldCopyTestIdButton-slAdYh6I.cjs");
+const require_FieldValidationError = require("../../FieldValidationError-BWrQN-Im.cjs");
+const require_useController = require("../../useController-BCvnjoe0.cjs");
+const require_useFormContext = require("../../useFormContext-C_EQr8dV.cjs");
+const require_useInputValueTransform = require("../../useInputValueTransform-f50WxOkF.cjs");
 let react = require("react");
 react = require_FormContext.__toESM(react);
 let _fuf_stack_pixels = require("@fuf-stack/pixels");
@@ -43,7 +43,7 @@ let _heroui_input = require("@heroui/input");
 const useUniformField = (params) => {
 	const { name, ariaLabel: customAriaLabel, disabled = false, testId: explicitTestId, label, type, transform } = params;
 	const { control, debugMode, formState: { submitCount }, getFieldState, getValues, resetField } = require_useFormContext.useFormContext();
-	const { error, invalid: rawInvalid, isTouched, required, testId } = getFieldState(name, explicitTestId);
+	const { error, invalid: rawInvalid, isDirty, isTouched, required, testId } = getFieldState(name, explicitTestId);
 	const { field } = require_useController.useController({
 		control,
 		disabled,
@@ -63,14 +63,14 @@ const useUniformField = (params) => {
 	* Determine when to show the invalid state to the user.
 	*
 	* Show errors when the field is invalid AND any of these conditions are met:
-	*   - Field has a value (show validation errors like format/length while typing)
+	*   - Field has a user-entered value (show validation errors like format/length while typing)
 	*   - Field is touched (focused and blurred) - good for text inputs
 	*   - Form has been submitted - shows all errors after submit attempt
 	*
-	* Note: We intentionally don't use isDirty because:
-	*   - Newly added array elements are marked "dirty" by RHF, causing immediate errors
-	*   - Field Cards with empty initial values show errors immediately
-	*   - hasValue + isTouched covers the same use cases more reliably
+	* Note: `hasValue` is gated by `isDirty` so invalid initial values do not
+	* show errors just because resolver-backed validation state is available.
+	* Newly added empty array elements can be dirty, but stay hidden until blur
+	* because they do not have a value yet.
 	*
 	* This prevents showing errors on pristine/untouched/empty fields for better UX.
 	* Examples:
@@ -84,7 +84,7 @@ const useUniformField = (params) => {
 	* The entire condition is debounced to prevent flickering and allow smooth animations.
 	*/
 	const hasValue = !require_helpers_index.isValueEmpty(fieldValue);
-	const invalid = (0, _fuf_stack_pixels.useDebounce)(rawInvalid && (hasValue || isTouched || submitCount > 0), 200);
+	const invalid = (0, _fuf_stack_pixels.useDebounce)(rawInvalid && (isDirty && hasValue || isTouched || submitCount > 0), 200);
 	const showTestIdCopyButton = debugMode === "debug-testids";
 	const labelNode = !!label || showTestIdCopyButton ? /* @__PURE__ */ (0, react_jsx_runtime.jsxs)(react_jsx_runtime.Fragment, { children: [label !== false ? label : null, showTestIdCopyButton ? /* @__PURE__ */ (0, react_jsx_runtime.jsx)(require_FieldCopyTestIdButton.FieldCopyTestIdButton, { testId }) : null] }) : null;
 	const errorMessage = /* @__PURE__ */ (0, react_jsx_runtime.jsx)(require_FieldValidationError.FieldValidationError, {

package/dist/hooks/useUniformField/index.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.cjs","names":["useFormContext","useController","useInputValueTransform","isValueEmpty","FieldCopyTestIdButton","FieldValidationError"],"sources":["../../../src/hooks/useUniformField/useUniformField.tsx","../../../src/hooks/useUniformField/index.ts"],"sourcesContent":["import type { ReactNode } from 'react';\nimport type { FieldError, FieldValues, Path } from 'react-hook-form';\nimport type { InputValueTransform } from '../useInputValueTransform/useInputValueTransform';\n\nimport React from 'react';\n\nimport { useDebounce } from '@fuf-stack/pixels';\n\nimport { isValueEmpty } from '../../helpers';\nimport { FieldCopyTestIdButton } from '../../partials/FieldCopyTestIdButton';\nimport { FieldValidationError } from '../../partials/FieldValidationError';\nimport { useController } from '../useController/useController';\nimport { useFormContext } from '../useFormContext/useFormContext';\nimport { useInput } from '../useInput/useInput';\nimport { useInputValueTransform } from '../useInputValueTransform/useInputValueTransform';\n\nexport interface UseUniformFieldParams<\n  TFieldValues extends FieldValues = FieldValues,\n  TDisplay = unknown,\n> {\n  /** Form field name */\n  name: Path<TFieldValues> & string;\n  /** Custom aria-label for accessibility. If not provided, falls back to field name when no visible label exists */\n  ariaLabel?: string;\n  /** Disable the field */\n  disabled?: boolean;\n  /** Optional label content */\n  label?: ReactNode;\n  /** Optional explicit test id used to build stable test ids */\n  testId?: string;\n  /** Optional value transformation between form and display values */\n  transform?: InputValueTransform<TDisplay>;\n  /** Input type for special number handling */\n  type?: 'text' | 'number' | 'password';\n}\n\nexport interface UseUniformFieldReturn<\n  TFieldValues extends FieldValues = FieldValues,\n> {\n  /** Computed aria-label fallback (field name) when no visible label exists. Components can override based on their accessibility needs (e.g., if placeholder provides sufficient context) */\n  ariaLabel: string | undefined;\n  /** react-hook-form control instance for advanced integrations */\n  control: ReturnType<typeof useFormContext<TFieldValues>>['control'];\n  /** Debug mode from Uniform provider */\n  debugMode: ReturnType<typeof useFormContext<TFieldValues>>['debugMode'];\n  /** Current value used to initialize uncontrolled components */\n  defaultValue: unknown;\n  /** Whether the field is currently disabled (from RHF) */\n  disabled: boolean | undefined;\n  /** Validation error(s) for the field */\n  error: FieldError[] | undefined;\n  /** Pre-built errorMessage node to plug into components */\n  errorMessage: ReactNode | null;\n  /** RHF controller field with transformed value/onChange (use this for simple components) */\n  field: ReturnType<typeof useController<TFieldValues>>['field'];\n  /** Helper to spread standardized error message props to underlying components */\n  getErrorMessageProps: ReturnType<typeof useInput>['getErrorMessageProps'];\n  /** Helper to spread standardized helper wrapper props (for spacing/animation) */\n  getHelperWrapperProps: ReturnType<typeof useInput>['getHelperWrapperProps'];\n  /** Helper to spread standardized label props to underlying components */\n  getLabelProps: ReturnType<typeof useInput>['getLabelProps'];\n  /** Access current form values (converted to validation-friendly format) */\n  getValues: ReturnType<typeof useFormContext<TFieldValues>>['getValues'];\n  /** Whether the field should show invalid state (debounced for smooth animations). True when field is invalid AND (dirty OR touched OR submitted) */\n  invalid: boolean;\n  /** Computed label node including optional test id copy button */\n  label: ReactNode | null;\n  /** onBlur handler from controller */\n  onBlur: ReturnType<typeof useController<TFieldValues>>['field']['onBlur'];\n  /** onChange handler from controller (with transform applied) */\n  onChange: ReturnType<typeof useController<TFieldValues>>['field']['onChange'];\n  /** Ref to forward to underlying control */\n  ref: ReturnType<typeof useController<TFieldValues>>['field']['ref'];\n  /** Whether the field is required according to validation schema */\n  required: boolean;\n  /** Reset a specific field in the form */\n  resetField: ReturnType<typeof useFormContext<TFieldValues>>['resetField'];\n  /** Generated HTML data-testid for the field */\n  testId: string;\n}\n\n/**\n * Combines frequently used form field logic into a single hook.\n *\n * Provides:\n * - Enhanced form context (validation-aware state, `testId`, value transforms)\n * - Controller field with nullish conversion handling\n * - Value transformation via `transform` prop:\n *   • Allows disentangled display and form values (e.g., string ↔ object, boolean ↔ array)\n *   • Automatically applies `toDisplayValue` to field value for components\n *   • Automatically applies `toFormValue` to display value when onChange is called\n *   • Works with `type` prop for automatic number/string conversion\n *   • Examples: storing objects while displaying strings, storing booleans as arrays, enriching values with metadata\n * - Debounced `invalid` state with smart timing:\n *   • `true` (field becomes invalid): applies immediately so errors show right away\n *   • `false` (field becomes valid): delayed 200ms to allow smooth exit animations\n *   • Respects `prefers-reduced-motion` by skipping delays when user prefers reduced motion\n * - Smart `invalid` visibility (via `showInvalid`):\n *   • Shows errors when field is dirty OR touched OR form has been submitted\n *   • Prevents showing errors on pristine/untouched fields for better UX\n *   • Works well for all field types (text inputs, checkboxes, radios, arrays)\n * - Prebuilt `errorMessage` React node using `FieldValidationError`\n * - Computed `label` node which appends a `FieldCopyTestIdButton` in\n *   `debug-testids` mode\n * - `defaultValue` for uncontrolled defaults and all usual field handlers\n * - Access to form utilities: `control`, `getValues`, `resetField`\n * - Presentation helpers: `getLabelProps`, `getErrorMessageProps`,\n *   `getHelperWrapperProps` for consistent wiring to underlying UI components\n */\nexport const useUniformField = <\n  TFieldValues extends FieldValues = FieldValues,\n  TDisplay = unknown,\n>(\n  params: UseUniformFieldParams<TFieldValues, TDisplay>,\n): UseUniformFieldReturn<TFieldValues> => {\n  const {\n    name,\n    ariaLabel: customAriaLabel,\n    disabled = false,\n    testId: explicitTestId,\n    label,\n    type,\n    transform,\n  } = params;\n\n  const {\n    control,\n    debugMode,\n    formState: { submitCount },\n    getFieldState,\n    getValues,\n    resetField,\n  } = useFormContext<TFieldValues>();\n\n  const {\n    error,\n    invalid: rawInvalid,\n    isTouched,\n    required,\n    testId,\n  } = getFieldState(name, explicitTestId);\n\n  const { field } = useController<TFieldValues>({\n    control,\n    disabled,\n    name,\n  });\n  const {\n    onChange: fieldOnChange,\n    value: fieldValue,\n    disabled: isDisabled,\n    onBlur,\n    ref,\n  } = field;\n\n  // Get transform utilities (but don't apply them automatically)\n  // Components can choose how to use them (directly or via useInputValueDebounce)\n  const { toDisplayValue, toFormValue } = useInputValueTransform<TDisplay>({\n    type,\n    transform,\n  });\n\n  // For components without special needs: apply transform to value and onChange\n  const transformedValue = toDisplayValue(fieldValue);\n  const transformedOnChange = (eventOrValue: TDisplay | React.ChangeEvent) => {\n    // Extract value from event or use value directly\n    const displayValue =\n      (eventOrValue as React.ChangeEvent<HTMLInputElement>)?.target?.value ??\n      eventOrValue;\n    const formValue = toFormValue(displayValue as TDisplay);\n    fieldOnChange(formValue as typeof fieldValue);\n  };\n\n  const defaultValue = (getValues() as Record<string, unknown>)?.[\n    name as string\n  ];\n\n  /**\n   * Determine when to show the invalid state to the user.\n   *\n   * Show errors when the field is invalid AND any of these conditions are met:\n   *   - Field has a value (show validation errors like format/length while typing)\n   *   - Field is touched (focused and blurred) - good for text inputs\n   *   - Form has been submitted - shows all errors after submit attempt\n   *\n   * Note: We intentionally don't use isDirty because:\n   *   - Newly added array elements are marked \"dirty\" by RHF, causing immediate errors\n   *   - Field Cards with empty initial values show errors immediately\n   *   - hasValue + isTouched covers the same use cases more reliably\n   *\n   * This prevents showing errors on pristine/untouched/empty fields for better UX.\n   * Examples:\n   *   - Text input: User loads form with empty required field → no error shown yet\n   *   - Text input: User types invalid content → error shows immediately (has value)\n   *   - Text input: User focuses and blurs without typing → error shows (via isTouched)\n   *   - Checkbox/radio: User selects option → error shows immediately (has value)\n   *   - Field array: User adds element → no error yet; after blur → error shows\n   *   - Any field: User submits form → all errors show (via submitCount)\n   *\n   * The entire condition is debounced to prevent flickering and allow smooth animations.\n   */\n\n  // isValueEmpty handles marker strings, flat array wrappers, empty arrays, and empty objects\n  const hasValue = !isValueEmpty(fieldValue);\n  const showInvalid = rawInvalid && (hasValue || isTouched || submitCount > 0);\n  // Debounce to prevent flickering during rapid state changes\n  const invalid = useDebounce(showInvalid, 200);\n\n  // Build a label node that:\n  // - shows the provided label (unless explicitly set to false)\n  // - appends a copy-to-clipboard button for the test id in `debug-testids` mode\n  // Consumers can pass this directly to component `label` props\n  const showTestIdCopyButton = debugMode === 'debug-testids';\n  const labelNode: ReactNode | null =\n    !!label || showTestIdCopyButton ? (\n      <>\n        {label !== false ? label : null}\n        {showTestIdCopyButton ? (\n          <FieldCopyTestIdButton testId={testId} />\n        ) : null}\n      </>\n    ) : null;\n\n  // Ready-to-render error message; consumers can drop this into their\n  // component `errorMessage` prop without repeating mapping/markup\n  const errorMessage = <FieldValidationError error={error} testId={testId} />;\n\n  // Generate standardized props for label, helper wrapper and error message\n  // so consumers can spread them directly into UI components (e.g. HeroUI),\n  // keeping animations/spacing consistent across fields\n  const { getErrorMessageProps, getLabelProps, getHelperWrapperProps } =\n    useInput({\n      ref,\n      classNames: {\n        // set padding to 0 for error message exit animation\n        helperWrapper: 'p-0',\n      },\n      errorMessage: JSON.stringify(error),\n      isInvalid: invalid,\n      isRequired: required,\n      label,\n      labelPlacement: 'outside',\n    });\n\n  // Compute aria-label: prefer custom prop, then use string label if available, otherwise field name\n  // Components can further override this based on their specific accessibility needs\n  // (e.g., Input/TextArea may skip this if they have a meaningful placeholder)\n  const ariaLabel =\n    customAriaLabel ?? (typeof label === 'string' ? label : name);\n\n  return {\n    ariaLabel,\n    control,\n    debugMode,\n    defaultValue,\n    disabled: isDisabled,\n    error,\n    errorMessage,\n    field: {\n      ...field,\n      value: transformedValue as typeof field.value,\n      onChange: transformedOnChange as typeof field.onChange,\n    },\n    getErrorMessageProps,\n    getHelperWrapperProps,\n    getLabelProps,\n    getValues,\n    invalid,\n    label: labelNode,\n    onBlur,\n    onChange: transformedOnChange as typeof field.onChange,\n    ref,\n    required,\n    resetField,\n    testId,\n  };\n};\n","/* v8 ignore start */\n\nexport * from './useUniformField';\n\n/* v8 ignore stop */\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6GA,MAAa,mBAIX,WACwC;CACxC,MAAM,EACJ,MACA,WAAW,iBACX,WAAW,OACX,QAAQ,gBACR,OACA,MACA,cACE;CAEJ,MAAM,EACJ,SACA,WACA,WAAW,EAAE,eACb,eACA,WACA,eACEA,uBAAAA,eAA6B;CAEjC,MAAM,EACJ,OACA,SAAS,YACT,WACA,UACA,WACE,cAAc,MAAM,cAAc;CAEtC,MAAM,EAAE,UAAUC,sBAAAA,cAA4B;EAC5C;EACA;EACA;CACF,CAAC;CACD,MAAM,EACJ,UAAU,eACV,OAAO,YACP,UAAU,YACV,QACA,QACE;CAIJ,MAAM,EAAE,gBAAgB,gBAAgBC,+BAAAA,uBAAiC;EACvE;EACA;CACF,CAAC;CAGD,MAAM,mBAAmB,eAAe,UAAU;CAClD,MAAM,uBAAuB,iBAA+C;EAM1E,cADkB,YAFf,cAAsD,QAAQ,SAC/D,YAEoB,CAAsB;CAC9C;CAEA,MAAM,eAAgB,UAAU,IAC9B;;;;;;;;;;;;;;;;;;;;;;;;;CA6BF,MAAM,WAAW,CAACC,sBAAAA,aAAa,UAAU;CAGzC,MAAM,WAAA,GAAA,kBAAA,aAFc,eAAe,YAAY,aAAa,cAAc,IAEjC,GAAG;CAM5C,MAAM,uBAAuB,cAAc;CAC3C,MAAM,YACJ,CAAC,CAAC,SAAS,uBACT,iBAAA,GAAA,kBAAA,MAAA,kBAAA,UAAA,EAAA,UAAA,CACG,UAAU,QAAQ,QAAQ,MAC1B,uBACC,iBAAA,GAAA,kBAAA,KAACC,8BAAAA,uBAAD,EAA+B,OAAS,CAAA,IACtC,IACJ,EAAA,CAAA,IACA;CAIN,MAAM,eAAe,iBAAA,GAAA,kBAAA,KAACC,6BAAAA,sBAAD;EAA6B;EAAe;CAAS,CAAA;CAK1E,MAAM,EAAE,sBAAsB,eAAe,2BAAA,GAAA,cAAA,UAClC;EACP;EACA,YAAY,EAEV,eAAe,MACjB;EACA,cAAc,KAAK,UAAU,KAAK;EAClC,WAAW;EACX,YAAY;EACZ;EACA,gBAAgB;CAClB,CAAC;CAQH,OAAO;EACL,WAHA,oBAAoB,OAAO,UAAU,WAAW,QAAQ;EAIxD;EACA;EACA;EACA,UAAU;EACV;EACA;EACA,OAAO;GACL,GAAG;GACH,OAAO;GACP,UAAU;EACZ;EACA;EACA;EACA;EACA;EACA;EACA,OAAO;EACP;EACA,UAAU;EACV;EACA;EACA;EACA;CACF;AACF"}
+{"version":3,"file":"index.cjs","names":["useFormContext","useController","useInputValueTransform","isValueEmpty","FieldCopyTestIdButton","FieldValidationError"],"sources":["../../../src/hooks/useUniformField/useUniformField.tsx","../../../src/hooks/useUniformField/index.ts"],"sourcesContent":["import type { ReactNode } from 'react';\nimport type { FieldError, FieldValues, Path } from 'react-hook-form';\nimport type { InputValueTransform } from '../useInputValueTransform/useInputValueTransform';\n\nimport React from 'react';\n\nimport { useDebounce } from '@fuf-stack/pixels';\n\nimport { isValueEmpty } from '../../helpers';\nimport { FieldCopyTestIdButton } from '../../partials/FieldCopyTestIdButton';\nimport { FieldValidationError } from '../../partials/FieldValidationError';\nimport { useController } from '../useController/useController';\nimport { useFormContext } from '../useFormContext/useFormContext';\nimport { useInput } from '../useInput/useInput';\nimport { useInputValueTransform } from '../useInputValueTransform/useInputValueTransform';\n\nexport interface UseUniformFieldParams<\n  TFieldValues extends FieldValues = FieldValues,\n  TDisplay = unknown,\n> {\n  /** Form field name */\n  name: Path<TFieldValues> & string;\n  /** Custom aria-label for accessibility. If not provided, falls back to field name when no visible label exists */\n  ariaLabel?: string;\n  /** Disable the field */\n  disabled?: boolean;\n  /** Optional label content */\n  label?: ReactNode;\n  /** Optional explicit test id used to build stable test ids */\n  testId?: string;\n  /** Optional value transformation between form and display values */\n  transform?: InputValueTransform<TDisplay>;\n  /** Input type for special number handling */\n  type?: 'text' | 'number' | 'password';\n}\n\nexport interface UseUniformFieldReturn<\n  TFieldValues extends FieldValues = FieldValues,\n> {\n  /** Computed aria-label fallback (field name) when no visible label exists. Components can override based on their accessibility needs (e.g., if placeholder provides sufficient context) */\n  ariaLabel: string | undefined;\n  /** react-hook-form control instance for advanced integrations */\n  control: ReturnType<typeof useFormContext<TFieldValues>>['control'];\n  /** Debug mode from Uniform provider */\n  debugMode: ReturnType<typeof useFormContext<TFieldValues>>['debugMode'];\n  /** Current value used to initialize uncontrolled components */\n  defaultValue: unknown;\n  /** Whether the field is currently disabled (from RHF) */\n  disabled: boolean | undefined;\n  /** Validation error(s) for the field */\n  error: FieldError[] | undefined;\n  /** Pre-built errorMessage node to plug into components */\n  errorMessage: ReactNode | null;\n  /** RHF controller field with transformed value/onChange (use this for simple components) */\n  field: ReturnType<typeof useController<TFieldValues>>['field'];\n  /** Helper to spread standardized error message props to underlying components */\n  getErrorMessageProps: ReturnType<typeof useInput>['getErrorMessageProps'];\n  /** Helper to spread standardized helper wrapper props (for spacing/animation) */\n  getHelperWrapperProps: ReturnType<typeof useInput>['getHelperWrapperProps'];\n  /** Helper to spread standardized label props to underlying components */\n  getLabelProps: ReturnType<typeof useInput>['getLabelProps'];\n  /** Access current form values (converted to validation-friendly format) */\n  getValues: ReturnType<typeof useFormContext<TFieldValues>>['getValues'];\n  /** Whether the field should show invalid state (debounced for smooth animations). True when field is invalid AND (dirty OR touched OR submitted) */\n  invalid: boolean;\n  /** Computed label node including optional test id copy button */\n  label: ReactNode | null;\n  /** onBlur handler from controller */\n  onBlur: ReturnType<typeof useController<TFieldValues>>['field']['onBlur'];\n  /** onChange handler from controller (with transform applied) */\n  onChange: ReturnType<typeof useController<TFieldValues>>['field']['onChange'];\n  /** Ref to forward to underlying control */\n  ref: ReturnType<typeof useController<TFieldValues>>['field']['ref'];\n  /** Whether the field is required according to validation schema */\n  required: boolean;\n  /** Reset a specific field in the form */\n  resetField: ReturnType<typeof useFormContext<TFieldValues>>['resetField'];\n  /** Generated HTML data-testid for the field */\n  testId: string;\n}\n\n/**\n * Combines frequently used form field logic into a single hook.\n *\n * Provides:\n * - Enhanced form context (validation-aware state, `testId`, value transforms)\n * - Controller field with nullish conversion handling\n * - Value transformation via `transform` prop:\n *   • Allows disentangled display and form values (e.g., string ↔ object, boolean ↔ array)\n *   • Automatically applies `toDisplayValue` to field value for components\n *   • Automatically applies `toFormValue` to display value when onChange is called\n *   • Works with `type` prop for automatic number/string conversion\n *   • Examples: storing objects while displaying strings, storing booleans as arrays, enriching values with metadata\n * - Debounced `invalid` state with smart timing:\n *   • `true` (field becomes invalid): applies immediately so errors show right away\n *   • `false` (field becomes valid): delayed 200ms to allow smooth exit animations\n *   • Respects `prefers-reduced-motion` by skipping delays when user prefers reduced motion\n * - Smart `invalid` visibility (via `showInvalid`):\n *   • Shows errors when field is dirty OR touched OR form has been submitted\n *   • Prevents showing errors on pristine/untouched fields for better UX\n *   • Works well for all field types (text inputs, checkboxes, radios, arrays)\n * - Prebuilt `errorMessage` React node using `FieldValidationError`\n * - Computed `label` node which appends a `FieldCopyTestIdButton` in\n *   `debug-testids` mode\n * - `defaultValue` for uncontrolled defaults and all usual field handlers\n * - Access to form utilities: `control`, `getValues`, `resetField`\n * - Presentation helpers: `getLabelProps`, `getErrorMessageProps`,\n *   `getHelperWrapperProps` for consistent wiring to underlying UI components\n */\nexport const useUniformField = <\n  TFieldValues extends FieldValues = FieldValues,\n  TDisplay = unknown,\n>(\n  params: UseUniformFieldParams<TFieldValues, TDisplay>,\n): UseUniformFieldReturn<TFieldValues> => {\n  const {\n    name,\n    ariaLabel: customAriaLabel,\n    disabled = false,\n    testId: explicitTestId,\n    label,\n    type,\n    transform,\n  } = params;\n\n  const {\n    control,\n    debugMode,\n    formState: { submitCount },\n    getFieldState,\n    getValues,\n    resetField,\n  } = useFormContext<TFieldValues>();\n\n  const {\n    error,\n    invalid: rawInvalid,\n    isDirty,\n    isTouched,\n    required,\n    testId,\n  } = getFieldState(name, explicitTestId);\n\n  const { field } = useController<TFieldValues>({\n    control,\n    disabled,\n    name,\n  });\n  const {\n    onChange: fieldOnChange,\n    value: fieldValue,\n    disabled: isDisabled,\n    onBlur,\n    ref,\n  } = field;\n\n  // Get transform utilities (but don't apply them automatically)\n  // Components can choose how to use them (directly or via useInputValueDebounce)\n  const { toDisplayValue, toFormValue } = useInputValueTransform<TDisplay>({\n    type,\n    transform,\n  });\n\n  // For components without special needs: apply transform to value and onChange\n  const transformedValue = toDisplayValue(fieldValue);\n  const transformedOnChange = (eventOrValue: TDisplay | React.ChangeEvent) => {\n    // Extract value from event or use value directly\n    const displayValue =\n      (eventOrValue as React.ChangeEvent<HTMLInputElement>)?.target?.value ??\n      eventOrValue;\n    const formValue = toFormValue(displayValue as TDisplay);\n    fieldOnChange(formValue);\n  };\n\n  const defaultValue = (getValues() as Record<string, unknown>)?.[\n    name as string\n  ];\n\n  /**\n   * Determine when to show the invalid state to the user.\n   *\n   * Show errors when the field is invalid AND any of these conditions are met:\n   *   - Field has a user-entered value (show validation errors like format/length while typing)\n   *   - Field is touched (focused and blurred) - good for text inputs\n   *   - Form has been submitted - shows all errors after submit attempt\n   *\n   * Note: `hasValue` is gated by `isDirty` so invalid initial values do not\n   * show errors just because resolver-backed validation state is available.\n   * Newly added empty array elements can be dirty, but stay hidden until blur\n   * because they do not have a value yet.\n   *\n   * This prevents showing errors on pristine/untouched/empty fields for better UX.\n   * Examples:\n   *   - Text input: User loads form with empty required field → no error shown yet\n   *   - Text input: User types invalid content → error shows immediately (has value)\n   *   - Text input: User focuses and blurs without typing → error shows (via isTouched)\n   *   - Checkbox/radio: User selects option → error shows immediately (has value)\n   *   - Field array: User adds element → no error yet; after blur → error shows\n   *   - Any field: User submits form → all errors show (via submitCount)\n   *\n   * The entire condition is debounced to prevent flickering and allow smooth animations.\n   */\n\n  // isValueEmpty handles marker strings, flat array wrappers, empty arrays, and empty objects\n  const hasValue = !isValueEmpty(fieldValue);\n  const showInvalid =\n    rawInvalid && ((isDirty && hasValue) || isTouched || submitCount > 0);\n  // Debounce to prevent flickering during rapid state changes\n  const invalid = useDebounce(showInvalid, 200);\n\n  // Build a label node that:\n  // - shows the provided label (unless explicitly set to false)\n  // - appends a copy-to-clipboard button for the test id in `debug-testids` mode\n  // Consumers can pass this directly to component `label` props\n  const showTestIdCopyButton = debugMode === 'debug-testids';\n  const labelNode: ReactNode | null =\n    !!label || showTestIdCopyButton ? (\n      <>\n        {label !== false ? label : null}\n        {showTestIdCopyButton ? (\n          <FieldCopyTestIdButton testId={testId} />\n        ) : null}\n      </>\n    ) : null;\n\n  // Ready-to-render error message; consumers can drop this into their\n  // component `errorMessage` prop without repeating mapping/markup\n  const errorMessage = <FieldValidationError error={error} testId={testId} />;\n\n  // Generate standardized props for label, helper wrapper and error message\n  // so consumers can spread them directly into UI components (e.g. HeroUI),\n  // keeping animations/spacing consistent across fields\n  const { getErrorMessageProps, getLabelProps, getHelperWrapperProps } =\n    useInput({\n      ref,\n      classNames: {\n        // set padding to 0 for error message exit animation\n        helperWrapper: 'p-0',\n      },\n      errorMessage: JSON.stringify(error),\n      isInvalid: invalid,\n      isRequired: required,\n      label,\n      labelPlacement: 'outside',\n    });\n\n  // Compute aria-label: prefer custom prop, then use string label if available, otherwise field name\n  // Components can further override this based on their specific accessibility needs\n  // (e.g., Input/TextArea may skip this if they have a meaningful placeholder)\n  const ariaLabel =\n    customAriaLabel ?? (typeof label === 'string' ? label : name);\n\n  return {\n    ariaLabel,\n    control,\n    debugMode,\n    defaultValue,\n    disabled: isDisabled,\n    error,\n    errorMessage,\n    field: {\n      ...field,\n      value: transformedValue as typeof field.value,\n      onChange: transformedOnChange as typeof field.onChange,\n    },\n    getErrorMessageProps,\n    getHelperWrapperProps,\n    getLabelProps,\n    getValues,\n    invalid,\n    label: labelNode,\n    onBlur,\n    onChange: transformedOnChange as typeof field.onChange,\n    ref,\n    required,\n    resetField,\n    testId,\n  };\n};\n","/* v8 ignore start */\n\nexport * from './useUniformField';\n\n/* v8 ignore stop */\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6GA,MAAa,mBAIX,WACwC;CACxC,MAAM,EACJ,MACA,WAAW,iBACX,WAAW,OACX,QAAQ,gBACR,OACA,MACA,cACE;CAEJ,MAAM,EACJ,SACA,WACA,WAAW,EAAE,eACb,eACA,WACA,eACEA,uBAAAA,eAA6B;CAEjC,MAAM,EACJ,OACA,SAAS,YACT,SACA,WACA,UACA,WACE,cAAc,MAAM,cAAc;CAEtC,MAAM,EAAE,UAAUC,sBAAAA,cAA4B;EAC5C;EACA;EACA;CACF,CAAC;CACD,MAAM,EACJ,UAAU,eACV,OAAO,YACP,UAAU,YACV,QACA,QACE;CAIJ,MAAM,EAAE,gBAAgB,gBAAgBC,+BAAAA,uBAAiC;EACvE;EACA;CACF,CAAC;CAGD,MAAM,mBAAmB,eAAe,UAAU;CAClD,MAAM,uBAAuB,iBAA+C;EAM1E,cADkB,YAFf,cAAsD,QAAQ,SAC/D,YAEoB,CAAC;CACzB;CAEA,MAAM,eAAgB,UAAU,IAC9B;;;;;;;;;;;;;;;;;;;;;;;;;CA6BF,MAAM,WAAW,CAACC,sBAAAA,aAAa,UAAU;CAIzC,MAAM,WAAA,GAAA,kBAAA,aAFJ,eAAgB,WAAW,YAAa,aAAa,cAAc,IAE5B,GAAG;CAM5C,MAAM,uBAAuB,cAAc;CAC3C,MAAM,YACJ,CAAC,CAAC,SAAS,uBACT,iBAAA,GAAA,kBAAA,MAAA,kBAAA,UAAA,EAAA,UAAA,CACG,UAAU,QAAQ,QAAQ,MAC1B,uBACC,iBAAA,GAAA,kBAAA,KAACC,8BAAAA,uBAAD,EAA+B,OAAS,CAAA,IACtC,IACJ,EAAA,CAAA,IACA;CAIN,MAAM,eAAe,iBAAA,GAAA,kBAAA,KAACC,6BAAAA,sBAAD;EAA6B;EAAe;CAAS,CAAA;CAK1E,MAAM,EAAE,sBAAsB,eAAe,2BAAA,GAAA,cAAA,UAClC;EACP;EACA,YAAY,EAEV,eAAe,MACjB;EACA,cAAc,KAAK,UAAU,KAAK;EAClC,WAAW;EACX,YAAY;EACZ;EACA,gBAAgB;CAClB,CAAC;CAQH,OAAO;EACL,WAHA,oBAAoB,OAAO,UAAU,WAAW,QAAQ;EAIxD;EACA;EACA;EACA,UAAU;EACV;EACA;EACA,OAAO;GACL,GAAG;GACH,OAAO;GACP,UAAU;EACZ;EACA;EACA;EACA;EACA;EACA;EACA,OAAO;EACP;EACA,UAAU;EACV;EACA;EACA;EACA;CACF;AACF"}

package/dist/hooks/useUniformField/index.d.cts

@@ -1,2 +1,2 @@
-import { n as UseUniformFieldReturn, r as useUniformField, t as UseUniformFieldParams } from "../../useUniformField-D-Klu-sM.cjs";
+import { n as UseUniformFieldReturn, r as useUniformField, t as UseUniformFieldParams } from "../../useUniformField-BWKBsUEX.cjs";
 export { UseUniformFieldParams, UseUniformFieldReturn, useUniformField };

package/dist/hooks/useUniformField/index.d.ts

@@ -1,2 +1,2 @@
-import { n as UseUniformFieldReturn, r as useUniformField, t as UseUniformFieldParams } from "../../useUniformField-CMb5EZ7Y.js";
+import { n as UseUniformFieldReturn, r as useUniformField, t as UseUniformFieldParams } from "../../useUniformField-B3Dj8K5J.js";
 export { UseUniformFieldParams, UseUniformFieldReturn, useUniformField };

package/dist/hooks/useUniformField/index.js

@@ -1,8 +1,8 @@
 import { isValueEmpty } from "../../helpers/index.js";
 import { n as FieldCopyTestIdButton } from "../../FieldCopyTestIdButton-Dpmo0uBV.js";
 import { n as FieldValidationError } from "../../FieldValidationError-ktTyyyip.js";
-import { t as useController } from "../../useController-BQ4LoFBd.js";
-import { n as useFormContext } from "../../useFormContext-2vyVWpUJ.js";
+import { t as useController } from "../../useController-DVF2y3O3.js";
+import { n as useFormContext } from "../../useFormContext-DJ-9hs8X.js";
 import { t as useInput } from "../../useInput-CVm3tP78.js";
 import { t as useInputValueTransform } from "../../useInputValueTransform-CXdmtc0Q.js";
 import "react";
@@ -40,7 +40,7 @@ import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 const useUniformField = (params) => {
 	const { name, ariaLabel: customAriaLabel, disabled = false, testId: explicitTestId, label, type, transform } = params;
 	const { control, debugMode, formState: { submitCount }, getFieldState, getValues, resetField } = useFormContext();
-	const { error, invalid: rawInvalid, isTouched, required, testId } = getFieldState(name, explicitTestId);
+	const { error, invalid: rawInvalid, isDirty, isTouched, required, testId } = getFieldState(name, explicitTestId);
 	const { field } = useController({
 		control,
 		disabled,
@@ -60,14 +60,14 @@ const useUniformField = (params) => {
 	* Determine when to show the invalid state to the user.
 	*
 	* Show errors when the field is invalid AND any of these conditions are met:
-	*   - Field has a value (show validation errors like format/length while typing)
+	*   - Field has a user-entered value (show validation errors like format/length while typing)
 	*   - Field is touched (focused and blurred) - good for text inputs
 	*   - Form has been submitted - shows all errors after submit attempt
 	*
-	* Note: We intentionally don't use isDirty because:
-	*   - Newly added array elements are marked "dirty" by RHF, causing immediate errors
-	*   - Field Cards with empty initial values show errors immediately
-	*   - hasValue + isTouched covers the same use cases more reliably
+	* Note: `hasValue` is gated by `isDirty` so invalid initial values do not
+	* show errors just because resolver-backed validation state is available.
+	* Newly added empty array elements can be dirty, but stay hidden until blur
+	* because they do not have a value yet.
 	*
 	* This prevents showing errors on pristine/untouched/empty fields for better UX.
 	* Examples:
@@ -81,7 +81,7 @@ const useUniformField = (params) => {
 	* The entire condition is debounced to prevent flickering and allow smooth animations.
 	*/
 	const hasValue = !isValueEmpty(fieldValue);
-	const invalid = useDebounce(rawInvalid && (hasValue || isTouched || submitCount > 0), 200);
+	const invalid = useDebounce(rawInvalid && (isDirty && hasValue || isTouched || submitCount > 0), 200);
 	const showTestIdCopyButton = debugMode === "debug-testids";
 	const labelNode = !!label || showTestIdCopyButton ? /* @__PURE__ */ jsxs(Fragment, { children: [label !== false ? label : null, showTestIdCopyButton ? /* @__PURE__ */ jsx(FieldCopyTestIdButton, { testId }) : null] }) : null;
 	const errorMessage = /* @__PURE__ */ jsx(FieldValidationError, {

package/dist/hooks/useUniformField/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":[],"sources":["../../../src/hooks/useUniformField/useUniformField.tsx","../../../src/hooks/useUniformField/index.ts"],"sourcesContent":["import type { ReactNode } from 'react';\nimport type { FieldError, FieldValues, Path } from 'react-hook-form';\nimport type { InputValueTransform } from '../useInputValueTransform/useInputValueTransform';\n\nimport React from 'react';\n\nimport { useDebounce } from '@fuf-stack/pixels';\n\nimport { isValueEmpty } from '../../helpers';\nimport { FieldCopyTestIdButton } from '../../partials/FieldCopyTestIdButton';\nimport { FieldValidationError } from '../../partials/FieldValidationError';\nimport { useController } from '../useController/useController';\nimport { useFormContext } from '../useFormContext/useFormContext';\nimport { useInput } from '../useInput/useInput';\nimport { useInputValueTransform } from '../useInputValueTransform/useInputValueTransform';\n\nexport interface UseUniformFieldParams<\n  TFieldValues extends FieldValues = FieldValues,\n  TDisplay = unknown,\n> {\n  /** Form field name */\n  name: Path<TFieldValues> & string;\n  /** Custom aria-label for accessibility. If not provided, falls back to field name when no visible label exists */\n  ariaLabel?: string;\n  /** Disable the field */\n  disabled?: boolean;\n  /** Optional label content */\n  label?: ReactNode;\n  /** Optional explicit test id used to build stable test ids */\n  testId?: string;\n  /** Optional value transformation between form and display values */\n  transform?: InputValueTransform<TDisplay>;\n  /** Input type for special number handling */\n  type?: 'text' | 'number' | 'password';\n}\n\nexport interface UseUniformFieldReturn<\n  TFieldValues extends FieldValues = FieldValues,\n> {\n  /** Computed aria-label fallback (field name) when no visible label exists. Components can override based on their accessibility needs (e.g., if placeholder provides sufficient context) */\n  ariaLabel: string | undefined;\n  /** react-hook-form control instance for advanced integrations */\n  control: ReturnType<typeof useFormContext<TFieldValues>>['control'];\n  /** Debug mode from Uniform provider */\n  debugMode: ReturnType<typeof useFormContext<TFieldValues>>['debugMode'];\n  /** Current value used to initialize uncontrolled components */\n  defaultValue: unknown;\n  /** Whether the field is currently disabled (from RHF) */\n  disabled: boolean | undefined;\n  /** Validation error(s) for the field */\n  error: FieldError[] | undefined;\n  /** Pre-built errorMessage node to plug into components */\n  errorMessage: ReactNode | null;\n  /** RHF controller field with transformed value/onChange (use this for simple components) */\n  field: ReturnType<typeof useController<TFieldValues>>['field'];\n  /** Helper to spread standardized error message props to underlying components */\n  getErrorMessageProps: ReturnType<typeof useInput>['getErrorMessageProps'];\n  /** Helper to spread standardized helper wrapper props (for spacing/animation) */\n  getHelperWrapperProps: ReturnType<typeof useInput>['getHelperWrapperProps'];\n  /** Helper to spread standardized label props to underlying components */\n  getLabelProps: ReturnType<typeof useInput>['getLabelProps'];\n  /** Access current form values (converted to validation-friendly format) */\n  getValues: ReturnType<typeof useFormContext<TFieldValues>>['getValues'];\n  /** Whether the field should show invalid state (debounced for smooth animations). True when field is invalid AND (dirty OR touched OR submitted) */\n  invalid: boolean;\n  /** Computed label node including optional test id copy button */\n  label: ReactNode | null;\n  /** onBlur handler from controller */\n  onBlur: ReturnType<typeof useController<TFieldValues>>['field']['onBlur'];\n  /** onChange handler from controller (with transform applied) */\n  onChange: ReturnType<typeof useController<TFieldValues>>['field']['onChange'];\n  /** Ref to forward to underlying control */\n  ref: ReturnType<typeof useController<TFieldValues>>['field']['ref'];\n  /** Whether the field is required according to validation schema */\n  required: boolean;\n  /** Reset a specific field in the form */\n  resetField: ReturnType<typeof useFormContext<TFieldValues>>['resetField'];\n  /** Generated HTML data-testid for the field */\n  testId: string;\n}\n\n/**\n * Combines frequently used form field logic into a single hook.\n *\n * Provides:\n * - Enhanced form context (validation-aware state, `testId`, value transforms)\n * - Controller field with nullish conversion handling\n * - Value transformation via `transform` prop:\n *   • Allows disentangled display and form values (e.g., string ↔ object, boolean ↔ array)\n *   • Automatically applies `toDisplayValue` to field value for components\n *   • Automatically applies `toFormValue` to display value when onChange is called\n *   • Works with `type` prop for automatic number/string conversion\n *   • Examples: storing objects while displaying strings, storing booleans as arrays, enriching values with metadata\n * - Debounced `invalid` state with smart timing:\n *   • `true` (field becomes invalid): applies immediately so errors show right away\n *   • `false` (field becomes valid): delayed 200ms to allow smooth exit animations\n *   • Respects `prefers-reduced-motion` by skipping delays when user prefers reduced motion\n * - Smart `invalid` visibility (via `showInvalid`):\n *   • Shows errors when field is dirty OR touched OR form has been submitted\n *   • Prevents showing errors on pristine/untouched fields for better UX\n *   • Works well for all field types (text inputs, checkboxes, radios, arrays)\n * - Prebuilt `errorMessage` React node using `FieldValidationError`\n * - Computed `label` node which appends a `FieldCopyTestIdButton` in\n *   `debug-testids` mode\n * - `defaultValue` for uncontrolled defaults and all usual field handlers\n * - Access to form utilities: `control`, `getValues`, `resetField`\n * - Presentation helpers: `getLabelProps`, `getErrorMessageProps`,\n *   `getHelperWrapperProps` for consistent wiring to underlying UI components\n */\nexport const useUniformField = <\n  TFieldValues extends FieldValues = FieldValues,\n  TDisplay = unknown,\n>(\n  params: UseUniformFieldParams<TFieldValues, TDisplay>,\n): UseUniformFieldReturn<TFieldValues> => {\n  const {\n    name,\n    ariaLabel: customAriaLabel,\n    disabled = false,\n    testId: explicitTestId,\n    label,\n    type,\n    transform,\n  } = params;\n\n  const {\n    control,\n    debugMode,\n    formState: { submitCount },\n    getFieldState,\n    getValues,\n    resetField,\n  } = useFormContext<TFieldValues>();\n\n  const {\n    error,\n    invalid: rawInvalid,\n    isTouched,\n    required,\n    testId,\n  } = getFieldState(name, explicitTestId);\n\n  const { field } = useController<TFieldValues>({\n    control,\n    disabled,\n    name,\n  });\n  const {\n    onChange: fieldOnChange,\n    value: fieldValue,\n    disabled: isDisabled,\n    onBlur,\n    ref,\n  } = field;\n\n  // Get transform utilities (but don't apply them automatically)\n  // Components can choose how to use them (directly or via useInputValueDebounce)\n  const { toDisplayValue, toFormValue } = useInputValueTransform<TDisplay>({\n    type,\n    transform,\n  });\n\n  // For components without special needs: apply transform to value and onChange\n  const transformedValue = toDisplayValue(fieldValue);\n  const transformedOnChange = (eventOrValue: TDisplay | React.ChangeEvent) => {\n    // Extract value from event or use value directly\n    const displayValue =\n      (eventOrValue as React.ChangeEvent<HTMLInputElement>)?.target?.value ??\n      eventOrValue;\n    const formValue = toFormValue(displayValue as TDisplay);\n    fieldOnChange(formValue as typeof fieldValue);\n  };\n\n  const defaultValue = (getValues() as Record<string, unknown>)?.[\n    name as string\n  ];\n\n  /**\n   * Determine when to show the invalid state to the user.\n   *\n   * Show errors when the field is invalid AND any of these conditions are met:\n   *   - Field has a value (show validation errors like format/length while typing)\n   *   - Field is touched (focused and blurred) - good for text inputs\n   *   - Form has been submitted - shows all errors after submit attempt\n   *\n   * Note: We intentionally don't use isDirty because:\n   *   - Newly added array elements are marked \"dirty\" by RHF, causing immediate errors\n   *   - Field Cards with empty initial values show errors immediately\n   *   - hasValue + isTouched covers the same use cases more reliably\n   *\n   * This prevents showing errors on pristine/untouched/empty fields for better UX.\n   * Examples:\n   *   - Text input: User loads form with empty required field → no error shown yet\n   *   - Text input: User types invalid content → error shows immediately (has value)\n   *   - Text input: User focuses and blurs without typing → error shows (via isTouched)\n   *   - Checkbox/radio: User selects option → error shows immediately (has value)\n   *   - Field array: User adds element → no error yet; after blur → error shows\n   *   - Any field: User submits form → all errors show (via submitCount)\n   *\n   * The entire condition is debounced to prevent flickering and allow smooth animations.\n   */\n\n  // isValueEmpty handles marker strings, flat array wrappers, empty arrays, and empty objects\n  const hasValue = !isValueEmpty(fieldValue);\n  const showInvalid = rawInvalid && (hasValue || isTouched || submitCount > 0);\n  // Debounce to prevent flickering during rapid state changes\n  const invalid = useDebounce(showInvalid, 200);\n\n  // Build a label node that:\n  // - shows the provided label (unless explicitly set to false)\n  // - appends a copy-to-clipboard button for the test id in `debug-testids` mode\n  // Consumers can pass this directly to component `label` props\n  const showTestIdCopyButton = debugMode === 'debug-testids';\n  const labelNode: ReactNode | null =\n    !!label || showTestIdCopyButton ? (\n      <>\n        {label !== false ? label : null}\n        {showTestIdCopyButton ? (\n          <FieldCopyTestIdButton testId={testId} />\n        ) : null}\n      </>\n    ) : null;\n\n  // Ready-to-render error message; consumers can drop this into their\n  // component `errorMessage` prop without repeating mapping/markup\n  const errorMessage = <FieldValidationError error={error} testId={testId} />;\n\n  // Generate standardized props for label, helper wrapper and error message\n  // so consumers can spread them directly into UI components (e.g. HeroUI),\n  // keeping animations/spacing consistent across fields\n  const { getErrorMessageProps, getLabelProps, getHelperWrapperProps } =\n    useInput({\n      ref,\n      classNames: {\n        // set padding to 0 for error message exit animation\n        helperWrapper: 'p-0',\n      },\n      errorMessage: JSON.stringify(error),\n      isInvalid: invalid,\n      isRequired: required,\n      label,\n      labelPlacement: 'outside',\n    });\n\n  // Compute aria-label: prefer custom prop, then use string label if available, otherwise field name\n  // Components can further override this based on their specific accessibility needs\n  // (e.g., Input/TextArea may skip this if they have a meaningful placeholder)\n  const ariaLabel =\n    customAriaLabel ?? (typeof label === 'string' ? label : name);\n\n  return {\n    ariaLabel,\n    control,\n    debugMode,\n    defaultValue,\n    disabled: isDisabled,\n    error,\n    errorMessage,\n    field: {\n      ...field,\n      value: transformedValue as typeof field.value,\n      onChange: transformedOnChange as typeof field.onChange,\n    },\n    getErrorMessageProps,\n    getHelperWrapperProps,\n    getLabelProps,\n    getValues,\n    invalid,\n    label: labelNode,\n    onBlur,\n    onChange: transformedOnChange as typeof field.onChange,\n    ref,\n    required,\n    resetField,\n    testId,\n  };\n};\n","/* v8 ignore start */\n\nexport * from './useUniformField';\n\n/* v8 ignore stop */\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6GA,MAAa,mBAIX,WACwC;CACxC,MAAM,EACJ,MACA,WAAW,iBACX,WAAW,OACX,QAAQ,gBACR,OACA,MACA,cACE;CAEJ,MAAM,EACJ,SACA,WACA,WAAW,EAAE,eACb,eACA,WACA,eACE,eAA6B;CAEjC,MAAM,EACJ,OACA,SAAS,YACT,WACA,UACA,WACE,cAAc,MAAM,cAAc;CAEtC,MAAM,EAAE,UAAU,cAA4B;EAC5C;EACA;EACA;CACF,CAAC;CACD,MAAM,EACJ,UAAU,eACV,OAAO,YACP,UAAU,YACV,QACA,QACE;CAIJ,MAAM,EAAE,gBAAgB,gBAAgB,uBAAiC;EACvE;EACA;CACF,CAAC;CAGD,MAAM,mBAAmB,eAAe,UAAU;CAClD,MAAM,uBAAuB,iBAA+C;EAM1E,cADkB,YAFf,cAAsD,QAAQ,SAC/D,YAEoB,CAAsB;CAC9C;CAEA,MAAM,eAAgB,UAAU,IAC9B;;;;;;;;;;;;;;;;;;;;;;;;;CA6BF,MAAM,WAAW,CAAC,aAAa,UAAU;CAGzC,MAAM,UAAU,YAFI,eAAe,YAAY,aAAa,cAAc,IAEjC,GAAG;CAM5C,MAAM,uBAAuB,cAAc;CAC3C,MAAM,YACJ,CAAC,CAAC,SAAS,uBACT,qBAAA,UAAA,EAAA,UAAA,CACG,UAAU,QAAQ,QAAQ,MAC1B,uBACC,oBAAC,uBAAD,EAA+B,OAAS,CAAA,IACtC,IACJ,EAAA,CAAA,IACA;CAIN,MAAM,eAAe,oBAAC,sBAAD;EAA6B;EAAe;CAAS,CAAA;CAK1E,MAAM,EAAE,sBAAsB,eAAe,0BAC3C,SAAS;EACP;EACA,YAAY,EAEV,eAAe,MACjB;EACA,cAAc,KAAK,UAAU,KAAK;EAClC,WAAW;EACX,YAAY;EACZ;EACA,gBAAgB;CAClB,CAAC;CAQH,OAAO;EACL,WAHA,oBAAoB,OAAO,UAAU,WAAW,QAAQ;EAIxD;EACA;EACA;EACA,UAAU;EACV;EACA;EACA,OAAO;GACL,GAAG;GACH,OAAO;GACP,UAAU;EACZ;EACA;EACA;EACA;EACA;EACA;EACA,OAAO;EACP;EACA,UAAU;EACV;EACA;EACA;EACA;CACF;AACF"}
+{"version":3,"file":"index.js","names":[],"sources":["../../../src/hooks/useUniformField/useUniformField.tsx","../../../src/hooks/useUniformField/index.ts"],"sourcesContent":["import type { ReactNode } from 'react';\nimport type { FieldError, FieldValues, Path } from 'react-hook-form';\nimport type { InputValueTransform } from '../useInputValueTransform/useInputValueTransform';\n\nimport React from 'react';\n\nimport { useDebounce } from '@fuf-stack/pixels';\n\nimport { isValueEmpty } from '../../helpers';\nimport { FieldCopyTestIdButton } from '../../partials/FieldCopyTestIdButton';\nimport { FieldValidationError } from '../../partials/FieldValidationError';\nimport { useController } from '../useController/useController';\nimport { useFormContext } from '../useFormContext/useFormContext';\nimport { useInput } from '../useInput/useInput';\nimport { useInputValueTransform } from '../useInputValueTransform/useInputValueTransform';\n\nexport interface UseUniformFieldParams<\n  TFieldValues extends FieldValues = FieldValues,\n  TDisplay = unknown,\n> {\n  /** Form field name */\n  name: Path<TFieldValues> & string;\n  /** Custom aria-label for accessibility. If not provided, falls back to field name when no visible label exists */\n  ariaLabel?: string;\n  /** Disable the field */\n  disabled?: boolean;\n  /** Optional label content */\n  label?: ReactNode;\n  /** Optional explicit test id used to build stable test ids */\n  testId?: string;\n  /** Optional value transformation between form and display values */\n  transform?: InputValueTransform<TDisplay>;\n  /** Input type for special number handling */\n  type?: 'text' | 'number' | 'password';\n}\n\nexport interface UseUniformFieldReturn<\n  TFieldValues extends FieldValues = FieldValues,\n> {\n  /** Computed aria-label fallback (field name) when no visible label exists. Components can override based on their accessibility needs (e.g., if placeholder provides sufficient context) */\n  ariaLabel: string | undefined;\n  /** react-hook-form control instance for advanced integrations */\n  control: ReturnType<typeof useFormContext<TFieldValues>>['control'];\n  /** Debug mode from Uniform provider */\n  debugMode: ReturnType<typeof useFormContext<TFieldValues>>['debugMode'];\n  /** Current value used to initialize uncontrolled components */\n  defaultValue: unknown;\n  /** Whether the field is currently disabled (from RHF) */\n  disabled: boolean | undefined;\n  /** Validation error(s) for the field */\n  error: FieldError[] | undefined;\n  /** Pre-built errorMessage node to plug into components */\n  errorMessage: ReactNode | null;\n  /** RHF controller field with transformed value/onChange (use this for simple components) */\n  field: ReturnType<typeof useController<TFieldValues>>['field'];\n  /** Helper to spread standardized error message props to underlying components */\n  getErrorMessageProps: ReturnType<typeof useInput>['getErrorMessageProps'];\n  /** Helper to spread standardized helper wrapper props (for spacing/animation) */\n  getHelperWrapperProps: ReturnType<typeof useInput>['getHelperWrapperProps'];\n  /** Helper to spread standardized label props to underlying components */\n  getLabelProps: ReturnType<typeof useInput>['getLabelProps'];\n  /** Access current form values (converted to validation-friendly format) */\n  getValues: ReturnType<typeof useFormContext<TFieldValues>>['getValues'];\n  /** Whether the field should show invalid state (debounced for smooth animations). True when field is invalid AND (dirty OR touched OR submitted) */\n  invalid: boolean;\n  /** Computed label node including optional test id copy button */\n  label: ReactNode | null;\n  /** onBlur handler from controller */\n  onBlur: ReturnType<typeof useController<TFieldValues>>['field']['onBlur'];\n  /** onChange handler from controller (with transform applied) */\n  onChange: ReturnType<typeof useController<TFieldValues>>['field']['onChange'];\n  /** Ref to forward to underlying control */\n  ref: ReturnType<typeof useController<TFieldValues>>['field']['ref'];\n  /** Whether the field is required according to validation schema */\n  required: boolean;\n  /** Reset a specific field in the form */\n  resetField: ReturnType<typeof useFormContext<TFieldValues>>['resetField'];\n  /** Generated HTML data-testid for the field */\n  testId: string;\n}\n\n/**\n * Combines frequently used form field logic into a single hook.\n *\n * Provides:\n * - Enhanced form context (validation-aware state, `testId`, value transforms)\n * - Controller field with nullish conversion handling\n * - Value transformation via `transform` prop:\n *   • Allows disentangled display and form values (e.g., string ↔ object, boolean ↔ array)\n *   • Automatically applies `toDisplayValue` to field value for components\n *   • Automatically applies `toFormValue` to display value when onChange is called\n *   • Works with `type` prop for automatic number/string conversion\n *   • Examples: storing objects while displaying strings, storing booleans as arrays, enriching values with metadata\n * - Debounced `invalid` state with smart timing:\n *   • `true` (field becomes invalid): applies immediately so errors show right away\n *   • `false` (field becomes valid): delayed 200ms to allow smooth exit animations\n *   • Respects `prefers-reduced-motion` by skipping delays when user prefers reduced motion\n * - Smart `invalid` visibility (via `showInvalid`):\n *   • Shows errors when field is dirty OR touched OR form has been submitted\n *   • Prevents showing errors on pristine/untouched fields for better UX\n *   • Works well for all field types (text inputs, checkboxes, radios, arrays)\n * - Prebuilt `errorMessage` React node using `FieldValidationError`\n * - Computed `label` node which appends a `FieldCopyTestIdButton` in\n *   `debug-testids` mode\n * - `defaultValue` for uncontrolled defaults and all usual field handlers\n * - Access to form utilities: `control`, `getValues`, `resetField`\n * - Presentation helpers: `getLabelProps`, `getErrorMessageProps`,\n *   `getHelperWrapperProps` for consistent wiring to underlying UI components\n */\nexport const useUniformField = <\n  TFieldValues extends FieldValues = FieldValues,\n  TDisplay = unknown,\n>(\n  params: UseUniformFieldParams<TFieldValues, TDisplay>,\n): UseUniformFieldReturn<TFieldValues> => {\n  const {\n    name,\n    ariaLabel: customAriaLabel,\n    disabled = false,\n    testId: explicitTestId,\n    label,\n    type,\n    transform,\n  } = params;\n\n  const {\n    control,\n    debugMode,\n    formState: { submitCount },\n    getFieldState,\n    getValues,\n    resetField,\n  } = useFormContext<TFieldValues>();\n\n  const {\n    error,\n    invalid: rawInvalid,\n    isDirty,\n    isTouched,\n    required,\n    testId,\n  } = getFieldState(name, explicitTestId);\n\n  const { field } = useController<TFieldValues>({\n    control,\n    disabled,\n    name,\n  });\n  const {\n    onChange: fieldOnChange,\n    value: fieldValue,\n    disabled: isDisabled,\n    onBlur,\n    ref,\n  } = field;\n\n  // Get transform utilities (but don't apply them automatically)\n  // Components can choose how to use them (directly or via useInputValueDebounce)\n  const { toDisplayValue, toFormValue } = useInputValueTransform<TDisplay>({\n    type,\n    transform,\n  });\n\n  // For components without special needs: apply transform to value and onChange\n  const transformedValue = toDisplayValue(fieldValue);\n  const transformedOnChange = (eventOrValue: TDisplay | React.ChangeEvent) => {\n    // Extract value from event or use value directly\n    const displayValue =\n      (eventOrValue as React.ChangeEvent<HTMLInputElement>)?.target?.value ??\n      eventOrValue;\n    const formValue = toFormValue(displayValue as TDisplay);\n    fieldOnChange(formValue);\n  };\n\n  const defaultValue = (getValues() as Record<string, unknown>)?.[\n    name as string\n  ];\n\n  /**\n   * Determine when to show the invalid state to the user.\n   *\n   * Show errors when the field is invalid AND any of these conditions are met:\n   *   - Field has a user-entered value (show validation errors like format/length while typing)\n   *   - Field is touched (focused and blurred) - good for text inputs\n   *   - Form has been submitted - shows all errors after submit attempt\n   *\n   * Note: `hasValue` is gated by `isDirty` so invalid initial values do not\n   * show errors just because resolver-backed validation state is available.\n   * Newly added empty array elements can be dirty, but stay hidden until blur\n   * because they do not have a value yet.\n   *\n   * This prevents showing errors on pristine/untouched/empty fields for better UX.\n   * Examples:\n   *   - Text input: User loads form with empty required field → no error shown yet\n   *   - Text input: User types invalid content → error shows immediately (has value)\n   *   - Text input: User focuses and blurs without typing → error shows (via isTouched)\n   *   - Checkbox/radio: User selects option → error shows immediately (has value)\n   *   - Field array: User adds element → no error yet; after blur → error shows\n   *   - Any field: User submits form → all errors show (via submitCount)\n   *\n   * The entire condition is debounced to prevent flickering and allow smooth animations.\n   */\n\n  // isValueEmpty handles marker strings, flat array wrappers, empty arrays, and empty objects\n  const hasValue = !isValueEmpty(fieldValue);\n  const showInvalid =\n    rawInvalid && ((isDirty && hasValue) || isTouched || submitCount > 0);\n  // Debounce to prevent flickering during rapid state changes\n  const invalid = useDebounce(showInvalid, 200);\n\n  // Build a label node that:\n  // - shows the provided label (unless explicitly set to false)\n  // - appends a copy-to-clipboard button for the test id in `debug-testids` mode\n  // Consumers can pass this directly to component `label` props\n  const showTestIdCopyButton = debugMode === 'debug-testids';\n  const labelNode: ReactNode | null =\n    !!label || showTestIdCopyButton ? (\n      <>\n        {label !== false ? label : null}\n        {showTestIdCopyButton ? (\n          <FieldCopyTestIdButton testId={testId} />\n        ) : null}\n      </>\n    ) : null;\n\n  // Ready-to-render error message; consumers can drop this into their\n  // component `errorMessage` prop without repeating mapping/markup\n  const errorMessage = <FieldValidationError error={error} testId={testId} />;\n\n  // Generate standardized props for label, helper wrapper and error message\n  // so consumers can spread them directly into UI components (e.g. HeroUI),\n  // keeping animations/spacing consistent across fields\n  const { getErrorMessageProps, getLabelProps, getHelperWrapperProps } =\n    useInput({\n      ref,\n      classNames: {\n        // set padding to 0 for error message exit animation\n        helperWrapper: 'p-0',\n      },\n      errorMessage: JSON.stringify(error),\n      isInvalid: invalid,\n      isRequired: required,\n      label,\n      labelPlacement: 'outside',\n    });\n\n  // Compute aria-label: prefer custom prop, then use string label if available, otherwise field name\n  // Components can further override this based on their specific accessibility needs\n  // (e.g., Input/TextArea may skip this if they have a meaningful placeholder)\n  const ariaLabel =\n    customAriaLabel ?? (typeof label === 'string' ? label : name);\n\n  return {\n    ariaLabel,\n    control,\n    debugMode,\n    defaultValue,\n    disabled: isDisabled,\n    error,\n    errorMessage,\n    field: {\n      ...field,\n      value: transformedValue as typeof field.value,\n      onChange: transformedOnChange as typeof field.onChange,\n    },\n    getErrorMessageProps,\n    getHelperWrapperProps,\n    getLabelProps,\n    getValues,\n    invalid,\n    label: labelNode,\n    onBlur,\n    onChange: transformedOnChange as typeof field.onChange,\n    ref,\n    required,\n    resetField,\n    testId,\n  };\n};\n","/* v8 ignore start */\n\nexport * from './useUniformField';\n\n/* v8 ignore stop */\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6GA,MAAa,mBAIX,WACwC;CACxC,MAAM,EACJ,MACA,WAAW,iBACX,WAAW,OACX,QAAQ,gBACR,OACA,MACA,cACE;CAEJ,MAAM,EACJ,SACA,WACA,WAAW,EAAE,eACb,eACA,WACA,eACE,eAA6B;CAEjC,MAAM,EACJ,OACA,SAAS,YACT,SACA,WACA,UACA,WACE,cAAc,MAAM,cAAc;CAEtC,MAAM,EAAE,UAAU,cAA4B;EAC5C;EACA;EACA;CACF,CAAC;CACD,MAAM,EACJ,UAAU,eACV,OAAO,YACP,UAAU,YACV,QACA,QACE;CAIJ,MAAM,EAAE,gBAAgB,gBAAgB,uBAAiC;EACvE;EACA;CACF,CAAC;CAGD,MAAM,mBAAmB,eAAe,UAAU;CAClD,MAAM,uBAAuB,iBAA+C;EAM1E,cADkB,YAFf,cAAsD,QAAQ,SAC/D,YAEoB,CAAC;CACzB;CAEA,MAAM,eAAgB,UAAU,IAC9B;;;;;;;;;;;;;;;;;;;;;;;;;CA6BF,MAAM,WAAW,CAAC,aAAa,UAAU;CAIzC,MAAM,UAAU,YAFd,eAAgB,WAAW,YAAa,aAAa,cAAc,IAE5B,GAAG;CAM5C,MAAM,uBAAuB,cAAc;CAC3C,MAAM,YACJ,CAAC,CAAC,SAAS,uBACT,qBAAA,UAAA,EAAA,UAAA,CACG,UAAU,QAAQ,QAAQ,MAC1B,uBACC,oBAAC,uBAAD,EAA+B,OAAS,CAAA,IACtC,IACJ,EAAA,CAAA,IACA;CAIN,MAAM,eAAe,oBAAC,sBAAD;EAA6B;EAAe;CAAS,CAAA;CAK1E,MAAM,EAAE,sBAAsB,eAAe,0BAC3C,SAAS;EACP;EACA,YAAY,EAEV,eAAe,MACjB;EACA,cAAc,KAAK,UAAU,KAAK;EAClC,WAAW;EACX,YAAY;EACZ;EACA,gBAAgB;CAClB,CAAC;CAQH,OAAO;EACL,WAHA,oBAAoB,OAAO,UAAU,WAAW,QAAQ;EAIxD;EACA;EACA;EACA,UAAU;EACV;EACA;EACA,OAAO;GACL,GAAG;GACH,OAAO;GACP,UAAU;EACZ;EACA;EACA;EACA;EACA;EACA;EACA,OAAO;EACP;EACA,UAAU;EACV;EACA;EACA;EACA;CACF;AACF"}

package/dist/hooks/useUniformFieldArray/index.cjs

@@ -1,7 +1,7 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-require("../../FormContext-Djp8wTG8.cjs");
+require("../../FormContext-CjDd8Zej.cjs");
 const require_helpers_index = require("../../helpers/index.cjs");
-const require_useFormContext = require("../../useFormContext-CNGE9heQ.cjs");
+const require_useFormContext = require("../../useFormContext-C_EQr8dV.cjs");
 const require_hooks_useUniformField_index = require("../useUniformField/index.cjs");
 let react = require("react");
 let _fuf_stack_pixel_motion = require("@fuf-stack/pixel-motion");

package/dist/hooks/useUniformFieldArray/index.d.cts

@@ -1,2 +1,2 @@
-import { n as useUniformFieldArray, t as UseUniformFieldArrayProps } from "../../useUniformFieldArray-KClEBFyP.cjs";
+import { n as useUniformFieldArray, t as UseUniformFieldArrayProps } from "../../useUniformFieldArray-RvOYml8h.cjs";
 export { UseUniformFieldArrayProps, useUniformFieldArray };

package/dist/hooks/useUniformFieldArray/index.d.ts

@@ -1,2 +1,2 @@
-import { n as useUniformFieldArray, t as UseUniformFieldArrayProps } from "../../useUniformFieldArray-eDkxErv8.js";
+import { n as useUniformFieldArray, t as UseUniformFieldArrayProps } from "../../useUniformFieldArray-C0U3eBr7.js";
 export { UseUniformFieldArrayProps, useUniformFieldArray };

package/dist/hooks/useUniformFieldArray/index.js

@@ -1,5 +1,5 @@
 import { flatArrayKey } from "../../helpers/index.js";
-import { n as useFormContext$1 } from "../../useFormContext-2vyVWpUJ.js";
+import { n as useFormContext$1 } from "../../useFormContext-DJ-9hs8X.js";
 import { useUniformField } from "../useUniformField/index.js";
 import { useEffect, useMemo, useRef, useState } from "react";
 import { useReducedMotion } from "@fuf-stack/pixel-motion";