@polymorphism-tech/morph-spec 8.37.1 → 8.38.0

package/framework/standards/frontend/admin-app/data-table.md

@@ -0,0 +1,562 @@
+# Admin App — Lists and Data Tables
+
+> **Scope:** frontend/admin-app
+> **Layer:** 2 (on keyword)
+> **Keywords:** data table, list, pagination, server-side pagination, sorting, filtering, searchParams, empty state, loading state, error state, density, row actions, bulk actions, row selection, tanstack table
+> **Load When:** designing or building any screen that lists records (admin panel, CRUD, back office, dashboard list)
+
+**Verified against:** Next.js 16 App Router + @tanstack/react-table 9 + Zod 4 + shadcn 4 (the code blocks typecheck under `tsc --strict`). Last-verified: 2026-09-24.
+
+---
+
+A list that renders "everything the API returned" works with 20 rows and breaks with 2 000: the page grows to 13 000 px, the browser sorts only what it loaded, and the fix that ships is "show the first 8 + see all" — which is not paging. In an admin app every list is **paged, sorted and filtered on the server**, its state lives **in the URL**, and it renders **three states besides the happy path**. This standard owns the one shared `DataTable`; `nextjs/components.md` points here instead of carrying its own.
+
+## Core Rules
+
+- ALWAYS page, sort and filter on the server. The browser receives one page plus the total count, never the whole collection.
+- ALWAYS keep page, page size, sort and filters in the URL (`searchParams`). State that dies on refresh, or that a colleague cannot open from a pasted link, is a bug.
+- ALWAYS parse `searchParams` with a Zod schema that has bounds and defaults — the URL is user input.
+- ALWAYS render loading, empty and error. "Empty" has two kinds: *no records yet* (offer the create action) and *no match for these filters* (offer to clear them).
+- NEVER set `manualPagination` without `manualSorting`: sorting the loaded page only produces an order that looks right and is wrong.
+- NEVER cap a list with "first N + see all" instead of paging it.
+- ONE shared `components/data-table.tsx`. Features pass columns and rows; they never write a second table.
+- A change of filter, sort or page size resets to page 1.
+
+## The List Contract (URL and API)
+
+| URL param | Meaning | Rule |
+|---|---|---|
+| `page` | 1-based page | integer ≥ 1, default 1 |
+| `pageSize` | rows per page | allowlist `10 / 25 / 50 / 100`, default 25 |
+| `sort` | column id | allowlist per screen — never pass a raw column name to the query |
+| `dir` | `asc` / `desc` | default per screen |
+| `q` + domain filters | search and filters | trimmed, bounded length |
+
+The API answers `{ items: T[], totalCount: number }`. On the backend the slice does `Skip/Take` (`backend/dotnet/vsa-handler-patterns.md`) over an `OrderBy` on the allowlisted column **plus a unique tiebreaker** (the id): paging over a non-unique order repeats and skips rows between pages.
+
+```ts
+// features/products/types/product-list.schemas.ts
+import { z } from 'zod';
+
+export const PAGE_SIZES = [10, 25, 50, 100] as const;
+export const PRODUCT_SORTS = ['name', 'price', 'updatedAt'] as const;
+
+export const productListQuerySchema = z.object({
+  page: z.coerce.number().int().min(1).catch(1),
+  pageSize: z.coerce
+    .number()
+    .int()
+    .refine((n) => (PAGE_SIZES as readonly number[]).includes(n))
+    .catch(25),
+  sort: z.enum(PRODUCT_SORTS).catch('updatedAt'),
+  dir: z.enum(['asc', 'desc']).catch('desc'),
+  q: z.string().trim().max(100).catch(''),
+  status: z.enum(['active', 'archived']).optional().catch(undefined),
+});
+
+export type ProductListQuery = z.infer<typeof productListQuerySchema>;
+
+export const productSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  price: z.number(),
+  status: z.enum(['active', 'archived']),
+  updatedAt: z.string(),
+});
+export type Product = z.infer<typeof productSchema>;
+
+export const productPageSchema = z.object({
+  items: z.array(productSchema),
+  totalCount: z.number().int().min(0),
+});
+export type ProductPage = z.infer<typeof productPageSchema>;
+```
+
+Every field carries `.catch()`: a hand-edited `?page=abc` renders page 1 instead of an error page.
+
+## The Page: Server Component Reads the URL
+
+The page parses the query, renders the toolbar, and wraps the results in a `Suspense` **keyed by the query** — each new page, sort or filter shows the skeleton for the table only, while the toolbar stays put.
+
+```tsx
+// app/(admin)/products/page.tsx
+import { Suspense } from 'react';
+import { DataTableSkeleton } from '@/components/data-table-skeleton';
+import { ProductResults } from '@/features/products/components/product-results';
+import { ProductToolbar } from '@/features/products/components/product-toolbar';
+import { productListQuerySchema } from '@/features/products/types/product-list.schemas';
+
+export default async function ProductsPage({
+  searchParams,
+}: {
+  searchParams: Promise<Record<string, string | string[] | undefined>>;
+}) {
+  const query = productListQuerySchema.parse(await searchParams);
+  return (
+    <>
+      <ProductToolbar query={query} />
+      <Suspense key={JSON.stringify(query)} fallback={<DataTableSkeleton rows={query.pageSize} />}>
+        <ProductResults query={query} />
+      </Suspense>
+    </>
+  );
+}
+```
+
+```tsx
+// features/products/components/product-results.tsx — Server Component
+import { DataTableError } from '@/components/data-table-error';
+import { fetchProductPage } from '@/features/products/api/fetch-product-page';
+import type { ProductListQuery } from '@/features/products/types/product-list.schemas';
+import { ProductTable } from './product-table';
+
+export async function ProductResults({ query }: { query: ProductListQuery }) {
+  const result = await fetchProductPage(query);
+  if (!result.ok) return <DataTableError message={result.message} />;
+  return <ProductTable query={query} page={result.page} />;
+}
+```
+
+```ts
+// features/products/api/fetch-product-page.ts — server-direct (BACKEND_API_PREFIX)
+import { BACKEND_API_PREFIX } from '@/lib/api/prefixes';
+import {
+  productPageSchema,
+  type ProductListQuery,
+  type ProductPage,
+} from '@/features/products/types/product-list.schemas';
+
+export type PageResult = { ok: true; page: ProductPage } | { ok: false; message: string };
+
+export async function fetchProductPage(query: ProductListQuery): Promise<PageResult> {
+  const params = new URLSearchParams({
+    page: String(query.page),
+    pageSize: String(query.pageSize),
+    sort: query.sort,
+    dir: query.dir,
+  });
+  if (query.q) params.set('q', query.q);
+  if (query.status) params.set('status', query.status);
+
+  const res = await fetch(`${BACKEND_API_PREFIX}/products?${params}`, { cache: 'no-store' });
+  if (!res.ok) return { ok: false, message: `Não foi possível carregar os produtos (${res.status}).` };
+  const parsed = productPageSchema.safeParse(await res.json());
+  return parsed.success
+    ? { ok: true, page: parsed.data }
+    : { ok: false, message: 'A resposta do servidor veio num formato inesperado.' };
+}
+```
+
+A failed load is a **value**, rendered as the error state with a retry — not an exception that blanks the whole segment. `error.tsx` stays for what nobody anticipated.
+
+## Writing the URL From the Client
+
+One hook owns "change the list query". It merges a patch into the current params, drops empty values, resets the page unless the patch *is* the page, and replaces the history entry without scrolling to the top.
+
+```tsx
+// components/use-list-query.ts
+'use client';
+
+import { usePathname, useRouter, useSearchParams } from 'next/navigation';
+import { useTransition } from 'react';
+
+type Patch = Record<string, string | number | null | undefined>;
+
+export function useListQuery() {
+  const router = useRouter();
+  const pathname = usePathname();
+  const searchParams = useSearchParams();
+  const [isPending, startTransition] = useTransition();
+
+  function update(patch: Patch) {
+    const params = new URLSearchParams(searchParams.toString());
+    for (const [key, value] of Object.entries(patch)) {
+      if (value === null || value === undefined || value === '') params.delete(key);
+      else params.set(key, String(value));
+    }
+    if (!('page' in patch)) params.delete('page');
+    const qs = params.toString();
+    startTransition(() => router.replace(qs ? `${pathname}?${qs}` : pathname, { scroll: false }));
+  }
+
+  return { update, isPending };
+}
+```
+
+## The Shared DataTable (Tier 2)
+
+Headless TanStack Table 9 with the three server-side switches on: `manualPagination` + `rowCount`, `manualSorting`, and selection keyed by a stable id. It never fetches — the page does.
+
+```tsx
+// components/data-table.tsx
+'use client';
+
+import type { ReactNode } from 'react';
+import {
+  functionalUpdate,
+  rowPaginationFeature,
+  rowSelectionFeature,
+  rowSortingFeature,
+  tableFeatures,
+  useTable,
+  type ColumnDef,
+  type PaginationState,
+  type RowData,
+  type RowSelectionState,
+  type SortingState,
+} from '@tanstack/react-table';
+import { Button } from '@/components/ui/button';
+import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from '@/components/ui/table';
+
+export const dataTableFeatures = tableFeatures({
+  rowPaginationFeature,
+  rowSortingFeature,
+  rowSelectionFeature,
+});
+export type DataTableFeatures = typeof dataTableFeatures;
+export type DataTableColumn<TData extends RowData> = ColumnDef<DataTableFeatures, TData>;
+
+export interface DataTableProps<TData extends RowData> {
+  columns: Array<DataTableColumn<TData>>;
+  rows: TData[];
+  rowCount: number;
+  getRowId: (row: TData) => string;
+  pagination: PaginationState;
+  sorting: SortingState;
+  onPaginationChange: (next: PaginationState) => void;
+  onSortingChange: (next: SortingState) => void;
+  rowSelection?: RowSelectionState;
+  onRowSelectionChange?: (next: RowSelectionState) => void;
+  bulkActions?: (selectedIds: string[]) => ReactNode;
+  empty: ReactNode;
+  density?: 'compact' | 'comfortable';
+}
+
+export function DataTable<TData extends RowData>(props: DataTableProps<TData>) {
+  const { rowSelection = {}, onRowSelectionChange, density = 'compact' } = props;
+
+  const table = useTable({
+    features: dataTableFeatures,
+    columns: props.columns,
+    data: props.rows,
+    getRowId: (row) => props.getRowId(row),
+    rowCount: props.rowCount,
+    manualPagination: true,
+    manualSorting: true,
+    enableRowSelection: onRowSelectionChange !== undefined,
+    state: { pagination: props.pagination, sorting: props.sorting, rowSelection },
+    onPaginationChange: (u) => props.onPaginationChange(functionalUpdate(u, props.pagination)),
+    onSortingChange: (u) => props.onSortingChange(functionalUpdate(u, props.sorting)),
+    onRowSelectionChange: (u) => onRowSelectionChange?.(functionalUpdate(u, rowSelection)),
+  });
+
+  const selectedIds = Object.keys(rowSelection).filter((id) => rowSelection[id]);
+  const cellY = density === 'compact' ? 'py-1.5' : 'py-3';
+
+  if (props.rowCount === 0) return <>{props.empty}</>;
+
+  return (
+    <div className="space-y-2">
+      {selectedIds.length > 0 && props.bulkActions && (
+        <div className="flex items-center gap-2 rounded-md border bg-muted/50 px-3 py-2 text-sm">
+          <span>{selectedIds.length} selecionado(s) nesta página</span>
+          {props.bulkActions(selectedIds)}
+        </div>
+      )}
+      <div className="overflow-x-auto rounded-md border">
+        <Table>
+          <TableHeader className="sticky top-0 bg-background">
+            {table.getHeaderGroups().map((group) => (
+              <TableRow key={group.id}>
+                {group.headers.map((header) => (
+                  <TableHead key={header.id} aria-sort={ariaSort(header.column.getIsSorted())}>
+                    {header.isPlaceholder ? null : <table.FlexRender header={header} />}
+                  </TableHead>
+                ))}
+              </TableRow>
+            ))}
+          </TableHeader>
+          <TableBody>
+            {table.getRowModel().rows.map((row) => (
+              <TableRow key={row.id} data-state={row.getIsSelected() ? 'selected' : undefined}>
+                {row.getAllCells().map((cell) => (
+                  <TableCell key={cell.id} className={cellY}>
+                    <table.FlexRender cell={cell} />
+                  </TableCell>
+                ))}
+              </TableRow>
+            ))}
+          </TableBody>
+        </Table>
+      </div>
+      <div className="flex items-center justify-between text-sm text-muted-foreground">
+        <span>
+          Página {props.pagination.pageIndex + 1} de {Math.max(1, table.getPageCount())} · {props.rowCount} registro(s)
+        </span>
+        <div className="flex gap-2">
+          <Button variant="outline" size="sm" onClick={() => table.previousPage()} disabled={!table.getCanPreviousPage()}>
+            Anterior
+          </Button>
+          <Button variant="outline" size="sm" onClick={() => table.nextPage()} disabled={!table.getCanNextPage()}>
+            Próxima
+          </Button>
+        </div>
+      </div>
+    </div>
+  );
+}
+
+function ariaSort(sorted: false | 'asc' | 'desc'): 'ascending' | 'descending' | 'none' {
+  if (sorted === 'asc') return 'ascending';
+  if (sorted === 'desc') return 'descending';
+  return 'none';
+}
+```
+
+`pageIndex` in the table is 0-based; the URL `page` is 1-based. The conversion lives in exactly one place — the feature table below.
+
+Two small shared pieces complete the tier: the sortable header and the empty state.
+
+```tsx
+// components/sortable-header.tsx
+'use client';
+
+import type { Column, RowData } from '@tanstack/react-table';
+import { ArrowDown, ArrowUp, ArrowUpDown } from 'lucide-react';
+import type { DataTableFeatures } from '@/components/data-table';
+import { Button } from '@/components/ui/button';
+import { cn } from '@/lib/utils';
+
+export function SortableHeader<TData extends RowData>({
+  column,
+  label,
+  align = 'left',
+}: {
+  column: Column<DataTableFeatures, TData, unknown>;
+  label: string;
+  align?: 'left' | 'right';
+}) {
+  const sorted = column.getIsSorted();
+  const Icon = sorted === 'asc' ? ArrowUp : sorted === 'desc' ? ArrowDown : ArrowUpDown;
+  return (
+    <Button
+      variant="ghost"
+      size="sm"
+      className={cn(align === 'right' ? 'ml-auto flex' : '-ml-3')}
+      onClick={() => column.toggleSorting(sorted === 'asc')}
+    >
+      {label}
+      <Icon className="ml-1 size-3.5" aria-hidden />
+    </Button>
+  );
+}
+```
+
+```tsx
+// components/data-table-empty.tsx
+'use client';
+
+import type { ReactNode } from 'react';
+import { useListQuery } from '@/components/use-list-query';
+import { Button } from '@/components/ui/button';
+
+export function DataTableEmpty({ filtered, entity, create }: {
+  filtered: boolean;
+  entity: string;
+  create?: ReactNode;
+}) {
+  const { update } = useListQuery();
+  return (
+    <div className="flex flex-col items-center gap-3 rounded-md border border-dashed p-10 text-center text-sm">
+      {filtered ? (
+        <>
+          <p>Nenhum {entity} com esses filtros.</p>
+          <Button variant="outline" size="sm" onClick={() => update({ q: null, status: null })}>
+            Limpar filtros
+          </Button>
+        </>
+      ) : (
+        <>
+          <p>Ainda não há nenhum {entity} cadastrado.</p>
+          {create}
+        </>
+      )}
+    </div>
+  );
+}
+```
+
+## The Feature Table (Tier 3)
+
+The feature owns its columns and the URL ⇄ table mapping; the shared table owns rendering.
+
+```tsx
+// features/products/components/product-table.tsx
+'use client';
+
+import { useState } from 'react';
+import type { RowSelectionState } from '@tanstack/react-table';
+import { DataTable, type DataTableColumn } from '@/components/data-table';
+import { DataTableEmpty } from '@/components/data-table-empty';
+import { useListQuery } from '@/components/use-list-query';
+import { Checkbox } from '@/components/ui/checkbox';
+import {
+  PRODUCT_SORTS,
+  type Product,
+  type ProductListQuery,
+  type ProductPage,
+} from '@/features/products/types/product-list.schemas';
+import { ProductBulkActions } from './product-bulk-actions';
+import { ProductRowActions } from './product-row-actions';
+import { SortableHeader } from '@/components/sortable-header';
+
+const columns: Array<DataTableColumn<Product>> = [
+  {
+    id: 'select',
+    header: ({ table }) => (
+      <Checkbox
+        checked={table.getIsAllPageRowsSelected() || (table.getIsSomePageRowsSelected() && 'indeterminate')}
+        onCheckedChange={(v) => table.toggleAllPageRowsSelected(!!v)}
+        aria-label="Selecionar a página"
+      />
+    ),
+    cell: ({ row }) => (
+      <Checkbox
+        checked={row.getIsSelected()}
+        onCheckedChange={(v) => row.toggleSelected(!!v)}
+        aria-label="Selecionar linha"
+      />
+    ),
+    enableSorting: false,
+  },
+  { accessorKey: 'name', header: ({ column }) => <SortableHeader column={column} label="Nome" /> },
+  {
+    accessorKey: 'price',
+    header: ({ column }) => <SortableHeader column={column} label="Preço" align="right" />,
+    cell: ({ row }) => <span className="block text-right tabular-nums">{formatBRL(row.original.price)}</span>,
+  },
+  { accessorKey: 'status', header: 'Status', enableSorting: false },
+  { id: 'actions', header: '', cell: ({ row }) => <ProductRowActions product={row.original} />, enableSorting: false },
+];
+
+export function ProductTable({ query, page }: { query: ProductListQuery; page: ProductPage }) {
+  const { update } = useListQuery();
+  const [rowSelection, setRowSelection] = useState<RowSelectionState>({});
+
+  return (
+    <DataTable
+      columns={columns}
+      rows={page.items}
+      rowCount={page.totalCount}
+      getRowId={(p) => p.id}
+      pagination={{ pageIndex: query.page - 1, pageSize: query.pageSize }}
+      sorting={[{ id: query.sort, desc: query.dir === 'desc' }]}
+      onPaginationChange={(next) => update({ page: next.pageIndex + 1, pageSize: next.pageSize })}
+      onSortingChange={(next) => {
+        const first = next[0];
+        const sort = PRODUCT_SORTS.find((s) => s === first?.id);
+        update({ sort: sort ?? null, dir: first ? (first.desc ? 'desc' : 'asc') : null });
+      }}
+      rowSelection={rowSelection}
+      onRowSelectionChange={setRowSelection}
+      bulkActions={(ids) => <ProductBulkActions ids={ids} onDone={() => setRowSelection({})} />}
+      empty={<DataTableEmpty filtered={query.q !== '' || query.status !== undefined} entity="produto" />}
+    />
+  );
+}
+
+function formatBRL(value: number) {
+  return new Intl.NumberFormat('pt-BR', { style: 'currency', currency: 'BRL' }).format(value);
+}
+```
+
+Selection is **per loaded page** (`getIsAllPageRowsSelected`, "selecionado(s) nesta página"). Rows the browser never received cannot be selected — an action over "everything matching the filter" is a separate, server-side operation with its own confirmation (`feedback.md`), never a loop over pages.
+
+## The Three States
+
+| State | What renders | Rule |
+|---|---|---|
+| **Loading** | `DataTableSkeleton` with the page's row count, header row visible | Same height as the loaded table — no layout jump. The `Suspense` keyed by the query shows it on the first load **and** on every page/sort/filter change; the toolbar, outside it, shows `isPending` from `useListQuery` (spinner in the search field) |
+| **Empty — no records** | Explanation + the primary create action | Never a bare "Nenhum resultado" on a table nobody has filled yet |
+| **Empty — no match** | "Nenhum produto com esses filtros" + "Limpar filtros" | Keeps the toolbar, so the user sees *which* filters caused it |
+| **Error** | Message from the `PageResult` + "Tentar de novo" (`router.refresh()`) | The toolbar stays; retry never discards the filters in the URL |
+
+```tsx
+// components/data-table-error.tsx
+'use client';
+
+import { useRouter } from 'next/navigation';
+import { useTransition } from 'react';
+import { Button } from '@/components/ui/button';
+
+export function DataTableError({ message }: { message: string }) {
+  const router = useRouter();
+  const [isPending, startTransition] = useTransition();
+  return (
+    <div role="alert" className="flex flex-col items-center gap-3 rounded-md border border-destructive/40 p-8 text-sm">
+      <p>{message}</p>
+      <Button variant="outline" size="sm" disabled={isPending} onClick={() => startTransition(() => router.refresh())}>
+        Tentar de novo
+      </Button>
+    </div>
+  );
+}
+```
+
+## Filters and Search
+
+- Every filter is a URL param and is applied **by the server**. A filter that runs over the loaded page lies about the result count.
+- Free-text search commits on a 300 ms debounce (or on Enter), never per keystroke into history — `router.replace`, not `push`.
+- Selects and toggles commit immediately.
+- Show active filters as removable chips plus one "Limpar filtros"; the count in the pager is the count **after** filters.
+
+## Density
+
+Admin screens are read in bulk: default to **compact** rows (`py-1.5`, 14 px text), offer "comfortable" only if the design asks for it.
+
+- Numbers and money right-aligned with `tabular-nums`; dates in one format per app.
+- Long text truncates with the full value in a tooltip — a cell never wraps into a paragraph.
+- Header sticky inside the table's scroll container; the first column is the record's name and links to its detail.
+- At most ~7 visible columns on desktop. More than that is a detail page, not a column.
+
+## Row Actions and Bulk Actions
+
+- One primary action inline (usually "Editar", or the name as a link); the rest in a row menu (`DropdownMenu` with a `…` icon button that has an `aria-label`).
+- Destructive actions — row or bulk — go through the confirmation dialog of `feedback.md`, and their result through the toast catalog there.
+- The bulk bar appears only with a selection, says how many rows it acts on, and clears the selection when the action finishes.
+- After a mutation, `router.refresh()` re-reads the current page from the server; never patch the row array by hand.
+
+## Mobile
+
+Below the `md` breakpoint a table with more than 3 columns becomes a **card list** (same data, same URL state, same pager): name + the 2 decisive fields + the row menu. Horizontal scrolling a dense table on a phone is the fallback only for tables the design marks as desktop-first, and the design must say so.
+
+## Where the Design Checklist Lands
+
+The per-screen checklist of the `morph-uiux` mockups (volume, pagination, sort, filter, the three states, mobile, tabs) is answered by this standard's rules:
+
+| Checklist item | Decided by |
+|---|---|
+| Expected volume | picks `pageSize` default and whether search is needed at all |
+| Pagination | [The List Contract](#the-list-contract-url-and-api) — always server-side above ~50 rows |
+| Sort | the `sort` allowlist + default `dir` |
+| Filter | [Filters and Search](#filters-and-search) |
+| Loading / empty / error | [The Three States](#the-three-states) |
+| Mobile | [Mobile](#mobile) |
+| Tabs | `admin-app/page-structure.md` |
+
+## Common Mistakes
+
+| Wrong | Right | Why |
+|---|---|---|
+| `useQuery` returns the whole collection, table paginates in memory | Server pages; table gets `rowCount` + `manualPagination` | The browser downloads and sorts everything, and it stops scaling silently |
+| `manualPagination: true` with client sorting | `manualSorting: true` too | Sorting only the loaded page gives a plausible, wrong order |
+| Page/sort/filter in `useState` | In `searchParams` | Refresh and shared links lose the list state |
+| `OrderBy(name).Skip().Take()` | `OrderBy(name).ThenBy(id)` | Non-unique order repeats and skips rows across pages |
+| "First 8 + ver todas" | Paging | A teto is not pagination; "ver todas" is the unbounded list again |
+| `router.push` on every keystroke | Debounced `router.replace` | History filled with one entry per letter |
+| One empty message for every case | "No records" vs "no match" | The user cannot tell a new table from a bad filter |
+| Second table component per feature | `components/data-table.tsx` + columns | Six hand-made tables drift in six ways |
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*