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

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

@@ -0,0 +1,58 @@
+/** engine 可处理的最小行数据合同；业务项目通常用自己的行接口替换默认类型。 */
+export type TableRow = object
+
+export interface TableGridCoordinate {
+  /** 排序、筛选后的可视行下标。 */
+  visualRow: number
+  /** 源数据中的稳定物理行下标。 */
+  physicalRow: number
+  /** 列移动、隐藏后的可视列下标。 */
+  visualColumn: number
+  /** 原始列定义中的物理列下标。 */
+  physicalColumn: number
+}
+
+/** engine 与 React 层共享的行点击上下文。 */
+export interface TableRowInteractionContext<
+  T extends TableRow = TableRow,
+> extends TableGridCoordinate {
+  /** 当前交互对应的后端业务行对象。 */
+  row: T
+  /** 兼容业务常用命名，值与 physicalRow 一致。 */
+  rowIndex: number
+  /** 点击的数据列 key；行头等非数据区域可能为空。 */
+  columnKey?: string
+  /** 当前单元格是否只读。 */
+  readOnly: boolean
+  /** Handsontable 交互产生的原始鼠标事件。 */
+  event: MouseEvent
+}
+
+export interface TableSelectionRangeContext {
+  /** 选区起点的可视与物理坐标。 */
+  start: TableGridCoordinate
+  /** 选区终点的可视与物理坐标。 */
+  end: TableGridCoordinate
+}
+
+/**
+ * 表格可配置字段键。
+ *
+ * 业务传入明确 DTO 时收窄为 DTO 的字符串字段；使用默认 `TableRow` 或运行时 Schema
+ * 时仍回退为 string，兼顾字段拼写检查与动态列能力。
+ */
+export type TableKeyOf<T extends TableRow> = [
+  Extract<keyof T, string>,
+] extends [never]
+  ? string
+  : Extract<keyof T, string>
+
+/** 搜索控件和单元格选择器共享的标签值选项。 */
+export interface TableOption<TValue = unknown> {
+  /** 下拉面板中展示的业务文案。 */
+  label: string
+  /** 写入后端 DTO 的原始值。 */
+  value: TValue
+  /** 是否禁止选择该选项。 */
+  disabled?: boolean
+}

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

@@ -0,0 +1,46 @@
+const cloneValue = <T>(value: T, seen: WeakMap<object, unknown>): T => {
+  if (
+    (typeof value !== 'object' && typeof value !== 'function') ||
+    value === null
+  )
+    return value
+  if (typeof value === 'function') return value
+  const existing = seen.get(value)
+  if (existing) return existing as T
+  if (value instanceof Date) return new Date(value.getTime()) as T
+  if (value instanceof RegExp) return new RegExp(value.source, value.flags) as T
+  if (Array.isArray(value)) {
+    const result: unknown[] = []
+    seen.set(value, result)
+    value.forEach((item) => result.push(cloneValue(item, seen)))
+    return result as T
+  }
+  if (value instanceof Map) {
+    const result = new Map()
+    seen.set(value, result)
+    value.forEach((item, key) =>
+      result.set(cloneValue(key, seen), cloneValue(item, seen))
+    )
+    return result as T
+  }
+  if (value instanceof Set) {
+    const result = new Set()
+    seen.set(value, result)
+    value.forEach((item) => result.add(cloneValue(item, seen)))
+    return result as T
+  }
+  const result = Object.create(Object.getPrototypeOf(value)) as object
+  seen.set(value, result)
+  Reflect.ownKeys(value).forEach((key) => {
+    const descriptor = Object.getOwnPropertyDescriptor(value, key)
+    if (!descriptor) return
+    if ('value' in descriptor)
+      descriptor.value = cloneValue(descriptor.value, seen)
+    Object.defineProperty(result, key, descriptor)
+  })
+  return result as T
+}
+
+/** 创建不共享子对象的通用值快照，供查询意图、保存事务和编辑基线复用。 */
+export const cloneTableValue = <T>(value: T): T =>
+  cloneValue(value, new WeakMap())

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

@@ -0,0 +1,117 @@
+import { resolveColumnFormat, type TableValueFormat } from '../../cell'
+import type { TableColumn } from '../../columns'
+import type { TablePreference } from '../../preference'
+import type { TableRow } from '../../shared'
+import type {
+  TableExportColumn,
+  TableExportFormat,
+  TableExportScope,
+} from '../export'
+import type {
+  ResolvedTableExportConfig,
+  TableExportAction,
+  TableExportConfig,
+} from './types'
+
+const TABLE_EXPORT_SCOPE_LABEL: Record<TableExportScope, string> = {
+  range: '选中区域',
+  page: '当前页',
+  selection: '已选数据',
+  all: '全部数据',
+}
+
+interface ResolveTableExportConfigOptions<T extends TableRow> {
+  remote: boolean
+  defaultXlsxWriter?: ResolvedTableExportConfig<T>['xlsxWriter']
+  locale?: string
+  timeZone?: string
+}
+
+/** 解析导出能力、后端范围和格式默认值；false 明确返回 null。 */
+export const resolveTableExportConfig = <T extends TableRow>(
+  config: TableExportConfig<T> | false | undefined,
+  options: ResolveTableExportConfigOptions<T>
+): ResolvedTableExportConfig<T> | null => {
+  if (config === false) return null
+  const source = config ?? {}
+  const defaultScopes: TableExportScope[] = ['page', 'selection']
+  if (!options.remote || source.provider) defaultScopes.push('all')
+  return {
+    provider: source.provider,
+    xlsxWriter: source.xlsxWriter ?? options.defaultXlsxWriter,
+    fileName: source.fileName,
+    sheetName: source.sheetName,
+    formats: [
+      ...new Set(
+        source.formats ?? (['csv', 'xlsx'] satisfies TableExportFormat[])
+      ),
+    ],
+    scopes: [...new Set(source.scopes ?? defaultScopes)],
+    locale: source.locale ?? options.locale,
+    timeZone: source.timeZone ?? options.timeZone,
+  }
+}
+
+/** 将可见业务列编译为导出列，操作按钮列不会进入文件。 */
+export const buildTableExportColumns = <T extends TableRow>(
+  columns: readonly TableColumn<T>[],
+  preference: Pick<TablePreference, 'columnWidths'>,
+  formatValue: (value: unknown, format: TableValueFormat) => unknown
+): TableExportColumn<T>[] =>
+  columns
+    .filter(
+      (column) => column.renderer !== 'button' && column.exportable !== false
+    )
+    .map((column) => {
+      const displayFormat = resolveColumnFormat(column)
+      return {
+        key: column.key,
+        label: column.label,
+        width:
+          preference.columnWidths[String(column.key)] ??
+          (typeof column.width === 'number' ? column.width : undefined),
+        format: column.formatter
+          ? (value, row, rowIndex) => column.formatter?.(value, row, rowIndex)
+          : displayFormat
+            ? (value) => formatValue(value, displayFormat)
+            : undefined,
+      }
+    })
+
+interface BuildTableExportActionsOptions<T extends TableRow> {
+  config: ResolvedTableExportConfig<T> | null
+  remote: boolean
+  hasSelection: boolean
+  selectionFullyLoaded: boolean
+  /** 各导出范围的展示文案；省略时保留中文兼容默认值。 */
+  scopeLabels?: Readonly<Record<TableExportScope, string>>
+}
+
+/** 根据远程范围、选择状态和 writer/provider 能力生成稳定操作列表。 */
+export const buildTableExportActions = <T extends TableRow>({
+  config,
+  remote,
+  hasSelection,
+  selectionFullyLoaded,
+  scopeLabels = TABLE_EXPORT_SCOPE_LABEL,
+}: BuildTableExportActionsOptions<T>): TableExportAction[] => {
+  if (!config) return []
+  return config.scopes.flatMap((scope) =>
+    config.formats.flatMap((format) => {
+      const remoteScope =
+        (scope === 'all' && remote) ||
+        (scope === 'selection' && !selectionFullyLoaded)
+      if (remoteScope && !config.provider) return []
+      if (format === 'xlsx' && !remoteScope && !config.xlsxWriter) return []
+      return [
+        {
+          key: `${scope}:${format}`,
+          label: `${scopeLabels[scope]} ${format.toUpperCase()}`,
+          scope,
+          format,
+          disabled: scope === 'selection' && !hasSelection,
+        },
+      ]
+    })
+  )
+}

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

@@ -0,0 +1,3 @@
+export * from './export'
+export * from './summary'
+export * from './types'

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

@@ -0,0 +1,62 @@
+import type { TableValueFormat } from '../../cell'
+import type { TableColumn } from '../../columns'
+import type { TableRow } from '../../shared/types'
+import type { TableSummaryColumn } from '../summary'
+import type { ResolvedTableSummaryConfig, TableSummaryConfig } from './types'
+
+interface ResolveTableSummaryConfigDefaults {
+  locale?: string
+  timeZone?: string
+  /** 未显式配置汇总标签时使用的本地化文案。 */
+  label?: string
+}
+
+/** 保留可判别联合的 operation，避免对象展开把 custom 合同重新拓宽。 */
+const cloneTableSummaryColumn = <T extends TableRow>(
+  column: TableSummaryColumn<T>
+): TableSummaryColumn<T> =>
+  column.operation === 'custom'
+    ? { ...column, operation: 'custom', aggregate: column.aggregate }
+    : { ...column, operation: column.operation }
+
+/** 解析汇总开关和稳定默认值；false 明确返回 null。 */
+export const resolveTableSummaryConfig = <T extends TableRow>(
+  config: TableSummaryConfig<T> | false | undefined,
+  defaults: ResolveTableSummaryConfigDefaults = {}
+): ResolvedTableSummaryConfig<T> | null => {
+  if (config === false) return null
+  const source = config ?? {}
+  return {
+    scope: source.scope ?? 'page',
+    label: source.label?.trim() || defaults.label || '合计',
+    columns: source.columns?.map(cloneTableSummaryColumn) ?? [],
+    provider: source.provider,
+    locale: source.locale ?? defaults.locale,
+    timeZone: source.timeZone ?? defaults.timeZone,
+  }
+}
+
+/** 从显式 summary columns 或业务列声明编译最终汇总字段。 */
+export const buildTableSummaryColumns = <T extends TableRow>(
+  config: ResolvedTableSummaryConfig<T> | null,
+  columns: readonly TableColumn<T>[],
+  formatValue: (value: unknown, format: TableValueFormat) => unknown
+): TableSummaryColumn<T>[] => {
+  if (!config) return []
+  if (config.columns.length) return config.columns.map(cloneTableSummaryColumn)
+  return columns.flatMap((column) => {
+    if (!column.summary) return []
+    const summaryColumn: TableSummaryColumn<T> = {
+      key: column.key,
+      label: column.label,
+      ...(typeof column.summary === 'string'
+        ? { operation: column.summary }
+        : column.summary),
+    }
+    const columnFormat = column.format
+    if (!summaryColumn.format && columnFormat) {
+      summaryColumn.format = (value) => formatValue(value, columnFormat)
+    }
+    return [summaryColumn]
+  })
+}

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

@@ -0,0 +1,93 @@
+import type { TableRow } from '../../shared/types'
+import type {
+  TableExportFormat,
+  TableExportProvider,
+  TableExportScope,
+  TableXlsxWriter,
+} from '../export'
+import type {
+  TableSummaryColumn,
+  TableSummaryProvider,
+  TableSummaryScope,
+} from '../summary'
+
+export interface TableSummaryConfig<T extends TableRow = TableRow> {
+  /** 默认汇总范围，page 为当前已加载页，all 为全部匹配数据。 */
+  scope?: TableSummaryScope
+  /** 表格底部汇总行的标签文案，默认“合计”。 */
+  label?: string
+  /** 显式汇总列；省略时从 TableColumn.summary 自动生成。 */
+  columns?: readonly TableSummaryColumn<T>[]
+  /** all 或无法本地完成的范围使用的后端汇总 provider。 */
+  provider?: TableSummaryProvider
+  /** 覆盖表格级区域语言。 */
+  locale?: string
+  /** 覆盖表格级 IANA 时区。 */
+  timeZone?: string
+}
+
+export interface ResolvedTableSummaryConfig<T extends TableRow = TableRow> {
+  /** 最终汇总范围。 */
+  scope: TableSummaryScope
+  /** 最终汇总行标签文案。 */
+  label: string
+  /** 编译后的汇总列列表。 */
+  columns: TableSummaryColumn<T>[]
+  /** 可选远程汇总 provider。 */
+  provider?: TableSummaryProvider
+  /** 最终区域语言。 */
+  locale?: string
+  /** 最终 IANA 时区。 */
+  timeZone?: string
+}
+
+export interface TableExportConfig<T extends TableRow = TableRow> {
+  /** 远程全量或未完整加载选择数据的导出 provider。 */
+  provider?: TableExportProvider
+  /** 本地 XLSX writer；由 React reporting 能力按需接入 ExcelJS。 */
+  xlsxWriter?: TableXlsxWriter<T>
+  /** 静态文件名或每次导出时计算的文件名。 */
+  fileName?: string | (() => string)
+  /** XLSX 工作表名称。 */
+  sheetName?: string
+  /** 允许用户选择的导出格式，默认 csv 和 xlsx。 */
+  formats?: readonly TableExportFormat[]
+  /** 允许用户选择的导出范围；远程能力会过滤缺少 provider 的范围。 */
+  scopes?: readonly TableExportScope[]
+  /** 覆盖表格级导出区域语言。 */
+  locale?: string
+  /** 覆盖表格级导出 IANA 时区。 */
+  timeZone?: string
+}
+
+export interface ResolvedTableExportConfig<T extends TableRow = TableRow> {
+  /** 最终远程导出 provider。 */
+  provider?: TableExportProvider
+  /** 最终本地 XLSX writer。 */
+  xlsxWriter?: TableXlsxWriter<T>
+  /** 最终文件名配置。 */
+  fileName?: string | (() => string)
+  /** 最终 XLSX 工作表名称。 */
+  sheetName?: string
+  /** 去重后的可用导出格式。 */
+  formats: TableExportFormat[]
+  /** 去重并经过能力过滤前的导出范围。 */
+  scopes: TableExportScope[]
+  /** 最终区域语言。 */
+  locale?: string
+  /** 最终 IANA 时区。 */
+  timeZone?: string
+}
+
+export interface TableExportAction {
+  /** 由范围和格式组成的稳定操作 key。 */
+  key: string
+  /** 导出菜单显示文案。 */
+  label: string
+  /** 本次导出数据范围。 */
+  scope: TableExportScope
+  /** 本次导出文件格式。 */
+  format: TableExportFormat
+  /** 当前选择状态下是否禁用该操作。 */
+  disabled?: boolean
+}

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

@@ -0,0 +1,13 @@
+export const TABLE_DEFAULT_SHEET_NAME = 'Sheet1'
+export const TABLE_CSV_MIME_TYPE = 'text/csv;charset=utf-8'
+export const TABLE_DEFAULT_AVERAGE_PRECISION = 6
+
+/** ExcelJS 输出约束与性能检查间隔。 */
+export const TABLE_EXCEL_DEFAULTS = {
+  abortCheckRowInterval: 250,
+  defaultColumnWidth: 16,
+  maxColumnWidth: 80,
+  minColumnWidth: 8,
+  pixelToCharacterRatio: 7,
+  sheetNameMaxLength: 31,
+} as const

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

@@ -0,0 +1,133 @@
+import type { Workbook as ExcelJsWorkbook } from 'exceljs'
+import { getTableRowValue } from '../shared/row'
+import { yieldTableMainThread } from '../shared/scheduler'
+import type { TableRow } from '../shared/types'
+import { TABLE_DEFAULT_SHEET_NAME, TABLE_EXCEL_DEFAULTS } from './constants'
+import { sanitizeSpreadsheetValue, type TableXlsxWriter } from './export'
+
+const XLSX_MIME =
+  'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet'
+
+interface TableExcelJsModule {
+  Workbook: typeof ExcelJsWorkbook
+}
+
+interface CreateExcelJsTableWriterOptions {
+  /** 测试或自定义运行时的替换入口；默认仍使用字面量动态导入。 */
+  loadExcelJs?: () => Promise<TableExcelJsModule>
+  creator?: string
+}
+
+const isTableExcelJsModule = (value: unknown): value is TableExcelJsModule =>
+  Boolean(
+    value &&
+    typeof value === 'object' &&
+    typeof Reflect.get(value, 'Workbook') === 'function'
+  )
+
+const loadExcelJs = async (): Promise<TableExcelJsModule> => {
+  const module = await import('exceljs')
+  const defaultModule = Reflect.get(module, 'default')
+  const candidate = isTableExcelJsModule(defaultModule) ? defaultModule : module
+  if (!isTableExcelJsModule(candidate)) {
+    throw new Error('[TableComponent] ExcelJS module has no Workbook export.')
+  }
+  return candidate
+}
+
+const throwIfAborted = (signal: AbortSignal) => {
+  if (signal.aborted) {
+    throw signal.reason ?? new DOMException('Export aborted', 'AbortError')
+  }
+}
+
+const normalizeTableSheetName = (sheetName: string) =>
+  sheetName
+    .replace(/[\\/*?:[\]]/g, ' ')
+    .trim()
+    .slice(0, TABLE_EXCEL_DEFAULTS.sheetNameMaxLength) ||
+  TABLE_DEFAULT_SHEET_NAME
+
+const normalizeCellValue = (value: unknown) => {
+  const safeValue = sanitizeSpreadsheetValue(value)
+  if (
+    safeValue === null ||
+    safeValue === undefined ||
+    typeof safeValue === 'string' ||
+    typeof safeValue === 'number' ||
+    typeof safeValue === 'boolean' ||
+    safeValue instanceof Date
+  ) {
+    return safeValue ?? null
+  }
+  try {
+    return JSON.stringify(safeValue)
+  } catch {
+    return String(safeValue)
+  }
+}
+
+export const createExcelJsTableWriter = <T extends TableRow = TableRow>(
+  options: CreateExcelJsTableWriterOptions = {}
+): TableXlsxWriter<T> => {
+  return async ({ rows, columns, sheetName, signal }) => {
+    throwIfAborted(signal)
+    const ExcelJs = await (options.loadExcelJs ?? loadExcelJs)()
+    throwIfAborted(signal)
+
+    const workbook = new ExcelJs.Workbook()
+    workbook.creator = options.creator ?? 'AppTable'
+    const worksheet = workbook.addWorksheet(normalizeTableSheetName(sheetName))
+    worksheet.views = [{ state: 'frozen', ySplit: 1 }]
+    worksheet.columns = columns.map((column) => ({
+      key: String(column.key),
+      width:
+        typeof column.width === 'number'
+          ? Math.max(
+              TABLE_EXCEL_DEFAULTS.minColumnWidth,
+              Math.min(
+                TABLE_EXCEL_DEFAULTS.maxColumnWidth,
+                column.width / TABLE_EXCEL_DEFAULTS.pixelToCharacterRatio
+              )
+            )
+          : TABLE_EXCEL_DEFAULTS.defaultColumnWidth,
+    }))
+
+    const header = worksheet.addRow(columns.map((column) => column.label))
+    header.font = { bold: true, color: { argb: 'FFFFFFFF' } }
+    header.fill = {
+      type: 'pattern',
+      pattern: 'solid',
+      fgColor: { argb: 'FF2563EB' },
+    }
+    header.alignment = { vertical: 'middle', horizontal: 'center' }
+
+    for (let rowIndex = 0; rowIndex < rows.length; rowIndex += 1) {
+      if (rowIndex % TABLE_EXCEL_DEFAULTS.abortCheckRowInterval === 0) {
+        throwIfAborted(signal)
+      }
+      const row = rows[rowIndex]!
+      worksheet.addRow(
+        columns.map((column) => {
+          const raw = getTableRowValue(row, column.key)
+          const value = column.format ? column.format(raw, row, rowIndex) : raw
+          return normalizeCellValue(value)
+        })
+      )
+      if ((rowIndex + 1) % TABLE_EXCEL_DEFAULTS.abortCheckRowInterval === 0) {
+        await yieldTableMainThread()
+      }
+    }
+    if (columns.length) {
+      worksheet.autoFilter = {
+        from: { row: 1, column: 1 },
+        to: { row: 1, column: columns.length },
+      }
+    }
+
+    throwIfAborted(signal)
+    const buffer = await workbook.xlsx.writeBuffer()
+    throwIfAborted(signal)
+    return new Blob([buffer], { type: XLSX_MIME })
+  }
+}