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

package/dist/es/utils/form.js

@@ -1,10 +1,12 @@
+import { getConfig } from "./config.js";
 import { createTypeMatchValidator } from "./typeMatch.js";
-import { readonly } from "vue";
-import dayjs from "dayjs";
-import utc from "dayjs/plugin/utc";
+import { createFormStateProxy, mergeFormContexts } from "./formStateProxy.js";
+import { readonly, unref } from "vue";
 import { cloneDeep } from "lodash-es";
-import { getDesignConfig } from "@tmagic/design";
 import { getValueByKeyPath } from "@tmagic/utils";
+import dayjs from "dayjs";
+import utc from "dayjs/plugin/utc.js";
+import { getDesignConfig } from "@tmagic/design/headless";
 //#region packages/form/src/utils/form.ts
 var isTDesignAdapter = () => getDesignConfig("adapterType") === "tdesign-vue-next";
 /**
@@ -116,6 +118,79 @@ var getDefaultValue = function(mForm, { defaultValue, type, filter, multiple, na
 	if (type === "daterange" && !names) return [];
 	return "";
 };
+/**
+* formState 中与表单 props 无关的公共部分：字段注册表、消息组件、post 请求。
+*
+* 由渲染式表单（`Form.vue`）与无渲染校验（`createHeadlessFormState`）共用，
+* 保证两者提供给字段配置（`onChange` / `validator` / 异步 options 等）的能力一致。
+*/
+var fallbackMessage = {
+	error: (msg) => console.error(msg),
+	success: (msg) => console.log(msg),
+	warning: (msg) => console.warn(msg),
+	info: (msg) => console.info(msg),
+	closeAll: () => void 0
+};
+var fallbackMessageBox = {
+	alert: (msg) => console.log(msg),
+	confirm: (msg) => console.log(msg),
+	close: (msg) => console.log(msg)
+};
+var createFormStateBase = (ui) => {
+	const fields = /* @__PURE__ */ new Map();
+	const requestFuc = getConfig("request");
+	return {
+		fields,
+		setField: (prop, field) => fields.set(prop, field),
+		getField: (prop) => fields.get(prop),
+		deleteField: (prop) => fields.delete(prop),
+		$messageBox: ui?.$messageBox ?? fallbackMessageBox,
+		$message: ui?.$message ?? fallbackMessage,
+		post: (options) => {
+			if (requestFuc) return requestFuc({
+				method: "POST",
+				...options
+			});
+		}
+	};
+};
+/**
+* 配置项的 `name` 是否可用于从 model 中下钻取值。
+*
+* 供 `Container.vue` 与无渲染校验（`collectValidatableFields`）共用，两者对「该不该下钻」
+* 的判断必须一致。
+*/
+var isValidName = (name) => {
+	const valueType = typeof name;
+	if (valueType !== "string" && valueType !== "symbol" && valueType !== "number") return false;
+	if (name === "") return false;
+	if (valueType === "number") return name >= 0;
+	return true;
+};
+/**
+* 在 `prop` 后追加一段路径。
+*
+* 用于容器把 `prop` 透传给子级时再拼上索引 / key（如 group-list 的行、table 的行）。
+*/
+var appendProp = (prop = "", key) => `${prop}${prop ? "." : ""}${key}`;
+/**
+* 由父级 `prop` 与配置项 `name` 拼出该配置项的完整 `prop`（即 FormItem 的 prop）。
+*
+* 调用方传入的 name 已按 `config.name || ''` 归一化，空 name 表示该配置项不占据值路径上的一层，
+* 此时沿用父级 `prop`。
+*/
+var getItemProp = (prop = "", name = "") => name === "" ? prop ?? "" : appendProp(prop, name);
+/**
+* 归一化配置项的 `type`：求值动态 type、剥离容器语义的 type、驼峰转中划线、补默认值。
+*
+* 供 `Container.vue` 与无渲染校验共用，保证两者分派到的 type 完全一致。
+*/
+var resolveItemType = (mForm, config, props) => {
+	let type = "type" in (config || {}) ? config.type : "";
+	type = type && filterFunction(mForm, type, props);
+	if (type === "form" || type === "container") return "";
+	return type?.replace(/([A-Z])/g, "-$1").toLowerCase() || (config?.items ? "" : "text");
+};
 var filterFunction = (mForm, config, props) => {
 	if (typeof config === "function") return config(mForm, {
 		values: readonly(mForm?.initValues || {}),
@@ -135,18 +210,18 @@ var display = function(mForm, config, props) {
 	if (config === false) return false;
 	return true;
 };
-var getRules = function(mForm, r = [], props, typeMatchValid) {
+var buildRules = function(mForm, r = [], props, typeMatchValid, adapt = (validator) => validator) {
 	let rules = cloneDeep(r);
 	if (typeof rules === "object" && !Array.isArray(rules)) rules = [rules];
-	if (typeMatchValid?.value && !rules.some((r) => typeof r.typeMatch !== "undefined")) rules.push({ typeMatch: true });
+	if (unref(typeMatchValid) && !rules.some((r) => typeof r.typeMatch !== "undefined")) rules.push({ typeMatch: true });
 	return rules.map((item) => {
 		if (item.typeMatch) {
-			item.validator = adaptFormValidator(createTypeMatchValidator(mForm, props, item));
+			item.validator = adapt(createTypeMatchValidator(mForm, props, item));
 			return item;
 		}
 		if (typeof item.validator === "function") {
 			const fnc = item.validator;
-			item.validator = adaptFormValidator((rule, value, callback, source, options) => fnc({
+			item.validator = adapt((rule, value, callback, source, options) => fnc({
 				rule,
 				value: props.config.names ? props.model : value,
 				callback,
@@ -167,6 +242,18 @@ var getRules = function(mForm, r = [], props, typeMatchValid) {
 		return true;
 	});
 };
+var getRules = function(mForm, r = [], props, typeMatchValid) {
+	return buildRules(mForm, r, props, typeMatchValid, adaptFormValidator);
+};
+/**
+* 与 `getRules` 相同，但 validator 保持 async-validator（Element Plus）原生签名，不做 UI 库适配。
+*
+* 供无渲染校验（`validateValues`）使用：它直接把规则交给 async-validator 执行，
+* 不经过 TDesign 的 `validator(val)` 调用约定，因此不能套 `adaptFormValidator`。
+*/
+var getNativeRules = function(mForm, r = [], props, typeMatchValid) {
+	return buildRules(mForm, r, props, typeMatchValid);
+};
 var initValue = async (mForm, { initValues, config }) => {
 	if (!Array.isArray(config)) throw new Error("config应该为数组");
 	const initValuesCopy = cloneDeep(initValues);
@@ -207,40 +294,6 @@ var sortChange = (data, { prop, order }) => {
 	if (order === "ascending") data.sort((a, b) => a[prop] - b[prop]);
 	else if (order === "descending") data.sort((a, b) => b[prop] - a[prop]);
 };
-/**
-* 将 extendState 返回的扩展字段合并进 formState。
-*
-* - data 描述符（普通字段）通过 `formState[key] = value` 写入，走 reactive proxy 的 set，
-*   触发依赖通知；
-* - accessor 描述符（`{ get stage() { return ... } }`）按原样 defineProperty，调用方
-*   可控制读时求值；强制 `configurable: true` 以便下一次合并可再 define。
-*
-* 注意：extendState 只能向 formState「新增」字段，不允许覆盖其已有 key。
-* 调用方可通过 `reservedKeys` 传入合并前已存在的内置 key 快照（keyProp / popperClass /
-* config / initValues / isCompare / lastValues / parentValues / values / $emit / fields /
-* post 等），命中这些 key 时统一跳过并告警。
-*
-* 兜底：未传 `reservedKeys` 时，仍会拦截 props 派生的只读 getter 字段（无 setter），
-* 否则以普通字段形式赋值会让 proxy 的 set trap 抛出
-* `TypeError: 'set' on proxy: trap returned falsish`。
-*/
-var applyExtendState = (formState, state, reservedKeys) => {
-	if (!state) return;
-	for (const [key, descriptor] of Object.entries(Object.getOwnPropertyDescriptors(state))) {
-		if (reservedKeys?.has(key)) continue;
-		if (!("value" in descriptor)) {
-			descriptor.configurable = true;
-			Object.defineProperty(formState, key, descriptor);
-			continue;
-		}
-		const targetDescriptor = Object.getOwnPropertyDescriptor(formState, key);
-		if (targetDescriptor && !("value" in targetDescriptor) && typeof targetDescriptor.set !== "function") {
-			console.warn(`[MForm] extendState: "${key}" is a read-only field derived from props and cannot be assigned a plain value. Return it as a getter accessor if you really need to override it.`);
-			continue;
-		}
-		formState[key] = state[key];
-	}
-};
 var createObjectProp = (prop, key, name) => {
 	if (prop === "") return key;
 	const itemPath = `${prop}`.split(".");
@@ -250,4 +303,4 @@ var createObjectProp = (prop, key, name) => {
 	return `${[...itemPath, key].join(".")}`;
 };
 //#endregion
-export { adaptFormValidator, applyExtendState, createObjectProp, createValues, datetimeFormatter, display, filterFunction, getDataByPage, getRules, initValue, sortArray, sortChange };
+export { adaptFormValidator, appendProp, createFormStateBase, createFormStateProxy, createObjectProp, createValues, datetimeFormatter, display, filterFunction, getDataByPage, getItemProp, getNativeRules, getRules, initValue, isValidName, mergeFormContexts, resolveItemType, sortArray, sortChange };

package/dist/es/utils/formStateProxy.js

@@ -0,0 +1,75 @@
+import { unref } from "vue";
+//#region packages/form/src/utils/formStateProxy.ts
+/** 无上下文时共用的空对象，避免每次读取都分配新对象 */
+var EMPTY_CONTEXT = Object.freeze({});
+/**
+* 按优先级分层合并上下文，**靠后的层优先**。
+*
+* 用读穿 Proxy 而非 `{ ...a, ...b }`：展开会立即执行 accessor，
+* 而宿主允许用 `{ get stage() { ... } }` 这类读时求值的描述符。
+*/
+var mergeFormContexts = (...layers) => {
+	const stack = layers.filter((layer) => Boolean(layer));
+	if (stack.length === 0) return EMPTY_CONTEXT;
+	if (stack.length === 1) return stack[0];
+	const ordered = stack.slice().reverse();
+	const owner = (k) => ordered.find((layer) => Reflect.has(layer, k));
+	return new Proxy({}, {
+		get: (_t, k) => owner(k)?.[k],
+		has: (_t, k) => Boolean(owner(k)),
+		ownKeys: () => [...new Set(ordered.flatMap((layer) => Reflect.ownKeys(layer)))],
+		getOwnPropertyDescriptor: (_t, k) => {
+			for (const layer of ordered) {
+				const descriptor = Object.getOwnPropertyDescriptor(layer, k);
+				if (descriptor) return {
+					...descriptor,
+					configurable: true
+				};
+			}
+		}
+	});
+};
+/**
+* 将 coreState 与宿主业务上下文关联：读取时优先 core，miss 再读穿到 context。
+*
+* - `get` 用属性访问而非 `Reflect.get(t, k, receiver)`，避免破坏 Vue reactive 的 `__v_raw`；
+* - symbol 键一律只走 core，四个 trap 保持一致。context 是业务数据袋，不承载 symbol 键，
+*   把 Vue / 工具链的内部 symbol 隔离在 core 上才能让 `toRaw` / `isReactive` 判定正确；
+* - `ownKeys` + `getOwnPropertyDescriptor` 保证 `Object.entries(formState)` 能枚举到扩展字段
+*   （admin-web-next 的 `pickPanelFormStateExtendFields` 依赖此语义）；
+* - `set` 写入 coreState，第三方 `formState.xxx = v` 仍生效且优先于 context。
+*
+* 独立成文件，避免与 `form.ts` ↔ `typeMatch.ts` 形成循环依赖。
+*/
+var createFormStateProxy = (coreState, getContext) => {
+	const resolve = () => (typeof getContext === "function" ? getContext() : unref(getContext)) || EMPTY_CONTEXT;
+	return new Proxy(coreState, {
+		get(t, k) {
+			if (typeof k === "symbol") return Reflect.get(t, k);
+			const v = t[k];
+			if (v !== void 0 || Reflect.has(t, k)) return v;
+			return resolve()[k];
+		},
+		set(t, k, value) {
+			t[k] = value;
+			return true;
+		},
+		has: (t, k) => Reflect.has(t, k) || typeof k !== "symbol" && k in resolve(),
+		ownKeys: (t) => [.../* @__PURE__ */ new Set([...Reflect.ownKeys(t), ...Reflect.ownKeys(resolve()).filter((k) => typeof k !== "symbol")])],
+		getOwnPropertyDescriptor: (t, k) => {
+			const own = Reflect.getOwnPropertyDescriptor(t, k);
+			if (own) return own;
+			if (typeof k === "symbol") return void 0;
+			const ctx = resolve();
+			if (!(k in ctx)) return void 0;
+			return {
+				configurable: true,
+				enumerable: true,
+				writable: true,
+				value: ctx[k]
+			};
+		}
+	});
+};
+//#endregion
+export { createFormStateProxy, mergeFormContexts };

package/dist/es/utils/registerField.js

@@ -0,0 +1,158 @@
+import { clearFieldInnerConfigs, deleteFieldInnerConfig, registerFieldInnerConfig } from "./fieldInnerConfig.js";
+import { clearLeafFieldTypes, deleteLeafFieldType, registerLeafFieldType } from "./fieldValueEffects.js";
+import { clearTypeMatchRules, deleteTypeMatchRule, registerTypeMatchRule } from "./typeMatch.js";
+import { clearContainerWalkers, deleteContainerWalker, registerContainerWalker } from "./collectFields.js";
+import { toLine } from "@tmagic/utils";
+//#region packages/form/src/utils/registerField.ts
+var extraComponents = /* @__PURE__ */ new Map();
+var builtInComponents = /* @__PURE__ */ new Map();
+var applyVueComponent = (type, component, app, builtIn, kind) => {
+	const key = toLine(type);
+	if (builtIn) builtInComponents.set(key, component);
+	else extraComponents.set(key, component);
+	app?.component(`m-${kind}-${key}`, component);
+};
+/**
+* 把多份字段登记表按 type 浅合并。后一份只覆盖自己带了的 key，未出现的 key 保留前一份。
+*
+* 安装插件时用：Node 侧只登记 `headless`，浏览器再补 `component` / `container`。
+*
+* @param tables - 待合并的登记表，`undefined` 会被跳过
+* @returns 合并后的登记表
+*/
+var mergeFieldOptions = (...tables) => {
+	const result = {};
+	for (const table of tables) {
+		if (!table) continue;
+		for (const [type, options] of Object.entries(table)) result[type] = {
+			...result[type],
+			...pickDefinedFieldOptions(options)
+		};
+	}
+	return result;
+};
+var FIELD_OPTION_KEYS = [
+	"component",
+	"container",
+	"effect",
+	"walk",
+	"innerConfig",
+	"typeMatch"
+];
+var pickDefinedFieldOptions = (options) => {
+	if (!options) return {};
+	const next = {};
+	for (const key of FIELD_OPTION_KEYS) if (options[key] !== void 0) next[key] = options[key];
+	return next;
+};
+var extraFieldOptions = /* @__PURE__ */ new Map();
+var builtInFieldOptions = /* @__PURE__ */ new Map();
+var removeFormComponent = (type) => {
+	extraComponents.delete(toLine(type));
+};
+var clearFormComponents = () => {
+	extraComponents.clear();
+};
+/**
+* 按字段 type 取已登记的渲染组件（`codeSelect` 与 `code-select` 等价）。
+*
+* @param type - 字段 type
+* @returns 已登记的 Vue 组件；未登记则为 `undefined`
+*/
+var getField = (type) => {
+	const key = toLine(type);
+	return extraComponents.get(key) ?? builtInComponents.get(key);
+};
+var registerFieldImpl = (type, options, app, builtIn) => {
+	if (typeof type !== "string" || !type) return;
+	const key = toLine(type);
+	const store = builtIn ? builtInFieldOptions : extraFieldOptions;
+	const incoming = pickDefinedFieldOptions(options);
+	const merged = {
+		...store.get(key),
+		...incoming
+	};
+	store.set(key, merged);
+	if (incoming.walk && (incoming.innerConfig || typeof incoming.effect === "function")) console.warn(`[MForm] registerField("${key}"): walk is set together with innerConfig/effect; headless validation will use walk and innerConfig/effect will be ignored.`);
+	if (incoming.component && incoming.container) console.warn(`[MForm] registerField("${key}"): component and container are both set; getField will use container, and both m-fields-* / m-form-* will be registered.`);
+	if (merged.component) applyVueComponent(type, merged.component, app, builtIn, "fields");
+	if (merged.container) applyVueComponent(type, merged.container, app, builtIn, "form");
+	if (merged.typeMatch) registerTypeMatchRule(type, merged.typeMatch, builtIn);
+	if (merged.walk) {
+		registerContainerWalker(type, merged.walk, builtIn);
+		if (!builtIn) {
+			deleteLeafFieldType(type);
+			deleteFieldInnerConfig(type);
+		}
+		return;
+	}
+	if (!builtIn) deleteContainerWalker(type);
+	if (merged.innerConfig) {
+		registerFieldInnerConfig(type, merged.innerConfig, builtIn);
+		if (typeof merged.effect === "function") registerLeafFieldType(type, merged.effect, builtIn);
+		else if (!builtIn) deleteLeafFieldType(type);
+		return;
+	}
+	if (merged.container && !merged.component && typeof merged.effect !== "function") {
+		if (!builtIn) deleteLeafFieldType(type);
+		return;
+	}
+	if (!builtIn) deleteFieldInnerConfig(type);
+	registerLeafFieldType(type, merged.effect, builtIn);
+};
+/**
+* 登记一个字段 type 在无渲染校验里的行为，以及可选的渲染组件。
+*
+* `type` 会按 Container 的规则归一化为中划线形式（`codeSelect` 与 `code-select` 等价）。
+* 对同一 type 重复登记按字段浅合并：后一次只覆盖自己传入的 key，未传入的 key 保留。
+* 传入 `app` 且带了 `component` / `container` 时，会同步 `app.component('m-fields-*'` / `'m-form-*')`。
+*
+* @param type - 字段 type
+* @param [options] - 登记项；省略或空对象视为叶子
+* @param [app] - Vue 应用；省略则不调用 `app.component`
+*/
+var registerField = (type, options, app) => {
+	registerFieldImpl(type, options, app, false);
+};
+/**
+* 批量登记字段。
+*
+* @param fields - type 到登记项的映射
+* @param [app] - Vue 应用；省略则不调用 `app.component`
+*/
+var registerFields = (fields, app) => {
+	for (const [type, options] of Object.entries(fields)) registerFieldImpl(type, options, app, false);
+};
+/**
+* 登记内置字段（`clearFields` / `unregisterField` 不会清掉）。
+*
+* @param fields - type 到登记项的映射
+* @param [app] - Vue 应用；省略则不调用 `app.component`
+*/
+var registerBuiltInFields = (fields, app) => {
+	for (const [type, options] of Object.entries(fields)) registerFieldImpl(type, options, app, true);
+};
+/**
+* 删除业务侧对指定 type 的登记（不影响内置；主要用于单测）。
+*
+* @param type - 字段 type
+*/
+var unregisterField = (type) => {
+	extraFieldOptions.delete(toLine(type));
+	deleteLeafFieldType(type);
+	deleteFieldInnerConfig(type);
+	deleteTypeMatchRule(type);
+	deleteContainerWalker(type);
+	removeFormComponent(type);
+};
+/** 清空业务侧登记（不影响内置；主要用于单测）。 */
+var clearFields = () => {
+	extraFieldOptions.clear();
+	clearLeafFieldTypes();
+	clearFieldInnerConfigs();
+	clearTypeMatchRules();
+	clearContainerWalkers();
+	clearFormComponents();
+};
+//#endregion
+export { clearFields, getField, mergeFieldOptions, registerBuiltInFields, registerField, registerFields, unregisterField };

package/dist/es/utils/submitHeadless.js

@@ -0,0 +1,54 @@
+import { validateValues } from "./validateValues.js";
+import { cloneDeep } from "lodash-es";
+//#region packages/form/src/utils/submitHeadless.ts
+var throwIfAborted = (signal, fnName) => {
+	if (signal?.aborted) throw signal.reason ?? /* @__PURE__ */ new Error(`${fnName} aborted`);
+};
+var throwIfDialog = (dialog, fnName) => {
+	if (dialog) throw new Error(`[MForm] ${fnName}({ dialog: true }) is not available from @tmagic/form/headless. Import from @tmagic/form instead.`);
+};
+/**
+* `submitForm` 与 `validateForm` 共用的无渲染校验流程：中断检查 → `validateValues`。
+*/
+var validateWithoutRender = async (fnName, options) => {
+	const { signal, config, initValues, parentValues, keyProp, typeMatchValid, useFieldTextInError, context } = options;
+	throwIfAborted(signal, fnName);
+	const result = await validateValues({
+		config,
+		initValues,
+		parentValues,
+		keyProp,
+		popperClass: options.popperClass,
+		typeMatchValid,
+		useFieldTextInError,
+		context
+	});
+	throwIfAborted(signal, fnName);
+	return result;
+};
+/**
+* 以命令式方式对一份「表单配置 + 值」做一次校验并取回表单值（无渲染）。
+*
+* `@tmagic/form/headless` 不支持 `dialog: true`。
+*/
+var submitForm = async (options) => {
+	throwIfDialog(options.dialog, "submitForm");
+	const validated = await validateWithoutRender("submitForm", options);
+	if (validated.error) throw new Error(validated.error);
+	const values = options.native ? validated.values : cloneDeep(validated.values);
+	return options.returnChangeRecords ? {
+		values,
+		changeRecords: []
+	} : values;
+};
+/**
+* 以命令式方式对一份「表单配置 + 值」做一次静默校验（无渲染）。
+*
+* `@tmagic/form/headless` 不支持 `dialog: true`。
+*/
+var validateForm = async (options) => {
+	throwIfDialog(options.dialog, "validateForm");
+	return (await validateWithoutRender("validateForm", options)).error;
+};
+//#endregion
+export { submitForm, validateForm, validateWithoutRender };

package/dist/es/utils/tableGroupList.js

@@ -0,0 +1,85 @@
+import { cloneDeep } from "lodash-es";
+//#region packages/form/src/utils/tableGroupList.ts
+/**
+* table / group-list 是同一份配置的两种展示形态，可以互相切换（`TableGroupList.vue`）。
+*
+* 本模块收口两种形态之间的配置派生，以及各形态下「子项配置怎么算出来」的规则，
+* 供渲染（`TableGroupList.vue` / `GroupListItem.vue` / `useTableColumns.ts`）与无渲染校验
+* （`collectValidatableFields`）共用，避免两条链路各写一份而产生偏差。
+*/
+/** group-list 形态的 type（兼容驼峰与中划线两种写法） */
+var isGroupListType = (type) => type === "groupList" || type === "group-list";
+/** 按 label 文案长度估算 label 宽度（中文按 20px、其他按 8px，最小 80px） */
+var calcLabelWidth = (label) => {
+	if (!label) return "0px";
+	const zhLength = label.match(/[^\x00-\xff]/g)?.length || 0;
+	const chLength = label.length - zhLength;
+	return `${Math.max(chLength * 8 + zhLength * 20, 80)}px`;
+};
+/** 由 group-list 形态的配置派生出 table 形态所需的配置；本身已是 table 形态则原样返回 */
+var toTableConfig = (config) => {
+	if (!isGroupListType(config.type)) return config;
+	const source = config;
+	return {
+		...config,
+		type: "table",
+		groupItems: source.items,
+		items: source.tableItems || source.items.map((item) => ({
+			...item,
+			label: item.label || item.text,
+			text: null
+		}))
+	};
+};
+/** 由 table 形态的配置派生出 group-list 形态所需的配置；本身已是 group-list 形态则原样返回 */
+var toGroupListConfig = (config) => {
+	if (isGroupListType(config.type)) return config;
+	const source = config;
+	return {
+		...config,
+		type: "groupList",
+		tableItems: source.items,
+		items: source.groupItems || source.items.map((item) => {
+			const text = item.text || item.label;
+			return {
+				...item,
+				text,
+				labelWidth: calcLabelWidth(text),
+				span: item.span || 12
+			};
+		})
+	};
+};
+/**
+* group-list 每一行渲染的 row 容器配置（`GroupListItem.vue` 渲染的 `Container` 的 config）。
+*
+* `keyProp` 由调用方从 `mForm.keyProp` 取，默认 `__key`。
+*/
+var getGroupListRowConfig = (config, index, keyProp) => {
+	const key = keyProp || "__key";
+	return {
+		type: "row",
+		span: config.span || 24,
+		items: config.items,
+		labelWidth: config.labelWidth,
+		labelPosition: config.labelPosition,
+		[key]: `${config[key]}${String(index)}`
+	};
+};
+/**
+* 列是否会被渲染成一列（`hidden` 列不渲染，`display` 为假的列也不渲染）。
+*
+* `display` 的求值上下文是表格自身的 props，由调用方通过 `evalDisplay` 注入。
+*/
+var isTableColumnRendered = (column, evalDisplay) => column.type !== "hidden" && Boolean(evalDisplay(column.display));
+/**
+* 单元格内 `Container` 实际收到的列配置：按行求值 `itemsFunction`，并去掉已在列层面消费过的 `display`。
+*/
+var makeTableColumnConfig = (column, row) => {
+	const newConfig = cloneDeep(column);
+	if (typeof column.itemsFunction === "function") newConfig.items = column.itemsFunction(row);
+	delete newConfig.display;
+	return newConfig;
+};
+//#endregion
+export { calcLabelWidth, getGroupListRowConfig, isGroupListType, isTableColumnRendered, makeTableColumnConfig, toGroupListConfig, toTableConfig };

package/dist/es/utils/typeMatch.js

@@ -1,29 +1,27 @@
 import { readonly } from "vue";
-import dayjs from "dayjs";
-import { appendValidateSuggestion } from "@tmagic/design";
 import { getValueByKeyPath, toLine } from "@tmagic/utils";
-import customParseFormat from "dayjs/plugin/customParseFormat";
+import dayjs from "dayjs";
+import { appendValidateSuggestion } from "@tmagic/design/headless";
+import customParseFormat from "dayjs/plugin/customParseFormat.js";
 //#region packages/form/src/utils/typeMatch.ts
 dayjs.extend(customParseFormat);
-var typeMatchRuleRegistry = /* @__PURE__ */ new Map();
+var extraTypeMatchRules = /* @__PURE__ */ new Map();
+var builtInTypeMatchRules = /* @__PURE__ */ new Map();
 var isPromise = (value) => typeof value === "object" && value !== null && typeof value.then === "function";
-/** 注册或覆盖某个字段 type 的 typeMatch 校验规则 */
-var registerTypeMatchRule = (type, validator) => {
-	typeMatchRuleRegistry.set(toLine(type), validator);
+/** 注册或覆盖某个字段 type 的 typeMatch 校验规则。`builtIn` 登记不受 `clearTypeMatchRules` / `deleteTypeMatchRule` 影响。 */
+var registerTypeMatchRule = (type, validator, builtIn = false) => {
+	(builtIn ? builtInTypeMatchRules : extraTypeMatchRules).set(toLine(type), validator);
 };
-/** 批量注册 typeMatch 校验规则 */
-var registerTypeMatchRules = (rules) => {
-	Object.entries(rules).forEach(([type, validator]) => {
-		registerTypeMatchRule(type, validator);
-	});
+/** 获取某个字段 type 的 typeMatch 校验规则（业务侧优先于内置） */
+var getTypeMatchRule = (type) => {
+	const key = toLine(type);
+	return extraTypeMatchRules.get(key) ?? builtInTypeMatchRules.get(key);
 };
-/** 获取某个字段 type 的自定义 typeMatch 校验规则 */
-var getTypeMatchRule = (type) => typeMatchRuleRegistry.get(toLine(type));
-/** 删除某个字段 type 的自定义 typeMatch 校验规则 */
-var deleteTypeMatchRule = (type) => typeMatchRuleRegistry.delete(toLine(type));
-/** 清空所有自定义 typeMatch 校验规则 */
+/** 删除业务侧 typeMatch 校验规则（不影响内置） */
+var deleteTypeMatchRule = (type) => extraTypeMatchRules.delete(toLine(type));
+/** 清空业务侧 typeMatch 校验规则（不影响内置） */
 var clearTypeMatchRules = () => {
-	typeMatchRuleRegistry.clear();
+	extraTypeMatchRules.clear();
 };
 /** 本地解析配置函数，避免与 form.ts 循环依赖 */
 var resolveConfig = (mForm, config, props) => {
@@ -487,4 +485,4 @@ var createTypeMatchValidator = (mForm, props, rule) => {
 	};
 };
 //#endregion
-export { MAX_SUGGESTION_OPTIONS, clearTypeMatchRules, createTypeMatchValidator, deleteTypeMatchRule, getTypeMatchRule, optionSuggestion, registerTypeMatchRule, registerTypeMatchRules, stringifyExampleValue, validateTypeMatch };
+export { MAX_SUGGESTION_OPTIONS, clearTypeMatchRules, createTypeMatchValidator, deleteTypeMatchRule, getTypeMatchRule, optionSuggestion, registerTypeMatchRule, stringifyExampleValue, validateTypeMatch };

package/dist/es/utils/validateError.js

@@ -0,0 +1,57 @@
+//#region packages/form/src/utils/validateError.ts
+/**
+* 通过 name 从 config 中查找对应的 text
+*
+* @param name - 字段名，支持点分隔的路径格式，如 'a.b.c'
+* @param config - 表单配置数组
+* @returns 找到的 text 值，如果未找到则返回 undefined
+*/
+var getTextByName = (name, config = []) => {
+	if (!name || !Array.isArray(config)) return void 0;
+	const nameParts = name.split(".");
+	const findInConfig = (configs, parts) => {
+		if (parts.length === 0) return void 0;
+		const [currentPart, ...remainingParts] = parts;
+		for (const item of configs) {
+			if (item.name === currentPart) {
+				if (remainingParts.length === 0) return typeof item.text === "string" ? item.text : void 0;
+				if ("items" in item && Array.isArray(item.items)) {
+					const result = findInConfig(item.items, remainingParts);
+					if (result !== void 0) return result;
+				}
+			}
+			if ("items" in item && Array.isArray(item.items)) {
+				const result = findInConfig(item.items, parts);
+				if (result !== void 0) return result;
+			}
+		}
+	};
+	return findInConfig(config, nameParts);
+};
+/**
+* 将校验返回的 invalidFields 汇总为可读的错误文案（多条以 `<br>` 拼接）。
+*
+* `useFieldTextInError` 为 `true`（默认）时用字段的 text 文案作为错误前缀，找不到则回退为字段 name。
+*
+* 由渲染式校验（Form.vue 的 `submitForm` / `validate`）与无渲染校验（`validateValues`）共用，
+* 保证两条校验链路产出的错误文案格式完全一致。
+*
+* @param invalidFields - async-validator 产出的字段错误表
+* @param [options] - 文案选项
+* @param [options.config] - 用于查找 text 的表单配置
+* @param [options.useFieldTextInError=true] - 错误前缀是否使用字段 text
+* @returns 拼接后的错误文案；无错误时为空串
+*/
+var formatValidateError = (invalidFields, { config = [], useFieldTextInError = true } = {}) => {
+	const error = [];
+	Object.entries(invalidFields).forEach(([prop, validateError]) => {
+		validateError.forEach(({ field, message }) => {
+			const name = field || prop;
+			const text = (useFieldTextInError ? getTextByName(name, config) : void 0) || name;
+			error.push(`${text} -> ${message}`);
+		});
+	});
+	return error.join("<br>");
+};
+//#endregion
+export { formatValidateError, getTextByName };