feat: update the comments in English to enhance the readability of the code

Author: Ohh-889

primitives/filed-form /src/form-core/types.ts

@@ -22,7 +22,7 @@ export interface Rule {
   validateTrigger?: ValidateTrigger | ValidateTrigger[];
   validator?: (value: any, allValues: Store) => string | Promise<string>;
   warningOnly?: boolean;
-  whitespace?: boolean; // true 时，空白字符串视为“无值”
+  whitespace?: boolean; // When true, whitespace-only strings are treated as "empty"
 }
 
 export interface FieldEntity {
@@ -62,8 +62,8 @@ export interface Callbacks<Values = any> {
 
 export type ChangeTag =
   | 'errors'
-  | 'meta' // touched/dirty 变化
-  | 'mount' // 校验进行中状态变化
-  | 'unmount' // 错误/警告变化
+  | 'meta' // touched/dirty changes
+  | 'mount' // validating state changes
+  | 'unmount' // error/warning changes
   | 'validating'
-  | 'value'; // 字段注册/注销
+  | 'value'; // field register/unregister

primitives/filed-form /src/react/components/ComputedField.tsx

@@ -41,7 +41,7 @@ function ComputedField<Values = any>({
   useEffect(() => {
     const unregister = registerComputed(name, deps, compute);
 
-    // 订阅当前字段的变化 → 强制刷新
+    // Subscribe to current field changes → force refresh
     const unsub = registerField({
       changeValue: newValue => {
         updateValue(newValue);

primitives/filed-form /src/react/components/List.tsx

@@ -61,7 +61,7 @@ function List<Values = any>(props: ListProps<Values>) {
       key = keyManager.keys[i];
     }
     return {
-      key: String(key), // 稳定 key
+      key: String(key), // Stable key
       name: `${keyOfName(name)}.${i}`
     };
   });

primitives/filed-form /src/react/hooks/FieldContext.ts

@@ -13,7 +13,7 @@ import type { Meta } from '../../types/shared-types';
 
 import type { FormState } from './types';
 
-// 核心改造：给每条路径套上 Meta
+// Core change: wrap each path with Meta
 type BuildMetaShape<T, P extends string> = P extends `${infer K}.${infer R}`
   ? K extends keyof T
     ? T[K] extends readonly (infer U)[]
@@ -26,7 +26,7 @@ type BuildMetaShape<T, P extends string> = P extends `${infer K}.${infer R}`
       : never
     : never;
 
-// 把路径数组转成 Meta 层级结构
+// Convert an array of paths into a hierarchical Meta structure
 export type MetaShapeFromPaths<T, Ps extends readonly string[]> = Ps extends never[] | []
   ? { [K in keyof T]: Meta<K & string, PathToDeepType<T, K & string>> }
   : MergeUnion<Ps[number] extends infer P ? (P extends string ? BuildMetaShape<T, P> : never) : never>;
@@ -67,13 +67,13 @@ export interface OperationOptions<Values = any> {
 }
 
 export interface ValidateErrorEntity<Values = any> {
-  // 便于 UI 直接滚动
-  errorCount: number; // 可选：按 _pruneForSubmit 过滤后的值（给埋点/回放）
-  errorFields: Meta<string, any>[]; // 逐字段列表（用于滚动到第一个错误、逐项显示）
-  errorMap: Record<string, string[]>; // 同上：警告
-  firstErrorName?: string; // 全量当前值（未裁剪）
+  // For UI to scroll directly
+  errorCount: number; // Optional: values filtered by _pruneForSubmit (for analytics/replay)
+  errorFields: Meta<string, any>[]; // Per-field list (used to scroll to the first error and show items)
+  errorMap: Record<string, string[]>; // Same as above: warnings
+  firstErrorName?: string; // Full current values (not pruned)
   submittedAt: number;
-  values: Values; // 快速索引（表头红点、侧边分组统计）
+  values: Values; // Fast index (header red dot, side group statistics)
   warningMap: Record<string, string[]>;
 }
 
@@ -128,7 +128,7 @@ export interface InternalFormContext<Values = any> extends FormInstance<Values>
 }
 
 export interface InternalFormInstance<Values = any> extends InternalFormContext<Values> {
-  /** 内部 API，不建议外部使用 */
+  /** Internal API, not recommended for external use */
   getInternalHooks: () => InternalFormHooks<Values>;
 }
 

primitives/filed-form /src/react/hooks/useFieldState.ts

@@ -30,10 +30,10 @@ function useFieldState<Values = any, T extends AllPathsKeys<Values> = AllPathsKe
   opts?: UseFormFieldsStateOpts<Values>
 ): MetaShapeFromPaths<Values, T[]>;
 
-// 无参数：全量嵌套对象
+// No arguments: return the full nested object
 function useFieldState<Values = any>(): MetaShapeFromPaths<Values, []>;
 
-// form 参数：全量嵌套对象
+// With a form instance: return the full nested object
 function useFieldState<Values = any>(form: FormInstance<Values>): MetaShapeFromPaths<Values, []>;
 
 function useFieldState<Values = any>(
@@ -44,7 +44,7 @@ function useFieldState<Values = any>(
 
   const isFormInstance = isObject(names) && 'getFields' in names;
 
-  const form = isFormInstance ? names : (opts?.form ?? context); // 优先外部传入，否则走 context
+  const form = isFormInstance ? names : (opts?.form ?? context); // Prefer external form, otherwise use context
 
   if (!form) {
     throw new Error('Can not find FormContext. Please make sure you wrap Field under Form or provide a form instance.');
@@ -53,16 +53,16 @@ function useFieldState<Values = any>(
   let subscribeNames: AllPathsKeys<Values>[] | undefined;
 
   if (isFormInstance) {
-    // 外部传 form → 订阅全部
+    // External form provided → subscribe to all
     subscribeNames = undefined;
   } else if (isNil(names)) {
-    // 未传 names → 订阅全部
+    // No names provided → subscribe to all
     subscribeNames = undefined;
   } else if (isArray(names)) {
-    // 多字段
+    // Multiple fields
     subscribeNames = names;
   } else {
-    // 单字段
+    // Single field
     subscribeNames = [names];
   }
 
@@ -99,14 +99,14 @@ function useFieldState<Values = any>(
   }, []);
 
   if (!subscribeNames) {
-    // names 为空 → 返回 Map 形式
+    // names empty → return Map shape
     return state;
   }
   if (subscribeNames.length === 1) {
-    // 单字段 → 直接返回该字段的 meta
+    // Single field → return that field's meta directly
     return get(state, subscribeNames[0]);
   }
-  // 多字段 → 返回对象
+  // Multiple fields → return object
   return state;
 }
 

primitives/filed-form /src/utils/set.ts

@@ -75,7 +75,7 @@ export function unset<T>(obj: T, path: NamePath, options: SetOptions = { safeKey
     if (Array.isArray(node)) {
       const arr = node.slice();
       if (isLast) {
-        arr.splice(key as number, 1); // 删除该元素并前移
+        arr.splice(key as number, 1); // Remove the element and shift left
         return arr;
       }
       arr[key as number] = unsetImpl(arr[key as number], i + 1);
@@ -87,7 +87,7 @@ export function unset<T>(obj: T, path: NamePath, options: SetOptions = { safeKey
       for (const k in node as any) {
         if (Object.hasOwn(node, k)) {
           if (isLast && k === key) {
-            // 跳过该 key，不写入 out
+            // Skip this key; do not write to out
             continue;
           }
           out[k] = k === key ? unsetImpl((node as any)[k], i + 1) : (node as any)[k];

primitives/filed-form /src/utils/util.ts

@@ -73,28 +73,28 @@ export const anyOn = (set: Set<string>, names?: NamePath[]) =>
 export const allOn = (set: Set<string>, names?: NamePath[]) =>
   !names || names.length === 0 ? set.size > 0 : names.every(n => set.has(keyOfName(n)));
 
-// ✅ 递归收集变更路径（会把数组也往里走）
+// ✅ Recursively collect changed paths (descend into arrays as well)
 export const collectChangedLeafPaths = (
   input: any,
   prefix: (string | number)[] = [],
   out: (string | number)[][] = []
 ) => {
   if (Array.isArray(input)) {
-    // 数组节点本身也视为变更（用于 List 层级）
+    // Array nodes themselves are also treated as changes (used by List level)
     out.push([...prefix]);
     input.forEach((item, i) => collectChangedLeafPaths(item, [...prefix, keyOfName(i)], out));
   } else if (input && typeof input === 'object') {
     Object.keys(input).forEach(k => {
       collectChangedLeafPaths(input[keyOfName(k)], [...prefix, keyOfName(k)], out);
     });
   } else {
-    // 原子值，叶子
+    // Atomic value, leaf
     out.push([...prefix]);
   }
   return out;
 };
 
-// ✅ 如果想覆盖“删除/缩短数组”的场景（通知旧叶子），可以把旧值的叶子也并上
+// ✅ To cover cases like array deletion/shortening (to notify old leaves), union with the old value's leaves as well
 export const unionPaths = (a: (string | number)[][], b: (string | number)[][]) => {
   const s = new Set<string>();
   const res: (string | number)[][] = [];
@@ -123,19 +123,19 @@ export const isUnderPrefix = (key: string, prefix: string): boolean => {
 
 export function collectDeepKeys(obj: any, prefix: string = ''): string[] {
   if (obj === null || obj === undefined) {
-    // 叶子节点（值是 null/undefined）
+    // Leaf node (value is null/undefined)
     return [prefix];
   }
 
   if (typeof obj !== 'object' || obj instanceof Date) {
-    // 基础值（string/number/boolean/function/Date...）
+    // Primitive value (string/number/boolean/function/Date...)
     return [prefix];
   }
 
-  // 对象/数组：即使值是 undefined/null，也要保留路径
+  // Object/Array: keep the path even if value is undefined/null
   const keys: string[] = [];
 
-  // 如果是空对象/数组，也要把自己 push 出来
+  // If empty object/array, also push itself
   if (Object.keys(obj).length === 0) {
     keys.push(prefix);
     return keys;