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

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

@@ -0,0 +1,15 @@
+/** 未落库新增行的身份前缀，服务端真实 key 不得使用该命名空间。 */
+export const TABLE_CLIENT_ROW_KEY_PREFIX = 'client:'
+
+interface TableChangeSources {
+  /** 普通受控单元格编辑来源。 */
+  readonly edit: 'TableComponent.edit'
+  /** 组件根据业务规则派生并写回的编辑来源。 */
+  readonly controlledEdit: 'TableComponent.controlledEdit'
+}
+
+/** 组件内部写入 Handsontable 时使用的来源标记。 */
+export const TABLE_CHANGE_SOURCE: TableChangeSources = {
+  edit: 'TableComponent.edit',
+  controlledEdit: 'TableComponent.controlledEdit',
+}

package/template/src/components/AppTable/engine/table/editing/dirtyCellIndex.ts

@@ -0,0 +1,96 @@
+import { encodeTableRowKey } from './rowKey'
+import type { DirtyCell, RowKey } from './types'
+
+export const createDirtyCellKey = (rowKey: RowKey, prop: string) =>
+  `${encodeTableRowKey(rowKey)}\u0000${prop}`
+
+/**
+ * 脏单元格的常量时间索引和快照列表。Map 负责按 rowKey+prop 查询，列表使用写时复制，
+ * 让高频 Controller snapshot 不需要扫描或重复分配全部脏项。
+ */
+export class TableDirtyCellIndex {
+  private readonly byKey = new Map<string, DirtyCell>()
+  private list: DirtyCell[] = []
+  private listShared = false
+  private readonly positions = new Map<string, number>()
+
+  get size() {
+    return this.byKey.size
+  }
+
+  get cells(): readonly DirtyCell[] {
+    this.listShared = true
+    return Object.freeze(this.list)
+  }
+
+  get(key: string) {
+    return this.byKey.get(key)
+  }
+
+  has(key: string) {
+    return this.byKey.has(key)
+  }
+
+  values() {
+    return this.byKey.values()
+  }
+
+  entries() {
+    return this.byKey.entries()
+  }
+
+  forEach(visitor: (cell: DirtyCell, key: string) => void) {
+    this.byKey.forEach(visitor)
+  }
+
+  [Symbol.iterator]() {
+    return this.byKey[Symbol.iterator]()
+  }
+
+  upsert(key: string, cell: DirtyCell) {
+    const current = this.byKey.get(key)
+    const next = Object.freeze(current ? { ...current, ...cell } : { ...cell })
+    this.ensureWritableList()
+    this.byKey.set(key, next)
+    const position = this.positions.get(key)
+    if (position !== undefined) this.list[position] = next
+    else {
+      this.positions.set(key, this.list.length)
+      this.list.push(next)
+    }
+    return next
+  }
+
+  delete(key: string) {
+    if (!this.byKey.delete(key)) return false
+    this.ensureWritableList()
+    const position = this.positions.get(key)
+    this.positions.delete(key)
+    if (position === undefined) return true
+    const last = this.list.pop()
+    if (last && position < this.list.length) {
+      this.list[position] = last
+      this.positions.set(createDirtyCellKey(last.rowKey, last.prop), position)
+    }
+    return true
+  }
+
+  deleteRow(rowKey: RowKey) {
+    for (const [key, cell] of this.byKey) {
+      if (cell.rowKey === rowKey) this.delete(key)
+    }
+  }
+
+  clear() {
+    this.byKey.clear()
+    this.list = []
+    this.listShared = false
+    this.positions.clear()
+  }
+
+  private ensureWritableList() {
+    if (!this.listShared) return
+    this.list = [...this.list]
+    this.listShared = false
+  }
+}

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

@@ -0,0 +1,6 @@
+export * from './changeSet'
+export * from './mutation'
+export * from './validation'
+export * from './constants'
+export * from './rowKey'
+export type * from './types'

package/template/src/components/AppTable/engine/table/editing/mutation.ts

@@ -0,0 +1,173 @@
+import {
+  TABLE_ENGINE_MESSAGES_ZH_CN,
+  type TableEngineMessages,
+} from '../../shared/messages'
+import type { TableRow } from '../../shared/types'
+import { TABLE_CHANGE_SOURCE } from './constants'
+import type {
+  TableMutationColumn,
+  TableMutationContext,
+  TableMutationInput,
+  TableMutationRejected,
+  TableMutationResult,
+  TableMutationSource,
+  TableNumberInputOptions,
+} from './types'
+
+export type {
+  TableChangeGuard,
+  TableDerivedChanges,
+  TableMutationBatchResult,
+  TableMutationColumn,
+  TableMutationRejected,
+  TableNumberInputOptions,
+  TableValueParser,
+} from './types'
+
+export const parseTableNumberInput = (
+  value: unknown,
+  options: TableNumberInputOptions = {},
+  messages: TableEngineMessages = TABLE_ENGINE_MESSAGES_ZH_CN
+) => {
+  if (typeof value !== 'string') return value
+  const trimmed = value.trim()
+  if (trimmed === '') return options.emptyValue === 'zero' ? 0 : ''
+  const normalized =
+    options.stripGroupingSeparators === false
+      ? trimmed
+      : trimmed.replace(/[,，]/g, '')
+  if (options.output !== 'number') return normalized
+  const number = Number(normalized)
+  if (!Number.isFinite(number)) throw new Error(messages.strInvalidNumber)
+  return number
+}
+
+const SOURCE_MAP: Record<string, TableMutationSource> = {
+  'CopyPaste.paste': 'paste',
+  'Autofill.fill': 'autofill',
+  'UndoRedo.undo': 'undo',
+  'UndoRedo.redo': 'redo',
+  [TABLE_CHANGE_SOURCE.controlledEdit]: 'edit',
+}
+
+const normalizeTableMutationSource = (source?: string): TableMutationSource => {
+  if (!source) return 'edit'
+  if (SOURCE_MAP[source]) return SOURCE_MAP[source]
+  if (source === 'edit') return 'edit'
+  return 'api'
+}
+
+const rejectTableMutation = <T extends TableRow>(
+  value: unknown,
+  message: string,
+  context: TableMutationContext<T>
+): TableMutationRejected<T> => ({ accepted: false, value, message, context })
+
+/** 在任何值转换前检查当前来源是否允许修改该列。 */
+const resolveTableMutationPolicyError = <T extends TableRow>(
+  source: TableMutationSource,
+  rawSource: string,
+  column: TableMutationColumn<T> | undefined,
+  messages: TableEngineMessages
+) => {
+  if (
+    source === 'edit' &&
+    rawSource !== TABLE_CHANGE_SOURCE.controlledEdit &&
+    column?.allowInput === false
+  ) {
+    return messages.strInputForbidden
+  }
+  if (source === 'paste' && column?.allowPaste === false) {
+    return messages.strPasteForbidden
+  }
+  if (source === 'autofill' && column?.allowAutofill === false) {
+    return messages.strAutofillForbidden
+  }
+}
+
+const isTableHistoryReplay = (source: TableMutationSource) =>
+  source === 'undo' || source === 'redo'
+
+/** 解析后同步更新 context.value，保证后续守卫和派生规则观察到同一个值。 */
+const parseTableMutationValue = <T extends TableRow>(
+  context: TableMutationContext<T>,
+  column?: TableMutationColumn<T>
+): TableMutationContext<T> => {
+  const value = column?.parseValue
+    ? column.parseValue(context.value, context)
+    : context.value
+  return { ...context, value }
+}
+
+/** 将 guard 的 boolean/string 协议收敛为可直接展示的错误文案。 */
+const resolveTableChangeGuardError = <T extends TableRow>(
+  context: TableMutationContext<T>,
+  column: TableMutationColumn<T> | undefined,
+  messages: TableEngineMessages
+) => {
+  const outcome = column?.acceptChange?.(context)
+  if (outcome === undefined || outcome === true) return
+  return typeof outcome === 'string' ? outcome : messages.strChangeForbidden
+}
+
+/** 派生字段必须作为同一事务提交；非对象结果按无派生修改处理。 */
+const deriveTableMutationChanges = <T extends TableRow>(
+  context: TableMutationContext<T>,
+  column?: TableMutationColumn<T>
+) => {
+  const derived = column?.deriveChanges?.(context)
+  return derived && typeof derived === 'object' ? derived : {}
+}
+
+export const processTableMutation = <T extends TableRow>(
+  input: TableMutationInput<T>,
+  column?: TableMutationColumn<T>
+): TableMutationResult<T> => {
+  const rawSource = input.rawSource ?? 'edit'
+  const source = normalizeTableMutationSource(rawSource)
+  const messages = column?.messages ?? TABLE_ENGINE_MESSAGES_ZH_CN
+  let context: TableMutationContext<T> = {
+    row: input.row,
+    rowIndex: input.rowIndex,
+    prop: input.prop,
+    oldValue: input.oldValue,
+    value: input.newValue,
+    source,
+    rawSource,
+  }
+
+  // 固定执行顺序：来源策略 -> 值解析 -> 准入守卫 -> 派生字段。
+  const policyError = resolveTableMutationPolicyError(
+    source,
+    rawSource,
+    column,
+    messages
+  )
+  if (policyError)
+    return rejectTableMutation(input.newValue, policyError, context)
+
+  // 历史值必须原样重放；如果撤销或重做时再次解析，会产生不同的历史值，
+  // 还可能让已经还原的单元格继续处于脏状态。
+  if (!isTableHistoryReplay(source)) {
+    try {
+      context = parseTableMutationValue(context, column)
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error)
+      return rejectTableMutation(input.newValue, message, context)
+    }
+
+    const guardError = resolveTableChangeGuardError(context, column, messages)
+    if (guardError)
+      return rejectTableMutation(context.value, guardError, context)
+  }
+
+  try {
+    const derivedChanges = isTableHistoryReplay(source)
+      ? {}
+      : deriveTableMutationChanges(context, column)
+    return { accepted: true, value: context.value, context, derivedChanges }
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error)
+    return rejectTableMutation(context.value, message, context)
+  }
+}

package/template/src/components/AppTable/engine/table/editing/rowKey.ts

@@ -0,0 +1,10 @@
+import type { RowKey } from './types'
+
+/** 行主键只能是非空字符串或有限数字，禁止对象和布尔值进入状态机。 */
+export const isRowKey = (value: unknown): value is RowKey =>
+  (typeof value === 'string' && value.length > 0) ||
+  (typeof value === 'number' && Number.isFinite(value))
+
+/** 为 Map/Set 生成带类型前缀的稳定身份，避免数字 1 与字符串 "1" 冲突。 */
+export const encodeTableRowKey = (rowKey: RowKey) =>
+  `${typeof rowKey}:${String(rowKey)}`