@melt-js/comps-vben 0.0.0-stage → 2026.11.8-2

package/src/form-ui/form-runtime-field.ts

@@ -0,0 +1,82 @@
+import type { Component } from 'vue';
+
+import { defineComponent, h, markRaw, onUnmounted } from 'vue';
+
+type AsyncFieldValidator = (...args: any[]) => unknown;
+
+export type FieldValidationInvalidator = () => void;
+
+const asyncValidatorKeys = [
+  'onBlurAsync',
+  'onChangeAsync',
+  'onDynamicAsync',
+  'onSubmitAsync',
+] as const;
+
+export function createRuntimeFieldComponent(
+  fieldComponent: Component,
+  registerInvalidator: (
+    fieldName: string,
+    invalidator: FieldValidationInvalidator,
+  ) => () => void,
+) {
+  return markRaw(
+    defineComponent({
+      inheritAttrs: false,
+      setup(_, { attrs, slots }) {
+        // 恢复上游原始语义：attrs.name 任意值一律 String() 化（number →
+        // '123'，未传 → ''）。此处是字段注册键的兜底归一化，需要的就是
+        // 「任何输入都产生一个字符串键」；String(symbol) 也不会抛错，
+        // 无需窄化成 '' 改变注册键（否则与上游同名对象的键不一致）。
+        // oxlint-disable-next-line typescript/no-base-to-string
+        const fieldName = String(attrs.name ?? '');
+        let validationRunId = 0;
+        let cachedValidators: Record<string, any> | undefined;
+        let cachedWrappedValidators: Record<string, any> | undefined;
+        const unregisterInvalidator = registerInvalidator(fieldName, () => {
+          validationRunId += 1;
+        });
+        onUnmounted(unregisterInvalidator);
+
+        function wrapValidators(validators: Record<string, any>) {
+          if (validators === cachedValidators && cachedWrappedValidators) {
+            return cachedWrappedValidators;
+          }
+          const wrappedValidators = { ...validators };
+          for (const key of asyncValidatorKeys) {
+            const validator = validators[key] as
+              | AsyncFieldValidator
+              | undefined;
+            if (!validator) {
+              continue;
+            }
+            wrappedValidators[key] = async (...args: any[]) => {
+              const currentValidationRunId = ++validationRunId;
+              const result = await validator(...args);
+              return currentValidationRunId === validationRunId
+                ? result
+                : undefined;
+            };
+          }
+          cachedValidators = validators;
+          cachedWrappedValidators = wrappedValidators;
+          return wrappedValidators;
+        }
+
+        return () => {
+          const validators = attrs.validators as
+            | Record<string, any>
+            | undefined;
+          return h(
+            fieldComponent,
+            {
+              ...attrs,
+              ...(validators ? { validators: wrapValidators(validators) } : {}),
+            },
+            slots,
+          );
+        };
+      },
+    }),
+  );
+}

package/src/form-ui/form-runtime.ts

@@ -0,0 +1,325 @@
+import type { FieldValidationInvalidator } from './form-runtime-field';
+import type {
+  FormActions,
+  FormFieldName,
+  FormFieldValue,
+  FormResetOptions,
+  FormRuntimeState,
+  FormValues,
+} from './types';
+
+import { computed, shallowRef } from 'vue';
+
+import { mergeWithArrayOverride } from '@melt-js/libs-vben/shared/utils';
+
+import { batch } from '@tanstack/store';
+import { useForm } from '@tanstack/vue-form';
+
+import { createRuntimeFieldComponent } from './form-runtime-field';
+
+function normalizeError(error: unknown): string | undefined {
+  if (typeof error === 'string') {
+    return error;
+  }
+  if (error && typeof error === 'object' && 'message' in error) {
+    const message = Reflect.get(error, 'message');
+    return typeof message === 'string' ? message : undefined;
+  }
+  // 恢复上游原始语义：任何非空拒绝值一律 String() 化（含 '[object Object]'），
+  // 否则校验失败会被识别为通过并放行提交（如 reject({ code: 42 })）。
+  // 错误归一化要的就是「任何失败都必须产生消息」的兜底字符串化，
+  // no-base-to-string 防 '[object Object]' 噪音的意图在此不适用。
+  // oxlint-disable-next-line typescript/no-base-to-string
+  return error === undefined || error === null ? undefined : String(error);
+}
+
+function normalizeFieldMetaError(meta: unknown) {
+  if (!meta || typeof meta !== 'object' || !('errors' in meta)) {
+    return undefined;
+  }
+  const errors = Reflect.get(meta, 'errors');
+  return normalizeError(Array.isArray(errors) ? errors[0] : undefined);
+}
+
+export function useFormRuntime<TValues extends FormValues>(
+  defaultValues: TValues,
+): FormActions<TValues> {
+  const rawForm = useForm({
+    defaultValues,
+    onSubmit: () => {},
+  });
+  const values = rawForm.useSelector((formState) => formState.values);
+  const fieldMeta = rawForm.useSelector((formState) => formState.fieldMeta);
+  const isDirty = rawForm.useSelector((formState) => formState.isDirty);
+  const isSubmitting = rawForm.useSelector(
+    (formState) => formState.isSubmitting,
+  );
+  const isValid = rawForm.useSelector((formState) => formState.isValid);
+  const isValidating = rawForm.useSelector(
+    (formState) => formState.isValidating,
+  );
+  const manualErrors = shallowRef(new Map<string, string>());
+  const validationInvalidators = new Map<
+    string,
+    Set<FieldValidationInvalidator>
+  >();
+
+  function registerValidationInvalidator(
+    fieldName: string,
+    invalidator: FieldValidationInvalidator,
+  ) {
+    let fieldInvalidators = validationInvalidators.get(fieldName);
+    if (!fieldInvalidators) {
+      fieldInvalidators = new Set();
+      validationInvalidators.set(fieldName, fieldInvalidators);
+    }
+    fieldInvalidators.add(invalidator);
+    return () => {
+      invalidator();
+      fieldInvalidators.delete(invalidator);
+      if (fieldInvalidators.size === 0) {
+        validationInvalidators.delete(fieldName);
+      }
+    };
+  }
+
+  function invalidateFieldValidation(fieldName: string) {
+    for (const invalidator of validationInvalidators.get(fieldName) ?? []) {
+      invalidator();
+    }
+  }
+
+  const RuntimeField = createRuntimeFieldComponent(
+    rawForm.Field,
+    registerValidationInvalidator,
+  );
+
+  function getErrors() {
+    const result: Record<string, string> = {};
+    for (const [fieldName, meta] of Object.entries(fieldMeta.value)) {
+      const error = normalizeFieldMetaError(meta);
+      if (error) {
+        result[fieldName] = error;
+      }
+    }
+    for (const [fieldName, error] of manualErrors.value) {
+      result[fieldName] = error;
+    }
+    return result;
+  }
+
+  const errors = computed(getErrors);
+  const meta = computed(() => ({
+    dirty: isDirty.value,
+    submitting: isSubmitting.value,
+    valid: isValid.value && manualErrors.value.size === 0,
+    validating: isValidating.value,
+  }));
+  const runtimeState = computed<FormRuntimeState<TValues>>(() => ({
+    errors: errors.value,
+    meta: meta.value,
+    values: values.value,
+  }));
+
+  function getFieldError(fieldName: string) {
+    return (
+      manualErrors.value.get(fieldName) ??
+      normalizeFieldMetaError(Reflect.get(fieldMeta.value, fieldName))
+    );
+  }
+
+  function useFieldError(fieldName: string) {
+    const schemaError = rawForm.useSelector((formState) =>
+      normalizeFieldMetaError(Reflect.get(formState.fieldMeta, fieldName)),
+    );
+    return computed(
+      () => manualErrors.value.get(fieldName) ?? schemaError.value,
+    );
+  }
+
+  function useFieldValue<TFieldName extends FormFieldName<TValues>>(
+    fieldName: TFieldName,
+  ) {
+    return rawForm.useSelector(
+      () =>
+        rawForm.getFieldValue(fieldName as never) as FormFieldValue<
+          TValues,
+          TFieldName
+        >,
+    );
+  }
+
+  function useFieldValues<TFieldName extends FormFieldName<TValues>>(
+    fieldNames: readonly TFieldName[],
+  ) {
+    const selectedValues = fieldNames.map((fieldName) =>
+      useFieldValue(fieldName),
+    );
+    return computed(() => selectedValues.map((value) => value.value));
+  }
+
+  async function validateField(fieldName: string) {
+    await rawForm.validateField(fieldName as never, 'submit');
+    const error = getFieldError(fieldName);
+    return {
+      errors: error ? { [fieldName]: error } : {},
+      valid: !error,
+    };
+  }
+
+  async function validate() {
+    await rawForm.validateAllFields('submit');
+    const errors = getErrors();
+    return {
+      errors,
+      valid: Object.keys(errors).length === 0,
+    };
+  }
+
+  function setFieldError(fieldName: string, error?: string) {
+    invalidateFieldValidation(fieldName);
+
+    const nextManualErrors = new Map(manualErrors.value);
+    if (error) {
+      nextManualErrors.set(fieldName, error);
+    } else {
+      nextManualErrors.delete(fieldName);
+    }
+    manualErrors.value = nextManualErrors;
+
+    if (error || !rawForm.getFieldMeta(fieldName as never)) {
+      return;
+    }
+    rawForm.setFieldMeta(fieldName as never, (meta) => ({
+      ...meta,
+      errorMap: {},
+    }));
+  }
+
+  function clearValidation(
+    fieldNames?: FormFieldName<TValues> | FormFieldName<TValues>[],
+  ) {
+    let requestedFieldNames: FormFieldName<TValues>[] | undefined;
+    if (Array.isArray(fieldNames)) {
+      requestedFieldNames = fieldNames;
+    } else if (fieldNames) {
+      requestedFieldNames = [fieldNames];
+    }
+    const targetFieldNames = requestedFieldNames ?? [
+      ...new Set([
+        ...validationInvalidators.keys(),
+        ...Object.keys(rawForm.getAllErrors().fields),
+        ...manualErrors.value.keys(),
+      ]),
+    ];
+
+    for (const fieldName of targetFieldNames) {
+      setFieldError(fieldName, undefined);
+    }
+  }
+
+  async function reset(
+    resetState?: { values?: Partial<TValues> },
+    options?: FormResetOptions,
+  ) {
+    for (const fieldName of validationInvalidators.keys()) {
+      invalidateFieldValidation(fieldName);
+    }
+    manualErrors.value = new Map();
+    const partialValues = resetState?.values;
+    let resetValues: TValues | undefined;
+    if (partialValues) {
+      resetValues = options?.force
+        ? (partialValues as TValues)
+        : (mergeWithArrayOverride(
+            partialValues,
+            rawForm.options.defaultValues ?? defaultValues,
+          ) as TValues);
+    }
+    rawForm.reset(resetValues, {
+      keepDefaultValues: options?.keepDefaultValues,
+    });
+  }
+
+  async function submit() {
+    await rawForm.handleSubmit();
+  }
+
+  const actions: FormActions<TValues> = {
+    clearValidation,
+    get errors() {
+      return errors.value;
+    },
+    fieldComponent: RuntimeField,
+    get meta() {
+      return meta.value;
+    },
+    get values() {
+      return values.value;
+    },
+    getFieldError,
+    getFieldValue(fieldName) {
+      return rawForm.getFieldValue(fieldName as never) as FormFieldValue<
+        TValues,
+        typeof fieldName
+      >;
+    },
+    handleSubmit(callback?) {
+      return async (event?: Event) => {
+        event?.preventDefault();
+        event?.stopPropagation();
+        const result = await validate();
+        if (result.valid) {
+          await callback?.(values.value);
+        }
+      };
+    },
+    isFieldValid(fieldName) {
+      return !getFieldError(fieldName);
+    },
+    pushFieldValue(fieldName, value) {
+      rawForm.pushFieldValue(fieldName as never, value as never);
+    },
+    async removeFieldValue(fieldName, index) {
+      await rawForm.removeFieldValue(fieldName as never, index);
+    },
+    reset,
+    resetForm: reset,
+    setFieldError,
+    async setFieldValue(fieldName, value, shouldValidate) {
+      rawForm.setFieldValue(fieldName as never, value as never, {
+        dontValidate: !shouldValidate,
+      });
+      if (shouldValidate) {
+        await validateField(fieldName);
+      }
+    },
+    async setValues(values, shouldValidate) {
+      batch(() => {
+        for (const [fieldName, value] of Object.entries(values)) {
+          rawForm.setFieldValue(fieldName as never, value as never, {
+            dontValidate: !shouldValidate,
+          });
+        }
+      });
+      if (shouldValidate) {
+        await validate();
+      }
+    },
+    submit,
+    submitForm: submit,
+    useSelector(selector) {
+      return computed(() => selector(runtimeState.value));
+    },
+    useFieldError,
+    useFieldValue,
+    useFieldValues,
+    useValues() {
+      return values;
+    },
+    validate,
+    validateField,
+  };
+
+  return actions;
+}

package/src/form-ui/form-value-transform.ts

@@ -0,0 +1,235 @@
+import type {
+  ArrayToStringFields,
+  BaseFormComponentType,
+  FieldMappingTime,
+  FormFieldSchema,
+  FormSchema,
+  FormSchemaContext,
+  FormValues,
+} from './types';
+
+import { cloneDeep, formatDate, isFunction } from '@melt-js/libs-vben/shared/utils';
+
+import {
+  deleteValueByFieldName,
+  getValueByFieldName,
+  resolveValueFormatFieldName,
+  setValueByFieldName,
+} from './field-name';
+import {
+  getFormArraySchemaChildren,
+  getFormFieldSchemas,
+  resolveArrayChildFieldName,
+} from './form-render/schema';
+
+type AnyFormSchema<TValues extends FormValues> = FormSchema<
+  BaseFormComponentType,
+  Record<string, any>,
+  TValues
+>;
+
+type AnyFormFieldSchema<TValues extends FormValues> = FormFieldSchema<
+  BaseFormComponentType,
+  Record<string, any>,
+  TValues
+>;
+
+function processFields(
+  fields: string[],
+  separator: string,
+  values: Record<string, any>,
+) {
+  for (const field of fields) {
+    const value = values[field];
+    if (value === undefined || value === null) {
+      continue;
+    }
+    if (Array.isArray(value)) {
+      values[field] = value.join(separator);
+      continue;
+    }
+    if (typeof value !== 'string') {
+      continue;
+    }
+    if (value === '') {
+      values[field] = [];
+      continue;
+    }
+    const escapedSeparator = separator.replaceAll(
+      /[.*+?^${}()|[\]\\]/g,
+      String.raw`\$&`,
+    );
+    values[field] = value.split(new RegExp(escapedSeparator));
+  }
+}
+
+function applyArrayToStringFields(
+  values: Record<string, any>,
+  arrayToStringFields?: ArrayToStringFields,
+) {
+  if (!arrayToStringFields || !Array.isArray(arrayToStringFields)) {
+    return;
+  }
+
+  if (arrayToStringFields.every((item) => typeof item === 'string')) {
+    const fieldsConfig = arrayToStringFields;
+    const lastItem = fieldsConfig.at(-1) ?? '';
+    const hasSeparator = lastItem.length === 1;
+    const fields = hasSeparator ? fieldsConfig.slice(0, -1) : fieldsConfig;
+    processFields(fields, hasSeparator ? lastItem : ',', values);
+    return;
+  }
+
+  for (const fieldConfig of arrayToStringFields) {
+    if (!Array.isArray(fieldConfig)) {
+      continue;
+    }
+    const [fields, separator = ','] = fieldConfig;
+    if (!Array.isArray(fields)) {
+      console.warn(
+        `Invalid field configuration: fields should be an array of strings, got ${typeof fields}`,
+      );
+      continue;
+    }
+    processFields(fields, separator, values);
+  }
+}
+
+function applyRangeTimeFields(
+  values: Record<string, any>,
+  fieldMappingTime?: FieldMappingTime,
+) {
+  if (!fieldMappingTime || !Array.isArray(fieldMappingTime)) {
+    return;
+  }
+
+  for (const [
+    field,
+    [startTimeKey, endTimeKey],
+    format = 'YYYY-MM-DD',
+  ] of fieldMappingTime) {
+    if (startTimeKey && endTimeKey && values[field] === null) {
+      Reflect.deleteProperty(values, startTimeKey);
+      Reflect.deleteProperty(values, endTimeKey);
+    }
+    if (!values[field]) {
+      Reflect.deleteProperty(values, field);
+      continue;
+    }
+
+    const [startTime, endTime] = values[field];
+    if (format === null) {
+      values[startTimeKey] = startTime;
+      values[endTimeKey] = endTime;
+    } else if (isFunction(format)) {
+      values[startTimeKey] = format(startTime, startTimeKey);
+      values[endTimeKey] = format(endTime, endTimeKey);
+    } else {
+      const [startTimeFormat, endTimeFormat] = Array.isArray(format)
+        ? format
+        : [format, format];
+      values[startTimeKey] = startTime
+        ? formatDate(startTime, startTimeFormat)
+        : undefined;
+      values[endTimeKey] = endTime
+        ? formatDate(endTime, endTimeFormat)
+        : undefined;
+    }
+    Reflect.deleteProperty(values, field);
+  }
+}
+
+function applyValueFormatBySchemas<TValues extends FormValues>(
+  schemas: AnyFormFieldSchema<TValues>[],
+  values: Record<string, any>,
+  parentPath?: string,
+  parentContext?: FormSchemaContext<TValues>,
+) {
+  for (const schema of schemas) {
+    const fieldName = parentPath
+      ? resolveArrayChildFieldName(parentPath, schema.fieldName)
+      : schema.fieldName;
+    const row =
+      parentPath && parentContext?.rowPath
+        ? getValueByFieldName(values, parentContext.rowPath)
+        : parentContext?.row;
+    const schemaContext: FormSchemaContext<TValues> = {
+      ...parentContext,
+      fieldName,
+      originalFieldName: schema.fieldName,
+      rootValues: values as TValues,
+      row,
+    };
+
+    const children =
+      getFormArraySchemaChildren<AnyFormFieldSchema<TValues>>(schema);
+    if (children.length > 0) {
+      const arrayValue = getValueByFieldName(values, fieldName);
+      if (Array.isArray(arrayValue)) {
+        arrayValue.forEach((rowValue, index) => {
+          const rowPath = `${fieldName}[${index}]`;
+          applyValueFormatBySchemas(children, values, rowPath, {
+            arrayField: fieldName,
+            row: rowValue,
+            rowIndex: index,
+            rowPath,
+          });
+        });
+      }
+    }
+
+    if (!schema.valueFormat) {
+      continue;
+    }
+    const value = getValueByFieldName(values, fieldName);
+    deleteValueByFieldName(values, fieldName);
+    const formattedValue = schema.valueFormat(
+      value,
+      (key, nextValue) => {
+        setValueByFieldName(
+          values,
+          resolveValueFormatFieldName(key, parentPath),
+          nextValue,
+        );
+      },
+      values as TValues,
+      schemaContext,
+    );
+    if (formattedValue !== undefined) {
+      setValueByFieldName(values, fieldName, formattedValue);
+    }
+  }
+}
+
+export function applyFormValueFormats<TValues extends FormValues>(
+  originValues: Record<string, any>,
+  schemas: AnyFormSchema<TValues>[],
+) {
+  const values = cloneDeep(originValues);
+  applyValueFormatBySchemas(getFormFieldSchemas(schemas), values);
+  return values;
+}
+
+export function formatFormValues<TValues extends FormValues>(
+  originValues: Readonly<Record<string, any>>,
+  schemas: AnyFormSchema<TValues>[],
+  fieldMappingTime?: FieldMappingTime,
+  arrayToStringFields?: ArrayToStringFields,
+) {
+  const values = cloneDeep(originValues);
+  applyArrayToStringFields(values, arrayToStringFields);
+  applyRangeTimeFields(values, fieldMappingTime);
+  applyValueFormatBySchemas(getFormFieldSchemas(schemas), values);
+  return values;
+}
+
+export function transformRangeTimeValues(
+  originValues: Record<string, any>,
+  fieldMappingTime?: FieldMappingTime,
+  arrayToStringFields?: ArrayToStringFields,
+) {
+  const values = cloneDeep(originValues);
+  applyArrayToStringFields(values, arrayToStringFields);
+  applyRangeTimeFields(values, fieldMappingTime);
+  return values;
+}

package/src/form-ui/index.ts

@@ -0,0 +1,39 @@
+export { setupVbenForm } from './config';
+export { FormCodecError } from './form-codec';
+
+export type { FormCodecPhase } from './form-codec';
+
+export type {
+  BaseFormComponentType,
+  ExtendedFormApi,
+  FormActions,
+  FormCodec,
+  FormContextApi,
+  FormGroupSchema,
+  FormLayout,
+  FormSchemaContext,
+  FormValues,
+  FormValueSnapshot,
+  VbenFormActionSlotProps,
+  VbenFormComponent,
+  VbenFormDefaultSlotProps,
+  VbenFormFieldArrayProps,
+  FormFieldSchema as VbenFormFieldSchema,
+  VbenFormFieldSlotProps,
+  FormGroupSchema as VbenFormGroupSchema,
+  VbenFormProps,
+  VbenFormResolvedComponentProps,
+  FormSchema as VbenFormSchema,
+  VbenFormSlots,
+} from './types';
+
+export { useCustomFieldValue } from './use-custom-field-value';
+
+export type {
+  UseCustomFieldValueOptions,
+  UseCustomFieldValueReturn,
+} from './use-custom-field-value';
+
+export * from './use-vben-form';
+// export { default as VbenForm } from './vben-form.vue';
+export * as z from 'zod';

package/src/form-ui/rule-registry.ts

@@ -0,0 +1,17 @@
+import type { FormRuleValidator } from './types';
+
+const FORM_RULES = new Map<string, FormRuleValidator>();
+
+export function getFormRule(name: string) {
+  return FORM_RULES.get(name);
+}
+
+export function registerFormRules(
+  rules: Partial<Record<string, FormRuleValidator>>,
+) {
+  for (const [name, validator] of Object.entries(rules)) {
+    if (validator) {
+      FORM_RULES.set(name, validator);
+    }
+  }
+}