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

package/template/src/components/AppTable/cell/customCell/tooltip/TooltipCell.tsx

@@ -0,0 +1,45 @@
+import {
+  Tooltip,
+  TooltipContent,
+  TooltipProvider,
+  TooltipTrigger,
+} from '@/components/ui/tooltip'
+import type { ITableCellLayerSession } from '../types'
+
+interface ITooltipCellProps {
+  objLayer: ITableCellLayerSession
+}
+
+export function TooltipCell({ objLayer }: ITooltipCellProps) {
+  const objTooltip = objLayer.getSnapshot().tooltip
+  if (!objTooltip.visible || !objTooltip.anchor) return null
+  const objRect = objTooltip.anchor.getBoundingClientRect()
+
+  return (
+    <TooltipProvider delayDuration={0}>
+      <Tooltip open>
+        <TooltipTrigger asChild>
+          <span
+            aria-hidden='true'
+            className='pointer-events-none fixed'
+            style={{
+              top: objRect.top,
+              left: objRect.left,
+              width: objRect.width,
+              height: objRect.height,
+            }}
+          />
+        </TooltipTrigger>
+        <TooltipContent
+          data-table-cell-layer='tooltip-content'
+          side='top'
+          sideOffset={8}
+          collisionPadding={8}
+          className='z-(--z-index-table-cell-tooltip) max-w-[400px] text-wrap break-words'
+        >
+          {objTooltip.content}
+        </TooltipContent>
+      </Tooltip>
+    </TooltipProvider>
+  )
+}

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

@@ -0,0 +1,63 @@
+import type {
+  TableCellComponentProps,
+  TableCellLayerAdapter,
+  TableTemporalType,
+} from '@/components/AppTable/engine/cell/customCell/types'
+import type {
+  TableAction,
+  TableCellContext,
+} from '@/components/AppTable/engine/cell/types'
+import type { TableOption } from '@/components/AppTable/engine/shared/types'
+
+export interface ITableCellEditorState {
+  visible: boolean
+  type: TableTemporalType | 'select'
+  value: unknown
+  componentProps: TableCellComponentProps
+  options: readonly TableOption[]
+  multiple: boolean
+  clearable: boolean
+  multipleLimit: number
+  searchable: boolean
+  collapseTags: boolean
+  maxCollapseTags: number
+  loading: boolean
+  remote: boolean
+  error: string | null
+  debounceMs: number
+  placeholder: string
+  rect: DOMRect | null
+  nSessionId: number
+  preview?: (
+    objValue: unknown,
+    objOption?: TableOption | readonly TableOption[]
+  ) => void
+  commit?: (
+    objValue: unknown,
+    objOption?: TableOption | readonly TableOption[]
+  ) => void
+  cancel?: (objOptions?: { restoreFocus?: boolean }) => void
+}
+
+export interface ITableCellLayerSnapshot {
+  editor: ITableCellEditorState
+  menu: {
+    visible: boolean
+    anchor: { getBoundingClientRect: () => DOMRect } | null
+    trigger: HTMLElement | null
+    actions: readonly TableAction[]
+    context?: TableCellContext
+  }
+  tooltip: {
+    visible: boolean
+    content: string
+    anchor: HTMLElement | null
+  }
+}
+
+export interface ITableCellLayerSession {
+  adapter: TableCellLayerAdapter
+  getSnapshot: () => ITableCellLayerSnapshot
+  subscribe: (fnListener: () => void) => () => void
+  setEditorValue: (objValue: unknown) => void
+}

package/template/src/components/AppTable/cell/customCell/useCellLayerLifecycle.ts

@@ -0,0 +1,111 @@
+import { useEffect } from 'react'
+import type { ITableCellLayerSession, ITableCellLayerSnapshot } from './types'
+
+const strLayerElementSelector = '[data-table-cell-layer]'
+
+const fnIsLayerElement = (objEvent: Event) =>
+  objEvent.target instanceof Element &&
+  Boolean(objEvent.target.closest(strLayerElementSelector))
+
+/** 将 aria-hidden 固定层触发器映射回主表语义单元格。 */
+function fnResolveSemanticFocusTarget(objTrigger: HTMLElement | null) {
+  if (!objTrigger?.closest('[aria-hidden="true"]')) return objTrigger
+  const objOverlayCell = objTrigger.closest<HTMLTableCellElement>(
+    'td[data-visual-row][data-visual-column]'
+  )
+  const objTable = objTrigger.closest<HTMLElement>('.table-component')
+  if (!objOverlayCell || !objTable) return null
+  const nRow = Number(objOverlayCell.dataset.visualRow)
+  const nColumn = Number(objOverlayCell.dataset.visualColumn)
+  if (!Number.isFinite(nRow) || !Number.isFinite(nColumn)) return null
+  const objSemanticCell = objTable.querySelector<HTMLTableCellElement>(
+    `.handsontable.ht_master tr[aria-rowindex="${nRow + 2}"] td[aria-colindex="${nColumn + 2}"]`
+  )
+  if (!objSemanticCell) return null
+  const strLabel = objTrigger.getAttribute('aria-label')
+  const arrCandidates = objSemanticCell.querySelectorAll<HTMLElement>(
+    'button, a[href], input, select, textarea, [tabindex]'
+  )
+  return (
+    Array.from(arrCandidates).find(
+      (objCandidate) =>
+        (strLabel !== null &&
+          objCandidate.getAttribute('aria-label') === strLabel) ||
+        objCandidate.textContent?.trim() === objTrigger.textContent?.trim()
+    ) ?? objSemanticCell.querySelector<HTMLElement>('button, a[href], input')
+  )
+}
+
+export function useCellLayerLifecycle(
+  objLayer: ITableCellLayerSession,
+  objSnapshot: ITableCellLayerSnapshot
+) {
+  useEffect(() => {
+    const fnOnViewportChange = (objEvent: Event) => {
+      const objCurrentSnapshot = objLayer.getSnapshot()
+      if (
+        (!objCurrentSnapshot.editor.visible &&
+          !objCurrentSnapshot.menu.visible) ||
+        objCurrentSnapshot.menu.trigger?.contains(objEvent.target as Node) ||
+        fnIsLayerElement(objEvent)
+      ) {
+        return
+      }
+      objLayer.adapter.close()
+    }
+
+    const fnOnDocumentPointerDown = (objEvent: PointerEvent) => {
+      if (
+        (!objSnapshot.editor.visible && !objSnapshot.menu.visible) ||
+        fnIsLayerElement(objEvent)
+      ) {
+        return
+      }
+      objLayer.adapter.close()
+    }
+
+    const fnOnDocumentScroll = (objEvent: Event) => {
+      if (
+        objEvent.target === document ||
+        objEvent.target === document.documentElement ||
+        objEvent.target === document.body ||
+        fnIsLayerElement(objEvent)
+      ) {
+        return
+      }
+      objLayer.adapter.close()
+    }
+
+    const fnOnDocumentKeyDown = (objEvent: KeyboardEvent) => {
+      if (
+        objEvent.key !== 'Escape' ||
+        (!objSnapshot.editor.visible && !objSnapshot.menu.visible)
+      ) {
+        return
+      }
+      const objTrigger = objSnapshot.menu.visible
+        ? objSnapshot.menu.trigger
+        : null
+      const objFocusTarget = fnResolveSemanticFocusTarget(objTrigger)
+      objEvent.preventDefault()
+      objEvent.stopPropagation()
+      objLayer.adapter.close({
+        restoreFocus: objSnapshot.editor.visible,
+      })
+      objFocusTarget?.focus({ preventScroll: true })
+    }
+
+    window.addEventListener('resize', fnOnViewportChange)
+    window.addEventListener('pointerdown', fnOnDocumentPointerDown, true)
+    document.addEventListener('scroll', fnOnDocumentScroll, true)
+    document.addEventListener('click', fnOnViewportChange)
+    document.addEventListener('keydown', fnOnDocumentKeyDown, true)
+    return () => {
+      window.removeEventListener('resize', fnOnViewportChange)
+      window.removeEventListener('pointerdown', fnOnDocumentPointerDown, true)
+      document.removeEventListener('scroll', fnOnDocumentScroll, true)
+      document.removeEventListener('click', fnOnViewportChange)
+      document.removeEventListener('keydown', fnOnDocumentKeyDown, true)
+    }
+  }, [objLayer, objSnapshot])
+}

package/template/src/components/AppTable/cell/frameworkCell/TableCellComponentLayer.tsx

@@ -0,0 +1,40 @@
+import { createElement, memo, useSyncExternalStore } from 'react'
+import { createPortal } from 'react-dom'
+import type {
+  ITableCellComponentEntry,
+  ITableCellComponentSession,
+} from './cellComponentSession'
+
+interface ITableCellComponentLayerProps {
+  objSession: ITableCellComponentSession
+}
+
+interface ITableCellComponentEntryViewProps {
+  objEntry: ITableCellComponentEntry
+}
+
+/** 仅在当前 TD 对应的组件、Props 或数据版本变化时重绘该单元格。 */
+const TableCellComponentEntryView = memo(function TableCellComponentEntryView({
+  objEntry,
+}: ITableCellComponentEntryViewProps) {
+  return createElement(objEntry.CellComponent, objEntry.objProps)
+})
+
+/** 在 TableComponent 原有 React 树内统一承载所有可见框架组件单元格。 */
+export function TableCellComponentLayer({
+  objSession,
+}: ITableCellComponentLayerProps) {
+  const arrEntries = useSyncExternalStore(
+    objSession.subscribe,
+    objSession.getSnapshot,
+    objSession.getSnapshot
+  )
+
+  return arrEntries.map((objEntry) =>
+    createPortal(
+      <TableCellComponentEntryView objEntry={objEntry} />,
+      objEntry.objHost,
+      objEntry.nId
+    )
+  )
+}

package/template/src/components/AppTable/cell/frameworkCell/cellComponentSession.ts

@@ -0,0 +1,203 @@
+import type { BaseRenderer } from 'handsontable/renderers'
+import { resolveColumnFormat } from '@/components/AppTable/engine/cell/customCell/renderers/display'
+import { resetTableInteractiveCell } from '@/components/AppTable/engine/cell/customCell/renderers/shared'
+import { setTableCellTooltip } from '@/components/AppTable/engine/cell/customCell/tooltip/tooltip'
+import type { TableValueFormat } from '@/components/AppTable/engine/cell/formatting'
+import { getTableRowValue } from '@/components/AppTable/engine/shared/row'
+import type { TableRow } from '@/components/AppTable/engine/shared/types'
+import type {
+  TableCellRendererComponent,
+  TableCellRendererProps,
+  TableColumn,
+} from '../../config'
+
+export interface ITableCellComponentEntry {
+  nId: number
+  objHost: HTMLSpanElement
+  CellComponent: TableCellRendererComponent<any>
+  objProps: TableCellRendererProps<any>
+  /** 生成该单元格 Props 时对应的业务数据版本。 */
+  nDataRevision: number
+}
+
+export interface ITableCellComponentSession {
+  subscribe: (fnListener: () => void) => () => void
+  getSnapshot: () => readonly ITableCellComponentEntry[]
+  /** 创建框架单元格 renderer；数据版本读取器用于识别后端 DTO 的原地更新。 */
+  createRenderer: <T extends TableRow>(
+    objColumn: TableColumn<T>,
+    CellComponent: TableCellRendererComponent<T>,
+    fnFormatValue: (objValue: unknown, objFormat?: TableValueFormat) => unknown,
+    fnGetDataRevision?: () => number
+  ) => BaseRenderer
+  prune: () => void
+  destroy: () => void
+}
+
+const fnResetReusedCell = (objCell: HTMLTableCellElement) => {
+  resetTableInteractiveCell(objCell)
+  setTableCellTooltip(objCell, undefined)
+}
+
+/**
+ * 判断两次 renderer 产生的公开 Props 是否相同。
+ *
+ * Handsontable 在滚动、冻结列和 overlay 同步时会重复渲染同一个 TD。这里使用
+ * 固定字段比较保留后端 DTO 的引用语义，并避免在滚动热路径创建 Object.keys 数组。
+ */
+const fnAreCellComponentPropsEqual = (
+  objPrevious: TableCellRendererProps<any>,
+  objNext: TableCellRendererProps<any>
+) =>
+  objPrevious.row === objNext.row &&
+  objPrevious.rowIndex === objNext.rowIndex &&
+  objPrevious.visualRow === objNext.visualRow &&
+  objPrevious.visualColumn === objNext.visualColumn &&
+  objPrevious.physicalRow === objNext.physicalRow &&
+  objPrevious.physicalColumn === objNext.physicalColumn &&
+  objPrevious.columnIndex === objNext.columnIndex &&
+  Object.is(objPrevious.value, objNext.value) &&
+  Object.is(objPrevious.displayValue, objNext.displayValue) &&
+  objPrevious.instance === objNext.instance
+
+/**
+ * 每张表一个 React 单元格组件会话。
+ *
+ * Handsontable 会复用 TD；会话以实际 TD 为身份复用宿主，并只发布一个批量快照。
+ * React Portal 始终挂到独立 span，HOT 替换 TD 内容时不会直接破坏 React 管理的节点。
+ */
+export const createTableCellComponentSession =
+  (): ITableCellComponentSession => {
+    const objEntries = new Map<HTMLTableCellElement, ITableCellComponentEntry>()
+    const setListeners = new Set<() => void>()
+    let arrSnapshot: readonly ITableCellComponentEntry[] = []
+    let nNextId = 1
+    let bPublishScheduled = false
+    let bSnapshotDirty = false
+    let bDestroyed = false
+
+    const fnPublish = () => {
+      bPublishScheduled = false
+      if (bDestroyed) return
+      let bSnapshotChanged = bSnapshotDirty
+      bSnapshotDirty = false
+      for (const [objCell, objEntry] of objEntries) {
+        if (!objCell.isConnected || objEntry.objHost.parentNode !== objCell) {
+          objEntries.delete(objCell)
+          bSnapshotChanged = true
+        }
+      }
+      if (!bSnapshotChanged) return
+      arrSnapshot = [...objEntries.values()]
+      setListeners.forEach((fnListener) => fnListener())
+    }
+
+    const fnSchedulePublish = () => {
+      if (bPublishScheduled || bDestroyed) return
+      bPublishScheduled = true
+      queueMicrotask(fnPublish)
+    }
+
+    const fnRegister = <T extends TableRow>(
+      objCell: HTMLTableCellElement,
+      CellComponent: TableCellRendererComponent<T>,
+      objProps: TableCellRendererProps<T>,
+      nDataRevision: number
+    ) => {
+      if (bDestroyed) return
+      fnResetReusedCell(objCell)
+      let objEntry: ITableCellComponentEntry | undefined =
+        objEntries.get(objCell)
+      if (!objEntry) {
+        const objHost = document.createElement('span')
+        objHost.dataset.tableCellComponentHost = ''
+        objHost.style.display = 'contents'
+        objEntry = {
+          nId: nNextId++,
+          objHost,
+          CellComponent: CellComponent as TableCellRendererComponent<any>,
+          objProps: objProps as TableCellRendererProps<any>,
+          nDataRevision,
+        }
+        objEntries.set(objCell, objEntry)
+        bSnapshotDirty = true
+      } else if (
+        objEntry.CellComponent !== CellComponent ||
+        objEntry.nDataRevision !== nDataRevision ||
+        !fnAreCellComponentPropsEqual(objEntry.objProps, objProps)
+      ) {
+        objEntry = {
+          ...objEntry,
+          CellComponent: CellComponent as TableCellRendererComponent<any>,
+          objProps: objProps as TableCellRendererProps<any>,
+          nDataRevision,
+        }
+        objEntries.set(objCell, objEntry)
+        bSnapshotDirty = true
+      }
+      if (objEntry.objHost.parentNode !== objCell) {
+        objCell.replaceChildren(objEntry.objHost)
+      }
+      if (bSnapshotDirty) fnSchedulePublish()
+    }
+
+    return {
+      subscribe(fnListener) {
+        setListeners.add(fnListener)
+        return () => setListeners.delete(fnListener)
+      },
+      getSnapshot: () => arrSnapshot,
+      createRenderer:
+        <T extends TableRow>(
+          objColumn: TableColumn<T>,
+          CellComponent: TableCellRendererComponent<T>,
+          fnFormatValue: (
+            objValue: unknown,
+            objFormat?: TableValueFormat
+          ) => unknown,
+          fnGetDataRevision = () => 0
+        ): BaseRenderer =>
+        (
+          objInstance,
+          objCell,
+          nVisualRow,
+          nVisualColumn,
+          _objProperty,
+          objDisplayValue
+        ) => {
+          const nPhysicalRow = objInstance.toPhysicalRow(nVisualRow)
+          const nPhysicalColumn =
+            objInstance.toPhysicalColumn?.(nVisualColumn) ?? nVisualColumn
+          const objRow = objInstance.getSourceDataAtRow(nPhysicalRow) as T
+          const objResolvedDisplayValue = objColumn.formatter
+            ? objDisplayValue
+            : fnFormatValue(objDisplayValue, resolveColumnFormat(objColumn))
+          fnRegister(
+            objCell,
+            CellComponent,
+            {
+              row: objRow,
+              rowIndex: nVisualRow,
+              visualRow: nVisualRow,
+              visualColumn: nVisualColumn,
+              physicalRow: nPhysicalRow,
+              physicalColumn: nPhysicalColumn,
+              columnIndex: nVisualColumn,
+              value: getTableRowValue(objRow, String(objColumn.key)),
+              displayValue: objResolvedDisplayValue,
+              instance: objInstance,
+            },
+            fnGetDataRevision()
+          )
+        },
+      prune: fnSchedulePublish,
+      destroy() {
+        if (bDestroyed) return
+        bDestroyed = true
+        objEntries.forEach((objEntry) => objEntry.objHost.remove())
+        objEntries.clear()
+        arrSnapshot = []
+        setListeners.clear()
+      },
+    }
+  }

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

@@ -0,0 +1,3 @@
+export { createTableCellComponentSession } from './cellComponentSession'
+export type { ITableCellComponentSession } from './cellComponentSession'
+export { TableCellComponentLayer } from './TableCellComponentLayer'

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

@@ -0,0 +1,2 @@
+export * from './customCell'
+export * from './frameworkCell'