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

package/template/src/components/AppTable/selection/useTableSelection.ts

@@ -0,0 +1,188 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
+import type { TableQuerySelectionTokenProvider } from '@/components/AppTable/engine/component/types'
+import { createTableQueryIdentity } from '@/components/AppTable/engine/search/query'
+import type { SelectionState } from '@/components/AppTable/engine/selection/types'
+import { flattenTableRows } from '@/components/AppTable/engine/shared/treeRows'
+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'
+
+interface IUseTableSelectionOptions<T extends TableRow> {
+  strTableKey: string
+  objController: TableController<T>
+  objSnapshot: TableSnapshot<T>
+  objProps: ResolvedTableComponentProps<T>
+  fnOnChange?: (arrRows: T[], objSelection: SelectionState<T>) => void
+  fnOnSelectionSummary?: () => void
+  fnReportError: (objError: unknown) => void
+}
+
+/** 管理 React 选择工具栏状态、查询令牌竞态和跨页全选。 */
+export function useTableSelection<T extends TableRow>({
+  strTableKey,
+  objController,
+  objSnapshot,
+  objProps,
+  fnOnChange,
+  fnOnSelectionSummary,
+  fnReportError,
+}: IUseTableSelectionOptions<T>) {
+  const objMessages = useAppTableMessages()
+  const [bSelectingAllMatching, fnSetSelectingAllMatching] = useState(false)
+  const nTokenRequestIdRef = useRef(0)
+  const objTokenRequestRef = useRef<AbortController | undefined>(undefined)
+  const arrSelectedRows = useMemo(
+    () => [...objSnapshot.selection.loadedRows.values()],
+    [objSnapshot.selection]
+  )
+  const arrSelectablePageRows = useMemo(
+    () =>
+      flattenTableRows(objSnapshot.rows).filter((objRow) =>
+        objController.canSelectRow(objRow)
+      ),
+    [objController, objSnapshot.rows]
+  )
+  const objSelectionHeaderState = useMemo(
+    () => ({
+      selectableRows: arrSelectablePageRows,
+      selectedCount: arrSelectablePageRows.reduce(
+        (nCount, objRow) =>
+          nCount + (objController.isRowSelected(objRow) ? 1 : 0),
+        0
+      ),
+    }),
+    // 控制器内部读取 selection，快照变化必须使表头计数重新计算。
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [arrSelectablePageRows, objController, objSnapshot.selection]
+  )
+  const bHasSelection =
+    objSnapshot.selection.mode === 'allMatching' ||
+    objSnapshot.selection.keys.size > 0
+  const bCanSelectAllMatching =
+    Boolean(objProps.query && objProps.getQuerySelectionToken) &&
+    objProps.selectionOptions.multiple !== false &&
+    objSnapshot.selection.mode === 'explicit' &&
+    arrSelectablePageRows.length > 0 &&
+    objSnapshot.total > arrSelectablePageRows.length &&
+    arrSelectablePageRows.every((objRow) => objController.isRowSelected(objRow))
+  const strSelectionLabel =
+    objSnapshot.selection.mode === 'allMatching'
+      ? objMessages.fnAllMatchingSelected(
+          objSnapshot.selection.excludedKeys.size
+        )
+      : objMessages.fnSelectedCount(objSnapshot.selection.keys.size)
+
+  const fnEmitSelection = useCallback(() => {
+    const objSelection = objController.getSelection()
+    fnOnChange?.(objController.getLoadedSelectedRows(), objSelection)
+    objController.render()
+    fnOnSelectionSummary?.()
+  }, [fnOnChange, fnOnSelectionSummary, objController])
+
+  const fnClearSelection = useCallback(() => {
+    objController.clearSelection()
+    fnEmitSelection()
+  }, [fnEmitSelection, objController])
+
+  const fnCancelSelectionTokenRequest = useCallback(() => {
+    nTokenRequestIdRef.current += 1
+    objTokenRequestRef.current?.abort('query-selection-token-invalidated')
+    objTokenRequestRef.current = undefined
+  }, [])
+
+  useEffect(
+    () => () => fnCancelSelectionTokenRequest(),
+    [fnCancelSelectionTokenRequest]
+  )
+
+  const fnSelectAllMatching = useCallback(
+    (strQueryToken: string) => {
+      objController.selectAllMatching(strQueryToken)
+      fnEmitSelection()
+    },
+    [fnEmitSelection, objController]
+  )
+
+  const fnRequestSelectAllMatching = useCallback(async () => {
+    if (bSelectingAllMatching) return
+    const fnGetQueryToken: TableQuerySelectionTokenProvider | undefined =
+      objProps.getQuerySelectionToken
+    if (!fnGetQueryToken) {
+      fnReportError(
+        new Error(
+          `[TableComponent] Table "${strTableKey}" requires getQuerySelectionToken for query-wide selection.`
+        )
+      )
+      return
+    }
+    const objParams = objController.getQueryParams()
+    if (!objParams) {
+      fnReportError(
+        new Error(
+          `[TableComponent] Table "${strTableKey}" must apply a query before requesting a query-wide selection token.`
+        )
+      )
+      return
+    }
+    fnCancelSelectionTokenRequest()
+    const nRequestId = nTokenRequestIdRef.current
+    const objAbortController = new AbortController()
+    objTokenRequestRef.current = objAbortController
+    const strQuerySignature = createTableQueryIdentity(objParams)
+    fnSetSelectingAllMatching(true)
+    try {
+      const strToken = await fnGetQueryToken(objParams, {
+        signal: objAbortController.signal,
+        querySignature: strQuerySignature,
+      })
+      const objCurrentParams = objController.getQueryParams()
+      if (
+        objAbortController.signal.aborted ||
+        nRequestId !== nTokenRequestIdRef.current ||
+        !objCurrentParams ||
+        strQuerySignature !== createTableQueryIdentity(objCurrentParams)
+      ) {
+        return
+      }
+      fnSelectAllMatching(strToken)
+    } catch (objError) {
+      if (
+        !objAbortController.signal.aborted &&
+        nRequestId === nTokenRequestIdRef.current
+      ) {
+        fnReportError(objError)
+      }
+    } finally {
+      if (objTokenRequestRef.current === objAbortController) {
+        objTokenRequestRef.current = undefined
+      }
+      if (nRequestId === nTokenRequestIdRef.current) {
+        fnSetSelectingAllMatching(false)
+      }
+    }
+  }, [
+    bSelectingAllMatching,
+    fnCancelSelectionTokenRequest,
+    fnReportError,
+    fnSelectAllMatching,
+    objController,
+    objProps.getQuerySelectionToken,
+    strTableKey,
+  ])
+
+  return {
+    arrSelectedRows,
+    objSelectionHeaderState,
+    bHasSelection,
+    bCanSelectAllMatching,
+    bSelectingAllMatching,
+    strSelectionLabel,
+    fnEmitSelection,
+    fnClearSelection,
+    fnCancelSelectionTokenRequest,
+    fnSelectAllMatching,
+    fnRequestSelectAllMatching,
+  }
+}

package/template/src/components/AppTable/sensitiveData.tsx

@@ -0,0 +1,41 @@
+import { SensitiveData } from '@/components/SensitiveData'
+import type {
+  ICreateSensitiveDataTableColumnOptions,
+  TableCellComponentColumn,
+  TableCellRendererProps,
+} from './config'
+import type { TableRow } from './engine/shared/types'
+
+/**
+ * 创建关闭 AppTable 原生复制和编辑旁路的敏感数据列。
+ *
+ * 如果列表接口不应返回原始值，仍必须让 objValue 使用 masked 形态，并通过
+ * fnRequestReveal 调用后端独立授权接口；该列工厂不能替代后端数据权限。
+ */
+export function fnCreateSensitiveDataTableColumn<
+  T extends TableRow = TableRow,
+  TValue = unknown,
+>({
+  fnResolveSensitiveDataProps,
+  objColumn,
+}: ICreateSensitiveDataTableColumnOptions<
+  T,
+  TValue
+>): TableCellComponentColumn<T> {
+  function SensitiveDataCell(objCell: TableCellRendererProps<T, TValue>) {
+    return (
+      <SensitiveData
+        {...fnResolveSensitiveDataProps(objCell)}
+        strLabel={objColumn.label}
+      />
+    )
+  }
+
+  return {
+    ...objColumn,
+    cellComponent: SensitiveDataCell,
+    copyable: false,
+    exportable: false,
+    readOnly: true,
+  }
+}

package/template/src/components/AppTable/shared/styles.ts

@@ -0,0 +1,2 @@
+export const strTableSelectClassName =
+  'flex h-9 rounded-md border border-input bg-transparent px-3 py-1 text-sm shadow-xs outline-none focus-visible:border-ring focus-visible:ring-[3px] focus-visible:ring-ring/50 disabled:cursor-not-allowed disabled:opacity-50'

package/template/src/components/AppTable/styles/index.css

@@ -0,0 +1,6 @@
+@import 'tailwindcss/theme.css' layer(theme);
+@import 'tailwindcss/utilities.css' layer(utilities);
+@import './theme.css';
+@import './tableComponent.css';
+
+@source '../**/*.{ts,tsx}';

package/template/src/components/AppTable/styles/tableComponent.css

@@ -0,0 +1,297 @@
+.table-component {
+  --table-component-primary: var(--primary);
+  --table-component-fixed-end-shadow-color: rgb(0 0 0 / 16%);
+}
+
+.table-component .handsontable {
+  font-family: inherit;
+  font-size: 0.8125rem;
+  color: var(--foreground);
+}
+
+.table-component .handsontable table.htCore {
+  border-spacing: 0;
+}
+
+.table-component .handsontable th,
+.table-component .handsontable td {
+  border-color: var(--border) !important;
+}
+
+.table-component .handsontable th {
+  font-weight: 600;
+}
+
+.table-component .handsontable tbody tr th .relative {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+}
+
+.table-component .handsontable .table-component__selection-header .colHeader {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+}
+
+/* Handsontable 默认让 colHeader 占满剩余宽度，导致标题旁空白也会触发排序。 */
+.table-component
+  .handsontable
+  thead
+  tr
+  th
+  .relative
+  .colHeader.columnSorting.sortAction {
+  flex: 0 1 auto;
+  margin-inline: auto;
+}
+
+.table-component .handsontable td {
+  color: var(--foreground) !important;
+}
+
+.table-component .handsontable td > .table-component__actions {
+  display: flex;
+  gap: 0.25rem;
+  align-items: center;
+  justify-content: center;
+  width: 100%;
+  min-height: 100%;
+}
+
+.table-component .handsontable [data-slot='table-action'] {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  padding: 0.25rem;
+  font: inherit;
+  font-weight: 500;
+  line-height: 1rem;
+  color: var(--table-component-primary);
+  white-space: nowrap;
+  text-underline-offset: 0.25rem;
+  cursor: pointer;
+  background: transparent;
+  border: 0;
+  border-radius: 0.375rem;
+}
+
+.table-component .handsontable [data-slot='table-action'].is-more {
+  gap: 0.125rem;
+}
+
+.table-component .handsontable .table-component__action-dropdown-icon {
+  flex: none;
+}
+
+.table-component .handsontable [data-slot='table-action']:hover {
+  text-decoration: underline;
+}
+
+.table-component .handsontable [data-slot='table-action']:focus-visible {
+  outline: none;
+  box-shadow: inset 0 0 0 2px color-mix(in oklab, var(--ring) 70%, transparent);
+}
+
+.table-component .handsontable [data-slot='table-action'].is-danger {
+  color: var(--destructive);
+}
+
+.table-component .handsontable [data-slot='table-action']:disabled {
+  color: var(--muted-foreground);
+  text-decoration: none;
+  cursor: not-allowed;
+  background: transparent;
+  opacity: 0.5;
+}
+
+.table-component__fixed-end-shadow {
+  position: absolute;
+  inset-block-start: 0;
+  z-index: 190;
+  width: 0.5rem;
+  height: 0;
+  contain: strict;
+  pointer-events: none;
+  background: linear-gradient(
+    to right,
+    transparent,
+    var(--table-component-fixed-end-shadow-color)
+  );
+  transform: translate3d(-100%, 0, 0);
+  will-change: transform;
+}
+
+.table-component__fixed-end-shadow.is-rtl {
+  background: linear-gradient(
+    to left,
+    transparent,
+    var(--table-component-fixed-end-shadow-color)
+  );
+  transform: translateZ(0);
+}
+
+.table-component__fixed-end-overlay {
+  position: absolute;
+  z-index: 185;
+  contain: strict;
+  overflow: hidden;
+  pointer-events: none;
+  transform: translateZ(0);
+  will-change: transform;
+}
+
+.table-component__fixed-end-overlay table {
+  table-layout: fixed;
+  border-spacing: 0;
+  border-collapse: separate;
+}
+
+.table-component__fixed-end-overlay th,
+.table-component__fixed-end-overlay td {
+  box-sizing: border-box;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  vertical-align: middle;
+  white-space: nowrap;
+  pointer-events: auto;
+}
+
+.table-component .handsontable .table-component__fixed-end-overlay th,
+.table-component .handsontable .table-component__fixed-end-overlay td {
+  height: inherit;
+}
+
+.table-component .handsontable .table-component__fixed-end-overlay th {
+  padding: 0;
+}
+
+.table-component .handsontable .table-component__fixed-end-overlay td {
+  padding: 0 var(--ht-cell-horizontal-padding, 0.75rem);
+}
+
+.table-component
+  .handsontable
+  .table-component__fixed-end-overlay
+  thead
+  tr
+  > th:first-child,
+.table-component
+  .handsontable
+  .table-component__fixed-end-overlay
+  tbody
+  tr
+  > td:first-child {
+  border-inline-start-width: 0;
+}
+
+.table-component__fixed-end-overlay th {
+  font-weight: var(--ht-header-font-weight, 600);
+  color: var(--ht-header-foreground-color, var(--foreground));
+  text-align: center;
+  background: var(--ht-header-background-color, var(--muted));
+}
+
+.table-component__fixed-end-overlay td {
+  color: var(--ht-foreground-color, var(--foreground));
+  background: var(--ht-row-cell-odd-background-color, var(--background));
+}
+
+.table-component__fixed-end-overlay td.table-component__striped-row {
+  background: var(
+    --ht-row-cell-even-background-color,
+    color-mix(in oklab, var(--table-component-primary) 3%, var(--background))
+  ) !important;
+}
+
+.table-component__fixed-end-overlay td.table-component__current-row {
+  background: color-mix(
+    in oklab,
+    var(--table-component-primary) 6%,
+    var(--background)
+  ) !important;
+}
+
+.table-component__fixed-end-overlay-header {
+  position: absolute;
+  inset-block: 0 auto;
+  inset-inline: 0;
+}
+
+.table-component__fixed-end-overlay-body {
+  position: absolute;
+  inset-inline: 0;
+  bottom: 0;
+  overflow: hidden;
+}
+
+.table-component__fixed-end-overlay-body > table,
+.table-component__fixed-end-overlay-footer > table {
+  position: absolute;
+  inset-inline-end: 0;
+}
+
+.table-component__fixed-end-overlay-footer {
+  position: absolute;
+  inset-inline: 0;
+  overflow: hidden;
+}
+
+.table-component .handsontable td.table-component__current-row {
+  background: color-mix(
+    in oklab,
+    var(--table-component-primary) 6%,
+    var(--background)
+  ) !important;
+}
+
+.table-component .handsontable td.table-component__striped-row {
+  background-color: color-mix(
+    in oklab,
+    var(--table-component-primary) 3%,
+    var(--background)
+  ) !important;
+}
+
+.table-component .handsontable td.area,
+.table-component .handsontable td.current {
+  background: color-mix(
+    in oklab,
+    var(--table-component-primary) 9%,
+    var(--background)
+  ) !important;
+}
+
+.table-component .handsontable input[type='checkbox'] {
+  accent-color: var(--table-component-primary);
+}
+
+.table-component .wtHolder {
+  scrollbar-color: var(--border) transparent;
+  scrollbar-width: thin;
+}
+
+/*
+ * TableComponent 的外层容器负责绘制组件边框。Handsontable 在出现横向
+ * 滚动时会给整个可滚动视口添加 inset 边框；fill 高度下数据不足一屏时，
+ * 这条边框会把剩余空间误画成空白表格区域。
+ */
+.table-component .handsontable.ht-wrapper.htHasScrollX .ht_master .wtHolder {
+  box-shadow: none;
+}
+
+.table-component .handsontable .htDimmed {
+  color: var(--foreground) !important;
+  background-color: var(--background) !important;
+}
+
+.dark .table-component .handsontable th,
+.dark .table-component .handsontable td {
+  background-color: var(--background) !important;
+}
+
+.dark .table-component,
+.table-component.dark {
+  --table-component-primary: #7aadff;
+  --table-component-fixed-end-shadow-color: rgb(0 0 0 / 42%);
+}

package/template/src/components/AppTable/styles/theme.css

@@ -0,0 +1,133 @@
+/* Tailwindadmin palette, source commit: 383285f4d3d462d64fd54691d1356a7f2bc89aa5 */
+.hgw-table-theme {
+  --radius: 0.625rem;
+  --background: #fff;
+  --foreground: #1c2536;
+  --card: #fff;
+  --card-foreground: #1c2536;
+  --popover: #fff;
+  --popover-foreground: #1c2536;
+  --primary: #4068d5;
+  --primary-foreground: #fff;
+  --secondary: #49beff;
+  --secondary-foreground: #102a43;
+  --muted: #f5f5f5;
+  --muted-foreground: #5a6a85;
+  --accent: color-mix(in oklab, var(--primary) 12%, transparent);
+  --accent-foreground: var(--primary);
+  --destructive: #dc2626;
+  --border: #dfe5ef;
+  --input: #e5e7eb;
+  --ring: color-mix(in oklab, var(--primary) 30%, transparent);
+  --chart-1: var(--primary);
+  --chart-2: var(--secondary);
+  --chart-3: #13deb9;
+  --chart-4: #f6b51e;
+  --chart-5: #ef4444;
+  --info: #8754ec;
+  --success: #13deb9;
+  --warning: #f6b51e;
+  --error: #ef4444;
+
+  /* Portal layers stay above Handsontable overlays (up to 180). */
+  --z-index-table-cell-layer: 2100;
+  --z-index-table-cell-menu: 2110;
+  --z-index-table-cell-tooltip: 2120;
+  --z-index-modal-overlay: 3000;
+  --z-index-modal: 3010;
+  --z-index-popover: 3100;
+  --z-index-tooltip: 3200;
+
+  --sidebar: #fff;
+  --sidebar-foreground: #2a3547;
+  --sidebar-primary: var(--primary);
+  --sidebar-primary-foreground: var(--primary-foreground);
+  --sidebar-accent: var(--accent);
+  --sidebar-accent-foreground: var(--accent-foreground);
+  --sidebar-border: var(--border);
+  --sidebar-ring: #a1a1a1;
+}
+
+.dark .hgw-table-theme,
+.hgw-table-theme.dark {
+  --background: #1c2536;
+  --foreground: #fff;
+  --card: #1c2536;
+  --card-foreground: #fff;
+  --popover: #333f55;
+  --popover-foreground: #fff;
+  --primary: #8aadff;
+  --primary-foreground: #0f172a;
+  --secondary: #49beff;
+  --secondary-foreground: #102a43;
+  --muted: #2a3851;
+  --muted-foreground: #7c8fac;
+  --accent: color-mix(in oklab, var(--primary) 20%, transparent);
+  --accent-foreground: var(--primary);
+  --destructive: #dc2626;
+  --border: #333f55;
+  --input: #333f55;
+  --ring: color-mix(in oklab, var(--primary) 40%, transparent);
+  --chart-1: var(--primary);
+  --chart-2: var(--secondary);
+  --chart-3: #13deb9;
+  --chart-4: #f6b51e;
+  --chart-5: #ef4444;
+  --info: #8754ec;
+  --success: #13deb9;
+  --warning: #f6b51e;
+  --error: #ef4444;
+
+  --sidebar: #1c2536;
+  --sidebar-foreground: #7c8fac;
+  --sidebar-primary: var(--primary);
+  --sidebar-primary-foreground: var(--primary-foreground);
+  --sidebar-accent: var(--accent);
+  --sidebar-accent-foreground: var(--accent-foreground);
+  --sidebar-border: var(--border);
+  --sidebar-ring: #a1a1a1;
+}
+
+@theme inline {
+  --font-sans: 'Inter Variable', ui-sans-serif, system-ui, sans-serif;
+
+  --radius-sm: calc(var(--radius) - 4px);
+  --radius-md: calc(var(--radius) - 2px);
+  --radius-lg: var(--radius);
+  --radius-xl: calc(var(--radius) + 4px);
+  --color-background: var(--background);
+  --color-foreground: var(--foreground);
+  --color-card: var(--card);
+  --color-card-foreground: var(--card-foreground);
+  --color-popover: var(--popover);
+  --color-popover-foreground: var(--popover-foreground);
+  --color-primary: var(--primary);
+  --color-primary-foreground: var(--primary-foreground);
+  --color-secondary: var(--secondary);
+  --color-secondary-foreground: var(--secondary-foreground);
+  --color-muted: var(--muted);
+  --color-muted-foreground: var(--muted-foreground);
+  --color-accent: var(--accent);
+  --color-accent-foreground: var(--accent-foreground);
+  --color-destructive: var(--destructive);
+  --color-border: var(--border);
+  --color-input: var(--input);
+  --color-ring: var(--ring);
+  --color-chart-1: var(--chart-1);
+  --color-chart-2: var(--chart-2);
+  --color-chart-3: var(--chart-3);
+  --color-chart-4: var(--chart-4);
+  --color-chart-5: var(--chart-5);
+  --color-info: var(--info);
+  --color-success: var(--success);
+  --color-warning: var(--warning);
+  --color-error: var(--error);
+  --color-sidebar: var(--sidebar);
+  --color-sidebar-foreground: var(--sidebar-foreground);
+  --color-sidebar-primary: var(--sidebar-primary);
+  --color-sidebar-primary-foreground: var(--sidebar-primary-foreground);
+  --color-sidebar-accent: var(--sidebar-accent);
+  --color-sidebar-accent-foreground: var(--sidebar-accent-foreground);
+  --color-sidebar-border: var(--sidebar-border);
+  --color-sidebar-ring: var(--sidebar-ring);
+}