@rainbow-oh/yee-c 0.8.20 → 0.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rainbow-oh/yee-c",
-  "version": "0.8.20",
+  "version": "0.9.0",
   "description": "yee basic components",
   "keywords": [
     "react",

package/src/Form/Field.tsx

@@ -44,7 +44,7 @@ const Field: React.FC<FieldProps> = (props) => {
   } = props;
   const {
     getCallbacks,
-    getFieldValidate,
+    getFieldStatus,
     getFieldValue,
     getFieldsValue,
     setFieldsValue,
@@ -88,7 +88,7 @@ const Field: React.FC<FieldProps> = (props) => {
     );
   };
 
-  const validate = getFieldValidate?.(normalizedName);
+  const fieldStatus = getFieldStatus?.(normalizedName);
 
   // Normalize tooltip into { icon, ...tooltipProps }, or null when not provided.
   // Everything except `icon` is forwarded to <Tooltip>, so any Tooltip prop
@@ -152,8 +152,7 @@ const Field: React.FC<FieldProps> = (props) => {
         `${prefixCls}-item`,
         `${prefixCls}-item-${layout}`,
         {
-          [`${prefixCls}-item-${validate?.status}`]:
-            validate && validate.status,
+          [`${prefixCls}-item-${fieldStatus?.status}`]: fieldStatus?.status,
         },
         className,
       )}
@@ -200,18 +199,18 @@ const Field: React.FC<FieldProps> = (props) => {
         </div>
       </div>
       <AnimatePresence>
-        {validate && (
+        {fieldStatus?.message && (
           <motion.small
             initial={{ opacity: 0, y: -10 }}
             animate={{ opacity: 1, y: 0 }}
             exit={{ opacity: 0, y: -10 }}
             transition={{ duration: 0.16 }}
             className={clsx(`${prefixCls}-item-additional`, {
-              [`${prefixCls}-item-additional-${validate.status}`]:
-                validate.status,
+              [`${prefixCls}-item-additional-${fieldStatus.status}`]:
+                fieldStatus.status,
             })}
           >
-            {validate.message}
+            {fieldStatus.message}
           </motion.small>
         )}
       </AnimatePresence>

package/src/Form/demo/field-status.tsx

@@ -0,0 +1,108 @@
+import {
+  Button,
+  Form,
+  Input,
+  Space,
+  type FieldStatusData,
+} from '@rainbow-oh/yee-c';
+import React, { useState } from 'react';
+
+export default () => {
+  const [form] = Form.useForm();
+  const [currentStatus, setCurrentStatus] = useState<FieldStatusData | null>(
+    null,
+  );
+  const [submitResult, setSubmitResult] = useState('');
+
+  const applyStatus = (status: FieldStatusData | null) => {
+    form.setFieldStatus('username', status);
+    setCurrentStatus(form.getFieldStatus('username'));
+    setSubmitResult('');
+  };
+
+  return (
+    <Form
+      form={form}
+      initialValues={{ username: 'demo-user' }}
+      onFinish={() => setSubmitResult('Submit succeeded')}
+      onFinishFailed={() =>
+        setSubmitResult('Submit blocked by the blocking error')
+      }
+    >
+      <Form.Field
+        name="username"
+        label="Username"
+        rules={[{ required: true, message: 'Please input your username!' }]}
+      >
+        <Input placeholder="Please input your username" />
+      </Form.Field>
+
+      <Space style={{ marginTop: 28, flexWrap: 'wrap' }}>
+        <Button
+          onClick={() =>
+            applyStatus({
+              status: 'error',
+              message: 'This username is unavailable',
+            })
+          }
+        >
+          Error
+        </Button>
+        <Button
+          onClick={() =>
+            applyStatus({
+              status: 'error',
+              message: 'This error prevents submission',
+              blocking: true,
+            })
+          }
+        >
+          Blocking error
+        </Button>
+        <Button
+          onClick={() =>
+            applyStatus({
+              status: 'warning',
+              message: 'This username is commonly used',
+            })
+          }
+        >
+          Warning
+        </Button>
+        <Button
+          onClick={() =>
+            applyStatus({
+              status: 'success',
+              message: 'This username is available',
+            })
+          }
+        >
+          Success
+        </Button>
+        <Button
+          onClick={() =>
+            applyStatus({
+              status: 'info',
+              message: 'The username can be changed later',
+            })
+          }
+        >
+          Info
+        </Button>
+        <Button onClick={() => applyStatus(null)}>Clear</Button>
+        <Button type="primary" htmlType="submit">
+          Submit
+        </Button>
+      </Space>
+
+      <pre style={{ marginTop: 16 }}>
+        Current status: {JSON.stringify(currentStatus, null, 2)}
+      </pre>
+      {submitResult ? <div>{submitResult}</div> : null}
+      <div style={{ marginTop: 8, color: '#999' }}>
+        Tip: set Success, then clear the input — the rule error takes display
+        precedence over the manually set status.
+      </div>
+    </Form>
+  );
+};

package/src/Form/form-store.ts

@@ -9,6 +9,7 @@ import validate from './utils/validate';
 import type {
   Callbacks,
   FieldEntity,
+  FieldStatusData,
   FormInstance,
   FormListField,
   FormListOperation,
@@ -43,6 +44,7 @@ export class FormStore {
   private fieldEntities: FieldEntity[] = [];
   private fieldMap: Map<Name, FieldEntity> = new Map();
   private validateMessages: Map<Name, ValidateMessage[]> = new Map();
+  private fieldStatuses: Map<Name, FieldStatusData> = new Map();
   private initialized = false;
   private initialValues: Store = {};
   // List key manager
@@ -114,6 +116,76 @@ export class FormStore {
     return null;
   };
 
+  getFieldStatus = (name: NamePath): FieldStatusData | null => {
+    const normalizedName = stringifyPath(getNamePath(name));
+    const manualStatus = this.fieldStatuses.get(normalizedName);
+    const validateMessage = this.validateMessages.get(normalizedName)?.[0];
+
+    // Rule errors reflect the current value and auto-clear once validation
+    // passes, so they always take display precedence — a stale manually set
+    // status must never hide why submission failed.
+    if (validateMessage?.status === 'error') {
+      return {
+        status: 'error',
+        message: validateMessage.message,
+      };
+    }
+
+    if (manualStatus) {
+      return { ...manualStatus };
+    }
+
+    if (validateMessage) {
+      return {
+        status: validateMessage.status,
+        message: validateMessage.message,
+      };
+    }
+
+    return null;
+  };
+
+  setFieldStatus = (name: NamePath, status: FieldStatusData | null) => {
+    const normalizedName = stringifyPath(getNamePath(name));
+    if (!normalizedName) return;
+
+    if (status) {
+      this.fieldStatuses.set(normalizedName, { ...status });
+    } else {
+      this.fieldStatuses.delete(normalizedName);
+    }
+
+    this.fieldMap.get(normalizedName)?.onStoreChange();
+  };
+
+  // Delete entries whose key equals or nests under one of `names`
+  // (no names = delete all). Keeps rule messages and manual statuses in
+  // sync with the fields that reset/clear actually touched.
+  private deleteRelatedEntries = <T>(
+    entries: Map<Name, T>,
+    names?: NamePath[],
+  ): void => {
+    if (!names) {
+      entries.clear();
+      return;
+    }
+
+    const normalizedNames = names.map((name) =>
+      stringifyPath(getNamePath(name)),
+    );
+    Array.from(entries.keys()).forEach((fieldName) => {
+      if (
+        normalizedNames.some((name) => isRelatedNamePath(fieldName, name))
+      ) {
+        entries.delete(fieldName);
+      }
+    });
+  };
+
+  private clearFieldStatuses = (names?: NamePath[]) => {
+    this.deleteRelatedEntries(this.fieldStatuses, names);
+  };
+
   setFieldsValue = (newStore: Store, trigger: TRIGGER = 'onChange') => {
     if (trigger === 'reset' || trigger === 'clear') {
       this.store = newStore;
@@ -196,7 +268,10 @@ export class FormStore {
       });
     }
     this.callbacks?.onReset?.();
-    this.validateMessages.clear();
+    // A named reset only clears rule messages of the fields it touched;
+    // unrelated fields keep their (still valid) validation state.
+    this.deleteRelatedEntries(this.validateMessages, name);
+    this.clearFieldStatuses(name);
     this.groupEntities.forEach((entity) => entity.reset());
     this.refreshField();
   };
@@ -208,6 +283,7 @@ export class FormStore {
       acc[name] = undefined;
       return acc;
     }, {} as Store);
+    this.clearFieldStatuses(name);
     this.setFieldsValue(clearStore, 'clear');
   };
 
@@ -567,7 +643,19 @@ export class FormStore {
     const { onFinish, onFinishFailed } = this.callbacks;
     const fieldErrors = await this.validateFields();
     const groupErrors = await this.validateGroups(true);
-    const allErrors = [...fieldErrors, ...groupErrors];
+    const statusErrors = Array.from(this.fieldStatuses.entries())
+      .filter(
+        ([, status]) => status.status === 'error' && status.blocking === true,
+      )
+      .map(
+        ([name, status]): ValidateMessage => ({
+          name,
+          message: status.message ?? '',
+          value: this.getFieldValue(name),
+          status: 'error',
+        }),
+      );
+    const allErrors = [...fieldErrors, ...groupErrors, ...statusErrors];
     if (allErrors.length === 0) {
       onFinish?.(this.getFieldsValue());
     } else {
@@ -580,6 +668,8 @@ export class FormStore {
   getForm(): FormInstance {
     return {
       getFieldValidate: this.getFieldValidate,
+      getFieldStatus: this.getFieldStatus,
+      setFieldStatus: this.setFieldStatus,
       getFieldsValue: this.getFieldsValue,
       getFieldValue: this.getFieldValue,
       setFieldsValue: this.setFieldsValue,

package/src/Form/index.en-US.md

@@ -21,6 +21,7 @@ High performance form component with data scope management.
 <code src="./demo/layout.tsx" title="Layout" description="Different form layouts"></code>
 <code src="./demo/validate.tsx" title="Validation" description="Form validation"></code>
 <code src="./demo/async-validate.tsx" title="Async Validation" description="async validator for server-side checks like uniqueness"></code>
+<code src="./demo/field-status.tsx" title="Dynamic Field Status" description="Set error, warning, success, and info feedback dynamically with setFieldStatus"></code>
 <code src="./demo/list.tsx" title="Form List" description="Form list field usage"></code>
 <code src="./demo/form-table.tsx" title="Form Table" description="Form table field usage"></code>
 <code src="./demo/dynamic.tsx" title="Dynamic Form" description="Dynamic form items"></code>
@@ -52,12 +53,14 @@ High performance form component with data scope management.
 | Property              | Type                                                                                       | Description               |
 | --------------------- | ------------------------------------------------------------------------------------------ | ------------------------- |
 | getFieldValidate      | `(name: Name) => ValidateMessage \| null` | Get field validation (may lag before async validation completes; updates via onStoreChange) |
+| getFieldStatus        | `(name: NamePath) => FieldStatusData \| null` | Get the displayed field status; rule validation errors take display precedence, otherwise a manually set status overrides validation |
+| setFieldStatus        | `(name: NamePath, status: FieldStatusData \| null) => void` | Set field status and message dynamically, or pass `null` to clear it; only blocking errors prevent submission |
 | getFieldValue         | `(name: Name) => StoreValue`                                                           | Get field value           |
 | submit                | `() => Promise<ValidateMessage[]>`                                                          | Submit form (async, triggers onFinish only after validation completes) |
 | getFieldsValue        | `() => Values`                                                                             | Get all field values      |
 | setFieldsValue        | `(newStore: Store, trigger?: TRIGGER) => void`                                            | Set field values          |
 | setCallbacks          | `(callbacks: Callbacks) => void`                                                           | Set callbacks             |
-| resetFields           | `(name?: Name[]) => void`                                                              | Reset fields              |
+| resetFields           | `(name?: Name[]) => void`                                                              | Reset fields (values and validation state; passing name only affects related fields) |
 | clearFields           | `(name?: Name[]) => void`                                                              | Clear fields              |
 | validateField         | `(name: Name, trigger?: 'onChange' \| 'onBlur') => Promise<ValidateMessage[]>`                 | Validate single field     |
 | validateFields        | `(names?: Name[], trigger?: TRIGGER) => Promise<ValidateMessage[]>`                              | Validate multiple fields  |
@@ -129,6 +132,8 @@ High performance form component with data scope management.
 | Store           | `Record<string, StoreValue>`                                  |
 | Name            | `string`                                                      |
 | NamePath        | `string \| string[] \| number \| (string \| number)[]`        |
+| FieldStatus     | `'error' \| 'success' \| 'warning' \| 'info'`                 |
+| FieldStatusData | `{ status: FieldStatus; message?: string; blocking?: boolean }`   |
 | ValidateMessage | `{ name: NamePath \| NamePath[] \| undefined; message: string; value: unknown; status: 'error' \| 'success' \| 'warning' \| 'info' }` |
 | FieldEntity     | `{ props: fieldProps & { name?: NamePath }; onStoreChange: () => void }` |
 | TRIGGER         | `'onChange' \| 'onBlur' \| 'onSubmit' \| 'reset' \| 'clear' \| 'update'` |

package/src/Form/index.ts

@@ -29,6 +29,8 @@ Form.List = List;
 
 export type {
   FieldGroupProps,
+  FieldStatus,
+  FieldStatusData,
   FormInstance,
   FormListProps,
   FormProps,

package/src/Form/index.zh-CN.md

@@ -23,6 +23,7 @@ toc: 'content'
 <code src="./demo/layout.tsx" title="表单布局" description="不同的表单布局"></code>
 <code src="./demo/validate.tsx" title="表单校验" description="表单校验功能"></code>
 <code src="./demo/async-validate.tsx" title="异步校验" description="async validator 实现服务端唯一性校验等异步场景"></code>
+<code src="./demo/field-status.tsx" title="动态字段状态" description="通过 setFieldStatus 动态设置 error、warning、success 和 info 状态及提示"></code>
 
 ## API
 
@@ -51,12 +52,14 @@ toc: 'content'
 | 属性名                | 类型                                                                                       | 描述                                       |
 | --------------------- | ------------------------------------------------------------------------------------------ | ------------------------------------------ |
 | getFieldValidate      | `(name: Name) => ValidateMessage \| null` | 获取字段验证（异步校验未完成时可能读到旧值，最终会随 onStoreChange 更新） |
+| getFieldStatus        | `(name: NamePath) => FieldStatusData \| null` | 获取字段当前展示状态；规则校验错误优先展示，其余情况手动设置的状态优先于校验结果 |
+| setFieldStatus        | `(name: NamePath, status: FieldStatusData \| null) => void` | 动态设置字段状态和提示，传入 `null` 清除；仅 `blocking: true` 的 error 会阻止提交 |
 | getFieldValue         | `(name: Name) => StoreValue`                                                               | 获取字段值                                 |
 | submit                | `() => Promise<ValidateMessage[]>`                                                          | 提交表单（异步，校验完成后才触发 onFinish） |
 | getFieldsValue        | `() => Values`                                                                             | 获取所有字段值                             |
 | setFieldsValue        | `(newStore: Store, trigger?: TRIGGER) => void`                                             | 设置字段值                                 |
 | setCallbacks          | `(callbacks: Callbacks) => void`                                                           | 设置回调                                   |
-| resetFields           | `(name?: Name[]) => void`                                                                  | 重置字段                                   |
+| resetFields           | `(name?: Name[]) => void`                                                                  | 重置字段（值与校验状态；指定 name 时只影响相关字段） |
 | clearFields           | `(name?: Name[]) => void`                                                                  | 清空字段                                   |
 | validateField         | `(name: Name, trigger?: 'onChange' \| 'onBlur') => Promise<ValidateMessage[]>`                      | 校验单个字段                               |
 | validateFields        | `(names?: Name[], trigger?: TRIGGER) => Promise<ValidateMessage[]>`                                 | 校验多个字段                               |
@@ -128,6 +131,8 @@ toc: 'content'
 | Store             | `Record<string, StoreValue>`                                                                                                                                                          |
 | Name              | `string`                                                                                                                                                                              |
 | NamePath          | `string \| string[] \| number \| (string \| number)[]`                                                                                                                                |
+| FieldStatus       | `'error' \| 'success' \| 'warning' \| 'info'`                                                                                                                                           |
+| FieldStatusData   | `{ status: FieldStatus; message?: string; blocking?: boolean }`                                                                                                                           |
 | ValidateMessage   | `{ name: NamePath \| NamePath[] \| undefined; message: string; value: unknown; status: 'error' \| 'success' \| 'warning' \| 'info' }`                                                 |
 | FieldEntity       | `{ props: fieldProps & { name?: NamePath }; onStoreChange: () => void }`                                                                                                              |
 | TRIGGER           | `'onChange' \| 'onBlur' \| 'onSubmit' \| 'reset' \| 'clear' \| 'update'`                                                                                                              |

package/src/Form/interface.ts

@@ -106,6 +106,15 @@ export interface FormInstance<Values = any> {
    * Get field validation info
    */
   getFieldValidate: (name: Name) => ValidateMessage | null;
+  /**
+   * Get the displayed field status. Rule validation errors take display
+   * precedence; otherwise a manually set status overrides validation.
+   */
+  getFieldStatus: (name: NamePath) => FieldStatusData | null;
+  /**
+   * Set or clear a field's displayed status. Pass null to clear it.
+   */
+  setFieldStatus: (name: NamePath, status: FieldStatusData | null) => void;
   /**
    * Get field value
    */
@@ -253,11 +262,20 @@ export type Rule = {
     | Array<'onBlur' | 'onChange' | 'onSubmit'>;
 };
 
+export type FieldStatus = 'error' | 'success' | 'warning' | 'info';
+
+export type FieldStatusData = {
+  status: FieldStatus;
+  message?: string;
+  /** Whether an error status should prevent form submission. */
+  blocking?: boolean;
+};
+
 export type ValidateMessage = {
   name: NamePath | NamePath[] | undefined;
   message: string;
   value: unknown;
-  status: 'error' | 'success' | 'warning' | 'info';
+  status: FieldStatus;
 };
 
 export type FieldConfigurableTooltip = Omit<TooltipProps, 'children'> & {

package/src/Form/style/index.less

@@ -79,6 +79,18 @@
       &-error {
         color: var(--yee-error-color);
       }
+
+      &-warning {
+        color: var(--yee-warning-color);
+      }
+
+      &-success {
+        color: var(--yee-success-color);
+      }
+
+      &-info {
+        color: var(--yee-info-color);
+      }
     }
 
     // 表单校验态：在此重定义控件读取的 border / box-shadow 变量，
@@ -97,5 +109,19 @@
       --yee-input-focus-bs-color: var(--yee-warning-color-border);
       --yee-checkbox-border-color: var(--yee-warning-color);
     }
+
+    &&-success {
+      --yee-input-border-color: var(--yee-success-color);
+      --yee-input-hover-border-color: var(--yee-success-color-hover);
+      --yee-input-focus-bs-color: var(--yee-success-color-border);
+      --yee-checkbox-border-color: var(--yee-success-color);
+    }
+
+    &&-info {
+      --yee-input-border-color: var(--yee-info-color);
+      --yee-input-hover-border-color: var(--yee-info-color-hover);
+      --yee-input-focus-bs-color: var(--yee-info-color-border);
+      --yee-checkbox-border-color: var(--yee-info-color);
+    }
   }
 }

package/src/version.ts

@@ -4,7 +4,7 @@ declare global {
   }
 }
 
-export const version = "0.8.20";
+export const version = "0.9.0";
 
 if (typeof window !== 'undefined') {
   window.__yee_c_version__ = version;