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

package/template/src/components/AppTable/table/components/types.ts

@@ -0,0 +1,90 @@
+import type { ReactNode } from 'react'
+import type { CellChange } from 'handsontable'
+import type { ResolvedTablePaginationConfig } from '@/components/AppTable/engine/pagination/types'
+import type {
+  TableQueryParams,
+  TableQueryResult,
+} from '@/components/AppTable/engine/search/types'
+import type { SelectionState } from '@/components/AppTable/engine/selection/types'
+import type {
+  TableRow,
+  TableRowInteractionContext,
+  TableSelectionRangeContext,
+} from '@/components/AppTable/engine/shared/types'
+import type { TableExportTask } from '@/components/AppTable/engine/summary/export'
+import type { TableSummaryResult } from '@/components/AppTable/engine/summary/summary'
+import type { TableSnapshot } from '@/components/AppTable/engine/table/controller/types'
+import type { IAppTableMessages, TableComponentProps } from '../../config'
+
+export interface ITablePaginationRenderProps {
+  /** 已补全默认值的分页展示配置。 */
+  pagination: ResolvedTablePaginationConfig
+  /** 从 1 开始的当前页码。 */
+  page: number
+  /** 当前每页条数。 */
+  pageSize: number
+  /** 当前查询条件下的数据总条数。 */
+  total: number
+  /** 根据总条数和每页条数计算出的总页数，最小为 1。 */
+  pageCount: number
+  /** 当前框选区域的格式化数值合计；没有可汇总单元格时为 `null`。 */
+  selectedCellSum: string | null
+  /** 当前是否正在执行查询。 */
+  loading: boolean
+  /** 请求切换页码或每页条数；组件仍负责状态更新和查询。 */
+  onChange: (page: number, pageSize: number) => void
+}
+
+/** AppTable 的 React 展示、交互事件和自定义渲染合同。 */
+export interface ITableComponentProps<
+  T extends TableRow = TableRow,
+> extends TableComponentProps<T> {
+  /** 附加到组件根容器的 CSS 类名。 */
+  className?: string
+  /** 单张表的内建文案覆盖；未提供字段跟随全局 Locale。 */
+  messages?: Partial<IAppTableMessages>
+  /** 是否接入应用级路由和浏览器离开保护，默认开启。 */
+  bProtectUnsavedChanges?: boolean
+  /** 本地数据或查询结果应用到控制器后触发。 */
+  onDataChange?: (rows: T[]) => void
+  /** Handsontable 接受单元格修改后触发，并携带原始变更来源。 */
+  onCellChange?: (changes: CellChange[], source: string) => void
+  /** 显式编辑事务的 dirty 状态变化时通知业务组合层。 */
+  onDirtyChange?: (bIsDirty: boolean, snapshot: TableSnapshot<T>) => void
+  /** 行选择状态变化后触发，同时返回已加载的选中行和完整选择状态。 */
+  onSelectionChange?: (rows: T[], selection: SelectionState<T>) => void
+  /** 单元格框选结束后触发，可用于读取选区和汇总结果。 */
+  onSelectionEnd?: (context: TableSelectionRangeContext) => void
+  /** 单击业务数据行时触发，不包含汇总等展示行。 */
+  onRowClick?: (
+    row: T,
+    rowIndex: number,
+    context: TableRowInteractionContext<T>
+  ) => void
+  /** 双击业务数据行时触发；行详情也会复用该交互。 */
+  onRowDoubleClick?: (
+    row: T,
+    rowIndex: number,
+    context: TableRowInteractionContext<T>
+  ) => void
+  /** 查询开始前触发，参数包含分页、筛选和排序状态。 */
+  onQuery?: (params: TableQueryParams) => void
+  /** 最新一次有效查询成功并应用结果后触发。 */
+  onQuerySuccess?: (result: TableQueryResult<T>) => void
+  /** 页码变化并成功应用后触发。 */
+  onPageChange?: (page: number, pageSize: number) => void
+  /** 每页条数变化并成功应用后触发，同时返回重置后的页码。 */
+  onPageSizeChange?: (pageSize: number, page: number) => void
+  /** 汇总任务成功完成后触发。 */
+  onSummarySuccess?: (result: TableSummaryResult) => void
+  /** 本地导出完成或远程导出任务创建成功后触发。 */
+  onExportSuccess?: (task: TableExportTask) => void
+  /** 创建远程异步导出任务后触发。 */
+  onExportJob?: (task: Extract<TableExportTask, { mode: 'job' }>) => void
+  /** 查询、汇总、导出或表格运行错误的统一通知入口。 */
+  onError?: (error: unknown) => void
+  /** 自定义无数据内容；是否展示仍由组件的反馈策略决定。 */
+  renderEmpty?: () => ReactNode
+  /** 自定义分页 UI；分页状态与查询仍由 TableComponent 管理。 */
+  renderPagination?: (props: ITablePaginationRenderProps) => ReactNode
+}

package/template/src/components/AppTable/table/controller/configuration.ts

@@ -0,0 +1,89 @@
+import { buildTableMutationColumns } from '@/components/AppTable/engine/columns/config/mutation'
+import { buildTableValidationOptions } from '@/components/AppTable/engine/columns/config/validation'
+import { TABLE_DEFAULT_ROW_KEY } from '@/components/AppTable/engine/config/constants'
+import { buildTableSelectionOptions } from '@/components/AppTable/engine/selection/config'
+import type { TableRow } from '@/components/AppTable/engine/shared/types'
+import { resolveTableExportConfig } from '@/components/AppTable/engine/summary/config/export'
+import { resolveTableSummaryConfig } from '@/components/AppTable/engine/summary/config/summary'
+import { createExcelJsTableWriter } from '@/components/AppTable/engine/summary/excelJs'
+import { createTableController } from '@/components/AppTable/engine/table/controller/TableController'
+import type { RowKeyResolver } from '@/components/AppTable/engine/table/editing/types'
+import type {
+  IAppTableMessages,
+  ResolvedTableComponentProps,
+} from '../../config'
+
+export function fnResolveTableRowKey<T extends TableRow>(
+  objProps: ResolvedTableComponentProps<T>
+) {
+  return (objProps.rowKey ?? TABLE_DEFAULT_ROW_KEY) as RowKeyResolver<T>
+}
+
+export function fnCreateConfiguredTableController<T extends TableRow>(
+  objProps: ResolvedTableComponentProps<T>,
+  objMessages: IAppTableMessages
+) {
+  const objRowKey = fnResolveTableRowKey(objProps)
+  const objSummary = resolveTableSummaryConfig(objProps.summary, {
+    locale: objProps.locale,
+    timeZone: objProps.timeZone,
+    label: objMessages.strSummary,
+  })
+  const objExport = resolveTableExportConfig(objProps.exportOptions, {
+    remote: Boolean(objProps.query),
+    defaultXlsxWriter: createExcelJsTableWriter<T>(),
+    locale: objProps.locale,
+    timeZone: objProps.timeZone,
+  })
+  return createTableController<T>({
+    tableKey: objProps.tableKey,
+    runtime: objProps.runtime,
+    initialData: objProps.data,
+    query: objProps.query,
+    selection: objProps.selectable
+      ? buildTableSelectionOptions(objRowKey, objProps.selectionOptions)
+      : undefined,
+    validation: buildTableValidationOptions(
+      objProps.columns,
+      objRowKey,
+      objMessages
+    ),
+    mutation: buildTableMutationColumns(objProps.columns, objMessages),
+    summaryProvider: objSummary?.provider,
+    export: objExport
+      ? { provider: objExport.provider, xlsxWriter: objExport.xlsxWriter }
+      : undefined,
+    editing: objProps.commitChanges
+      ? {
+          rowKey: objRowKey,
+          getVersion: objProps.getRowVersion,
+          commitChanges: objProps.commitChanges,
+          messages: objMessages,
+        }
+      : undefined,
+  })
+}
+
+export function fnApplyTableReportingConfiguration<T extends TableRow>(
+  objProps: ResolvedTableComponentProps<T>,
+  objController: ReturnType<typeof createTableController<T>>,
+  objMessages: IAppTableMessages
+) {
+  const objSummary = resolveTableSummaryConfig(objProps.summary, {
+    locale: objProps.locale,
+    timeZone: objProps.timeZone,
+    label: objMessages.strSummary,
+  })
+  const objExport = resolveTableExportConfig(objProps.exportOptions, {
+    remote: Boolean(objProps.query),
+    defaultXlsxWriter: createExcelJsTableWriter<T>(),
+    locale: objProps.locale,
+    timeZone: objProps.timeZone,
+  })
+  objController.setSummaryProvider(objSummary?.provider)
+  objController.setExport(
+    objExport
+      ? { provider: objExport.provider, xlsxWriter: objExport.xlsxWriter }
+      : undefined
+  )
+}

package/template/src/components/AppTable/table/controller/index.ts

@@ -0,0 +1,2 @@
+export { useTableController } from './useTableController'
+export { useTableLifecycle } from './useTableLifecycle'

package/template/src/components/AppTable/table/controller/useTableController.ts

@@ -0,0 +1,155 @@
+import {
+  useCallback,
+  useEffect,
+  useRef,
+  useState,
+  useSyncExternalStore,
+} from 'react'
+import { buildTableMutationColumns } from '@/components/AppTable/engine/columns/config/mutation'
+import { buildTableValidationOptions } from '@/components/AppTable/engine/columns/config/validation'
+import { buildTableSelectionOptions } from '@/components/AppTable/engine/selection/config'
+import type { TableRow } from '@/components/AppTable/engine/shared/types'
+import type { TableController } from '@/components/AppTable/engine/table/controller/TableController'
+import type { TableSnapshot } from '@/components/AppTable/engine/table/controller/types'
+import type { ResolvedTableComponentProps } from '../../config'
+import { useAppTableMessages } from '../../messages'
+import {
+  fnCreateConfiguredTableController,
+  fnApplyTableReportingConfiguration,
+  fnResolveTableRowKey,
+} from './configuration'
+
+interface IUseTableControllerOptions<T extends TableRow> {
+  strTableKey: string
+  objExternalController?: TableController<T>
+  objProps: ResolvedTableComponentProps<T>
+  fnReportError: (objError: unknown) => void
+}
+
+const fnAreArrayItemsEqual = (
+  arrPrevious: readonly unknown[],
+  arrNext: readonly unknown[]
+) =>
+  arrPrevious === arrNext ||
+  (arrPrevious.length === arrNext.length &&
+    arrPrevious.every((objItem, nIndex) => Object.is(objItem, arrNext[nIndex])))
+
+export function useTableController<T extends TableRow>({
+  strTableKey,
+  objExternalController,
+  objProps,
+  fnReportError,
+}: IUseTableControllerOptions<T>) {
+  const objMessages = useAppTableMessages()
+  const [objController] = useState(
+    () =>
+      objExternalController ??
+      fnCreateConfiguredTableController(objProps, objMessages)
+  )
+  const bOwnsController = !objExternalController
+  const objAppliedConfigurationRef = useRef<
+    ResolvedTableComponentProps<T> | undefined
+  >(bOwnsController ? objProps : undefined)
+
+  const objAppliedMessagesRef = useRef(
+    bOwnsController ? objMessages : undefined
+  )
+
+  if (objController.tableKey !== strTableKey) {
+    throw new Error(
+      `[TableComponent] controller.tableKey "${objController.tableKey}" does not match prop tableKey "${strTableKey}".`
+    )
+  }
+
+  const fnSubscribe = useCallback(
+    (fnListener: () => void) => objController.subscribe(fnListener),
+    [objController]
+  )
+  const fnGetSnapshot = useCallback(
+    () => objController.snapshot,
+    [objController]
+  )
+  const objSnapshot: TableSnapshot<T> = useSyncExternalStore(
+    fnSubscribe,
+    fnGetSnapshot,
+    fnGetSnapshot
+  )
+
+  useEffect(() => {
+    if (objSnapshot.isDirty || objSnapshot.saving || objSnapshot.validating) {
+      return
+    }
+    const objRowKey = fnResolveTableRowKey(objProps)
+    const objPreviousSources = objAppliedConfigurationRef.current
+    const bMessagesChanged = objAppliedMessagesRef.current !== objMessages
+    const bDomainChanged =
+      bMessagesChanged ||
+      !objPreviousSources ||
+      !fnAreArrayItemsEqual(objPreviousSources.columns, objProps.columns) ||
+      objPreviousSources.commitChanges !== objProps.commitChanges ||
+      objPreviousSources.getRowVersion !== objProps.getRowVersion ||
+      objPreviousSources.rowKey !== objProps.rowKey ||
+      objPreviousSources.selectable !== objProps.selectable ||
+      objPreviousSources.selectionOptions !== objProps.selectionOptions
+    const bDataSourceChanged =
+      !objPreviousSources ||
+      objPreviousSources.query !== objProps.query ||
+      objPreviousSources.dataConfigured !== objProps.dataConfigured ||
+      (objProps.dataConfigured &&
+        !fnAreArrayItemsEqual(objPreviousSources.data, objProps.data))
+    const bReportingChanged =
+      bMessagesChanged ||
+      !objPreviousSources ||
+      objPreviousSources.summary !== objProps.summary ||
+      objPreviousSources.exportOptions !== objProps.exportOptions ||
+      objPreviousSources.query !== objProps.query ||
+      objPreviousSources.locale !== objProps.locale ||
+      objPreviousSources.timeZone !== objProps.timeZone
+    try {
+      if (bDomainChanged) {
+        objController.reconfigure({
+          editing: objProps.commitChanges
+            ? {
+                rowKey: objRowKey,
+                getVersion: objProps.getRowVersion,
+                commitChanges: objProps.commitChanges,
+                messages: objMessages,
+              }
+            : undefined,
+          selection: objProps.selectable
+            ? buildTableSelectionOptions(objRowKey, objProps.selectionOptions)
+            : undefined,
+          validation: buildTableValidationOptions(
+            objProps.columns,
+            objRowKey,
+            objMessages
+          ),
+          mutation: buildTableMutationColumns(objProps.columns, objMessages),
+        })
+      }
+      if (bDataSourceChanged) {
+        objController.reconfigureDataSource({
+          query: objProps.query,
+          ...(objProps.dataConfigured ? { rows: objProps.data } : {}),
+        })
+      }
+      if (bReportingChanged) {
+        fnApplyTableReportingConfiguration(objProps, objController, objMessages)
+      }
+      objAppliedConfigurationRef.current = objProps
+      objAppliedMessagesRef.current = objMessages
+    } catch (objError) {
+      fnReportError(objError)
+    }
+  }, [
+    fnReportError,
+    objController,
+    objMessages,
+    objProps,
+    objSnapshot.isDirty,
+    objSnapshot.saving,
+    objSnapshot.validating,
+  ])
+
+  return { objController, objSnapshot, bOwnsController }
+}

package/template/src/components/AppTable/table/controller/useTableLifecycle.ts

@@ -0,0 +1,97 @@
+import { useEffect, useLayoutEffect, useRef, type RefObject } from 'react'
+import type { GridSettings } from 'handsontable'
+import { attachTableCellTooltip } from '@/components/AppTable/engine/cell/customCell/tooltip/tooltip'
+import { type TableCellLayerAdapter } from '@/components/AppTable/engine/cell/customCell/types'
+import {
+  diffTableGridRuntimeSettings,
+  hasTableGridRuntimeSettings,
+} from '@/components/AppTable/engine/config/grid/runtimeDelta'
+import { type TableRow } from '@/components/AppTable/engine/shared/types'
+import { type TableController } from '@/components/AppTable/engine/table/controller/TableController'
+import { useTableGridRuntimeSettings } from '../grid/useTableGridRuntimeSettings'
+
+interface IUseTableLifecycleOptions<T extends TableRow> {
+  objContainerRef: RefObject<HTMLDivElement | null>
+  objController: TableController<T>
+  objGridSettings: GridSettings
+  objLayer: TableCellLayerAdapter
+  fnDestroyCellComponentSession: () => void
+  bOwnsController: boolean
+  bReady: boolean
+  bLayoutTransitioning: boolean
+  fnSyncThemeTokens: () => void
+}
+
+export function useTableLifecycle<T extends TableRow>({
+  objContainerRef,
+  objController,
+  objGridSettings,
+  objLayer,
+  fnDestroyCellComponentSession,
+  bOwnsController,
+  bReady,
+  bLayoutTransitioning,
+  fnSyncThemeTokens,
+}: IUseTableLifecycleOptions<T>) {
+  const objDestroyTimerRef = useRef<number | undefined>(undefined)
+  const objAppliedGridSettingsRef = useRef<GridSettings | null>(null)
+  const objRuntimeGridSettings = useTableGridRuntimeSettings(objGridSettings)
+
+  useLayoutEffect(() => {
+    objController.setLayoutTransitioning(bLayoutTransitioning)
+  }, [bLayoutTransitioning, objController])
+
+  useLayoutEffect(() => {
+    if (!bReady) return
+    if (!objContainerRef.current) return
+    const objInstance = objController.mount(
+      objContainerRef.current,
+      objRuntimeGridSettings
+    )
+    objAppliedGridSettingsRef.current = objRuntimeGridSettings
+    const fnDetachTooltip = attachTableCellTooltip(
+      objContainerRef.current,
+      objLayer
+    )
+    const nThemeSyncFrame = window.requestAnimationFrame(fnSyncThemeTokens)
+    return () => {
+      window.cancelAnimationFrame(nThemeSyncFrame)
+      fnDetachTooltip()
+      if (objController.unmountGrid(objInstance)) {
+        objAppliedGridSettingsRef.current = null
+      }
+    }
+    // 网格实例只挂载一次，后续设置由 updateSettings effect 同步。
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [bReady, fnSyncThemeTokens, objController])
+
+  useEffect(() => {
+    const objPreviousSettings = objAppliedGridSettingsRef.current
+    if (!objController.mounted || !objPreviousSettings) return
+
+    const objRuntimeDelta = diffTableGridRuntimeSettings(
+      objPreviousSettings,
+      objRuntimeGridSettings
+    )
+    if (hasTableGridRuntimeSettings(objRuntimeDelta)) {
+      objController.updateSettings(objRuntimeDelta)
+    }
+    objAppliedGridSettingsRef.current = objRuntimeGridSettings
+  }, [objController, objRuntimeGridSettings])
+
+  // 不在网格节点上重复注册 ResizeObserver：Handsontable 已观察自身 wrapper，
+  // 自适应 Hook 只观察外部高度约束。再次监听并调用 refreshDimensions 会把组件
+  // 自己的 height 写入反馈给 Handsontable，形成尺寸测量循环。
+
+  useEffect(() => {
+    window.clearTimeout(objDestroyTimerRef.current)
+    return () => {
+      objController.setLayoutTransitioning(false)
+      objDestroyTimerRef.current = window.setTimeout(() => {
+        fnDestroyCellComponentSession()
+        objLayer.destroy()
+        if (bOwnsController) objController.destroy()
+      }, 0)
+    }
+  }, [bOwnsController, fnDestroyCellComponentSession, objController, objLayer])
+}

package/template/src/components/AppTable/table/grid/index.ts

@@ -0,0 +1 @@
+export { useTableGrid } from './useTableGrid'