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

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

@@ -0,0 +1,13 @@
+export * from './types'
+export * from './row'
+export * from './constants'
+export * from './tableKey'
+export * from './messages'
+export * from './theme'
+export * from './feedback'
+export * from './interaction'
+export * from './action'
+export * from './decimal'
+export * from './valueSnapshot'
+export * from './scheduler'
+export * from './treeRows'

package/template/src/components/AppTable/engine/shared/interaction.ts

@@ -0,0 +1,55 @@
+import { TABLE_ROW_CLICK_DELAY_MS } from './constants'
+
+interface TableClickCoordinatorOptions<T> {
+  /** 区分单击和双击的等待毫秒数；默认使用组件统一常量。 */
+  delay?: number
+  /** 等待窗口结束且未形成双击时触发。 */
+  onClick: (payload: T) => void
+  /** 同一行在等待窗口内第二次点击时触发。 */
+  onDoubleClick: (payload: T) => void
+}
+
+type TableClickDisposition = 'pending' | 'double'
+
+/** 为各框架的行适配器提供单击与双击的框架无关协调逻辑。 */
+export const createTableClickCoordinator = <T>(
+  options: TableClickCoordinatorOptions<T>
+) => {
+  const delay = options.delay ?? TABLE_ROW_CLICK_DELAY_MS
+  let pending:
+    | { key: string | number; payload: T; timer: ReturnType<typeof setTimeout> }
+    | undefined
+
+  const cancel = () => {
+    if (!pending) return
+    clearTimeout(pending.timer)
+    pending = undefined
+  }
+
+  const schedule = (
+    key: string | number,
+    payload: T
+  ): TableClickDisposition => {
+    if (pending) {
+      clearTimeout(pending.timer)
+      const previous = pending
+      pending = undefined
+      if (previous.key === key) {
+        options.onDoubleClick(payload)
+        return 'double'
+      }
+      options.onClick(previous.payload)
+    }
+
+    const timer = setTimeout(() => {
+      if (pending?.timer !== timer) return
+      const current = pending
+      pending = undefined
+      options.onClick(current.payload)
+    }, delay)
+    pending = { key, payload, timer }
+    return 'pending'
+  }
+
+  return { schedule, cancel }
+}

package/template/src/components/AppTable/engine/shared/messages.ts

@@ -0,0 +1,161 @@
+/** 纯 engine 在解析、校验和修改准入阶段使用的可见文案。 */
+export interface TableEngineMessages {
+  /** 空公式错误。 */
+  strFormulaRequired: string
+  /** 公式长度上限错误。 */
+  strFormulaTooLong: string
+  /** 公式括号不匹配错误。 */
+  strFormulaParentheses: string
+  /** 生成公式非法字符位置错误。 */
+  fnFormulaInvalidCharacter: (nPosition: number) => string
+  /** 公式科学计数指数范围错误。 */
+  strFormulaExponentRange: string
+  /** 公式幂指数范围错误。 */
+  strFormulaPowerRange: string
+  /** 公式除零错误。 */
+  strFormulaDivisionByZero: string
+  /** 公式结果范围错误。 */
+  strFormulaResultRange: string
+  /** 公式结果无法安全转成 number 的错误。 */
+  strFormulaUnsafeNumber: string
+  /** 日期格式错误。 */
+  strInvalidDateFormat: string
+  /** 日期值不存在错误。 */
+  strInvalidDate: string
+  /** 时间格式错误。 */
+  strInvalidTimeFormat: string
+  /** 时间值不存在错误。 */
+  strInvalidTime: string
+  /** 日期时间格式错误。 */
+  strInvalidDateTimeFormat: string
+  /** 单选列不允许清空错误。 */
+  strSelectClearForbidden: string
+  /** 单选值不在选项内错误。 */
+  strSelectValueUnknown: string
+  /** 单选项已禁用错误。 */
+  strSelectOptionDisabled: string
+  /** 多选值不是数组错误。 */
+  strMultiSelectArrayRequired: string
+  /** 生成多选数量上限错误。 */
+  fnMultiSelectLimit: (nMaximum: number) => string
+  /** 数字输入解析错误。 */
+  strInvalidNumber: string
+  /** 禁止直接输入错误。 */
+  strInputForbidden: string
+  /** 禁止粘贴错误。 */
+  strPasteForbidden: string
+  /** 禁止自动填充错误。 */
+  strAutofillForbidden: string
+  /** 业务守卫拒绝但未给原因时的错误。 */
+  strChangeForbidden: string
+  /** 生成整数校验错误。 */
+  fnValidationInteger: (strLabel: string) => string
+  /** 生成整数位数校验错误。 */
+  fnValidationIntegerDigits: (strLabel: string, nDigits: number) => string
+  /** 生成正数校验错误。 */
+  fnValidationPositive: (strLabel: string) => string
+  /** 生成最小值校验错误。 */
+  fnValidationMin: (strLabel: string, nMinimum: number) => string
+  /** 生成最大值校验错误。 */
+  fnValidationMax: (strLabel: string, nMaximum: number) => string
+  /** 生成小数位数校验错误。 */
+  fnValidationDecimals: (strLabel: string, nPlaces: number) => string
+  /** 生成必填校验错误。 */
+  fnValidationRequired: (strLabel: string) => string
+  /** 生成字符长度校验错误。 */
+  fnValidationMaxLength: (strLabel: string, nMaximum: number) => string
+  /** 生成有效数字校验错误。 */
+  fnValidationNumber: (strLabel: string) => string
+  /** 生成自定义校验未提供消息时的错误。 */
+  fnValidationFailed: (strLabel: string) => string
+  /** 选择控件未配置占位文案时的默认值。 */
+  strSelectPlaceholder: string
+  /** 操作列折叠菜单入口文案。 */
+  strMoreActions: string
+  /** 生成开关单元格的无障碍名称。 */
+  fnSwitchAriaLabel: (strLabel: string, bChecked: boolean) => string
+  /** 生成清除链接值入口的无障碍名称。 */
+  fnClearLinkAriaLabel: (strLabel: string) => string
+  /** 确认输入单元格的默认提交文案。 */
+  strConfirmInput: string
+  /** 生成行选择框的无障碍名称。 */
+  fnSelectRowAriaLabel: (nRow: number) => string
+  /** 当前页全选框的无障碍名称。 */
+  strSelectCurrentPage: string
+  /** 必填列表头标记的无障碍名称。 */
+  strRequired: string
+  /** 固定尾部操作列区域的无障碍名称。 */
+  strFixedActionColumns: string
+  /** 单元格编辑图标的无障碍名称。 */
+  strOpenCellEditor: string
+  /** 新增行缺少服务端提交结果时的错误。 */
+  strMissingCreateResult: string
+  /** 更新行缺少服务端提交结果时的错误。 */
+  strMissingUpdateResult: string
+  /** 删除行缺少服务端提交结果时的错误。 */
+  strMissingRemoveResult: string
+  /** 乐观锁冲突未返回显式消息时的错误。 */
+  strServerDataUpdated: string
+  /** 保存失败且服务端未返回显式消息时的错误。 */
+  strSaveFailed: string
+}
+
+/** 非 React 消费者的中文兼容默认值。 */
+export const TABLE_ENGINE_MESSAGES_ZH_CN: TableEngineMessages = Object.freeze({
+  strFormulaRequired: '公式不能为空',
+  strFormulaTooLong: '公式不能超过 256 个字符',
+  strFormulaParentheses: '公式括号不匹配',
+  fnFormulaInvalidCharacter: (nPosition) =>
+    `公式在第 ${nPosition} 个字符处无效`,
+  strFormulaExponentRange: '公式指数超出范围',
+  strFormulaPowerRange: '公式幂指数必须是 -100 到 100 的整数',
+  strFormulaDivisionByZero: '公式不能除以 0',
+  strFormulaResultRange: '公式结果超出范围',
+  strFormulaUnsafeNumber: '公式结果无法安全转换为 number',
+  strInvalidDateFormat: '请输入有效日期，格式为 YYYY-MM-DD',
+  strInvalidDate: '请输入真实存在的日期',
+  strInvalidTimeFormat: '请输入有效时间，格式为 HH:mm:ss',
+  strInvalidTime: '请输入真实存在的时间',
+  strInvalidDateTimeFormat: '请输入有效日期时间，格式为 YYYY-MM-DD HH:mm:ss',
+  strSelectClearForbidden: '该下拉列不允许清空',
+  strSelectValueUnknown: '所选值不在下拉选项中',
+  strSelectOptionDisabled: '该下拉选项已禁用',
+  strMultiSelectArrayRequired: '多选列的值必须是数组',
+  fnMultiSelectLimit: (nMaximum) => `最多选择 ${nMaximum} 项`,
+  strInvalidNumber: '请输入有效数字',
+  strInputForbidden: '该列不允许直接输入',
+  strPasteForbidden: '该列不允许粘贴',
+  strAutofillForbidden: '该列不允许自动填充',
+  strChangeForbidden: '该修改不被允许',
+  fnValidationInteger: (strLabel) => `【${strLabel}】必须是整数`,
+  fnValidationIntegerDigits: (strLabel, nDigits) =>
+    `【${strLabel}】整数部分不能超过 ${nDigits} 位`,
+  fnValidationPositive: (strLabel) => `【${strLabel}】必须大于 0`,
+  fnValidationMin: (strLabel, nMinimum) =>
+    `【${strLabel}】不能小于 ${nMinimum}`,
+  fnValidationMax: (strLabel, nMaximum) =>
+    `【${strLabel}】不能大于 ${nMaximum}`,
+  fnValidationDecimals: (strLabel, nPlaces) =>
+    `【${strLabel}】最多保留 ${nPlaces} 位小数`,
+  fnValidationRequired: (strLabel) => `【${strLabel}】不能为空`,
+  fnValidationMaxLength: (strLabel, nMaximum) =>
+    `【${strLabel}】不能超过 ${nMaximum} 个字符`,
+  fnValidationNumber: (strLabel) => `【${strLabel}】必须是有效数字`,
+  fnValidationFailed: (strLabel) => `【${strLabel}】校验失败`,
+  strSelectPlaceholder: '请选择',
+  strMoreActions: '更多',
+  fnSwitchAriaLabel: (strLabel, bChecked) =>
+    `${strLabel}：${bChecked ? '开启' : '关闭'}`,
+  fnClearLinkAriaLabel: (strLabel) => `清除${strLabel}`,
+  strConfirmInput: '提交',
+  fnSelectRowAriaLabel: (nRow) => `选择第 ${nRow} 行`,
+  strSelectCurrentPage: '选择当前页',
+  strRequired: '必填',
+  strFixedActionColumns: '固定操作列',
+  strOpenCellEditor: '打开单元格编辑器',
+  strMissingCreateResult: '服务端未返回该新增行的提交结果',
+  strMissingUpdateResult: '服务端未返回该行的提交结果',
+  strMissingRemoveResult: '服务端未返回该删除行的提交结果',
+  strServerDataUpdated: '服务端数据已更新',
+  strSaveFailed: '保存失败',
+} satisfies TableEngineMessages)

package/template/src/components/AppTable/engine/shared/row.ts

@@ -0,0 +1,32 @@
+import type { TableRow } from './types'
+
+/** 动态列访问时允许的属性名；业务 DTO 本身不需要声明字符串索引签名。 */
+type TableFieldKey = string | number | symbol
+
+/**
+ * 读取后端 DTO 的动态字段。
+ *
+ * 不把带字符串索引签名的 Record 暴露到公共泛型；只有这一层使用 Reflect 访问运行时列名，
+ * 返回值保持 unknown，调用方必须通过 formatter/parser/validator 明确收窄类型。
+ */
+export const getTableRowValue = <T extends TableRow>(
+  row: T,
+  key: TableFieldKey
+): unknown => Reflect.get(row, key)
+
+/** 在受控编辑事务内写入动态字段。 */
+export const setTableRowValue = <T extends TableRow>(
+  row: T,
+  key: TableFieldKey,
+  value: unknown
+): void => {
+  Reflect.set(row, key, value)
+}
+
+/** 删除可选动态字段，主要用于重建冲突 patch。 */
+export const deleteTableRowValue = <T extends TableRow>(
+  row: T,
+  key: TableFieldKey
+): void => {
+  Reflect.deleteProperty(row, key)
+}

package/template/src/components/AppTable/engine/shared/scheduler.ts

@@ -0,0 +1,17 @@
+/** 主线程长任务的默认让出间隔；约束单段同步工作而不是只统计总耗时。 */
+export const TABLE_TASK_YIELD_INTERVAL = 8_192
+
+/**
+ * 把大型本地计算切成可取消任务。优先使用 scheduler.yield，旧浏览器退化到 0ms
+ * macrotask，确保 loading/validating 能先绘制且滚动、输入不会被单次长任务饿死。
+ */
+export const yieldTableMainThread = async () => {
+  const scheduler = Reflect.get(globalThis, 'scheduler') as
+    | { yield?: () => Promise<void> }
+    | undefined
+  if (typeof scheduler?.yield === 'function') {
+    await scheduler.yield()
+    return
+  }
+  await new Promise<void>((resolve) => setTimeout(resolve, 0))
+}

package/template/src/components/AppTable/engine/shared/tableKey.ts

@@ -0,0 +1,31 @@
+const activeTableKeys = new Map<string, symbol>()
+
+const requireNonEmpty = (value: string | undefined, label: string) => {
+  const normalized = value?.trim()
+  if (!normalized) throw new Error(`[TableComponent] ${label} cannot be empty.`)
+  return normalized
+}
+
+/** 解析并校验业务显式提供的稳定表格身份。 */
+export const resolveTableKey = (tableKey: string): string =>
+  requireNonEmpty(tableKey, 'tableKey')
+
+/** 注册已挂载的表格身份，并返回可重复调用的释放回调。 */
+export const claimTableKey = (tableKey: string): (() => void) => {
+  const key = resolveTableKey(tableKey)
+  if (activeTableKeys.has(key)) {
+    throw new Error(
+      `[TableComponent] Duplicate mounted tableKey "${key}". Provide a unique business tableKey.`
+    )
+  }
+
+  const owner = Symbol(key)
+  activeTableKeys.set(key, owner)
+  let released = false
+
+  return () => {
+    if (released) return
+    released = true
+    if (activeTableKeys.get(key) === owner) activeTableKeys.delete(key)
+  }
+}

package/template/src/components/AppTable/engine/shared/theme.ts

@@ -0,0 +1,196 @@
+import {
+  hasTheme,
+  horizonTheme,
+  mainTheme,
+  registerTheme,
+  reinitTheme,
+  type BaseTheme,
+  type ThemeBuilder,
+  type ThemeColorScheme,
+} from 'handsontable/themes'
+
+export const TABLE_DENSITIES: readonly ['compact', 'default', 'comfortable'] = [
+  'compact',
+  'default',
+  'comfortable',
+]
+
+export type TableDensity = (typeof TABLE_DENSITIES)[number]
+export type TableThemeMode = 'auto' | 'light' | 'dark'
+export type TableTheme =
+  | TableThemeMode
+  | (string & {})
+  | BaseTheme
+  | ThemeBuilder
+
+interface TableThemeSnapshot {
+  /** 当前生效的表格密度。 */
+  density: TableDensity
+  /** 当前主题是否由组件创建的 ThemeBuilder 实例管理。 */
+  managed: boolean
+  /** Handsontable 实际使用的主题名称。 */
+  themeName: string
+  /** 当前主题配色；直接使用外部主题名时可能不存在。 */
+  colorScheme?: ThemeColorScheme
+}
+
+interface TableThemeControllerOptions {
+  /** 表格稳定标识，用于生成互不冲突的运行时主题名称。 */
+  tableKey: string
+  /** 主题模式、已注册主题名、基础主题对象或 ThemeBuilder 实例。 */
+  theme?: TableTheme
+  /** 初始密度；未传时采用 comfortable。 */
+  density?: TableDensity
+  /** theme 为 auto 时用于选择初始深浅配色。 */
+  dark?: boolean
+}
+
+/** Theme Builder 预设：Main 令牌、Main 配色和 Horizon 图标。 */
+const TABLE_DEFAULT_THEME: BaseTheme = {
+  ...mainTheme,
+  density: 'comfortable',
+  icons: horizonTheme.icons,
+}
+
+const isTableDensity = (value: unknown): value is TableDensity =>
+  typeof value === 'string' && TABLE_DENSITIES.some((item) => item === value)
+
+export const normalizeTableDensity = (
+  value: unknown,
+  fallback: TableDensity = 'comfortable'
+): TableDensity => (isTableDensity(value) ? value : fallback)
+
+const isThemeBuilder = (value: unknown): value is ThemeBuilder =>
+  Boolean(
+    value &&
+    typeof value === 'object' &&
+    'getThemeConfig' in value &&
+    typeof value.getThemeConfig === 'function'
+  )
+
+const createRuntimeThemeName = (tableKey: string) => {
+  const safeKey = tableKey
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9_-]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 48)
+  let hash = 2166136261
+  for (const character of tableKey) {
+    hash ^= character.charCodeAt(0)
+    hash = Math.imul(hash, 16777619)
+  }
+  return `he-table-${safeKey || 'anonymous'}-${(hash >>> 0).toString(36)}`
+}
+
+const isThemeMode = (value: TableTheme): value is TableThemeMode =>
+  value === 'auto' || value === 'light' || value === 'dark'
+
+/** 对 Handsontable v18 ThemeBuilder 的框架无关、表格实例级封装。 */
+export class TableThemeController {
+  readonly theme: ThemeBuilder | string
+  private readonly mode?: TableThemeMode
+  private density: TableDensity
+
+  constructor(options: TableThemeControllerOptions) {
+    const source = options.theme ?? 'auto'
+    this.density = normalizeTableDensity(options.density)
+
+    if (typeof source === 'string' && !isThemeMode(source)) {
+      this.theme = source
+      return
+    }
+
+    this.mode = typeof source === 'string' ? source : undefined
+    const sourceConfig = isThemeBuilder(source)
+      ? source.getThemeConfig()
+      : typeof source === 'object'
+        ? source
+        : undefined
+    const sourceDensity =
+      typeof sourceConfig?.density === 'string'
+        ? sourceConfig.density
+        : sourceConfig?.density?.type
+    this.density = normalizeTableDensity(
+      options.density,
+      normalizeTableDensity(sourceDensity)
+    )
+    const baseTheme = isThemeBuilder(source)
+      ? sourceConfig!
+      : (sourceConfig ?? TABLE_DEFAULT_THEME)
+    const colorScheme: ThemeColorScheme =
+      this.mode === 'light'
+        ? 'light'
+        : this.mode === 'dark'
+          ? 'dark'
+          : this.mode === 'auto'
+            ? options.dark
+              ? 'dark'
+              : 'light'
+            : (sourceConfig?.colorScheme ?? 'auto')
+    const themeConfig = {
+      ...baseTheme,
+      name: createRuntimeThemeName(options.tableKey),
+    }
+    const theme = hasTheme(themeConfig.name)
+      ? reinitTheme(themeConfig.name, themeConfig)!
+      : registerTheme(themeConfig)
+    if (sourceConfig && !isThemeBuilder(source)) {
+      const { name: _name, ...params } = sourceConfig
+      theme.params(params)
+    }
+    this.theme = theme.setColorScheme(colorScheme).setDensityType(this.density)
+  }
+
+  get managed() {
+    return isThemeBuilder(this.theme)
+  }
+
+  get snapshot(): TableThemeSnapshot {
+    if (!isThemeBuilder(this.theme)) {
+      return {
+        density: this.density,
+        managed: false,
+        themeName: this.theme,
+      }
+    }
+    const config = this.theme.getThemeConfig()
+    return {
+      density: normalizeTableDensity(config.density.type, this.density),
+      managed: true,
+      themeName: String(config.name),
+      colorScheme: config.colorScheme,
+    }
+  }
+
+  setDensity(density: TableDensity) {
+    if (!isTableDensity(density)) {
+      throw new Error(`[TableComponent] Unsupported density "${density}".`)
+    }
+    if (!isThemeBuilder(this.theme)) {
+      throw new Error(
+        '[TableComponent] Runtime density requires a ThemeBuilder or a built-in theme mode.'
+      )
+    }
+    this.density = density
+    this.theme.setDensityType(density)
+  }
+
+  setDarkMode(dark: boolean) {
+    if (this.mode !== 'auto' || !isThemeBuilder(this.theme)) return
+    this.theme.setColorScheme(dark ? 'dark' : 'light')
+  }
+
+  setColorScheme(colorScheme: ThemeColorScheme) {
+    if (!isThemeBuilder(this.theme)) {
+      throw new Error(
+        '[TableComponent] Runtime color scheme requires a ThemeBuilder or a built-in theme mode.'
+      )
+    }
+    this.theme.setColorScheme(colorScheme)
+  }
+}
+
+export const createTableThemeController = (
+  options: TableThemeControllerOptions
+) => new TableThemeController(options)

package/template/src/components/AppTable/engine/shared/treeRows.ts

@@ -0,0 +1,155 @@
+import type { TableRow } from './types'
+import { cloneTableValue } from './valueSnapshot'
+
+/** Handsontable NestedRows 约定的子行字段。 */
+const TABLE_ROW_CHILDREN_KEY = '__children'
+
+export interface TableRowTreeEntry<T extends TableRow> {
+  row: T
+  parentRows: T[]
+  index: number
+  flatIndex: number
+  path: readonly number[]
+}
+
+/** 返回合法的 NestedRows 子行；非数组值按无子行处理。 */
+const getTableRowChildren = <T extends TableRow>(row: T): T[] => {
+  const children = Reflect.get(row, TABLE_ROW_CHILDREN_KEY)
+  return Array.isArray(children) ? (children as T[]) : []
+}
+
+/** 以前序深度优先顺序遍历父行和全部子行。 */
+export const walkTableRows = <T extends TableRow>(
+  rows: readonly T[],
+  visit: (entry: TableRowTreeEntry<T>) => void
+) => {
+  for (const entry of iterateTableRows(rows)) visit(entry)
+}
+
+/** 惰性以前序深度优先顺序遍历父子行，避免大数据任务预先分配完整扁平数组。 */
+export function* iterateTableRows<T extends TableRow>(
+  rows: readonly T[],
+  path: readonly number[] = [],
+  counter = { value: 0 }
+): Generator<TableRowTreeEntry<T>> {
+  for (let index = 0; index < rows.length; index += 1) {
+    const row = rows[index]
+    const entryPath = [...path, index]
+    yield {
+      row,
+      parentRows: rows as T[],
+      index,
+      flatIndex: counter.value++,
+      path: entryPath,
+    }
+    yield* iterateTableRows(getTableRowChildren(row), entryPath, counter)
+  }
+}
+
+/** 将 NestedRows 展开为父子行共享的业务行集合。 */
+export const flattenTableRows = <T extends TableRow>(rows: readonly T[]) => {
+  const result: T[] = []
+  walkTableRows(rows, ({ row }) => result.push(row))
+  return result
+}
+
+/** 按统一树遍历语义定位业务行及其父数组。 */
+export const findTableRowEntry = <T extends TableRow>(
+  rows: readonly T[],
+  predicate: (row: T) => boolean
+) => {
+  let result: TableRowTreeEntry<T> | undefined
+  walkTableRows(rows, (entry) => {
+    if (!result && predicate(entry.row)) result = entry
+  })
+  return result
+}
+
+/** 一次遍历建立稳定业务键到树节点的索引，供批量事务避免重复扫描整棵树。 */
+export const createTableRowIndex = <T extends TableRow, K>(
+  rows: readonly T[],
+  resolveKey: (row: T) => K
+) => {
+  const result = new Map<K, TableRowTreeEntry<T>>()
+  walkTableRows(rows, (entry) => result.set(resolveKey(entry.row), entry))
+  return result
+}
+
+/** 深拷贝完整父子行树。 */
+export const cloneTableRows = <T extends TableRow>(rows: readonly T[]): T[] =>
+  cloneTableValue(rows) as T[]
+
+/** 结构共享地替换树中第一条匹配行。 */
+export const replaceTableRow = <T extends TableRow>(
+  rows: readonly T[],
+  predicate: (row: T) => boolean,
+  replacement: T
+): { rows: T[]; replaced: boolean } => {
+  let replaced = false
+  const visit = (items: readonly T[]): T[] =>
+    items.map((row) => {
+      if (!replaced && predicate(row)) {
+        replaced = true
+        return replacement
+      }
+      const children = getTableRowChildren(row)
+      if (!children.length || replaced) return row
+      const nextChildren = visit(children)
+      if (nextChildren.every((child, index) => child === children[index]))
+        return row
+      const nextRow = { ...row }
+      Reflect.set(nextRow, TABLE_ROW_CHILDREN_KEY, nextChildren)
+      return nextRow
+    })
+  return { rows: visit(rows), replaced }
+}
+
+/** 一次遍历批量替换 NestedRows，父子行同时更新时仍保留替换后的完整树结构。 */
+export const replaceTableRows = <T extends TableRow, K>(
+  rows: readonly T[],
+  resolveKey: (row: T) => K,
+  replacements: ReadonlyMap<K, T>
+): T[] => {
+  if (!replacements.size) return [...rows]
+  const visit = (items: readonly T[]): T[] =>
+    items.map((row) => {
+      const nextRow = replacements.get(resolveKey(row)) ?? row
+      const children = getTableRowChildren(nextRow)
+      if (!children.length) return nextRow
+      const nextChildren = visit(children)
+      if (nextChildren.every((child, index) => child === children[index]))
+        return nextRow
+      const nextWithChildren = { ...nextRow }
+      Reflect.set(nextWithChildren, TABLE_ROW_CHILDREN_KEY, nextChildren)
+      return nextWithChildren
+    })
+  return visit(rows)
+}
+
+/** 结构共享地删除树中全部匹配行，并返回真实删除集合。 */
+export const removeTableRows = <T extends TableRow>(
+  rows: readonly T[],
+  predicate: (row: T) => boolean
+): { rows: T[]; removed: T[] } => {
+  const removed: T[] = []
+  const visit = (items: readonly T[]): T[] =>
+    items.flatMap((row) => {
+      if (predicate(row)) {
+        removed.push(row, ...flattenTableRows(getTableRowChildren(row)))
+        return []
+      }
+      const children = getTableRowChildren(row)
+      if (!children.length) return [row]
+      const nextChildren = visit(children)
+      if (
+        nextChildren.length === children.length &&
+        nextChildren.every((child, index) => child === children[index])
+      ) {
+        return [row]
+      }
+      const nextRow = { ...row }
+      Reflect.set(nextRow, TABLE_ROW_CHILDREN_KEY, nextChildren)
+      return [nextRow]
+    })
+  return { rows: visit(rows), removed }
+}