niuma-ui 1.0.0 → 1.0.2

package/src/composables/useRsTableShell.ts

@@ -0,0 +1,416 @@
+/**
+ * RsTable 壳层装配：前缀列几何 + 列宽/列虚拟/列布局 + 交互 + 右键菜单。
+ *
+ * 性能约定（不可破）：
+ * - 列宽拖拽仍走 useRsTableColumnResize 的 DOM 直写（禁止拖拽中写 reactive 全表宽）
+ * - columnVirtual 在 isColumnResizing 时冻结切片，避免拖宽时重算窗口
+ * - 不引入对 data 的 deep watch；状态经 getter / 受控 ref 读写
+ *
+ * 不做：Engine/Virtual 行切片（useRsTableCore）、编辑提交（useRsTableEditActions）、模板。
+ */
+
+import { computed, type ComputedRef, type Ref } from 'vue'
+import type { RsContextMenuItem } from '../components/context-menu-utils'
+import type { RsTableRowDragTrigger, RsTableRowDropMode } from '../components/table-drag'
+import type {
+  RsTableColumn,
+  RsTableRowData,
+  RsTableRowEntry,
+  RsTableRowKey,
+  RsTableSelectionType,
+  RsTableSortState,
+  RsTableTreeConfig,
+  RsTableTreeNodeIndex,
+  RsTableRowDropPosition,
+} from '../components/table-utils'
+import { resolveScrollWidth, selectRowKeys } from '../components/table-utils'
+import {
+  measureRsTablePrefixWidth,
+  RS_TABLE_PREFIX_COL_WIDTH,
+  useRsTableColumnVirtual,
+} from './useRsTableColumnVirtual'
+import { useRsTableColumnLayout } from './useRsTableColumnLayout'
+import { useRsTableColumnResize } from './useRsTableColumnResize'
+import { useRsTableContextMenu } from './useRsTableContextMenu'
+import { useRsTableInteraction } from './useRsTableInteraction'
+import { resolveVirtualListHeight } from '../components/virtual-list-utils'
+
+/** 壳层依赖的 Core 状态切片（显式列出，避免吞整个 core） */
+export interface UseRsTableShellCoreSlice<T extends RsTableRowData> {
+  displayColumns: ComputedRef<RsTableColumn<T>[]>
+  resolvedColumnWidths: {
+    get: () => Record<string, number>
+    set: (value: Record<string, number>) => void
+  } | Ref<Record<string, number>>
+  useStableColumnWidths: ComputedRef<boolean>
+  scrollLeft: Ref<number>
+  measuredViewportWidth: Ref<number>
+  virtualScrollEnabled: ComputedRef<boolean>
+  dataRows: ComputedRef<Array<Extract<RsTableRowEntry<T>, { type: 'row' }>>>
+  selectedRows: ComputedRef<T[]>
+  rowKeyByIndex: ComputedRef<Map<number, string>>
+  selectedRowKeys: {
+    get: () => string[]
+    set: (keys: string[]) => void
+  } | Ref<string[]>
+  selectedKeySet: ComputedRef<Set<string>>
+  selectableRowKeys: ComputedRef<string[]>
+  selectAllState: ComputedRef<'checked' | 'indeterminate' | 'unchecked'>
+  expandedRowKeys: {
+    get: () => string[]
+    set: (keys: string[]) => void
+  } | Ref<string[]>
+  expandedKeySet: ComputedRef<Set<string>>
+  detailExpandable: ComputedRef<boolean>
+  treeMode: ComputedRef<boolean>
+  treeCheckStrictly: ComputedRef<boolean>
+  treeLazy: ComputedRef<boolean>
+  treeChildrenField: ComputedRef<string>
+  treeIsLeafField: ComputedRef<string>
+  treeLoadingKeys: {
+    get: () => string[]
+    set: (keys: string[]) => void
+  } | Ref<string[]>
+  treeLoadingKeySet: ComputedRef<Set<string>>
+  tableTreeNodeIndex: ComputedRef<Map<string, RsTableTreeNodeIndex> | null>
+  sortState: {
+    get: () => RsTableSortState | null
+    set: (value: RsTableSortState | null) => void
+  } | Ref<RsTableSortState | null>
+  sortsState: {
+    get: () => RsTableSortState[]
+    set: (value: RsTableSortState[]) => void
+  } | Ref<RsTableSortState[]>
+  columnOrderState: {
+    get: () => string[]
+    set: (value: string[]) => void
+  } | Ref<string[]>
+}
+
+function asAccessor<T>(source: { get: () => T; set: (v: T) => void } | Ref<T>): {
+  get: () => T
+  set: (v: T) => void
+} {
+  if ('get' in source && typeof source.get === 'function') return source
+  const r = source as Ref<T>
+  return {
+    get: () => r.value,
+    set: (v) => {
+      r.value = v
+    },
+  }
+}
+
+export interface UseRsTableShellOptions<T extends RsTableRowData> {
+  core: UseRsTableShellCoreSlice<T>
+  // chrome / layout props
+  rowDraggable: () => boolean
+  rowDragTrigger: () => RsTableRowDragTrigger
+  selectable: () => boolean
+  selectionType: () => RsTableSelectionType
+  scrollX: () => number | string | undefined
+  resizable: () => boolean
+  minColumnWidth: () => number | undefined
+  maxColumnWidth: () => number | undefined
+  columnLayout: () => 'auto' | 'fixed'
+  virtualColumns: () => boolean | 'auto' | undefined
+  virtualColumnsAutoThreshold: () => number | undefined
+  virtualColumnOverscan: () => number | undefined
+  fill: () => boolean
+  infinite: () => boolean
+  height: () => number | string | undefined
+  showEditGutterColumn: () => boolean
+  showIndexColumn: () => boolean
+  showRowStatusColumn: () => boolean
+  resolvedGutterWidth: () => number
+  resolvedIndexWidth: () => number
+  // interaction
+  multiSort: () => boolean
+  maxSort: () => number | undefined
+  columnDraggable: () => boolean
+  rowSelectable?: (row: T, index: number) => boolean
+  rowDropMode: () => RsTableRowDropMode
+  rowDraggableWhen?: (row: T, index: number) => boolean
+  rowDropTargetWhen?: (row: T, index: number) => boolean
+  canRowDrop?: (dragKeys: string[], dropKey: string) => boolean
+  rowKey: () => RsTableRowKey<T> | undefined
+  treeConfig: () => RsTableTreeConfig<T> | undefined
+  expandable: () => boolean
+  rowExpandable?: (row: T, index: number) => boolean
+  isEditingAny: () => boolean
+  applyRowClickHighlight: (key: string) => void
+  onRowClickEmit: (row: T, index: number) => void
+  onRowDblclickEmit: (row: T, index: number) => void
+  onRowDragStartEmit: (dragKeys: string[], event: DragEvent) => void
+  onRowDropEmit: (dragKeys: string[], dropKey: string, position: RsTableRowDropPosition) => void
+  onColumnResize: (key: string, width: number) => void
+  // context menu
+  contextMenuEnabled: ComputedRef<boolean> | (() => boolean)
+  copyCellLabel: () => string
+  copyRowLabel: () => string
+  contextMenuItems?: (row: T | null, selectedRows: T[]) => RsContextMenuItem[]
+  mergeFeatureMenuItems?: (
+    items: RsContextMenuItem[],
+    ctx: { row: T | null; selectedRows: T[] },
+  ) => RsContextMenuItem[]
+  selectOnContextmenu: () => boolean
+  getDraft: (rowKey: string, colKey: string) => string | undefined
+  onContextMenuSelect: (key: string, row: T | null, selected: T[]) => void
+  onRowContextmenuEmit: (row: T, rowIndex: number, event: MouseEvent) => void
+}
+
+/**
+ * 装配壳层：列几何/布局/交互/右键。
+ */
+export function useRsTableShell<T extends RsTableRowData>(options: UseRsTableShellOptions<T>) {
+  const { core } = options
+  const PREFIX_COL_WIDTH = RS_TABLE_PREFIX_COL_WIDTH
+
+  const showRowDragHandle = computed(
+    () => options.rowDraggable() && options.rowDragTrigger() === 'handle',
+  )
+  const dragColumnOffset = computed(() => (showRowDragHandle.value ? 40 : 0))
+  const expandColumnOffset = computed(
+    () => dragColumnOffset.value + (core.detailExpandable.value ? 40 : 0),
+  )
+  const showSelectColumn = computed(
+    () => options.selectable() && options.selectionType() !== 'row',
+  )
+  const isRowSelection = computed(
+    () => options.selectable() && options.selectionType() === 'row',
+  )
+  const isRadioSelection = computed(() => options.selectionType() === 'radio')
+  const selectColumnOffset = computed(
+    () => expandColumnOffset.value + (showSelectColumn.value ? 40 : 0),
+  )
+  const tableMinWidth = computed(() => resolveScrollWidth(options.scrollX()))
+
+  const selectedRowKeysAcc = asAccessor(core.selectedRowKeys)
+  const expandedRowKeysAcc = asAccessor(core.expandedRowKeys)
+  const treeLoadingKeysAcc = asAccessor(core.treeLoadingKeys)
+  const sortStateAcc = asAccessor(core.sortState)
+  const sortsStateAcc = asAccessor(core.sortsState)
+  const columnOrderStateAcc = asAccessor(core.columnOrderState)
+  const resolvedWidthsAcc = asAccessor(core.resolvedColumnWidths)
+
+  const {
+    tableRef,
+    isColumnResizing,
+    resizePaintWidths,
+    onResizeStart,
+  } = useRsTableColumnResize<T>({
+    resizable: () => options.resizable(),
+    minColumnWidth: () => options.minColumnWidth(),
+    maxColumnWidth: () => options.maxColumnWidth(),
+    displayColumns: () => core.displayColumns.value,
+    resolvedColumnWidths: resolvedWidthsAcc,
+    measurePrefixColumnWidth: () =>
+      measureRsTablePrefixWidth({
+        showRowDragHandle: showRowDragHandle.value,
+        detailExpandable: core.detailExpandable.value,
+        showSelectColumn: showSelectColumn.value,
+        showEditGutterColumn: options.showEditGutterColumn(),
+        showIndexColumn: options.showIndexColumn(),
+        gutterWidth: options.resolvedGutterWidth(),
+        indexWidth: options.resolvedIndexWidth(),
+      }),
+    tableMinWidth: () => tableMinWidth.value,
+    onColumnResize: options.onColumnResize,
+  })
+
+  /** 拖拽帧用快照，否则持久化宽 —— 供布局/列虚拟共用，避免双份计算 */
+  const effectiveColumnWidths = computed(
+    () => resizePaintWidths.value ?? resolvedWidthsAcc.get(),
+  )
+
+  const {
+    virtualColumnsEnabled,
+    visibleDataColumns,
+    columnPadLeft,
+    columnPadRight,
+  } = useRsTableColumnVirtual<T>({
+    displayColumns: () => core.displayColumns.value,
+    virtualColumns: () => options.virtualColumns(),
+    virtualColumnsAutoThreshold: () => options.virtualColumnsAutoThreshold(),
+    virtualColumnOverscan: () => options.virtualColumnOverscan(),
+    isColumnResizing: () => isColumnResizing.value,
+    scrollLeft: () => core.scrollLeft.value,
+    measuredViewportWidth: () => core.measuredViewportWidth.value,
+    columnWidths: () => effectiveColumnWidths.value,
+    showRowDragHandle: () => showRowDragHandle.value,
+    detailExpandable: () => core.detailExpandable.value,
+    showSelectColumn: () => showSelectColumn.value,
+    showEditGutterColumn: () => options.showEditGutterColumn(),
+    showIndexColumn: () => options.showIndexColumn(),
+    showRowStatusColumn: () => options.showRowStatusColumn(),
+    resolvedGutterWidth: () => options.resolvedGutterWidth(),
+    resolvedIndexWidth: () => options.resolvedIndexWidth(),
+  })
+
+  const layout = useRsTableColumnLayout<T>({
+    displayColumns: () => core.displayColumns.value,
+    effectiveColumnWidths: () => effectiveColumnWidths.value,
+    measuredViewportWidth: () => core.measuredViewportWidth.value,
+    tableMinWidth: () => tableMinWidth.value,
+    resizable: () => options.resizable(),
+    columnLayout: () => options.columnLayout(),
+    useStableColumnWidths: () => core.useStableColumnWidths.value,
+    isColumnResizing: () => isColumnResizing.value,
+    virtualColumnsEnabled: () => virtualColumnsEnabled.value,
+    scrollX: () => options.scrollX(),
+    showRowDragHandle: () => showRowDragHandle.value,
+    detailExpandable: () => core.detailExpandable.value,
+    showSelectColumn: () => showSelectColumn.value,
+    showEditGutterColumn: () => options.showEditGutterColumn(),
+    showIndexColumn: () => options.showIndexColumn(),
+    showRowStatusColumn: () => options.showRowStatusColumn(),
+    resolvedGutterWidth: () => options.resolvedGutterWidth(),
+    resolvedIndexWidth: () => options.resolvedIndexWidth(),
+    dragColumnOffset: () => dragColumnOffset.value,
+    expandColumnOffset: () => expandColumnOffset.value,
+    selectColumnOffset: () => selectColumnOffset.value,
+    resizePaintWidths: () => resizePaintWidths.value,
+  })
+
+  const useScrollContainer = computed(
+    () =>
+      core.virtualScrollEnabled.value ||
+      options.infinite() ||
+      virtualColumnsEnabled.value,
+  )
+
+  const scrollContainerStyle = computed(() => {
+    const style: Record<string, string> = {}
+    if (useScrollContainer.value && !options.fill()) {
+      const resolvedHeight = resolveVirtualListHeight(options.height(), 320)
+      if (resolvedHeight) {
+        style.height = resolvedHeight
+        style.maxHeight = resolvedHeight
+      }
+    }
+    if (options.showEditGutterColumn()) {
+      style['--rs-table-gutter-width'] = `${options.resolvedGutterWidth()}px`
+    }
+    if (showSelectColumn.value) {
+      style['--rs-table-select-width'] = `${PREFIX_COL_WIDTH.select}px`
+    }
+    if (options.showIndexColumn()) {
+      style['--rs-table-index-width'] = `${options.resolvedIndexWidth()}px`
+    }
+    return Object.keys(style).length ? style : undefined
+  })
+
+  const bodyColspan = computed(() => {
+    let count = visibleDataColumns.value.length
+    if (columnPadLeft.value > 0) count += 1
+    if (columnPadRight.value > 0) count += 1
+    if (showRowDragHandle.value) count += 1
+    if (core.detailExpandable.value) count += 1
+    if (showSelectColumn.value) count += 1
+    if (options.showEditGutterColumn() || options.showIndexColumn()) count += 1
+    if (options.showRowStatusColumn()) count += 1
+    return count
+  })
+
+  const emptyContentStyle = computed(() => {
+    const w = core.measuredViewportWidth.value
+    if (w <= 0) return undefined
+    return { width: `${w}px` }
+  })
+
+  const interaction = useRsTableInteraction<T>({
+    multiSort: () => options.multiSort(),
+    maxSort: () => options.maxSort(),
+    columnDraggable: () => options.columnDraggable(),
+    selectable: () => options.selectable(),
+    selectionType: () => options.selectionType(),
+    rowSelectable: options.rowSelectable,
+    rowDraggable: () => options.rowDraggable(),
+    rowDragTrigger: () => options.rowDragTrigger(),
+    rowDropMode: () => options.rowDropMode(),
+    rowDraggableWhen: options.rowDraggableWhen,
+    rowDropTargetWhen: options.rowDropTargetWhen,
+    canRowDrop: options.canRowDrop,
+    rowKey: () => options.rowKey(),
+    rowKeyByIndex: () => core.rowKeyByIndex.value,
+    selectedRowKeys: selectedRowKeysAcc,
+    selectedKeySet: () => core.selectedKeySet.value,
+    selectableRowKeys: () => core.selectableRowKeys.value,
+    selectAllState: () => core.selectAllState.value,
+    expandedRowKeys: expandedRowKeysAcc,
+    expandedKeySet: () => core.expandedKeySet.value,
+    treeMode: () => core.treeMode.value,
+    treeCheckStrictly: () => core.treeCheckStrictly.value,
+    treeLazy: () => core.treeLazy.value,
+    treeChildrenField: () => core.treeChildrenField.value,
+    treeIsLeafField: () => core.treeIsLeafField.value,
+    treeLoadingKeys: treeLoadingKeysAcc,
+    treeLoadingKeySet: () => core.treeLoadingKeySet.value,
+    tableTreeNodeIndex: () => core.tableTreeNodeIndex.value,
+    treeConfig: () => options.treeConfig(),
+    expandable: () => options.expandable(),
+    rowExpandable: options.rowExpandable,
+    sortState: sortStateAcc,
+    sortsState: sortsStateAcc,
+    columnOrderState: columnOrderStateAcc,
+    isEditingAny: () => options.isEditingAny(),
+    applyRowClickHighlight: options.applyRowClickHighlight,
+    onRowClickEmit: options.onRowClickEmit,
+    onRowDblclickEmit: options.onRowDblclickEmit,
+    onRowDragStartEmit: options.onRowDragStartEmit,
+    onRowDropEmit: options.onRowDropEmit,
+  })
+
+  const contextMenu = useRsTableContextMenu<T>({
+    enabled: options.contextMenuEnabled,
+    dataRows: () => core.dataRows.value,
+    displayColumns: () => core.displayColumns.value,
+    selectedRows: () => core.selectedRows.value,
+    rowKey: () => options.rowKey(),
+    rowKeyByIndex: () => core.rowKeyByIndex.value,
+    copyCellLabel: () => options.copyCellLabel(),
+    copyRowLabel: () => options.copyRowLabel(),
+    contextMenuItems: (row, selected) => options.contextMenuItems?.(row, selected) ?? [],
+    mergeFeatureMenuItems: options.mergeFeatureMenuItems,
+    shouldSelectOnContextmenu: () => options.selectOnContextmenu(),
+    canSelectRow: interaction.canSelectRow,
+    isRowSelected: interaction.isRowSelected,
+    selectionType: () => options.selectionType(),
+    getSelectedRowKeys: () => selectedRowKeysAcc.get(),
+    setSelectedRowKeys: (keys) => selectedRowKeysAcc.set(keys),
+    selectRowKeys,
+    getDraft: options.getDraft,
+    onSelect: options.onContextMenuSelect,
+    onRowContextmenu: options.onRowContextmenuEmit,
+  })
+
+  return {
+    PREFIX_COL_WIDTH,
+    showRowDragHandle,
+    dragColumnOffset,
+    expandColumnOffset,
+    showSelectColumn,
+    isRowSelection,
+    isRadioSelection,
+    selectColumnOffset,
+    tableMinWidth,
+    tableRef,
+    isColumnResizing,
+    resizePaintWidths,
+    onResizeStart,
+    effectiveColumnWidths,
+    virtualColumnsEnabled,
+    visibleDataColumns,
+    columnPadLeft,
+    columnPadRight,
+    ...layout,
+    useScrollContainer,
+    scrollContainerStyle,
+    bodyColspan,
+    emptyContentStyle,
+    ...interaction,
+    ...contextMenu,
+  }
+}
+
+export type RsTableShellApi<T extends RsTableRowData> = ReturnType<typeof useRsTableShell<T>>

package/src/composables/useRsTableShellChrome.ts

@@ -0,0 +1,170 @@
+/**
+ * RsTable 壳层编排：i18n 文案、a11y 绑定、Grid 键盘、滚动宿主 class。
+ * 从 RsTable.vue 下沉，SFC 只保留接线。
+ */
+
+import { computed, useAttrs, useSlots, type ComputedRef, type Ref } from 'vue'
+import type { useTableEdit } from './useTableEdit'
+import { useRsI18n } from './useRsI18n'
+import { useRsTableA11y } from './useRsTableA11y'
+import { useRsTableGridKeyboard } from './useRsTableGridKeyboard'
+import type { RsTableColumn, RsTableRowData, RsTableRowEntry } from '../components/table-utils'
+
+type TableEditApi = ReturnType<typeof useTableEdit>
+
+export interface UseRsTableShellChromeOptions<T extends RsTableRowData> {
+  ariaLabel: () => string | undefined
+  loading: () => boolean
+  dataRows:
+    | Ref<Array<Extract<RsTableRowEntry<T>, { type: 'row' }>>>
+    | ComputedRef<Array<Extract<RsTableRowEntry<T>, { type: 'row' }>>>
+  visibleDataColumns: Ref<RsTableColumn<T>[]> | ComputedRef<RsTableColumn<T>[]>
+  displayColumns: () => RsTableColumn<T>[]
+  tableEdit: TableEditApi
+  rowKeyFor: (entry: Extract<RsTableRowEntry<T>, { type: 'row' }>) => string
+  applyRowClickHighlight: (rowKey: string) => void
+  pageSize: () => number
+  onTableKeydown: (event: KeyboardEvent) => void
+  scrollContainerRef?: Ref<HTMLElement | null | undefined>
+  /** 滚动宿主 class 所需状态 */
+  hostClass: {
+    bordered: () => boolean
+    columnBordered: () => boolean
+    rounded: () => boolean
+    fill: () => boolean
+    compact: () => boolean
+    resolvedSize: () => string
+    virtualScrollEnabled: () => boolean
+    virtualColumnsEnabled: () => boolean
+    dataLength: () => number
+    infinite: () => boolean
+    resizable: () => boolean
+    columnLayout: () => string
+    useFixedColumnLayout: () => boolean
+    striped: () => boolean
+    selectable: () => boolean
+    isRowSelection: () => boolean
+    detailExpandable: () => boolean
+    treeMode: () => boolean
+    rowDraggable: () => boolean
+    columnDraggable: () => boolean
+    scrollX: () => number | string | undefined
+    overflowXEnabled: () => boolean
+    contextMenuEnabled: () => boolean
+    showEditGutterColumn: () => boolean
+  }
+}
+
+/**
+ * 壳层 chrome：文案 / a11y / 键盘 / 宿主 class。
+ */
+export function useRsTableShellChrome<T extends RsTableRowData>(
+  options: UseRsTableShellChromeOptions<T>,
+) {
+  const { t } = useRsI18n()
+  const slots = useSlots()
+  const attrs = useAttrs()
+
+  const hasData = computed(() => options.dataRows.value.length > 0)
+
+  const headerLabels = computed(() => ({
+    selectAll: t('table.selectAll'),
+    index: t('table.index'),
+    rowStatus: t('table.rowStatus'),
+    dragColumn: t('table.dragColumn'),
+    filterColumn: t('table.filterColumn'),
+    filterPlaceholder: t('table.filterPlaceholder'),
+    filterClear: t('table.filterClear'),
+    filterApply: t('table.filterApply'),
+  }))
+
+  const bodyLabels = computed(() => ({
+    loading: t('table.loading'),
+    empty: t('table.empty'),
+    loadingMore: t('table.loadingMore'),
+    dragRow: t('table.dragRow'),
+    expandRow: t('table.expandRow'),
+    collapseRow: t('table.collapseRow'),
+    selectRow: t('table.selectRow'),
+    rowCommit: t('table.rowCommit'),
+    rowRollback: t('table.rowRollback'),
+    gutterCommit: t('table.gutterCommit'),
+  }))
+
+  function hasColumnSlot(key: string): boolean {
+    return Boolean(slots[key])
+  }
+
+  function hasEditSlot(key: string): boolean {
+    return Boolean(slots[`edit-${key}`])
+  }
+
+  const { shellA11y, tableA11y } = useRsTableA11y({
+    ariaLabel: options.ariaLabel,
+    defaultLabel: () => t('table.a11yLabel'),
+    loading: options.loading,
+    rowCount: () => options.dataRows.value.length,
+    colCount: () => options.visibleDataColumns.value.length,
+  })
+
+  const shellBind = computed(() => ({
+    ...shellA11y.value,
+    ...attrs,
+  }))
+
+  const { onGridKeydown } = useRsTableGridKeyboard<T>({
+    tableEdit: options.tableEdit,
+    dataRows: () => options.dataRows.value,
+    rowKeyFor: options.rowKeyFor,
+    colKeys: () => options.visibleDataColumns.value.map((c) => c.key),
+    displayColumns: options.displayColumns,
+    applyRowClickHighlight: options.applyRowClickHighlight,
+    pageSize: options.pageSize,
+    scrollContainerRef: options.scrollContainerRef,
+  })
+
+  function onShellKeydown(event: KeyboardEvent): void {
+    if (onGridKeydown(event)) return
+    options.onTableKeydown(event)
+  }
+
+  const h = options.hostClass
+  const scrollHostClass = computed(() => ({
+    'rs-table--bordered': h.bordered(),
+    'rs-table--column-bordered': h.columnBordered(),
+    'rs-table--rounded': h.rounded(),
+    'rs-table--fill': h.fill(),
+    'rs-table--compact': h.compact(),
+    [`rs-table--${h.resolvedSize()}`]: true,
+    'rs-table--virtual': h.virtualScrollEnabled(),
+    'rs-table--virtual-cols': h.virtualColumnsEnabled(),
+    'rs-table--content-visibility': !h.virtualScrollEnabled() && h.dataLength() >= 30,
+    'rs-table--infinite': h.infinite(),
+    'rs-table--resizable': h.resizable(),
+    'rs-table--col-auto': h.resizable() && h.columnLayout() === 'auto',
+    'rs-table--col-fixed': h.useFixedColumnLayout(),
+    'rs-table--striped': h.striped(),
+    'rs-table--selectable': h.selectable(),
+    'rs-table--row-select': h.isRowSelection(),
+    'rs-table--expandable': h.detailExpandable(),
+    'rs-table--tree': h.treeMode(),
+    'rs-table--draggable': h.rowDraggable() || h.columnDraggable(),
+    'rs-table--scroll-x': !!h.scrollX(),
+    'rs-table--overflow-x': h.overflowXEnabled(),
+    'rs-table--ctx': h.contextMenuEnabled(),
+    'rs-table--edit-gutter': h.showEditGutterColumn(),
+  }))
+
+  return {
+    t,
+    hasData,
+    headerLabels,
+    bodyLabels,
+    hasColumnSlot,
+    hasEditSlot,
+    tableA11y,
+    shellBind,
+    onShellKeydown,
+    scrollHostClass,
+  }
+}

package/src/composables/useRsTableSummary.ts

@@ -0,0 +1,113 @@
+/**
+ * RsTable 汇总行编排：是否启用、footer 单元格、前缀 colspan。
+ *
+ * 纯聚合算法在 table-summary-utils；本 composable 对接 props / slots / 前缀列状态。
+ */
+
+import { computed, watch, type ComputedRef } from 'vue'
+import type { RsTableColumn, RsTableRowData } from '../components/table-utils'
+import {
+  buildTableSummaryCells,
+  hasTableSummaryConfig,
+  warnSummaryCompatibility,
+  type RsTableColumnSummary,
+  type RsTableSummaryData,
+  type RsTableSummaryMode,
+} from '../components/table/table-summary-utils'
+
+function read<T>(source: ComputedRef<T> | (() => T)): T {
+  return typeof source === 'function' ? (source as () => T)() : source.value
+}
+
+type ColumnWithSummary<T extends RsTableRowData> = RsTableColumn<T> & {
+  summary?: RsTableColumnSummary<T>
+}
+
+export interface UseRsTableSummaryOptions<T extends RsTableRowData> {
+  /** 显式开启汇总行 */
+  showSummary: ComputedRef<boolean | undefined> | (() => boolean | undefined)
+  summaryMode: ComputedRef<RsTableSummaryMode> | (() => RsTableSummaryMode)
+  summaryData: ComputedRef<RsTableSummaryData | null | undefined> | (() => RsTableSummaryData | null | undefined)
+  /** 原始列（判断是否配置 summary） */
+  columns: ComputedRef<ColumnWithSummary<T>[]> | (() => ColumnWithSummary<T>[])
+  /** 展示列（footer 与表体对齐） */
+  displayColumns: ComputedRef<ColumnWithSummary<T>[]> | (() => ColumnWithSummary<T>[])
+  viewRows: ComputedRef<T[]> | (() => T[])
+  /** 是否存在 #summary 插槽（有则不渲染内置行） */
+  hasSummarySlot: ComputedRef<boolean> | (() => boolean)
+  treeMode: ComputedRef<boolean> | (() => boolean)
+  detailExpandable: ComputedRef<boolean> | (() => boolean)
+  showRowDragHandle: ComputedRef<boolean> | (() => boolean)
+  showSelectColumn: ComputedRef<boolean> | (() => boolean)
+  showEditGutterOrIndex: ComputedRef<boolean> | (() => boolean)
+  showRowStatusColumn: ComputedRef<boolean> | (() => boolean)
+}
+
+/**
+ * 汇总 feature 状态。
+ *
+ * @returns enabled / cells / showBuiltinSummaryRow / prefixColspan
+ */
+export function useRsTableSummary<T extends RsTableRowData>(options: UseRsTableSummaryOptions<T>) {
+  const summaryFeatureEnabled = computed(() => {
+    if (read(options.showSummary)) return true
+    return hasTableSummaryConfig({
+      columns: read(options.columns),
+      mode: read(options.summaryMode),
+      summaryData: read(options.summaryData),
+    })
+  })
+
+  const summaryCells = computed(() => {
+    if (!summaryFeatureEnabled.value) return []
+    return buildTableSummaryCells({
+      columns: read(options.displayColumns),
+      rows: read(options.viewRows),
+      mode: read(options.summaryMode),
+      summaryData: read(options.summaryData),
+    })
+  })
+
+  const showBuiltinSummaryRow = computed(
+    () => summaryFeatureEnabled.value && !read(options.hasSummarySlot),
+  )
+
+  const summaryPrefixColspan = computed(() => {
+    let n = 0
+    if (read(options.showRowDragHandle)) n += 1
+    if (read(options.detailExpandable)) n += 1
+    if (read(options.showSelectColumn)) n += 1
+    if (read(options.showEditGutterOrIndex)) n += 1
+    if (read(options.showRowStatusColumn)) n += 1
+    return n
+  })
+
+  if (import.meta.env.DEV) {
+    watch(
+      () =>
+        [
+          summaryFeatureEnabled.value,
+          read(options.treeMode),
+          read(options.detailExpandable),
+        ] as const,
+      ([summaryEnabled, tree, detail]) => {
+        warnSummaryCompatibility({
+          summaryEnabled,
+          tree,
+          detailExpandable: detail,
+        })
+      },
+      { immediate: true },
+    )
+  }
+
+  return {
+    summaryFeatureEnabled,
+    summaryCells,
+    showBuiltinSummaryRow,
+    summaryPrefixColspan,
+  }
+}
+
+/** 供 feature 注册表识别：summary 已由 useRsTableSummary 承载 */
+export const RS_TABLE_SUMMARY_FEATURE_ID = 'summary' as const