@seedgrid/ai-toolkit 0.0.0-stage → 0.3.0

package/seedgridKB/SeedGrid/SeedGrid-components/datatable/API.md

@@ -0,0 +1,174 @@
+---
+tags: [seedgrid, component, frontend, react, datatable, api]
+fonte: front/seedgrid-fe-components/packages/seedgrid-fe-components/src/inputs/SgDatatable.tsx
+branch: main
+commit: ad30fc11de
+analisado-em: 2026-10-14
+---
+
+# SgDatatable: API
+
+Import: `import { SgDatatable, type SgDatatableColumn } from "@seedgrid/fe-components";` (pacote v`2026.7.1`). Contexto: [[SeedGrid/SeedGrid-components/datatable/Visao-geral|Visão geral do SgDatatable]]. Exemplos: [[SeedGrid/SeedGrid-components/datatable/Exemplos|Exemplos do SgDatatable]]. A metodologia das tabelas está em [[SeedGrid/SeedGrid-components/inputs-texto/API#Como as tabelas foram montadas|Como as tabelas foram montadas]].
+
+O componente é genérico: `SgDatatable<T extends SgDatatableRow = SgDatatableRow>`, com `SgDatatableRow = Record<string, unknown>`. É declarado com `React.forwardRef` e recebe `ref?: React.Ref<SgDatatableRef<T>>`. **Não** usa `RhfFieldProps`, então não há integração com react-hook-form. **Confirmado**.
+
+## Tipos exportados
+
+`SgDatatableProps`, `SgDatatableRow`, `SgDatatableColumn`, `SgDatatableColumnAlign`, `SgDatatableCellMeta`, `SgDatatableFilterEvent`, `SgDatatableFilterMatchMode`, `SgDatatablePageEvent`, `SgDatatableRef`, `SgDatatableSelection`, `SgDatatableSelectionMode`, `SgDatatableSortEvent`, `SgDatatableSortOrder`. **Confirmado** em `src/index.ts`.
+
+## Props de `SgDatatable` (40)
+
+| Prop | Tipo | Padrão | Obrigatória | Descrição |
+|---|---|---|---|---|
+| `id` | `string` | — | Não | Também chave de persistência das colunas (`datatable:<id>:columns`) quando há `SgEnvironmentProvider`. |
+| `title` | `string` | — | Não | Título do `SgGroupBox`. |
+| `value` | `T[]` | — | Sim | Linhas (`Record<string, unknown>[]`). |
+| `columns` | `SgDatatableColumn<T>[]` | — | Sim | `SgDatatableColumn<T>[]`. |
+| `dataKey` | `string` | — | Não | Campo identidade da linha (seleção e `key`). |
+| `lazy` | `boolean` | `false` | Não | Server-side: não filtra, ordena nem pagina localmente. |
+| `totalRecords` | `number` | `value.length` | Não | Total em modo `lazy`. |
+| `paginator` | `boolean` | `false` | Não | Exibe paginação. |
+| `rows` | `number` | `10` | Não | Linhas por página (valor inicial). |
+| `first` | `number` | `0` | Não | Índice da 1ª linha (controlado quando definido). |
+| `rowsPerPageOptions` | `number[]` | — | Não | Opções de linhas por página. |
+| `onPage` | `((event: SgDatatablePageEvent) => void)` | — | Não | `{first, rows, page (base 1), pageCount, totalRecords}`. |
+| `sortField` | `string \| null` | — | Não | Campo ordenado (controlado). |
+| `sortOrder` | `SgDatatableSortOrder` | `0` | Não | `1` asc, `-1` desc, `0` sem ordem (controlado). |
+| `onSort` | `((event: SgDatatableSortEvent) => void)` | — | Não | `{sortField, sortOrder}`. |
+| `removableSort` | `boolean` | `true` | Não | Ciclo asc → desc → sem ordem (senão volta a asc). |
+| `selectionMode` | `SgDatatableSelectionMode` | — | Não | `single` ou `multiple` (clique na linha). |
+| `selection` | `SgDatatableSelection<T>` | — | Não | Seleção controlada (`T`, `T[]` ou `null`). |
+| `onSelectionChange` | `((selection: SgDatatableSelection<T>) => void)` | — | Não | Recebe a nova seleção. |
+| `showGlobalFilter` | `boolean` | `false` | Não | Campo de filtro global (match `contains`). |
+| `globalFilter` | `string` | — | Não | Filtro global controlado. |
+| `globalFilterPlaceholder` | `string` | i18n `components.datatable.globalFilterPlaceholder` | Não | Placeholder. |
+| `onGlobalFilterChange` | `((value: string) => void)` | — | Não | Recebe o texto do filtro global. |
+| `showColumnFilters` | `boolean` | `false` | Não | Filtros por coluna (colunas com `filter`). |
+| `filters` | `Record<string, string>` | — | Não | Filtros por coluna controlados (`{campo: texto}`). |
+| `onFilter` | `((event: SgDatatableFilterEvent) => void)` | — | Não | `{filters, globalFilter}`. |
+| `showClearFiltersButton` | `boolean` | `false` | Não | Botão limpar filtros. |
+| `stripedRows` | `boolean` | `false` | Não | Zebrado. |
+| `showGridlines` | `boolean` | `false` | Não | Linhas de grade. |
+| `hoverableRows` | `boolean` | `true` | Não | Destaque no hover. |
+| `loading` | `boolean` | `false` | Não | Linha de carregamento (i18n `components.datatable.loading`). |
+| `emptyMessage` | `string` | i18n `components.datatable.empty` | Não | Texto sem linhas. |
+| `className` | `string` | `""` | Não | Classes do wrapper. |
+| `style` | `CSSProperties` | — | Não | Estilo do wrapper. |
+| `tableClassName` | `string` | `""` | Não | Classes do `<table>`. |
+| `rowClassName` | `string \| ((rowData: T, rowIndex: number) => string)` | — | Não | Classe fixa ou função `(row, index)`. |
+| `groupBoxProps` | `(Omit<Partial<SgGroupBoxProps>, "title" \| "children"> & { title?: string; })` | `{}` | Não | Props do `SgGroupBox`. |
+| `showColumnManager` | `boolean` | `true` | Não | Gerenciador de colunas (ocultar/reordenar). |
+| `columnManagerLabel` | `string` | i18n `components.datatable.columns` (fallback "Colunas") | Não | Rótulo do gerenciador. |
+| `columnManagerMaxHeight` | `string \| number` | `320` | Não | Altura máxima do painel. |
+
+## `SgDatatableColumn<T>` (22 campos)
+
+| Campo | Tipo | Padrão | Obrigatório | Descrição |
+|---|---|---|---|---|
+| `columnId` | `string` | — | Não | Chave estável da coluna, usada na persistência e na reordenação. A chave final segue a ordem `columnId` → `field` → índice. |
+| `field` | `string` | — | Não | Campo da linha. Aceita caminho com ponto, como `"cliente.nome"` (`getFieldValue`). |
+| `header` | `ReactNode` | — | **Sim** | Cabeçalho. |
+| `body` | `(rowData: T, meta: SgDatatableCellMeta<T>) => ReactNode` | valor do campo | Não | Render da célula. `meta = {rowIndex, field, value, rowData}`. |
+| `footer` | `ReactNode \| ((rows: T[]) => ReactNode)` | — | Não | Rodapé. A função recebe as linhas filtradas e ordenadas, **todas**, não só a página. |
+| `sortable` | `boolean` | — | Não | Habilita ordenação pelo cabeçalho. |
+| `sortField` | `string` | `field` | Não | Campo usado para ordenar. |
+| `sortFunction` | `(rowA: T, rowB: T) => number` | `compareValues` | Não | Comparador próprio. A direção é aplicada por cima. |
+| `filter` | `boolean` | — | Não | Mostra filtro na coluna (requer `showColumnFilters`). |
+| `filterField` | `string` | `field` | Não | Campo filtrado. |
+| `filterPlaceholder` | `string` | i18n `components.datatable.columnFilterPlaceholder` | Não | Placeholder do filtro. |
+| `filterMatchMode` | `SgDatatableFilterMatchMode` | `"contains"` | Não | `contains`, `startsWith`, `endsWith` ou `equals`. |
+| `excludeGlobalFilter` | `boolean` | — | Não | Tira a coluna do filtro global. |
+| `align` | `SgDatatableColumnAlign` | — | Não | `left`, `center` ou `right`. |
+| `width` | `number \| string` | — | Não | Largura (número = px). |
+| `minWidth` | `number \| string` | — | Não | Largura mínima. |
+| `hidden` | `boolean` | `false` | Não | Começa oculta. O gerenciador de colunas pode mudar isso. |
+| `hideable` | `boolean` | `true` (efetivo) | Não | `false` impede ocultar pelo gerenciador. |
+| `reorderable` | `boolean` | `true` (efetivo) | Não | `false` impede reordenar pelo gerenciador. |
+| `className` | `string` | — | Não | Classe aplicada ao `<th>`, às células e ao rodapé da coluna. |
+| `headerClassName` | `string` | — | Não | Classe do `<th>`. |
+| `bodyClassName` | `string \| ((rowData: T, rowIndex: number) => string \| undefined)` | — | Não | Classe da célula, fixa ou calculada. |
+
+Fonte: `SgDatatable.tsx` → tipo `SgDatatableColumn` e usos em `SgDatatableBase`. **Confirmado**, exceto onde a célula indica outra coisa.
+
+## Eventos e formatos
+
+| Evento | Payload | Quando |
+|---|---|---|
+| `onPage` | `SgDatatablePageEvent` = `{ first, rows, page, pageCount, totalRecords }` (`page` começa em **1**) | Troca de página, de linhas por página e `resetPage`/`goToPage` |
+| `onSort` | `SgDatatableSortEvent` = `{ sortField: string \| null, sortOrder: 1 \| -1 \| 0 }` | Clique em cabeçalho ordenável |
+| `onFilter` | `SgDatatableFilterEvent` = `{ filters: Record<string,string>, globalFilter: string }` | Mudança de filtro global ou de coluna |
+| `onGlobalFilterChange` | `string` | Mudança do filtro global |
+| `onSelectionChange` | `SgDatatableSelection<T>` = `T \| T[] \| null` | Clique na linha. Em `single`, clicar de novo na linha selecionada desmarca (`null`). Em `multiple`, alterna a linha no array. |
+
+**Seleção por clique:** o clique é ignorado quando o alvo está dentro de `button`, `a`, `input`, `select`, `textarea`, `label` ou de um elemento com `data-sg-stop-row-select="true"`. Por isso os botões de ação na célula não selecionam a linha. **Confirmado**.
+
+**Ordenação:** o clique em uma coluna nova ordena asc. Na mesma coluna, a sequência é asc → desc → sem ordem com `removableSort` (padrão); sem ele, desc → asc. **Confirmado**.
+
+## Ref (`SgDatatableRef<T>`)
+
+| Método | Retorno/efeito |
+|---|---|
+| `getProcessedRows()` | Linhas filtradas e ordenadas (`T[]`). Em `lazy`, devolve o próprio `value`. |
+| `getPagedRows()` | Linhas da página atual. |
+| `clearFilters()` | Limpa os filtros global e de coluna. |
+| `clearSelection()` | Limpa a seleção. |
+| `resetSort()` | Remove a ordenação. |
+| `resetPage()` | Volta para a primeira página. |
+| `goToPage(page)` | Vai para a página indicada. |
+
+**Confirmado** (`useImperativeHandle` em `SgDatatableBase`).
+
+## Modos controlado e não controlado
+
+Cada estado é controlado só quando a prop correspondente é passada (`!== undefined`):
+- `first`;
+- `sortField`;
+- `sortOrder`;
+- `selection`;
+- `globalFilter`;
+- `filters`.
+
+Quando não é passada, o componente guarda o estado internamente. `rows` é **só valor inicial**: o estado interno `internalRows` muda pelo seletor de linhas por página. **Confirmado**.
+
+## Modo `lazy` (server-side)
+
+- Com `lazy`, as linhas de `value` são exibidas como chegam: sem filtro, sem ordenação e sem fatiar por página.
+- O total vem de `totalRecords`.
+- A aplicação busca os dados em `onPage`, `onSort` e `onFilter`.
+- Testes em `tests/datatable-dom.test.mjs`: "lazy: nao ordena localmente", "lazy: nao pagina localmente". **Confirmado** (testes lidos, não executados).
+
+## Persistência de colunas
+
+- **Quando:** só com `SgEnvironmentProvider` presente (`useHasSgEnvironmentProvider()`) e `id` não vazio.
+- **O que é salvo:** `{version: 1, columnOrder, hiddenColumnsMap}`, via `useSgPersistence()`, na chave `datatable:<id>:columns`.
+- **Ao carregar:** colunas novas entram no fim; colunas que deixaram de existir são descartadas.
+- **Falhas:** erros de persistência são ignorados.
+- **Testes:** `tests/datatable-dom.test.mjs` garante que re-renders do pai com `columns` instável não regravam a persistência.
+
+**Confirmado**.
+
+## Internacionalização
+
+Todos os textos visíveis vêm de `components.datatable.*`:
+- `empty`, `loading`;
+- `globalFilterPlaceholder`, `columnFilterPlaceholder`, `clearFilters`;
+- `columns`, `restoreColumns`, `showAllColumns`, `dragToReorder`;
+- `first`, `prev`, `next`, `last`, `jumpBackward`, `jumpForward`;
+- `rowsPerPage`, `pageReport`, `page`, `pagination`.
+
+`columns` e `restoreColumns` têm fallback fixo em pt-BR ("Colunas", "Restaurar padrão") caso a chave não exista. **Confirmado**.
+
+## Acessibilidade comprovável
+
+- Linhas com `aria-selected` quando selecionadas.
+- Paginação com `aria-label` (`components.datatable.pagination`). Os botões têm `aria-label` próprio, e a página atual tem `aria-current="page"`.
+- O botão do gerenciador de colunas tem `aria-label`.
+- Não há `aria-sort` nos cabeçalhos ordenáveis. A seleção de linha é feita só por clique (o `<tr>` não tem `tabIndex`).
+
+**Confirmado** pela presença ou ausência no código.
+
+## Fontes
+
+- `front/seedgrid-fe-components/packages/seedgrid-fe-components/src/inputs/SgDatatable.tsx` (`SgDatatableBase`, tipos, `buildDatatableColumnsPersistenceKey`)
+- `front/seedgrid-fe-components/packages/seedgrid-fe-components/src/environment/SgEnvironmentProvider.tsx` (`useHasSgEnvironmentProvider`, `useSgPersistence`)
+- `front/seedgrid-fe-components/packages/seedgrid-fe-components/tests/datatable-dom.test.mjs`

package/seedgridKB/SeedGrid/SeedGrid-components/datatable/Exemplos.md

@@ -0,0 +1,236 @@
+---
+tags: [seedgrid, component, frontend, react, datatable, exemplos]
+fonte: front/seedgrid-fe-components/apps/showcase/src/app/components/sg-datatable
+branch: main
+commit: ad30fc11de
+analisado-em: 2026-10-14
+---
+
+# SgDatatable: exemplos
+
+Os exemplos foram conferidos contra [[SeedGrid/SeedGrid-components/datatable/API|API do SgDatatable]]. As fontes são relativas a `front/seedgrid-fe-components/apps/showcase/src/app/components/sg-datatable/samples/`. Não foram compilados nem executados.
+
+Os samples `basico` e `templates` do showcase declaram as colunas **sem tipo** (`const BASE_COLUMNS = [{ …, align: "right" }]`). Sem anotação, o TypeScript alarga `"right"` para `string`, que não é atribuível a `SgDatatableColumnAlign`. Por isso, abaixo, as colunas são anotadas com `SgDatatableColumn<Row>[]`. Isso é **Inferência** pelas regras do TS: os `.sample` não passam pelo `typecheck` do pacote.
+
+## Básico: paginação, zebra e grade
+
+Adaptado de `basico.tsx.sample`, com menos linhas e colunas tipadas.
+
+```tsx
+import React from "react";
+import { SgDatatable, type SgDatatableColumn } from "@seedgrid/fe-components";
+
+type ProductRow = { id: number; code: string; name: string; category: string; price: number; stock: number };
+
+const PRODUCT_ROWS: ProductRow[] = [
+  { id: 1, code: "P-1000", name: "Notebook Pro 14", category: "Computers", price: 1899, stock: 22 },
+  { id: 2, code: "P-1001", name: "Mechanical Keyboard", category: "Accessories", price: 149, stock: 64 },
+  { id: 3, code: "P-1002", name: "Ergonomic Mouse", category: "Accessories", price: 89, stock: 48 }
+];
+
+const BASE_COLUMNS: SgDatatableColumn<ProductRow>[] = [
+  { field: "code", header: "Code", sortable: true },
+  { field: "name", header: "Name", sortable: true, filter: true },
+  { field: "category", header: "Category", sortable: true },
+  { field: "price", header: "Price", sortable: true, align: "right" },
+  { field: "stock", header: "Stock", sortable: true, align: "right" }
+];
+
+export default function BasicDatatableExample() {
+  return (
+    <SgDatatable<ProductRow>
+      id="datatable-basic"
+      title="Product catalog"
+      value={PRODUCT_ROWS}
+      columns={BASE_COLUMNS}
+      dataKey="id"
+      paginator
+      rows={5}
+      rowsPerPageOptions={[5, 10]}
+      showGlobalFilter
+      showColumnFilters
+      stripedRows
+      showGridlines
+    />
+  );
+}
+```
+
+## Templates de célula e rodapé
+
+Adaptado de `templates.tsx.sample`. O `footer` recebe **todas** as linhas processadas (filtradas e ordenadas), não só a página atual.
+
+```tsx
+import React from "react";
+import { SgDatatable, type SgDatatableColumn } from "@seedgrid/fe-components";
+
+type ProductRow = { id: number; code: string; name: string; price: number };
+
+const currency = new Intl.NumberFormat("pt-BR", { style: "currency", currency: "BRL" });
+
+const TEMPLATE_COLUMNS: SgDatatableColumn<ProductRow>[] = [
+  {
+    field: "name",
+    header: "Produto",
+    sortable: true,
+    body: (row) => (
+      <div className="space-y-0.5">
+        <p className="font-medium">{row.name}</p>
+        <p className="text-xs text-muted-foreground">{row.code}</p>
+      </div>
+    ),
+    footer: (rows) => <span>Total: {rows.length}</span>
+  },
+  {
+    field: "price",
+    header: "Preço",
+    align: "right",
+    body: (row) => <span>{currency.format(row.price)}</span>,
+    footer: (rows) => <span>{currency.format(rows.reduce((sum, r) => sum + r.price, 0))}</span>
+  }
+];
+
+export default function TemplateDatatableExample({ rows }: { rows: ProductRow[] }) {
+  return <SgDatatable<ProductRow> id="datatable-template" title="Custom body and footer" value={rows} columns={TEMPLATE_COLUMNS} dataKey="id" paginator rows={5} showGridlines />;
+}
+```
+
+## Ações por linha sem disparar a seleção
+
+Baseado em `acoes.tsx.sample`. Botões dentro da célula não selecionam a linha (`button`, `a` e outros são ignorados pelo `onClick` do `<tr>`).
+
+```tsx
+import React from "react";
+import { Pencil } from "lucide-react";
+import { SgButton, SgDatatable, type SgDatatableColumn, type SgDatatableSelection } from "@seedgrid/fe-components";
+
+type PermissionRow = { id: number; name: string; description: string };
+
+export default function ActionsDatatableExample({ rows }: { rows: PermissionRow[] }) {
+  const [selection, setSelection] = React.useState<SgDatatableSelection<PermissionRow>>(null);
+
+  const columns = React.useMemo<SgDatatableColumn<PermissionRow>[]>(() => [
+    { field: "id", header: "ID", sortable: true, width: 80 },
+    { field: "name", header: "Name", sortable: true },
+    {
+      header: "Actions",
+      align: "center",
+      width: 120,
+      body: (row) => (
+        <SgButton
+          size="sm"
+          appearance="ghost"
+          severity="secondary"
+          iconOnly
+          leftIcon={<Pencil className="size-4" />}
+          aria-label={`Edit ${row.name}`}
+          onClick={() => console.log("edit", row.id)}
+        />
+      )
+    }
+  ], []);
+
+  return (
+    <SgDatatable<PermissionRow>
+      id="datatable-actions"
+      title="Permissions"
+      value={rows}
+      columns={columns}
+      dataKey="id"
+      selectionMode="single"
+      selection={selection}
+      onSelectionChange={setSelection}
+      paginator
+      rows={4}
+    />
+  );
+}
+```
+
+## Server-side (`lazy`)
+
+Resumo de `server-side.tsx.sample`, que traz também uma API simulada completa. O componente só emite eventos: a aplicação busca os dados e devolve `value` + `totalRecords`.
+
+```tsx
+import React from "react";
+import {
+  SgDatatable,
+  type SgDatatableColumn,
+  type SgDatatableFilterEvent,
+  type SgDatatablePageEvent,
+  type SgDatatableSortEvent,
+  type SgDatatableSortOrder
+} from "@seedgrid/fe-components";
+
+type ProductRow = { id: number; code: string; name: string };
+type ServerQuery = { first: number; rows: number; sortField: string | null; sortOrder: SgDatatableSortOrder; globalFilter: string; filters: Record<string, string> };
+
+const COLUMNS: SgDatatableColumn<ProductRow>[] = [
+  { field: "code", header: "Code", sortable: true, filter: true },
+  { field: "name", header: "Name", sortable: true, filter: true }
+];
+
+export default function ServerSideDatatableExample({ fetchPage }: { fetchPage: (q: ServerQuery) => Promise<{ data: ProductRow[]; totalRecords: number }> }) {
+  const [query, setQuery] = React.useState<ServerQuery>({ first: 0, rows: 10, sortField: "name", sortOrder: 1, globalFilter: "", filters: {} });
+  const [rows, setRows] = React.useState<ProductRow[]>([]);
+  const [total, setTotal] = React.useState(0);
+  const [loading, setLoading] = React.useState(false);
+
+  React.useEffect(() => {
+    let cancelled = false;
+    setLoading(true);
+    fetchPage(query)
+      .then((r) => { if (!cancelled) { setRows(r.data); setTotal(r.totalRecords); } })
+      .finally(() => { if (!cancelled) setLoading(false); });
+    return () => { cancelled = true; };
+  }, [query, fetchPage]);
+
+  return (
+    <SgDatatable<ProductRow>
+      id="datatable-server"
+      value={rows}
+      columns={COLUMNS}
+      dataKey="id"
+      lazy
+      totalRecords={total}
+      paginator
+      rows={query.rows}
+      first={query.first}
+      rowsPerPageOptions={[10, 20, 50]}
+      sortField={query.sortField}
+      sortOrder={query.sortOrder}
+      onSort={(e: SgDatatableSortEvent) => setQuery((p) => ({ ...p, first: 0, sortField: e.sortField, sortOrder: e.sortOrder }))}
+      showGlobalFilter
+      globalFilter={query.globalFilter}
+      showColumnFilters
+      filters={query.filters}
+      onFilter={(e: SgDatatableFilterEvent) => setQuery((p) => ({ ...p, first: 0, globalFilter: e.globalFilter, filters: e.filters }))}
+      onPage={(e: SgDatatablePageEvent) => setQuery((p) => ({ ...p, first: e.first, rows: e.rows }))}
+      loading={loading}
+    />
+  );
+}
+```
+
+## Ref imperativo
+
+```tsx
+import React from "react";
+import { SgButton, SgDatatable, type SgDatatableColumn, type SgDatatableRef } from "@seedgrid/fe-components";
+
+type Row = { id: number; name: string };
+const COLUMNS: SgDatatableColumn<Row>[] = [{ field: "name", header: "Nome", sortable: true, filter: true }];
+
+export default function RefExample({ rows }: { rows: Row[] }) {
+  const tableRef = React.useRef<SgDatatableRef<Row>>(null);
+  return (
+    <>
+      <SgDatatable<Row> ref={tableRef} id="tbl-ref" value={rows} columns={COLUMNS} dataKey="id" paginator showColumnFilters />
+      <SgButton onClick={() => tableRef.current?.clearFilters()}>Limpar filtros</SgButton>
+      <SgButton onClick={() => console.log(tableRef.current?.getProcessedRows())}>Exportar visíveis</SgButton>
+    </>
+  );
+}
+```
+
+Os métodos estão confirmados em `SgDatatableRef`. A tipagem com `ref` vem do cast de `React.forwardRef(SgDatatableBase)` para uma função genérica com `ref?: React.Ref<SgDatatableRef<T>>`.

package/seedgridKB/SeedGrid/SeedGrid-components/datatable/Visao-geral.md

@@ -0,0 +1,76 @@
+---
+tags: [seedgrid, component, frontend, react, datatable]
+fonte: front/seedgrid-fe-components/packages/seedgrid-fe-components/src/inputs/SgDatatable.tsx
+branch: main
+commit: ad30fc11de
+analisado-em: 2026-10-14
+---
+
+# SgDatatable
+
+O `SgDatatable` é a tabela de dados do pacote `@seedgrid/fe-components` (v`2026.7.1`). O arquivo fica em `src/inputs/` e é exportado pela raiz do pacote. Referência completa: [[SeedGrid/SeedGrid-components/datatable/API|API do SgDatatable]]. Código: [[SeedGrid/SeedGrid-components/datatable/Exemplos|Exemplos do SgDatatable]].
+
+## Objetivo e funcionalidades
+
+Mostra coleções tabulares com as funções abaixo, todas **Confirmado** em `SgDatatable.tsx`:
+- **Paginação** com seletor de linhas por página e relatório "x–y de n". O número de botões de página se adapta à largura, via `ResizeObserver`.
+- **Ordenação** por coluna, com ciclo asc → desc → sem ordem e comparador customizável.
+- **Filtros:** um global (`contains`) e um por coluna (`contains`, `startsWith`, `endsWith`, `equals`), com botão "limpar filtros".
+- **Seleção** de linha `single` ou `multiple` por clique. Botões e links dentro da célula não selecionam.
+- **Templates** de célula (`body`) e de rodapé (`footer`), além de classes por linha e por célula.
+- **Gerenciador de colunas** (padrão ligado): ocultar e reordenar por arrastar.
+  - Com `SgEnvironmentProvider` e `id`, persiste a ordem e a visibilidade.
+- **Modo `lazy`** para paginação, ordenação e filtro no servidor.
+- **Estados** `loading` e vazio.
+- **Ref imperativo:** `getProcessedRows`, `getPagedRows`, `clearFilters`, `clearSelection`, `resetSort`, `resetPage` e `goToPage`.
+
+## Quando usar
+
+- **Use para:** listagens de cadastros (CRUD), consultas e relatórios em tela, com até algumas centenas de linhas em memória. Para volume maior, use `lazy` e faça o trabalho no backend.
+- **Não use para:**
+  - edição inline: não há edição de célula no componente;
+  - árvores: veja `SgTreeView` (outro grupo);
+  - escolher itens para um formulário: prefira [[SeedGrid/SeedGrid-components/inputs-selecao/Visao-geral|inputs de seleção]] como `SgPickList`/`SgMultiSelect`.
+
+  Essas recomendações são **Inferência**, a partir das props existentes.
+- **Formulário:** não há integração com react-hook-form. A seleção é controlada por `selection`/`onSelectionChange`. **Confirmado**.
+
+## Composição e dependências
+
+- **Componentes internos:**
+  - `SgGroupBox`: moldura e título (`groupBoxProps`);
+  - `SgButton`: paginação e ações;
+  - `createPortal` do `react-dom`: painel do gerenciador de colunas.
+- **Ícones** do `lucide-react`: setas, chevrons, `GripVertical`, `SlidersHorizontal` e outros.
+- **Persistência:** `useHasSgEnvironmentProvider` e `useSgPersistence` (`src/environment/SgEnvironmentProvider.tsx`). Sem provider, nada é persistido.
+- **Peers:** `react`, `lucide-react`. Diferente dos inputs, o arquivo do SgDatatable não importa `react-hook-form`; mesmo assim, ele continua peer obrigatório do pacote.
+
+**Confirmado**.
+
+## Tema e estilos
+
+- **Variáveis CSS do tema:**
+  - linha selecionada/hover: `--sg-primary-100`;
+  - zebra: `--sg-primary-50`;
+  - texto secundário: `--sg-muted`.
+- **Customização:** `className`, `style`, `tableClassName`, `rowClassName` (string ou função), além de `className`/`headerClassName`/`bodyClassName` por coluna. Flags visuais: `stripedRows`, `showGridlines`, `hoverableRows`.
+- O CSS é injetado na importação do pacote (ver [[SeedGrid/SeedGrid-components/inputs-texto/Visao-geral#Tema e estilos|Tema e estilos]]).
+
+**Confirmado**.
+
+## Internacionalização
+
+Os textos usam as chaves `components.datatable.*` (ver [[SeedGrid/SeedGrid-components/datatable/API#Internacionalização|API]]), resolvidas pelo `SgComponentsI18nProvider`. Sem provider, o locale padrão é `en-US`. **Confirmado**.
+
+## Testes (lidos, **não executados**)
+
+`tests/datatable-dom.test.mjs` cobre:
+- no modo `lazy`, não ordena nem pagina localmente;
+- com `columns` instável (nova identidade a cada render), um render do pai causa um render do corpo e não toca na persistência de colunas.
+
+## Limitações e pontos de atenção
+
+- Não há `aria-sort`, nem navegação de linhas por teclado. **Confirmado**.
+- `rows` só define o valor inicial de linhas por página; não existe prop controlada para isso. **Confirmado**.
+- O `id` serve também de chave de persistência: duas tabelas com o mesmo `id` dentro do mesmo `SgEnvironmentProvider` compartilham o layout de colunas. **Inferência**, pela chave `datatable:<id>:columns`.
+- Para o gerenciador de colunas e a persistência, dê `columnId` ou `field` estáveis. Colunas sem nenhum dos dois usam o índice como chave. **Confirmado**.