@tmagic/form 1.8.0-beta.25 → 1.8.0-beta.27

package/src/headless.ts

@@ -0,0 +1,78 @@
+/*
+ * Tencent is pleased to support the open source community by making TMagicEditor available.
+ *
+ * Copyright (C) 2025 Tencent.  All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * @fileoverview `@tmagic/form/headless`：无渲染校验入口，不加载 Vue 组件与样式。
+ *
+ * 纯 Node / CI 请从这里引入 `submitForm` / `validateForm` / `registerField`。
+ * `dialog: true` 需要 DOM，请改从 `@tmagic/form` 引入。
+ *
+ * ESM 下本入口与 `@tmagic/form` 共用同一批模块文件，字段注册表是同一份。
+ * CJS（`require`）下两者是各自独立的 UMD bundle，注册表不共享，同一进程里不要
+ * 同时 `require('@tmagic/form')` 和 `require('@tmagic/form/headless')`。
+ *
+ * @module @tmagic/form/headless
+ */
+
+export * from './schema';
+export * from './utils/form';
+export { builtInFields } from './utils/builtInFields';
+
+export {
+  clearFields,
+  getField as getFormField,
+  mergeFieldOptions,
+  registerBuiltInFields,
+  registerField,
+  registerFields,
+  unregisterField,
+} from './utils/registerField';
+export type { FieldOptions, HeadlessFieldOptions } from './utils/registerField';
+
+export type { FieldInnerConfig, FieldInnerConfigContext, FieldInnerConfigResult } from './utils/fieldInnerConfig';
+
+export { isLeafFieldType } from './utils/fieldValueEffects';
+export type { FieldMountValueEffect, FieldMountValueEffectContext } from './utils/fieldValueEffects';
+
+export {
+  applyMountValueEffects,
+  collectValidatableFields,
+  FieldInnerConfigError,
+  isFieldInnerConfigError,
+} from './utils/collectFields';
+export type { CollectedField } from './utils/collectFields';
+
+export { createHeadlessFormState, validateValues } from './utils/validateValues';
+export type { HeadlessFormStateOptions, ValidateValuesOptions, ValidateValuesResult } from './utils/validateValues';
+
+export { formatValidateError, getTextByName } from './utils/validateError';
+
+export {
+  clearTypeMatchRules,
+  deleteTypeMatchRule,
+  getTypeMatchRule,
+  MAX_SUGGESTION_OPTIONS,
+  optionSuggestion,
+  stringifyExampleValue,
+  validateTypeMatch,
+} from './utils/typeMatch';
+
+export type { TypeMatchValidateContext, TypeMatchValidator } from './utils/typeMatch';
+
+export { submitForm, validateForm } from './utils/submitHeadless';
+export type { SubmitFormOptions, SubmitFormResult, ValidateFormOptions } from './utils/submitHeadless';

package/src/index.ts

@@ -38,36 +38,55 @@ export { default as MGroupList } from './containers/table-group-list/TableGroupL
 export { default as MTableGroupList } from './containers/table-group-list/TableGroupList.vue';
 export { default as MText } from './fields/Text.vue';
 export { default as MNumber } from './fields/Number.vue';
-export { default as MNumberRange } from './fields/NumberRange.vue';
+export { default as MNumberRange } from './fields/NumberRange/Index.vue';
 export { default as MTextarea } from './fields/Textarea.vue';
 export { default as MHidden } from './fields/Hidden.vue';
-export { default as MDate } from './fields/Date.vue';
-export { default as MDateTime } from './fields/DateTime.vue';
+export { default as MDate } from './fields/Date/Index.vue';
+export { default as MDateTime } from './fields/DateTime/Index.vue';
 export { default as MTime } from './fields/Time.vue';
 export { default as MCheckbox } from './fields/Checkbox.vue';
 export { default as MSwitch } from './fields/Switch.vue';
 export { default as MDaterange } from './fields/Daterange.vue';
 export { default as MTimerange } from './fields/Timerange.vue';
 export { default as MColorPicker } from './fields/ColorPicker.vue';
-export { default as MCheckboxGroup } from './fields/CheckboxGroup.vue';
+export { default as MCheckboxGroup } from './fields/CheckboxGroup/Index.vue';
 export { default as MRadioGroup } from './fields/RadioGroup.vue';
-export { default as MDisplay } from './fields/Display.vue';
+export { default as MDisplay } from './fields/Display/Index.vue';
 export { default as MLink } from './fields/Link.vue';
 export { default as MSelect } from './fields/Select.vue';
 export { default as MCascader } from './fields/Cascader.vue';
-export { default as MDynamicField } from './fields/DynamicField.vue';
+export { default as MDynamicField } from './fields/DynamicField/Index.vue';
+
+export { builtInFields } from './utils/builtInFields';
 
 export {
-  deleteField as deleteFormField,
+  clearFields,
   getField as getFormField,
-  registerField as registerFormField,
-} from './utils/config';
+  mergeFieldOptions,
+  registerBuiltInFields,
+  registerField,
+  registerFields,
+  unregisterField,
+} from './utils/registerField';
+export type { FieldOptions, HeadlessFieldOptions } from './utils/registerField';
+
+export type { FieldInnerConfig, FieldInnerConfigContext, FieldInnerConfigResult } from './utils/fieldInnerConfig';
+
+export { isLeafFieldType } from './utils/fieldValueEffects';
+export type { FieldMountValueEffect, FieldMountValueEffectContext } from './utils/fieldValueEffects';
 
 export {
-  clearSilentLeafFieldTypes,
-  getSilentLeafFieldTypes,
-  registerSilentLeafFieldTypes,
-} from './utils/silentLeafFieldTypes';
+  applyMountValueEffects,
+  collectValidatableFields,
+  FieldInnerConfigError,
+  isFieldInnerConfigError,
+} from './utils/collectFields';
+export type { CollectedField } from './utils/collectFields';
+
+export { createHeadlessFormState, validateValues } from './utils/validateValues';
+export type { HeadlessFormStateOptions, ValidateValuesOptions, ValidateValuesResult } from './utils/validateValues';
+
+export { formatValidateError, getTextByName } from './utils/validateError';
 
 export {
   clearTypeMatchRules,
@@ -75,8 +94,6 @@ export {
   getTypeMatchRule,
   MAX_SUGGESTION_OPTIONS,
   optionSuggestion,
-  registerTypeMatchRule,
-  registerTypeMatchRules,
   stringifyExampleValue,
   validateTypeMatch,
 } from './utils/typeMatch';

package/src/plugin.ts

@@ -28,17 +28,17 @@ import TableGroupList from './containers/table-group-list/TableGroupList.vue';
 import Tabs from './containers/Tabs.vue';
 import Cascader from './fields/Cascader.vue';
 import Checkbox from './fields/Checkbox.vue';
-import CheckboxGroup from './fields/CheckboxGroup.vue';
+import CheckboxGroup from './fields/CheckboxGroup/Index.vue';
 import ColorPicker from './fields/ColorPicker.vue';
-import Date from './fields/Date.vue';
+import Date from './fields/Date/Index.vue';
 import Daterange from './fields/Daterange.vue';
-import DateTime from './fields/DateTime.vue';
-import Display from './fields/Display.vue';
-import DynamicField from './fields/DynamicField.vue';
+import DateTime from './fields/DateTime/Index.vue';
+import Display from './fields/Display/Index.vue';
+import DynamicField from './fields/DynamicField/Index.vue';
 import Hidden from './fields/Hidden.vue';
 import Link from './fields/Link.vue';
 import Number from './fields/Number.vue';
-import NumberRange from './fields/NumberRange.vue';
+import NumberRange from './fields/NumberRange/Index.vue';
 import RadioGroup from './fields/RadioGroup.vue';
 import Select from './fields/Select.vue';
 import Switch from './fields/Switch.vue';
@@ -46,8 +46,9 @@ import Text from './fields/Text.vue';
 import Textarea from './fields/Textarea.vue';
 import Time from './fields/Time.vue';
 import Timerange from './fields/Timerange.vue';
+import { builtInFields } from './utils/builtInFields';
 import { setConfig } from './utils/config';
-import { registerTypeMatchRules, type TypeMatchValidator } from './utils/typeMatch';
+import { type FieldOptions, registerBuiltInFields, registerFields } from './utils/registerField';
 import Form from './Form.vue';
 import FormDialog from './FormDialog.vue';
 import FormDrawer from './FormDrawer.vue';
@@ -55,59 +56,79 @@ import FormDrawer from './FormDrawer.vue';
 import './theme/index.scss';
 
 // #region FormInstallOptions
+/**
+ * `@tmagic/form` 插件安装选项。
+ */
 export interface FormInstallOptions {
+  /** 是否启用全局 flat 模式。 */
   flat?: boolean;
-  /** 自定义字段 type 的 typeMatch 校验规则，可覆盖内置规则或扩展业务字段 */
-  typeMatchRules?: Record<string, TypeMatchValidator>;
+  /**
+   * 自定义字段 type 的登记（叶子 / innerConfig / walk / typeMatch / component / container）。
+   * 与 `registerFields` 相同。
+   */
+  fields?: Record<string, FieldOptions>;
   [key: string]: any;
 }
 // #endregion FormInstallOptions
 
+const builtInFieldVue: Record<string, Pick<FieldOptions, 'component' | 'container'>> = {
+  text: { component: Text },
+  'img-upload': { component: Text },
+  number: { component: Number },
+  'number-range': { component: NumberRange },
+  textarea: { component: Textarea },
+  hidden: { component: Hidden },
+  date: { component: Date },
+  datetime: { component: DateTime },
+  daterange: { component: Daterange },
+  timerange: { component: Timerange },
+  time: { component: Time },
+  checkbox: { component: Checkbox },
+  switch: { component: Switch },
+  'color-picker': { component: ColorPicker },
+  'checkbox-group': { component: CheckboxGroup },
+  'radio-group': { component: RadioGroup },
+  display: { component: Display },
+  link: { component: Link },
+  select: { component: Select },
+  cascader: { component: Cascader },
+  'dynamic-field': { component: DynamicField },
+  container: { container: Container },
+  tab: { container: Tabs },
+  row: { container: Row },
+  'flex-layout': { container: FlexLayout },
+  fieldset: { container: Fieldset },
+  panel: { container: Panel },
+  step: { container: MStep },
+  table: { container: TableGroupList },
+  'group-list': { container: TableGroupList },
+  'table-group-list': { container: TableGroupList },
+};
+
 const defaultInstallOpt: FormInstallOptions = {};
 
 export default {
+  /**
+   * 安装 `@tmagic/form`：登记内置字段、挂载 `m-form` / `m-form-dialog` / `m-form-drawer`。
+   *
+   * @param app - Vue 应用
+   * @param [opt] - 安装选项
+   */
   install(app: App, opt: FormInstallOptions = {}) {
-    const option = Object.assign(defaultInstallOpt, opt);
+    const option = { ...defaultInstallOpt, ...opt };
 
     app.config.globalProperties.$MAGIC_FORM = option;
     setConfig(option);
 
-    if (option.typeMatchRules) {
-      registerTypeMatchRules(option.typeMatchRules);
+    registerBuiltInFields(builtInFields);
+    registerBuiltInFields(builtInFieldVue, app);
+
+    if (option.fields) {
+      registerFields(option.fields, app);
     }
 
     app.component('m-form', Form);
     app.component('m-form-dialog', FormDialog);
     app.component('m-form-drawer', FormDrawer);
-    app.component('m-form-container', Container);
-    app.component('m-form-fieldset', Fieldset);
-    app.component('m-form-group-list', TableGroupList);
-    app.component('m-form-panel', Panel);
-    app.component('m-form-row', Row);
-    app.component('m-form-step', MStep);
-    app.component('m-form-table', TableGroupList);
-    app.component('m-form-tab', Tabs);
-    app.component('m-form-flex-layout', FlexLayout);
-    app.component('m-fields-text', Text);
-    app.component('m-fields-img-upload', Text);
-    app.component('m-fields-number', Number);
-    app.component('m-fields-number-range', NumberRange);
-    app.component('m-fields-textarea', Textarea);
-    app.component('m-fields-hidden', Hidden);
-    app.component('m-fields-date', Date);
-    app.component('m-fields-datetime', DateTime);
-    app.component('m-fields-daterange', Daterange);
-    app.component('m-fields-timerange', Timerange);
-    app.component('m-fields-time', Time);
-    app.component('m-fields-checkbox', Checkbox);
-    app.component('m-fields-switch', Switch);
-    app.component('m-fields-color-picker', ColorPicker);
-    app.component('m-fields-checkbox-group', CheckboxGroup);
-    app.component('m-fields-radio-group', RadioGroup);
-    app.component('m-fields-display', Display);
-    app.component('m-fields-link', Link);
-    app.component('m-fields-select', Select);
-    app.component('m-fields-cascader', Cascader);
-    app.component('m-fields-dynamic-field', DynamicField);
   },
 };

package/src/schema.ts

@@ -1,6 +1,6 @@
 import type { ComputedRef, InjectionKey } from 'vue';
 
-import type { FormItemConfig } from '@tmagic/form-schema';
+import type { FormContext, FormItemConfig } from '@tmagic/form-schema';
 
 export * from '@tmagic/form-schema';
 
@@ -30,16 +30,14 @@ export const FORM_DIFF_CONFIG_KEY: InjectionKey<FormDiffConfig> = Symbol('mFormD
 export const FORM_TYPE_MATCH_VALID_KEY: InjectionKey<ComputedRef<boolean>> = Symbol('mFormTypeMatchValid');
 
 /**
- * 静默模式标记，由 `submitForm` / `validateForm` 以隐藏方式挂载临时表单时 provide（debug 弹层模式不提供）。
+ * 宿主业务上下文，由 `MForm`（或更外层的 Editor）通过 `provide` 下发。
  *
- * Container 会基于该标记，并对照 `getSilentLeafFieldTypes()`（默认 `LEAF_FIELD_TYPES`）
- * 跳过叶子字段的渲染，只保留 FormItem：字段校验由 FormItem 基于 model 值完成，与叶子 UI 组件实例无关。
- * 重型字段组件（如 vs-code）也可 inject 该标记跳过自身渲染，省去无谓的实例化开销。
+ * 嵌套表单（Link 子表单、FormBox、临时校验表单等）会自动继承最近祖先的 context，
+ * 无需层层透传。
  *
- * 注意：仅「挂载无值副作用」（不在 onMounted/watch immediate 中 emit change、不依赖 DOM 计算值）的
- * 字段组件可以安全跳过，接入前需逐一审计；业务扩展请使用 `registerSilentLeafFieldTypes`。
+ * 配置回调统一通过 `mForm.xxx` 读取，由 formState 的读穿 Proxy 落到这里。
  */
-export const FORM_SILENT_MODE_KEY: InjectionKey<boolean> = Symbol('mFormSilentMode');
+export const FORM_CONTEXT_KEY: InjectionKey<ComputedRef<FormContext>> = Symbol('mFormContext');
 
 export interface ValidateError {
   message: string;