@fuf-stack/uniform 1.6.0 → 1.6.2

package/dist/hooks/index.d.ts

@@ -1,290 +1,13 @@
-import * as _fuf_stack_veto_dist_types_d_CNPgNK_V from '@fuf-stack/veto/dist/types.d-CNPgNK-V';
-import * as _fuf_stack_veto from '@fuf-stack/veto';
-import { VetoTypeAny, VetoInstance, VetoFormattedError } from '@fuf-stack/veto';
-import * as react_hook_form from 'react-hook-form';
-import { UseControllerProps as UseControllerProps$1, ControllerRenderProps, UseFormStateReturn, ControllerFieldState, FieldValues, Path, FieldError, ArrayPath } from 'react-hook-form';
-import * as _heroui_input from '@heroui/input';
-import { useInput } from '@heroui/input';
+export { clientValidationSchemaByName, useClientValidation } from './useClientValidation/index.js';
+export { UseControllerProps, UseControllerReturn, useController } from './useController/index.js';
+export { UseUniformFieldArrayProps, useUniformFieldArray } from './useUniformFieldArray/index.js';
+export { checkFieldIsRequired, useFormContext } from './useFormContext/index.js';
 export { useInput } from '@heroui/input';
-import * as React from 'react';
-import { ReactNode } from 'react';
-import { D as DebugModeSettings } from '../FormContext-LRho0tno.js';
 export { UseInputValueDebounceOptions, UseInputValueDebounceReturn, useInputValueDebounce } from './useInputValueDebounce/index.js';
 export { InputValueTransform, UseInputValueTransformOptions, UseInputValueTransformReturn, useInputValueTransform } from './useInputValueTransform/index.js';
-
-/**
- * Hook for adding dynamic client-side validation to forms.
- *
- * Automatically manages validation schema lifecycle: sets schema when data is provided,
- * clears schema when data is null/undefined, and cleans up on unmount.
- *
- * When the client validation schema changes, automatically re-validates all touched
- * fields to ensure they are validated against the new schema.
- *
- * @param data - Data to create validation schema from (or null/undefined to clear validation)
- * @param schemaFactory - Function that creates a validation schema from the data.
- *
- * @example
- * ```tsx
- * const { data: teamData } = useTeamQuery(teamId);
- *
- * useClientValidation(teamData, (data) =>
- *   vt.object({
- *     username: vt.string().refine(
- *       (value) => !data.existingUsers.includes(value),
- *       { message: 'Username already exists' }
- *     )
- *   })
- * );
- * ```
- */
-declare const useClientValidation: <TData = unknown>(data: TData | null | undefined, schemaFactory: (data: TData) => VetoTypeAny) => void;
-/**
- * Helper function to create a veto looseObject schema for a single field with nested path support.
- *
- * Parses field paths (dot-notation) and creates properly nested loose object schemas with array support.
- * All intermediate objects and arrays are marked as optional to allow partial data structures.
- * Numeric segments in the path are treated as array indices, and the parent field is wrapped in an array schema.
- *
- * @param name - The dot-separated path to the field (e.g., 'username', 'user.profile.email', 'items.0.name')
- * @param fieldSchema - The veto validation schema for the field
- * @returns A nested loose object schema matching the field path structure with proper type inference
- *
- * @example
- * ```tsx
- * // Simple field
- * clientValidationSchemaByName('username', vt.string())
- * // => objectLoose({ username: vt.string() })
- * ```
- *
- * @example
- * ```tsx
- * // Nested field (with optional intermediate objects)
- * clientValidationSchemaByName('user.profile.email', vt.string().email())
- * // => objectLoose({ user: objectLoose({ profile: objectLoose({ email: vt.string().email() }).optional() }).optional() })
- * ```
- *
- * @example
- * ```tsx
- * // Array field (with optional array)
- * clientValidationSchemaByName('items.0.name', vt.string())
- * // => objectLoose({ items: array(objectLoose({ name: vt.string() })).optional() })
- * ```
- *
- * @example
- * ```tsx
- * // Usage with useClientValidation
- * const { data: userData } = useUserQuery(userId);
- *
- * useClientValidation(userData, (data) =>
- *   clientValidationSchemaByName('username', vt.string().refine(
- *     (value) => !data.existingUsernames.includes(value),
- *     { message: 'Username already taken' }
- *   ))
- * );
- * ```
- */
-declare const clientValidationSchemaByName: <T extends VetoTypeAny>(name: string, fieldSchema: T) => _fuf_stack_veto_dist_types_d_CNPgNK_V.Z;
-
-type UseControllerProps<TFieldValues extends object = object> = UseControllerProps$1<TFieldValues>;
-interface UseControllerReturn<TFieldValues extends object = object> {
-    field: Omit<ControllerRenderProps<TFieldValues>, 'onChange' | 'value'> & {
-        onChange: (...event: any[]) => void;
-        value: string;
-    };
-    formState: UseFormStateReturn<TFieldValues>;
-    fieldState: ControllerFieldState;
-}
-/**
- * A wrapper around react-hook-form's useController that transparently handles nullish string conversions.
- *
- * Key features:
- * 1. Empty strings ('') in the UI are stored as null in form state
- * 2. Null/undefined values in form state are displayed as empty strings in the UI
- * 3. Handles both direct value changes and React synthetic events
- * 4. Maintains the same API as react-hook-form's useController
- *
- * This enables consistent handling of empty/null values while keeping a clean API
- * for form inputs that expect string values.
- *
- * @see https://react-hook-form.com/docs/usecontroller
- */
-declare const useController: <TFieldValues extends object = object>(props: UseControllerProps<TFieldValues>) => UseControllerReturn<TFieldValues>;
-
-/** Schema check whether a field is required or optional */
-declare const checkFieldIsRequired: (validation: VetoInstance, path: string[]) => boolean;
-/**
- * Custom hook that extends react-hook-form's useFormContext to add validation and state management.
- */
-declare const useFormContext: <TFieldValues extends FieldValues = FieldValues, TContext = any, TTransformedValues = TFieldValues>() => {
-    formState: react_hook_form.FormState<TFieldValues>;
-    getFieldState: (name: Path<TFieldValues>, testId?: string) => {
-        error: FieldError[] | undefined;
-        invalid: boolean;
-        required: boolean;
-        testId: string;
-        isDirty: boolean;
-        isTouched: boolean;
-        isValidating: boolean;
-    };
-    getValues: react_hook_form.UseFormGetValues<TFieldValues>;
-    subscribe: react_hook_form.UseFromSubscribe<TFieldValues>;
-    watch: react_hook_form.UseFormWatch<TFieldValues>;
-    debugMode: "debug" | "debug-testids" | "off" | "disabled";
-    debugModeSettings?: DebugModeSettings;
-    preventSubmit: (prevent: boolean) => void;
-    setDebugMode: (debugMode: "debug" | "debug-testids" | "off" | "disabled") => void;
-    triggerSubmit: (e?: React.BaseSyntheticEvent) => Promise<void> | void;
-    validation: {
-        instance?: VetoInstance;
-        errors?: VetoFormattedError;
-        setClientValidationSchema: (key: string, schema: _fuf_stack_veto.VetoTypeAny | null) => void;
-    };
-    setError: react_hook_form.UseFormSetError<TFieldValues>;
-    clearErrors: react_hook_form.UseFormClearErrors<TFieldValues>;
-    setValue: react_hook_form.UseFormSetValue<TFieldValues>;
-    trigger: react_hook_form.UseFormTrigger<TFieldValues>;
-    resetField: react_hook_form.UseFormResetField<TFieldValues>;
-    reset: react_hook_form.UseFormReset<TFieldValues>;
-    handleSubmit: react_hook_form.UseFormHandleSubmit<TFieldValues, TTransformedValues>;
-    unregister: react_hook_form.UseFormUnregister<TFieldValues>;
-    control: react_hook_form.Control<TFieldValues, TContext, TTransformedValues>;
-    register: react_hook_form.UseFormRegister<TFieldValues>;
-    setFocus: react_hook_form.UseFormSetFocus<TFieldValues>;
-};
-
-interface UseUniformFieldArrayProps<TFieldValues extends FieldValues = FieldValues> {
-    /** Field name for the array */
-    name: ArrayPath<TFieldValues>;
-    /** Whether this is a flat array (array of primitives) */
-    flat?: boolean;
-    /** Initial value for new array elements */
-    elementInitialValue?: unknown;
-    /** Whether the last element cannot be removed (always maintain at least one element) */
-    lastElementNotRemovable?: boolean;
-    /** Disable the field */
-    disabled?: boolean;
-    /** Optional explicit test id used to build stable test ids */
-    testId?: string;
-    /** Optional label content; pass false to suppress label entirely */
-    label?: ReactNode | false;
-}
-/**
- * Enhanced useFieldArray hook with initialization and animation logic.
- * Based on React Hook Form's useFieldArray with additional features:
- * - Automatic initialization when lastElementNotRemovable is set
- * - Animation control (disabled during initialization)
- * - Support for flat arrays (arrays of primitives)
- *
- * Note: Automatic validation triggering on length change is disabled to prevent
- * triggering form-wide validation. Array validation still runs on form submission.
- *
- * @see https://react-hook-form.com/docs/usefieldarray
- */
-declare const useUniformFieldArray: <TFieldValues extends FieldValues = FieldValues>({ name, flat, elementInitialValue: _elementInitialValue, lastElementNotRemovable, disabled, testId: explicitTestId, label, }: UseUniformFieldArrayProps<TFieldValues>) => {
-    control: react_hook_form.Control<TFieldValues, any, TFieldValues>;
-    debugMode: ReturnType<typeof useFormContext<TFieldValues_1>>["debugMode"];
-    defaultValue: unknown;
-    disabled: boolean | undefined;
-    error: react_hook_form.FieldError[] | undefined;
-    errorMessage: ReactNode | null;
-    field: Omit<react_hook_form.ControllerRenderProps<TFieldValues>, "value" | "onChange"> & {
-        onChange: (... /** Initial value for new array elements */event: any[]) => void;
-        value: string;
-    };
-    getErrorMessageProps: ReturnType<typeof _heroui_input.useInput>["getErrorMessageProps"];
-    getHelperWrapperProps: ReturnType<typeof _heroui_input.useInput>["getHelperWrapperProps"];
-    getLabelProps: ReturnType<typeof _heroui_input.useInput>["getLabelProps"];
-    getValues: react_hook_form.UseFormGetValues<TFieldValues>;
-    invalid: boolean;
-    label: ReactNode | null;
-    onBlur: ReturnType<typeof useController>["field"]["onBlur"];
-    onChange: ReturnType<typeof useController>["field"]["onChange"];
-    ref: ReturnType<typeof useController>["field"]["ref"];
-    required: boolean;
-    resetField: react_hook_form.UseFormResetField<TFieldValues>;
-    testId: string;
-    fields: react_hook_form.FieldArrayWithId<TFieldValues, ArrayPath<TFieldValues>, "id">[];
-    append: react_hook_form.UseFieldArrayAppend<TFieldValues, ArrayPath<TFieldValues>>;
-    remove: react_hook_form.UseFieldArrayRemove;
-    insert: react_hook_form.UseFieldArrayInsert<TFieldValues, ArrayPath<TFieldValues>>;
-    move: react_hook_form.UseFieldArrayMove;
-    disableAnimation: boolean;
-    elementInitialValue: {};
-};
-
-interface UseUniformFieldParams<TFieldValues extends FieldValues = FieldValues> {
-    /** Form field name */
-    name: Path<TFieldValues> & string;
-    /** Disable the field */
-    disabled?: boolean;
-    /** Optional explicit test id used to build stable test ids */
-    testId?: string;
-    /** Optional label content; pass false to suppress label entirely */
-    label?: ReactNode | false;
-}
-interface UseUniformFieldReturn<TFieldValues extends FieldValues = FieldValues> {
-    /** react-hook-form control instance for advanced integrations */
-    control: ReturnType<typeof useFormContext<TFieldValues>>['control'];
-    /** Debug mode from Uniform provider */
-    debugMode: ReturnType<typeof useFormContext<TFieldValues>>['debugMode'];
-    /** Current value used to initialize uncontrolled components */
-    defaultValue: unknown;
-    /** Whether the field is currently disabled (from RHF) */
-    disabled: boolean | undefined;
-    /** Validation error(s) for the field */
-    error: FieldError[] | undefined;
-    /** Pre-built errorMessage node to plug into components */
-    errorMessage: ReactNode | null;
-    /** RHF controller field with nullish conversions applied */
-    field: ReturnType<typeof useController<TFieldValues>>['field'];
-    /** Helper to spread standardized error message props to underlying components */
-    getErrorMessageProps: ReturnType<typeof useInput>['getErrorMessageProps'];
-    /** Helper to spread standardized helper wrapper props (for spacing/animation) */
-    getHelperWrapperProps: ReturnType<typeof useInput>['getHelperWrapperProps'];
-    /** Helper to spread standardized label props to underlying components */
-    getLabelProps: ReturnType<typeof useInput>['getLabelProps'];
-    /** Access current form values (converted to validation-friendly format) */
-    getValues: ReturnType<typeof useFormContext<TFieldValues>>['getValues'];
-    /** Whether the field should show invalid state (debounced for smooth animations). True when field is invalid AND (dirty OR touched OR submitted) */
-    invalid: boolean;
-    /** Computed label node including optional test id copy button */
-    label: ReactNode | null;
-    /** onBlur handler from controller */
-    onBlur: ReturnType<typeof useController<TFieldValues>>['field']['onBlur'];
-    /** onChange handler from controller (with nullish handling) */
-    onChange: ReturnType<typeof useController<TFieldValues>>['field']['onChange'];
-    /** Ref to forward to underlying control */
-    ref: ReturnType<typeof useController<TFieldValues>>['field']['ref'];
-    /** Whether the field is required according to validation schema */
-    required: boolean;
-    /** Reset a specific field in the form */
-    resetField: ReturnType<typeof useFormContext<TFieldValues>>['resetField'];
-    /** Generated HTML data-testid for the field */
-    testId: string;
-}
-/**
- * Combines frequently used form field logic into a single hook.
- *
- * Provides:
- * - Enhanced form context (validation-aware state, `testId`, value transforms)
- * - Controller field with nullish conversion handling
- * - Debounced `invalid` state with smart timing:
- *   • `true` (field becomes invalid): applies immediately so errors show right away
- *   • `false` (field becomes valid): delayed 200ms to allow smooth exit animations
- *   • Respects `prefers-reduced-motion` by skipping delays when user prefers reduced motion
- * - Smart `invalid` visibility (via `showInvalid`):
- *   • 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`
- * - Computed `label` node which appends a `FieldCopyTestIdButton` in
- *   `debug-testids` mode
- * - `defaultValue` for uncontrolled defaults and all usual field handlers
- * - Access to form utilities: `control`, `getValues`, `resetField`
- * - Presentation helpers: `getLabelProps`, `getErrorMessageProps`,
- *   `getHelperWrapperProps` for consistent wiring to underlying UI components
- */
-declare function useUniformField<TFieldValues extends FieldValues = FieldValues>(params: UseUniformFieldParams<TFieldValues>): UseUniformFieldReturn<TFieldValues>;
-
-export { type UseControllerProps, type UseControllerReturn, type UseUniformFieldArrayProps, type UseUniformFieldParams, type UseUniformFieldReturn, checkFieldIsRequired, clientValidationSchemaByName, useClientValidation, useController, useFormContext, useUniformField, useUniformFieldArray };
+export { UseUniformFieldParams, UseUniformFieldReturn, useUniformField } from './useUniformField/index.js';
+import '@fuf-stack/veto/dist/types.d-Dzd6j9xO';
+import '@fuf-stack/veto';
+import 'react-hook-form';
+import 'react';
+import '../FormContext-LRho0tno.js';

package/dist/hooks/index.js

@@ -1,22 +1,33 @@
-import {
-  checkFieldIsRequired,
-  clientValidationSchemaByName,
-  useClientValidation,
-  useController,
-  useFormContext,
-  useInput,
-  useUniformField,
-  useUniformFieldArray
-} from "../chunk-2K6FWC4H.js";
-import "../chunk-NTDKZW4E.js";
-import "../chunk-ELYGQTXB.js";
-import "../chunk-76KOVUDN.js";
+import "../chunk-35V726MB.js";
 import {
   useInputValueDebounce
 } from "../chunk-MODD3TFE.js";
 import {
   useInputValueTransform
 } from "../chunk-7KLFK2IT.js";
+import {
+  useUniformFieldArray
+} from "../chunk-Z7FVILDT.js";
+import {
+  useUniformField
+} from "../chunk-D3NAUOYG.js";
+import "../chunk-ELYGQTXB.js";
+import {
+  useController
+} from "../chunk-CK362NWK.js";
+import {
+  useInput
+} from "../chunk-AHJJIANM.js";
+import "../chunk-NTDKZW4E.js";
+import {
+  clientValidationSchemaByName,
+  useClientValidation
+} from "../chunk-L5TXRTPB.js";
+import {
+  checkFieldIsRequired,
+  useFormContext
+} from "../chunk-PO5UQAU6.js";
+import "../chunk-76KOVUDN.js";
 import "../chunk-K2V4ULA2.js";
 export {
   checkFieldIsRequired,

package/dist/hooks/useClientValidation/index.cjs

@@ -0,0 +1,12 @@
+"use strict";Object.defineProperty(exports, "__esModule", {value: true});
+
+
+var _chunkD5UUY4BDcjs = require('../../chunk-D5UUY4BD.cjs');
+require('../../chunk-NZBO4N3S.cjs');
+require('../../chunk-Z353BLWI.cjs');
+require('../../chunk-555JRYCS.cjs');
+
+
+
+exports.clientValidationSchemaByName = _chunkD5UUY4BDcjs.clientValidationSchemaByName; exports.useClientValidation = _chunkD5UUY4BDcjs.useClientValidation;
+//# sourceMappingURL=index.cjs.map

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

@@ -0,0 +1 @@
+{"version":3,"sources":["/home/runner/work/pixels/pixels/packages/uniform/dist/hooks/useClientValidation/index.cjs"],"names":[],"mappings":"AAAA;AACE;AACA;AACF,4DAAiC;AACjC,oCAAiC;AACjC,oCAAiC;AACjC,oCAAiC;AACjC;AACE;AACA;AACF,2JAAC","file":"/home/runner/work/pixels/pixels/packages/uniform/dist/hooks/useClientValidation/index.cjs"}

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

@@ -0,0 +1,147 @@
+import * as _fuf_stack_veto_dist_types_d_Dzd6j9xO from '@fuf-stack/veto/dist/types.d-Dzd6j9xO';
+import { VetoTypeAny } from '@fuf-stack/veto';
+
+/**
+ * Hook for adding dynamic client-side validation to forms.
+ *
+ * Client validation is used for context-dependent validation rules that require external data
+ * (e.g., checking if a username already exists). It complements base validation (passed to Form),
+ * which handles static rules like "required", min/max length, format, etc.
+ *
+ * **Typical pattern:**
+ * - Base validation: Static, always-on rules (required, format, length constraints)
+ * - Client validation: Dynamic rules based on external data (uniqueness, business logic)
+ * - Client schemas should use `.nullish()` to allow empty values (base validation handles "required")
+ *
+ * Automatically manages validation schema lifecycle: sets schema when data is provided,
+ * clears schema when data is null/undefined, and cleans up on unmount. When the client
+ * validation schema changes, automatically re-validates all touched fields.
+ *
+ * @param data - Data to create validation schema from (or null/undefined to clear validation)
+ * @param schemaFactory - Function that creates a validation schema from the data. Schemas should typically use `.nullish()`.
+ * @param options - Optional configuration object
+ * @param options.key - Optional custom key for registration. Useful when multiple instances should share validation (e.g., in field arrays)
+ *
+ * @example
+ * ```tsx
+ * // Base validation handles "required" and format
+ * const baseSchema = veto({ username: vt.string({ min: 3 }) });
+ *
+ * // Client validation adds dynamic uniqueness check
+ * const { data: teamData } = useTeamQuery(teamId);
+ * useClientValidation(teamData, (data) =>
+ *   vt.objectLoose({
+ *     username: vt.string()
+ *       .refine(
+ *         (value) => !data.existingUsers.includes(value),
+ *         { message: 'Username already exists' }
+ *       )
+ *       .nullish() // Allow empty - base validation handles "required"
+ *   })
+ * );
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Using custom key in a field array to avoid multiple registrations
+ * fields.map((field, index) => (
+ *   useClientValidation(
+ *     userData,
+ *     (data) => clientValidationSchemaByName(
+ *       `items.${index}.name`,
+ *       vt.string()
+ *         .refine((val) => !data.forbidden.includes(val), { message: 'Name not allowed' })
+ *         .nullish()
+ *     ),
+ *     { key: 'items-validation' } // All instances share the same key
+ *   )
+ * ));
+ * ```
+ */
+declare const useClientValidation: <TData = unknown>(data: TData | null | undefined, schemaFactory: (data: TData) => VetoTypeAny, options?: {
+    key?: string;
+}) => void;
+/**
+ * Helper function to create a veto looseObject schema for a single field with nested path support.
+ *
+ * Parses field paths (dot-notation) and creates properly nested loose object schemas with array support.
+ * All intermediate objects and arrays are marked as optional to allow partial data structures.
+ * Numeric segments in the path are treated as array indices, and the parent field is wrapped in an array schema.
+ * Supports flat arrays (arrays of primitives) via the special `__FLAT__` key.
+ *
+ * **Important:** The fieldSchema should typically use `.nullish()` to allow empty values. This is because:
+ * - Base validation (passed to Form) handles "required" constraints
+ * - Client validation adds dynamic, context-dependent rules (e.g., "username already exists")
+ * - Form data processing converts empty strings in flat arrays to `null` (not `undefined`)
+ * - `.nullish()` accepts both `null` and `undefined`, while `.optional()` only accepts `undefined`
+ *
+ * This pattern ensures client validation only validates non-empty values, while base validation
+ * enforces required fields and basic constraints (min length, format, etc.).
+ *
+ * @param name - The dot-separated path to the field (e.g., 'username', 'user.profile.email', 'items.0.name', 'tags.0.__FLAT__')
+ * @param fieldSchema - The veto validation schema for the field. Should typically use `.nullish()` to allow empty values.
+ * @returns A nested loose object schema matching the field path structure with proper type inference
+ *
+ * @example
+ * ```tsx
+ * // Typical usage: base validation handles "required", client validation adds dynamic rules
+ * // Base validation (in Form component)
+ * const baseSchema = veto({ username: vt.string({ min: 3 }) }); // Required + min length
+ *
+ * // Client validation (dynamic check for existing usernames)
+ * const { data: userData } = useUserQuery(userId);
+ * useClientValidation(userData, (data) =>
+ *   clientValidationSchemaByName(
+ *     'username',
+ *     vt.string()
+ *       .refine(
+ *         (value) => !data.existingUsernames.includes(value),
+ *         { message: 'Username already taken' }
+ *       )
+ *       .nullish() // Allow empty - base validation handles "required"
+ *   )
+ * );
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Nested field path with dynamic validation
+ * clientValidationSchemaByName(
+ *   'user.profile.email',
+ *   vt.string()
+ *     .refine(
+ *       (value) => !reservedEmails.includes(value),
+ *       { message: 'This email is reserved' }
+ *     )
+ *     .nullish()
+ * )
+ * // => objectLoose({ user: objectLoose({ profile: objectLoose({ email: ... }).optional() }).optional() })
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Array of objects with dynamic validation
+ * clientValidationSchemaByName(
+ *   'items.0.tag',
+ *   vt.string()
+ *     .refine((value) => !forbiddenTags.includes(value), { message: 'Tag not allowed' })
+ *     .nullish()
+ * )
+ * // => objectLoose({ items: array(objectLoose({ tag: ... })).optional() })
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Flat array (array of primitives) with dynamic validation
+ * clientValidationSchemaByName(
+ *   'tags.0.__FLAT__',
+ *   vt.string()
+ *     .refine((value) => !forbiddenWords.includes(value), { message: 'Word not allowed' })
+ *     .nullish()
+ * )
+ * // => objectLoose({ tags: array(vt.string().refine(...).nullish()).optional() })
+ * ```
+ */
+declare const clientValidationSchemaByName: <T extends VetoTypeAny>(name: string, fieldSchema: T) => _fuf_stack_veto_dist_types_d_Dzd6j9xO.Z;
+
+export { clientValidationSchemaByName, useClientValidation };

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

@@ -0,0 +1,147 @@
+import * as _fuf_stack_veto_dist_types_d_Dzd6j9xO from '@fuf-stack/veto/dist/types.d-Dzd6j9xO';
+import { VetoTypeAny } from '@fuf-stack/veto';
+
+/**
+ * Hook for adding dynamic client-side validation to forms.
+ *
+ * Client validation is used for context-dependent validation rules that require external data
+ * (e.g., checking if a username already exists). It complements base validation (passed to Form),
+ * which handles static rules like "required", min/max length, format, etc.
+ *
+ * **Typical pattern:**
+ * - Base validation: Static, always-on rules (required, format, length constraints)
+ * - Client validation: Dynamic rules based on external data (uniqueness, business logic)
+ * - Client schemas should use `.nullish()` to allow empty values (base validation handles "required")
+ *
+ * Automatically manages validation schema lifecycle: sets schema when data is provided,
+ * clears schema when data is null/undefined, and cleans up on unmount. When the client
+ * validation schema changes, automatically re-validates all touched fields.
+ *
+ * @param data - Data to create validation schema from (or null/undefined to clear validation)
+ * @param schemaFactory - Function that creates a validation schema from the data. Schemas should typically use `.nullish()`.
+ * @param options - Optional configuration object
+ * @param options.key - Optional custom key for registration. Useful when multiple instances should share validation (e.g., in field arrays)
+ *
+ * @example
+ * ```tsx
+ * // Base validation handles "required" and format
+ * const baseSchema = veto({ username: vt.string({ min: 3 }) });
+ *
+ * // Client validation adds dynamic uniqueness check
+ * const { data: teamData } = useTeamQuery(teamId);
+ * useClientValidation(teamData, (data) =>
+ *   vt.objectLoose({
+ *     username: vt.string()
+ *       .refine(
+ *         (value) => !data.existingUsers.includes(value),
+ *         { message: 'Username already exists' }
+ *       )
+ *       .nullish() // Allow empty - base validation handles "required"
+ *   })
+ * );
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Using custom key in a field array to avoid multiple registrations
+ * fields.map((field, index) => (
+ *   useClientValidation(
+ *     userData,
+ *     (data) => clientValidationSchemaByName(
+ *       `items.${index}.name`,
+ *       vt.string()
+ *         .refine((val) => !data.forbidden.includes(val), { message: 'Name not allowed' })
+ *         .nullish()
+ *     ),
+ *     { key: 'items-validation' } // All instances share the same key
+ *   )
+ * ));
+ * ```
+ */
+declare const useClientValidation: <TData = unknown>(data: TData | null | undefined, schemaFactory: (data: TData) => VetoTypeAny, options?: {
+    key?: string;
+}) => void;
+/**
+ * Helper function to create a veto looseObject schema for a single field with nested path support.
+ *
+ * Parses field paths (dot-notation) and creates properly nested loose object schemas with array support.
+ * All intermediate objects and arrays are marked as optional to allow partial data structures.
+ * Numeric segments in the path are treated as array indices, and the parent field is wrapped in an array schema.
+ * Supports flat arrays (arrays of primitives) via the special `__FLAT__` key.
+ *
+ * **Important:** The fieldSchema should typically use `.nullish()` to allow empty values. This is because:
+ * - Base validation (passed to Form) handles "required" constraints
+ * - Client validation adds dynamic, context-dependent rules (e.g., "username already exists")
+ * - Form data processing converts empty strings in flat arrays to `null` (not `undefined`)
+ * - `.nullish()` accepts both `null` and `undefined`, while `.optional()` only accepts `undefined`
+ *
+ * This pattern ensures client validation only validates non-empty values, while base validation
+ * enforces required fields and basic constraints (min length, format, etc.).
+ *
+ * @param name - The dot-separated path to the field (e.g., 'username', 'user.profile.email', 'items.0.name', 'tags.0.__FLAT__')
+ * @param fieldSchema - The veto validation schema for the field. Should typically use `.nullish()` to allow empty values.
+ * @returns A nested loose object schema matching the field path structure with proper type inference
+ *
+ * @example
+ * ```tsx
+ * // Typical usage: base validation handles "required", client validation adds dynamic rules
+ * // Base validation (in Form component)
+ * const baseSchema = veto({ username: vt.string({ min: 3 }) }); // Required + min length
+ *
+ * // Client validation (dynamic check for existing usernames)
+ * const { data: userData } = useUserQuery(userId);
+ * useClientValidation(userData, (data) =>
+ *   clientValidationSchemaByName(
+ *     'username',
+ *     vt.string()
+ *       .refine(
+ *         (value) => !data.existingUsernames.includes(value),
+ *         { message: 'Username already taken' }
+ *       )
+ *       .nullish() // Allow empty - base validation handles "required"
+ *   )
+ * );
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Nested field path with dynamic validation
+ * clientValidationSchemaByName(
+ *   'user.profile.email',
+ *   vt.string()
+ *     .refine(
+ *       (value) => !reservedEmails.includes(value),
+ *       { message: 'This email is reserved' }
+ *     )
+ *     .nullish()
+ * )
+ * // => objectLoose({ user: objectLoose({ profile: objectLoose({ email: ... }).optional() }).optional() })
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Array of objects with dynamic validation
+ * clientValidationSchemaByName(
+ *   'items.0.tag',
+ *   vt.string()
+ *     .refine((value) => !forbiddenTags.includes(value), { message: 'Tag not allowed' })
+ *     .nullish()
+ * )
+ * // => objectLoose({ items: array(objectLoose({ tag: ... })).optional() })
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Flat array (array of primitives) with dynamic validation
+ * clientValidationSchemaByName(
+ *   'tags.0.__FLAT__',
+ *   vt.string()
+ *     .refine((value) => !forbiddenWords.includes(value), { message: 'Word not allowed' })
+ *     .nullish()
+ * )
+ * // => objectLoose({ tags: array(vt.string().refine(...).nullish()).optional() })
+ * ```
+ */
+declare const clientValidationSchemaByName: <T extends VetoTypeAny>(name: string, fieldSchema: T) => _fuf_stack_veto_dist_types_d_Dzd6j9xO.Z;
+
+export { clientValidationSchemaByName, useClientValidation };

package/dist/hooks/useClientValidation/index.js

@@ -0,0 +1,12 @@
+import {
+  clientValidationSchemaByName,
+  useClientValidation
+} from "../../chunk-L5TXRTPB.js";
+import "../../chunk-PO5UQAU6.js";
+import "../../chunk-76KOVUDN.js";
+import "../../chunk-K2V4ULA2.js";
+export {
+  clientValidationSchemaByName,
+  useClientValidation
+};
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}