@tu-design/vue 0.5.7 → 0.5.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (56) hide show
  1. package/dist/index.d.mts +186 -82
  2. package/dist/index.mjs +678 -74
  3. package/dist/registry/vue/alert-dialog.json +1 -1
  4. package/dist/registry/vue/alert.json +1 -1
  5. package/dist/registry/vue/avatar-group.json +1 -1
  6. package/dist/registry/vue/avatar.json +1 -1
  7. package/dist/registry/vue/badge.json +1 -1
  8. package/dist/registry/vue/button.json +1 -1
  9. package/dist/registry/vue/calendar.json +3 -3
  10. package/dist/registry/vue/card.json +1 -1
  11. package/dist/registry/vue/cascader.json +1 -1
  12. package/dist/registry/vue/checkbox.json +1 -1
  13. package/dist/registry/vue/context-menu.json +1 -1
  14. package/dist/registry/vue/currency-input.json +2 -2
  15. package/dist/registry/vue/date-picker.json +1 -1
  16. package/dist/registry/vue/date-range-picker.json +1 -1
  17. package/dist/registry/vue/date-shared.json +3 -3
  18. package/dist/registry/vue/dialog.json +1 -1
  19. package/dist/registry/vue/drawer.json +1 -1
  20. package/dist/registry/vue/dropdown-menu.json +1 -1
  21. package/dist/registry/vue/empty.json +1 -1
  22. package/dist/registry/vue/form-render.json +12 -12
  23. package/dist/registry/vue/form.json +1 -1
  24. package/dist/registry/vue/icon-shared.json +1 -1
  25. package/dist/registry/vue/input.json +1 -1
  26. package/dist/registry/vue/label.json +1 -1
  27. package/dist/registry/vue/month-picker.json +1 -1
  28. package/dist/registry/vue/number-input.json +3 -3
  29. package/dist/registry/vue/overlay-shared.json +5 -5
  30. package/dist/registry/vue/password-input.json +1 -1
  31. package/dist/registry/vue/pin-input.json +1 -1
  32. package/dist/registry/vue/popconfirm.json +1 -1
  33. package/dist/registry/vue/popover.json +1 -1
  34. package/dist/registry/vue/progress.json +1 -1
  35. package/dist/registry/vue/radio-group.json +1 -1
  36. package/dist/registry/vue/registry.json +52 -52
  37. package/dist/registry/vue/select.json +2 -2
  38. package/dist/registry/vue/separator.json +1 -1
  39. package/dist/registry/vue/skeleton.json +1 -1
  40. package/dist/registry/vue/slider.json +1 -1
  41. package/dist/registry/vue/slot.json +2 -2
  42. package/dist/registry/vue/spin.json +1 -1
  43. package/dist/registry/vue/switch.json +1 -1
  44. package/dist/registry/vue/table-render.json +9 -9
  45. package/dist/registry/vue/tabs.json +1 -1
  46. package/dist/registry/vue/textarea.json +1 -1
  47. package/dist/registry/vue/timeline.json +2 -2
  48. package/dist/registry/vue/toast.json +2 -2
  49. package/dist/registry/vue/tokens.json +1 -1
  50. package/dist/registry/vue/tooltip.json +1 -1
  51. package/dist/registry/vue/tree-select.json +1 -1
  52. package/dist/registry/vue/tree-shared.json +9 -9
  53. package/dist/registry/vue/utils.json +2 -2
  54. package/dist/registry/vue/week-picker.json +2 -2
  55. package/dist/registry/vue/year-picker.json +1 -1
  56. package/package.json +1 -1
package/dist/index.mjs CHANGED
@@ -25,6 +25,11 @@ import { Progress } from "@ark-ui/vue/progress";
25
25
  import { Toast, Toaster, createToaster } from "@ark-ui/vue/toast";
26
26
  import { Drawer } from "@ark-ui/vue/drawer";
27
27
  //#region src/lib/utils.ts
28
+ /**
29
+ * 合并 Tailwind CSS 类名:clsx 组合条件类名,tailwind-merge 消解冲突规则。
30
+ * @param inputs - 任意数量的类名值(字符串、数组或对象)
31
+ * @returns 消解冲突后的类名字符串
32
+ */
28
33
  function cn(...inputs) {
29
34
  return twMerge(clsx(inputs));
30
35
  }
@@ -94,6 +99,12 @@ const COMPONENT_NAMES = [
94
99
  "WeekPicker",
95
100
  "YearPicker"
96
101
  ];
102
+ /**
103
+ * 创建 unplugin-vue-components 的自动导入 Resolver:T 前缀(PascalCase)且命中
104
+ * 白名单的组件名(如 TButton)被解析为对应库导出;其余名称返回 undefined
105
+ * 交由后续 Resolver 或默认流程处理。
106
+ * @returns Resolver 函数(组件名到导入描述的映射)
107
+ */
97
108
  function TuDesignResolver() {
98
109
  return (name) => {
99
110
  if (!/^T[A-Z]/.test(name)) return;
@@ -107,7 +118,11 @@ function TuDesignResolver() {
107
118
  }
108
119
  //#endregion
109
120
  //#region src/components/slot/Slot.ts
110
- /** 递归展平 `<slot />` 插槽出口(renderSlot)产生的 Fragment 包裹,取出真实子节点。 */
121
+ /**
122
+ * 递归展平 `<slot />` 插槽出口(renderSlot)产生的 Fragment 包裹,取出真实子节点。
123
+ * @param children - 插槽渲染输出的 vnode 数组
124
+ * @returns 展平后的 vnode 数组(已剥离 Fragment 包裹层级)
125
+ */
111
126
  function flattenVNodes(children) {
112
127
  const out = [];
113
128
  for (const child of children) if (child.type === Fragment && Array.isArray(child.children)) out.push(...flattenVNodes(child.children));
@@ -674,6 +689,9 @@ const SLIDER = {
674
689
  /**
675
690
  * TanStack field → 控件 props 的统一绑定:
676
691
  * 值回显(field.state.value)+ 写回(handleChange)+ 失焦(handleBlur)。
692
+ * @param field - TanStack 表单字段实例,提供值读取与变更/失焦句柄
693
+ * @param spec - 绑定形态描述,决定值 prop 名、事件名与可选的双向转换
694
+ * @returns 可展开到组件 props 上的对象(值 prop、onUpdate:<event>、onBlur)
677
695
  */
678
696
  function bindField(field, spec) {
679
697
  return {
@@ -687,6 +705,8 @@ function bindField(field, spec) {
687
705
  /**
688
706
  * checkbox/switch widget:boolean 形态(值 prop 为 checked,非 modelValue)。
689
707
  * 单行布局倾向 hideLabel + label 经 item.title 展示由使用者决定。
708
+ * @param options - widget 选项,整体展开后经 checked 受控绑定与 componentProps 透传给 Checkbox
709
+ * @returns 渲染函数,接收渲染上下文并产出 Checkbox vnode
690
710
  */
691
711
  function renderCheckboxItem(options = {}) {
692
712
  return (ctx) => h(_sfc_main$9, {
@@ -695,6 +715,11 @@ function renderCheckboxItem(options = {}) {
695
715
  ...ctx.item.componentProps
696
716
  });
697
717
  }
718
+ /**
719
+ * switch widget:boolean 开关(checked 受控形态,绑定与 checkbox 一致)
720
+ * @param options - widget 选项,整体展开后经 checked 受控绑定与 componentProps 透传给 Switch
721
+ * @returns 渲染函数,接收渲染上下文并产出 Switch vnode
722
+ */
698
723
  function renderSwitchItem(options = {}) {
699
724
  return (ctx) => h(_sfc_main$42, {
700
725
  ...options,
@@ -715,6 +740,10 @@ const UNIT_FEN_EXP = {
715
740
  * 解析输入文本为 valueUnit 单位的数值(number|null)。
716
741
  * 全程十进制字符串移位(BigInt),仅在超出整数分精度时一次四舍五入;
717
742
  * 白名单 ^\d*(\.\d*)?$,负号/非法字符/无数字一律 null。
743
+ * @param raw - 用户键入的数字文本(labelUnit 单位)
744
+ * @param labelUnit - 输入文本的货币单位
745
+ * @param valueUnit - 输出数值的目标货币单位
746
+ * @returns valueUnit 单位的数值;格式非法或不含数字时返回 null
718
747
  */
719
748
  function parseCurrency(raw, labelUnit, valueUnit) {
720
749
  if (!/^\d*(\.\d*)?$/.test(raw) || !/\d/.test(raw)) return null;
@@ -733,6 +762,10 @@ function parseCurrency(raw, labelUnit, valueUnit) {
733
762
  /**
734
763
  * 受控值(valueUnit 单位)反算为 labelUnit 单位的回显文本。
735
764
  * 值先取整到整数分(吸收浮点噪声),再做十进制移位并去尾零。
765
+ * @param value - 受控值(valueUnit 单位)
766
+ * @param valueUnit - 受控值的货币单位
767
+ * @param labelUnit - 回显文本的目标货币单位
768
+ * @returns labelUnit 单位的回显文本(已去尾零);非有限值返回空串
736
769
  */
737
770
  function formatCurrency(value, valueUnit, labelUnit) {
738
771
  if (!Number.isFinite(value)) return "";
@@ -845,7 +878,11 @@ const _sfc_main$11 = /*@__PURE__*/ defineComponent({
845
878
  * 独立使用时 inject 落到 fallback false → 自建 Root(standalone 独立形态,恒开)。
846
879
  */
847
880
  const CALENDAR_IN_PICKER = Symbol("tu-calendar-in-picker");
848
- /** zag 按 locale 分隔符清洗键入字符(zh-CN 为 "/"),解析前统一归一为 "-" */
881
+ /**
882
+ * zag 按 locale 分隔符清洗键入字符(zh-CN 为 "/"),解析前统一归一为 "-"。
883
+ * @param raw - 原始键入文本
884
+ * @returns 去除首尾空白并把 "/" 归一为 "-" 后的文本
885
+ */
849
886
  function normalizeSeparators(raw) {
850
887
  return raw.trim().replace(/\//g, "-");
851
888
  }
@@ -853,6 +890,8 @@ function normalizeSeparators(raw) {
853
890
  * "yyyy-MM-dd" → DateValue(@internationalized/date 纯日历解析,无时区参与)。
854
891
  * 兼容 "/" 分隔(zag 键入清洗路径,如 "2026/10/09"),归一后做严格 ISO 校验;
855
892
  * 非法/非补零(如 "abc"、"2026-2-3")返回 undefined,由调用方忽略。
893
+ * @param raw - 待解析的日期文本
894
+ * @returns 解析成功返回对应 DateValue;非法/非补零输入返回 undefined
856
895
  */
857
896
  function parseIsoDate(raw) {
858
897
  const normalized = normalizeSeparators(raw);
@@ -863,11 +902,19 @@ function parseIsoDate(raw) {
863
902
  return;
864
903
  }
865
904
  }
866
- /** DateValue → "yyyy-MM-dd"(CalendarDate.toString 原生 ISO 输出) */
905
+ /**
906
+ * DateValue → "yyyy-MM-dd"(CalendarDate.toString 原生 ISO 输出)。
907
+ * @param date - 目标日期
908
+ * @returns ISO "yyyy-MM-dd" 格式日期串
909
+ */
867
910
  function formatIsoDate(date) {
868
911
  return date.toString();
869
912
  }
870
- /** "yyyy-MM" → DateValue(锚定 1 日);非法/非补零返回 undefined */
913
+ /**
914
+ * "yyyy-MM" → DateValue(锚定 1 日);非法/非补零返回 undefined。
915
+ * @param raw - 待解析的月份文本
916
+ * @returns 解析成功返回锚定 1 日的 DateValue;非法输入返回 undefined
917
+ */
871
918
  function parseIsoMonth(raw) {
872
919
  const normalized = normalizeSeparators(raw);
873
920
  if (!/^\d{4}-\d{2}$/.test(normalized)) return void 0;
@@ -877,11 +924,19 @@ function parseIsoMonth(raw) {
877
924
  return;
878
925
  }
879
926
  }
880
- /** DateValue → "yyyy-MM"(不能走 toString(),会带 day) */
927
+ /**
928
+ * DateValue → "yyyy-MM"(不能走 toString(),会带 day)。
929
+ * @param date - 目标日期
930
+ * @returns 补零的 "yyyy-MM" 格式月份串
931
+ */
881
932
  function formatIsoMonth(date) {
882
933
  return `${date.year}-${String(date.month).padStart(2, "0")}`;
883
934
  }
884
- /** "yyyy" → DateValue(锚定 1 月 1 日);非四位年份返回 undefined */
935
+ /**
936
+ * "yyyy" → DateValue(锚定 1 月 1 日);非四位年份返回 undefined。
937
+ * @param raw - 待解析的年份文本
938
+ * @returns 解析成功返回锚定 1 月 1 日的 DateValue;非法输入返回 undefined
939
+ */
885
940
  function parseIsoYear(raw) {
886
941
  const normalized = normalizeSeparators(raw);
887
942
  if (!/^\d{4}$/.test(normalized)) return void 0;
@@ -891,13 +946,19 @@ function parseIsoYear(raw) {
891
946
  return;
892
947
  }
893
948
  }
894
- /** DateValue → "yyyy" */
949
+ /**
950
+ * DateValue → "yyyy"。
951
+ * @param date - 目标日期
952
+ * @returns 四位年份串
953
+ */
895
954
  function formatIsoYear(date) {
896
955
  return String(date.year);
897
956
  }
898
957
  /**
899
958
  * locale 周起点(1=周一 … 7=周日,ISO 语义)。
900
959
  * 取 Intl.Locale.weekInfo.firstDay(Node ≥ 22 / 现代浏览器可用),异常兜底周一。
960
+ * @param locale - BCP 47 语言标签(如 "zh-CN"、"en-US")
961
+ * @returns 该 locale 的周起点序号(1=周一 … 7=周日);异常时兜底 1(周一)
901
962
  */
902
963
  function localeFirstDay(locale) {
903
964
  try {
@@ -906,24 +967,49 @@ function localeFirstDay(locale) {
906
967
  } catch {}
907
968
  return 1;
908
969
  }
909
- /** DateValue → 周起点(跟随 locale;zh-CN 周一起始、en-US 周日起始) */
970
+ /**
971
+ * DateValue → 周起点(跟随 locale;zh-CN 周一起始、en-US 周日起始)。
972
+ * @param date - 目标日期
973
+ * @param locale - BCP 47 语言标签,决定每周起始日
974
+ * @returns 该日期所在周的起点日期
975
+ */
910
976
  function weekStartOf(date, locale = "zh-CN") {
911
977
  const diff = (new Date(Date.UTC(date.year, date.month - 1, date.day)).getUTCDay() - localeFirstDay(locale) % 7 + 7) % 7;
912
978
  return diff === 0 ? date : date.subtract({ days: diff });
913
979
  }
914
- /** DateValue → 周终点(= 周起点 + 6 天) */
980
+ /**
981
+ * DateValue → 周终点(= 周起点 + 6 天)。
982
+ * @param date - 目标日期
983
+ * @param locale - BCP 47 语言标签,决定每周起始日
984
+ * @returns 该日期所在周的终点日期
985
+ */
915
986
  function weekEndOf(date, locale = "zh-CN") {
916
987
  return weekStartOf(date, locale).add({ days: 6 });
917
988
  }
918
- /** 两日期是否同属一周(跟随 locale) */
989
+ /**
990
+ * 两日期是否同属一周(跟随 locale)。
991
+ * @param a - 待比较的第一个日期
992
+ * @param b - 待比较的第二个日期
993
+ * @param locale - BCP 47 语言标签,决定每周起始日
994
+ * @returns 两日期同属一周时返回 true,否则返回 false
995
+ */
919
996
  function isSameWeek(a, b, locale = "zh-CN") {
920
997
  return weekStartOf(a, locale).compare(weekStartOf(b, locale)) === 0;
921
998
  }
922
- /** DateValue → "yyyy-MM-dd ~ yyyy-MM-dd"(所在周区间,输入框回显用) */
999
+ /**
1000
+ * DateValue → "yyyy-MM-dd ~ yyyy-MM-dd"(所在周区间,输入框回显用)。
1001
+ * @param date - 目标日期
1002
+ * @param locale - BCP 47 语言标签,决定每周起始日
1003
+ * @returns 形如 "yyyy-MM-dd ~ yyyy-MM-dd" 的周区间串
1004
+ */
923
1005
  function formatIsoWeek(date, locale = "zh-CN") {
924
1006
  return `${formatIsoDate(weekStartOf(date, locale))} ~ ${formatIsoDate(weekEndOf(date, locale))}`;
925
1007
  }
926
- /** 区间解析:逐侧 parseIsoDate + 顺序归一(start ≤ end);null / 任一侧非法返回 undefined */
1008
+ /**
1009
+ * 区间解析:逐侧 parseIsoDate + 顺序归一(start ≤ end);null / 任一侧非法返回 undefined。
1010
+ * @param raw - [起, 止] 文本二元组,可为 null 或 undefined
1011
+ * @returns 顺序归一后的 [start, end];输入为空或任一侧非法时返回 undefined
1012
+ */
927
1013
  function parseIsoRange(raw) {
928
1014
  if (!raw) return void 0;
929
1015
  const start = parseIsoDate(raw[0] ?? "");
@@ -968,7 +1054,11 @@ const viewControlCls = "flex items-center justify-between px-1 pb-3";
968
1054
  const navBtnCls = "text-muted-foreground inline-flex size-8 items-center justify-center rounded-md outline-none hover:bg-accent disabled:cursor-not-allowed disabled:opacity-40";
969
1055
  const viewTriggerCls = "hover:bg-accent inline-flex items-center gap-1 rounded-[3px] px-3 py-1.5 text-sm font-semibold text-foreground outline-none transition-colors disabled:pointer-events-none";
970
1056
  const viewTitleCls = "text-sm font-semibold text-foreground";
971
- /** 年代范围文本(zag 无现成 part,由 focusedValue.year 推算):2026 → "2020 - 2029" */
1057
+ /**
1058
+ * 年代范围文本(zag 无现成 part,由 focusedValue.year 推算):2026 → "2020 - 2029"
1059
+ * @param year - 聚焦年份
1060
+ * @returns "起 - 止" 形式的年代范围文本
1061
+ */
972
1062
  const _sfc_main$62 = /*@__PURE__*/ defineComponent({
973
1063
  __name: "CalendarNav",
974
1064
  props: {
@@ -1031,7 +1121,12 @@ const tableCls = "w-full min-w-0 flex-1 table-fixed border-collapse";
1031
1121
  const headCellCls = "text-muted-foreground h-8 border-x-0! border-t-0! border-b border-border p-0! text-center! text-xs! align-middle font-normal whitespace-nowrap";
1032
1122
  const bodyCellCls = "border-0! p-0! text-center";
1033
1123
  const rowCls = "bg-transparent!";
1034
- /** 表 i 的锚点月起点(zag getOffset({months: i-1}).visibleRange.start) */
1124
+ /**
1125
+ * 表 i 的锚点月起点(zag getOffset({months: i-1}).visibleRange.start)
1126
+ * @param context - zag Table 上下文
1127
+ * @param i - 表序号(1-based,相对当前锚点月偏移 i-1 个月)
1128
+ * @returns 该表锚点月的起始日期
1129
+ */
1035
1130
  const _sfc_main$61 = /*@__PURE__*/ defineComponent({
1036
1131
  __name: "CalendarBody",
1037
1132
  props: {
@@ -1049,7 +1144,12 @@ const _sfc_main$61 = /*@__PURE__*/ defineComponent({
1049
1144
  function tableAnchor(context, i) {
1050
1145
  return context.getOffset({ months: i - 1 })?.visibleRange?.start;
1051
1146
  }
1052
- /** 格子日期不属于锚点月(年或月不一致)即为补位格 */
1147
+ /**
1148
+ * 格子日期不属于锚点月(年或月不一致)即为补位格
1149
+ * @param day - 格子日期
1150
+ * @param anchor - 所在表的锚点月起点
1151
+ * @returns 是否为补位格
1152
+ */
1053
1153
  function isOutsideView(day, anchor) {
1054
1154
  return !!anchor && (day.year !== anchor.year || day.month !== anchor.month);
1055
1155
  }
@@ -1058,6 +1158,9 @@ const _sfc_main$61 = /*@__PURE__*/ defineComponent({
1058
1158
  * 与 data-week-selected(视觉标记,驱动 trigger 整行条带与 dot 层反色变体);
1059
1159
  * 非 week 形态返回空对象,完全不下发属性,选中视觉交回 zag 原生绑定,避免 fallthrough 覆盖。
1060
1160
  * 走显式函数而非模板内联,避免与日视图 v-for 的 `week` 循环变量同名遮蔽。
1161
+ * @param day - 格子日期
1162
+ * @param selected - 当前选中日期集合(单选语义,取首个)
1163
+ * @returns 需下发的 data 属性对象(无命中时为空对象)
1061
1164
  */
1062
1165
  function weekSelectedAttrs(day, selected) {
1063
1166
  return weekSelected(day, selected) ? {
@@ -1531,12 +1634,18 @@ var CloseIcon_default = /*#__PURE__*/ export_helper_default(_sfc_main$59, [["ren
1531
1634
  * - fixed 面板在祖先滚动时依赖 autoUpdate 重算,重算前一帧有视口驻留(瞬时视觉差异)
1532
1635
  * - 若未来出现「非 iframe 的 graft 型沙箱」,本探测无法覆盖,需追加该沙箱的 marker 信号
1533
1636
  */
1534
- /** 组件 JS 是否运行在 iframe realm(wujie / iframe 型沙箱 / 普通 iframe 嵌入) */
1637
+ /**
1638
+ * 组件 JS 是否运行在 iframe realm(wujie / iframe 型沙箱 / 普通 iframe 嵌入)。
1639
+ * @returns 运行在 iframe realm 时返回 true,否则返回 false
1640
+ */
1535
1641
  function isInIframeRealm() {
1536
1642
  return typeof window !== "undefined" && window.self !== window.top;
1537
1643
  }
1538
- /** 是否处于 wujie graft 沙箱(getRootNode/父链被 wujie patch 伪装,结构探测失效,
1539
- * 依赖官方标记;wujie 在子应用脚本执行前注入,时序可靠) */
1644
+ /**
1645
+ * 是否处于 wujie graft 沙箱(getRootNode/父链被 wujie patch 伪装,结构探测失效,
1646
+ * 依赖官方标记;wujie 在子应用脚本执行前注入,时序可靠)。
1647
+ * @returns 处于 wujie graft 沙箱时返回 true,否则返回 false
1648
+ */
1540
1649
  function isInWujie() {
1541
1650
  return typeof window !== "undefined" && window.__POWERED_BY_WUJIE__ === true;
1542
1651
  }
@@ -1763,6 +1872,8 @@ const _sfc_main$58 = /*@__PURE__*/ defineComponent({
1763
1872
  /**
1764
1873
  * 业务组件惯例:Ark Root 恒走受控,非受控语义由内部 ref 实现。
1765
1874
  * `controlled()` 返回 undefined 时用内部值,否则永远跟随外部 prop。
1875
+ * @param options - 受控/非受控配置:受控值读取器、非受控初值与变更回调
1876
+ * @returns isOpen(当前开合状态)与 setOpen(写入状态并同步 onChange)
1766
1877
  */
1767
1878
  function useControlledBoolean(options) {
1768
1879
  const internal = ref(options.defaultValue?.() ?? false);
@@ -1781,6 +1892,8 @@ function useControlledBoolean(options) {
1781
1892
  /**
1782
1893
  * 单值日期选择器的受控桥接:值以内部 ref 为镜像、Root 恒走受控,
1783
1894
  * 开合复用 useControlledBoolean,openFromInput 统一「点击/↓ 输入框即开」。
1895
+ * @param options - 桥接配置:值与开合的受控/非受控读写、解析与回写转换、事件回调
1896
+ * @returns rootValue(zag 受控值)、isOpen 与 setOpen(开合状态)、openFromInput(输入框驱动开弹层)与 handleValueUpdate(日历值更新处理)
1784
1897
  */
1785
1898
  function usePickerBridge(options) {
1786
1899
  const initial = options.defaultValue();
@@ -2310,7 +2423,11 @@ const _sfc_main$29 = /*@__PURE__*/ defineComponent({
2310
2423
  });
2311
2424
  //#endregion
2312
2425
  //#region src/components/number-input/utils.ts
2313
- /** Ark ValueChangeDetails → number|null(空串/NaN 归一 null,numberOrNull 为可单测的纯函数) */
2426
+ /**
2427
+ * Ark ValueChangeDetails → number|null(空串/NaN 归一 null,numberOrNull 为可单测的纯函数)
2428
+ * @param details - Ark NumberInput 的 ValueChangeDetails
2429
+ * @returns 有效数字;空串或 NaN 时返回 null
2430
+ */
2314
2431
  function numberOrNull(details) {
2315
2432
  return details.value === "" || Number.isNaN(details.valueAsNumber) ? null : details.valueAsNumber;
2316
2433
  }
@@ -2362,7 +2479,10 @@ const _sfc_main$30 = /*@__PURE__*/ defineComponent({
2362
2479
  const current = computed(() => props.modelValue === void 0 ? internalValue.value : props.modelValue);
2363
2480
  /** number → Ark 受控 string(null/NaN → 空串) */
2364
2481
  const arkValue = computed(() => current.value == null || Number.isNaN(current.value) ? "" : String(current.value));
2365
- /** Ark details(value: string / valueAsNumber: number)→ number|null(空串/NaN 归一 null) */
2482
+ /**
2483
+ * Ark details(value: string / valueAsNumber: number)→ number|null(空串/NaN 归一 null)
2484
+ * @param details - Ark NumberInput 的 ValueChangeDetails
2485
+ */
2366
2486
  function handleValueChange(details) {
2367
2487
  const next = numberOrNull(details);
2368
2488
  internalValue.value = next;
@@ -2660,7 +2780,11 @@ const _sfc_main$51 = /*@__PURE__*/ defineComponent({
2660
2780
  const props = __props;
2661
2781
  const emit = __emit;
2662
2782
  provide(CALENDAR_IN_PICKER, true);
2663
- /** "yyyy-MM-dd" → 归一到所在周起始日的 ISO 串(非法输入返回 undefined) */
2783
+ /**
2784
+ * "yyyy-MM-dd" → 归一到所在周起始日的 ISO 串(非法输入返回 undefined)
2785
+ * @param raw - 输入的 ISO 日期串
2786
+ * @returns 该日期所在周起始日的 ISO 串;解析失败返回 undefined
2787
+ */
2664
2788
  function formatIsoWeekStart(raw) {
2665
2789
  const date = parseIsoDate(raw);
2666
2790
  return date ? weekStartOf(date, props.locale).toString() : void 0;
@@ -2875,7 +2999,11 @@ const _sfc_main$52 = /*@__PURE__*/ defineComponent({
2875
2999
  * item 级缺省 → options 整体展开(命名穿透,组件全 props)→ 受控绑定 → 逃逸口。
2876
3000
  * options.placeholder 为 undefined 时 Vue 视为未传,item 级缺省保留(I1 语义)。
2877
3001
  */
2878
- /** password widget:密码输入(autoComplete 为组件真实 prop,直接派生透传) */
3002
+ /**
3003
+ * password widget:密码输入(autoComplete 为组件真实 prop,直接派生透传)
3004
+ * @param options - widget 选项,整体展开后经 modelValue 受控绑定与 componentProps 透传给 PasswordInput
3005
+ * @returns 渲染函数,接收渲染上下文并产出 PasswordInput vnode
3006
+ */
2879
3007
  function renderPasswordItem(options = {}) {
2880
3008
  return (ctx) => h(_sfc_main$31, {
2881
3009
  placeholder: ctx.item.placeholder,
@@ -2884,7 +3012,11 @@ function renderPasswordItem(options = {}) {
2884
3012
  ...ctx.item.componentProps
2885
3013
  });
2886
3014
  }
2887
- /** number widget:数值输入(modelValue: number|null) */
3015
+ /**
3016
+ * number widget:数值输入(modelValue: number|null)
3017
+ * @param options - widget 选项,整体展开后经 modelValue 受控绑定与 componentProps 透传给 NumberInput
3018
+ * @returns 渲染函数,接收渲染上下文并产出 NumberInput vnode
3019
+ */
2888
3020
  function renderNumberItem(options = {}) {
2889
3021
  return (ctx) => h(_sfc_main$30, {
2890
3022
  ...options,
@@ -2892,7 +3024,11 @@ function renderNumberItem(options = {}) {
2892
3024
  ...ctx.item.componentProps
2893
3025
  });
2894
3026
  }
2895
- /** currency widget:金额输入(labelUnit/valueUnit 单位展示) */
3027
+ /**
3028
+ * currency widget:金额输入(labelUnit/valueUnit 单位展示)
3029
+ * @param options - widget 选项,整体展开后经 modelValue 受控绑定与 componentProps 透传给 CurrencyInput
3030
+ * @returns 渲染函数,接收渲染上下文并产出 CurrencyInput vnode
3031
+ */
2896
3032
  function renderCurrencyItem(options = {}) {
2897
3033
  return (ctx) => h(_sfc_main$11, {
2898
3034
  placeholder: ctx.item.placeholder,
@@ -2901,7 +3037,11 @@ function renderCurrencyItem(options = {}) {
2901
3037
  ...ctx.item.componentProps
2902
3038
  });
2903
3039
  }
2904
- /** textarea widget:多行文本(placeholder/rows 为原生 attr 透传) */
3040
+ /**
3041
+ * textarea widget:多行文本(placeholder/rows 为原生 attr 透传)
3042
+ * @param options - widget 选项,整体展开后经 modelValue 受控绑定与 componentProps 透传给 Textarea
3043
+ * @returns 渲染函数,接收渲染上下文并产出 Textarea vnode
3044
+ */
2905
3045
  function renderTextareaItem(options = {}) {
2906
3046
  return (ctx) => h(_sfc_main$46, {
2907
3047
  placeholder: ctx.item.placeholder,
@@ -2913,6 +3053,9 @@ function renderTextareaItem(options = {}) {
2913
3053
  /**
2914
3054
  * 日期类 widget 共用工厂:入口各自携带强类型(DatePicker/Month/Year/DateRange 的
2915
3055
  * props 面互不相同,见 types.ts 各派生接口),内部共享实现无需重复泛型关联。
3056
+ * @param component - 日期类组件(DatePicker/MonthPicker/YearPicker/DateRangePicker/WeekPicker)
3057
+ * @param options - widget 选项,整体展开后经 modelValue 受控绑定与 componentProps 透传给组件
3058
+ * @returns 渲染函数,接收渲染上下文并产出对应日期组件的 vnode
2916
3059
  */
2917
3060
  function pickerRenderer(component, options) {
2918
3061
  return (ctx) => h(component, {
@@ -2922,19 +3065,43 @@ function pickerRenderer(component, options) {
2922
3065
  ...ctx.item.componentProps
2923
3066
  });
2924
3067
  }
3068
+ /**
3069
+ * datePicker widget:日期选择(单日,modelValue 受控形态)
3070
+ * @param options - widget 选项,经 pickerRenderer 共享实现透传给 DatePicker
3071
+ * @returns 渲染函数,接收渲染上下文并产出 DatePicker vnode
3072
+ */
2925
3073
  function renderDatePickerItem(options = {}) {
2926
3074
  return pickerRenderer(_sfc_main$12, options);
2927
3075
  }
3076
+ /**
3077
+ * monthPicker widget:月份选择(modelValue 受控形态)
3078
+ * @param options - widget 选项,经 pickerRenderer 共享实现透传给 MonthPicker
3079
+ * @returns 渲染函数,接收渲染上下文并产出 MonthPicker vnode
3080
+ */
2928
3081
  function renderMonthPickerItem(options = {}) {
2929
3082
  return pickerRenderer(_sfc_main$29, options);
2930
3083
  }
3084
+ /**
3085
+ * yearPicker widget:年份选择(modelValue 受控形态)
3086
+ * @param options - widget 选项,经 pickerRenderer 共享实现透传给 YearPicker
3087
+ * @returns 渲染函数,接收渲染上下文并产出 YearPicker vnode
3088
+ */
2931
3089
  function renderYearPickerItem(options = {}) {
2932
3090
  return pickerRenderer(_sfc_main$52, options);
2933
3091
  }
2934
- /** dateRangePicker widget:[start, end] | null 形态 */
3092
+ /**
3093
+ * dateRangePicker widget:[start, end] | null 形态
3094
+ * @param options - widget 选项,经 pickerRenderer 共享实现透传给 DateRangePicker
3095
+ * @returns 渲染函数,接收渲染上下文并产出 DateRangePicker vnode
3096
+ */
2935
3097
  function renderDateRangePickerItem(options = {}) {
2936
3098
  return pickerRenderer(_sfc_main$13, options);
2937
3099
  }
3100
+ /**
3101
+ * weekPicker widget:周选择(modelValue 受控形态)
3102
+ * @param options - widget 选项,经 pickerRenderer 共享实现透传给 WeekPicker
3103
+ * @returns 渲染函数,接收渲染上下文并产出 WeekPicker vnode
3104
+ */
2938
3105
  function renderWeekPickerItem(options = {}) {
2939
3106
  return pickerRenderer(_sfc_main$51, options);
2940
3107
  }
@@ -2965,7 +3132,11 @@ const _sfc_main$27 = /*@__PURE__*/ defineComponent({
2965
3132
  });
2966
3133
  //#endregion
2967
3134
  //#region src/components/form-render/widgets/input.ts
2968
- /** input widget:单行文本输入(placeholder 为原生 attr 透传,aria-invalid 由 FormControl 接线) */
3135
+ /**
3136
+ * input widget:单行文本输入(placeholder 为原生 attr 透传,aria-invalid 由 FormControl 接线)
3137
+ * @param options - widget 选项,整体展开后经 modelValue 受控绑定与 componentProps 透传给 Input
3138
+ * @returns 渲染函数,接收渲染上下文并产出 Input vnode
3139
+ */
2969
3140
  function renderInputItem(options = {}) {
2970
3141
  return (ctx) => h(_sfc_main$27, {
2971
3142
  placeholder: ctx.item.placeholder,
@@ -2999,11 +3170,17 @@ function renderInputItem(options = {}) {
2999
3170
  * 边界:parts 只声明「字符串型覆盖口」的 part;函数型 part(如 select 的
3000
3171
  * item/itemGroup/itemGroupLabel——元素必渲染,[id="…"] 首查即命中,无炸点)不进
3001
3172
  * parts,由 user 经 attrs.ids 直传原样保留。user 永远最后展开:显式传入以其为准。
3173
+ * @param attrs - 组件透传 attrs(其中的 ids 为用户覆盖项,可为 undefined)
3174
+ * @param options - 生成配置:primary 为主 part(stemId 不加后缀),parts 为声明覆盖口的 part 列表
3175
+ * @returns ids(合并用户覆盖后的完整 id 映射,供 :ids 受控绑定)与 resolveId(取实际生效的字符串 id,供 aria 手动接线)
3002
3176
  */
3003
3177
  function useOverlayIds(attrs, options) {
3004
3178
  const stemId = useId();
3005
3179
  const userIds = computed(() => attrs.ids ?? {});
3006
- /** 默认派生值(不含 user 覆盖),独立于 ids 供 resolveId 回退;构造恒为字符串 */
3180
+ /**
3181
+ * 默认派生值(不含 user 覆盖),独立于 ids 供 resolveId 回退;构造恒为字符串。
3182
+ * @returns 以 part 为键的默认 id 映射
3183
+ */
3007
3184
  const buildBase = () => {
3008
3185
  const base = {};
3009
3186
  for (const part of options.parts) base[part] = part === options.primary ? stemId : `${stemId}-${part}`;
@@ -3013,7 +3190,11 @@ function useOverlayIds(attrs, options) {
3013
3190
  ...buildBase(),
3014
3191
  ...userIds.value
3015
3192
  }));
3016
- /** aria 接线用:user 字符串覆盖优先,函数型 user 回退默认值 */
3193
+ /**
3194
+ * aria 接线用:user 字符串覆盖优先,函数型 user 回退默认值。
3195
+ * @param part - 目标 part 名(如 "title"、"trigger")
3196
+ * @returns 该 part 实际生效的字符串 id;part 未声明覆盖口时返回 undefined
3197
+ */
3017
3198
  const resolveId = (part) => {
3018
3199
  const v = userIds.value[part];
3019
3200
  return typeof v === "string" ? v : buildBase()[part];
@@ -3025,6 +3206,11 @@ function useOverlayIds(attrs, options) {
3025
3206
  }
3026
3207
  //#endregion
3027
3208
  //#region src/components/select/types.ts
3209
+ /**
3210
+ * 将字符串简写归一为完整选项对象:字符串同时作为 label 与 value。
3211
+ * @param item - 字符串简写或完整选项对象
3212
+ * @returns 归一后的选项对象(字符串入参转为 label/value 同值的选项)
3213
+ */
3028
3214
  function normalizeSelectItem(item) {
3029
3215
  return typeof item === "string" ? {
3030
3216
  label: item,
@@ -3201,6 +3387,8 @@ const _sfc_main$37 = /*@__PURE__*/ defineComponent({
3201
3387
  * select widget:Select 已单组件化,items/placeholder 均为正式 prop 直写。
3202
3388
  * v3 命名穿透:options 整体透传给 Select(内部做 string 归一化);
3203
3389
  * placeholder 解构出来做 item 级缺省回退(options 优先,I1 语义)。
3390
+ * @param options - widget 选项,items/placeholder 直写为组件 prop,其余整体透传给 Select
3391
+ * @returns 渲染函数,接收渲染上下文并产出 Select vnode
3204
3392
  */
3205
3393
  function renderSelectItem(options) {
3206
3394
  const { placeholder, items, ...rootProps } = options;
@@ -3362,6 +3550,8 @@ const _sfc_main$40 = /*@__PURE__*/ defineComponent({
3362
3550
  /**
3363
3551
  * radioGroup widget:单选组(值 prop 为 value)。
3364
3552
  * 命名穿透:选项字段为组件 required prop `items`,整体直传,widget 不做组装。
3553
+ * @param options - widget 选项,整体展开后经 value 受控绑定与 componentProps 透传给 RadioGroup
3554
+ * @returns 渲染函数,接收渲染上下文并产出 RadioGroup vnode
3365
3555
  */
3366
3556
  function renderRadioGroupItem(options) {
3367
3557
  return (ctx) => h(_sfc_main$36, {
@@ -3373,6 +3563,8 @@ function renderRadioGroupItem(options) {
3373
3563
  /**
3374
3564
  * slider widget:number ↔ number[] 混合绑定特例
3375
3565
  * (值 prop 为 `value`,事件却是 `update:modelValue` 且数组语义,由 SLIDER spec 转换)。
3566
+ * @param options - widget 选项,整体展开后经 SLIDER 受控绑定与 componentProps 透传给 Slider
3567
+ * @returns 渲染函数,接收渲染上下文并产出 Slider vnode
3376
3568
  */
3377
3569
  function renderSliderItem(options = {}) {
3378
3570
  return (ctx) => h(_sfc_main$40, {
@@ -3457,15 +3649,33 @@ const _sfc_main$57 = /*@__PURE__*/ defineComponent({
3457
3649
  * MIT License · Copyright (c) 07akioni
3458
3650
  * 本地改动:defaultGetChildren 返回类型同步 GetChildren 塌缩为 `unknown`(语义不变)。
3459
3651
  */
3652
+ /**
3653
+ * 把任意值归一为数组:本身是数组则原样返回,否则包装为单元素数组。
3654
+ * @param arg - 任意输入值
3655
+ * @returns 数组形式的输入值
3656
+ */
3460
3657
  function toArray(arg) {
3461
3658
  if (Array.isArray(arg)) return arg;
3462
3659
  return [arg];
3463
3660
  }
3464
3661
  const TRAVERSE_COMMAND = { STOP: "STOP" };
3662
+ /**
3663
+ * 深度优先遍历节点子树,callback 返回 STOP 指令时终止该分支的继续下钻。
3664
+ * @param treeNode - 遍历起点节点
3665
+ * @param callback - 访问每个节点时执行的回调
3666
+ * @returns 无返回值
3667
+ */
3465
3668
  function traverseWithCb(treeNode, callback) {
3466
3669
  const command = callback(treeNode);
3467
3670
  if (treeNode.children !== void 0 && command !== TRAVERSE_COMMAND.STOP) treeNode.children.forEach((childNode) => traverseWithCb(childNode, callback));
3468
3671
  }
3672
+ /**
3673
+ * 收集树中所有非叶子节点的 key;preserveGroup 为 true 时保留 group 节点,
3674
+ * 否则排除 group,仅返回普通父节点 key。
3675
+ * @param treeNodes - 待收集的节点树
3676
+ * @param options - 选项;preserveGroup 控制是否包含 group 节点
3677
+ * @returns 非叶子节点 key 列表
3678
+ */
3469
3679
  function getNonLeafKeys(treeNodes, options = {}) {
3470
3680
  const { preserveGroup = false } = options;
3471
3681
  const keys = [];
@@ -3480,38 +3690,88 @@ function getNonLeafKeys(treeNodes, options = {}) {
3480
3690
  traverse(node.children);
3481
3691
  }
3482
3692
  };
3693
+ /**
3694
+ * 用预设回调遍历当前层节点列表。
3695
+ * @param nodes - 当前层的节点列表
3696
+ * @returns 无返回值
3697
+ */
3483
3698
  function traverse(nodes) {
3484
3699
  nodes.forEach(cb);
3485
3700
  }
3486
3701
  traverse(treeNodes);
3487
3702
  return keys;
3488
3703
  }
3704
+ /**
3705
+ * 判断原始节点是否为叶子:显式 isLeaf 字段优先,否则以取不到子节点视为叶子。
3706
+ * @param rawNode - 原始节点数据
3707
+ * @param getChildren - 取子节点的函数
3708
+ * @returns 是否为叶子节点
3709
+ */
3489
3710
  function isLeaf(rawNode, getChildren) {
3490
3711
  const { isLeaf } = rawNode;
3491
3712
  if (isLeaf !== void 0) return isLeaf;
3492
3713
  else if (!getChildren(rawNode)) return true;
3493
3714
  return false;
3494
3715
  }
3716
+ /**
3717
+ * 默认取子节点实现:读取节点数据的 children 字段。
3718
+ * @param node - 原始节点数据
3719
+ * @returns 子节点数组或 undefined
3720
+ */
3495
3721
  function defaultGetChildren(node) {
3496
3722
  return node.children;
3497
3723
  }
3724
+ /**
3725
+ * 默认取 key 实现:读取节点数据的 key 字段。
3726
+ * @param node - 原始节点数据
3727
+ * @returns 节点 key
3728
+ */
3498
3729
  function defaultGetKey(node) {
3499
3730
  return node.key;
3500
3731
  }
3732
+ /**
3733
+ * 默认的节点忽略判定:始终返回 false。
3734
+ * @returns 恒为 false
3735
+ */
3501
3736
  function isIgnored() {
3502
3737
  return false;
3503
3738
  }
3739
+ /**
3740
+ * 判断节点是否处于浅加载完成状态:显式 isLeaf=false 但取不到子节点数组时视为未加载,
3741
+ * 其余情况(含已加载)均视为完成。
3742
+ * @param rawNode - 原始节点数据
3743
+ * @param getChildren - 取子节点的函数
3744
+ * @returns 节点是否已浅加载
3745
+ */
3504
3746
  function isShallowLoaded(rawNode, getChildren) {
3505
3747
  const { isLeaf } = rawNode;
3506
3748
  if (isLeaf === false && !Array.isArray(getChildren(rawNode))) return false;
3507
3749
  return true;
3508
3750
  }
3751
+ /**
3752
+ * 判断原始节点是否被禁用。
3753
+ * @param rawNode - 原始节点数据
3754
+ * @returns disabled === true 时返回 true
3755
+ */
3509
3756
  function isDisabled(rawNode) {
3510
3757
  return rawNode.disabled === true;
3511
3758
  }
3759
+ /**
3760
+ * 判断节点是否显式未加载:isLeaf === false 且 getChildren 未返回数组
3761
+ * (异步加载占位,子树尚未到位)。
3762
+ * @param rawNode - 原始节点数据
3763
+ * @param getChildren - 取子节点的函数
3764
+ * @returns 是否显式未加载
3765
+ */
3512
3766
  function isExpilicitlyNotLoaded(rawNode, getChildren) {
3513
3767
  return rawNode.isLeaf === false && !Array.isArray(getChildren(rawNode));
3514
3768
  }
3769
+ /**
3770
+ * 判断节点数据是否非法:声明 isLeaf === true 却仍返回非空子节点数组。
3771
+ * @param rawNode - 原始节点数据
3772
+ * @param getChildren - 取子节点的函数
3773
+ * @returns 数据非法时返回 true
3774
+ */
3515
3775
  function isNodeInvalid(rawNode, getChildren) {
3516
3776
  if (rawNode.isLeaf === true) {
3517
3777
  const children = getChildren(rawNode);
@@ -3519,15 +3779,33 @@ function isNodeInvalid(rawNode, getChildren) {
3519
3779
  }
3520
3780
  return false;
3521
3781
  }
3782
+ /**
3783
+ * 从勾选结果中取出选中 key 列表:兼容 key 数组直传与 merged 结果对象两种形态,
3784
+ * 空值返回空数组。
3785
+ * @param result - 勾选结果(key 数组、merged 对象或空值)
3786
+ * @returns 选中 key 数组
3787
+ */
3522
3788
  function unwrapCheckedKeys(result) {
3523
3789
  if (result === void 0 || result === null) return [];
3524
3790
  if (Array.isArray(result)) return result;
3525
3791
  return result.checkedKeys ?? [];
3526
3792
  }
3793
+ /**
3794
+ * 从勾选结果中取出半选 key 列表:仅 merged 结果对象包含该信息,
3795
+ * 数组与空值均返回空数组。
3796
+ * @param result - 勾选结果(key 数组、merged 对象或空值)
3797
+ * @returns 半选 key 数组
3798
+ */
3527
3799
  function unwrapIndeterminateKeys(result) {
3528
3800
  if (result === void 0 || result === null || Array.isArray(result)) return [];
3529
3801
  return result.indeterminateKeys ?? [];
3530
3802
  }
3803
+ /**
3804
+ * 求并集:把 keysToAdd 中不存在的 key 追加到 originalKeys,保持原有顺序。
3805
+ * @param originalKeys - 原始 key 列表
3806
+ * @param keysToAdd - 待追加的 key 列表
3807
+ * @returns 合并去重后的 key 列表
3808
+ */
3531
3809
  function merge(originalKeys, keysToAdd) {
3532
3810
  const set = new Set(originalKeys);
3533
3811
  keysToAdd.forEach((key) => {
@@ -3535,6 +3813,12 @@ function merge(originalKeys, keysToAdd) {
3535
3813
  });
3536
3814
  return Array.from(set);
3537
3815
  }
3816
+ /**
3817
+ * 求差集:从 originalKeys 中移除 keysToRemove 里出现的 key,保持原有顺序。
3818
+ * @param originalKeys - 原始 key 列表
3819
+ * @param keysToRemove - 待移除的 key 列表
3820
+ * @returns 移除后的 key 列表
3821
+ */
3538
3822
  function minus(originalKeys, keysToRemove) {
3539
3823
  const set = new Set(originalKeys);
3540
3824
  keysToRemove.forEach((key) => {
@@ -3542,6 +3826,11 @@ function minus(originalKeys, keysToRemove) {
3542
3826
  });
3543
3827
  return Array.from(set);
3544
3828
  }
3829
+ /**
3830
+ * 判断原始节点是否为 group 分组节点(type === "group")。
3831
+ * @param rawNode - 原始节点数据
3832
+ * @returns 是否 group 节点
3833
+ */
3545
3834
  function isGroup(rawNode) {
3546
3835
  return rawNode?.type === "group";
3547
3836
  }
@@ -3558,9 +3847,23 @@ var SubtreeNotLoadedError = class extends Error {
3558
3847
  this.message = "SubtreeNotLoadedError: checking a subtree whose required nodes are not fully loaded.";
3559
3848
  }
3560
3849
  };
3850
+ /**
3851
+ * 计算勾选后的完整选中 key 集合:把新增勾选并入当前选中集,再级联扩展到子孙节点。
3852
+ * @param checkKeys - 本次新增勾选的节点 key 列表
3853
+ * @param currentCheckedKeys - 当前已选中的 key 列表
3854
+ * @param treeMate - 树 mate 实例,用于查询节点与子树
3855
+ * @returns 扩展后的选中 key 集合
3856
+ */
3561
3857
  function getExtendedCheckedKeySetAfterCheck(checkKeys, currentCheckedKeys, treeMate) {
3562
3858
  return getExtendedCheckedKeySet(currentCheckedKeys.concat(checkKeys), treeMate);
3563
3859
  }
3860
+ /**
3861
+ * 收集取消勾选节点的可用祖先 key 集合(级联反选时这些祖先需同步取消勾选);
3862
+ * 上溯在遇到 disabled 节点或已访问节点时截断。
3863
+ * @param uncheckedKeys - 被取消勾选的节点 key 列表
3864
+ * @param treeMate - 树 mate 实例,用于查询节点父子关系
3865
+ * @returns 需要联动取消勾选的祖先 key 集合
3866
+ */
3564
3867
  function getAvailableAscendantNodeSet(uncheckedKeys, treeMate) {
3565
3868
  const visitedKeys = /* @__PURE__ */ new Set();
3566
3869
  uncheckedKeys.forEach((uncheckedKey) => {
@@ -3577,6 +3880,14 @@ function getAvailableAscendantNodeSet(uncheckedKeys, treeMate) {
3577
3880
  });
3578
3881
  return visitedKeys;
3579
3882
  }
3883
+ /**
3884
+ * 计算取消勾选后的完整选中 key 集合:从扩展选中集移除被取消的 key
3885
+ * 及其可用祖先,返回剩余集合。
3886
+ * @param uncheckedKeys - 本次取消勾选的节点 key 列表
3887
+ * @param currentCheckedKeys - 当前已选中的 key 列表
3888
+ * @param treeMate - 树 mate 实例
3889
+ * @returns 取消勾选后剩余的选中 key 集合
3890
+ */
3580
3891
  function getExtendedCheckedKeySetAfterUncheck(uncheckedKeys, currentCheckedKeys, treeMate) {
3581
3892
  const extendedCheckedKeySet = getExtendedCheckedKeySet(currentCheckedKeys, treeMate);
3582
3893
  const extendedKeySetToUncheck = getExtendedCheckedKeySet(uncheckedKeys, treeMate, true);
@@ -3588,6 +3899,15 @@ function getExtendedCheckedKeySetAfterUncheck(uncheckedKeys, currentCheckedKeys,
3588
3899
  keysToRemove.forEach((key) => extendedCheckedKeySet.delete(key));
3589
3900
  return extendedCheckedKeySet;
3590
3901
  }
3902
+ /**
3903
+ * 计算树勾选结果:cascade=false 时直接在现有选中集上增删;
3904
+ * cascade=true 时先扩展选中集,再自底向上按层归并出最终勾选状态
3905
+ * (checkStrategy 为 all/parent/child 时分别保留全部/父节点/叶子选中)。
3906
+ * @param options - 勾选参数:当前选中与半选 key、本次勾选/取消的 key、
3907
+ * cascade、leafOnly 与 checkStrategy
3908
+ * @param treeMate - 树 mate 实例,提供层级节点表用于自底向上归并
3909
+ * @returns 最终的选中 key 列表与半选 key 列表
3910
+ */
3591
3911
  function getCheckedKeys(options, treeMate) {
3592
3912
  const { checkedKeys, keysToCheck, keysToUncheck, indeterminateKeys, cascade, leafOnly, checkStrategy } = options;
3593
3913
  if (!cascade) {
@@ -3655,6 +3975,14 @@ function getCheckedKeys(options, treeMate) {
3655
3975
  indeterminateKeys: Array.from(syntheticIndeterminateKeySet)
3656
3976
  };
3657
3977
  }
3978
+ /**
3979
+ * 计算扩展选中 key 集合:把每个选中节点连同其可达子孙并入集合,遇 disabled 子树停止下钻;
3980
+ * 子树未完全加载时,勾选流程抛出 SubtreeNotLoadedError,取消勾选流程安全截断。
3981
+ * @param checkedKeys - 当前选中的节点 key 列表
3982
+ * @param treeMate - 树 mate 实例,提供节点映射与 getChildren
3983
+ * @param isUnchecking - 是否处于取消勾选流程,决定未加载子树的处理方式
3984
+ * @returns 含全部级联选中节点的 key 集合
3985
+ */
3658
3986
  function getExtendedCheckedKeySet(checkedKeys, treeMate, isUnchecking = false) {
3659
3987
  const { treeNodeMap, getChildren } = treeMate;
3660
3988
  const visitedKeySet = /* @__PURE__ */ new Set();
@@ -3682,6 +4010,16 @@ function getExtendedCheckedKeySet(checkedKeys, treeMate, isUnchecking = false) {
3682
4010
  * MIT License · Copyright (c) 07akioni
3683
4011
  * 本地改动:无实质改动。
3684
4012
  */
4013
+ /**
4014
+ * 计算指定节点的路径信息:从目标节点沿父链上溯收集并反转,得到根到该节点的
4015
+ * keyPath 与 treeNodePath;ignored 节点返回空路径且 treeNode 为 null。
4016
+ * @param key - 目标节点 key;null/undefined 时返回空路径
4017
+ * @param root0 - 路径选项
4018
+ * @param root0.includeGroup - 是否在路径中包含 group 节点
4019
+ * @param root0.includeSelf - 是否在路径中包含自身节点
4020
+ * @param treeMate - 树 mate 实例,提供节点映射查询
4021
+ * @returns 合并后的路径对象(keyPath、treeNodePath 与 treeNode)
4022
+ */
3685
4023
  function getPath(key, { includeGroup = false, includeSelf = true }, treeMate) {
3686
4024
  const treeNodeMap = treeMate.treeNodeMap;
3687
4025
  let treeNode = key === null || key === void 0 ? null : treeNodeMap.get(key) ?? null;
@@ -3710,12 +4048,24 @@ function getPath(key, { includeGroup = false, includeSelf = true }, treeMate) {
3710
4048
  * MIT License · Copyright (c) 07akioni
3711
4049
  * 本地改动:无实质改动。
3712
4050
  */
4051
+ /**
4052
+ * 返回树中第一个可用节点(非 group、非 ignored、非 disabled);
4053
+ * 首节点不可用时沿 getNext 继续向后找。
4054
+ * @param nodes - 顶层节点列表
4055
+ * @returns 首个可用节点;整树不可用时返回 null
4056
+ */
3713
4057
  function getFirstAvailableNode(nodes) {
3714
4058
  if (nodes.length === 0) return null;
3715
4059
  const node = nodes[0];
3716
4060
  if (node.isGroup || node.ignored || node.disabled) return node.getNext();
3717
4061
  return node;
3718
4062
  }
4063
+ /**
4064
+ * 取同级下一兄弟节点;loop 为 true 时越过末尾循环回首节点,否则返回 null。
4065
+ * @param node - 当前节点
4066
+ * @param loop - 是否循环绕回
4067
+ * @returns 下一兄弟节点或 null
4068
+ */
3719
4069
  function rawGetNext(node, loop) {
3720
4070
  const sibs = node.siblings;
3721
4071
  const l = sibs.length;
@@ -3726,11 +4076,26 @@ function rawGetNext(node, loop) {
3726
4076
  return sibs[index + 1];
3727
4077
  }
3728
4078
  }
4079
+ /**
4080
+ * 沿 dir 方向游标移动到下一个可用节点(非 group、非 ignored;disabled 需 includeDisabled),
4081
+ * 遇 group 节点下钻其子节点;loop 为 true 时绕树循环一周回到起点即以起点为结果。
4082
+ * @param fromNode - 起始节点
4083
+ * @param dir - 移动方向:prev 向前、next 向后
4084
+ * @param root0 - 移动选项对象(GetPrevNextOptions)
4085
+ * @param root0.loop - 到达端点后是否循环绕回
4086
+ * @param root0.includeDisabled - 是否把 disabled 节点纳入游标可达范围
4087
+ * @returns 目标节点;无可达节点时返回 null
4088
+ */
3729
4089
  function move(fromNode, dir, { loop = false, includeDisabled = false } = {}) {
3730
4090
  const iterate = dir === "prev" ? rawGetPrev : rawGetNext;
3731
4091
  const getChildOptions = { reverse: dir === "prev" };
3732
4092
  let meet = false;
3733
4093
  let endNode = null;
4094
+ /**
4095
+ * 沿方向游标遍历,记录第一个遇到的可用节点。
4096
+ * @param node - 当前游标节点
4097
+ * @returns 无返回值
4098
+ */
3734
4099
  function traverse(node) {
3735
4100
  if (node === null) return;
3736
4101
  if (node === fromNode) {
@@ -3760,6 +4125,12 @@ function move(fromNode, dir, { loop = false, includeDisabled = false } = {}) {
3760
4125
  traverse(fromNode);
3761
4126
  return endNode;
3762
4127
  }
4128
+ /**
4129
+ * 取同级上一兄弟节点;loop 为 true 时越过开头循环回尾节点,否则返回 null。
4130
+ * @param node - 当前节点
4131
+ * @param loop - 是否循环绕回
4132
+ * @returns 上一兄弟节点或 null
4133
+ */
3763
4134
  function rawGetPrev(node, loop) {
3764
4135
  const sibs = node.siblings;
3765
4136
  const l = sibs.length;
@@ -3770,9 +4141,21 @@ function rawGetPrev(node, loop) {
3770
4141
  return sibs[index - 1];
3771
4142
  }
3772
4143
  }
4144
+ /**
4145
+ * 取节点的直接父节点。
4146
+ * @param node - 当前节点
4147
+ * @returns 父节点;根节点返回 null
4148
+ */
3773
4149
  function rawGetParent(node) {
3774
4150
  return node.parent;
3775
4151
  }
4152
+ /**
4153
+ * 取节点下第一个可用子节点(非 disabled、非 ignored,递归下钻 group);
4154
+ * reverse 为 true 时从末尾向前查找。
4155
+ * @param node - 父节点
4156
+ * @param options - 查找选项;reverse 表示从末尾向前查找
4157
+ * @returns 可用子节点;不存在时返回 null
4158
+ */
3776
4159
  function getChild(node, options = {}) {
3777
4160
  const { reverse = false } = options;
3778
4161
  const { children } = node;
@@ -3817,9 +4200,21 @@ const moveMethods = {
3817
4200
  * MIT License · Copyright (c) 07akioni
3818
4201
  * 本地改动:无实质改动。
3819
4202
  */
4203
+ /**
4204
+ * 按展开状态把节点树拍平为一维列表:group 节点总是下钻;普通节点仅在
4205
+ * 未提供 expandedKeys 或其 key 在展开集合内时下钻;ignored 节点不下钻。
4206
+ * @param treeNodes - 待拍平的节点树
4207
+ * @param expandedKeys - 已展开节点的 key 列表;缺省视为全部展开
4208
+ * @returns 深度优先顺序的一维节点列表
4209
+ */
3820
4210
  function flatten(treeNodes, expandedKeys) {
3821
4211
  const expandedKeySet = expandedKeys ? new Set(expandedKeys) : void 0;
3822
4212
  const flattenedNodes = [];
4213
+ /**
4214
+ * 深度优先收集当前层节点并按展开状态决定是否下钻。
4215
+ * @param treeNodes - 当前层的节点列表
4216
+ * @returns 无返回值
4217
+ */
3823
4218
  function traverse(treeNodes) {
3824
4219
  treeNodes.forEach((treeNode) => {
3825
4220
  flattenedNodes.push(treeNode);
@@ -3838,6 +4233,12 @@ function flatten(treeNodes, expandedKeys) {
3838
4233
  * MIT License · Copyright (c) 07akioni
3839
4234
  * 本地改动:无实质改动。
3840
4235
  */
4236
+ /**
4237
+ * 判断 child 是否为 parent 的后代(含自身),沿父链逐级上溯比对 key。
4238
+ * @param parent - 祖先节点
4239
+ * @param child - 待判定的节点,可为 null 或 undefined
4240
+ * @returns child 位于 parent 子树内(含相等)时返回 true
4241
+ */
3841
4242
  function contains(parent, child) {
3842
4243
  const parentKey = parent.key;
3843
4244
  while (child) {
@@ -3853,6 +4254,18 @@ function contains(parent, child) {
3853
4254
  * MIT License · Copyright (c) 07akioni
3854
4255
  * 本地改动:process.env.NODE_ENV 守卫替换为 import.meta.env?.DEV。
3855
4256
  */
4257
+ /**
4258
+ * 递归构建树节点:以 nodeProto 为原型创建实例,回填 siblings/level/index/父子
4259
+ * 等结构信息,并把每个节点登记进 treeNodeMap 与 levelTreeNodeMap。
4260
+ * @param rawNodes - 当前层级的原始节点数组
4261
+ * @param treeNodeMap - key → 节点 的全量映射(原地写入)
4262
+ * @param levelTreeNodeMap - 层级 → 该层节点列表 的映射(原地写入)
4263
+ * @param nodeProto - 节点实例共享的原型(惰性 getter 与移动方法)
4264
+ * @param getChildren - 取子节点的函数
4265
+ * @param parent - 父节点;根层调用时为 null
4266
+ * @param level - 当前层级,根为 0
4267
+ * @returns 当前层级构建好的节点数组
4268
+ */
3856
4269
  function createTreeNodes(rawNodes, treeNodeMap, levelTreeNodeMap, nodeProto, getChildren, parent = null, level = 0) {
3857
4270
  const treeNodes = [];
3858
4271
  rawNodes.forEach((rawNode, index) => {
@@ -3876,6 +4289,14 @@ function createTreeNodes(rawNodes, treeNodeMap, levelTreeNodeMap, nodeProto, get
3876
4289
  });
3877
4290
  return treeNodes;
3878
4291
  }
4292
+ /**
4293
+ * 创建 TreeMate 实例:以 options 覆盖默认的取 key/子节点/禁用等策略,构建共享节点原型
4294
+ * (惰性 getter 与移动、contains 方法),并暴露节点查询、路径、展开拍平与勾选级联计算等 API。
4295
+ * @param rawNodes - 原始节点树
4296
+ * @param options - 自定义策略(getKey/getChildren/getDisabled/getIgnored/getIsGroup、
4297
+ * ignoreEmptyChildren 等);缺省走默认实现
4298
+ * @returns TreeMate 实例
4299
+ */
3879
4300
  function createTreeMate(rawNodes, options = {}) {
3880
4301
  const treeNodeMap = /* @__PURE__ */ new Map();
3881
4302
  const levelTreeNodeMap = /* @__PURE__ */ new Map();
@@ -4011,6 +4432,11 @@ function createTreeMate(rawNodes, options = {}) {
4011
4432
  * 计算键盘移动后的活动节点 key。
4012
4433
  * - 仅在非 disabled 节点间移动;loop 默认 true(末尾循环回首行)。
4013
4434
  * - activeKey 为 null 或不在候选序列时,ArrowDown 从首行开始、ArrowUp 从末行开始。
4435
+ * @param flattened - 已展开的扁平节点列表
4436
+ * @param activeKey - 当前活动节点 key;null 表示尚无活动节点
4437
+ * @param key - 本次键盘操作(ArrowDown/ArrowUp/Home/End)
4438
+ * @param options - 选项;loop 控制到端点后是否循环绕回(默认 true)
4439
+ * @returns 移动后的活动节点 key;无可用候选节点时返回 null
4014
4440
  */
4015
4441
  function nextActiveKey(flattened, activeKey, key, options) {
4016
4442
  const loop = options?.loop ?? true;
@@ -5194,6 +5620,12 @@ const _sfc_main$50 = /*@__PURE__*/ defineComponent({
5194
5620
  });
5195
5621
  //#endregion
5196
5622
  //#region src/components/form-render/widgets/tree.ts
5623
+ /**
5624
+ * treeSelect widget:树形下拉选择,options 原名直传(TreeOption 命名穿透),
5625
+ * placeholder 先用 item 级回退(I1),options.placeholder 展开时覆盖。
5626
+ * @param options - widget 选项,原名直传给 TreeSelect,placeholder 以 item 级缺省兜底
5627
+ * @returns 渲染函数,接收渲染上下文并产出 TreeSelect vnode
5628
+ */
5197
5629
  function renderTreeSelectItem(options) {
5198
5630
  const { placeholder, ...rest } = options;
5199
5631
  return (ctx) => h(_sfc_main$50, {
@@ -5203,6 +5635,12 @@ function renderTreeSelectItem(options) {
5203
5635
  ...ctx.item.componentProps
5204
5636
  });
5205
5637
  }
5638
+ /**
5639
+ * cascader widget:级联选择,绑定与 treeSelect 一致(modelValue 受控形态),
5640
+ * placeholder 先用 item 级回退(I1),options.placeholder 展开时覆盖。
5641
+ * @param options - widget 选项,原名直传给 Cascader,placeholder 以 item 级缺省兜底
5642
+ * @returns 渲染函数,接收渲染上下文并产出 Cascader vnode
5643
+ */
5206
5644
  function renderCascaderItem(options) {
5207
5645
  const { placeholder, ...rest } = options;
5208
5646
  return (ctx) => h(_sfc_main$8, {
@@ -5218,6 +5656,7 @@ function renderCascaderItem(options) {
5218
5656
  * widget 注册表:`r.input({...})` 等柯里化工厂的运行时对象。
5219
5657
  * 文件按绑定形态聚合:input / model-value(modelValue 系)/ boolean(checked 系)/
5220
5658
  * value(radioGroup/slider)/ select(多子组件组装)。
5659
+ * @returns 各 widget 类型的柯里化工厂映射(render 为恒等直通),供 FormRender 渲染时调用
5221
5660
  */
5222
5661
  function widgetRenders() {
5223
5662
  return {
@@ -5315,8 +5754,11 @@ const _sfc_main$25 = /*@__PURE__*/ defineComponent({
5315
5754
  if (import.meta.env.DEV && actions) {
5316
5755
  if (props.searchable !== void 0 || props.submitable !== void 0 || props.resetable !== void 0 || props.cancelable !== void 0 || props.searchText !== void 0 || props.submitText !== void 0 || props.resetText !== void 0) console.warn("[tu-design] <FormRender> definition.actions 与按钮 props 同传,已按 actions 渲染。");
5317
5756
  }
5318
- /** I4:校验失败时 isFieldsValid=false,不 emit;成功后才 emit(事件回调中一次性读取不受 S1 限制)。
5319
- * 校验语义单点化(R30):definition 存在时复用 definition.submit();拆分式 :form + :items 走内联逻辑 */
5757
+ /**
5758
+ * I4:校验失败时 isFieldsValid=false,不 emit;成功后才 emit(事件回调中一次性读取不受 S1 限制)。
5759
+ * 校验语义单点化(R30):definition 存在时复用 definition.submit();拆分式 :form + :items 走内联逻辑
5760
+ * @param mode - 提交语义:"search" 触发 search 事件(查询按钮),"submit" 触发 submit 事件
5761
+ */
5320
5762
  async function submit(mode) {
5321
5763
  if (!instance) return;
5322
5764
  let valid;
@@ -5399,6 +5841,8 @@ const _sfc_main$25 = /*@__PURE__*/ defineComponent({
5399
5841
  * - `defaultValues` 从 `items[].default` 派生(值或同步工厂,缺省 null)——单一真相源;
5400
5842
  * - 显式泛型 `useForm<T>`,保住 onSubmit `{ value: T }` 全链路推断;
5401
5843
  * - 须在组件 setup 中调用(TanStack useForm 内部 `onMounted(formApi.mount)`)。
5844
+ * @param options - 表单选项:字段定义、校验 schema、提交回调、按钮预设七项与 TanStack 透传项
5845
+ * @returns 表单渲染 definition(items + form + resetToDefaults + submit + actions?)
5402
5846
  */
5403
5847
  function useFormRender(options) {
5404
5848
  const { items, schema, onSubmit, formOptions, searchable, submitable, resetable, cancelable, searchText, submitText, resetText } = options;
@@ -5443,6 +5887,8 @@ function useFormRender(options) {
5443
5887
  * - `actions` 按钮预设(searchable 等七项直传):存在时 `<FormRender>` 组件按钮 props 全量忽略(A1 块级互斥)。
5444
5888
  *
5445
5889
  * 须在组件 setup 中调用(TanStack useForm 约束)。
5890
+ * @param config - 表单配置:字段定义、校验 schema、提交回调、按钮预设七项与 TanStack 透传项
5891
+ * @returns 表单渲染 definition(items + form + resetToDefaults + submit + actions?),直接传给 <FormRender>
5446
5892
  */
5447
5893
  function defineForm(config) {
5448
5894
  return useFormRender(config);
@@ -6646,8 +7092,18 @@ const _sfc_main$43 = /*@__PURE__*/ defineComponent({
6646
7092
  });
6647
7093
  //#endregion
6648
7094
  //#region src/components/table-render/column-renders.ts
7095
+ /**
7096
+ * 两位补零
7097
+ * @param value - 数字(月/日/时/分/秒)
7098
+ * @returns 补零后的两位字符串
7099
+ */
6649
7100
  const pad = (value) => String(value).padStart(2, "0");
6650
- /** 迷你日期令牌格式化,不引入 date-fns;非法输入原样返回 */
7101
+ /**
7102
+ * 迷你日期令牌格式化,不引入 date-fns;非法输入原样返回
7103
+ * @param input - 单元格原始值(Date 或可构造 Date 的字符串/数字)
7104
+ * @param pattern - 令牌模板(支持 yyyy/MM/dd/HH/mm/ss)
7105
+ * @returns 格式化后的文本;输入非法时原样返回
7106
+ */
6651
7107
  function formatDate(input, pattern) {
6652
7108
  const date = input instanceof Date ? input : new Date(input);
6653
7109
  if (Number.isNaN(date.getTime())) return input;
@@ -6665,6 +7121,7 @@ function formatDate(input, pattern) {
6665
7121
  * 内置列渲染器工厂(对标 x-render table-columns,v1:dict/date/currency/serial/button)。
6666
7122
  * 返回值直接填入 TableColumnOptions.render;column 参数用于读取字段值。
6667
7123
  * 与 FormRender widget 的 r.xxx() 范式共词根(D10)。
7124
+ * @returns 各内置渲染器集合(render/dict/date/currency/serial/button)
6668
7125
  */
6669
7126
  function columnRenders() {
6670
7127
  return {
@@ -6704,7 +7161,7 @@ function columnRenders() {
6704
7161
  button(items) {
6705
7162
  return (record, index) => {
6706
7163
  if (items.length === 0) return "";
6707
- return h("div", { class: "flex items-center gap-1" }, items.map((item) => {
7164
+ return h("div", { class: "inline-flex items-center gap-1" }, items.map((item) => {
6708
7165
  const action = typeof item === "string" ? { text: item } : item;
6709
7166
  return h(_sfc_main$5, {
6710
7167
  size: "sm",
@@ -6842,7 +7299,13 @@ const SELECTION_CELL = "__selection__";
6842
7299
  const PAGE_TABLE_FILL_KEY = "tu-design:page-table-fill";
6843
7300
  //#endregion
6844
7301
  //#region src/components/table-render/sticky.ts
6845
- /** sticky 定位样式;head 为 true 时 z-index 高于表体(表头压住表体 sticky) */
7302
+ /**
7303
+ * sticky 定位样式;head 为 true 时 z-index 高于表体(表头压住表体 sticky)
7304
+ * @param sticky - 列 key → sticky 信息的映射
7305
+ * @param key - 列 key
7306
+ * @param head - 是否为表头单元格(true 使用更高的 --z-sticky-head)
7307
+ * @returns inline style 对象;列非 sticky 时返回 undefined
7308
+ */
6846
7309
  function stickyStyle(sticky, key, head = false) {
6847
7310
  const info = sticky.get(key);
6848
7311
  if (!info) return void 0;
@@ -6852,7 +7315,12 @@ function stickyStyle(sticky, key, head = false) {
6852
7315
  zIndex: head ? "var(--z-sticky-head)" : "var(--z-sticky)"
6853
7316
  };
6854
7317
  }
6855
- /** sticky 底色(防滚动透出)与交界分隔边框 */
7318
+ /**
7319
+ * sticky 底色(防滚动透出)与交界分隔边框
7320
+ * @param sticky - 列 key → sticky 信息的映射
7321
+ * @param key - 列 key
7322
+ * @returns class 列表(未命中项为空串);列非 sticky 时返回 undefined
7323
+ */
6856
7324
  function stickyClass(sticky, key) {
6857
7325
  const info = sticky.get(key);
6858
7326
  if (!info) return void 0;
@@ -6921,8 +7389,13 @@ const _sfc_main$53 = /*@__PURE__*/ defineComponent({
6921
7389
  const value = line.cells[index];
6922
7390
  return isVNode(value) ? "" : String(value ?? "");
6923
7391
  }
6924
- /** ellipsis: "tooltip" 的单元格内容:默认插槽承载截断内容(触发元素本体,不额外包裹),content 显示完整文本。
6925
- * VNode(render 工厂)单元格经 cloneVNode 复制进触发位(VNode 不可二次挂载)。 */
7392
+ /**
7393
+ * ellipsis: "tooltip" 的单元格内容:默认插槽承载截断内容(触发元素本体,不额外包裹),content 显示完整文本。
7394
+ * VNode(render 工厂)单元格经 cloneVNode 复制进触发位(VNode 不可二次挂载)。
7395
+ * @param value - 单元格原始内容(VNode 或文本)
7396
+ * @param text - 用于 tooltip content 与纯文本兜底的完整文本
7397
+ * @returns 包裹 Tooltip 后的渲染结果
7398
+ */
6926
7399
  function tooltipCell(value, text) {
6927
7400
  const trigger = isVNode(value) ? cloneVNode(value) : h("span", { class: "block truncate" }, text);
6928
7401
  return h(_sfc_main$49, {
@@ -6940,7 +7413,7 @@ const _sfc_main$53 = /*@__PURE__*/ defineComponent({
6940
7413
  createCommentVNode(" 选择单元格:阻断冒泡避免触发行 row-click(S5);radio 为原生控件 "),
6941
7414
  props.selection ? (openBlock(), createElementBlock("td", {
6942
7415
  key: 0,
6943
- class: normalizeClass(["w-12 p-2 align-middle", unref(stickyClass)(props.sticky, unref(SELECTION_CELL))]),
7416
+ class: normalizeClass(["w-12 p-2 text-center align-middle", unref(stickyClass)(props.sticky, unref(SELECTION_CELL))]),
6944
7417
  style: normalizeStyle(unref(stickyStyle)(props.sticky, unref(SELECTION_CELL), false)),
6945
7418
  onClick: _cache[2] || (_cache[2] = withModifiers(() => {}, ["stop"]))
6946
7419
  }, [props.selection === "radio" ? (openBlock(), createElementBlock("input", {
@@ -6967,7 +7440,7 @@ const _sfc_main$53 = /*@__PURE__*/ defineComponent({
6967
7440
  key: props.columns[index].key,
6968
7441
  class: normalizeClass(["p-2 align-middle", [unref(stickyClass)(props.sticky, props.columns[index].key), { truncate: props.columns[index].ellipsis === true }]]),
6969
7442
  title: props.columns[index].ellipsis === true ? cellText(props.line, index) : void 0,
6970
- style: normalizeStyle([{ textAlign: props.columns[index].align }, unref(stickyStyle)(props.sticky, props.columns[index].key, false)]),
7443
+ style: normalizeStyle([{ textAlign: props.columns[index].align ?? "center" }, unref(stickyStyle)(props.sticky, props.columns[index].key, false)]),
6971
7444
  onClick: ($event) => emit("cell-click", props.columns[index].key, $event)
6972
7445
  }, [createCommentVNode(" 首列(tree 启用时):depth 缩进 + 展开 caret(点击 stop 避免误触发行点击) "), props.treeIndent !== void 0 && index === 0 ? (openBlock(), createElementBlock("span", {
6973
7446
  key: 0,
@@ -6998,11 +7471,18 @@ const DEFAULT_PAGE_SIZE_OPTS = [
6998
7471
  50,
6999
7472
  100
7000
7473
  ];
7001
- /** 数值配置防御:受控 getter(组件层)与数值配置(defineTable 层)同字段共存时只认数字 */
7474
+ /**
7475
+ * 数值配置防御:受控 getter(组件层)与数值配置(defineTable 层)同字段共存时只认数字
7476
+ * @param value - 待判定的配置值
7477
+ * @returns 值为数字时原样返回,否则返回 undefined
7478
+ */
7002
7479
  function numericOption(value) {
7003
7480
  return typeof value === "number" ? value : void 0;
7004
7481
  }
7005
- /** DEV 兜底提示:生产构建静默,只留可读的降级行为(R1–R7) */
7482
+ /**
7483
+ * DEV 兜底提示:生产构建静默,只留可读的降级行为(R1–R7)
7484
+ * @param message - 提示文本
7485
+ */
7006
7486
  function warn(message) {
7007
7487
  if (import.meta.env.DEV) console.warn(`[tu-design] <TableRender> ${message}`);
7008
7488
  }
@@ -7011,6 +7491,9 @@ function warn(message) {
7011
7491
  *
7012
7492
  * 状态真相源是 TanStack 引擎(pageIndex 为 0-based),
7013
7493
  * `page`/`sort` 是对外的 1-based 只读投影,由 watch 同步。
7494
+ * @param options - 表格配置:列定义、数据源(静态 data 或服务端 onLoad)、分页排序、
7495
+ * 行选择、树形、列显隐、搜索表单等
7496
+ * @returns 表格渲染定义(含只读投影与实例动作),供 TableRender 组件消费
7014
7497
  */
7015
7498
  function useTableRender(options) {
7016
7499
  const columns = options.columns;
@@ -7030,7 +7513,10 @@ function useTableRender(options) {
7030
7513
  }
7031
7514
  const childrenKey = tree?.childrenKey ?? "children";
7032
7515
  let search;
7033
- /** search 唯一装配入口:静态模式 / 缺 form·items 时 DEV 警告并忽略 */
7516
+ /**
7517
+ * search 唯一装配入口:静态模式 / 缺 form·items 时 DEV 警告并忽略
7518
+ * @param next - 待装配的搜索表单定义,undefined 表示移除
7519
+ */
7034
7520
  function applySearch(next) {
7035
7521
  if (next === void 0) {
7036
7522
  search = void 0;
@@ -7049,7 +7535,10 @@ function useTableRender(options) {
7049
7535
  search = next;
7050
7536
  }
7051
7537
  applySearch(options.search);
7052
- /** 拆分式/组件级装配口:definition 未配置 search 时由 TableRender 回填 prop(对齐 setRowKey) */
7538
+ /**
7539
+ * 拆分式/组件级装配口:definition 未配置 search 时由 TableRender 回填 prop(对齐 setRowKey)
7540
+ * @param next - 待回填的搜索表单定义
7541
+ */
7053
7542
  function setSearch(next) {
7054
7543
  if (search || !next) return;
7055
7544
  applySearch(next);
@@ -7090,12 +7579,20 @@ function useTableRender(options) {
7090
7579
  selectedKeys.value = keys;
7091
7580
  selectionRows.value = [...keys].map((key) => selectionSnapshot.get(String(key)) ?? { [rowKey.value]: key });
7092
7581
  }
7093
- /** 选中集写入的唯一入口:赋受控 state + 重建对外投影 */
7582
+ /**
7583
+ * 选中集写入的唯一入口:赋受控 state + 重建对外投影
7584
+ * @param next - TanStack 行选择状态(row id → 是否选中)
7585
+ */
7094
7586
  function applyRowSelection(next) {
7095
7587
  rowSelectionState.value = next;
7096
7588
  selectionEmitSafe();
7097
7589
  }
7098
- /** 行主键 → TanStack row id;rowKey 缺失时退化为索引(仅非选择场景可达,S1) */
7590
+ /**
7591
+ * 行主键 → TanStack row id;rowKey 缺失时退化为索引(仅非选择场景可达,S1)
7592
+ * @param record - 行记录
7593
+ * @param index - 行索引(rowKey 缺失时的退化 id 来源)
7594
+ * @returns 稳定的行标识字符串
7595
+ */
7099
7596
  function rowIdOf(record, index) {
7100
7597
  const key = rowKey.value;
7101
7598
  const value = key ? record[key] : void 0;
@@ -7192,7 +7689,9 @@ function useTableRender(options) {
7192
7689
  table.setPageIndex(0);
7193
7690
  }
7194
7691
  /** 排序应用的唯一管线:服务端模式归位第 1 页(R8)+ 投影落值 + TanStack setSorting。
7195
- * 受控 sort 的外部同步与此共用(直接 setSorting 会漏服务端重载) */
7692
+ * 受控 sort 的外部同步与此共用(直接 setSorting 会漏服务端重载)
7693
+ * @param next - 目标排序(key + direction),undefined 表示取消排序
7694
+ */
7196
7695
  function applySort(next) {
7197
7696
  if (serverMode && page.pageIndex !== 1) setPageIndex(1);
7198
7697
  sort.value = next;
@@ -7201,7 +7700,10 @@ function useTableRender(options) {
7201
7700
  desc: next.direction === "desc"
7202
7701
  }] : []);
7203
7702
  }
7204
- /** 排序三态:无 → asc → desc → 取消;非 sortable 列为空操作(R8) */
7703
+ /**
7704
+ * 排序三态:无 → asc → desc → 取消;非 sortable 列为空操作(R8)
7705
+ * @param key - 目标列 key
7706
+ */
7205
7707
  function toggleSort(key) {
7206
7708
  if (!columns.some((column) => column.key === key && column.sortable === true)) return;
7207
7709
  const current = sort.value;
@@ -7274,7 +7776,11 @@ function useTableRender(options) {
7274
7776
  setSelection(next);
7275
7777
  }, { immediate: true });
7276
7778
  let emptyVisibleWarned = false;
7277
- /** 规范化:未知 key 静默忽略、按 columns 原序、空数组钳制为首列(R24,warn 一次) */
7779
+ /**
7780
+ * 规范化:未知 key 静默忽略、按 columns 原序、空数组钳制为首列(R24,warn 一次)
7781
+ * @param keys - 目标可见列 key 列表(任意顺序,可含未知 key)
7782
+ * @returns 规范化后的可见列 key 列表(columns 原序)
7783
+ */
7278
7784
  function normalizeVisibleKeys(keys) {
7279
7785
  const known = columns.filter((column) => keys.includes(column.key)).map((column) => column.key);
7280
7786
  if (known.length > 0) return known;
@@ -7295,7 +7801,10 @@ function useTableRender(options) {
7295
7801
  return raw ? normalizeVisibleKeys(raw) : void 0;
7296
7802
  })();
7297
7803
  const visibleKeysInternal = ref(controlledVisibleKeys() ? normalizeVisibleKeys(controlledVisibleKeys()) : parsedDefaultVisibleKeys ?? columns.map((column) => column.key));
7298
- /** 列显隐动作(面板交互/程序化):规范化后更新统一投影 */
7804
+ /**
7805
+ * 列显隐动作(面板交互/程序化):规范化后更新统一投影
7806
+ * @param keys - 目标可见列 key 列表
7807
+ */
7299
7808
  function setVisibleKeys(keys) {
7300
7809
  visibleKeysInternal.value = normalizeVisibleKeys(keys);
7301
7810
  }
@@ -7318,7 +7827,10 @@ function useTableRender(options) {
7318
7827
  if (resetPage) setPageIndex(1);
7319
7828
  syncData();
7320
7829
  }
7321
- /** 程序化设置选中集;不存在的 key 保留进入 dirtyKeys(S12);不可选行被过滤(对齐 S5) */
7830
+ /**
7831
+ * 程序化设置选中集;不存在的 key 保留进入 dirtyKeys(S12);不可选行被过滤(对齐 S5)
7832
+ * @param keys - 目标选中行的 key 列表(整体替换现有选中集)
7833
+ */
7322
7834
  function setSelection(keys) {
7323
7835
  const next = {};
7324
7836
  for (const key of keys) {
@@ -7344,7 +7856,10 @@ function useTableRender(options) {
7344
7856
  [key]: true
7345
7857
  });
7346
7858
  }
7347
- /** 拆分式装配口:TableRender setup 时回传组件 rowKey(S1) */
7859
+ /**
7860
+ * 拆分式装配口:TableRender setup 时回传组件 rowKey(S1)
7861
+ * @param key - 行主键字段名
7862
+ */
7348
7863
  function setRowKey(key) {
7349
7864
  if (rowKey.value === key) return;
7350
7865
  rowKey.value = key;
@@ -7573,7 +8088,10 @@ const _sfc_main$44 = /*@__PURE__*/ defineComponent({
7573
8088
  watch(() => props.visibleKeys, (next) => {
7574
8089
  if (props.definition && next !== void 0) instance.setVisibleKeys(next);
7575
8090
  }, { immediate: true });
7576
- /** 当前搜索表单值快照(浅拷贝;无 search 时为空对象) */
8091
+ /**
8092
+ * 当前搜索表单值快照(浅拷贝;无 search 时为空对象)
8093
+ * @returns 表单值快照
8094
+ */
7577
8095
  function searchValues() {
7578
8096
  return search ? { ...search.form.state.values } : {};
7579
8097
  }
@@ -7615,7 +8133,11 @@ const _sfc_main$44 = /*@__PURE__*/ defineComponent({
7615
8133
  function isColumnVisible(key) {
7616
8134
  return visibleKeySet.value.has(key);
7617
8135
  }
7618
- /** 最少一列(R20):唯一可见列不可隐藏 */
8136
+ /**
8137
+ * 最少一列(R20):唯一可见列不可隐藏
8138
+ * @param key - 列 key
8139
+ * @returns 是否允许隐藏该列
8140
+ */
7619
8141
  function canHideColumn(key) {
7620
8142
  return !(instance.visibleKeys.value.length <= 1 && visibleKeySet.value.has(key));
7621
8143
  }
@@ -7690,7 +8212,10 @@ const _sfc_main$44 = /*@__PURE__*/ defineComponent({
7690
8212
  return sum;
7691
8213
  });
7692
8214
  /** 列宽 inline style 值(R33):数字补 px 单位——Vue :style 不自动加单位,
7693
- * 裸数字会被浏览器当非法 CSS 值丢弃,列宽即失效;字符串视为已带单位原样输出。 */
8215
+ * 裸数字会被浏览器当非法 CSS 值丢弃,列宽即失效;字符串视为已带单位原样输出。
8216
+ * @param width - 列宽配置
8217
+ * @returns 可直接用于 :style 的 CSS 宽度值;未配置返回 undefined
8218
+ */
7694
8219
  function widthOf(width) {
7695
8220
  return typeof width === "number" ? `${width}px` : width;
7696
8221
  }
@@ -7701,7 +8226,11 @@ const _sfc_main$44 = /*@__PURE__*/ defineComponent({
7701
8226
  function onHeaderSelect(checked) {
7702
8227
  instance.table.toggleAllPageRowsSelected(checked);
7703
8228
  }
7704
- /** 行选择控件切换;radio 不可取消由引擎 S4 守卫,不选中态点击传 checked=true */
8229
+ /**
8230
+ * 行选择控件切换;radio 不可取消由引擎 S4 守卫,不选中态点击传 checked=true
8231
+ * @param line - 行数据(含行 key)
8232
+ * @param checked - 目标选中态
8233
+ */
7705
8234
  function onRowSelect(line, checked) {
7706
8235
  instance.toggleRowSelected(line.key, checked);
7707
8236
  }
@@ -7731,7 +8260,12 @@ const _sfc_main$44 = /*@__PURE__*/ defineComponent({
7731
8260
  const tree = instance.tree;
7732
8261
  const treeIndent = tree?.indentSize ?? 16;
7733
8262
  let missingRowKeyWarned = false;
7734
- /** 行主键:rowKey 字段缺失时以行索引兜底(R3) */
8263
+ /**
8264
+ * 行主键:rowKey 字段缺失时以行索引兜底(R3)
8265
+ * @param record - 行记录
8266
+ * @param index - 行索引(兜底来源)
8267
+ * @returns 稳定的行主键字符串
8268
+ */
7735
8269
  function rowKeyOf(record, index) {
7736
8270
  const value = record[props.rowKey];
7737
8271
  if (value === void 0 || value === null) {
@@ -7794,12 +8328,18 @@ const _sfc_main$44 = /*@__PURE__*/ defineComponent({
7794
8328
  return items.length === 0 ? 0 : Math.max(0, virtualTotal.value - items[items.length - 1].end);
7795
8329
  });
7796
8330
  /** 行高动态测量:measureElement 读 data-index 把实测高度写回(行内容高度可变,不假设固定行高)。
7797
- * 行组件为函数 ref,拿到的是组件实例,需经 $el 取真实 tr。 */
8331
+ * 行组件为函数 ref,拿到的是组件实例,需经 $el 取真实 tr。
8332
+ * @param node - 函数 ref 收到的行元素或组件实例
8333
+ */
7798
8334
  function measureRow(node) {
7799
8335
  const el = node instanceof Element ? node : node?.$el;
7800
8336
  if (el instanceof Element) virtualizerRef?.value.measureElement(el);
7801
8337
  }
7802
- /** aria-sort 仅在该列当前被排序时标注(R16) */
8338
+ /**
8339
+ * aria-sort 仅在该列当前被排序时标注(R16)
8340
+ * @param column - 列配置
8341
+ * @returns 当前排序方向对应的 aria-sort 值;未排序返回 undefined
8342
+ */
7803
8343
  function ariaSort(column) {
7804
8344
  if (instance.sort.value?.key !== column.key) return void 0;
7805
8345
  return instance.sort.value.direction === "asc" ? "ascending" : "descending";
@@ -7984,7 +8524,7 @@ const _sfc_main$44 = /*@__PURE__*/ defineComponent({
7984
8524
  hasSelection.value ? (openBlock(), createElementBlock("th", {
7985
8525
  key: 0,
7986
8526
  scope: "col",
7987
- class: normalizeClass(["h-10 w-12 px-2 align-middle font-medium text-muted-foreground", [unref(stickyClass)(stickyOf.value, unref(SELECTION_CELL)), unref(theadThClass)]]),
8527
+ class: normalizeClass(["h-10 w-12 px-2 text-center align-middle font-medium text-muted-foreground", [unref(stickyClass)(stickyOf.value, unref(SELECTION_CELL)), unref(theadThClass)]]),
7988
8528
  style: normalizeStyle([{ width: `${selection.value.width}px` }, unref(stickyStyle)(stickyOf.value, unref(SELECTION_CELL), true)])
7989
8529
  }, [selection.value.type === "checkbox" ? (openBlock(), createBlock(unref(_sfc_main$9), {
7990
8530
  key: 0,
@@ -7999,7 +8539,7 @@ const _sfc_main$44 = /*@__PURE__*/ defineComponent({
7999
8539
  class: normalizeClass(["h-10 px-2 align-middle font-medium text-muted-foreground", [unref(stickyClass)(stickyOf.value, column.key), unref(theadThClass)]]),
8000
8540
  style: normalizeStyle([{
8001
8541
  width: widthOf(column.width),
8002
- textAlign: column.align
8542
+ textAlign: column.align ?? "center"
8003
8543
  }, unref(stickyStyle)(stickyOf.value, column.key, true)]),
8004
8544
  "aria-sort": ariaSort(column)
8005
8545
  }, [column.sortable ? (openBlock(), createElementBlock("button", {
@@ -8017,13 +8557,13 @@ const _sfc_main$44 = /*@__PURE__*/ defineComponent({
8017
8557
  "data-skeleton": ""
8018
8558
  }, [hasSelection.value ? (openBlock(), createElementBlock("td", {
8019
8559
  key: 0,
8020
- class: normalizeClass(["p-2 align-middle", unref(stickyClass)(stickyOf.value, unref(SELECTION_CELL))]),
8560
+ class: normalizeClass(["p-2 text-center align-middle", unref(stickyClass)(stickyOf.value, unref(SELECTION_CELL))]),
8021
8561
  style: normalizeStyle(unref(stickyStyle)(stickyOf.value, unref(SELECTION_CELL), false))
8022
8562
  }, [createVNode(unref(_sfc_main$39), { class: "size-4" })], 6)) : createCommentVNode("v-if", true), (openBlock(true), createElementBlock(Fragment, null, renderList(visibleColumns.value, (column) => {
8023
8563
  return openBlock(), createElementBlock("td", {
8024
8564
  key: column.key,
8025
8565
  class: normalizeClass(["p-2 align-middle", unref(stickyClass)(stickyOf.value, column.key)]),
8026
- style: normalizeStyle([{ textAlign: column.align }, unref(stickyStyle)(stickyOf.value, column.key, false)])
8566
+ style: normalizeStyle([{ textAlign: column.align ?? "center" }, unref(stickyStyle)(stickyOf.value, column.key, false)])
8027
8567
  }, [createVNode(unref(_sfc_main$39), { class: "h-4 w-full" })], 6);
8028
8568
  }), 128))]);
8029
8569
  }), 64)) : showError.value ? (openBlock(), createElementBlock(Fragment, { key: 1 }, [createCommentVNode(" 错误态:error 优先于正常数据;插槽可自定义(slot props { error, retry }) "), createElementVNode("tr", _hoisted_11, [createElementVNode("td", {
@@ -8151,6 +8691,8 @@ const _sfc_main$44 = /*@__PURE__*/ defineComponent({
8151
8691
  * 列定义辅助:补全泛型推导,便于把列配置抽到独立文件。
8152
8692
  *
8153
8693
  * 纯类型辅助,原样返回入参——裸数组同样可直接传给 defineTable(无需此函数)。
8694
+ * @param columns - 列配置数组
8695
+ * @returns 原样返回的列配置数组
8154
8696
  */
8155
8697
  function defineColumns(columns) {
8156
8698
  return columns;
@@ -8162,6 +8704,8 @@ function defineColumns(columns) {
8162
8704
  *
8163
8705
  * 返回值直接传给 `<TableRender :definition="def" />`;
8164
8706
  * 须在组件 setup 中调用(TanStack useVueTable 约束)。
8707
+ * @param config - 表格配置:列定义、数据源(静态 data 或服务端 onLoad)、分页排序、行选择等
8708
+ * @returns 表格渲染定义,直接传给 TableRender 组件的 definition prop
8165
8709
  */
8166
8710
  function defineTable(config) {
8167
8711
  return useTableRender(config);
@@ -8632,6 +9176,8 @@ let providerMounted = false;
8632
9176
  * 按 props 重建单例内部 store(ToastProvider 挂载时调用)。
8633
9177
  * 配置未变化时复用现有 store,避免 Provider 重挂载丢弃排队中的 toast。
8634
9178
  * 返回 store 供 Provider 的 <Toaster> 渲染使用。
9179
+ * @param props - Provider 传入的 placement/duration/max 配置,缺省项回退内置默认值
9180
+ * @returns 当前 toast store 实例
8635
9181
  */
8636
9182
  function __configureToaster(props = {}) {
8637
9183
  const next = {
@@ -8643,15 +9189,25 @@ function __configureToaster(props = {}) {
8643
9189
  current = createToaster(next);
8644
9190
  return current;
8645
9191
  }
8646
- /** 标记 Provider 已挂载/已卸载(Provider 生命周期与测试用) */
9192
+ /**
9193
+ * 标记 Provider 已挂载/已卸载(Provider 生命周期与测试用)。
9194
+ * @param value - true 表示 Provider 已挂载,false 表示已卸载
9195
+ */
8647
9196
  function __setToastMounted(value) {
8648
9197
  providerMounted = value;
8649
9198
  }
9199
+ /**
9200
+ * Provider 未挂载时在开发环境输出告警,提醒先在应用根部挂载 <ToastProvider>。
9201
+ */
8650
9202
  function warnIfUnmounted() {
8651
9203
  if (!providerMounted && import.meta.env.DEV) console.warn("[tu-design] 在 <ToastProvider> 挂载前调用了 toast。请在应用根部挂载一次 <ToastProvider>,否则提示不会渲染。");
8652
9204
  }
8653
9205
  const toastApi = {
8654
- /** 成功提示 */
9206
+ /**
9207
+ * 成功提示。
9208
+ * @param options - toast 配置(标题、描述、时长等)
9209
+ * @returns 该条 toast 的创建结果,可用于后续控制
9210
+ */
8655
9211
  success: (options) => {
8656
9212
  warnIfUnmounted();
8657
9213
  return current.create({
@@ -8659,7 +9215,11 @@ const toastApi = {
8659
9215
  type: "success"
8660
9216
  });
8661
9217
  },
8662
- /** 错误提示 */
9218
+ /**
9219
+ * 错误提示。
9220
+ * @param options - toast 配置(标题、描述、时长等)
9221
+ * @returns 该条 toast 的创建结果,可用于后续控制
9222
+ */
8663
9223
  error: (options) => {
8664
9224
  warnIfUnmounted();
8665
9225
  return current.create({
@@ -8667,7 +9227,11 @@ const toastApi = {
8667
9227
  type: "error"
8668
9228
  });
8669
9229
  },
8670
- /** 信息提示 */
9230
+ /**
9231
+ * 信息提示。
9232
+ * @param options - toast 配置(标题、描述、时长等)
9233
+ * @returns 该条 toast 的创建结果,可用于后续控制
9234
+ */
8671
9235
  info: (options) => {
8672
9236
  warnIfUnmounted();
8673
9237
  return current.create({
@@ -8675,7 +9239,11 @@ const toastApi = {
8675
9239
  type: "info"
8676
9240
  });
8677
9241
  },
8678
- /** 警告提示 */
9242
+ /**
9243
+ * 警告提示。
9244
+ * @param options - toast 配置(标题、描述、时长等)
9245
+ * @returns 该条 toast 的创建结果,可用于后续控制
9246
+ */
8679
9247
  warning: (options) => {
8680
9248
  warnIfUnmounted();
8681
9249
  return current.create({
@@ -8683,7 +9251,11 @@ const toastApi = {
8683
9251
  type: "warning"
8684
9252
  });
8685
9253
  },
8686
- /** 加载中提示 */
9254
+ /**
9255
+ * 加载中提示。
9256
+ * @param options - toast 配置(标题、描述、时长等)
9257
+ * @returns 该条 toast 的创建结果,可用于后续控制
9258
+ */
8687
9259
  loading: (options) => {
8688
9260
  warnIfUnmounted();
8689
9261
  return current.create({
@@ -8691,17 +9263,31 @@ const toastApi = {
8691
9263
  type: "loading"
8692
9264
  });
8693
9265
  },
8694
- /** 跟踪 Promise 状态的提示 */
9266
+ /**
9267
+ * 跟踪 Promise 状态的提示。
9268
+ * @param promise - 待跟踪的 Promise 或返回 Promise 的工厂函数
9269
+ * @param options - Promise 各阶段(loading/success/error)的 toast 配置
9270
+ * @param shared - 各阶段共享的基础配置(不含 type)
9271
+ * @returns 该条 toast 的创建结果,可用于后续控制
9272
+ */
8695
9273
  promise: (promise, options, shared) => {
8696
9274
  warnIfUnmounted();
8697
9275
  return current.promise(promise, options, shared);
8698
9276
  },
8699
- /** 关闭指定 toast;不传 id 时关闭全部 */
9277
+ /**
9278
+ * 关闭指定 toast;不传 id 时关闭全部。
9279
+ * @param id - 目标 toast 的 id;缺省时关闭全部
9280
+ */
8700
9281
  dismiss: (id) => {
8701
9282
  warnIfUnmounted();
8702
9283
  current.dismiss(id);
8703
9284
  }
8704
9285
  };
9286
+ /**
9287
+ * 获取 toast API。模块级单例外观对象,任意位置调用返回同一引用(引用稳定);
9288
+ * 内部转发到 Provider 挂载后重建的 store,调用前须在应用根部挂载 <ToastProvider>。
9289
+ * @returns toast 操作 API(success/error/info/warning/loading/promise/dismiss)
9290
+ */
8705
9291
  function useToast() {
8706
9292
  return toastApi;
8707
9293
  }
@@ -8864,6 +9450,8 @@ const _sfc_main$48 = /*@__PURE__*/ defineComponent({
8864
9450
  /**
8865
9451
  * 确认弹层公共 pending 语义:@confirm 处理器返回 Promise 时锁定关闭通道,
8866
9452
  * resolve 后自动关闭,reject 保持打开并退出 loading;同步处理器直接关闭。
9453
+ * @param options - pending 配置:组件实例、confirm/cancel 补发与弹层关闭回调
9454
+ * @returns loading(确认进行中标记)、handleConfirm(异步确认处理)与 handleCancel(取消处理)
8867
9455
  */
8868
9456
  function useConfirmPending(options) {
8869
9457
  const loading = ref(false);
@@ -9441,13 +10029,21 @@ const _sfc_main$47 = /*@__PURE__*/ defineComponent({
9441
10029
  }));
9442
10030
  const titleClass = computed(() => props.size === "sm" ? "text-xs leading-4 font-medium text-foreground" : "text-sm font-medium leading-5 text-foreground");
9443
10031
  const descriptionClass = computed(() => props.size === "sm" ? "mt-1 text-xs leading-relaxed text-muted-foreground" : "mt-1 text-sm leading-relaxed text-muted-foreground");
9444
- /** 连线类:首末项按 index 裁切(不用 first:/last: 伪类——line 恒为 li 首个子元素,伪类会全量误命中) */
10032
+ /**
10033
+ * 连线类:首末项按 index 裁切(不用 first:/last: 伪类——line 恒为 li 首个子元素,伪类会全量误命中)
10034
+ * @param index - 项在 items 中的下标
10035
+ * @returns 连线元素的 class
10036
+ */
9445
10037
  function lineClass(index) {
9446
10038
  const isFirst = index === 0;
9447
10039
  const isLast = index === props.items.length - 1;
9448
10040
  return cn("absolute w-0.5 -translate-x-1/2 bg-border", props.mode === "alternate" ? "left-1/2" : props.size === "sm" ? "left-[5px]" : "left-[6px]", isFirst ? "top-[10px]" : "top-0", isLast ? "bottom-[calc(100%-10px)]" : "bottom-0");
9449
10041
  }
9450
- /** 节点类:颜色/空心取自单项数据,位置与尺寸取自组件变体 */
10042
+ /**
10043
+ * 节点类:颜色/空心取自单项数据,位置与尺寸取自组件变体
10044
+ * @param item - 时间轴单项数据
10045
+ * @returns 节点元素的 class
10046
+ */
9451
10047
  function dotClass(item) {
9452
10048
  return cn(timelineDotVariants({
9453
10049
  mode: props.mode,
@@ -9456,13 +10052,21 @@ const _sfc_main$47 = /*@__PURE__*/ defineComponent({
9456
10052
  hollow: item.hollow
9457
10053
  }));
9458
10054
  }
9459
- /** 内容区类:right 占第 2 列;alternate 按奇偶交替占第 1/3 列并切换对齐 */
10055
+ /**
10056
+ * 内容区类:right 占第 2 列;alternate 按奇偶交替占第 1/3 列并切换对齐
10057
+ * @param index - 项在 items 中的下标(alternate 模式据此决定占列与对齐)
10058
+ * @returns 内容区元素的 class
10059
+ */
9460
10060
  function contentClass(index) {
9461
10061
  const base = "min-w-0 flex flex-col";
9462
10062
  if (props.mode === "alternate") return cn(base, index % 2 === 0 ? "col-start-1 row-start-1 pr-4 text-right" : "col-start-3 row-start-1 pl-4 text-left");
9463
10063
  return cn(base, props.size === "sm" ? "pl-2.5" : "pl-3");
9464
10064
  }
9465
- /** 时间戳类:bottom 时 DOM 仍在前部,仅切 order-last 移到内容下方(不分支 DOM) */
10065
+ /**
10066
+ * 时间戳类:bottom 时 DOM 仍在前部,仅切 order-last 移到内容下方(不分支 DOM)
10067
+ * @param item - 时间轴单项数据(读 timestampPlacement)
10068
+ * @returns 时间戳元素的 class
10069
+ */
9466
10070
  function timestampClass(item) {
9467
10071
  return item.timestampPlacement === "bottom" ? "mb-1 mt-1.5 order-last text-xs leading-4 text-muted-foreground tabular-nums" : "mb-1 text-xs leading-4 text-muted-foreground tabular-nums";
9468
10072
  }