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

package/template/src/components/AppTable/engine/table/hooks/fixedEndHooks.ts

@@ -0,0 +1,44 @@
+import type { TableGridHooks } from './gridHooks'
+
+interface CreateTableFixedEndHooksOptions {
+  applyFixedEndElement: (
+    element: HTMLElement,
+    column: number,
+    enabled?: boolean
+  ) => void
+  scheduleFixedEndShadow: (renderOverlay?: boolean) => void
+}
+
+/** 创建固定尾列所需的 Handsontable hooks；不依赖任何 UI 框架。 */
+export const createTableFixedEndHooks = (
+  options: CreateTableFixedEndHooksOptions
+): TableGridHooks => {
+  let horizontalScrollPending = false
+  return {
+    // 横向滚动只改变阴影可见性；afterViewRender 不得把它升级成完整 overlay 测量。
+    afterScrollHorizontally: () => {
+      horizontalScrollPending = true
+      options.scheduleFixedEndShadow(false)
+    },
+    afterScrollVertically: () => {
+      horizontalScrollPending = false
+      options.scheduleFixedEndShadow()
+    },
+    afterViewRender: () => {
+      options.scheduleFixedEndShadow(!horizontalScrollPending)
+      horizontalScrollPending = false
+    },
+    afterRenderer: (td, _row, column, _prop, _value, cellProperties) => {
+      const { tableError } = cellProperties
+      if (tableError !== undefined) {
+        td.title =
+          typeof tableError === 'string'
+            ? tableError
+            : tableError instanceof Error
+              ? tableError.message
+              : String(tableError)
+      } else if (td.hasAttribute('title')) td.removeAttribute('title')
+      options.applyFixedEndElement(td, column)
+    },
+  }
+}

package/template/src/components/AppTable/engine/table/hooks/gridHooks.ts

@@ -0,0 +1,108 @@
+import type { GridSettings } from 'handsontable'
+
+/** 组件会组合并拥有明确执行顺序的 Handsontable 设置与 Hook。 */
+type TableManagedGridSettingName =
+  | 'cells'
+  | 'afterChange'
+  | 'afterColumnFreeze'
+  | 'afterColumnMove'
+  | 'afterColumnResize'
+  | 'afterColumnUnfreeze'
+  | 'afterDeselect'
+  | 'afterDropdownMenuShow'
+  | 'afterFilter'
+  | 'afterGetColHeader'
+  | 'afterOnCellMouseOut'
+  | 'afterOnCellMouseOver'
+  | 'afterOnCellMouseUp'
+  | 'afterRenderer'
+  | 'afterScrollHorizontally'
+  | 'afterScrollVertically'
+  | 'afterSelectionEnd'
+  | 'afterViewRender'
+  | 'beforeAutofill'
+  | 'beforeChange'
+  | 'beforeColumnMove'
+  | 'beforeColumnSort'
+  | 'beforeCopy'
+  | 'beforeCreateRow'
+  | 'beforePaste'
+
+/**
+ * Handsontable 官方 hook 名称到回调签名的映射。
+ *
+ * v18 运行时允许 beforeAutofill 返回 false 取消填充，但其声明文件遗漏了该返回值；
+ * 组件在统一 hook 边界补全真实合同，业务钩子不再使用 `false as never` 绕过检查。
+ */
+export type TableGridHooks = Omit<
+  Partial<Pick<GridSettings, TableManagedGridSettingName>>,
+  'beforeAutofill'
+> & {
+  beforeAutofill?: (
+    selectionData: unknown[][],
+    sourceRange: unknown,
+    targetRange: unknown,
+    direction: 'up' | 'down' | 'left' | 'right'
+  ) => unknown[][] | void | false
+}
+
+/** hook 组合器的函数约束；具体签名由传入的 Handsontable Events 回调推断。 */
+export type TableGridHook = (this: unknown, ...args: never[]) => unknown
+
+export interface ComposeTableGridHookOptions {
+  /** 默认先执行内部一致性逻辑，除非需要保留调用方优先的既有合同。 */
+  order?: 'internal-first' | 'consumer-first'
+  /** Handsontable 的 before 类钩子使用 false 作为取消信号。 */
+  stopOnFalse?: boolean
+}
+
+const composedHookCache = new WeakMap<
+  TableGridHook,
+  WeakMap<TableGridHook, Map<string, TableGridHook>>
+>()
+
+/** 组合 Handsontable 公共钩子，不依赖适配器的闭包状态。 */
+export const composeTableGridHook = <THook extends TableGridHook>(
+  internal: THook | undefined,
+  consumer: THook | undefined,
+  options: ComposeTableGridHookOptions = {}
+): THook | undefined => {
+  if (!internal) return consumer
+  if (!consumer) return internal
+  const order = options.order ?? 'internal-first'
+  const stopOnFalse = options.stopOnFalse ?? true
+  const cacheKey = `${order}:${String(stopOnFalse)}`
+  let consumerCache = composedHookCache.get(internal)
+  if (!consumerCache) {
+    consumerCache = new WeakMap()
+    composedHookCache.set(internal, consumerCache)
+  }
+  let policyCache = consumerCache.get(consumer)
+  if (!policyCache) {
+    policyCache = new Map()
+    consumerCache.set(consumer, policyCache)
+  }
+  const cached = policyCache.get(cacheKey)
+  if (cached) return cached as THook
+  const hooks =
+    order === 'consumer-first' ? [consumer, internal] : [internal, consumer]
+
+  const composed = function composedTableGridHook(
+    this: unknown,
+    ...args: unknown[]
+  ) {
+    let result: unknown
+    for (const hook of hooks) {
+      const callable = hook as unknown as (
+        this: unknown,
+        ...args: unknown[]
+      ) => unknown
+      const next = callable.apply(this, args)
+      if (next !== undefined) result = next
+      if (stopOnFalse && next === false) return false
+    }
+    return result
+  } as unknown as THook
+  policyCache.set(cacheKey, composed)
+  return composed
+}

package/template/src/components/AppTable/engine/table/hooks/headerHooks.ts

@@ -0,0 +1,103 @@
+import { isTableActionColumn, type TableColumn } from '../../columns'
+import {
+  renderTableSelectionHeader,
+  type RenderTableSelectionHeaderOptions,
+} from '../../selection'
+import type { TableEngineMessages } from '../../shared/messages'
+import type { TableRow } from '../../shared/types'
+import type { TableNestedHeadersResult } from '../layout'
+import type { TableGridHooks } from './gridHooks'
+
+interface CreateTableHeaderHooksOptions<T extends TableRow> {
+  messages: TableEngineMessages
+  getNestedHeaders: () => TableNestedHeadersResult | undefined
+  getSelectable: () => boolean
+  getColumns: () => readonly TableColumn<T>[]
+  getRows: () => readonly T[]
+  getColumnProperty: (visualColumn: number) => string | number | undefined
+  applyFixedEndElement: (
+    element: HTMLElement,
+    column: number,
+    enabled?: boolean
+  ) => void
+  getSelectionOptions: () => Pick<
+    RenderTableSelectionHeaderOptions<T>,
+    'showSelectAll' | 'multiple'
+  >
+  canSelect: (row: T) => boolean
+  isSelected: (row: T) => boolean
+  selectPage: (rows: readonly T[], selected: boolean) => void
+  onSelectionChange: () => void
+  getSelectionState: () =>
+    | RenderTableSelectionHeaderOptions<T>['state']
+    | undefined
+}
+
+/**
+ * 同步普通数据列表头的 Handsontable DOM 约束。
+ *
+ * 操作列不允许打开列菜单，必填标记由 engine 幂等维护；React 层无需了解 HOT 的
+ * `changeType`、`colHeader` 等 DOM 细节。
+ */
+const syncTableColumnHeader = <T extends TableRow>(
+  th: HTMLTableCellElement,
+  definition: TableColumn<T> | undefined,
+  messages: TableEngineMessages
+) => {
+  const isActionHeader = definition ? isTableActionColumn(definition) : false
+  th.classList.toggle('table-component__action-header', isActionHeader)
+  if (isActionHeader) th.querySelector('button.changeType')?.remove()
+
+  const host = th.querySelector('.colHeader') ?? th
+  host.querySelector('.table-component__required-marker')?.remove()
+  if (!host.textContent?.trim() && definition?.label) {
+    host.textContent = definition.label
+  }
+  const required = definition?.required === true
+  th.classList.toggle('table-component__required-header', required)
+  if (!required) return
+
+  const marker = th.ownerDocument.createElement('span')
+  marker.className = 'table-component__required-marker'
+  marker.textContent = '*'
+  marker.setAttribute('aria-label', messages.strRequired)
+  host.append(marker)
+}
+
+/** 创建表头选择、尾列样式和列菜单约束所需的 Handsontable hooks。 */
+export const createTableHeaderHooks = <T extends TableRow>(
+  options: CreateTableHeaderHooksOptions<T>
+): TableGridHooks => ({
+  afterGetColHeader: (column, th, headerLevel) => {
+    const bottomHeaderLevel =
+      (options.getNestedHeaders()?.nestedHeaders.length ?? 1) - 1
+    options.applyFixedEndElement(th, column, headerLevel === bottomHeaderLevel)
+    const isSelectionHeader =
+      options.getSelectable() &&
+      column === 0 &&
+      headerLevel === bottomHeaderLevel
+    th.classList.toggle('table-component__selection-header', isSelectionHeader)
+    if (isSelectionHeader) {
+      const selection = options.getSelectionOptions()
+      renderTableSelectionHeader({
+        th,
+        rows: options.getRows(),
+        showSelectAll: selection.showSelectAll,
+        multiple: selection.multiple,
+        canSelect: options.canSelect,
+        isSelected: options.isSelected,
+        selectPage: options.selectPage,
+        onChange: options.onSelectionChange,
+        ariaLabel: options.messages.strSelectCurrentPage,
+        state: options.getSelectionState(),
+      })
+      return
+    }
+    if (column < 0 || headerLevel !== bottomHeaderLevel) return
+    const prop = options.getColumnProperty(column)
+    const definition = options
+      .getColumns()
+      .find((item) => String(item.key) === String(prop))
+    syncTableColumnHeader(th, definition, options.messages)
+  },
+})

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

@@ -0,0 +1,3 @@
+export * from './gridHooks'
+export * from './fixedEndHooks'
+export * from './headerHooks'

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

@@ -0,0 +1,6 @@
+export * from './controller'
+export * from './editing'
+export * from './clipboard'
+export * from './layout'
+export * from './grid'
+export * from './hooks'

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

@@ -0,0 +1,2 @@
+/** 判断横向滚动是否到达边界时允许的亚像素误差。 */
+export const TABLE_SCROLL_BOUNDARY_EPSILON = 1

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

@@ -0,0 +1,89 @@
+const TABLE_DROPDOWN_MENU_VIEWPORT_GAP = 8
+
+interface ResolveTableDropdownMenuLayoutOptions {
+  viewportHeight: number
+  scrollTop: number
+  menuTop: number
+  menuHeight: number
+  holderHeight: number
+  gap?: number
+}
+
+interface TableDropdownMenuLayout {
+  maxHolderHeight: number
+  top: number
+}
+
+/**
+ * 将列菜单限制在浏览器可视区域内。
+ *
+ * Handsontable 只负责判断菜单放在锚点上方还是下方，不会压缩一个本身已经高于
+ * 可用空间的菜单。这里先扣除菜单边框、内边距等固定高度，再计算内容区最大高度，
+ * 最后将整个浮层位置夹在视口上下边界之间。
+ */
+const resolveTableDropdownMenuLayout = ({
+  viewportHeight,
+  scrollTop,
+  menuTop,
+  menuHeight,
+  holderHeight,
+  gap = TABLE_DROPDOWN_MENU_VIEWPORT_GAP,
+}: ResolveTableDropdownMenuLayoutOptions): TableDropdownMenuLayout => {
+  const normalizedViewportHeight = Math.max(0, viewportHeight)
+  const normalizedGap = Math.max(0, gap)
+  const chromeHeight = Math.max(0, menuHeight - holderHeight)
+  const maxHolderHeight = Math.max(
+    0,
+    normalizedViewportHeight - normalizedGap * 2 - chromeHeight
+  )
+  const fittedMenuHeight = Math.min(menuHeight, maxHolderHeight + chromeHeight)
+  const minimumTop = normalizedGap
+  const maximumTop = Math.max(
+    minimumTop,
+    normalizedViewportHeight - normalizedGap - fittedMenuHeight
+  )
+  const relativeTop = Math.min(
+    Math.max(menuTop - scrollTop, minimumTop),
+    maximumTop
+  )
+
+  return {
+    maxHolderHeight,
+    top: scrollTop + relativeTop,
+  }
+}
+
+interface TableDropdownMenuInstance {
+  menu?: { container?: HTMLElement } | null
+}
+
+/** 对 Handsontable body portal 中的列菜单应用视口高度和位置。 */
+export const fitTableDropdownMenuToViewport = (
+  instance: TableDropdownMenuInstance
+) => {
+  const rootWindow = instance.menu?.container?.ownerDocument.defaultView
+  if (!rootWindow) return
+
+  // Handsontable 的 afterDropdownMenuShow 早于最终 setPosition，延后一拍才能避免
+  // 组件内部定位覆盖这里计算出的视口边界。
+  rootWindow.queueMicrotask(() => {
+    const container = instance.menu?.container
+    const holder = container?.querySelector<HTMLElement>(
+      ':scope > .ht_master > .wtHolder'
+    )
+    if (!container || !holder || container.style.display === 'none') return
+
+    // 菜单实例会被重复使用；测量前清除上一次打开时留下的视口上限。
+    holder.style.removeProperty('max-height')
+    const layout = resolveTableDropdownMenuLayout({
+      viewportHeight: rootWindow.innerHeight,
+      scrollTop: rootWindow.scrollY,
+      menuTop: container.getBoundingClientRect().top + rootWindow.scrollY,
+      menuHeight: container.offsetHeight,
+      holderHeight: holder.offsetHeight,
+    })
+
+    holder.style.maxHeight = `${layout.maxHolderHeight}px`
+    container.style.top = `${layout.top}px`
+  })
+}

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

@@ -0,0 +1,44 @@
+import { isTableActionColumn, type TableColumn } from '../../columns/column'
+import type { TableRow } from '../../shared/types'
+
+interface ResolveTableFixedColumnsEndOptions<T extends TableRow = TableRow> {
+  columns: readonly TableColumn<T>[]
+  fixedColumnsEnd?: number
+  autoFreezeEndActions?: boolean
+}
+
+/** 从表格逻辑结束侧向前统计连续的操作列。 */
+const countTableEndActionColumns = <T extends TableRow>(
+  columns: readonly TableColumn<T>[]
+) => {
+  let count = 0
+  for (let index = columns.length - 1; index >= 0; index--) {
+    const column = columns[index]
+    if (!isTableActionColumn(column)) break
+    count++
+  }
+  return count
+}
+
+const normalizeTableFixedColumnsEnd = (
+  value: number | undefined,
+  totalColumns: number
+) =>
+  Math.min(
+    Math.max(0, Math.trunc(Number(totalColumns) || 0)),
+    Math.max(0, Math.trunc(Number(value) || 0))
+  )
+
+/** 显式 fixedColumnsEnd 优先，否则按尾部连续操作列约定自动计算。 */
+export const resolveTableFixedColumnsEnd = <T extends TableRow>({
+  columns,
+  fixedColumnsEnd,
+  autoFreezeEndActions = true,
+}: ResolveTableFixedColumnsEndOptions<T>) => {
+  let resolved = fixedColumnsEnd
+  if (resolved === undefined) {
+    // 仅在未配置时启用自动冻结，显式传入 0 必须保留“关闭固定列”的语义。
+    resolved = autoFreezeEndActions ? countTableEndActionColumns(columns) : 0
+  }
+  return normalizeTableFixedColumnsEnd(resolved, columns.length)
+}

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

@@ -0,0 +1,90 @@
+import { TABLE_SCROLL_BOUNDARY_EPSILON } from './constants'
+import { readHandsontableFixedEndDom } from './handsontableDomAdapter'
+
+export const TABLE_FIXED_END_CLASS = 'table-component__fixed-end'
+export const TABLE_FIXED_END_BOUNDARY_CLASS =
+  'table-component__fixed-end-boundary'
+
+interface TableFixedEndShadowSnapshot {
+  /** 阴影相对表格宿主的纵向起点，确保覆盖表头。 */
+  blockStart?: number
+  /** 阴影实际高度；数据不足一屏时止于最后一行。 */
+  height?: number
+  position?: number
+  rtl: boolean
+  visible: boolean
+}
+
+interface ResolveTableFixedEndShadowOptions {
+  host?: HTMLElement
+  fixedColumnsEnd: number
+  boundaryClass?: string
+  getDirection?: (element: HTMLElement) => string
+}
+
+/** 仅读取滚动边界，供横向滚动帧复用，避免重复测量 DOMRect。 */
+export const isTableFixedEndShadowVisible = (holder?: HTMLElement | null) => {
+  if (!holder) return false
+  const maximumScroll = Math.max(0, holder.scrollWidth - holder.clientWidth)
+  return (
+    maximumScroll > TABLE_SCROLL_BOUNDARY_EPSILON &&
+    Math.abs(holder.scrollLeft) < maximumScroll - TABLE_SCROLL_BOUNDARY_EPSILON
+  )
+}
+
+/**
+ * 通过公开 DOM 几何信息计算整条固定列阴影的位置和可见性。
+ * 横向滚动到最右端后 `visible=false`，适配层应隐藏阴影。
+ */
+export const resolveTableFixedEndShadow = ({
+  host,
+  fixedColumnsEnd,
+  boundaryClass = TABLE_FIXED_END_BOUNDARY_CLASS,
+  getDirection = (element) => getComputedStyle(element).direction,
+}: ResolveTableFixedEndShadowOptions): TableFixedEndShadowSnapshot => {
+  const hidden: TableFixedEndShadowSnapshot = { rtl: false, visible: false }
+  if (!host || fixedColumnsEnd === 0) return hidden
+  const boundary = host.querySelector<HTMLElement>(
+    `.table-component__fixed-end-overlay .${boundaryClass}`
+  )
+  if (!boundary) return hidden
+  const { holder, headerClone, masterRows, bottomRows } =
+    readHandsontableFixedEndDom(host)
+  const rtl = getDirection(host) === 'rtl'
+  const visible = isTableFixedEndShadowVisible(holder)
+  const hostRect = host.getBoundingClientRect()
+  const boundaryRect = boundary.getBoundingClientRect()
+  const holderRect = holder?.getBoundingClientRect()
+  let blockStart: number | undefined
+  let height: number | undefined
+  if (holder && holderRect) {
+    const start = Math.max(hostRect.top, holderRect.top)
+    const hasVerticalOverflow =
+      holder.scrollHeight - holder.clientHeight > TABLE_SCROLL_BOUNDARY_EPSILON
+    // Handsontable 按视觉顺序维护 master/bottom clone 行。内容底部只可能来自表头、
+    // 最后一条 master 行或最后一条 bottom clone 行，无需在每次布局同步时读取所有行。
+    const renderedContentBottom = [
+      headerClone?.getBoundingClientRect().bottom,
+      masterRows.at(-1)?.getBoundingClientRect().bottom,
+      bottomRows.at(-1)?.getBoundingClientRect().bottom,
+    ].reduce<number>(
+      (maximum, bottom) =>
+        bottom === undefined ? maximum : Math.max(maximum, bottom),
+      start
+    )
+    const end = hasVerticalOverflow
+      ? holderRect.bottom
+      : Math.min(holderRect.bottom, renderedContentBottom)
+    blockStart = Math.round(start - hostRect.top)
+    height = Math.max(0, Math.round(end - start))
+  }
+  return {
+    blockStart,
+    height,
+    position: Math.round(
+      (rtl ? boundaryRect.right : boundaryRect.left) - hostRect.left
+    ),
+    rtl,
+    visible,
+  }
+}

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

@@ -0,0 +1,104 @@
+const restoreElement = (element: HTMLElement) => {
+  element.inert = false
+  element.removeAttribute('aria-hidden')
+}
+
+const hideElement = (element: HTMLElement) => {
+  element.inert = true
+  element.setAttribute('aria-hidden', 'true')
+}
+
+export interface FixedEndSemanticReconciler {
+  readonly active: boolean
+  setActive(active: boolean): void
+  updateElement(element: HTMLElement, duplicate: boolean): void
+  reconcile(
+    overlayRoot: HTMLElement | undefined,
+    roots: readonly Element[],
+    columns: readonly number[]
+  ): void
+  /** 释放 Handsontable 虚拟滚动已经拆除的单元格引用。 */
+  pruneDisconnected(): void
+  restoreAll(): void
+}
+
+/**
+ * 固定尾列唯一的辅助技术语义协调器。它同时接收 Handsontable renderer 的增量
+ * 单元格和 overlay 的全量可见集合，每轮都恢复退出集合的 DOM，避免虚拟复用后
+ * 残留 inert，也避免横向滚动后主表与 overlay 出现双份按钮。
+ */
+export const createFixedEndSemanticReconciler =
+  (): FixedEndSemanticReconciler => {
+    let enabled = false
+    let hidden = new Set<HTMLElement>()
+
+    const restoreAll = () => {
+      hidden.forEach(restoreElement)
+      hidden.clear()
+    }
+
+    const setActive = (active: boolean) => {
+      enabled = active
+      if (!active) restoreAll()
+    }
+
+    const updateElement = (element: HTMLElement, duplicate: boolean) => {
+      if (enabled && duplicate) {
+        // Handsontable renderer 会在复用 TD 时重写属性。即使节点仍在
+        // hidden 集合中，aria-hidden 也可能已被移除，必须每次重申语义。
+        hideElement(element)
+        hidden.add(element)
+        return
+      }
+      // afterRenderer 会覆盖整个可见窗口；只恢复真正从尾列复用到普通列的节点，
+      // 避免对数百个从未隐藏的单元格重复写 inert/aria-hidden。
+      if (hidden.delete(element)) restoreElement(element)
+    }
+
+    const pruneDisconnected = () => {
+      hidden.forEach((element) => {
+        if (!element.isConnected) hidden.delete(element)
+      })
+    }
+
+    const reconcile: FixedEndSemanticReconciler['reconcile'] = (
+      overlayRoot,
+      roots,
+      columns
+    ) => {
+      if (!enabled) {
+        restoreAll()
+        return
+      }
+      const next = new Set<HTMLElement>()
+      roots.forEach((root) => {
+        columns.forEach((column) => {
+          root
+            .querySelectorAll<HTMLElement>(`[aria-colindex="${column + 2}"]`)
+            .forEach((element) => {
+              if (!overlayRoot?.contains(element)) next.add(element)
+            })
+        })
+      })
+      const previous = hidden
+      previous.forEach((element) => {
+        if (!next.has(element)) restoreElement(element)
+      })
+      next.forEach((element) => {
+        // 全量协调同样不能假设已缓存节点仍保留 ARIA 属性。
+        hideElement(element)
+      })
+      hidden = next
+    }
+
+    return {
+      get active() {
+        return enabled
+      },
+      setActive,
+      updateElement,
+      reconcile,
+      pruneDisconnected,
+      restoreAll,
+    }
+  }