@pisell/utils 3.0.4 → 3.0.6

package/es/weighing.d.ts

@@ -0,0 +1,65 @@
+//#region src/weighing.d.ts
+/** 商品配置与 NativeScale 使用的重量单位。 */
+type WeightUnitName = 'KILOGRAMS' | 'GRAMS' | 'POUNDS' | 'OUNCES';
+/** 订单快照与 UI 使用的标准单位符号。 */
+type WeightUnitSymbol = 'kg' | 'g' | 'lb' | 'oz';
+type WeightUnit = WeightUnitName | WeightUnitSymbol;
+/**
+ * Pisell 的标准重量单位。目录单价、缺省秤单位和缺省展示均以它为准。
+ * 后续标准单位变化时，应优先只修改此处。
+ */
+declare const STANDARD_WEIGHT_UNIT: WeightUnitName;
+declare const WEIGHT_PRECISION = 3;
+declare const UNIT_PRICE_PRECISION = 2;
+declare const MAX_RETAIL_SCALE_WEIGHT_KG = 1000;
+declare const WEIGHT_UNIT_SYMBOLS: Record<WeightUnitName, WeightUnitSymbol>;
+declare const WEIGHT_UNIT_NAMES: Record<WeightUnitSymbol, WeightUnitName>;
+/** 单位对应的克数，作为不依赖 NativeScale 的目录价格换算基准。 */
+declare const WEIGHT_UNIT_GRAMS: Record<WeightUnit, number>;
+declare const STANDARD_WEIGHT_UNIT_SYMBOL: WeightUnitSymbol;
+declare const normalizeWeightUnit: (unit?: string | null, fallback?: WeightUnitName) => WeightUnitName;
+declare const getWeightUnitSymbol: (unit?: string | null) => string;
+declare const getWeightUnitGrams: (unit?: string | null) => number | undefined;
+/**
+ * 将“每 sourceUnitValue 个 sourceUnit 的价格”换算到每 1 个目标单位的倍率。
+ * 这里只处理目录单价的单位关系；实际秤读数计价仍应使用 NativeScale。
+ */
+declare const getWeightUnitPriceConversionFactor: (params: {
+  sourceUnit?: string | null;
+  sourceUnitValue?: string | number | null;
+  targetUnit?: string | null;
+}) => number | undefined;
+declare const isSupportedWeightUnit: (unit?: unknown) => unit is WeightUnit;
+declare const formatWeightValue: (value: unknown, precision?: number) => string;
+declare const formatUnitPriceValue: (value: unknown, precision?: number) => string;
+type ScaleReadingStatus = 'stable' | 'unstable' | 'overload' | 'negative' | string | null;
+declare const INVALID_SCALE_READING_STATUSES: readonly ["overload", "negative"];
+declare const isInvalidScaleReadingStatus: (status?: ScaleReadingStatus) => boolean;
+declare const getUsableScaleWeight: (status: ScaleReadingStatus | undefined, weight: number) => number;
+interface WeighingSnapshot {
+  open_sold_weight?: number | string | boolean;
+  mode?: 'auto' | 'manual' | string;
+  weight_source?: 'auto' | 'manual' | string;
+  weight?: string | number;
+  tare?: {
+    id?: string;
+    label?: string;
+    value?: string | number;
+    unit?: WeightUnit | string;
+  };
+  tare_name?: string;
+  tare_weight?: string | number;
+  net_weight?: string | number;
+  unit_price?: string | number;
+  unit?: WeightUnit | string;
+  unit_weight?: string | number;
+  unit_data_snapshot?: unknown;
+  scalePriceProduct?: unknown;
+  total_amount?: string | number;
+}
+/**
+ * 解析订单行称重快照：product_sku 是权威源，_extend.weighing 仅用于旧流程兼容。
+ */
+declare const resolveWeighingSnapshot: (dataSource?: Record<string, any> | null) => WeighingSnapshot | undefined;
+//#endregion
+export { INVALID_SCALE_READING_STATUSES, MAX_RETAIL_SCALE_WEIGHT_KG, STANDARD_WEIGHT_UNIT, STANDARD_WEIGHT_UNIT_SYMBOL, ScaleReadingStatus, UNIT_PRICE_PRECISION, WEIGHT_PRECISION, WEIGHT_UNIT_GRAMS, WEIGHT_UNIT_NAMES, WEIGHT_UNIT_SYMBOLS, WeighingSnapshot, WeightUnit, WeightUnitName, WeightUnitSymbol, formatUnitPriceValue, formatWeightValue, getUsableScaleWeight, getWeightUnitGrams, getWeightUnitPriceConversionFactor, getWeightUnitSymbol, isInvalidScaleReadingStatus, isSupportedWeightUnit, normalizeWeightUnit, resolveWeighingSnapshot };

package/es/weighing.js

@@ -0,0 +1,96 @@
+//#region src/weighing.ts
+/**
+* Pisell 的标准重量单位。目录单价、缺省秤单位和缺省展示均以它为准。
+* 后续标准单位变化时，应优先只修改此处。
+*/
+const STANDARD_WEIGHT_UNIT = "KILOGRAMS";
+const WEIGHT_PRECISION = 3;
+const UNIT_PRICE_PRECISION = 2;
+const MAX_RETAIL_SCALE_WEIGHT_KG = 1e3;
+const WEIGHT_UNIT_SYMBOLS = {
+	KILOGRAMS: "kg",
+	GRAMS: "g",
+	POUNDS: "lb",
+	OUNCES: "oz"
+};
+const WEIGHT_UNIT_NAMES = {
+	kg: "KILOGRAMS",
+	g: "GRAMS",
+	lb: "POUNDS",
+	oz: "OUNCES"
+};
+/** 单位对应的克数，作为不依赖 NativeScale 的目录价格换算基准。 */
+const WEIGHT_UNIT_GRAMS = {
+	KILOGRAMS: 1e3,
+	GRAMS: 1,
+	POUNDS: 453.59237,
+	OUNCES: 28.349523125,
+	kg: 1e3,
+	g: 1,
+	lb: 453.59237,
+	oz: 28.349523125
+};
+const STANDARD_WEIGHT_UNIT_SYMBOL = WEIGHT_UNIT_SYMBOLS[STANDARD_WEIGHT_UNIT];
+const normalizeWeightUnit = (unit, fallback = STANDARD_WEIGHT_UNIT) => {
+	if (unit && unit in WEIGHT_UNIT_SYMBOLS) return unit;
+	if (unit && unit in WEIGHT_UNIT_NAMES) return WEIGHT_UNIT_NAMES[unit];
+	return fallback;
+};
+const getWeightUnitSymbol = (unit) => {
+	if (unit && unit in WEIGHT_UNIT_SYMBOLS) return WEIGHT_UNIT_SYMBOLS[unit];
+	if (unit && unit in WEIGHT_UNIT_NAMES) return unit;
+	return unit || STANDARD_WEIGHT_UNIT_SYMBOL;
+};
+const getWeightUnitGrams = (unit) => unit ? WEIGHT_UNIT_GRAMS[unit] : WEIGHT_UNIT_GRAMS[STANDARD_WEIGHT_UNIT];
+/**
+* 将“每 sourceUnitValue 个 sourceUnit 的价格”换算到每 1 个目标单位的倍率。
+* 这里只处理目录单价的单位关系；实际秤读数计价仍应使用 NativeScale。
+*/
+const getWeightUnitPriceConversionFactor = (params) => {
+	var _params$sourceUnitVal;
+	const sourceGrams = getWeightUnitGrams(params.sourceUnit || "KILOGRAMS");
+	const targetGrams = getWeightUnitGrams(params.targetUnit || "KILOGRAMS");
+	const sourceUnitValue = Number((_params$sourceUnitVal = params.sourceUnitValue) !== null && _params$sourceUnitVal !== void 0 ? _params$sourceUnitVal : 1);
+	if (!sourceGrams || !targetGrams || !Number.isFinite(sourceUnitValue) || sourceUnitValue <= 0) return;
+	return targetGrams / (sourceGrams * sourceUnitValue);
+};
+const isSupportedWeightUnit = (unit) => typeof unit === "string" && unit in WEIGHT_UNIT_GRAMS;
+const formatWeightValue = (value, precision = 3) => {
+	const parsedValue = Number(value);
+	return (Number.isFinite(parsedValue) ? parsedValue : 0).toFixed(precision);
+};
+const formatUnitPriceValue = (value, precision = 2) => {
+	const parsedValue = Number(value);
+	return (Number.isFinite(parsedValue) ? parsedValue : 0).toFixed(precision);
+};
+const INVALID_SCALE_READING_STATUSES = ["overload", "negative"];
+const isInvalidScaleReadingStatus = (status) => INVALID_SCALE_READING_STATUSES.includes(status);
+const getUsableScaleWeight = (status, weight) => isInvalidScaleReadingStatus(status) ? 0 : weight;
+const hasDisplayWeight = (value) => Boolean(value && (Number(value.weight) > 0 || Number(value.net_weight) > 0));
+const resolveProductSkuSnapshot = (value) => {
+	const snapshot = value;
+	return Number(snapshot === null || snapshot === void 0 ? void 0 : snapshot.open_sold_weight) === 1 && hasDisplayWeight(snapshot) ? snapshot : void 0;
+};
+/**
+* 解析订单行称重快照：product_sku 是权威源，_extend.weighing 仅用于旧流程兼容。
+*/
+const resolveWeighingSnapshot = (dataSource) => {
+	var _dataSource$_origin, _dataSource$metadata, _dataSource$_origin2, _dataSource$_extend, _dataSource$metadata2;
+	if (!dataSource) return void 0;
+	const productSkuCandidates = [
+		dataSource.product_sku,
+		(_dataSource$_origin = dataSource._origin) === null || _dataSource$_origin === void 0 ? void 0 : _dataSource$_origin.product_sku,
+		(_dataSource$metadata = dataSource.metadata) === null || _dataSource$metadata === void 0 || (_dataSource$metadata = _dataSource$metadata.origin) === null || _dataSource$metadata === void 0 ? void 0 : _dataSource$metadata.product_sku
+	];
+	for (const candidate of productSkuCandidates) {
+		const snapshot = resolveProductSkuSnapshot(candidate);
+		if (snapshot) return snapshot;
+	}
+	return [
+		(_dataSource$_origin2 = dataSource._origin) === null || _dataSource$_origin2 === void 0 || (_dataSource$_origin2 = _dataSource$_origin2._extend) === null || _dataSource$_origin2 === void 0 ? void 0 : _dataSource$_origin2.weighing,
+		(_dataSource$_extend = dataSource._extend) === null || _dataSource$_extend === void 0 ? void 0 : _dataSource$_extend.weighing,
+		(_dataSource$metadata2 = dataSource.metadata) === null || _dataSource$metadata2 === void 0 || (_dataSource$metadata2 = _dataSource$metadata2.origin) === null || _dataSource$metadata2 === void 0 || (_dataSource$metadata2 = _dataSource$metadata2._extend) === null || _dataSource$metadata2 === void 0 ? void 0 : _dataSource$metadata2.weighing
+	].find((candidate) => hasDisplayWeight(candidate));
+};
+//#endregion
+export { INVALID_SCALE_READING_STATUSES, MAX_RETAIL_SCALE_WEIGHT_KG, STANDARD_WEIGHT_UNIT, STANDARD_WEIGHT_UNIT_SYMBOL, UNIT_PRICE_PRECISION, WEIGHT_PRECISION, WEIGHT_UNIT_GRAMS, WEIGHT_UNIT_NAMES, WEIGHT_UNIT_SYMBOLS, formatUnitPriceValue, formatWeightValue, getUsableScaleWeight, getWeightUnitGrams, getWeightUnitPriceConversionFactor, getWeightUnitSymbol, isInvalidScaleReadingStatus, isSupportedWeightUnit, normalizeWeightUnit, resolveWeighingSnapshot };

package/lib/_virtual/_@oxc-project_runtime@0.122.0/helpers/asyncToGenerator.js

@@ -0,0 +1,27 @@
+//#region \0@oxc-project+runtime@0.122.0/helpers/asyncToGenerator.js
+function asyncGeneratorStep(n, t, e, r, o, a, c) {
+	try {
+		var i = n[a](c), u = i.value;
+	} catch (n) {
+		e(n);
+		return;
+	}
+	i.done ? t(u) : Promise.resolve(u).then(r, o);
+}
+function _asyncToGenerator(n) {
+	return function() {
+		var t = this, e = arguments;
+		return new Promise(function(r, o) {
+			var a = n.apply(t, e);
+			function _next(n) {
+				asyncGeneratorStep(a, r, o, _next, _throw, "next", n);
+			}
+			function _throw(n) {
+				asyncGeneratorStep(a, r, o, _next, _throw, "throw", n);
+			}
+			_next(void 0);
+		});
+	};
+}
+//#endregion
+exports._asyncToGenerator = _asyncToGenerator;

package/lib/_virtual/_@oxc-project_runtime@0.122.0/helpers/defineProperty.js

@@ -0,0 +1,12 @@
+const require_toPropertyKey = require("./toPropertyKey.js");
+//#region \0@oxc-project+runtime@0.122.0/helpers/defineProperty.js
+function _defineProperty(e, r, t) {
+	return (r = require_toPropertyKey.toPropertyKey(r)) in e ? Object.defineProperty(e, r, {
+		value: t,
+		enumerable: !0,
+		configurable: !0,
+		writable: !0
+	}) : e[r] = t, e;
+}
+//#endregion
+exports._defineProperty = _defineProperty;

package/lib/_virtual/_@oxc-project_runtime@0.122.0/helpers/objectSpread2.js

@@ -0,0 +1,25 @@
+const require_defineProperty = require("./defineProperty.js");
+//#region \0@oxc-project+runtime@0.122.0/helpers/objectSpread2.js
+function ownKeys(e, r) {
+	var t = Object.keys(e);
+	if (Object.getOwnPropertySymbols) {
+		var o = Object.getOwnPropertySymbols(e);
+		r && (o = o.filter(function(r) {
+			return Object.getOwnPropertyDescriptor(e, r).enumerable;
+		})), t.push.apply(t, o);
+	}
+	return t;
+}
+function _objectSpread2(e) {
+	for (var r = 1; r < arguments.length; r++) {
+		var t = null != arguments[r] ? arguments[r] : {};
+		r % 2 ? ownKeys(Object(t), !0).forEach(function(r) {
+			require_defineProperty._defineProperty(e, r, t[r]);
+		}) : Object.getOwnPropertyDescriptors ? Object.defineProperties(e, Object.getOwnPropertyDescriptors(t)) : ownKeys(Object(t)).forEach(function(r) {
+			Object.defineProperty(e, r, Object.getOwnPropertyDescriptor(t, r));
+		});
+	}
+	return e;
+}
+//#endregion
+exports._objectSpread2 = _objectSpread2;

package/lib/_virtual/_@oxc-project_runtime@0.122.0/helpers/toPrimitive.js

@@ -0,0 +1,14 @@
+const require_typeof = require("./typeof.js");
+//#region \0@oxc-project+runtime@0.122.0/helpers/toPrimitive.js
+function toPrimitive(t, r) {
+	if ("object" != require_typeof._typeof(t) || !t) return t;
+	var e = t[Symbol.toPrimitive];
+	if (void 0 !== e) {
+		var i = e.call(t, r || "default");
+		if ("object" != require_typeof._typeof(i)) return i;
+		throw new TypeError("@@toPrimitive must return a primitive value.");
+	}
+	return ("string" === r ? String : Number)(t);
+}
+//#endregion
+exports.toPrimitive = toPrimitive;

package/lib/_virtual/_@oxc-project_runtime@0.122.0/helpers/toPropertyKey.js

@@ -0,0 +1,9 @@
+const require_typeof = require("./typeof.js");
+const require_toPrimitive = require("./toPrimitive.js");
+//#region \0@oxc-project+runtime@0.122.0/helpers/toPropertyKey.js
+function toPropertyKey(t) {
+	var i = require_toPrimitive.toPrimitive(t, "string");
+	return "symbol" == require_typeof._typeof(i) ? i : i + "";
+}
+//#endregion
+exports.toPropertyKey = toPropertyKey;

package/lib/_virtual/_@oxc-project_runtime@0.122.0/helpers/typeof.js

@@ -0,0 +1,16 @@
+//#region \0@oxc-project+runtime@0.122.0/helpers/typeof.js
+function _typeof(o) {
+	"@babel/helpers - typeof";
+	return _typeof = "function" == typeof Symbol && "symbol" == typeof Symbol.iterator ? function(o) {
+		return typeof o;
+	} : function(o) {
+		return o && "function" == typeof Symbol && o.constructor === Symbol && o !== Symbol.prototype ? "symbol" : typeof o;
+	}, _typeof(o);
+}
+//#endregion
+Object.defineProperty(exports, "_typeof", {
+	enumerable: true,
+	get: function() {
+		return _typeof;
+	}
+});

package/lib/_virtual/_rolldown/runtime.js

@@ -0,0 +1,23 @@
+//#region \0rolldown/runtime.js
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+		key = keys[i];
+		if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
+			get: ((k) => from[k]).bind(null, key),
+			enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+		});
+	}
+	return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
+	value: mod,
+	enumerable: true
+}) : target, mod));
+//#endregion
+exports.__toESM = __toESM;

package/lib/arrayUtils.d.ts

@@ -1 +1,76 @@
-export declare const uniqueByKey: <T>(arr: T[], key: keyof T) => T[];
+//#region src/arrayUtils.d.ts
+declare const uniqueByKey: <T>(arr: T[], key: keyof T) => T[];
+/**
+ * 分组键的基础类型
+ * @description 分组条件计算后得到的标量值
+ */
+type GroupKey = string | number | boolean;
+/**
+ * 分组规则
+ * @template T - 数据项类型
+ * @description
+ * - `string`：单字段路径，支持 `'a.b.c'` 点路径
+ * - `string[]`：多字段组合，按顺序拼接为组合键
+ * - `(item, index) => GroupKey | GroupKey[]`：完全自定义分组键
+ */
+type GroupBySpec<T> = string | string[] | ((item: T, index: number) => GroupKey | GroupKey[]);
+/**
+ * 单个分组的结果模型
+ * @template T - 数据项类型
+ */
+interface GroupResult<T> {
+  /** 分组唯一标识（默认由各分组键以 `|` 拼接） */
+  groupId: string;
+  /** 分组键值数组，与 `GroupBySpec` 顺序对应 */
+  keys: GroupKey[];
+  /** 字段名 -> 键值映射，便于头部直接按字段名取值（自定义函数分组时为空对象） */
+  keyMap: Record<string, GroupKey>;
+  /** 该分组内的原始数据项（保持原数组中的相对顺序） */
+  items: T[];
+  /** 分组的最终顺序下标 */
+  index: number;
+}
+/**
+ * 分组可选项
+ * @template T - 数据项类型
+ */
+interface GroupByOptions<T> {
+  /** 自定义分组 id 生成（默认 `keys.join('|')`） */
+  getGroupId?: (keys: GroupKey[]) => string;
+  /** 分组之间的排序；不传则保持各分组首次出现的顺序 */
+  sortGroups?: (a: GroupResult<T>, b: GroupResult<T>) => number;
+  /** 分组内数据项的排序；不传则保持原始相对顺序 */
+  sortItems?: (a: T, b: T) => number;
+}
+/**
+ * 按点路径安全取值
+ * @param obj - 取值对象
+ * @param path - 字段路径，支持 `'a.b.c'`
+ * @returns 路径对应的值，路径不存在时返回 undefined
+ * @example
+ * getByPath({ a: { b: 1 } }, 'a.b') // 1
+ * getByPath({ id: 9 }, 'id') // 9
+ */
+declare const getByPath: (obj: unknown, path: string) => unknown;
+/**
+ * 将数组按指定条件分组
+ * @template T - 数据项类型
+ * @param dataSource - 待分组的数据数组
+ * @param spec - 分组规则，详见 {@link GroupBySpec}
+ * @param options - 可选项（自定义 groupId、分组/组内排序）
+ * @returns 分组结果数组，默认保持各分组首次出现的顺序、组内保持原始相对顺序
+ * @description
+ * 该函数为纯函数，不修改入参（排序时对内部拷贝操作）。相同分组键的数据会被归入同一分组。
+ * @example
+ * // 单字段
+ * groupBy(list, 'productId');
+ * @example
+ * // 商品 + 时间组合
+ * groupBy(list, ['productId', 'time']);
+ * @example
+ * // 自定义键
+ * groupBy(list, (item) => `${item.productId}_${item.time}`);
+ */
+declare const groupBy: <T>(dataSource: T[], spec: GroupBySpec<T>, options?: GroupByOptions<T>) => GroupResult<T>[];
+//#endregion
+export { GroupByOptions, GroupBySpec, GroupKey, GroupResult, getByPath, groupBy, uniqueByKey };

package/lib/arrayUtils.js

@@ -1,40 +1,105 @@
-var __defProp = Object.defineProperty;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __export = (target, all) => {
-  for (var name in all)
-    __defProp(target, name, { get: all[name], enumerable: true });
+//#region src/arrayUtils.ts
+const uniqueByKey = (arr, key) => {
+	const seen = /* @__PURE__ */ new Set();
+	const result = [];
+	for (const item of arr) {
+		const keyValue = item[key];
+		if (!seen.has(keyValue)) {
+			seen.add(keyValue);
+			result.push(item);
+		}
+	}
+	return result;
 };
-var __copyProps = (to, from, except, desc) => {
-  if (from && typeof from === "object" || typeof from === "function") {
-    for (let key of __getOwnPropNames(from))
-      if (!__hasOwnProp.call(to, key) && key !== except)
-        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
-  }
-  return to;
+/**
+* 按点路径安全取值
+* @param obj - 取值对象
+* @param path - 字段路径，支持 `'a.b.c'`
+* @returns 路径对应的值，路径不存在时返回 undefined
+* @example
+* getByPath({ a: { b: 1 } }, 'a.b') // 1
+* getByPath({ id: 9 }, 'id') // 9
+*/
+const getByPath = (obj, path) => {
+	if (obj === null || obj === void 0) return;
+	if (path.indexOf(".") === -1) return obj[path];
+	return path.split(".").reduce((acc, key) => {
+		if (acc === null || acc === void 0) return;
+		return acc[key];
+	}, obj);
 };
-var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
-
-// src/arrayUtils.ts
-var arrayUtils_exports = {};
-__export(arrayUtils_exports, {
-  uniqueByKey: () => uniqueByKey
-});
-module.exports = __toCommonJS(arrayUtils_exports);
-var uniqueByKey = (arr, key) => {
-  const seen = /* @__PURE__ */ new Set();
-  const result = [];
-  for (const item of arr) {
-    const keyValue = item[key];
-    if (!seen.has(keyValue)) {
-      seen.add(keyValue);
-      result.push(item);
-    }
-  }
-  return result;
+/**
+* 将任意值规范化为可用于分组的标量键
+* @description null/undefined 统一归一为空字符串，对象/数组等转为字符串，避免分组键不稳定
+*/
+const normalizeGroupKey = (value) => {
+	if (value === null || value === void 0) return "";
+	if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") return value;
+	return String(value);
 };
-// Annotate the CommonJS export names for ESM import in node:
-0 && (module.exports = {
-  uniqueByKey
-});
+/**
+* 将数组按指定条件分组
+* @template T - 数据项类型
+* @param dataSource - 待分组的数据数组
+* @param spec - 分组规则，详见 {@link GroupBySpec}
+* @param options - 可选项（自定义 groupId、分组/组内排序）
+* @returns 分组结果数组，默认保持各分组首次出现的顺序、组内保持原始相对顺序
+* @description
+* 该函数为纯函数，不修改入参（排序时对内部拷贝操作）。相同分组键的数据会被归入同一分组。
+* @example
+* // 单字段
+* groupBy(list, 'productId');
+* @example
+* // 商品 + 时间组合
+* groupBy(list, ['productId', 'time']);
+* @example
+* // 自定义键
+* groupBy(list, (item) => `${item.productId}_${item.time}`);
+*/
+const groupBy = (dataSource, spec, options = {}) => {
+	const { getGroupId, sortGroups, sortItems } = options;
+	const fieldNames = Array.isArray(spec) ? spec : typeof spec === "string" ? [spec] : [];
+	const groupMap = /* @__PURE__ */ new Map();
+	const order = [];
+	(dataSource || []).forEach((item, index) => {
+		let keys;
+		if (typeof spec === "function") {
+			const result = spec(item, index);
+			keys = (Array.isArray(result) ? result : [result]).map(normalizeGroupKey);
+		} else if (Array.isArray(spec)) keys = spec.map((field) => normalizeGroupKey(getByPath(item, field)));
+		else keys = [normalizeGroupKey(getByPath(item, spec))];
+		const groupId = getGroupId ? getGroupId(keys) : keys.join("|");
+		let group = groupMap.get(groupId);
+		if (!group) {
+			const keyMap = {};
+			fieldNames.forEach((field, i) => {
+				keyMap[field] = keys[i];
+			});
+			group = {
+				groupId,
+				keys,
+				keyMap,
+				items: [],
+				index: order.length
+			};
+			groupMap.set(groupId, group);
+			order.push(groupId);
+		}
+		group.items.push(item);
+	});
+	let groups = order.map((id) => groupMap.get(id));
+	if (sortItems) groups.forEach((group) => {
+		group.items.sort(sortItems);
+	});
+	if (sortGroups) {
+		groups = groups.slice().sort(sortGroups);
+		groups.forEach((group, i) => {
+			group.index = i;
+		});
+	}
+	return groups;
+};
+//#endregion
+exports.getByPath = getByPath;
+exports.groupBy = groupBy;
+exports.uniqueByKey = uniqueByKey;

package/lib/common/stateHelper.d.ts

@@ -0,0 +1,22 @@
+import { DisplayState } from "./types.js";
+
+//#region src/common/stateHelper.d.ts
+/**
+ * 根据 mode 和 disabled 计算组件的显示状态
+ *
+ * 状态优先级：disabled > mode
+ * 当 disabled=true 时，无论 mode 是什么，都显示为禁用态
+ *
+ * @param mode 状态模式（'read' | 'edit'）
+ * @param disabled 是否禁用
+ * @returns 显示状态（'read' | 'edit' | 'disabled'）
+ *
+ * @example
+ * getDisplayState('edit', false) // 'edit'
+ * getDisplayState('read', false) // 'read'
+ * getDisplayState('edit', true)  // 'disabled'
+ * getDisplayState('read', true)  // 'disabled'
+ */
+declare function getDisplayState(mode?: 'read' | 'edit', disabled?: boolean): DisplayState;
+//#endregion
+export { getDisplayState };

package/lib/common/stateHelper.js

@@ -0,0 +1,23 @@
+//#region src/common/stateHelper.ts
+/**
+* 根据 mode 和 disabled 计算组件的显示状态
+* 
+* 状态优先级：disabled > mode
+* 当 disabled=true 时，无论 mode 是什么，都显示为禁用态
+* 
+* @param mode 状态模式（'read' | 'edit'）
+* @param disabled 是否禁用
+* @returns 显示状态（'read' | 'edit' | 'disabled'）
+* 
+* @example
+* getDisplayState('edit', false) // 'edit'
+* getDisplayState('read', false) // 'read'
+* getDisplayState('edit', true)  // 'disabled'
+* getDisplayState('read', true)  // 'disabled'
+*/
+function getDisplayState(mode, disabled) {
+	if (disabled) return "disabled";
+	return mode || "edit";
+}
+//#endregion
+exports.getDisplayState = getDisplayState;

package/lib/common/types.d.ts

@@ -0,0 +1,31 @@
+//#region src/common/types.d.ts
+/**
+ * 公共类型定义
+ * 供所有输入组件使用
+ */
+/**
+ * 显示状态类型
+ *
+ * 所有输入组件的三种状态：
+ * - read: 只读态，纯文本展示
+ * - edit: 编辑态，显示输入控件
+ * - disabled: 禁用态，禁用的输入控件
+ */
+type DisplayState = 'read' | 'edit' | 'disabled';
+/**
+ * 校验结果类型
+ *
+ * 所有输入组件的校验结果统一格式
+ */
+interface ValidationResult {
+  /**
+   * 是否校验通过
+   */
+  isValid: boolean;
+  /**
+   * 错误信息数组
+   */
+  errors: string[];
+}
+//#endregion
+export { DisplayState, ValidationResult };

package/lib/componentStorage.d.ts

@@ -0,0 +1,38 @@
+//#region src/componentStorage.d.ts
+/** 生成存储 key 的路径后缀：pathname 或 pathname#memory_key（来自 URL memory_key 参数） */
+declare function getStorageKeySuffix(): string;
+/**
+ * 生成组件实例的存储 key。
+ * @param componentId 组件实例 id（如 __id）
+ * @param prefix 前缀，如 'table-setting'、'record-board-column-visibility'
+ */
+declare function getComponentStorageKey(componentId: string, prefix: string): string;
+interface ColumnSettingStorageItem {
+  key: string;
+  dataIndex: string;
+  title?: unknown;
+  titleString?: string;
+  isShow: boolean;
+  sortIndex?: number;
+  fixed?: 'left' | 'right' | boolean;
+}
+declare function saveColumnSettingToLocal(params: {
+  componentId: string;
+  columnSetting: ColumnSettingStorageItem[];
+}): void;
+declare function getColumnSettingFromLocal(componentId?: string): ColumnSettingStorageItem[] | null;
+declare function clearColumnSettingFromLocal(componentId?: string): void;
+declare function saveColumnVisibilityToLocal(params: {
+  componentId: string;
+  columnVisibility: Record<string, boolean>; /** 列 key 顺序，用于列设置弹层拖拽排序后持久化 */
+  columnOrder?: string[];
+}): void;
+declare function getColumnVisibilityFromLocal(componentId?: string): Record<string, boolean> | null;
+/** RecordBoard 列设置（显隐 + 顺序）从 localStorage 读取，用于列设置弹层拖拽排序与显隐持久化 */
+declare function getRecordBoardColumnSettingFromLocal(componentId?: string): {
+  columnVisibility: Record<string, boolean>;
+  columnOrder: string[] | null;
+} | null;
+declare function clearColumnVisibilityFromLocal(componentId?: string): void;
+//#endregion
+export { ColumnSettingStorageItem, clearColumnSettingFromLocal, clearColumnVisibilityFromLocal, getColumnSettingFromLocal, getColumnVisibilityFromLocal, getComponentStorageKey, getRecordBoardColumnSettingFromLocal, getStorageKeySuffix, saveColumnSettingToLocal, saveColumnVisibilityToLocal };