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

package/template/src/components/AppTable/pagination/TablePaginationBar.tsx

@@ -0,0 +1,193 @@
+import { useEffect, useState, type FormEvent } from 'react'
+import { Button } from '@/components/ui/button'
+import { Input } from '@/components/ui/input'
+import {
+  Pagination,
+  PaginationContent,
+  PaginationEllipsis,
+  PaginationFirst,
+  PaginationItem,
+  PaginationLast,
+  PaginationLink,
+  PaginationNext,
+  PaginationPrevious,
+} from '@/components/ui/pagination'
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from '@/components/ui/select'
+import type { ResolvedTablePaginationConfig } from '@/components/AppTable/engine/pagination/types'
+import { useAppTableMessages } from '../messages'
+import { buildTablePaginationItems } from './paginationItems'
+
+interface ITablePaginationBarProps {
+  objPagination: ResolvedTablePaginationConfig
+  nPage: number
+  nPageSize: number
+  nTotal: number
+  strSelectedCellSum?: string | null
+  bLoading: boolean
+  fnOnChange: (nPage: number, nPageSize: number) => void
+}
+
+export function TablePaginationBar({
+  objPagination,
+  nPage,
+  nPageSize,
+  nTotal,
+  strSelectedCellSum,
+  bLoading,
+  fnOnChange,
+}: ITablePaginationBarProps) {
+  const objMessages = useAppTableMessages()
+  const nTotalPages = Math.max(1, Math.ceil(nTotal / Math.max(1, nPageSize)))
+  const nCurrentPage = Math.min(nTotalPages, Math.max(1, nPage))
+  const [strJumpPage, fnSetJumpPage] = useState(String(nCurrentPage))
+
+  useEffect(() => {
+    fnSetJumpPage(String(nCurrentPage))
+  }, [nCurrentPage])
+
+  const fnHandleJump = (objEvent: FormEvent<HTMLFormElement>) => {
+    objEvent.preventDefault()
+    const nTargetPage = Math.min(
+      nTotalPages,
+      Math.max(1, Math.trunc(Number(strJumpPage)) || nCurrentPage)
+    )
+    fnSetJumpPage(String(nTargetPage))
+    if (nTargetPage !== nCurrentPage) fnOnChange(nTargetPage, nPageSize)
+  }
+
+  return (
+    <footer className='flex shrink-0 flex-wrap items-center justify-between gap-3 border-t px-4 py-3 text-sm'>
+      {strSelectedCellSum !== null && strSelectedCellSum !== undefined ? (
+        <div
+          data-slot='table-pagination-status'
+          className='flex h-8 items-center text-muted-foreground'
+        >
+          <span className='whitespace-nowrap'>
+            {objMessages.fnSelectedCellSum(strSelectedCellSum)}
+          </span>
+        </div>
+      ) : null}
+
+      <div
+        data-slot='table-pagination-controls'
+        className='ml-auto flex min-h-8 max-w-full min-w-0 flex-wrap items-center justify-end gap-3'
+      >
+        {objPagination.showTotal ? (
+          <span className='inline-flex h-8 items-center whitespace-nowrap text-muted-foreground'>
+            {objMessages.fnTotalRows(nTotal)}
+          </span>
+        ) : null}
+        {objPagination.showPageSize ? (
+          <Select
+            value={String(nPageSize)}
+            disabled={bLoading}
+            onValueChange={(strPageSize) => fnOnChange(1, Number(strPageSize))}
+          >
+            <SelectTrigger
+              size='sm'
+              className='w-[7rem]'
+              aria-label={objMessages.strPageSizeAriaLabel}
+            >
+              <SelectValue />
+            </SelectTrigger>
+            <SelectContent position='popper'>
+              {objPagination.pageSizes.map((nSize) => (
+                <SelectItem key={nSize} value={String(nSize)}>
+                  {objMessages.fnRowsPerPage(nSize)}
+                </SelectItem>
+              ))}
+            </SelectContent>
+          </Select>
+        ) : null}
+        <Pagination className='max-w-full min-w-0 overflow-x-auto'>
+          <PaginationContent className='min-w-max'>
+            <PaginationItem>
+              <PaginationFirst
+                disabled={nCurrentPage <= 1 || bLoading}
+                onClick={() => fnOnChange(1, nPageSize)}
+              />
+            </PaginationItem>
+            <PaginationItem>
+              <PaginationPrevious
+                disabled={nCurrentPage <= 1 || bLoading}
+                onClick={() => fnOnChange(nCurrentPage - 1, nPageSize)}
+              />
+            </PaginationItem>
+            {objPagination.showPageNumbers
+              ? buildTablePaginationItems(
+                  nCurrentPage,
+                  nTotalPages,
+                  objPagination.siblingCount
+                ).map((objItem) => (
+                  <PaginationItem key={objItem}>
+                    {typeof objItem === 'number' ? (
+                      <PaginationLink
+                        isActive={objItem === nCurrentPage}
+                        disabled={bLoading}
+                        aria-label={objMessages.fnPageAriaLabel(objItem)}
+                        onClick={() => fnOnChange(objItem, nPageSize)}
+                      >
+                        {objItem}
+                      </PaginationLink>
+                    ) : (
+                      <PaginationEllipsis />
+                    )}
+                  </PaginationItem>
+                ))
+              : null}
+            <PaginationItem>
+              <PaginationNext
+                disabled={nCurrentPage >= nTotalPages || bLoading}
+                onClick={() => fnOnChange(nCurrentPage + 1, nPageSize)}
+              />
+            </PaginationItem>
+            <PaginationItem>
+              <PaginationLast
+                disabled={nCurrentPage >= nTotalPages || bLoading}
+                onClick={() => fnOnChange(nTotalPages, nPageSize)}
+              />
+            </PaginationItem>
+          </PaginationContent>
+        </Pagination>
+
+        {objPagination.showJumper ? (
+          <form
+            className='m-0 flex h-8 items-center gap-2'
+            onSubmit={fnHandleJump}
+          >
+            <span className='inline-flex h-8 items-center text-muted-foreground'>
+              {objMessages.strGoTo}
+            </span>
+            <Input
+              type='number'
+              min={1}
+              max={nTotalPages}
+              value={strJumpPage}
+              disabled={bLoading}
+              aria-label={objMessages.strTargetPageAriaLabel}
+              className='h-8 w-16 px-2 text-center'
+              onChange={(objEvent) => fnSetJumpPage(objEvent.target.value)}
+            />
+            <span className='inline-flex h-8 items-center text-muted-foreground'>
+              {objMessages.strPage}
+            </span>
+            <Button
+              type='submit'
+              variant='outline'
+              size='sm'
+              disabled={bLoading}
+            >
+              {objMessages.strJump}
+            </Button>
+          </form>
+        ) : null}
+      </div>
+    </footer>
+  )
+}

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

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

package/template/src/components/AppTable/pagination/paginationItems.ts

@@ -0,0 +1,56 @@
+type TablePaginationItem = number | 'start-ellipsis' | 'end-ellipsis'
+
+const range = (start: number, end: number) =>
+  Array.from({ length: Math.max(0, end - start + 1) }, (_, index) =>
+    Math.trunc(start + index)
+  )
+
+/** 生成稳定的数字页码窗口；首尾页始终可见，中间缺口以省略号表示。 */
+export function buildTablePaginationItems(
+  page: number,
+  pageCount: number,
+  siblingCount = 1
+): TablePaginationItem[] {
+  const normalizedPageCount = Math.max(1, Math.trunc(pageCount) || 1)
+  const normalizedPage = Math.min(
+    normalizedPageCount,
+    Math.max(1, Math.trunc(page) || 1)
+  )
+  const normalizedSiblingCount = Math.min(
+    3,
+    Math.max(0, Math.trunc(siblingCount) || 0)
+  )
+
+  if (normalizedPageCount <= normalizedSiblingCount * 2 + 5) {
+    return range(1, normalizedPageCount)
+  }
+
+  const siblingsStart = Math.max(
+    Math.min(
+      normalizedPage - normalizedSiblingCount,
+      normalizedPageCount - normalizedSiblingCount * 2 - 2
+    ),
+    2
+  )
+  const siblingsEnd = Math.min(
+    Math.max(
+      normalizedPage + normalizedSiblingCount,
+      normalizedSiblingCount * 2 + 3
+    ),
+    normalizedPageCount - 1
+  )
+  const items: TablePaginationItem[] = [1]
+
+  if (siblingsStart > 2) items.push('start-ellipsis')
+  else if (siblingsStart === 2) items.push(2)
+
+  items.push(...range(Math.max(2, siblingsStart), siblingsEnd))
+
+  if (siblingsEnd < normalizedPageCount - 1) items.push('end-ellipsis')
+  else if (siblingsEnd === normalizedPageCount - 1) {
+    items.push(normalizedPageCount - 1)
+  }
+
+  items.push(normalizedPageCount)
+  return [...new Set(items)]
+}

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

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

package/template/src/components/AppTable/preference/useTablePreference.ts

@@ -0,0 +1,208 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
+import { resolveTablePaginationConfig } from '@/components/AppTable/engine/pagination/config'
+import type { TablePageSize } from '@/components/AppTable/engine/pagination/types'
+import {
+  createLocalPreferenceStore,
+  createMemoryPreferenceStore,
+  createPreferenceCoordinator,
+  type PreferenceStatus,
+  type TablePreferenceSession,
+  type TablePreferenceUpdater,
+} from '@/components/AppTable/engine/preference/preference'
+import type { TablePreference } from '@/components/AppTable/engine/preference/types'
+import type { TableDensity } from '@/components/AppTable/engine/shared/theme'
+import type { TableRow } from '@/components/AppTable/engine/shared/types'
+import type {
+  ResolvedTableComponentProps,
+  TableColumn,
+  TableSearchCondition,
+} from '../config'
+import type { ITableSearchConditionPreferenceChange } from '../search/types'
+
+interface IUseTablePreferenceOptions<T extends TableRow> {
+  strTableKey: string
+  objProps: ResolvedTableComponentProps<T>
+  fnReportError: (objError: unknown) => void
+}
+
+interface IUseTablePreferenceResult<T extends TableRow> {
+  objSession: TablePreferenceSession
+  objPreference: TablePreference
+  strStatus: PreferenceStatus
+  bReady: boolean
+  arrColumns: TableColumn<T>[]
+  arrAllConditions: readonly TableSearchCondition[]
+  arrOrderedConditions: TableSearchCondition[]
+  arrConditionOrder: string[]
+  arrHiddenConditionKeys: string[]
+  nPreferredPageSize: TablePageSize
+  strPreferredDensity: TableDensity
+  fnUpdatePreference: (
+    updater: TablePreferenceUpdater
+  ) => Promise<TablePreference>
+  fnResetPreference: () => Promise<TablePreference>
+  fnApplySearchConditionChanges: (
+    value: ITableSearchConditionPreferenceChange
+  ) => void
+}
+
+const fnCreateFallback = <T extends TableRow>(
+  objProps: ResolvedTableComponentProps<T>
+): TablePreference => ({
+  columnOrder: [],
+  hiddenColumns: [],
+  columnWidths: {},
+  frozenColumns: [],
+  frozenRows: 0,
+  searchOrder: [],
+  hiddenSearchConditions: [],
+  density: objProps.density,
+})
+
+/** React 侧单张表唯一的偏好桥接器；所有领域通过同一个 engine 会话原子更新。 */
+export function useTablePreference<T extends TableRow>({
+  strTableKey,
+  objProps,
+  fnReportError,
+}: IUseTablePreferenceOptions<T>): IUseTablePreferenceResult<T> {
+  const [objFallback] = useState(() => fnCreateFallback(objProps))
+  const [objCoordinator] = useState(() =>
+    createPreferenceCoordinator({
+      store:
+        objProps.preference === false
+          ? createMemoryPreferenceStore()
+          : (objProps.preference.store ?? createLocalPreferenceStore()),
+      key: {
+        userScope:
+          objProps.preference === false
+            ? 'memory'
+            : (objProps.preference.userScope ?? 'local'),
+        tableKey: strTableKey,
+      },
+      legacyTableKeys: objProps.legacyTableKeys,
+      fallback: objFallback,
+    })
+  )
+  const [objPreference, fnSetPreference] =
+    useState<TablePreference>(objFallback)
+  const [strStatus, fnSetStatus] = useState<PreferenceStatus>(
+    objCoordinator.status
+  )
+  const [bReady, fnSetReady] = useState(false)
+  const objLoadPromiseRef = useRef<Promise<TablePreference> | null>(null)
+  const fnReportErrorRef = useRef(fnReportError)
+  fnReportErrorRef.current = fnReportError
+
+  const fnSyncSnapshot = useCallback(() => {
+    const objSnapshot = objCoordinator.snapshot
+    fnSetPreference(objSnapshot.value)
+    fnSetStatus(objSnapshot.status)
+  }, [objCoordinator])
+
+  useEffect(
+    () => objCoordinator.subscribe(fnSyncSnapshot),
+    [fnSyncSnapshot, objCoordinator]
+  )
+
+  useEffect(() => {
+    let bActive = true
+    objLoadPromiseRef.current ??= objCoordinator.load()
+    void objLoadPromiseRef.current.then(() => {
+      if (!bActive) return
+      fnSyncSnapshot()
+      fnSetReady(true)
+      if (objCoordinator.status === 'failed') {
+        fnReportErrorRef.current(objCoordinator.error)
+      }
+    })
+    return () => {
+      bActive = false
+    }
+  }, [fnSyncSnapshot, objCoordinator])
+
+  const fnUpdatePreference = useCallback(
+    async (fnUpdater: TablePreferenceUpdater) => {
+      try {
+        return await objCoordinator.update(fnUpdater)
+      } catch (objError) {
+        fnReportError(objError)
+        return objCoordinator.snapshot.value
+      }
+    },
+    [fnReportError, objCoordinator]
+  )
+
+  const fnResetPreference = useCallback(async () => {
+    try {
+      return await objCoordinator.reset()
+    } catch (objError) {
+      fnReportError(objError)
+      return objCoordinator.snapshot.value
+    }
+  }, [fnReportError, objCoordinator])
+
+  const arrColumns = useMemo(() => {
+    const arrOrder = objPreference.columnOrder
+    return objProps.columns
+      .map((objColumn) => ({
+        ...objColumn,
+        hidden:
+          objPreference.hiddenColumns.includes(String(objColumn.key)) ||
+          objColumn.hidden,
+        width:
+          objPreference.columnWidths[String(objColumn.key)] ?? objColumn.width,
+      }))
+      .sort((objLeft, objRight) => {
+        const nLeft = arrOrder.indexOf(String(objLeft.key))
+        const nRight = arrOrder.indexOf(String(objRight.key))
+        if (nLeft < 0 && nRight < 0) return 0
+        if (nLeft < 0) return 1
+        if (nRight < 0) return -1
+        return nLeft - nRight
+      })
+  }, [objPreference, objProps.columns])
+
+  const arrOrderedConditions = useMemo(() => {
+    const arrOrder = objPreference.searchOrder ?? []
+    const objHidden = new Set(objPreference.hiddenSearchConditions ?? [])
+    return [...objProps.searchConditions]
+      .filter((objCondition) => !objHidden.has(objCondition.key))
+      .sort((objLeft, objRight) => {
+        const nLeft = arrOrder.indexOf(objLeft.key)
+        const nRight = arrOrder.indexOf(objRight.key)
+        if (nLeft < 0 && nRight < 0) return 0
+        if (nLeft < 0) return 1
+        if (nRight < 0) return -1
+        return nLeft - nRight
+      })
+  }, [objPreference, objProps.searchConditions])
+
+  const fnApplySearchConditionChanges = useCallback(
+    ({ arrOrder, arrHidden }: ITableSearchConditionPreferenceChange) =>
+      void fnUpdatePreference((objCurrent) => ({
+        ...objCurrent,
+        searchOrder: [...arrOrder],
+        hiddenSearchConditions: [...arrHidden],
+      })),
+    [fnUpdatePreference]
+  )
+
+  return {
+    objSession: objCoordinator,
+    objPreference,
+    strStatus,
+    bReady,
+    arrColumns,
+    arrAllConditions: objProps.searchConditions,
+    arrOrderedConditions,
+    arrConditionOrder: objPreference.searchOrder ?? [],
+    arrHiddenConditionKeys: objPreference.hiddenSearchConditions ?? [],
+    nPreferredPageSize:
+      objPreference.pageSize ??
+      resolveTablePaginationConfig(objProps.pagination).pageSize,
+    strPreferredDensity: objPreference.density ?? objProps.density,
+    fnUpdatePreference,
+    fnResetPreference,
+    fnApplySearchConditionChanges,
+  }
+}

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

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