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

package/template/src/components/AppTable/engine/table/layout/fixedEndOverlaySignature.ts

@@ -0,0 +1,58 @@
+import type Handsontable from 'handsontable'
+
+interface TableFixedEndOverlaySignatureOptions {
+  hot: Handsontable
+  holder: HTMLElement
+  rows: readonly HTMLTableRowElement[]
+  bottomRows: readonly HTMLTableRowElement[]
+  columns: readonly number[]
+  widths: readonly number[]
+  fixedColumnsEnd: number
+  dataRevision: number
+}
+
+const resolveOverlayVisualRow = (row: HTMLTableRowElement) => {
+  const ariaIndex = Number(row.getAttribute('aria-rowindex'))
+  return Number.isFinite(ariaIndex) ? ariaIndex - 2 : -1
+}
+
+/**
+ * 创建不读取 DOMRect 的固定尾列结构签名。
+ *
+ * Handsontable 在纯横向滚动后也会触发 afterViewRender；纵向 scrollTop 必须进入
+ * 签名，否则同一批可见行内的小幅滚动会错误复用旧的行坐标。
+ */
+export const buildTableFixedEndOverlayLayoutKey = ({
+  hot,
+  holder,
+  rows,
+  bottomRows,
+  columns,
+  widths,
+  fixedColumnsEnd,
+  dataRevision,
+}: TableFixedEndOverlaySignatureOptions) => {
+  const rowKey = (row: HTMLTableRowElement) => {
+    const visualRow = resolveOverlayVisualRow(row)
+    return `${visualRow}:${hot.toPhysicalRow(visualRow)}:${hot.getRowHeight(visualRow)}:${Boolean(row.querySelector('td.table-component__current-row'))}`
+  }
+  return [
+    dataRevision,
+    fixedColumnsEnd,
+    hot.countRows(),
+    hot.countCols(),
+    holder.clientWidth,
+    holder.clientHeight,
+    holder.scrollTop,
+    widths.join(','),
+    columns
+      .map((column) => {
+        const label = hot.getColHeader(column)
+        return Array.isArray(label) ? label.at(-1) : label
+      })
+      .join('|'),
+    rows.map(rowKey).join(','),
+    bottomRows.map(rowKey).join(','),
+    hot.isRtl(),
+  ].join(';')
+}

package/template/src/components/AppTable/engine/table/layout/fixedEndRuntime.ts

@@ -0,0 +1,137 @@
+import type Handsontable from 'handsontable'
+import {
+  TABLE_ENGINE_MESSAGES_ZH_CN,
+  type TableEngineMessages,
+} from '../../shared/messages'
+import {
+  isTableFixedEndShadowVisible,
+  resolveTableFixedEndShadow,
+} from './fixedEndOverlay'
+import { createFixedEndSemanticReconciler } from './fixedEndOverlayAccessibility'
+import { createTableFixedEndOverlay } from './fixedEndOverlayRenderer'
+import { findHandsontableMasterHolder } from './handsontableDomAdapter'
+import { createTableLayoutScheduler } from './layoutScheduler'
+
+interface CreateTableFixedEndRuntimeOptions {
+  getContainer: () => HTMLElement | null | undefined
+  getShadowElement: () => HTMLElement | null | undefined
+  getFixedColumnsEnd: () => number
+  getTotalColumns: () => number
+  getInstance: () => Handsontable | null | undefined
+  getDataRevision: () => number
+  messages?: TableEngineMessages
+  requestFrame?: (callback: FrameRequestCallback) => number
+  cancelFrame?: (handle: number) => void
+}
+
+/**
+ * 管理固定尾列的唯一 overlay、重复语义和连续阴影。
+ *
+ * 运行时只依赖 DOM 与 Handsontable 公共能力，React 层仅负责提供节点引用和
+ * 主题样式，避免两个适配层分别维护滚动调度与几何缓存。
+ */
+export const createTableFixedEndRuntime = ({
+  getContainer,
+  getShadowElement,
+  getFixedColumnsEnd,
+  getTotalColumns,
+  getInstance,
+  getDataRevision,
+  messages = TABLE_ENGINE_MESSAGES_ZH_CN,
+  requestFrame = (callback) => requestAnimationFrame(callback),
+  cancelFrame = (handle) => cancelAnimationFrame(handle),
+}: CreateTableFixedEndRuntimeOptions) => {
+  let shadowPosition: number | undefined
+  let geometryDirty = true
+  let holder: HTMLElement | undefined
+  const semantics = createFixedEndSemanticReconciler()
+  const overlay = createTableFixedEndOverlay({
+    getContainer: () => getContainer() ?? undefined,
+    getFixedColumnsEnd,
+    getInstance,
+    getDataRevision,
+    semantics,
+    ariaLabel: messages.strFixedActionColumns,
+  })
+
+  const getHolder = () => {
+    if (holder?.isConnected) return holder
+    holder = findHandsontableMasterHolder(getContainer() ?? undefined)
+    return holder
+  }
+
+  const syncShadowVisibility = () => {
+    const shadow = getShadowElement()
+    if (!shadow) return
+    shadow.style.display = isTableFixedEndShadowVisible(getHolder())
+      ? ''
+      : 'none'
+  }
+
+  const syncShadow = () => {
+    const requiresGeometry = geometryDirty || shadowPosition === undefined
+    if (getFixedColumnsEnd() > 0) {
+      if (requiresGeometry) overlay.render()
+    } else overlay.destroy()
+    geometryDirty = false
+
+    // 横向滚动不改变固定层几何，只同步边界可见性，避免每帧读取 DOMRect。
+    if (!requiresGeometry) {
+      syncShadowVisibility()
+      return
+    }
+    const snapshot = resolveTableFixedEndShadow({
+      host: getContainer() ?? undefined,
+      fixedColumnsEnd: getFixedColumnsEnd(),
+      getDirection: () => (getInstance()?.isRtl() ? 'rtl' : 'ltr'),
+    })
+    shadowPosition = snapshot.position
+    const shadow = getShadowElement()
+    if (!shadow) return
+    shadow.style.left =
+      snapshot.position === undefined ? '' : `${snapshot.position}px`
+    shadow.style.top =
+      snapshot.blockStart === undefined ? '' : `${snapshot.blockStart}px`
+    shadow.style.height =
+      snapshot.height === undefined ? '' : `${snapshot.height}px`
+    shadow.style.display = snapshot.visible ? '' : 'none'
+    shadow.classList.toggle('is-rtl', snapshot.rtl)
+  }
+  const layoutScheduler = createTableLayoutScheduler({
+    onFrame: syncShadow,
+    requestFrame,
+    cancelFrame,
+  })
+
+  const scheduleShadow = (measureGeometry = true) => {
+    geometryDirty ||= measureGeometry
+    layoutScheduler.scheduleFrame()
+  }
+
+  const cancel = () => {
+    layoutScheduler.cancel()
+    shadowPosition = undefined
+    geometryDirty = true
+    holder = undefined
+    overlay.destroy()
+    const shadow = getShadowElement()
+    if (shadow) shadow.style.display = 'none'
+  }
+
+  const applyElement = (
+    element: HTMLElement,
+    column: number,
+    enabled = true
+  ) => {
+    const totalColumns = getInstance()?.countCols() ?? getTotalColumns()
+    const fixedColumnsEnd = getFixedColumnsEnd()
+    const isSemanticDuplicate =
+      semantics.active &&
+      enabled &&
+      fixedColumnsEnd > 0 &&
+      column >= Math.max(0, totalColumns - fixedColumnsEnd)
+    semantics.updateElement(element, isSemanticDuplicate)
+  }
+
+  return { applyElement, cancel, scheduleShadow }
+}

package/template/src/components/AppTable/engine/table/layout/handsontableDomAdapter.ts

@@ -0,0 +1,40 @@
+/**
+ * Handsontable 私有 DOM 结构的唯一兼容层。
+ *
+ * 版本升级若调整 clone/holder 类名，只需修改这里并运行固定尾列契约测试；业务布局
+ * 模块不得再次直接查询这些选择器。
+ */
+const selectors = {
+  masterHolder: '.ht_master .wtHolder',
+  masterRows: '.ht_master tbody tr',
+  topClone: '.ht_clone_top',
+  topHeaderRow: 'thead tr:last-child',
+  bottomClone: '.ht_clone_bottom',
+  bodyRows: 'tbody tr',
+} as const
+
+export const findHandsontableMasterHolder = (host?: HTMLElement) =>
+  host?.querySelector<HTMLElement>(selectors.masterHolder) ?? undefined
+
+export const readHandsontableFixedEndDom = (host?: HTMLElement) => {
+  const headerClone = host?.querySelector<HTMLElement>(selectors.topClone)
+  const bottomClone = host?.querySelector<HTMLElement>(selectors.bottomClone)
+  return {
+    holder: findHandsontableMasterHolder(host),
+    headerClone,
+    headerRow:
+      headerClone?.querySelector<HTMLTableRowElement>(selectors.topHeaderRow) ??
+      undefined,
+    bottomClone,
+    masterRows: host
+      ? Array.from(
+          host.querySelectorAll<HTMLTableRowElement>(selectors.masterRows)
+        )
+      : [],
+    bottomRows: bottomClone
+      ? Array.from(
+          bottomClone.querySelectorAll<HTMLTableRowElement>(selectors.bodyRows)
+        )
+      : [],
+  }
+}

package/template/src/components/AppTable/engine/table/layout/height.ts

@@ -0,0 +1,72 @@
+/** 表格网格高度策略；页面布局约束由父容器负责。 */
+export type TableHeight = 'content' | 'fill' | number
+
+const TABLE_EMPTY_GRID_HEIGHT = 160
+
+export interface TableHeightGridInstance {
+  countRows: () => number
+  getRowHeight: (visualRow: number) => number | undefined
+  stylesHandler: {
+    getDefaultRowHeight: (visualRow?: number) => number | null
+  }
+}
+
+/** 首次挂载必须使用确定像素，避免 Handsontable 关闭行虚拟化。 */
+export const resolveTableInitialGridHeight = (height: TableHeight) =>
+  typeof height === 'number' ? Math.max(1, height) : TABLE_EMPTY_GRID_HEIGHT
+
+/** 累加 Handsontable 已解析的行高；达到可用上限后立即停止。 */
+export const measureTableGridContentHeight = ({
+  instance,
+  rowCount,
+  headerHeight,
+  horizontalScrollbarHeight,
+  availableHeight,
+}: {
+  instance: TableHeightGridInstance
+  rowCount: number
+  headerHeight: number
+  horizontalScrollbarHeight: number
+  availableHeight: number
+}) => {
+  const safeAvailableHeight = Math.max(1, availableHeight)
+  if (rowCount === 0) {
+    return Math.min(TABLE_EMPTY_GRID_HEIGHT, safeAvailableHeight)
+  }
+
+  let rowsHeight = 0
+  const gridRowCount = instance.countRows()
+  for (let visualRow = 0; visualRow < gridRowCount; visualRow += 1) {
+    rowsHeight +=
+      instance.getRowHeight(visualRow) ??
+      instance.stylesHandler.getDefaultRowHeight(visualRow) ??
+      0
+    if (
+      headerHeight + rowsHeight + horizontalScrollbarHeight >=
+      safeAvailableHeight
+    ) {
+      return safeAvailableHeight
+    }
+  }
+
+  return Math.max(1, headerHeight + rowsHeight + horizontalScrollbarHeight)
+}
+
+/** 将语义高度策略解析为适配器最终传给 Handsontable 的像素高度。 */
+export const resolveTableGridHeight = ({
+  height,
+  contentHeight,
+  availableHeight,
+}: {
+  height: TableHeight
+  contentHeight: number
+  availableHeight: number
+}) => {
+  const safeAvailableHeight = Math.max(1, availableHeight)
+  if (typeof height === 'number') {
+    return Math.max(1, Math.min(height, safeAvailableHeight))
+  }
+  return height === 'fill'
+    ? safeAvailableHeight
+    : Math.max(1, Math.min(contentHeight, safeAvailableHeight))
+}

package/template/src/components/AppTable/engine/table/layout/index.ts

@@ -0,0 +1,14 @@
+export * from './fixedColumns'
+export * from './constants'
+export * from './dropdownMenu'
+export * from './fixedEndOverlay'
+export * from './fixedEndOverlayAccessibility'
+export * from './fixedEndOverlayRenderer'
+export * from './fixedEndOverlaySignature'
+export * from './fixedEndRuntime'
+export * from './handsontableDomAdapter'
+export * from './height'
+export * from './layoutScheduler'
+export * from './mergeCells'
+export * from './nestedHeaders'
+export * from './types'

package/template/src/components/AppTable/engine/table/layout/layoutScheduler.ts

@@ -0,0 +1,60 @@
+interface CreateTableLayoutSchedulerOptions {
+  /** 下一帧执行的布局写入，例如固定列 overlay 或显式尺寸刷新。 */
+  onFrame?: () => void
+  /** 连续尺寸变化停止两个动画帧后执行的布局测量。 */
+  onSettled?: () => void
+  requestFrame?: (callback: FrameRequestCallback) => number
+  cancelFrame?: (handle: number) => void
+}
+
+/**
+ * 表格自有布局工作的统一帧调度器。
+ *
+ * Handsontable 继续负责观察并刷新自身容器；这里仅合并适配层拥有的 overlay、
+ * 自适应高度等额外工作，避免 React/Vue 各自维护不同的 RAF 策略。
+ */
+export const createTableLayoutScheduler = ({
+  onFrame,
+  onSettled,
+  requestFrame = (callback) => requestAnimationFrame(callback),
+  cancelFrame = (handle) => cancelAnimationFrame(handle),
+}: CreateTableLayoutSchedulerOptions) => {
+  let frame = 0
+  let settledFrame = 0
+
+  const cancelFrameTask = () => {
+    if (frame) cancelFrame(frame)
+    frame = 0
+  }
+  const cancelSettledTask = () => {
+    if (settledFrame) cancelFrame(settledFrame)
+    settledFrame = 0
+  }
+  const scheduleFrame = () => {
+    if (frame || !onFrame) return
+    frame = requestFrame(() => {
+      frame = 0
+      onFrame()
+    })
+  }
+  const scheduleSettled = () => {
+    if (!onSettled) return
+    cancelSettledTask()
+    settledFrame = requestFrame(() => {
+      settledFrame = requestFrame(() => {
+        settledFrame = 0
+        onSettled()
+      })
+    })
+  }
+  const cancel = () => {
+    cancelFrameTask()
+    cancelSettledTask()
+  }
+
+  return {
+    cancel,
+    scheduleFrame,
+    scheduleSettled,
+  }
+}

package/template/src/components/AppTable/engine/table/layout/mergeCells.ts

@@ -0,0 +1,146 @@
+import { getTableRowValue, type TableRow } from '../../shared'
+
+/** 表格布局模块使用的可视合并区域。 */
+export interface TableMergeCellRange {
+  /** 合并区域起始可视行下标。 */
+  row: number
+  /** 合并区域起始可视列下标。 */
+  col: number
+  /** 纵向覆盖行数。 */
+  rowspan: number
+  /** 横向覆盖列数。 */
+  colspan: number
+}
+
+export interface TableMergeCellsContext<T extends TableRow> {
+  /** 当前已加载的源数据行。 */
+  rows: readonly T[]
+  /** 当前可见业务列，不包含选择列。 */
+  columns: readonly string[]
+  /** 选择列等框架附加列产生的视觉偏移。 */
+  columnOffset: number
+  /** 把稳定列 key 解析为当前可视列下标；隐藏列返回 undefined。 */
+  resolveColumn(key: string): number | undefined
+}
+
+/** 任意动态合并规则保持纯函数，因此可由不同 React 表格入口复用。 */
+export type TableMergeCellsResolver<T extends TableRow> = (
+  context: TableMergeCellsContext<T>
+) => readonly TableMergeCellRange[] | false | null | undefined
+
+/** 清洗业务动态合并结果，拒绝负坐标、零跨度和超出当前表格边界的区域。 */
+export const resolveTableMergeCells = <T extends TableRow>(
+  resolver: TableMergeCellsResolver<T>,
+  context: TableMergeCellsContext<T>
+): TableMergeCellRange[] | false => {
+  const ranges = resolver(context)
+  if (ranges === false || !ranges) return false
+  const totalColumns = context.columns.length + context.columnOffset
+  return ranges.flatMap((range) => {
+    const row = Math.trunc(Number(range.row))
+    const col = Math.trunc(Number(range.col))
+    const rowspan = Math.trunc(Number(range.rowspan))
+    const colspan = Math.trunc(Number(range.colspan))
+    const valid =
+      row >= 0 &&
+      col >= 0 &&
+      rowspan > 0 &&
+      colspan > 0 &&
+      row + rowspan <= context.rows.length &&
+      col + colspan <= totalColumns &&
+      (rowspan > 1 || colspan > 1)
+    return valid ? [{ row, col, rowspan, colspan }] : []
+  })
+}
+
+interface BuildTableAutoMergeOptions<T extends TableRow> {
+  /** 按当前显示顺序排列的源数据行。 */
+  rows: readonly T[]
+  /** 按顺序排列的稳定列键，靠前的列键构成上级分组边界。 */
+  columns: readonly string[]
+  /** 可视列偏移量，例如前置选择列。 */
+  columnOffset?: number
+  /** 防止子列跨越已变化的父列进行合并。 */
+  hierarchical?: boolean
+  /** 默认不合并空值，因为空值通常不构成有效业务分组。 */
+  mergeEmpty?: boolean
+  /** 将稳定列键解析为当前可视列，隐藏列键返回 undefined。 */
+  resolveColumn?: (key: string, index: number) => number | undefined
+}
+
+const isEmptyMergeValue = (value: unknown) =>
+  value === undefined || value === null || value === ''
+
+/**
+ * 在不导入 Handsontable 的情况下构建兼容的合并区域。
+ * 仅返回至少包含两行的区域。
+ */
+export const buildTableAutoMergeCells = <T extends TableRow>({
+  rows,
+  columns,
+  columnOffset = 0,
+  hierarchical = true,
+  mergeEmpty = false,
+  resolveColumn = (_key, index) => index,
+}: BuildTableAutoMergeOptions<T>): TableMergeCellRange[] => {
+  const result: TableMergeCellRange[] = []
+  // 每个相邻行边界只比较一次列前缀。第 n 列可继续合并，当且仅当共同前缀长度 > n。
+  // 这样层级合并从 rows × columns² 降为 rows × columns。
+  const commonPrefixByBoundary = hierarchical
+    ? Array.from({ length: rows.length }, (_, rowIndex) => {
+        if (rowIndex === 0) return 0
+        const previous = rows[rowIndex - 1]
+        const current = rows[rowIndex]
+        if (!previous || !current) return 0
+        let prefix = 0
+        while (
+          prefix < columns.length &&
+          Object.is(
+            getTableRowValue(previous, columns[prefix]!),
+            getTableRowValue(current, columns[prefix]!)
+          )
+        ) {
+          prefix += 1
+        }
+        return prefix
+      })
+    : []
+
+  columns.forEach((key, keyIndex) => {
+    const resolvedColumn = resolveColumn(key, keyIndex)
+    if (resolvedColumn === undefined || resolvedColumn < 0) return
+    let start = 0
+
+    const appendRange = (end: number) => {
+      const rowspan = end - start
+      if (rowspan < 2) return
+      const startRow = rows[start]
+      const value = startRow ? getTableRowValue(startRow, key) : undefined
+      if (!mergeEmpty && isEmptyMergeValue(value)) return
+      result.push({
+        row: start,
+        col: resolvedColumn + columnOffset,
+        rowspan,
+        colspan: 1,
+      })
+    }
+
+    for (let rowIndex = 1; rowIndex <= rows.length; rowIndex += 1) {
+      const previous = rows[rowIndex - 1]
+      const current = rows[rowIndex]
+      const continues =
+        current !== undefined &&
+        previous !== undefined &&
+        Object.is(
+          getTableRowValue(previous, key),
+          getTableRowValue(current, key)
+        ) &&
+        (!hierarchical || (commonPrefixByBoundary[rowIndex] ?? 0) > keyIndex)
+      if (continues) continue
+      appendRange(rowIndex)
+      start = rowIndex
+    }
+  })
+
+  return result
+}