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

package/dist/utils/data/history.js

@@ -0,0 +1,132 @@
+import { sameValue } from "./equality.js";
+import { shallowRef } from "vue";
+import { snapshot } from "@zerodep-dev/vue-tsx-pro-tsx";
+//#region src/utils/data/history.ts
+/**
+* 撤销重做：记下一份状态的各个版本，撤销、重做时把记下的版本写回去。设计器、画布、富编辑器这类“改了还能退回去”的地方用它。
+* 参考 VueUse 的 useManualRefHistory（手动提交、限制步数）与 ProseMirror 的 history（连续输入在一段时间内合成一步）。
+*
+*   const doc = _state({ … });
+*   const history = createHistory({ read: () => doc, write: (value) => Object.assign(doc, value) });
+*   rename(node, name);  history.commit('改名称', { merge: `name:${node.id}` });   // 逐字输入合成一步
+*   const drag = history.begin('移动节点');  …拖动中随便改…  drag.end();          // 松开时记一步，Esc 时 drag.cancel()
+*   <IconButton disabled={!history.canUndo} onClick={history.undo} label={`撤销 ${history.undoLabel ?? ''}`} />
+*
+* 记的是快照：每一步一份深拷贝（默认 snapshot，去掉响应式代理）。几十 KB 的定义记 100 步也只有几 MB，
+* 不做补丁：补丁要么要求状态按不可变方式更新，要么每次都要深比较，换来的内存不值这份复杂度。
+* 状态本来就按不可变方式更新时，clone 写成 (value) => value，每一步只存一个引用。
+* 保存点：markSaved() 记下当前这一步，dirty 表示现在与保存时不同（撤销回保存点时又变回 false）。
+* 不在 setup 里也能用（只用 Vue 的 shallowRef），快捷键（Mod+Z、Mod+Shift+Z）由使用方接上 useHotkeys。
+*/
+/** 撤销重做的历史（在哪里都能调用：不用生命周期与注入） */
+function createHistory(options) {
+	const limit = Math.max(1, options.limit ?? 100);
+	const mergeWindow = options.mergeWindow ?? 500;
+	const clone = options.clone ?? snapshot;
+	const equals = options.equals ?? sameValue;
+	const entry = (label, merge) => ({
+		value: clone(options.read()),
+		label,
+		merge,
+		at: Date.now()
+	});
+	let entries = [entry()];
+	let current = 0;
+	let saved = 0;
+	let gesture;
+	const revision = shallowRef(0);
+	const touch = () => revision.value++;
+	const track = () => revision.value;
+	function record(label, merge) {
+		const next = entry(label, merge);
+		const last = entries[current];
+		if (equals(next.value, last.value)) return;
+		entries.length = current + 1;
+		if (merge !== void 0 && last.merge === merge && next.at - last.at <= mergeWindow && current > 0 && current !== saved) entries[current] = {
+			...next,
+			label: last.label ?? label
+		};
+		else {
+			entries.push(next);
+			current++;
+			if (entries.length > limit + 1) {
+				const dropped = entries.length - (limit + 1);
+				entries = entries.slice(dropped);
+				current -= dropped;
+				saved = saved - dropped < 0 ? -1 : saved - dropped;
+			}
+		}
+		touch();
+	}
+	function go(index) {
+		if (index < 0 || index >= entries.length || index === current) return;
+		gesture = void 0;
+		current = index;
+		options.write(clone(entries[current].value));
+		touch();
+	}
+	return {
+		get canUndo() {
+			track();
+			return current > 0;
+		},
+		get canRedo() {
+			track();
+			return current < entries.length - 1;
+		},
+		get undoLabel() {
+			track();
+			return current > 0 ? entries[current].label : void 0;
+		},
+		get redoLabel() {
+			track();
+			return entries[current + 1]?.label;
+		},
+		get dirty() {
+			track();
+			return current !== saved;
+		},
+		get busy() {
+			track();
+			return gesture !== void 0;
+		},
+		commit(label, commitOptions) {
+			if (gesture) return;
+			record(label, commitOptions?.merge);
+		},
+		begin(label) {
+			if (gesture) record(gesture.label);
+			const own = { label };
+			gesture = own;
+			touch();
+			const finish = (keep) => {
+				if (gesture !== own) return;
+				gesture = void 0;
+				if (keep) record(label);
+				else options.write(clone(entries[current].value));
+				touch();
+			};
+			return {
+				end: () => finish(true),
+				cancel: () => finish(false)
+			};
+		},
+		undo: () => go(current - 1),
+		redo: () => go(current + 1),
+		markSaved() {
+			saved = current;
+			touch();
+		},
+		reset() {
+			gesture = void 0;
+			entries = [entry()];
+			current = 0;
+			saved = 0;
+			touch();
+		}
+	};
+}
+//#endregion
+export { createHistory };
+
+//# sourceMappingURL=history.js.map

package/dist/utils/data/history.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"history.js","names":[],"sources":["../../../src/utils/data/history.ts"],"sourcesContent":["/**\n * 撤销重做：记下一份状态的各个版本，撤销、重做时把记下的版本写回去。设计器、画布、富编辑器这类“改了还能退回去”的地方用它。\n * 参考 VueUse 的 useManualRefHistory（手动提交、限制步数）与 ProseMirror 的 history（连续输入在一段时间内合成一步）。\n *\n *   const doc = _state({ … });\n *   const history = createHistory({ read: () => doc, write: (value) => Object.assign(doc, value) });\n *   rename(node, name);  history.commit('改名称', { merge: `name:${node.id}` });   // 逐字输入合成一步\n *   const drag = history.begin('移动节点');  …拖动中随便改…  drag.end();          // 松开时记一步，Esc 时 drag.cancel()\n *   <IconButton disabled={!history.canUndo} onClick={history.undo} label={`撤销 ${history.undoLabel ?? ''}`} />\n *\n * 记的是快照：每一步一份深拷贝（默认 snapshot，去掉响应式代理）。几十 KB 的定义记 100 步也只有几 MB，\n * 不做补丁：补丁要么要求状态按不可变方式更新，要么每次都要深比较，换来的内存不值这份复杂度。\n * 状态本来就按不可变方式更新时，clone 写成 (value) => value，每一步只存一个引用。\n * 保存点：markSaved() 记下当前这一步，dirty 表示现在与保存时不同（撤销回保存点时又变回 false）。\n * 不在 setup 里也能用（只用 Vue 的 shallowRef），快捷键（Mod+Z、Mod+Shift+Z）由使用方接上 useHotkeys。\n */\nimport { snapshot } from '@zerodep-dev/vue-tsx-pro-tsx';\nimport { shallowRef } from 'vue';\nimport { sameValue } from './equality';\n\n/** createHistory 的选项 */\nexport interface HistoryOptions<T> {\n  /** 读当前的状态 */\n  read: () => T;\n  /** 撤销、重做时把记下的版本写回状态（拿到的是一份拷贝，可以直接放进状态里） */\n  write: (value: T) => void;\n  /** 最多记多少步（不算起点），默认 100；超出时丢掉最早的 */\n  limit?: number;\n  /** 同一个 merge 键的连续提交，间隔不超过多少毫秒就合成一步，默认 500 */\n  mergeWindow?: number;\n  /** 记下一个版本时怎样复制，默认 snapshot（深拷贝、去掉代理）；状态按不可变方式更新时写 (value) => value */\n  clone?: (value: T) => T;\n  /** 与上一步是否相同（相同就不记），默认结构相等（sameValue） */\n  equals?: (a: T, b: T) => boolean;\n}\n\n/** commit 的选项 */\nexport interface HistoryCommitOptions {\n  /**\n   * 合并的键：与上一步的键相同、间隔在 mergeWindow 以内时并进上一步（逐字输入、连续微调）。\n   * 键里带上对象，例如 `name:${node.id}`，改另一个对象的同一个字段时另起一步\n   */\n  merge?: string;\n}\n\n/** 一次连续的操作（拖动、调整大小）：期间的改动不记，结束时合成一步 */\nexport interface HistoryGesture {\n  /** 结束：有改动就记成一步 */\n  end(): void;\n  /** 取消：状态回到开始前（Esc 取消拖动） */\n  cancel(): void;\n}\n\n/** createHistory 的返回值：状态加方法，交给工具栏、快捷键 */\nexport interface History {\n  /** 有可以撤销的步骤 */\n  readonly canUndo: boolean;\n  /** 有可以重做的步骤 */\n  readonly canRedo: boolean;\n  /** 下一次撤销会撤掉的那一步的说明（commit 时写的 label），按钮的提示里用；没有时 undefined */\n  readonly undoLabel: string | undefined;\n  /** 下一次重做会重做的那一步的说明 */\n  readonly redoLabel: string | undefined;\n  /** 现在与保存点（markSaved）不同；还没保存过时与起点比 */\n  readonly dirty: boolean;\n  /** 正在进行一次连续的操作（begin 之后、end 或 cancel 之前） */\n  readonly busy: boolean;\n  /** 把当前状态记成新的一步；与上一步相同时不记。撤销过再提交会丢掉可以重做的步骤 */\n  commit(label?: string, options?: HistoryCommitOptions): void;\n  /** 开始一次连续的操作：期间的 commit 不起作用，end 时记一步、cancel 时回到开始前。已有进行中的操作时先结束它 */\n  begin(label?: string): HistoryGesture;\n  /** 撤销一步 */\n  undo(): void;\n  /** 重做一步 */\n  redo(): void;\n  /** 把当前这一步记为已保存：dirty 变回 false */\n  markSaved(): void;\n  /** 清空历史，以当前状态为新的起点并记为已保存（载入另一份文档、发布之后） */\n  reset(): void;\n}\n\ninterface Entry<T> {\n  value: T;\n  label: string | undefined;\n  merge: string | undefined;\n  at: number;\n}\n\n/** 撤销重做的历史（在哪里都能调用：不用生命周期与注入） */\nexport function createHistory<T>(options: HistoryOptions<T>): History {\n  const limit = Math.max(1, options.limit ?? 100);\n  const mergeWindow = options.mergeWindow ?? 500;\n  const clone = options.clone ?? snapshot;\n  const equals = options.equals ?? sameValue;\n\n  const entry = (label?: string, merge?: string): Entry<T> => ({\n    value: clone(options.read()),\n    label,\n    merge,\n    at: Date.now(),\n  });\n  // 历史不是响应式数据（快照可能很大）；current、saved 的变化经 revision 通知读取方\n  let entries: Entry<T>[] = [entry()];\n  let current = 0;\n  // 保存点在 entries 里的位置；被 limit 挤掉后是 -1，之后一直算有改动\n  let saved = 0;\n  let gesture: { label: string | undefined } | undefined;\n  const revision = shallowRef(0);\n  const touch = () => revision.value++;\n  const track = () => revision.value;\n\n  function record(label?: string, merge?: string) {\n    const next = entry(label, merge);\n    const last = entries[current]!;\n    if (equals(next.value, last.value)) return;\n    entries.length = current + 1;\n    // 合并进上一步：同一个键、间隔不长，且上一步不是起点或保存点（否则撤销会越过它们）\n    const merges =\n      merge !== undefined &&\n      last.merge === merge &&\n      next.at - last.at <= mergeWindow &&\n      current > 0 &&\n      current !== saved;\n    if (merges) {\n      entries[current] = { ...next, label: last.label ?? label };\n    } else {\n      entries.push(next);\n      current++;\n      if (entries.length > limit + 1) {\n        const dropped = entries.length - (limit + 1);\n        entries = entries.slice(dropped);\n        current -= dropped;\n        saved = saved - dropped < 0 ? -1 : saved - dropped;\n      }\n    }\n    touch();\n  }\n\n  function go(index: number) {\n    if (index < 0 || index >= entries.length || index === current) return;\n    gesture = undefined;\n    current = index;\n    options.write(clone(entries[current]!.value));\n    touch();\n  }\n\n  return {\n    get canUndo() {\n      track();\n      return current > 0;\n    },\n    get canRedo() {\n      track();\n      return current < entries.length - 1;\n    },\n    get undoLabel() {\n      track();\n      return current > 0 ? entries[current]!.label : undefined;\n    },\n    get redoLabel() {\n      track();\n      return entries[current + 1]?.label;\n    },\n    get dirty() {\n      track();\n      return current !== saved;\n    },\n    get busy() {\n      track();\n      return gesture !== undefined;\n    },\n    commit(label, commitOptions) {\n      if (gesture) return;\n      record(label, commitOptions?.merge);\n    },\n    begin(label) {\n      if (gesture) record(gesture.label);\n      const own = { label };\n      gesture = own;\n      touch();\n      // 只结束自己：被新的 begin、undo 顶掉之后再调用不起作用\n      const finish = (keep: boolean) => {\n        if (gesture !== own) return;\n        gesture = undefined;\n        if (keep) record(label);\n        else options.write(clone(entries[current]!.value));\n        touch();\n      };\n      return { end: () => finish(true), cancel: () => finish(false) };\n    },\n    undo: () => go(current - 1),\n    redo: () => go(current + 1),\n    markSaved() {\n      saved = current;\n      touch();\n    },\n    reset() {\n      gesture = undefined;\n      entries = [entry()];\n      current = 0;\n      saved = 0;\n      touch();\n    },\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;AAyFA,SAAgB,cAAiB,SAAqC;CACpE,MAAM,QAAQ,KAAK,IAAI,GAAG,QAAQ,SAAS,GAAG;CAC9C,MAAM,cAAc,QAAQ,eAAe;CAC3C,MAAM,QAAQ,QAAQ,SAAS;CAC/B,MAAM,SAAS,QAAQ,UAAU;CAEjC,MAAM,SAAS,OAAgB,WAA8B;EAC3D,OAAO,MAAM,QAAQ,KAAK,CAAC;EAC3B;EACA;EACA,IAAI,KAAK,IAAI;CACf;CAEA,IAAI,UAAsB,CAAC,MAAM,CAAC;CAClC,IAAI,UAAU;CAEd,IAAI,QAAQ;CACZ,IAAI;CACJ,MAAM,WAAW,WAAW,CAAC;CAC7B,MAAM,cAAc,SAAS;CAC7B,MAAM,cAAc,SAAS;CAE7B,SAAS,OAAO,OAAgB,OAAgB;EAC9C,MAAM,OAAO,MAAM,OAAO,KAAK;EAC/B,MAAM,OAAO,QAAQ;EACrB,IAAI,OAAO,KAAK,OAAO,KAAK,KAAK,GAAG;EACpC,QAAQ,SAAS,UAAU;EAQ3B,IALE,UAAU,KAAA,KACV,KAAK,UAAU,SACf,KAAK,KAAK,KAAK,MAAM,eACrB,UAAU,KACV,YAAY,OAEZ,QAAQ,WAAW;GAAE,GAAG;GAAM,OAAO,KAAK,SAAS;EAAM;OACpD;GACL,QAAQ,KAAK,IAAI;GACjB;GACA,IAAI,QAAQ,SAAS,QAAQ,GAAG;IAC9B,MAAM,UAAU,QAAQ,UAAU,QAAQ;IAC1C,UAAU,QAAQ,MAAM,OAAO;IAC/B,WAAW;IACX,QAAQ,QAAQ,UAAU,IAAI,KAAK,QAAQ;GAC7C;EACF;EACA,MAAM;CACR;CAEA,SAAS,GAAG,OAAe;EACzB,IAAI,QAAQ,KAAK,SAAS,QAAQ,UAAU,UAAU,SAAS;EAC/D,UAAU,KAAA;EACV,UAAU;EACV,QAAQ,MAAM,MAAM,QAAQ,QAAQ,CAAE,KAAK,CAAC;EAC5C,MAAM;CACR;CAEA,OAAO;EACL,IAAI,UAAU;GACZ,MAAM;GACN,OAAO,UAAU;EACnB;EACA,IAAI,UAAU;GACZ,MAAM;GACN,OAAO,UAAU,QAAQ,SAAS;EACpC;EACA,IAAI,YAAY;GACd,MAAM;GACN,OAAO,UAAU,IAAI,QAAQ,QAAQ,CAAE,QAAQ,KAAA;EACjD;EACA,IAAI,YAAY;GACd,MAAM;GACN,OAAO,QAAQ,UAAU,EAAE,EAAE;EAC/B;EACA,IAAI,QAAQ;GACV,MAAM;GACN,OAAO,YAAY;EACrB;EACA,IAAI,OAAO;GACT,MAAM;GACN,OAAO,YAAY,KAAA;EACrB;EACA,OAAO,OAAO,eAAe;GAC3B,IAAI,SAAS;GACb,OAAO,OAAO,eAAe,KAAK;EACpC;EACA,MAAM,OAAO;GACX,IAAI,SAAS,OAAO,QAAQ,KAAK;GACjC,MAAM,MAAM,EAAE,MAAM;GACpB,UAAU;GACV,MAAM;GAEN,MAAM,UAAU,SAAkB;IAChC,IAAI,YAAY,KAAK;IACrB,UAAU,KAAA;IACV,IAAI,MAAM,OAAO,KAAK;SACjB,QAAQ,MAAM,MAAM,QAAQ,QAAQ,CAAE,KAAK,CAAC;IACjD,MAAM;GACR;GACA,OAAO;IAAE,WAAW,OAAO,IAAI;IAAG,cAAc,OAAO,KAAK;GAAE;EAChE;EACA,YAAY,GAAG,UAAU,CAAC;EAC1B,YAAY,GAAG,UAAU,CAAC;EAC1B,YAAY;GACV,QAAQ;GACR,MAAM;EACR;EACA,QAAQ;GACN,UAAU,KAAA;GACV,UAAU,CAAC,MAAM,CAAC;GAClB,UAAU;GACV,QAAQ;GACR,MAAM;EACR;CACF;AACF"}

package/dist/utils/data/intl-cache.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Intl 对象（NumberFormat、DateTimeFormat、Collator……）的共用缓存：新建一个要解析语言与选项，比调用它慢得多，
+ * 格式化、比较、解析又在渲染与输入里频繁发生。键写成“种类|语言|选项”，同样的配置只建一次。
+ *
+ *   const formatter = cachedIntl(`number|${locale}|${JSON.stringify(options)}`, () => new Intl.NumberFormat(locale, options));
+ */
+/** 取 key 对应的缓存，没有时用 create 新建并记下 */
+export declare function cachedIntl<T>(key: string, create: () => T): T;

package/dist/utils/data/intl-cache.js

@@ -0,0 +1,19 @@
+//#region src/utils/data/intl-cache.ts
+/**
+* Intl 对象（NumberFormat、DateTimeFormat、Collator……）的共用缓存：新建一个要解析语言与选项，比调用它慢得多，
+* 格式化、比较、解析又在渲染与输入里频繁发生。键写成“种类|语言|选项”，同样的配置只建一次。
+*
+*   const formatter = cachedIntl(`number|${locale}|${JSON.stringify(options)}`, () => new Intl.NumberFormat(locale, options));
+*/
+var cache = /* @__PURE__ */ new Map();
+/** 取 key 对应的缓存，没有时用 create 新建并记下 */
+function cachedIntl(key, create) {
+	if (cache.has(key)) return cache.get(key);
+	const created = create();
+	cache.set(key, created);
+	return created;
+}
+//#endregion
+export { cachedIntl };
+
+//# sourceMappingURL=intl-cache.js.map

package/dist/utils/data/intl-cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"intl-cache.js","names":[],"sources":["../../../src/utils/data/intl-cache.ts"],"sourcesContent":["/**\n * Intl 对象（NumberFormat、DateTimeFormat、Collator……）的共用缓存：新建一个要解析语言与选项，比调用它慢得多，\n * 格式化、比较、解析又在渲染与输入里频繁发生。键写成“种类|语言|选项”，同样的配置只建一次。\n *\n *   const formatter = cachedIntl(`number|${locale}|${JSON.stringify(options)}`, () => new Intl.NumberFormat(locale, options));\n */\n\nconst cache = new Map<string, unknown>();\n\n/** 取 key 对应的缓存，没有时用 create 新建并记下 */\nexport function cachedIntl<T>(key: string, create: () => T): T {\n  if (cache.has(key)) return cache.get(key) as T;\n  const created = create();\n  cache.set(key, created);\n  return created;\n}\n"],"mappings":";;;;;;;AAOA,IAAM,wBAAQ,IAAI,IAAqB;;AAGvC,SAAgB,WAAc,KAAa,QAAoB;CAC7D,IAAI,MAAM,IAAI,GAAG,GAAG,OAAO,MAAM,IAAI,GAAG;CACxC,MAAM,UAAU,OAAO;CACvB,MAAM,IAAI,KAAK,OAAO;CACtB,OAAO;AACT"}

package/dist/utils/data/number-parse.d.ts

@@ -0,0 +1,7 @@
+/**
+ * 按语言把用户输入规范成十进制文本（'-1234.5'）：去掉千分位与空白，认全角数字；
+ * 空字符串为 null，解析不了时为 undefined。不经过浮点数，大整数、长小数不丢精度
+ */
+export declare function normalizeNumber(text: string, locale: string): string | null | undefined;
+/** 按语言解析用户输入成 number：解析不了时为 NaN，空字符串为 null */
+export declare function parseNumber(text: string, locale: string): number | null;

package/dist/utils/data/number-parse.js

@@ -0,0 +1,45 @@
+import { cachedIntl } from "./intl-cache.js";
+//#region src/utils/data/number-parse.ts
+/**
+* 按语言解析用户输入的数字（NumberField 用；表格筛选、导入等要读数字文本的地方也可以用）：
+* 认当前语言的小数点与千分位、全角数字与负号。
+*
+*   normalizeNumber('1.234,5', 'de-DE') → '1234.5'
+*   parseNumber('１２．５', 'zh-CN')      → 12.5
+*/
+/** 当前语言的数字符号：小数点、千分位、负号（按语言缓存：每次输入都要用） */
+function numberSymbols(locale) {
+	return cachedIntl(`number-symbols|${locale}`, () => {
+		const parts = new Intl.NumberFormat(locale).formatToParts(-12345.6);
+		const find = (type) => parts.find((part) => part.type === type)?.value;
+		return {
+			decimal: find("decimal") ?? ".",
+			group: find("group") ?? ",",
+			minus: find("minusSign") ?? "-"
+		};
+	});
+}
+/**
+* 按语言把用户输入规范成十进制文本（'-1234.5'）：去掉千分位与空白，认全角数字；
+* 空字符串为 null，解析不了时为 undefined。不经过浮点数，大整数、长小数不丢精度
+*/
+function normalizeNumber(text, locale) {
+	const { decimal, group, minus } = numberSymbols(locale);
+	let normalized = text.replace(/[０-９]/g, (char) => String.fromCharCode(char.charCodeAt(0) - 65248)).replace(/[．｡]/g, ".").replace(/[－−]/g, "-").replace(/[\s  ]/g, "");
+	if (!normalized) return null;
+	if (group !== decimal) normalized = normalized.split(group).join("");
+	if (decimal !== ".") normalized = normalized.split(decimal).join(".");
+	normalized = normalized.split(minus).join("-");
+	if (!/^-?(\d+\.?\d*|\.\d+)$/.test(normalized)) return void 0;
+	return normalized.replace(/^(-?)\./, "$10.").replace(/\.$/, "");
+}
+/** 按语言解析用户输入成 number：解析不了时为 NaN，空字符串为 null */
+function parseNumber(text, locale) {
+	const normalized = normalizeNumber(text, locale);
+	if (normalized === void 0) return NaN;
+	return normalized === null ? null : Number(normalized);
+}
+//#endregion
+export { normalizeNumber, parseNumber };
+
+//# sourceMappingURL=number-parse.js.map

package/dist/utils/data/number-parse.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"number-parse.js","names":[],"sources":["../../../src/utils/data/number-parse.ts"],"sourcesContent":["/**\n * 按语言解析用户输入的数字（NumberField 用；表格筛选、导入等要读数字文本的地方也可以用）：\n * 认当前语言的小数点与千分位、全角数字与负号。\n *\n *   normalizeNumber('1.234,5', 'de-DE') → '1234.5'\n *   parseNumber('１２．５', 'zh-CN')      → 12.5\n */\nimport { cachedIntl } from './intl-cache';\n\n/** 当前语言的数字符号：小数点、千分位、负号（按语言缓存：每次输入都要用） */\nfunction numberSymbols(locale: string) {\n  return cachedIntl(`number-symbols|${locale}`, () => {\n    const parts = new Intl.NumberFormat(locale).formatToParts(-12345.6);\n    const find = (type: string) => parts.find((part) => part.type === type)?.value;\n    return {\n      decimal: find('decimal') ?? '.',\n      group: find('group') ?? ',',\n      minus: find('minusSign') ?? '-',\n    };\n  });\n}\n\n/**\n * 按语言把用户输入规范成十进制文本（'-1234.5'）：去掉千分位与空白，认全角数字；\n * 空字符串为 null，解析不了时为 undefined。不经过浮点数，大整数、长小数不丢精度\n */\nexport function normalizeNumber(text: string, locale: string): string | null | undefined {\n  const { decimal, group, minus } = numberSymbols(locale);\n  let normalized = text\n    // 全角数字、全角句点与负号（中文输入法）\n    .replace(/[０-９]/g, (char) => String.fromCharCode(char.charCodeAt(0) - 0xfee0))\n    .replace(/[．｡]/g, '.')\n    .replace(/[－−]/g, '-')\n    .replace(/[\\s  ]/g, '');\n  if (!normalized) return null;\n  if (group !== decimal) normalized = normalized.split(group).join('');\n  if (decimal !== '.') normalized = normalized.split(decimal).join('.');\n  normalized = normalized.split(minus).join('-');\n  if (!/^-?(\\d+\\.?\\d*|\\.\\d+)$/.test(normalized)) return undefined;\n  // '.5' → '0.5'、'12.' → '12'：Decimal 与 BigInt 都认的写法\n  return normalized.replace(/^(-?)\\./, '$10.').replace(/\\.$/, '');\n}\n\n/** 按语言解析用户输入成 number：解析不了时为 NaN，空字符串为 null */\nexport function parseNumber(text: string, locale: string): number | null {\n  const normalized = normalizeNumber(text, locale);\n  if (normalized === undefined) return Number.NaN;\n  return normalized === null ? null : Number(normalized);\n}\n"],"mappings":";;;;;;;;;;AAUA,SAAS,cAAc,QAAgB;CACrC,OAAO,WAAW,kBAAkB,gBAAgB;EAClD,MAAM,QAAQ,IAAI,KAAK,aAAa,MAAM,CAAC,CAAC,cAAc,QAAQ;EAClE,MAAM,QAAQ,SAAiB,MAAM,MAAM,SAAS,KAAK,SAAS,IAAI,CAAC,EAAE;EACzE,OAAO;GACL,SAAS,KAAK,SAAS,KAAK;GAC5B,OAAO,KAAK,OAAO,KAAK;GACxB,OAAO,KAAK,WAAW,KAAK;EAC9B;CACF,CAAC;AACH;;;;;AAMA,SAAgB,gBAAgB,MAAc,QAA2C;CACvF,MAAM,EAAE,SAAS,OAAO,UAAU,cAAc,MAAM;CACtD,IAAI,aAAa,KAEd,QAAQ,WAAW,SAAS,OAAO,aAAa,KAAK,WAAW,CAAC,IAAI,KAAM,CAAC,CAAC,CAC7E,QAAQ,SAAS,GAAG,CAAC,CACrB,QAAQ,SAAS,GAAG,CAAC,CACrB,QAAQ,WAAW,EAAE;CACxB,IAAI,CAAC,YAAY,OAAO;CACxB,IAAI,UAAU,SAAS,aAAa,WAAW,MAAM,KAAK,CAAC,CAAC,KAAK,EAAE;CACnE,IAAI,YAAY,KAAK,aAAa,WAAW,MAAM,OAAO,CAAC,CAAC,KAAK,GAAG;CACpE,aAAa,WAAW,MAAM,KAAK,CAAC,CAAC,KAAK,GAAG;CAC7C,IAAI,CAAC,wBAAwB,KAAK,UAAU,GAAG,OAAO,KAAA;CAEtD,OAAO,WAAW,QAAQ,WAAW,MAAM,CAAC,CAAC,QAAQ,OAAO,EAAE;AAChE;;AAGA,SAAgB,YAAY,MAAc,QAA+B;CACvE,MAAM,aAAa,gBAAgB,MAAM,MAAM;CAC/C,IAAI,eAAe,KAAA,GAAW,OAAO;CACrC,OAAO,eAAe,OAAO,OAAO,OAAO,UAAU;AACvD"}

package/dist/utils/data/number.d.ts

@@ -0,0 +1,10 @@
+/**
+ * 数值的小工具：取值夹在范围内、对齐到步长（滑块、数字输入、分页、虚拟滚动共用）。
+ */
+/** 把 value 夹在 [min, max] 之间 */
+export declare function clamp(value: number, min: number, max: number): number;
+/**
+ * 夹在 [min, max] 之间并对齐到 min + n × step（没有 min 时对齐到 0 + n × step）；
+ * 结果按 step 与 min 的小数位取整，不带进 0.1 + 0.2 这类浮点误差。Slider、NumberField 共用
+ */
+export declare function snapToStep(value: number, step: number, min?: number, max?: number): number;

package/dist/utils/data/number.js

@@ -0,0 +1,28 @@
+//#region src/utils/data/number.ts
+/**
+* 数值的小工具：取值夹在范围内、对齐到步长（滑块、数字输入、分页、虚拟滚动共用）。
+*/
+/** 把 value 夹在 [min, max] 之间 */
+function clamp(value, min, max) {
+	return Math.min(max, Math.max(min, value));
+}
+/** 小数位数：0.1 → 1，1e-7 → 7（String(1e-7) 是科学计数法，不能按小数点拆） */
+function decimals(value) {
+	if (!Number.isFinite(value)) return 0;
+	const [mantissa = "", exponent = "0"] = value.toExponential().split("e");
+	return Math.max(0, (mantissa.split(".")[1] ?? "").length - Number(exponent));
+}
+/**
+* 夹在 [min, max] 之间并对齐到 min + n × step（没有 min 时对齐到 0 + n × step）；
+* 结果按 step 与 min 的小数位取整，不带进 0.1 + 0.2 这类浮点误差。Slider、NumberField 共用
+*/
+function snapToStep(value, step, min = -Infinity, max = Infinity) {
+	const base = Number.isFinite(min) ? min : 0;
+	const stepped = base + Math.round((value - base) / step) * step;
+	const places = Math.max(decimals(step), Number.isFinite(min) ? decimals(min) : 0);
+	return Number(clamp(stepped, min, max).toFixed(places));
+}
+//#endregion
+export { clamp, snapToStep };
+
+//# sourceMappingURL=number.js.map

package/dist/utils/data/number.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"number.js","names":[],"sources":["../../../src/utils/data/number.ts"],"sourcesContent":["/**\n * 数值的小工具：取值夹在范围内、对齐到步长（滑块、数字输入、分页、虚拟滚动共用）。\n */\n\n/** 把 value 夹在 [min, max] 之间 */\nexport function clamp(value: number, min: number, max: number): number {\n  return Math.min(max, Math.max(min, value));\n}\n\n/** 小数位数：0.1 → 1，1e-7 → 7（String(1e-7) 是科学计数法，不能按小数点拆） */\nfunction decimals(value: number): number {\n  if (!Number.isFinite(value)) return 0;\n  const [mantissa = '', exponent = '0'] = value.toExponential().split('e');\n  return Math.max(0, (mantissa.split('.')[1] ?? '').length - Number(exponent));\n}\n\n/**\n * 夹在 [min, max] 之间并对齐到 min + n × step（没有 min 时对齐到 0 + n × step）；\n * 结果按 step 与 min 的小数位取整，不带进 0.1 + 0.2 这类浮点误差。Slider、NumberField 共用\n */\nexport function snapToStep(value: number, step: number, min = -Infinity, max = Infinity): number {\n  const base = Number.isFinite(min) ? min : 0;\n  const stepped = base + Math.round((value - base) / step) * step;\n  const places = Math.max(decimals(step), Number.isFinite(min) ? decimals(min) : 0);\n  return Number(clamp(stepped, min, max).toFixed(places));\n}\n"],"mappings":";;;;;AAKA,SAAgB,MAAM,OAAe,KAAa,KAAqB;CACrE,OAAO,KAAK,IAAI,KAAK,KAAK,IAAI,KAAK,KAAK,CAAC;AAC3C;;AAGA,SAAS,SAAS,OAAuB;CACvC,IAAI,CAAC,OAAO,SAAS,KAAK,GAAG,OAAO;CACpC,MAAM,CAAC,WAAW,IAAI,WAAW,OAAO,MAAM,cAAc,CAAC,CAAC,MAAM,GAAG;CACvE,OAAO,KAAK,IAAI,IAAI,SAAS,MAAM,GAAG,CAAC,CAAC,MAAM,GAAA,CAAI,SAAS,OAAO,QAAQ,CAAC;AAC7E;;;;;AAMA,SAAgB,WAAW,OAAe,MAAc,MAAM,WAAW,MAAM,UAAkB;CAC/F,MAAM,OAAO,OAAO,SAAS,GAAG,IAAI,MAAM;CAC1C,MAAM,UAAU,OAAO,KAAK,OAAO,QAAQ,QAAQ,IAAI,IAAI;CAC3D,MAAM,SAAS,KAAK,IAAI,SAAS,IAAI,GAAG,OAAO,SAAS,GAAG,IAAI,SAAS,GAAG,IAAI,CAAC;CAChF,OAAO,OAAO,MAAM,SAAS,KAAK,GAAG,CAAC,CAAC,QAAQ,MAAM,CAAC;AACxD"}

package/dist/utils/data/numeric.d.ts

@@ -0,0 +1,55 @@
+/**
+ * 内置支持的数值类型：number、bigint 与 decimal.js 的 Decimal（金额、精确运算）。
+ * 组件的数值属性都接受它们（NumericValue），排序、格式化、表单提交不丢精度。
+ *
+ *   compareNumeric(new Decimal('1.5'), 1.25)   // 1：不同类型也按大小比
+ *   numericText(new Decimal('1e21'))           // '1000000000000000000000'：提交给服务端的十进制文本
+ *
+ * 这里不在运行时导入 decimal.js：按实例自己的构造函数识别与运算（使用方可能用 Decimal.clone 配了精度），
+ * 没用到 Decimal 的应用不会因此打包它。
+ */
+import type Decimal from 'decimal.js';
+/** 组件接受的数值 */
+export type NumericValue = number | bigint | Decimal;
+type DecimalConstructor = typeof Decimal;
+/** 是不是 decimal.js 的 Decimal（含 Decimal.clone 出来的构造函数的实例） */
+export declare function isDecimal(value: unknown): value is Decimal;
+/** 能读成数字的文字：接口常把金额给成十进制字符串（'19.90'）；空白、Infinity、不是数字的都不算 */
+export declare function isNumericText(value: unknown): value is string;
+/** 是不是组件接受的数值（NaN 也算 number，由使用方决定怎么处理） */
+export declare function isNumeric(value: unknown): value is NumericValue;
+/** 转成 number：只给需要浮点数的地方用（动画的中间帧、图表坐标、aria-valuenow），会丢精度 */
+export declare function toNumber(value: NumericValue): number;
+/** 十进制文本，不用科学计数法：表单提交、复制给服务端；NaN、Infinity 原样 */
+export declare function numericText(value: NumericValue): string;
+/**
+ * 十进制文本的小数点左移 places 位（除以 10 的 places 次方；负数右移），按文字移位、不经过浮点数：
+ * `shiftDecimal('155353.2', 4)` → `'15.53532'`。不是普通十进制写法的文本（NaN、科学计数法）原样返回
+ */
+export declare function shiftDecimal(text: string, places: number): string;
+/**
+ * 按大小比较两个数值，不同类型混着也行：返回负数、0 或正数（同 Array.prototype.sort 的约定）。
+ * 有 Decimal 时按十进制精确比较；number 与 bigint 之间不经过浮点数（大整数不丢精度）；NaN 排在最后
+ */
+export declare function compareNumeric(a: NumericValue, b: NumericValue): number;
+/** 两个数值是否相等（1 与 1n、Decimal('1.0') 与 1 都算相等） */
+export declare const sameNumeric: (a: NumericValue, b: NumericValue) => boolean;
+/** 数值写回成什么类型：number、bigint，或某个 Decimal 构造函数（使用方 Decimal.clone 配过精度的也行） */
+export type NumericKind = 'number' | 'bigint' | DecimalConstructor;
+/** 值的类型：Decimal 取它自己的构造函数 */
+export declare function numericKind(value: NumericValue): NumericKind;
+/**
+ * 转成指定类型；value 也可以是十进制文本（'-12.5'，输入框解析出来的）。
+ * bigint 四舍五入到整数，Decimal 按十进制文本转（不经过浮点数）
+ */
+export declare function toNumericKind(value: NumericValue | string, kind: NumericKind): NumericValue;
+/** 按 kind 精确相加：Decimal 用它的构造函数算，bigint 整数相加，number 浮点相加（再由 snapNumeric 去掉误差） */
+export declare function addNumeric(value: NumericValue, delta: NumericValue, kind: NumericKind): number | bigint | Decimal;
+/** value 的 times 倍（times 是整数，如 -1、10），按 kind 精确运算 */
+export declare function multiplyNumeric(value: NumericValue, times: number, kind: NumericKind): number | bigint | Decimal;
+/**
+ * 夹在 [min, max] 之间并对齐到 min + n × step（没有 min 时对齐到 0 + n × step），按 kind 精确运算：
+ * number 走 snapToStep（按小数位取整去掉浮点误差），bigint 的步长至少为 1，Decimal 用值自己的构造函数
+ */
+export declare function snapNumeric(value: NumericValue, step: NumericValue, min: NumericValue | undefined, max: NumericValue | undefined, kind: NumericKind): NumericValue;
+export {};

package/dist/utils/data/numeric.js

@@ -0,0 +1,133 @@
+import { snapToStep } from "./number.js";
+//#region src/utils/data/numeric.ts
+/** 是不是 decimal.js 的 Decimal（含 Decimal.clone 出来的构造函数的实例） */
+function isDecimal(value) {
+	if (typeof value !== "object" || value === null) return false;
+	const constructor = value.constructor;
+	return typeof constructor?.isDecimal === "function" && constructor.isDecimal(value);
+}
+/** 能读成数字的文字：接口常把金额给成十进制字符串（'19.90'）；空白、Infinity、不是数字的都不算 */
+function isNumericText(value) {
+	return typeof value === "string" && value.trim() !== "" && Number.isFinite(Number(value));
+}
+/** 是不是组件接受的数值（NaN 也算 number，由使用方决定怎么处理） */
+function isNumeric(value) {
+	return typeof value === "number" || typeof value === "bigint" || isDecimal(value);
+}
+/** 转成 number：只给需要浮点数的地方用（动画的中间帧、图表坐标、aria-valuenow），会丢精度 */
+function toNumber(value) {
+	if (typeof value === "number") return value;
+	if (typeof value === "bigint") return Number(value);
+	return value.toNumber();
+}
+/** 十进制文本，不用科学计数法：表单提交、复制给服务端；NaN、Infinity 原样 */
+function numericText(value) {
+	if (typeof value === "bigint") return value.toString();
+	if (typeof value === "number") {
+		if (!Number.isFinite(value)) return String(value);
+		return value === 0 || Math.abs(value) < 1e21 && Math.abs(value) >= 1e-6 ? String(value) : value.toLocaleString("en-US", {
+			useGrouping: false,
+			maximumFractionDigits: 20
+		});
+	}
+	return value.isFinite() ? value.toFixed() : value.toString();
+}
+/**
+* 十进制文本的小数点左移 places 位（除以 10 的 places 次方；负数右移），按文字移位、不经过浮点数：
+* `shiftDecimal('155353.2', 4)` → `'15.53532'`。不是普通十进制写法的文本（NaN、科学计数法）原样返回
+*/
+function shiftDecimal(text, places) {
+	const match = /^([+-]?)(\d*)(?:\.(\d*))?$/.exec(text);
+	if (!match || places === 0 || !/\d/.test(text)) return text;
+	const [, sign, whole = "", fraction = ""] = match;
+	const digits = whole + fraction;
+	const point = whole.length - places;
+	const padded = point <= 0 ? "0".repeat(1 - point) + digits : digits.padEnd(point, "0");
+	const at = Math.max(point, 1);
+	const integer = padded.slice(0, at).replace(/^0+(?=\d)/, "");
+	const decimal = padded.slice(at).replace(/0+$/, "");
+	return `${sign}${integer}${decimal ? `.${decimal}` : ""}`;
+}
+/** 用 Decimal 的构造函数（从 a 或 b 里找）把两个值都转成 Decimal 比较 */
+function compareWithDecimal(a, b, Ctor) {
+	return (isDecimal(a) ? a : new Ctor(numericText(a))).cmp(isDecimal(b) ? b : new Ctor(numericText(b)));
+}
+/**
+* 按大小比较两个数值，不同类型混着也行：返回负数、0 或正数（同 Array.prototype.sort 的约定）。
+* 有 Decimal 时按十进制精确比较；number 与 bigint 之间不经过浮点数（大整数不丢精度）；NaN 排在最后
+*/
+function compareNumeric(a, b) {
+	if (typeof a === "number" && Number.isNaN(a)) return typeof b === "number" && Number.isNaN(b) ? 0 : 1;
+	if (typeof b === "number" && Number.isNaN(b)) return -1;
+	if (isDecimal(a)) return compareWithDecimal(a, b, a.constructor);
+	if (isDecimal(b)) return compareWithDecimal(a, b, b.constructor);
+	return a < b ? -1 : a > b ? 1 : 0;
+}
+/** 两个数值是否相等（1 与 1n、Decimal('1.0') 与 1 都算相等） */
+var sameNumeric = (a, b) => compareNumeric(a, b) === 0;
+/** 值的类型：Decimal 取它自己的构造函数 */
+function numericKind(value) {
+	if (typeof value === "number") return "number";
+	if (typeof value === "bigint") return "bigint";
+	return value.constructor;
+}
+/** 十进制文本（'-12.5'）→ 整数，四舍五入（远离 0） */
+function roundedBigInt(text) {
+	const [whole = "0", fraction = ""] = text.replace(/^[+-]/, "").split(".");
+	const negative = text.startsWith("-");
+	let result = BigInt(whole || "0");
+	if (Number(fraction[0] ?? 0) >= 5) result += 1n;
+	return negative ? -result : result;
+}
+/**
+* 转成指定类型；value 也可以是十进制文本（'-12.5'，输入框解析出来的）。
+* bigint 四舍五入到整数，Decimal 按十进制文本转（不经过浮点数）
+*/
+function toNumericKind(value, kind) {
+	const text = () => typeof value === "string" ? value : numericText(value);
+	if (kind === "number") return typeof value === "string" ? Number(value) : toNumber(value);
+	if (kind === "bigint") return typeof value === "bigint" ? value : roundedBigInt(text());
+	return isDecimal(value) && value.constructor === kind ? value : new kind(text());
+}
+/** 按 kind 精确相加：Decimal 用它的构造函数算，bigint 整数相加，number 浮点相加（再由 snapNumeric 去掉误差） */
+function addNumeric(value, delta, kind) {
+	const left = toNumericKind(value, kind);
+	const right = toNumericKind(delta, kind);
+	if (typeof left === "number") return left + right;
+	if (typeof left === "bigint") return left + right;
+	return left.plus(right);
+}
+/** value 的 times 倍（times 是整数，如 -1、10），按 kind 精确运算 */
+function multiplyNumeric(value, times, kind) {
+	const typed = toNumericKind(value, kind);
+	if (typeof typed === "number") return typed * times;
+	if (typeof typed === "bigint") return typed * BigInt(times);
+	return typed.times(times);
+}
+/**
+* 夹在 [min, max] 之间并对齐到 min + n × step（没有 min 时对齐到 0 + n × step），按 kind 精确运算：
+* number 走 snapToStep（按小数位取整去掉浮点误差），bigint 的步长至少为 1，Decimal 用值自己的构造函数
+*/
+function snapNumeric(value, step, min, max, kind) {
+	if (kind === "number") return snapToStep(toNumber(value), toNumber(step), min == null ? -Infinity : toNumber(min), max == null ? Infinity : toNumber(max));
+	const at = (item) => toNumericKind(item, kind);
+	let snapped;
+	if (kind === "bigint") {
+		const size = at(step) > 0n ? at(step) : 1n;
+		const base = min == null ? 0n : at(min);
+		const offset = at(value) - base;
+		const half = offset < 0n ? -size : size;
+		snapped = base + (2n * offset + half) / (2n * size) * size;
+	} else {
+		const base = min == null ? new kind(0) : at(min);
+		const size = at(step);
+		snapped = base.plus(at(value).minus(base).div(size).round().times(size));
+	}
+	if (min != null && compareNumeric(snapped, min) < 0) snapped = at(min);
+	if (max != null && compareNumeric(snapped, max) > 0) snapped = at(max);
+	return snapped;
+}
+//#endregion
+export { addNumeric, compareNumeric, isDecimal, isNumeric, isNumericText, multiplyNumeric, numericKind, numericText, sameNumeric, shiftDecimal, snapNumeric, toNumber, toNumericKind };
+
+//# sourceMappingURL=numeric.js.map

package/dist/utils/data/numeric.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"numeric.js","names":[],"sources":["../../../src/utils/data/numeric.ts"],"sourcesContent":["/**\n * 内置支持的数值类型：number、bigint 与 decimal.js 的 Decimal（金额、精确运算）。\n * 组件的数值属性都接受它们（NumericValue），排序、格式化、表单提交不丢精度。\n *\n *   compareNumeric(new Decimal('1.5'), 1.25)   // 1：不同类型也按大小比\n *   numericText(new Decimal('1e21'))           // '1000000000000000000000'：提交给服务端的十进制文本\n *\n * 这里不在运行时导入 decimal.js：按实例自己的构造函数识别与运算（使用方可能用 Decimal.clone 配了精度），\n * 没用到 Decimal 的应用不会因此打包它。\n */\nimport type Decimal from 'decimal.js';\nimport { snapToStep } from './number';\n\n/** 组件接受的数值 */\nexport type NumericValue = number | bigint | Decimal;\n\ntype DecimalConstructor = typeof Decimal;\n\n/** 是不是 decimal.js 的 Decimal（含 Decimal.clone 出来的构造函数的实例） */\nexport function isDecimal(value: unknown): value is Decimal {\n  if (typeof value !== 'object' || value === null) return false;\n  const constructor = (value as { constructor?: Partial<DecimalConstructor> }).constructor;\n  return typeof constructor?.isDecimal === 'function' && constructor.isDecimal(value);\n}\n\n/** 能读成数字的文字：接口常把金额给成十进制字符串（'19.90'）；空白、Infinity、不是数字的都不算 */\nexport function isNumericText(value: unknown): value is string {\n  return typeof value === 'string' && value.trim() !== '' && Number.isFinite(Number(value));\n}\n\n/** 是不是组件接受的数值（NaN 也算 number，由使用方决定怎么处理） */\nexport function isNumeric(value: unknown): value is NumericValue {\n  return typeof value === 'number' || typeof value === 'bigint' || isDecimal(value);\n}\n\n/** 转成 number：只给需要浮点数的地方用（动画的中间帧、图表坐标、aria-valuenow），会丢精度 */\nexport function toNumber(value: NumericValue): number {\n  if (typeof value === 'number') return value;\n  if (typeof value === 'bigint') return Number(value);\n  return value.toNumber();\n}\n\n/** 十进制文本，不用科学计数法：表单提交、复制给服务端；NaN、Infinity 原样 */\nexport function numericText(value: NumericValue): string {\n  if (typeof value === 'bigint') return value.toString();\n  if (typeof value === 'number') {\n    if (!Number.isFinite(value)) return String(value);\n    // 1e21 以上、1e-6 以下 String() 会写成科学计数法；toLocaleString 不带分组时给出完整的十进制\n    const plain = value === 0 || (Math.abs(value) < 1e21 && Math.abs(value) >= 1e-6);\n    return plain\n      ? String(value)\n      : value.toLocaleString('en-US', { useGrouping: false, maximumFractionDigits: 20 });\n  }\n  return value.isFinite() ? value.toFixed() : value.toString();\n}\n\n/**\n * 十进制文本的小数点左移 places 位（除以 10 的 places 次方；负数右移），按文字移位、不经过浮点数：\n * `shiftDecimal('155353.2', 4)` → `'15.53532'`。不是普通十进制写法的文本（NaN、科学计数法）原样返回\n */\nexport function shiftDecimal(text: string, places: number): string {\n  const match = /^([+-]?)(\\d*)(?:\\.(\\d*))?$/.exec(text);\n  if (!match || places === 0 || !/\\d/.test(text)) return text;\n  const [, sign, whole = '', fraction = ''] = match;\n  const digits = whole + fraction;\n  const point = whole.length - places;\n  const padded = point <= 0 ? '0'.repeat(1 - point) + digits : digits.padEnd(point, '0');\n  const at = Math.max(point, 1);\n  const integer = padded.slice(0, at).replace(/^0+(?=\\d)/, '');\n  const decimal = padded.slice(at).replace(/0+$/, '');\n  return `${sign}${integer}${decimal ? `.${decimal}` : ''}`;\n}\n\n/** 用 Decimal 的构造函数（从 a 或 b 里找）把两个值都转成 Decimal 比较 */\nfunction compareWithDecimal(a: NumericValue, b: NumericValue, Ctor: DecimalConstructor): number {\n  const left = isDecimal(a) ? a : new Ctor(numericText(a));\n  return left.cmp(isDecimal(b) ? b : new Ctor(numericText(b)));\n}\n\n/**\n * 按大小比较两个数值，不同类型混着也行：返回负数、0 或正数（同 Array.prototype.sort 的约定）。\n * 有 Decimal 时按十进制精确比较；number 与 bigint 之间不经过浮点数（大整数不丢精度）；NaN 排在最后\n */\nexport function compareNumeric(a: NumericValue, b: NumericValue): number {\n  if (typeof a === 'number' && Number.isNaN(a))\n    return typeof b === 'number' && Number.isNaN(b) ? 0 : 1;\n  if (typeof b === 'number' && Number.isNaN(b)) return -1;\n  if (isDecimal(a)) return compareWithDecimal(a, b, a.constructor as DecimalConstructor);\n  if (isDecimal(b)) return compareWithDecimal(a, b, b.constructor as DecimalConstructor);\n  // number、bigint 之间：JavaScript 的关系运算符对混合类型按数学值比较，不丢精度\n  return a < b ? -1 : a > b ? 1 : 0;\n}\n\n/** 两个数值是否相等（1 与 1n、Decimal('1.0') 与 1 都算相等） */\nexport const sameNumeric = (a: NumericValue, b: NumericValue) => compareNumeric(a, b) === 0;\n\n/** 数值写回成什么类型：number、bigint，或某个 Decimal 构造函数（使用方 Decimal.clone 配过精度的也行） */\nexport type NumericKind = 'number' | 'bigint' | DecimalConstructor;\n\n/** 值的类型：Decimal 取它自己的构造函数 */\nexport function numericKind(value: NumericValue): NumericKind {\n  if (typeof value === 'number') return 'number';\n  if (typeof value === 'bigint') return 'bigint';\n  return value.constructor as DecimalConstructor;\n}\n\n/** 十进制文本（'-12.5'）→ 整数，四舍五入（远离 0） */\nfunction roundedBigInt(text: string): bigint {\n  const [whole = '0', fraction = ''] = text.replace(/^[+-]/, '').split('.');\n  const negative = text.startsWith('-');\n  let result = BigInt(whole || '0');\n  if (Number(fraction[0] ?? 0) >= 5) result += 1n;\n  return negative ? -result : result;\n}\n\n/**\n * 转成指定类型；value 也可以是十进制文本（'-12.5'，输入框解析出来的）。\n * bigint 四舍五入到整数，Decimal 按十进制文本转（不经过浮点数）\n */\nexport function toNumericKind(value: NumericValue | string, kind: NumericKind): NumericValue {\n  const text = () => (typeof value === 'string' ? value : numericText(value));\n  if (kind === 'number') return typeof value === 'string' ? Number(value) : toNumber(value);\n  if (kind === 'bigint') return typeof value === 'bigint' ? value : roundedBigInt(text());\n  return isDecimal(value) && value.constructor === kind ? value : new kind(text());\n}\n\n/** 按 kind 精确相加：Decimal 用它的构造函数算，bigint 整数相加，number 浮点相加（再由 snapNumeric 去掉误差） */\nexport function addNumeric(value: NumericValue, delta: NumericValue, kind: NumericKind) {\n  const left = toNumericKind(value, kind);\n  const right = toNumericKind(delta, kind);\n  if (typeof left === 'number') return left + (right as number);\n  if (typeof left === 'bigint') return left + (right as bigint);\n  return (left as Decimal).plus(right as Decimal);\n}\n\n/** value 的 times 倍（times 是整数，如 -1、10），按 kind 精确运算 */\nexport function multiplyNumeric(value: NumericValue, times: number, kind: NumericKind) {\n  const typed = toNumericKind(value, kind);\n  if (typeof typed === 'number') return typed * times;\n  if (typeof typed === 'bigint') return typed * BigInt(times);\n  return (typed as Decimal).times(times);\n}\n\n/**\n * 夹在 [min, max] 之间并对齐到 min + n × step（没有 min 时对齐到 0 + n × step），按 kind 精确运算：\n * number 走 snapToStep（按小数位取整去掉浮点误差），bigint 的步长至少为 1，Decimal 用值自己的构造函数\n */\nexport function snapNumeric(\n  value: NumericValue,\n  step: NumericValue,\n  min: NumericValue | undefined,\n  max: NumericValue | undefined,\n  kind: NumericKind,\n): NumericValue {\n  if (kind === 'number') {\n    return snapToStep(\n      toNumber(value),\n      toNumber(step),\n      min == null ? -Infinity : toNumber(min),\n      max == null ? Infinity : toNumber(max),\n    );\n  }\n  const at = (item: NumericValue) => toNumericKind(item, kind);\n  let snapped: NumericValue;\n  if (kind === 'bigint') {\n    const size = (at(step) as bigint) > 0n ? (at(step) as bigint) : 1n;\n    const base = min == null ? 0n : (at(min) as bigint);\n    const offset = (at(value) as bigint) - base;\n    // 整数除法四舍五入（远离 0）\n    const half = offset < 0n ? -size : size;\n    snapped = base + ((2n * offset + half) / (2n * size)) * size;\n  } else {\n    const base = (min == null ? new kind(0) : at(min)) as Decimal;\n    const size = at(step) as Decimal;\n    snapped = base.plus((at(value) as Decimal).minus(base).div(size).round().times(size));\n  }\n  if (min != null && compareNumeric(snapped, min) < 0) snapped = at(min);\n  if (max != null && compareNumeric(snapped, max) > 0) snapped = at(max);\n  return snapped;\n}\n"],"mappings":";;;AAmBA,SAAgB,UAAU,OAAkC;CAC1D,IAAI,OAAO,UAAU,YAAY,UAAU,MAAM,OAAO;CACxD,MAAM,cAAe,MAAwD;CAC7E,OAAO,OAAO,aAAa,cAAc,cAAc,YAAY,UAAU,KAAK;AACpF;;AAGA,SAAgB,cAAc,OAAiC;CAC7D,OAAO,OAAO,UAAU,YAAY,MAAM,KAAK,MAAM,MAAM,OAAO,SAAS,OAAO,KAAK,CAAC;AAC1F;;AAGA,SAAgB,UAAU,OAAuC;CAC/D,OAAO,OAAO,UAAU,YAAY,OAAO,UAAU,YAAY,UAAU,KAAK;AAClF;;AAGA,SAAgB,SAAS,OAA6B;CACpD,IAAI,OAAO,UAAU,UAAU,OAAO;CACtC,IAAI,OAAO,UAAU,UAAU,OAAO,OAAO,KAAK;CAClD,OAAO,MAAM,SAAS;AACxB;;AAGA,SAAgB,YAAY,OAA6B;CACvD,IAAI,OAAO,UAAU,UAAU,OAAO,MAAM,SAAS;CACrD,IAAI,OAAO,UAAU,UAAU;EAC7B,IAAI,CAAC,OAAO,SAAS,KAAK,GAAG,OAAO,OAAO,KAAK;EAGhD,OADc,UAAU,KAAM,KAAK,IAAI,KAAK,IAAI,QAAQ,KAAK,IAAI,KAAK,KAAK,OAEvE,OAAO,KAAK,IACZ,MAAM,eAAe,SAAS;GAAE,aAAa;GAAO,uBAAuB;EAAG,CAAC;CACrF;CACA,OAAO,MAAM,SAAS,IAAI,MAAM,QAAQ,IAAI,MAAM,SAAS;AAC7D;;;;;AAMA,SAAgB,aAAa,MAAc,QAAwB;CACjE,MAAM,QAAQ,6BAA6B,KAAK,IAAI;CACpD,IAAI,CAAC,SAAS,WAAW,KAAK,CAAC,KAAK,KAAK,IAAI,GAAG,OAAO;CACvD,MAAM,GAAG,MAAM,QAAQ,IAAI,WAAW,MAAM;CAC5C,MAAM,SAAS,QAAQ;CACvB,MAAM,QAAQ,MAAM,SAAS;CAC7B,MAAM,SAAS,SAAS,IAAI,IAAI,OAAO,IAAI,KAAK,IAAI,SAAS,OAAO,OAAO,OAAO,GAAG;CACrF,MAAM,KAAK,KAAK,IAAI,OAAO,CAAC;CAC5B,MAAM,UAAU,OAAO,MAAM,GAAG,EAAE,CAAC,CAAC,QAAQ,aAAa,EAAE;CAC3D,MAAM,UAAU,OAAO,MAAM,EAAE,CAAC,CAAC,QAAQ,OAAO,EAAE;CAClD,OAAO,GAAG,OAAO,UAAU,UAAU,IAAI,YAAY;AACvD;;AAGA,SAAS,mBAAmB,GAAiB,GAAiB,MAAkC;CAE9F,QADa,UAAU,CAAC,IAAI,IAAI,IAAI,KAAK,YAAY,CAAC,CAAC,EAAA,CAC3C,IAAI,UAAU,CAAC,IAAI,IAAI,IAAI,KAAK,YAAY,CAAC,CAAC,CAAC;AAC7D;;;;;AAMA,SAAgB,eAAe,GAAiB,GAAyB;CACvE,IAAI,OAAO,MAAM,YAAY,OAAO,MAAM,CAAC,GACzC,OAAO,OAAO,MAAM,YAAY,OAAO,MAAM,CAAC,IAAI,IAAI;CACxD,IAAI,OAAO,MAAM,YAAY,OAAO,MAAM,CAAC,GAAG,OAAO;CACrD,IAAI,UAAU,CAAC,GAAG,OAAO,mBAAmB,GAAG,GAAG,EAAE,WAAiC;CACrF,IAAI,UAAU,CAAC,GAAG,OAAO,mBAAmB,GAAG,GAAG,EAAE,WAAiC;CAErF,OAAO,IAAI,IAAI,KAAK,IAAI,IAAI,IAAI;AAClC;;AAGA,IAAa,eAAe,GAAiB,MAAoB,eAAe,GAAG,CAAC,MAAM;;AAM1F,SAAgB,YAAY,OAAkC;CAC5D,IAAI,OAAO,UAAU,UAAU,OAAO;CACtC,IAAI,OAAO,UAAU,UAAU,OAAO;CACtC,OAAO,MAAM;AACf;;AAGA,SAAS,cAAc,MAAsB;CAC3C,MAAM,CAAC,QAAQ,KAAK,WAAW,MAAM,KAAK,QAAQ,SAAS,EAAE,CAAC,CAAC,MAAM,GAAG;CACxE,MAAM,WAAW,KAAK,WAAW,GAAG;CACpC,IAAI,SAAS,OAAO,SAAS,GAAG;CAChC,IAAI,OAAO,SAAS,MAAM,CAAC,KAAK,GAAG,UAAU;CAC7C,OAAO,WAAW,CAAC,SAAS;AAC9B;;;;;AAMA,SAAgB,cAAc,OAA8B,MAAiC;CAC3F,MAAM,aAAc,OAAO,UAAU,WAAW,QAAQ,YAAY,KAAK;CACzE,IAAI,SAAS,UAAU,OAAO,OAAO,UAAU,WAAW,OAAO,KAAK,IAAI,SAAS,KAAK;CACxF,IAAI,SAAS,UAAU,OAAO,OAAO,UAAU,WAAW,QAAQ,cAAc,KAAK,CAAC;CACtF,OAAO,UAAU,KAAK,KAAK,MAAM,gBAAgB,OAAO,QAAQ,IAAI,KAAK,KAAK,CAAC;AACjF;;AAGA,SAAgB,WAAW,OAAqB,OAAqB,MAAmB;CACtF,MAAM,OAAO,cAAc,OAAO,IAAI;CACtC,MAAM,QAAQ,cAAc,OAAO,IAAI;CACvC,IAAI,OAAO,SAAS,UAAU,OAAO,OAAQ;CAC7C,IAAI,OAAO,SAAS,UAAU,OAAO,OAAQ;CAC7C,OAAQ,KAAiB,KAAK,KAAgB;AAChD;;AAGA,SAAgB,gBAAgB,OAAqB,OAAe,MAAmB;CACrF,MAAM,QAAQ,cAAc,OAAO,IAAI;CACvC,IAAI,OAAO,UAAU,UAAU,OAAO,QAAQ;CAC9C,IAAI,OAAO,UAAU,UAAU,OAAO,QAAQ,OAAO,KAAK;CAC1D,OAAQ,MAAkB,MAAM,KAAK;AACvC;;;;;AAMA,SAAgB,YACd,OACA,MACA,KACA,KACA,MACc;CACd,IAAI,SAAS,UACX,OAAO,WACL,SAAS,KAAK,GACd,SAAS,IAAI,GACb,OAAO,OAAO,YAAY,SAAS,GAAG,GACtC,OAAO,OAAO,WAAW,SAAS,GAAG,CACvC;CAEF,MAAM,MAAM,SAAuB,cAAc,MAAM,IAAI;CAC3D,IAAI;CACJ,IAAI,SAAS,UAAU;EACrB,MAAM,OAAQ,GAAG,IAAI,IAAe,KAAM,GAAG,IAAI,IAAe;EAChE,MAAM,OAAO,OAAO,OAAO,KAAM,GAAG,GAAG;EACvC,MAAM,SAAU,GAAG,KAAK,IAAe;EAEvC,MAAM,OAAO,SAAS,KAAK,CAAC,OAAO;EACnC,UAAU,QAAS,KAAK,SAAS,SAAS,KAAK,QAAS;CAC1D,OAAO;EACL,MAAM,OAAQ,OAAO,OAAO,IAAI,KAAK,CAAC,IAAI,GAAG,GAAG;EAChD,MAAM,OAAO,GAAG,IAAI;EACpB,UAAU,KAAK,KAAM,GAAG,KAAK,CAAC,CAAa,MAAM,IAAI,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,MAAM,CAAC,CAAC,MAAM,IAAI,CAAC;CACtF;CACA,IAAI,OAAO,QAAQ,eAAe,SAAS,GAAG,IAAI,GAAG,UAAU,GAAG,GAAG;CACrE,IAAI,OAAO,QAAQ,eAAe,SAAS,GAAG,IAAI,GAAG,UAAU,GAAG,GAAG;CACrE,OAAO;AACT"}

package/dist/utils/data/pagination.d.ts

@@ -0,0 +1,21 @@
+/**
+ * 分页的页码序列（纯函数，算法同 MUI 的 usePagination）：首尾各留 boundaries 页、当前页左右各留 siblings 页，
+ * 中间用省略号；序列长度固定（页数够多时总是 2 × boundaries + 2 × siblings + 3 项），翻页时按钮不跳动。
+ *
+ *   paginationItems({ page: 6, pageCount: 20 })  // [1, 'start-ellipsis', 5, 6, 7, 'end-ellipsis', 20]
+ */
+/** 省略号：start 在当前页之前，end 在之后（两者都可能出现，作为 key 要区分开） */
+export type PaginationEllipsis = 'start-ellipsis' | 'end-ellipsis';
+/** paginationItems 的参数 */
+export interface PaginationOptions {
+    /** 当前页，从 1 开始 */
+    page: number;
+    /** 总页数 */
+    pageCount: number;
+    /** 当前页左右各显示几页，默认 1 */
+    siblings?: number;
+    /** 首尾各固定显示几页，默认 1 */
+    boundaries?: number;
+}
+/** 要显示的页码与省略号，依次排列 */
+export declare function paginationItems({ page, pageCount, siblings, boundaries, }: PaginationOptions): (number | PaginationEllipsis)[];

package/dist/utils/data/pagination.js

@@ -0,0 +1,22 @@
+//#region src/utils/data/pagination.ts
+var range = (from, to) => Array.from({ length: Math.max(0, to - from + 1) }, (_, index) => from + index);
+/** 要显示的页码与省略号，依次排列 */
+function paginationItems({ page, pageCount, siblings = 1, boundaries = 1 }) {
+	const startPages = range(1, Math.min(boundaries, pageCount));
+	const endPages = range(Math.max(pageCount - boundaries + 1, boundaries + 1), pageCount);
+	const siblingsStart = Math.max(Math.min(page - siblings, pageCount - boundaries - siblings * 2 - 1), boundaries + 2);
+	const siblingsEnd = Math.min(Math.max(page + siblings, boundaries + siblings * 2 + 2), endPages.length > 0 ? endPages[0] - 2 : pageCount - 1);
+	const before = siblingsStart > boundaries + 2 ? ["start-ellipsis"] : boundaries + 1 < pageCount - boundaries ? [boundaries + 1] : [];
+	const after = siblingsEnd < pageCount - boundaries - 1 ? ["end-ellipsis"] : pageCount - boundaries > boundaries ? [pageCount - boundaries] : [];
+	return [
+		...startPages,
+		...before,
+		...range(siblingsStart, siblingsEnd),
+		...after,
+		...endPages
+	];
+}
+//#endregion
+export { paginationItems };
+
+//# sourceMappingURL=pagination.js.map

package/dist/utils/data/pagination.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pagination.js","names":[],"sources":["../../../src/utils/data/pagination.ts"],"sourcesContent":["/**\n * 分页的页码序列（纯函数，算法同 MUI 的 usePagination）：首尾各留 boundaries 页、当前页左右各留 siblings 页，\n * 中间用省略号；序列长度固定（页数够多时总是 2 × boundaries + 2 × siblings + 3 项），翻页时按钮不跳动。\n *\n *   paginationItems({ page: 6, pageCount: 20 })  // [1, 'start-ellipsis', 5, 6, 7, 'end-ellipsis', 20]\n */\n\n/** 省略号：start 在当前页之前，end 在之后（两者都可能出现，作为 key 要区分开） */\nexport type PaginationEllipsis = 'start-ellipsis' | 'end-ellipsis';\n\n/** paginationItems 的参数 */\nexport interface PaginationOptions {\n  /** 当前页，从 1 开始 */\n  page: number;\n  /** 总页数 */\n  pageCount: number;\n  /** 当前页左右各显示几页，默认 1 */\n  siblings?: number;\n  /** 首尾各固定显示几页，默认 1 */\n  boundaries?: number;\n}\n\nconst range = (from: number, to: number) =>\n  Array.from({ length: Math.max(0, to - from + 1) }, (_, index) => from + index);\n\n/** 要显示的页码与省略号，依次排列 */\nexport function paginationItems({\n  page,\n  pageCount,\n  siblings = 1,\n  boundaries = 1,\n}: PaginationOptions): (number | PaginationEllipsis)[] {\n  const startPages = range(1, Math.min(boundaries, pageCount));\n  const endPages = range(Math.max(pageCount - boundaries + 1, boundaries + 1), pageCount);\n  // 当前页这一组的起止：靠近两端时向另一侧多借几页，保持总项数不变\n  const siblingsStart = Math.max(\n    Math.min(page - siblings, pageCount - boundaries - siblings * 2 - 1),\n    boundaries + 2,\n  );\n  const siblingsEnd = Math.min(\n    Math.max(page + siblings, boundaries + siblings * 2 + 2),\n    endPages.length > 0 ? endPages[0]! - 2 : pageCount - 1,\n  );\n  // 省略号只代替两页以上；只隔一页时直接显示那一页\n  const before =\n    siblingsStart > boundaries + 2\n      ? ['start-ellipsis' as const]\n      : boundaries + 1 < pageCount - boundaries\n        ? [boundaries + 1]\n        : [];\n  const after =\n    siblingsEnd < pageCount - boundaries - 1\n      ? ['end-ellipsis' as const]\n      : pageCount - boundaries > boundaries\n        ? [pageCount - boundaries]\n        : [];\n  return [...startPages, ...before, ...range(siblingsStart, siblingsEnd), ...after, ...endPages];\n}\n"],"mappings":";AAsBA,IAAM,SAAS,MAAc,OAC3B,MAAM,KAAK,EAAE,QAAQ,KAAK,IAAI,GAAG,KAAK,OAAO,CAAC,EAAE,IAAI,GAAG,UAAU,OAAO,KAAK;;AAG/E,SAAgB,gBAAgB,EAC9B,MACA,WACA,WAAW,GACX,aAAa,KACwC;CACrD,MAAM,aAAa,MAAM,GAAG,KAAK,IAAI,YAAY,SAAS,CAAC;CAC3D,MAAM,WAAW,MAAM,KAAK,IAAI,YAAY,aAAa,GAAG,aAAa,CAAC,GAAG,SAAS;CAEtF,MAAM,gBAAgB,KAAK,IACzB,KAAK,IAAI,OAAO,UAAU,YAAY,aAAa,WAAW,IAAI,CAAC,GACnE,aAAa,CACf;CACA,MAAM,cAAc,KAAK,IACvB,KAAK,IAAI,OAAO,UAAU,aAAa,WAAW,IAAI,CAAC,GACvD,SAAS,SAAS,IAAI,SAAS,KAAM,IAAI,YAAY,CACvD;CAEA,MAAM,SACJ,gBAAgB,aAAa,IACzB,CAAC,gBAAyB,IAC1B,aAAa,IAAI,YAAY,aAC3B,CAAC,aAAa,CAAC,IACf,CAAC;CACT,MAAM,QACJ,cAAc,YAAY,aAAa,IACnC,CAAC,cAAuB,IACxB,YAAY,aAAa,aACvB,CAAC,YAAY,UAAU,IACvB,CAAC;CACT,OAAO;EAAC,GAAG;EAAY,GAAG;EAAQ,GAAG,MAAM,eAAe,WAAW;EAAG,GAAG;EAAO,GAAG;CAAQ;AAC/F"}

package/dist/utils/data/selection.d.ts

@@ -0,0 +1,41 @@
+/**
+ * 选择模型：单选、多选怎样响应“点了一项”（纯函数），以及单选 / 多选组件共用的 props。
+ * ToggleGroup、Listbox、Select、Combobox、CheckboxGroup、DataTable 的行选择都用它。
+ */
+/** 选择方式 */
+export interface SelectionModes {
+    /** 单选：选中一项会取消其他项；再点已选的项取消选中（required 时不取消） */
+    single: unknown;
+    /** 多选：每项独立切换 */
+    multiple: unknown;
+}
+/** 单选：value 是选中项的值 */
+export interface SingleSelectionProps {
+    /** 选择方式，默认 single */
+    selectionMode?: Extract<keyof SelectionModes, 'single'>;
+    /** 选中项：父级写 _value={x}；没有选中时是 null */
+    _value?: string | null;
+}
+/** 多选：value 是选中项的值的数组 */
+export interface MultipleSelectionProps {
+    /** 选择方式 */
+    selectionMode: Extract<keyof SelectionModes, 'multiple'>;
+    /** 选中项：父级写 _value={list} */
+    _value?: string[];
+}
+/** 单选或多选：按 selectionMode 区分 value 是一个值还是数组（Listbox、Select、ToggleGroup） */
+export type SelectionProps = SingleSelectionProps | MultipleSelectionProps;
+/** toggleSelection 的选项 */
+export interface SelectionOptions {
+    /** 选择方式 */
+    mode: keyof SelectionModes;
+    /** 至少保留一项：最后一个已选项不能被取消 */
+    required?: boolean;
+}
+/**
+ * 单选的值或多选的值数组 → 已选值的数组（单选、多选共用一套渲染与列表状态时）。
+ * 单选的空字符串算没有选中：表单的初始值常写 ''（同原生 select 的占位项），这时显示占位文字、不出清除按钮
+ */
+export declare const selectedValues: (value: string | readonly string[] | null | undefined) => readonly string[];
+/** 点了 key 之后的选择；没有变化时返回原数组 */
+export declare function toggleSelection<Key>(selected: readonly Key[], key: Key, { mode, required }: SelectionOptions): readonly Key[];