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

package/src/form-ui/use-custom-field-value.ts

@@ -0,0 +1,124 @@
+import type { ComputedRef, InjectionKey, Ref, ShallowRef } from 'vue';
+
+import type { FormValidationTrigger } from './types';
+
+import { computed, inject, onUnmounted, provide, toRaw, watch } from 'vue';
+
+import { cloneDeep, isEqual } from '@melt-js/libs-vben/shared/utils';
+
+export interface FormCustomFieldContext {
+  /** 已注册的取值函数，同一表单项只接受一个 */
+  customValue: ShallowRef<(() => any) | undefined>;
+  disabled: ComputedRef<boolean>;
+  error: Readonly<Ref<string | undefined>>;
+  fieldName: string;
+  resetValidation: () => void;
+  setValue: (value: any) => void;
+  validateWithTrigger: (trigger: FormValidationTrigger) => void;
+  value: Readonly<Ref>;
+}
+
+export interface UseCustomFieldValueOptions {
+  /** 取值为对象/数组且原地修改时开启 */
+  deep?: boolean;
+  /** 挂载时把当前值写入表单（不触发校验） */
+  immediate?: boolean;
+}
+
+export interface UseCustomFieldValueReturn<T> {
+  /** 表单项的禁用态（含表单级、schema 级、依赖计算） */
+  disabled: ComputedRef<boolean>;
+  /** 表单项当前的校验错误 */
+  error: Readonly<Ref<string | undefined>>;
+  /** 所在表单项的字段名，不在表单项内时为 undefined */
+  fieldName: string | undefined;
+  /** 清除该表单项的校验状态 */
+  resetValidation: () => void;
+  /** 表单中该字段的值，可用于响应 setValues / resetForm */
+  value: ComputedRef<T | undefined>;
+}
+
+const CUSTOM_FIELD_INJECTION_KEY: InjectionKey<FormCustomFieldContext> = Symbol(
+  'VbenFormCustomField',
+);
+
+export function provideFormCustomField(context: FormCustomFieldContext) {
+  provide(CUSTOM_FIELD_INJECTION_KEY, context);
+}
+
+/**
+ * 让 VbenForm 表单项内的自定义组件把自己的值交给表单。
+ *
+ * 组件既没有绑定 `componentProps`（插槽用法），也没有实现 `modelValue` 时，
+ * 表单拿不到它的值，schema 上的 rules 也就无从校验。调用该函数后，取值函数的
+ * 结果会写回表单字段，并按表单项的 `validateOn` 触发校验。
+ *
+ * 值仍归表单所有：组件应继续用 `modelValue` 接收表单下发的值（插槽用法就是
+ * `v-bind="slotProps.componentProps"`），`setValues`、重置才能顺着 props 流回组件。
+ * 只有完全自持内部状态的组件，才需要用返回的 `value` 自行同步。
+ */
+export function useCustomFieldValue<T = any>(
+  customValue: () => T,
+  options: UseCustomFieldValueOptions = {},
+): UseCustomFieldValueReturn<T> {
+  const field = inject(CUSTOM_FIELD_INJECTION_KEY, null);
+
+  if (!field) {
+    console.warn('useCustomFieldValue 只能在 VbenForm 的表单项内部使用');
+    return {
+      disabled: computed(() => false),
+      error: computed(() => undefined),
+      fieldName: undefined,
+      resetValidation: () => {},
+      value: computed(() => undefined),
+    };
+  }
+
+  // 一个字段只能有一个值来源，后来者会互相覆盖
+  if (field.customValue.value) {
+    console.warn(
+      `表单项 ${field.fieldName} 已存在自定义取值函数，本次注册被忽略`,
+    );
+  } else {
+    field.customValue.value = customValue;
+
+    onUnmounted(() => {
+      if (field.customValue.value === customValue) {
+        field.customValue.value = undefined;
+      }
+    });
+
+    // deep 时组件原地改的就是这个对象，存一份副本进表单，
+    // 下次比较才不是拿它跟自己比，原地改动也就不会被当成没变
+    const toFormValue = (value: T) =>
+      options.deep ? cloneDeep(toRaw(value)) : value;
+
+    if (options.immediate) {
+      field.setValue(toFormValue(customValue()));
+    }
+
+    watch(
+      customValue,
+      (value) => {
+        // 组件由表单驱动（v-model / componentProps）时，setValues、重置下发的新值
+        // 会经组件再流回这里，此时值与表单一致：不重复写回，也不触发校验，
+        // 否则一点重置就立刻冒出必填错误
+        if (isEqual(value, toRaw(field.value.value))) {
+          return;
+        }
+        field.setValue(toFormValue(value));
+        field.resetValidation();
+        field.validateWithTrigger('change');
+      },
+      { deep: options.deep },
+    );
+  }
+
+  return {
+    disabled: field.disabled,
+    error: field.error,
+    fieldName: field.fieldName,
+    resetValidation: field.resetValidation,
+    value: computed(() => field.value.value as T | undefined),
+  };
+}

package/src/form-ui/use-form-context.ts

@@ -0,0 +1,148 @@
+import type { ZodType } from 'zod';
+
+import type { ComputedRef } from 'vue';
+
+import type { ExtendedFormApi, FormActions, VbenFormProps } from './types';
+
+import { computed, toRaw, unref, useSlots } from 'vue';
+
+import { createContext } from '@melt-js/comps-vben/shadcn-ui';
+import { isString, mergeWithArrayOverride, set } from '@melt-js/libs-vben/shared/utils';
+
+import {
+  object,
+  ZodIntersection,
+  ZodNumber,
+  ZodObject,
+  ZodString,
+  string as zodString,
+  ZodStringFormat,
+} from 'zod';
+import { getDefaultsForSchema } from 'zod-defaults';
+
+import { getFormFieldSchemas } from './form-render/schema';
+import { useFormRuntime } from './form-runtime';
+
+type ExtendFormProps = VbenFormProps & {
+  formApi?: ExtendedFormApi<any, any, any>;
+};
+
+export const [injectFormProps, provideFormProps] =
+  createContext<[ComputedRef<ExtendFormProps> | ExtendFormProps, FormActions]>(
+    'VbenFormProps',
+  );
+
+export const [injectComponentRefMap, provideComponentRefMap] =
+  createContext<Map<string, unknown>>('ComponentRefMap');
+
+/**
+ * Rebuild the schema used by zod-defaults, replacing native format nodes that
+ * zod-defaults does not recognise while retaining supported wrappers.
+ */
+function normalizeSchemaForDefaults(rule: ZodType): ZodType {
+  const rawRule = toRaw(rule) as any;
+
+  if (rawRule instanceof ZodStringFormat) {
+    return zodString();
+  }
+
+  if (rawRule instanceof ZodObject) {
+    const shape = Object.fromEntries(
+      Object.entries(rawRule.shape).map(([key, value]) => [
+        key,
+        normalizeSchemaForDefaults(value as ZodType),
+      ]),
+    );
+    return object(shape);
+  }
+
+  if (rawRule instanceof ZodIntersection) {
+    const { left, right } = (rawRule as any).def;
+    return normalizeSchemaForDefaults(left as ZodType).and(
+      normalizeSchemaForDefaults(right as ZodType),
+    );
+  }
+
+  if (rawRule.constructor.name === 'ZodDefault') {
+    const inner = normalizeSchemaForDefaults(rawRule.unwrap());
+    return inner.default(rawRule.def.defaultValue);
+  }
+
+  if (rawRule.constructor.name === 'ZodPipe') {
+    return normalizeSchemaForDefaults(rawRule.in).pipe(rawRule.out);
+  }
+
+  return rawRule;
+}
+
+export function useFormInitial(
+  props: ComputedRef<VbenFormProps> | VbenFormProps,
+) {
+  const slots = useSlots();
+  const initialValues = generateInitialValues();
+
+  const form = useFormRuntime(initialValues);
+
+  const delegatedSlots = computed(() => {
+    const resultSlots: string[] = [];
+
+    for (const key of Object.keys(slots)) {
+      if (key !== 'default') {
+        resultSlots.push(key);
+      }
+    }
+    return resultSlots;
+  });
+
+  function generateInitialValues() {
+    const initialValues: Record<string, any> = {};
+
+    const zodObject: Record<string, ZodType> = {};
+    getFormFieldSchemas(unref(props).schema ?? []).forEach((item) => {
+      if (Reflect.has(item, 'defaultValue')) {
+        set(initialValues, item.fieldName, item.defaultValue);
+      } else if (item.rules && !isString(item.rules)) {
+        // 检查规则是否适合提取默认值
+        const rawRules = toRaw(item.rules);
+        const customDefaultValue = getCustomDefaultValue(rawRules);
+        zodObject[item.fieldName] = normalizeSchemaForDefaults(rawRules);
+        if (customDefaultValue !== undefined) {
+          initialValues[item.fieldName] = customDefaultValue;
+        }
+      }
+    });
+
+    const schemaInitialValues = getDefaultsForSchema(object(zodObject));
+
+    const zodDefaults: Record<string, any> = {};
+    for (const key in schemaInitialValues) {
+      set(zodDefaults, key, schemaInitialValues[key]);
+    }
+    return mergeWithArrayOverride(initialValues, zodDefaults);
+  }
+  // 自定义默认值提取逻辑
+  function getCustomDefaultValue(rule: any): any {
+    rule = toRaw(rule);
+    if (rule instanceof ZodString || rule instanceof ZodStringFormat) {
+      return ''; // 字符串及其格式校验默认为空字符串
+    } else if (rule instanceof ZodNumber) {
+      return null; // 默认为 null（避免显示 0）
+    } else if (rule instanceof ZodObject) {
+      // 递归提取嵌套对象的默认值
+      const defaultValues: Record<string, any> = {};
+      for (const [key, valueSchema] of Object.entries(rule.shape)) {
+        defaultValues[key] = getCustomDefaultValue(valueSchema);
+      }
+      return defaultValues;
+    } else if (rule instanceof ZodIntersection) {
+      return getDefaultsForSchema(normalizeSchemaForDefaults(rule) as any);
+    } else {
+      return undefined; // 其他类型不提供默认值
+    }
+  }
+
+  return {
+    delegatedSlots,
+    form,
+  };
+}

package/src/form-ui/use-vben-form.ts

@@ -0,0 +1,81 @@
+import type {
+  BaseFormComponentType,
+  ExtendedFormApi,
+  FormValues,
+  VbenFormComponent,
+  VbenFormProps,
+} from './types';
+
+import { defineComponent, h, isReactive, onBeforeUnmount, watch } from 'vue';
+
+import { useSelector } from '@melt-js/libs-vben/shared/store';
+
+import { FormApi } from './form-api';
+import VbenUseForm from './vben-use-form.vue';
+
+type UseVbenFormReturn<
+  TValues extends FormValues,
+  T extends BaseFormComponentType,
+  P extends Record<string, any>,
+  TSubmitValues extends FormValues = TValues,
+> = readonly [
+  VbenFormComponent<TValues, T, P, TSubmitValues>,
+  ExtendedFormApi<TValues, T, P, TSubmitValues>,
+];
+
+export function useVbenForm<
+  T extends BaseFormComponentType = BaseFormComponentType,
+  P extends Record<string, any> = Record<string, never>,
+>(options: VbenFormProps<T, P>): UseVbenFormReturn<FormValues, T, P>;
+
+export function useVbenForm<
+  TValues extends FormValues,
+  T extends BaseFormComponentType = BaseFormComponentType,
+  P extends Record<string, any> = Record<string, never>,
+  TSubmitValues extends FormValues = TValues,
+>(
+  options: VbenFormProps<T, P, TValues, TSubmitValues>,
+): UseVbenFormReturn<TValues, T, P, TSubmitValues>;
+
+export function useVbenForm(
+  options: VbenFormProps<any, any, any, any>,
+): UseVbenFormReturn<any, any, any, any> {
+  const IS_REACTIVE = isReactive(options);
+  const api = new FormApi<any, any, any, any>(options);
+  const extendedApi = api as ExtendedFormApi<any, any, any, any>;
+  extendedApi.useStore = (selector: any) => {
+    return useSelector(api.store, selector);
+  };
+
+  const Form = defineComponent(
+    (props: VbenFormProps, { attrs, slots }) => {
+      onBeforeUnmount(() => {
+        api.unmount();
+      });
+      api.setState({ ...props, ...attrs });
+      return () =>
+        h(VbenUseForm, { ...props, ...attrs, formApi: extendedApi }, slots);
+    },
+    {
+      name: 'VbenUseForm',
+      inheritAttrs: false,
+    },
+  );
+  // Add reactivity support
+  if (IS_REACTIVE) {
+    watch(
+      () => options.schema,
+      () => {
+        api.setState({ schema: options.schema });
+      },
+      { immediate: true },
+    );
+  }
+
+  return [Form, extendedApi] as unknown as UseVbenFormReturn<
+    any,
+    any,
+    any,
+    any
+  >;
+}

package/src/form-ui/vben-form.vue

@@ -0,0 +1,79 @@
+<script setup lang="ts">
+import type { VbenFormProps } from './types';
+
+import { ref, watchEffect } from 'vue';
+
+import { useForwardPropsEmits } from '@melt-js/libs-vben/composables';
+
+import FormActions from './components/form-actions.vue';
+import {
+  COMPONENT_BIND_EVENT_MAP,
+  COMPONENT_MAP,
+  DEFAULT_FORM_COMMON_CONFIG,
+} from './config';
+import { Form } from './form-render';
+import { provideFormProps, useFormInitial } from './use-form-context';
+
+// 通过 extends 会导致热更新卡死
+interface Props extends VbenFormProps {}
+const props = withDefaults(defineProps<Props>(), {
+  actionWrapperClass: '',
+  collapsed: false,
+  collapsedRows: 1,
+  commonConfig: () => ({}),
+  handleReset: undefined,
+  handleSubmit: undefined,
+  layout: 'horizontal',
+  resetButtonOptions: () => ({}),
+  showCollapseButton: false,
+  showDefaultActions: true,
+  submitButtonOptions: () => ({}),
+  wrapperClass: 'grid-cols-1',
+});
+
+const forward = useForwardPropsEmits(props);
+
+const currentCollapsed = ref(false);
+
+const { delegatedSlots, form } = useFormInitial(props);
+
+provideFormProps([props, form]);
+
+const handleUpdateCollapsed = (value: boolean) => {
+  currentCollapsed.value = value;
+  // 触发收起展开状态变化回调
+  props.handleCollapsedChange?.(value);
+};
+
+watchEffect(() => {
+  currentCollapsed.value = props.collapsed;
+});
+</script>
+
+<template>
+  <Form
+    v-bind="forward"
+    :collapsed="currentCollapsed"
+    :component-bind-event-map="COMPONENT_BIND_EVENT_MAP"
+    :component-map="COMPONENT_MAP"
+    :form="form"
+    :global-common-config="DEFAULT_FORM_COMMON_CONFIG"
+  >
+    <template
+      v-for="slotName in delegatedSlots"
+      :key="slotName"
+      #[slotName]="slotProps"
+    >
+      <slot :name="slotName" v-bind="slotProps"></slot>
+    </template>
+    <template #default="slotProps">
+      <slot v-bind="slotProps">
+        <FormActions
+          v-if="showDefaultActions"
+          :model-value="currentCollapsed"
+          @update:model-value="handleUpdateCollapsed"
+        />
+      </slot>
+    </template>
+  </Form>
+</template>

package/src/form-ui/vben-use-form.vue

@@ -0,0 +1,187 @@
+<script setup lang="ts">
+import type { ExtendedFormApi, VbenFormProps, VbenFormSlots } from './types';
+
+import { nextTick, onMounted, readonly, watch } from 'vue';
+
+import { useForwardPriorityValues } from '@melt-js/libs-vben/composables';
+import { get, isEqual } from '@melt-js/libs-vben/shared/utils';
+
+import { useDebounceFn } from '@vueuse/core';
+
+import FormActions from './components/form-actions.vue';
+import {
+  COMPONENT_BIND_EVENT_MAP,
+  COMPONENT_MAP,
+  DEFAULT_FORM_COMMON_CONFIG,
+} from './config';
+import { Form } from './form-render';
+import { getFormFieldSchemas } from './form-render/schema';
+import {
+  provideComponentRefMap,
+  provideFormProps,
+  useFormInitial,
+} from './use-form-context';
+
+// 通过 extends 会导致热更新卡死，所以重复写了一遍
+interface Props extends VbenFormProps {
+  formApi?: ExtendedFormApi<any, any, any, any>;
+}
+
+const props = defineProps<Props>();
+defineSlots<
+  Record<string, ((props: Record<string, any>) => any) | undefined> &
+    VbenFormSlots<any, any, any>
+>();
+
+const formApi = props.formApi;
+if (!formApi) {
+  throw new Error('Form api is required in <VbenUseForm />');
+}
+
+const state = formApi.useStore();
+
+const forward = useForwardPriorityValues(props, state);
+
+const componentRefMap = new Map<string, unknown>();
+
+const { delegatedSlots, form } = useFormInitial(forward);
+const values = form.useValues();
+
+provideFormProps([forward, form]);
+provideComponentRefMap(componentRefMap);
+
+formApi.mount(form, componentRefMap);
+
+function handleUpdateCollapsed(value: boolean) {
+  props.formApi?.setState({ collapsed: value });
+  // 触发收起展开状态变化回调
+  forward.value.handleCollapsedChange?.(value);
+}
+
+function handleKeyDownEnter(event: KeyboardEvent) {
+  if (!state?.value.submitOnEnter || !forward.value.formApi?.isMounted) {
+    return;
+  }
+  // 如果是 textarea 不阻止默认行为，否则会导致无法换行。
+  // 跳过 textarea 的回车提交处理
+  if (event.target instanceof HTMLTextAreaElement) {
+    return;
+  }
+  event.preventDefault();
+
+  forward.value.formApi?.validateAndSubmit();
+}
+
+const handleValuesChangeDebounced = useDebounceFn(async () => {
+  state?.value.submitOnChange && forward.value.formApi?.validateAndSubmit();
+}, state?.value?.changeDebouncedTime ?? 300);
+
+let valuesChangeReady = false;
+
+onMounted(async () => {
+  // 只在挂载后开始监听，form.values会有一个初始化的过程
+  await nextTick();
+  valuesChangeReady = true;
+});
+
+watch(values, (currentValues, previousValues) => {
+  if (!valuesChangeReady) {
+    return;
+  }
+  const handleValuesChange = forward.value.handleValuesChange;
+  const submitOnChange = state?.value.submitOnChange;
+  if (!handleValuesChange && !submitOnChange) {
+    return;
+  }
+  const fields = getFormFieldSchemas(state?.value.schema ?? []).map(
+    (item) => item.fieldName,
+  );
+  if (handleValuesChange && fields.length > 0) {
+    const changedFields = fields.filter((field) => {
+      return !isEqual(
+        get(currentValues, field),
+        get(previousValues ?? {}, field),
+      );
+    });
+    if (changedFields.length > 0) {
+      handleValuesChange(readonly(currentValues), changedFields, () =>
+        formApi.formatValues(currentValues),
+      );
+    }
+  }
+  if (submitOnChange) {
+    handleValuesChangeDebounced();
+  }
+});
+</script>
+
+<template>
+  <Form
+    @keydown.enter="handleKeyDownEnter"
+    v-bind="forward"
+    :collapsed="state?.collapsed"
+    :component-bind-event-map="COMPONENT_BIND_EVENT_MAP"
+    :component-map="COMPONENT_MAP"
+    :form="form"
+    :global-common-config="DEFAULT_FORM_COMMON_CONFIG"
+  >
+    <template
+      v-for="slotName in delegatedSlots"
+      :key="slotName"
+      #[slotName]="slotProps"
+    >
+      <slot
+        :name="slotName"
+        v-bind="slotProps"
+        :form-api="formApi"
+        :values="form.values"
+      ></slot>
+    </template>
+    <template #default="slotProps">
+      <slot
+        v-if="$slots.default"
+        v-bind="slotProps"
+        :form-api="formApi"
+        :values="form.values"
+      ></slot>
+      <FormActions
+        v-else-if="forward.showDefaultActions"
+        :model-value="state?.collapsed"
+        @update:model-value="handleUpdateCollapsed"
+      >
+        <template #reset-before="resetSlotProps">
+          <slot
+            name="reset-before"
+            v-bind="resetSlotProps"
+            :form-api="formApi"
+            :values="form.values"
+          ></slot>
+        </template>
+        <template #submit-before="submitSlotProps">
+          <slot
+            name="submit-before"
+            v-bind="submitSlotProps"
+            :form-api="formApi"
+            :values="form.values"
+          ></slot>
+        </template>
+        <template #expand-before="expandBeforeSlotProps">
+          <slot
+            name="expand-before"
+            v-bind="expandBeforeSlotProps"
+            :form-api="formApi"
+            :values="form.values"
+          ></slot>
+        </template>
+        <template #expand-after="expandAfterSlotProps">
+          <slot
+            name="expand-after"
+            v-bind="expandAfterSlotProps"
+            :form-api="formApi"
+            :values="form.values"
+          ></slot>
+        </template>
+      </FormActions>
+    </template>
+  </Form>
+</template>

package/src/layout-ui/components/index.ts

@@ -0,0 +1,5 @@
+export { default as LayoutContent } from './layout-content.vue';
+export { default as LayoutFooter } from './layout-footer.vue';
+export { default as LayoutHeader } from './layout-header.vue';
+export { default as LayoutSidebar } from './layout-sidebar.vue';
+export { default as LayoutTabbar } from './layout-tabbar.vue';

package/src/layout-ui/components/layout-content.vue

@@ -0,0 +1,75 @@
+<script setup lang="ts">
+import type { CSSProperties } from 'vue';
+
+import type { ContentCompactType } from '@melt-js/libs-vben/typings';
+
+import { computed } from 'vue';
+
+interface Props {
+  /**
+   * 内容区域定宽
+   */
+  contentCompact: ContentCompactType;
+  /**
+   * 定宽布局宽度
+   */
+  contentCompactWidth: number;
+  padding: number;
+  paddingBottom: number;
+  paddingLeft: number;
+  paddingRight: number;
+  paddingTop: number;
+}
+
+const props = withDefaults(defineProps<Props>(), {});
+
+const overlayViewportStyle: CSSProperties = {
+  height:
+    'calc(var(--vben-viewport-height) - var(--vben-header-height, 0px) - var(--vben-footer-height, 0px))',
+};
+
+const style = computed((): CSSProperties => {
+  const {
+    contentCompact,
+    padding,
+    paddingBottom,
+    paddingLeft,
+    paddingRight,
+    paddingTop,
+  } = props;
+
+  const compactStyle: CSSProperties =
+    contentCompact === 'compact'
+      ? { margin: '0 auto', width: `${props.contentCompactWidth}px` }
+      : {};
+  return {
+    ...compactStyle,
+    flex: 1,
+    minWidth: 0,
+    padding: `${padding}px`,
+    paddingBottom: `${paddingBottom}px`,
+    paddingLeft: `${paddingLeft}px`,
+    paddingRight: `${paddingRight}px`,
+    paddingTop: `${paddingTop}px`,
+  };
+});
+</script>
+
+<template>
+  <main :style="style" class="relative min-w-0">
+    <div
+      v-if="$slots.overlay"
+      data-layout-region="content-overlay"
+      class="pointer-events-none sticky top-0 z-150 h-0 w-full"
+    >
+      <div
+        :style="overlayViewportStyle"
+        data-layout-region="overlay-viewport"
+        class="pointer-events-none relative min-h-0 w-full"
+      >
+        <slot name="overlay"></slot>
+      </div>
+    </div>
+    <slot></slot>
+  </main>
+</template>