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

package/template/src/components/AppTable/engine/table/controller/tableGridHost.ts

@@ -0,0 +1,324 @@
+import type Handsontable from 'handsontable'
+import { getTableRowValue } from '../../shared/row'
+import { claimTableKey } from '../../shared/tableKey'
+import type { TableRow } from '../../shared/types'
+import { TABLE_CHANGE_SOURCE } from '../editing'
+import {
+  createHandsontable,
+  type GridSettings,
+  type TableRuntimeOptions,
+} from '../grid'
+import { createTableLayoutScheduler } from '../layout/layoutScheduler'
+import type { TableDataProjection } from './types'
+
+interface TableGridHostOptions<T extends TableRow> {
+  tableKey: string
+  runtime?: TableRuntimeOptions
+  getRows: () => T[]
+  getDataRevision: () => number
+}
+
+interface TableGridSize {
+  width: number
+  height: number
+}
+
+interface TableLayoutSettlement {
+  lastSize: TableGridSize | null
+  stableSamples: number
+  startedAt: number
+}
+
+const TABLE_LAYOUT_STABLE_SAMPLE_COUNT = 2
+const TABLE_LAYOUT_SETTLE_TIMEOUT_MS = 500
+
+const reportTableLayoutSubscriberError = (error: unknown) => {
+  const reporter = Reflect.get(globalThis, 'reportError')
+  if (typeof reporter === 'function') {
+    Reflect.apply(reporter, globalThis, [error])
+    return
+  }
+  setTimeout(() => {
+    throw error
+  })
+}
+
+/**
+ * Handsontable 宿主边界：只管理第三方实例、tableKey 占用和展示数据投影，不持有
+ * 查询、编辑、选择等业务状态。
+ */
+export class TableGridHost<T extends TableRow> {
+  private hot: Handsontable | null = null
+  private releaseTableKey: (() => void) | null = null
+  private dataProjection: TableDataProjection<T> | null = null
+  private layoutTransitioning = false
+  private layoutSettlement: TableLayoutSettlement | null = null
+  private pendingLayoutRender: Handsontable | null = null
+  private readonly layoutListeners = new Set<() => void>()
+  private readonly layoutScheduler = createTableLayoutScheduler({
+    onFrame: () => {
+      if (this.pendingLayoutRender) {
+        this.finalizeLayout()
+        return
+      }
+      this.settleLayout()
+    },
+  })
+  private readonly guardDimensionRefresh = () =>
+    this.layoutTransitioning ||
+    this.layoutSettlement ||
+    this.pendingLayoutRender
+      ? false
+      : undefined
+  private readonly notifyLayoutChange = () => {
+    this.layoutListeners.forEach((listener) => {
+      try {
+        listener()
+      } catch (error) {
+        reportTableLayoutSubscriberError(error)
+      }
+    })
+  }
+
+  constructor(private readonly options: TableGridHostOptions<T>) {}
+
+  private settleLayout() {
+    const settlement = this.layoutSettlement
+    const hot = this.hot
+    if (
+      !settlement ||
+      this.layoutTransitioning ||
+      !hot ||
+      hot.isDestroyed ||
+      hot.rootWrapperElement?.isConnected === false
+    ) {
+      this.layoutSettlement = null
+      return
+    }
+
+    const { width, height } = hot.rootElement.getBoundingClientRect()
+    const sizeUnchanged =
+      settlement.lastSize?.width === width &&
+      settlement.lastSize.height === height
+    settlement.lastSize = { width, height }
+    settlement.stableSamples = sizeUnchanged ? settlement.stableSamples + 1 : 1
+
+    const timedOut =
+      performance.now() - settlement.startedAt >= TABLE_LAYOUT_SETTLE_TIMEOUT_MS
+    if (
+      settlement.stableSamples < TABLE_LAYOUT_STABLE_SAMPLE_COUNT &&
+      !timedOut
+    ) {
+      this.layoutScheduler.scheduleFrame()
+      return
+    }
+
+    this.layoutSettlement = null
+    hot.refreshDimensions()
+    // refreshDimensions 的首轮渲染先提交最终列宽。AutoRowSize 必须在下一帧基于
+    // 已提交的列宽再次测量，rowHeaders 等 overlay 才能消费同一份最终行高。
+    this.pendingLayoutRender = hot
+    this.layoutScheduler.scheduleFrame()
+  }
+
+  private finalizeLayout() {
+    const hot = this.pendingLayoutRender
+    this.pendingLayoutRender = null
+    if (
+      this.layoutTransitioning ||
+      !hot ||
+      hot !== this.hot ||
+      hot.isDestroyed ||
+      hot.rootWrapperElement?.isConnected === false
+    )
+      return
+    hot.render()
+    this.notifyLayoutChange()
+  }
+
+  /** 返回当前实例；尚未挂载或已经销毁时为 null。 */
+  get instance() {
+    return this.hot
+  }
+
+  /** 判断宿主是否持有一个尚未销毁的 Handsontable 实例。 */
+  get mounted() {
+    return this.hot !== null && !this.hot.isDestroyed
+  }
+
+  /** 创建实例；仍连接文档的挂载必须显式卸载，脱离文档的旧实例允许安全接管。 */
+  mount(container: HTMLElement, settings: GridSettings) {
+    if (this.mounted && this.hot?.rootWrapperElement?.isConnected) {
+      throw new Error(
+        `[TableComponent] Controller "${this.options.tableKey}" is already mounted by another live component.`
+      )
+    }
+    this.unmount()
+    this.releaseTableKey = claimTableKey(this.options.tableKey)
+    try {
+      this.hot = createHandsontable(container, settings, this.options.runtime)
+      // Handsontable 自己会观察 rootElement 尺寸。外层动画及尺寸稳定检测期间在其
+      // 原生刷新钩子处阻断，避免逐帧重绘；真实宽高稳定后再统一刷新一次。
+      this.hot.addHook('beforeRefreshDimensions', this.guardDimensionRefresh)
+      this.hot.addHook('afterColumnResize', this.notifyLayoutChange)
+      this.hot.addHook('afterRowResize', this.notifyLayoutChange)
+      this.notifyLayoutChange()
+      return this.hot
+    } catch (error) {
+      this.releaseTableKey()
+      this.releaseTableKey = null
+      throw error
+    }
+  }
+
+  /**
+   * 只释放当前网格挂载，不销毁 Controller 持有的数据投影和业务状态。
+   * expectedInstance 用于阻止旧组件卸载时误伤同一 Controller 的新挂载。
+   */
+  unmount(expectedInstance?: Handsontable) {
+    if (expectedInstance && this.hot !== expectedInstance) return false
+    this.layoutScheduler.cancel()
+    this.layoutSettlement = null
+    this.pendingLayoutRender = null
+    if (this.hot && !this.hot.isDestroyed) {
+      const rootWrapper = this.hot.rootWrapperElement
+      this.hot.destroy()
+      if (rootWrapper) Reflect.deleteProperty(rootWrapper, '__hotInstance')
+    }
+    const changed = this.hot !== null || this.releaseTableKey !== null
+    this.hot = null
+    this.releaseTableKey?.()
+    this.releaseTableKey = null
+    return changed
+  }
+
+  /** 将增量设置传给当前实例。 */
+  updateSettings(settings: GridSettings) {
+    this.hot?.updateSettings(settings)
+    this.notifyLayoutChange()
+  }
+
+  /** 订阅会改变网格内容尺寸的布局事件；所有框架适配层共享同一事件源。 */
+  subscribeLayout(listener: () => void) {
+    this.layoutListeners.add(listener)
+    let active = true
+    return () => {
+      if (!active) return
+      active = false
+      this.layoutListeners.delete(listener)
+    }
+  }
+
+  /** 注册展示数据投影，并返回只释放本次注册的 disposer。 */
+  setDataProjection(projection: TableDataProjection<T>) {
+    this.dataProjection = projection
+    return () => {
+      if (this.dataProjection === projection) this.dataProjection = null
+    }
+  }
+
+  /**
+   * 在领域状态提交前计算展示投影；返回函数只执行 Handsontable 写入，不再调用投影器。
+   */
+  prepareLoadData(
+    rows = this.options.getRows(),
+    dataRevision = this.options.getDataRevision()
+  ) {
+    const hot = this.hot
+    if (!hot) return () => {}
+    const projected = this.dataProjection?.(rows, dataRevision)
+    const projection = Array.isArray(projected)
+      ? { data: projected }
+      : (projected ?? { data: rows })
+    return () => {
+      hot.batch(() => {
+        if (projection.settings) hot.updateSettings(projection.settings)
+        hot.loadData(projection.data)
+      })
+      this.notifyLayoutChange()
+    }
+  }
+
+  /** 重新计算展示投影，并在一个 HOT batch 内提交设置和数据。 */
+  loadData() {
+    this.prepareLoadData()()
+  }
+
+  /** 按视觉行读取源数据，自动适配排序后的物理行映射。 */
+  getRow(visualRow: number) {
+    const rows = this.options.getRows()
+    if (!this.hot) return rows[visualRow]
+    return this.hot.getSourceDataAtRow(this.hot.toPhysicalRow(visualRow)) as T
+  }
+
+  /** 通过 Handsontable 写入单元格并透传 change source。 */
+  setCell(visualRow: number, key: string, value: unknown, source?: string) {
+    this.hot?.setDataAtRowProp(visualRow, key, value, source)
+  }
+
+  /** 提交框架浮层值，并通过同步数据结果判断 mutation 门禁是否接受。 */
+  commitControlledCell(visualRow: number, key: string, value: unknown) {
+    const previousRow = this.getRow(visualRow)
+    if (!previousRow) return false
+    const previousValue = getTableRowValue(previousRow, key)
+    this.setCell(visualRow, key, value, TABLE_CHANGE_SOURCE.controlledEdit)
+    const nextRow = this.getRow(visualRow)
+    return (
+      nextRow !== undefined &&
+      (Object.is(previousValue, value) ||
+        !Object.is(getTableRowValue(nextRow, key), previousValue))
+    )
+  }
+
+  /** 请求当前实例重绘。 */
+  render() {
+    this.hot?.render()
+  }
+
+  /** 请求当前实例重新测量宿主尺寸。 */
+  refreshDimensions() {
+    if (
+      this.layoutTransitioning ||
+      this.layoutSettlement ||
+      this.pendingLayoutRender
+    )
+      return
+    this.hot?.refreshDimensions()
+  }
+
+  /** 合并外层连续布局变化；尺寸稳定后按最终列宽完成测量、渲染和布局通知。 */
+  setLayoutTransitioning(active: boolean) {
+    if (this.layoutTransitioning === active) return
+    this.layoutTransitioning = active
+    if (active) {
+      this.layoutScheduler.cancel()
+      this.layoutSettlement = null
+      this.pendingLayoutRender = null
+      return
+    }
+    const hot = this.hot
+    if (
+      !hot ||
+      hot.isDestroyed ||
+      hot.rootWrapperElement?.isConnected === false
+    )
+      return
+    this.layoutSettlement = {
+      lastSize: null,
+      stableSamples: 0,
+      startedAt: performance.now(),
+    }
+    this.layoutScheduler.scheduleFrame()
+  }
+
+  /**
+   * 销毁第三方实例并释放 tableKey；额外删除 wrapper 残留的实例引用，避免反向保留
+   * Walkontable 子树。
+   */
+  destroy() {
+    this.unmount()
+    this.layoutTransitioning = false
+    this.dataProjection = null
+    this.layoutListeners.clear()
+  }
+}

package/template/src/components/AppTable/engine/table/controller/tableIdentity.ts

@@ -0,0 +1,68 @@
+import { getTableRowValue } from '../../shared/row'
+import { walkTableRows } from '../../shared/treeRows'
+import type { TableRow } from '../../shared/types'
+import {
+  encodeTableRowKey,
+  isRowKey,
+  type RowKey,
+  type RowKeyResolver,
+} from '../editing'
+
+/** 使用统一语义解析行身份；所有有状态领域都复用这一实现。 */
+export const resolveTableRowKey = <T extends TableRow>(
+  row: T,
+  rowKey: RowKeyResolver<T>
+): RowKey => {
+  const value =
+    typeof rowKey === 'function' ? rowKey(row) : getTableRowValue(row, rowKey)
+  if (!isRowKey(value)) {
+    throw new Error('[TableComponent] Every stateful row requires a rowKey.')
+  }
+  return value
+}
+
+/**
+ * 选择、编辑和校验必须共享同一个身份解析器；函数解析器要求复用同一函数引用，避免
+ * 新数据进入后才暴露出各领域对同一行计算出不同 key。
+ */
+export const resolveCanonicalTableRowKey = <T extends TableRow>(
+  resolvers: ReadonlyArray<RowKeyResolver<T> | null | undefined>
+) => {
+  const configured = resolvers.filter(
+    (resolver): resolver is RowKeyResolver<T> => resolver != null
+  )
+  const canonical = configured[0] ?? null
+  if (
+    canonical &&
+    configured.some((resolver) => !Object.is(resolver, canonical))
+  ) {
+    throw new Error(
+      '[TableComponent] editing, selection and validation must share one canonical rowKey resolver.'
+    )
+  }
+  return canonical
+}
+
+/**
+ * 一次遍历验证父子行全树身份并返回与树前序一致的 key，供编辑和选择共享，避免重复
+ * 执行业务 rowKey resolver。
+ */
+export const assertTableRowIdentity = <T extends TableRow>(
+  rows: readonly T[],
+  rowKey: RowKeyResolver<T>
+) => {
+  const seen = new Set<string>()
+  const keys: RowKey[] = []
+  walkTableRows(rows, ({ row }) => {
+    const value = resolveTableRowKey(row, rowKey)
+    const encoded = encodeTableRowKey(value)
+    if (seen.has(encoded)) {
+      throw new Error(
+        `[TableComponent] Duplicate rowKey "${String(value)}" in loaded rows.`
+      )
+    }
+    seen.add(encoded)
+    keys.push(value)
+  })
+  return keys
+}

package/template/src/components/AppTable/engine/table/controller/tableMutationPipeline.ts

@@ -0,0 +1,79 @@
+import type { CellChange } from 'handsontable'
+import { getTableRowValue, type TableRow } from '../../shared'
+import {
+  processTableMutation,
+  type TableMutationBatchResult,
+  type TableMutationColumn,
+  type TableMutationRejected,
+} from '../editing/mutation'
+
+/** 统一处理 edit、paste、autofill 和 API 输入的解析、准入与派生字段。 */
+export class TableMutationPipeline<T extends TableRow> {
+  private columns = new Map<string, TableMutationColumn<T>>()
+
+  /** 按字段 key 重建可变更列索引。 */
+  setColumns(columns?: readonly TableMutationColumn<T>[]) {
+    this.columns = new Map(
+      columns?.map((column) => [String(column.prop), column]) ?? []
+    )
+  }
+
+  /**
+   * 处理一个 HOT change batch；拒绝项原位改为 null，派生字段追加到同一批次，确保
+   * 最终只形成一个撤销事务。
+   */
+  process(
+    changes: Array<CellChange | null>,
+    getRow: (visualRow: number) => T | undefined,
+    rawSource = 'edit'
+  ): TableMutationBatchResult<T> {
+    const accepted: TableMutationBatchResult<T>['accepted'] = []
+    const rejected: TableMutationRejected<T>[] = []
+    const scheduledKeys = new Set(
+      changes.flatMap((change) =>
+        change &&
+        (typeof change[1] === 'string' || typeof change[1] === 'number')
+          ? [`${change[0]}:${String(change[1])}`]
+          : []
+      )
+    )
+
+    for (let index = 0; index < changes.length; index += 1) {
+      const change = changes[index]
+      if (!change) continue
+      const [visualRow, prop, oldValue, newValue] = change
+      if (typeof prop !== 'string' && typeof prop !== 'number') continue
+      const row = getRow(visualRow)
+      if (!row) continue
+      const key = String(prop)
+      const result = processTableMutation(
+        { row, rowIndex: visualRow, prop: key, oldValue, newValue, rawSource },
+        this.columns.get(key)
+      )
+      if (result.accepted !== true) {
+        changes[index] = null
+        rejected.push(result)
+        continue
+      }
+
+      change[3] = result.value
+      accepted.push(result)
+      Object.entries(result.derivedChanges).forEach(
+        ([derivedProp, derivedValue]) => {
+          if (derivedProp === key) return
+          const identity = `${visualRow}:${derivedProp}`
+          if (scheduledKeys.has(identity)) return
+          scheduledKeys.add(identity)
+          changes.push([
+            visualRow,
+            derivedProp,
+            getTableRowValue(row, derivedProp),
+            derivedValue,
+          ])
+        }
+      )
+    }
+
+    return { accepted, rejected }
+  }
+}

package/template/src/components/AppTable/engine/table/controller/tableQueryCoordinator.ts

@@ -0,0 +1,187 @@
+import {
+  createTableQueryIdentity,
+  createTableQueryParamsSnapshot,
+} from '../../search/query'
+import {
+  createRemoteQueryRunner,
+  type RemoteQueryOutcome,
+} from '../../search/remoteQuery'
+import type { TableQuery, TableQueryParams } from '../../search/types'
+import type { TableRow } from '../../shared'
+import { TableQueryIncompleteError, TableQueryResultLimitError } from './errors'
+import type { TableQueryExecutionOptions } from './types'
+
+interface TableQueryCoordinatorContext<T extends TableRow> {
+  tableKey: string
+  getRows: () => T[]
+  getTotal: () => number
+  guardReload: () => void
+  applyResult: (
+    rows: T[],
+    total: number,
+    params: TableQueryParams,
+    queryIdentity: string
+  ) => void
+  applyLocalResult: (params: TableQueryParams, queryIdentity: string) => void
+  commitState: (commitPreparedState: () => void) => void
+  setError: (error: unknown) => void
+  notify: () => void
+}
+
+/** 远程查询协调器：管理请求竞态、查询快照、限制校验和 loading 状态。 */
+export class TableQueryCoordinator<T extends TableRow> {
+  private runner: ReturnType<typeof createRemoteQueryRunner<T>> | null = null
+  private querySource: TableQuery<T> | undefined
+  private lastParams: TableQueryParams | undefined
+  private lastIdentity: string | undefined
+  private running = false
+
+  constructor(private readonly context: TableQueryCoordinatorContext<T>) {}
+
+  /** 最近一次成功应用的查询参数。 */
+  get params() {
+    return this.lastParams
+      ? createTableQueryParamsSnapshot(this.lastParams)
+      : undefined
+  }
+
+  /** 最近一次成功应用的查询结果集身份，不包含分页位置。 */
+  get identity() {
+    return this.lastIdentity
+  }
+
+  /** 当前是否正在执行查询。 */
+  get loading() {
+    return this.running
+  }
+
+  /** 当前远程请求序号；没有远程查询时为 0。 */
+  get requestId() {
+    return this.runner?.currentRequestId ?? 0
+  }
+
+  /** 是否配置了远程查询函数。 */
+  get remote() {
+    return Boolean(this.runner)
+  }
+
+  /** 仅由 Controller 的同步事务调用，提交已通过全部预检的查询参数。 */
+  commitAppliedParams(params: TableQueryParams, queryIdentity: string) {
+    this.lastParams = params
+    this.lastIdentity = queryIdentity
+  }
+
+  /**
+   * 构造无副作用的查询 provider 切换提交；调用方可与数据替换组合成更大的事务。
+   */
+  prepareQuery(query?: TableQuery<T>) {
+    if (this.querySource === query) return () => {}
+    this.context.guardReload()
+    const nextRunner = query
+      ? createRemoteQueryRunner(query, { tableKey: this.context.tableKey })
+      : null
+    return () => {
+      this.runner?.cancel()
+      this.querySource = query
+      this.lastParams = undefined
+      this.lastIdentity = undefined
+      this.runner = nextRunner
+      this.running = false
+      this.context.setError(null)
+    }
+  }
+
+  /** 热切换查询函数，取消旧请求并清理旧查询上下文。 */
+  setQuery(query?: TableQuery<T>) {
+    const commit = this.prepareQuery(query)
+    this.context.commitState(commit)
+  }
+
+  /** 执行查询；只允许最后一个请求写入状态和数据。 */
+  async run(
+    params: TableQueryParams,
+    options: TableQueryExecutionOptions = {}
+  ): Promise<RemoteQueryOutcome<T>> {
+    this.context.guardReload()
+    const paramsSnapshot = createTableQueryParamsSnapshot(params)
+    const queryIdentity = createTableQueryIdentity(paramsSnapshot)
+    const runner = this.runner
+    if (!runner) {
+      this.context.applyLocalResult(paramsSnapshot, queryIdentity)
+      const rows = this.context.getRows()
+      return {
+        status: 'applied',
+        requestId: 0,
+        result: { list: [...rows], total: this.context.getTotal() },
+      }
+    }
+
+    const requestId = runner.currentRequestId + 1
+    this.running = true
+    this.context.setError(null)
+    this.context.notify()
+
+    try {
+      // provider 获得独立副本；即使业务代码原地修改请求，也不会污染最终应用的快照。
+      const outcome = await runner.run(
+        createTableQueryParamsSnapshot(paramsSnapshot)
+      )
+      if (outcome.status === 'applied' && outcome.result) {
+        const receivedRows = outcome.result.list?.length ?? 0
+        const resultTotal = Math.max(0, outcome.result.total ?? receivedRows)
+        if (
+          options.maxRows !== undefined &&
+          (resultTotal > options.maxRows || receivedRows > options.maxRows)
+        ) {
+          throw new TableQueryResultLimitError(
+            options.maxRows,
+            resultTotal,
+            receivedRows
+          )
+        }
+        if (options.requireComplete && receivedRows !== resultTotal) {
+          throw new TableQueryIncompleteError(resultTotal, receivedRows)
+        }
+        // 请求期间仍允许用户编辑，因此必须在同步提交区再次校验。Controller 只接收
+        // 声明式查询身份，并自行提交 rows、total、params 和选择状态，不执行外部闭包。
+        this.context.guardReload()
+        this.context.applyResult(
+          outcome.result.list ?? [],
+          resultTotal,
+          paramsSnapshot,
+          queryIdentity
+        )
+      }
+      return outcome
+    } catch (error) {
+      if (this.runner === runner && runner.currentRequestId === requestId) {
+        this.context.setError(error)
+      }
+      throw error
+    } finally {
+      if (this.runner === runner && runner.currentRequestId === requestId) {
+        this.running = false
+        this.context.notify()
+      }
+    }
+  }
+
+  /** 取消当前请求并保留 query provider，供更晚的用户意图重新发起查询。 */
+  cancel() {
+    if (!this.runner) return
+    const wasRunning = this.running
+    this.runner.cancel()
+    this.running = false
+    if (wasRunning) this.context.notify()
+  }
+
+  /** 取消进行中的查询并清理运行状态。 */
+  destroy() {
+    this.runner?.cancel()
+    this.runner = null
+    this.querySource = undefined
+    this.lastParams = undefined
+    this.lastIdentity = undefined
+    this.running = false
+  }
+}