@nocobase/app-template-default 1.0.0-beta.67 → 1.0.0-beta.69

package/.agents/rules/components.md

@@ -21,7 +21,7 @@ Build your own components by composing these primitives, and put them in `client
 
 ## UI Library items
 
-`PageContainer`, `PageHeader`, `RouteDialog`, `RouteDrawer`, `RouteChildPage` and `useRouteOverlay` in `client/components/` come from the NocoBase UI Library, as do the authentication blocks in `client/extensions/nocobase-auth-forms/`, `nocobase-auth-methods/`, `nocobase-auth-split-layout/` and `nocobase-device-approval/` that `client/pages/auth/` composes, and the inbox block in `client/extensions/nocobase-inbox/` that `client/pages/inbox.tsx` renders on `/inbox`; like the rest of the source, they belong to the application. `yes n | pnpm exec shadcn add @nocobase/<item>` adds another item from the library: a single component lands in `client/components/`, a complete feature in `client/extensions/nocobase-<item>/`. A date field and a list's `DataTable` are the application's own components: compose `DatePicker` in `client/components/date-picker.tsx` from the `calendar` and `popover` primitives, following shadcn's Date Picker guide, and build `DataTable` in `client/components/` from the `table` primitive and `@tanstack/react-table`, following shadcn's Data Table guide. The CLI adds the packages an item or primitive needs to `dependencies`: move the new ones, such as `react-day-picker` for `calendar`, to `devDependencies`, as [where to declare a dependency](../skills/nocobase-app-development/references/dependencies.md) explains for everything client code imports, but leave `@nocobase/i18n` in `dependencies`, where the server needs it, and put back the `^` of its range, which the CLI pins.
+`PageContainer`, `PageHeader`, `RouteDialog`, `RouteDrawer`, `RouteChildPage` and `useRouteOverlay` in `client/components/` come from the NocoBase UI Library, as do the authentication blocks in `client/extensions/nocobase-auth-forms/`, `nocobase-auth-methods/`, `nocobase-auth-split-layout/` and `nocobase-device-approval/` that `client/pages/auth/` composes, and the inbox block in `client/extensions/nocobase-inbox/` that `client/pages/inbox.tsx` renders on `/inbox`; like the rest of the source, they belong to the application. `yes n | pnpm exec shadcn add @nocobase/<item>` adds another item from the library: a single component lands in `client/components/`, a complete feature in `client/extensions/nocobase-<item>/`. A date field and a list's `DataTable` are the application's own components: compose `DatePicker` in `client/components/date-picker.tsx` from the `calendar` and `popover` primitives, following shadcn's Date Picker guide, and reuse the template's standard `DataTable` and companions from `#components/data-table` (`client/components/data-table/`). They use the template's declared TanStack Table v8 dependency; do not generate a separate table engine or substitute a hand-written HTML table for a business list. Server pagination uses the same component's controlled `manualPagination`/`rowCount` and sorting props. Verify the installed version and the `useReactTable`/`getCoreRowModel` exports before reporting incompatibility; repair an incompatible dependency to the supported v8 range instead of recording a custom implementation as an accepted deviation. The CLI adds the packages an item or primitive needs to `dependencies`: move the new ones, such as `react-day-picker` for `calendar`, to `devDependencies`, as [where to declare a dependency](../skills/nocobase-app-development/references/dependencies.md) explains for everything client code imports, but leave `@nocobase/i18n` in `dependencies`, where the server needs it, and put back the `^` of its range, which the CLI pins.
 
 ## Styling and visual consistency
 
@@ -29,6 +29,6 @@ Style with the semantic Tailwind tokens — `bg-background`, `text-foreground`,
 
 **Visual consistency is a whole-application property.** Match the surrounding code's spacing, typography, and component choices. If a change genuinely calls for a different look, change the application's design tokens in `client/theme/themes/*.css` so every page moves together. Never restyle only the part you are working on — a page that looks different from the rest is a defect, not a customization.
 
-The default brand palette and density live in `client/theme/themes/*.css`; shared hover/cursor and Badge geometry live in `client/styles.css`, outside generated shadcn primitives. For semantic status labels, use `StatusBadge` from `client/components/status-badge.tsx` with `neutral`, `info`, `warning`, or `success`; choose the tone by meaning and keep the visible status text. Reuse these shared components and tokens in new pages so template upgrades can carry the design consistently.
+The default brand palette and density live in `client/theme/themes/*.css`; shared hover/cursor and Badge geometry live in `client/styles.css`, outside generated shadcn primitives. For semantic status labels, use `StatusBadge` from `client/components/status-badge.tsx` with `neutral`, `info`, `warning`, or `success`; choose the tone by meaning and keep the visible status text. A badge beside a title or on a dense card is the small one, `size='sm'` on `StatusBadge` or `data-size='sm'` on `Badge`. Reuse these shared components and tokens in new pages so template upgrades can carry the design consistently.
 
 **Follow the UI guidelines.** [The UI guidelines](../skills/nocobase-app-development/references/frontend/ui-guidelines.md) set the conventions every page follows, among them the page header and the single placement of the primary action, empty states, row actions behind one "…" menu, dates picked from a `Calendar` in a `Popover` rather than a native date input, and medium-width drawers; the frontend workflow says how much of it to read for a change.

package/.agents/rules/shell.md

@@ -8,10 +8,12 @@ Layouts own breadcrumb route context and render the current page's trail in the
 
 ## Header and sidebar
 
-`client/layouts/components/layout-header.tsx` is a presentation container accepting children. The sidebar is shadcn's Sidebar: `components/app-sidebar.tsx` wraps its provider, desktop icon mode and phone sheet, and `components/navigation-menu.tsx` draws the permission-filtered route tree with `SidebarMenu*` and controlled `Collapsible` sub-menus. Leave `client/components/ui/sidebar.tsx` as the shadcn CLI writes it and customize from outside: widths go through the provider's `style` in spacing units, the phone sheet is rendered in `app-sidebar.tsx` with a translated title, and the provider's Ctrl/Cmd+B shortcut is stopped at `document`. The App layout owns menus, branding, permissions and redirects. Desktop icon mode shows leaf labels as zero-delay tooltips and opens groups in hover and keyboard-focus popovers, preserving filtered navigation, parent-page links, nested groups and the selected group's highlight. Keep this behavior aligned across layouts. Desktop collapse state is shared through `useSidebarPreference` at `nocobase:sidebar:collapsed` across applications on the same origin; whether the phone sheet is open stays local to each layout.
+`client/layouts/components/layout-header.tsx` is a presentation container accepting children. The sidebar is shadcn's Sidebar: `components/app-sidebar.tsx` wraps its provider, desktop icon mode and phone sheet, and `components/navigation-menu.tsx` draws the permission-filtered route tree with `SidebarMenu*`: a top-level group with no page of its own is a section, its entries always shown under a `SidebarGroupLabel` heading, while clickable parents and nested groups are controlled `Collapsible` sub-menus, and an item `client/lib/navigation-transform.ts` marks `section` deeper in the tree is a heading over its direct links inside that menu; a count beside an entry, such as unread items, is passed by the App layout in `NavigationMenu`'s `badges`, keyed by route name. Keep `client/components/ui/sidebar.tsx` as the shadcn CLI writes it except for removing its unused origin-wide `sidebar_state` cookie write; persistence belongs to the application-scoped preference. Customize from outside: widths go through the provider's `style` in spacing units, the phone sheet is rendered in `app-sidebar.tsx` with a translated title, and the provider's Ctrl/Cmd+B shortcut is stopped at `document`. The App layout owns menus, branding, permissions and redirects. Desktop icon mode hides top-level section headings and keeps their entries' icons, shows leaf labels as zero-delay tooltips and opens groups in hover and keyboard-focus popovers, preserving filtered navigation, parent-page links, nested groups and the selected group's highlight. Keep this behavior aligned across layouts. Desktop collapse state is shared through `useSidebarPreference` at `nocobase:sidebar:collapsed:app:<basename>` across layouts and tabs of the same application. `createApp(runtime)` provides a stable store using `runtime.basename`, with only empty/root and boundary slashes normalized; paths and case remain intact. Missing new keys default to expanded without migrating the old shared preference; whether the phone sheet is open stays local to each layout.
 
 The header carries no Settings or Inbox entry. An application has no separate settings area: a page that configures something is an ordinary route in `client/routes.ts` with `navigation`, placed in the sidebar like any other page, for example under a Settings navigation group. The `/inbox` page declares no navigation; give it an entry where the application wants one.
 
+`client/lib/navigation-transform.ts` is the application-owned hook for customizing the permission-filtered navigation tree. The shared sidebar supports static section labels with direct links as well as collapsible groups.
+
 Navigation groups retain their expanded or collapsed state while the navigation tree stays mounted. Selecting a new page expands its ancestor groups without collapsing other groups; users can still collapse the active group manually.
 
 ## Account menu and session
@@ -27,3 +29,5 @@ The account menu language control in `client/layouts/components/language-switche
 Use `Loading` for page or panel waits and `Spinner` (the shadcn-compatible adapter to `BrandSpinner`) for inline pending actions, uploads, and refresh indicators. Both share the stable NocoBase mark and orbit animation; do not introduce independent Lucide spinners for application loading. Keep skeletons for content placeholders and progress bars for determinate progress. `index.html` has the matching pre-JavaScript mark and must stay visually consistent. All animations respect reduced motion.
 
 The shared list of shell behaviors to keep when customizing is in [customizing the shell](../skills/nocobase-app-development/references/frontend/references/shell.md).
+
+The signed-in region waits in `client/routing/session-preparation.tsx` before mounting `AppLayout`: the authentication provider first reconnects active realtime subscriptions as the current session and waits for the open notification, including permission invalidation. A ten-second timeout shows a localized retry/sign-out screen. Keep this boundary inside `RequiredAuthentication`; guest login must remain reachable without realtime. Readiness is only for initial session preparation. Subsequent permission notifications and reconnects still use normal fail-closed route unmounting, including portal and effect cleanup.

package/AGENTS.md

@@ -4,11 +4,9 @@ This is a NocoBase 3 application. Do not apply globally installed NocoBase 2 Ski
 
 Do not create a plugin to add a feature. Plugins are separately published packages for capabilities shared across several applications; building one for this application's own feature adds a package boundary, a version, and a release process to work that belongs in `client/` and `server/`. Create one only when the user explicitly asks for a reusable published package.
 
-When users refer to annotations, marks, or selections in the current application, first run `pnpm exec agent-annotations list --json` from the application root to find Agent Annotations records, ask for clarification only if none match or the target remains unclear, and do not implement annotation requests when the user only asks where they are.
-
 ## Default template scope
 
-Default is the clean application starting point. It registers product capabilities but no `app-plugin-*-example` plugins, example pages, application sample services, or sample APIs. Keep runnable demonstrations in `app-template-examples`. Application-owned server routes start empty; the only built-in application provider exposes Authorization Permission Sets as direct roles in the Users page. The only application page is a localized homepage.
+Default is the clean application starting point. It registers product capabilities but no `app-plugin-*-example` plugins, example pages, application sample services, or sample APIs. Keep runnable demonstrations in `app-template-examples`. Application-owned business server routes start empty; Users supplies the standard Permission Set role scope. Application-owned pages include the localized homepage and inbox; prepared user/role administration modules are unregistered in the bare template and enabled as business capabilities are developed.
 
 `database/main/` contains required permission initialization only; application-owned business migrations and seeds start empty. Do not add article history, demo seeds, or compatibility copies from Examples to this template. Existing installations retain their own executed migration sources when upgrading; see the [upgrade migration rules](.agents/skills/nocobase-app-upgrade/references/edge-cases.md#migrations).
 
@@ -53,6 +51,10 @@ tests/                    Tests; never beside the source
 
 A feature with a page and an API touches five places: a migration for the table, a route in `server/routes/`, a page in `client/pages/` declared in `client/routes.ts`, navigation on the page route, and strings in `client/locales/`. A page with children or page-local helpers uses a folder with `index.tsx`; child folders mirror route paths. [Application structure](.agents/skills/nocobase-app-development/references/app-structure.md) explains how the runtime composes these pieces, where configuration and its environment variables are declared, and the runtime paths.
 
+## System settings are part of feature delivery
+
+A bare create-app stays Home-only with no settings routes or menu. As the application develops business capabilities, inspect its current state on every iteration and automatically register the prepared Users and Roles and permissions contribution from `client/pages/settings/routes.ts` once in `client/routes.ts`; preserve it and reconcile missing management surfaces on every iteration, without a first-build flag or one-time setup stage. Whenever an application adds lifecycles, workflows, approvals, notifications, files or other configurable capabilities, automatically include their real administration surfaces without requiring a second user request. Follow [system settings delivery](.agents/skills/nocobase-app-development/references/system-settings.md); in particular, every used process includes a definitions directory, standard diagram, supported parameters and authorized execution history. Do not add demo plugins or empty settings for unused capabilities.
+
 ## Rules that apply everywhere
 
 ### Pages and routes

package/Dockerfile.dockerignore

@@ -25,7 +25,6 @@ ui-library/dist
 .git
 **/.agents
 **/.claude
-**/.agent-annotations
 **/coverage
 **/playwright-report
 **/test-results

package/README.MD

@@ -6,10 +6,12 @@ You own everything in this directory. Add pages, API routes, database tables, an
 
 ## Default and Examples
 
-Default provides the application shell and product capabilities without example plugins or business demo pages. Application-owned routes start empty, and new databases receive no article sample data. Its built-in Users integration lists direct Authorization Permission Sets as application roles, while access assigned to all authenticated users remains separate. Use `app-template-examples` for article management and runnable plugin demonstrations.
+Default provides the application shell and product capabilities without example plugins or business demo pages. Application-owned business API routes start empty, and new databases receive no article sample data. A bare create-app shows Home only, with no System settings routes or menu. As business capabilities are developed, the app development skill reconciles missing core administration on every iteration and registers the prepared Users and Roles and permissions contribution (`client/pages/settings/routes.ts`); each actually used configurable capability includes its administration as part of feature delivery. Its built-in Users integration lists direct Authorization Permission Sets as application roles, while access assigned to all authenticated users remains separate. Use `app-template-examples` for article management and runnable plugin demonstrations.
 
 Existing Default installations retain their data when example plugins are unregistered. If an installation already ran the article migration, retain its original migration sources as described in the [upgrade migration rules](.agents/skills/nocobase-app-upgrade/references/edge-cases.md#migrations) before upgrading. Do not erase migration history or delete existing data to make an upgrade start.
 
+Business lists reuse the template's standard `DataTable` and companions from `#components/data-table`. The template declares the compatible TanStack Table v8 dependency and provides controlled server pagination/sorting; application agents should not generate an independent table engine. See the [table guide](.agents/skills/nocobase-app-development/references/frontend/references/table.md).
+
 ## Getting started
 
 Configure the application, then start the development server:

package/client/app.ts

@@ -11,12 +11,26 @@ import {
   type ReactElement,
 } from 'react';
 
+import {
+  createAppSidebarPreferenceStore,
+  SidebarPreferenceProvider,
+} from './layouts/use-sidebar-preference.js';
 import { AppRouter } from './routing/app-router.js';
 export function createApp(runtime: AppRuntimeContext): ClientApplication {
   // Outermost, so every provider and page below can translate.
   const AppI18nProvider = ({ children }: PropsWithChildren): ReactElement =>
     createElement(I18nProvider, { runtime: runtime.i18n }, children);
 
+  const sidebarPreference = createAppSidebarPreferenceStore(runtime.basename);
+  const AppSidebarPreferenceProvider = ({
+    children,
+  }: PropsWithChildren): ReactElement =>
+    createElement(
+      SidebarPreferenceProvider,
+      { value: sidebarPreference },
+      children,
+    );
+
   const app = new ClientApplication({
     runtime,
     createRenderConfig: (): AppClientRenderConfig =>
@@ -24,6 +38,7 @@ export function createApp(runtime: AppRuntimeContext): ClientApplication {
         basename: runtime.basename,
         reactProviders: [
           AppI18nProvider,
+          AppSidebarPreferenceProvider,
           ...runtime.reactProviders.map((provider) => provider.component),
         ],
         routes: createElement(AppRouter, {

package/client/components/data-table/column-header.tsx

@@ -0,0 +1,91 @@
+import { useTranslation } from '@nocobase/i18n/client';
+import type { Column, SortDirection } from '@tanstack/react-table';
+import {
+  ArrowDownIcon,
+  ArrowUpIcon,
+  ChevronsUpDownIcon,
+  EyeOffIcon,
+} from 'lucide-react';
+import type { ComponentPropsWithoutRef, ReactElement, ReactNode } from 'react';
+
+import { Button } from '#components/ui/button';
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuSeparator,
+  DropdownMenuTrigger,
+} from '#components/ui/dropdown-menu';
+import { cn } from 'cn';
+
+export interface DataTableColumnHeaderProps<TData, TValue> extends Omit<
+  ComponentPropsWithoutRef<'div'>,
+  'title'
+> {
+  readonly column: Column<TData, TValue>;
+  readonly title: ReactNode;
+}
+
+function SortIcon({
+  direction,
+}: {
+  readonly direction: SortDirection | false;
+}): ReactElement {
+  if (direction === 'desc') return <ArrowDownIcon />;
+  if (direction === 'asc') return <ArrowUpIcon />;
+  return <ChevronsUpDownIcon />;
+}
+
+/**
+ * A column header that opens a menu for sorting and hiding the column. Use it
+ * as the `header` of a column definition:
+ * `header: ({ column }) => <DataTableColumnHeader column={column} title='Email' />`.
+ */
+export function DataTableColumnHeader<TData, TValue>({
+  column,
+  title,
+  className,
+  ...props
+}: DataTableColumnHeaderProps<TData, TValue>): ReactElement {
+  const { t } = useTranslation();
+
+  if (!column.getCanSort()) {
+    return (
+      <div className={cn(className)} {...props}>
+        {title}
+      </div>
+    );
+  }
+
+  return (
+    <div className={cn('flex items-center gap-2', className)} {...props}>
+      <DropdownMenu>
+        <DropdownMenuTrigger
+          render={<Button variant='ghost' size='sm' className='-ml-3 h-8' />}
+        >
+          <span>{title}</span>
+          <SortIcon direction={column.getIsSorted()} />
+        </DropdownMenuTrigger>
+        <DropdownMenuContent align='start' className='w-auto min-w-40'>
+          <DropdownMenuItem onClick={() => column.toggleSorting(false)}>
+            <ArrowUpIcon />
+            {t('dataTable.sortAscending', { defaultValue: 'Asc' })}
+          </DropdownMenuItem>
+          <DropdownMenuItem onClick={() => column.toggleSorting(true)}>
+            <ArrowDownIcon />
+            {t('dataTable.sortDescending', { defaultValue: 'Desc' })}
+          </DropdownMenuItem>
+          {column.getCanHide() ? (
+            <>
+              <DropdownMenuSeparator />
+              <DropdownMenuItem onClick={() => column.toggleVisibility(false)}>
+                <EyeOffIcon />
+                {t('dataTable.hideColumn', { defaultValue: 'Hide' })}
+              </DropdownMenuItem>
+            </>
+          ) : null}
+        </DropdownMenuContent>
+      </DropdownMenu>
+    </div>
+  );
+}

package/client/components/data-table/data-table.tsx

@@ -0,0 +1,216 @@
+import { useTranslation } from '@nocobase/i18n/client';
+import {
+  type ColumnDef,
+  type PaginationState,
+  type OnChangeFn,
+  type ColumnFiltersState,
+  type Row,
+  type RowSelectionState,
+  type SortingState,
+  type Table as TableInstance,
+  type VisibilityState,
+  flexRender,
+  getCoreRowModel,
+  getFilteredRowModel,
+  getPaginationRowModel,
+  getSortedRowModel,
+  useReactTable,
+} from '@tanstack/react-table';
+import { type ReactElement, type ReactNode, useMemo, useState } from 'react';
+
+import { DataTablePagination } from './pagination.js';
+import {
+  Table,
+  TableBody,
+  TableCell,
+  TableHead,
+  TableHeader,
+  TableRow,
+} from '#components/ui/table';
+import { cn } from 'cn';
+
+export interface DataTableProps<TData, TValue = unknown> {
+  readonly columns: ColumnDef<TData, TValue>[];
+  readonly data: readonly TData[];
+  readonly manualPagination?: boolean;
+  readonly rowCount?: number;
+  readonly paginationState?: PaginationState;
+  readonly onPaginationChange?: OnChangeFn<PaginationState>;
+  readonly manualSorting?: boolean;
+  readonly sortingState?: SortingState;
+  readonly onSortingChange?: OnChangeFn<SortingState>;
+  readonly showSelectedCount?: boolean;
+  readonly loading?: boolean;
+  readonly className?: string;
+  /**
+   * Rendered above the table and handed the table instance, so filters and
+   * `DataTableViewOptions` can read and drive its state.
+   */
+  readonly toolbar?: (table: TableInstance<TData>) => ReactNode;
+  /** Shown in place of the body when no row survives filtering. */
+  readonly emptyMessage?: ReactNode;
+  /** Set to `false` to render every row and hide the pagination footer. */
+  readonly pagination?: boolean;
+  readonly pageSize?: number;
+  readonly pageSizeOptions?: readonly number[];
+  readonly getRowId?: (
+    row: TData,
+    index: number,
+    parent?: Row<TData>,
+  ) => string;
+  readonly onRowClick?: (row: Row<TData>) => void;
+}
+
+/**
+ * A table driven by TanStack Table with client-side sorting, filtering, column
+ * visibility, row selection and pagination, composed from the shadcn `Table`
+ * primitive the way the shadcn Data Table guide describes.
+ *
+ * Column definitions decide what each feature does: sort through
+ * `DataTableColumnHeader`, filter from the `toolbar` with
+ * `table.getColumn(id)?.setFilterValue(...)`, and select rows with a display
+ * column that renders a `Checkbox`.
+ */
+export function DataTable<TData, TValue = unknown>({
+  columns,
+  data,
+  className,
+  toolbar,
+  emptyMessage,
+  pagination = true,
+  pageSize = 10,
+  pageSizeOptions,
+  getRowId,
+  onRowClick,
+  manualPagination = false,
+  rowCount,
+  paginationState,
+  onPaginationChange,
+  manualSorting = false,
+  sortingState,
+  onSortingChange,
+  showSelectedCount = true,
+  loading = false,
+}: DataTableProps<TData, TValue>): ReactElement {
+  const { t } = useTranslation();
+  const tableData = useMemo(() => [...data], [data]);
+  const [sorting, setSorting] = useState<SortingState>([]);
+  const [columnFilters, setColumnFilters] = useState<ColumnFiltersState>([]);
+  const [columnVisibility, setColumnVisibility] = useState<VisibilityState>({});
+  const [rowSelection, setRowSelection] = useState<RowSelectionState>({});
+
+  // TanStack Table hands back one mutable instance that the React Compiler
+  // cannot memoize, so it skips compiling this component; the table is still
+  // correct without it.
+  // eslint-disable-next-line react-hooks/incompatible-library
+  const table = useReactTable({
+    data: tableData,
+    columns,
+    manualPagination,
+    rowCount,
+    manualSorting,
+    ...(onPaginationChange ? { onPaginationChange } : {}),
+    getRowId,
+    state: {
+      sorting: sortingState ?? sorting,
+      columnFilters,
+      columnVisibility,
+      rowSelection,
+      ...(paginationState ? { pagination: paginationState } : {}),
+    },
+    initialState: { pagination: { pageSize } },
+    onSortingChange: onSortingChange ?? setSorting,
+    onColumnFiltersChange: setColumnFilters,
+    onColumnVisibilityChange: setColumnVisibility,
+    onRowSelectionChange: setRowSelection,
+    getCoreRowModel: getCoreRowModel(),
+    ...(!manualSorting ? { getSortedRowModel: getSortedRowModel() } : {}),
+    getFilteredRowModel: getFilteredRowModel(),
+    ...(pagination && !manualPagination
+      ? { getPaginationRowModel: getPaginationRowModel() }
+      : {}),
+  });
+
+  const rows = table.getRowModel().rows;
+
+  return (
+    <div className={cn('flex flex-col gap-4', className)}>
+      {toolbar ? (
+        <div className='flex flex-wrap items-center gap-2'>
+          {toolbar(table)}
+        </div>
+      ) : null}
+      <div className='overflow-hidden rounded-lg border'>
+        <Table aria-busy={loading}>
+          <TableHeader>
+            {table.getHeaderGroups().map((headerGroup) => (
+              <TableRow key={headerGroup.id}>
+                {headerGroup.headers.map((header) => (
+                  <TableHead
+                    key={header.id}
+                    colSpan={header.colSpan}
+                    aria-sort={
+                      header.column.getCanSort()
+                        ? header.column.getIsSorted() === 'asc'
+                          ? 'ascending'
+                          : header.column.getIsSorted() === 'desc'
+                            ? 'descending'
+                            : 'none'
+                        : undefined
+                    }
+                  >
+                    {header.isPlaceholder
+                      ? null
+                      : flexRender(
+                          header.column.columnDef.header,
+                          header.getContext(),
+                        )}
+                  </TableHead>
+                ))}
+              </TableRow>
+            ))}
+          </TableHeader>
+          <TableBody>
+            {rows.length > 0 ? (
+              rows.map((row) => (
+                <TableRow
+                  key={row.id}
+                  data-state={row.getIsSelected() ? 'selected' : undefined}
+                  className={onRowClick ? 'cursor-pointer' : undefined}
+                  onClick={onRowClick ? () => onRowClick(row) : undefined}
+                >
+                  {row.getVisibleCells().map((cell) => (
+                    <TableCell key={cell.id}>
+                      {flexRender(
+                        cell.column.columnDef.cell,
+                        cell.getContext(),
+                      )}
+                    </TableCell>
+                  ))}
+                </TableRow>
+              ))
+            ) : (
+              <TableRow>
+                <TableCell
+                  colSpan={columns.length}
+                  className='h-24 text-center text-muted-foreground'
+                >
+                  {emptyMessage ??
+                    t('dataTable.noResults', { defaultValue: 'No results.' })}
+                </TableCell>
+              </TableRow>
+            )}
+          </TableBody>
+        </Table>
+      </div>
+      {pagination ? (
+        <DataTablePagination
+          table={table}
+          pageSizeOptions={pageSizeOptions}
+          showSelectedCount={showSelectedCount}
+          disabled={loading}
+        />
+      ) : null}
+    </div>
+  );
+}

package/client/components/data-table/index.ts

@@ -0,0 +1,13 @@
+export { DataTable, type DataTableProps } from './data-table.js';
+export {
+  DataTablePagination,
+  type DataTablePaginationProps,
+} from './pagination.js';
+export {
+  DataTableColumnHeader,
+  type DataTableColumnHeaderProps,
+} from './column-header.js';
+export {
+  DataTableViewOptions,
+  type DataTableViewOptionsProps,
+} from './view-options.js';

package/client/components/data-table/pagination.tsx

@@ -0,0 +1,165 @@
+import { useTranslation } from '@nocobase/i18n/client';
+import type { Table as TableInstance } from '@tanstack/react-table';
+import {
+  ChevronLeftIcon,
+  ChevronRightIcon,
+  ChevronsLeftIcon,
+  ChevronsRightIcon,
+} from 'lucide-react';
+import type { ComponentPropsWithoutRef, ReactElement } from 'react';
+
+import { Button } from '#components/ui/button';
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from '#components/ui/select';
+import { cn } from 'cn';
+
+export interface DataTablePaginationProps<
+  TData,
+> extends ComponentPropsWithoutRef<'div'> {
+  readonly table: TableInstance<TData>;
+  readonly pageSizeOptions?: readonly number[];
+  /** Hide the "n of m selected" summary for tables without row selection. */
+  readonly showSelectedCount?: boolean;
+  readonly disabled?: boolean;
+}
+
+const DEFAULT_PAGE_SIZE_OPTIONS: readonly number[] = [10, 20, 30, 40, 50];
+
+/**
+ * Pagination controls for a TanStack table: selected-row summary, page size,
+ * current page, and first/previous/next/last buttons. `DataTable` renders it
+ * for you; use it directly when composing a table by hand.
+ */
+export function DataTablePagination<TData>({
+  table,
+  pageSizeOptions = DEFAULT_PAGE_SIZE_OPTIONS,
+  showSelectedCount = true,
+  disabled = false,
+  className,
+  ...props
+}: DataTablePaginationProps<TData>): ReactElement {
+  const { t } = useTranslation();
+  const { pageIndex, pageSize } = table.getState().pagination;
+  const pageCount = Math.max(table.getPageCount(), 1);
+  const selected = table.getFilteredSelectedRowModel().rows.length;
+  const total = table.getFilteredRowModel().rows.length;
+  const options = pageSizeOptions.includes(pageSize)
+    ? pageSizeOptions
+    : [...pageSizeOptions, pageSize].sort((a, b) => a - b);
+
+  return (
+    <div
+      className={cn(
+        'flex flex-wrap items-center justify-between gap-4 px-2',
+        className,
+      )}
+      {...props}
+    >
+      <div className='flex-1 text-sm text-muted-foreground'>
+        {showSelectedCount
+          ? t('dataTable.selectedCount', {
+              defaultValue: '{{selected}} of {{total}} row(s) selected.',
+              selected,
+              total,
+            })
+          : null}
+      </div>
+      <div className='flex flex-wrap items-center gap-6 lg:gap-8'>
+        <div className='flex items-center gap-2'>
+          <p className='text-sm font-medium'>
+            {t('dataTable.rowsPerPage', { defaultValue: 'Rows per page' })}
+          </p>
+          <Select
+            disabled={disabled}
+            value={String(pageSize)}
+            onValueChange={(value) => {
+              if (value) table.setPageSize(Number(value));
+            }}
+          >
+            <SelectTrigger
+              size='sm'
+              className='w-[70px]'
+              aria-label={t('dataTable.rowsPerPage', {
+                defaultValue: 'Rows per page',
+              })}
+            >
+              <SelectValue />
+            </SelectTrigger>
+            <SelectContent
+              side='top'
+              className='w-auto max-w-[min(var(--container-sm),var(--available-width))] min-w-(--anchor-width) [&_[data-slot=select-item]>:first-child]:whitespace-normal'
+            >
+              {options.map((size) => (
+                <SelectItem key={size} value={String(size)}>
+                  {size}
+                </SelectItem>
+              ))}
+            </SelectContent>
+          </Select>
+        </div>
+        <div className='flex w-[100px] items-center justify-center text-sm font-medium'>
+          {t('dataTable.pageOf', {
+            defaultValue: 'Page {{page}} of {{pageCount}}',
+            page: pageIndex + 1,
+            pageCount,
+          })}
+        </div>
+        <div className='flex items-center gap-2'>
+          <Button
+            variant='outline'
+            size='icon-sm'
+            className='hidden lg:flex'
+            onClick={() => table.setPageIndex(0)}
+            disabled={disabled || !table.getCanPreviousPage()}
+          >
+            <span className='sr-only'>
+              {t('dataTable.firstPage', { defaultValue: 'Go to first page' })}
+            </span>
+            <ChevronsLeftIcon />
+          </Button>
+          <Button
+            variant='outline'
+            size='icon-sm'
+            onClick={() => table.previousPage()}
+            disabled={disabled || !table.getCanPreviousPage()}
+          >
+            <span className='sr-only'>
+              {t('dataTable.previousPage', {
+                defaultValue: 'Go to previous page',
+              })}
+            </span>
+            <ChevronLeftIcon />
+          </Button>
+          <Button
+            variant='outline'
+            size='icon-sm'
+            onClick={() => table.nextPage()}
+            disabled={disabled || !table.getCanNextPage()}
+          >
+            <span className='sr-only'>
+              {t('dataTable.nextPage', { defaultValue: 'Go to next page' })}
+            </span>
+            <ChevronRightIcon />
+          </Button>
+          <Button
+            variant='outline'
+            size='icon-sm'
+            className='hidden lg:flex'
+            onClick={() => table.setPageIndex(pageCount - 1)}
+            disabled={disabled || !table.getCanNextPage()}
+          >
+            <span className='sr-only'>
+              {t('dataTable.lastPage', { defaultValue: 'Go to last page' })}
+            </span>
+            <ChevronsRightIcon />
+          </Button>
+        </div>
+      </div>
+    </div>
+  );
+}