@tu-design/vue 0.5.5 → 0.5.7

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 +89 -87
  2. package/dist/index.mjs +54 -35
  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 +2 -2
  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 +1 -1
  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 +1 -1
  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 +2 -2
  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 +1 -1
  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 +1 -1
  29. package/dist/registry/vue/overlay-shared.json +1 -1
  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 +2 -2
  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 -1
  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 +3 -3
  45. package/dist/registry/vue/tabs.json +2 -1
  46. package/dist/registry/vue/textarea.json +1 -1
  47. package/dist/registry/vue/timeline.json +1 -1
  48. package/dist/registry/vue/toast.json +1 -1
  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 +1 -1
  53. package/dist/registry/vue/utils.json +1 -1
  54. package/dist/registry/vue/week-picker.json +1 -1
  55. package/dist/registry/vue/year-picker.json +1 -1
  56. package/package.json +1 -1
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
3
3
  "name": "table-render",
4
- "version": "0.5.5",
4
+ "version": "0.5.7",
5
5
  "type": "registry:ui",
6
6
  "description": "配置驱动表格渲染器:defineTable 聚合 TanStack Table 实例与列配置,静态/服务端双模式(onLoad 回写分页排序),搜索表单联动(search 接 FormRender),左右固定列 sticky 横向滚动,表体虚拟滚动(virtual + height,TanStack Virtual 动态测量行高),树形数据(tree:子行展开/收起、depth 缩进、caret 位于首列),列显隐(columnSettings 面板 + visibleKeys 受控),错误态占位与重试(#error 插槽 + load-error),ellipsis 支持 tooltip 形态,v-model 受控(pageIndex/pageSize/sort/selectedKeys),Ark Pagination 分页条 + 原生 select 每页条数,排序表头 aria-sort、加载骨架与空态插槽,语义化 table + Tailwind tokens。",
7
7
  "registryDependencies": [
@@ -38,7 +38,7 @@
38
38
  "path": "table-render/TableRender.vue",
39
39
  "type": "registry:component",
40
40
  "target": "components/ui/table-render/TableRender.vue",
41
- "content": "<script setup lang=\"ts\">\nimport type { ComponentPublicInstance, PropType, VNodeChild } from \"vue\";\nimport { useVirtualizer } from \"@tanstack/vue-virtual\";\nimport { columnRenders } from \"./column-renders\";\nimport { computed, inject, onMounted, ref, watch } from \"vue\";\nimport { Button } from \"@/components/ui/button\";\nimport { Checkbox } from \"@/components/ui/checkbox\";\nimport { FormRender, type FormRenderDefinition } from \"@/components/ui/form-render\";\nimport { Popover } from \"@/components/ui/popover\";\nimport { Separator } from \"@/components/ui/separator\";\nimport { Skeleton } from \"@/components/ui/skeleton\";\nimport { Tooltip } from \"@/components/ui/tooltip\";\nimport { cn } from \"@/lib/utils\";\nimport { PAGE_TABLE_FILL_KEY, SELECTION_CELL } from \"./constants\";\nimport { stickyClass, stickyStyle, type StickyMap } from \"./sticky\";\nimport TableBodyRow from \"./TableBodyRow.vue\";\nimport TablePagination from \"./TablePagination.vue\";\nimport type {\n ColumnVisibilityOptions,\n DataRecord,\n SortableOptions,\n TableBodyLine,\n TableColumnOptions,\n TableLoadParams,\n TableRenderDefinition,\n TableSelectionOptions,\n TreeOptions,\n} from \"./types\";\nimport { useTableRender } from \"./useTableRender\";\n\n// boolean flags 用运行时声明 + default: undefined 禁用 Vue 的 Boolean casting\n// (casting 会让未传的 prop 变 false;Checkbox/Dialog/FormRender 同款约定)\nconst props = defineProps({\n /** 聚合式(推荐):defineTable 返回的定义对象 */\n definition: { type: Object as PropType<TableRenderDefinition<any>> },\n /** 数据主键(记录缺字段时以行索引兜底) */\n rowKey: { type: String, required: true },\n /** 拆分式:与 definition 二选一,definition 优先 */\n columns: { type: Array as PropType<TableColumnOptions[]> },\n onLoad: {\n type: Function as PropType<(params: TableLoadParams) => void | Promise<unknown>>,\n },\n data: { type: Array as PropType<DataRecord[]> },\n autoLoad: { type: Boolean as PropType<boolean | undefined>, default: undefined },\n /** 每页条数 / 受控每页条数(D11):传入即受控(pageIndex 未受控时 R9 归位内部处理并通知) */\n pageSize: { type: Number },\n pageSizeOpts: { type: Array as PropType<number[]> },\n loading: { type: Boolean as PropType<boolean | undefined>, default: undefined },\n emptyText: { type: String },\n /** 行选择(仅拆分式生效;聚合式请在 defineTable 配置):\"radio\" | \"checkbox\" | 对象 */\n rowSelection: {\n type: [String, Object] as PropType<\"radio\" | \"checkbox\" | TableSelectionOptions>,\n default: undefined,\n },\n /** 搜索表单(defineForm 返回值):拆分式直接传;聚合式请在 defineTable 配置(definition 优先,同传 DEV 警告) */\n search: { type: Object as PropType<FormRenderDefinition<any>> },\n /** 虚拟滚动:开启后表体行虚拟化渲染;聚合式请在 defineTable 配置(definition 优先);须同时给 height */\n virtual: { type: Boolean as PropType<boolean | undefined>, default: undefined },\n /** 虚拟滚动容器高度(数字 px 或 CSS 高度);仅 virtual: true 时生效 */\n height: { type: [Number, String] as PropType<number | string> },\n /** 树形数据(子行展开/收起);拆分式直接传,聚合式请在 defineTable 配置 */\n tree: { type: Object as PropType<TreeOptions> },\n /** 受控页码(1-based):传入即受控,缺省非受控;内部翻页经 update:page-index 通知 */\n pageIndex: { type: Number },\n /** 受控排序:传入即受控;内部/外部变化均经 sort-change 通知 */\n sort: { type: Object as PropType<SortableOptions> },\n /** 受控选中集(数组,与 update:selected-keys 载荷同构):传入即受控 */\n selectedKeys: { type: Array as PropType<Array<string | number>> },\n /** 受控可见列 key(columns 原序子集):传入即受控;内部显隐经 update:visible-keys 通知 */\n visibleKeys: { type: Array as PropType<string[]> },\n /** 拆分式默认可见列集;与聚合式 columnVisibility.defaultVisibleKeys 同传时 DEV 警告(R26,definition 优先) */\n defaultVisibleKeys: { type: Array as PropType<string[]> },\n /** 列设置触发器/面板开关(默认 true);false 时不渲染 UI,受控 API 不受影响 */\n columnSettings: { type: Boolean as PropType<boolean | undefined>, default: undefined },\n /** 搜索区渲染开关(R27):false 关闭内置搜索区(组合式外置 FormRender);数据链路不变 */\n showSearch: { type: Boolean as PropType<boolean | undefined>, default: undefined },\n /** 分页条渲染开关(R28):false 关闭内置分页条(组合式外置 TablePagination);缺省模式 R13 不变 */\n showPagination: { type: Boolean as PropType<boolean | undefined>, default: undefined },\n /** 填充模式:根容器 h-full 纵向 flex,滚动区 flex-1 内滚;表头 sticky 钉住。\n * 父链需有确定高度(如页面布局的 .table-body);无确定高度时安全退化为自然高度。\n * 显式 prop 优先于布局 provide(key: \"tu-design:page-table-fill\");显式传 false 可强制关闭。\n * 纯布局属性,不进 defineTable/definition(virtual/height 例外),setup 期定版不支持运行时切换。 */\n fillHeight: { type: Boolean as PropType<boolean | undefined>, default: undefined },\n});\n\n// ---- 填充模式(fillHeight)---------------------------------------------------\n// 布局上下文:页面布局容器 provide 同名 key,slot 内 TableRender 自动 fill。\n// 字符串 key 跨包约定(常量 PAGE_TABLE_FILL_KEY 已导出,消费方零依赖时按字符串值 provide),\n// setup 期定版,不支持运行时切换(与 virtual/search 同约定)。\nconst pageTableFill = inject<boolean>(PAGE_TABLE_FILL_KEY, false);\nconst fill = props.fillHeight ?? pageTableFill;\n\nconst emit = defineEmits<{\n \"update:page-index\": [pageIndex: number];\n \"update:page-size\": [pageSize: number];\n \"sort-change\": [sort: SortableOptions | undefined];\n \"row-click\": [record: DataRecord, index: number, event: MouseEvent];\n /** 行双击(与 row-click 独立,双击会先后触发 click 两次,属预期) */\n \"row-dblclick\": [record: DataRecord, index: number, event: MouseEvent];\n /** 行右键;不主动 preventDefault */\n \"row-contextmenu\": [record: DataRecord, index: number, event: MouseEvent];\n /** 单元格点击(columnKey 定位列);冒泡并存——cell-click 触发时 row-click 也会触发 */\n \"cell-click\": [record: DataRecord, columnKey: string, index: number, event: MouseEvent];\n \"selection-change\": [rows: DataRecord[]];\n \"update:selected-keys\": [keys: Array<string | number>];\n /** 搜索:FormRender 校验通过后触发;载荷为当前表单值 */\n search: [values: DataRecord];\n /** 重置:FormRender 已重置为 defaults 后触发;载荷为重置后的表单值 */\n reset: [values: DataRecord];\n /** 服务端模式 onLoad 抛错/ rejects 时触发;下一次 load 开始时 error 投影清除 */\n \"load-error\": [error: Error];\n /** 可见列变化(受控回写通知 / v-model:visible-keys) */\n \"update:visible-keys\": [keys: string[]];\n /** 列显隐变化(受控/非受控均触发,供业务持久化;载荷 = 可见列 key 有序数组,columns 原序) */\n \"column-visibility-change\": [keys: string[]];\n}>();\n\ndefineSlots<{\n empty?: () => VNodeChild;\n /** 错误态占位(服务端模式 onLoad 失败时渲染,优先于数据区) */\n error?: (props: { error: Error | undefined; retry: () => void }) => VNodeChild;\n}>();\n\n/** 加载态骨架行数(R14) */\nconst SKELETON_ROWS = [1, 2, 3, 4, 5];\n\n/** 内置渲染器单例:render 工厂按列求值时复用(工厂本身轻量,仅为整洁) */\nconst RENDERS = columnRenders();\n\n// 聚合式直接复用 defineTable 建好的内核;拆分式在本组件 setup 内建内核\n// (TanStack useVueTable 只能在 setup 调用,故不能放进条件分支深处)\nif (props.definition && props.columns && import.meta.env.DEV) {\n console.warn(\"[tu-design] <TableRender> definition 与 columns 同时传入,已按 definition 渲染。\");\n}\nif (props.definition && props.rowSelection && import.meta.env.DEV) {\n console.warn(\n \"[tu-design] <TableRender> 聚合式下 rowSelection 请在 defineTable 配置,组件 prop 已忽略。\",\n );\n}\nconst instance =\n props.definition ??\n useTableRender({\n columns: props.columns ?? [],\n onLoad: props.onLoad,\n data: () => props.data,\n autoLoad: props.autoLoad,\n pageSizeOpts: props.pageSizeOpts,\n rowKey: props.rowKey,\n rowSelection: props.rowSelection,\n search: props.search,\n virtual: props.virtual,\n height: props.height,\n tree: props.tree,\n pageIndex: () => props.pageIndex,\n pageSize: () => props.pageSize,\n sort: () => props.sort,\n selectedKeys: () => props.selectedKeys,\n columnVisibility: props.definition?.columnVisibility,\n defaultVisibleKeys: () => props.defaultVisibleKeys,\n visibleKeys: () => props.visibleKeys,\n });\n// 拆分式已传 rowKey;聚合式由组件回填(S1:选择引擎依赖 rowKey 就绪)\ninstance.setRowKey(props.rowKey);\n\n// ---- 搜索表单(FormRender 联动) --------------------------------------------\n// 与 rowSelection 不同:聚合式下 prop 未被 definition 覆盖时回填引擎(不做聚合式忽略限制);\n// definition 与 prop 二选一,definition 优先,同传 DEV 警告\nif (props.definition && props.search) {\n if (instance.search && import.meta.env.DEV) {\n console.warn(\n \"[tu-design] <TableRender> 聚合式下 search 已在 defineTable 配置,组件 prop 已忽略。\",\n );\n } else {\n instance.setSearch(props.search);\n }\n}\n// search 不支持运行时切换(与 FormRender definition/form 同款约定),setup 期定版即可\nconst search = instance.search;\n\n// 列设置触发器的 Tooltip 受控开合(Tooltip 与 Popover 触发器嵌套会吞点击,故手动控制、不嵌套触发器)\nconst settingsTipOpen = ref(false);\n\n// ---- 列显隐(column visibility,R20–R26) ------------------------------------\n// R26:聚合式(columnVisibility.defaultVisibleKeys 经引擎解析回传)与拆分式 prop 同传 → definition 优先。\n// 引擎是唯一解析点;聚合式受控回填经 setVisibleKeys(normalize 等值守卫防回弹);\n// 拆分式由引擎受控 watch 直接同步(源 = props getter)\nif (\n props.definition &&\n instance.defaultVisibleKeys !== undefined &&\n props.defaultVisibleKeys !== undefined &&\n import.meta.env.DEV\n) {\n console.warn(\n \"[tu-design] <TableRender> 聚合式下 defaultVisibleKeys 已在 columnVisibility 配置,组件 prop 已忽略。\",\n );\n}\nwatch(\n () => props.visibleKeys,\n (next) => {\n if (props.definition && next !== undefined) instance.setVisibleKeys(next);\n },\n { immediate: true },\n);\n\n/** 当前搜索表单值快照(浅拷贝;无 search 时为空对象) */\nfunction searchValues(): DataRecord {\n return search ? { ...search.form.state.values } : {};\n}\n\n/** 搜索:校验已由 FormRender 完成;归位第 1 页重载,分页/排序取数自动携带最新表单值 */\nfunction onSearch() {\n emit(\"search\", searchValues());\n instance.reload(true);\n}\n\n/** 重置:FormRender 已同步重置为 defaults(TanStack reset 为同步 setState),此刻读取即 defaults */\nfunction onReset() {\n emit(\"reset\", searchValues());\n instance.reload(true);\n}\n\nconst columns = computed(() => instance.columns);\nconst rows = computed(() => instance.table.getRowModel().rows);\n/** 内部加载态 ∪ 外部受控加载态(R14) */\nconst loading = computed(() => props.loading === true || instance.loading.value);\nconst showPagination = computed(() => Math.ceil(instance.page.total / instance.page.pageSize) > 1);\n/** 内置分页条开关(R28):showPagination=false 关闭;R13 仅作用于缺省模式 */\nconst showPaginationBar = computed(() => showPagination.value && props.showPagination !== false);\n/** 内置搜索区开关(R27):配置了 search 且未被 showSearch=false 关闭;列设置触发器不受影响 */\nconst showSearchArea = computed(() => search !== undefined && props.showSearch !== false);\n\n// ---- 错误态(服务端模式 onLoad 失败) ----------------------------------------\n// loading 判定优先;error 优先于正常数据(load 开始时引擎已清除旧错误,loading 期间 error 恒空)\nconst loadError = computed(() => instance.error.value);\nconst showError = computed(() => !loading.value && loadError.value !== undefined);\n\nwatch(loadError, (err) => {\n if (err) emit(\"load-error\", err);\n});\n\nfunction retry() {\n instance.reload();\n}\n\n// ---- 行选择(S 系列) -------------------------------------------------------\nconst selection = computed(() => instance.selection);\nconst selectedKeys = instance.selectedKeys;\nconst hasSelection = computed(() => selection.value.enabled);\n\n// ---- 列显隐(column visibility,R20–R26) -------------------------------------\nconst visibleKeySet = computed(() => new Set(instance.visibleKeys.value));\n/** 可见业务列(columns 原序子集):header/body/骨架/colspan/sticky 全部基于此渲染(R23/R25) */\nconst visibleColumns = computed(() =>\n columns.value.filter((column) => visibleKeySet.value.has(column.key)),\n);\n/** 列设置触发器/面板开关(默认 true);false 时不渲染 UI,受控 API 不受影响 */\nconst showColumnSettings = computed(() => props.columnSettings ?? true);\n\nfunction isColumnVisible(key: string): boolean {\n return visibleKeySet.value.has(key);\n}\n\n/** 最少一列(R20):唯一可见列不可隐藏 */\nfunction canHideColumn(key: string): boolean {\n return !(instance.visibleKeys.value.length <= 1 && visibleKeySet.value.has(key));\n}\n\nfunction toggleColumnVisible(key: string) {\n if (!canHideColumn(key)) return;\n instance.setVisibleKeys(\n isColumnVisible(key)\n ? instance.visibleKeys.value.filter((k) => k !== key)\n : [...instance.visibleKeys.value, key],\n );\n}\n\nconst allColumnsVisible = computed(\n () => columns.value.length > 0 && visibleColumns.value.length === columns.value.length,\n);\n\nfunction selectAllColumns() {\n if (allColumnsVisible.value) return;\n instance.setVisibleKeys(columns.value.map((column) => column.key));\n}\n\nfunction resetColumns() {\n // R21:恢复 defaultVisibleKeys;未配置 = 全部可见\n instance.setVisibleKeys(instance.defaultVisibleKeys ?? columns.value.map((column) => column.key));\n}\n\n// 受控/非受控均通知:统一投影变化 → 双事件(载荷 = columns 原序可见 key)\nwatch(instance.visibleKeys, (keys) => {\n emit(\"update:visible-keys\", [...keys]);\n emit(\"column-visibility-change\", [...keys]);\n});\n\n/** 总列数 = 可见业务列 + 选择列(空态 colspan 与骨架行,S8/R23) */\nconst columnCount = computed(() => visibleColumns.value.length + (hasSelection.value ? 1 : 0));\n\n// ---- 固定列(sticky) --------------------------------------------------------\n\n// DEV 校验:sticky 偏移只能从数字 width(px)推算,否则降级普通列(columns setup 期定版,只查一次)\nfor (const column of columns.value) {\n if (column.fixed !== undefined && typeof column.width !== \"number\") {\n console.warn(\n `[tu-design] <TableRender> fixed 列 \"${column.key}\" 需要数字 width,已忽略 fixed。`,\n );\n }\n}\n\n/** sticky 单元格映射(纯渲染层 computed,不进 TanStack pinning state):\n * 选择列视作最左 fixed 列参与累计(offset 0);fixed-left 按列序累加,\n * fixed-right 从最右列反向累计。edge = 该 sticky 组朝滚动方向的交界列(加分隔边框)。\n * 全部基于**可见集**(R23):sticky 组因隐藏变空则无该组输出(不输出边框)。\n */\nconst stickyOf = computed<StickyMap>(() => {\n const map: StickyMap = new Map();\n // instance.columns 是联合数组(聚合式 any / 拆分式 DataRecord),联合上的 filter\n // 类型谓词重载解析不可靠,故 map 提取时以断言收窄 width(条件已含 typeof 守卫)\n const lefts = visibleColumns.value\n .filter((column) => column.fixed === \"left\" && typeof column.width === \"number\")\n .map((column) => ({ key: column.key, width: column.width as number }));\n const rights = visibleColumns.value\n .filter((column) => column.fixed === \"right\" && typeof column.width === \"number\")\n .map((column) => ({ key: column.key, width: column.width as number }));\n\n let acc = 0;\n if (hasSelection.value) {\n map.set(SELECTION_CELL, { side: \"left\", offset: 0, edge: lefts.length === 0 });\n acc = selection.value.width;\n }\n lefts.forEach((left, index) => {\n map.set(left.key, { side: \"left\", offset: acc, edge: index === lefts.length - 1 });\n acc += left.width;\n });\n\n let racc = 0;\n for (let index = rights.length - 1; index >= 0; index--) {\n const right = rights[index]!;\n map.set(right.key, { side: \"right\", offset: racc, edge: index === 0 });\n racc += right.width;\n }\n return map;\n});\n\n/** 表头全选三态(S10):本页可选行与选中集求交派生(TanStack getter 追踪不稳,自算) */\nconst selectableKeys = computed(() =>\n rows.value.filter((row) => row.getCanSelect()).map((row) => rowKeyOf(row.original, row.index)),\n);\nconst headerChecked = computed(\n () =>\n hasSelection.value &&\n selection.value.type === \"checkbox\" &&\n selectableKeys.value.length > 0 &&\n selectableKeys.value.every((key) => selectedKeys.value.has(key)),\n);\nconst headerIndeterminate = computed(\n () =>\n hasSelection.value &&\n !headerChecked.value &&\n selectableKeys.value.some((key) => selectedKeys.value.has(key)),\n);\n\nfunction onHeaderSelect(checked: boolean) {\n instance.table.toggleAllPageRowsSelected(checked);\n}\n\n/** 行选择控件切换;radio 不可取消由引擎 S4 守卫,不选中态点击传 checked=true */\nfunction onRowSelect(line: { key: string }, checked: boolean) {\n instance.toggleRowSelected(line.key, checked);\n}\n\n// 选中集变化 → 对外事件(S7):排序/翻页不改变选中集,故不会误发\nwatch(instance.selectedKeys, (keys) => {\n emit(\"selection-change\", [...selection.value.value]);\n emit(\"update:selected-keys\", [...keys]);\n});\n\n/** 行 → 单元格值矩阵:render > formatter > record[key](R17) */\nconst body = computed<TableBodyLine[]>(() => {\n // 渲染器工厂按列求值一次(而非每单元格),避免用户工厂内的重分配被放大\n const renderFns = new Map(\n columns.value.filter((c) => c.render).map((c) => [c, c.render!(RENDERS)]),\n );\n return rows.value.map((row) => ({\n /** TanStack Row:树形渲染读 depth / getCanExpand / getIsExpanded / toggleExpanded */\n row,\n key: rowKeyOf(row.original, row.index),\n index: row.index,\n record: row.original,\n /** 行级可选过滤(S5):selectable 谓词交由引擎 enableRowSelection 判定 */\n canSelect: row.getCanSelect(),\n // 可见列的值矩阵(列显隐只裁剪列;R25 状态不受影响)\n cells: visibleColumns.value.map((column): VNodeChild => {\n const render = renderFns.get(column);\n if (render) return render(row.original, row.index, column);\n if (column.formatter) return column.formatter(row.original) as VNodeChild;\n return String(row.original[column.key] ?? \"\");\n }),\n }));\n});\n\n// ---- 树形数据(T 系列) ------------------------------------------------------\n// 引擎是唯一解析点(无效配置已 warn 并忽略,回传 undefined);tree 为 undefined 时不渲染缩进与 caret\nconst tree = instance.tree;\nconst treeIndent = tree?.indentSize ?? 16;\n\nlet missingRowKeyWarned = false;\n\n/** 行主键:rowKey 字段缺失时以行索引兜底(R3) */\nfunction rowKeyOf(record: DataRecord, index: number): string {\n const value = record[props.rowKey];\n if (value === undefined || value === null) {\n if (!missingRowKeyWarned && import.meta.env.DEV) {\n missingRowKeyWarned = true;\n console.warn(\n `[tu-design] <TableRender> 部分记录缺少 rowKey 字段 \"${props.rowKey}\",已退化为按行索引标识。`,\n );\n }\n return `index-${index}`;\n }\n return String(value);\n}\n\n// ---- 虚拟滚动 / 填充模式 ------------------------------------------------------\n// definition 优先于 prop(配置定版,不支持运行时切换)\nconst virtualRaw = instance.virtual ?? props.virtual;\nconst heightRaw = instance.height ?? props.height;\n// fill 模式自带真实滚动盒(flex-1 实测高度),virtual 无需显式 height\nif (virtualRaw === true && heightRaw === undefined && !fill) {\n console.warn(\"[tu-design] <TableRender> virtual 需要配置 height,已降级普通渲染。\");\n}\nconst virtualEnabled = virtualRaw === true && (heightRaw !== undefined || fill);\nconst scrollHeight = computed(() => (typeof heightRaw === \"number\" ? `${heightRaw}px` : heightRaw));\n/** 表头 sticky 仅在组件内存在真实纵向滚动盒时生效(fill / virtual),普通模式不挂载,行为不变 */\nconst theadSticky = fill || virtualEnabled;\n/** 滚动区样式:virtual 用固定 height;fill 交给 flex 分配(二者同传以 fill 优先) */\nconst scrollStyle = computed(() => {\n if (fill || !virtualEnabled) return undefined;\n return { height: scrollHeight.value, overflowY: \"auto\" as const };\n});\n/** sticky 表头普通列类:不透明底防行内容透出;分隔线归 th(thead 行级 border 会随行滚走);\n * z-20 高于表体 fixed 列(--z-sticky: 10),纵向滚动行滑过表头时不穿透;\n * 表头 fixed 列的 z 由 stickyStyle inline style(var(--z-sticky-head))提供,inline 优先级天然覆盖此处 class */\nconst theadThClass = theadSticky ? \"sticky top-0 z-20 border-b border-border bg-background\" : \"\";\n/** sticky 态 table 改分离边框:preflight 为 border-collapse: collapse,\n * 折叠边框几何归属 table,Chrome 下 sticky th 粘住后自身 border-b 渲染丢失;\n * separate + spacing-0 恢复单元格边框。普通模式保持 collapse,零回归。 */\nconst tableClass = theadSticky ? \"border-separate border-spacing-0\" : \"\";\n\nconst scrollEl = ref<HTMLElement | null>(null);\nconst theadEl = ref<HTMLElement | null>(null);\n/** 滚动容器内 thead 占据的前缀高度(scrollMargin);表头内容静态,挂载后测量一次 */\nconst theadOffset = ref(0);\n\n// 仅 virtual: true 且 height 就绪时创建(配置 setup 期定版,顶层条件分支可安全注册生命周期)\nconst virtualizerRef = virtualEnabled\n ? useVirtualizer(\n computed(() => ({\n count: rows.value.length, // 翻页/重载后行窗口变化 → options 更新(setOptions 自动生效)\n getScrollElement: () => scrollEl.value,\n estimateSize: () => 40,\n overscan: 8,\n getItemKey: (index: number) => rowKeyOf(rows.value[index]!, index), // rowKey 作为虚拟行 key\n scrollMargin: theadOffset.value, // thead 在滚动容器内的 offset 前缀\n })),\n )\n : null;\n\nonMounted(() => {\n if (virtualEnabled) theadOffset.value = theadEl.value?.offsetHeight ?? 0;\n});\n\nconst virtualRows = computed(() => (virtualizerRef ? virtualizerRef.value.getVirtualItems() : []));\nconst virtualTotal = computed(() => (virtualizerRef ? virtualizerRef.value.getTotalSize() : 0));\n/** 窗口行 + 对应全量行数据(cells 矩阵已由 body computed 缓存,虚拟化只裁剪 DOM 节点) */\nconst virtualLines = computed(() =>\n virtualRows.value.map((row) => ({ row, line: body.value[row.index]! })),\n);\nconst padTop = computed(() => virtualRows.value[0]?.start ?? 0);\nconst padBottom = computed(() => {\n const items = virtualRows.value;\n return items.length === 0 ? 0 : Math.max(0, virtualTotal.value - items[items.length - 1]!.end);\n});\n\n/** 行高动态测量:measureElement 读 data-index 把实测高度写回(行内容高度可变,不假设固定行高)。\n * 行组件为函数 ref,拿到的是组件实例,需经 $el 取真实 tr。 */\nfunction measureRow(node: Element | ComponentPublicInstance | null) {\n const el = node instanceof Element ? node : (node?.$el as Element | undefined);\n if (el instanceof Element) virtualizerRef?.value.measureElement(el);\n}\n\n/** aria-sort 仅在该列当前被排序时标注(R16) */\nfunction ariaSort(column: TableColumnOptions): \"ascending\" | \"descending\" | undefined {\n if (instance.sort.value?.key !== column.key) return undefined;\n return instance.sort.value.direction === \"asc\" ? \"ascending\" : \"descending\";\n}\n\nfunction sortMark(column: TableColumnOptions): string {\n const direction = instance.sort.value?.key === column.key ? instance.sort.value.direction : \"\";\n return direction === \"asc\" ? \"↑\" : direction === \"desc\" ? \"↓\" : \"\";\n}\n\nfunction onSort(key: string) {\n instance.toggleSort(key);\n emit(\"sort-change\", instance.sort.value);\n}\n\nfunction onPageIndex(pageIndex: number) {\n instance.setPageIndex(pageIndex);\n lastEmittedPage.pageIndex = pageIndex;\n emit(\"update:page-index\", pageIndex);\n}\n\nfunction onPageSize(pageSize: number) {\n instance.setPageSize(pageSize);\n lastEmittedPage.pageSize = pageSize;\n emit(\"update:page-size\", pageSize);\n}\n\n// ---- 受控模式(v-model):page 投影 → update:* 通知 ---------------------------\n// 仅 page-index/page-size 至少一方受控时安装;lastEmittedPage 去重——\n// 动作路径已 emit 过的值不再重复发(受控回写/内部归位只通知「未通知过的」变化)\nconst pageControlled = () => props.pageIndex !== undefined || props.pageSize !== undefined;\nconst lastEmittedPage = {\n pageIndex: undefined as number | undefined,\n pageSize: undefined as number | undefined,\n};\n\nif (pageControlled()) {\n watch(\n () => [instance.page.pageIndex, instance.page.pageSize] as const,\n ([pageIndex, pageSize]) => {\n if (pageIndex !== lastEmittedPage.pageIndex) {\n lastEmittedPage.pageIndex = pageIndex;\n emit(\"update:page-index\", pageIndex);\n }\n if (pageSize !== lastEmittedPage.pageSize) {\n lastEmittedPage.pageSize = pageSize;\n emit(\"update:page-size\", pageSize);\n }\n },\n );\n}\n\nfunction onRowClick(record: DataRecord, index: number, event: MouseEvent) {\n emit(\"row-click\", record, index, event);\n}\n\nfunction onRowDblclick(record: DataRecord, index: number, event: MouseEvent) {\n emit(\"row-dblclick\", record, index, event);\n}\n\nfunction onRowContextmenu(record: DataRecord, index: number, event: MouseEvent) {\n emit(\"row-contextmenu\", record, index, event);\n}\n\nfunction onCellClick(record: DataRecord, columnKey: string, index: number, event: MouseEvent) {\n emit(\"cell-click\", record, columnKey, index, event);\n}\n\ndefineExpose({\n table: instance.table,\n page: instance.page,\n sort: instance.sort,\n loading: instance.loading,\n error: instance.error,\n visibleKeys: instance.visibleKeys,\n setVisibleKeys: instance.setVisibleKeys,\n reload: instance.reload,\n toggleSort: onSort,\n setPageIndex: onPageIndex,\n setPageSize: onPageSize,\n selection: instance.selection,\n selectedKeys: instance.selectedKeys,\n setSelection: instance.setSelection,\n clearSelection: instance.clearSelection,\n});\n</script>\n\n<template>\n <div :class=\"cn('w-full', fill && 'flex h-full min-h-0 flex-col', $attrs.class)\">\n <!-- 搜索区 + 列设置触发器:同行右对齐(items-end);无搜索时触发器位于表格上方(R27:showSearch=false 关闭搜索区) -->\n <div\n v-if=\"showSearchArea || showColumnSettings\"\n :class=\"cn('mb-2 flex items-end justify-between gap-2', fill && 'shrink-0')\"\n >\n <FormRender\n v-if=\"showSearchArea\"\n class=\"min-w-0 flex-1\"\n :definition=\"search\"\n :searchable=\"search.actions ? undefined : true\"\n @search=\"onSearch\"\n @reset=\"onReset\"\n />\n\n <!-- 列设置:Popover 面板(R20 最少一列 / R21 重置 / R22 不含选择列);\n 触发钮 Tooltip 手动受控开合(Tooltip 与 Popover 触发器嵌套会吞点击,故并列渲染、不走 hover 自动触发) -->\n <template v-if=\"showColumnSettings\">\n <Popover align=\"end\" content-class=\"w-56 p-0\">\n <Button\n variant=\"ghost\"\n size=\"icon\"\n aria-label=\"列设置\"\n aria-haspopup=\"true\"\n @pointerenter=\"settingsTipOpen = true\"\n @pointerleave=\"settingsTipOpen = false\"\n >\n <!-- lucide Settings2(内联 SVG,跟随项目图标现状) -->\n <svg\n xmlns=\"http://www.w3.org/2000/svg\"\n viewBox=\"0 0 24 24\"\n fill=\"none\"\n stroke=\"currentColor\"\n stroke-width=\"2\"\n stroke-linecap=\"round\"\n stroke-linejoin=\"round\"\n class=\"size-4\"\n aria-hidden=\"true\"\n >\n <path d=\"M20 7h-9\" />\n <path d=\"M14 17H5\" />\n <circle cx=\"17\" cy=\"17\" r=\"3\" />\n <circle cx=\"7\" cy=\"7\" r=\"3\" />\n </svg>\n </Button>\n <template #content>\n <div class=\"flex items-center justify-end gap-3 px-3 py-2\">\n <button\n type=\"button\"\n class=\"text-muted-foreground hover:text-foreground cursor-pointer text-xs disabled:cursor-not-allowed disabled:opacity-50\"\n :disabled=\"allColumnsVisible\"\n @click=\"selectAllColumns\"\n >\n 全选\n </button>\n <button\n type=\"button\"\n class=\"text-muted-foreground hover:text-foreground cursor-pointer text-xs\"\n @click=\"resetColumns\"\n >\n 重置\n </button>\n </div>\n <Separator />\n <div class=\"max-h-64 overflow-y-auto py-1\">\n <div\n v-for=\"column in columns\"\n :key=\"column.key\"\n data-column-item\n :data-column-key=\"column.key\"\n class=\"hover:bg-accent/50 flex h-8 cursor-pointer items-center gap-2 px-3\"\n @click=\"toggleColumnVisible(column.key)\"\n >\n <Checkbox\n :checked=\"isColumnVisible(column.key)\"\n :disabled=\"!canHideColumn(column.key)\"\n @update:checked=\"toggleColumnVisible(column.key)\"\n @click.stop\n />\n <span class=\"min-w-0 flex-1 truncate\">{{ column.title }}</span>\n <!-- 有效 fixed 列(数字 width)标识 -->\n <svg\n v-if=\"column.fixed !== undefined && typeof column.width === 'number'\"\n xmlns=\"http://www.w3.org/2000/svg\"\n viewBox=\"0 0 24 24\"\n fill=\"none\"\n stroke=\"currentColor\"\n stroke-width=\"2\"\n stroke-linecap=\"round\"\n stroke-linejoin=\"round\"\n class=\"text-muted-foreground size-3 shrink-0\"\n aria-hidden=\"true\"\n >\n <path d=\"M12 17v5\" />\n <path\n d=\"M9 10.76a2 2 0 0 1-1.11 1.79l-1.78.9A2 2 0 0 0 5 15.24V16a1 1 0 0 0 1 1h12a1 1 0 0 0 1-1v-.76a2 2 0 0 0-1.11-1.79l-1.78-.9A2 2 0 0 1 15 10.76V7h1a2 2 0 0 0 0-4H8a2 2 0 0 0 0 4h1z\"\n />\n </svg>\n </div>\n </div>\n </template>\n </Popover>\n <!-- 纯受控气泡(无默认插槽,不渲染触发器):开合由触发钮 pointerenter/leave 驱动 -->\n <Tooltip :open=\"settingsTipOpen\" content=\"列设置\" />\n </template>\n </div>\n\n <!-- 滚动容器:横向滚动时 fixed 列 sticky 生效;virtual/fill 模式兼任纵向滚动(分页条不参与滚动) -->\n <div\n ref=\"scrollEl\"\n :class=\"cn('overflow-x-auto', fill && 'min-h-0 flex-1 overflow-y-auto')\"\n :style=\"scrollStyle\"\n >\n <table class=\"w-full caption-bottom text-sm\" :class=\"tableClass\">\n <thead ref=\"theadEl\" :class=\"theadSticky ? undefined : '[&_tr]:border-b'\">\n <tr>\n <!-- 选择列:checkbox 型表头为本页全选三态(S3/S10);radio 型占位;视作最左固定列 -->\n <th\n v-if=\"hasSelection\"\n scope=\"col\"\n class=\"h-10 w-12 px-2 align-middle font-medium text-muted-foreground\"\n :class=\"[stickyClass(stickyOf, SELECTION_CELL), theadThClass]\"\n :style=\"[\n { width: `${selection.width}px` },\n stickyStyle(stickyOf, SELECTION_CELL, true),\n ]\"\n >\n <Checkbox\n v-if=\"selection.type === 'checkbox'\"\n :checked=\"headerIndeterminate ? 'indeterminate' : headerChecked\"\n :aria-label=\"'全选本页'\"\n @update:checked=\"onHeaderSelect\"\n />\n </th>\n <th\n v-for=\"column in visibleColumns\"\n :key=\"column.key\"\n scope=\"col\"\n class=\"h-10 px-2 align-middle font-medium text-muted-foreground\"\n :class=\"[stickyClass(stickyOf, column.key), theadThClass]\"\n :style=\"[\n { width: column.width, textAlign: column.align },\n stickyStyle(stickyOf, column.key, true),\n ]\"\n :aria-sort=\"ariaSort(column)\"\n >\n <button\n v-if=\"column.sortable\"\n type=\"button\"\n class=\"inline-flex items-center gap-1 hover:text-foreground\"\n @click=\"onSort(column.key)\"\n >\n {{ column.title }}\n <span aria-hidden=\"true\" class=\"text-xs\">{{ sortMark(column) }}</span>\n </button>\n <template v-else>{{ column.title }}</template>\n </th>\n </tr>\n </thead>\n\n <tbody class=\"[&_tr:last-child]:border-0\">\n <!-- 加载态:固定 5 行骨架(R14);选择列一并占位(S8);骨架不虚拟化;loading 判定优先 -->\n <template v-if=\"loading\">\n <tr v-for=\"row in SKELETON_ROWS\" :key=\"row\" data-skeleton>\n <td\n v-if=\"hasSelection\"\n class=\"p-2 align-middle\"\n :class=\"stickyClass(stickyOf, SELECTION_CELL)\"\n :style=\"stickyStyle(stickyOf, SELECTION_CELL, false)\"\n >\n <Skeleton class=\"size-4\" />\n </td>\n <td\n v-for=\"column in visibleColumns\"\n :key=\"column.key\"\n class=\"p-2 align-middle\"\n :class=\"stickyClass(stickyOf, column.key)\"\n :style=\"[{ textAlign: column.align }, stickyStyle(stickyOf, column.key, false)]\"\n >\n <Skeleton class=\"h-4 w-full\" />\n </td>\n </tr>\n </template>\n\n <!-- 错误态:error 优先于正常数据;插槽可自定义(slot props { error, retry }) -->\n <template v-else-if=\"showError\">\n <tr data-error>\n <td :colspan=\"columnCount\" class=\"p-8 text-center text-muted-foreground\">\n <slot name=\"error\" :error=\"loadError\" :retry=\"retry\">\n <div class=\"flex flex-col items-center gap-3\">\n <p>{{ loadError?.message ?? \"加载失败\" }}</p>\n <Button variant=\"outline\" size=\"sm\" @click=\"retry\">重试</Button>\n </div>\n </slot>\n </td>\n </tr>\n </template>\n\n <!-- 虚拟滚动:窗口行 + 前后占位行(总高撑开滚动区间;行高经 measureElement 动态测量) -->\n <template v-else-if=\"virtualEnabled\">\n <tr aria-hidden=\"true\" data-virtual-pad :style=\"{ height: `${padTop}px` }\">\n <td :colspan=\"columnCount\" class=\"border-0 p-0\"></td>\n </tr>\n <TableBodyRow\n v-for=\"item in virtualLines\"\n :key=\"item.line.key\"\n :ref=\"measureRow\"\n :data-index=\"item.row.index\"\n :line=\"item.line\"\n :columns=\"visibleColumns\"\n :selection=\"hasSelection ? selection.type : undefined\"\n :selected=\"selectedKeys.has(item.line.key)\"\n :sticky=\"stickyOf\"\n :tree-indent=\"tree ? treeIndent : undefined\"\n @select=\"(checked: boolean) => onRowSelect(item.line, checked)\"\n @row-click=\"onRowClick(item.line.record, item.line.index, $event)\"\n @row-dblclick=\"onRowDblclick(item.line.record, item.line.index, $event)\"\n @row-contextmenu=\"onRowContextmenu(item.line.record, item.line.index, $event)\"\n @cell-click=\"\n (columnKey: string, event: MouseEvent) =>\n onCellClick(item.line.record, columnKey, item.line.index, event)\n \"\n />\n <tr aria-hidden=\"true\" data-virtual-pad :style=\"{ height: `${padBottom}px` }\">\n <td :colspan=\"columnCount\" class=\"border-0 p-0\"></td>\n </tr>\n </template>\n\n <template v-else>\n <TableBodyRow\n v-for=\"line in body\"\n :key=\"line.key\"\n :line=\"line\"\n :columns=\"visibleColumns\"\n :selection=\"hasSelection ? selection.type : undefined\"\n :selected=\"selectedKeys.has(line.key)\"\n :sticky=\"stickyOf\"\n :tree-indent=\"tree ? treeIndent : undefined\"\n @select=\"(checked: boolean) => onRowSelect(line, checked)\"\n @row-click=\"onRowClick(line.record, line.index, $event)\"\n @row-dblclick=\"onRowDblclick(line.record, line.index, $event)\"\n @row-contextmenu=\"onRowContextmenu(line.record, line.index, $event)\"\n @cell-click=\"\n (columnKey: string, event: MouseEvent) =>\n onCellClick(line.record, columnKey, line.index, event)\n \"\n />\n </template>\n\n <!-- 空态:横跨全列的单单元格,不虚拟化;错误态优先 -->\n <tr v-if=\"!loading && !showError && body.length === 0\" data-empty>\n <td :colspan=\"columnCount\" class=\"p-8 text-center text-muted-foreground\">\n <slot name=\"empty\">{{ emptyText ?? \"暂无数据\" }}</slot>\n </td>\n </tr>\n </tbody>\n </table>\n </div>\n\n <!-- R31:手动接线(须经 onPageIndex/onPageSize 包装器保留受控去重);显式补 border-t 与 size select 保持现状 -->\n <TablePagination\n v-if=\"showPaginationBar\"\n :class=\"cn('border-t', fill && 'shrink-0')\"\n :page-index=\"instance.page.pageIndex\"\n :page-size=\"instance.page.pageSize\"\n :page-size-opts=\"instance.page.pageSizeOpts\"\n :total=\"instance.page.total\"\n :show-size-select=\"true\"\n @update:page-index=\"onPageIndex\"\n @update:page-size=\"onPageSize\"\n />\n </div>\n</template>\n"
41
+ "content": "<script setup lang=\"ts\">\nimport type { ComponentPublicInstance, PropType, VNodeChild } from \"vue\";\nimport { useVirtualizer } from \"@tanstack/vue-virtual\";\nimport { columnRenders } from \"./column-renders\";\nimport { computed, inject, onMounted, ref, watch } from \"vue\";\nimport { Button } from \"@/components/ui/button\";\nimport { Checkbox } from \"@/components/ui/checkbox\";\nimport { FormRender, type FormRenderDefinition } from \"@/components/ui/form-render\";\nimport { Popover } from \"@/components/ui/popover\";\nimport { Separator } from \"@/components/ui/separator\";\nimport { Skeleton } from \"@/components/ui/skeleton\";\nimport { Tooltip } from \"@/components/ui/tooltip\";\nimport { cn } from \"@/lib/utils\";\nimport { PAGE_TABLE_FILL_KEY, SELECTION_CELL } from \"./constants\";\nimport { stickyClass, stickyStyle, type StickyMap } from \"./sticky\";\nimport TableBodyRow from \"./TableBodyRow.vue\";\nimport TablePagination from \"./TablePagination.vue\";\nimport type {\n ColumnVisibilityOptions,\n DataRecord,\n SortableOptions,\n TableBodyLine,\n TableColumnOptions,\n TableLoadParams,\n TableRenderDefinition,\n TableSelectionOptions,\n TreeOptions,\n} from \"./types\";\nimport { useTableRender } from \"./useTableRender\";\n\n// boolean flags 用运行时声明 + default: undefined 禁用 Vue 的 Boolean casting\n// (casting 会让未传的 prop 变 false;Checkbox/Dialog/FormRender 同款约定)\nconst props = defineProps({\n /** 聚合式(推荐):defineTable 返回的定义对象 */\n definition: { type: Object as PropType<TableRenderDefinition<any>> },\n /** 数据主键(记录缺字段时以行索引兜底) */\n rowKey: { type: String, required: true },\n /** 拆分式:与 definition 二选一,definition 优先 */\n columns: { type: Array as PropType<TableColumnOptions[]> },\n onLoad: {\n type: Function as PropType<(params: TableLoadParams) => void | Promise<unknown>>,\n },\n data: { type: Array as PropType<DataRecord[]> },\n autoLoad: { type: Boolean as PropType<boolean | undefined>, default: undefined },\n /** 每页条数 / 受控每页条数(D11):传入即受控(pageIndex 未受控时 R9 归位内部处理并通知) */\n pageSize: { type: Number },\n pageSizeOpts: { type: Array as PropType<number[]> },\n loading: { type: Boolean as PropType<boolean | undefined>, default: undefined },\n emptyText: { type: String },\n /** 行选择(仅拆分式生效;聚合式请在 defineTable 配置):\"radio\" | \"checkbox\" | 对象 */\n rowSelection: {\n type: [String, Object] as PropType<\"radio\" | \"checkbox\" | TableSelectionOptions>,\n default: undefined,\n },\n /** 搜索表单(defineForm 返回值):拆分式直接传;聚合式请在 defineTable 配置(definition 优先,同传 DEV 警告) */\n search: { type: Object as PropType<FormRenderDefinition<any>> },\n /** 虚拟滚动:开启后表体行虚拟化渲染;聚合式请在 defineTable 配置(definition 优先);须同时给 height */\n virtual: { type: Boolean as PropType<boolean | undefined>, default: undefined },\n /** 虚拟滚动容器高度(数字 px 或 CSS 高度);仅 virtual: true 时生效 */\n height: { type: [Number, String] as PropType<number | string> },\n /** 树形数据(子行展开/收起);拆分式直接传,聚合式请在 defineTable 配置 */\n tree: { type: Object as PropType<TreeOptions> },\n /** 受控页码(1-based):传入即受控,缺省非受控;内部翻页经 update:page-index 通知 */\n pageIndex: { type: Number },\n /** 受控排序:传入即受控;内部/外部变化均经 sort-change 通知 */\n sort: { type: Object as PropType<SortableOptions> },\n /** 受控选中集(数组,与 update:selected-keys 载荷同构):传入即受控 */\n selectedKeys: { type: Array as PropType<Array<string | number>> },\n /** 受控可见列 key(columns 原序子集):传入即受控;内部显隐经 update:visible-keys 通知 */\n visibleKeys: { type: Array as PropType<string[]> },\n /** 拆分式默认可见列集;与聚合式 columnVisibility.defaultVisibleKeys 同传时 DEV 警告(R26,definition 优先) */\n defaultVisibleKeys: { type: Array as PropType<string[]> },\n /** 列设置触发器/面板开关(默认 true);false 时不渲染 UI,受控 API 不受影响 */\n columnSettings: { type: Boolean as PropType<boolean | undefined>, default: undefined },\n /** 搜索区渲染开关(R27):false 关闭内置搜索区(组合式外置 FormRender);数据链路不变 */\n showSearch: { type: Boolean as PropType<boolean | undefined>, default: undefined },\n /** 分页条渲染开关(R28):false 关闭内置分页条(组合式外置 TablePagination);缺省模式 R13 不变 */\n showPagination: { type: Boolean as PropType<boolean | undefined>, default: undefined },\n /** 填充模式:根容器 h-full 纵向 flex,滚动区 flex-1 内滚;表头 sticky 钉住。\n * 父链需有确定高度(如页面布局的 .table-body);无确定高度时安全退化为自然高度。\n * 显式 prop 优先于布局 provide(key: \"tu-design:page-table-fill\");显式传 false 可强制关闭。\n * 纯布局属性,不进 defineTable/definition(virtual/height 例外),setup 期定版不支持运行时切换。 */\n fillHeight: { type: Boolean as PropType<boolean | undefined>, default: undefined },\n});\n\n// ---- 填充模式(fillHeight)---------------------------------------------------\n// 布局上下文:页面布局容器 provide 同名 key,slot 内 TableRender 自动 fill。\n// 字符串 key 跨包约定(常量 PAGE_TABLE_FILL_KEY 已导出,消费方零依赖时按字符串值 provide),\n// setup 期定版,不支持运行时切换(与 virtual/search 同约定)。\nconst pageTableFill = inject<boolean>(PAGE_TABLE_FILL_KEY, false);\nconst fill = props.fillHeight ?? pageTableFill;\n\nconst emit = defineEmits<{\n \"update:page-index\": [pageIndex: number];\n \"update:page-size\": [pageSize: number];\n \"sort-change\": [sort: SortableOptions | undefined];\n \"row-click\": [record: DataRecord, index: number, event: MouseEvent];\n /** 行双击(与 row-click 独立,双击会先后触发 click 两次,属预期) */\n \"row-dblclick\": [record: DataRecord, index: number, event: MouseEvent];\n /** 行右键;不主动 preventDefault */\n \"row-contextmenu\": [record: DataRecord, index: number, event: MouseEvent];\n /** 单元格点击(columnKey 定位列);冒泡并存——cell-click 触发时 row-click 也会触发 */\n \"cell-click\": [record: DataRecord, columnKey: string, index: number, event: MouseEvent];\n \"selection-change\": [rows: DataRecord[]];\n \"update:selected-keys\": [keys: Array<string | number>];\n /** 搜索:FormRender 校验通过后触发;载荷为当前表单值 */\n search: [values: DataRecord];\n /** 重置:FormRender 已重置为 defaults 后触发;载荷为重置后的表单值 */\n reset: [values: DataRecord];\n /** 服务端模式 onLoad 抛错/ rejects 时触发;下一次 load 开始时 error 投影清除 */\n \"load-error\": [error: Error];\n /** 可见列变化(受控回写通知 / v-model:visible-keys) */\n \"update:visible-keys\": [keys: string[]];\n /** 列显隐变化(受控/非受控均触发,供业务持久化;载荷 = 可见列 key 有序数组,columns 原序) */\n \"column-visibility-change\": [keys: string[]];\n}>();\n\ndefineSlots<{\n empty?: () => VNodeChild;\n /** 错误态占位(服务端模式 onLoad 失败时渲染,优先于数据区) */\n error?: (props: { error: Error | undefined; retry: () => void }) => VNodeChild;\n}>();\n\n/** 加载态骨架行数(R14) */\nconst SKELETON_ROWS = [1, 2, 3, 4, 5];\n\n/** 内置渲染器单例:render 工厂按列求值时复用(工厂本身轻量,仅为整洁) */\nconst RENDERS = columnRenders();\n\n// 聚合式直接复用 defineTable 建好的内核;拆分式在本组件 setup 内建内核\n// (TanStack useVueTable 只能在 setup 调用,故不能放进条件分支深处)\nif (props.definition && props.columns && import.meta.env.DEV) {\n console.warn(\"[tu-design] <TableRender> definition 与 columns 同时传入,已按 definition 渲染。\");\n}\nif (props.definition && props.rowSelection && import.meta.env.DEV) {\n console.warn(\n \"[tu-design] <TableRender> 聚合式下 rowSelection 请在 defineTable 配置,组件 prop 已忽略。\",\n );\n}\nconst instance =\n props.definition ??\n useTableRender({\n columns: props.columns ?? [],\n onLoad: props.onLoad,\n data: () => props.data,\n autoLoad: props.autoLoad,\n pageSizeOpts: props.pageSizeOpts,\n rowKey: props.rowKey,\n rowSelection: props.rowSelection,\n search: props.search,\n virtual: props.virtual,\n height: props.height,\n tree: props.tree,\n pageIndex: () => props.pageIndex,\n pageSize: () => props.pageSize,\n sort: () => props.sort,\n selectedKeys: () => props.selectedKeys,\n columnVisibility: props.definition?.columnVisibility,\n defaultVisibleKeys: () => props.defaultVisibleKeys,\n visibleKeys: () => props.visibleKeys,\n });\n// 拆分式已传 rowKey;聚合式由组件回填(S1:选择引擎依赖 rowKey 就绪)\ninstance.setRowKey(props.rowKey);\n\n// ---- 搜索表单(FormRender 联动) --------------------------------------------\n// 与 rowSelection 不同:聚合式下 prop 未被 definition 覆盖时回填引擎(不做聚合式忽略限制);\n// definition 与 prop 二选一,definition 优先,同传 DEV 警告\nif (props.definition && props.search) {\n if (instance.search && import.meta.env.DEV) {\n console.warn(\n \"[tu-design] <TableRender> 聚合式下 search 已在 defineTable 配置,组件 prop 已忽略。\",\n );\n } else {\n instance.setSearch(props.search);\n }\n}\n// search 不支持运行时切换(与 FormRender definition/form 同款约定),setup 期定版即可\nconst search = instance.search;\n\n// 列设置触发器的 Tooltip 受控开合(Tooltip 与 Popover 触发器嵌套会吞点击,故手动控制、不嵌套触发器)\nconst settingsTipOpen = ref(false);\n\n// ---- 列显隐(column visibility,R20–R26) ------------------------------------\n// R26:聚合式(columnVisibility.defaultVisibleKeys 经引擎解析回传)与拆分式 prop 同传 → definition 优先。\n// 引擎是唯一解析点;聚合式受控回填经 setVisibleKeys(normalize 等值守卫防回弹);\n// 拆分式由引擎受控 watch 直接同步(源 = props getter)\nif (\n props.definition &&\n instance.defaultVisibleKeys !== undefined &&\n props.defaultVisibleKeys !== undefined &&\n import.meta.env.DEV\n) {\n console.warn(\n \"[tu-design] <TableRender> 聚合式下 defaultVisibleKeys 已在 columnVisibility 配置,组件 prop 已忽略。\",\n );\n}\nwatch(\n () => props.visibleKeys,\n (next) => {\n if (props.definition && next !== undefined) instance.setVisibleKeys(next);\n },\n { immediate: true },\n);\n\n/** 当前搜索表单值快照(浅拷贝;无 search 时为空对象) */\nfunction searchValues(): DataRecord {\n return search ? { ...search.form.state.values } : {};\n}\n\n/** 搜索:校验已由 FormRender 完成;归位第 1 页重载,分页/排序取数自动携带最新表单值 */\nfunction onSearch() {\n emit(\"search\", searchValues());\n instance.reload(true);\n}\n\n/** 重置:FormRender 已同步重置为 defaults(TanStack reset 为同步 setState),此刻读取即 defaults */\nfunction onReset() {\n emit(\"reset\", searchValues());\n instance.reload(true);\n}\n\nconst columns = computed(() => instance.columns);\nconst rows = computed(() => instance.table.getRowModel().rows);\n/** 内部加载态 ∪ 外部受控加载态(R14) */\nconst loading = computed(() => props.loading === true || instance.loading.value);\nconst showPagination = computed(() => Math.ceil(instance.page.total / instance.page.pageSize) > 1);\n/** 内置分页条开关(R28):showPagination=false 关闭;R13 仅作用于缺省模式 */\nconst showPaginationBar = computed(() => showPagination.value && props.showPagination !== false);\n/** 内置搜索区开关(R27):配置了 search 且未被 showSearch=false 关闭;列设置触发器不受影响 */\nconst showSearchArea = computed(() => search !== undefined && props.showSearch !== false);\n\n// ---- 错误态(服务端模式 onLoad 失败) ----------------------------------------\n// loading 判定优先;error 优先于正常数据(load 开始时引擎已清除旧错误,loading 期间 error 恒空)\nconst loadError = computed(() => instance.error.value);\nconst showError = computed(() => !loading.value && loadError.value !== undefined);\n\nwatch(loadError, (err) => {\n if (err) emit(\"load-error\", err);\n});\n\nfunction retry() {\n instance.reload();\n}\n\n// ---- 行选择(S 系列) -------------------------------------------------------\nconst selection = computed(() => instance.selection);\nconst selectedKeys = instance.selectedKeys;\nconst hasSelection = computed(() => selection.value.enabled);\n\n// ---- 列显隐(column visibility,R20–R26) -------------------------------------\nconst visibleKeySet = computed(() => new Set(instance.visibleKeys.value));\n/** 可见业务列(columns 原序子集):header/body/骨架/colspan/sticky 全部基于此渲染(R23/R25) */\nconst visibleColumns = computed(() =>\n columns.value.filter((column) => visibleKeySet.value.has(column.key)),\n);\n/** 列设置触发器/面板开关(默认 true);false 时不渲染 UI,受控 API 不受影响 */\nconst showColumnSettings = computed(() => props.columnSettings ?? true);\n\nfunction isColumnVisible(key: string): boolean {\n return visibleKeySet.value.has(key);\n}\n\n/** 最少一列(R20):唯一可见列不可隐藏 */\nfunction canHideColumn(key: string): boolean {\n return !(instance.visibleKeys.value.length <= 1 && visibleKeySet.value.has(key));\n}\n\nfunction toggleColumnVisible(key: string) {\n if (!canHideColumn(key)) return;\n instance.setVisibleKeys(\n isColumnVisible(key)\n ? instance.visibleKeys.value.filter((k) => k !== key)\n : [...instance.visibleKeys.value, key],\n );\n}\n\nconst allColumnsVisible = computed(\n () => columns.value.length > 0 && visibleColumns.value.length === columns.value.length,\n);\n\nfunction selectAllColumns() {\n if (allColumnsVisible.value) return;\n instance.setVisibleKeys(columns.value.map((column) => column.key));\n}\n\nfunction resetColumns() {\n // R21:恢复 defaultVisibleKeys;未配置 = 全部可见\n instance.setVisibleKeys(instance.defaultVisibleKeys ?? columns.value.map((column) => column.key));\n}\n\n// 受控/非受控均通知:统一投影变化 → 双事件(载荷 = columns 原序可见 key)\nwatch(instance.visibleKeys, (keys) => {\n emit(\"update:visible-keys\", [...keys]);\n emit(\"column-visibility-change\", [...keys]);\n});\n\n/** 总列数 = 可见业务列 + 选择列(空态 colspan 与骨架行,S8/R23) */\nconst columnCount = computed(() => visibleColumns.value.length + (hasSelection.value ? 1 : 0));\n\n// ---- 固定列(sticky) --------------------------------------------------------\n\n// DEV 校验:sticky 偏移只能从数字 width(px)推算,否则降级普通列(columns setup 期定版,只查一次)\nfor (const column of columns.value) {\n if (column.fixed !== undefined && typeof column.width !== \"number\") {\n console.warn(\n `[tu-design] <TableRender> fixed 列 \"${column.key}\" 需要数字 width,已忽略 fixed。`,\n );\n }\n}\n\n// DEV 提示(一次性,columns setup 期定版,R32):多列宽表全列无数字 width 时,\n// min-width 横滚不可达 —— 宽表请为列声明数字 width(px)。\nif (columns.value.length >= 10 && !columns.value.some((c) => typeof c.width === \"number\")) {\n console.warn(\n `[tu-design] <TableRender> ${columns.value.length} 列均无数字 width,` +\n `窄容器下不会出现横向滚动(R32);宽表请为列声明数字 width(px)。`,\n );\n}\n\n/** sticky 单元格映射(纯渲染层 computed,不进 TanStack pinning state):\n * 选择列视作最左 fixed 列参与累计(offset 0);fixed-left 按列序累加,\n * fixed-right 从最右列反向累计。edge = 该 sticky 组朝滚动方向的交界列(加分隔边框)。\n * 全部基于**可见集**(R23):sticky 组因隐藏变空则无该组输出(不输出边框)。\n */\nconst stickyOf = computed<StickyMap>(() => {\n const map: StickyMap = new Map();\n // instance.columns 是联合数组(聚合式 any / 拆分式 DataRecord),联合上的 filter\n // 类型谓词重载解析不可靠,故 map 提取时以断言收窄 width(条件已含 typeof 守卫)\n const lefts = visibleColumns.value\n .filter((column) => column.fixed === \"left\" && typeof column.width === \"number\")\n .map((column) => ({ key: column.key, width: column.width as number }));\n const rights = visibleColumns.value\n .filter((column) => column.fixed === \"right\" && typeof column.width === \"number\")\n .map((column) => ({ key: column.key, width: column.width as number }));\n\n let acc = 0;\n if (hasSelection.value) {\n map.set(SELECTION_CELL, { side: \"left\", offset: 0, edge: lefts.length === 0 });\n acc = selection.value.width;\n }\n lefts.forEach((left, index) => {\n map.set(left.key, { side: \"left\", offset: acc, edge: index === lefts.length - 1 });\n acc += left.width;\n });\n\n let racc = 0;\n for (let index = rights.length - 1; index >= 0; index--) {\n const right = rights[index]!;\n map.set(right.key, { side: \"right\", offset: racc, edge: index === 0 });\n racc += right.width;\n }\n return map;\n});\n\n// ---- 表格 min-width(列宽硬约束,R32) ----------------------------------------\n// 可见业务列数字 width 之和(含选择列)作为 <table> min-width 下限:\n// 容器不足 → 表格被顶到 Σwidth,auto 布局下列渲染宽度 == 指定宽度,stickyOf 偏移精确成立,\n// 滚动区 overflow-x-auto 横滚;容器充足 → 表格仍 100% 拉伸(有宽列可能被拉伸,\n// sticky 偏移按指定值累计的漂移为既有限制,非 R32 引入)。\n// 字符串 width 仅渲染提示值,不参与求和(与 stickyOf 口径一致);和为 0 不挂 style(零回归)。\nconst tableMinWidth = computed(() => {\n let sum = 0;\n for (const column of visibleColumns.value) {\n if (typeof column.width === \"number\" && column.width > 0) sum += column.width;\n }\n if (hasSelection.value && selection.value.width > 0) sum += selection.value.width;\n return sum;\n});\n\n/** 列宽 inline style 值(R33):数字补 px 单位——Vue :style 不自动加单位,\n * 裸数字会被浏览器当非法 CSS 值丢弃,列宽即失效;字符串视为已带单位原样输出。 */\nfunction widthOf(width?: number | string) {\n return typeof width === \"number\" ? `${width}px` : width;\n}\n\n/** 表头全选三态(S10):本页可选行与选中集求交派生(TanStack getter 追踪不稳,自算) */\nconst selectableKeys = computed(() =>\n rows.value.filter((row) => row.getCanSelect()).map((row) => rowKeyOf(row.original, row.index)),\n);\nconst headerChecked = computed(\n () =>\n hasSelection.value &&\n selection.value.type === \"checkbox\" &&\n selectableKeys.value.length > 0 &&\n selectableKeys.value.every((key) => selectedKeys.value.has(key)),\n);\nconst headerIndeterminate = computed(\n () =>\n hasSelection.value &&\n !headerChecked.value &&\n selectableKeys.value.some((key) => selectedKeys.value.has(key)),\n);\n\nfunction onHeaderSelect(checked: boolean) {\n instance.table.toggleAllPageRowsSelected(checked);\n}\n\n/** 行选择控件切换;radio 不可取消由引擎 S4 守卫,不选中态点击传 checked=true */\nfunction onRowSelect(line: { key: string }, checked: boolean) {\n instance.toggleRowSelected(line.key, checked);\n}\n\n// 选中集变化 → 对外事件(S7):排序/翻页不改变选中集,故不会误发\nwatch(instance.selectedKeys, (keys) => {\n emit(\"selection-change\", [...selection.value.value]);\n emit(\"update:selected-keys\", [...keys]);\n});\n\n/** 行 → 单元格值矩阵:render > formatter > record[key](R17) */\nconst body = computed<TableBodyLine[]>(() => {\n // 渲染器工厂按列求值一次(而非每单元格),避免用户工厂内的重分配被放大\n const renderFns = new Map(\n columns.value.filter((c) => c.render).map((c) => [c, c.render!(RENDERS)]),\n );\n return rows.value.map((row) => ({\n /** TanStack Row:树形渲染读 depth / getCanExpand / getIsExpanded / toggleExpanded */\n row,\n key: rowKeyOf(row.original, row.index),\n index: row.index,\n record: row.original,\n /** 行级可选过滤(S5):selectable 谓词交由引擎 enableRowSelection 判定 */\n canSelect: row.getCanSelect(),\n // 可见列的值矩阵(列显隐只裁剪列;R25 状态不受影响)\n cells: visibleColumns.value.map((column): VNodeChild => {\n const render = renderFns.get(column);\n if (render) return render(row.original, row.index, column);\n if (column.formatter) return column.formatter(row.original) as VNodeChild;\n return String(row.original[column.key] ?? \"\");\n }),\n }));\n});\n\n// ---- 树形数据(T 系列) ------------------------------------------------------\n// 引擎是唯一解析点(无效配置已 warn 并忽略,回传 undefined);tree 为 undefined 时不渲染缩进与 caret\nconst tree = instance.tree;\nconst treeIndent = tree?.indentSize ?? 16;\n\nlet missingRowKeyWarned = false;\n\n/** 行主键:rowKey 字段缺失时以行索引兜底(R3) */\nfunction rowKeyOf(record: DataRecord, index: number): string {\n const value = record[props.rowKey];\n if (value === undefined || value === null) {\n if (!missingRowKeyWarned && import.meta.env.DEV) {\n missingRowKeyWarned = true;\n console.warn(\n `[tu-design] <TableRender> 部分记录缺少 rowKey 字段 \"${props.rowKey}\",已退化为按行索引标识。`,\n );\n }\n return `index-${index}`;\n }\n return String(value);\n}\n\n// ---- 虚拟滚动 / 填充模式 ------------------------------------------------------\n// definition 优先于 prop(配置定版,不支持运行时切换)\nconst virtualRaw = instance.virtual ?? props.virtual;\nconst heightRaw = instance.height ?? props.height;\n// fill 模式自带真实滚动盒(flex-1 实测高度),virtual 无需显式 height\nif (virtualRaw === true && heightRaw === undefined && !fill) {\n console.warn(\"[tu-design] <TableRender> virtual 需要配置 height,已降级普通渲染。\");\n}\nconst virtualEnabled = virtualRaw === true && (heightRaw !== undefined || fill);\nconst scrollHeight = computed(() => (typeof heightRaw === \"number\" ? `${heightRaw}px` : heightRaw));\n/** 表头 sticky 仅在组件内存在真实纵向滚动盒时生效(fill / virtual),普通模式不挂载,行为不变 */\nconst theadSticky = fill || virtualEnabled;\n/** 滚动区样式:virtual 用固定 height;fill 交给 flex 分配(二者同传以 fill 优先) */\nconst scrollStyle = computed(() => {\n if (fill || !virtualEnabled) return undefined;\n return { height: scrollHeight.value, overflowY: \"auto\" as const };\n});\n/** sticky 表头普通列类:不透明底防行内容透出;分隔线归 th(thead 行级 border 会随行滚走);\n * z-20 高于表体 fixed 列(--z-sticky: 10),纵向滚动行滑过表头时不穿透;\n * 表头 fixed 列的 z 由 stickyStyle inline style(var(--z-sticky-head))提供,inline 优先级天然覆盖此处 class */\nconst theadThClass = theadSticky ? \"sticky top-0 z-20 border-b border-border bg-background\" : \"\";\n/** sticky 态 table 改分离边框:preflight 为 border-collapse: collapse,\n * 折叠边框几何归属 table,Chrome 下 sticky th 粘住后自身 border-b 渲染丢失;\n * separate + spacing-0 恢复单元格边框。普通模式保持 collapse,零回归。 */\nconst tableClass = theadSticky ? \"border-separate border-spacing-0\" : \"\";\n\nconst scrollEl = ref<HTMLElement | null>(null);\nconst theadEl = ref<HTMLElement | null>(null);\n/** 滚动容器内 thead 占据的前缀高度(scrollMargin);表头内容静态,挂载后测量一次 */\nconst theadOffset = ref(0);\n\n// 仅 virtual: true 且 height 就绪时创建(配置 setup 期定版,顶层条件分支可安全注册生命周期)\nconst virtualizerRef = virtualEnabled\n ? useVirtualizer(\n computed(() => ({\n count: rows.value.length, // 翻页/重载后行窗口变化 → options 更新(setOptions 自动生效)\n getScrollElement: () => scrollEl.value,\n estimateSize: () => 40,\n overscan: 8,\n getItemKey: (index: number) => rowKeyOf(rows.value[index]!, index), // rowKey 作为虚拟行 key\n scrollMargin: theadOffset.value, // thead 在滚动容器内的 offset 前缀\n })),\n )\n : null;\n\nonMounted(() => {\n if (virtualEnabled) theadOffset.value = theadEl.value?.offsetHeight ?? 0;\n});\n\nconst virtualRows = computed(() => (virtualizerRef ? virtualizerRef.value.getVirtualItems() : []));\nconst virtualTotal = computed(() => (virtualizerRef ? virtualizerRef.value.getTotalSize() : 0));\n/** 窗口行 + 对应全量行数据(cells 矩阵已由 body computed 缓存,虚拟化只裁剪 DOM 节点) */\nconst virtualLines = computed(() =>\n virtualRows.value.map((row) => ({ row, line: body.value[row.index]! })),\n);\nconst padTop = computed(() => virtualRows.value[0]?.start ?? 0);\nconst padBottom = computed(() => {\n const items = virtualRows.value;\n return items.length === 0 ? 0 : Math.max(0, virtualTotal.value - items[items.length - 1]!.end);\n});\n\n/** 行高动态测量:measureElement 读 data-index 把实测高度写回(行内容高度可变,不假设固定行高)。\n * 行组件为函数 ref,拿到的是组件实例,需经 $el 取真实 tr。 */\nfunction measureRow(node: Element | ComponentPublicInstance | null) {\n const el = node instanceof Element ? node : (node?.$el as Element | undefined);\n if (el instanceof Element) virtualizerRef?.value.measureElement(el);\n}\n\n/** aria-sort 仅在该列当前被排序时标注(R16) */\nfunction ariaSort(column: TableColumnOptions): \"ascending\" | \"descending\" | undefined {\n if (instance.sort.value?.key !== column.key) return undefined;\n return instance.sort.value.direction === \"asc\" ? \"ascending\" : \"descending\";\n}\n\nfunction sortMark(column: TableColumnOptions): string {\n const direction = instance.sort.value?.key === column.key ? instance.sort.value.direction : \"\";\n return direction === \"asc\" ? \"↑\" : direction === \"desc\" ? \"↓\" : \"\";\n}\n\nfunction onSort(key: string) {\n instance.toggleSort(key);\n emit(\"sort-change\", instance.sort.value);\n}\n\nfunction onPageIndex(pageIndex: number) {\n instance.setPageIndex(pageIndex);\n lastEmittedPage.pageIndex = pageIndex;\n emit(\"update:page-index\", pageIndex);\n}\n\nfunction onPageSize(pageSize: number) {\n instance.setPageSize(pageSize);\n lastEmittedPage.pageSize = pageSize;\n emit(\"update:page-size\", pageSize);\n}\n\n// ---- 受控模式(v-model):page 投影 → update:* 通知 ---------------------------\n// 仅 page-index/page-size 至少一方受控时安装;lastEmittedPage 去重——\n// 动作路径已 emit 过的值不再重复发(受控回写/内部归位只通知「未通知过的」变化)\nconst pageControlled = () => props.pageIndex !== undefined || props.pageSize !== undefined;\nconst lastEmittedPage = {\n pageIndex: undefined as number | undefined,\n pageSize: undefined as number | undefined,\n};\n\nif (pageControlled()) {\n watch(\n () => [instance.page.pageIndex, instance.page.pageSize] as const,\n ([pageIndex, pageSize]) => {\n if (pageIndex !== lastEmittedPage.pageIndex) {\n lastEmittedPage.pageIndex = pageIndex;\n emit(\"update:page-index\", pageIndex);\n }\n if (pageSize !== lastEmittedPage.pageSize) {\n lastEmittedPage.pageSize = pageSize;\n emit(\"update:page-size\", pageSize);\n }\n },\n );\n}\n\nfunction onRowClick(record: DataRecord, index: number, event: MouseEvent) {\n emit(\"row-click\", record, index, event);\n}\n\nfunction onRowDblclick(record: DataRecord, index: number, event: MouseEvent) {\n emit(\"row-dblclick\", record, index, event);\n}\n\nfunction onRowContextmenu(record: DataRecord, index: number, event: MouseEvent) {\n emit(\"row-contextmenu\", record, index, event);\n}\n\nfunction onCellClick(record: DataRecord, columnKey: string, index: number, event: MouseEvent) {\n emit(\"cell-click\", record, columnKey, index, event);\n}\n\ndefineExpose({\n table: instance.table,\n page: instance.page,\n sort: instance.sort,\n loading: instance.loading,\n error: instance.error,\n visibleKeys: instance.visibleKeys,\n setVisibleKeys: instance.setVisibleKeys,\n reload: instance.reload,\n toggleSort: onSort,\n setPageIndex: onPageIndex,\n setPageSize: onPageSize,\n selection: instance.selection,\n selectedKeys: instance.selectedKeys,\n setSelection: instance.setSelection,\n clearSelection: instance.clearSelection,\n});\n</script>\n\n<template>\n <div :class=\"cn('w-full', fill && 'flex h-full min-h-0 flex-col', $attrs.class)\">\n <!-- 搜索区 + 列设置触发器:同行右对齐(items-end);无搜索时触发器位于表格上方(R27:showSearch=false 关闭搜索区) -->\n <div\n v-if=\"showSearchArea || showColumnSettings\"\n :class=\"cn('mb-2 flex items-end justify-between gap-2', fill && 'shrink-0')\"\n >\n <FormRender\n v-if=\"showSearchArea\"\n class=\"min-w-0 flex-1\"\n :definition=\"search\"\n :searchable=\"search.actions ? undefined : true\"\n @search=\"onSearch\"\n @reset=\"onReset\"\n />\n\n <!-- 列设置:Popover 面板(R20 最少一列 / R21 重置 / R22 不含选择列);\n 触发钮 Tooltip 手动受控开合(Tooltip 与 Popover 触发器嵌套会吞点击,故并列渲染、不走 hover 自动触发) -->\n <template v-if=\"showColumnSettings\">\n <Popover align=\"end\" content-class=\"w-56 p-0\">\n <Button\n variant=\"ghost\"\n size=\"icon\"\n aria-label=\"列设置\"\n aria-haspopup=\"true\"\n @pointerenter=\"settingsTipOpen = true\"\n @pointerleave=\"settingsTipOpen = false\"\n >\n <!-- lucide Settings2(内联 SVG,跟随项目图标现状) -->\n <svg\n xmlns=\"http://www.w3.org/2000/svg\"\n viewBox=\"0 0 24 24\"\n fill=\"none\"\n stroke=\"currentColor\"\n stroke-width=\"2\"\n stroke-linecap=\"round\"\n stroke-linejoin=\"round\"\n class=\"size-4\"\n aria-hidden=\"true\"\n >\n <path d=\"M20 7h-9\" />\n <path d=\"M14 17H5\" />\n <circle cx=\"17\" cy=\"17\" r=\"3\" />\n <circle cx=\"7\" cy=\"7\" r=\"3\" />\n </svg>\n </Button>\n <template #content>\n <div class=\"flex items-center justify-end gap-3 px-3 py-2\">\n <button\n type=\"button\"\n class=\"text-muted-foreground hover:text-foreground cursor-pointer text-xs disabled:cursor-not-allowed disabled:opacity-50\"\n :disabled=\"allColumnsVisible\"\n @click=\"selectAllColumns\"\n >\n 全选\n </button>\n <button\n type=\"button\"\n class=\"text-muted-foreground hover:text-foreground cursor-pointer text-xs\"\n @click=\"resetColumns\"\n >\n 重置\n </button>\n </div>\n <Separator />\n <div class=\"max-h-64 overflow-y-auto py-1\">\n <div\n v-for=\"column in columns\"\n :key=\"column.key\"\n data-column-item\n :data-column-key=\"column.key\"\n class=\"hover:bg-accent/50 flex h-8 cursor-pointer items-center gap-2 px-3\"\n @click=\"toggleColumnVisible(column.key)\"\n >\n <Checkbox\n :checked=\"isColumnVisible(column.key)\"\n :disabled=\"!canHideColumn(column.key)\"\n @update:checked=\"toggleColumnVisible(column.key)\"\n @click.stop\n />\n <span class=\"min-w-0 flex-1 truncate\">{{ column.title }}</span>\n <!-- 有效 fixed 列(数字 width)标识 -->\n <svg\n v-if=\"column.fixed !== undefined && typeof column.width === 'number'\"\n xmlns=\"http://www.w3.org/2000/svg\"\n viewBox=\"0 0 24 24\"\n fill=\"none\"\n stroke=\"currentColor\"\n stroke-width=\"2\"\n stroke-linecap=\"round\"\n stroke-linejoin=\"round\"\n class=\"text-muted-foreground size-3 shrink-0\"\n aria-hidden=\"true\"\n >\n <path d=\"M12 17v5\" />\n <path\n d=\"M9 10.76a2 2 0 0 1-1.11 1.79l-1.78.9A2 2 0 0 0 5 15.24V16a1 1 0 0 0 1 1h12a1 1 0 0 0 1-1v-.76a2 2 0 0 0-1.11-1.79l-1.78-.9A2 2 0 0 1 15 10.76V7h1a2 2 0 0 0 0-4H8a2 2 0 0 0 0 4h1z\"\n />\n </svg>\n </div>\n </div>\n </template>\n </Popover>\n <!-- 纯受控气泡(无默认插槽,不渲染触发器):开合由触发钮 pointerenter/leave 驱动 -->\n <Tooltip :open=\"settingsTipOpen\" content=\"列设置\" />\n </template>\n </div>\n\n <!-- 滚动容器:横向滚动时 fixed 列 sticky 生效;virtual/fill 模式兼任纵向滚动(分页条不参与滚动) -->\n <div\n ref=\"scrollEl\"\n :class=\"cn('overflow-x-auto', fill && 'min-h-0 flex-1 overflow-y-auto')\"\n :style=\"scrollStyle\"\n >\n <table\n class=\"w-full caption-bottom text-sm\"\n :class=\"tableClass\"\n :style=\"tableMinWidth > 0 ? { minWidth: `${tableMinWidth}px` } : undefined\"\n >\n <thead ref=\"theadEl\" :class=\"theadSticky ? undefined : '[&_tr]:border-b'\">\n <tr>\n <!-- 选择列:checkbox 型表头为本页全选三态(S3/S10);radio 型占位;视作最左固定列 -->\n <th\n v-if=\"hasSelection\"\n scope=\"col\"\n class=\"h-10 w-12 px-2 align-middle font-medium text-muted-foreground\"\n :class=\"[stickyClass(stickyOf, SELECTION_CELL), theadThClass]\"\n :style=\"[\n { width: `${selection.width}px` },\n stickyStyle(stickyOf, SELECTION_CELL, true),\n ]\"\n >\n <Checkbox\n v-if=\"selection.type === 'checkbox'\"\n :checked=\"headerIndeterminate ? 'indeterminate' : headerChecked\"\n :aria-label=\"'全选本页'\"\n @update:checked=\"onHeaderSelect\"\n />\n </th>\n <th\n v-for=\"column in visibleColumns\"\n :key=\"column.key\"\n scope=\"col\"\n class=\"h-10 px-2 align-middle font-medium text-muted-foreground\"\n :class=\"[stickyClass(stickyOf, column.key), theadThClass]\"\n :style=\"[\n { width: widthOf(column.width), textAlign: column.align },\n stickyStyle(stickyOf, column.key, true),\n ]\"\n :aria-sort=\"ariaSort(column)\"\n >\n <button\n v-if=\"column.sortable\"\n type=\"button\"\n class=\"inline-flex items-center gap-1 hover:text-foreground\"\n @click=\"onSort(column.key)\"\n >\n {{ column.title }}\n <span aria-hidden=\"true\" class=\"text-xs\">{{ sortMark(column) }}</span>\n </button>\n <template v-else>{{ column.title }}</template>\n </th>\n </tr>\n </thead>\n\n <tbody class=\"[&_tr:last-child]:border-0\">\n <!-- 加载态:固定 5 行骨架(R14);选择列一并占位(S8);骨架不虚拟化;loading 判定优先 -->\n <template v-if=\"loading\">\n <tr v-for=\"row in SKELETON_ROWS\" :key=\"row\" data-skeleton>\n <td\n v-if=\"hasSelection\"\n class=\"p-2 align-middle\"\n :class=\"stickyClass(stickyOf, SELECTION_CELL)\"\n :style=\"stickyStyle(stickyOf, SELECTION_CELL, false)\"\n >\n <Skeleton class=\"size-4\" />\n </td>\n <td\n v-for=\"column in visibleColumns\"\n :key=\"column.key\"\n class=\"p-2 align-middle\"\n :class=\"stickyClass(stickyOf, column.key)\"\n :style=\"[{ textAlign: column.align }, stickyStyle(stickyOf, column.key, false)]\"\n >\n <Skeleton class=\"h-4 w-full\" />\n </td>\n </tr>\n </template>\n\n <!-- 错误态:error 优先于正常数据;插槽可自定义(slot props { error, retry }) -->\n <template v-else-if=\"showError\">\n <tr data-error>\n <td :colspan=\"columnCount\" class=\"p-8 text-center text-muted-foreground\">\n <slot name=\"error\" :error=\"loadError\" :retry=\"retry\">\n <div class=\"flex flex-col items-center gap-3\">\n <p>{{ loadError?.message ?? \"加载失败\" }}</p>\n <Button variant=\"outline\" size=\"sm\" @click=\"retry\">重试</Button>\n </div>\n </slot>\n </td>\n </tr>\n </template>\n\n <!-- 虚拟滚动:窗口行 + 前后占位行(总高撑开滚动区间;行高经 measureElement 动态测量) -->\n <template v-else-if=\"virtualEnabled\">\n <tr aria-hidden=\"true\" data-virtual-pad :style=\"{ height: `${padTop}px` }\">\n <td :colspan=\"columnCount\" class=\"border-0 p-0\"></td>\n </tr>\n <TableBodyRow\n v-for=\"item in virtualLines\"\n :key=\"item.line.key\"\n :ref=\"measureRow\"\n :data-index=\"item.row.index\"\n :line=\"item.line\"\n :columns=\"visibleColumns\"\n :selection=\"hasSelection ? selection.type : undefined\"\n :selected=\"selectedKeys.has(item.line.key)\"\n :sticky=\"stickyOf\"\n :tree-indent=\"tree ? treeIndent : undefined\"\n @select=\"(checked: boolean) => onRowSelect(item.line, checked)\"\n @row-click=\"onRowClick(item.line.record, item.line.index, $event)\"\n @row-dblclick=\"onRowDblclick(item.line.record, item.line.index, $event)\"\n @row-contextmenu=\"onRowContextmenu(item.line.record, item.line.index, $event)\"\n @cell-click=\"\n (columnKey: string, event: MouseEvent) =>\n onCellClick(item.line.record, columnKey, item.line.index, event)\n \"\n />\n <tr aria-hidden=\"true\" data-virtual-pad :style=\"{ height: `${padBottom}px` }\">\n <td :colspan=\"columnCount\" class=\"border-0 p-0\"></td>\n </tr>\n </template>\n\n <template v-else>\n <TableBodyRow\n v-for=\"line in body\"\n :key=\"line.key\"\n :line=\"line\"\n :columns=\"visibleColumns\"\n :selection=\"hasSelection ? selection.type : undefined\"\n :selected=\"selectedKeys.has(line.key)\"\n :sticky=\"stickyOf\"\n :tree-indent=\"tree ? treeIndent : undefined\"\n @select=\"(checked: boolean) => onRowSelect(line, checked)\"\n @row-click=\"onRowClick(line.record, line.index, $event)\"\n @row-dblclick=\"onRowDblclick(line.record, line.index, $event)\"\n @row-contextmenu=\"onRowContextmenu(line.record, line.index, $event)\"\n @cell-click=\"\n (columnKey: string, event: MouseEvent) =>\n onCellClick(line.record, columnKey, line.index, event)\n \"\n />\n </template>\n\n <!-- 空态:横跨全列的单单元格,不虚拟化;错误态优先 -->\n <tr v-if=\"!loading && !showError && body.length === 0\" data-empty>\n <td :colspan=\"columnCount\" class=\"p-8 text-center text-muted-foreground\">\n <slot name=\"empty\">{{ emptyText ?? \"暂无数据\" }}</slot>\n </td>\n </tr>\n </tbody>\n </table>\n </div>\n\n <!-- R31:手动接线(须经 onPageIndex/onPageSize 包装器保留受控去重);显式补 border-t 与 size select 保持现状 -->\n <TablePagination\n v-if=\"showPaginationBar\"\n :class=\"cn('border-t', fill && 'shrink-0')\"\n :page-index=\"instance.page.pageIndex\"\n :page-size=\"instance.page.pageSize\"\n :page-size-opts=\"instance.page.pageSizeOpts\"\n :total=\"instance.page.total\"\n :show-size-select=\"true\"\n @update:page-index=\"onPageIndex\"\n @update:page-size=\"onPageSize\"\n />\n </div>\n</template>\n"
42
42
  },
43
43
  {
44
44
  "path": "table-render/column-renders.ts",
@@ -80,7 +80,7 @@
80
80
  "path": "table-render/types.ts",
81
81
  "type": "registry:lib",
82
82
  "target": "components/ui/table-render/types.ts",
83
- "content": "import type { ColumnRender, ColumnRenders } from \"./column-renders\";\nimport type { FormRenderDefinition } from \"../form-render\";\nimport type { Row, Table as TanstackTable } from \"@tanstack/vue-table\";\nimport type { MaybeRefOrGetter, Ref, VNodeChild } from \"vue\";\n\n/** 任意数据行(表格是弱类型数据容器,行结构由调用方的 T 决定) */\nexport interface DataRecord {\n [key: string]: any;\n}\n\n/** 表体行渲染单元:TanStack Row 引用 + 可见列值矩阵(TableRender → TableBodyRow) */\nexport interface TableBodyLine {\n /** TanStack Row:树形渲染读 depth / getCanExpand / getIsExpanded / toggleExpanded */\n row: Row<DataRecord>;\n key: string;\n index: number;\n record: DataRecord;\n /** 行级可选过滤(S5):selectable 谓词交由引擎 enableRowSelection 判定 */\n canSelect: boolean;\n /** 可见列的值矩阵(列显隐只裁剪列;R25 状态不受影响) */\n cells: VNodeChild[];\n}\n\n/**\n * 列配置。\n *\n * 命名总纲(D10):能力/性质用 `-able` 形容词(sortable/ellipsis),\n * 配置值用名词(title/align/width),无 `allow-*`。\n */\nexport interface TableColumnOptions<T extends DataRecord = DataRecord> {\n /** 列标识,同时作为默认取值字段 */\n key: string;\n title: string;\n align?: \"left\" | \"center\" | \"right\";\n width?: number | string;\n /** 自定义单元格渲染,取值链 render > formatter > record[key](R17) */\n render?: (r: ColumnRenders<T>) => ColumnRender<T>;\n /** 纯数据格式化;render 存在时被忽略 */\n formatter?: (record: T) => string | number | Date | undefined;\n /** 超宽截断 + 原生 title 提示(R15);\"tooltip\" 形态改用库内 Tooltip(不设原生 title) */\n ellipsis?: boolean | \"tooltip\";\n /** 是否可排序(能力开关) */\n sortable?: boolean;\n /** 初始排序方向;需 sortable: true,否则 DEV 警告并忽略(R7) */\n defaultSort?: \"asc\" | \"desc\";\n /** 固定列:横向滚动时 sticky 在左/右;须同时提供数字 width,否则 DEV 警告并按普通列渲染 */\n fixed?: \"left\" | \"right\";\n}\n\nexport interface PageableOptions {\n /** 1-based 页码(对外 API 唯一口径) */\n pageIndex: number;\n pageSize: number;\n total: number;\n /** 只读:状态投影不允许调用方直接改写每页条数选项 */\n pageSizeOpts: readonly number[];\n}\n\nexport interface SortableOptions {\n key: string;\n direction: \"asc\" | \"desc\";\n}\n\n/** onLoad 入参:数据协议与 x-render 同构,request 生态由调用方自理 */\nexport interface TableLoadParams<T extends DataRecord = DataRecord> {\n /** 搜索表单值(来自 options.search 的表单当前值);未配置 search 时为 {} */\n form: DataRecord;\n page: PageableOptions;\n /** 无排序或已取消排序时为 undefined */\n sort?: SortableOptions;\n /** 回写数据;total 缺省时保留旧值(R10) */\n update: (data: T[], total?: number) => void;\n}\n\n/** defineTable 的声明式配置 */\nexport interface DefineTableOptions<T extends DataRecord = DataRecord> {\n columns: TableColumnOptions<T>[];\n /** 服务端模式数据源;与 data 二选一,onLoad 优先 */\n onLoad?: (params: TableLoadParams<T>) => void | Promise<unknown>;\n /** 静态模式数据源(本地分页/排序) */\n data?: T[];\n /** 是否在挂载后自动加载,默认 true;仅服务端模式生效 */\n autoLoad?: boolean;\n /**\n * 每页条数 / 受控每页条数(D11)。约定:传入(非 undefined)即受控,缺省(undefined)时\n * 以默认 10 行运行;R9 归位:pageIndex 未受控时内部归位第 1 页并经 update:page-index 通知,\n * 两个都受控时由父层自行联动。支持传 ref/getter(聚合式受控)\n */\n pageSize?: MaybeRefOrGetter<number | undefined>;\n pageSizeOpts?: number[];\n /** 行选择:radio 单选 / checkbox 多选;字符串为简写(S2) */\n rowSelection?: \"radio\" | \"checkbox\" | TableSelectionOptions<T>;\n /** 行主键字段;rowSelection 启用且此值无效时禁用选择(S1) */\n rowKey?: string;\n /**\n * 搜索表单(defineForm 返回值):仅服务端模式生效,每次 onLoad 的 form 参数\n * 携带 `search.form.state.values` 当前值。静态模式传入时 DEV 警告并忽略。\n * 泛型为 any:FormRenderDefinition 对 T 不变(FormRenderItem.key 字面量收窄),\n * DataRecord 版会拒收一切具体 defineForm<Q> 结果(对齐 FormRender.vue prop 约定)。\n */\n search?: FormRenderDefinition<any>;\n /** 虚拟滚动:开启后表体行在当前页行窗口内虚拟化(分页语义不变);须同时配置 height,否则 DEV 警告并降级普通渲染 */\n virtual?: boolean;\n /** 虚拟滚动容器高度(数字 px 或 CSS 高度);仅 virtual: true 时生效 */\n height?: number | string;\n /** 树形数据:子行展开/收起(展开按钮在首个业务列内);配置无效时 DEV 警告并忽略 */\n tree?: TreeOptions;\n /**\n * 受控页码(1-based,D11)。约定:传入(非 undefined)即受控,缺省保持非受控;\n * 内部翻页经 update:page-index 通知,外部变更经受控 watch 同步(语义等值跳过,防回弹循环)\n */\n pageIndex?: MaybeRefOrGetter<number | undefined>;\n /** 受控排序。内部/外部变化均经 sort-change 通知;指向不可排序列时 DEV 警告并忽略 */\n sort?: MaybeRefOrGetter<SortableOptions | undefined>;\n /** 受控选中集(数组,与 update:selected-keys 载荷同构)。经 setSelection 写入(S5 过滤/S12 待定 key 继承) */\n selectedKeys?: MaybeRefOrGetter<Array<string | number> | undefined>;\n /**\n * 列显隐:默认可见列集(R21「重置」基准;未知 key 静默忽略;未传 = 全部可见)。\n * 列显隐不触发 onLoad、不重置 pageIndex/sort/selectedKeys(R25)\n */\n columnVisibility?: ColumnVisibilityOptions;\n /**\n * 受控可见列 key(columns 原序子集)。约定:传入(非 undefined)即受控;\n * 内部显隐经 update:visible-keys 通知;空数组钳制为首列可见(R24,warn 一次)\n */\n visibleKeys?: MaybeRefOrGetter<string[] | undefined>;\n /**\n * 拆分式默认可见列集;与聚合式 columnVisibility.defaultVisibleKeys 同传时\n * DEV 警告 definition 优先(R26)\n */\n defaultVisibleKeys?: MaybeRefOrGetter<string[] | undefined>;\n}\n\n/** 树形数据配置(T 系列) */\nexport interface TreeOptions {\n /** 子行字段名,默认 \"children\" */\n childrenKey?: string;\n /** 默认全部展开,默认 false */\n defaultExpandAll?: boolean;\n /** 每层缩进 px,默认 16 */\n indentSize?: number;\n}\n\n/** 列显隐配置(R20–R24) */\nexport interface ColumnVisibilityOptions {\n /** 默认可见列 key 列表(R21「重置」基准);未知 key 静默忽略;未传 = 全部可见 */\n defaultVisibleKeys?: string[];\n}\n\n/** 行选择配置(S 系列) */\nexport interface TableSelectionOptions<T extends DataRecord = DataRecord> {\n type: \"radio\" | \"checkbox\";\n /** 选择列宽,默认 48 */\n width?: number;\n /** 行级可选过滤;false 的行选择控件置灰且被全选跳过(S5) */\n selectable?: (record: T) => boolean;\n /** radio 再点已选中行是否取消,默认 true(S4) */\n cancelable?: boolean;\n /** 翻页/重载后是否保留选中,默认 true(S6) */\n reserveOnPageChange?: boolean;\n}\n\n/** useTableRender 的入参:data 额外支持 ref/getter(拆分模式下 props 天然响应式) */\nexport interface UseTableRenderOptions<T extends DataRecord = DataRecord> extends Omit<\n DefineTableOptions<T>,\n \"data\"\n> {\n data?: MaybeRefOrGetter<T[] | undefined>;\n}\n\n/** defineTable / useTableRender 的返回物:列配置 + 引擎实例 + 只读状态 + 实例动作 */\nexport interface TableRenderDefinition<T extends DataRecord = DataRecord> {\n columns: TableColumnOptions<T>[];\n /** TanStack 表格实例(逃逸舱口) */\n table: TanstackTable<T>;\n page: Readonly<PageableOptions>;\n sort: Readonly<{ value: SortableOptions | undefined }>;\n loading: Readonly<{ value: boolean }>;\n /** 重新加载;resetPage 为 true 时先回到第 1 页(R12) */\n reload: (resetPage?: boolean) => void;\n /** 排序三态切换:无 → asc → desc → 取消(R8) */\n toggleSort: (key: string) => void;\n setPageIndex: (pageIndex: number) => void;\n setPageSize: (pageSize: number) => void;\n /** 选中行快照(含跨页保留行;跨页行可能为过期数据,见 S6) */\n selection: Readonly<{\n value: T[];\n /** rowSelection 配置有效(含 rowKey 就绪)时为 true(S1) */\n enabled: boolean;\n type: \"radio\" | \"checkbox\";\n width: number;\n }>;\n /** 选中主键集合;每次选中集变化替换为新 Set(S7) */\n selectedKeys: Readonly<Ref<Set<string | number>>>;\n /** 程序化设置选中集;不存在的 key 保留(S12) */\n setSelection: (keys: Array<string | number>) => void;\n clearSelection: () => void;\n /** 行控件切换:checked 为 false 时移除(radio 受 cancelable 约束,S4) */\n toggleRowSelected: (key: string, checked: boolean) => void;\n /** 搜索表单定义(options.search 校验后的回传,供 TableRender 渲染搜索区;被忽略时为 undefined) */\n search: FormRenderDefinition<any> | undefined;\n /** 内部装配口:definition 未配置 search 时由 TableRender 回填组件 prop(对齐 setRowKey) */\n setSearch: (search: FormRenderDefinition<any> | undefined) => void;\n /** 虚拟滚动配置透传(未配置为 undefined),供组件渲染层判定(definition 优先于 prop) */\n virtual: boolean | undefined;\n /** 虚拟滚动容器高度配置透传(仅 virtual: true 时被组件使用) */\n height: number | string | undefined;\n /** 树形配置(引擎校验后的回传,供组件读取 indentSize;无效配置被忽略时为 undefined) */\n tree: TreeOptions | undefined;\n /** 最近一次 onLoad 失败的 Error(仅服务端模式产生);下一次 load 开始时清除 */\n error: Readonly<Ref<Error | undefined>>;\n /** 可见列 key(columns 原序子集);受控/非受控统一投影 */\n visibleKeys: Readonly<Ref<readonly string[]>>;\n /** 列显隐动作:规范化(未知忽略、columns 原序、空钳制为首列 R24)后更新 */\n setVisibleKeys: (keys: string[]) => void;\n /** 解析后的默认可见集(R21 重置基准;未配置为 undefined = 全部可见) */\n defaultVisibleKeys: string[] | undefined;\n /** 聚合式列显隐配置回传(拆分式为 undefined) */\n columnVisibility: ColumnVisibilityOptions | undefined;\n /** 内部装配口:拆分式由 TableRender 在 setup 时回填 rowKey(S1) */\n setRowKey: (rowKey: string | undefined) => void;\n}\n"
83
+ "content": "import type { ColumnRender, ColumnRenders } from \"./column-renders\";\nimport type { FormRenderDefinition } from \"../form-render\";\nimport type { Row, Table as TanstackTable } from \"@tanstack/vue-table\";\nimport type { MaybeRefOrGetter, Ref, VNodeChild } from \"vue\";\n\n/** 任意数据行(表格是弱类型数据容器,行结构由调用方的 T 决定) */\nexport interface DataRecord {\n [key: string]: any;\n}\n\n/** 表体行渲染单元:TanStack Row 引用 + 可见列值矩阵(TableRender → TableBodyRow) */\nexport interface TableBodyLine {\n /** TanStack Row:树形渲染读 depth / getCanExpand / getIsExpanded / toggleExpanded */\n row: Row<DataRecord>;\n key: string;\n index: number;\n record: DataRecord;\n /** 行级可选过滤(S5):selectable 谓词交由引擎 enableRowSelection 判定 */\n canSelect: boolean;\n /** 可见列的值矩阵(列显隐只裁剪列;R25 状态不受影响) */\n cells: VNodeChild[];\n}\n\n/**\n * 列配置。\n *\n * 命名总纲(D10):能力/性质用 `-able` 形容词(sortable/ellipsis),\n * 配置值用名词(title/align/width),无 `allow-*`。\n */\nexport interface TableColumnOptions<T extends DataRecord = DataRecord> {\n /** 列标识,同时作为默认取值字段 */\n key: string;\n title: string;\n align?: \"left\" | \"center\" | \"right\";\n /** 列宽(R32)。数字(px):布局硬约束 —— 参与表格 min-width 求和与 fixed 列 sticky 偏移推算;\n * 字符串(如 \"10rem\"):仅渲染提示值,不参与求和与 sticky。 */\n width?: number | string;\n /** 自定义单元格渲染,取值链 render > formatter > record[key](R17) */\n render?: (r: ColumnRenders<T>) => ColumnRender<T>;\n /** 纯数据格式化;render 存在时被忽略 */\n formatter?: (record: T) => string | number | Date | undefined;\n /** 超宽截断 + 原生 title 提示(R15);\"tooltip\" 形态改用库内 Tooltip(不设原生 title) */\n ellipsis?: boolean | \"tooltip\";\n /** 是否可排序(能力开关) */\n sortable?: boolean;\n /** 初始排序方向;需 sortable: true,否则 DEV 警告并忽略(R7) */\n defaultSort?: \"asc\" | \"desc\";\n /** 固定列:横向滚动时 sticky 在左/右;须同时提供数字 width,否则 DEV 警告并按普通列渲染 */\n fixed?: \"left\" | \"right\";\n}\n\nexport interface PageableOptions {\n /** 1-based 页码(对外 API 唯一口径) */\n pageIndex: number;\n pageSize: number;\n total: number;\n /** 只读:状态投影不允许调用方直接改写每页条数选项 */\n pageSizeOpts: readonly number[];\n}\n\nexport interface SortableOptions {\n key: string;\n direction: \"asc\" | \"desc\";\n}\n\n/** onLoad 入参:数据协议与 x-render 同构,request 生态由调用方自理 */\nexport interface TableLoadParams<T extends DataRecord = DataRecord> {\n /** 搜索表单值(来自 options.search 的表单当前值);未配置 search 时为 {} */\n form: DataRecord;\n page: PageableOptions;\n /** 无排序或已取消排序时为 undefined */\n sort?: SortableOptions;\n /** 回写数据;total 缺省时保留旧值(R10) */\n update: (data: T[], total?: number) => void;\n}\n\n/** defineTable 的声明式配置 */\nexport interface DefineTableOptions<T extends DataRecord = DataRecord> {\n columns: TableColumnOptions<T>[];\n /** 服务端模式数据源;与 data 二选一,onLoad 优先 */\n onLoad?: (params: TableLoadParams<T>) => void | Promise<unknown>;\n /** 静态模式数据源(本地分页/排序) */\n data?: T[];\n /** 是否在挂载后自动加载,默认 true;仅服务端模式生效 */\n autoLoad?: boolean;\n /**\n * 每页条数 / 受控每页条数(D11)。约定:传入(非 undefined)即受控,缺省(undefined)时\n * 以默认 10 行运行;R9 归位:pageIndex 未受控时内部归位第 1 页并经 update:page-index 通知,\n * 两个都受控时由父层自行联动。支持传 ref/getter(聚合式受控)\n */\n pageSize?: MaybeRefOrGetter<number | undefined>;\n pageSizeOpts?: number[];\n /** 行选择:radio 单选 / checkbox 多选;字符串为简写(S2) */\n rowSelection?: \"radio\" | \"checkbox\" | TableSelectionOptions<T>;\n /** 行主键字段;rowSelection 启用且此值无效时禁用选择(S1) */\n rowKey?: string;\n /**\n * 搜索表单(defineForm 返回值):仅服务端模式生效,每次 onLoad 的 form 参数\n * 携带 `search.form.state.values` 当前值。静态模式传入时 DEV 警告并忽略。\n * 泛型为 any:FormRenderDefinition 对 T 不变(FormRenderItem.key 字面量收窄),\n * DataRecord 版会拒收一切具体 defineForm<Q> 结果(对齐 FormRender.vue prop 约定)。\n */\n search?: FormRenderDefinition<any>;\n /** 虚拟滚动:开启后表体行在当前页行窗口内虚拟化(分页语义不变);须同时配置 height,否则 DEV 警告并降级普通渲染 */\n virtual?: boolean;\n /** 虚拟滚动容器高度(数字 px 或 CSS 高度);仅 virtual: true 时生效 */\n height?: number | string;\n /** 树形数据:子行展开/收起(展开按钮在首个业务列内);配置无效时 DEV 警告并忽略 */\n tree?: TreeOptions;\n /**\n * 受控页码(1-based,D11)。约定:传入(非 undefined)即受控,缺省保持非受控;\n * 内部翻页经 update:page-index 通知,外部变更经受控 watch 同步(语义等值跳过,防回弹循环)\n */\n pageIndex?: MaybeRefOrGetter<number | undefined>;\n /** 受控排序。内部/外部变化均经 sort-change 通知;指向不可排序列时 DEV 警告并忽略 */\n sort?: MaybeRefOrGetter<SortableOptions | undefined>;\n /** 受控选中集(数组,与 update:selected-keys 载荷同构)。经 setSelection 写入(S5 过滤/S12 待定 key 继承) */\n selectedKeys?: MaybeRefOrGetter<Array<string | number> | undefined>;\n /**\n * 列显隐:默认可见列集(R21「重置」基准;未知 key 静默忽略;未传 = 全部可见)。\n * 列显隐不触发 onLoad、不重置 pageIndex/sort/selectedKeys(R25)\n */\n columnVisibility?: ColumnVisibilityOptions;\n /**\n * 受控可见列 key(columns 原序子集)。约定:传入(非 undefined)即受控;\n * 内部显隐经 update:visible-keys 通知;空数组钳制为首列可见(R24,warn 一次)\n */\n visibleKeys?: MaybeRefOrGetter<string[] | undefined>;\n /**\n * 拆分式默认可见列集;与聚合式 columnVisibility.defaultVisibleKeys 同传时\n * DEV 警告 definition 优先(R26)\n */\n defaultVisibleKeys?: MaybeRefOrGetter<string[] | undefined>;\n}\n\n/** 树形数据配置(T 系列) */\nexport interface TreeOptions {\n /** 子行字段名,默认 \"children\" */\n childrenKey?: string;\n /** 默认全部展开,默认 false */\n defaultExpandAll?: boolean;\n /** 每层缩进 px,默认 16 */\n indentSize?: number;\n}\n\n/** 列显隐配置(R20–R24) */\nexport interface ColumnVisibilityOptions {\n /** 默认可见列 key 列表(R21「重置」基准);未知 key 静默忽略;未传 = 全部可见 */\n defaultVisibleKeys?: string[];\n}\n\n/** 行选择配置(S 系列) */\nexport interface TableSelectionOptions<T extends DataRecord = DataRecord> {\n type: \"radio\" | \"checkbox\";\n /** 选择列宽,默认 48 */\n width?: number;\n /** 行级可选过滤;false 的行选择控件置灰且被全选跳过(S5) */\n selectable?: (record: T) => boolean;\n /** radio 再点已选中行是否取消,默认 true(S4) */\n cancelable?: boolean;\n /** 翻页/重载后是否保留选中,默认 true(S6) */\n reserveOnPageChange?: boolean;\n}\n\n/** useTableRender 的入参:data 额外支持 ref/getter(拆分模式下 props 天然响应式) */\nexport interface UseTableRenderOptions<T extends DataRecord = DataRecord> extends Omit<\n DefineTableOptions<T>,\n \"data\"\n> {\n data?: MaybeRefOrGetter<T[] | undefined>;\n}\n\n/** defineTable / useTableRender 的返回物:列配置 + 引擎实例 + 只读状态 + 实例动作 */\nexport interface TableRenderDefinition<T extends DataRecord = DataRecord> {\n columns: TableColumnOptions<T>[];\n /** TanStack 表格实例(逃逸舱口) */\n table: TanstackTable<T>;\n page: Readonly<PageableOptions>;\n sort: Readonly<{ value: SortableOptions | undefined }>;\n loading: Readonly<{ value: boolean }>;\n /** 重新加载;resetPage 为 true 时先回到第 1 页(R12) */\n reload: (resetPage?: boolean) => void;\n /** 排序三态切换:无 → asc → desc → 取消(R8) */\n toggleSort: (key: string) => void;\n setPageIndex: (pageIndex: number) => void;\n setPageSize: (pageSize: number) => void;\n /** 选中行快照(含跨页保留行;跨页行可能为过期数据,见 S6) */\n selection: Readonly<{\n value: T[];\n /** rowSelection 配置有效(含 rowKey 就绪)时为 true(S1) */\n enabled: boolean;\n type: \"radio\" | \"checkbox\";\n width: number;\n }>;\n /** 选中主键集合;每次选中集变化替换为新 Set(S7) */\n selectedKeys: Readonly<Ref<Set<string | number>>>;\n /** 程序化设置选中集;不存在的 key 保留(S12) */\n setSelection: (keys: Array<string | number>) => void;\n clearSelection: () => void;\n /** 行控件切换:checked 为 false 时移除(radio 受 cancelable 约束,S4) */\n toggleRowSelected: (key: string, checked: boolean) => void;\n /** 搜索表单定义(options.search 校验后的回传,供 TableRender 渲染搜索区;被忽略时为 undefined) */\n search: FormRenderDefinition<any> | undefined;\n /** 内部装配口:definition 未配置 search 时由 TableRender 回填组件 prop(对齐 setRowKey) */\n setSearch: (search: FormRenderDefinition<any> | undefined) => void;\n /** 虚拟滚动配置透传(未配置为 undefined),供组件渲染层判定(definition 优先于 prop) */\n virtual: boolean | undefined;\n /** 虚拟滚动容器高度配置透传(仅 virtual: true 时被组件使用) */\n height: number | string | undefined;\n /** 树形配置(引擎校验后的回传,供组件读取 indentSize;无效配置被忽略时为 undefined) */\n tree: TreeOptions | undefined;\n /** 最近一次 onLoad 失败的 Error(仅服务端模式产生);下一次 load 开始时清除 */\n error: Readonly<Ref<Error | undefined>>;\n /** 可见列 key(columns 原序子集);受控/非受控统一投影 */\n visibleKeys: Readonly<Ref<readonly string[]>>;\n /** 列显隐动作:规范化(未知忽略、columns 原序、空钳制为首列 R24)后更新 */\n setVisibleKeys: (keys: string[]) => void;\n /** 解析后的默认可见集(R21 重置基准;未配置为 undefined = 全部可见) */\n defaultVisibleKeys: string[] | undefined;\n /** 聚合式列显隐配置回传(拆分式为 undefined) */\n columnVisibility: ColumnVisibilityOptions | undefined;\n /** 内部装配口:拆分式由 TableRender 在 setup 时回填 rowKey(S1) */\n setRowKey: (rowKey: string | undefined) => void;\n}\n"
84
84
  },
85
85
  {
86
86
  "path": "table-render/useTableRender.ts",
@@ -1,10 +1,11 @@
1
1
  {
2
2
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
3
3
  "name": "tabs",
4
- "version": "0.5.5",
4
+ "version": "0.5.7",
5
5
  "type": "registry:ui",
6
6
  "description": "选项卡:基于 Ark UI Tabs 原语,键盘导航与受控/非受控双模式。",
7
7
  "registryDependencies": ["utils"],
8
+ "dependencies": ["@ark-ui/vue@^5.39.2"],
8
9
  "files": [
9
10
  {
10
11
  "path": "tabs/Tabs.vue",
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
3
3
  "name": "textarea",
4
- "version": "0.5.5",
4
+ "version": "0.5.7",
5
5
  "type": "registry:ui",
6
6
  "description": "多行文本输入:纯样式封装,支持 invalid 校验态。",
7
7
  "registryDependencies": ["utils"],
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
3
3
  "name": "timeline",
4
- "version": "0.5.5",
4
+ "version": "0.5.7",
5
5
  "type": "registry:ui",
6
6
  "description": "时间轴:数据驱动 items 渲染竖向事件流,支持单列/左右交替、五种语义节点色与空心节点、#item 作用域插槽自定义内容。",
7
7
  "registryDependencies": ["utils"],
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
3
3
  "name": "toast",
4
- "version": "0.5.5",
4
+ "version": "0.5.7",
5
5
  "type": "registry:ui",
6
6
  "description": "全局轻提示:ToastProvider 在应用根部挂载一次,useToast() 提供命令式 API(success/error/info/warning/loading/promise/dismiss);基于 Ark UI Toast 原语,语义 type 映射主题 token 配色。",
7
7
  "registryDependencies": ["icon-shared", "utils"],
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
3
3
  "name": "tokens",
4
- "version": "0.5.5",
4
+ "version": "0.5.7",
5
5
  "type": "registry:style",
6
6
  "description": "Tailwind CSS v4 语义 tokens(shadcn 官方 v4 集合)。",
7
7
  "dependencies": ["tw-animate-css@^1.4.0"],
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
3
3
  "name": "tooltip",
4
- "version": "0.5.5",
4
+ "version": "0.5.7",
5
5
  "type": "registry:ui",
6
6
  "description": "文字提示气泡:悬停触发,基于 Ark UI Tooltip 原语,支持 asChild 与延迟配置。",
7
7
  "registryDependencies": ["utils", "overlay-shared"],
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
3
3
  "name": "tree-select",
4
- "version": "0.5.5",
4
+ "version": "0.5.7",
5
5
  "type": "registry:ui",
6
6
  "description": "树形下拉选择:一站式 props 驱动,支持单/多选、勾选级联、过滤与多标签折叠。",
7
7
  "registryDependencies": ["icon-shared", "tree-shared", "utils", "date-shared", "overlay-shared"],
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
3
3
  "name": "tree-shared",
4
- "version": "0.5.5",
4
+ "version": "0.5.7",
5
5
  "type": "registry:ui",
6
6
  "description": "树形数据层与共享类型(移植自 treemate v0.3.11,MIT)。",
7
7
  "registryDependencies": ["icon-shared", "utils"],
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
3
3
  "name": "utils",
4
- "version": "0.5.5",
4
+ "version": "0.5.7",
5
5
  "type": "registry:lib",
6
6
  "description": "cn 类名合并工具(clsx + tailwind-merge)。",
7
7
  "dependencies": ["clsx@^2.1.1", "tailwind-merge@^3.7.0", "class-variance-authority@^0.7.1"],
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
3
3
  "name": "week-picker",
4
- "version": "0.5.5",
4
+ "version": "0.5.7",
5
5
  "type": "registry:ui",
6
6
  "description": "周选择器:输入框 + 日历弹层,点任意可选日归一到所在周并整周高亮,值以 \"yyyy-MM-dd\"(所在周起始日)字符串受控;周起点跟随 locale(zh-CN 周一起始),输入框回显 \"start ~ end\"。",
7
7
  "registryDependencies": ["utils", "date-shared", "calendar"],
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
3
3
  "name": "year-picker",
4
- "version": "0.5.5",
4
+ "version": "0.5.7",
5
5
  "type": "registry:ui",
6
6
  "description": "年份选择器:输入框 + 锁定年视图的日历弹层(decade 网格),值以 \"yyyy\" 字符串受控,min/max 为年粒度闭区间。",
7
7
  "registryDependencies": ["utils", "date-shared", "calendar"],
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@tu-design/vue",
3
- "version": "0.5.5",
3
+ "version": "0.5.7",
4
4
  "description": "shadcn 风格的 Vue 3 组件库:Tailwind CSS v4 主题 + Ark UI 原语,CLI 分发组件源码。",
5
5
  "keywords": [
6
6
  "components",