@fuf-stack/uniform 1.22.7 → 1.22.9

package/dist/hooks/useUniformField/index.js

@@ -1,4 +1,4 @@
-import { isValueEmpty } from "../../helpers/index.js";
+import { flattenFieldErrors, isValueEmpty } from "../../helpers/index.js";
 import { t as FieldCopyTestIdButton_default } from "../../FieldCopyTestIdButton-CRJBix9D.js";
 import { t as FieldValidationError_default } from "../../FieldValidationError-ByRoIxaM.js";
 import { t as useController } from "../../useController-DxFS0u7c.js";
@@ -29,7 +29,7 @@ import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 *   • Shows errors when field is dirty OR touched OR form has been submitted
 *   • Prevents showing errors on pristine/untouched fields for better UX
 *   • Works well for all field types (text inputs, checkboxes, radios, arrays)
-* - Prebuilt `errorMessage` React node using `FieldValidationError`
+* - Prebuilt `errorMessage` React node (with optional array-error normalization via `isArrayValue`)
 * - Computed `label` node which appends a `FieldCopyTestIdButton` in
 *   `debug-testids` mode
 * - `defaultValue` for uncontrolled defaults and all usual field handlers
@@ -38,9 +38,9 @@ import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 *   `getHelperWrapperProps` for consistent wiring to underlying UI components
 */
 const useUniformField = (params) => {
-	const { name, ariaLabel: customAriaLabel, disabled = false, testId: explicitTestId, label, type, transform } = params;
+	const { name, ariaLabel: customAriaLabel, disabled = false, isArrayValue = false, testId: explicitTestId, label, type, transform } = params;
 	const { control, debugMode, formState: { submitCount }, getFieldState, getValues, resetField } = useFormContext();
-	const { error, invalid: rawInvalid, isDirty, isTouched, required, testId } = getFieldState(name, explicitTestId);
+	const { error: rawError, invalid: rawInvalid, isDirty, isTouched, required, testId } = getFieldState(name, explicitTestId);
 	const { field } = useController({
 		control,
 		disabled,
@@ -84,8 +84,9 @@ const useUniformField = (params) => {
 	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_default, { testId }) : null] }) : null;
+	const error = isArrayValue ? flattenFieldErrors(rawError) : rawError;
 	const errorMessage = /* @__PURE__ */ jsx(FieldValidationError_default, {
-		error,
+		error: flattenFieldErrors(rawError),
 		testId
 	});
 	const { getErrorMessageProps, getLabelProps, getHelperWrapperProps } = useInput({

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

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":["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,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,oBAACA,+BAAD,EAA+B,OAAS,CAAA,IACtC,IACJ,EAAA,CAAA,IACA;CAIN,MAAM,eAAe,oBAACC,8BAAD;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":["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 { flattenFieldErrors, 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  /** Normalize nested RHF errors into a flat array for array-like fields */\n  isArrayValue?: 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 errors from form state; flattened only when `isArrayValue` is enabled */\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 (with optional array-error normalization via `isArrayValue`)\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    isArrayValue = 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: rawError,\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  // Array-like fields can receive nested RHF error objects (index keys, _errors).\n  // Opt-in flattening keeps backward compatibility for components that rely on\n  // object-shaped errors (e.g. FieldCard/FieldArray).\n  const error = isArrayValue ? flattenFieldErrors(rawError) : rawError;\n  const normalizedError = flattenFieldErrors(rawError);\n\n  // Ready-to-render error message; consumers can drop this into their\n  // component `errorMessage` prop without repeating mapping/markup\n  const errorMessage = (\n    <FieldValidationError error={normalizedError} testId={testId} />\n  );\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":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA+GA,MAAa,mBAIX,WACwC;CACxC,MAAM,EACJ,MACA,WAAW,iBACX,WAAW,OACX,eAAe,OACf,QAAQ,gBACR,OACA,MACA,cACE;CAEJ,MAAM,EACJ,SACA,WACA,WAAW,EAAE,eACb,eACA,WACA,eACE,eAA6B;CAEjC,MAAM,EACJ,OAAO,UACP,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,oBAACA,+BAAD,EAA+B,OAAS,CAAA,IACtC,IACJ,EAAA,CAAA,IACA;CAKN,MAAM,QAAQ,eAAe,mBAAmB,QAAQ,IAAI;CAK5D,MAAM,eACJ,oBAACC,8BAAD;EAAsB,OALA,mBAAmB,QAKE;EAAW;CAAS,CAAA;CAMjE,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.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.cts","names":[],"sources":["../../../src/hooks/useUniformFieldArray/useUniformFieldArray.ts"],"mappings":";;;;;;UAaiB,yBAAA,sBACM,WAAA,GAAc,WAAA;;EAGnC,IAAA,EAAM,SAAA,CAAU,YAAA;;EAEhB,IAAA;EANe;EAQf,mBAAA;EARwC;EAUxC,uBAAA;EATmC;EAWnC,QAAA;EARM;EAUN,MAAA;EAEiB;EAAjB,KAAA,GAAQ,SAAA;AAAA;;;;;;;;;;;;;;AAAS;cAiBN,oBAAA,wBACU,WAAA,GAAc,WAAA;EACnC,IAAA;EAAA,IAAA;EAAA,mBAAA,EAAA,oBAAA;EAAA,uBAAA;EAAA,QAAA;EAAA,MAAA,EAAA,cAAA;EAAA;AAAA,GAQC,yBAAA,CAA0B,YAAA;;;;;;;;;kBAnCR,KAAA;;;;;;;;;UAoEZ,UAAA;YAEuB,UAAA,QAFvB,aAAA;OAK4B,UAAA,QAHL,aAAA"}
+{"version":3,"file":"index.d.cts","names":[],"sources":["../../../src/hooks/useUniformFieldArray/useUniformFieldArray.ts"],"mappings":";;;;;;UAaiB,yBAAA,sBACM,WAAA,GAAc,WAAA;;EAGnC,IAAA,EAAM,SAAA,CAAU,YAAA;;EAEhB,IAAA;EANe;EAQf,mBAAA;EARwC;EAUxC,uBAAA;EATmC;EAWnC,QAAA;EARM;EAUN,MAAA;EAEiB;EAAjB,KAAA,GAAQ,SAAA;AAAA;;;;;;;;;;;;;;AAAS;cAiBN,oBAAA,wBACU,WAAA,GAAc,WAAA;EACnC,IAAA;EAAA,IAAA;EAAA,mBAAA,EAAA,oBAAA;EAAA,uBAAA;EAAA,QAAA;EAAA,MAAA,EAAA,cAAA;EAAA;AAAA,GAQC,yBAAA,CAA0B,YAAA;;;;;;;;;kBAnCR,KAAA;;;;;;;;;UAsEmC,UAAA;YAIxC,UAAA,QAJwC,aAAA;OAKL,UAAA,QADnC,aAAA"}

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":[],"sources":["../../../src/hooks/useUniformFieldArray/useUniformFieldArray.ts"],"mappings":";;;;;;UAaiB,yBAAA,sBACM,WAAA,GAAc,WAAA;;EAGnC,IAAA,EAAM,SAAA,CAAU,YAAA;;EAEhB,IAAA;EANe;EAQf,mBAAA;EARwC;EAUxC,uBAAA;EATmC;EAWnC,QAAA;EARM;EAUN,MAAA;EAEiB;EAAjB,KAAA,GAAQ,SAAA;AAAA;;;;;;;;;;;;;;AAAS;cAiBN,oBAAA,wBACU,WAAA,GAAc,WAAA;EACnC,IAAA;EAAA,IAAA;EAAA,mBAAA,EAAA,oBAAA;EAAA,uBAAA;EAAA,QAAA;EAAA,MAAA,EAAA,cAAA;EAAA;AAAA,GAQC,yBAAA,CAA0B,YAAA;;;;;;;;;kBAnCR,KAAA;;;;;;;;;UAoEZ,UAAA;YAEuB,UAAA,QAFvB,eAAA;OAK4B,UAAA,QAHL,eAAA"}
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../../src/hooks/useUniformFieldArray/useUniformFieldArray.ts"],"mappings":";;;;;;UAaiB,yBAAA,sBACM,WAAA,GAAc,WAAA;;EAGnC,IAAA,EAAM,SAAA,CAAU,YAAA;;EAEhB,IAAA;EANe;EAQf,mBAAA;EARwC;EAUxC,uBAAA;EATmC;EAWnC,QAAA;EARM;EAUN,MAAA;EAEiB;EAAjB,KAAA,GAAQ,SAAA;AAAA;;;;;;;;;;;;;;AAAS;cAiBN,oBAAA,wBACU,WAAA,GAAc,WAAA;EACnC,IAAA;EAAA,IAAA;EAAA,mBAAA,EAAA,oBAAA;EAAA,uBAAA;EAAA,QAAA;EAAA,MAAA,EAAA,cAAA;EAAA;AAAA,GAQC,yBAAA,CAA0B,YAAA;;;;;;;;;kBAnCR,KAAA;;;;;;;;;UAsEmC,UAAA;YAIxC,UAAA,QAJwC,eAAA;OAKL,UAAA,QADnC,eAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fuf-stack/uniform",
-  "version": "1.22.7",
+  "version": "1.22.9",
   "description": "fuf react form library",
   "author": "Fröhlich ∧ Frei",
   "homepage": "https://github.com/fuf-stack/pixels#readme",
@@ -174,8 +174,8 @@
     "@heroui/switch": "2.2.27",
     "@heroui/system": "2.4.28",
     "@heroui/theme": "2.4.26",
-    "@internationalized/date": "3.12.1",
-    "@react-aria/visually-hidden": "3.9.0",
+    "@internationalized/date": "3.12.2",
+    "@react-aria/visually-hidden": "3.9.1",
     "debug": "4.4.3",
     "framer-motion": "12.40.0",
     "react-hook-form": "7.76.1",
@@ -189,5 +189,5 @@
     "react": "19.2.6",
     "react-dom": "19.2.6"
   },
-  "gitHead": "87fd30d29958345d893297d200c3716592e80b2e"
+  "gitHead": "407bdec37c7fee39ceac95a33e62c1b5741ea598"
 }