@etus/ui 0.1.0

package/src/components/data-display/DataTable/DataTable.types.ts

@@ -0,0 +1,190 @@
+import type {
+  Column,
+  ColumnDef,
+  ColumnFiltersState,
+  ExpandedState,
+  OnChangeFn,
+  PaginationState,
+  Row,
+  RowSelectionState,
+  SortingState,
+  Table as TanStackTable,
+  VisibilityState,
+} from "@tanstack/react-table"
+import type { ReactNode } from "react"
+
+/**
+ * DataTable component props
+ * Advanced table with sorting, filtering, pagination, selection
+ * Built on TanStack Table (React Table v8)
+ */
+export interface DataTableProps<TData> {
+  /** Additional CSS classes */
+  className?: string
+
+  /** Column filters state (controlled) */
+  columnFilters?: ColumnFiltersState
+
+  /** Column definitions (required) */
+  columns: ColumnDef<TData>[]
+
+  /** Column visibility state (controlled) */
+  columnVisibility?: VisibilityState
+
+  /** Array of data to display (required) */
+  data: TData[]
+
+  /** Content to display when data is empty */
+  emptyState?: ReactNode
+
+  /** Enable column filters */
+  enableColumnFilters?: boolean
+
+  /** Enable column visibility toggle */
+  enableColumnVisibility?: boolean
+
+  /** Enable global filtering */
+  enableFiltering?: boolean
+
+  /** Enable pagination controls */
+  enablePagination?: boolean
+
+  /** Enable row selection with checkboxes */
+  enableRowSelection?: boolean
+
+  /** Enable search input */
+  enableSearch?: boolean
+
+  /** Enable sorting on columns */
+  enableSorting?: boolean
+
+  /** Expanded state (controlled) */
+  expanded?: ExpandedState
+
+  /** Function to determine if row can expand */
+  getRowCanExpand?: (row: Row<TData>) => boolean
+
+  /** Global filter value (controlled) */
+  globalFilter?: string
+
+  /** Initial sorting state */
+  initialSorting?: SortingState
+
+  /** Show loading state */
+  loading?: boolean
+
+  /** Loading component to render */
+  loadingComponent?: ReactNode
+
+  /** Enable manual (server-side) filtering */
+  manualFiltering?: boolean
+
+  /** Enable manual (server-side) pagination */
+  manualPagination?: boolean
+
+  /** Enable manual (server-side) sorting */
+  manualSorting?: boolean
+
+  /** Callback for column filters change */
+  onColumnFiltersChange?: OnChangeFn<ColumnFiltersState>
+
+  /** Callback for column visibility change */
+  onColumnVisibilityChange?: OnChangeFn<VisibilityState>
+
+  /** Callback for expanded state change */
+  onExpandedChange?: OnChangeFn<ExpandedState>
+
+  /** Callback for global filter change */
+  onGlobalFilterChange?: (value: string) => void
+
+  /** Callback for pagination change */
+  onPaginationChange?: OnChangeFn<PaginationState>
+
+  /** Callback when row is clicked */
+  onRowClick?: (row: TData) => void
+
+  /** Callback for row selection change */
+  onRowSelectionChange?: OnChangeFn<RowSelectionState>
+
+  /** Callback when selection changes */
+  onSelectionChange?: (rows: TData[]) => void
+
+  /** Callback for sorting change */
+  onSortingChange?: OnChangeFn<SortingState>
+
+  /** Total page count (for server-side pagination) */
+  pageCount?: number
+
+  /** Number of items per page */
+  pageSize?: number
+
+  /** Options for page size selector */
+  pageSizeOptions?: number[]
+
+  /** Pagination state (controlled) */
+  pagination?: PaginationState
+
+  /** Render function for column filter */
+  renderColumnFilter?: (props: {
+    column: Column<TData>
+    table: TanStackTable<TData>
+  }) => ReactNode
+
+  /** Render function for expanded sub-component */
+  renderSubComponent?: (props: { row: Row<TData> }) => ReactNode
+
+  /** Custom row className */
+  rowClassName?: (row: Row<TData>) => string
+
+  /** Row selection state (controlled) */
+  rowSelection?: RowSelectionState
+
+  /** Search input placeholder */
+  searchPlaceholder?: string
+
+  /** Show footer row */
+  showFooter?: boolean
+
+  /** Sorting state (controlled) */
+  sorting?: SortingState
+}
+
+/**
+ * DataTable pagination info
+ */
+export interface DataTablePaginationInfo {
+  canNextPage: boolean
+  canPreviousPage: boolean
+  pageCount: number
+  pageIndex: number
+  pageSize: number
+  totalItems: number
+}
+
+/**
+ * DataTable column filter variant
+ */
+export type DataTableFilterVariant = "range" | "select" | "text"
+
+/**
+ * Column filter meta information
+ */
+export interface DataTableColumnMeta {
+  filterOptions?: string[]
+  filterVariant?: DataTableFilterVariant
+}
+
+/**
+ * Re-export useful types from TanStack Table
+ */
+export type {
+  Column,
+  ColumnDef,
+  ColumnFiltersState,
+  ExpandedState,
+  PaginationState,
+  Row,
+  RowSelectionState,
+  SortingState,
+  VisibilityState,
+} from "@tanstack/react-table"

package/src/components/data-display/DataTable/DataTable.variants.ts

@@ -0,0 +1,79 @@
+// DataTable/DataTable.variants.ts
+import { cva, type VariantProps } from "class-variance-authority"
+
+/**
+ * DataTable container style variants using CVA
+ *
+ * @see https://cva.style/docs
+ */
+export const dataTableVariants = cva(
+  // Base styles (always applied)
+  "space-y-4",
+  {
+    variants: {
+      density: {
+        compact: "[&_td]:py-[var(--datatable-row-padding-y-compact)] [&_th]:py-[var(--datatable-header-padding-y-compact)]",
+        default: "[&_td]:py-[var(--datatable-row-padding-y-default)] [&_th]:py-[var(--datatable-header-padding-y-default)]",
+        comfortable: "[&_td]:py-[var(--datatable-row-padding-y-comfortable)] [&_th]:py-[var(--datatable-header-padding-y-comfortable)]",
+      },
+    },
+    defaultVariants: {
+      density: "default",
+    },
+  }
+)
+
+/**
+ * DataTable row style variants
+ */
+export const dataTableRowVariants = cva(
+  // Base styles (always applied)
+  "transition-colors",
+  {
+    variants: {
+      state: {
+        default: "",
+        selected: "bg-[color:var(--datatable-row-bg-selected)]",
+        highlighted: "bg-[color:var(--datatable-row-bg-highlighted)]/5",
+      },
+      interactive: {
+        true: "cursor-pointer hover:bg-[color:var(--datatable-row-bg-hover)]/50",
+        false: "",
+      },
+    },
+    defaultVariants: {
+      state: "default",
+      interactive: false,
+    },
+  }
+)
+
+/**
+ * DataTable header cell style variants
+ */
+export const dataTableHeaderVariants = cva(
+  // Base styles (always applied)
+  "text-muted-foreground",
+  {
+    variants: {
+      sortable: {
+        true: "cursor-pointer select-none hover:text-foreground",
+        false: "",
+      },
+      sorted: {
+        asc: "text-foreground",
+        desc: "text-foreground",
+        none: "",
+      },
+    },
+    defaultVariants: {
+      sortable: false,
+      sorted: "none",
+    },
+  }
+)
+
+// Export variant prop types
+export type DataTableVariantProps = VariantProps<typeof dataTableVariants>
+export type DataTableRowVariantProps = VariantProps<typeof dataTableRowVariants>
+export type DataTableHeaderVariantProps = VariantProps<typeof dataTableHeaderVariants>

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

@@ -0,0 +1,447 @@
+# DataTable
+
+## Visão Geral
+
+O DataTable e uma versao avancada do Table com funcionalidades interativas como ordenacao, filtragem, paginacao, selecao de linhas e acoes em lote. Construido sobre TanStack Table (React Table v8), oferece uma API poderosa e performatica para manipulacao de dados tabulares.
+
+### Classificacao Atomica
+
+- **Categoria**: Organisms
+- **Subcategoria**: Data Display / Tables
+
+### Casos de Uso Comuns
+
+- Listagens com busca e filtros
+- Gerenciamento de usuarios/recursos
+- Logs com ordenacao
+- Inventario e catalogo
+- Relatorios interativos
+- Admin panels
+
+### Relacao com Outros Componentes
+
+- **Table**: Componentes base de renderizacao
+- **VirtualTable**: Para grandes volumes de dados
+- **Pagination**: Controle de paginas
+- **Input**: Campo de busca
+- **Checkbox**: Selecao de linhas
+- **DropdownMenu**: Acoes por linha
+
+## Design Specs
+
+### Features
+
+| Feature           | Descricao                       |
+| ----------------- | ------------------------------- |
+| Sorting           | Ordenacao por coluna (asc/desc) |
+| Filtering         | Filtros globais e por coluna    |
+| Pagination        | Navegacao entre paginas         |
+| Selection         | Selecao de linhas               |
+| Column Visibility | Mostrar/ocultar colunas         |
+| Column Resize     | Redimensionar colunas           |
+| Row Expansion     | Linhas expansiveis              |
+
+### Estados
+
+- **Default**: Tabela com dados
+- **Loading**: Skeleton ou spinner
+- **Empty**: Mensagem sem resultados
+- **Filtered**: Indicador de filtros ativos
+- **Selected**: Linhas selecionadas
+
+### Tokens de Design
+
+Herda tokens do Table component, com tokens adicionais específicos:
+
+### Padrão de Tokens com Tailwind v4
+
+O componente DataTable 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
+/* Row */
+--datatable-row-padding-y-compact
+--datatable-row-padding-y-default
+--datatable-row-padding-y-comfortable
+--datatable-row-bg-selected
+--datatable-row-bg-highlighted
+--datatable-row-bg-hover
+
+/* Header */
+--datatable-header-padding-y-compact
+--datatable-header-padding-y-default
+--datatable-header-padding-y-comfortable
+
+/* Pagination */
+--datatable-pagination-padding-x
+--datatable-pagination-info-color
+--datatable-pagination-info-size
+
+/* Toolbar */
+--datatable-toolbar-gap
+--datatable-toolbar-search-icon-color
+--datatable-toolbar-search-icon-size
+--datatable-toolbar-search-icon-top
+--datatable-toolbar-search-icon-left
+--datatable-toolbar-search-input-padding-left
+```
+
+#### Sintaxe Tailwind v4
+
+```tsx
+// ✅ CORRETO - cores precisam do prefixo color:
+bg-[color:var(--datatable-row-bg-selected)]
+bg-[color:var(--datatable-row-bg-hover)]
+bg-[color:var(--datatable-row-bg-highlighted)]
+text-[color:var(--datatable-pagination-info-color)]
+text-[color:var(--datatable-toolbar-search-icon-color)]
+
+// ✅ CORRETO - dimensões não precisam de prefixo
+py-[var(--datatable-row-padding-y-default)]
+py-[var(--datatable-header-padding-y-default)]
+px-[var(--datatable-pagination-padding-x)]
+gap-[var(--datatable-toolbar-gap)]
+text-[length:var(--datatable-pagination-info-size)]
+
+// ❌ INCORRETO - nunca usar hsl() ou omitir color:
+bg-[hsl(var(--datatable-row-bg-selected))]
+bg-[var(--datatable-row-bg-selected)]
+```
+
+#### 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.
+
+## API
+
+### Props
+
+| Prop                     | Tipo                      | Padrao       | Descricao                    |
+| ------------------------ | ------------------------- | ------------ | ---------------------------- |
+| `data`                   | `TData[]`                 | -            | Array de dados (obrigatorio) |
+| `columns`                | `ColumnDef<TData>[]`      | -            | Definicao de colunas         |
+| `pageSize`               | `number`                  | `10`         | Itens por pagina             |
+| `pageSizeOptions`        | `number[]`                | `[10,20,50]` | Opcoes de tamanho            |
+| `enableSorting`          | `boolean`                 | `true`       | Habilitar ordenacao          |
+| `enableFiltering`        | `boolean`                 | `true`       | Habilitar filtros            |
+| `enablePagination`       | `boolean`                 | `true`       | Habilitar paginacao          |
+| `enableRowSelection`     | `boolean`                 | `false`      | Habilitar selecao            |
+| `enableColumnVisibility` | `boolean`                 | `false`      | Controle de colunas          |
+| `onRowClick`             | `(row: TData) => void`    | -            | Callback click na linha      |
+| `onSelectionChange`      | `(rows: TData[]) => void` | -            | Callback selecao             |
+| `loading`                | `boolean`                 | `false`      | Estado de loading            |
+| `emptyState`             | `ReactNode`               | -            | Conteudo quando vazio        |
+| `className`              | `string`                  | `""`         | Classes adicionais           |
+
+### Column Definition
+
+```typescript
+interface ColumnDef<TData> {
+  id: string;
+  accessorKey?: keyof TData;
+  accessorFn?: (row: TData) => unknown;
+  header: string | ((props: HeaderContext) => ReactNode);
+  cell?: (props: CellContext<TData>) => ReactNode;
+  footer?: string | ((props: FooterContext) => ReactNode);
+  enableSorting?: boolean;
+  enableFiltering?: boolean;
+  sortingFn?: SortingFn<TData>;
+  filterFn?: FilterFn<TData>;
+  size?: number;
+  minSize?: number;
+  maxSize?: number;
+  meta?: Record<string, unknown>;
+}
+```
+
+## Exemplos
+
+### Uso Básico
+
+```tsx
+import { DataTable } from "@etus/ui";
+import { ColumnDef } from "@tanstack/react-table";
+
+interface User {
+  id: string;
+  name: string;
+  email: string;
+  role: string;
+  status: "active" | "inactive";
+}
+
+const columns: ColumnDef<User>[] = [
+  {
+    accessorKey: "name",
+    header: "Name",
+    cell: ({ row }) => (
+      <div className="font-medium">{row.getValue("name")}</div>
+    ),
+  },
+  {
+    accessorKey: "email",
+    header: "Email",
+  },
+  {
+    accessorKey: "role",
+    header: "Role",
+    cell: ({ row }) => <Badge>{row.getValue("role")}</Badge>,
+  },
+  {
+    accessorKey: "status",
+    header: "Status",
+    cell: ({ row }) => (
+      <Badge
+        variant={row.getValue("status") === "active" ? "default" : "secondary"}
+      >
+        {row.getValue("status")}
+      </Badge>
+    ),
+  },
+];
+
+function UserTable() {
+  return (
+    <DataTable
+      data={users}
+      columns={columns}
+      enableRowSelection
+      enableFiltering
+    />
+  );
+}
+```
+
+### Com Acoes por Linha
+
+```tsx
+import {
+  DropdownMenu,
+  DropdownMenuTrigger,
+  DropdownMenuContent,
+  DropdownMenuItem,
+} from "@etus/ui";
+import { MoreHorizontal, Pencil, Trash } from "lucide-react";
+
+const columnsWithActions: ColumnDef<User>[] = [
+  // ... other columns
+  {
+    id: "actions",
+    cell: ({ row }) => (
+      <DropdownMenu>
+        <DropdownMenuTrigger asChild>
+          <Button variant="ghost" size="icon">
+            <MoreHorizontal className="size-4" />
+          </Button>
+        </DropdownMenuTrigger>
+        <DropdownMenuContent align="end">
+          <DropdownMenuItem onClick={() => handleEdit(row.original)}>
+            <Pencil className="mr-2 size-4" />
+            Edit
+          </DropdownMenuItem>
+          <DropdownMenuItem
+            onClick={() => handleDelete(row.original)}
+            className="text-destructive"
+          >
+            <Trash className="mr-2 size-4" />
+            Delete
+          </DropdownMenuItem>
+        </DropdownMenuContent>
+      </DropdownMenu>
+    ),
+  },
+];
+```
+
+### Com Toolbar
+
+```tsx
+import { Input } from "@etus/ui";
+import { Search } from "lucide-react";
+
+function DataTableWithToolbar() {
+  const [globalFilter, setGlobalFilter] = useState("");
+
+  return (
+    <div className="space-y-4">
+      <div className="flex items-center justify-between">
+        <div className="relative">
+          <Search className="absolute left-2.5 top-2.5 size-4 text-muted-foreground" />
+          <Input
+            placeholder="Search..."
+            value={globalFilter}
+            onChange={(e) => setGlobalFilter(e.target.value)}
+            className="pl-8 w-64"
+          />
+        </div>
+        <div className="flex gap-2">
+          <ColumnVisibilityDropdown table={table} />
+          <Button>Add New</Button>
+        </div>
+      </div>
+      <DataTable
+        data={data}
+        columns={columns}
+        globalFilter={globalFilter}
+        onGlobalFilterChange={setGlobalFilter}
+      />
+    </div>
+  );
+}
+```
+
+### Selecao com Acoes em Lote
+
+```tsx
+function DataTableWithBulkActions() {
+  const [selectedRows, setSelectedRows] = useState<User[]>([]);
+
+  return (
+    <div className="space-y-4">
+      {selectedRows.length > 0 && (
+        <div className="flex items-center gap-2 p-2 bg-muted rounded-md">
+          <span className="text-sm text-muted-foreground">
+            {selectedRows.length} selected
+          </span>
+          <Button variant="outline" size="sm" onClick={handleBulkDelete}>
+            Delete Selected
+          </Button>
+          <Button variant="outline" size="sm" onClick={handleBulkExport}>
+            Export Selected
+          </Button>
+        </div>
+      )}
+      <DataTable
+        data={data}
+        columns={columns}
+        enableRowSelection
+        onSelectionChange={setSelectedRows}
+      />
+    </div>
+  );
+}
+```
+
+### Server-Side
+
+```tsx
+function ServerSideDataTable() {
+  const [pagination, setPagination] = useState({ pageIndex: 0, pageSize: 10 });
+  const [sorting, setSorting] = useState<SortingState>([]);
+
+  const { data, isLoading, totalCount } = useQuery({
+    queryKey: ["users", pagination, sorting],
+    queryFn: () => fetchUsers({ pagination, sorting }),
+  });
+
+  return (
+    <DataTable
+      data={data ?? []}
+      columns={columns}
+      pageCount={Math.ceil(totalCount / pagination.pageSize)}
+      pagination={pagination}
+      onPaginationChange={setPagination}
+      sorting={sorting}
+      onSortingChange={setSorting}
+      loading={isLoading}
+      manualPagination
+      manualSorting
+    />
+  );
+}
+```
+
+## Acessibilidade (A11y)
+
+### Recomendacoes
+
+- Anunciar ordenacao atual
+- Labels para controles de paginacao
+- Checkboxes com labels
+- Acoes com foco adequado
+
+### ARIA
+
+- `aria-sort` nas colunas ordenadas
+- `aria-selected` nas linhas selecionadas
+- `role="grid"` para tabelas interativas
+
+### Navegacao por Teclado
+
+- `Tab`: Navega entre elementos interativos
+- `Space`: Seleciona linha/checkbox
+- `Enter`: Ativa acao
+
+## Testes
+
+```typescript
+import { render, screen, within } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import { DataTable } from './DataTable'
+
+describe('DataTable', () => {
+  const data = [
+    { id: '1', name: 'John', email: 'john@test.com' },
+    { id: '2', name: 'Jane', email: 'jane@test.com' },
+  ]
+
+  const columns = [
+    { accessorKey: 'name', header: 'Name' },
+    { accessorKey: 'email', header: 'Email' },
+  ]
+
+  it('renders data correctly', () => {
+    render(<DataTable data={data} columns={columns} />)
+
+    expect(screen.getByText('John')).toBeInTheDocument()
+    expect(screen.getByText('Jane')).toBeInTheDocument()
+  })
+
+  it('sorts on header click', async () => {
+    const user = userEvent.setup()
+    render(<DataTable data={data} columns={columns} enableSorting />)
+
+    await user.click(screen.getByText('Name'))
+
+    const rows = screen.getAllByRole('row')
+    expect(within(rows[1]).getByText('Jane')).toBeInTheDocument()
+  })
+
+  it('filters data', async () => {
+    const user = userEvent.setup()
+    render(<DataTable data={data} columns={columns} enableFiltering />)
+
+    const search = screen.getByPlaceholderText('Search...')
+    await user.type(search, 'John')
+
+    expect(screen.getByText('John')).toBeInTheDocument()
+    expect(screen.queryByText('Jane')).not.toBeInTheDocument()
+  })
+
+  it('selects rows', async () => {
+    const onSelectionChange = vi.fn()
+    const user = userEvent.setup()
+
+    render(
+      <DataTable
+        data={data}
+        columns={columns}
+        enableRowSelection
+        onSelectionChange={onSelectionChange}
+      />
+    )
+
+    const checkbox = screen.getAllByRole('checkbox')[1]
+    await user.click(checkbox)
+
+    expect(onSelectionChange).toHaveBeenCalledWith([data[0]])
+  })
+})
+```
+
+## Referências
+
+- [TanStack Table](https://tanstack.com/table/latest)
+- [Shadcn UI Data Table](https://ui.shadcn.com/docs/components/data-table)
+- [MUI DataGrid](https://mui.com/x/react-data-grid/)

package/src/components/data-display/DataTable/index.ts

@@ -0,0 +1,2 @@
+export * from './DataTable'
+export type * from './DataTable.types'