@fuf-stack/uniform 1.22.5 → 1.22.7

package/dist/hooks/useClientValidation/index.cjs

@@ -1,9 +1,183 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_useClientValidation = require("../../useClientValidation-BRfhqRom.cjs");
+require("../../helpers/index.cjs");
+const require_useFormContext = require("../../useFormContext-kUHonwgu.cjs");
+let react = require("react");
+let _fuf_stack_veto = require("@fuf-stack/veto");
+//#region src/hooks/useClientValidation/useClientValidation.ts
+/**
+* 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
+*   )
+* ));
+* ```
+*/
+const useClientValidation = (data, schemaFactory, options) => {
+	const { formState: { touchedFields }, validation: { setClientValidationSchema }, trigger } = require_useFormContext.useFormContext();
+	const autoGeneratedKey = (0, react.useId)();
+	const key = options?.key ?? autoGeneratedKey;
+	(0, react.useEffect)(() => {
+		if (data != null) setClientValidationSchema(key, schemaFactory(data));
+		else setClientValidationSchema(key, null);
+		const touchedFieldNames = Object.keys(touchedFields);
+		if (touchedFieldNames.length > 0) setTimeout(async () => {
+			return trigger(touchedFieldNames);
+		}, 1);
+		return () => {
+			setClientValidationSchema(key, null);
+		};
+	}, [JSON.stringify(data), key]);
+};
+/**
+* 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() })
+* ```
+*/
+const clientValidationSchemaByName = (name, fieldSchema) => {
+	const segments = name.split(".");
+	let schema = fieldSchema;
+	for (let i = segments.length - 1; i >= 0; i -= 1) {
+		const segment = segments[i];
+		const isNumeric = /^\d+$/.test(segment);
+		if (segment === "__FLAT__") continue;
+		if (isNumeric) schema = (0, _fuf_stack_veto.array)(schema).optional();
+		else {
+			const obj = (0, _fuf_stack_veto.objectLoose)({ [segment]: schema });
+			schema = i > 0 ? obj.optional() : obj;
+		}
+	}
+	return schema;
+};
+//#endregion
 //#region src/hooks/useClientValidation/index.ts
 /* v8 ignore stop */
 //#endregion
-exports.clientValidationSchemaByName = require_useClientValidation.clientValidationSchemaByName;
-exports.useClientValidation = require_useClientValidation.useClientValidation;
+exports.clientValidationSchemaByName = clientValidationSchemaByName;
+exports.useClientValidation = useClientValidation;
 
 //# sourceMappingURL=index.cjs.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.cjs","names":[],"sources":["../../../src/hooks/useClientValidation/index.ts"],"sourcesContent":["/* v8 ignore start */\n\nexport * from './useClientValidation';\n\n/* v8 ignore stop */\n"],"mappings":""}
+{"version":3,"file":"index.cjs","names":["useFormContext"],"sources":["../../../src/hooks/useClientValidation/useClientValidation.ts","../../../src/hooks/useClientValidation/index.ts"],"sourcesContent":["import type { VetoTypeAny } from '@fuf-stack/veto';\n\nimport { useEffect, useId } from 'react';\n\nimport { array, objectLoose } from '@fuf-stack/veto';\n\nimport { flatArrayKey } from '../../helpers';\nimport { useFormContext } from '../useFormContext/useFormContext';\n\n/**\n * Hook for adding dynamic client-side validation to forms.\n *\n * Client validation is used for context-dependent validation rules that require external data\n * (e.g., checking if a username already exists). It complements base validation (passed to Form),\n * which handles static rules like \"required\", min/max length, format, etc.\n *\n * **Typical pattern:**\n * - Base validation: Static, always-on rules (required, format, length constraints)\n * - Client validation: Dynamic rules based on external data (uniqueness, business logic)\n * - Client schemas should use `.nullish()` to allow empty values (base validation handles \"required\")\n *\n * Automatically manages validation schema lifecycle: sets schema when data is provided,\n * clears schema when data is null/undefined, and cleans up on unmount. When the client\n * validation schema changes, automatically re-validates all touched fields.\n *\n * @param data - Data to create validation schema from (or null/undefined to clear validation)\n * @param schemaFactory - Function that creates a validation schema from the data. Schemas should typically use `.nullish()`.\n * @param options - Optional configuration object\n * @param options.key - Optional custom key for registration. Useful when multiple instances should share validation (e.g., in field arrays)\n *\n * @example\n * ```tsx\n * // Base validation handles \"required\" and format\n * const baseSchema = veto({ username: vt.string({ min: 3 }) });\n *\n * // Client validation adds dynamic uniqueness check\n * const { data: teamData } = useTeamQuery(teamId);\n * useClientValidation(teamData, (data) =>\n *   vt.objectLoose({\n *     username: vt.string()\n *       .refine(\n *         (value) => !data.existingUsers.includes(value),\n *         { message: 'Username already exists' }\n *       )\n *       .nullish() // Allow empty - base validation handles \"required\"\n *   })\n * );\n * ```\n *\n * @example\n * ```tsx\n * // Using custom key in a field array to avoid multiple registrations\n * fields.map((field, index) => (\n *   useClientValidation(\n *     userData,\n *     (data) => clientValidationSchemaByName(\n *       `items.${index}.name`,\n *       vt.string()\n *         .refine((val) => !data.forbidden.includes(val), { message: 'Name not allowed' })\n *         .nullish()\n *     ),\n *     { key: 'items-validation' } // All instances share the same key\n *   )\n * ));\n * ```\n */\nexport const useClientValidation = <TData = unknown>(\n  data: TData | null | undefined,\n  schemaFactory: (data: TData) => VetoTypeAny,\n  options?: { key?: string },\n): void => {\n  const {\n    formState: { touchedFields },\n    validation: { setClientValidationSchema },\n    trigger,\n  } = useFormContext();\n\n  // Use provided key or auto-generate unique key\n  const autoGeneratedKey = useId();\n  const key = options?.key ?? autoGeneratedKey;\n\n  // Use data hash instead of object reference to avoid unnecessary re-runs\n  // when data object reference changes but data remains the same\n  const dataHash = JSON.stringify(data);\n\n  // Single effect to manage validation schema lifecycle\n  useEffect(() => {\n    // Set validation schema when data is available\n    if (data != null) {\n      const validationSchema = schemaFactory(data);\n      setClientValidationSchema(key, validationSchema);\n    } else {\n      // Clear validation schema when no data\n      setClientValidationSchema(key, null);\n    }\n\n    // Re-validate all touched fields when client validation schema changes\n    const touchedFieldNames = Object.keys(touchedFields);\n    if (touchedFieldNames.length > 0) {\n      // Use setTimeout to ensure the client validation schema update has propagated\n      // before triggering re-validation (fixes race condition)\n      setTimeout(async () => {\n        return trigger(touchedFieldNames);\n      }, 1);\n    }\n\n    // Cleanup on unmount or when dependencies change\n    return () => {\n      setClientValidationSchema(key, null);\n    };\n    // Only re-run when data (dataHash) or key changes\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n  }, [dataHash, key]);\n};\n\n/**\n * Helper function to create a veto looseObject schema for a single field with nested path support.\n *\n * Parses field paths (dot-notation) and creates properly nested loose object schemas with array support.\n * All intermediate objects and arrays are marked as optional to allow partial data structures.\n * Numeric segments in the path are treated as array indices, and the parent field is wrapped in an array schema.\n * Supports flat arrays (arrays of primitives) via the special `__FLAT__` key.\n *\n * **Important:** The fieldSchema should typically use `.nullish()` to allow empty values. This is because:\n * - Base validation (passed to Form) handles \"required\" constraints\n * - Client validation adds dynamic, context-dependent rules (e.g., \"username already exists\")\n * - Form data processing converts empty strings in flat arrays to `null` (not `undefined`)\n * - `.nullish()` accepts both `null` and `undefined`, while `.optional()` only accepts `undefined`\n *\n * This pattern ensures client validation only validates non-empty values, while base validation\n * enforces required fields and basic constraints (min length, format, etc.).\n *\n * @param name - The dot-separated path to the field (e.g., 'username', 'user.profile.email', 'items.0.name', 'tags.0.__FLAT__')\n * @param fieldSchema - The veto validation schema for the field. Should typically use `.nullish()` to allow empty values.\n * @returns A nested loose object schema matching the field path structure with proper type inference\n *\n * @example\n * ```tsx\n * // Typical usage: base validation handles \"required\", client validation adds dynamic rules\n * // Base validation (in Form component)\n * const baseSchema = veto({ username: vt.string({ min: 3 }) }); // Required + min length\n *\n * // Client validation (dynamic check for existing usernames)\n * const { data: userData } = useUserQuery(userId);\n * useClientValidation(userData, (data) =>\n *   clientValidationSchemaByName(\n *     'username',\n *     vt.string()\n *       .refine(\n *         (value) => !data.existingUsernames.includes(value),\n *         { message: 'Username already taken' }\n *       )\n *       .nullish() // Allow empty - base validation handles \"required\"\n *   )\n * );\n * ```\n *\n * @example\n * ```tsx\n * // Nested field path with dynamic validation\n * clientValidationSchemaByName(\n *   'user.profile.email',\n *   vt.string()\n *     .refine(\n *       (value) => !reservedEmails.includes(value),\n *       { message: 'This email is reserved' }\n *     )\n *     .nullish()\n * )\n * // => objectLoose({ user: objectLoose({ profile: objectLoose({ email: ... }).optional() }).optional() })\n * ```\n *\n * @example\n * ```tsx\n * // Array of objects with dynamic validation\n * clientValidationSchemaByName(\n *   'items.0.tag',\n *   vt.string()\n *     .refine((value) => !forbiddenTags.includes(value), { message: 'Tag not allowed' })\n *     .nullish()\n * )\n * // => objectLoose({ items: array(objectLoose({ tag: ... })).optional() })\n * ```\n *\n * @example\n * ```tsx\n * // Flat array (array of primitives) with dynamic validation\n * clientValidationSchemaByName(\n *   'tags.0.__FLAT__',\n *   vt.string()\n *     .refine((value) => !forbiddenWords.includes(value), { message: 'Word not allowed' })\n *     .nullish()\n * )\n * // => objectLoose({ tags: array(vt.string().refine(...).nullish()).optional() })\n * ```\n */\nexport const clientValidationSchemaByName = <T extends VetoTypeAny>(\n  name: string,\n  fieldSchema: T,\n) => {\n  const segments = name.split('.');\n\n  // Build schema from innermost to outermost\n  let schema: VetoTypeAny = fieldSchema;\n\n  // Process segments in reverse order to build nested structure\n  for (let i = segments.length - 1; i >= 0; i -= 1) {\n    const segment = segments[i];\n\n    const isNumeric = /^\\d+$/.test(segment);\n    const isFlatArrayKey = segment === flatArrayKey;\n\n    if (isFlatArrayKey) {\n      // Skip the __FLAT__ key - it's just a marker for flat arrays\n      // The schema is already correct (primitive type), just continue\n      // eslint-disable-next-line no-continue\n      continue;\n    }\n\n    if (isNumeric) {\n      // Current segment is an array index - wrap current schema in optional array\n      schema = array(schema).optional();\n    } else {\n      // Current segment is a field name - wrap in objectLoose\n      // Make it optional if it's an intermediate object (not the root)\n      const obj = objectLoose({\n        [segment]: schema,\n      });\n      schema = i > 0 ? obj.optional() : obj;\n    }\n  }\n\n  return schema;\n};\n","/* v8 ignore start */\n\nexport * from './useClientValidation';\n\n/* v8 ignore stop */\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAkEA,MAAa,uBACX,MACA,eACA,YACS;CACT,MAAM,EACJ,WAAW,EAAE,iBACb,YAAY,EAAE,6BACd,YACEA,uBAAAA,eAAe;CAGnB,MAAM,oBAAA,GAAA,MAAA,OAAyB;CAC/B,MAAM,MAAM,SAAS,OAAO;CAO5B,CAAA,GAAA,MAAA,iBAAgB;EAEd,IAAI,QAAQ,MAEV,0BAA0B,KADD,cAAc,IACO,CAAC;OAG/C,0BAA0B,KAAK,IAAI;EAIrC,MAAM,oBAAoB,OAAO,KAAK,aAAa;EACnD,IAAI,kBAAkB,SAAS,GAG7B,WAAW,YAAY;GACrB,OAAO,QAAQ,iBAAiB;EAClC,GAAG,CAAC;EAIN,aAAa;GACX,0BAA0B,KAAK,IAAI;EACrC;CAGF,GAAG,CA7Bc,KAAK,UAAU,IA6BrB,GAAG,GAAG,CAAC;AACpB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAmFA,MAAa,gCACX,MACA,gBACG;CACH,MAAM,WAAW,KAAK,MAAM,GAAG;CAG/B,IAAI,SAAsB;CAG1B,KAAK,IAAI,IAAI,SAAS,SAAS,GAAG,KAAK,GAAG,KAAK,GAAG;EAChD,MAAM,UAAU,SAAS;EAEzB,MAAM,YAAY,QAAQ,KAAK,OAAO;EAGtC,IAFuB,YAAA,YAMrB;EAGF,IAAI,WAEF,UAAA,GAAA,gBAAA,OAAe,MAAM,EAAE,SAAS;OAC3B;GAGL,MAAM,OAAA,GAAA,gBAAA,aAAkB,GACrB,UAAU,OACb,CAAC;GACD,SAAS,IAAI,IAAI,IAAI,SAAS,IAAI;EACpC;CACF;CAEA,OAAO;AACT"}

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

@@ -1,2 +1,148 @@
-import { n as useClientValidation, t as clientValidationSchemaByName } from "../../useClientValidation-C2dLJnDI.cjs";
-export { clientValidationSchemaByName, useClientValidation };
+import { VetoTypeAny } from "@fuf-stack/veto";
+
+//#region src/hooks/useClientValidation/useClientValidation.d.ts
+/**
+ * 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) => VetoTypeAny;
+//#endregion
+export { clientValidationSchemaByName, useClientValidation };
+//# sourceMappingURL=index.d.cts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.cts","names":[],"sources":["../../../src/hooks/useClientValidation/useClientValidation.ts"],"mappings":";;;;;AAkEA;;;;;;;;;;;;;;;;;;AAG4B;AA+H5B;;;;;;;;;;;;;;;AAqCC;;;;;;;;;;;;;;;;;;;;;cAvKY,mBAAA,oBACX,IAAA,EAAM,KAAA,qBACN,aAAA,GAAgB,IAAA,EAAM,KAAA,KAAU,WAAA,EAChC,OAAA;EAAY,GAAA;AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cA+HD,4BAAA,aAA0C,WAAA,EACrD,IAAA,UACA,WAAA,EAAa,CAAA,KAAC,WAAA"}

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

@@ -1,2 +1,148 @@
-import { n as useClientValidation, t as clientValidationSchemaByName } from "../../useClientValidation-qRq2_spX.js";
-export { clientValidationSchemaByName, useClientValidation };
+import { VetoTypeAny } from "@fuf-stack/veto";
+
+//#region src/hooks/useClientValidation/useClientValidation.d.ts
+/**
+ * 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) => VetoTypeAny;
+//#endregion
+export { clientValidationSchemaByName, useClientValidation };
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../../src/hooks/useClientValidation/useClientValidation.ts"],"mappings":";;;;;AAkEA;;;;;;;;;;;;;;;;;;AAG4B;AA+H5B;;;;;;;;;;;;;;;AAqCC;;;;;;;;;;;;;;;;;;;;;cAvKY,mBAAA,oBACX,IAAA,EAAM,KAAA,qBACN,aAAA,GAAgB,IAAA,EAAM,KAAA,KAAU,WAAA,EAChC,OAAA;EAAY,GAAA;AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cA+HD,4BAAA,aAA0C,WAAA,EACrD,IAAA,UACA,WAAA,EAAa,CAAA,KAAC,WAAA"}