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

package/template/src/components/AppTable/engine/cell/customCell/renderers/step.ts

@@ -0,0 +1,37 @@
+import type { TableColumn } from '../../../columns/column'
+import type { TableRow } from '../../../shared/types'
+import type { TableCellContext } from '../../types'
+import { setTableElementTooltip } from '../tooltip'
+import { resolveTableStepLabels } from './display'
+
+/**
+ * 渲染 step 单元格，把业务步骤排列为带方向分隔符的紧凑流程；单个步骤文本
+ * 被截断时通过共享浮层显示完整内容。
+ */
+export const renderTableSteps = <T extends TableRow>(
+  td: HTMLTableCellElement,
+  column: TableColumn<T>,
+  context: TableCellContext<T>
+) => {
+  td.replaceChildren()
+  const container = document.createElement('div')
+  container.className = 'table-component__steps'
+  const groups = column.step?.resolve(context) ?? []
+  resolveTableStepLabels(groups, column.step?.labelKey).forEach(
+    (label, index, labels) => {
+      const item = document.createElement('span')
+      item.className = 'table-component__step'
+      item.textContent = label
+      setTableElementTooltip(item, label)
+      container.append(item)
+      if (index < labels.length - 1) {
+        const separator = document.createElement('span')
+        separator.className = 'table-component__step-separator'
+        separator.textContent = '→'
+        separator.setAttribute('aria-hidden', 'true')
+        container.append(separator)
+      }
+    }
+  )
+  td.append(container)
+}

package/template/src/components/AppTable/engine/cell/customCell/renderers/switch.ts

@@ -0,0 +1,45 @@
+import type { TableColumn } from '../../../columns/column'
+import type { TableRow } from '../../../shared/types'
+import type { TableCellContext } from '../../types'
+import type { TableRendererOptions } from '../types'
+import { resolveTableSwitchChecked, toggleTableSwitchValue } from './display'
+
+/**
+ * 渲染 switch 单元格，使用具备 ARIA switch 语义的原生按钮展示布尔状态，
+ * 点击后通过表格事务更新值并触发列级 onChange。
+ */
+export const renderTableSwitchCell = <T extends TableRow>(options: {
+  td: HTMLTableCellElement
+  column: TableColumn<T>
+  context: TableCellContext<T>
+  cellProperties: { readOnly?: boolean }
+  rendererOptions: TableRendererOptions
+}) => {
+  const { td, column, context, cellProperties, rendererOptions } = options
+  td.replaceChildren()
+  td.classList.add('htCenter')
+  const control = document.createElement('button')
+  const checked = resolveTableSwitchChecked(context.value)
+  control.type = 'button'
+  control.className = 'table-component__switch'
+  control.setAttribute('role', 'switch')
+  control.setAttribute('aria-checked', String(checked))
+  control.setAttribute(
+    'aria-label',
+    rendererOptions.messages.fnSwitchAriaLabel(column.label, checked)
+  )
+  control.disabled = Boolean(cellProperties.readOnly)
+  if (checked) control.classList.add('is-checked')
+  const thumb = document.createElement('span')
+  thumb.className = 'table-component__switch-thumb'
+  thumb.setAttribute('aria-hidden', 'true')
+  control.append(thumb)
+  control.onmousedown = (event) => event.stopPropagation()
+  control.onclick = (event) => {
+    event.stopPropagation()
+    const nextValue = toggleTableSwitchValue(context.value)
+    rendererOptions.updateCell(context.visualRow, String(column.key), nextValue)
+    column.onChange?.(nextValue, { ...context, value: nextValue })
+  }
+  td.append(control)
+}

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

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

package/template/src/components/AppTable/engine/cell/customCell/select/renderer.ts

@@ -0,0 +1,33 @@
+import type { TableColumn } from '../../../columns/column'
+import type { TableRow } from '../../../shared/types'
+import type { TableCellContext } from '../../types'
+import {
+  beginTableCellEditing,
+  bindTableCellEditorTrigger,
+} from '../editors/editorTrigger'
+import type { TableRendererOptions } from '../types'
+
+/**
+ * 渲染 select 和 multiSelect 的选项标签，并为可编辑单元格绑定打开选择浮层的
+ * 触发器；远程选项加载和实际选择器 UI 由框架适配层负责。
+ */
+export const renderTableSelectCell = <T extends TableRow>(options: {
+  td: HTMLTableCellElement
+  column: TableColumn<T>
+  displayValue: unknown
+  context: TableCellContext<T>
+  cellProperties: { readOnly?: boolean }
+  rendererOptions: TableRendererOptions
+}) => {
+  const { td, column, displayValue, context, cellProperties, rendererOptions } =
+    options
+  td.textContent = String(displayValue ?? '')
+  if (cellProperties.readOnly) return
+  const open = (event: MouseEvent) => beginTableCellEditing(context, event)
+  bindTableCellEditorTrigger(
+    td,
+    column.editorTrigger ?? 'doubleClick',
+    open,
+    rendererOptions.messages
+  )
+}

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

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

package/template/src/components/AppTable/engine/cell/customCell/tooltip/tooltip.ts

@@ -0,0 +1,94 @@
+import type { TableCellLayerAdapter } from '../types'
+
+const tableCellTooltipValues = new WeakMap<HTMLTableCellElement, string>()
+const TABLE_ELEMENT_TOOLTIP_ATTRIBUTE = 'data-table-cell-tooltip'
+
+/** 交互 renderer 可把提示绑定到真正发生截断的子元素，而不是整个 TD。 */
+export const setTableElementTooltip = (
+  element: HTMLElement,
+  displayValue: unknown
+) => {
+  if (displayValue === undefined) {
+    element.removeAttribute(TABLE_ELEMENT_TOOLTIP_ATTRIBUTE)
+  } else {
+    element.setAttribute(
+      TABLE_ELEMENT_TOOLTIP_ATTRIBUTE,
+      String(displayValue ?? '')
+    )
+  }
+}
+
+export const setTableCellTooltip = (
+  td: HTMLTableCellElement,
+  displayValue: unknown
+) => {
+  if (!td.classList.contains('table-component__cell')) {
+    td.classList.add('table-component__cell')
+  }
+  if (displayValue === undefined) tableCellTooltipValues.delete(td)
+  else tableCellTooltipValues.set(td, String(displayValue ?? ''))
+}
+
+/** 一张表只注册一组冒泡事件，仅在文字实际截断时展示 tooltip。 */
+export const attachTableCellTooltip = (
+  host: HTMLElement,
+  layer: TableCellLayerAdapter
+) => {
+  let activeTarget: HTMLElement | undefined
+  const resolveCell = (target: EventTarget | null) =>
+    target instanceof Element
+      ? target.closest<HTMLTableCellElement>('td.table-component__cell')
+      : null
+  const resolveTarget = (target: EventTarget | null) => {
+    const cell = resolveCell(target)
+    if (!cell || !host.contains(cell)) return
+    const elementTarget =
+      target instanceof Element
+        ? target.closest<HTMLElement>(`[${TABLE_ELEMENT_TOOLTIP_ATTRIBUTE}]`)
+        : null
+    if (elementTarget && cell.contains(elementTarget)) {
+      return {
+        element: elementTarget,
+        value: elementTarget.getAttribute(TABLE_ELEMENT_TOOLTIP_ATTRIBUTE),
+      }
+    }
+    return { element: cell, value: tableCellTooltipValues.get(cell) }
+  }
+  const showForTarget = (eventTarget: EventTarget | null) => {
+    const target = resolveTarget(eventTarget)
+    if (!target || target.element === activeTarget) return
+    if (activeTarget) layer.hideTooltip()
+    activeTarget = target.element
+    if (
+      target.value !== undefined &&
+      target.value !== null &&
+      target.element.scrollWidth > target.element.clientWidth
+    ) {
+      layer.showTooltip(target.value, target.element)
+    }
+  }
+  const hideForTarget = (relatedTarget: EventTarget | null) => {
+    if (!activeTarget) return
+    const next = resolveTarget(relatedTarget)
+    if (next?.element === activeTarget) return
+    activeTarget = undefined
+    layer.hideTooltip()
+  }
+  const onPointerOver = (event: PointerEvent) => showForTarget(event.target)
+  const onPointerOut = (event: PointerEvent) =>
+    hideForTarget(event.relatedTarget)
+  const onFocusIn = (event: FocusEvent) => showForTarget(event.target)
+  const onFocusOut = (event: FocusEvent) => hideForTarget(event.relatedTarget)
+  host.addEventListener('pointerover', onPointerOver)
+  host.addEventListener('pointerout', onPointerOut)
+  host.addEventListener('focusin', onFocusIn)
+  host.addEventListener('focusout', onFocusOut)
+  return () => {
+    host.removeEventListener('pointerover', onPointerOver)
+    host.removeEventListener('pointerout', onPointerOut)
+    host.removeEventListener('focusin', onFocusIn)
+    host.removeEventListener('focusout', onFocusOut)
+    if (activeTarget) layer.hideTooltip()
+    activeTarget = undefined
+  }
+}

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

@@ -0,0 +1,82 @@
+import type { TableEngineMessages } from '../../shared/messages'
+import type { TableOption, TableRow } from '../../shared/types'
+import type { TableValueFormat } from '../formatting'
+import type { TableOptionCachePolicy, TableOptionSource } from '../options'
+import type { TableAction, TableCellContext } from '../types'
+
+/** 框架适配层可原样交给第三方编辑组件的属性与原生 attrs。 */
+export type TableCellComponentProps = Readonly<Record<string, unknown>>
+
+/** 日期、时间和日期时间 renderer 共享的稳定类型。 */
+export type TableTemporalType = 'date' | 'time' | 'datetime'
+
+/** 日期、时间和日期时间 renderer 的单一运行时判定入口。 */
+export const isTableTemporalType = (
+  value: unknown
+): value is TableTemporalType =>
+  value === 'date' || value === 'time' || value === 'datetime'
+
+/** engine 自定义单元格调用 React 浮层的最小运行时端口。 */
+export interface TableCellLayerAdapter {
+  openSelect<T extends TableRow>(options: {
+    rect: DOMRect
+    value: unknown
+    componentProps?: TableCellComponentProps
+    multiple?: boolean
+    clearable?: boolean
+    multipleLimit?: number
+    searchable?: boolean
+    collapseTags?: boolean
+    maxCollapseTags?: number
+    row: T
+    columnKey: string
+    source?: TableOptionSource<T>
+    cache?: TableOptionCachePolicy<T>
+    debounceMs?: number
+    placeholder?: string
+    onOptionsLoaded?: (options: readonly TableOption[]) => void
+    preview?: (
+      value: unknown,
+      option?: TableOption | readonly TableOption[]
+    ) => void
+    commit: (
+      value: unknown,
+      option?: TableOption | readonly TableOption[]
+    ) => void
+    cancel?: (options?: { restoreFocus?: boolean }) => void
+  }): void | Promise<void>
+  searchSelect(query: string): void | Promise<void>
+  getOptionLabel(columnKey: string, value: unknown): string | undefined
+  clearOptionCache(columnKey?: string): void
+  openDate(options: {
+    rect: DOMRect
+    value: unknown
+    componentProps?: TableCellComponentProps
+    type?: TableTemporalType
+    commit: (value: unknown) => void
+    cancel?: (options?: { restoreFocus?: boolean }) => void
+  }): void
+  openActionMenu<T extends TableRow>(options: {
+    anchor: HTMLElement
+    actions: TableAction<T>[]
+    context: TableCellContext<T>
+  }): void
+  /** 将单元格业务动作的同步异常和 Promise 拒绝交给框架错误边界。 */
+  reportActionError(error: unknown): void
+  showTooltip(content: string, anchor: HTMLElement): void
+  hideTooltip(): void
+  close(options?: { cancel?: boolean; restoreFocus?: boolean }): void
+  destroy(): void
+}
+
+/** 自定义 renderer 从网格组合器获得的稳定运行时依赖。 */
+export interface TableRendererOptions {
+  /** 通过控制器事务更新指定行列值。 */
+  updateCell: (rowIndex: number, key: string, value: unknown) => void
+  /** 框架提供的浮层适配器。 */
+  layer: TableCellLayerAdapter
+  /** 使用统一 locale、时区和格式声明转换显示值。 */
+  formatValue: (value: unknown, format?: TableValueFormat) => unknown
+  /** 纯 DOM renderer 使用的可见文案与无障碍名称。 */
+  messages: TableEngineMessages
+}

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

@@ -0,0 +1,355 @@
+import { TABLE_CELL_DEFAULTS } from './constants'
+
+type TableLocale = string | string[]
+
+export interface TableFormatBase {
+  /** null、undefined 和空字符串的展示值，默认为空字符串。 */
+  emptyText?: string
+  /** 无效数字或日期的展示值，默认保留原值。 */
+  invalidText?: string
+}
+
+export interface TableNumberFormat extends TableFormatBase {
+  /** 使用 Intl.NumberFormat 的普通数字格式。 */
+  type: 'number'
+  /** 透传给 Intl.NumberFormat 的数字选项。 */
+  options?: Intl.NumberFormatOptions
+}
+
+export interface TableCurrencyFormat extends TableFormatBase {
+  /** 使用 Intl.NumberFormat 的货币格式。 */
+  type: 'currency'
+  /** ISO 4217 货币代码，例如 CNY、USD。 */
+  currency: string
+  /** 除 style/currency 外透传给 Intl.NumberFormat 的选项。 */
+  options?: Omit<Intl.NumberFormatOptions, 'style' | 'currency'>
+}
+
+export interface TablePercentFormat extends TableFormatBase {
+  /** 使用 Intl.NumberFormat 的百分比格式。 */
+  type: 'percent'
+  /** Intl 要求传入比例值（0.12 表示 12%）；数值为 12 时应启用 percentage。 */
+  valueScale?: 'ratio' | 'percentage'
+  /** 除 style 外透传给 Intl.NumberFormat 的选项。 */
+  options?: Omit<Intl.NumberFormatOptions, 'style'>
+}
+
+export interface TableDateTimeFormat extends TableFormatBase {
+  /** 日期、时间或日期时间展示类型。 */
+  type: 'date' | 'time' | 'datetime'
+  /** 透传给 Intl.DateTimeFormat 的展示选项。 */
+  options?: Intl.DateTimeFormatOptions
+  /** 为时间戳值覆盖表格级时区。 */
+  timeZone?: string
+}
+
+export type TableValueFormat =
+  | TableNumberFormat
+  | TableCurrencyFormat
+  | TablePercentFormat
+  | TableDateTimeFormat
+
+interface TableIntlFormatterOptions {
+  /** BCP 47 区域语言或优先级列表。 */
+  locale?: TableLocale
+  /** 默认 IANA 时区。 */
+  timeZone?: string
+  /** 数字和日期格式化器的实例级 LRU 最大条目数，默认 100。 */
+  maxCacheEntries?: number
+}
+
+interface TemporalValue {
+  date: Date
+  /** 纯日期、纯时间和不含偏移量的日期时间字符串均视为墙上时间。 */
+  wallClock: boolean
+}
+
+const ISO_DATE = /^(\d{4})-(\d{2})-(\d{2})$/
+const ISO_TIME = /^(\d{2}):(\d{2})(?::(\d{2})(?:\.(\d{1,3}))?)?$/
+const ISO_FLOATING_DATETIME =
+  /^(\d{4})-(\d{2})-(\d{2})[T ](\d{2}):(\d{2})(?::(\d{2})(?:\.(\d{1,3}))?)?$/
+
+const isValidDateParts = (
+  date: Date,
+  year: number,
+  month: number,
+  day: number,
+  hour = 0,
+  minute = 0,
+  second = 0
+) =>
+  date.getUTCFullYear() === year &&
+  date.getUTCMonth() === month - 1 &&
+  date.getUTCDate() === day &&
+  date.getUTCHours() === hour &&
+  date.getUTCMinutes() === minute &&
+  date.getUTCSeconds() === second
+
+const parseMilliseconds = (value?: string) =>
+  Number((value ?? '').padEnd(3, '0'))
+
+const parseTemporalValue = (value: unknown): TemporalValue | undefined => {
+  if (value instanceof Date) {
+    return Number.isNaN(value.getTime())
+      ? undefined
+      : { date: new Date(value.getTime()), wallClock: false }
+  }
+  if (typeof value === 'number') {
+    const date = new Date(value)
+    return Number.isNaN(date.getTime()) ? undefined : { date, wallClock: false }
+  }
+  if (typeof value !== 'string') return
+  const text = value.trim()
+  let match = text.match(ISO_DATE)
+  if (match) {
+    const [, yearText, monthText, dayText] = match
+    const [year, month, day] = [yearText, monthText, dayText].map(Number)
+    const date = new Date(Date.UTC(year, month - 1, day))
+    return isValidDateParts(date, year, month, day)
+      ? { date, wallClock: true }
+      : undefined
+  }
+  match = text.match(ISO_TIME)
+  if (match) {
+    const [, hourText, minuteText, secondText, millisecondText] = match
+    const [hour, minute, second] = [
+      hourText,
+      minuteText,
+      secondText ?? '0',
+    ].map(Number)
+    const millisecond = parseMilliseconds(millisecondText)
+    const date = new Date(
+      Date.UTC(1970, 0, 1, hour, minute, second, millisecond)
+    )
+    return isValidDateParts(date, 1970, 1, 1, hour, minute, second)
+      ? { date, wallClock: true }
+      : undefined
+  }
+  match = text.match(ISO_FLOATING_DATETIME)
+  if (match) {
+    const [
+      ,
+      yearText,
+      monthText,
+      dayText,
+      hourText,
+      minuteText,
+      secondText,
+      millisecondText,
+    ] = match
+    const [year, month, day, hour, minute, second] = [
+      yearText,
+      monthText,
+      dayText,
+      hourText,
+      minuteText,
+      secondText ?? '0',
+    ].map(Number)
+    const date = new Date(
+      Date.UTC(
+        year,
+        month - 1,
+        day,
+        hour,
+        minute,
+        second,
+        parseMilliseconds(millisecondText)
+      )
+    )
+    return isValidDateParts(date, year, month, day, hour, minute, second)
+      ? { date, wallClock: true }
+      : undefined
+  }
+  const timestamp = Date.parse(text)
+  return Number.isNaN(timestamp)
+    ? undefined
+    : { date: new Date(timestamp), wallClock: false }
+}
+
+type IntlNumericValue = number | bigint | string
+
+const DECIMAL_NUMBER = /^([+-]?)(\d+)(?:\.(\d*))?(?:e([+-]?\d+))?$/i
+
+const numberValue = (value: unknown): IntlNumericValue | null => {
+  if (typeof value === 'number') return Number.isFinite(value) ? value : null
+  if (typeof value === 'bigint') return value
+  if (typeof value !== 'string' || !DECIMAL_NUMBER.test(value.trim())) {
+    return null
+  }
+  return value.trim()
+}
+
+const decimalPercentageToRatio = (value: bigint | string) => {
+  const text = String(value)
+  const match = text.match(DECIMAL_NUMBER)!
+  const sign = match[1]
+  const integer = match[2]
+  const fraction = match[3] ?? ''
+  const exponent = Number(match[4] ?? 0)
+  const digits = `${integer}${fraction}`
+  const decimalPosition = integer.length + exponent - 2
+  if (decimalPosition <= 0) {
+    return `${sign}0.${'0'.repeat(-decimalPosition)}${digits}`
+  }
+  if (decimalPosition >= digits.length) {
+    return `${sign}${digits}${'0'.repeat(decimalPosition - digits.length)}`
+  }
+  return `${sign}${digits.slice(0, decimalPosition)}.${digits.slice(decimalPosition)}`
+}
+
+const formatNumeric = (formatter: Intl.NumberFormat, value: IntlNumericValue) =>
+  // 当前 Intl 可直接接受十进制字符串，无需先转成 Number 而损失精度；
+  // TypeScript 的标准库类型声明可能落后于运行时规范。
+  formatter.format(value as number)
+
+const fallbackValue = (value: unknown, invalidText?: string) =>
+  invalidText ?? String(value ?? '')
+
+/** 表格实例级、框架无关的 Intl 格式化器，并限制格式化器缓存大小。 */
+export class TableIntlFormatter {
+  private readonly numberCache = new Map<string, Intl.NumberFormat>()
+  private readonly dateTimeCache = new Map<string, Intl.DateTimeFormat>()
+  private readonly locale?: TableLocale
+  private readonly timeZone?: string
+  private readonly maxCacheEntries: number
+
+  constructor(options: TableIntlFormatterOptions = {}) {
+    if (
+      options.maxCacheEntries !== undefined &&
+      (!Number.isInteger(options.maxCacheEntries) ||
+        options.maxCacheEntries < 1)
+    ) {
+      throw new Error(
+        '[TableComponent] Intl formatter maxCacheEntries must be a positive integer.'
+      )
+    }
+    this.locale = options.locale
+    this.timeZone = options.timeZone
+    this.maxCacheEntries =
+      options.maxCacheEntries ?? TABLE_CELL_DEFAULTS.cacheEntries
+  }
+
+  private cached<T>(cache: Map<string, T>, key: string, create: () => T) {
+    const existing = cache.get(key)
+    if (existing) {
+      cache.delete(key)
+      cache.set(key, existing)
+      return existing
+    }
+    const value = create()
+    cache.set(key, value)
+    while (cache.size > this.maxCacheEntries) {
+      cache.delete(cache.keys().next().value!)
+    }
+    return value
+  }
+
+  private numberFormatter(options: Intl.NumberFormatOptions) {
+    const key = JSON.stringify([this.locale, options])
+    return this.cached(
+      this.numberCache,
+      key,
+      () => new Intl.NumberFormat(this.locale, options)
+    )
+  }
+
+  private dateTimeFormatter(
+    options: Intl.DateTimeFormatOptions,
+    timeZone?: string
+  ) {
+    const resolvedOptions = { ...options, timeZone }
+    const key = JSON.stringify([this.locale, resolvedOptions])
+    return this.cached(
+      this.dateTimeCache,
+      key,
+      () => new Intl.DateTimeFormat(this.locale, resolvedOptions)
+    )
+  }
+
+  format(value: unknown, format?: TableValueFormat): unknown {
+    if (!format) return value
+    if (value === null || value === undefined || value === '') {
+      return format.emptyText ?? ''
+    }
+    if (
+      format.type === 'number' ||
+      format.type === 'currency' ||
+      format.type === 'percent'
+    ) {
+      const parsed = numberValue(value)
+      if (parsed === null) return fallbackValue(value, format.invalidText)
+      if (format.type === 'number') {
+        return formatNumeric(
+          this.numberFormatter({
+            ...format.options,
+            style: 'decimal',
+          }),
+          parsed
+        )
+      }
+      if (format.type === 'currency') {
+        return formatNumeric(
+          this.numberFormatter({
+            ...format.options,
+            style: 'currency',
+            currency: format.currency,
+          }),
+          parsed
+        )
+      }
+      const percentValue =
+        format.valueScale === 'percentage'
+          ? typeof parsed === 'number'
+            ? parsed / 100
+            : decimalPercentageToRatio(parsed)
+          : parsed
+      return formatNumeric(
+        this.numberFormatter({
+          ...format.options,
+          style: 'percent',
+        }),
+        percentValue
+      )
+    }
+
+    const temporal = parseTemporalValue(value)
+    if (!temporal) return fallbackValue(value, format.invalidText)
+    const defaults: Record<
+      TableDateTimeFormat['type'],
+      Intl.DateTimeFormatOptions
+    > = {
+      date: { year: 'numeric', month: '2-digit', day: '2-digit' },
+      time: {
+        hour: '2-digit',
+        minute: '2-digit',
+        second: '2-digit',
+        hour12: false,
+      },
+      datetime: {
+        year: 'numeric',
+        month: '2-digit',
+        day: '2-digit',
+        hour: '2-digit',
+        minute: '2-digit',
+        second: '2-digit',
+        hour12: false,
+      },
+    }
+    const dateTimeOptions =
+      format.options?.dateStyle || format.options?.timeStyle
+        ? format.options
+        : { ...defaults[format.type], ...format.options }
+    return this.dateTimeFormatter(
+      dateTimeOptions,
+      temporal.wallClock ? 'UTC' : (format.timeZone ?? this.timeZone)
+    ).format(temporal.date)
+  }
+
+  clear() {
+    this.numberCache.clear()
+    this.dateTimeCache.clear()
+  }
+}
+
+export const createTableIntlFormatter = (options?: TableIntlFormatterOptions) =>
+  new TableIntlFormatter(options)