@zerodep-dev/vue-tsx-pro-ui 0.0.0-stage → 0.1.0

package/dist/form/form-constraints.d.ts

@@ -0,0 +1,38 @@
+/**
+ * 从 zod schema 推出字段约束：必填、长度、数值范围、格式、可选值。useForm 据此告诉 Field 与控件，
+ * 只写一份 schema，标签上的必填标记、输入框的 maxlength、NumberField 的 min / max 就都有了。
+ *
+ * 用 zod 的 toJSONSchema（输入一侧）把 schema 转成 JSON Schema，再按字段路径取约束；JSON Schema 表达不了的部分
+ * （transform、refine、自定义类型）不产生约束，校验照常由 schema 负责。控件上显式写的属性总是优先。
+ *
+ *   const constraints = createConstraints(z.object({ name: z.string().min(1).max(20), age: z.number().int().min(0) }));
+ *   constraints('name')  // { required: true, minLength: 1, maxLength: 20 }
+ *   constraints('age')   // { required: true, min: 0, step: 1 }
+ */
+import { type $ZodType } from 'zod/v4/core';
+/** 一个字段从 schema 推出的约束；推不出的项不出现 */
+export interface FieldConstraints {
+    /** 必填：值不能为空（字符串至少 1 个字、数组至少 1 项、数字等不能缺） */
+    required?: boolean;
+    /** 最少几个字 */
+    minLength?: number;
+    /** 最多几个字 */
+    maxLength?: number;
+    /** 最小值 */
+    min?: number;
+    /** 最大值 */
+    max?: number;
+    /** 步长（倍数约束，整数时为 1） */
+    step?: number;
+    /** 正则（字符串约束，不含首尾的 /） */
+    pattern?: string;
+    /** 格式：email、uri、date 等（JSON Schema 的 format） */
+    format?: string;
+    /** 可选值（枚举） */
+    options?: readonly (string | number)[];
+}
+/**
+ * 按 schema 创建 路径 → 约束 的查询函数；JSON Schema 在第一次查询时才转换，结果按路径缓存。
+ * 没有 schema 时总是返回空约束
+ */
+export declare function createConstraints(schema: $ZodType | undefined): (path: string) => FieldConstraints;

package/dist/form/form-constraints.js

@@ -0,0 +1,131 @@
+import { toJSONSchema } from "zod/v4/core";
+//#region src/form/form-constraints.ts
+/**
+* 从 zod schema 推出字段约束：必填、长度、数值范围、格式、可选值。useForm 据此告诉 Field 与控件，
+* 只写一份 schema，标签上的必填标记、输入框的 maxlength、NumberField 的 min / max 就都有了。
+*
+* 用 zod 的 toJSONSchema（输入一侧）把 schema 转成 JSON Schema，再按字段路径取约束；JSON Schema 表达不了的部分
+* （transform、refine、自定义类型）不产生约束，校验照常由 schema 负责。控件上显式写的属性总是优先。
+*
+*   const constraints = createConstraints(z.object({ name: z.string().min(1).max(20), age: z.number().int().min(0) }));
+*   constraints('name')  // { required: true, minLength: 1, maxLength: 20 }
+*   constraints('age')   // { required: true, min: 0, step: 1 }
+*/
+var NONE = Object.freeze({});
+/** schema → JSON Schema（输入一侧）；表达不了的类型当作 any，循环引用写成 $ref */
+function toJsonSchema(schema) {
+	try {
+		return toJSONSchema(schema, {
+			io: "input",
+			unrepresentable: "any",
+			cycles: "ref"
+		});
+	} catch (error) {
+		console.warn("useForm：无法从 schema 推出字段约束", error);
+		return;
+	}
+}
+/** 解开 $ref（只认本文档的 #/$defs/…）与“允许 null”的 anyOf：返回实际的 schema 与是否允许 null */
+function unwrap(root, node) {
+	let current = node;
+	let nullable = false;
+	for (let depth = 0; current && depth < 10; depth++) {
+		const ref = current.$ref;
+		if (typeof ref === "string" && ref.startsWith("#/$defs/")) {
+			current = root.$defs?.[ref.slice(8)];
+			continue;
+		}
+		if (Array.isArray(current.type) && current.type.includes("null")) {
+			const types = current.type.filter((type) => type !== "null");
+			nullable = true;
+			current = {
+				...current,
+				type: types.length === 1 ? types[0] : types
+			};
+			continue;
+		}
+		const variants = current.anyOf ?? current.oneOf;
+		if (variants) {
+			const rest = variants.filter((variant) => variant.type !== "null");
+			nullable ||= rest.length < variants.length;
+			if (rest.length === 1) {
+				current = rest[0];
+				continue;
+			}
+		}
+		break;
+	}
+	return {
+		node: current,
+		nullable
+	};
+}
+var numberOf = (value) => typeof value === "number" ? value : void 0;
+/** 正则能不能匹配空字符串（如 `^$|^\S+ R\d+$` 是“选填，填了要合格式”）；写错的正则当作不能 */
+function matchesEmpty(pattern) {
+	try {
+		return new RegExp(pattern, "u").test("");
+	} catch {
+		return false;
+	}
+}
+/** 字段自己的 schema → 约束；parentRequires 表示父对象要求这个键存在 */
+function constraintsOf(node, nullable, parentRequires) {
+	const result = {};
+	const type = node.type;
+	if (type === "string") {
+		result.minLength = numberOf(node.minLength);
+		result.maxLength = numberOf(node.maxLength);
+		if (typeof node.pattern === "string") result.pattern = node.pattern;
+		if (typeof node.format === "string") result.format = node.format;
+	}
+	if (type === "number" || type === "integer") {
+		result.min = numberOf(node.minimum);
+		result.max = numberOf(node.maximum);
+		result.step = numberOf(node.multipleOf) ?? (type === "integer" ? 1 : void 0);
+	}
+	if (Array.isArray(node.enum)) result.options = node.enum;
+	const nonEmpty = type === "string" ? (result.minLength ?? 0) > 0 || result.format != null || result.pattern != null && !matchesEmpty(result.pattern) || result.options != null : type === "boolean" ? node.const === true : type === "array" ? (numberOf(node.minItems) ?? 0) > 0 : true;
+	if (parentRequires && !nullable && nonEmpty) result.required = true;
+	for (const key of Object.keys(result)) if (result[key] === void 0) delete result[key];
+	return result;
+}
+/** 按点连接的路径找字段：对象走 properties，数组走 items（下标是数字） */
+function find(root, path) {
+	let { node, nullable } = unwrap(root, root);
+	let required = true;
+	for (const segment of path.split(".")) {
+		if (!node) return NONE;
+		if (node.type === "array") {
+			({node, nullable} = unwrap(root, node.items));
+			required = true;
+			continue;
+		}
+		const properties = node.properties;
+		required = (node.required ?? []).includes(segment);
+		({node, nullable} = unwrap(root, properties?.[segment]));
+	}
+	return node ? constraintsOf(node, nullable, required) : NONE;
+}
+/**
+* 按 schema 创建 路径 → 约束 的查询函数；JSON Schema 在第一次查询时才转换，结果按路径缓存。
+* 没有 schema 时总是返回空约束
+*/
+function createConstraints(schema) {
+	let root = null;
+	const cache = /* @__PURE__ */ new Map();
+	return (path) => {
+		if (root === null) root = schema && toJsonSchema(schema);
+		if (!root) return NONE;
+		let found = cache.get(path);
+		if (!found) {
+			found = find(root, path);
+			cache.set(path, found);
+		}
+		return found;
+	};
+}
+//#endregion
+export { createConstraints };
+
+//# sourceMappingURL=form-constraints.js.map

package/dist/form/form-constraints.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"form-constraints.js","names":[],"sources":["../../src/form/form-constraints.ts"],"sourcesContent":["/**\n * 从 zod schema 推出字段约束：必填、长度、数值范围、格式、可选值。useForm 据此告诉 Field 与控件，\n * 只写一份 schema，标签上的必填标记、输入框的 maxlength、NumberField 的 min / max 就都有了。\n *\n * 用 zod 的 toJSONSchema（输入一侧）把 schema 转成 JSON Schema，再按字段路径取约束；JSON Schema 表达不了的部分\n * （transform、refine、自定义类型）不产生约束，校验照常由 schema 负责。控件上显式写的属性总是优先。\n *\n *   const constraints = createConstraints(z.object({ name: z.string().min(1).max(20), age: z.number().int().min(0) }));\n *   constraints('name')  // { required: true, minLength: 1, maxLength: 20 }\n *   constraints('age')   // { required: true, min: 0, step: 1 }\n */\nimport { toJSONSchema, type $ZodType } from 'zod/v4/core';\n\n/** 一个字段从 schema 推出的约束；推不出的项不出现 */\nexport interface FieldConstraints {\n  /** 必填：值不能为空（字符串至少 1 个字、数组至少 1 项、数字等不能缺） */\n  required?: boolean;\n  /** 最少几个字 */\n  minLength?: number;\n  /** 最多几个字 */\n  maxLength?: number;\n  /** 最小值 */\n  min?: number;\n  /** 最大值 */\n  max?: number;\n  /** 步长（倍数约束，整数时为 1） */\n  step?: number;\n  /** 正则（字符串约束，不含首尾的 /） */\n  pattern?: string;\n  /** 格式：email、uri、date 等（JSON Schema 的 format） */\n  format?: string;\n  /** 可选值（枚举） */\n  options?: readonly (string | number)[];\n}\n\ntype JsonSchema = Record<string, unknown>;\n\nconst NONE: FieldConstraints = Object.freeze({});\n\n/** schema → JSON Schema（输入一侧）；表达不了的类型当作 any，循环引用写成 $ref */\nfunction toJsonSchema(schema: $ZodType): JsonSchema | undefined {\n  try {\n    return toJSONSchema(schema, {\n      io: 'input',\n      unrepresentable: 'any',\n      cycles: 'ref',\n    }) as JsonSchema;\n  } catch (error) {\n    // 理论上不会走到这里（unrepresentable: 'any'）；约束只是辅助，失败时不影响校验\n    console.warn('useForm：无法从 schema 推出字段约束', error);\n    return undefined;\n  }\n}\n\n/** 解开 $ref（只认本文档的 #/$defs/…）与“允许 null”的 anyOf：返回实际的 schema 与是否允许 null */\nfunction unwrap(\n  root: JsonSchema,\n  node: JsonSchema | undefined,\n): { node?: JsonSchema; nullable: boolean } {\n  let current = node;\n  let nullable = false;\n  for (let depth = 0; current && depth < 10; depth++) {\n    const ref = current.$ref;\n    if (typeof ref === 'string' && ref.startsWith('#/$defs/')) {\n      current = (root.$defs as Record<string, JsonSchema> | undefined)?.[ref.slice(8)];\n      continue;\n    }\n    // type: ['string', 'null']（nullable）\n    if (Array.isArray(current.type) && current.type.includes('null')) {\n      const types = current.type.filter((type) => type !== 'null');\n      nullable = true;\n      current = { ...current, type: types.length === 1 ? types[0] : types };\n      continue;\n    }\n    const variants = (current.anyOf ?? current.oneOf) as JsonSchema[] | undefined;\n    if (variants) {\n      const rest = variants.filter((variant) => variant.type !== 'null');\n      nullable ||= rest.length < variants.length;\n      if (rest.length === 1) {\n        current = rest[0];\n        continue;\n      }\n    }\n    break;\n  }\n  return { node: current, nullable };\n}\n\nconst numberOf = (value: unknown) => (typeof value === 'number' ? value : undefined);\n\n/** 正则能不能匹配空字符串（如 `^$|^\\S+ R\\d+$` 是“选填，填了要合格式”）；写错的正则当作不能 */\nfunction matchesEmpty(pattern: string): boolean {\n  try {\n    return new RegExp(pattern, 'u').test('');\n  } catch {\n    return false;\n  }\n}\n\n/** 字段自己的 schema → 约束；parentRequires 表示父对象要求这个键存在 */\nfunction constraintsOf(\n  node: JsonSchema,\n  nullable: boolean,\n  parentRequires: boolean,\n): FieldConstraints {\n  const result: FieldConstraints = {};\n  const type = node.type;\n  if (type === 'string') {\n    result.minLength = numberOf(node.minLength);\n    result.maxLength = numberOf(node.maxLength);\n    if (typeof node.pattern === 'string') result.pattern = node.pattern;\n    if (typeof node.format === 'string') result.format = node.format;\n  }\n  if (type === 'number' || type === 'integer') {\n    result.min = numberOf(node.minimum);\n    result.max = numberOf(node.maximum);\n    result.step = numberOf(node.multipleOf) ?? (type === 'integer' ? 1 : undefined);\n  }\n  if (Array.isArray(node.enum)) result.options = node.enum as (string | number)[];\n  // 键存在不等于“必填”：空字符串、false 通过 z.string()、z.boolean() 的校验，要看值本身能不能为空\n  const nonEmpty =\n    type === 'string'\n      ? (result.minLength ?? 0) > 0 ||\n        result.format != null ||\n        (result.pattern != null && !matchesEmpty(result.pattern)) ||\n        result.options != null\n      : type === 'boolean'\n        ? node.const === true\n        : type === 'array'\n          ? (numberOf(node.minItems) ?? 0) > 0\n          : true;\n  if (parentRequires && !nullable && nonEmpty) result.required = true;\n  for (const key of Object.keys(result) as (keyof FieldConstraints)[]) {\n    if (result[key] === undefined) delete result[key];\n  }\n  return result;\n}\n\n/** 按点连接的路径找字段：对象走 properties，数组走 items（下标是数字） */\nfunction find(root: JsonSchema, path: string): FieldConstraints {\n  let { node, nullable } = unwrap(root, root);\n  let required = true;\n  for (const segment of path.split('.')) {\n    if (!node) return NONE;\n    if (node.type === 'array') {\n      ({ node, nullable } = unwrap(root, node.items as JsonSchema | undefined));\n      required = true;\n      continue;\n    }\n    const properties = node.properties as Record<string, JsonSchema> | undefined;\n    required = ((node.required as string[] | undefined) ?? []).includes(segment);\n    ({ node, nullable } = unwrap(root, properties?.[segment]));\n  }\n  return node ? constraintsOf(node, nullable, required) : NONE;\n}\n\n/**\n * 按 schema 创建 路径 → 约束 的查询函数；JSON Schema 在第一次查询时才转换，结果按路径缓存。\n * 没有 schema 时总是返回空约束\n */\nexport function createConstraints(\n  schema: $ZodType | undefined,\n): (path: string) => FieldConstraints {\n  let root: JsonSchema | undefined | null = null;\n  const cache = new Map<string, FieldConstraints>();\n  return (path) => {\n    if (root === null) root = schema && toJsonSchema(schema);\n    if (!root) return NONE;\n    let found = cache.get(path);\n    if (!found) {\n      found = find(root, path);\n      cache.set(path, found);\n    }\n    return found;\n  };\n}\n"],"mappings":"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"}

package/dist/form/leave-confirmation.d.ts

@@ -0,0 +1,9 @@
+/** useLeaveConfirmation 的选项：站内跳转时确认对话框的文字，默认取语言包 */
+export interface LeaveConfirmationOptions {
+    /** 标题，默认“离开这个页面？” */
+    title?: string;
+    /** 说明，默认“有未保存的修改，离开后会丢失。” */
+    description?: string;
+}
+/** 有未保存的修改时拦住离开（在 setup 里调用，组件卸载时自动解除） */
+export declare function useLeaveConfirmation(read: () => boolean, options?: LeaveConfirmationOptions): void;

package/dist/form/leave-confirmation.js

@@ -0,0 +1,31 @@
+import { useConfig, useLang } from "../config/context.js";
+import { useEventListener } from "../utils/dom/event-listener.js";
+import { useConfirm } from "../overlay/AlertDialog.js";
+import { onScopeDispose } from "vue";
+//#region src/form/leave-confirmation.ts
+/**
+* 未保存离开的提醒：read() 为 true 时——
+*   - 关闭标签页、刷新、跳到别的网站前，浏览器问一下（beforeunload；只显示浏览器自己的固定文案）；
+*   - 站内跳转（路由适配有 beforeLeave 时，如 vueRouterAdapter）先弹确认对话框，选“离开”才走。
+*
+*   useLeaveConfirmation(() => form.dirty && !form.submitting);
+*/
+/** 有未保存的修改时拦住离开（在 setup 里调用，组件卸载时自动解除） */
+function useLeaveConfirmation(read, options = {}) {
+	useEventListener(() => read() ? window : null, "beforeunload", (event) => event.preventDefault());
+	const router = useConfig().router;
+	if (!router?.beforeLeave) return;
+	const lang = useLang();
+	const confirm = useConfirm();
+	const remove = router.beforeLeave(() => !read() || confirm({
+		title: options.title ?? lang.leaveTitle,
+		description: options.description ?? lang.leaveDescription,
+		confirmText: lang.leaveConfirm,
+		tone: "danger"
+	}));
+	onScopeDispose(remove);
+}
+//#endregion
+export { useLeaveConfirmation };
+
+//# sourceMappingURL=leave-confirmation.js.map

package/dist/form/leave-confirmation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"leave-confirmation.js","names":[],"sources":["../../src/form/leave-confirmation.ts"],"sourcesContent":["/**\n * 未保存离开的提醒：read() 为 true 时——\n *   - 关闭标签页、刷新、跳到别的网站前，浏览器问一下（beforeunload；只显示浏览器自己的固定文案）；\n *   - 站内跳转（路由适配有 beforeLeave 时，如 vueRouterAdapter）先弹确认对话框，选“离开”才走。\n *\n *   useLeaveConfirmation(() => form.dirty && !form.submitting);\n */\nimport { onScopeDispose } from 'vue';\nimport { useConfig, useLang } from '../config/context';\nimport { useConfirm } from '../overlay/AlertDialog';\nimport { useEventListener } from '../utils/dom/event-listener';\n\n/** useLeaveConfirmation 的选项：站内跳转时确认对话框的文字，默认取语言包 */\nexport interface LeaveConfirmationOptions {\n  /** 标题，默认“离开这个页面？” */\n  title?: string;\n  /** 说明，默认“有未保存的修改，离开后会丢失。” */\n  description?: string;\n}\n\n/** 有未保存的修改时拦住离开（在 setup 里调用，组件卸载时自动解除） */\nexport function useLeaveConfirmation(\n  read: () => boolean,\n  options: LeaveConfirmationOptions = {},\n): void {\n  // 只在需要时注册：注册了 beforeunload 的页面进不了往返缓存（bfcache）\n  useEventListener(\n    () => (read() ? window : null),\n    'beforeunload',\n    (event) => event.preventDefault(),\n  );\n\n  const router = useConfig().router;\n  if (!router?.beforeLeave) return;\n  const lang = useLang();\n  const confirm = useConfirm();\n  const remove = router.beforeLeave(\n    () =>\n      !read() ||\n      confirm({\n        title: options.title ?? lang.leaveTitle,\n        description: options.description ?? lang.leaveDescription,\n        confirmText: lang.leaveConfirm,\n        tone: 'danger',\n      }),\n  );\n  onScopeDispose(remove);\n}\n"],"mappings":";;;;;;;;;;;;;AAqBA,SAAgB,qBACd,MACA,UAAoC,CAAC,GAC/B;CAEN,uBACS,KAAK,IAAI,SAAS,MACzB,iBACC,UAAU,MAAM,eAAe,CAClC;CAEA,MAAM,SAAS,UAAU,CAAC,CAAC;CAC3B,IAAI,CAAC,QAAQ,aAAa;CAC1B,MAAM,OAAO,QAAQ;CACrB,MAAM,UAAU,WAAW;CAC3B,MAAM,SAAS,OAAO,kBAElB,CAAC,KAAK,KACN,QAAQ;EACN,OAAO,QAAQ,SAAS,KAAK;EAC7B,aAAa,QAAQ,eAAe,KAAK;EACzC,aAAa,KAAK;EAClB,MAAM;CACR,CAAC,CACL;CACA,eAAe,MAAM;AACvB"}

package/dist/form/schemas.d.ts

@@ -0,0 +1,52 @@
+/**
+ * 内置值类型的 zod schema：Decimal（金额、精确小数）与 bigint（超过 2^53 的整数、ID）；
+ * 常见的格式：手机号（phoneSchema）、居民身份证号（idCardSchema，校验出生日期与校验码）。
+ *
+ *   const schema = z.object({
+ *     price: decimalSchema({ min: 0, scale: 2 }),         // Decimal，最小 0，最多两位小数
+ *     stock: bigintSchema({ min: 0n }),
+ *   });
+ *   // useForm 从 schema 推出约束：NumberField 拿到 min 0、step 0.01，不用再写一遍
+ *
+ * zod 自带的 z.bigint()、自定义类型转 JSON Schema 时表达不了，表单推不出字段约束；
+ * 这里用 .meta() 把 minimum、maximum、multipleOf 写进去（form-constraints 读 JSON Schema）。
+ * 校验用 zod 的标准错误码（too_small、too_big、not_multiple_of），提示跟着使用方配置的 zod 语言走。
+ */
+import type Decimal from 'decimal.js';
+import * as z from 'zod';
+import { type NumericValue } from '../utils/data/numeric';
+/** decimalSchema 的选项；边界与步长可以是数字、bigint、Decimal 或十进制文本（'0.01'） */
+export interface DecimalSchemaOptions {
+    /** 最小值（含） */
+    min?: NumericValue | string;
+    /** 最大值（含） */
+    max?: NumericValue | string;
+    /** 步长：值要是 step 的整数倍（从 0 算起） */
+    step?: NumericValue | string;
+    /** 最多几位小数（金额通常是 2） */
+    scale?: number;
+}
+/** Decimal 的 schema：类型、范围、步长与小数位数 */
+export declare function decimalSchema({ min, max, step, scale }?: DecimalSchemaOptions): z.ZodCustom<Decimal, Decimal>;
+/** bigintSchema 的选项 */
+export interface BigIntSchemaOptions {
+    /** 最小值（含） */
+    min?: bigint;
+    /** 最大值（含） */
+    max?: bigint;
+}
+/** bigint 的 schema：范围由 zod 精确校验，约束（转成 number，只给控件用）写进 JSON Schema */
+export declare function bigintSchema({ min, max }?: BigIntSchemaOptions): z.ZodBigInt;
+/** phoneSchema、idCardSchema 的选项 */
+export interface PatternSchemaOptions {
+    /** 不符合时的提示；不写时用 zod 的“格式不对”（跟着语言包） */
+    message?: string;
+}
+/** 中国大陆手机号：1 开头、第二位 3–9、共 11 位数字（配 TextField 的 phoneFormat，值里没有空格） */
+export declare function phoneSchema({ message }?: PatternSchemaOptions): z.ZodString;
+/**
+ * 居民身份证号（GB 11643）是否有效：18 位，出生日期是真实的日期，最后一位校验码对得上（配 idCardFormat）
+ */
+export declare function isValidIdCard(value: string): boolean;
+/** 居民身份证号的 schema：长度、出生日期与校验码（isValidIdCard） */
+export declare function idCardSchema({ message }?: PatternSchemaOptions): z.ZodString;

package/dist/form/schemas.js

@@ -0,0 +1,97 @@
+import { isDecimal, toNumber } from "../utils/data/numeric.js";
+import * as z from "zod";
+//#region src/form/schemas.ts
+/** Decimal 的 schema：类型、范围、步长与小数位数 */
+function decimalSchema({ min, max, step, scale } = {}) {
+	const steps = [step, scale == null ? void 0 : `1e-${scale}`].filter((item) => item != null);
+	return z.custom(isDecimal).check((ctx) => {
+		const value = ctx.value;
+		const Ctor = value.constructor;
+		const of = (bound) => isDecimal(bound) ? bound : new Ctor(String(bound));
+		if (min != null && value.lt(of(min))) ctx.issues.push({
+			code: "too_small",
+			origin: "number",
+			minimum: toNumber(of(min)),
+			inclusive: true,
+			input: value
+		});
+		if (max != null && value.gt(of(max))) ctx.issues.push({
+			code: "too_big",
+			origin: "number",
+			maximum: toNumber(of(max)),
+			inclusive: true,
+			input: value
+		});
+		for (const item of steps) {
+			const divisor = of(item);
+			if (!value.mod(divisor).isZero()) ctx.issues.push({
+				code: "not_multiple_of",
+				origin: "number",
+				divisor: toNumber(divisor),
+				input: toNumber(value)
+			});
+		}
+	}).meta({
+		type: "number",
+		...min != null && { minimum: Number(String(min)) },
+		...max != null && { maximum: Number(String(max)) },
+		...steps.length > 0 && { multipleOf: Math.min(...steps.map((item) => Number(String(item)))) }
+	});
+}
+/** bigint 的 schema：范围由 zod 精确校验，约束（转成 number，只给控件用）写进 JSON Schema */
+function bigintSchema({ min, max } = {}) {
+	let schema = z.bigint();
+	if (min != null) schema = schema.min(min);
+	if (max != null) schema = schema.max(max);
+	return schema.meta({
+		type: "integer",
+		...min != null && { minimum: Number(min) },
+		...max != null && { maximum: Number(max) }
+	});
+}
+/** 中国大陆手机号：1 开头、第二位 3–9、共 11 位数字（配 TextField 的 phoneFormat，值里没有空格） */
+function phoneSchema({ message } = {}) {
+	return z.string().regex(/^1[3-9]\d{9}$/, message === void 0 ? void 0 : { message });
+}
+var ID_WEIGHTS = [
+	7,
+	9,
+	10,
+	5,
+	8,
+	4,
+	2,
+	1,
+	6,
+	3,
+	7,
+	9,
+	10,
+	5,
+	8,
+	4,
+	2
+];
+var ID_CHECK_CODES = "10X98765432";
+/**
+* 居民身份证号（GB 11643）是否有效：18 位，出生日期是真实的日期，最后一位校验码对得上（配 idCardFormat）
+*/
+function isValidIdCard(value) {
+	if (!/^\d{17}[\dX]$/.test(value)) return false;
+	const [year, month, day] = [
+		value.slice(6, 10),
+		value.slice(10, 12),
+		value.slice(12, 14)
+	].map(Number);
+	const birth = new Date(Date.UTC(year, month - 1, day));
+	if (birth.getUTCFullYear() !== year || birth.getUTCMonth() !== month - 1 || birth.getUTCDate() !== day || year < 1900) return false;
+	return ID_CHECK_CODES[ID_WEIGHTS.reduce((total, weight, index) => total + weight * Number(value[index]), 0) % 11] === value[17];
+}
+/** 居民身份证号的 schema：长度、出生日期与校验码（isValidIdCard） */
+function idCardSchema({ message } = {}) {
+	return z.string().refine(isValidIdCard, message === void 0 ? void 0 : { message });
+}
+//#endregion
+export { bigintSchema, decimalSchema, idCardSchema, isValidIdCard, phoneSchema };
+
+//# sourceMappingURL=schemas.js.map

package/dist/form/schemas.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schemas.js","names":[],"sources":["../../src/form/schemas.ts"],"sourcesContent":["/**\n * 内置值类型的 zod schema：Decimal（金额、精确小数）与 bigint（超过 2^53 的整数、ID）；\n * 常见的格式：手机号（phoneSchema）、居民身份证号（idCardSchema，校验出生日期与校验码）。\n *\n *   const schema = z.object({\n *     price: decimalSchema({ min: 0, scale: 2 }),         // Decimal，最小 0，最多两位小数\n *     stock: bigintSchema({ min: 0n }),\n *   });\n *   // useForm 从 schema 推出约束：NumberField 拿到 min 0、step 0.01，不用再写一遍\n *\n * zod 自带的 z.bigint()、自定义类型转 JSON Schema 时表达不了，表单推不出字段约束；\n * 这里用 .meta() 把 minimum、maximum、multipleOf 写进去（form-constraints 读 JSON Schema）。\n * 校验用 zod 的标准错误码（too_small、too_big、not_multiple_of），提示跟着使用方配置的 zod 语言走。\n */\nimport type Decimal from 'decimal.js';\nimport * as z from 'zod';\nimport { isDecimal, toNumber, type NumericValue } from '../utils/data/numeric';\n\n/** decimalSchema 的选项；边界与步长可以是数字、bigint、Decimal 或十进制文本（'0.01'） */\nexport interface DecimalSchemaOptions {\n  /** 最小值（含） */\n  min?: NumericValue | string;\n  /** 最大值（含） */\n  max?: NumericValue | string;\n  /** 步长：值要是 step 的整数倍（从 0 算起） */\n  step?: NumericValue | string;\n  /** 最多几位小数（金额通常是 2） */\n  scale?: number;\n}\n\n/** Decimal 的 schema：类型、范围、步长与小数位数 */\nexport function decimalSchema({ min, max, step, scale }: DecimalSchemaOptions = {}) {\n  // 小数位数等价于步长 10^-scale；两个都给时都要满足\n  const steps = [step, scale == null ? undefined : `1e-${scale}`].filter((item) => item != null);\n  return z\n    .custom<Decimal>(isDecimal)\n    .check((ctx) => {\n      const value = ctx.value;\n      // 边界按值自己的构造函数转成 Decimal：使用方可能用 Decimal.clone 配了精度\n      const Ctor = value.constructor as typeof Decimal;\n      const of = (bound: NumericValue | string) =>\n        isDecimal(bound) ? bound : new Ctor(String(bound));\n      if (min != null && value.lt(of(min))) {\n        ctx.issues.push({\n          code: 'too_small',\n          origin: 'number',\n          minimum: toNumber(of(min)),\n          inclusive: true,\n          input: value,\n        });\n      }\n      if (max != null && value.gt(of(max))) {\n        ctx.issues.push({\n          code: 'too_big',\n          origin: 'number',\n          maximum: toNumber(of(max)),\n          inclusive: true,\n          input: value,\n        });\n      }\n      for (const item of steps) {\n        const divisor = of(item);\n        if (!value.mod(divisor).isZero()) {\n          ctx.issues.push({\n            code: 'not_multiple_of',\n            origin: 'number',\n            divisor: toNumber(divisor),\n            // zod 的类型要求这里是 number（只用来拼提示文字）；判断本身已经按十进制精确做过了\n            input: toNumber(value),\n          });\n        }\n      }\n    })\n    .meta({\n      type: 'number',\n      ...(min != null && { minimum: Number(String(min)) }),\n      ...(max != null && { maximum: Number(String(max)) }),\n      ...(steps.length > 0 && {\n        multipleOf: Math.min(...steps.map((item) => Number(String(item)))),\n      }),\n    });\n}\n\n/** bigintSchema 的选项 */\nexport interface BigIntSchemaOptions {\n  /** 最小值（含） */\n  min?: bigint;\n  /** 最大值（含） */\n  max?: bigint;\n}\n\n/** bigint 的 schema：范围由 zod 精确校验，约束（转成 number，只给控件用）写进 JSON Schema */\nexport function bigintSchema({ min, max }: BigIntSchemaOptions = {}) {\n  let schema = z.bigint();\n  if (min != null) schema = schema.min(min);\n  if (max != null) schema = schema.max(max);\n  return schema.meta({\n    type: 'integer',\n    ...(min != null && { minimum: Number(min) }),\n    ...(max != null && { maximum: Number(max) }),\n  });\n}\n\n/** phoneSchema、idCardSchema 的选项 */\nexport interface PatternSchemaOptions {\n  /** 不符合时的提示；不写时用 zod 的“格式不对”（跟着语言包） */\n  message?: string;\n}\n\n/** 中国大陆手机号：1 开头、第二位 3–9、共 11 位数字（配 TextField 的 phoneFormat，值里没有空格） */\nexport function phoneSchema({ message }: PatternSchemaOptions = {}) {\n  return z.string().regex(/^1[3-9]\\d{9}$/, message === undefined ? undefined : { message });\n}\n\nconst ID_WEIGHTS = [7, 9, 10, 5, 8, 4, 2, 1, 6, 3, 7, 9, 10, 5, 8, 4, 2];\nconst ID_CHECK_CODES = '10X98765432';\n\n/**\n * 居民身份证号（GB 11643）是否有效：18 位，出生日期是真实的日期，最后一位校验码对得上（配 idCardFormat）\n */\nexport function isValidIdCard(value: string): boolean {\n  if (!/^\\d{17}[\\dX]$/.test(value)) return false;\n  const [year, month, day] = [value.slice(6, 10), value.slice(10, 12), value.slice(12, 14)].map(\n    Number,\n  ) as [number, number, number];\n  const birth = new Date(Date.UTC(year, month - 1, day));\n  if (\n    birth.getUTCFullYear() !== year ||\n    birth.getUTCMonth() !== month - 1 ||\n    birth.getUTCDate() !== day ||\n    year < 1900\n  ) {\n    return false;\n  }\n  const sum = ID_WEIGHTS.reduce((total, weight, index) => total + weight * Number(value[index]), 0);\n  return ID_CHECK_CODES[sum % 11] === value[17];\n}\n\n/** 居民身份证号的 schema：长度、出生日期与校验码（isValidIdCard） */\nexport function idCardSchema({ message }: PatternSchemaOptions = {}) {\n  return z.string().refine(isValidIdCard, message === undefined ? undefined : { message });\n}\n"],"mappings":"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"}

package/dist/form/useForm.d.ts

@@ -0,0 +1,192 @@
+/**
+ * 表单控制器：值、校验、错误、提交状态放在一个对象里，交给 <Form controller>（COMPONENTS.md §1 的“命令式能力”）。
+ * 校验用 zod（使用方安装的 peer 依赖，zod 与 zod/mini 都可以），也可以写 validate 函数。
+ * 参考 TanStack Form、React Hook Form 的做法，取其中最常用的部分。
+ *
+ *   const form = useForm({
+ *     schema: z.object({ email: z.email('邮箱格式不对'), age: z.coerce.number().int().min(18, '未满 18 岁') }),
+ *     initial: { email: '', age: '' },          // 类型是 schema 的输入（z.input）
+ *     onSubmit: (values) => api.signup(values), // 拿到解析后的输出（z.output）：age 已是数字
+ *   });
+ *   <Form controller={form}>
+ *     <FormErrorSummary />                        // 提交没通过时在顶上列出各项错误，点了跳到字段
+ *     <form.Field name="email" label="邮箱"><TextField /></form.Field>   // 只有一个控件时自动绑定值
+ *     <Button type="submit" loading={form.submitting}>登录</Button>
+ *   </Form>
+ *
+ * form.Field 里只有一个控件、控件上没写值时，自动绑定 form.values 的这个字段（同 Ant Design Form.Item 的 name）：
+ * 写回的是 _value；声明了 _checked 而没有 _value 的控件（Switch、单个 Checkbox）写回 _checked，也可以用 Field 的 valueProp 指定。
+ * 自己写了 _value={form.values.email} 时照旧。
+ *
+ * 何时显示错误（“迟一点批评、早一点肯定”）：字段失焦后才显示它的错误，之后它随输入实时更新；提交过一次之后，所有字段随输入实时更新。
+ * 不属于哪个字段的错误（对象级 refine 没写 path、validate 返回的 '' 键、setError('', …)）是整份表单的错误，见 formError。
+ * 字段的值经 v-model 写回，中文输入法组合输入期间不写回，所以组合中途不会触发校验。
+ *
+ * schema 还决定字段的约束（form-constraints.ts）：标签的必填标记、输入框的 maxlength、NumberField 的 min / max
+ * 都从 schema 来，不用在控件上再写一遍。
+ *
+ * - 数组字段：`form.array('items')` 增删、插入、移动，给每项一个稳定的 key；错误与失焦记录跟着下标移动。
+ * - 单字段异步校验：`fields: { username: { validate: (name, values, signal) => api.taken(name, { signal }) } }`，
+ *   这个字段变化时防抖运行、只采用最后一次的结果，提交时等它完成；`form.validating('username')` 显示校验中。
+ * - 改动：`form.dirty` 是值与初始值（或上次 reset 的值）不同；未保存离开的提醒用 useLeaveConfirmation(() => form.dirty)。
+ * - 局部校验：`form.validate(['name', 'address'])` 只校验这些字段（含子路径）并显示它们的错误，分步表单进下一步前用。
+ * - 字段联动：`dependencies: { confirm: ['password'] }`，password 改了重新校验 confirm（confirm 填过或失焦过时显示它的错误），
+ *   confirm 的单字段校验也跟着重跑。
+ */
+import type { TsxComponent } from '@zerodep-dev/vue-tsx-pro-tsx';
+import { type $ZodType } from 'zod/v4/core';
+import { type FieldProps } from './Field';
+import { type FieldConstraints } from './form-constraints';
+/** 字段路径 → 错误信息；路径用点连接（`address.city`、`items.0.name`） */
+export type FormErrors = Partial<Record<string, string>>;
+/** 当作一个整体的值：不再往里展开路径 */
+type FieldLeaf = string | number | boolean | bigint | symbol | null | undefined | Date | Blob;
+/**
+ * 值里的字段路径：点连接，数组下标是数字（`email`、`address.city`、`items.0.name`）。
+ * 最多展开 6 层，再深的结构写成 string 也照样能用（Field 的 name、setError 都接受）
+ */
+export type FieldPath<Values, Depth extends unknown[] = []> = Depth['length'] extends 6 ? never : Values extends readonly (infer Item)[] ? `${number}` | `${number}.${FieldPath<Item, [...Depth, unknown]>}` : Values extends object ? {
+    [K in keyof Values & string]: K | (NonNullable<Values[K]> extends FieldLeaf ? never : `${K}.${FieldPath<NonNullable<Values[K]>, [...Depth, unknown]>}`);
+}[keyof Values & string] : never;
+/** 字段路径 P 处的值的类型（`PathValue<Values, 'items.0.name'>` → string） */
+export type PathValue<Values, P extends string> = P extends `${infer Key}.${infer Rest}` ? Values extends readonly (infer Item)[] ? PathValue<NonNullable<Item>, Rest> : Key extends keyof Values ? PathValue<NonNullable<Values[Key]>, Rest> : never : Values extends readonly (infer Item)[] ? Item : P extends keyof Values ? Values[P] : never;
+/** 值是数组的字段路径：form.array 只接受这些 */
+export type ArrayPath<Values> = {
+    [P in FieldPath<Values>]: NonNullable<PathValue<Values, P>> extends readonly unknown[] ? P : never;
+}[FieldPath<Values>];
+/** 单个字段的校验：只在这个字段变化时运行（防抖），适合要请求接口的“用户名已占用” */
+export interface FieldValidator<Value, Values> {
+    /** 返回错误信息，通过时返回 undefined；signal 在值又变了、表单重置时中止 */
+    validate: (value: Value, values: Values, signal: AbortSignal) => string | undefined | Promise<string | undefined>;
+    /** 值停止变化多久（毫秒）后运行，默认 300 */
+    debounce?: number;
+}
+/** 数组字段的操作：form.array(path) 的返回值 */
+export interface FieldArray<Item> {
+    /** 当前的各项（就是 values 里的数组） */
+    readonly items: readonly Item[];
+    /** 每项一个稳定的 key：渲染列表时用，增删、移动后不变 */
+    readonly keys: readonly string[];
+    /** 加到末尾 */
+    append(item: Item): void;
+    /** 插到 index 处 */
+    insert(index: number, item: Item): void;
+    /** 删掉 index 处的一项 */
+    remove(index: number): void;
+    /** 把 from 处的一项移到 to 处 */
+    move(from: number, to: number): void;
+}
+/** 什么时候开始校验；提交过一次之后总是随输入更新 */
+export interface FormValidateTimings {
+    /** 失焦后（默认） */
+    blur: unknown;
+    /** 输入时 */
+    change: unknown;
+    /** 只在提交时 */
+    submit: unknown;
+}
+/** useForm 的选项；Values 是表单里的值（有 schema 时是它的输入类型），Output 是校验通过后交给 onSubmit 的值 */
+export interface FormOptions<Values extends object, Output = Values> {
+    /** 初始值；reset() 回到它 */
+    initial: Values;
+    /** zod schema：整份值一起校验，issue 的 path 决定错误挂在哪个字段上；字段约束也从它推出 */
+    schema?: $ZodType<Output, Values>;
+    /** 自定义校验：返回各字段的错误（可以是 Promise），与 schema 的结果合并 */
+    validate?: (values: Values) => FormErrors | Promise<FormErrors>;
+    /**
+     * 单字段异步校验：按字段路径给出，这个字段变化时防抖运行，结果与 schema 的合并（schema 的错误优先）。
+     * NoInfer：Values 只从 initial 与 schema 推出，validate 的参数类型才能跟着推出来
+     */
+    fields?: NoInfer<{
+        [P in FieldPath<Values>]?: FieldValidator<PathValue<Values, P>, Values>;
+    }>;
+    /** 什么时候开始校验，默认 blur；提交过一次之后总是随输入更新 */
+    validateOn?: keyof FormValidateTimings;
+    /**
+     * 字段联动：字段 → 它依赖的字段。依赖的值改了就重新校验它（它填过或失焦过时显示错误），它的单字段校验也重跑。
+     * 如 `{ confirm: ['password'], endDate: ['startDate'] }`
+     */
+    dependencies?: NoInfer<{
+        [P in FieldPath<Values>]?: readonly FieldPath<Values>[];
+    }>;
+    /** 校验通过后调用，拿到 schema 解析后的值（转换、默认值、coerce 都已生效）；返回 Promise 时 submitting 一直为 true 直到完成 */
+    onSubmit?: (values: Output) => unknown;
+}
+/** 控制器里与值的类型无关的部分：Form、Field 只用到它，任何 FormController 都能交给 <Form controller> */
+export interface FormControllerBase {
+    /** 所有字段当前的校验错误（含还没显示的）；整份表单的错误在 '' 键上 */
+    readonly errors: Readonly<FormErrors>;
+    /** 整份表单的错误（不属于哪个字段），提交过之后才有；放在提交按钮旁或表单顶上 */
+    readonly formError: string | undefined;
+    /** 正在执行 onSubmit */
+    readonly submitting: boolean;
+    /** 提交过几次（不论成功与否） */
+    readonly submitCount: number;
+    /** 重置过几次：控件据此丢掉自己还没写回的输入（useFormReset） */
+    readonly resetCount: number;
+    /** 值与初始值（或上次 reset 的值）不同 */
+    readonly dirty: boolean;
+    /** 字段（不写时为任一字段）的单字段校验正在进行 */
+    validating(path?: string): boolean;
+    /** 字段的错误是否该显示：失焦过、或提交过之后才显示；Field 用它 */
+    visibleError(path: string): string | undefined;
+    /** 字段失焦：Field 在焦点离开字段时调用 */
+    blur(path: string): void;
+    /**
+     * 校验整份表单，返回是否通过。给了 paths 时只看这些字段（含子路径）：它们的错误立即显示，
+     * 返回它们是否都通过（分步表单进下一步前用）
+     */
+    validate(paths?: readonly string[]): Promise<boolean>;
+    /** 提交：先校验，通过后调用 onSubmit；返回是否通过校验 */
+    submit(): Promise<boolean>;
+    /** 回到初始值，清空错误与失焦记录 */
+    reset(): void;
+    /** 字段从 schema 推出的约束（必填、长度、范围…）；Field 交给控件，控件上显式写的优先 */
+    constraints(path: string): FieldConstraints;
+    /** 字段的当前值（按点连接的路径）：Field 自动绑定值时用 */
+    getValue(path: string): unknown;
+    /** 写字段的值：中途是 null / undefined 时什么也不做 */
+    setValue(path: string, value: unknown): void;
+    /** 写了 name 的 Field 登记标签与控件的 id：错误汇总据此显示字段名、跳到控件。返回注销函数 */
+    register(path: string, field: FormFieldInfo): () => void;
+    /** 登记过的字段，按登记（渲染）的顺序 */
+    readonly fields: ReadonlyMap<string, FormFieldInfo>;
+}
+/** Field 登记的字段信息 */
+export interface FormFieldInfo {
+    /** 标签的文字 */
+    label: string;
+    /** 控件的 id：错误汇总的链接指向它 */
+    controlId: string;
+}
+/** 表单控制器：useForm 的返回值 */
+export interface FormController<Values extends object> extends FormControllerBase {
+    /** 当前值（响应式）：控件写 _value={form.values.email} */
+    readonly values: Values;
+    /** 回到初始值（或给定的值，之后 dirty 以它为准），清空错误与失焦记录；保存成功后写 reset(form.values) */
+    reset(values?: Values): void;
+    /** 字段与初始值不同 */
+    isDirty(path: FieldPath<Values>): boolean;
+    /** 校验整份表单，或只校验 paths 里的字段（含子路径）并显示它们的错误；返回是否通过 */
+    validate(paths?: readonly FieldPath<Values>[]): Promise<boolean>;
+    /** 数组字段的增删、插入、移动 */
+    array<P extends ArrayPath<Values>>(path: P): FieldArray<NonNullable<PathValue<Values, P>> extends readonly (infer Item)[] ? Item : never>;
+    /**
+     * 设置某个字段的错误（如服务端返回的“邮箱已注册”），undefined 清除；'' 是整份表单的错误。
+     * 校验不会冲掉它，这个字段（整份表单的错误是任一字段）的值改了之后自动消失
+     */
+    setError(path: FieldPath<Values> | '', message: string | undefined): void;
+    /**
+     * 就是 Field 组件，只是 name 的类型收窄为这份值的字段路径，写错字段名时类型检查报错：
+     * `<form.Field name="email" label="邮箱">…</form.Field>`（参考 TanStack Form 的 form.Field）
+     */
+    readonly Field: TsxComponent<Omit<FieldProps, 'name'> & {
+        name?: FieldPath<Values>;
+    }>;
+}
+/**
+ * 创建表单控制器（组件 setup 里或模块顶层都可以）。
+ * 有 schema 时值的类型取自 schema（initial 要符合它的输入类型），onSubmit 拿到解析后的输出
+ */
+export declare function useForm<Values extends object, Output = Values>(options: FormOptions<Values, Output>): FormController<Values>;
+export {};