@etus/ui 0.1.0 → 0.1.2

package/src/components/data-display/Table/README.md

@@ -1,821 +0,0 @@
-# Table
-
-## Visão Geral
-
-O Table e um conjunto de componentes compound para exibicao de dados tabulares. Construido com elementos HTML semanticos nativos (`<table>`, `<thead>`, `<tbody>`, etc.), fornece uma base acessivel e estilizada para tabelas de dados simples a moderadamente complexas.
-
-### Classificacao Atomica
-
-- **Categoria**: Organisms
-- **Subcategoria**: Data Display / Tables
-
-### Casos de Uso Comuns
-
-- Listagem de usuarios, produtos ou recursos
-- Relatorios financeiros e estatisticos
-- Logs e historicos de atividades
-- Comparacao de planos/precos
-- Exibicao de configuracoes
-- Dados read-only sem interacao complexa
-
-### Relacao com Outros Componentes
-
-- **DataTable**: Versao avancada com sorting, filtering, pagination
-- **VirtualTable**: Versao otimizada para grandes volumes de dados
-- **Card**: Alternativa para exibicao em mobile
-- **List/Item**: Alternativa para dados menos estruturados
-- **Checkbox**: Usado para selecao de linhas
-
-## Design Specs
-
-### Componentes do Sistema
-
-1. **Table**: Container principal com scroll horizontal
-2. **TableHeader**: Cabecalho da tabela (`<thead>`)
-3. **TableBody**: Corpo da tabela (`<tbody>`)
-4. **TableFooter**: Rodape da tabela (`<tfoot>`)
-5. **TableRow**: Linha da tabela (`<tr>`)
-6. **TableHead**: Celula de cabecalho (`<th>`)
-7. **TableCell**: Celula de dados (`<td>`)
-8. **TableCaption**: Legenda da tabela (`<caption>`)
-
-### Variantes
-
-Por ser baseado em elementos nativos, variantes sao aplicadas via classes:
-
-- **Default**: Linhas com bordas sutis, hover highlight
-- **Striped**: Linhas alternadas com background diferente
-- **Bordered**: Bordas em todas as celulas
-- **Compact**: Padding reduzido
-
-### Tamanhos
-
-Controlados via classes de padding nas celulas:
-
-- **Small (sm)**: `p-1` nas celulas
-- **Medium (md)**: `p-2` nas celulas (padrao)
-- **Large (lg)**: `p-4` nas celulas
-
-### Estados
-
-- **Default**: Estilo base da linha
-- **Hover**: `hover:bg-muted/50` na linha
-- **Selected**: `data-[state=selected]:bg-muted`
-- **Striped**: Alternancia via `odd:bg-muted/50` ou `even:bg-muted/50`
-
-### Tokens de Design
-
-#### Cores
-
-- Header Text: `text-foreground`
-- Cell Text: Default
-- Muted Text: `text-muted-foreground`
-- Border: `border-b` (usa `--border`)
-- Hover: `bg-muted/50`
-- Selected: `bg-muted`
-- Footer: `bg-muted/50`
-
-#### Espacamento
-
-- Cell Padding: `p-2`
-- Header Height: `h-10`
-- Caption Margin: `mt-4`
-
-#### Tipografia
-
-- Table Font Size: `text-sm`
-- Header Weight: `font-medium`
-- Caption Size: `text-sm`
-
-#### Bordas
-
-- Row Border: `border-b`
-- Last Row: `last:border-b-0`
-- Footer Border: `border-t`
-
-### Padrão de Tokens com Tailwind v4
-
-O componente Table utiliza tokens de design definidos em `@etus/tokens`. No Tailwind v4, variáveis CSS que contêm cores OKLCH precisam do prefixo `color:` para serem interpretadas corretamente.
-
-#### Tokens Disponíveis
-
-```css
-/* Header */
---table-header-bg
---table-header-fg
---table-header-height
---table-header-padding-x
-
-/* Row */
---table-row-border
---table-row-hover
---table-row-selected
---table-row-striped
-
-/* Cell */
---table-cell-padding-compact-y
---table-cell-padding-default-y
---table-cell-padding-comfortable-y
---table-cell-padding-x
---table-cell-text
-
-/* Footer */
---table-footer-bg
---table-footer-border
-
-/* Caption */
---table-caption-text
---table-caption-fg
---table-caption-margin-top
-```
-
-#### Sintaxe Tailwind v4
-
-```tsx
-// ✅ CORRETO - cores precisam do prefixo color:
-bg-[color:var(--table-header-bg)]
-text-[color:var(--table-header-fg)]
-border-[color:var(--table-row-border)]
-bg-[color:var(--table-row-hover)]
-bg-[color:var(--table-row-selected)]
-
-// ✅ CORRETO - dimensões não precisam de prefixo
-h-[var(--table-header-height)]
-py-[var(--table-cell-padding-default-y)]
-px-[var(--table-cell-padding-x)]
-text-[length:var(--table-cell-text)]
-
-// ❌ INCORRETO - nunca usar hsl() ou omitir color:
-bg-[hsl(var(--table-header-bg))]
-bg-[var(--table-header-bg)]
-```
-
-#### Por que usar `color:`?
-
-O Tailwind v4 usa Lightning CSS que requer type hints para valores ambíguos. Cores OKLCH como `oklch(81.06% 0.2032 150.12)` precisam do prefixo `color:` para serem corretamente interpretadas como cores e não como valores genéricos.
-
-### Consideracoes de Responsividade
-
-- **Scroll Horizontal**: Container com `overflow-x-auto` para telas pequenas
-- **Mobile**: Considerar Card layout ou tabelas empilhadas
-- **Text Wrapping**: `whitespace-nowrap` por padrao, ajustar conforme necessidade
-- **Container Queries**: Use `@container` para layouts adaptativos
-
-## API
-
-### Table
-
-| Prop        | Tipo     | Padrao | Descricao                   |
-| ----------- | -------- | ------ | --------------------------- |
-| `className` | `string` | `""`   | Classes Tailwind adicionais |
-
-### TableHeader
-
-| Prop        | Tipo     | Padrao | Descricao                   |
-| ----------- | -------- | ------ | --------------------------- |
-| `className` | `string` | `""`   | Classes Tailwind adicionais |
-
-### TableBody
-
-| Prop        | Tipo     | Padrao | Descricao                   |
-| ----------- | -------- | ------ | --------------------------- |
-| `className` | `string` | `""`   | Classes Tailwind adicionais |
-
-### TableFooter
-
-| Prop        | Tipo     | Padrao | Descricao                   |
-| ----------- | -------- | ------ | --------------------------- |
-| `className` | `string` | `""`   | Classes Tailwind adicionais |
-
-### TableRow
-
-| Prop         | Tipo         | Padrao | Descricao                   |
-| ------------ | ------------ | ------ | --------------------------- |
-| `className`  | `string`     | `""`   | Classes Tailwind adicionais |
-| `data-state` | `"selected"` | -      | Estado de selecao           |
-
-### TableHead
-
-| Prop        | Tipo             | Padrao | Descricao                     |
-| ----------- | ---------------- | ------ | ----------------------------- |
-| `className` | `string`         | `""`   | Classes Tailwind adicionais   |
-| `scope`     | `"col" \| "row"` | -      | Escopo da celula de cabecalho |
-
-### TableCell
-
-| Prop        | Tipo     | Padrao | Descricao                   |
-| ----------- | -------- | ------ | --------------------------- |
-| `className` | `string` | `""`   | Classes Tailwind adicionais |
-| `colSpan`   | `number` | -      | Numero de colunas a ocupar  |
-| `rowSpan`   | `number` | -      | Numero de linhas a ocupar   |
-
-### TableCaption
-
-| Prop        | Tipo     | Padrao | Descricao                   |
-| ----------- | -------- | ------ | --------------------------- |
-| `className` | `string` | `""`   | Classes Tailwind adicionais |
-
-### Interfaces TypeScript
-
-```typescript
-// Table Props
-interface TableProps extends React.ComponentProps<"table"> {
-  className?: string;
-}
-
-// TableHeader Props
-interface TableHeaderProps extends React.ComponentProps<"thead"> {
-  className?: string;
-}
-
-// TableBody Props
-interface TableBodyProps extends React.ComponentProps<"tbody"> {
-  className?: string;
-}
-
-// TableFooter Props
-interface TableFooterProps extends React.ComponentProps<"tfoot"> {
-  className?: string;
-}
-
-// TableRow Props
-interface TableRowProps extends React.ComponentProps<"tr"> {
-  className?: string;
-}
-
-// TableHead Props
-interface TableHeadProps extends React.ComponentProps<"th"> {
-  className?: string;
-}
-
-// TableCell Props
-interface TableCellProps extends React.ComponentProps<"td"> {
-  className?: string;
-}
-
-// TableCaption Props
-interface TableCaptionProps extends React.ComponentProps<"caption"> {
-  className?: string;
-}
-```
-
-### Comparacao com Referencias
-
-| Feature        | ETUS    | Shadcn  | MUI    | Chakra | Ant Design |
-| -------------- | ------- | ------- | ------ | ------ | ---------- |
-| HTML Semantico | Sim     | Sim     | Sim    | Sim    | Sim        |
-| Sorting        | Nao\*   | Nao\*   | Sim    | Nao\*  | Sim        |
-| Pagination     | Nao\*   | Nao\*   | Sim    | Nao\*  | Sim        |
-| Selection      | Sim\*\* | Sim\*\* | Sim    | Sim    | Sim        |
-| Virtual        | Nao     | Nao     | Sim    | Nao    | Sim        |
-| Responsive     | Scroll  | Scroll  | Varios | Scroll | Scroll     |
-
-\*Use DataTable para essas features
-\*\*Via data-state e Checkbox manual
-
-## Acessibilidade (A11y)
-
-### Atributos ARIA
-
-Tabelas HTML semanticas sao nativamente acessiveis:
-
-- `<table>` e reconhecido como grid de dados
-- `<th scope="col|row">` indica cabecalhos
-- `<caption>` fornece descricao da tabela
-
-Atributos adicionais quando necessario:
-
-- `aria-sort="ascending|descending|none"` para colunas ordenadas
-- `aria-selected` para linhas selecionadas
-- `role="rowgroup"` automatico em thead/tbody/tfoot
-
-### Navegacao por Teclado
-
-| Tecla        | Acao                                          |
-| ------------ | --------------------------------------------- |
-| `Tab`        | Move entre elementos focaveis (links, botoes) |
-| `Arrow Keys` | Navega entre celulas (quando implementado)    |
-| `Enter`      | Ativa link ou botao na celula                 |
-| `Space`      | Toggle checkbox de selecao                    |
-
-### Contraste e Legibilidade
-
-- Texto com contraste minimo de 4.5:1
-- Bordas com contraste minimo de 3:1
-- Estados hover/selected claramente visiveis
-
-### Tecnologias Assistivas
-
-- Screen readers anunciam "table, X columns, Y rows"
-- Cabecalhos sao associados automaticamente as celulas
-- Caption e lido como titulo da tabela
-
-### Conformidade WCAG
-
-- **1.3.1** Info e Relacionamentos: Uso de elementos semanticos
-- **1.3.2** Sequencia Significativa: Ordem logica de leitura
-- **2.4.6** Cabecalhos e Labels: Cabecalhos descritivos
-- **4.1.1** Parsing: HTML valido e bem-formado
-
-## Exemplos
-
-### Uso Basico
-
-```tsx
-import {
-  Table,
-  TableHeader,
-  TableBody,
-  TableRow,
-  TableHead,
-  TableCell,
-  TableCaption,
-} from "@etus/ui";
-
-function BasicTable() {
-  return (
-    <Table>
-      <TableCaption>Lista de usuarios recentes</TableCaption>
-      <TableHeader>
-        <TableRow>
-          <TableHead>Nome</TableHead>
-          <TableHead>Email</TableHead>
-          <TableHead>Status</TableHead>
-        </TableRow>
-      </TableHeader>
-      <TableBody>
-        <TableRow>
-          <TableCell>Joao Silva</TableCell>
-          <TableCell>joao@email.com</TableCell>
-          <TableCell>Ativo</TableCell>
-        </TableRow>
-        <TableRow>
-          <TableCell>Maria Santos</TableCell>
-          <TableCell>maria@email.com</TableCell>
-          <TableCell>Inativo</TableCell>
-        </TableRow>
-      </TableBody>
-    </Table>
-  );
-}
-```
-
-### Com Dados Dinamicos
-
-```tsx
-import {
-  Table,
-  TableHeader,
-  TableBody,
-  TableRow,
-  TableHead,
-  TableCell,
-} from "@etus/ui";
-
-interface User {
-  id: string;
-  name: string;
-  email: string;
-  role: string;
-}
-
-const users: User[] = [
-  { id: "1", name: "Joao Silva", email: "joao@email.com", role: "Admin" },
-  { id: "2", name: "Maria Santos", email: "maria@email.com", role: "User" },
-  { id: "3", name: "Pedro Costa", email: "pedro@email.com", role: "Editor" },
-];
-
-function DynamicTable() {
-  return (
-    <Table>
-      <TableHeader>
-        <TableRow>
-          <TableHead>Nome</TableHead>
-          <TableHead>Email</TableHead>
-          <TableHead>Funcao</TableHead>
-        </TableRow>
-      </TableHeader>
-      <TableBody>
-        {users.map((user) => (
-          <TableRow key={user.id}>
-            <TableCell className="font-medium">{user.name}</TableCell>
-            <TableCell>{user.email}</TableCell>
-            <TableCell>{user.role}</TableCell>
-          </TableRow>
-        ))}
-      </TableBody>
-    </Table>
-  );
-}
-```
-
-### Com Selecao de Linhas
-
-```tsx
-import { useState } from "react";
-import {
-  Table,
-  TableHeader,
-  TableBody,
-  TableRow,
-  TableHead,
-  TableCell,
-} from "@etus/ui";
-import { Checkbox } from "@etus/ui";
-
-function SelectableTable() {
-  const [selected, setSelected] = useState<string[]>([]);
-
-  const toggleRow = (id: string) => {
-    setSelected((prev) =>
-      prev.includes(id) ? prev.filter((i) => i !== id) : [...prev, id],
-    );
-  };
-
-  const toggleAll = () => {
-    setSelected((prev) =>
-      prev.length === users.length ? [] : users.map((u) => u.id),
-    );
-  };
-
-  return (
-    <Table>
-      <TableHeader>
-        <TableRow>
-          <TableHead className="w-12">
-            <Checkbox
-              checked={selected.length === users.length}
-              onCheckedChange={toggleAll}
-            />
-          </TableHead>
-          <TableHead>Nome</TableHead>
-          <TableHead>Email</TableHead>
-        </TableRow>
-      </TableHeader>
-      <TableBody>
-        {users.map((user) => (
-          <TableRow
-            key={user.id}
-            data-state={selected.includes(user.id) ? "selected" : undefined}
-          >
-            <TableCell>
-              <Checkbox
-                checked={selected.includes(user.id)}
-                onCheckedChange={() => toggleRow(user.id)}
-              />
-            </TableCell>
-            <TableCell>{user.name}</TableCell>
-            <TableCell>{user.email}</TableCell>
-          </TableRow>
-        ))}
-      </TableBody>
-    </Table>
-  );
-}
-```
-
-### Com Footer
-
-```tsx
-import {
-  Table,
-  TableHeader,
-  TableBody,
-  TableFooter,
-  TableRow,
-  TableHead,
-  TableCell,
-} from "@etus/ui";
-
-function TableWithFooter() {
-  const items = [
-    { produto: "Produto A", quantidade: 10, preco: 100 },
-    { produto: "Produto B", quantidade: 5, preco: 200 },
-    { produto: "Produto C", quantidade: 20, preco: 50 },
-  ];
-
-  const total = items.reduce(
-    (acc, item) => acc + item.quantidade * item.preco,
-    0,
-  );
-
-  return (
-    <Table>
-      <TableHeader>
-        <TableRow>
-          <TableHead>Produto</TableHead>
-          <TableHead className="text-right">Qtd</TableHead>
-          <TableHead className="text-right">Preco</TableHead>
-          <TableHead className="text-right">Subtotal</TableHead>
-        </TableRow>
-      </TableHeader>
-      <TableBody>
-        {items.map((item) => (
-          <TableRow key={item.produto}>
-            <TableCell>{item.produto}</TableCell>
-            <TableCell className="text-right">{item.quantidade}</TableCell>
-            <TableCell className="text-right">
-              R$ {item.preco.toFixed(2)}
-            </TableCell>
-            <TableCell className="text-right">
-              R$ {(item.quantidade * item.preco).toFixed(2)}
-            </TableCell>
-          </TableRow>
-        ))}
-      </TableBody>
-      <TableFooter>
-        <TableRow>
-          <TableCell colSpan={3}>Total</TableCell>
-          <TableCell className="text-right font-bold">
-            R$ {total.toFixed(2)}
-          </TableCell>
-        </TableRow>
-      </TableFooter>
-    </Table>
-  );
-}
-```
-
-### Striped Rows
-
-```tsx
-import {
-  Table,
-  TableHeader,
-  TableBody,
-  TableRow,
-  TableHead,
-  TableCell,
-} from "@etus/ui";
-
-function StripedTable() {
-  return (
-    <Table>
-      <TableHeader>
-        <TableRow>
-          <TableHead>Nome</TableHead>
-          <TableHead>Valor</TableHead>
-        </TableRow>
-      </TableHeader>
-      <TableBody>
-        {data.map((item, index) => (
-          <TableRow
-            key={item.id}
-            className={index % 2 === 0 ? "bg-muted/50" : ""}
-          >
-            <TableCell>{item.name}</TableCell>
-            <TableCell>{item.value}</TableCell>
-          </TableRow>
-        ))}
-      </TableBody>
-    </Table>
-  );
-}
-```
-
-### Com Acoes
-
-```tsx
-import {
-  Table,
-  TableHeader,
-  TableBody,
-  TableRow,
-  TableHead,
-  TableCell,
-} from "@etus/ui";
-import { Button } from "@etus/ui";
-import { MoreHorizontal, Pencil, Trash2 } from "lucide-react";
-
-function TableWithActions() {
-  return (
-    <Table>
-      <TableHeader>
-        <TableRow>
-          <TableHead>Nome</TableHead>
-          <TableHead>Status</TableHead>
-          <TableHead className="text-right">Acoes</TableHead>
-        </TableRow>
-      </TableHeader>
-      <TableBody>
-        {items.map((item) => (
-          <TableRow key={item.id}>
-            <TableCell>{item.name}</TableCell>
-            <TableCell>{item.status}</TableCell>
-            <TableCell className="text-right">
-              <div className="flex justify-end gap-2">
-                <Button variant="ghost" size="icon">
-                  <Pencil className="size-4" />
-                </Button>
-                <Button variant="ghost" size="icon">
-                  <Trash2 className="size-4" />
-                </Button>
-              </div>
-            </TableCell>
-          </TableRow>
-        ))}
-      </TableBody>
-    </Table>
-  );
-}
-```
-
-### Compact Table
-
-```tsx
-import {
-  Table,
-  TableHeader,
-  TableBody,
-  TableRow,
-  TableHead,
-  TableCell,
-} from "@etus/ui";
-
-function CompactTable() {
-  return (
-    <Table>
-      <TableHeader>
-        <TableRow>
-          <TableHead className="h-8 p-1 text-xs">ID</TableHead>
-          <TableHead className="h-8 p-1 text-xs">Nome</TableHead>
-          <TableHead className="h-8 p-1 text-xs">Valor</TableHead>
-        </TableRow>
-      </TableHeader>
-      <TableBody>
-        {data.map((item) => (
-          <TableRow key={item.id}>
-            <TableCell className="p-1 text-xs">{item.id}</TableCell>
-            <TableCell className="p-1 text-xs">{item.name}</TableCell>
-            <TableCell className="p-1 text-xs">{item.value}</TableCell>
-          </TableRow>
-        ))}
-      </TableBody>
-    </Table>
-  );
-}
-```
-
-## Testes
-
-### Estrategias de Teste
-
-#### Testes Unitarios
-
-- Renderizacao de todos os componentes compound
-- Classes aplicadas corretamente
-- Props passadas para elementos nativos
-
-#### Testes de Integracao
-
-- Tabela completa com header, body, footer
-- Selecao de linhas
-- Acoes em celulas
-
-#### Testes de Acessibilidade
-
-- Estrutura semantica correta
-- Associacao header-cell
-- Caption presente
-
-### Exemplos de Codigo
-
-```typescript
-import { describe, it, expect } from 'vitest'
-import { render, screen } from '@testing-library/react'
-import {
-  Table,
-  TableHeader,
-  TableBody,
-  TableRow,
-  TableHead,
-  TableCell,
-  TableCaption
-} from './Table'
-
-describe('Table', () => {
-  it('renders semantic table structure', () => {
-    render(
-      <Table>
-        <TableCaption>Test Caption</TableCaption>
-        <TableHeader>
-          <TableRow>
-            <TableHead>Header</TableHead>
-          </TableRow>
-        </TableHeader>
-        <TableBody>
-          <TableRow>
-            <TableCell>Cell</TableCell>
-          </TableRow>
-        </TableBody>
-      </Table>
-    )
-
-    expect(screen.getByRole('table')).toBeInTheDocument()
-    expect(screen.getByText('Test Caption')).toBeInTheDocument()
-    expect(screen.getByRole('columnheader')).toHaveTextContent('Header')
-    expect(screen.getByRole('cell')).toHaveTextContent('Cell')
-  })
-
-  it('applies hover styles to rows', () => {
-    render(
-      <Table>
-        <TableBody>
-          <TableRow>
-            <TableCell>Cell</TableCell>
-          </TableRow>
-        </TableBody>
-      </Table>
-    )
-
-    const row = screen.getByRole('row')
-    expect(row.className).toContain('hover:bg-muted/50')
-  })
-
-  it('supports selected state', () => {
-    render(
-      <Table>
-        <TableBody>
-          <TableRow data-state="selected">
-            <TableCell>Selected Cell</TableCell>
-          </TableRow>
-        </TableBody>
-      </Table>
-    )
-
-    const row = screen.getByRole('row')
-    expect(row).toHaveAttribute('data-state', 'selected')
-  })
-
-  it('renders with data-slot attributes', () => {
-    const { container } = render(
-      <Table>
-        <TableHeader>
-          <TableRow>
-            <TableHead>H</TableHead>
-          </TableRow>
-        </TableHeader>
-        <TableBody>
-          <TableRow>
-            <TableCell>C</TableCell>
-          </TableRow>
-        </TableBody>
-      </Table>
-    )
-
-    expect(container.querySelector('[data-slot="table"]')).toBeInTheDocument()
-    expect(container.querySelector('[data-slot="table-header"]')).toBeInTheDocument()
-    expect(container.querySelector('[data-slot="table-body"]')).toBeInTheDocument()
-  })
-})
-```
-
-### Testes de Acessibilidade
-
-```typescript
-import { axe, toHaveNoViolations } from 'jest-axe'
-
-expect.extend(toHaveNoViolations)
-
-describe('Table A11y', () => {
-  it('has no accessibility violations', async () => {
-    const { container } = render(
-      <Table>
-        <TableCaption>Users</TableCaption>
-        <TableHeader>
-          <TableRow>
-            <TableHead scope="col">Name</TableHead>
-            <TableHead scope="col">Email</TableHead>
-          </TableRow>
-        </TableHeader>
-        <TableBody>
-          <TableRow>
-            <TableCell>John</TableCell>
-            <TableCell>john@email.com</TableCell>
-          </TableRow>
-        </TableBody>
-      </Table>
-    )
-
-    const results = await axe(container)
-    expect(results).toHaveNoViolations()
-  })
-})
-```
-
----
-
-## Roadmap / Features Futuras
-
-- Usa elementos HTML nativos para maxima acessibilidade
-- Container com `overflow-x-auto` para scroll horizontal
-- `data-slot` para identificacao de componentes
-- Transicao suave no hover das linhas
-- Compativel com Checkbox para selecao
-
-## Referências
-
-- [MDN HTML Table](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/table)
-- [Shadcn UI Table](https://ui.shadcn.com/docs/components/table)
-- [WAI-ARIA Table Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/table/)
-- [Inclusive Components: Data Tables](https://inclusive-components.design/data-tables/)