rl-core-front 0.15.5 → 0.15.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rl-core-front",
-  "version": "0.15.5",
+  "version": "0.15.6",
   "description": "Telas e componentes Next.js do core: login com 2FA, usuários, RBAC, auditoria, logs e listagens com filtro dinâmico",
   "author": "Rodrigo Liberti",
   "license": "MIT",

package/src/components/ui/data-table.tsx

@@ -30,7 +30,7 @@ import {
   SlidersHorizontal,
 } from "lucide-react";
 import type { JSX, PointerEvent as ReactPointerEvent } from "react";
-import { useMemo, useRef, useState } from "react";
+import { Fragment, useMemo, useRef, useState } from "react";
 
 import { countConditions } from "#core/_utils/advanced-filter";
 import { activeFilterCount } from "#core/_utils/filter";
@@ -42,11 +42,13 @@ import {
   ColumnVisibilityOption,
 } from "#core/components/ui/column-visibility-modal";
 import { FilterSheet } from "#core/components/ui/filter-sheet";
+import { SegmentedControl } from "#core/components/ui/segmented-control";
 import { Spinner } from "#core/components/ui/spinner";
 import {
   Table,
   TableBody,
   TableCell,
+  TableFooter,
   TableHead,
   TableHeader,
   TableRow,
@@ -54,6 +56,8 @@ import {
 import { useI18n } from "#core/contexts";
 import { useColumnVisibility } from "#core/hooks/use-column-visibility";
 import type { FiltersState } from "#core/hooks/use-filters";
+import type { TableView } from "#core/hooks/use-table-view";
+import { useTableView } from "#core/hooks/use-table-view";
 import { cn } from "#core/lib/utils";
 
 export const dataTableFeatures = tableFeatures({
@@ -148,6 +152,66 @@ interface DataTableProps<T extends RowData> {
    * gravada, e arrastar escreveria uma sequência que ninguém viu.
    */
   onRowReorder?: (activeId: string, overId: string) => void;
+  /**
+   * Desenha a listagem em cartões, e não em linhas.
+   *
+   * Recebe as linhas da página atual, já ordenadas e filtradas, e devolve o
+   * que aparece no lugar da tabela. Com esta prop a barra ganha o alternador
+   * lista/cartões, e a escolha fica guardada por `storageKey` — dado que se vê
+   * (uma coleção, um catálogo de fotos) se compara olhando, e dado que se
+   * confere se compara lendo; a mesma listagem serve às duas coisas.
+   *
+   * Em cartões não há cabeçalho, logo não há por onde ordenar: a ordem
+   * escolhida na lista continua valendo, e o botão de colunas some — cartão
+   * não tem coluna para esconder.
+   */
+  renderGrid?: (rows: T[]) => React.ReactNode;
+  /** Como a listagem abre na primeira visita, antes de alguém escolher. */
+  defaultView?: TableView;
+  /**
+   * A que seção cada linha pertence — sem isto, não há agrupamento.
+   *
+   * O grupo é sempre a chave primária da ordem: ordenar por uma coluna ordena
+   * **dentro** da seção. Do contrário, um clique no cabeçalho intercalaria as
+   * seções e o cabeçalho de grupo reapareceria a cada troca de valor — dez
+   * faixas onde existem duas.
+   */
+  groupBy?: (row: T) => string;
+  /**
+   * O cabeçalho de cada seção: uma linha que atravessa a tabela inteira.
+   *
+   * Recebe a chave e as linhas da seção — é de onde saem contagem e total sem
+   * o consumidor precisar refazer a divisão que a tabela acabou de fazer. Sem
+   * esta prop o agrupamento só ordena, e nada é desenhado.
+   */
+  renderGroupHeader?: (group: DataTableGroup<T>) => React.ReactNode;
+  /**
+   * A faixa de cada seção fecha e abre no clique.
+   *
+   * Fechada, a seção fica só na faixa — e é por isso que a faixa recebe
+   * `collapsed`: quem a desenha decide o que dizer quando as linhas não estão
+   * à vista (a contagem, em geral, que aberta é redundante). A escolha vale
+   * enquanto a listagem estiver na tela; não é gravada.
+   */
+  collapsibleGroups?: boolean;
+  /**
+   * A ordem das seções.
+   *
+   * Chave que não aparecer aqui vai para o fim, na ordem em que apareceu nos
+   * dados. Sem a prop, a ordem é a de chegada — e "a de chegada" muda quando
+   * alguém ordena por uma coluna, por isso toda listagem com seções fixas
+   * (a receber / recebidas) declara esta lista.
+   */
+  groupOrder?: string[];
+}
+
+/** Uma seção da listagem, como o cabeçalho de grupo a recebe. */
+export interface DataTableGroup<T> {
+  key: string;
+  /** As linhas da seção — todas, mesmo com ela fechada. */
+  rows: T[];
+  /** Sempre `false` sem `collapsibleGroups`. */
+  collapsed: boolean;
 }
 
 /** Extras que uma coluna pode declarar em `meta`. */
@@ -159,6 +223,33 @@ export interface DataTableColumnMeta {
    * É o caso da coluna de ações: sem isso o `<table>` a esticava.
    */
   shrink?: boolean;
+  /**
+   * A coluna existe, mas não aparece até alguém ligá-la em "Colunas".
+   *
+   * Para o dado que a listagem tem e quase ninguém procura — a loja, o dia da
+   * compra — em tabela que já mostra o essencial. Vale só na primeira visita:
+   * a partir do momento em que alguém escolhe as colunas, a escolha guardada é
+   * que manda, e uma coluna nova nascendo escondida não mexe no que a pessoa
+   * já arrumou.
+   */
+  defaultHidden?: boolean;
+}
+
+/**
+ * O id que a coluna terá na tabela: o declarado, ou a chave do acessor.
+ *
+ * É o mesmo par que o TanStack usa para nomear a coluna, e precisa ser lido
+ * antes dela existir — o padrão de visibilidade entra na montagem da tabela.
+ */
+function columnId<T extends RowData>(
+  col: ColumnDef<DataTableFeatures, T, unknown>,
+): string | undefined {
+  if (col.id) {
+    return col.id;
+  }
+  const acessor = (col as { accessorKey?: unknown }).accessorKey;
+
+  return typeof acessor === "string" ? acessor : undefined;
 }
 
 function columnLabel<T extends RowData>(
@@ -175,6 +266,85 @@ function columnLabel<T extends RowData>(
   return id;
 }
 
+/**
+ * As linhas repartidas em seções, na ordem em que as seções saem.
+ *
+ * Estável de propósito: dentro da seção, as linhas mantêm a ordem que a tabela
+ * já lhes deu — a ordenação por coluna continua valendo, só que dentro de cada
+ * faixa. Seção declarada em `order` que não tiver nenhuma linha não vira faixa
+ * vazia: some, como o bloco vazio de uma listagem some.
+ */
+function groupRows<T, R extends { original: T }>(
+  rows: R[],
+  groupBy: (row: T) => string,
+  order?: string[],
+): { key: string; rows: R[] }[] {
+  const buckets = new Map<string, R[]>();
+
+  rows.forEach((row) => {
+    const key = groupBy(row.original);
+    const bucket = buckets.get(key);
+    if (bucket) {
+      bucket.push(row);
+    } else {
+      buckets.set(key, [row]);
+    }
+  });
+
+  const declared = (order ?? []).filter((key) => buckets.has(key));
+  const rest = [...buckets.keys()].filter((key) => !declared.includes(key));
+
+  return [...declared, ...rest].map((key) => ({
+    key,
+    rows: buckets.get(key) ?? [],
+  }));
+}
+
+/**
+ * O corpo da tabela em seções, com o índice de onde cada uma começa.
+ *
+ * Uma seção só, sem faixa, quando não há agrupamento — assim o corpo se
+ * desenha do mesmo jeito nos dois casos, em vez de dois caminhos que precisam
+ * ser mantidos iguais. O `offset` é a posição da primeira linha da seção na
+ * lista visível: é dele que sai o índice que o arrasto usa para medir o
+ * deslocamento.
+ */
+function bodySections<T, R extends { original: T }>(
+  rows: R[],
+  groupBy: ((row: T) => string) | undefined,
+  order: string[] | undefined,
+  collapsedKeys: string[],
+): {
+  key: string;
+  offset: number;
+  rows: R[];
+  header: DataTableGroup<T> | null;
+}[] {
+  if (!groupBy) {
+    return [{ key: "", offset: 0, rows, header: null }];
+  }
+
+  let offset = 0;
+
+  return groupRows(rows, groupBy, order).map((group) => {
+    const collapsed = collapsedKeys.includes(group.key);
+    const section = {
+      key: group.key,
+      offset,
+      rows: collapsed ? [] : group.rows,
+      header: {
+        key: group.key,
+        rows: group.rows.map((row) => row.original),
+        collapsed,
+      },
+    };
+
+    offset += section.rows.length;
+
+    return section;
+  });
+}
+
 /**
  * `w-px` + `whitespace-nowrap` é o jeito de fazer uma coluna de tabela encolher
  * até o conteúdo: o navegador trata a largura mínima como o conteúdo e o espaço
@@ -207,9 +377,17 @@ export function DataTable<T extends RowData>({
   emptyMessage,
   hideFooter = false,
   onRowReorder,
+  renderGrid,
+  defaultView = "list",
+  groupBy,
+  renderGroupHeader,
+  groupOrder,
+  collapsibleGroups = false,
 }: DataTableProps<T>): JSX.Element {
   const { t } = useI18n();
   const [colsOpen, setColsOpen] = useState(false);
+  /** As seções fechadas, por chave. */
+  const [collapsedGroups, setCollapsedGroups] = useState<string[]>([]);
   const [filtersOpen, setFiltersOpen] = useState(false);
   /** A linha na mão e a linha embaixo do dedo, enquanto o arrasto dura. */
   const [draggedRow, setDraggedRow] = useState<string | null>(null);
@@ -233,7 +411,22 @@ export function DataTable<T extends RowData>({
   */
   const [dragHeight, setDragHeight] = useState(0);
 
-  const { hiddenColumns, saveHiddenColumns } = useColumnVisibility(storageKey);
+  const { view, setView } = useTableView(storageKey, defaultView);
+
+  const ocultasPorPadrao = useMemo(
+    () =>
+      columns
+        .filter((column) => (column.meta as DataTableColumnMeta)?.defaultHidden)
+        .map((column) => columnId(column))
+        .filter((id): id is string => Boolean(id)),
+    [columns],
+  );
+  const emCartoes = Boolean(renderGrid) && view === "grid";
+
+  const { hiddenColumns, saveHiddenColumns } = useColumnVisibility(
+    storageKey,
+    ocultasPorPadrao,
+  );
   const columnVisibility = useMemo<ColumnVisibilityState>(() => {
     const v: ColumnVisibilityState = {};
     hiddenColumns.forEach((id) => {
@@ -289,6 +482,17 @@ export function DataTable<T extends RowData>({
     ...(manualPagination ? { rowCount: rowCount ?? 0 } : {}),
   });
 
+  /*
+    Linha de fechamento: existe só se alguma coluna visível declarar `footer`.
+
+    Vem do `columnDef` e não de uma última linha no `data` porque totalizador
+    não é registro — no corpo, ele ordenaria junto com os outros e apareceria no
+    meio da tabela à primeira troca de coluna.
+  */
+  const temFechamento = table
+    .getAllColumns()
+    .some((c) => c.getIsVisible() && Boolean(c.columnDef.footer));
+
   const hideable: ColumnVisibilityOption[] = table
     .getAllColumns()
     .filter((c) => c.getCanHide())
@@ -312,7 +516,30 @@ export function DataTable<T extends RowData>({
     A coluna da alça continua no lugar para a tabela não mudar de largura — só
     o botão fica inerte, e o `title` diz o motivo.
   */
-  const canReorder = reorderable && (table.state.sorting ?? []).length === 0;
+  const canReorder =
+    reorderable && (table.state.sorting ?? []).length === 0 && !groupBy;
+
+  /*
+    A lista já repartida em seções, achatada de volta numa sequência.
+
+    Achatada, e não desenhada como uma tabela por seção: seção que vira tabela
+    própria mede as próprias linhas, e a mesma coluna acaba com uma largura em
+    cada faixa. Uma tabela só é o que garante que a coluna vale o mesmo de cima
+    a baixo — sem largura fixa em lugar nenhum.
+  */
+  const sections = bodySections(
+    table.getRowModel().rows,
+    groupBy,
+    groupOrder,
+    collapsedGroups,
+  );
+
+  const toggleGroup = (key: string): void =>
+    setCollapsedGroups((atual) =>
+      atual.includes(key)
+        ? atual.filter((fechada) => fechada !== key)
+        : [...atual, key],
+    );
   const colSpan =
     (table.getVisibleLeafColumns().length || 1) + (reorderable ? 1 : 0);
 
@@ -405,6 +632,18 @@ export function DataTable<T extends RowData>({
   };
 
   const filtersEnabled = Boolean(filters);
+  const columnsButton =
+    Boolean(storageKey) && hideable.length > 0 && !emCartoes;
+  /*
+    A barra só existe se tiver o que mostrar.
+
+    Vazia, ela continuava ocupando os 12px do `mb-3` e empurrava a tabela para
+    baixo — a listagem sem toolbar, sem filtro e sem escolha de colunas ficava
+    com um vão maior que o das outras, sem nada que o explicasse.
+  */
+  const temBarra = Boolean(
+    toolbar || toolbarEnd || renderGrid || filtersEnabled || columnsButton,
+  );
   const activeFilters = !filters
     ? 0
     : filters.mode === "advanced"
@@ -420,6 +659,82 @@ export function DataTable<T extends RowData>({
     emptyMessage ??
     (activeFilters > 0 ? t("table.emptyFiltered") : t("table.empty"));
 
+  /*
+    Três blocos, e a ordem tem motivo: quantos são à esquerda, para onde ir no
+    meio, e o tamanho da página à direita — o controle que se mexe uma vez fica
+    na ponta, e a navegação, que se usa o tempo todo, no centro. Em tela estreita
+    eles empilham em vez de espremer.
+
+    Fora do JSX da tabela porque a mesma navegação serve à lista e aos cartões:
+    o formato muda o que está acima dele, não em que página se está.
+  */
+  const rodape = (
+    <div className="flex flex-col items-center gap-3 border-t border-border px-4 py-3 text-sm text-muted-foreground sm:flex-row sm:justify-between">
+      <span className="sm:flex-1">
+        {total} {t("table.results")}
+      </span>
+
+      <div className="flex items-center gap-1">
+        <Button
+          variant="ghost"
+          size="icon"
+          aria-label={t("table.previousPage")}
+          disabled={!table.getCanPreviousPage()}
+          onClick={() => table.previousPage()}
+        >
+          <ChevronLeft className="h-4 w-4" />
+        </Button>
+
+        {pageRange(pageIndex, pageCount).map((item, posicao) =>
+          item === "gap" ? (
+            // O buraco não é botão: `key` pela posição porque duas elipses
+            // são indistinguíveis entre si.
+            <span key={`gap-${posicao}`} className="px-1 text-muted-foreground">
+              …
+            </span>
+          ) : (
+            <Button
+              key={item}
+              variant={item === pageIndex + 1 ? "default" : "ghost"}
+              size="icon"
+              // Quadrado de 40px como base, mas cresce com o número: a
+              // página 128 não pode vazar do botão.
+              className="w-auto min-w-10 px-2 tabular-nums"
+              aria-current={item === pageIndex + 1 ? "page" : undefined}
+              onClick={() => table.setPageIndex(item - 1)}
+            >
+              {item}
+            </Button>
+          ),
+        )}
+
+        <Button
+          variant="ghost"
+          size="icon"
+          aria-label={t("table.nextPage")}
+          disabled={!table.getCanNextPage()}
+          onClick={() => table.nextPage()}
+        >
+          <ChevronRight className="h-4 w-4" />
+        </Button>
+      </div>
+
+      <div className="sm:flex-1 sm:text-right">
+        <select
+          value={pageSize}
+          onChange={(e) => table.setPageSize(Number(e.target.value))}
+          className="h-9 rounded-md border border-input bg-transparent px-2 text-sm"
+        >
+          {pageSizeOptions.map((n) => (
+            <option key={n} value={n}>
+              {n} {t("table.perPage")}
+            </option>
+          ))}
+        </select>
+      </div>
+    </div>
+  );
+
   return (
     <div>
       {/*
@@ -431,272 +746,307 @@ export function DataTable<T extends RowData>({
         `min-w-0` é o par obrigatório disso — filho de flex não encolhe abaixo
         do próprio conteúdo sem ele, e o `flex-wrap` sozinho não bastaria.
       */}
-      <div className="mb-3 flex flex-wrap items-center justify-between gap-2">
-        <div className="flex min-w-0 flex-wrap items-center gap-2">
-          {toolbar}
-        </div>
-        <div className="flex flex-wrap items-center gap-2">
-          {toolbarEnd}
-          {/* Filtro antes de colunas: filtrar é a ação do dia a dia, escolher
+      {temBarra && (
+        <div className="mb-3 flex flex-wrap items-center justify-between gap-2">
+          <div className="flex min-w-0 flex-wrap items-center gap-2">
+            {toolbar}
+          </div>
+          <div className="flex flex-wrap items-center gap-2">
+            {renderGrid && (
+              <SegmentedControl
+                label={t("table.view")}
+                value={view}
+                onValueChange={(next) => setView(next as TableView)}
+                options={[
+                  { value: "list", label: t("table.viewList") },
+                  { value: "grid", label: t("table.viewGrid") },
+                ]}
+              />
+            )}
+            {toolbarEnd}
+            {/* Filtro antes de colunas: filtrar é a ação do dia a dia, escolher
               coluna se faz uma vez e a tela guarda. */}
-          {filtersEnabled && (
-            <Button
-              variant="outline"
-              size="sm"
-              onClick={() => setFiltersOpen(true)}
-            >
-              <Filter className="h-4 w-4" />
-              {t("filters.button")}
-              {activeFilters > 0 && (
-                <span className="ml-1 rounded-full bg-primary px-1.5 text-xs text-primary-foreground">
-                  {activeFilters}
-                </span>
-              )}
-            </Button>
+            {filtersEnabled && (
+              <Button
+                variant="outline"
+                size="sm"
+                onClick={() => setFiltersOpen(true)}
+              >
+                <Filter className="h-4 w-4" />
+                {t("filters.button")}
+                {activeFilters > 0 && (
+                  <span className="ml-1 rounded-full bg-primary px-1.5 text-xs text-primary-foreground">
+                    {activeFilters}
+                  </span>
+                )}
+              </Button>
+            )}
+            {columnsButton && (
+              <Button
+                variant="outline"
+                size="sm"
+                onClick={() => setColsOpen(true)}
+              >
+                <SlidersHorizontal className="h-4 w-4" />
+                {t("table.columnsButton")}
+              </Button>
+            )}
+          </div>
+        </div>
+      )}
+
+      {emCartoes && renderGrid ? (
+        <div className="flex flex-col gap-3">
+          {loading && (
+            <Card className="p-10">
+              <Spinner className="mx-auto" />
+            </Card>
           )}
-          {storageKey && hideable.length > 0 && (
-            <Button
-              variant="outline"
-              size="sm"
-              onClick={() => setColsOpen(true)}
-            >
-              <SlidersHorizontal className="h-4 w-4" />
-              {t("table.columnsButton")}
-            </Button>
+          {!loading && table.getRowModel().rows.length === 0 && (
+            <Card className="p-10 text-center text-muted-foreground">
+              {emptyText}
+            </Card>
           )}
-        </div>
-      </div>
+          {!loading &&
+            table.getRowModel().rows.length > 0 &&
+            renderGrid(table.getRowModel().rows.map((row) => row.original))}
 
-      <Card>
-        <Table>
-          <TableHeader>
-            {table.getHeaderGroups().map((hg) => (
-              <TableRow key={hg.id}>
-                {reorderable && (
-                  <TableHead className="w-px">
-                    <span className="sr-only">{t("table.reorder")}</span>
-                  </TableHead>
-                )}
-                {hg.headers.map((header) => {
-                  const canSort = header.column.getCanSort();
-                  const sorted = header.column.getIsSorted();
-                  return (
-                    <TableHead
-                      key={header.id}
-                      className={shrinkClass(header.column.columnDef)}
-                    >
-                      {header.isPlaceholder ? null : canSort ? (
-                        <button
-                          className="flex items-center gap-1 hover:text-foreground"
-                          onClick={header.column.getToggleSortingHandler()}
-                        >
-                          {flexRender(
+          {/* O rodapé ganha moldura própria: solto sobre o fundo, a navegação
+              ficaria pendurada abaixo dos cartões, sem nada que a segure. */}
+          {!semRodape && <Card>{rodape}</Card>}
+        </div>
+      ) : (
+        <Card>
+          <Table>
+            <TableHeader>
+              {table.getHeaderGroups().map((hg) => (
+                <TableRow key={hg.id}>
+                  {reorderable && (
+                    <TableHead className="w-px">
+                      <span className="sr-only">{t("table.reorder")}</span>
+                    </TableHead>
+                  )}
+                  {hg.headers.map((header) => {
+                    const canSort = header.column.getCanSort();
+                    const sorted = header.column.getIsSorted();
+                    return (
+                      <TableHead
+                        key={header.id}
+                        className={shrinkClass(header.column.columnDef)}
+                      >
+                        {header.isPlaceholder ? null : canSort ? (
+                          <button
+                            className="flex items-center gap-1 hover:text-foreground"
+                            onClick={header.column.getToggleSortingHandler()}
+                          >
+                            {flexRender(
+                              header.column.columnDef.header,
+                              header.getContext(),
+                            )}
+                            {sorted === "asc" ? (
+                              <ArrowUp className="h-3.5 w-3.5 text-primary" />
+                            ) : sorted === "desc" ? (
+                              <ArrowDown className="h-3.5 w-3.5 text-primary" />
+                            ) : (
+                              // Seta dupla apagada na coluna livre e seta única
+                              // em destaque na que ordena: sem a cor, achar a
+                              // coluna ativa exige comparar o desenho de todas.
+                              <ArrowUpDown className="h-3.5 w-3.5 opacity-40" />
+                            )}
+                          </button>
+                        ) : (
+                          flexRender(
                             header.column.columnDef.header,
                             header.getContext(),
-                          )}
-                          {sorted === "asc" ? (
-                            <ArrowUp className="h-3.5 w-3.5 text-primary" />
-                          ) : sorted === "desc" ? (
-                            <ArrowDown className="h-3.5 w-3.5 text-primary" />
+                          )
+                        )}
+                      </TableHead>
+                    );
+                  })}
+                </TableRow>
+              ))}
+            </TableHeader>
+            <TableBody>
+              {loading && (
+                <TableRow>
+                  <TableCell colSpan={colSpan} className="h-24 text-center">
+                    <Spinner className="mx-auto" />
+                  </TableCell>
+                </TableRow>
+              )}
+              {!loading && table.getRowModel().rows.length === 0 && (
+                <TableRow>
+                  <TableCell
+                    colSpan={colSpan}
+                    className="h-24 text-center text-muted-foreground"
+                  >
+                    {emptyText}
+                  </TableCell>
+                </TableRow>
+              )}
+              {!loading &&
+                sections.map((section) => (
+                  <Fragment key={section.key}>
+                    {section.header && renderGroupHeader && (
+                      <TableRow className="hover:bg-transparent">
+                        {/* Uma célula atravessando a tabela: é o que faz a
+                            faixa parecer cabeçalho, e não registro sem
+                            dados. */}
+                        <TableCell
+                          colSpan={colSpan}
+                          className="bg-muted/40 py-2"
+                        >
+                          {collapsibleGroups ? (
+                            <button
+                              type="button"
+                              className="flex w-full items-center gap-3 text-left"
+                              aria-expanded={!section.header.collapsed}
+                              onClick={() => toggleGroup(section.key)}
+                            >
+                              <ChevronRight
+                                className={cn(
+                                  "h-3.5 w-3.5 flex-none text-muted-foreground transition-transform",
+                                  !section.header.collapsed && "rotate-90",
+                                )}
+                              />
+                              {/* O conteúdo ocupa o resto: é o que deixa o
+                                  total encostar na borda direita, como
+                                  encostaria fora do botão. */}
+                              <span className="min-w-0 flex-1">
+                                {renderGroupHeader(section.header)}
+                              </span>
+                            </button>
                           ) : (
-                            // Seta dupla apagada na coluna livre e seta única
-                            // em destaque na que ordena: sem a cor, achar a
-                            // coluna ativa exige comparar o desenho de todas.
-                            <ArrowUpDown className="h-3.5 w-3.5 opacity-40" />
+                            renderGroupHeader(section.header)
                           )}
-                        </button>
-                      ) : (
-                        flexRender(
-                          header.column.columnDef.header,
-                          header.getContext(),
-                        )
-                      )}
-                    </TableHead>
-                  );
-                })}
-              </TableRow>
-            ))}
-          </TableHeader>
-          <TableBody>
-            {loading && (
-              <TableRow>
-                <TableCell colSpan={colSpan} className="h-24 text-center">
-                  <Spinner className="mx-auto" />
-                </TableCell>
-              </TableRow>
-            )}
-            {!loading && table.getRowModel().rows.length === 0 && (
-              <TableRow>
-                <TableCell
-                  colSpan={colSpan}
-                  className="h-24 text-center text-muted-foreground"
-                >
-                  {emptyText}
-                </TableCell>
-              </TableRow>
-            )}
-            {!loading &&
-              table.getRowModel().rows.map((row, index) => {
-                const dragging = draggedRow === row.id;
-                const shift = dragging ? 0 : rowShift(index);
-
-                return (
-                  <TableRow
-                    key={row.id}
-                    data-row-id={row.id}
-                    className={cn(
-                      // A linha viaja com o dedo, destacada do resto da tabela —
-                      // é o que diz que o arrasto pegou, e qual linha pegou.
-                      dragging &&
-                        "relative z-20 bg-card shadow-xl ring-1 ring-primary/50",
-                      draggedRow !== null && "select-none",
-                      /*
-                        A transição existe só enquanto o arrasto dura, e só nas
-                        linhas paradas: na que segue o dedo ela viraria atraso,
-                        e depois de soltar ela animaria a volta ao zero por
-                        cima da lista já reordenada — dois movimentos ao mesmo
-                        tempo, que é o tremor que se vê ao largar a linha.
-                      */
-                      draggedRow !== null &&
-                        !dragging &&
-                        "transition-transform duration-200",
+                        </TableCell>
+                      </TableRow>
                     )}
-                    style={
-                      dragging
-                        ? {
-                            // O `scale` é o "levantou da mesa": a linha na mão
-                            // fica maior que as paradas, como o card que sai
-                            // da coluna no quadro.
-                            transform: `translateY(${dragOffset}px) scale(1.01)`,
-                          }
-                        : shift !== 0
-                          ? { transform: `translateY(${shift}px)` }
-                          : undefined
-                    }
-                  >
-                    {reorderable && (
-                      <TableCell className="w-px pr-0">
-                        <button
-                          type="button"
-                          aria-label={t("table.reorder")}
-                          title={
-                            canReorder
-                              ? t("table.reorder")
-                              : t("table.reorderSorted")
-                          }
-                          disabled={!canReorder}
-                          // `touch-none` é o que impede a página de rolar embaixo
-                          // do dedo enquanto a linha viaja.
+
+                    {section.rows.map((row, indexNaSecao) => {
+                      const index = section.offset + indexNaSecao;
+                      const dragging = draggedRow === row.id;
+                      const shift = dragging ? 0 : rowShift(index);
+
+                      return (
+                        <TableRow
+                          key={row.id}
+                          data-row-id={row.id}
                           className={cn(
-                            "flex touch-none items-center text-muted-foreground",
-                            canReorder
-                              ? "cursor-grab active:cursor-grabbing hover:text-foreground"
-                              : "cursor-not-allowed opacity-30",
+                            // A linha viaja com o dedo, destacada do resto da tabela —
+                            // é o que diz que o arrasto pegou, e qual linha pegou.
+                            dragging &&
+                              "relative z-20 bg-card shadow-xl ring-1 ring-primary/50",
+                            draggedRow !== null && "select-none",
+                            /*
+                          A transição existe só enquanto o arrasto dura, e só nas
+                          linhas paradas: na que segue o dedo ela viraria atraso,
+                          e depois de soltar ela animaria a volta ao zero por
+                          cima da lista já reordenada — dois movimentos ao mesmo
+                          tempo, que é o tremor que se vê ao largar a linha.
+                        */
+                            draggedRow !== null &&
+                              !dragging &&
+                              "transition-transform duration-200",
                           )}
-                          onPointerDown={
-                            canReorder ? startRowDrag(row.id) : undefined
+                          style={
+                            dragging
+                              ? {
+                                  // O `scale` é o "levantou da mesa": a linha na mão
+                                  // fica maior que as paradas, como o card que sai
+                                  // da coluna no quadro.
+                                  transform: `translateY(${dragOffset}px) scale(1.01)`,
+                                }
+                              : shift !== 0
+                                ? { transform: `translateY(${shift}px)` }
+                                : undefined
                           }
-                          onPointerMove={canReorder ? moveRowDrag : undefined}
-                          onPointerUp={canReorder ? endRowDrag : undefined}
-                          onPointerCancel={canReorder ? endRowDrag : undefined}
                         >
-                          <GripVertical className="h-4 w-4" />
-                        </button>
-                      </TableCell>
-                    )}
-                    {row.getVisibleCells().map((cell) => (
+                          {reorderable && (
+                            <TableCell className="w-px pr-0">
+                              <button
+                                type="button"
+                                aria-label={t("table.reorder")}
+                                title={
+                                  canReorder
+                                    ? t("table.reorder")
+                                    : groupBy
+                                      ? t("table.reorderGrouped")
+                                      : t("table.reorderSorted")
+                                }
+                                disabled={!canReorder}
+                                // `touch-none` é o que impede a página de rolar embaixo
+                                // do dedo enquanto a linha viaja.
+                                className={cn(
+                                  "flex touch-none items-center text-muted-foreground",
+                                  canReorder
+                                    ? "cursor-grab active:cursor-grabbing hover:text-foreground"
+                                    : "cursor-not-allowed opacity-30",
+                                )}
+                                onPointerDown={
+                                  canReorder ? startRowDrag(row.id) : undefined
+                                }
+                                onPointerMove={
+                                  canReorder ? moveRowDrag : undefined
+                                }
+                                onPointerUp={
+                                  canReorder ? endRowDrag : undefined
+                                }
+                                onPointerCancel={
+                                  canReorder ? endRowDrag : undefined
+                                }
+                              >
+                                <GripVertical className="h-4 w-4" />
+                              </button>
+                            </TableCell>
+                          )}
+                          {row.getVisibleCells().map((cell) => (
+                            <TableCell
+                              key={cell.id}
+                              className={shrinkClass(cell.column.columnDef)}
+                            >
+                              {flexRender(
+                                cell.column.columnDef.cell,
+                                cell.getContext(),
+                              )}
+                            </TableCell>
+                          ))}
+                        </TableRow>
+                      );
+                    })}
+                  </Fragment>
+                ))}
+            </TableBody>
+
+            {temFechamento && !loading && (
+              <TableFooter>
+                {table.getFooterGroups().map((grupo) => (
+                  <TableRow key={grupo.id}>
+                    {/* A coluna da alça não tem fechamento, mas precisa da
+                        célula: sem ela a linha inteira sobe uma casa. */}
+                    {reorderable && <TableCell className="w-px" />}
+                    {grupo.headers.map((header) => (
                       <TableCell
-                        key={cell.id}
-                        className={shrinkClass(cell.column.columnDef)}
+                        key={header.id}
+                        className={shrinkClass(header.column.columnDef)}
                       >
-                        {flexRender(
-                          cell.column.columnDef.cell,
-                          cell.getContext(),
-                        )}
+                        {header.isPlaceholder
+                          ? null
+                          : flexRender(
+                              header.column.columnDef.footer,
+                              header.getContext(),
+                            )}
                       </TableCell>
                     ))}
                   </TableRow>
-                );
-              })}
-          </TableBody>
-        </Table>
-
-        {/*
-          Três blocos, e a ordem tem motivo: quantos são à esquerda, para onde
-          ir no meio, e o tamanho da página à direita — o controle que se mexe
-          uma vez fica na ponta, e a navegação, que se usa o tempo todo, no
-          centro. Em tela estreita eles empilham em vez de espremer.
-        */}
-        {!semRodape && (
-          <div className="flex flex-col items-center gap-3 border-t border-border px-4 py-3 text-sm text-muted-foreground sm:flex-row sm:justify-between">
-            <span className="sm:flex-1">
-              {total} {t("table.results")}
-            </span>
-
-            <div className="flex items-center gap-1">
-              <Button
-                variant="ghost"
-                size="icon"
-                aria-label={t("table.previousPage")}
-                disabled={!table.getCanPreviousPage()}
-                onClick={() => table.previousPage()}
-              >
-                <ChevronLeft className="h-4 w-4" />
-              </Button>
-
-              {pageRange(pageIndex, pageCount).map((item, posicao) =>
-                item === "gap" ? (
-                  // O buraco não é botão: `key` pela posição porque duas elipses
-                  // são indistinguíveis entre si.
-                  <span
-                    key={`gap-${posicao}`}
-                    className="px-1 text-muted-foreground"
-                  >
-                    …
-                  </span>
-                ) : (
-                  <Button
-                    key={item}
-                    variant={item === pageIndex + 1 ? "default" : "ghost"}
-                    size="icon"
-                    // Quadrado de 40px como base, mas cresce com o número: a
-                    // página 128 não pode vazar do botão.
-                    className="w-auto min-w-10 px-2 tabular-nums"
-                    aria-current={item === pageIndex + 1 ? "page" : undefined}
-                    onClick={() => table.setPageIndex(item - 1)}
-                  >
-                    {item}
-                  </Button>
-                ),
-              )}
-
-              <Button
-                variant="ghost"
-                size="icon"
-                aria-label={t("table.nextPage")}
-                disabled={!table.getCanNextPage()}
-                onClick={() => table.nextPage()}
-              >
-                <ChevronRight className="h-4 w-4" />
-              </Button>
-            </div>
-
-            <div className="sm:flex-1 sm:text-right">
-              <select
-                value={pageSize}
-                onChange={(e) => table.setPageSize(Number(e.target.value))}
-                className="h-9 rounded-md border border-input bg-transparent px-2 text-sm"
-              >
-                {pageSizeOptions.map((n) => (
-                  <option key={n} value={n}>
-                    {n} {t("table.perPage")}
-                  </option>
                 ))}
-              </select>
-            </div>
-          </div>
-        )}
-      </Card>
+              </TableFooter>
+            )}
+          </Table>
+
+          {!semRodape && rodape}
+        </Card>
+      )}
 
       {storageKey && (
         <ColumnVisibilityModal

package/src/components/ui/table.tsx

@@ -36,6 +36,27 @@ const TableBody = React.forwardRef<
 ));
 TableBody.displayName = "TableBody";
 
+/**
+ * A linha de fechamento da tabela: total, saldo, contagem.
+ *
+ * `tfoot` e não uma última linha do corpo: ela não é registro — não ordena
+ * junto, não entra na contagem e continua embaixo quando a ordenação muda.
+ */
+const TableFooter = React.forwardRef<
+  HTMLTableSectionElement,
+  React.HTMLAttributes<HTMLTableSectionElement>
+>(({ className, ...props }, ref) => (
+  <tfoot
+    ref={ref}
+    className={cn(
+      "border-t border-border bg-muted/40 font-medium [&_tr]:border-0",
+      className,
+    )}
+    {...props}
+  />
+));
+TableFooter.displayName = "TableFooter";
+
 const TableRow = React.forwardRef<
   HTMLTableRowElement,
   React.HTMLAttributes<HTMLTableRowElement>
@@ -90,4 +111,12 @@ const TableCell = React.forwardRef<
 ));
 TableCell.displayName = "TableCell";
 
-export { Table, TableBody, TableCell,TableHead, TableHeader, TableRow };
+export {
+  Table,
+  TableBody,
+  TableCell,
+  TableFooter,
+  TableHead,
+  TableHeader,
+  TableRow,
+};

package/src/hooks/use-column-visibility.ts

@@ -15,11 +15,16 @@ export interface UseColumnVisibilityResult {
 /**
  * Persiste as colunas ocultas de uma tabela em localStorage (por storageKey).
  * Retorna a lista de ocultas + helpers para ler/salvar.
+ *
+ * `defaultHidden` é só o ponto de partida: vale enquanto ninguém tiver
+ * escolhido as colunas nesta tela. Depois da primeira escolha, a lista guardada
+ * é a verdade — inclusive quando ela mostra uma coluna que nasceu escondida.
  */
 export function useColumnVisibility(
   storageKey?: string,
+  defaultHidden: string[] = [],
 ): UseColumnVisibilityResult {
-  const [hiddenColumns, setHiddenColumns] = useState<string[]>([]);
+  const [hiddenColumns, setHiddenColumns] = useState<string[]>(defaultHidden);
 
   useEffect(() => {
     if (!storageKey) {return;}

package/src/hooks/use-table-view.ts

@@ -0,0 +1,54 @@
+"use client";
+
+import { useCallback, useEffect, useState } from "react";
+
+import { safeStorage } from "#core/_utils/storage";
+
+const STORAGE_PREFIX = "view:";
+
+/** Como a listagem se apresenta: em linhas ou em cartões. */
+export type TableView = "list" | "grid";
+
+export interface UseTableViewResult {
+  view: TableView;
+  setView: (next: TableView) => void;
+}
+
+/**
+ * Guarda em qual formato a pessoa deixou a listagem, por `storageKey`.
+ *
+ * Mesma ideia das colunas escondidas: é escolha de quem olha, não da tela, e
+ * refazê-la a cada visita transformaria o alternador num incômodo. Sem
+ * `storageKey` o formato dura só enquanto a tela estiver aberta — igual às
+ * colunas, que também só persistem quando a tabela tem chave.
+ */
+export function useTableView(
+  storageKey?: string,
+  defaultView: TableView = "list",
+): UseTableViewResult {
+  const [view, setStoredView] = useState<TableView>(defaultView);
+
+  useEffect(() => {
+    if (!storageKey) {
+      return;
+    }
+    const raw = safeStorage.get(`${STORAGE_PREFIX}${storageKey}`);
+
+    if (raw === "list" || raw === "grid") {
+      setStoredView(raw);
+    }
+  }, [storageKey]);
+
+  const setView = useCallback(
+    (next: TableView) => {
+      setStoredView(next);
+
+      if (storageKey) {
+        safeStorage.set(`${STORAGE_PREFIX}${storageKey}`, next);
+      }
+    },
+    [storageKey],
+  );
+
+  return { view, setView };
+}

package/src/i18n/messages/en.ts

@@ -165,8 +165,12 @@ export const en: Messages = {
     nextPage: "Next page",
     empty: "No records",
     emptyFiltered: "No records match this filter",
+    view: "List format",
+    viewList: "List",
+    viewGrid: "Cards",
     reorder: "Drag to reorder",
     reorderSorted: "Clear the column sorting to drag rows",
+    reorderGrouped: "Rows cannot be reordered while the list is grouped",
   },
   filters: {
     button: "Filters",

package/src/i18n/messages/pt.ts

@@ -167,9 +167,13 @@ export const pt = {
     nextPage: "Próxima página",
     empty: "Nenhum registro",
     emptyFiltered: "Nenhum registro para este filtro",
+    view: "Formato da listagem",
+    viewList: "Lista",
+    viewGrid: "Cartões",
     reorder: "Arraste para reordenar",
     reorderSorted:
       "Limpe a ordenação por coluna para arrastar as linhas",
+    reorderGrouped: "Não dá para reordenar com a lista dividida em seções",
   },
   filters: {
     button: "Filtros",

package/src/index.ts

@@ -110,6 +110,8 @@ export {
   EXPAND_SHORTCUT_LABEL,
   useShortcut,
 } from "#core/hooks/use-shortcut";
+export type { TableView, UseTableViewResult } from "#core/hooks/use-table-view";
+export { useTableView } from "#core/hooks/use-table-view";
 // RequestOperation é enum (valor, não só tipo): sem ele o projeto não consegue
 // pedir o toast padrão de criado/alterado/removido que o core já traduz.
 export { RequestOperation, useRequest } from "#core/hooks/use-request";