taro-form-react 0.0.1

package/src/context/FormContext.tsx

@@ -0,0 +1,441 @@
+import React, { createContext, useCallback, useContext, useState } from "react";
+
+import { cloneDeep, get, merge, set, unset } from "lodash-es";
+
+import useMap from "@/hooks/useMap";
+
+import type { FormLabelProps } from "../components/Label";
+import type { NamePath } from "../types";
+
+import { namePathToString } from "../utils";
+
+export type FieldTransformResult = {
+  __form_internals_should_merge?: boolean;
+  value: any;
+};
+
+export type FieldRefActions = {
+  validate: () => (void | string[] | Promise<void | string[]>);
+  // transform 会将返回的对象 merge 到整个表单的 data 中
+  // 如果设置了 transform 且 __form_internals_should_merge 为 true
+  // 那么 field 的 name 会被忽略（仅在使用 getFieldsFormattedValue 时有效）
+  // 否则会直接使用返回的值
+  transform?: () => FieldTransformResult | Promise<FieldTransformResult>;
+};
+export type FieldRef = React.RefObject<FieldRefActions>;
+
+export type Field = {
+  refs: FieldRef[];
+  name: NamePath;
+  touched: boolean;
+  errors: string[];
+  initialValue?: any;
+  count: number;
+};
+
+export type FormContextProps = {
+  initialValues?: Record<string, any>;
+
+  showError?: boolean;
+  colon?: boolean;
+  labelProps?: FormLabelProps;
+  layout?: "horizontal" | "vertical";
+  validateFirst?: boolean | "parallel";
+  showErrors?: boolean;
+  passthroughErrors?: boolean;
+  // merge 会将 transform 返回的对象 merge 到整个表单的 data 中
+  // replace 会直接使用 transform 返回的值填充到对应的 field 中
+  transformBehavior?: "merge" | "replace";
+  getRequiredMessage?: (label: string) => string;
+
+  data: Record<string, any>;
+  setData: (data: Record<string, any>) => void;
+
+  fields: Map<string, Field>;
+  registerField: (name: NamePath, ref: FieldRef, initialValue?: any) => void;
+  unregisterField: (name: NamePath, ref: FieldRef) => void;
+
+  setFieldValue: (name: NamePath, value: any) => void;
+  getFieldValue: (name: NamePath) => any;
+  getFieldsValue: (nameList?: NamePath[]) => Record<string, any>;
+  getFieldsFormattedValue: (nameList?: NamePath[]) => Promise<Record<string, any>>;
+
+  setFields: (
+    fields: Array<
+      Pick<Field, "name">
+      & { touched?: boolean; }
+      & { value?: any }
+    >
+  ) => void;
+  getFields: (nameList?: NamePath[]) => Array<
+    Pick<Field, "name" | "touched" | "errors">
+    & { value: any }
+  >;
+
+  resetFields: (nameList?: NamePath[]) => void;
+
+  setFieldError: (name: NamePath, errors: string[]) => void;
+  getFieldError: (name: NamePath) => string[];
+
+  validateFields: (nameList?: NamePath[]) => Promise<void | Pick<Field, "name" | "errors">[]>;
+
+  isFieldsTouched: (nameList?: NamePath[], options?: { allTouched?: boolean }) => boolean;
+};
+
+const FormContext = createContext<FormContextProps | undefined>(void 0);
+
+export const useFormContext = () => {
+  const context = useContext(FormContext);
+  if (!context) {
+    throw new Error("useFormContext must be used within a FormProvider");
+  }
+  return context;
+};
+
+export type FormProviderConfiguration = Pick<FormContextProps, "colon" | "labelProps" | "layout" | "validateFirst" | "showErrors" | "passthroughErrors" | "transformBehavior" | "getRequiredMessage">;
+
+export type FormProviderProps =
+  & FormProviderConfiguration
+  & Pick<FormContextProps, "initialValues">
+  & {
+    onFieldsChange?: (changedFields: Array<{ name: NamePath; value: any }>, allFields: Array<{ name: NamePath; value: any }>) => void;
+    onValuesChange?: (changedValues: Record<string, any>, allValues: Record<string, any>) => void;
+    children: React.ReactNode;
+  };
+
+export const FormContextProvider: React.FC<FormProviderProps> = ({
+  initialValues,
+  onFieldsChange,
+  onValuesChange,
+  children,
+  ...props
+}) => {
+  const [fields, { set: setField, get: getField, remove: removeField }] = useMap<string, Field>();
+  const [data, setData] = useState<Record<string, any>>({});
+
+  const registerField = useCallback<FormContextProps["registerField"]>((name, ref, initialValue) => {
+    const nameString = namePathToString(name);
+    const value = initialValue ?? get(initialValues, name);
+    setData(data => {
+      const nextData = cloneDeep(data);
+      set(nextData, name, value);
+      return nextData;
+    });
+
+    const field = getField(nameString);
+    if (field) {
+      console.warn(`Field "${nameString}" is already registered, register multiple times may cause unexpected behavior.`);
+    }
+    const fieldToSet = field
+      ? {
+        ...field,
+        refs: [...field.refs, ref],
+        initialValue,
+        count: field.count + 1,
+      }
+      : {
+        refs: [ref],
+        name,
+        touched: false,
+        errors: [],
+        initialValue,
+        count: 1,
+      };
+    setField(nameString, fieldToSet);
+
+    onFieldsChange?.(
+      [{ name, value }],
+      Array.from(fields.values()).map(field => ({ name: field.name, value: get(data, field.name) })).concat([{ name, value }]),
+    );
+  }, [data, fields, getField, initialValues, onFieldsChange, setField]);
+
+  const unregisterField = useCallback<FormContextProps["unregisterField"]>((name, ref) => {
+    const nameString = namePathToString(name);
+    const field = getField(nameString);
+    if (field) {
+      if (field.count === 1) {
+        removeField(nameString);
+        setData(data => {
+          const nextData = cloneDeep(data);
+          unset(nextData, name);
+          return nextData;
+        });
+        onFieldsChange?.(
+          [{ name, value: get(data, name) }],
+          Array.from(fields.values()).map(field => ({ name: field.name, value: get(data, field.name) })).filter(f => f.name !== name),
+        );
+      } else {
+        setField(nameString, {
+          ...field,
+          count: field.count - 1,
+          refs: field.refs.filter(r => r !== ref),
+        });
+      }
+    } else {
+      console.warn(`Attempted to unregister field "${nameString}" that was never registered.`);
+    }
+  }, [data, fields, getField, onFieldsChange, removeField, setField]);
+
+  const setFieldValue = useCallback<FormContextProps["setFieldValue"]>((name, value) => {
+    const nameString = namePathToString(name);
+    const field = getField(nameString);
+    if (!field) {
+      console.warn(`Attempted to set value for field "${nameString}" that was never registered.`);
+      return;
+    }
+
+    setData(data => {
+      const nextData = cloneDeep(data);
+      set(nextData, name, value);
+      return nextData;
+    });
+
+    setField(nameString, { ...field, touched: true });
+
+    if (onValuesChange) {
+      const changes = {};
+      set(changes, name, value);
+      const all = cloneDeep(data);
+      set(all, name, value);
+      onValuesChange(changes, all);
+    }
+  }, [data, getField, onValuesChange, setField]);
+
+  const getFieldValue = useCallback<FormContextProps["getFieldValue"]>(name => {
+    return get(data, name);
+  }, [data]);
+
+  const getFieldsValue = useCallback<FormContextProps["getFieldsValue"]>(nameList => {
+    if (!nameList) return data;
+
+    const result = {} as Record<string, any>;
+    for (const name of nameList) {
+      const value = get(data, name);
+      set(result, name, value);
+    }
+    return result;
+  }, [data]);
+
+  const getFieldsFormattedValue = useCallback<FormContextProps["getFieldsFormattedValue"]>(async nameList => {
+    const realNameList = nameList ?? Array.from(fields.values()).map(field => field.name);
+
+    const result = {} as Record<string, any>;
+
+    for (const name of realNameList) {
+      const field = getField(namePathToString(name));
+      if (!field) {
+        console.warn(`Attempted to get formatted value for field "${namePathToString(name)}" that was never registered.`);
+        continue;
+      }
+
+      if (
+        field.refs.some(ref => !ref.current)
+      ) {
+        console.warn(`Attempted to get formatted value for field "${namePathToString(name)}" that has no or missing ref.`);
+        continue;
+      }
+
+      // only consider the last ref's transform result
+      const transformFunc = field.refs[field.refs.length - 1].current!.transform;
+      if (!transformFunc) {
+        set(result, name, get(data, name));
+      } else {
+        const transformedValue = await transformFunc();
+        if (transformedValue.__form_internals_should_merge) {
+          merge(result, transformedValue.value);
+        } else {
+          set(result, name, transformedValue);
+        }
+      }
+    }
+
+    return result;
+  }, [data, fields, getField]);
+
+  const setFields = useCallback<FormContextProps["setFields"]>(fields => {
+    const changes = {};
+    for (const fieldData of fields) {
+      const nameString = namePathToString(fieldData.name);
+      const field = getField(namePathToString(fieldData.name));
+      if (!field) {
+        console.warn(`Attempted to set field "${nameString}" that was never registered.`);
+        continue;
+      }
+
+      if (fieldData.touched !== undefined) {
+        setField(nameString, { ...field, touched: fieldData.touched });
+      }
+
+      setData(data => {
+        const nextData = cloneDeep(data);
+        set(nextData, fieldData.name, fieldData.value);
+        set(changes, fieldData.name, fieldData.value);
+        return nextData;
+      });
+    }
+    onValuesChange?.(changes, merge(cloneDeep(data), changes));
+  }, [data, getField, onValuesChange, setField]);
+
+  const getFields = useCallback<FormContextProps["getFields"]>(nameList => {
+    if (!nameList) {
+      return Array
+        .from(fields.values())
+        .map(field => ({ ...field, value: get(data, field.name) }));
+    }
+
+    const result = [] as ReturnType<FormContextProps["getFields"]>;
+    for (const name of nameList) {
+      const field = getField(namePathToString(name));
+      if (!field) {
+        console.warn(`Attempted to get field "${namePathToString(name)}" that was never registered.`);
+        continue;
+      }
+
+      const value = get(data, name);
+      result.push({ ...field, value });
+    }
+    return result;
+  }, [data, fields, getField]);
+
+  const resetFields = useCallback<FormContextProps["resetFields"]>(nameList => {
+    const fieldsToReset =
+      nameList
+        ?.map(name => {
+          const nameString = namePathToString(name);
+          const field = getField(nameString);
+          if (!field) {
+            console.warn(`Attempted to reset field "${nameString}" that was never registered.`);
+            return undefined;
+          }
+          return field;
+        })
+        .filter(v => v !== undefined)
+      ?? Array.from(fields.values());
+
+    for (const field of fieldsToReset) {
+      setData(data => {
+        const nextData = cloneDeep(data);
+        set(nextData, field.name, field.initialValue ?? get(initialValues, field.name));
+        return nextData;
+      });
+
+      setField(namePathToString(field.name), { ...field, touched: false });
+    }
+  }, [fields, getField, initialValues, setField]);
+
+  const setFieldError = useCallback<FormContextProps["setFieldError"]>((name, errors) => {
+    const nameString = namePathToString(name);
+    const field = getField(nameString);
+    if (!field) {
+      console.warn(`Attempted to set errors for field "${nameString}" that was never registered.`);
+      return;
+    }
+
+    setField(nameString, { ...field, errors });
+  }, [getField, setField]);
+
+  const getFieldError = useCallback<FormContextProps["getFieldError"]>(name => {
+    const field = getField(namePathToString(name));
+    if (!field) {
+      console.warn(`Attempted to get errors for field "${namePathToString(name)}" that was never registered.`);
+      return [];
+    }
+    return field.errors;
+  }, [getField]);
+
+  const validateFields = useCallback<FormContextProps["validateFields"]>(async nameList => {
+    const fieldsToValidate =
+      nameList
+        ?.map(name => {
+          const nameString = namePathToString(name);
+          const field = getField(nameString);
+          if (!field) {
+            console.warn(`Attempted to validate field "${nameString}" that was never registered.`);
+            return undefined;
+          }
+          return field;
+        })
+        .filter(v => v !== undefined)
+      ?? Array.from(fields.values());
+
+    const errors = [] as Pick<Field, "name" | "errors">[];
+
+    for (const field of fieldsToValidate) {
+      if (
+        field.refs.some(ref => !ref.current)
+      ) {
+        console.warn(`Attempted to validate field "${namePathToString(field.name)}" that has no or missing ref.`);
+        continue;
+      }
+
+      const result = await Promise.all(field.refs.map(ref => ref.current!.validate()));
+      const resultErrors = Array.from(new Set(result.flat().filter(Boolean))) as string[];
+      if (resultErrors.length > 0) {
+        errors.push({
+          name: field.name,
+          errors: resultErrors,
+        });
+      }
+    }
+
+    return errors.length > 0 ? errors : void 0;
+  }, [fields, getField]);
+
+  const isFieldsTouched = useCallback<FormContextProps["isFieldsTouched"]>((nameList, options) => {
+    const { allTouched = false } = options ?? {};
+
+    const fieldsToCheck =
+      nameList
+        ?.map(name => {
+          const nameString = namePathToString(name);
+          const field = getField(nameString);
+          if (!field) {
+            console.warn(`Attempted to check if field "${nameString}" is touched but it was never registered.`);
+            return undefined;
+          }
+          return field;
+        })
+        .filter(v => v !== undefined)
+      ?? Array.from(fields.values());
+
+    return allTouched
+      ? fieldsToCheck.every(field => field.touched)
+      : fieldsToCheck.some(field => field.touched);
+  }, [fields, getField]);
+
+  return (
+    <FormContext.Provider
+      value={{
+        initialValues,
+
+        ...props,
+
+        data,
+        setData,
+
+        fields,
+        registerField,
+        unregisterField,
+
+        setFieldValue,
+        getFieldValue,
+        getFieldsValue,
+        getFieldsFormattedValue,
+
+        setFields,
+        getFields,
+
+        resetFields,
+
+        setFieldError,
+        getFieldError,
+
+        validateFields,
+
+        isFieldsTouched,
+      }}
+    >
+      {children}
+    </FormContext.Provider>
+  );
+};

package/src/hooks/useFormConfiguration.ts

@@ -0,0 +1,37 @@
+import type { FormProviderConfiguration } from "../context/FormContext";
+
+import { useFormContext } from "../context/FormContext";
+
+const fallback = (value: any, fallbackValue: any) => (value === undefined ? fallbackValue : value);
+
+export default function useFormConfiguration ({
+  colon,
+  labelProps,
+  layout,
+  validateFirst,
+  passthroughErrors,
+  showErrors,
+  getRequiredMessage,
+}: Partial<FormProviderConfiguration> = {}) {
+  const {
+    colon: contextColon = true,
+    labelProps: contextLabelProps = {},
+    layout: contextLayout = "vertical",
+    validateFirst: contextValidateFirst = false,
+    passthroughErrors: contextPassthroughErrors = false,
+    showErrors: contextShowErrors = true,
+    transformBehavior: contextTransformBehavior = "replace",
+    getRequiredMessage: contextGetRequiredMessage = label => `${label}不能为空`,
+  } = useFormContext();
+
+  return {
+    colon: fallback(colon, contextColon),
+    labelProps: fallback(labelProps, contextLabelProps),
+    layout: fallback(layout, contextLayout),
+    validateFirst: fallback(validateFirst, contextValidateFirst),
+    passthroughErrors: fallback(passthroughErrors, contextPassthroughErrors),
+    showErrors: fallback(showErrors, contextShowErrors),
+    transformBehavior: contextTransformBehavior,
+    getRequiredMessage: fallback(getRequiredMessage, contextGetRequiredMessage),
+  };
+}

package/src/hooks/useFormItem.ts

@@ -0,0 +1,75 @@
+import { useCallback, useMemo, useRef } from "react";
+
+import { useDeepCompareEffect } from "ahooks";
+import { get } from "lodash-es";
+
+import type { FieldRef } from "../context/FormContext";
+import type { NamePath } from "../types";
+
+import { useFormContext } from "../context/FormContext";
+
+export type UseFormItemProps = {
+  ref: FieldRef;
+  name: NamePath;
+  initialValue?: any;
+  dependencies?: NamePath[];
+};
+
+export type UseFormItemResult = {
+  value: any;
+  errors: string[];
+  isTouched: boolean;
+  dependencyValues: any[];
+  onChange: (value: any) => void;
+  onErrorsChange: (errors: string[]) => void;
+};
+
+export default function useFormItem ({
+  ref,
+  name,
+  initialValue,
+  dependencies,
+}: UseFormItemProps): UseFormItemResult {
+  const isFieldRegistered = useRef(false);
+  const { data, registerField, unregisterField, setFieldValue, setFieldError, getFieldError, isFieldsTouched } = useFormContext();
+
+  useDeepCompareEffect(() => {
+    const currentName = name;
+    const currentRef = ref;
+    registerField(currentName, currentRef, initialValue);
+    isFieldRegistered.current = true;
+
+    return () => {
+      unregisterField(currentName, currentRef);
+      isFieldRegistered.current = false;
+    };
+  }, [name]);
+
+  const value = useMemo(() => {
+    return get(data, name);
+  }, [data, name]);
+
+  const errors = isFieldRegistered.current ? getFieldError(name) : [];
+  const isTouched = isFieldRegistered.current ? isFieldsTouched([name]) : false;
+
+  const onChange = useCallback((value: any) => {
+    setFieldValue(name, value);
+  }, [name, setFieldValue]);
+
+  const onErrorsChange = useCallback((errors: string[]) => {
+    setFieldError(name, errors);
+  }, [name, setFieldError]);
+
+  const dependencyValues = useMemo(() => {
+    return (dependencies || []).map(dep => get(data, dep));
+  }, [data, dependencies]);
+
+  return {
+    value,
+    errors,
+    isTouched,
+    onChange,
+    onErrorsChange,
+    dependencyValues,
+  };
+}

package/src/hooks/useMap.ts

@@ -0,0 +1,36 @@
+import { useCallback, useRef } from "react";
+
+import { useUpdate } from "ahooks";
+
+export default function useMap<
+  K extends string | number | symbol,
+  V,
+> () {
+  const map = useRef(new Map<K, V>());
+
+  const update = useUpdate();
+
+  const set = useCallback((key: K, value: V) => {
+    map.current.set(key, value);
+    update();
+  }, [update]);
+
+  const setAll = useCallback((newMap: Iterable<readonly [K, V]>) => {
+    map.current = new Map(newMap);
+    update();
+  }, [update]);
+
+  const remove = useCallback((key: K) => {
+    map.current.delete(key);
+    update();
+  }, [update]);
+
+  const reset = useCallback(() => {
+    map.current.clear();
+    update();
+  }, [update]);
+
+  const get = useCallback((key: K) => map.current.get(key), []);
+
+  return [map.current, { set, setAll, remove, reset, get }] as const;
+}

package/src/index.tsx

@@ -0,0 +1,99 @@
+import React, { forwardRef, useCallback, useImperativeHandle } from "react";
+
+import FormItem from "./components/Item";
+import FormKeep from "./components/Keep";
+import FormLabel from "./components/Label";
+import FormProvider from "./components/Provider";
+
+import { filterUndefined } from "@/utils/tools";
+
+import type { Field, FormContextProps, FormProviderConfiguration } from "./context/FormContext";
+
+import { FormContextProvider, useFormContext } from "./context/FormContext";
+
+export type FormActions =
+  Pick<FormContextProps, "setFieldValue" | "getFieldValue" | "getFieldsValue" | "setFields" | "getFields" | "resetFields" | "setFieldError" | "getFieldError" | "validateFields" | "isFieldsTouched">
+  & {
+    submit: () => Promise<Record<string, any> | undefined>;
+    reset: () => void;
+  };
+
+export type FormProps =
+  & FormProviderConfiguration
+  & {
+    // goes to FormProvider
+    initialValues?: Record<string, any>;
+    onFieldsChange?: (changedFields: Array<{ name: string[]; value: any }>, allFields: Array<{ name: string[]; value: any }>) => void;
+    onValuesChange?: (changedValues: Record<string, any>, allValues: Record<string, any>) => void;
+
+    // goes to InnerForm
+    omitNil?: boolean;
+    onFinish?: (values: Record<string, any>) => void;
+    onFinishFailed?: (errors: Pick<Field, "name" | "errors">[]) => void;
+    children: React.ReactNode;
+  };
+
+const InnerForm = forwardRef<FormActions, FormProps>(({
+  omitNil = true,
+  onFinish,
+  onFinishFailed,
+  children,
+}, ref) => {
+  const context = useFormContext();
+
+  const handleSubmit = useCallback(async () => {
+    const errors = await context.validateFields();
+    if (errors) {
+      onFinishFailed?.(errors);
+      return;
+    }
+    const values = omitNil ? filterUndefined(context.getFieldsValue(), true) : context.getFieldsValue();
+
+    try {
+      onFinish?.(values);
+    } catch (e) {
+      console.log(e);
+    }
+
+    return values;
+  }, [context, omitNil, onFinish, onFinishFailed]);
+
+  useImperativeHandle(ref, () => ({
+    submit: handleSubmit,
+    reset: context.resetFields,
+    setFieldValue: context.setFieldValue,
+    getFieldValue: context.getFieldValue,
+    getFieldsValue: context.getFieldsValue,
+    setFields: context.setFields,
+    getFields: context.getFields,
+    resetFields: context.resetFields,
+    setFieldError: context.setFieldError,
+    getFieldError: context.getFieldError,
+    validateFields: context.validateFields,
+    isFieldsTouched: context.isFieldsTouched,
+  }), [context.getFieldError, context.getFieldValue, context.getFields, context.getFieldsValue, context.isFieldsTouched, context.resetFields, context.setFieldError, context.setFieldValue, context.setFields, context.validateFields, handleSubmit]);
+
+  return children;
+});
+
+interface FormComponent extends React.ForwardRefExoticComponent<FormProps & React.RefAttributes<FormActions>> {
+  Item: typeof FormItem;
+  Provider: typeof FormProvider;
+  Label: typeof FormLabel;
+  Keep: typeof FormKeep;
+}
+
+const Form = forwardRef<FormActions, FormProps>((props, ref) => {
+  return (
+    <FormContextProvider {...props}>
+      <InnerForm ref={ref} {...props} />
+    </FormContextProvider>
+  );
+}) as FormComponent;
+
+Form.Item = FormItem;
+Form.Provider = FormProvider;
+Form.Label = FormLabel;
+Form.Keep = FormKeep;
+
+export default Form;