@1money/react-ui 1.15.3 → 1.17.0

package/lib/components/Form/interface.d.ts

@@ -0,0 +1,238 @@
+import type { CSSProperties, ReactNode } from 'react';
+import type { Control, DefaultValues, FieldErrors, FieldPath, FieldPathValue, FieldValues, RegisterOptions, UseFormProps, UseFormReturn, ControllerRenderProps, ControllerFieldState } from 'react-hook-form';
+import type { TRIGGER_BLUR, TRIGGER_CHANGE } from './constants';
+/**
+ * Subset of `RegisterOptions` used by `FormItem` for declarative validation rules.
+ *
+ * @template TFieldValues - The shape of the form values.
+ */
+export type FormItemRules<TFieldValues extends FieldValues = FieldValues> = Pick<RegisterOptions<TFieldValues>, 'required' | 'min' | 'max' | 'minLength' | 'maxLength' | 'pattern' | 'validate' | 'deps'>;
+/** Form layout direction. */
+export type FormLayout = 'horizontal' | 'vertical' | 'inline';
+/** Label text alignment within the label column. */
+export type FormLabelAlign = 'left' | 'right';
+/** Form size variant applied to all child items. */
+export type FormSize = 'small' | 'middle' | 'large';
+/** Validation status used for visual feedback on a form field. */
+export type FormValidateStatus = 'success' | 'warning' | 'error' | 'validating';
+/**
+ * Shared context value provided by `<Form>` to all descendant `<FormItem>` components.
+ */
+export interface FormContextValue {
+    /** Layout direction for the form. */
+    layout: FormLayout;
+    /** Alignment of labels within the label column. */
+    labelAlign: FormLabelAlign;
+    /** Label column span in a 12-column grid (0–12). */
+    labelCol: number;
+    /** Wrapper/control column span in a 12-column grid (0–12). */
+    wrapperCol: number;
+    /** Size variant applied to all form items. */
+    size: FormSize;
+    /** When `true`, all form fields are disabled. */
+    disabled?: boolean;
+    /** Whether to render a colon after each label. */
+    colon: boolean;
+    /** Whether to show the required asterisk mark on required fields. */
+    requiredMark: boolean;
+    /** The `react-hook-form` methods instance shared across the form. */
+    methods: UseFormReturn<FieldValues>;
+}
+/**
+ * Props for the `<Form>` component.
+ *
+ * Extends `react-hook-form`'s `UseFormProps` (excluding `defaultValues`) with
+ * layout configuration, submit callbacks, value-change subscriptions, and
+ * scroll-to-error behavior.
+ *
+ * @template TFieldValues - The shape of the form values.
+ */
+export interface FormProps<TFieldValues extends FieldValues = FieldValues> extends Omit<UseFormProps<TFieldValues>, 'defaultValues'> {
+    /** Initial values for the form fields. */
+    defaultValues?: DefaultValues<TFieldValues>;
+    /** An external `useForm()` return value to make the form fully controlled. */
+    form?: UseFormReturn<TFieldValues>;
+    /** Callback invoked with valid form values on successful submission. */
+    onFinish?: (values: TFieldValues) => void | Promise<void>;
+    /** Callback invoked with validation errors on failed submission. */
+    onFinishFailed?: (errors: FieldErrors<TFieldValues>) => void;
+    /** Callback fired when any watched field value changes. */
+    onValuesChange?: (values: TFieldValues, info: {
+        name?: FieldPath<TFieldValues>;
+        type?: string;
+    }) => void;
+    /** Field paths to subscribe to for `onValuesChange`. If omitted, all fields are watched. */
+    watchNames?: Array<FieldPath<TFieldValues>>;
+    /**
+     * Whether to scroll to the first invalid field on submit failure.
+     * Pass `true` for default scroll behavior, or an object to customize scroll options.
+     */
+    scrollToFirstError?: boolean | {
+        behavior?: ScrollBehavior;
+        block?: ScrollLogicalPosition;
+        inline?: ScrollLogicalPosition;
+        /** Pixel offset from the top when scrolling. */
+        offset?: number;
+    };
+    /** Layout direction. @defaultValue `'horizontal'` */
+    layout?: FormLayout;
+    /** Label text alignment. @defaultValue `'right'` */
+    labelAlign?: FormLabelAlign;
+    /** Label column span in a 12-column grid (0–12). @defaultValue `3` */
+    labelCol?: number;
+    /** Wrapper/control column span in a 12-column grid (0–12). @defaultValue `9` */
+    wrapperCol?: number;
+    /** Size variant. @defaultValue `'middle'` */
+    size?: FormSize;
+    /** When `true`, disables all form fields. */
+    disabled?: boolean;
+    /** Whether to show a colon after each label. @defaultValue `true` */
+    colon?: boolean;
+    /** Whether to show the required asterisk mark. @defaultValue `true` */
+    requiredMark?: boolean;
+    /** Additional CSS class name for the `<form>` element. */
+    className?: string;
+    /** Inline styles for the `<form>` element. */
+    style?: CSSProperties;
+    /** Form content (typically `<FormItem>` components). */
+    children?: ReactNode;
+}
+/**
+ * Props passed to a `FormItem` render-prop child function.
+ *
+ * @template TFieldValues - The shape of the form values.
+ */
+export interface FormItemRenderProps<TFieldValues extends FieldValues = FieldValues> {
+    /** Controller field bindings with additional status flags. Only present when `name` is set. */
+    field?: ControllerRenderProps<TFieldValues, FieldPath<TFieldValues>> & {
+        /** `true` when the field has a validation error. */
+        invalid?: boolean;
+        /** `true` when the field has been successfully validated. */
+        success?: boolean;
+    };
+    /** Controller field state (error, dirty, touched, etc.). Only present when `name` is set. */
+    fieldState?: ControllerFieldState;
+    /** The `react-hook-form` methods instance for imperative access. */
+    form: UseFormReturn<TFieldValues>;
+    /** Current snapshot of all form values. */
+    values: TFieldValues;
+}
+/**
+ * Extended `CSSProperties` including custom CSS variables for label/wrapper widths.
+ */
+export type FormItemStyle = CSSProperties & {
+    ['--om-form-label-width']?: string;
+    ['--om-form-wrapper-width']?: string;
+};
+/**
+ * Render-prop function signature used by `FormItem` children.
+ *
+ * @template TFieldValues - The shape of the form values.
+ */
+export type FormItemRenderFn<TFieldValues extends FieldValues> = (props: FormItemRenderProps<TFieldValues>) => ReactNode;
+/**
+ * Props for the `<FormItem>` component.
+ *
+ * Bridges `react-hook-form`'s `Controller` with layout, validation status,
+ * and trigger behavior.
+ *
+ * @template TFieldValues - The shape of the form values.
+ */
+export interface FormItemProps<TFieldValues extends FieldValues = FieldValues> {
+    /** Field path within the form values. When omitted, the item renders as a free (uncontrolled) wrapper. */
+    name?: FieldPath<TFieldValues>;
+    /** Label content rendered beside the field. */
+    label?: ReactNode;
+    /** Marks the field as required. When `rules.required` is set, this is inferred automatically. */
+    required?: boolean;
+    /** Declarative validation rules forwarded to `react-hook-form`'s `Controller`. */
+    rules?: FormItemRules<TFieldValues>;
+    /** Default value for the field. */
+    defaultValue?: FieldPathValue<TFieldValues, FieldPath<TFieldValues>>;
+    /** Custom help text displayed below the field. Overrides error messages when set. */
+    help?: ReactNode;
+    /** Extra content rendered below the help text. */
+    extra?: ReactNode;
+    /** Explicit validation status override. When set, bypasses automatic status derived from `fieldState`. */
+    validateStatus?: FormValidateStatus;
+    /** Field paths that trigger re-validation of this field when they change. */
+    dependencies?: Array<FieldPath<TFieldValues>>;
+    /** Additional field paths to watch, causing re-render when their values change. */
+    watchNames?: Array<FieldPath<TFieldValues>>;
+    /**
+     * Controls re-rendering behavior.
+     * - `true`: re-renders on every form value change.
+     * - A comparator function: re-renders when it returns `true`.
+     */
+    shouldUpdate?: boolean | ((prev: TFieldValues, next: TFieldValues) => boolean);
+    /** Event(s) that trigger validation. @defaultValue `[]` (validation on submit only) */
+    validateTrigger?: 'onChange' | 'onBlur' | Array<'onChange' | 'onBlur'>;
+    /**
+     * Controls multi-validator execution order.
+     * - `true`: runs validators sequentially, stops at first error.
+     * - `'parallel'`: runs all validators concurrently, returns first error found.
+     */
+    validateFirst?: boolean | 'parallel';
+    /** Debounce delay in milliseconds for triggered validation. */
+    validateDebounce?: number;
+    /** When `true`, renders only the field content without label/wrapper markup. */
+    noStyle?: boolean;
+    /** The prop name used to bind the controlled value to the child. @defaultValue `'value'` */
+    valuePropName?: string;
+    /** Additional CSS class name for the form item wrapper. */
+    className?: string;
+    /** Label column span override (0–12 grid). */
+    labelCol?: number;
+    /** Wrapper column span override (0–12 grid). */
+    wrapperCol?: number;
+    /** Field content — either a React node (auto-bound via `cloneElement`) or a render-prop function. */
+    children?: ReactNode | ((props: FormItemRenderProps<TFieldValues>) => ReactNode);
+}
+/**
+ * Internal props for the `<FormItemContent>` component.
+ *
+ * This is not part of the public API; it carries resolved context and
+ * validation state from `FormItem` down to the render layer.
+ *
+ * @template TFieldValues - The shape of the form values.
+ */
+export interface FormItemContentProps<TFieldValues extends FieldValues = FieldValues> {
+    /** Field path (determines controlled vs free branch). */
+    name?: FieldPath<TFieldValues>;
+    /** The `react-hook-form` `Control` instance. */
+    control: Control<TFieldValues>;
+    /** The `react-hook-form` methods instance. */
+    methods: UseFormReturn<TFieldValues>;
+    /** Merged validation rules. */
+    rules?: FormItemRules<TFieldValues>;
+    /** Default value for the Controller. */
+    defaultValue?: FormItemProps<TFieldValues>['defaultValue'];
+    /** Explicit validation status override. */
+    validateStatus?: FormValidateStatus;
+    /** Prop name used to bind the controlled value. */
+    valuePropName: string;
+    /** Help text displayed below the field. */
+    help?: ReactNode;
+    /** Extra content rendered below help text. */
+    extra?: ReactNode;
+    /** Form context value from the parent `<Form>`. */
+    ctx: FormContextValue | null;
+    /** Raw children from `FormItem`. */
+    children: FormItemProps<TFieldValues>['children'];
+    /** Resolved render-prop function, or `null` if children is a React node. */
+    renderFn: FormItemRenderFn<TFieldValues> | null;
+    /** Current snapshot of all form values. */
+    allValues: TFieldValues;
+    /** The `shouldUpdate` prop from `FormItem`. */
+    shouldUpdate?: FormItemProps<TFieldValues>['shouldUpdate'];
+    /** Whether the item should render based on `shouldUpdate` evaluation. */
+    shouldRender: boolean;
+    /**
+     * Wraps an event handler to conditionally trigger validation based on trigger mode.
+     *
+     * @param mode - The trigger mode (`'onChange'` or `'onBlur'`).
+     * @param fn - The original event handler to compose with.
+     * @returns A composed handler that calls `fn` and optionally triggers validation.
+     */
+    withTrigger: (mode: typeof TRIGGER_CHANGE | typeof TRIGGER_BLUR, fn?: (...args: unknown[]) => void) => (...args: unknown[]) => void;
+}

package/lib/components/Form/interface.js

@@ -0,0 +1,6 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+//# sourceMappingURL=data:application/json;charset=utf8;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiY29tcG9uZW50cy9Gb3JtL2ludGVyZmFjZS5qcyIsIm5hbWVzIjpbXSwic291cmNlUm9vdCI6Ii4uLy4uLy4uLy4uLy4uLy4uLy4uLy4uLy4uL3NyYyIsInNvdXJjZXMiOlsiY29tcG9uZW50cy9Gb3JtL2ludGVyZmFjZS5qcyJdLCJzb3VyY2VzQ29udGVudCI6WyJleHBvcnQge307Il0sIm1hcHBpbmdzIjoiIiwiaWdub3JlTGlzdCI6W119

package/lib/components/Form/style/Form.css

@@ -0,0 +1 @@
+.om-react-ui-form,.om-react-ui-form-root{--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}.om-react-ui-form-root{width:100%}.om-react-ui-form-layout-horizontal .om-react-ui-form-item-root{display:flex;align-items:flex-start}.om-react-ui-form-layout-vertical .om-react-ui-form-item-root{display:flex;flex-direction:column}.om-react-ui-form-layout-inline{display:flex;flex-wrap:wrap;gap:var(--om-form-spacing-lg)}.om-react-ui-form-label-left .om-react-ui-form-item-label{text-align:left}.om-react-ui-form-item,.om-react-ui-form-item-root{--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}.om-react-ui-form-item-root{width:100%;margin-bottom:var(--om-form-spacing-lg)}.om-react-ui-form-item-label{display:flex;flex:0 0 var(--om-form-label-width,25%);align-items:center;justify-content:flex-end;min-width:-moz-fit-content;min-width:fit-content;min-height:var(--om-form-control-height);padding-right:var(--om-form-spacing-md);color:#131313;font-size:var(--om-form-font-size-base);line-height:var(--om-form-line-height-base);white-space:nowrap;text-align:right}.om-react-ui-form-item-label-required:before{margin-right:var(--om-form-spacing-xs);color:#ae0000;content:"*"}.om-react-ui-form-item-colon{margin-left:var(--om-form-spacing-xs)}.om-react-ui-form-item-control{flex:1 1 auto;max-width:var(--om-form-wrapper-width,75%)}.om-react-ui-form-item-content{display:flex;flex-direction:column;gap:var(--om-form-spacing-sm)}.om-react-ui-form-item-content-disabled{opacity:var(--om-form-opacity-disabled)}.om-react-ui-form-item-help{color:#646465;font-size:var(--om-form-font-size-help);line-height:var(--om-form-line-height-help)}.om-react-ui-form-item-help-error{color:#ae0000}.om-react-ui-form-item-help-warning{color:#db8600}.om-react-ui-form-item-help-success{color:#1f5800}.om-react-ui-form-item-content-error{--om-form-item-status-color:#ae0000}.om-react-ui-form-item-content-warning{--om-form-item-status-color:#db8600}.om-react-ui-form-item-content-success{--om-form-item-status-color:#1f5800}.om-react-ui-form-item-content-validating{--om-form-item-status-color:#3d7cf5}.om-react-ui-form-item-extra{color:#9fa3a3;font-size:var(--om-form-font-size-help);line-height:var(--om-form-line-height-help)}.om-react-ui-form-layout-vertical .om-react-ui-form-item-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}.om-react-ui-form-layout-vertical .om-react-ui-form-item-control{max-width:100%}.om-react-ui-form-layout-inline .om-react-ui-form-item-root{width:auto;margin-bottom:0}

package/lib/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/lib/components/Form/style/css.js

@@ -0,0 +1,4 @@
+"use strict";
+
+require("./Form.css");
+//# sourceMappingURL=data:application/json;charset=utf8;base64,eyJ2ZXJzaW9uIjozLCJzb3VyY2VzIjpbImNvbXBvbmVudHMvRm9ybS9zcmMvY29tcG9uZW50cy9Gb3JtL3N0eWxlL2luZGV4LnRzIl0sIm5hbWVzIjpbInJlcXVpcmUiXSwibWFwcGluZ3MiOiI7O0FBQUFBLE9BQUEiLCJmaWxlIjoiY29tcG9uZW50cy9Gb3JtL3N0eWxlL2Nzcy5qcyIsInNvdXJjZXNDb250ZW50IjpbbnVsbF0sInNvdXJjZVJvb3QiOiIuLi8uLi8uLi8uLi8uLi8uLi8uLi8uLi8uLi8uLi9zcmMifQ==

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

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

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

@@ -0,0 +1,4 @@
+"use strict";
+
+require("./Form.scss");
+//# sourceMappingURL=data:application/json;charset=utf8;base64,eyJ2ZXJzaW9uIjozLCJzb3VyY2VzIjpbImNvbXBvbmVudHMvRm9ybS9zcmMvY29tcG9uZW50cy9Gb3JtL3N0eWxlL2luZGV4LnRzIl0sIm5hbWVzIjpbInJlcXVpcmUiXSwibWFwcGluZ3MiOiI7O0FBQUFBLE9BQUEiLCJmaWxlIjoiY29tcG9uZW50cy9Gb3JtL3N0eWxlL2luZGV4LmpzIiwic291cmNlc0NvbnRlbnQiOltudWxsXSwic291cmNlUm9vdCI6Ii4uLy4uLy4uLy4uLy4uLy4uLy4uLy4uLy4uLy4uL3NyYyJ9

package/lib/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/lib/components/Form/useFormItemContext.js

@@ -0,0 +1,62 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.FallbackFormProvider = FallbackFormProvider;
+exports.useFormItemContext = useFormItemContext;
+var _react = require("react");
+var _reactHookForm = require("react-hook-form");
+var _Form = require("./Form");
+var FallbackFormContext = /*#__PURE__*/(0, _react.createContext)(null);
+/**
+ * Lazily creates form methods only when mounted.
+ *
+ * Use this provider when rendering form-aware components outside `<Form>`.
+ */
+function FallbackFormProvider(_ref) {
+  var children = _ref.children;
+  var methods = (0, _reactHookForm.useForm)();
+  return /*#__PURE__*/(0, _react.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`.
+ */
+function useFormItemContext(name) {
+  var _a;
+  var ctx = (0, _react.useContext)(_Form.FormContext);
+  var fallbackMethods = (0, _react.useContext)(FallbackFormContext);
+  var warnedRef = (0, _react.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;
+  (0, _react.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,eyJ2ZXJzaW9uIjozLCJzb3VyY2VzIjpbImNvbXBvbmVudHMvc3JjL2NvbXBvbmVudHMvRm9ybS91c2VGb3JtSXRlbUNvbnRleHQudHMiLCJjb21wb25lbnRzL0Zvcm0vdXNlRm9ybUl0ZW1Db250ZXh0LmpzIl0sIm5hbWVzIjpbIl9yZWFjdCIsInJlcXVpcmUiLCJfcmVhY3RIb29rRm9ybSIsIl9Gb3JtIiwiRmFsbGJhY2tGb3JtQ29udGV4dCIsImNyZWF0ZUNvbnRleHQiLCJGYWxsYmFja0Zvcm1Qcm92aWRlciIsIl9yZWYiLCJjaGlsZHJlbiIsIm1ldGhvZHMiLCJ1c2VGb3JtIiwiY3JlYXRlRWxlbWVudCIsIlByb3ZpZGVyIiwidmFsdWUiLCJ1c2VGb3JtSXRlbUNvbnRleHQiLCJuYW1lIiwiX2EiLCJjdHgiLCJ1c2VDb250ZXh0IiwiRm9ybUNvbnRleHQiLCJmYWxsYmFja01ldGhvZHMiLCJ3YXJuZWRSZWYiLCJ1c2VSZWYiLCJTZXQiLCJFcnJvciIsImNvbnRyb2wiLCJ0cmlnZ2VyIiwidXNlRWZmZWN0IiwiY3VycmVudCIsImhhcyIsImFkZCIsImNvbnNvbGUiLCJ3YXJuIl0sIm1hcHBpbmdzIjoiOzs7Ozs7O0FBQUEsSUFBQUEsTUFBQSxHQUFBQyxPQUFBO0FBQ0EsSUFBQUMsY0FBQSxHQUFBRCxPQUFBO0FBR0EsSUFBQUUsS0FBQSxHQUFBRixPQUFBO0FBRUEsSUFBTUcsbUJBQW1CLGdCQUFHLElBQUFDLG9CQUFhLEVBQW9DLElBQUksQ0FBQztBQU1sRjtBQ1BBO0FBQ0E7QUFDQTtBQUNBO0FEU00sU0FBVUMsb0JBQW9CQSxDQUFBQyxJQUFBLEVBQXdDO0VBQUEsSUFBckNDLFFBQVEsR0FBQUQsSUFBQSxDQUFSQyxRQUFRO0VBQzdDLElBQU1DLE9BQU8sR0FBRyxJQUFBQyxzQkFBTyxFQUFBLENBQWU7RUFDdEMsb0JBQU8sSUFBQUMsb0JBQWEsRUFBQ1AsbUJBQW1CLENBQUNRLFFBQVEsRUFBRTtJQUFFQyxLQUFLLEVBQUVKO0VBQU8sQ0FBRSxFQUFFRCxRQUFRLENBQUM7QUFDbEY7QUFFQTtBQ1JBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FEVU0sU0FBVU0sa0JBQWtCQSxDQUFpREMsSUFBYSxFQUFBO0VDUjVGLElBQUlDLEVBQUU7RURTUixJQUFNQyxHQUFHLEdBQUcsSUFBQUMsaUJBQVUsRUFBQ0MsaUJBQVcsQ0FBQztFQUNuQyxJQUFNQyxlQUFlLEdBQUcsSUFBQUYsaUJBQVUsRUFBQ2QsbUJBQW1CLENBQUM7RUFDdkQsSUFBTWlCLFNBQVMsR0FBRyxJQUFBQyxhQUFNLEVBQWMsSUFBSUMsR0FBRyxDQUFBLENBQUUsQ0FBQztFQUNoRCxJQUFNZCxPQUFPLEdBQUcsQ0FBQU8sRUFBQSxHQUFDQyxHQUFHLEtBQUEsSUFBQSxJQUFIQSxHQUFHLEtBQUEsS0FBQSxDQUFBLEdBQUEsS0FBQSxDQUFBLEdBQUhBLEdBQUcsQ0FBRVIsT0FBbUQsTUFBQSxJQUFBLElBQUFPLEVBQUEsS0FBQSxLQUFBLENBQUEsR0FBQUEsRUFBQSxHQUNuRUksZUFBc0Q7RUFFNUQsSUFBSSxDQUFDWCxPQUFPLEVBQUU7SUFDWixNQUFNLElBQUllLEtBQUssQ0FDYiw0RkFBNEYsQ0FDN0Y7RUFDSDtFQUVBLElBQU1DLE9BQU8sR0FBR2hCLE9BQU8sQ0FBQ2dCLE9BQU87RUFDL0IsSUFBTUMsT0FBTyxHQUFHakIsT0FBTyxDQUFDaUIsT0FBTztFQUUvQixJQUFBQyxnQkFBUyxFQUFDLFlBQUs7SUFDYixJQUFJWixJQUFJLElBQUksRUFBQ0UsR0FBRyxLQUFBLElBQUEsSUFBSEEsR0FBRyxLQUFBLEtBQUEsQ0FBQSxHQUFBLEtBQUEsQ0FBQSxHQUFIQSxHQUFHLENBQUVSLE9BQU8sQ0FBQSxJQUFJLENBQUNZLFNBQVMsQ0FBQ08sT0FBTyxDQUFDQyxHQUFHLENBQUNkLElBQUksQ0FBQyxFQUFFO01BQ3pETSxTQUFTLENBQUNPLE9BQU8sQ0FBQ0UsR0FBRyxDQUFDZixJQUFJLENBQUM7TUFDM0JnQixPQUFPLENBQUNDLElBQUksQ0FBQyxtR0FBbUcsQ0FBQztJQUNuSDtFQUNGLENBQUMsRUFBRSxDQUFDakIsSUFBSSxFQUFFRSxHQUFHLEtBQUEsSUFBQSxJQUFIQSxHQUFHLEtBQUEsS0FBQSxDQUFBLEdBQUEsS0FBQSxDQUFBLEdBQUhBLEdBQUcsQ0FBRVIsT0FBTyxDQUFDLENBQUM7RUFFeEIsT0FBTztJQUFFUSxHQUFHLEVBQUhBLEdBQUc7SUFBRVIsT0FBTyxFQUFQQSxPQUFPO0lBQUVnQixPQUFPLEVBQVBBLE9BQU87SUFBRUMsT0FBTyxFQUFQQTtFQUFPLENBQUU7QUFDM0MiLCJmaWxlIjoiY29tcG9uZW50cy9Gb3JtL3VzZUZvcm1JdGVtQ29udGV4dC5qcyIsInNvdXJjZXNDb250ZW50IjpbbnVsbCwiaW1wb3J0IHsgY3JlYXRlQ29udGV4dCwgY3JlYXRlRWxlbWVudCwgdXNlQ29udGV4dCwgdXNlRWZmZWN0LCB1c2VSZWYgfSBmcm9tICdyZWFjdCc7XG5pbXBvcnQgeyB1c2VGb3JtIH0gZnJvbSAncmVhY3QtaG9vay1mb3JtJztcbmltcG9ydCB7IEZvcm1Db250ZXh0IH0gZnJvbSAnLi9Gb3JtJztcbmNvbnN0IEZhbGxiYWNrRm9ybUNvbnRleHQgPSBjcmVhdGVDb250ZXh0KG51bGwpO1xuLyoqXG4gKiBMYXppbHkgY3JlYXRlcyBmb3JtIG1ldGhvZHMgb25seSB3aGVuIG1vdW50ZWQuXG4gKlxuICogVXNlIHRoaXMgcHJvdmlkZXIgd2hlbiByZW5kZXJpbmcgZm9ybS1hd2FyZSBjb21wb25lbnRzIG91dHNpZGUgYDxGb3JtPmAuXG4gKi9cbmV4cG9ydCBmdW5jdGlvbiBGYWxsYmFja0Zvcm1Qcm92aWRlcih7IGNoaWxkcmVuIH0pIHtcbiAgICBjb25zdCBtZXRob2RzID0gdXNlRm9ybSgpO1xuICAgIHJldHVybiBjcmVhdGVFbGVtZW50KEZhbGxiYWNrRm9ybUNvbnRleHQuUHJvdmlkZXIsIHsgdmFsdWU6IG1ldGhvZHMgfSwgY2hpbGRyZW4pO1xufVxuLyoqXG4gKiBSZXNvbHZlcyBmb3JtIGNvbnRleHQgZm9yIGEgYDxGb3JtSXRlbT5gLlxuICpcbiAqIFdoZW4gcmVuZGVyZWQgaW5zaWRlIGEgYDxGb3JtPmAsIHRoaXMgaG9vayB1c2VzIHRoZSBjb250ZXh0LXByb3ZpZGVkXG4gKiBgcmVhY3QtaG9vay1mb3JtYCBtZXRob2RzLiBPdGhlcndpc2UgaXQgcmVhZHMgbWV0aG9kcyBmcm9tXG4gKiB7QGxpbmsgRmFsbGJhY2tGb3JtUHJvdmlkZXJ9LCB3aGljaCBjcmVhdGVzIGEgbG9jYWwgYHVzZUZvcm0oKWAgaW5zdGFuY2UuXG4gKlxuICogQSBkZXZlbG9wbWVudC1vbmx5IGNvbnNvbGUgd2FybmluZyBpcyBlbWl0dGVkIChvbmNlIHBlciBmaWVsZCBuYW1lKSB3aGVuXG4gKiBhIGBuYW1lYCBwcm9wIGlzIHNldCBidXQgbm8gcGFyZW50IGA8Rm9ybT5gIGNvbnRleHQgaXMgZm91bmQuXG4gKlxuICogQHRlbXBsYXRlIFRGaWVsZFZhbHVlcyAtIFRoZSBzaGFwZSBvZiB0aGUgZm9ybSB2YWx1ZXMuXG4gKiBAcGFyYW0gbmFtZSAtIFRoZSBmaWVsZCBuYW1lLCB1c2VkIGZvciB0aGUgbWlzc2luZy1jb250ZXh0IHdhcm5pbmcgY2hlY2suXG4gKiBAcmV0dXJucyBBbiBvYmplY3Qgd2l0aCBgY3R4YCAoZm9ybSBjb250ZXh0IG9yIGBudWxsYCksIGBtZXRob2RzYCwgYGNvbnRyb2xgLCBhbmQgYHRyaWdnZXJgLlxuICovXG5leHBvcnQgZnVuY3Rpb24gdXNlRm9ybUl0ZW1Db250ZXh0KG5hbWUpIHtcbiAgICB2YXIgX2E7XG4gICAgY29uc3QgY3R4ID0gdXNlQ29udGV4dChGb3JtQ29udGV4dCk7XG4gICAgY29uc3QgZmFsbGJhY2tNZXRob2RzID0gdXNlQ29udGV4dChGYWxsYmFja0Zvcm1Db250ZXh0KTtcbiAgICBjb25zdCB3YXJuZWRSZWYgPSB1c2VSZWYobmV3IFNldCgpKTtcbiAgICBjb25zdCBtZXRob2RzID0gKF9hID0gY3R4ID09PSBudWxsIHx8IGN0eCA9PT0gdm9pZCAwID8gdm9pZCAwIDogY3R4Lm1ldGhvZHMpICE9PSBudWxsICYmIF9hICE9PSB2b2lkIDAgPyBfYSA6IGZhbGxiYWNrTWV0aG9kcztcbiAgICBpZiAoIW1ldGhvZHMpIHtcbiAgICAgICAgdGhyb3cgbmV3IEVycm9yKCdbRm9ybUl0ZW1dIE5vIGZvcm0gY29udHJvbCBmb3VuZC4gV3JhcCB3aXRoIDxGb3JtPiBvciBtb3VudCBpbnNpZGUgPEZhbGxiYWNrRm9ybVByb3ZpZGVyPi4nKTtcbiAgICB9XG4gICAgY29uc3QgY29udHJvbCA9IG1ldGhvZHMuY29udHJvbDtcbiAgICBjb25zdCB0cmlnZ2VyID0gbWV0aG9kcy50cmlnZ2VyO1xuICAgIHVzZUVmZmVjdCgoKSA9PiB7XG4gICAgICAgIGlmIChuYW1lICYmICEoY3R4ID09PSBudWxsIHx8IGN0eCA9PT0gdm9pZCAwID8gdm9pZCAwIDogY3R4Lm1ldGhvZHMpICYmICF3YXJuZWRSZWYuY3VycmVudC5oYXMobmFtZSkpIHtcbiAgICAgICAgICAgIHdhcm5lZFJlZi5jdXJyZW50LmFkZChuYW1lKTtcbiAgICAgICAgICAgIGNvbnNvbGUud2FybignW0Zvcm1JdGVtXSBgbmFtZWAgcHJvcCBpcyBzZXQgYnV0IG5vIGZvcm0gY29udHJvbCBmb3VuZC4gV3JhcCBGb3JtSXRlbSBpbnNpZGUgYSA8Rm9ybT4gY29tcG9uZW50LicpO1xuICAgICAgICB9XG4gICAgfSwgW25hbWUsIGN0eCA9PT0gbnVsbCB8fCBjdHggPT09IHZvaWQgMCA/IHZvaWQgMCA6IGN0eC5tZXRob2RzXSk7XG4gICAgcmV0dXJuIHsgY3R4LCBtZXRob2RzLCBjb250cm9sLCB0cmlnZ2VyIH07XG59Il0sInNvdXJjZVJvb3QiOiIuLi8uLi8uLi8uLi8uLi8uLi8uLi8uLi8uLi9zcmMifQ==

package/lib/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 {};