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

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

@@ -0,0 +1,245 @@
+import type { CellProperties } from 'handsontable'
+import {
+  rendererFactory,
+  textRenderer,
+  type BaseRenderer,
+} from 'handsontable/renderers'
+import type { TableColumn } from '../../../columns/column'
+import { getTableRowValue } from '../../../shared/row'
+import type { TableRow } from '../../../shared/types'
+import type { TableCellContext } from '../../types'
+import { renderTableActions } from '../actions'
+import { renderTableDateCell } from '../date'
+import { renderTableSelectCell } from '../select'
+import { setTableCellTooltip } from '../tooltip'
+import type { TableRendererOptions } from '../types'
+import { renderTableConfirmInput } from './confirmInput'
+import { resolveColumnFormat, resolveTableSelectDisplay } from './display'
+import { renderTableItemList } from './itemList'
+import { renderTableLinks } from './links'
+import {
+  createTableCellContext,
+  markTableInteractiveCell,
+  resetTableInteractiveCell,
+} from './shared'
+import { renderTableSteps } from './step'
+import { renderTableSwitchCell } from './switch'
+
+/** 优先读取源行中的真实字段；不存在该字段时才使用 Handsontable 传入值。 */
+const resolveRawCellValue = <T extends TableRow>(
+  row: T,
+  prop: string | number,
+  fallback: unknown
+) =>
+  Object.prototype.hasOwnProperty.call(row, prop)
+    ? getTableRowValue(row, prop)
+    : fallback
+
+/**
+ * 统一计算基础文本 renderer 使用的展示值。
+ * valueGetter 已执行 formatter 时直接复用 renderedValue，避免同一 formatter 执行两次。
+ */
+const resolveDisplayValue = <T extends TableRow>(options: {
+  column: TableColumn<T>
+  renderer: string
+  rawValue: unknown
+  renderedValue: unknown
+  row: T
+  physicalRow: number
+  cellProperties: CellProperties
+  rendererOptions: TableRendererOptions
+}) => {
+  const {
+    column,
+    renderer,
+    rawValue,
+    renderedValue,
+    row,
+    physicalRow,
+    cellProperties,
+    rendererOptions,
+  } = options
+  if (renderer === 'select' || renderer === 'multiSelect') {
+    return resolveTableSelectDisplay(
+      column,
+      rawValue,
+      row,
+      physicalRow,
+      rendererOptions.layer
+    )
+  }
+  if (!column.formatter) {
+    return rendererOptions.formatValue(rawValue, resolveColumnFormat(column))
+  }
+  return cellProperties.valueGetter
+    ? renderedValue
+    : column.formatter(rawValue, row, physicalRow)
+}
+
+/** 基础文本完成后，按 renderer 类型叠加按钮、选择器等交互 DOM。 */
+const renderConfiguredCell = <T extends TableRow>(options: {
+  renderer: string
+  td: HTMLTableCellElement
+  column: TableColumn<T>
+  displayValue: unknown
+  rawValue: unknown
+  context: TableCellContext<T>
+  cellProperties: CellProperties
+  rendererOptions: TableRendererOptions
+}) => {
+  const {
+    renderer,
+    td,
+    column,
+    displayValue,
+    rawValue,
+    context,
+    cellProperties,
+    rendererOptions,
+  } = options
+  switch (renderer) {
+    case 'button':
+      renderTableActions(td, column, context, rendererOptions)
+      break
+    case 'link':
+      renderTableLinks(td, column, displayValue, context, rendererOptions)
+      break
+    case 'select':
+    case 'multiSelect':
+      renderTableSelectCell({
+        td,
+        column,
+        displayValue,
+        context,
+        cellProperties,
+        rendererOptions,
+      })
+      break
+    case 'date':
+    case 'time':
+    case 'datetime':
+      renderTableDateCell({
+        td,
+        column,
+        context,
+        cellProperties,
+        rendererOptions,
+      })
+      break
+    case 'switch':
+      renderTableSwitchCell({
+        td,
+        column,
+        context,
+        cellProperties,
+        rendererOptions,
+      })
+      break
+    case 'itemList':
+      renderTableItemList(td, column, rawValue, context, rendererOptions.layer)
+      break
+    case 'step':
+      renderTableSteps(td, column, context)
+      break
+    case 'confirmInput':
+    case 'pasteConfirmInput':
+      renderTableConfirmInput(
+        td,
+        column,
+        displayValue,
+        context,
+        rendererOptions
+      )
+      break
+  }
+}
+
+const overflowTooltipRenderers = new Set([
+  'text',
+  'select',
+  'multiSelect',
+  'date',
+  'time',
+  'datetime',
+  'confirmInput',
+  'pasteConfirmInput',
+])
+
+/**
+ * 自定义单元格的纯 JS 统一渲染入口，基于 Handsontable v18 rendererFactory。
+ *
+ * engine 只生成安全 DOM 并通过 TableCellLayerAdapter 请求复杂交互；React 组件和
+ * Portal 不得反向进入这里。每次渲染先清理复用 TD 的旧状态，避免
+ * 虚拟滚动把上一单元格的事件、class 或 tooltip 带到新单元格。
+ */
+export const createColumnRenderer = <T extends TableRow>(
+  column: TableColumn<T>,
+  options: TableRendererOptions
+): BaseRenderer => {
+  if (typeof column.renderer === 'function') return column.renderer
+  const configuredRenderer = column.renderer ?? 'text'
+
+  return rendererFactory(
+    ({
+      instance,
+      td,
+      row,
+      column: visualColumn,
+      prop,
+      value,
+      cellProperties,
+    }) => {
+      // Handsontable 会循环复用 TD，任何自定义 renderer 都必须从干净状态开始。
+      resetTableInteractiveCell(td)
+      const physicalRow = instance.toPhysicalRow(row)
+      // 排序/筛选后 visualRow 会变化，业务回调和 raw value 必须以 physicalRow 取源数据。
+      const rowData = instance.getSourceDataAtRow(physicalRow) as T
+      const rawValue = resolveRawCellValue(rowData, prop, value)
+      const displayValue = resolveDisplayValue({
+        column,
+        renderer: configuredRenderer,
+        rawValue,
+        renderedValue: value,
+        row: rowData,
+        physicalRow,
+        cellProperties,
+        rendererOptions: options,
+      })
+      textRenderer(
+        instance,
+        td,
+        row,
+        visualColumn,
+        prop,
+        displayValue ?? '',
+        cellProperties
+      )
+      if (configuredRenderer !== 'text') {
+        markTableInteractiveCell(td)
+        renderConfiguredCell({
+          renderer: configuredRenderer,
+          td,
+          column,
+          displayValue,
+          rawValue,
+          context: createTableCellContext<T>({
+            instance,
+            visualRow: row,
+            visualColumn,
+            value: rawValue,
+          }),
+          cellProperties,
+          rendererOptions: options,
+        })
+      }
+      // 按最终 DOM 测量溢出，但只为真正展示 displayValue 的文本型单元格提供内容。
+      // 操作、开关、步骤等 renderer 会替换基础文本，不得携带陈旧 tooltip。
+      setTableCellTooltip(
+        td,
+        overflowTooltipRenderers.has(configuredRenderer)
+          ? displayValue
+          : undefined
+      )
+    }
+  ) as BaseRenderer
+}

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

@@ -0,0 +1,57 @@
+import type { TableColumn } from '../../../columns/column'
+import { runTableAction } from '../../../shared/action'
+import type { TableRow } from '../../../shared/types'
+import type { TableCellContext } from '../../types'
+import type { TableRendererOptions } from '../types'
+import { resolveCellBoolean } from './shared'
+
+/**
+ * 渲染 confirmInput 和 pasteConfirmInput 单元格，在当前展示值旁提供确认按钮，
+ * 并按列配置支持按钮事件或单元格双击确认。
+ */
+export const renderTableConfirmInput = <T extends TableRow>(
+  td: HTMLTableCellElement,
+  column: TableColumn<T>,
+  displayValue: unknown,
+  context: TableCellContext<T>,
+  rendererOptions: TableRendererOptions
+) => {
+  const { layer, messages } = rendererOptions
+  td.replaceChildren()
+  const container = document.createElement('div')
+  container.className = 'table-component__confirm-input'
+  const value = document.createElement('span')
+  value.className = 'table-component__confirm-value'
+  value.textContent = String(displayValue ?? '')
+  container.append(value)
+  const config = column.confirmInput
+  if (!config) {
+    td.append(container)
+    return
+  }
+  const confirm = () =>
+    runTableAction(
+      () => config.onConfirm(context),
+      (error) => layer.reportActionError(error)
+    )
+  const button = document.createElement('button')
+  button.type = 'button'
+  button.dataset.slot = 'table-action'
+  button.dataset.variant = 'link'
+  button.className = 'table-component__action'
+  button.textContent = config.buttonLabel ?? messages.strConfirmInput
+  button.disabled = resolveCellBoolean(config.disabled, context)
+  button.onmousedown = (event) => event.stopPropagation()
+  button.addEventListener(config.trigger ?? 'click', (event) => {
+    event.stopPropagation()
+    confirm()
+  })
+  container.append(button)
+  td.append(container)
+  if (config.doubleClickTrigger) {
+    td.ondblclick = (event) => {
+      event.stopPropagation()
+      confirm()
+    }
+  }
+}

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

@@ -0,0 +1,78 @@
+import type { TableColumn } from '../../../columns/column'
+import type { TableRow } from '../../../shared/types'
+import type { TableValueFormat } from '../../formatting'
+import { isTableTemporalType, type TableCellLayerAdapter } from '../types'
+
+export const resolveTableSelectDisplay = <T extends TableRow>(
+  column: TableColumn<T>,
+  value: unknown,
+  row: T,
+  rowIndex: number,
+  layer: TableCellLayerAdapter
+) => {
+  if (column.formatter) return column.formatter(value, row, rowIndex)
+  const staticOptions = Array.isArray(column.options) ? column.options : []
+  const labelFor = (item: unknown) => {
+    const option = staticOptions.find((candidate) =>
+      typeof candidate === 'string' || typeof candidate === 'number'
+        ? Object.is(candidate, item)
+        : Object.is(candidate.value, item)
+    )
+    return (
+      (typeof option === 'string' || typeof option === 'number'
+        ? String(option)
+        : option?.label) ??
+      layer.getOptionLabel(String(column.key), item) ??
+      String(item ?? '')
+    )
+  }
+  return Array.isArray(value) ? value.map(labelFor).join('、') : labelFor(value)
+}
+
+export const resolveColumnFormat = <T extends TableRow>(
+  column: TableColumn<T>
+): TableValueFormat | undefined => {
+  if (column.format) return column.format
+  return isTableTemporalType(column.renderer)
+    ? { type: column.renderer }
+    : undefined
+}
+
+export const normalizeTableItemListValue = (
+  value: unknown,
+  separator = ';'
+): unknown[] => {
+  if (Array.isArray(value)) return value.flat(Infinity)
+  if (typeof value === 'string') return value.split(separator)
+  return value === null || value === undefined ? [] : [value]
+}
+
+const getStepLabel = (item: unknown, labelKey: string) => {
+  if (item && typeof item === 'object' && labelKey in item) {
+    return String(Reflect.get(item, labelKey) ?? '')
+  }
+  return String(item ?? '')
+}
+
+export const resolveTableStepLabels = (
+  groups: readonly (readonly unknown[] | unknown)[],
+  labelKey = 'label'
+) =>
+  groups.map((group) =>
+    (Array.isArray(group) ? group : [group])
+      .map((item) => getStepLabel(item, labelKey))
+      .filter(Boolean)
+      .join('、')
+  )
+
+export const resolveTableSwitchChecked = (value: unknown) =>
+  typeof value === 'string' || typeof value === 'number'
+    ? Number(value) !== 0
+    : Boolean(value)
+
+export const toggleTableSwitchValue = (value: unknown) => {
+  const checked = !resolveTableSwitchChecked(value)
+  if (typeof value === 'number') return checked ? 1 : 0
+  if (typeof value === 'string') return checked ? '1' : '0'
+  return checked
+}

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

@@ -0,0 +1,3 @@
+export * from './columnRenderer'
+export * from './display'
+export * from './selection'

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

@@ -0,0 +1,60 @@
+import type { TableColumn } from '../../../columns/column'
+import { runTableAction } from '../../../shared/action'
+import type { TableRow } from '../../../shared/types'
+import type { TableCellContext } from '../../types'
+import { setTableElementTooltip } from '../tooltip'
+import type { TableCellLayerAdapter } from '../types'
+import { normalizeTableItemListValue } from './display'
+
+const resolveLabel = (item: unknown, labelKey?: string) => {
+  if (labelKey && item && typeof item === 'object' && labelKey in item) {
+    return String(Reflect.get(item, labelKey) ?? '')
+  }
+  return String(item ?? '')
+}
+
+/**
+ * 渲染 itemList 单元格，将数组或分隔文本拆成多个条目展示，并可按配置把
+ * 每个条目变为可点击链接。
+ */
+export const renderTableItemList = <T extends TableRow>(
+  td: HTMLTableCellElement,
+  column: TableColumn<T>,
+  value: unknown,
+  context: TableCellContext<T>,
+  layer: TableCellLayerAdapter
+) => {
+  td.replaceChildren()
+  td.classList.add('table-component__item-list')
+  normalizeTableItemListValue(value, column.itemList?.separator).forEach(
+    (item) => {
+      const element = document.createElement('div')
+      element.className = 'table-component__item-list-item'
+      const align = column.itemList?.align ?? 'auto'
+      const rightAligned =
+        align === 'right' ||
+        (align === 'auto' &&
+          (column.type === 'numeric' || typeof item === 'number'))
+      if (rightAligned) element.classList.add('htRight')
+      else if (align === 'center') element.classList.add('htCenter')
+      const text = resolveLabel(item, column.itemList?.labelKey)
+      setTableElementTooltip(element, text)
+      if (column.itemList?.link && text) {
+        const button = document.createElement('button')
+        button.type = 'button'
+        button.className = 'table-component__link'
+        button.textContent = text
+        button.onmousedown = (event) => event.stopPropagation()
+        button.onclick = (event) => {
+          event.stopPropagation()
+          runTableAction(
+            () => column.itemList?.onItemClick?.(item, context),
+            (error) => layer.reportActionError(error)
+          )
+        }
+        element.append(button)
+      } else element.textContent = text
+      td.append(element)
+    }
+  )
+}

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

@@ -0,0 +1,131 @@
+import type { TableColumn, TableLink } from '../../../columns/column'
+import { runTableAction } from '../../../shared/action'
+import { createTableClickCoordinator } from '../../../shared/interaction'
+import type { TableRow } from '../../../shared/types'
+import { TABLE_CELL_DEFAULTS } from '../../constants'
+import type { TableCellContext } from '../../types'
+import { setTableElementTooltip } from '../tooltip'
+import type { TableRendererOptions } from '../types'
+import { resolveCellBoolean } from './shared'
+
+const SAFE_TABLE_LINK_PROTOCOLS = new Set([
+  'http:',
+  'https:',
+  'mailto:',
+  'tel:',
+])
+
+/** 仅允许浏览器导航协议和相对地址，拒绝 javascript:/data: 等可执行 URL。 */
+const resolveSafeTableHref = (href?: string) => {
+  const value = href?.trim()
+  if (!value) return undefined
+  try {
+    const url = new URL(value, 'https://table-component.invalid')
+    return SAFE_TABLE_LINK_PROTOCOLS.has(url.protocol) ? value : undefined
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * 渲染 link 单元格：支持一个或多个安全链接、禁用态、单击和双击业务动作，
+ * 文本被截断时按链接元素显示溢出提示。
+ */
+export const renderTableLinks = <T extends TableRow>(
+  td: HTMLTableCellElement,
+  column: TableColumn<T>,
+  displayValue: unknown,
+  context: TableCellContext<T>,
+  rendererOptions: TableRendererOptions
+) => {
+  const { layer, messages } = rendererOptions
+  td.replaceChildren()
+  const container = document.createElement('div')
+  container.className = 'table-component__links'
+  const configured =
+    typeof column.links === 'function' ? column.links(context) : column.links
+  const links: readonly TableLink<T>[] = configured?.length
+    ? configured
+    : [
+        {
+          key: String(column.key),
+          label: String(displayValue ?? ''),
+          href: column.link?.(context),
+          onClick: column.actions?.[0]?.onClick,
+        },
+      ]
+
+  links.forEach((item, index) => {
+    const disabled = resolveCellBoolean(item.disabled, context)
+    const label =
+      typeof item.label === 'function' ? item.label(context) : item.label
+    const href = resolveSafeTableHref(
+      typeof item.href === 'function' ? item.href(context) : item.href
+    )
+    const wrap = document.createElement('span')
+    wrap.className = 'table-component__link-item'
+    const link =
+      href && !disabled
+        ? document.createElement('a')
+        : document.createElement('button')
+    if (link instanceof HTMLButtonElement) {
+      link.type = 'button'
+      link.disabled = disabled
+    } else {
+      link.href = href!
+      link.target = '_blank'
+      link.rel = 'noopener noreferrer'
+    }
+    link.className = 'table-component__link'
+    link.textContent = label
+    setTableElementTooltip(link, label)
+    link.onmousedown = (event) => event.stopPropagation()
+
+    if ((item.onClick || item.onDoubleClick) && !disabled) {
+      const coordinator = createTableClickCoordinator({
+        delay: TABLE_CELL_DEFAULTS.linkClickDelayMs,
+        onClick: () =>
+          runTableAction(
+            () => item.onClick?.(context),
+            (error) => layer.reportActionError(error)
+          ),
+        onDoubleClick: () =>
+          runTableAction(
+            () => (item.onDoubleClick ?? item.onClick)?.(context),
+            (error) => layer.reportActionError(error)
+          ),
+      })
+      link.onclick = (event) => {
+        event.preventDefault()
+        event.stopPropagation()
+        context.instance?.deselectCell?.()
+        coordinator.schedule(
+          `${context.visualRow}:${context.visualColumn}:${item.key}:${index}`,
+          context
+        )
+      }
+    } else link.onclick = (event) => event.stopPropagation()
+    wrap.append(link)
+
+    if (item.onClear) {
+      const clear = document.createElement('button')
+      clear.type = 'button'
+      clear.className = 'table-component__link-clear'
+      clear.textContent = '×'
+      clear.title = item.clearLabel ?? messages.fnClearLinkAriaLabel(label)
+      clear.setAttribute('aria-label', clear.title)
+      clear.disabled = disabled
+      clear.onmousedown = (event) => event.stopPropagation()
+      clear.onclick = (event) => {
+        event.stopPropagation()
+        runTableAction(
+          () => item.onClear?.(context),
+          (error) => layer.reportActionError(error)
+        )
+      }
+      wrap.append(clear)
+    }
+    container.append(wrap)
+  })
+  td.append(container)
+}

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

@@ -0,0 +1,41 @@
+import { rendererFactory, type BaseRenderer } from 'handsontable/renderers'
+import {
+  TABLE_ENGINE_MESSAGES_ZH_CN,
+  type TableEngineMessages,
+} from '../../../shared/messages'
+import type { TableRow } from '../../../shared/types'
+import { resetTableInteractiveCell } from './shared'
+
+/** 表格选择控制器使用的框架无关复选框渲染器。 */
+export const createSelectionRenderer = <T extends TableRow>(options: {
+  isSelected: (row: T) => boolean
+  isDisabled?: (row: T) => boolean
+  isInteractive?: (row: T) => boolean
+  toggle: (row: T, checked: boolean) => void
+  messages?: TableEngineMessages
+}): BaseRenderer =>
+  rendererFactory(({ instance, td, row }) => {
+    const physicalRow = instance.toPhysicalRow(row)
+    const rowData = instance.getSourceDataAtRow(physicalRow) as T
+    resetTableInteractiveCell(td)
+    td.replaceChildren()
+    // 汇总行等展示型数据不进入选择状态，也不创建可交互控件。
+    if (options.isInteractive?.(rowData) === false) {
+      td.className = 'htMiddle columnSummaryResult'
+      return
+    }
+    td.className = 'htCenter htMiddle table-component__selection'
+    const checkbox = document.createElement('input')
+    checkbox.type = 'checkbox'
+    checkbox.checked = options.isSelected(rowData)
+    checkbox.disabled = options.isDisabled?.(rowData) ?? false
+    checkbox.setAttribute(
+      'aria-label',
+      (options.messages ?? TABLE_ENGINE_MESSAGES_ZH_CN).fnSelectRowAriaLabel(
+        row + 1
+      )
+    )
+    checkbox.onclick = (event) => event.stopPropagation()
+    checkbox.onchange = () => options.toggle(rowData, checkbox.checked)
+    td.append(checkbox)
+  }) as BaseRenderer

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

@@ -0,0 +1,71 @@
+import type Handsontable from 'handsontable'
+import type { TableRow } from '../../../shared/types'
+import type { TableCellContext } from '../../types'
+
+export const resolveCellBoolean = <T extends TableRow>(
+  value: boolean | ((context: TableCellContext<T>) => boolean) | undefined,
+  context: TableCellContext<T>
+) => (typeof value === 'function' ? value(context) : Boolean(value))
+
+const getTableRendererRow = <T extends TableRow>(
+  instance: Handsontable,
+  visualRow: number
+): { row: T; physicalRow: number } => {
+  const physicalRow = instance.toPhysicalRow(visualRow)
+  return {
+    row: instance.getSourceDataAtRow(physicalRow) as T,
+    physicalRow,
+  }
+}
+
+export const createTableCellContext = <T extends TableRow>(options: {
+  instance: Handsontable
+  visualRow: number
+  visualColumn: number
+  value: unknown
+}): TableCellContext<T> => {
+  const { row, physicalRow } = getTableRendererRow<T>(
+    options.instance,
+    options.visualRow
+  )
+  const physicalColumn =
+    options.instance.toPhysicalColumn?.(options.visualColumn) ??
+    options.visualColumn
+  return {
+    row,
+    rowIndex: options.visualRow,
+    visualRow: options.visualRow,
+    visualColumn: options.visualColumn,
+    physicalRow,
+    physicalColumn,
+    columnIndex: options.visualColumn,
+    value: options.value,
+    instance: options.instance,
+  }
+}
+
+const interactiveTableCells = new WeakSet<HTMLTableCellElement>()
+
+export const markTableInteractiveCell = (td: HTMLTableCellElement) => {
+  interactiveTableCells.add(td)
+}
+
+export const resetTableInteractiveCell = (td: HTMLTableCellElement) => {
+  if (!interactiveTableCells.delete(td)) return
+  td.classList.remove(
+    'table-component__actions',
+    'table-component__links',
+    'table-component__steps',
+    'table-component__confirm-input',
+    'table-component__item-list',
+    'table-component__editable',
+    'table-component__editor-icon-cell'
+  )
+  td.onclick = null
+  td.ondblclick = null
+  td.onmousedown = null
+  td.onmouseup = null
+  td.onmouseenter = null
+  td.onmouseleave = null
+  td.onchange = null
+}