@etus/ui 0.1.0

package/src/components/layout/Grid/README.md

@@ -0,0 +1,762 @@
+# Grid
+
+## Visao Geral
+
+O **Grid** e um componente de layout que fornece uma API declarativa para CSS Grid. Como elemento de layout, e usado para organizar conteudo em grades bidimensionais com colunas, linhas, espacamento e alinhamento.
+
+### Casos de Uso
+
+- Layouts de pagina com multiplas colunas responsivas
+- Galerias de imagens e cards
+- Dashboards com widgets organizados em grid
+- Formularios com campos alinhados em grid
+- Layouts de conteudo complexos com areas definidas
+
+### Classificacao
+
+**Categoria:** Layout
+**Dependencias:** class-variance-authority, tailwind-merge
+
+### Relacao com Outros Componentes
+
+| Componente | Relacao |
+|------------|---------|
+| **Flex** | Alternativa para layouts unidimensionais |
+| **Stack** | Simplificacao do Flex para stacks verticais/horizontais |
+| **Card** | Frequentemente usado como item de Grid |
+| **Container** | Envolve grids para limitar largura maxima |
+| **Section** | Organiza grids em secoes semanticas |
+
+---
+
+## Design Specs
+
+### Colunas (`cols`)
+
+| Valor | Classe | Uso |
+|-------|--------|-----|
+| `1` | `grid-cols-1` | Layout single-column, mobile-first |
+| `2` | `grid-cols-2` | Layouts simples lado a lado |
+| `3` | `grid-cols-3` | Cards de features, galerias |
+| `4` | `grid-cols-4` | Dashboards, grids de midias |
+| `6` | `grid-cols-6` | Layouts complexos |
+| `12` | `grid-cols-12` | Sistema de grid completo |
+| `none` | `grid-cols-none` | Sem colunas definidas (padrao) |
+
+### Linhas (`rows`)
+
+| Valor | Classe | Uso |
+|-------|--------|-----|
+| `1` | `grid-rows-1` | Layouts horizontais |
+| `2` | `grid-rows-2` | Grid fixo 2 linhas |
+| `3` | `grid-rows-3` | Grid fixo 3 linhas |
+| `4` | `grid-rows-4` | Grid fixo 4 linhas |
+| `6` | `grid-rows-6` | Grid fixo 6 linhas |
+| `none` | `grid-rows-none` | Sem linhas definidas |
+
+### Espacamento (`gap`, `gapX`, `gapY`)
+
+| Valor | Classe | Pixels |
+|-------|--------|--------|
+| `0` | `gap-0` | 0px |
+| `1` | `gap-1` | 4px (0.25rem) |
+| `2` | `gap-2` | 8px (0.5rem) |
+| `4` | `gap-4` | 16px (1rem) - **Padrao** |
+| `6` | `gap-6` | 24px (1.5rem) |
+| `8` | `gap-8` | 32px (2rem) |
+
+### Alinhamento de Items (`items`)
+
+| Valor | Classe | Comportamento |
+|-------|--------|---------------|
+| `start` | `items-start` | Alinha ao topo |
+| `center` | `items-center` | Centraliza verticalmente |
+| `end` | `items-end` | Alinha ao fundo |
+| `stretch` | `items-stretch` | Estica para preencher |
+
+### Justificacao de Items (`justify`)
+
+| Valor | Classe | Comportamento |
+|-------|--------|---------------|
+| `start` | `justify-items-start` | Alinha a esquerda |
+| `center` | `justify-items-center` | Centraliza horizontalmente |
+| `end` | `justify-items-end` | Alinha a direita |
+| `stretch` | `justify-items-stretch` | Estica para preencher |
+
+### Direcao do Fluxo (`flow`)
+
+| Valor | Classe | Comportamento |
+|-------|--------|---------------|
+| `row` | `grid-flow-row` | Preenche por linhas |
+| `col` | `grid-flow-col` | Preenche por colunas |
+| `dense` | `grid-flow-dense` | Preenche espacos vazios |
+| `row-dense` | `grid-flow-row-dense` | Linhas com preenchimento denso |
+| `col-dense` | `grid-flow-col-dense` | Colunas com preenchimento denso |
+
+### data-slot
+
+```html
+<div data-slot="grid">
+  <!-- grid items -->
+</div>
+```
+
+---
+
+## API
+
+### Props
+
+| Prop | Tipo | Padrao | Descricao |
+|------|------|--------|-----------|
+| `cols` | `1 \| 2 \| 3 \| 4 \| 6 \| 12 \| "none"` | `"none"` | Numero de colunas |
+| `rows` | `1 \| 2 \| 3 \| 4 \| 6 \| "none"` | - | Numero de linhas |
+| `gap` | `0 \| 1 \| 2 \| 4 \| 6 \| 8` | `4` | Espacamento entre items |
+| `gapX` | `0 \| 1 \| 2 \| 4 \| 6 \| 8` | - | Espacamento horizontal |
+| `gapY` | `0 \| 1 \| 2 \| 4 \| 6 \| 8` | - | Espacamento vertical |
+| `items` | `"start" \| "center" \| "end" \| "stretch"` | - | Alinhamento vertical |
+| `justify` | `"start" \| "center" \| "end" \| "stretch"` | - | Alinhamento horizontal |
+| `flow` | `"row" \| "col" \| "dense" \| "row-dense" \| "col-dense"` | - | Direcao do fluxo |
+| `as` | `"div" \| "section" \| "article" \| "main" \| "ul" \| "ol"` | `"div"` | Elemento HTML |
+| `className` | `string` | - | Classes CSS adicionais |
+| `children` | `ReactNode` | - | Conteudo |
+| `ref` | `Ref<HTMLDivElement>` | - | Referencia ao elemento DOM |
+
+> Herda todas as props de `React.ComponentProps<"div">`
+
+### Callbacks
+
+O Grid e um componente de layout sem callbacks especificos. Eventos padrao do DOM podem ser passados diretamente.
+
+### TypeScript
+
+```typescript
+import { type VariantProps } from "class-variance-authority"
+import type { ComponentProps } from "react"
+
+// Variants exportadas
+const gridVariants = cva("grid", {
+  variants: {
+    cols: { 1: "grid-cols-1", 2: "grid-cols-2", 3: "grid-cols-3", 4: "grid-cols-4", 6: "grid-cols-6", 12: "grid-cols-12", none: "grid-cols-none" },
+    rows: { 1: "grid-rows-1", 2: "grid-rows-2", 3: "grid-rows-3", 4: "grid-rows-4", 6: "grid-rows-6", none: "grid-rows-none" },
+    gap: { 0: "gap-0", 1: "gap-1", 2: "gap-2", 4: "gap-4", 6: "gap-6", 8: "gap-8" },
+    gapX: { 0: "gap-x-0", 1: "gap-x-1", 2: "gap-x-2", 4: "gap-x-4", 6: "gap-x-6", 8: "gap-x-8" },
+    gapY: { 0: "gap-y-0", 1: "gap-y-1", 2: "gap-y-2", 4: "gap-y-4", 6: "gap-y-6", 8: "gap-y-8" },
+    items: { start: "items-start", center: "items-center", end: "items-end", stretch: "items-stretch" },
+    justify: { start: "justify-items-start", center: "justify-items-center", end: "justify-items-end", stretch: "justify-items-stretch" },
+    flow: { row: "grid-flow-row", col: "grid-flow-col", dense: "grid-flow-dense", "row-dense": "grid-flow-row-dense", "col-dense": "grid-flow-col-dense" },
+  },
+  defaultVariants: {
+    cols: "none",
+    gap: 4,
+  },
+})
+
+// Tipos de elemento permitidos
+type GridElement = "article" | "div" | "main" | "ol" | "section" | "ul"
+
+// Props do componente
+interface GridProps extends ComponentProps<"div">, VariantProps<typeof gridVariants> {
+  as?: GridElement
+}
+
+// Tipos derivados
+type GridCols = NonNullable<VariantProps<typeof gridVariants>["cols"]>
+type GridRows = NonNullable<VariantProps<typeof gridVariants>["rows"]>
+type GridGap = NonNullable<VariantProps<typeof gridVariants>["gap"]>
+type GridAlign = NonNullable<VariantProps<typeof gridVariants>["items"]>
+type GridFlow = NonNullable<VariantProps<typeof gridVariants>["flow"]>
+```
+
+### Comparativo com Design Systems de Referencia
+
+#### Matriz de Features (12 Design Systems)
+
+| Feature | ETUS | Chakra | MUI | Mantine | AntD | NextUI | Tailwind | Bootstrap | Foundation | Fluent | Carbon | Blueprint |
+|---------|:----:|:------:|:---:|:-------:|:----:|:------:|:--------:|:---------:|:----------:|:------:|:------:|:---------:|
+| Cols predefinidos | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
+| Rows predefinidos | ✓ | - | - | - | - | - | ✓ | - | - | - | - | - |
+| Gap uniforme | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | - |
+| Gap X/Y separados | ✓ | ✓ | - | ✓ | ✓ | ✓ | ✓ | - | - | - | - | - |
+| Align items | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | - |
+| Justify items | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | - | - | - | - |
+| Flow direction | ✓ | - | - | - | - | - | ✓ | - | - | - | - | - |
+| Dense packing | ✓ | - | - | - | - | - | ✓ | - | - | - | - | - |
+| Polimorfismo (as) | ✓ | ✓ | ✓ | ✓ | - | ✓ | - | - | - | - | - | - |
+| Responsive cols | ~ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | - |
+| Auto-fit/fill | - | ✓ | - | - | - | ✓ | ✓ | - | - | - | - | - |
+| Template areas | - | ✓ | - | - | - | - | ✓ | - | - | - | - | - |
+
+**Legenda:** ✓ = Suporte completo | ~ = Via className | - = Nao suportado
+
+#### Comparativo de Props por Design System
+
+| Prop | ETUS | Chakra | MUI | Mantine | AntD | Bootstrap |
+|------|:----:|:------:|:---:|:-------:|:----:|:---------:|
+| **Colunas** | `cols` | `templateColumns` | `columns` | `cols` | `span` | `cols` |
+| **Linhas** | `rows` | `templateRows` | - | - | - | - |
+| **Gap** | `gap` | `gap` | `spacing` | `gutter` | `gutter` | `gap` |
+| **Gap X** | `gapX` | `columnGap` | `columnSpacing` | `gutterX` | - | - |
+| **Gap Y** | `gapY` | `rowGap` | `rowSpacing` | `gutterY` | - | - |
+| **Align** | `items` | `alignItems` | `alignItems` | `align` | `align` | `align-items-*` |
+| **Justify** | `justify` | `justifyItems` | `justifyContent` | `justify` | `justify` | `justify-content-*` |
+| **Element** | `as` | `as` | `component` | `component` | - | - |
+
+---
+
+## Acessibilidade (A11y)
+
+### ARIA Attributes
+
+| Atributo | Uso |
+|----------|-----|
+| `role="grid"` | Opcional para grids de dados interativos |
+| `role="region"` | Para secoes importantes com aria-label |
+| `aria-label` | Descreve o proposito do grid |
+| `aria-labelledby` | Referencia um titulo visivel |
+
+### Suporte a Teclado
+
+Grid e um componente de layout, nao um componente interativo. O suporte a teclado depende dos elementos filhos.
+
+| Tecla | Acao |
+|-------|------|
+| `Tab` | Navega entre items focaveis dentro do grid |
+| `Arrow Keys` | Depende dos filhos (e.g., se for um data grid) |
+
+### Focus Management
+
+Grid nao gerencia foco diretamente. Filhos interativos devem ter seus proprios estilos de foco:
+
+```tsx
+// Filhos devem ter focus-visible
+<Grid cols={3}>
+  <Button className="focus-visible:ring-2 focus-visible:ring-ring">Item</Button>
+</Grid>
+```
+
+### Contraste de Cores
+
+Grid e um componente de layout sem cores proprias. Cores de contraste dependem dos elementos filhos.
+
+### Screen Readers
+
+- Use `as="ul"` ou `as="ol"` para listas semanticas
+- Adicione `aria-label` para descrever o proposito do grid
+- Use `role="region"` com `aria-labelledby` para secoes importantes
+
+```tsx
+// Lista de produtos
+<Grid as="ul" cols={4} aria-label="Lista de produtos">
+  <li>Produto 1</li>
+  <li>Produto 2</li>
+</Grid>
+
+// Secao com titulo
+<h2 id="features-title">Features</h2>
+<Grid cols={3} role="region" aria-labelledby="features-title">
+  ...
+</Grid>
+```
+
+### Reduced Motion
+
+Grid nao possui animacoes. Nenhuma consideracao especial necessaria.
+
+### Conformidade WCAG
+
+| Criterio | Status | Notas |
+|----------|--------|-------|
+| 1.3.1 Info and Relationships | ✓ | Suporta elementos semanticos via `as` |
+| 1.3.2 Meaningful Sequence | ✓ | Ordem visual segue ordem do DOM |
+| 2.4.3 Focus Order | ✓ | Foco segue ordem logica |
+
+### Comparativo A11y (12 Design Systems)
+
+| Feature | ETUS | Chakra | MUI | Mantine | AntD | Tailwind | Bootstrap |
+|---------|:----:|:------:|:---:|:-------:|:----:|:--------:|:---------:|
+| Semantica HTML (as) | ✓ | ✓ | ✓ | ✓ | - | - | - |
+| ARIA support | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
+| Role grid | ~ | ~ | ✓ | ~ | ✓ | ~ | ~ |
+| Keyboard nav | ~ | ~ | ✓ | ~ | ~ | ~ | ~ |
+
+**Legenda:** ✓ = Suporte built-in | ~ = Manual/Via props | - = Nao suportado
+
+---
+
+## Exemplos
+
+### Uso Basico
+
+```tsx
+import { Grid } from "@etus/ui"
+
+function Example() {
+  return (
+    <Grid cols={3} gap={4}>
+      <div>Item 1</div>
+      <div>Item 2</div>
+      <div>Item 3</div>
+    </Grid>
+  )
+}
+```
+
+### Numero de Colunas
+
+```tsx
+// 2 colunas
+<Grid cols={2}>
+  <div>Left</div>
+  <div>Right</div>
+</Grid>
+
+// 3 colunas
+<Grid cols={3}>
+  <div>Item 1</div>
+  <div>Item 2</div>
+  <div>Item 3</div>
+</Grid>
+
+// 4 colunas
+<Grid cols={4}>
+  <div>Item 1</div>
+  <div>Item 2</div>
+  <div>Item 3</div>
+  <div>Item 4</div>
+</Grid>
+
+// 12 colunas (sistema de grid completo)
+<Grid cols={12}>
+  <div className="col-span-4">4/12</div>
+  <div className="col-span-8">8/12</div>
+</Grid>
+```
+
+### Espacamento
+
+```tsx
+// Sem espacamento
+<Grid cols={3} gap={0}>
+  <div>Sem gap</div>
+  <div>Entre</div>
+  <div>Items</div>
+</Grid>
+
+// Espacamento grande
+<Grid cols={3} gap={8}>
+  <div>Gap</div>
+  <div>32px</div>
+  <div>Entre items</div>
+</Grid>
+
+// Espacamento diferente X/Y
+<Grid cols={3} gapX={8} gapY={2}>
+  <div>Gap X 32px</div>
+  <div>Gap Y 8px</div>
+  <div>Diferente</div>
+</Grid>
+```
+
+### Alinhamento
+
+```tsx
+// Items centralizados verticalmente
+<Grid cols={3} items="center" className="h-40">
+  <div className="h-10">Pequeno</div>
+  <div className="h-20">Medio</div>
+  <div className="h-8">Menor</div>
+</Grid>
+
+// Items justificados ao centro
+<Grid cols={3} justify="center">
+  <div className="w-20">Item 1</div>
+  <div className="w-16">Item 2</div>
+  <div className="w-24">Item 3</div>
+</Grid>
+
+// Combinando alinhamentos
+<Grid cols={3} items="center" justify="center">
+  <div>Centralizado em ambos os eixos</div>
+</Grid>
+```
+
+### Fluxo de Grid
+
+```tsx
+// Fluxo por colunas
+<Grid cols={3} rows={2} flow="col">
+  <div>1</div> {/* Col 1, Row 1 */}
+  <div>2</div> {/* Col 1, Row 2 */}
+  <div>3</div> {/* Col 2, Row 1 */}
+  <div>4</div> {/* Col 2, Row 2 */}
+</Grid>
+
+// Preenchimento denso (preenche espacos vazios)
+<Grid cols={3} flow="dense">
+  <div className="col-span-2">Largo</div>
+  <div>Pequeno 1</div>
+  <div>Pequeno 2</div> {/* Preenche o espaco vazio */}
+</Grid>
+```
+
+### Polimorfismo com `as`
+
+```tsx
+// Lista nao ordenada
+<Grid as="ul" cols={3}>
+  <li>Item de lista 1</li>
+  <li>Item de lista 2</li>
+  <li>Item de lista 3</li>
+</Grid>
+
+// Lista ordenada
+<Grid as="ol" cols={2}>
+  <li>Primeiro</li>
+  <li>Segundo</li>
+</Grid>
+
+// Secao semantica
+<Grid as="section" cols={4} aria-label="Features">
+  <article>Feature 1</article>
+  <article>Feature 2</article>
+  <article>Feature 3</article>
+  <article>Feature 4</article>
+</Grid>
+
+// Conteudo principal
+<Grid as="main" cols={1} gap={8}>
+  <header>Header</header>
+  <article>Content</article>
+  <footer>Footer</footer>
+</Grid>
+```
+
+### Responsividade
+
+```tsx
+// Responsivo via className do Tailwind
+<Grid cols={1} className="sm:grid-cols-2 md:grid-cols-3 lg:grid-cols-4" gap={4}>
+  <div>Item 1</div>
+  <div>Item 2</div>
+  <div>Item 3</div>
+  <div>Item 4</div>
+</Grid>
+
+// Dashboard responsivo
+<Grid cols={1} className="lg:grid-cols-12" gap={6}>
+  <aside className="lg:col-span-3">Sidebar</aside>
+  <main className="lg:col-span-9">Content</main>
+</Grid>
+```
+
+### Composicao com Cards
+
+```tsx
+import { Grid, Card, CardHeader, CardContent, CardTitle, CardDescription } from "@etus/ui"
+
+function FeatureGrid() {
+  const features = [
+    { title: "Feature 1", description: "Description 1" },
+    { title: "Feature 2", description: "Description 2" },
+    { title: "Feature 3", description: "Description 3" },
+  ]
+
+  return (
+    <Grid cols={1} className="md:grid-cols-3" gap={6}>
+      {features.map((feature) => (
+        <Card key={feature.title}>
+          <CardHeader>
+            <CardTitle>{feature.title}</CardTitle>
+            <CardDescription>{feature.description}</CardDescription>
+          </CardHeader>
+          <CardContent>
+            {/* Card content */}
+          </CardContent>
+        </Card>
+      ))}
+    </Grid>
+  )
+}
+```
+
+### Dashboard Layout
+
+```tsx
+function DashboardGrid() {
+  return (
+    <Grid cols={12} gap={4}>
+      {/* Header - full width */}
+      <header className="col-span-12">
+        Header
+      </header>
+
+      {/* Sidebar */}
+      <aside className="col-span-12 md:col-span-3 lg:col-span-2">
+        Sidebar
+      </aside>
+
+      {/* Main content */}
+      <main className="col-span-12 md:col-span-9 lg:col-span-10">
+        <Grid cols={1} className="lg:grid-cols-2 xl:grid-cols-3" gap={4}>
+          <div>Widget 1</div>
+          <div>Widget 2</div>
+          <div>Widget 3</div>
+        </Grid>
+      </main>
+    </Grid>
+  )
+}
+```
+
+### Galeria de Imagens
+
+```tsx
+function ImageGallery({ images }: { images: string[] }) {
+  return (
+    <Grid
+      cols={2}
+      className="sm:grid-cols-3 md:grid-cols-4"
+      gap={2}
+      as="ul"
+      aria-label="Galeria de imagens"
+    >
+      {images.map((src, index) => (
+        <li key={index}>
+          <img
+            src={src}
+            alt={`Image ${index + 1}`}
+            className="w-full h-auto aspect-square object-cover rounded"
+          />
+        </li>
+      ))}
+    </Grid>
+  )
+}
+```
+
+### Features Grid com Icones
+
+```tsx
+import { Grid } from "@etus/ui"
+import { Zap, Shield, Globe, Users } from "lucide-react"
+
+function FeaturesGrid() {
+  const features = [
+    { icon: Zap, title: "Rapido", description: "Performance otimizada" },
+    { icon: Shield, title: "Seguro", description: "Protecao avancada" },
+    { icon: Globe, title: "Global", description: "CDN mundial" },
+    { icon: Users, title: "Colaborativo", description: "Trabalho em equipe" },
+  ]
+
+  return (
+    <Grid cols={2} gap={8} className="lg:grid-cols-4">
+      {features.map((feature) => (
+        <div key={feature.title} className="text-center">
+          <feature.icon className="size-12 mx-auto mb-4 text-primary" />
+          <h3 className="font-semibold mb-2">{feature.title}</h3>
+          <p className="text-muted-foreground text-sm">
+            {feature.description}
+          </p>
+        </div>
+      ))}
+    </Grid>
+  )
+}
+```
+
+---
+
+## Testes
+
+### Testes Unitarios
+
+```tsx
+// Grid.test.tsx
+import { render, screen } from "@testing-library/react"
+import { describe, expect, it } from "vitest"
+import { Grid } from "./Grid"
+
+describe("Grid", () => {
+  it("renders with grid display", () => {
+    render(<Grid data-testid="grid">Content</Grid>)
+    expect(screen.getByTestId("grid")).toHaveClass("grid")
+  })
+
+  it("applies column classes", () => {
+    render(<Grid cols={3} data-testid="grid">Content</Grid>)
+    expect(screen.getByTestId("grid")).toHaveClass("grid-cols-3")
+  })
+
+  it("applies gap classes", () => {
+    render(<Grid gap={6} data-testid="grid">Content</Grid>)
+    expect(screen.getByTestId("grid")).toHaveClass("gap-6")
+  })
+
+  it("has data-slot attribute", () => {
+    render(<Grid data-testid="grid">Content</Grid>)
+    expect(screen.getByTestId("grid")).toHaveAttribute("data-slot", "grid")
+  })
+
+  it("supports polymorphism with as prop", () => {
+    render(<Grid as="ul" data-testid="grid"><li>Item</li></Grid>)
+    expect(screen.getByTestId("grid").tagName).toBe("UL")
+  })
+})
+```
+
+### Testes de Interacao
+
+```tsx
+describe("Grid interactions", () => {
+  it("gapX/gapY override gap", () => {
+    render(<Grid gap={6} gapX={2} data-testid="grid">Content</Grid>)
+    const grid = screen.getByTestId("grid")
+    expect(grid).toHaveClass("gap-x-2")
+    expect(grid).not.toHaveClass("gap-6")
+  })
+
+  it("applies multiple variants together", () => {
+    render(
+      <Grid
+        cols={4}
+        rows={2}
+        gap={6}
+        items="center"
+        justify="start"
+        flow="row"
+        data-testid="grid"
+      >
+        Content
+      </Grid>
+    )
+    const grid = screen.getByTestId("grid")
+    expect(grid).toHaveClass("grid-cols-4")
+    expect(grid).toHaveClass("grid-rows-2")
+    expect(grid).toHaveClass("gap-6")
+    expect(grid).toHaveClass("items-center")
+    expect(grid).toHaveClass("justify-items-start")
+    expect(grid).toHaveClass("grid-flow-row")
+  })
+})
+```
+
+### Testes de Acessibilidade
+
+```tsx
+import { axe, toHaveNoViolations } from "jest-axe"
+
+expect.extend(toHaveNoViolations)
+
+describe("Grid accessibility", () => {
+  it("has no accessibility violations", async () => {
+    const { container } = render(
+      <Grid cols={3}>
+        <div>Item 1</div>
+        <div>Item 2</div>
+        <div>Item 3</div>
+      </Grid>
+    )
+    const results = await axe(container)
+    expect(results).toHaveNoViolations()
+  })
+
+  it("preserves semantic structure with ul", async () => {
+    render(
+      <Grid as="ul" cols={2}>
+        <li>Item 1</li>
+        <li>Item 2</li>
+      </Grid>
+    )
+    expect(screen.getByRole("list")).toBeInTheDocument()
+    expect(screen.getAllByRole("listitem")).toHaveLength(2)
+  })
+
+  it("supports aria attributes", () => {
+    render(
+      <Grid
+        aria-labelledby="grid-title"
+        data-testid="grid"
+        role="region"
+      >
+        Content
+      </Grid>
+    )
+    const grid = screen.getByTestId("grid")
+    expect(grid).toHaveAttribute("role", "region")
+    expect(grid).toHaveAttribute("aria-labelledby", "grid-title")
+  })
+})
+```
+
+---
+
+## Roadmap / Features Futuras
+
+Baseado na analise comparativa com 14 design systems, as seguintes features sao candidatas para implementacao futura:
+
+### Prioridade Alta
+
+| Feature | Referencia | Justificativa |
+|---------|------------|---------------|
+| **Responsive cols props** | Chakra, MUI, Mantine | Permitir `cols={{ base: 1, md: 2, lg: 3 }}` sem className |
+| **Auto-fit/fill** | Chakra, NextUI, Tailwind | `cols="auto-fit"` para grids responsivos automaticos |
+
+### Prioridade Media
+
+| Feature | Referencia | Justificativa |
+|---------|------------|---------------|
+| **Template areas** | Chakra, CSS Grid | Suporte a `grid-template-areas` para layouts complexos |
+| **Subgrid** | CSS Grid Level 2 | Items filhos herdam grid do pai |
+| **Place props** | Chakra | `place` como atalho para `items` + `justify` |
+
+### Prioridade Baixa
+
+| Feature | Referencia | Justificativa |
+|---------|------------|---------------|
+| **Auto columns/rows** | Tailwind | `auto-cols-*` e `auto-rows-*` |
+| **Grid.Item** | Chakra, MUI | Compound component para items com `span` |
+| **Debug mode** | Dev tools | Visualizar linhas do grid em desenvolvimento |
+
+### Decisoes de Design
+
+| Feature | Recomendacao | Justificativa |
+|---------|--------------|---------------|
+| Responsive via props | Considerar | Ergonomia vs complexidade - avaliar demanda |
+| Auto-fit/fill | Implementar | Alta demanda, baixa complexidade |
+| Template areas | Avaliar | Complexidade alta, casos de uso limitados |
+| Grid.Item | Nao implementar | className com Tailwind e suficiente |
+
+---
+
+## Referencias
+
+### Design Systems Analisados
+
+| Design System | Documentacao | GitHub |
+|---------------|--------------|--------|
+| **Chakra UI** | [Grid](https://chakra-ui.com/docs/components/grid) | [chakra-ui/chakra-ui](https://github.com/chakra-ui/chakra-ui) |
+| **MUI** | [Grid](https://mui.com/material-ui/react-grid/) | [mui/material-ui](https://github.com/mui/material-ui) |
+| **Mantine** | [Grid](https://mantine.dev/core/grid/) | [mantinedev/mantine](https://github.com/mantinedev/mantine) |
+| **Ant Design** | [Grid](https://ant.design/components/grid) | [ant-design/ant-design](https://github.com/ant-design/ant-design) |
+| **NextUI** | [Grid](https://nextui.org/docs/components/grid) | [nextui-org/nextui](https://github.com/nextui-org/nextui) |
+| **Fluent UI** | [Grid](https://react.fluentui.dev/?path=/docs/components-grid) | [microsoft/fluentui](https://github.com/microsoft/fluentui) |
+| **Carbon** | [Grid](https://carbondesignsystem.com/components/grid/usage/) | [carbon-design-system/carbon](https://github.com/carbon-design-system/carbon) |
+| **Bootstrap** | [Grid](https://getbootstrap.com/docs/5.3/layout/grid/) | [twbs/bootstrap](https://github.com/twbs/bootstrap) |
+| **Tailwind CSS** | [Grid](https://tailwindcss.com/docs/grid-template-columns) | [tailwindlabs/tailwindcss](https://github.com/tailwindlabs/tailwindcss) |
+| **Blueprint** | [Grid](https://blueprintjs.com/docs/#core/components/grid) | [palantir/blueprint](https://github.com/palantir/blueprint) |
+| **Foundation** | [XY Grid](https://get.foundation/sites/docs/xy-grid.html) | [foundation/foundation-sites](https://github.com/foundation/foundation-sites) |
+
+### Especificacoes e Padroes
+
+- [CSS Grid Layout - MDN](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Grid_Layout)
+- [CSS Grid Layout Module Level 1](https://www.w3.org/TR/css-grid-1/)
+- [CSS Grid Layout Module Level 2](https://www.w3.org/TR/css-grid-2/)
+- [A Complete Guide to CSS Grid - CSS-Tricks](https://css-tricks.com/snippets/css/complete-guide-grid/)
+- [Every Layout - Grid](https://every-layout.dev/layouts/grid/)
+
+### Ferramentas Utilizadas
+
+- [CVA - Class Variance Authority](https://cva.style/docs)
+- [Tailwind CSS](https://tailwindcss.com/docs)
+- [tailwind-merge](https://github.com/dcastil/tailwind-merge)