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

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

@@ -0,0 +1,106 @@
+import type { VersionConflict } from '../editing/changeSet'
+import type { TableValidationResult } from '../editing/validation'
+
+/** 有未保存修改时禁止整体重载业务数据。 */
+export class TableDirtyReloadError extends Error {
+  readonly code = 'TABLE_DIRTY_RELOAD'
+
+  constructor(readonly tableKey: string) {
+    super(
+      `[TableComponent] Table "${tableKey}" has unsaved changes. Save or discard them before reloading.`
+    )
+    this.name = 'TableDirtyReloadError'
+  }
+}
+
+/** 保存请求在途时禁止改变行树或清空事务，避免服务端结果与本地结构分叉。 */
+class TableSaveInProgressError extends Error {
+  readonly code = 'TABLE_SAVE_IN_PROGRESS'
+
+  constructor(
+    readonly tableKey: string,
+    readonly operation:
+      | 'addRow'
+      | 'removeRows'
+      | 'discardChanges'
+      | 'replaceData'
+      | 'setEditing'
+      | 'reconfigure'
+  ) {
+    super(
+      `[TableComponent] Table "${tableKey}" cannot ${operation} while a save is in progress.`
+    )
+    this.name = 'TableSaveInProgressError'
+  }
+}
+
+/** 统一保护所有会改变行树或清空变更集的命令。 */
+export const assertTableSaveIdle = (
+  savePromise: Promise<unknown> | null,
+  tableKey: string,
+  operation:
+    | 'addRow'
+    | 'removeRows'
+    | 'discardChanges'
+    | 'replaceData'
+    | 'setEditing'
+    | 'reconfigure'
+) => {
+  if (savePromise) throw new TableSaveInProgressError(tableKey, operation)
+}
+
+/** 保存前校验未通过。 */
+export class TableValidationError extends Error {
+  readonly code = 'TABLE_VALIDATION_FAILED'
+
+  constructor(readonly result: TableValidationResult) {
+    super(result.firstIssue?.message ?? 'Table validation failed.')
+    this.name = 'TableValidationError'
+  }
+}
+
+/** 存在尚未解决的乐观锁版本冲突。 */
+export class TableUnresolvedConflictError extends Error {
+  readonly code = 'TABLE_UNRESOLVED_CONFLICT'
+
+  constructor(
+    readonly tableKey: string,
+    readonly conflicts: readonly VersionConflict[]
+  ) {
+    super(
+      `[TableComponent] Table "${tableKey}" has unresolved version conflicts.`
+    )
+    this.name = 'TableUnresolvedConflictError'
+  }
+}
+
+/** 查询结果超过 all-mode 配置的最大行数。 */
+export class TableQueryResultLimitError extends Error {
+  readonly code = 'TABLE_QUERY_RESULT_LIMIT'
+
+  constructor(
+    readonly maxRows: number,
+    readonly total: number,
+    readonly receivedRows: number
+  ) {
+    super(
+      `[TableComponent] Query returned ${total} total rows (${receivedRows} received), exceeding the configured all-row limit of ${maxRows}.`
+    )
+    this.name = 'TableQueryResultLimitError'
+  }
+}
+
+/** all-mode 查询收到被后端截断的不完整数据。 */
+export class TableQueryIncompleteError extends Error {
+  readonly code = 'TABLE_QUERY_INCOMPLETE'
+
+  constructor(
+    readonly total: number,
+    readonly receivedRows: number
+  ) {
+    super(
+      `[TableComponent] All-row query expected ${total} rows but received ${receivedRows}; the backend may have capped pageSize.`
+    )
+    this.name = 'TableQueryIncompleteError'
+  }
+}

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

@@ -0,0 +1,4 @@
+export * from './TableController'
+export * from './errors'
+export * from './tableIdentity'
+export type * from './types'

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

@@ -0,0 +1,33 @@
+/**
+ * 管理“最后一次调用生效”的可取消任务槽。新任务会取消旧任务，只有当前任务可以
+ * 在 finally 中清理对应 loading 状态，避免陈旧 Promise 反向覆盖新请求。
+ */
+export class LatestAbortableTask {
+  private current: AbortController | null = null
+
+  /** 取消旧任务并返回本次调用独占的 AbortController。 */
+  start() {
+    this.cancel()
+    const controller = new AbortController()
+    this.current = controller
+    return controller
+  }
+
+  /** 判断 controller 是否仍是槽内最后启动且未被替换的任务。 */
+  isCurrent(controller: AbortController) {
+    return this.current === controller
+  }
+
+  /** 仅清理匹配的当前任务；返回调用方是否可以结束对应 loading 状态。 */
+  finish(controller: AbortController) {
+    if (!this.isCurrent(controller)) return false
+    this.current = null
+    return true
+  }
+
+  /** 取消并释放当前任务；没有运行中任务时保持幂等。 */
+  cancel() {
+    this.current?.abort()
+    this.current = null
+  }
+}

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

@@ -0,0 +1,60 @@
+import type { TableSelection } from '../../selection'
+import type { TableRow } from '../../shared'
+import type { RowKeyResolver, TableChangeTracker } from '../editing/changeSet'
+import type { TableValidation } from '../editing/validation'
+import { TableDirtyReloadError, assertTableSaveIdle } from './errors'
+import { assertTableRowIdentity } from './tableIdentity'
+
+interface PrepareTableDataReplacementOptions<T extends TableRow> {
+  tableKey: string
+  rows: readonly T[]
+  total?: number
+  savePromise: Promise<unknown> | null
+  dirty: boolean
+  rowKey: RowKeyResolver<T> | null
+  tracker: TableChangeTracker<T> | null
+  selection: TableSelection<T> | null
+  validation: TableValidation<T> | null
+}
+
+/** 已完成行身份、编辑基线和选择映射预检的数据替换提交。 */
+interface PreparedTableDataReplacement<T extends TableRow> {
+  rows: T[]
+  total: number
+  commitDomains: () => void
+}
+
+/**
+ * 一次遍历解析并校验 canonical rowKey，再把同一 key 序列交给编辑和选择预检。
+ * 返回的提交函数不再调用业务 resolver，也不会修改 rows 集合。
+ */
+export const prepareTableDataReplacement = <T extends TableRow>({
+  tableKey,
+  rows,
+  total = rows.length,
+  savePromise,
+  dirty,
+  rowKey,
+  tracker,
+  selection,
+  validation,
+}: PrepareTableDataReplacementOptions<T>): PreparedTableDataReplacement<T> => {
+  assertTableSaveIdle(savePromise, tableKey, 'replaceData')
+  if (dirty) throw new TableDirtyReloadError(tableKey)
+  const nextRows = [...rows]
+  const resolvedKeys = rowKey
+    ? assertTableRowIdentity(nextRows, rowKey)
+    : undefined
+  const commitEditing = tracker?.prepareReset(nextRows, resolvedKeys)
+  const commitSelection = selection?.prepareLoadedRows(nextRows, resolvedKeys)
+
+  return {
+    rows: nextRows,
+    total: Math.max(0, total ?? rows.length),
+    commitDomains: () => {
+      commitEditing?.()
+      commitSelection?.()
+      validation?.reset()
+    },
+  }
+}

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

@@ -0,0 +1,94 @@
+import { createTableSelection, type TableSelection } from '../../selection'
+import type { TableRow } from '../../shared'
+import {
+  createTableChangeTracker,
+  type ChangeSetHandler,
+  type TableChangeTracker,
+} from '../editing/changeSet'
+import {
+  createTableValidation,
+  type TableValidation,
+} from '../editing/validation'
+import {
+  assertTableRowIdentity,
+  resolveCanonicalTableRowKey,
+} from './tableIdentity'
+import { TableMutationPipeline } from './tableMutationPipeline'
+import type { TableControllerConfigurationPatch } from './types'
+
+interface TableDomainConfigurationContext<T extends TableRow> {
+  configuration: TableControllerConfigurationPatch<T>
+  rows: readonly T[]
+  tracker: TableChangeTracker<T> | null
+  selection: TableSelection<T> | null
+  validation: TableValidation<T> | null
+  mutation: TableMutationPipeline<T>
+  commitChanges: ChangeSetHandler<T> | null
+}
+
+/** 已完成全部业务回调和 rowKey 预检、可直接同步交换的领域候选。 */
+export const prepareTableDomainConfiguration = <T extends TableRow>({
+  configuration,
+  rows,
+  tracker,
+  selection,
+  validation,
+  mutation,
+  commitChanges,
+}: TableDomainConfigurationContext<T>) => {
+  const changesEditing = 'editing' in configuration
+  const changesSelection = 'selection' in configuration
+  const changesValidation = 'validation' in configuration
+  const changesMutation = 'mutation' in configuration
+  const nextTracker = changesEditing
+    ? configuration.editing
+      ? createTableChangeTracker({
+          rowKey: configuration.editing.rowKey,
+          getVersion: configuration.editing.getVersion,
+          messages: configuration.editing.messages,
+        })
+      : null
+    : tracker
+
+  const nextSelection = changesSelection
+    ? configuration.selection
+      ? createTableSelection(configuration.selection)
+      : null
+    : selection
+
+  const nextValidation = changesValidation
+    ? configuration.validation
+      ? createTableValidation(configuration.validation)
+      : null
+    : validation
+  const nextMutation = changesMutation
+    ? new TableMutationPipeline<T>()
+    : mutation
+  if (changesMutation) nextMutation.setColumns(configuration.mutation)
+  const rowKey = resolveCanonicalTableRowKey<T>([
+    nextTracker?.rowKeyResolver,
+    nextSelection?.rowKeyResolver,
+    nextValidation?.rowKeyResolver,
+  ])
+  const resolvedKeys = rowKey ? assertTableRowIdentity(rows, rowKey) : undefined
+  if (changesEditing) nextTracker?.reset(rows, resolvedKeys)
+  if (changesSelection) nextSelection?.setLoadedRows(rows, resolvedKeys)
+
+  return {
+    changesEditing,
+    changesSelection,
+    changesValidation,
+    changesMutation,
+    tracker: nextTracker,
+    selection: nextSelection,
+    validation: nextValidation,
+    mutation: nextMutation,
+    rowKey,
+    commitChanges:
+      'commitChanges' in configuration
+        ? (configuration.commitChanges ?? null)
+        : changesEditing
+          ? (configuration.editing?.commitChanges ?? null)
+          : commitChanges,
+  }
+}

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

@@ -0,0 +1,163 @@
+import type { CellChange } from 'handsontable'
+import type { TableSelection } from '../../selection'
+import type { TableRow } from '../../shared'
+import { removeTableRows } from '../../shared/treeRows'
+import type { RowKey } from '../editing'
+import type {
+  ConflictResolution,
+  TableChangeTracker,
+} from '../editing/changeSet'
+import { isRowKey } from '../editing/rowKey'
+import type { TableValidation } from '../editing/validation'
+import { assertTableSaveIdle } from './errors'
+import type { TableCellState } from './types'
+
+interface TableEditingCommandsContext<T extends TableRow> {
+  tableKey: string
+  getSavePromise: () => Promise<unknown> | null
+  getRows: () => T[]
+  setRows: (rows: T[]) => void
+  getTotal: () => number
+  setTotal: (total: number) => void
+  getBaselineTotal: () => number
+  getRow: (visualRow: number) => T | undefined
+  getTracker: () => TableChangeTracker<T> | null
+  getSelection: () => TableSelection<T> | null
+  getValidation: () => TableValidation<T> | null
+  getRowIdentity: (row: T) => RowKey | T
+  refreshRevision: () => void
+  reloadRows: () => void
+  notify: () => void
+}
+
+/**
+ * 编辑命令域：把行增删、脏单元格登记、冲突处理及放弃事务集中到同一原子边界。
+ * Controller 只保留公开 facade，不再重复编排行/选择/校验三个状态机。
+ */
+export class TableEditingCommands<T extends TableRow> {
+  constructor(private readonly context: TableEditingCommandsContext<T>) {}
+
+  recordChanges(changes: CellChange[]) {
+    const tracker = this.context.getTracker()
+    let changed = false
+    changes.forEach(([visualRow, prop, oldValue, newValue]) => {
+      if (
+        Object.is(oldValue, newValue) ||
+        (typeof prop !== 'string' && typeof prop !== 'number')
+      )
+        return
+      const row = this.context.getRow(visualRow)
+      if (!row) return
+      changed = true
+      tracker?.trackCell(row, String(prop), oldValue, newValue)
+      if (tracker) {
+        this.context
+          .getValidation()
+          ?.clearCell(tracker.getRowKey(row), String(prop))
+      }
+    })
+    if (!changed) return
+    this.context.refreshRevision()
+    this.context.notify()
+  }
+
+  getCellState(rowKey: unknown, prop: string): TableCellState {
+    if (!isRowKey(rowKey)) return { conflict: false }
+    const tracker = this.context.getTracker()
+    const validationIssue = this.context.getValidation()?.getIssue(rowKey, prop)
+    return {
+      error: validationIssue?.message ?? tracker?.getCellError(rowKey, prop),
+      conflict: tracker?.hasCellConflict(rowKey, prop) ?? false,
+    }
+  }
+
+  addRow(row: T, index: number) {
+    this.assertSaveIdle('addRow')
+    const rows = this.context.getRows()
+    const target = Math.max(0, Math.min(index, rows.length))
+    const preparedAdd = this.context.getTracker()?.prepareAdd(row)
+    const nextRows = [...rows]
+    nextRows.splice(target, 0, row)
+    let commitSelection: (() => void) | undefined
+    try {
+      commitSelection = this.context.getSelection()?.prepareLoadedRows(nextRows)
+    } catch (error) {
+      preparedAdd?.rollback()
+      throw error
+    }
+    this.context.setRows(nextRows)
+    this.context.setTotal(this.context.getTotal() + 1)
+    preparedAdd?.commit()
+    commitSelection?.()
+    this.context.reloadRows()
+  }
+
+  removeRows(rows: readonly T[]) {
+    if (!rows.length) return
+    this.assertSaveIdle('removeRows')
+    const selection = this.context.getSelection()
+    const tracker = this.context.getTracker()
+    const validation = this.context.getValidation()
+    const getKey = this.context.getRowIdentity
+    const keys = new Set(rows.map(getKey))
+    const currentRows = this.context.getRows()
+    const removedTopLevelCount = currentRows.filter((row) =>
+      keys.has(getKey(row))
+    ).length
+    const removal = removeTableRows(currentRows, (row) => keys.has(getKey(row)))
+    if (!removal.removed.length) return
+    const removedKeys = removal.removed.map(getKey)
+    const commitSelection = selection?.prepareLoadedRows(removal.rows)
+    const commitTracker = tracker?.prepareRemoveRows(removal.removed)
+    // 到这里身份、选择映射和 tracker 操作均已完成预检；提交区只执行不会失败的集合交换。
+    this.context.setRows(removal.rows)
+    commitTracker?.()
+    commitSelection?.()
+    removedKeys.forEach((key) => {
+      if (typeof key === 'string' || typeof key === 'number') {
+        selection?.removeKey(key)
+        validation?.removeRow(key)
+      }
+    })
+    this.context.setTotal(
+      Math.max(0, this.context.getTotal() - removedTopLevelCount)
+    )
+    this.context.reloadRows()
+  }
+
+  resolveConflict(rowKey: string | number, resolution: ConflictResolution) {
+    const tracker = this.context.getTracker()
+    if (!tracker) return
+    const rows = tracker.resolveConflict(
+      this.context.getRows(),
+      rowKey,
+      resolution
+    )
+    this.context.setRows(rows)
+    this.context.getSelection()?.setLoadedRows(rows)
+    this.context.getValidation()?.removeRow(rowKey)
+    this.context.reloadRows()
+  }
+
+  discardChanges() {
+    const tracker = this.context.getTracker()
+    if (!tracker?.isDirty) return
+    this.assertSaveIdle('discardChanges')
+    const rows = tracker.discardRows()
+    this.context.setRows(rows)
+    this.context.setTotal(this.context.getBaselineTotal())
+    this.context.getSelection()?.setLoadedRows(rows)
+    this.context.getValidation()?.reset()
+    this.context.reloadRows()
+  }
+
+  private assertSaveIdle(
+    operation: 'addRow' | 'removeRows' | 'discardChanges'
+  ) {
+    assertTableSaveIdle(
+      this.context.getSavePromise(),
+      this.context.tableKey,
+      operation
+    )
+  }
+}