@1money/react-ui 1.16.0 → 1.17.0

package/es/components/Form/style/Form.scss

@@ -0,0 +1,167 @@
+@use '../../../variable.scss' as *;
+
+// Intentionally token-level SCSS (no global tag selectors): spacing/typography/
+// opacity values are centralized as component CSS variables for predictable BEM output.
+$component: 'form';
+$cls: #{$prefix}-#{$component};
+
+@mixin om-form-token-vars {
+  --om-form-spacing-xs: 4px;
+  --om-form-spacing-sm: 8px;
+  --om-form-spacing-md: 12px;
+  --om-form-spacing-lg: 16px;
+  --om-form-control-height: 44px;
+  --om-form-font-size-base: 14px;
+  --om-form-line-height-base: 20px;
+  --om-form-font-size-help: 12px;
+  --om-form-line-height-help: 18px;
+  --om-form-opacity-disabled: 0.6;
+}
+
+.#{$cls} {
+  @include om-form-token-vars;
+
+  &-root {
+    width: 100%;
+
+    @include om-form-token-vars;
+  }
+
+  &-layout-horizontal .#{$prefix}-form-item-root {
+    display: flex;
+    align-items: flex-start;
+  }
+
+  &-layout-vertical .#{$prefix}-form-item-root {
+    display: flex;
+    flex-direction: column;
+  }
+
+  &-layout-inline {
+    display: flex;
+    flex-wrap: wrap;
+    gap: var(--om-form-spacing-lg);
+  }
+
+  &-label-left .#{$prefix}-form-item-label {
+    text-align: left;
+  }
+}
+
+$item: 'form-item';
+$item-cls: #{$prefix}-#{$item};
+
+.#{$item-cls} {
+  @include om-form-token-vars;
+
+  &-root {
+    width: 100%;
+    margin-bottom: var(--om-form-spacing-lg);
+
+    @include om-form-token-vars;
+  }
+
+  &-label {
+    display: flex;
+    flex: 0 0 var(--om-form-label-width, 25%);
+    align-items: center;
+    justify-content: flex-end;
+    min-width: fit-content;
+    min-height: var(--om-form-control-height);
+    padding-right: var(--om-form-spacing-md);
+    color: $color-primary-black;
+    font-size: var(--om-form-font-size-base);
+    line-height: var(--om-form-line-height-base);
+    white-space: nowrap;
+    text-align: right;
+  }
+
+  &-label-required::before {
+    margin-right: var(--om-form-spacing-xs);
+    color: $color-negative;
+    content: '*';
+  }
+
+  &-colon {
+    margin-left: var(--om-form-spacing-xs);
+  }
+
+  &-control {
+    flex: 1 1 auto;
+    max-width: var(--om-form-wrapper-width, 75%);
+  }
+
+  &-content {
+    display: flex;
+    flex-direction: column;
+    gap: var(--om-form-spacing-sm);
+  }
+
+  &-content-disabled {
+    opacity: var(--om-form-opacity-disabled);
+  }
+
+  &-help {
+    color: $color-grey-midnight;
+    font-size: var(--om-form-font-size-help);
+    line-height: var(--om-form-line-height-help);
+  }
+
+  &-help-error {
+    color: $color-negative;
+  }
+
+  &-help-warning {
+    color: $color-warning-dark;
+  }
+
+  &-help-success {
+    color: $color-success;
+  }
+
+  &-content-error {
+    --om-form-item-status-color: #{$color-negative};
+  }
+
+  &-content-warning {
+    --om-form-item-status-color: #{$color-warning-dark};
+  }
+
+  &-content-success {
+    --om-form-item-status-color: #{$color-success};
+  }
+
+  &-content-validating {
+    --om-form-item-status-color: #{$color-info};
+  }
+
+  &-extra {
+    color: $color-grey-dark;
+    font-size: var(--om-form-font-size-help);
+    line-height: var(--om-form-line-height-help);
+  }
+}
+
+.#{$prefix}-form-layout-vertical {
+  .#{$item-cls}-label {
+    flex: 0 0 auto;
+    justify-content: flex-start;
+    min-width: 0;
+    min-height: auto;
+    margin-bottom: var(--om-form-spacing-sm);
+    padding-right: 0;
+    white-space: normal;
+    text-align: left;
+  }
+
+  .#{$item-cls}-control {
+    max-width: 100%;
+  }
+}
+
+.#{$prefix}-form-layout-inline {
+  .#{$item-cls}-root {
+    width: auto;
+    margin-bottom: 0;
+  }
+}

package/es/components/Form/style/css.js

@@ -0,0 +1,2 @@
+import './Form.css';
+//# sourceMappingURL=data:application/json;charset=utf8;base64,eyJ2ZXJzaW9uIjozLCJzb3VyY2VzIjpbImNvbXBvbmVudHMvRm9ybS9zcmMvY29tcG9uZW50cy9Gb3JtL3N0eWxlL2luZGV4LnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLE9BQU8sYUFBYSIsImZpbGUiOiJjb21wb25lbnRzL0Zvcm0vc3R5bGUvY3NzLmpzIiwic291cmNlc0NvbnRlbnQiOltudWxsXSwic291cmNlUm9vdCI6Ii4uLy4uLy4uLy4uLy4uLy4uLy4uLy4uLy4uLy4uL3NyYyJ9

package/es/components/Form/style/index.d.ts

@@ -0,0 +1 @@
+import './Form.scss';

package/es/components/Form/style/index.js

@@ -0,0 +1,2 @@
+import './Form.scss';
+//# sourceMappingURL=data:application/json;charset=utf8;base64,eyJ2ZXJzaW9uIjozLCJzb3VyY2VzIjpbImNvbXBvbmVudHMvRm9ybS9zcmMvY29tcG9uZW50cy9Gb3JtL3N0eWxlL2luZGV4LnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLE9BQU8sYUFBYSIsImZpbGUiOiJjb21wb25lbnRzL0Zvcm0vc3R5bGUvaW5kZXguanMiLCJzb3VyY2VzQ29udGVudCI6W251bGxdLCJzb3VyY2VSb290IjoiLi4vLi4vLi4vLi4vLi4vLi4vLi4vLi4vLi4vLi4vc3JjIn0=

package/es/components/Form/useFormItemContext.d.ts

@@ -0,0 +1,32 @@
+import type { ReactNode } from 'react';
+import type { FieldValues, UseFormReturn } from 'react-hook-form';
+interface FallbackFormProviderProps {
+    children: ReactNode;
+}
+/**
+ * Lazily creates form methods only when mounted.
+ *
+ * Use this provider when rendering form-aware components outside `<Form>`.
+ */
+export declare function FallbackFormProvider({ children }: FallbackFormProviderProps): import("react").FunctionComponentElement<import("react").ProviderProps<UseFormReturn<FieldValues> | null>>;
+/**
+ * Resolves form context for a `<FormItem>`.
+ *
+ * When rendered inside a `<Form>`, this hook uses the context-provided
+ * `react-hook-form` methods. Otherwise it reads methods from
+ * {@link FallbackFormProvider}, which creates a local `useForm()` instance.
+ *
+ * A development-only console warning is emitted (once per field name) when
+ * a `name` prop is set but no parent `<Form>` context is found.
+ *
+ * @template TFieldValues - The shape of the form values.
+ * @param name - The field name, used for the missing-context warning check.
+ * @returns An object with `ctx` (form context or `null`), `methods`, `control`, and `trigger`.
+ */
+export declare function useFormItemContext<TFieldValues extends FieldValues = FieldValues>(name?: string): {
+    ctx: import("./interface").FormContextValue | null;
+    methods: UseFormReturn<TFieldValues>;
+    control: import("react-hook-form").Control<TFieldValues, any, TFieldValues>;
+    trigger: import("react-hook-form").UseFormTrigger<TFieldValues>;
+};
+export {};

package/es/components/Form/useFormItemContext.js

@@ -0,0 +1,55 @@
+import { createContext, createElement, useContext, useEffect, useRef } from 'react';
+import { useForm } from 'react-hook-form';
+import { FormContext } from './Form';
+var FallbackFormContext = /*#__PURE__*/createContext(null);
+/**
+ * Lazily creates form methods only when mounted.
+ *
+ * Use this provider when rendering form-aware components outside `<Form>`.
+ */
+export function FallbackFormProvider(_ref) {
+  var children = _ref.children;
+  var methods = useForm();
+  return /*#__PURE__*/createElement(FallbackFormContext.Provider, {
+    value: methods
+  }, children);
+}
+/**
+ * Resolves form context for a `<FormItem>`.
+ *
+ * When rendered inside a `<Form>`, this hook uses the context-provided
+ * `react-hook-form` methods. Otherwise it reads methods from
+ * {@link FallbackFormProvider}, which creates a local `useForm()` instance.
+ *
+ * A development-only console warning is emitted (once per field name) when
+ * a `name` prop is set but no parent `<Form>` context is found.
+ *
+ * @template TFieldValues - The shape of the form values.
+ * @param name - The field name, used for the missing-context warning check.
+ * @returns An object with `ctx` (form context or `null`), `methods`, `control`, and `trigger`.
+ */
+export function useFormItemContext(name) {
+  var _a;
+  var ctx = useContext(FormContext);
+  var fallbackMethods = useContext(FallbackFormContext);
+  var warnedRef = useRef(new Set());
+  var methods = (_a = ctx === null || ctx === void 0 ? void 0 : ctx.methods) !== null && _a !== void 0 ? _a : fallbackMethods;
+  if (!methods) {
+    throw new Error('[FormItem] No form control found. Wrap with <Form> or mount inside <FallbackFormProvider>.');
+  }
+  var control = methods.control;
+  var trigger = methods.trigger;
+  useEffect(function () {
+    if (name && !(ctx === null || ctx === void 0 ? void 0 : ctx.methods) && !warnedRef.current.has(name)) {
+      warnedRef.current.add(name);
+      console.warn('[FormItem] `name` prop is set but no form control found. Wrap FormItem inside a <Form> component.');
+    }
+  }, [name, ctx === null || ctx === void 0 ? void 0 : ctx.methods]);
+  return {
+    ctx: ctx,
+    methods: methods,
+    control: control,
+    trigger: trigger
+  };
+}
+//# sourceMappingURL=data:application/json;charset=utf8;base64,eyJ2ZXJzaW9uIjozLCJzb3VyY2VzIjpbImNvbXBvbmVudHMvc3JjL2NvbXBvbmVudHMvRm9ybS91c2VGb3JtSXRlbUNvbnRleHQudHMiLCJjb21wb25lbnRzL0Zvcm0vdXNlRm9ybUl0ZW1Db250ZXh0LmpzIl0sIm5hbWVzIjpbImNyZWF0ZUNvbnRleHQiLCJjcmVhdGVFbGVtZW50IiwidXNlQ29udGV4dCIsInVzZUVmZmVjdCIsInVzZVJlZiIsInVzZUZvcm0iLCJGb3JtQ29udGV4dCIsIkZhbGxiYWNrRm9ybUNvbnRleHQiLCJGYWxsYmFja0Zvcm1Qcm92aWRlciIsIl9yZWYiLCJjaGlsZHJlbiIsIm1ldGhvZHMiLCJQcm92aWRlciIsInZhbHVlIiwidXNlRm9ybUl0ZW1Db250ZXh0IiwibmFtZSIsIl9hIiwiY3R4IiwiZmFsbGJhY2tNZXRob2RzIiwid2FybmVkUmVmIiwiU2V0IiwiRXJyb3IiLCJjb250cm9sIiwidHJpZ2dlciIsImN1cnJlbnQiLCJoYXMiLCJhZGQiLCJjb25zb2xlIiwid2FybiJdLCJtYXBwaW5ncyI6IkFBQUEsU0FBU0EsYUFBYSxFQUFFQyxhQUFhLEVBQUVDLFVBQVUsRUFBRUMsU0FBUyxFQUFFQyxNQUFNLFFBQVEsT0FBTztBQUNuRixTQUFTQyxPQUFPLFFBQVEsaUJBQWlCO0FBR3pDLFNBQVNDLFdBQVcsUUFBUSxRQUFRO0FBRXBDLElBQU1DLG1CQUFtQixnQkFBR1AsYUFBYSxDQUFvQyxJQUFJLENBQUM7QUFNbEY7QUNQQTtBQUNBO0FBQ0E7QUFDQTtBRFNBLE9BQU0sU0FBVVEsb0JBQW9CQSxDQUFBQyxJQUFBLEVBQXdDO0VBQUEsSUFBckNDLFFBQVEsR0FBQUQsSUFBQSxDQUFSQyxRQUFRO0VBQzdDLElBQU1DLE9BQU8sR0FBR04sT0FBTyxDQUFBLENBQWU7RUFDdEMsb0JBQU9KLGFBQWEsQ0FBQ00sbUJBQW1CLENBQUNLLFFBQVEsRUFBRTtJQUFFQyxLQUFLLEVBQUVGO0VBQU8sQ0FBRSxFQUFFRCxRQUFRLENBQUM7QUFDbEY7QUFFQTtBQ1JBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FEVUEsT0FBTSxTQUFVSSxrQkFBa0JBLENBQWlEQyxJQUFhLEVBQUE7RUNSNUYsSUFBSUMsRUFBRTtFRFNSLElBQU1DLEdBQUcsR0FBR2YsVUFBVSxDQUFDSSxXQUFXLENBQUM7RUFDbkMsSUFBTVksZUFBZSxHQUFHaEIsVUFBVSxDQUFDSyxtQkFBbUIsQ0FBQztFQUN2RCxJQUFNWSxTQUFTLEdBQUdmLE1BQU0sQ0FBYyxJQUFJZ0IsR0FBRyxDQUFBLENBQUUsQ0FBQztFQUNoRCxJQUFNVCxPQUFPLEdBQUcsQ0FBQUssRUFBQSxHQUFDQyxHQUFHLEtBQUEsSUFBQSxJQUFIQSxHQUFHLEtBQUEsS0FBQSxDQUFBLEdBQUEsS0FBQSxDQUFBLEdBQUhBLEdBQUcsQ0FBRU4sT0FBbUQsTUFBQSxJQUFBLElBQUFLLEVBQUEsS0FBQSxLQUFBLENBQUEsR0FBQUEsRUFBQSxHQUNuRUUsZUFBc0Q7RUFFNUQsSUFBSSxDQUFDUCxPQUFPLEVBQUU7SUFDWixNQUFNLElBQUlVLEtBQUssQ0FDYiw0RkFBNEYsQ0FDN0Y7RUFDSDtFQUVBLElBQU1DLE9BQU8sR0FBR1gsT0FBTyxDQUFDVyxPQUFPO0VBQy9CLElBQU1DLE9BQU8sR0FBR1osT0FBTyxDQUFDWSxPQUFPO0VBRS9CcEIsU0FBUyxDQUFDLFlBQUs7SUFDYixJQUFJWSxJQUFJLElBQUksRUFBQ0UsR0FBRyxLQUFBLElBQUEsSUFBSEEsR0FBRyxLQUFBLEtBQUEsQ0FBQSxHQUFBLEtBQUEsQ0FBQSxHQUFIQSxHQUFHLENBQUVOLE9BQU8sQ0FBQSxJQUFJLENBQUNRLFNBQVMsQ0FBQ0ssT0FBTyxDQUFDQyxHQUFHLENBQUNWLElBQUksQ0FBQyxFQUFFO01BQ3pESSxTQUFTLENBQUNLLE9BQU8sQ0FBQ0UsR0FBRyxDQUFDWCxJQUFJLENBQUM7TUFDM0JZLE9BQU8sQ0FBQ0MsSUFBSSxDQUFDLG1HQUFtRyxDQUFDO0lBQ25IO0VBQ0YsQ0FBQyxFQUFFLENBQUNiLElBQUksRUFBRUUsR0FBRyxLQUFBLElBQUEsSUFBSEEsR0FBRyxLQUFBLEtBQUEsQ0FBQSxHQUFBLEtBQUEsQ0FBQSxHQUFIQSxHQUFHLENBQUVOLE9BQU8sQ0FBQyxDQUFDO0VBRXhCLE9BQU87SUFBRU0sR0FBRyxFQUFIQSxHQUFHO0lBQUVOLE9BQU8sRUFBUEEsT0FBTztJQUFFVyxPQUFPLEVBQVBBLE9BQU87SUFBRUMsT0FBTyxFQUFQQTtFQUFPLENBQUU7QUFDM0MiLCJmaWxlIjoiY29tcG9uZW50cy9Gb3JtL3VzZUZvcm1JdGVtQ29udGV4dC5qcyIsInNvdXJjZXNDb250ZW50IjpbbnVsbCwiaW1wb3J0IHsgY3JlYXRlQ29udGV4dCwgY3JlYXRlRWxlbWVudCwgdXNlQ29udGV4dCwgdXNlRWZmZWN0LCB1c2VSZWYgfSBmcm9tICdyZWFjdCc7XG5pbXBvcnQgeyB1c2VGb3JtIH0gZnJvbSAncmVhY3QtaG9vay1mb3JtJztcbmltcG9ydCB7IEZvcm1Db250ZXh0IH0gZnJvbSAnLi9Gb3JtJztcbmNvbnN0IEZhbGxiYWNrRm9ybUNvbnRleHQgPSBjcmVhdGVDb250ZXh0KG51bGwpO1xuLyoqXG4gKiBMYXppbHkgY3JlYXRlcyBmb3JtIG1ldGhvZHMgb25seSB3aGVuIG1vdW50ZWQuXG4gKlxuICogVXNlIHRoaXMgcHJvdmlkZXIgd2hlbiByZW5kZXJpbmcgZm9ybS1hd2FyZSBjb21wb25lbnRzIG91dHNpZGUgYDxGb3JtPmAuXG4gKi9cbmV4cG9ydCBmdW5jdGlvbiBGYWxsYmFja0Zvcm1Qcm92aWRlcih7IGNoaWxkcmVuIH0pIHtcbiAgICBjb25zdCBtZXRob2RzID0gdXNlRm9ybSgpO1xuICAgIHJldHVybiBjcmVhdGVFbGVtZW50KEZhbGxiYWNrRm9ybUNvbnRleHQuUHJvdmlkZXIsIHsgdmFsdWU6IG1ldGhvZHMgfSwgY2hpbGRyZW4pO1xufVxuLyoqXG4gKiBSZXNvbHZlcyBmb3JtIGNvbnRleHQgZm9yIGEgYDxGb3JtSXRlbT5gLlxuICpcbiAqIFdoZW4gcmVuZGVyZWQgaW5zaWRlIGEgYDxGb3JtPmAsIHRoaXMgaG9vayB1c2VzIHRoZSBjb250ZXh0LXByb3ZpZGVkXG4gKiBgcmVhY3QtaG9vay1mb3JtYCBtZXRob2RzLiBPdGhlcndpc2UgaXQgcmVhZHMgbWV0aG9kcyBmcm9tXG4gKiB7QGxpbmsgRmFsbGJhY2tGb3JtUHJvdmlkZXJ9LCB3aGljaCBjcmVhdGVzIGEgbG9jYWwgYHVzZUZvcm0oKWAgaW5zdGFuY2UuXG4gKlxuICogQSBkZXZlbG9wbWVudC1vbmx5IGNvbnNvbGUgd2FybmluZyBpcyBlbWl0dGVkIChvbmNlIHBlciBmaWVsZCBuYW1lKSB3aGVuXG4gKiBhIGBuYW1lYCBwcm9wIGlzIHNldCBidXQgbm8gcGFyZW50IGA8Rm9ybT5gIGNvbnRleHQgaXMgZm91bmQuXG4gKlxuICogQHRlbXBsYXRlIFRGaWVsZFZhbHVlcyAtIFRoZSBzaGFwZSBvZiB0aGUgZm9ybSB2YWx1ZXMuXG4gKiBAcGFyYW0gbmFtZSAtIFRoZSBmaWVsZCBuYW1lLCB1c2VkIGZvciB0aGUgbWlzc2luZy1jb250ZXh0IHdhcm5pbmcgY2hlY2suXG4gKiBAcmV0dXJucyBBbiBvYmplY3Qgd2l0aCBgY3R4YCAoZm9ybSBjb250ZXh0IG9yIGBudWxsYCksIGBtZXRob2RzYCwgYGNvbnRyb2xgLCBhbmQgYHRyaWdnZXJgLlxuICovXG5leHBvcnQgZnVuY3Rpb24gdXNlRm9ybUl0ZW1Db250ZXh0KG5hbWUpIHtcbiAgICB2YXIgX2E7XG4gICAgY29uc3QgY3R4ID0gdXNlQ29udGV4dChGb3JtQ29udGV4dCk7XG4gICAgY29uc3QgZmFsbGJhY2tNZXRob2RzID0gdXNlQ29udGV4dChGYWxsYmFja0Zvcm1Db250ZXh0KTtcbiAgICBjb25zdCB3YXJuZWRSZWYgPSB1c2VSZWYobmV3IFNldCgpKTtcbiAgICBjb25zdCBtZXRob2RzID0gKF9hID0gY3R4ID09PSBudWxsIHx8IGN0eCA9PT0gdm9pZCAwID8gdm9pZCAwIDogY3R4Lm1ldGhvZHMpICE9PSBudWxsICYmIF9hICE9PSB2b2lkIDAgPyBfYSA6IGZhbGxiYWNrTWV0aG9kcztcbiAgICBpZiAoIW1ldGhvZHMpIHtcbiAgICAgICAgdGhyb3cgbmV3IEVycm9yKCdbRm9ybUl0ZW1dIE5vIGZvcm0gY29udHJvbCBmb3VuZC4gV3JhcCB3aXRoIDxGb3JtPiBvciBtb3VudCBpbnNpZGUgPEZhbGxiYWNrRm9ybVByb3ZpZGVyPi4nKTtcbiAgICB9XG4gICAgY29uc3QgY29udHJvbCA9IG1ldGhvZHMuY29udHJvbDtcbiAgICBjb25zdCB0cmlnZ2VyID0gbWV0aG9kcy50cmlnZ2VyO1xuICAgIHVzZUVmZmVjdCgoKSA9PiB7XG4gICAgICAgIGlmIChuYW1lICYmICEoY3R4ID09PSBudWxsIHx8IGN0eCA9PT0gdm9pZCAwID8gdm9pZCAwIDogY3R4Lm1ldGhvZHMpICYmICF3YXJuZWRSZWYuY3VycmVudC5oYXMobmFtZSkpIHtcbiAgICAgICAgICAgIHdhcm5lZFJlZi5jdXJyZW50LmFkZChuYW1lKTtcbiAgICAgICAgICAgIGNvbnNvbGUud2FybignW0Zvcm1JdGVtXSBgbmFtZWAgcHJvcCBpcyBzZXQgYnV0IG5vIGZvcm0gY29udHJvbCBmb3VuZC4gV3JhcCBGb3JtSXRlbSBpbnNpZGUgYSA8Rm9ybT4gY29tcG9uZW50LicpO1xuICAgICAgICB9XG4gICAgfSwgW25hbWUsIGN0eCA9PT0gbnVsbCB8fCBjdHggPT09IHZvaWQgMCA/IHZvaWQgMCA6IGN0eC5tZXRob2RzXSk7XG4gICAgcmV0dXJuIHsgY3R4LCBtZXRob2RzLCBjb250cm9sLCB0cmlnZ2VyIH07XG59Il0sInNvdXJjZVJvb3QiOiIuLi8uLi8uLi8uLi8uLi8uLi8uLi8uLi8uLi9zcmMifQ==

package/es/components/Form/useFormItemWatch.d.ts

@@ -0,0 +1,51 @@
+import type { Control, FieldPath, FieldValues, UseFormReturn } from 'react-hook-form';
+import type { FormItemProps } from './interface';
+/**
+ * Return type of {@link useFormItemWatch}.
+ *
+ * @template TFieldValues - The shape of the form values.
+ */
+interface UseFormItemWatchResult<TFieldValues extends FieldValues> {
+    /** Current snapshot of all form values. */
+    allValues: TFieldValues;
+    /** Watched dependency values (array when multiple, single value otherwise). */
+    depValues: unknown;
+    /** Whether the FormItem should render based on `shouldUpdate` evaluation. */
+    shouldRender: boolean;
+}
+/**
+ * Arguments for {@link useFormItemWatch}.
+ *
+ * @template TFieldValues - The shape of the form values.
+ */
+interface UseFormItemWatchArgs<TFieldValues extends FieldValues> {
+    /** The `react-hook-form` `Control` instance. */
+    control: Control<TFieldValues>;
+    /** The `react-hook-form` methods instance. */
+    methods: UseFormReturn<TFieldValues>;
+    /** Field paths that trigger re-validation when their values change. */
+    dependencies?: FormItemProps<TFieldValues>['dependencies'];
+    /** Additional field paths to watch for re-render. */
+    watchNames?: FormItemProps<TFieldValues>['watchNames'];
+    /** Controls when the FormItem re-renders. */
+    shouldUpdate?: FormItemProps<TFieldValues>['shouldUpdate'];
+    /** The field path for this FormItem. */
+    name?: FieldPath<TFieldValues>;
+}
+/**
+ * Consolidates the three `useWatch` subscriptions (dependencies, all values,
+ * and named watches) along with `allValues` derivation and `shouldRender`
+ * gating into a single hook.
+ *
+ * This hook manages:
+ * 1. Watching dependency fields for cross-field re-validation.
+ * 2. Watching all values when `shouldUpdate` requires a full-form comparison.
+ * 3. Watching named fields specified via `watchNames`.
+ * 4. Computing `shouldRender` based on the `shouldUpdate` prop.
+ *
+ * @template TFieldValues - The shape of the form values.
+ * @param args - {@link UseFormItemWatchArgs}
+ * @returns {@link UseFormItemWatchResult} containing current values and render gate.
+ */
+export declare function useFormItemWatch<TFieldValues extends FieldValues = FieldValues>({ control, methods, dependencies, watchNames, shouldUpdate, name, }: UseFormItemWatchArgs<TFieldValues>): UseFormItemWatchResult<TFieldValues>;
+export {};

package/es/components/Form/useFormItemWatch.js

@@ -0,0 +1,69 @@
+import { useMemo } from 'react';
+import { useWatch } from 'react-hook-form';
+import usePrevious from '../usePrevious';
+// Module-level constant to avoid recreating empty array on each render.
+var EMPTY_NAMES = [];
+/**
+ * Consolidates the three `useWatch` subscriptions (dependencies, all values,
+ * and named watches) along with `allValues` derivation and `shouldRender`
+ * gating into a single hook.
+ *
+ * This hook manages:
+ * 1. Watching dependency fields for cross-field re-validation.
+ * 2. Watching all values when `shouldUpdate` requires a full-form comparison.
+ * 3. Watching named fields specified via `watchNames`.
+ * 4. Computing `shouldRender` based on the `shouldUpdate` prop.
+ *
+ * @template TFieldValues - The shape of the form values.
+ * @param args - {@link UseFormItemWatchArgs}
+ * @returns {@link UseFormItemWatchResult} containing current values and render gate.
+ */
+export function useFormItemWatch(_ref) {
+  var control = _ref.control,
+    methods = _ref.methods,
+    dependencies = _ref.dependencies,
+    watchNames = _ref.watchNames,
+    shouldUpdate = _ref.shouldUpdate,
+    name = _ref.name;
+  var shouldWatchAllValues = shouldUpdate === true || typeof shouldUpdate === 'function';
+  var depNames = (dependencies === null || dependencies === void 0 ? void 0 : dependencies.length) ? dependencies : EMPTY_NAMES;
+  var shouldWatchDeps = !!(name && depNames.length);
+  var watchNamesList = (watchNames === null || watchNames === void 0 ? void 0 : watchNames.length) ? watchNames : EMPTY_NAMES;
+  var shouldWatchNames = !!(watchNames === null || watchNames === void 0 ? void 0 : watchNames.length);
+  var depValues = useWatch({
+    control: control,
+    name: depNames,
+    disabled: !shouldWatchDeps
+  });
+  var watchedAllValues = useWatch({
+    control: control,
+    disabled: !shouldWatchAllValues
+  });
+  var watchedNamesValues = useWatch({
+    control: control,
+    name: watchNamesList,
+    disabled: !shouldWatchNames
+  });
+  var allValues = useMemo(function () {
+    var getValues = methods.getValues;
+    if (!getValues) return {};
+    if (shouldWatchAllValues) return watchedAllValues !== null && watchedAllValues !== void 0 ? watchedAllValues : getValues();
+    return getValues();
+  }, [methods, shouldWatchAllValues, watchedAllValues,
+  // Intentionally unused in useMemo body: this dependency forces `allValues`
+  // to recompute via methods.getValues() when watched names change while
+  // `shouldWatchAllValues` is false.
+  watchedNamesValues]);
+  var prevValues = usePrevious(allValues);
+  var shouldRender = useMemo(function () {
+    if (!shouldUpdate || shouldUpdate === true) return true;
+    if (prevValues === undefined) return true;
+    return shouldUpdate(prevValues, allValues);
+  }, [allValues, prevValues, shouldUpdate]);
+  return {
+    allValues: allValues,
+    depValues: depValues,
+    shouldRender: shouldRender
+  };
+}
+//# sourceMappingURL=data:application/json;charset=utf8;base64,eyJ2ZXJzaW9uIjozLCJzb3VyY2VzIjpbImNvbXBvbmVudHMvc3JjL2NvbXBvbmVudHMvRm9ybS91c2VGb3JtSXRlbVdhdGNoLnRzIiwiY29tcG9uZW50cy9Gb3JtL3VzZUZvcm1JdGVtV2F0Y2guanMiXSwibmFtZXMiOlsidXNlTWVtbyIsInVzZVdhdGNoIiwidXNlUHJldmlvdXMiLCJFTVBUWV9OQU1FUyIsInVzZUZvcm1JdGVtV2F0Y2giLCJfcmVmIiwiY29udHJvbCIsIm1ldGhvZHMiLCJkZXBlbmRlbmNpZXMiLCJ3YXRjaE5hbWVzIiwic2hvdWxkVXBkYXRlIiwibmFtZSIsInNob3VsZFdhdGNoQWxsVmFsdWVzIiwiZGVwTmFtZXMiLCJsZW5ndGgiLCJzaG91bGRXYXRjaERlcHMiLCJ3YXRjaE5hbWVzTGlzdCIsInNob3VsZFdhdGNoTmFtZXMiLCJkZXBWYWx1ZXMiLCJkaXNhYmxlZCIsIndhdGNoZWRBbGxWYWx1ZXMiLCJ3YXRjaGVkTmFtZXNWYWx1ZXMiLCJhbGxWYWx1ZXMiLCJnZXRWYWx1ZXMiLCJwcmV2VmFsdWVzIiwic2hvdWxkUmVuZGVyIiwidW5kZWZpbmVkIl0sIm1hcHBpbmdzIjoiQUFBQSxTQUFTQSxPQUFPLFFBQVEsT0FBTztBQUMvQixTQUFTQyxRQUFRLFFBQVEsaUJBQWlCO0FBQzFDLE9BQU9DLFdBQVcsTUFBTSxnQkFBZ0I7QUFzQ3hDO0FBQ0EsSUFBTUMsV0FBVyxHQUFZLEVBQUU7QUFFL0I7QUNyQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBRHVDQSxPQUFNLFNBQVVDLGdCQUFnQkEsQ0FBQUMsSUFBQSxFQU9LO0VBQUEsSUFObkNDLE9BQU8sR0FBQUQsSUFBQSxDQUFQQyxPQUFPO0lBQ1BDLE9BQU8sR0FBQUYsSUFBQSxDQUFQRSxPQUFPO0lBQ1BDLFlBQVksR0FBQUgsSUFBQSxDQUFaRyxZQUFZO0lBQ1pDLFVBQVUsR0FBQUosSUFBQSxDQUFWSSxVQUFVO0lBQ1ZDLFlBQVksR0FBQUwsSUFBQSxDQUFaSyxZQUFZO0lBQ1pDLElBQUksR0FBQU4sSUFBQSxDQUFKTSxJQUFJO0VBRUosSUFBTUMsb0JBQW9CLEdBQUdGLFlBQVksS0FBSyxJQUFJLElBQUksT0FBT0EsWUFBWSxLQUFLLFVBQVU7RUFDeEYsSUFBTUcsUUFBUSxHQUFJLENBQUFMLFlBQVksS0FBQSxJQUFBLElBQVpBLFlBQVksS0FBQSxLQUFBLENBQUEsR0FBQSxLQUFBLENBQUEsR0FBWkEsWUFBWSxDQUFFTSxNQUFNLElBQUdOLFlBQVksR0FBR0wsV0FBeUM7RUFDakcsSUFBTVksZUFBZSxHQUFHLENBQUMsRUFBRUosSUFBSSxJQUFJRSxRQUFRLENBQUNDLE1BQU0sQ0FBQztFQUNuRCxJQUFNRSxjQUFjLEdBQUksQ0FBQVAsVUFBVSxLQUFBLElBQUEsSUFBVkEsVUFBVSxLQUFBLEtBQUEsQ0FBQSxHQUFBLEtBQUEsQ0FBQSxHQUFWQSxVQUFVLENBQUVLLE1BQU0sSUFBR0wsVUFBVSxHQUFHTixXQUF5QztFQUNuRyxJQUFNYyxnQkFBZ0IsR0FBRyxDQUFDLEVBQUNSLFVBQVUsS0FBQSxJQUFBLElBQVZBLFVBQVUsS0FBQSxLQUFBLENBQUEsR0FBQSxLQUFBLENBQUEsR0FBVkEsVUFBVSxDQUFFSyxNQUFNLENBQUE7RUFFN0MsSUFBTUksU0FBUyxHQUFHakIsUUFBUSxDQUFDO0lBQUVLLE9BQU8sRUFBUEEsT0FBTztJQUFFSyxJQUFJLEVBQUVFLFFBQVE7SUFBRU0sUUFBUSxFQUFFLENBQUNKO0VBQWUsQ0FBRSxDQUFDO0VBQ25GLElBQU1LLGdCQUFnQixHQUFHbkIsUUFBUSxDQUFDO0lBQUVLLE9BQU8sRUFBUEEsT0FBTztJQUFFYSxRQUFRLEVBQUUsQ0FBQ1A7RUFBb0IsQ0FBRSxDQUFDO0VBQy9FLElBQU1TLGtCQUFrQixHQUFHcEIsUUFBUSxDQUFDO0lBQ2xDSyxPQUFPLEVBQVBBLE9BQU87SUFDUEssSUFBSSxFQUFFSyxjQUFjO0lBQ3BCRyxRQUFRLEVBQUUsQ0FBQ0Y7RUM3Q1gsQ0Q4Q0QsQ0FBQztFQUVGLElBQU1LLFNBQVMsR0FBR3RCLE9BQU8sQ0FBQyxZQUFLO0lBQzdCLElBQU11QixTQUFTLEdBQUdoQixPQUFPLENBQUNnQixTQUFTO0lBQ25DLElBQUksQ0FBQ0EsU0FBUyxFQUFFLE9BQU8sQ0FBQSxDQUFrQjtJQUN6QyxJQUFJWCxvQkFBb0IsRUFBRSxPQUFRUSxnQkFBZ0IsS0FBQSxJQUFBLElBQWhCQSxnQkFBZ0IsS0FBQSxLQUFBLENBQUEsR0FBaEJBLGdCQUFnQixHQUFJRyxTQUFTLENBQUEsQ0FBRTtJQUNqRSxPQUFPQSxTQUFTLENBQUEsQ0FBRTtFQUNwQixDQUFDLEVBQUUsQ0FDRGhCLE9BQU8sRUFDUEssb0JBQW9CLEVBQ3BCUSxnQkFBZ0I7RUFDaEI7RUFDQTtFQUNBO0VBQ0FDLGtCQUFrQixDQUNuQixDQUFDO0VBRUYsSUFBTUcsVUFBVSxHQUFHdEIsV0FBVyxDQUFDb0IsU0FBUyxDQUFDO0VBRXpDLElBQU1HLFlBQVksR0FBR3pCLE9BQU8sQ0FBQyxZQUFLO0lBQ2hDLElBQUksQ0FBQ1UsWUFBWSxJQUFJQSxZQUFZLEtBQUssSUFBSSxFQUFFLE9BQU8sSUFBSTtJQUN2RCxJQUFJYyxVQUFVLEtBQUtFLFNBQVMsRUFBRSxPQUFPLElBQUk7SUFDekMsT0FBT2hCLFlBQVksQ0FBQ2MsVUFBVSxFQUFFRixTQUFTLENBQUM7RUFDNUMsQ0FBQyxFQUFFLENBQUNBLFNBQVMsRUFBRUUsVUFBVSxFQUFFZCxZQUFZLENBQUMsQ0FBQztFQUV6QyxPQUFPO0lBQUVZLFNBQVMsRUFBVEEsU0FBUztJQUFFSixTQUFTLEVBQVRBLFNBQVM7SUFBRU8sWUFBWSxFQUFaQTtFQUFZLENBQUU7QUFDL0MiLCJmaWxlIjoiY29tcG9uZW50cy9Gb3JtL3VzZUZvcm1JdGVtV2F0Y2guanMiLCJzb3VyY2VzQ29udGVudCI6W251bGwsImltcG9ydCB7IHVzZU1lbW8gfSBmcm9tICdyZWFjdCc7XG5pbXBvcnQgeyB1c2VXYXRjaCB9IGZyb20gJ3JlYWN0LWhvb2stZm9ybSc7XG5pbXBvcnQgdXNlUHJldmlvdXMgZnJvbSAnLi4vdXNlUHJldmlvdXMnO1xuLy8gTW9kdWxlLWxldmVsIGNvbnN0YW50IHRvIGF2b2lkIHJlY3JlYXRpbmcgZW1wdHkgYXJyYXkgb24gZWFjaCByZW5kZXIuXG5jb25zdCBFTVBUWV9OQU1FUyA9IFtdO1xuLyoqXG4gKiBDb25zb2xpZGF0ZXMgdGhlIHRocmVlIGB1c2VXYXRjaGAgc3Vic2NyaXB0aW9ucyAoZGVwZW5kZW5jaWVzLCBhbGwgdmFsdWVzLFxuICogYW5kIG5hbWVkIHdhdGNoZXMpIGFsb25nIHdpdGggYGFsbFZhbHVlc2AgZGVyaXZhdGlvbiBhbmQgYHNob3VsZFJlbmRlcmBcbiAqIGdhdGluZyBpbnRvIGEgc2luZ2xlIGhvb2suXG4gKlxuICogVGhpcyBob29rIG1hbmFnZXM6XG4gKiAxLiBXYXRjaGluZyBkZXBlbmRlbmN5IGZpZWxkcyBmb3IgY3Jvc3MtZmllbGQgcmUtdmFsaWRhdGlvbi5cbiAqIDIuIFdhdGNoaW5nIGFsbCB2YWx1ZXMgd2hlbiBgc2hvdWxkVXBkYXRlYCByZXF1aXJlcyBhIGZ1bGwtZm9ybSBjb21wYXJpc29uLlxuICogMy4gV2F0Y2hpbmcgbmFtZWQgZmllbGRzIHNwZWNpZmllZCB2aWEgYHdhdGNoTmFtZXNgLlxuICogNC4gQ29tcHV0aW5nIGBzaG91bGRSZW5kZXJgIGJhc2VkIG9uIHRoZSBgc2hvdWxkVXBkYXRlYCBwcm9wLlxuICpcbiAqIEB0ZW1wbGF0ZSBURmllbGRWYWx1ZXMgLSBUaGUgc2hhcGUgb2YgdGhlIGZvcm0gdmFsdWVzLlxuICogQHBhcmFtIGFyZ3MgLSB7QGxpbmsgVXNlRm9ybUl0ZW1XYXRjaEFyZ3N9XG4gKiBAcmV0dXJucyB7QGxpbmsgVXNlRm9ybUl0ZW1XYXRjaFJlc3VsdH0gY29udGFpbmluZyBjdXJyZW50IHZhbHVlcyBhbmQgcmVuZGVyIGdhdGUuXG4gKi9cbmV4cG9ydCBmdW5jdGlvbiB1c2VGb3JtSXRlbVdhdGNoKHsgY29udHJvbCwgbWV0aG9kcywgZGVwZW5kZW5jaWVzLCB3YXRjaE5hbWVzLCBzaG91bGRVcGRhdGUsIG5hbWUsIH0pIHtcbiAgICBjb25zdCBzaG91bGRXYXRjaEFsbFZhbHVlcyA9IHNob3VsZFVwZGF0ZSA9PT0gdHJ1ZSB8fCB0eXBlb2Ygc2hvdWxkVXBkYXRlID09PSAnZnVuY3Rpb24nO1xuICAgIGNvbnN0IGRlcE5hbWVzID0gKChkZXBlbmRlbmNpZXMgPT09IG51bGwgfHwgZGVwZW5kZW5jaWVzID09PSB2b2lkIDAgPyB2b2lkIDAgOiBkZXBlbmRlbmNpZXMubGVuZ3RoKSA/IGRlcGVuZGVuY2llcyA6IEVNUFRZX05BTUVTKTtcbiAgICBjb25zdCBzaG91bGRXYXRjaERlcHMgPSAhIShuYW1lICYmIGRlcE5hbWVzLmxlbmd0aCk7XG4gICAgY29uc3Qgd2F0Y2hOYW1lc0xpc3QgPSAoKHdhdGNoTmFtZXMgPT09IG51bGwgfHwgd2F0Y2hOYW1lcyA9PT0gdm9pZCAwID8gdm9pZCAwIDogd2F0Y2hOYW1lcy5sZW5ndGgpID8gd2F0Y2hOYW1lcyA6IEVNUFRZX05BTUVTKTtcbiAgICBjb25zdCBzaG91bGRXYXRjaE5hbWVzID0gISEod2F0Y2hOYW1lcyA9PT0gbnVsbCB8fCB3YXRjaE5hbWVzID09PSB2b2lkIDAgPyB2b2lkIDAgOiB3YXRjaE5hbWVzLmxlbmd0aCk7XG4gICAgY29uc3QgZGVwVmFsdWVzID0gdXNlV2F0Y2goeyBjb250cm9sLCBuYW1lOiBkZXBOYW1lcywgZGlzYWJsZWQ6ICFzaG91bGRXYXRjaERlcHMgfSk7XG4gICAgY29uc3Qgd2F0Y2hlZEFsbFZhbHVlcyA9IHVzZVdhdGNoKHsgY29udHJvbCwgZGlzYWJsZWQ6ICFzaG91bGRXYXRjaEFsbFZhbHVlcyB9KTtcbiAgICBjb25zdCB3YXRjaGVkTmFtZXNWYWx1ZXMgPSB1c2VXYXRjaCh7XG4gICAgICAgIGNvbnRyb2wsXG4gICAgICAgIG5hbWU6IHdhdGNoTmFtZXNMaXN0LFxuICAgICAgICBkaXNhYmxlZDogIXNob3VsZFdhdGNoTmFtZXMsXG4gICAgfSk7XG4gICAgY29uc3QgYWxsVmFsdWVzID0gdXNlTWVtbygoKSA9PiB7XG4gICAgICAgIGNvbnN0IGdldFZhbHVlcyA9IG1ldGhvZHMuZ2V0VmFsdWVzO1xuICAgICAgICBpZiAoIWdldFZhbHVlcylcbiAgICAgICAgICAgIHJldHVybiB7fTtcbiAgICAgICAgaWYgKHNob3VsZFdhdGNoQWxsVmFsdWVzKVxuICAgICAgICAgICAgcmV0dXJuICh3YXRjaGVkQWxsVmFsdWVzICE9PSBudWxsICYmIHdhdGNoZWRBbGxWYWx1ZXMgIT09IHZvaWQgMCA/IHdhdGNoZWRBbGxWYWx1ZXMgOiBnZXRWYWx1ZXMoKSk7XG4gICAgICAgIHJldHVybiBnZXRWYWx1ZXMoKTtcbiAgICB9LCBbXG4gICAgICAgIG1ldGhvZHMsXG4gICAgICAgIHNob3VsZFdhdGNoQWxsVmFsdWVzLFxuICAgICAgICB3YXRjaGVkQWxsVmFsdWVzLFxuICAgICAgICAvLyBJbnRlbnRpb25hbGx5IHVudXNlZCBpbiB1c2VNZW1vIGJvZHk6IHRoaXMgZGVwZW5kZW5jeSBmb3JjZXMgYGFsbFZhbHVlc2BcbiAgICAgICAgLy8gdG8gcmVjb21wdXRlIHZpYSBtZXRob2RzLmdldFZhbHVlcygpIHdoZW4gd2F0Y2hlZCBuYW1lcyBjaGFuZ2Ugd2hpbGVcbiAgICAgICAgLy8gYHNob3VsZFdhdGNoQWxsVmFsdWVzYCBpcyBmYWxzZS5cbiAgICAgICAgd2F0Y2hlZE5hbWVzVmFsdWVzLFxuICAgIF0pO1xuICAgIGNvbnN0IHByZXZWYWx1ZXMgPSB1c2VQcmV2aW91cyhhbGxWYWx1ZXMpO1xuICAgIGNvbnN0IHNob3VsZFJlbmRlciA9IHVzZU1lbW8oKCkgPT4ge1xuICAgICAgICBpZiAoIXNob3VsZFVwZGF0ZSB8fCBzaG91bGRVcGRhdGUgPT09IHRydWUpXG4gICAgICAgICAgICByZXR1cm4gdHJ1ZTtcbiAgICAgICAgaWYgKHByZXZWYWx1ZXMgPT09IHVuZGVmaW5lZClcbiAgICAgICAgICAgIHJldHVybiB0cnVlO1xuICAgICAgICByZXR1cm4gc2hvdWxkVXBkYXRlKHByZXZWYWx1ZXMsIGFsbFZhbHVlcyk7XG4gICAgfSwgW2FsbFZhbHVlcywgcHJldlZhbHVlcywgc2hvdWxkVXBkYXRlXSk7XG4gICAgcmV0dXJuIHsgYWxsVmFsdWVzLCBkZXBWYWx1ZXMsIHNob3VsZFJlbmRlciB9O1xufSJdLCJzb3VyY2VSb290IjoiLi4vLi4vLi4vLi4vLi4vLi4vLi4vLi4vLi4vc3JjIn0=

package/es/components/Form/useValidationTrigger.d.ts

@@ -0,0 +1,40 @@
+import type { FieldPath, FieldValues } from 'react-hook-form';
+import type { FormItemProps } from './interface';
+/**
+ * Arguments for {@link useValidationTrigger}.
+ *
+ * @template TFieldValues - The shape of the form values.
+ */
+interface UseValidationTriggerArgs<TFieldValues extends FieldValues> {
+    /** The field path to validate. When `undefined`, validation is skipped. */
+    name?: FieldPath<TFieldValues>;
+    /** The `trigger` function from `react-hook-form` for imperative validation. */
+    trigger: (name: FieldPath<TFieldValues>) => Promise<boolean>;
+    /** Event(s) that should trigger validation (`'onChange'`, `'onBlur'`, or both). */
+    validateTrigger?: FormItemProps<TFieldValues>['validateTrigger'];
+    /** Debounce delay in milliseconds for triggered validation. */
+    validateDebounce?: number;
+    /** Field paths whose changes should re-trigger this field's validation. */
+    dependencies?: FormItemProps<TFieldValues>['dependencies'];
+    /** Current watched dependency values used to detect changes. */
+    depValues: unknown;
+}
+/**
+ * Encapsulates validation trigger logic for a single form field.
+ *
+ * Responsibilities:
+ * - Normalizes the `validateTrigger` prop into an array of trigger modes.
+ * - Provides a `withTrigger` wrapper that composes event handlers (onChange/onBlur)
+ *   with conditional validation calls.
+ * - Applies optional debounce to validation triggers.
+ * - Re-validates the field when dependency values change (cross-field validation).
+ * - Cleans up debounce timers on unmount.
+ *
+ * @template TFieldValues - The shape of the form values.
+ * @param args - {@link UseValidationTriggerArgs}
+ * @returns An object containing the `withTrigger` function.
+ */
+export declare function useValidationTrigger<TFieldValues extends FieldValues = FieldValues>({ name, trigger, validateTrigger, validateDebounce, dependencies, depValues, }: UseValidationTriggerArgs<TFieldValues>): {
+    withTrigger: (mode: "onBlur" | "onChange", fn?: ((...args: unknown[]) => void) | undefined) => (...args: unknown[]) => void;
+};
+export {};

package/es/components/Form/useValidationTrigger.js

@@ -0,0 +1,74 @@
+import { useEffect, useMemo, useRef } from 'react';
+import useMemoizedFn from '../useMemoizedFn';
+import { DEBOUNCE_MIN } from './constants';
+import { normalizeValidateTrigger, shallowEqualArray } from './helper';
+/**
+ * Encapsulates validation trigger logic for a single form field.
+ *
+ * Responsibilities:
+ * - Normalizes the `validateTrigger` prop into an array of trigger modes.
+ * - Provides a `withTrigger` wrapper that composes event handlers (onChange/onBlur)
+ *   with conditional validation calls.
+ * - Applies optional debounce to validation triggers.
+ * - Re-validates the field when dependency values change (cross-field validation).
+ * - Cleans up debounce timers on unmount.
+ *
+ * @template TFieldValues - The shape of the form values.
+ * @param args - {@link UseValidationTriggerArgs}
+ * @returns An object containing the `withTrigger` function.
+ */
+export function useValidationTrigger(_ref) {
+  var name = _ref.name,
+    trigger = _ref.trigger,
+    validateTrigger = _ref.validateTrigger,
+    validateDebounce = _ref.validateDebounce,
+    dependencies = _ref.dependencies,
+    depValues = _ref.depValues;
+  var triggerTimerRef = useRef(null);
+  var prevDepValuesRef = useRef(null);
+  var triggerModes = useMemo(function () {
+    return normalizeValidateTrigger(validateTrigger);
+  }, [validateTrigger]);
+  var triggerValidation = useMemoizedFn(function () {
+    if (!name) return;
+    var run = function run() {
+      void trigger(name);
+    };
+    if (validateDebounce && validateDebounce > DEBOUNCE_MIN) {
+      if (triggerTimerRef.current) clearTimeout(triggerTimerRef.current);
+      triggerTimerRef.current = setTimeout(run, validateDebounce);
+      return;
+    }
+    run();
+  });
+  useEffect(function () {
+    if (!name || !(dependencies === null || dependencies === void 0 ? void 0 : dependencies.length)) return;
+    var nextDeps = Array.isArray(depValues) ? depValues : [depValues];
+    var prevDeps = prevDepValuesRef.current;
+    if (!prevDeps) {
+      prevDepValuesRef.current = nextDeps;
+      return;
+    }
+    if (shallowEqualArray(prevDeps, nextDeps)) return;
+    prevDepValuesRef.current = nextDeps;
+    triggerValidation();
+  }, [depValues, dependencies === null || dependencies === void 0 ? void 0 : dependencies.length, name, triggerValidation]);
+  useEffect(function () {
+    return function () {
+      if (triggerTimerRef.current) clearTimeout(triggerTimerRef.current);
+    };
+  }, []);
+  var shouldTrigger = useMemoizedFn(function (mode) {
+    return triggerModes.includes(mode);
+  });
+  var withTrigger = useMemoizedFn(function (mode, fn) {
+    return function () {
+      fn === null || fn === void 0 ? void 0 : fn.apply(void 0, arguments);
+      if (name && shouldTrigger(mode)) triggerValidation();
+    };
+  });
+  return {
+    withTrigger: withTrigger
+  };
+}
+//# sourceMappingURL=data:application/json;charset=utf8;base64,eyJ2ZXJzaW9uIjozLCJzb3VyY2VzIjpbImNvbXBvbmVudHMvc3JjL2NvbXBvbmVudHMvRm9ybS91c2VWYWxpZGF0aW9uVHJpZ2dlci50cyIsImNvbXBvbmVudHMvRm9ybS91c2VWYWxpZGF0aW9uVHJpZ2dlci5qcyJdLCJuYW1lcyI6WyJ1c2VFZmZlY3QiLCJ1c2VNZW1vIiwidXNlUmVmIiwidXNlTWVtb2l6ZWRGbiIsIkRFQk9VTkNFX01JTiIsIm5vcm1hbGl6ZVZhbGlkYXRlVHJpZ2dlciIsInNoYWxsb3dFcXVhbEFycmF5IiwidXNlVmFsaWRhdGlvblRyaWdnZXIiLCJfcmVmIiwibmFtZSIsInRyaWdnZXIiLCJ2YWxpZGF0ZVRyaWdnZXIiLCJ2YWxpZGF0ZURlYm91bmNlIiwiZGVwZW5kZW5jaWVzIiwiZGVwVmFsdWVzIiwidHJpZ2dlclRpbWVyUmVmIiwicHJldkRlcFZhbHVlc1JlZiIsInRyaWdnZXJNb2RlcyIsInRyaWdnZXJWYWxpZGF0aW9uIiwicnVuIiwiY3VycmVudCIsImNsZWFyVGltZW91dCIsInNldFRpbWVvdXQiLCJsZW5ndGgiLCJuZXh0RGVwcyIsIkFycmF5IiwiaXNBcnJheSIsInByZXZEZXBzIiwic2hvdWxkVHJpZ2dlciIsIm1vZGUiLCJpbmNsdWRlcyIsIndpdGhUcmlnZ2VyIiwiZm4iLCJhcHBseSIsImFyZ3VtZW50cyJdLCJtYXBwaW5ncyI6IkFBQUEsU0FBU0EsU0FBUyxFQUFFQyxPQUFPLEVBQUVDLE1BQU0sUUFBUSxPQUFPO0FBQ2xELE9BQU9DLGFBQWEsTUFBTSxrQkFBa0I7QUFFNUMsU0FBU0MsWUFBWSxRQUFzQyxhQUFhO0FBQ3hFLFNBQVNDLHdCQUF3QixFQUFFQyxpQkFBaUIsUUFBUSxVQUFVO0FBdUJ0RTtBQ3RCQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FEd0JBLE9BQU0sU0FBVUMsb0JBQW9CQSxDQUFBQyxJQUFBLEVBT0s7RUFBQSxJQU52Q0MsSUFBSSxHQUFBRCxJQUFBLENB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QUFFWCxpQkFBaUIsQ0FBQSxDQUFFO0lBQ3RELENBQUM7RUFBQSxFQUNKO0VBRUQsT0FBTztJQUFFYSxXQUFXLEVBQVhBO0VBQVcsQ0FBRTtBQUN4QiIsImZpbGUiOiJjb21wb25lbnRzL0Zvcm0vdXNlVmFsaWRhdGlvblRyaWdnZXIuanMiLCJzb3VyY2VzQ29udGVudCI6W251bGwsImltcG9ydCB7IHVzZUVmZmVjdCwgdXNlTWVtbywgdXNlUmVmIH0gZnJvbSAncmVhY3QnO1xuaW1wb3J0IHVzZU1lbW9pemVkRm4gZnJvbSAnLi4vdXNlTWVtb2l6ZWRGbic7XG5pbXBvcnQgeyBERUJPVU5DRV9NSU4gfSBmcm9tICcuL2NvbnN0YW50cyc7XG5pbXBvcnQgeyBub3JtYWxpemVWYWxpZGF0ZVRyaWdnZXIsIHNoYWxsb3dFcXVhbEFycmF5IH0gZnJvbSAnLi9oZWxwZXInO1xuLyoqXG4gKiBFbmNhcHN1bGF0ZXMgdmFsaWRhdGlvbiB0cmlnZ2VyIGxvZ2ljIGZvciBhIHNpbmdsZSBmb3JtIGZpZWxkLlxuICpcbiAqIFJlc3BvbnNpYmlsaXRpZXM6XG4gKiAtIE5vcm1hbGl6ZXMgdGhlIGB2YWxpZGF0ZVRyaWdnZXJgIHByb3AgaW50byBhbiBhcnJheSBvZiB0cmlnZ2VyIG1vZGVzLlxuICogLSBQcm92aWRlcyBhIGB3aXRoVHJpZ2dlcmAgd3JhcHBlciB0aGF0IGNvbXBvc2VzIGV2ZW50IGhhbmRsZXJzIChvbkNoYW5nZS9vbkJsdXIpXG4gKiAgIHdpdGggY29uZGl0aW9uYWwgdmFsaWRhdGlvbiBjYWxscy5cbiAqIC0gQXBwbGllcyBvcHRpb25hbCBkZWJvdW5jZSB0byB2YWxpZGF0aW9uIHRyaWdnZXJzLlxuICogLSBSZS12YWxpZGF0ZXMgdGhlIGZpZWxkIHdoZW4gZGVwZW5kZW5jeSB2YWx1ZXMgY2hhbmdlIChjcm9zcy1maWVsZCB2YWxpZGF0aW9uKS5cbiAqIC0gQ2xlYW5zIHVwIGRlYm91bmNlIHRpbWVycyBvbiB1bm1vdW50LlxuICpcbiAqIEB0ZW1wbGF0ZSBURmllbGRWYWx1ZXMgLSBUaGUgc2hhcGUgb2YgdGhlIGZvcm0gdmFsdWVzLlxuICogQHBhcmFtIGFyZ3MgLSB7QGxpbmsgVXNlVmFsaWRhdGlvblRyaWdnZXJBcmdzfVxuICogQHJldHVybnMgQW4gb2JqZWN0IGNvbnRhaW5pbmcgdGhlIGB3aXRoVHJpZ2dlcmAgZnVuY3Rpb24uXG4gKi9cbmV4cG9ydCBmdW5jdGlvbiB1c2VWYWxpZGF0aW9uVHJpZ2dlcih7IG5hbWUsIHRyaWdnZXIsIHZhbGlkYXRlVHJpZ2dlciwgdmFsaWRhdGVEZWJvdW5jZSwgZGVwZW5kZW5jaWVzLCBkZXBWYWx1ZXMsIH0pIHtcbiAgICBjb25zdCB0cmlnZ2VyVGltZXJSZWYgPSB1c2VSZWYobnVsbCk7XG4gICAgY29uc3QgcHJldkRlcFZhbHVlc1JlZiA9IHVzZVJlZihudWxsKTtcbiAgICBjb25zdCB0cmlnZ2VyTW9kZXMgPSB1c2VNZW1vKCgpID0+IG5vcm1hbGl6ZVZhbGlkYXRlVHJpZ2dlcih2YWxpZGF0ZVRyaWdnZXIpLCBbdmFsaWRhdGVUcmlnZ2VyXSk7XG4gICAgY29uc3QgdHJpZ2dlclZhbGlkYXRpb24gPSB1c2VNZW1vaXplZEZuKCgpID0+IHtcbiAgICAgICAgaWYgKCFuYW1lKVxuICAgICAgICAgICAgcmV0dXJuO1xuICAgICAgICBjb25zdCBydW4gPSAoKSA9PiB7XG4gICAgICAgICAgICB2b2lkIHRyaWdnZXIobmFtZSk7XG4gICAgICAgIH07XG4gICAgICAgIGlmICh2YWxpZGF0ZURlYm91bmNlICYmIHZhbGlkYXRlRGVib3VuY2UgPiBERUJPVU5DRV9NSU4pIHtcbiAgICAgICAgICAgIGlmICh0cmlnZ2VyVGltZXJSZWYuY3VycmVudClcbiAgICAgICAgICAgICAgICBjbGVhclRpbWVvdXQodHJpZ2dlclRpbWVyUmVmLmN1cnJlbnQpO1xuICAgICAgICAgICAgdHJpZ2dlclRpbWVyUmVmLmN1cnJlbnQgPSBzZXRUaW1lb3V0KHJ1biwgdmFsaWRhdGVEZWJvdW5jZSk7XG4gICAgICAgICAgICByZXR1cm47XG4gICAgICAgIH1cbiAgICAgICAgcnVuKCk7XG4gICAgfSk7XG4gICAgdXNlRWZmZWN0KCgpID0+IHtcbiAgICAgICAgaWYgKCFuYW1lIHx8ICEoZGVwZW5kZW5jaWVzID09PSBudWxsIHx8IGRlcGVuZGVuY2llcyA9PT0gdm9pZCAwID8gdm9pZCAwIDogZGVwZW5kZW5jaWVzLmxlbmd0aCkpXG4gICAgICAgICAgICByZXR1cm47XG4gICAgICAgIGNvbnN0IG5leHREZXBzID0gQXJyYXkuaXNBcnJheShkZXBWYWx1ZXMpID8gZGVwVmFsdWVzIDogW2RlcFZhbHVlc107XG4gICAgICAgIGNvbnN0IHByZXZEZXBzID0gcHJldkRlcFZhbHVlc1JlZi5jdXJyZW50O1xuICAgICAgICBpZiAoIXByZXZEZXBzKSB7XG4gICAgICAgICAgICBwcmV2RGVwVmFsdWVzUmVmLmN1cnJlbnQgPSBuZXh0RGVwcztcbiAgICAgICAgICAgIHJldHVybjtcbiAgICAgICAgfVxuICAgICAgICBpZiAoc2hhbGxvd0VxdWFsQXJyYXkocHJldkRlcHMsIG5leHREZXBzKSlcbiAgICAgICAgICAgIHJldHVybjtcbiAgICAgICAgcHJldkRlcFZhbHVlc1JlZi5jdXJyZW50ID0gbmV4dERlcHM7XG4gICAgICAgIHRyaWdnZXJWYWxpZGF0aW9uKCk7XG4gICAgfSwgW2RlcFZhbHVlcywgZGVwZW5kZW5jaWVzID09PSBudWxsIHx8IGRlcGVuZGVuY2llcyA9PT0gdm9pZCAwID8gdm9pZCAwIDogZGVwZW5kZW5jaWVzLmxlbmd0aCwgbmFtZSwgdHJpZ2dlclZhbGlkYXRpb25dKTtcbiAgICB1c2VFZmZlY3QoKCkgPT4gKCkgPT4ge1xuICAgICAgICBpZiAodHJpZ2dlclRpbWVyUmVmLmN1cnJlbnQpXG4gICAgICAgICAgICBjbGVhclRpbWVvdXQodHJpZ2dlclRpbWVyUmVmLmN1cnJlbnQpO1xuICAgIH0sIFtdKTtcbiAgICBjb25zdCBzaG91bGRUcmlnZ2VyID0gdXNlTWVtb2l6ZWRGbigobW9kZSkgPT4gdHJpZ2dlck1vZGVzLmluY2x1ZGVzKG1vZGUpKTtcbiAgICBjb25zdCB3aXRoVHJpZ2dlciA9IHVzZU1lbW9pemVkRm4oKG1vZGUsIGZuKSA9PiAoLi4uYXJncykgPT4ge1xuICAgICAgICBmbiA9PT0gbnVsbCB8fCBmbiA9PT0gdm9pZCAwID8gdm9pZCAwIDogZm4oLi4uYXJncyk7XG4gICAgICAgIGlmIChuYW1lICYmIHNob3VsZFRyaWdnZXIobW9kZSkpXG4gICAgICAgICAgICB0cmlnZ2VyVmFsaWRhdGlvbigpO1xuICAgIH0pO1xuICAgIHJldHVybiB7IHdpdGhUcmlnZ2VyIH07XG59Il0sInNvdXJjZVJvb3QiOiIuLi8uLi8uLi8uLi8uLi8uLi8uLi8uLi8uLi9zcmMifQ==