@1money/component-ui 0.0.75 → 0.0.76

package/lib/components/ProForm/core/interface.d.ts

@@ -1,39 +1,101 @@
 import type React from 'react';
 import type { FC, ReactNode } from 'react';
 import type { FormSize, FormLayout, LabelAlign, ValidateStatus, ValidateTrigger } from './constants';
+import { RULE_CONTEXT_READ_MEMBERS, RULE_CONTEXT_MUTATOR_MEMBERS } from './constants';
 export type { FormSize, FormLayout, LabelAlign, ValidateStatus, ValidateTrigger, };
+/** Built-in `type` check names. */
+export type RuleType = 'string' | 'number' | 'boolean' | 'method' | 'regexp' | 'integer' | 'float' | 'object' | 'array' | 'date' | 'url' | 'hex' | 'email' | 'enum';
 export interface Rule {
     /** Fails on undefined / null / '' / empty array */
     required?: boolean;
-    message?: string;
+    /** Error content shown on failure — any ReactNode (falls back to a generated string) */
+    message?: ReactNode;
     /** For strings: min length; arrays: min item count; numbers: min value */
     min?: number;
     /** For strings: max length; arrays: max item count; numbers: max value */
     max?: number;
+    /** Exact string length / array item count / numeric value. Takes precedence over min/max */
+    len?: number;
     pattern?: RegExp;
-    type?: 'number' | 'email' | 'url';
+    type?: RuleType;
     enum?: unknown[];
+    /** Fails a non-empty string consisting only of whitespace */
+    whitespace?: boolean;
+    /** Transform the value before every check (builtin and validator) of THIS rule */
+    transform?: (value: unknown) => unknown;
+    /** Deep rule(s) applied to every member of an array/object value */
+    defaultField?: Rule | Rule[];
+    /** Deep rules applied per key of an object/array value */
+    fields?: Record<string, Rule | Rule[]>;
     /** A failing rule produces a non-blocking warning instead of an error */
     warningOnly?: boolean;
     /**
-     * Run this rule only on the given interactive trigger(s); rules without it
-     * follow the form-level validateTrigger. Submit always runs every rule.
+     * Run this rule only on the given interactive event(s). It
+     * must be a subset of the item's effective triggers to fire interactively.
+     * Rules without it run on every effective trigger. Submit always runs
+     * every rule.
      */
     validateTrigger?: ValidateTrigger | ValidateTrigger[];
-    validator?: (value: unknown, values: Record<string, unknown>) => boolean | string | Promise<boolean | string>;
+    /**
+     * Custom validator: resolve (or return undefined) to pass,
+     * reject/throw to fail. The failure message is taken from the rejection
+     * (Error.message or a plain string), then `rule.message`, then a generic
+     * fallback. Return values are ignored — returning `false` or a string does
+     * NOT fail the rule.
+     */
+    validator?: (rule: Rule, value: unknown) => Promise<void> | void;
 }
+/**
+ * Form/Item-level validateTrigger config: a single event, a
+ * list of events, or `false` to disable interactive validation entirely
+ * (submit / validateFields still run every rule). Item-level overrides
+ * form-level.
+ */
+export type ValidateTriggerProp = ValidateTrigger | ValidateTrigger[] | false;
+/**
+ * The form context handed to function-form rules. The read helpers are
+ * always available (derived from the validation-time value snapshot). The
+ * remaining members are backed by the live form instance and are present
+ * whenever rules run inside a mounted form — they are only absent when the
+ * pure rule engine is invoked directly without an instance.
+ */
+export interface RuleContext {
+    getFieldValue: (name: string) => unknown;
+    getFieldsValue: () => Record<string, unknown>;
+    setFieldValue?: (name: string, value: unknown) => void;
+    setFieldsValue?: (values: Record<string, unknown>) => void;
+    resetFields?: () => void;
+    getFieldError?: (name: string) => ReactNode | undefined;
+    getFieldWarning?: (name: string) => ReactNode | undefined;
+    isFieldTouched?: (name: string) => boolean;
+    isFieldValidating?: (name: string) => boolean;
+}
+/**
+ * A rule entry as consumers write it: a static Rule, or — for cross-field
+ * validation — a function of the form context returning a Rule (the
+ * `({ getFieldValue }) => ({ validator })` idiom).
+ */
+export type FormRule = Rule | ((ctx: RuleContext) => Rule);
+export type RuleContextReadMember = (typeof RULE_CONTEXT_READ_MEMBERS)[number];
+export type RuleContextMutatorMember = (typeof RULE_CONTEXT_MUTATOR_MEMBERS)[number];
+type AssertRuleContextMembers<T extends keyof RuleContext> = T;
+/**
+ * Compile-time guard: the member lists in constants.ts must stay subsets of
+ * RuleContext — renaming or removing a member there breaks this line.
+ */
+export type RuleContextInstanceMember = AssertRuleContextMembers<RuleContextReadMember | RuleContextMutatorMember>;
 export interface FieldProps {
     name: string;
     value: unknown;
-    error?: string;
+    error?: ReactNode;
     touched?: boolean;
     validating?: boolean;
     onChange: (value: unknown) => void;
     onBlur: () => void;
 }
 export interface FieldOptions {
-    rules?: Rule[];
-    validateTrigger?: ValidateTrigger;
+    rules?: FormRule[];
+    validateTrigger?: ValidateTriggerProp;
 }
 export interface FieldComponentProps {
     children: ReactNode | ((props: FieldProps) => ReactNode);
@@ -44,14 +106,14 @@ export interface FormCoreInstance {
     submit: () => {
         success: boolean;
         values?: Record<string, unknown>;
-        errors?: Record<string, string>;
+        errors?: Record<string, ReactNode>;
     };
     resetFields: () => void;
     getFieldValue: (name: string) => unknown;
     getFieldsValue: () => Record<string, unknown>;
     setFieldsValue: (values: Record<string, unknown>) => void;
     setFieldValue: (name: string, value: unknown) => void;
-    validateFields: (fieldsRules?: Record<string, Rule[]>) => boolean;
+    validateFields: (fieldsRules?: Record<string, FormRule[]>) => boolean;
 }
 /**
  * Full form instance returned by useForm — extends FormCoreInstance with async
@@ -63,84 +125,84 @@ export interface FormInstance<Values = Record<string, unknown>> {
     getFieldsValue: (nameList?: string[]) => Values;
     setFieldValue: (name: string, value: unknown) => void;
     setFieldsValue: (values: Partial<Values>) => void;
-    setFieldError: (name: string, error: string | null) => void;
-    setFieldsError: (errors: Record<string, string>) => void;
+    setFieldError: (name: string, error: ReactNode | null) => void;
+    setFieldsError: (errors: Record<string, ReactNode>) => void;
     resetFields: (fields?: string[]) => void;
     validateFields: (nameList?: string[]) => Promise<Values>;
     submit: (callback?: (values: Values) => void | Promise<void>) => Promise<Values | undefined>;
-    getFieldError: (name: string) => string | undefined;
-    getFieldsError: (nameList?: string[]) => Record<string, string>;
-    getFieldWarning: (name: string) => string | undefined;
+    getFieldError: (name: string) => ReactNode | undefined;
+    getFieldsError: (nameList?: string[]) => Record<string, ReactNode>;
+    getFieldWarning: (name: string) => ReactNode | undefined;
     isFieldTouched: (name: string) => boolean;
     isFieldsTouched: (nameList?: string[], allTouched?: boolean) => boolean;
     isFieldValidating: (name: string) => boolean;
     setFieldTouched: (name: string, isTouched?: boolean) => void;
     setFieldsTouched: (touched: Record<string, boolean>) => void;
     defineField: (name: string, options?: FieldOptions) => FC<FieldComponentProps>;
-    registerField: (name: string, rules: Rule[]) => void;
+    registerField: (name: string, rules: FormRule[]) => void;
     unregisterField: (name: string) => void;
 }
 export interface UseFormOptions {
     onValuesChange?: (changedValues: Record<string, unknown>, allValues: Record<string, unknown>) => void;
-    validateTrigger?: ValidateTrigger;
-    rules?: Record<string, Rule[]>;
+    validateTrigger?: ValidateTriggerProp;
+    rules?: Record<string, FormRule[]>;
 }
 export interface UseFormCoreConfig<Values = Record<string, unknown>> {
     initialValues?: Partial<Values>;
     onFinish?: (values: Values) => void;
     onFinishFailed?: (errorInfo: {
         values: Values;
-        errors: Record<string, string>;
+        errors: Record<string, ReactNode>;
     }) => void;
     onValuesChange?: (changedValues: Partial<Values>, allValues: Values) => void;
     onReset?: () => void;
     size?: FormSize;
     labelAlign?: LabelAlign;
     disabled?: boolean;
-    colon?: boolean;
-    requiredMark?: boolean;
-    validateTrigger?: ValidateTrigger;
+    validateTrigger?: ValidateTriggerProp;
 }
 /** Internal shape of data produced by useFormCore, consumed by ProForm to build ProFormContext */
 export interface FormCoreContextShape {
     values: Record<string, unknown>;
-    errors: Record<string, string>;
-    warnings: Record<string, string>;
+    errors: Record<string, ReactNode>;
+    warnings: Record<string, ReactNode>;
     touched: Record<string, boolean>;
     formInstance: FormCoreInstance;
     setFieldValue: (name: string, value: unknown) => void;
-    setFieldError: (name: string, error: string | null) => void;
-    setFieldWarning: (name: string, warning: string | null) => void;
-    validateField: (name: string, rules: Rule[], providedValue?: unknown) => boolean;
-    registerField: (name: string, rules: Rule[]) => void;
+    setFieldError: (name: string, error: ReactNode | null) => void;
+    setFieldWarning: (name: string, warning: ReactNode | null) => void;
+    validateField: (name: string, rules: FormRule[], providedValue?: unknown) => boolean;
+    registerField: (name: string, rules: FormRule[]) => void;
     unregisterField: (name: string) => void;
     size: FormSize;
     labelAlign: LabelAlign;
     disabled: boolean;
-    colon: boolean;
-    requiredMark: boolean;
-    validateTrigger: ValidateTrigger;
+    validateTrigger: ValidateTriggerProp;
 }
 /** Config for useForm — accepts all UseFormCoreConfig fields */
 export type UseFormConfig<Values = Record<string, unknown>> = UseFormCoreConfig<Values>;
 /** Internal state exposed by useForm for ProForm integration */
 export interface UseFormInternals {
     values: Record<string, unknown>;
-    errors: Record<string, string>;
-    warnings: Record<string, string>;
+    errors: Record<string, ReactNode>;
+    warnings: Record<string, ReactNode>;
     touched: Record<string, boolean>;
     validating: Record<string, boolean>;
-    fieldRules: Record<string, Rule[]>;
+    fieldRules: Record<string, FormRule[]>;
     setFieldValue: (name: string, value: unknown) => void;
-    setFieldError: (name: string, error: string | null) => void;
-    setFieldWarning: (name: string, warning: string | null) => void;
-    validateField: (name: string, rules: Rule[], providedValue?: unknown) => boolean;
-    validateFieldAsync: (name: string, value: unknown, rules: Rule[]) => Promise<{
+    setFieldError: (name: string, error: ReactNode | null) => void;
+    setFieldWarning: (name: string, warning: ReactNode | null) => void;
+    validateField: (name: string, rules: FormRule[], providedValue?: unknown) => boolean;
+    validateFieldAsync: (name: string, value: unknown, rules: FormRule[]) => Promise<{
         isValid: boolean;
-        error: string | null;
+        error: ReactNode | null;
     }>;
-    registerField: (name: string, rules: Rule[]) => void;
+    registerField: (name: string, rules: FormRule[]) => void;
     unregisterField: (name: string) => void;
+    /** Count a mounted instance for `name` — pair with `releaseField` on unmount. */
+    retainField: (name: string) => void;
+    /** Drop one instance count; the field's rules are removed only at zero. */
+    releaseField: (name: string) => void;
     handleSubmit: (e?: React.FormEvent) => void;
     handleReset: (e?: React.FormEvent) => void;
 }
@@ -151,21 +213,34 @@ export interface UseFormReturn {
 }
 export interface UseFormCoreReturn {
     values: Record<string, unknown>;
-    errors: Record<string, string>;
-    warnings: Record<string, string>;
+    errors: Record<string, ReactNode>;
+    warnings: Record<string, ReactNode>;
     touched: Record<string, boolean>;
-    fieldRules: Record<string, Rule[]>;
-    getFieldRules: (name: string) => Rule[] | undefined;
+    fieldRules: Record<string, FormRule[]>;
+    getFieldRules: (name: string) => FormRule[] | undefined;
+    /** Instance handed to function-form rules; useForm upgrades it to the full form instance. */
+    getRuleContextInstance: () => Partial<RuleContext>;
+    setRuleContextInstance: (instance: Partial<RuleContext>) => void;
+    /** Bump and return the field's validation epoch — every run captures one. */
+    beginValidationRun: (name: string) => number;
+    /** True while no newer run has started for the field since `epoch` was issued. */
+    isValidationRunCurrent: (name: string, epoch: number) => boolean;
+    /** Invalidate in-flight runs (all fields, or the given ones) — e.g. on reset. */
+    invalidateValidationRuns: (names?: string[]) => void;
     setFieldValue: (name: string, value: unknown) => void;
-    setFieldError: (name: string, error: string | null) => void;
-    setFieldWarning: (name: string, warning: string | null) => void;
+    setFieldError: (name: string, error: ReactNode | null) => void;
+    setFieldWarning: (name: string, warning: ReactNode | null) => void;
     setFieldsValue: (values: Record<string, unknown>) => void;
     getFieldValue: (name: string) => unknown;
     getFieldsValue: () => Record<string, unknown>;
-    validateField: (name: string, rules: Rule[], providedValue?: unknown) => boolean;
-    validateFields: (fieldsRules?: Record<string, Rule[]>) => boolean;
-    registerField: (name: string, rules: Rule[]) => void;
+    validateField: (name: string, rules: FormRule[], providedValue?: unknown) => boolean;
+    validateFields: (fieldsRules?: Record<string, FormRule[]>) => boolean;
+    registerField: (name: string, rules: FormRule[]) => void;
     unregisterField: (name: string) => void;
+    /** Count a mounted instance for `name` — pair with `releaseField` on unmount. */
+    retainField: (name: string) => void;
+    /** Drop one instance count; the field's rules are removed only at zero. */
+    releaseField: (name: string) => void;
     handleSubmit: (e?: React.FormEvent) => void;
     handleReset: (e?: React.FormEvent) => void;
     resetFields: () => void;

package/lib/components/ProForm/core/runRules.d.ts

@@ -1,25 +1,57 @@
-import type { Rule, ValidateTrigger } from './interface';
+import type { ReactNode } from 'react';
+import type { FormRule, Rule, RuleContext, ValidateTrigger, ValidateTriggerProp } from './interface';
 export interface RuleRunResult {
-    error: string | null;
-    warning: string | null;
+    error: ReactNode | null;
+    warning: ReactNode | null;
 }
 /**
- * Filter rules applicable to an interactive trigger. A rule WITHOUT an
- * explicit `validateTrigger` follows the form-level trigger; a rule WITH one
- * runs on exactly those trigger(s), regardless of the form-level setting.
- * Submit-time validation bypasses this filter and runs every rule.
+ * Coerce a thrown/rejected reason into displayable failure content:
+ * a non-empty Error.message or a non-empty plain string — otherwise null
+ * (caller picks its fallback). Shared with the form-level last-resort nets.
  */
-export declare function filterRulesByTrigger(rules: Rule[], trigger: ValidateTrigger, formTrigger: ValidateTrigger): Rule[];
+export declare function coerceFailureReason(reason: unknown): ReactNode | null;
+/**
+ * Resolve function-form rules into static rules. The
+ * context exposes the value snapshot the run was invoked with; function rules
+ * must be cheap and side-effect free — they may be resolved more than once
+ * per validation pass.
+ */
+export declare function resolveRules(rules: FormRule[], values: Record<string, unknown>, instance?: Partial<RuleContext>): Rule[];
+/**
+ * Normalize a form/item-level validateTrigger config into the effective
+ * interactive event list: item-level (when present) overrides form-level;
+ * `false` disables interactive validation entirely.
+ */
+export declare function normalizeTriggers(itemTrigger: ValidateTriggerProp | undefined, formTrigger: ValidateTriggerProp): ValidateTrigger[];
+/**
+ * Filter rules applicable to an interactive event: the event
+ * validates only when it is in the item's effective trigger set. Within the
+ * set, a rule WITHOUT `validateTrigger` runs on every event; a rule WITH one
+ * runs only on matching events — so a rule trigger outside the item's set
+ * never fires interactively. Submit-time validation bypasses this filter and
+ * runs every rule.
+ *
+ * Dev guard: a rule whose (non-empty) trigger set is fully OUTSIDE the
+ * active set can never fire interactively — usually a leftover of the
+ * pre-0.0.76 override semantics, so it warns once. `validateTrigger: []`
+ * is the deliberate submit-only idiom and stays silent.
+ */
+export declare function filterRulesByTrigger(rules: Rule[], trigger: ValidateTrigger, activeTriggers: ValidateTrigger[], fieldName?: string): Rule[];
 /**
  * Synchronous rule run. A Promise-returning validator CANNOT be evaluated
  * here — it is deferred (treated as passing for this run; its rejection is
  * swallowed) and left to the async runs (blur/submit), which always await it.
  * Failing it instead would mis-report "Validation failed" on every keystroke
  * for perfectly valid input.
+ *
+ * The per-rule try/catch is the engine's totality choke point: NO input —
+ * including exotic values that break a builtin check — may escape as a throw;
+ * every failure surfaces through the error/warning channels.
  */
-export declare function runRulesSync(name: string, value: unknown, values: Record<string, unknown>, rules: Rule[]): RuleRunResult;
+export declare function runRulesSync(name: string, value: unknown, values: Record<string, unknown>, rules: FormRule[], instance?: Partial<RuleContext>): RuleRunResult;
 /**
- * Asynchronous rule run. Custom validators are awaited (sync or async). A
- * validator returning `undefined` is treated as passing.
+ * Asynchronous rule run. Custom validators are awaited (sync or async):
+ * resolving passes, rejecting/throwing fails. Return values are ignored.
+ * Shares the totality choke point with runRulesSync.
  */
-export declare function runRulesAsync(name: string, value: unknown, values: Record<string, unknown>, rules: Rule[]): Promise<RuleRunResult>;
+export declare function runRulesAsync(name: string, value: unknown, values: Record<string, unknown>, rules: FormRule[], instance?: Partial<RuleContext>): Promise<RuleRunResult>;