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

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

@@ -0,0 +1,116 @@
+import type { TableColumn } from '../../../columns/column'
+import {
+  TABLE_ENGINE_MESSAGES_ZH_CN,
+  type TableEngineMessages,
+} from '../../../shared/messages'
+import type { TableRow } from '../../../shared/types'
+import type { TableCellContext } from '../../types'
+import {
+  beginTableCellEditing,
+  bindTableCellEditorTrigger,
+} from '../editors/editorTrigger'
+import type { TableRendererOptions, TableTemporalType } from '../types'
+
+const padTemporalPart = (value: string) => value.padStart(2, '0')
+
+const parseDateParts = (value: string, messages: TableEngineMessages) => {
+  const match = /^(\d{4})-(\d{1,2})-(\d{1,2})$/.exec(value)
+  if (!match) throw new Error(messages.strInvalidDateFormat)
+  const [, yearText, monthText, dayText] = match
+  const year = Number(yearText)
+  const month = Number(monthText)
+  const day = Number(dayText)
+  const date = new Date(Date.UTC(year, month - 1, day))
+  if (
+    date.getUTCFullYear() !== year ||
+    date.getUTCMonth() !== month - 1 ||
+    date.getUTCDate() !== day
+  ) {
+    throw new Error(messages.strInvalidDate)
+  }
+  return `${yearText}-${padTemporalPart(monthText)}-${padTemporalPart(dayText)}`
+}
+
+const parseTimeParts = (value: string, messages: TableEngineMessages) => {
+  const match = /^(\d{1,2}):(\d{1,2}):(\d{1,2})$/.exec(value)
+  if (!match) throw new Error(messages.strInvalidTimeFormat)
+  const [, hourText, minuteText, secondText] = match
+  const hour = Number(hourText)
+  const minute = Number(minuteText)
+  const second = Number(secondText)
+  if (hour > 23 || minute > 59 || second > 59) {
+    throw new Error(messages.strInvalidTime)
+  }
+  return [hourText, minuteText, secondText].map(padTemporalPart).join(':')
+}
+
+/**
+ * 规范化可编辑日期时间值，避免 Date.parse 的时区歧义。
+ * 空值和 API 返回的非字符串值保持原样，输入或粘贴的字符串则严格校验。
+ */
+export const parseTableTemporalInput = (
+  value: unknown,
+  type: TableTemporalType,
+  messages: TableEngineMessages = TABLE_ENGINE_MESSAGES_ZH_CN
+) => {
+  if (typeof value !== 'string') return value
+  const normalized = value.trim()
+  if (!normalized) return ''
+  if (type === 'date') return parseDateParts(normalized, messages)
+  if (type === 'time') return parseTimeParts(normalized, messages)
+  // 保留有效的绝对时间戳。格式化阶段会应用表格时区；
+  // 如果在此强制转换为本地墙上时间，会改变它表示的真实时刻。
+  if (
+    /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,9})?(?:Z|[+-]\d{2}:\d{2})$/.test(
+      normalized
+    ) &&
+    Number.isFinite(Date.parse(normalized))
+  ) {
+    return normalized
+  }
+  const match = /^(\d{4}-\d{1,2}-\d{1,2})[ T](\d{1,2}:\d{1,2}:\d{1,2})$/.exec(
+    normalized
+  )
+  if (!match) {
+    throw new Error(messages.strInvalidDateTimeFormat)
+  }
+  return `${parseDateParts(match[1], messages)} ${parseTimeParts(
+    match[2],
+    messages
+  )}`
+}
+
+export const validateTableTemporalValue = (
+  value: unknown,
+  type: TableTemporalType,
+  messages: TableEngineMessages = TABLE_ENGINE_MESSAGES_ZH_CN
+): true | string => {
+  try {
+    parseTableTemporalInput(value, type, messages)
+    return true
+  } catch (error) {
+    return error instanceof Error ? error.message : String(error)
+  }
+}
+
+/**
+ * 为 date、time 和 datetime 单元格绑定编辑触发器；展示文本沿用统一基础
+ * renderer，真正的日期时间选择器由框架浮层在进入编辑状态后提供。
+ */
+export const renderTableDateCell = <T extends TableRow>(options: {
+  td: HTMLTableCellElement
+  column: TableColumn<T>
+  context: TableCellContext<T>
+  cellProperties: { readOnly?: boolean }
+  rendererOptions: TableRendererOptions
+}) => {
+  const { td, column, context, cellProperties, rendererOptions } = options
+  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/editors/editorBounds.ts

@@ -0,0 +1,57 @@
+type TableRectBounds = Pick<
+  DOMRect,
+  'top' | 'right' | 'bottom' | 'left' | 'width' | 'height'
+>
+
+const distance = (first: number, second: number) => Math.abs(first - second)
+
+/**
+ * 计算 Handsontable 原生选区框内部边界。
+ *
+ * wtBorder 的四条边并非相对 TD 对称定位，且主题可改变边框宽度，因此必须依据
+ * 实际边框几何计算，不能用固定 inset 猜测。
+ */
+export const resolveTableEditorBounds = (
+  cellRect: TableRectBounds,
+  borderRects: readonly TableRectBounds[]
+) => {
+  const fallback = {
+    left: cellRect.left,
+    top: cellRect.top,
+    width: cellRect.width,
+    height: cellRect.height,
+  }
+  const horizontal = borderRects.filter((rect) => rect.width > rect.height)
+  const vertical = borderRects.filter((rect) => rect.height > rect.width)
+  if (horizontal.length < 2 || vertical.length < 2) return fallback
+
+  const topBorder = horizontal.reduce((closest, rect) =>
+    distance(rect.top, cellRect.top) < distance(closest.top, cellRect.top)
+      ? rect
+      : closest
+  )
+  const bottomBorder = horizontal.reduce((closest, rect) =>
+    distance(rect.bottom, cellRect.bottom) <
+    distance(closest.bottom, cellRect.bottom)
+      ? rect
+      : closest
+  )
+  const leftBorder = vertical.reduce((closest, rect) =>
+    distance(rect.left, cellRect.left) < distance(closest.left, cellRect.left)
+      ? rect
+      : closest
+  )
+  const rightBorder = vertical.reduce((closest, rect) =>
+    distance(rect.right, cellRect.right) <
+    distance(closest.right, cellRect.right)
+      ? rect
+      : closest
+  )
+  const left = Math.max(cellRect.left, leftBorder.right)
+  const top = Math.max(cellRect.top, topBorder.bottom)
+  const right = Math.min(cellRect.right, rightBorder.left)
+  const bottom = Math.min(cellRect.bottom, bottomBorder.top)
+  return right > left && bottom > top
+    ? { left, top, width: right - left, height: bottom - top }
+    : fallback
+}

package/template/src/components/AppTable/engine/cell/customCell/editors/editorTrigger.ts

@@ -0,0 +1,46 @@
+import {
+  TABLE_ENGINE_MESSAGES_ZH_CN,
+  type TableEngineMessages,
+} from '../../../shared/messages'
+import type { TableRow } from '../../../shared/types'
+import type { TableCellContext } from '../../types'
+
+export const beginTableCellEditing = <T extends TableRow>(
+  context: TableCellContext<T>,
+  event: MouseEvent
+) => {
+  event.stopPropagation()
+  // 先让 Handsontable 完成初始鼠标手势处理，再挂载 body 级浮层；
+  // 否则同一次点击会立即关闭刚打开的浮层。
+  context.instance.rootWindow.setTimeout(() => {
+    context.instance.selectCell(context.visualRow, context.visualColumn)
+    const editor = context.instance.getActiveEditor()
+    if (editor && !editor.isOpened()) editor.beginEditing(undefined, event)
+  }, 0)
+}
+
+export const bindTableCellEditorTrigger = (
+  td: HTMLTableCellElement,
+  trigger: 'doubleClick' | 'click' | 'icon',
+  open: (event: MouseEvent) => void,
+  messages: TableEngineMessages = TABLE_ENGINE_MESSAGES_ZH_CN
+) => {
+  td.classList.add('table-component__editable')
+  if (trigger === 'doubleClick') {
+    td.ondblclick = open
+    return
+  }
+  if (trigger === 'click') {
+    td.onclick = open
+    return
+  }
+  td.classList.add('table-component__editor-icon-cell')
+  const icon = document.createElement('button')
+  icon.type = 'button'
+  icon.className = 'table-component__editor-icon'
+  icon.textContent = '⌄'
+  icon.setAttribute('aria-label', messages.strOpenCellEditor)
+  icon.onmousedown = (event) => event.stopPropagation()
+  icon.onclick = open
+  td.append(icon)
+}

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

@@ -0,0 +1,3 @@
+export * from './editorBounds'
+export * from './editorTrigger'
+export * from './layerEditor'

package/template/src/components/AppTable/engine/cell/customCell/editors/layerEditor.ts

@@ -0,0 +1,244 @@
+import type Handsontable from 'handsontable'
+import type { ColumnSettings } from 'handsontable'
+import { editorFactory } from 'handsontable/editors'
+import type { TableColumn } from '../../../columns/column'
+import type { TableEngineMessages } from '../../../shared/messages'
+import type { TableOption, TableRow } from '../../../shared/types'
+import { resolveTableMultiSelectConfig } from '../../multiSelect'
+import type { TableCellContext } from '../../types'
+import { createTableCellContext } from '../renderers/shared'
+import { isTableTemporalType, type TableCellLayerAdapter } from '../types'
+import { resolveTableEditorBounds } from './editorBounds'
+
+interface TableLayerEditorState {
+  input: HTMLInputElement
+  value: unknown
+}
+
+interface CreateTableLayerEditorOptions {
+  layer: TableCellLayerAdapter
+  updateCell: (visualRow: number, key: string, value: unknown) => boolean
+  messages: TableEngineMessages
+}
+
+type TableLayerEditor = ReturnType<Handsontable['getActiveEditor']> &
+  TableLayerEditorState
+
+type OpenTableLayerEditor = TableLayerEditor & {
+  row: number
+  col: number
+  TD: HTMLTableCellElement
+}
+
+type TableLayerCommit = (
+  value: unknown,
+  selectedOption?: TableOption | readonly TableOption[]
+) => void
+
+/**
+ * 返回 Handsontable 原生选区框内部的可编辑区域。
+ *
+ * 四条 wtBorder 的位置并不对称，且主题可以改变边框粗细，所以这里读取真实 DOM
+ * 几何，不复制边框、不硬编码 inset；找不到完整边框时安全回退到原单元格范围。
+ */
+const resolveTableLayerEditorRect = (editor: OpenTableLayerEditor) => {
+  const cellRect = editor.TD.getBoundingClientRect()
+  const view = editor.TD.ownerDocument.defaultView
+  if (!view) return cellRect
+  const borderRoot = editor.TD.closest('.wtHolder') ?? editor.hot.rootElement
+  const borderRects = Array.from(
+    borderRoot.querySelectorAll<HTMLElement>('.wtBorder.current')
+  )
+    .filter((border) => view.getComputedStyle(border).display !== 'none')
+    .map((border) => border.getBoundingClientRect())
+    .filter(
+      (rect) =>
+        rect.width > 0 &&
+        rect.height > 0 &&
+        rect.right >= cellRect.left &&
+        rect.left <= cellRect.right &&
+        rect.bottom >= cellRect.top &&
+        rect.top <= cellRect.bottom
+    )
+  const bounds = resolveTableEditorBounds(cellRect, borderRects)
+  return new view.DOMRect(bounds.left, bounds.top, bounds.width, bounds.height)
+}
+
+/** 排除尚未完成定位或已经关闭的 BaseEditor，避免浮层读取空 TD。 */
+const isOpenTableLayerEditor = (
+  editor: TableLayerEditor
+): editor is OpenTableLayerEditor =>
+  editor.row !== null &&
+  editor.col !== null &&
+  Boolean(editor.TD) &&
+  editor.isOpened()
+
+/** 在浮层事务完成后恢复 HOT 的键盘监听和原活动单元格。 */
+const restoreTableLayerEditorFocus = (editor: OpenTableLayerEditor) => {
+  const row = editor.row
+  const column = editor.col
+  editor.hot.rootWindow.requestAnimationFrame(() => {
+    if (editor.hot.isDestroyed || row === null || column === null) return
+    editor.hot.selectCell(row, column, row, column, false)
+    editor.hot.listen()
+  })
+}
+
+/** 在 engine 解析按行属性，但保持属性内容不依赖任何具体组件库。 */
+const resolveTableCellComponentProps = <T extends TableRow>(
+  column: TableColumn<T>,
+  context: TableCellContext<T>
+) => {
+  const source = column.componentProps
+  if (!source) return undefined
+  return typeof source === 'function' ? source(context) : source
+}
+
+/** 封装 select/multiSelect 的公共浮层协议，并返回是否已经接管本次打开。 */
+const openTableSelectLayer = <T extends TableRow>(options: {
+  column: TableColumn<T>
+  editor: OpenTableLayerEditor
+  context: TableCellContext<T>
+  layer: TableCellLayerAdapter
+  messages: TableEngineMessages
+  commit: TableLayerCommit
+}) => {
+  const { column, editor, context, layer, messages, commit } = options
+  const renderer = column.renderer
+  if (renderer !== 'select' && renderer !== 'multiSelect') return false
+  const multiSelect =
+    renderer === 'multiSelect'
+      ? resolveTableMultiSelectConfig(column.options, column.multiSelect)
+      : undefined
+  void layer.openSelect({
+    rect: resolveTableLayerEditorRect(editor),
+    value: editor.originalValue,
+    componentProps: resolveTableCellComponentProps(column, context),
+    multiple: renderer === 'multiSelect' || column.multiple,
+    clearable: column.optionClearable !== false,
+    multipleLimit: multiSelect?.maxSelections,
+    searchable: multiSelect?.searchInput,
+    collapseTags: multiSelect?.collapseTags,
+    maxCollapseTags: multiSelect?.maxCollapseTags,
+    row: context.row,
+    columnKey: String(column.key),
+    source: column.options ?? [],
+    cache: column.optionCache,
+    debounceMs: column.optionDebounceMs,
+    placeholder:
+      multiSelect?.placeholder ??
+      column.optionPlaceholder ??
+      messages.strSelectPlaceholder,
+    onOptionsLoaded: () => editor.hot.render(),
+    preview: (value) => editor.setValue(value),
+    commit,
+    cancel: (cancelOptions) => {
+      editor.cancelChanges()
+      if (cancelOptions?.restoreFocus) restoreTableLayerEditorFocus(editor)
+    },
+  })
+  return true
+}
+
+/**
+ * 将框架无关的单元格浮层接入 Handsontable v18 BaseEditor 事务。
+ * React 层只需实现可视化浮层适配器。
+ */
+export const createTableLayerEditor = <T extends TableRow>(
+  column: TableColumn<T>,
+  options: CreateTableLayerEditorOptions
+): NonNullable<ColumnSettings['editor']> => {
+  const openLayer = (editor: TableLayerEditor) => {
+    if (!isOpenTableLayerEditor(editor)) return
+    // BaseEditor 在完整编辑模式下会把初始值转成字符串；受控值（尤其是数组）
+    // 必须保留原始结构。
+    editor.setValue(editor.originalValue)
+    const context = createTableCellContext<T>({
+      instance: editor.hot,
+      visualRow: editor.row,
+      visualColumn: editor.col,
+      value: editor.originalValue,
+    })
+    const finish: TableLayerCommit = (value, selectedOption) => {
+      const row = editor.row
+      const columnIndex = editor.col
+      // BaseEditor.finishEditing 固定产生原生 `edit` source，会被受控列输入门禁拒绝。
+      // 关闭占位 editor 后，通过 Controller 的 controlledEdit 事务提交真实值。
+      editor.cancelChanges()
+      const accepted = options.updateCell(row, String(column.key), value)
+      if (accepted) {
+        column.onChange?.(value, { ...context, value }, selectedOption)
+      }
+      editor.hot.rootWindow.requestAnimationFrame(() => {
+        if (editor.hot.isDestroyed) return
+        editor.hot.selectCell(row, columnIndex, row, columnIndex, false)
+        editor.hot.listen()
+      })
+    }
+
+    if (
+      openTableSelectLayer({
+        column,
+        editor,
+        context,
+        layer: options.layer,
+        messages: options.messages,
+        commit: finish,
+      })
+    )
+      return
+
+    if (isTableTemporalType(column.renderer)) {
+      options.layer.openDate({
+        rect: resolveTableLayerEditorRect(editor),
+        value: editor.originalValue,
+        componentProps: resolveTableCellComponentProps(column, context),
+        type: column.renderer,
+        commit: finish,
+        cancel: (cancelOptions) => {
+          editor.cancelChanges()
+          if (cancelOptions?.restoreFocus) restoreTableLayerEditorFocus(editor)
+        },
+      })
+    }
+  }
+
+  const Editor = editorFactory<TableLayerEditorState>({
+    value: undefined,
+    shortcutsGroup: `TableComponent.${String(column.key)}.layerEditor`,
+    position: 'container',
+    init(editor) {
+      // BaseEditor 需要可聚焦元素来接收键盘事务，但真实 UI 由外部 layer 渲染。
+      const input = editor.hot.rootDocument.createElement('input')
+      input.type = 'text'
+      input.tabIndex = -1
+      input.setAttribute('aria-hidden', 'true')
+      input.style.cssText =
+        'position:absolute;inline-size:1px;block-size:1px;opacity:0;pointer-events:none'
+      editor.container.style.pointerEvents = 'none'
+      editor.input = input
+    },
+    beforeOpen(editor, { originalValue }) {
+      editor.setValue(originalValue)
+    },
+    afterOpen(editor) {
+      openLayer(editor as TableLayerEditor)
+    },
+    afterClose() {
+      options.layer.close({ cancel: false })
+    },
+    getValue(editor) {
+      return editor.value
+    },
+    setValue(editor, value) {
+      editor.value = value
+    },
+    onFocus(editor) {
+      editor.input.focus({ preventScroll: true })
+    },
+  })
+
+  // v18 当前的类型声明描述的是编辑器实例，但运行时返回的是
+  // ColumnSettings.editor 所需的构造函数。
+  return Editor as unknown as NonNullable<ColumnSettings['editor']>
+}

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

@@ -0,0 +1,7 @@
+export * from './renderers'
+export * from './editors'
+export * from './actions'
+export * from './date'
+export * from './select'
+export * from './tooltip'
+export * from './types'