create-react-admin-template 0.0.0-stage → 0.1.0

package/template/src/components/AppTable/engine/selection/selection.ts

@@ -0,0 +1,357 @@
+import { getTableRowValue } from '../shared/row'
+import { walkTableRows } from '../shared/treeRows'
+import type { TableRow } from '../shared/types'
+import {
+  isRowKey,
+  TABLE_CLIENT_ROW_KEY_PREFIX,
+  type RowKey,
+} from '../table/editing'
+import type {
+  SelectionDescriptor,
+  SelectionState,
+  TableRowSelectionUpdate,
+  TableSelectionOptions,
+} from './types'
+
+export type {
+  SelectionDescriptor,
+  SelectionState,
+  TableRowSelectionUpdate,
+  TableSelectionOptions,
+} from './types'
+
+export const serializeSelection = <T extends TableRow>(
+  selection: SelectionState<T>
+): SelectionDescriptor =>
+  selection.mode === 'explicit'
+    ? { mode: 'explicit', keys: [...selection.keys] }
+    : {
+        mode: 'allMatching',
+        queryToken: selection.queryToken,
+        excludedKeys: [...selection.excludedKeys],
+      }
+
+export const isSelectionFullyLoaded = <T extends TableRow>(
+  selection: SelectionState<T>
+) =>
+  selection.mode === 'explicit' &&
+  selection.keys.size === selection.loadedRows.size
+
+/** 未启用选择能力时使用的空显式状态。 */
+export const createEmptyTableSelectionState = <
+  T extends TableRow,
+>(): SelectionState<T> => ({
+  mode: 'explicit',
+  keys: new Set(),
+  loadedRows: new Map(),
+})
+
+const isClientKey = (key: RowKey) =>
+  typeof key === 'string' && key.startsWith(TABLE_CLIENT_ROW_KEY_PREFIX)
+
+/**
+ * 框架无关的选择状态机。
+ *
+ * 选择身份只依赖稳定 rowKey；行对象只缓存当前已加载页面中的最新实例，避免翻页后
+ * 继续把旧对象提交给业务接口。跨页全选使用 queryToken + excludedKeys 表达，绝不把
+ * 当前页 rows 冒充全部数据。
+ */
+export class TableSelection<T extends TableRow = TableRow> {
+  private mode: SelectionState<T>['mode'] = 'explicit'
+  private keys = new Set<RowKey>()
+  private queryToken = ''
+  private queryIdentity = ''
+  private excludedKeys = new Set<RowKey>()
+  private loadedRows = new Map<RowKey, T>()
+  private stateCache: SelectionState<T> | null = null
+
+  constructor(private readonly options: TableSelectionOptions<T>) {}
+
+  /** 返回 Controller 装配时验证过的统一行身份解析器。 */
+  get rowKeyResolver() {
+    return this.options.rowKey
+  }
+
+  getRowKey(row: T): RowKey {
+    const value =
+      typeof this.options.rowKey === 'function'
+        ? this.options.rowKey(row)
+        : getTableRowValue(row, this.options.rowKey)
+    if (!isRowKey(value)) {
+      throw new Error(
+        '[TableComponent] Every selectable row requires a rowKey.'
+      )
+    }
+    return value
+  }
+
+  get state(): SelectionState<T> {
+    if (this.stateCache) return this.stateCache
+    const loadedRows = new Map(this.loadedRows)
+    if (this.mode === 'allMatching') {
+      this.stateCache = {
+        mode: 'allMatching',
+        queryToken: this.queryToken,
+        excludedKeys: new Set(this.excludedKeys),
+        loadedRows,
+      }
+      return this.stateCache
+    }
+    this.stateCache = {
+      mode: 'explicit',
+      keys: new Set(this.keys),
+      loadedRows,
+    }
+    return this.stateCache
+  }
+
+  private invalidateState() {
+    this.stateCache = null
+  }
+
+  get loadedSelectedRows(): T[] {
+    return [...this.loadedRows.values()]
+  }
+
+  isSelected(rowOrKey: T | RowKey) {
+    if (typeof rowOrKey === 'object' && !this.canSelect(rowOrKey)) return false
+    const key =
+      typeof rowOrKey === 'object' ? this.getRowKey(rowOrKey) : rowOrKey
+    return this.mode === 'allMatching'
+      ? !isClientKey(key) && !this.excludedKeys.has(key)
+      : this.keys.has(key)
+  }
+
+  canSelect(row: T) {
+    return (
+      this.options.isRowSelectable?.(row) !== false &&
+      (this.mode !== 'allMatching' || !isClientKey(this.getRowKey(row)))
+    )
+  }
+
+  /**
+   * 在不修改当前选择状态的前提下构建新页面映射；调用返回函数才会提交。
+   * Controller 用它保证 rows、编辑基线和选择状态要么一起成功，要么都不改变。
+   */
+  prepareLoadedRows(rows: readonly T[], resolvedKeys?: readonly RowKey[]) {
+    const loadedRows = new Map<RowKey, T>()
+    const loadedKeys = new Set<RowKey>()
+    const keys = new Set(this.keys)
+    const excludedKeys = new Set(this.excludedKeys)
+    let flatIndex = 0
+    walkTableRows(rows, ({ row }) => {
+      const key = resolvedKeys?.[flatIndex] ?? this.getRowKey(row)
+      flatIndex += 1
+      if (loadedKeys.has(key)) {
+        throw new Error(
+          `[TableComponent] Duplicate rowKey "${String(key)}" in loaded rows.`
+        )
+      }
+      loadedKeys.add(key)
+      const selectable =
+        this.options.isRowSelectable?.(row) !== false &&
+        (this.mode !== 'allMatching' || !isClientKey(key))
+      const selected =
+        selectable &&
+        (this.mode === 'allMatching'
+          ? !isClientKey(key) && !excludedKeys.has(key)
+          : keys.has(key))
+      if (selected) loadedRows.set(key, row)
+      else if (this.mode === 'explicit') keys.delete(key)
+      else if (!selectable) excludedKeys.add(key)
+    })
+    if (resolvedKeys && flatIndex !== resolvedKeys.length) {
+      throw new Error(
+        '[TableComponent] Prepared row identity count does not match the data tree.'
+      )
+    }
+
+    // 未保存的 client 行被丢弃后不可能在其他分页重新出现，应同步清理其选择痕迹。
+    const isMissingClientKey = (key: RowKey) =>
+      isClientKey(key) && !loadedKeys.has(key)
+    if (this.mode === 'explicit') {
+      for (const key of keys) {
+        if (isMissingClientKey(key)) keys.delete(key)
+      }
+    } else {
+      for (const key of excludedKeys) {
+        if (isMissingClientKey(key)) excludedKeys.delete(key)
+      }
+    }
+    return () => {
+      this.invalidateState()
+      this.keys = keys
+      this.excludedKeys = excludedKeys
+      this.loadedRows = loadedRows
+    }
+  }
+
+  setLoadedRows(rows: readonly T[], resolvedKeys?: readonly RowKey[]) {
+    this.prepareLoadedRows(rows, resolvedKeys)()
+  }
+
+  toggle(row: T, selected: boolean) {
+    const key = this.getRowKey(row)
+    if (selected && !this.canSelect(row)) {
+      if (this.mode === 'allMatching' && isClientKey(key)) {
+        throw new Error(
+          '[TableComponent] Save a client row before adding it to allMatching selection.'
+        )
+      }
+      throw new Error(
+        `[TableComponent] Row "${String(key)}" is not selectable.`
+      )
+    }
+    this.invalidateState()
+    if (this.mode === 'allMatching') {
+      if (!this.canSelect(row)) return
+      if (selected) this.excludedKeys.delete(key)
+      else this.excludedKeys.add(key)
+    } else if (selected) {
+      if (this.options.multiple === false) {
+        this.keys.clear()
+        this.loadedRows.clear()
+      }
+      this.keys.add(key)
+    } else {
+      this.keys.delete(key)
+    }
+    if (selected) this.loadedRows.set(key, row)
+    else this.loadedRows.delete(key)
+  }
+
+  updateRows(rows: readonly T[], update: TableRowSelectionUpdate) {
+    const selectable = rows.filter((row) => this.canSelect(row))
+    if (this.options.multiple === false && update !== 'deselect') {
+      const row = selectable[0]
+      if (row) {
+        this.toggle(row, update === 'toggle' ? !this.isSelected(row) : true)
+      }
+      return
+    }
+    selectable.forEach((row) => {
+      const selected =
+        update === 'toggle' ? !this.isSelected(row) : update === 'select'
+      this.toggle(row, selected)
+    })
+  }
+
+  selectPage(rows: readonly T[], selected = true) {
+    this.updateRows(rows, selected ? 'select' : 'deselect')
+  }
+
+  replaceExplicit(rows: readonly T[]) {
+    if (this.options.multiple === false && rows.length > 1) {
+      throw new Error(
+        '[TableComponent] Single-selection tables accept at most one selected row.'
+      )
+    }
+    const unavailable = rows.find((row) => !this.canSelect(row))
+    if (unavailable) {
+      throw new Error(
+        `[TableComponent] Row "${String(this.getRowKey(unavailable))}" is not selectable.`
+      )
+    }
+    const keys = rows.map((row) => this.getRowKey(row))
+    if (new Set(keys).size !== keys.length) {
+      throw new Error(
+        '[TableComponent] Explicit selection contains duplicate rowKey values.'
+      )
+    }
+    this.invalidateState()
+    this.mode = 'explicit'
+    this.queryToken = ''
+    this.excludedKeys.clear()
+    this.keys = new Set(keys)
+    this.loadedRows = new Map(
+      rows.map((row): [RowKey, T] => [this.getRowKey(row), row])
+    )
+  }
+
+  selectAllMatching(
+    queryToken: string,
+    queryIdentity: string,
+    loadedRows: readonly T[] = []
+  ) {
+    if (this.options.multiple === false) {
+      throw new Error(
+        '[TableComponent] Query-wide selection is unavailable in single-selection mode.'
+      )
+    }
+    if (!queryToken.trim()) {
+      throw new Error(
+        '[TableComponent] allMatching selection requires an immutable queryToken.'
+      )
+    }
+    if (!queryIdentity.trim()) {
+      throw new Error(
+        '[TableComponent] allMatching selection requires a query identity.'
+      )
+    }
+    this.invalidateState()
+    this.mode = 'allMatching'
+    this.queryToken = queryToken
+    this.queryIdentity = queryIdentity
+    this.keys.clear()
+    this.excludedKeys.clear()
+    this.setLoadedRows(loadedRows)
+  }
+
+  /**
+   * 与查询数据提交同步更新结果集身份；身份变化时只清除旧 allMatching 状态。
+   * 本方法不调用业务回调且不会抛错，可安全位于 Controller 的提交区。
+   */
+  applyQueryIdentity(nextIdentity: string) {
+    const invalidated =
+      this.mode === 'allMatching' && this.queryIdentity !== nextIdentity
+    if (invalidated) this.clear()
+    this.queryIdentity = nextIdentity
+    return invalidated
+  }
+
+  /** 不可变查询快照失效时清除 allMatching 选择状态。 */
+  invalidateQueryToken(nextQueryToken?: string) {
+    if (
+      this.mode !== 'allMatching' ||
+      (nextQueryToken !== undefined && nextQueryToken === this.queryToken)
+    ) {
+      return false
+    }
+    this.clear()
+    return true
+  }
+
+  clear() {
+    this.invalidateState()
+    this.mode = 'explicit'
+    this.keys.clear()
+    this.queryToken = ''
+    this.queryIdentity = ''
+    this.excludedKeys.clear()
+    this.loadedRows.clear()
+  }
+
+  removeKey(key: RowKey) {
+    this.invalidateState()
+    if (this.mode === 'explicit') this.keys.delete(key)
+    else this.excludedKeys.delete(key)
+    this.loadedRows.delete(key)
+  }
+
+  remapKey(previousKey: RowKey, nextKey: RowKey, row: T) {
+    this.invalidateState()
+    if (this.mode === 'explicit' && this.keys.delete(previousKey)) {
+      this.keys.add(nextKey)
+    }
+    if (this.mode === 'allMatching' && this.excludedKeys.delete(previousKey)) {
+      this.excludedKeys.add(nextKey)
+    }
+    if (this.loadedRows.delete(previousKey) && this.isSelected(nextKey)) {
+      this.loadedRows.set(nextKey, row)
+    }
+  }
+}
+
+export const createTableSelection = <T extends TableRow>(
+  options: TableSelectionOptions<T>
+) => new TableSelection(options)

package/template/src/components/AppTable/engine/selection/selectionHeader.ts

@@ -0,0 +1,88 @@
+import { TABLE_ENGINE_MESSAGES_ZH_CN } from '../shared/messages'
+import type { TableRow } from '../shared/types'
+
+export interface RenderTableSelectionHeaderOptions<T extends TableRow> {
+  th: HTMLTableCellElement
+  rows: readonly T[]
+  showSelectAll?: boolean
+  multiple?: boolean
+  canSelect: (row: T) => boolean
+  isSelected: (row: T) => boolean
+  selectPage: (rows: readonly T[], selected: boolean) => void
+  onChange: () => void
+  createCheckbox?: () => HTMLInputElement
+  /** 当前页全选框的无障碍名称。 */
+  ariaLabel?: string
+  /** 由响应式选择状态预计算；提供后表头重绘不再扫描整页数据。 */
+  state?: {
+    selectableRows: readonly T[]
+    selectedCount: number
+  }
+}
+
+interface SelectionHeaderBinding<T extends TableRow> {
+  rows: readonly T[]
+  selectPage: (rows: readonly T[], selected: boolean) => void
+  onChange: () => void
+}
+
+const selectionHeaderBindings = new WeakMap<
+  HTMLInputElement,
+  SelectionHeaderBinding<TableRow>
+>()
+
+/** 不依赖框架组件或全局挂载节点渲染选择列表头。 */
+export const renderTableSelectionHeader = <T extends TableRow>({
+  th,
+  rows,
+  showSelectAll = true,
+  multiple = true,
+  canSelect,
+  isSelected,
+  selectPage,
+  onChange,
+  createCheckbox = () => document.createElement('input'),
+  ariaLabel = TABLE_ENGINE_MESSAGES_ZH_CN.strSelectCurrentPage,
+  state,
+}: RenderTableSelectionHeaderOptions<T>) => {
+  th.querySelector('button.changeType')?.remove()
+  th.removeAttribute('aria-haspopup')
+  const host = th.querySelector('.colHeader') ?? th
+  if (!showSelectAll || !multiple) {
+    host.replaceChildren()
+    return
+  }
+  const selectableRows = state?.selectableRows ?? rows.filter(canSelect)
+  const selectedCount =
+    state?.selectedCount ?? selectableRows.filter(isSelected).length
+  let checkbox = host.querySelector<HTMLInputElement>(
+    '.table-component__select-page'
+  )
+  if (!checkbox) {
+    checkbox = createCheckbox()
+    checkbox.onclick = (event) => event.stopPropagation()
+    checkbox.onchange = () => {
+      const binding = selectionHeaderBindings.get(checkbox!)
+      if (!binding) return
+      binding.selectPage(binding.rows, checkbox!.checked)
+      binding.onChange()
+    }
+    host.replaceChildren(checkbox)
+  }
+  selectionHeaderBindings.set(checkbox, {
+    rows: selectableRows,
+    selectPage: selectPage as (
+      rows: readonly TableRow[],
+      selected: boolean
+    ) => void,
+    onChange,
+  })
+  checkbox.type = 'checkbox'
+  checkbox.className = 'table-component__select-page'
+  checkbox.ariaLabel = ariaLabel
+  checkbox.disabled = selectableRows.length === 0
+  checkbox.checked =
+    selectableRows.length > 0 && selectedCount === selectableRows.length
+  checkbox.indeterminate =
+    selectedCount > 0 && selectedCount < selectableRows.length
+}

package/template/src/components/AppTable/engine/selection/types.ts

@@ -0,0 +1,66 @@
+import type { TableRow } from '../shared/types'
+import type { RowKey, RowKeyResolver } from '../table/editing'
+
+export interface ExplicitSelectionState<T extends TableRow = TableRow> {
+  /** 当前选择模式；explicit 表示逐行选择。 */
+  mode: 'explicit'
+  /** 用户逐条选择的稳定行 key，可以包含当前页尚未加载的行。 */
+  keys: ReadonlySet<RowKey>
+  /** 当前已加载数据中能够还原出的选中行对象，不保存跨页旧对象快照。 */
+  loadedRows: ReadonlyMap<RowKey, T>
+}
+
+export interface AllMatchingSelectionState<T extends TableRow = TableRow> {
+  /** 当前选择模式；allMatching 表示选中某次查询的全部匹配行。 */
+  mode: 'allMatching'
+  /** 后端生成的不可变查询快照，用于跨页批量操作和导出。 */
+  queryToken: string
+  /** “全部匹配”模式下被用户手工取消选择的行 key。 */
+  excludedKeys: ReadonlySet<RowKey>
+  /** 当前已加载数据中能够还原出的选中行对象，不代表全部匹配数据。 */
+  loadedRows: ReadonlyMap<RowKey, T>
+}
+
+export type SelectionState<T extends TableRow = TableRow> =
+  | ExplicitSelectionState<T>
+  | AllMatchingSelectionState<T>
+
+export type SelectionDescriptor =
+  | {
+      /** 显式逐行选择模式。 */
+      mode: 'explicit'
+      /** 用户明确选中的稳定行主键。 */
+      keys: RowKey[]
+    }
+  | {
+      /** 选中某次查询全部匹配行的模式。 */
+      mode: 'allMatching'
+      /** 服务端生成、用于重建不可变查询结果集的令牌。 */
+      queryToken: string
+      /** 全部匹配模式下被用户手工排除的行主键。 */
+      excludedKeys: RowKey[]
+    }
+
+export interface TableSelectionOptions<T extends TableRow> {
+  /** 返回稳定行主键，选择状态不会依赖可变的行对象引用。 */
+  rowKey: RowKeyResolver<T>
+  /** 是否允许同时选择多行；false 时新选择会替换旧选择。 */
+  multiple?: boolean
+  /** 按业务规则判断某一行是否允许被选择。 */
+  isRowSelectable?: (row: T) => boolean
+}
+
+export type TableRowSelectionUpdate = 'select' | 'deselect' | 'toggle'
+
+export interface TableRowSelectionConfig<T extends TableRow = TableRow> {
+  /** 是否允许同时选择多行，默认 true；false 时页全选和全量匹配不可用。 */
+  multiple?: boolean
+  /** 是否在选择列表头显示当前页全选框，默认 true。 */
+  showSelectAll?: boolean
+  /** 点击普通数据单元格时不选择、只选中或反选整行，默认 none。 */
+  rowClick?: 'none' | 'select' | 'toggle'
+  /** 选中多单元格区域时执行显式批量操作。 */
+  rangeSelection?: false | 'select' | 'toggle'
+  /** 返回 false 的行不会被点击、拖动、页全选或全量匹配选中。 */
+  isRowSelectable?: (row: T) => boolean
+}

package/template/src/components/AppTable/engine/shared/action.ts

@@ -0,0 +1,11 @@
+/** 统一执行可同步抛错或返回 Promise 的业务动作，并转入组件错误边界。 */
+export const runTableAction = (
+  action: () => void | Promise<void>,
+  onError: (error: unknown) => void
+) => {
+  try {
+    void Promise.resolve(action()).catch(onError)
+  } catch (error) {
+    onError(error)
+  }
+}

package/template/src/components/AppTable/engine/shared/constants.ts

@@ -0,0 +1,2 @@
+/** 单击等待窗口；窗口内第二次点击同一行会被识别为双击。 */
+export const TABLE_ROW_CLICK_DELAY_MS = 200

package/template/src/components/AppTable/engine/shared/decimal.ts

@@ -0,0 +1,114 @@
+import Decimal from 'decimal.js'
+
+const TABLE_DECIMAL_MAX_DIGITS = 10_000
+const TABLE_DECIMAL_ROUND_HALF_UP = Decimal.ROUND_HALF_UP
+
+interface TableDecimalContextOptions {
+  precision?: number
+  maxExponent?: number
+}
+
+/** 创建具有统一舍入和指数显示策略的表格十进制上下文。 */
+export const createTableDecimalContext = (
+  options: TableDecimalContextOptions = {}
+) => {
+  const maxExponent = Math.max(
+    1,
+    Math.trunc(options.maxExponent ?? TABLE_DECIMAL_MAX_DIGITS)
+  )
+  return Decimal.clone({
+    precision: Math.max(
+      1,
+      Math.trunc(options.precision ?? TABLE_DECIMAL_MAX_DIGITS + 50)
+    ),
+    rounding: TABLE_DECIMAL_ROUND_HALF_UP,
+    maxE: maxExponent,
+    minE: -maxExponent,
+    toExpNeg: -maxExponent,
+    toExpPos: maxExponent,
+  })
+}
+
+export const TableDecimal = createTableDecimalContext()
+export type TableDecimalInstance = InstanceType<typeof TableDecimal>
+
+interface ParseTableDecimalOptions {
+  maxDigits?: number
+  maxExponent?: number
+  DecimalContext?: typeof TableDecimal
+}
+
+const TABLE_DECIMAL_PATTERN =
+  /^([+-]?)(?:(\d+)(?:\.(\d*))?|\.(\d+))(?:e([+-]?\d+))?$/i
+
+/** 严格解析普通/科学计数法数值，并限制系数与指数避免异常内存消耗。 */
+export const parseTableDecimal = (
+  value: unknown,
+  options: ParseTableDecimalOptions = {}
+): TableDecimalInstance | undefined => {
+  if (typeof value !== 'number' && typeof value !== 'string') return
+  const text = String(value).trim()
+  if (!text) return
+  const match = TABLE_DECIMAL_PATTERN.exec(text)
+  if (!match) return
+  const maxDigits = Math.max(
+    1,
+    Math.trunc(options.maxDigits ?? TABLE_DECIMAL_MAX_DIGITS)
+  )
+  const maxExponent = Math.max(
+    1,
+    Math.trunc(options.maxExponent ?? TABLE_DECIMAL_MAX_DIGITS)
+  )
+  const exponent = Number(match[5] ?? 0)
+  const coefficient = `${match[2] ?? ''}${match[3] ?? match[4] ?? ''}`
+  const significantDigits = coefficient.replace(/^0+/, '').length
+  if (
+    !Number.isSafeInteger(exponent) ||
+    Math.abs(exponent) > maxExponent ||
+    coefficient.length > maxDigits ||
+    significantDigits + Math.max(0, exponent) > maxDigits
+  ) {
+    return
+  }
+  try {
+    const DecimalContext = options.DecimalContext ?? TableDecimal
+    const decimal = new DecimalContext(text)
+    return decimal.isFinite() ? decimal : undefined
+  } catch {
+    return undefined
+  }
+}
+
+interface TableDecimalMetrics {
+  integerDigits: number
+  decimalPlaces: number
+}
+
+/** 返回输入文本对应的精确整数位和小数位，不经过 Number 舍入。 */
+export const getTableDecimalMetrics = (
+  value: unknown
+): TableDecimalMetrics | undefined => {
+  const text = String(value).trim()
+  const match = TABLE_DECIMAL_PATTERN.exec(text)
+  const decimal = parseTableDecimal(value)
+  if (!match || !decimal) return
+  const exponent = Number(match[5] ?? 0)
+  const fractionLength = (match[3] ?? match[4] ?? '').length
+  const integer = decimal.abs().trunc()
+  return {
+    integerDigits: integer.isZero() ? 1 : integer.toFixed(0).length,
+    decimalPlaces: Math.max(0, fractionLength - exponent),
+  }
+}
+
+export const roundTableDecimal = (
+  value: TableDecimalInstance,
+  decimalPlaces: number
+) =>
+  value.toDecimalPlaces(
+    Math.max(0, Math.trunc(decimalPlaces)),
+    TABLE_DECIMAL_ROUND_HALF_UP
+  )
+
+export const tableDecimalToString = (value: TableDecimalInstance) =>
+  value.toFixed()

package/template/src/components/AppTable/engine/shared/feedback.ts

@@ -0,0 +1,62 @@
+import type {
+  NotificationConfig,
+  NotificationMessageOptions,
+} from 'handsontable/plugins/notification'
+
+export interface TableFeedbackAction {
+  /** 空状态操作按钮显示的文本。 */
+  label: string
+  /** 按钮视觉级别；默认使用次要按钮。 */
+  type?: 'primary' | 'secondary'
+  /** 用户点击空状态操作按钮时执行的回调。 */
+  onClick: () => void
+}
+
+export interface TableEmptyStateCopy {
+  /** 空状态主标题。 */
+  title?: string
+  /** 空状态补充说明。 */
+  description?: string
+}
+
+export interface TableEmptyStateOptions extends TableEmptyStateCopy {
+  /** 有筛选条件但无匹配数据时使用的文案。 */
+  filtered?: TableEmptyStateCopy
+  /** 首次加载且尚无数据时使用的文案。 */
+  loading?: TableEmptyStateCopy
+  /** 普通空数据状态下显示的业务操作按钮。 */
+  action?: TableFeedbackAction
+  /** 筛选无结果时“清除筛选”按钮的自定义文本。 */
+  resetFiltersLabel?: string
+}
+
+export interface TableQueryErrorFeedbackOptions {
+  /** 查询失败通知的标题；默认显示“加载失败”。 */
+  title?: string
+  /** 查询失败通知正文，函数形式可根据原始异常生成业务文案。 */
+  message?: string | ((error: unknown) => string)
+  /** 查询失败通知中重试按钮的文本。 */
+  retryLabel?: string
+  /** Handsontable 通知在表格区域中的显示位置。 */
+  position?: NotificationMessageOptions['position']
+}
+
+export interface TableFeedbackOptions {
+  /** 是否启用 Handsontable 通知，也可传入通知栈和动画配置。 */
+  notification?: boolean | NotificationConfig
+  /** 空数据反馈配置；设为 false 时完全关闭空状态覆盖层。 */
+  emptyState?: false | TableEmptyStateOptions
+  /** 远程查询失败反馈配置；设为 false 时不显示查询错误通知。 */
+  queryError?: false | TableQueryErrorFeedbackOptions
+}
+
+export type TableLoadingMaskMode = 'initial' | 'always' | 'never'
+
+export const resolveTableLoadingMask = (
+  mode: TableLoadingMaskMode,
+  loading: boolean,
+  rowCount: number
+) =>
+  loading &&
+  mode !== 'never' &&
+  (mode === 'always' || (mode === 'initial' && rowCount === 0))