@fuf-stack/uniform 1.10.3 → 1.11.0

package/dist/partials/FieldValidationError/index.cjs

@@ -1,10 +1,5 @@
-"use strict";Object.defineProperty(exports, "__esModule", {value: true});
+Object.defineProperty(exports, '__esModule', { value: true });
+const require_FieldValidationError = require('../../FieldValidationError-Cq6aI0tE.cjs');
 
-
-var _chunkNHEZXA4Hcjs = require('../../chunk-NHEZXA4H.cjs');
-require('../../chunk-555JRYCS.cjs');
-
-
-
-exports.FieldValidationError = _chunkNHEZXA4Hcjs.FieldValidationError_default; exports.default = _chunkNHEZXA4Hcjs.FieldValidationError_default2;
-//# sourceMappingURL=index.cjs.map
+exports.FieldValidationError = require_FieldValidationError.FieldValidationError_default$1;
+exports.default = require_FieldValidationError.FieldValidationError_default;

package/dist/partials/FieldValidationError/index.d.cts

@@ -1,8 +1,2 @@
-import { F as FieldValidationError } from '../../FieldValidationError-DwtLkGMo.cjs';
-export { a as FieldValidationErrorProps } from '../../FieldValidationError-DwtLkGMo.cjs';
-import 'react/jsx-runtime';
-import 'react-hook-form';
-
-
-
-export { FieldValidationError, FieldValidationError as default };
+import { n as FieldValidationErrorProps, t as FieldValidationError } from "../../index-BMN2XNyT.cjs";
+export { FieldValidationError, FieldValidationError as default, FieldValidationErrorProps };

package/dist/partials/FieldValidationError/index.d.ts

@@ -1,8 +1,2 @@
-import { F as FieldValidationError } from '../../FieldValidationError-DwtLkGMo.js';
-export { a as FieldValidationErrorProps } from '../../FieldValidationError-DwtLkGMo.js';
-import 'react/jsx-runtime';
-import 'react-hook-form';
-
-
-
-export { FieldValidationError, FieldValidationError as default };
+import { n as FieldValidationErrorProps, t as FieldValidationError } from "../../index-DHHBSmJb.js";
+export { FieldValidationError, FieldValidationError as default, FieldValidationErrorProps };

package/dist/partials/FieldValidationError/index.js

@@ -1,10 +1,3 @@
-import {
-  FieldValidationError_default,
-  FieldValidationError_default2
-} from "../../chunk-ELYGQTXB.js";
-import "../../chunk-K2V4ULA2.js";
-export {
-  FieldValidationError_default as FieldValidationError,
-  FieldValidationError_default2 as default
-};
-//# sourceMappingURL=index.js.map
+import { n as FieldValidationError_default, t as FieldValidationError_default$1 } from "../../FieldValidationError-D86DPSOH.js";
+
+export { FieldValidationError_default as FieldValidationError, FieldValidationError_default$1 as default };

package/dist/useClientValidation-BnnscAEe.js

@@ -0,0 +1,179 @@
+import { t as flatArrayKey } from "./helpers-B-CJOBt3.js";
+import { n as useFormContext } from "./useFormContext-JCm1UR_e.js";
+import { useEffect, useId } from "react";
+import { array, objectLoose } from "@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 } = useFormContext();
+	const autoGeneratedKey = useId();
+	const key = options?.key ?? autoGeneratedKey;
+	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 === flatArrayKey) continue;
+		if (isNumeric) schema = array(schema).optional();
+		else {
+			const obj = objectLoose({ [segment]: schema });
+			schema = i > 0 ? obj.optional() : obj;
+		}
+	}
+	return schema;
+};
+
+//#endregion
+export { useClientValidation as n, clientValidationSchemaByName as t };
+//# sourceMappingURL=useClientValidation-BnnscAEe.js.map

package/dist/useClientValidation-BnnscAEe.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useClientValidation-BnnscAEe.js","names":["schema: VetoTypeAny"],"sources":["../src/hooks/useClientValidation/useClientValidation.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"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAkEA,MAAa,uBACX,MACA,eACA,YACS;CACT,MAAM,EACJ,WAAW,EAAE,iBACb,YAAY,EAAE,6BACd,YACE,gBAAgB;CAGpB,MAAM,mBAAmB,OAAO;CAChC,MAAM,MAAM,SAAS,OAAO;AAO5B,iBAAgB;AAEd,MAAI,QAAQ,KAEV,2BAA0B,KADD,cAAc,KAAK,CACI;MAGhD,2BAA0B,KAAK,KAAK;EAItC,MAAM,oBAAoB,OAAO,KAAK,cAAc;AACpD,MAAI,kBAAkB,SAAS,EAG7B,YAAW,YAAY;AACrB,UAAO,QAAQ,kBAAkB;KAChC,EAAE;AAIP,eAAa;AACX,6BAA0B,KAAK,KAAK;;IAIrC,CA7Bc,KAAK,UAAU,KAAK,EA6BvB,IAAI,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAoFrB,MAAa,gCACX,MACA,gBACG;CACH,MAAM,WAAW,KAAK,MAAM,IAAI;CAGhC,IAAIA,SAAsB;AAG1B,MAAK,IAAI,IAAI,SAAS,SAAS,GAAG,KAAK,GAAG,KAAK,GAAG;EAChD,MAAM,UAAU,SAAS;EAEzB,MAAM,YAAY,QAAQ,KAAK,QAAQ;AAGvC,MAFuB,YAAY,aAMjC;AAGF,MAAI,UAEF,UAAS,MAAM,OAAO,CAAC,UAAU;OAC5B;GAGL,MAAM,MAAM,YAAY,GACrB,UAAU,QACZ,CAAC;AACF,YAAS,IAAI,IAAI,IAAI,UAAU,GAAG;;;AAItC,QAAO"}

package/dist/useClientValidation-C3Q5UCy9.d.cts

@@ -0,0 +1,150 @@
+import { VetoTypeAny } from "@fuf-stack/veto";
+import * as zod0 from "zod";
+
+//#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) => zod0.ZodTypeAny;
+//#endregion
+export { useClientValidation as n, clientValidationSchemaByName as t };
+//# sourceMappingURL=useClientValidation-C3Q5UCy9.d.cts.map

package/dist/useClientValidation-C3Q5UCy9.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useClientValidation-C3Q5UCy9.d.cts","names":[],"sources":["../src/hooks/useClientValidation/useClientValidation.ts"],"sourcesContent":[],"mappings":";;;;;;;;AAkEA;;;;;AAkIA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cAlIa,6CACL,gDACgB,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cAgIrB,yCAA0C,wCAExC,MAAC,IAAA,CAAA"}

package/dist/useClientValidation-CkBtUSco.d.ts

@@ -0,0 +1,150 @@
+import { VetoTypeAny } from "@fuf-stack/veto";
+import * as zod0 from "zod";
+
+//#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) => zod0.ZodTypeAny;
+//#endregion
+export { useClientValidation as n, clientValidationSchemaByName as t };
+//# sourceMappingURL=useClientValidation-CkBtUSco.d.ts.map

package/dist/useClientValidation-CkBtUSco.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useClientValidation-CkBtUSco.d.ts","names":[],"sources":["../src/hooks/useClientValidation/useClientValidation.ts"],"sourcesContent":[],"mappings":";;;;;;;;AAkEA;;;;;AAkIA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cAlIa,6CACL,gDACgB,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cAgIrB,yCAA0C,wCAExC,MAAC,IAAA,CAAA"}