feat(form): enhance form functionality with field disable/hidden states and improved field management logic

Author: Ohh-889

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

@@ -450,9 +450,12 @@ class FormStore {
     const listeners = this._exactListeners.get(name);
 
     if (listeners) {
-      listeners.add({ cb: entity.changeValue, mask: ChangeTag.Value });
+      listeners.add({ cb: entity.changeValue, mask: ChangeTag.Value | ChangeTag.Disabled | ChangeTag.Hidden });
     } else {
-      this._exactListeners.set(name, new Set([{ cb: entity.changeValue, mask: ChangeTag.Value }]));
+      this._exactListeners.set(
+        name,
+        new Set([{ cb: entity.changeValue, mask: ChangeTag.Value | ChangeTag.Disabled | ChangeTag.Hidden }])
+      );
     }
 
     return () => {
@@ -478,15 +481,27 @@ class FormStore {
    */
   private setDisabled = (name: NamePath, disabled: boolean) => {
     const k = keyOfName(name);
+
+    const before = this._disabledKeys.has(k);
+    if (before === disabled) return; // 状态没变，避免多余通知
+
     disabled ? this._disabledKeys.add(k) : this._disabledKeys.delete(k);
+
+    this.enqueueNotify([k], ChangeTag.Disabled);
   };
 
   /**
-   * Sets the visibility state of a field
+   * Sets the hidden state of a field
    */
   private setHidden = (name: NamePath, hidden: boolean) => {
     const k = keyOfName(name);
+
+    const before = this._hiddenKeys.has(k);
+    if (before === hidden) return; // 状态没变
+
     hidden ? this._hiddenKeys.add(k) : this._hiddenKeys.delete(k);
+
+    this.enqueueNotify([k], ChangeTag.Hidden);
   };
 
   /**
@@ -1103,7 +1118,7 @@ class FormStore {
     }
   }
 
-  private getArrayFields = (name: NamePath, initialValue?: StoreValue[]) => {
+  private getArrayFields = (name: NamePath, initialValue?: StoreValue[], disabled?: boolean) => {
     const arr = (this.getFieldValue(name) as any[]) || initialValue || [];
 
     const ak = keyOfName(name);
@@ -1115,6 +1130,7 @@ class FormStore {
         keyMgr.keys[i] = keyMgr.id++;
       }
       return {
+        disabled,
         key: String(keyMgr.keys[i]),
         name: `${ak}.${i}`
       };
@@ -1140,13 +1156,6 @@ class FormStore {
 
   // ===== Submit =====
 
-  /**
-   * Registers a pre-submit transform function
-   */
-  usePreSubmit(fn: (values: Store) => Store) {
-    this._preSubmit.push(fn);
-  }
-
   /**
    * Removes disabled and hidden fields from values before submission
    */
@@ -1211,7 +1220,7 @@ class FormStore {
    * Submits the form after validation
    * Calls onFinish if validation passes, onFinishFailed if it fails
    */
-  private submit = () => {
+  private submit = (prune: boolean = true) => {
     this._isSubmitted = true;
     this._isSubmitting = true;
     this._submitCount++;
@@ -1220,7 +1229,8 @@ class FormStore {
       this._isSubmitting = false;
       if (ok) {
         this._isSubmitSuccessful = true;
-        this._callbacks.onFinish?.(this._store);
+        const values = prune ? this._pruneForSubmit(this._store) : this._store;
+        this._callbacks.onFinish?.(values);
       } else {
         this._isSubmitSuccessful = false;
         this._callbacks.onFinishFailed?.(this.buildFailedPayload());
@@ -1396,10 +1406,14 @@ class FormStore {
       getFieldWarning: this.getFieldWarning,
       getFormState: this.getFormState,
       getInternalHooks: this.getInternalHooks,
+      isDisabled: this.isDisabled,
+      isHidden: this.isHidden,
       resetFields: (names: string[] = []) => this.dispatch({ names, type: 'reset' }),
+      setDisabled: this.setDisabled,
       setFieldsValue: (values: Store, validate = false) => this.dispatch({ type: 'setFieldsValue', validate, values }),
       setFieldValue: (name: string, value: StoreValue, validate = false) =>
         this.dispatch({ name, type: 'setFieldValue', validate, value }),
+      setHidden: this.setHidden,
       submit: this.submit,
       use: this.use,
       validateField: (name: string, opts?: ValidateOptions) => this.dispatch({ name, opts, type: 'validateField' }),

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

@@ -27,8 +27,13 @@ export enum ChangeTag {
   Validated = 0b1000000,
   /** Field has been reset */
   Reset = 0b10000000,
+  /** Field disabled state has changed */
+  Disabled = 0b100000000,
+  /** Field hidden state has changed */
+  Hidden = 0b1000000000,
+
   /** Combination of all validation status flags */
-  Status = Errors | Warnings | Validated | Validating,
+  Status = Errors | Warnings | Validated | Validating | Disabled | Hidden,
   /** All possible change flags */
   All = 0x7fffffff
 }
@@ -41,9 +46,6 @@ export type ChangeMask = number;
 
 /**
  * Checks if a change mask contains a specific tag
- * @param mask - The change mask to check
- * @param tag - The tag to look for
- * @returns True if the mask contains the tag
  */
 export const hasTag = (mask: ChangeMask, tag: ChangeTag) => (mask & tag) !== 0;
 
@@ -66,8 +68,12 @@ export interface SubscribeMaskOptions {
   all?: boolean;
   /** Subscribe to dirty state changes */
   dirty?: boolean;
+  /** Subscribe to disabled state changes */
+  disabled?: boolean;
   /** Subscribe to validation error changes */
   errors?: boolean;
+  /** Subscribe to hidden state changes */
+  hidden?: boolean;
   /** Subscribe to field reset events */
   reset?: boolean;
   /** Subscribe to touched state changes */
@@ -98,6 +104,8 @@ export const toMask = (opt: SubscribeMaskOptions = {}): ChangeMask => {
   if (opt.validated) tags.push(ChangeTag.Validated);
   if (opt.touched) tags.push(ChangeTag.Touched);
   if (opt.dirty) tags.push(ChangeTag.Dirty);
+  if (opt.disabled) tags.push(ChangeTag.Disabled);
+  if (opt.hidden) tags.push(ChangeTag.Hidden);
   if (opt.reset) tags.push(ChangeTag.Reset);
 
   // Combine all selected tags into a single mask

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

@@ -77,10 +77,17 @@ function ComputedField<Values = any>({
   const fieldContext = useFieldContext<Values>();
 
   // Extract form instance methods
-  const { getFieldValue, getInternalHooks } = fieldContext as unknown as InternalFormInstance<Values>;
+  const { getFieldValue, getInternalHooks, isDisabled, isHidden } =
+    fieldContext as unknown as InternalFormInstance<Values>;
 
   // Local state to track computed value for re-rendering
-  const [value, updateValue] = useState(getFieldValue(name));
+
+  const value = getFieldValue(name);
+  const [_, forceUpdate] = useState({});
+
+  const fieldIsHidden = isHidden(name);
+
+  const fieldIsDisabled = isDisabled(name);
 
   // Get internal hooks for field registration and rule setting
   const { registerComputed, registerField, setFieldRules } = getInternalHooks();
@@ -92,8 +99,8 @@ function ComputedField<Values = any>({
     // Register field entity to receive value change notifications
     // This ensures the component re-renders when the computed value changes
     const unsub = registerField({
-      changeValue: newValue => {
-        updateValue(newValue);
+      changeValue: () => {
+        forceUpdate({});
       },
       initialValue: getFieldValue(name),
       name,
@@ -112,10 +119,14 @@ function ComputedField<Values = any>({
 
   // Prepare props to pass to child component
   const slotProps = {
-    readOnly: true, // Computed fields are always read-only
+    // Computed fields are always read-only
+    disabled: fieldIsDisabled,
+    readOnly: true,
     [valuePropName]: value ?? '' // Pass computed value using specified prop name
   };
 
+  if (fieldIsHidden) return null;
+
   // Render child component with computed value and read-only state
   return <Slot {...slotProps}>{children}</Slot>;
 }

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

@@ -11,7 +11,7 @@ import { Slot } from '@radix-ui/react-slot';
 import type { ReactElement } from 'react';
 import { useEffect, useId, useRef, useState } from 'react';
 import type { AllPathsKeys } from 'skyroc-type-utils';
-import { capitalize, getEventValue, isEqual, isNil, omitUndefined, toArray } from 'skyroc-utils';
+import { getEventValue, isEqual, omitUndefined, toArray } from 'skyroc-utils';
 
 import type { EventArgs, StoreValue } from '../../form-core/types';
 import type { Rule } from '../../form-core/validation';
@@ -21,8 +21,6 @@ import { useFieldContext } from '../hooks/FieldContext';
 export type FieldProps<Values> = {
   /** Child element to render as the form field */
   children?: ReactElement;
-  /** Control mode: 'controlled' for React controlled components, 'uncontrolled' for DOM-based */
-  controlMode?: 'controlled' | 'uncontrolled';
   /** Custom function to extract value from event arguments */
   getValueFromEvent?: (...args: EventArgs) => StoreValue;
   /** Function to transform value before passing to child component */
@@ -39,8 +37,6 @@ export type FieldProps<Values> = {
   rules?: Rule[];
   /** Event name that triggers value change (default: 'onChange') */
   trigger?: string;
-  /** Custom function to update uncontrolled component value */
-  unControlledValueChange?: (ref: any, newValue: StoreValue) => void;
   /** Event name(s) that trigger validation */
   validateTrigger?: string | string[] | false;
   /** Name of the prop to pass the field value (default: 'value') */
@@ -53,38 +49,6 @@ export type FieldProps<Values> = {
  *
  * @example
  * ```tsx
- * // Basic usage with validation
- * <Form>
- *   <Field
- *     name="email"
- *     rules={[
- *       { required: true, message: 'Email is required' },
- *       { type: 'email', message: 'Invalid email format' }
- *     ]}
- *   >
- *     <Input placeholder="Enter your email" />
- *   </Field>
- * </Form>
- * ```
- *
- * @example
- * ```tsx
- * // Controlled mode with custom validation trigger
- * <Field
- *   name="password"
- *   controlMode="controlled"
- *   validateTrigger={['onChange', 'onBlur']}
- *   rules={[
- *     { required: true, message: 'Password is required' },
- *     { min: 8, message: 'Password must be at least 8 characters' }
- *   ]}
- * >
- *   <Input type="password" placeholder="Enter password" />
- * </Field>
- * ```
- *
- * @example
- * ```tsx
  * // Custom value extraction and normalization
  * <Field
  *   name="phone"
@@ -105,15 +69,13 @@ function Field<Values = any>(props: FieldProps<Values>) {
   // Destructure props with default values
   const {
     children,
-    controlMode = 'uncontrolled',
     getValueFromEvent,
     initialValue,
     name,
     normalize,
     preserve = true,
     rules,
     trigger = 'onChange',
-    unControlledValueChange,
     validateTrigger,
     valuePropName = 'value',
     ...rest
@@ -139,17 +101,19 @@ function Field<Values = any>(props: FieldProps<Values>) {
     getFieldsValue,
     getFieldValue,
     getInternalHooks,
+    isDisabled,
+    isHidden,
     setFieldValue,
     validateField,
     validateTrigger: fieldValidateTrigger
   } = fieldContext as unknown as InternalFormInstance<Values>;
 
+  const fieldDIsabled = isDisabled(name);
+  const fieldIsHidden = isHidden(name);
+
   // Get internal hooks for field registration and rule setting
   const { registerField, setFieldRules } = getInternalHooks();
 
-  // Determine if field should be controlled
-  const isControlled = controlMode === 'controlled';
-
   // Merge field-level and form-level validation triggers
   const mergedValidateTrigger = validateTrigger || fieldValidateTrigger;
 
@@ -179,10 +143,11 @@ function Field<Values = any>(props: FieldProps<Values>) {
 
   // Prepare value props based on control mode
   // Controlled: use 'value' prop, Uncontrolled: use 'defaultValue' prop
-  const valueProps = isControlled ? { [valuePropName]: value } : { [`default${capitalize(valuePropName)}`]: value };
+  const valueProps = { [valuePropName]: value };
 
   // Create controlled props with change handler
   const controlledProps = omitUndefined({
+    disabled: fieldDIsabled,
     [trigger]: name
       ? (...args: any[]) => {
           let newValue: StoreValue;
@@ -223,24 +188,9 @@ function Field<Values = any>(props: FieldProps<Values>) {
   useEffect(() => {
     // Register field with form store
     const unregister = registerField({
-      changeValue: newValue => {
-        if (isControlled) {
-          // Force re-render for controlled components
-          forceUpdate({});
-          return;
-        }
-        // Handle uncontrolled component value updates
-        const el = cref.current;
-
-        if (!el) return;
-
-        if (unControlledValueChange) {
-          // Use custom value update function
-          unControlledValueChange(el, newValue);
-        } else {
-          // Default: update DOM element value directly
-          el.value = isNil(newValue) ? '' : (newValue as any);
-        }
+      changeValue: () => {
+        // Force re-render for controlled components
+        forceUpdate({});
       },
       initialValue,
       name,
@@ -256,6 +206,8 @@ function Field<Values = any>(props: FieldProps<Values>) {
     };
   }, []);
 
+  if (fieldIsHidden) return null;
+
   // Render child component with all necessary props
   return (
     <Slot

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

@@ -9,7 +9,7 @@
  */
 
 import React, { useEffect, useRef, useState } from 'react';
-import type { ArrayElementValue, ArrayKeys } from 'skyroc-type-utils';
+import type { AllPathsKeys, ArrayElementValue, ArrayKeys } from 'skyroc-type-utils';
 
 import type { InternalFormInstance, ListRenderItem } from '../hooks/FieldContext';
 import { useFieldContext } from '../hooks/FieldContext';
@@ -180,7 +180,10 @@ function List<Values = any>(props: ListProps<Values>) {
   const fieldContext = useFieldContext<Values>();
 
   // Extract array operations and internal hooks
-  const { arrayOp, getInternalHooks } = fieldContext as unknown as InternalFormInstance<Values>;
+  const { arrayOp, getInternalHooks, isDisabled, isHidden } = fieldContext as unknown as InternalFormInstance<Values>;
+
+  const fieldIsHidden = isHidden(name as AllPathsKeys<Values>);
+  const fieldIsDisabled = isDisabled(name as AllPathsKeys<Values>);
 
   // Get methods for array field management
   const { getArrayFields, registerField } = getInternalHooks();
@@ -189,7 +192,7 @@ function List<Values = any>(props: ListProps<Values>) {
   const [_, forceUpdate] = useState({});
 
   // Get current array fields with stable keys
-  const fields = getArrayFields(name, initialValue);
+  const fields = getArrayFields(name, initialValue, fieldIsDisabled);
 
   // Reference to cleanup function for field registration
   const unregisterRef = useRef<() => void>(null);
@@ -214,6 +217,8 @@ function List<Values = any>(props: ListProps<Values>) {
     };
   }, []);
 
+  if (fieldIsHidden) return null;
+
   // Render children with fields and array operations
   return <>{children(fields, arrayOp(name))}</>;
 }