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

package/template/src/components/AppTable/engine/summary/summary.ts

@@ -0,0 +1,457 @@
+import type { TableQueryParams } from '../search/types'
+import {
+  isSelectionFullyLoaded,
+  serializeSelection,
+  type SelectionDescriptor,
+  type SelectionState,
+} from '../selection/selection'
+import {
+  parseTableDecimal,
+  roundTableDecimal,
+  TableDecimal,
+  tableDecimalToString,
+  type TableDecimalInstance,
+} from '../shared/decimal'
+import { getTableRowValue } from '../shared/row'
+import {
+  TABLE_TASK_YIELD_INTERVAL,
+  yieldTableMainThread,
+} from '../shared/scheduler'
+import type { TableKeyOf, TableRow } from '../shared/types'
+import { TABLE_DEFAULT_AVERAGE_PRECISION } from './constants'
+
+export type TableSummaryScope = 'page' | 'selection' | 'all'
+export type TableSummaryOperation =
+  | 'sum'
+  | 'avg'
+  | 'min'
+  | 'max'
+  | 'count'
+  | 'custom'
+
+export type TableSummaryAwaitable<T> = T | PromiseLike<T>
+
+/**
+ * 自定义本地汇总只能通过受控迭代器读取行，框架会在分片边界检查取消并让出主线程。
+ * 大数据全量汇总仍应使用远程 provider，避免把业务闭包序列化进 Worker。
+ */
+export interface TableSummaryAggregateContext<T extends TableRow = TableRow> {
+  /** 新汇总任务、组件销毁或主动取消时触发的信号。 */
+  signal: AbortSignal
+  /** 当前汇总范围内可迭代的业务行总数。 */
+  rowCount: number
+  /** 可取消、分片地遍历汇总范围内的每一行业务数据。 */
+  forEachRow(
+    visitor: (row: T, index: number) => TableSummaryAwaitable<void>
+  ): Promise<void>
+  /** 可取消、分片地把汇总范围内的业务行归约为单个结果。 */
+  reduceRows<R>(
+    initial: R,
+    reducer: (accumulator: R, row: T, index: number) => TableSummaryAwaitable<R>
+  ): Promise<R>
+}
+
+interface TableSummaryColumnBase<T extends TableRow = TableRow> {
+  /** 参与汇总的 DTO 字段 key，也是结果 values 中的 key。 */
+  key: TableKeyOf<T>
+  /** 汇总行显示名称，省略时继承业务列标题。 */
+  label?: string
+  /** 平均值保留的小数位数，默认 6 位，并移除末尾的零。 */
+  precision?: number
+  /** 从每行提取参与聚合的值，默认按 key 读取。 */
+  value?: (row: T) => unknown
+  /** 对聚合结果进行最终显示格式化，不改变原始 values。 */
+  format?: (value: unknown, column: TableSummaryColumn<T>) => unknown
+}
+
+/** custom 汇总必须提供 aggregate；内置操作禁止携带不会被执行的 aggregate。 */
+export type TableSummaryColumn<T extends TableRow = TableRow> =
+  TableSummaryColumnBase<T> &
+    (
+      | {
+          /** 使用业务自定义聚合函数。 */
+          operation: 'custom'
+          /** 通过受控迭代上下文计算当前列的汇总原始值。 */
+          aggregate: (
+            context: TableSummaryAggregateContext<T>,
+            column: TableSummaryColumn<T>
+          ) => TableSummaryAwaitable<unknown>
+        }
+      | {
+          /** 使用内置 sum、avg、min、max 或 count 聚合。 */
+          operation: Exclude<TableSummaryOperation, 'custom'>
+          /** 内置聚合不接受自定义 aggregate，避免配置被静默忽略。 */
+          aggregate?: never
+        }
+    )
+
+/** 本地或远程汇总成功后返回的原始值和格式化值。 */
+export interface TableSummaryResult {
+  /** 本次实际执行的汇总数据范围。 */
+  scope: TableSummaryScope
+  /** 汇总由浏览器本地计算还是远程 provider 完成。 */
+  source: 'local' | 'remote'
+  /** 按汇总列 key 索引的原始聚合结果。 */
+  values: Record<string, unknown>
+  /** 按汇总列 key 索引、已执行 format 的展示结果。 */
+  formattedValues: Record<string, unknown>
+}
+
+/** 发送给远程汇总 provider 的稳定请求合同。 */
+export interface RemoteSummaryRequest {
+  /** 发起汇总的稳定表格业务标识。 */
+  tableKey: string
+  /** 需要远程处理的已选数据或全部匹配数据。 */
+  scope: 'selection' | 'all'
+  /** 当前查询参数；全量匹配范围可据此在服务端重建数据集。 */
+  query?: TableQueryParams
+  /** 可序列化的显式选择或全部匹配选择描述。 */
+  selection: SelectionDescriptor
+  /** 服务端需要执行的汇总列和聚合规则。 */
+  columns: Array<{
+    /** 参与汇总的 DTO 字段名。 */
+    key: string
+    /** 服务端需要执行的聚合操作。 */
+    operation: TableSummaryOperation
+    /** 平均值等结果允许保留的小数位数。 */
+    precision?: number
+  }>
+  /** 汇总格式化使用的区域语言。 */
+  locale?: string
+  /** 日期时间汇总使用的 IANA 时区。 */
+  timeZone?: string
+}
+
+/** 远程汇总 provider 收到的任务生命周期上下文。 */
+export interface TableSummaryContext {
+  /** 新任务、组件销毁或主动取消时触发的信号。 */
+  signal: AbortSignal
+}
+
+export type TableSummaryProvider = (
+  request: RemoteSummaryRequest,
+  context: TableSummaryContext
+) => Promise<{
+  /** 按请求汇总列 key 索引的服务端原始聚合结果。 */
+  values: Record<string, unknown>
+}>
+
+/** 汇总执行器使用的完整数据、范围和 provider 选项。 */
+interface RunTableSummaryOptions<T extends TableRow = TableRow> {
+  /** 发起汇总的稳定表格业务标识。 */
+  tableKey: string
+  /** 本次请求的汇总数据范围。 */
+  scope: TableSummaryScope
+  /** 当前已加载、可用于本地汇总的业务行。 */
+  rows: readonly T[]
+  /** 当前完整行选择状态。 */
+  selection: SelectionState<T>
+  /** 需要计算的汇总列。 */
+  columns: readonly TableSummaryColumn<T>[]
+  /** 当前表格是否使用远程数据源。 */
+  remote: boolean
+  /** 当前分页、筛选和排序查询参数。 */
+  query?: TableQueryParams
+  /** 处理全部匹配或未完整加载选择范围的远程 provider。 */
+  provider?: TableSummaryProvider
+  /** 汇总格式化使用的区域语言。 */
+  locale?: string
+  /** 日期时间汇总使用的 IANA 时区。 */
+  timeZone?: string
+  /** 主动取消本次汇总任务的信号。 */
+  signal?: AbortSignal
+}
+
+class TableSummaryProviderRequiredError extends Error {
+  readonly code = 'TABLE_SUMMARY_PROVIDER_REQUIRED'
+
+  constructor(readonly scope: TableSummaryScope) {
+    super(
+      `[TableComponent] Summary scope "${scope}" requires a remote summary provider.`
+    )
+    this.name = 'TableSummaryProviderRequiredError'
+  }
+}
+
+export const countTableSelectionCells = (
+  ranges: readonly (readonly number[])[]
+): number =>
+  ranges.reduce((total, range) => {
+    const [row, column, row2, column2] = range
+    if (
+      row === undefined ||
+      column === undefined ||
+      row2 === undefined ||
+      column2 === undefined
+    )
+      return total
+    return total + (Math.abs(row2 - row) + 1) * (Math.abs(column2 - column) + 1)
+  }, 0)
+
+/** 对任意单元格或嵌套区域值做十进制安全求和。 */
+export const sumTableNumericValues = (
+  values: Iterable<unknown>
+): string | null => {
+  let sum = new TableDecimal(0)
+  let count = 0
+  const append = (value: unknown) => {
+    if (Array.isArray(value)) {
+      value.forEach(append)
+      return
+    }
+    const decimal = parseTableDecimal(value)
+    if (!decimal) return
+    sum = sum.plus(decimal)
+    count += 1
+  }
+  for (const value of values) append(value)
+  return count ? tableDecimalToString(sum) : null
+}
+
+/** 大选区求和的可取消分片版本。 */
+export const sumTableNumericValuesAsync = async (
+  values: Iterable<unknown>,
+  options: { signal?: AbortSignal; yieldInterval?: number } = {}
+): Promise<string | null> => {
+  let sum = new TableDecimal(0)
+  let count = 0
+  let processed = 0
+  const yieldInterval = Math.max(
+    1,
+    options.yieldInterval ?? TABLE_TASK_YIELD_INTERVAL
+  )
+  for (const source of values) {
+    const pending = [source]
+    while (pending.length) {
+      if (options.signal?.aborted) throw options.signal.reason
+      const value = pending.pop()
+      if (Array.isArray(value)) {
+        pending.push(...value)
+        continue
+      }
+      const decimal = parseTableDecimal(value)
+      if (decimal) {
+        sum = sum.plus(decimal)
+        count += 1
+      }
+      processed += 1
+      if (processed % yieldInterval === 0) await yieldTableMainThread()
+    }
+  }
+  if (options.signal?.aborted) throw options.signal.reason
+  return count ? tableDecimalToString(sum) : null
+}
+
+const countSummaryValue = (value: unknown) => {
+  // 多值单元格按实际元素数统计，普通单元格按非空值统计。
+  if (Array.isArray(value)) return value.length
+  return value == null || value === '' ? 0 : 1
+}
+
+const selectSummaryDecimal = (
+  operation: 'min' | 'max',
+  current: TableDecimalInstance,
+  candidate: TableDecimalInstance
+) => {
+  if (operation === 'min') return candidate.lt(current) ? candidate : current
+  return candidate.gt(current) ? candidate : current
+}
+
+const createSummaryAggregateContext = <T extends TableRow>(
+  rows: readonly T[],
+  signal: AbortSignal
+): TableSummaryAggregateContext<T> => {
+  const isPromiseLike = <R>(
+    value: TableSummaryAwaitable<R>
+  ): value is PromiseLike<R> =>
+    typeof value === 'object' &&
+    value !== null &&
+    typeof (value as PromiseLike<R>).then === 'function'
+  const visitRows = async (
+    visitor: (row: T, index: number) => TableSummaryAwaitable<void>
+  ) => {
+    for (let index = 0; index < rows.length; index += 1) {
+      if (signal.aborted) throw signal.reason
+      const pending = visitor(rows[index]!, index)
+      if (isPromiseLike(pending)) await pending
+      if ((index + 1) % TABLE_TASK_YIELD_INTERVAL === 0) {
+        await yieldTableMainThread()
+        if (signal.aborted) throw signal.reason
+      }
+    }
+  }
+  const reduceRows = async <R>(
+    initial: R,
+    reducer: (accumulator: R, row: T, index: number) => TableSummaryAwaitable<R>
+  ) => {
+    let accumulator = initial
+    for (let index = 0; index < rows.length; index += 1) {
+      if (signal.aborted) throw signal.reason
+      const pending = reducer(accumulator, rows[index]!, index)
+      accumulator = isPromiseLike(pending) ? await pending : pending
+      if ((index + 1) % TABLE_TASK_YIELD_INTERVAL === 0) {
+        await yieldTableMainThread()
+        if (signal.aborted) throw signal.reason
+      }
+    }
+    return accumulator
+  }
+  return {
+    signal,
+    rowCount: rows.length,
+    reduceRows,
+    forEachRow: visitRows,
+  }
+}
+
+const calculateColumn = async <T extends TableRow>(
+  rows: readonly T[],
+  column: TableSummaryColumn<T>,
+  signal: AbortSignal
+) => {
+  // custom 完全交给调用方，其余内置操作统一使用 Decimal 精确十进制实现。
+  if (column.operation === 'custom') {
+    const columnKey = column.key
+    const aggregate = column.aggregate
+    if (typeof aggregate !== 'function') {
+      throw new Error(
+        `[TableComponent] Summary column "${String(columnKey)}" requires aggregate().`
+      )
+    }
+    const value = await aggregate(
+      createSummaryAggregateContext(rows, signal),
+      column
+    )
+    if (signal.aborted) throw signal.reason
+    return value
+  }
+  if (column.operation === 'count') {
+    let count = 0
+    for (let index = 0; index < rows.length; index += 1) {
+      if (signal?.aborted) throw signal.reason
+      const row = rows[index]!
+      const raw = column.value
+        ? column.value(row)
+        : getTableRowValue(row, column.key)
+      count += countSummaryValue(raw)
+      if ((index + 1) % TABLE_TASK_YIELD_INTERVAL === 0)
+        await yieldTableMainThread()
+    }
+    return count
+  }
+  let count = 0
+  let sum = new TableDecimal(0)
+  let target: TableDecimalInstance | undefined
+  for (let rowIndex = 0; rowIndex < rows.length; rowIndex += 1) {
+    const row = rows[rowIndex]!
+    if (rowIndex % 256 === 0 && signal?.aborted) throw signal.reason
+    const raw = column.value
+      ? column.value(row)
+      : getTableRowValue(row, column.key)
+    const values = Array.isArray(raw) ? raw : [raw]
+    values.forEach((value) => {
+      const decimal = parseTableDecimal(value)
+      if (!decimal) return
+      count += 1
+      if (column.operation === 'min' || column.operation === 'max') {
+        target = target
+          ? selectSummaryDecimal(column.operation, target, decimal)
+          : decimal
+      } else {
+        sum = sum.plus(decimal)
+      }
+    })
+    if ((rowIndex + 1) % TABLE_TASK_YIELD_INTERVAL === 0)
+      await yieldTableMainThread()
+  }
+  if (!count) return column.operation === 'sum' ? '0' : null
+  if (column.operation === 'min' || column.operation === 'max') {
+    return tableDecimalToString(target!)
+  }
+  return column.operation === 'avg'
+    ? tableDecimalToString(
+        roundTableDecimal(
+          sum.div(count),
+          column.precision ?? TABLE_DEFAULT_AVERAGE_PRECISION
+        )
+      )
+    : tableDecimalToString(sum)
+}
+
+const formatValues = <T extends TableRow>(
+  values: Record<string, unknown>,
+  columns: readonly TableSummaryColumn<T>[]
+) =>
+  Object.fromEntries(
+    columns.map((column) => {
+      const key = String(column.key)
+      const value = values[key]
+      return [key, column.format ? column.format(value, column) : value]
+    })
+  )
+
+/**
+ * 按 page/selection/all 范围执行汇总。
+ *
+ * 当前数据完整时使用 Decimal 精确十进制算法；远程全量或跨页选择必须交给 provider，
+ * 不允许用当前页数据伪装全量合计。
+ */
+export const runTableSummary = async <T extends TableRow>(
+  options: RunTableSummaryOptions<T>
+): Promise<TableSummaryResult> => {
+  if (options.signal?.aborted) throw options.signal.reason
+  const requiresRemote =
+    (options.scope === 'all' && options.remote) ||
+    (options.scope === 'selection' &&
+      !isSelectionFullyLoaded(options.selection))
+  if (requiresRemote) {
+    if (!options.provider) {
+      throw new TableSummaryProviderRequiredError(options.scope)
+    }
+    const signal = options.signal ?? new AbortController().signal
+    const response = await options.provider(
+      {
+        tableKey: options.tableKey,
+        scope: options.scope as 'selection' | 'all',
+        query: options.query,
+        selection: serializeSelection(options.selection),
+        columns: options.columns.map((column) => ({
+          key: String(column.key),
+          operation: column.operation,
+          precision: column.precision,
+        })),
+        locale: options.locale,
+        timeZone: options.timeZone,
+      },
+      { signal }
+    )
+    if (signal.aborted) throw signal.reason
+    const values = response.values
+    return {
+      scope: options.scope,
+      source: 'remote',
+      values,
+      formattedValues: formatValues(values, options.columns),
+    }
+  }
+
+  // 显式选择只有在全部键都已加载时才会进入本地分支。
+  const rows =
+    options.scope === 'selection'
+      ? [...options.selection.loadedRows.values()]
+      : options.rows
+  const values: Record<string, unknown> = {}
+  const signal = options.signal ?? new AbortController().signal
+  for (const column of options.columns) {
+    if (signal.aborted) throw signal.reason
+    const value = await calculateColumn(rows, column, signal)
+    if (signal.aborted) throw signal.reason
+    values[String(column.key)] = value
+  }
+  return {
+    scope: options.scope,
+    source: 'local',
+    values,
+    formattedValues: formatValues(values, options.columns),
+  }
+}

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

@@ -0,0 +1 @@
+export * from './transfer'

package/template/src/components/AppTable/engine/table/clipboard/transfer.ts

@@ -0,0 +1,9 @@
+/** 单列复制、粘贴与自动填充策略。 */
+export interface TableTransferConfig {
+  /** 限制该列只能粘贴同一个表格实例复制出来的数据。 */
+  pasteSource?: 'any' | 'same-table'
+  /** 要求复制源和粘贴目标覆盖完全相同的可视列范围。 */
+  pasteShape?: 'any' | 'same-columns'
+  /** 粘贴或自动填充时，把源行的这些关联字段放入同一变更事务。 */
+  synchronizedFields?: readonly string[]
+}