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

package/template/src/components/AppTable/engine/cell/formula.ts

@@ -0,0 +1,145 @@
+import {
+  createTableDecimalContext,
+  roundTableDecimal,
+  type TableDecimalInstance,
+} from '../shared/decimal'
+import {
+  TABLE_ENGINE_MESSAGES_ZH_CN,
+  type TableEngineMessages,
+} from '../shared/messages'
+
+export interface TableFormulaInputOptions {
+  /** 除法等非整数结果保留的小数位数，默认 16 位。 */
+  precision?: number
+  /** 计算结果写回字符串以保留精度，或显式转换为 number；默认 string。 */
+  output?: 'string' | 'number'
+}
+
+const normalizeExpression = (expression: string) =>
+  expression
+    .replace(/[（]/g, '(')
+    .replace(/[）]/g, ')')
+    .replace(/[＋]/g, '+')
+    .replace(/[－]/g, '-')
+    .replace(/[×＊]/g, '*')
+    .replace(/[÷／]/g, '/')
+
+const evaluate = (source: string, messages: TableEngineMessages) => {
+  const expression = normalizeExpression(source)
+  if (!expression.trim()) throw new Error(messages.strFormulaRequired)
+  if (expression.length > 256) throw new Error(messages.strFormulaTooLong)
+  const ExactDecimal = createTableDecimalContext({
+    precision: 80,
+    maxExponent: 1000,
+  })
+  let index = 0
+  const skipSpaces = () => {
+    while (/\s/.test(expression[index] ?? '')) index++
+  }
+  const match = (operator: string) => {
+    skipSpaces()
+    if (expression[index] !== operator) return false
+    index++
+    return true
+  }
+
+  const primary = (): TableDecimalInstance => {
+    skipSpaces()
+    if (match('(')) {
+      const value = sum()
+      if (!match(')')) throw new Error(messages.strFormulaParentheses)
+      return value
+    }
+    const literal = expression
+      .slice(index)
+      .match(/^(?:\d+(?:\.\d*)?|\.\d+)(?:e[+-]?\d+)?/i)?.[0]
+    if (!literal) {
+      throw new Error(messages.fnFormulaInvalidCharacter(index + 1))
+    }
+    const exponent = Number(literal.toLowerCase().split('e')[1] ?? 0)
+    if (!Number.isInteger(exponent) || Math.abs(exponent) > 1000) {
+      throw new Error(messages.strFormulaExponentRange)
+    }
+    index += literal.length
+    return new ExactDecimal(literal)
+  }
+
+  const unary = (): TableDecimalInstance => {
+    if (match('+')) return unary()
+    if (match('-')) return unary().negated()
+    return primary()
+  }
+
+  const power = (): TableDecimalInstance => {
+    const base = unary()
+    if (!match('^')) return base
+    const exponent = power()
+    if (
+      !exponent.isInteger() ||
+      exponent.lessThan(-100) ||
+      exponent.greaterThan(100)
+    ) {
+      throw new Error(messages.strFormulaPowerRange)
+    }
+    if (base.isZero() && exponent.isNegative())
+      throw new Error(messages.strFormulaDivisionByZero)
+    return base.pow(exponent.toNumber())
+  }
+
+  const product = (): TableDecimalInstance => {
+    let value = power()
+    while (true) {
+      if (match('*')) value = value.times(power())
+      else if (match('/')) {
+        const divisor = power()
+        if (divisor.isZero()) {
+          throw new Error(messages.strFormulaDivisionByZero)
+        }
+        value = value.dividedBy(divisor)
+      } else if (match('%')) {
+        const divisor = power()
+        if (divisor.isZero()) {
+          throw new Error(messages.strFormulaDivisionByZero)
+        }
+        value = value.modulo(divisor)
+      } else return value
+    }
+  }
+
+  function sum(): TableDecimalInstance {
+    let value = product()
+    while (true) {
+      if (match('+')) value = value.plus(product())
+      else if (match('-')) value = value.minus(product())
+      else return value
+    }
+  }
+
+  const result = sum()
+  skipSpaces()
+  if (index !== expression.length) {
+    throw new Error(messages.fnFormulaInvalidCharacter(index + 1))
+  }
+  if (!result.isFinite()) throw new Error(messages.strFormulaResultRange)
+  return result
+}
+
+/** 计算显式启用的算术公式，不使用 eval，也不支持变量或函数。 */
+export const parseTableFormulaInput = (
+  value: unknown,
+  options: TableFormulaInputOptions = {},
+  messages: TableEngineMessages = TABLE_ENGINE_MESSAGES_ZH_CN
+) => {
+  if (typeof value !== 'string' || !value.trimStart().startsWith('=')) {
+    return value
+  }
+  const precision = Math.min(30, Math.max(0, options.precision ?? 16))
+  const result = roundTableDecimal(
+    evaluate(value.trimStart().slice(1), messages),
+    precision
+  ).toFixed()
+  if (options.output !== 'number') return result
+  const number = Number(result)
+  if (!Number.isFinite(number)) throw new Error(messages.strFormulaUnsafeNumber)
+  return number
+}

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

@@ -0,0 +1,7 @@
+export * from './options'
+export * from './multiSelect'
+export * from './formula'
+export * from './formatting'
+export * from './customCell'
+export * from './types'
+export * from './constants'

package/template/src/components/AppTable/engine/cell/multiSelect.ts

@@ -0,0 +1,96 @@
+import {
+  TABLE_ENGINE_MESSAGES_ZH_CN,
+  type TableEngineMessages,
+} from '../shared/messages'
+import type { TableRow } from '../shared/types'
+import type { TableOptionSource } from './options'
+
+export type TableMultiSelectEngine = 'auto' | 'native' | 'layer'
+
+export interface TableMultiSelectConfig {
+  /** 自动模式仅在数据源为静态基本类型时使用 v18 原生实现。 */
+  engine?: TableMultiSelectEngine
+  /** 最多允许选择的条目数，必须是正整数。 */
+  maxSelections?: number
+  /** 是否在下拉面板中显示搜索输入框。 */
+  searchInput?: boolean
+  /** 未选择值时的占位文案。 */
+  placeholder?: string
+  /** 出现滚动条前最多展示的候选行数，必须是正整数。 */
+  visibleRows?: number
+  /** 是否允许 Enter 直接提交当前选择。 */
+  enterCommits?: boolean
+  /** 搜索过滤是否区分大小写。 */
+  filteringCaseSensitive?: boolean
+  /** 对原生多选候选项进行稳定排序的函数。 */
+  sourceSortFunction?: (entries: unknown[]) => unknown[]
+  /** 单元格浮层使用的展示选项。 */
+  collapseTags?: boolean
+  /** 折叠前最多展示的标签数量，必须是正整数。 */
+  maxCollapseTags?: number
+}
+
+interface ResolvedTableMultiSelectConfig extends Omit<
+  TableMultiSelectConfig,
+  'engine'
+> {
+  /** auto 解析后的实际引擎。 */
+  engine: Exclude<TableMultiSelectEngine, 'auto'>
+}
+
+export const isPrimitiveTableOptionSource = <T extends TableRow>(
+  source?: TableOptionSource<T>
+): source is readonly (string | number)[] =>
+  Array.isArray(source) &&
+  source.every(
+    (option) => typeof option === 'string' || typeof option === 'number'
+  )
+
+const requirePositiveInteger = (value: number | undefined, name: string) => {
+  if (value !== undefined && (!Number.isInteger(value) || value < 1)) {
+    throw new Error(
+      `[TableComponent] MultiSelect ${name} must be a positive integer.`
+    )
+  }
+}
+
+export const resolveTableMultiSelectConfig = <T extends TableRow>(
+  source?: TableOptionSource<T>,
+  config: TableMultiSelectConfig = {}
+): ResolvedTableMultiSelectConfig => {
+  requirePositiveInteger(config.maxSelections, 'maxSelections')
+  requirePositiveInteger(config.visibleRows, 'visibleRows')
+  requirePositiveInteger(config.maxCollapseTags, 'maxCollapseTags')
+  const supportsNative = isPrimitiveTableOptionSource(source)
+  if (config.engine === 'native' && !supportsNative) {
+    throw new Error(
+      '[TableComponent] Native MultiSelect requires a static string/number options array. Use layer mode for label/value options or remote loaders.'
+    )
+  }
+  return {
+    ...config,
+    engine:
+      config.engine === 'auto' || config.engine === undefined
+        ? supportsNative
+          ? 'native'
+          : 'layer'
+        : config.engine,
+  }
+}
+
+export const validateTableMultiSelectValue = (
+  value: unknown,
+  config: TableMultiSelectConfig = {},
+  messages: TableEngineMessages = TABLE_ENGINE_MESSAGES_ZH_CN
+): true | string => {
+  requirePositiveInteger(config.maxSelections, 'maxSelections')
+  if (value === null || value === undefined || value === '') return true
+  if (!Array.isArray(value)) return messages.strMultiSelectArrayRequired
+  if (
+    config.maxSelections !== undefined &&
+    value.length > config.maxSelections
+  ) {
+    return messages.fnMultiSelectLimit(config.maxSelections)
+  }
+  return true
+}

package/template/src/components/AppTable/engine/cell/options.ts

@@ -0,0 +1,339 @@
+import {
+  TABLE_ENGINE_MESSAGES_ZH_CN,
+  type TableEngineMessages,
+} from '../shared/messages'
+import type { TableOption, TableRow } from '../shared/types'
+import { TABLE_CELL_DEFAULTS } from './constants'
+
+export interface TableOptionLoaderContext<T extends TableRow = TableRow> {
+  /** 当前表格稳定 key。 */
+  tableKey: string
+  /** 当前选项列稳定 key。 */
+  columnKey: string
+  /** 当前单元格对应的业务行。 */
+  row: T
+  /** 用户输入的远程搜索文本。 */
+  query: string
+  /** 新请求、关闭编辑器或销毁实例时会中止的信号。 */
+  signal: AbortSignal
+  /** 当前选项协调器单调递增的请求编号。 */
+  requestId: number
+}
+
+export type TablePrimitiveOption = string | number
+export type TableOptionInput = TableOption | TablePrimitiveOption
+
+export type TableOptionLoader<T extends TableRow = TableRow> = (
+  context: TableOptionLoaderContext<T>
+) => readonly TableOptionInput[] | Promise<readonly TableOptionInput[]>
+
+export type TableOptionSource<T extends TableRow = TableRow> =
+  | readonly TableOptionInput[]
+  | TableOptionLoader<T>
+
+interface TableSelectValidationOptions {
+  /** 是否允许空值，默认 true。 */
+  clearable?: boolean
+  /** 是否接受静态选项表中不存在的历史值。 */
+  allowUnknownValue?: boolean
+}
+
+export interface TableOptionCacheContext<T extends TableRow = TableRow> {
+  /** 当前表格稳定 key。 */
+  tableKey: string
+  /** 当前选项列稳定 key。 */
+  columnKey: string
+  /** 当前业务行。 */
+  row: T
+  /** 当前远程搜索文本。 */
+  query: string
+}
+
+export interface TableOptionCacheConfig<T extends TableRow = TableRow> {
+  /** 缓存存活毫秒数，默认 60 秒。 */
+  ttlMs?: number
+  /** 实例级最大缓存条目数，默认 100。 */
+  maxEntries?: number
+  /** 自定义缓存 key；可把行级依赖字段纳入缓存隔离。 */
+  key?: (context: TableOptionCacheContext<T>) => string
+}
+
+export type TableOptionCachePolicy<T extends TableRow = TableRow> =
+  | boolean
+  | TableOptionCacheConfig<T>
+
+interface TableOptionLoadRequest<T extends TableRow = TableRow> {
+  /** 需要加载选项的列 key。 */
+  columnKey: string
+  /** 当前业务行。 */
+  row: T
+  /** 当前搜索文本，默认空字符串。 */
+  query?: string
+  /** 静态或远程选项源。 */
+  source: TableOptionSource<T>
+  /** 本次请求的缓存策略。 */
+  cache?: TableOptionCachePolicy<T>
+  /** 调用方提供的取消信号。 */
+  signal?: AbortSignal
+}
+
+export interface TableOptionLoadResult {
+  /** 已规范化为 label/value 结构的选项。 */
+  options: TableOption[]
+  /** 本次加载的请求编号。 */
+  requestId: number
+  /** 数据来自静态声明、loader 还是缓存。 */
+  source: 'static' | 'loader' | 'cache'
+}
+
+interface TableOptionCoordinatorOptions {
+  /** 当前表格稳定 key。 */
+  tableKey: string
+  /** 未在列上指定时使用的缓存存活毫秒数。 */
+  defaultTtlMs?: number
+  /** 未在列上指定时使用的最大缓存条目数。 */
+  defaultMaxEntries?: number
+  /** 每列最多记忆的 value-label 映射数量。 */
+  maxRememberedOptionsPerColumn?: number
+  /** 注入时间函数，主要用于确定性测试。 */
+  now?: () => number
+}
+
+interface CacheEntry {
+  columnKey: string
+  expiresAt: number
+  options: TableOption[]
+}
+
+const requirePositive = (value: number, name: string) => {
+  if (!Number.isFinite(value) || value <= 0) {
+    throw new Error(`[TableComponent] ${name} must be a positive number.`)
+  }
+  return value
+}
+
+const cloneOptions = (options: readonly TableOption[]) =>
+  options.map((option) => ({ ...option }))
+
+function assertOptions(
+  value: unknown
+): asserts value is readonly TableOptionInput[] {
+  if (!Array.isArray(value)) {
+    throw new Error('[TableComponent] An option loader must return an array.')
+  }
+  value.forEach((option) => {
+    if (typeof option === 'string' || typeof option === 'number') return
+    if (!option || typeof option !== 'object' || !('value' in option)) {
+      throw new Error(
+        '[TableComponent] Every option must be a string, number, or label/value object.'
+      )
+    }
+    if (!('label' in option)) {
+      throw new Error(
+        '[TableComponent] Every option must be a string, number, or label/value object.'
+      )
+    }
+  })
+}
+
+export const normalizeTableOptions = (value: unknown): TableOption[] => {
+  assertOptions(value)
+  return value.map((option) =>
+    typeof option === 'string' || typeof option === 'number'
+      ? { label: String(option), value: option }
+      : { ...option }
+  )
+}
+
+/** 校验静态下拉值，不让数据变更逻辑耦合具体 UI 适配器。 */
+export const validateTableSelectValue = <T extends TableRow>(
+  value: unknown,
+  source: TableOptionSource<T> | undefined,
+  options: TableSelectValidationOptions = {},
+  messages: TableEngineMessages = TABLE_ENGINE_MESSAGES_ZH_CN
+): true | string => {
+  if (value === undefined || value === null || value === '') {
+    return options.clearable === false ? messages.strSelectClearForbidden : true
+  }
+  if (options.allowUnknownValue || typeof source === 'function') return true
+  const option = normalizeTableOptions(source ?? []).find((item) =>
+    Object.is(item.value, value)
+  )
+  if (!option) return messages.strSelectValueUnknown
+  return option.disabled ? messages.strSelectOptionDisabled : true
+}
+
+const throwIfAborted = (signal?: AbortSignal) => {
+  if (!signal?.aborted) return
+  throw signal.reason ?? new DOMException('Aborted', 'AbortError')
+}
+
+/** 框架无关的远程或静态选项加载器，可按需启用 LRU 缓存。 */
+class TableOptionCoordinator {
+  private requestId = 0
+  private readonly cache = new Map<string, CacheEntry>()
+  private readonly optionIndexes = new Map<string, Map<unknown, TableOption>>()
+  private readonly now: () => number
+  private readonly defaultTtlMs: number
+  private readonly defaultMaxEntries: number
+  private readonly maxRememberedOptionsPerColumn: number
+
+  constructor(readonly options: TableOptionCoordinatorOptions) {
+    if (!options.tableKey.trim()) {
+      throw new Error('[TableComponent] OptionCoordinator requires tableKey.')
+    }
+    this.now = options.now ?? Date.now
+    this.defaultTtlMs = requirePositive(
+      options.defaultTtlMs ?? TABLE_CELL_DEFAULTS.optionCacheTtlMs,
+      'defaultTtlMs'
+    )
+    this.defaultMaxEntries = requirePositive(
+      options.defaultMaxEntries ?? TABLE_CELL_DEFAULTS.cacheEntries,
+      'defaultMaxEntries'
+    )
+    this.maxRememberedOptionsPerColumn = requirePositive(
+      options.maxRememberedOptionsPerColumn ??
+        TABLE_CELL_DEFAULTS.rememberedOptionsPerColumn,
+      'maxRememberedOptionsPerColumn'
+    )
+  }
+
+  get currentRequestId() {
+    return this.requestId
+  }
+
+  remember(columnKey: string, options: readonly TableOption[]) {
+    const index = this.optionIndexes.get(columnKey) ?? new Map()
+    options.forEach((option) => {
+      index.delete(option.value)
+      index.set(option.value, { ...option })
+      while (index.size > this.maxRememberedOptionsPerColumn) {
+        const oldest = index.keys().next().value
+        if (oldest === undefined) break
+        index.delete(oldest)
+      }
+    })
+    this.optionIndexes.set(columnKey, index)
+  }
+
+  getOption(columnKey: string, value: unknown) {
+    return this.optionIndexes.get(columnKey)?.get(value)
+  }
+
+  private resolveCache<T extends TableRow>(
+    request: TableOptionLoadRequest<T>,
+    query: string
+  ) {
+    if (!request.cache) return null
+    const config = typeof request.cache === 'object' ? request.cache : {}
+    const context: TableOptionCacheContext<T> = {
+      tableKey: this.options.tableKey,
+      columnKey: request.columnKey,
+      row: request.row,
+      query,
+    }
+    const suffix = config.key?.(context) ?? query
+    if (!suffix && config.key) {
+      throw new Error('[TableComponent] option cache key cannot be empty.')
+    }
+    return {
+      key: `${request.columnKey}\u0000${suffix}`,
+      ttlMs: requirePositive(config.ttlMs ?? this.defaultTtlMs, 'ttlMs'),
+      maxEntries: requirePositive(
+        config.maxEntries ?? this.defaultMaxEntries,
+        'maxEntries'
+      ),
+    }
+  }
+
+  private readCache(key: string) {
+    const entry = this.cache.get(key)
+    if (!entry) return undefined
+    if (entry.expiresAt <= this.now()) {
+      this.cache.delete(key)
+      return undefined
+    }
+    this.cache.delete(key)
+    this.cache.set(key, entry)
+    return cloneOptions(entry.options)
+  }
+
+  private writeCache(
+    key: string,
+    columnKey: string,
+    options: readonly TableOption[],
+    ttlMs: number,
+    maxEntries: number
+  ) {
+    this.cache.delete(key)
+    this.cache.set(key, {
+      columnKey,
+      expiresAt: this.now() + ttlMs,
+      options: cloneOptions(options),
+    })
+    while (this.cache.size > maxEntries) {
+      const oldest = this.cache.keys().next().value
+      if (oldest === undefined) break
+      this.cache.delete(oldest)
+    }
+  }
+
+  async load<T extends TableRow>(
+    request: TableOptionLoadRequest<T>
+  ): Promise<TableOptionLoadResult> {
+    const requestId = ++this.requestId
+    const query = request.query?.trim() ?? ''
+    throwIfAborted(request.signal)
+
+    if (typeof request.source !== 'function') {
+      const options = normalizeTableOptions(request.source)
+      this.remember(request.columnKey, options)
+      return { options, requestId, source: 'static' }
+    }
+
+    const cache = this.resolveCache(request, query)
+    const cached = cache ? this.readCache(cache.key) : undefined
+    if (cached) {
+      this.remember(request.columnKey, cached)
+      return { options: cached, requestId, source: 'cache' }
+    }
+
+    const options = await request.source({
+      tableKey: this.options.tableKey,
+      columnKey: request.columnKey,
+      row: request.row,
+      query,
+      signal: request.signal ?? new AbortController().signal,
+      requestId,
+    })
+    throwIfAborted(request.signal)
+    const cloned = normalizeTableOptions(options)
+    this.remember(request.columnKey, cloned)
+    if (cache) {
+      this.writeCache(
+        cache.key,
+        request.columnKey,
+        cloned,
+        cache.ttlMs,
+        cache.maxEntries
+      )
+    }
+    return { options: cloned, requestId, source: 'loader' }
+  }
+
+  clear(columnKey?: string) {
+    if (!columnKey) {
+      this.cache.clear()
+      this.optionIndexes.clear()
+      return
+    }
+    for (const [key, entry] of this.cache) {
+      if (entry.columnKey === columnKey) this.cache.delete(key)
+    }
+    this.optionIndexes.delete(columnKey)
+  }
+}
+
+export const createTableOptionCoordinator = (
+  options: TableOptionCoordinatorOptions
+) => new TableOptionCoordinator(options)

package/template/src/components/AppTable/engine/cell/types.ts

@@ -0,0 +1,53 @@
+import type Handsontable from 'handsontable'
+import type { TableRow } from '../shared/types'
+
+/** 单元格业务回调上下文，同时保留 visual/physical 坐标。 */
+export interface TableCellContext<
+  T extends TableRow = TableRow,
+  TValue = unknown,
+> {
+  /** 当前物理行对应的业务 DTO。 */
+  row: T
+  /** 兼容旧回调的可视行号，等同 visualRow。 */
+  rowIndex: number
+  /** 排序、筛选后的可视行下标。 */
+  visualRow: number
+  /** 列移动、隐藏后的可视列下标。 */
+  visualColumn: number
+  /** 排序、筛选前的稳定源行下标。 */
+  physicalRow: number
+  /** 原始列定义中的物理列下标。 */
+  physicalColumn: number
+  /** 兼容自定义单元格回调的当前可视列下标。 */
+  columnIndex: number
+  /** 当前单元格原始值或经泛型收窄后的值。 */
+  value: TValue
+  /** 原始 Handsontable Core 实例，适配层不得使用响应式代理。 */
+  instance: Handsontable
+}
+
+/** 操作列按钮和下拉菜单共享的业务动作合同。 */
+export interface TableAction<T extends TableRow = TableRow> {
+  /** 稳定唯一 key，也用于“更多”菜单命令定位。 */
+  key: string
+  /** 静态或按行计算的按钮文案。 */
+  label: string | ((context: TableCellContext<T>) => string)
+  /** 按钮语义色，默认 primary。 */
+  type?: 'primary' | 'success' | 'warning' | 'danger' | 'info'
+  /** 图标 CSS 类名。 */
+  icon?: string
+  /** 按钮尺寸，默认 default。 */
+  size?: 'small' | 'default' | 'large'
+  /** 追加到按钮和菜单项的业务样式类。 */
+  className?: string
+  /** 静态或按行计算的原生 title 提示。 */
+  title?: string | ((context: TableCellContext<T>) => string)
+  /** 静态或按行计算的禁用状态。 */
+  disabled?: boolean | ((context: TableCellContext<T>) => boolean)
+  /** 静态或按行计算的隐藏状态。 */
+  hidden?: boolean | ((context: TableCellContext<T>) => boolean)
+  /** 将该动作声明为整张表唯一的行双击默认动作。 */
+  rowDoubleClick?: boolean
+  /** 点击按钮或“更多”菜单项时执行的业务回调。 */
+  onClick: (context: TableCellContext<T>) => void | Promise<void>
+}