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

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

@@ -0,0 +1,36 @@
+/**
+ * 按语言比较与匹配文字（Intl.Collator）：Combobox 的过滤、表格的排序与筛选共用。
+ * Collator 按语言缓存，重复调用不再新建。
+ *
+ *   const match = createMatcher('zh-CN');  match('Ångström', 'ang') → true（忽略大小写与重音）
+ *   rows.sort(createComparer('zh-CN'))     数字按大小、日期按时间、文字按语言的排序规则（中文按拼音）
+ *   sortByValue(rows, (row) => row.amount, 'descending', 'zh-CN')   按取出的值排，空值总在最后（表格、接口的排序）
+ */
+import type { DateValue } from '@internationalized/date';
+import type Decimal from 'decimal.js';
+/** 判断 text 是否包含 query：忽略大小写与重音（é 与 e、Å 与 a 视为相同）；query 为空时总是 true */
+export declare function createMatcher(locale: string): (text: string, query: string) => boolean;
+/** 可以排序的值：表格列的 value 返回它 */
+export type SortValue = string | number | bigint | Decimal | boolean | Date | DateValue | null | undefined;
+/** @internationalized/date 的日期值（CalendarDate、CalendarDateTime、ZonedDateTime）：不在运行时导入，按形状识别 */
+export declare const isDateValue: (value: unknown) => value is DateValue;
+/**
+ * 比较两个值，给排序用：null / undefined 排在最后；number、bigint、Decimal 按大小（混着也行，不丢精度）；
+ * Date 按时间，DateValue 按它自己的 compare（不经过时区换算）；布尔 false 在前；
+ * 文字按语言比较（“第2章”排在“第10章”前）
+ */
+export declare function createComparer(locale: string): (a: SortValue, b: SortValue) => number;
+/**
+ * 按每行取出的值排序（返回新数组，原数组不变）：比较用 createComparer，相等时保持原来的先后（稳定），
+ * 空值不随方向翻转、总在最后。表格的 sortRows、服务端（或假接口）的分页排序共用
+ */
+export declare function sortByValue<T>(rows: readonly T[], value: (row: T) => SortValue, direction: 'ascending' | 'descending', locale: string): T[];
+/** sortByValues 的一个排序键 */
+export interface SortKey<T> {
+    /** 每行取出的值 */
+    value: (row: T) => SortValue;
+    /** 方向 */
+    direction: 'ascending' | 'descending';
+}
+/** 按几个键排序（多列排序）：前一个键相等时比下一个，都相等时保持原来的先后；空值总在最后，同 sortByValue */
+export declare function sortByValues<T>(rows: readonly T[], keys: readonly SortKey<T>[], locale: string): T[];

package/dist/utils/data/collation.js

@@ -0,0 +1,69 @@
+import { cachedIntl } from "./intl-cache.js";
+import { compareNumeric, isNumeric } from "./numeric.js";
+//#region src/utils/data/collation.ts
+function collator(locale, usage) {
+	return cachedIntl(`collator|${locale}|${usage}`, () => new Intl.Collator(locale, {
+		usage,
+		sensitivity: "base",
+		numeric: true
+	}));
+}
+/** 判断 text 是否包含 query：忽略大小写与重音（é 与 e、Å 与 a 视为相同）；query 为空时总是 true */
+function createMatcher(locale) {
+	const compare = collator(locale, "search");
+	return (text, query) => {
+		if (!query) return true;
+		for (let start = 0; start + query.length <= text.length; start++) if (compare.compare(text.slice(start, start + query.length), query) === 0) return true;
+		return false;
+	};
+}
+/** @internationalized/date 的日期值（CalendarDate、CalendarDateTime、ZonedDateTime）：不在运行时导入，按形状识别 */
+var isDateValue = (value) => typeof value === "object" && value !== null && "calendar" in value && typeof value.compare === "function";
+/**
+* 比较两个值，给排序用：null / undefined 排在最后；number、bigint、Decimal 按大小（混着也行，不丢精度）；
+* Date 按时间，DateValue 按它自己的 compare（不经过时区换算）；布尔 false 在前；
+* 文字按语言比较（“第2章”排在“第10章”前）
+*/
+function createComparer(locale) {
+	const compare = collator(locale, "sort");
+	return (a, b) => {
+		if (a == null || b == null) return a == null ? b == null ? 0 : 1 : -1;
+		if (isNumeric(a) && isNumeric(b)) return compareNumeric(a, b);
+		if (a instanceof Date && b instanceof Date) return a.getTime() - b.getTime();
+		if (isDateValue(a) && isDateValue(b)) return a.compare(b);
+		if (typeof a === "boolean" && typeof b === "boolean") return Number(a) - Number(b);
+		return compare.compare(String(a), String(b));
+	};
+}
+/**
+* 按每行取出的值排序（返回新数组，原数组不变）：比较用 createComparer，相等时保持原来的先后（稳定），
+* 空值不随方向翻转、总在最后。表格的 sortRows、服务端（或假接口）的分页排序共用
+*/
+function sortByValue(rows, value, direction, locale) {
+	return sortByValues(rows, [{
+		value,
+		direction
+	}], locale);
+}
+/** 按几个键排序（多列排序）：前一个键相等时比下一个，都相等时保持原来的先后；空值总在最后，同 sortByValue */
+function sortByValues(rows, keys, locale) {
+	const compare = createComparer(locale);
+	const factors = keys.map((key) => key.direction === "ascending" ? 1 : -1);
+	return rows.map((row, index) => ({
+		row,
+		index,
+		values: keys.map((key) => key.value(row))
+	})).sort((a, b) => {
+		for (let at = 0; at < keys.length; at++) {
+			const x = a.values[at];
+			const y = b.values[at];
+			const order = x == null || y == null ? compare(x, y) : compare(x, y) * factors[at];
+			if (order) return order;
+		}
+		return a.index - b.index;
+	}).map((item) => item.row);
+}
+//#endregion
+export { createComparer, createMatcher, isDateValue, sortByValue, sortByValues };
+
+//# sourceMappingURL=collation.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"collation.js","names":[],"sources":["../../../src/utils/data/collation.ts"],"sourcesContent":["/**\n * 按语言比较与匹配文字（Intl.Collator）：Combobox 的过滤、表格的排序与筛选共用。\n * Collator 按语言缓存，重复调用不再新建。\n *\n *   const match = createMatcher('zh-CN');  match('Ångström', 'ang') → true（忽略大小写与重音）\n *   rows.sort(createComparer('zh-CN'))     数字按大小、日期按时间、文字按语言的排序规则（中文按拼音）\n *   sortByValue(rows, (row) => row.amount, 'descending', 'zh-CN')   按取出的值排，空值总在最后（表格、接口的排序）\n */\nimport type { DateValue } from '@internationalized/date';\nimport type Decimal from 'decimal.js';\nimport { cachedIntl } from './intl-cache';\nimport { compareNumeric, isNumeric } from './numeric';\n\nfunction collator(locale: string, usage: 'search' | 'sort'): Intl.Collator {\n  return cachedIntl(\n    `collator|${locale}|${usage}`,\n    () => new Intl.Collator(locale, { usage, sensitivity: 'base', numeric: true }),\n  );\n}\n\n/** 判断 text 是否包含 query：忽略大小写与重音（é 与 e、Å 与 a 视为相同）；query 为空时总是 true */\nexport function createMatcher(locale: string): (text: string, query: string) => boolean {\n  const compare = collator(locale, 'search');\n  return (text, query) => {\n    if (!query) return true;\n    // Collator 没有“包含”，逐个位置比较等长的片段\n    for (let start = 0; start + query.length <= text.length; start++) {\n      if (compare.compare(text.slice(start, start + query.length), query) === 0) return true;\n    }\n    return false;\n  };\n}\n\n/** 可以排序的值：表格列的 value 返回它 */\nexport type SortValue =\n  string | number | bigint | Decimal | boolean | Date | DateValue | null | undefined;\n\n/** @internationalized/date 的日期值（CalendarDate、CalendarDateTime、ZonedDateTime）：不在运行时导入，按形状识别 */\nexport const isDateValue = (value: unknown): value is DateValue =>\n  typeof value === 'object' &&\n  value !== null &&\n  'calendar' in value &&\n  typeof (value as DateValue).compare === 'function';\n\n/**\n * 比较两个值，给排序用：null / undefined 排在最后；number、bigint、Decimal 按大小（混着也行，不丢精度）；\n * Date 按时间，DateValue 按它自己的 compare（不经过时区换算）；布尔 false 在前；\n * 文字按语言比较（“第2章”排在“第10章”前）\n */\nexport function createComparer(locale: string): (a: SortValue, b: SortValue) => number {\n  const compare = collator(locale, 'sort');\n  return (a, b) => {\n    if (a == null || b == null) return a == null ? (b == null ? 0 : 1) : -1;\n    if (isNumeric(a) && isNumeric(b)) return compareNumeric(a, b);\n    if (a instanceof Date && b instanceof Date) return a.getTime() - b.getTime();\n    if (isDateValue(a) && isDateValue(b)) return a.compare(b);\n    if (typeof a === 'boolean' && typeof b === 'boolean') return Number(a) - Number(b);\n    return compare.compare(String(a), String(b));\n  };\n}\n\n/**\n * 按每行取出的值排序（返回新数组，原数组不变）：比较用 createComparer，相等时保持原来的先后（稳定），\n * 空值不随方向翻转、总在最后。表格的 sortRows、服务端（或假接口）的分页排序共用\n */\nexport function sortByValue<T>(\n  rows: readonly T[],\n  value: (row: T) => SortValue,\n  direction: 'ascending' | 'descending',\n  locale: string,\n): T[] {\n  return sortByValues(rows, [{ value, direction }], locale);\n}\n\n/** sortByValues 的一个排序键 */\nexport interface SortKey<T> {\n  /** 每行取出的值 */\n  value: (row: T) => SortValue;\n  /** 方向 */\n  direction: 'ascending' | 'descending';\n}\n\n/** 按几个键排序（多列排序）：前一个键相等时比下一个，都相等时保持原来的先后；空值总在最后，同 sortByValue */\nexport function sortByValues<T>(\n  rows: readonly T[],\n  keys: readonly SortKey<T>[],\n  locale: string,\n): T[] {\n  const compare = createComparer(locale);\n  const factors = keys.map((key) => (key.direction === 'ascending' ? 1 : -1));\n  return rows\n    .map((row, index) => ({ row, index, values: keys.map((key) => key.value(row)) }))\n    .sort((a, b) => {\n      for (let at = 0; at < keys.length; at++) {\n        const x = a.values[at];\n        const y = b.values[at];\n        const order = x == null || y == null ? compare(x, y) : compare(x, y) * factors[at]!;\n        if (order) return order;\n      }\n      return a.index - b.index;\n    })\n    .map((item) => item.row);\n}\n"],"mappings":";;;AAaA,SAAS,SAAS,QAAgB,OAAyC;CACzE,OAAO,WACL,YAAY,OAAO,GAAG,eAChB,IAAI,KAAK,SAAS,QAAQ;EAAE;EAAO,aAAa;EAAQ,SAAS;CAAK,CAAC,CAC/E;AACF;;AAGA,SAAgB,cAAc,QAA0D;CACtF,MAAM,UAAU,SAAS,QAAQ,QAAQ;CACzC,QAAQ,MAAM,UAAU;EACtB,IAAI,CAAC,OAAO,OAAO;EAEnB,KAAK,IAAI,QAAQ,GAAG,QAAQ,MAAM,UAAU,KAAK,QAAQ,SACvD,IAAI,QAAQ,QAAQ,KAAK,MAAM,OAAO,QAAQ,MAAM,MAAM,GAAG,KAAK,MAAM,GAAG,OAAO;EAEpF,OAAO;CACT;AACF;;AAOA,IAAa,eAAe,UAC1B,OAAO,UAAU,YACjB,UAAU,QACV,cAAc,SACd,OAAQ,MAAoB,YAAY;;;;;;AAO1C,SAAgB,eAAe,QAAwD;CACrF,MAAM,UAAU,SAAS,QAAQ,MAAM;CACvC,QAAQ,GAAG,MAAM;EACf,IAAI,KAAK,QAAQ,KAAK,MAAM,OAAO,KAAK,OAAQ,KAAK,OAAO,IAAI,IAAK;EACrE,IAAI,UAAU,CAAC,KAAK,UAAU,CAAC,GAAG,OAAO,eAAe,GAAG,CAAC;EAC5D,IAAI,aAAa,QAAQ,aAAa,MAAM,OAAO,EAAE,QAAQ,IAAI,EAAE,QAAQ;EAC3E,IAAI,YAAY,CAAC,KAAK,YAAY,CAAC,GAAG,OAAO,EAAE,QAAQ,CAAC;EACxD,IAAI,OAAO,MAAM,aAAa,OAAO,MAAM,WAAW,OAAO,OAAO,CAAC,IAAI,OAAO,CAAC;EACjF,OAAO,QAAQ,QAAQ,OAAO,CAAC,GAAG,OAAO,CAAC,CAAC;CAC7C;AACF;;;;;AAMA,SAAgB,YACd,MACA,OACA,WACA,QACK;CACL,OAAO,aAAa,MAAM,CAAC;EAAE;EAAO;CAAU,CAAC,GAAG,MAAM;AAC1D;;AAWA,SAAgB,aACd,MACA,MACA,QACK;CACL,MAAM,UAAU,eAAe,MAAM;CACrC,MAAM,UAAU,KAAK,KAAK,QAAS,IAAI,cAAc,cAAc,IAAI,EAAG;CAC1E,OAAO,KACJ,KAAK,KAAK,WAAW;EAAE;EAAK;EAAO,QAAQ,KAAK,KAAK,QAAQ,IAAI,MAAM,GAAG,CAAC;CAAE,EAAE,CAAC,CAChF,MAAM,GAAG,MAAM;EACd,KAAK,IAAI,KAAK,GAAG,KAAK,KAAK,QAAQ,MAAM;GACvC,MAAM,IAAI,EAAE,OAAO;GACnB,MAAM,IAAI,EAAE,OAAO;GACnB,MAAM,QAAQ,KAAK,QAAQ,KAAK,OAAO,QAAQ,GAAG,CAAC,IAAI,QAAQ,GAAG,CAAC,IAAI,QAAQ;GAC/E,IAAI,OAAO,OAAO;EACpB;EACA,OAAO,EAAE,QAAQ,EAAE;CACrB,CAAC,CAAC,CACD,KAAK,SAAS,KAAK,GAAG;AAC3B"}

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

@@ -0,0 +1,32 @@
+/**
+ * 颜色工具（culori）：解析、格式化、半透明颜色的叠加、WCAG 对比度、按对比度挑文字色。
+ * 主题编辑器的实时对比度提示与 pnpm themes:check 用的是同一套计算。
+ *
+ *   contrastRatio('#3e63dd', '#ffffff')            → 4.6
+ *   contrastRatio('rgba(0,0,0,0.5)', '#fff')       半透明前景先叠到背景上再算
+ *   readableText('#ffc53d')                        → 深色文字（亮黄底上白字达不到 4.5:1）
+ */
+import { type Rgb } from 'culori/fn';
+/** WCAG 2.2 AA 的对比度要求 */
+export declare const CONTRAST_AA: {
+    /** 正文文字 */
+    readonly text: 4.5;
+    /** 大字、图形与界面部件（焦点环、勾选框边框） */
+    readonly ui: 3;
+};
+/** 解析 CSS 颜色（#hex、rgb() / rgba()、颜色名）；解析不了时返回 undefined */
+export declare function parseColor(value: string): Rgb | undefined;
+/** 格式化成 #rrggbb；有透明度时是 #rrggbbaa。解析不了时返回 undefined */
+export declare function toHex(value: string): string | undefined;
+/**
+ * 前景与背景的 WCAG 对比度（1–21）。半透明的颜色按实际看到的算：背景先叠到页面底色（page）上，
+ * 前景再叠到背景上。颜色解析不了时抛错
+ */
+export declare function contrastRatio(foreground: string, background: string, page?: string): number;
+/**
+ * 实色背景上的文字色（实色按钮上用白字还是深色字）：按候选的顺序，第一个达到正文对比度（4.5:1）的就用它；
+ * 都达不到时取对比度最高的
+ */
+export declare function readableText(background: string, candidates?: readonly string[]): string;
+/** 同一个颜色换成给定的不透明度（0–1），输出 rgba()；解析不了时抛错 */
+export declare function withAlpha(value: string, alpha: number): string;

package/dist/utils/data/color.js

@@ -0,0 +1,90 @@
+import { converter, formatHex, formatHex8, formatRgb, modeLrgb, modeRgb, parse, useMode, wcagLuminance } from "culori/fn";
+//#region src/utils/data/color.ts
+/**
+* 颜色工具（culori）：解析、格式化、半透明颜色的叠加、WCAG 对比度、按对比度挑文字色。
+* 主题编辑器的实时对比度提示与 pnpm themes:check 用的是同一套计算。
+*
+*   contrastRatio('#3e63dd', '#ffffff')            → 4.6
+*   contrastRatio('rgba(0,0,0,0.5)', '#fff')       半透明前景先叠到背景上再算
+*   readableText('#ffc53d')                        → 深色文字（亮黄底上白字达不到 4.5:1）
+*/
+useMode(modeRgb);
+useMode(modeLrgb);
+var toRgb = converter("rgb");
+/** WCAG 2.2 AA 的对比度要求 */
+var CONTRAST_AA = {
+	/** 正文文字 */
+	text: 4.5,
+	/** 大字、图形与界面部件（焦点环、勾选框边框） */
+	ui: 3
+};
+/** 解析 CSS 颜色（#hex、rgb() / rgba()、颜色名）；解析不了时返回 undefined */
+function parseColor(value) {
+	const color = parse(value.trim());
+	return color && toRgb(color);
+}
+/** 格式化成 #rrggbb；有透明度时是 #rrggbbaa。解析不了时返回 undefined */
+function toHex(value) {
+	const color = parseColor(value);
+	if (!color) return void 0;
+	return (color.alpha ?? 1) < 1 ? formatHex8(color) : formatHex(color);
+}
+/** 半透明的前景叠到不透明的背景上，得到人眼看到的颜色 */
+function over(foreground, background) {
+	const alpha = foreground.alpha ?? 1;
+	return {
+		mode: "rgb",
+		r: foreground.r * alpha + background.r * (1 - alpha),
+		g: foreground.g * alpha + background.g * (1 - alpha),
+		b: foreground.b * alpha + background.b * (1 - alpha)
+	};
+}
+/**
+* 前景与背景的 WCAG 对比度（1–21）。半透明的颜色按实际看到的算：背景先叠到页面底色（page）上，
+* 前景再叠到背景上。颜色解析不了时抛错
+*/
+function contrastRatio(foreground, background, page = "#ffffff") {
+	const [fg, bg, base] = [
+		foreground,
+		background,
+		page
+	].map((value) => {
+		const color = parseColor(value);
+		if (!color) throw new Error(`无法解析的颜色：${value}`);
+		return color;
+	});
+	const solidBackground = over(bg, {
+		...base,
+		alpha: 1
+	});
+	const solidForeground = over(fg, solidBackground);
+	const [high, low] = [wcagLuminance(solidForeground), wcagLuminance(solidBackground)].sort((a, b) => b - a);
+	return (high + .05) / (low + .05);
+}
+/**
+* 实色背景上的文字色（实色按钮上用白字还是深色字）：按候选的顺序，第一个达到正文对比度（4.5:1）的就用它；
+* 都达不到时取对比度最高的
+*/
+function readableText(background, candidates = ["#ffffff", "#1c2024"]) {
+	let best = candidates[0];
+	let bestRatio = 0;
+	for (const candidate of candidates) {
+		const ratio = contrastRatio(candidate, background);
+		if (ratio >= CONTRAST_AA.text) return candidate;
+		if (ratio > bestRatio) [best, bestRatio] = [candidate, ratio];
+	}
+	return best;
+}
+/** 同一个颜色换成给定的不透明度（0–1），输出 rgba()；解析不了时抛错 */
+function withAlpha(value, alpha) {
+	const color = parseColor(value);
+	if (!color) throw new Error(`无法解析的颜色：${value}`);
+	return formatRgb({
+		...color,
+		alpha
+	});
+}
+//#endregion
+export { CONTRAST_AA, contrastRatio, parseColor, readableText, toHex, withAlpha };
+
+//# sourceMappingURL=color.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"color.js","names":[],"sources":["../../../src/utils/data/color.ts"],"sourcesContent":["/**\n * 颜色工具（culori）：解析、格式化、半透明颜色的叠加、WCAG 对比度、按对比度挑文字色。\n * 主题编辑器的实时对比度提示与 pnpm themes:check 用的是同一套计算。\n *\n *   contrastRatio('#3e63dd', '#ffffff')            → 4.6\n *   contrastRatio('rgba(0,0,0,0.5)', '#fff')       半透明前景先叠到背景上再算\n *   readableText('#ffc53d')                        → 深色文字（亮黄底上白字达不到 4.5:1）\n */\nimport {\n  converter,\n  formatHex,\n  formatHex8,\n  formatRgb,\n  modeLrgb,\n  modeRgb,\n  parse,\n  useMode,\n  wcagLuminance,\n  type Rgb,\n} from 'culori/fn';\n\n// culori/fn 按需注册颜色空间：sRGB（解析 #hex、rgb()、颜色名）与线性 RGB（算相对亮度）\nuseMode(modeRgb);\nuseMode(modeLrgb);\nconst toRgb = converter('rgb');\n\n/** WCAG 2.2 AA 的对比度要求 */\nexport const CONTRAST_AA = {\n  /** 正文文字 */\n  text: 4.5,\n  /** 大字、图形与界面部件（焦点环、勾选框边框） */\n  ui: 3,\n} as const;\n\n/** 解析 CSS 颜色（#hex、rgb() / rgba()、颜色名）；解析不了时返回 undefined */\nexport function parseColor(value: string): Rgb | undefined {\n  const color = parse(value.trim());\n  return color && toRgb(color);\n}\n\n/** 格式化成 #rrggbb；有透明度时是 #rrggbbaa。解析不了时返回 undefined */\nexport function toHex(value: string): string | undefined {\n  const color = parseColor(value);\n  if (!color) return undefined;\n  return (color.alpha ?? 1) < 1 ? formatHex8(color) : formatHex(color);\n}\n\n/** 半透明的前景叠到不透明的背景上，得到人眼看到的颜色 */\nfunction over(foreground: Rgb, background: Rgb): Rgb {\n  const alpha = foreground.alpha ?? 1;\n  return {\n    mode: 'rgb',\n    r: foreground.r * alpha + background.r * (1 - alpha),\n    g: foreground.g * alpha + background.g * (1 - alpha),\n    b: foreground.b * alpha + background.b * (1 - alpha),\n  };\n}\n\n/**\n * 前景与背景的 WCAG 对比度（1–21）。半透明的颜色按实际看到的算：背景先叠到页面底色（page）上，\n * 前景再叠到背景上。颜色解析不了时抛错\n */\nexport function contrastRatio(foreground: string, background: string, page = '#ffffff'): number {\n  const [fg, bg, base] = [foreground, background, page].map((value) => {\n    const color = parseColor(value);\n    if (!color) throw new Error(`无法解析的颜色：${value}`);\n    return color;\n  }) as [Rgb, Rgb, Rgb];\n  const solidBackground = over(bg, { ...base, alpha: 1 });\n  const solidForeground = over(fg, solidBackground);\n  const [high, low] = [wcagLuminance(solidForeground), wcagLuminance(solidBackground)].sort(\n    (a, b) => b - a,\n  ) as [number, number];\n  return (high + 0.05) / (low + 0.05);\n}\n\n/**\n * 实色背景上的文字色（实色按钮上用白字还是深色字）：按候选的顺序，第一个达到正文对比度（4.5:1）的就用它；\n * 都达不到时取对比度最高的\n */\nexport function readableText(\n  background: string,\n  candidates: readonly string[] = ['#ffffff', '#1c2024'],\n): string {\n  let best = candidates[0]!;\n  let bestRatio = 0;\n  for (const candidate of candidates) {\n    const ratio = contrastRatio(candidate, background);\n    if (ratio >= CONTRAST_AA.text) return candidate;\n    if (ratio > bestRatio) [best, bestRatio] = [candidate, ratio];\n  }\n  return best;\n}\n\n/** 同一个颜色换成给定的不透明度（0–1），输出 rgba()；解析不了时抛错 */\nexport function withAlpha(value: string, alpha: number): string {\n  const color = parseColor(value);\n  if (!color) throw new Error(`无法解析的颜色：${value}`);\n  return formatRgb({ ...color, alpha });\n}\n"],"mappings":";;;;;;;;;;AAsBA,QAAQ,OAAO;AACf,QAAQ,QAAQ;AAChB,IAAM,QAAQ,UAAU,KAAK;;AAG7B,IAAa,cAAc;;CAEzB,MAAM;;CAEN,IAAI;AACN;;AAGA,SAAgB,WAAW,OAAgC;CACzD,MAAM,QAAQ,MAAM,MAAM,KAAK,CAAC;CAChC,OAAO,SAAS,MAAM,KAAK;AAC7B;;AAGA,SAAgB,MAAM,OAAmC;CACvD,MAAM,QAAQ,WAAW,KAAK;CAC9B,IAAI,CAAC,OAAO,OAAO,KAAA;CACnB,QAAQ,MAAM,SAAS,KAAK,IAAI,WAAW,KAAK,IAAI,UAAU,KAAK;AACrE;;AAGA,SAAS,KAAK,YAAiB,YAAsB;CACnD,MAAM,QAAQ,WAAW,SAAS;CAClC,OAAO;EACL,MAAM;EACN,GAAG,WAAW,IAAI,QAAQ,WAAW,KAAK,IAAI;EAC9C,GAAG,WAAW,IAAI,QAAQ,WAAW,KAAK,IAAI;EAC9C,GAAG,WAAW,IAAI,QAAQ,WAAW,KAAK,IAAI;CAChD;AACF;;;;;AAMA,SAAgB,cAAc,YAAoB,YAAoB,OAAO,WAAmB;CAC9F,MAAM,CAAC,IAAI,IAAI,QAAQ;EAAC;EAAY;EAAY;CAAI,CAAC,CAAC,KAAK,UAAU;EACnE,MAAM,QAAQ,WAAW,KAAK;EAC9B,IAAI,CAAC,OAAO,MAAM,IAAI,MAAM,WAAW,OAAO;EAC9C,OAAO;CACT,CAAC;CACD,MAAM,kBAAkB,KAAK,IAAI;EAAE,GAAG;EAAM,OAAO;CAAE,CAAC;CACtD,MAAM,kBAAkB,KAAK,IAAI,eAAe;CAChD,MAAM,CAAC,MAAM,OAAO,CAAC,cAAc,eAAe,GAAG,cAAc,eAAe,CAAC,CAAC,CAAC,MAClF,GAAG,MAAM,IAAI,CAChB;CACA,QAAQ,OAAO,QAAS,MAAM;AAChC;;;;;AAMA,SAAgB,aACd,YACA,aAAgC,CAAC,WAAW,SAAS,GAC7C;CACR,IAAI,OAAO,WAAW;CACtB,IAAI,YAAY;CAChB,KAAK,MAAM,aAAa,YAAY;EAClC,MAAM,QAAQ,cAAc,WAAW,UAAU;EACjD,IAAI,SAAS,YAAY,MAAM,OAAO;EACtC,IAAI,QAAQ,WAAW,CAAC,MAAM,aAAa,CAAC,WAAW,KAAK;CAC9D;CACA,OAAO;AACT;;AAGA,SAAgB,UAAU,OAAe,OAAuB;CAC9D,MAAM,QAAQ,WAAW,KAAK;CAC9B,IAAI,CAAC,OAAO,MAAM,IAAI,MAAM,WAAW,OAAO;CAC9C,OAAO,UAAU;EAAE,GAAG;EAAO;CAAM,CAAC;AACtC"}

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

@@ -0,0 +1,196 @@
+/**
+ * 日期运算（不含界面）：ISO 字符串互转、月份网格、星期名与月份名、可选范围、区间、周数、快捷区间。
+ * Calendar、DateField、各种日期选择器共用；运算交给 @internationalized/date（时区、地区的周起始日、非公历）。
+ *
+ * 组件对外的值是 ISO 8601 字符串（'2026-10-20'、'14:30'、'2026-10-20T14:30'），与原生 input、URL 参数、
+ * zod 的 z.iso.date() 一致；组件内部换成 CalendarDate 等对象运算。月份名、星期名一律取自 Intl。
+ * 出错的约定：parseXxx 解析不了时返回 null（输入框里的半截内容是常态）；shiftIsoDate、daysBetween 这类运算
+ * 要求合法的 ISO 字符串，不合法时抛 RangeError 并带上原值（多半是调用方的数据错了，不该悄悄算出别的日子）。
+ *
+ *   monthGrid(new CalendarDate(2026, 10, 1), { locale: 'zh-CN' })  → 6 行 × 7 天，补齐上下月
+ *   weekdayNames('en-US', { format: 'short' })                      → ['Sun', 'Mon', …]
+ */
+import { CalendarDate, CalendarDateTime, Time, type Calendar, type DateDuration, type DateValue, type DayOfWeek } from '@internationalized/date';
+/** 'YYYY-MM-DD' → CalendarDate（公历）；空值或格式不对时为 null */
+export declare function parseIsoDate(value: string | null | undefined): CalendarDate | null;
+/** 'HH:mm' 或 'HH:mm:ss' → Time；空值或格式不对时为 null */
+export declare function parseIsoTime(value: string | null | undefined): Time | null;
+/**
+ * 补成完整的 ISO 日期（这一段的第一天）：'2026' 与 '2026-10' 补成 1 日，'2026-Q4' 是 10 月 1 日，
+ * '2026-W43' 是那一周的周一，日期时间取日期部分（DateField、各种日期选择器的粒度）
+ */
+export declare function fullIsoDay(iso: string): string;
+/** 这一段的最后一天：'2026' 是 12 月 31 日，'2026-10' 是 31 日，'2026-Q4' 是 12 月 31 日，'2026-W43' 是那周的周日 */
+export declare function lastIsoDay(iso: string): string;
+/** 日期所在的季度：'2026-Q4' */
+export declare function toIsoQuarter(date: DateValue): string;
+/** ISO 8601 的周（周一开始，含 1 月 4 日的那周是第 1 周，跨年的周归周四所在的年）：所属的年与第几周 */
+export declare function isoWeekOf(date: DateValue): {
+    year: number;
+    week: number;
+};
+/** 日期所在的 ISO 周：'2026-W43'（同原生 input type="week"） */
+export declare function toIsoWeek(date: DateValue): string;
+/** 一年有几个 ISO 周（52 或 53）：12 月 28 日总在最后一周里 */
+export declare const isoWeeksInYear: (year: number) => number;
+/** 'YYYY-MM-DDTHH:mm[:ss]' → CalendarDateTime（公历）；空值或格式不对时为 null */
+export declare function parseIsoDateTime(value: string | null | undefined): CalendarDateTime | null;
+/** 日期 → 'YYYY-MM-DD'；不是公历的日期先换回公历 */
+export declare function toIsoDate(date: DateValue): string;
+/** 时间 → 'HH:mm'；withSeconds 时 'HH:mm:ss'（同原生 input type="time"） */
+export declare function toIsoTime(time: Time, withSeconds?: boolean): string;
+/** 日期时间 → 'YYYY-MM-DDTHH:mm'；withSeconds 时带秒（同原生 input type="datetime-local"） */
+export declare function toIsoDateTime(value: CalendarDateTime, withSeconds?: boolean): string;
+/** 今天的 ISO 日期，按时区（不写时取浏览器的）：`todayIso()` → '2026-10-20' */
+export declare function todayIso(timeZone?: string): string;
+/** ISO 日期加减（月末自动夹到下个月的最后一天）：`shiftIsoDate('2026-01-31', { months: 1 })` → '2026-02-28' */
+export declare function shiftIsoDate(value: string, duration: DateDuration): string;
+/** 从 a 到 b 相隔几天（b 在后为正）：`daysBetween('2026-10-20', '2026-10-23')` → 3 */
+export declare function daysBetween(a: string, b: string): number;
+/**
+ * ISO 日期是星期几：0 周日 … 6 周六（同 Date#getDay）。直接按日期算，不受时区影响；
+ * `new Date('2026-10-20').getDay()` 在 UTC 以西的时区会算成前一天
+ */
+export declare function isoDayOfWeek(value: string): number;
+/**
+ * 语言里的日历标识 → 运算用的日历；@internationalized/date 不支持的（如农历 'chinese'）退回公历，
+ * 月份网格仍按公历排，显示的文字照常由 Intl 按该日历格式化
+ */
+export declare function calendarOf(identifier: string): Calendar;
+/** 语言配置的一周第一天（0 表示周日）→ @internationalized/date 的写法；不写时按地区惯例 */
+export declare function toDayOfWeek(firstDayOfWeek: number | undefined): DayOfWeek | undefined;
+/** 一周的排法：语言与一周第一天（0 表示周日，不写时按地区惯例） */
+export interface WeekOptions {
+    /** BCP 47 语言标签 */
+    locale: string;
+    /** 一周的第一天，0 表示周日；不写时按地区惯例（zh-CN 周一，en-US 周日） */
+    firstDayOfWeek?: number;
+}
+/** monthGrid 的选项 */
+export interface MonthGridOptions extends WeekOptions {
+    /** 总是 6 行：几个月并排、或翻页时高度不跳，默认 true */
+    fixedWeeks?: boolean;
+}
+/** 一个月的日期网格：按周分行，首尾用上个月、下个月的日期补齐（同 React Aria 的 getDatesInWeek） */
+export declare function monthGrid(month: CalendarDate, { locale, firstDayOfWeek, fixedWeeks }: MonthGridOptions): CalendarDate[][];
+/** 星期名的长短 */
+export interface WeekdayFormats {
+    /** 最短：一、二 / S、M */
+    narrow: unknown;
+    /** 简写：周一 / Mon */
+    short: unknown;
+    /** 全称：星期一 / Monday */
+    long: unknown;
+}
+/** 按一周的排法列出七天的星期名（取自 Intl），从一周第一天开始 */
+export declare function weekdayNames(locale: string, { firstDayOfWeek, format, }?: {
+    firstDayOfWeek?: number;
+    format?: keyof WeekdayFormats;
+}): string[];
+/** 一年的各月（每月 1 日），按日期所在的日历系统（个别日历一年有 13 个月） */
+export declare function monthsOfYear(date: CalendarDate): CalendarDate[];
+/** 年份视图的一页：所在的十年，前后各补一年（共 12 年，排成 4 × 3；同 Ant Design 的年份面板） */
+export declare function yearsOfDecade(date: CalendarDate): CalendarDate[];
+/** 是不是十年之外、补上的那两年 */
+export declare const isOutsideDecade: (year: CalendarDate, page: CalendarDate) => boolean;
+/**
+ * 一年里的第几周：一周从周一开始时按 ISO 8601（含 1 月 4 日的那周是第 1 周），
+ * 其他（周日、周六开始）按含 1 月 1 日的那周是第 1 周（美国、日本的惯例）
+ */
+export declare function weekOfYear(date: CalendarDate, options: WeekOptions): number;
+/** 比较的粒度：日历的三种视图 */
+export interface DateUnits {
+    /** 天 */
+    day: unknown;
+    /** 月 */
+    month: unknown;
+    /** 年 */
+    year: unknown;
+}
+/** 日期的粒度 */
+export type DateUnit = keyof DateUnits;
+/** 截到粒度：月取 1 日，年取 1 月 1 日 */
+export declare function truncateDate(date: CalendarDate, unit: DateUnit): CalendarDate;
+/** 按粒度比较：小于 0 表示 a 在前；跨日历系统时按同一天比较 */
+export declare function compareDates(a: CalendarDate, b: CalendarDate, unit?: DateUnit): number;
+/** 是不是同一天 / 同一月 / 同一年；任一方为空时为 false */
+export declare function isSameDate(a: CalendarDate | null | undefined, b: CalendarDate | null | undefined, unit?: DateUnit): boolean;
+/** 可选范围与不可选的日期：Calendar、DatePicker、DateField 共用 */
+export interface DateLimits {
+    /** 最早可选的日期 */
+    min?: CalendarDate | null;
+    /** 最晚可选的日期 */
+    max?: CalendarDate | null;
+    /** 不可选的日期（已订满、节假日）：仍能用方向键经过，读屏能听到，不能选 */
+    isUnavailable?: (date: CalendarDate) => boolean;
+}
+/** 在 min–max 之外（按粒度：月份视图里只要这个月有一天可选就不算在外面） */
+export declare function isOutOfRange(date: CalendarDate, { min, max }: DateLimits, unit?: DateUnit): boolean;
+/** 不能选：在范围外，或是不可选的日期（只在天的粒度上判断 isUnavailable） */
+export declare function isDateDisabled(date: CalendarDate, limits: DateLimits, unit?: DateUnit): boolean;
+/** 把日期夹到 min–max 之间 */
+export declare function clampDate(date: CalendarDate, { min, max }: DateLimits): CalendarDate;
+/** 日期区间：两端都包含 */
+export interface DateRange<T = CalendarDate> {
+    /** 开始（含） */
+    start: T;
+    /** 结束（含） */
+    end: T;
+}
+/**
+ * 日期区间换成一对时刻，交给按时刻查的接口：从开始那天的零点起（含），到结束那天的第二天零点前（不含）。
+ * 一天按 timeZone 算（默认浏览器的时区），所以"10 月 27 日"在东八区是 26 日 16:00Z 到 27 日 16:00Z。
+ *
+ *   const { from, to } = dayRangeBounds(range);   // 发成 ISO：from.toISOString()
+ */
+export declare function dayRangeBounds(range: DateRange, timeZone?: string): {
+    from: Date;
+    to: Date;
+};
+/** 两个日期排成区间：先的在前 */
+export declare function orderedRange(a: CalendarDate, b: CalendarDate): DateRange;
+/** 日期是否在区间里（含两端；按粒度） */
+export declare function isInRange(date: CalendarDate, range: DateRange | null | undefined, unit?: DateUnit): boolean;
+/** 区间一共几天（含两端） */
+export declare function rangeDays({ start, end }: DateRange): number;
+/** 区间里有没有不可选的日期：酒店连住时中间不能有订满的一天（React Aria 的 allowsNonContiguousRanges 为 false 时） */
+export declare function rangeHasUnavailable({ start, end }: DateRange, isUnavailable: ((date: CalendarDate) => boolean) | undefined): boolean;
+/** ISO 字符串的区间 → CalendarDate 的区间；任一端解析不了时为 null */
+export declare function parseIsoRange(range: DateRange<string> | null | undefined): DateRange | null;
+/** CalendarDate 的区间 → ISO 字符串的区间 */
+export declare function toIsoRange(range: DateRange): DateRange<string>;
+/** 常用的快捷区间：报表、筛选里的“最近 7 天”“本月” */
+export interface DateRangePresets {
+    /** 今天 */
+    today: unknown;
+    /** 昨天 */
+    yesterday: unknown;
+    /** 最近 7 天（含今天） */
+    last7Days: unknown;
+    /** 最近 30 天（含今天） */
+    last30Days: unknown;
+    /** 本周（按语言的一周第一天） */
+    thisWeek: unknown;
+    /** 本月 */
+    thisMonth: unknown;
+    /** 上月 */
+    lastMonth: unknown;
+    /** 今年 */
+    thisYear: unknown;
+}
+/** 快捷区间的名字 */
+export type DateRangePreset = keyof DateRangePresets;
+/** 按今天算出快捷区间 */
+export declare function presetRange(preset: DateRangePreset, today: CalendarDate, week: WeekOptions): DateRange;
+/** 快捷区间的 ISO 值，按今天（时区，不写时取浏览器的）与一周的排法：`presetIsoRange('last7Days', { locale: 'zh-CN' })` */
+export declare function presetIsoRange(preset: DateRangePreset, week: WeekOptions, timeZone?: string): DateRange<string>;
+/**
+ * 日期值 → 时刻（毫秒时间戳）：Date 与带时区的值照原样；不带时区的（'2026-10-20T14:30'、CalendarDateTime）
+ * 按 timeZone 的墙上时间算。格式不对时 NaN
+ */
+export declare function toInstant(value: Date | DateValue | string, timeZone?: string): number;
+/** 相差的毫秒数 → 相对时间的数值与单位：`relativeUnit(-180_000)` → `{ value: -3, unit: 'minute' }` */
+export declare function relativeUnit(diff: number): {
+    value: number;
+    unit: Intl.RelativeTimeFormatUnit;
+};