@etus/ui 0.1.0

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

@@ -0,0 +1,885 @@
+# Collapsible
+
+## Visão Geral
+
+O **Collapsible** é um componente interativo que permite expandir e recolher conteúdo de forma animada. Como elemento de layout, serve para organizar informações de maneira progressiva, revelando detalhes apenas quando necessário.
+
+### Casos de Uso
+
+- FAQs e seções de perguntas frequentes
+- Filtros avançados em painéis laterais
+- Detalhes expandíveis em cards
+- Conteúdo secundário que pode ser ocultado
+- Sidebars com seções colapsáveis
+- Formulários com seções opcionais
+
+### Classificação
+
+**Categoria:** Layout
+**Dependências:** `@radix-ui/react-collapsible`, `class-variance-authority`
+
+---
+
+## Design Specs
+
+### Variantes (`animation`)
+
+| Variante | Uso | Comportamento |
+|----------|-----|---------------|
+| `animated` | Padrão, transições suaves | Animação de altura e opacidade |
+| `none` | Performance crítica | Mostrar/ocultar instantâneo |
+
+### Estados
+
+| Estado | Classes/Atributos | Comportamento |
+|--------|-------------------|---------------|
+| Open | `data-state="open"` | Conteúdo visível, trigger com `aria-expanded="true"` |
+| Closed | `data-state="closed"` | Conteúdo oculto, trigger com `aria-expanded="false"` |
+| Disabled | `data-disabled` | Trigger não-interativo, 50% opacidade |
+
+### Tokens Utilizados
+
+```css
+/* Animações */
+animate-collapsible-down  /* Expansão: de 0 para altura natural */
+animate-collapsible-up    /* Recolhimento: de altura natural para 0 */
+
+/* CSS Variables (Radix) */
+--radix-collapsible-content-height  /* Altura do conteúdo */
+--radix-collapsible-content-width   /* Largura do conteúdo */
+
+/* Cursor */
+cursor-pointer            /* Trigger interativo */
+cursor-not-allowed        /* Trigger desabilitado */
+
+/* Transições */
+overflow-hidden           /* Conteúdo durante animação */
+```
+
+### data-slot
+
+```html
+<div data-slot="collapsible">
+  <button data-slot="collapsible-trigger">...</button>
+  <div data-slot="collapsible-content">...</div>
+</div>
+```
+
+---
+
+## API
+
+### Collapsible (Root)
+
+| Prop | Tipo | Padrão | Descrição |
+|------|------|--------|-----------|
+| `open` | `boolean` | - | Estado controlado de aberto/fechado |
+| `defaultOpen` | `boolean` | `false` | Estado inicial (não-controlado) |
+| `onOpenChange` | `(open: boolean) => void` | - | Callback ao mudar estado |
+| `disabled` | `boolean` | `false` | Desabilita o componente |
+| `className` | `string` | - | Classes CSS adicionais |
+| `children` | `ReactNode` | - | Trigger e Content |
+
+> Herda todas as props de `React.ComponentProps<"div">`
+
+### CollapsibleTrigger
+
+| Prop | Tipo | Padrão | Descrição |
+|------|------|--------|-----------|
+| `asChild` | `boolean` | `false` | Renderiza children como elemento |
+| `className` | `string` | - | Classes CSS adicionais |
+| `children` | `ReactNode` | - | Conteúdo do trigger |
+
+> Herda todas as props de `React.ComponentProps<"button">`
+
+### CollapsibleContent
+
+| Prop | Tipo | Padrão | Descrição |
+|------|------|--------|-----------|
+| `animation` | `"animated" \| "none"` | `"animated"` | Tipo de animação |
+| `forceMount` | `boolean` | `false` | Força montagem no DOM quando fechado |
+| `className` | `string` | - | Classes CSS adicionais |
+| `children` | `ReactNode` | - | Conteúdo colapsável |
+
+> Herda todas as props de `React.ComponentProps<"div">`
+
+### Callbacks
+
+| Callback | Tipo | Descrição |
+|----------|------|-----------|
+| `onOpenChange` | `(open: boolean) => void` | Disparado ao expandir/recolher |
+
+### TypeScript
+
+```typescript
+import type { VariantProps } from "class-variance-authority"
+
+// Props do componente root
+interface CollapsibleProps extends ComponentProps<typeof CollapsiblePrimitive.Root> {}
+
+// Props do trigger
+interface CollapsibleTriggerProps
+  extends ComponentProps<typeof CollapsiblePrimitive.CollapsibleTrigger> {}
+
+// Props do content
+interface CollapsibleContentProps
+  extends ComponentProps<typeof CollapsiblePrimitive.CollapsibleContent>,
+    VariantProps<typeof collapsibleContentVariants> {}
+
+// Tipos derivados
+type CollapsibleContentAnimation = "animated" | "none"
+```
+
+### Comparativo com Design Systems de Referência
+
+#### Matriz de Features (12 Design Systems)
+
+| Feature | ETUS | Shadcn | Radix | Chakra | MUI | Mantine | AntD | NextUI | Headless | Ariakit | Fluent | Carbon |
+|---------|:----:|:------:|:-----:|:------:|:---:|:-------:|:----:|:------:|:--------:|:-------:|:------:|:------:|
+| **Compound Components** | ✓ | ✓ | ✓ | ✓ | - | - | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
+| **Controlled/Uncontrolled** | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
+| **Animation** | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | - | - | ✓ | ✓ |
+| **asChild/Slot** | ✓ | ✓ | ✓ | - | - | - | - | ✓ | ✓ | ✓ | - | - |
+| **data-state** | ✓ | ✓ | ✓ | - | - | - | - | ✓ | ✓ | ✓ | - | - |
+| **data-slot** | ✓ | ✓ | - | - | - | - | - | - | - | - | - | - |
+| **CSS Variables** | ✓ | ✓ | ✓ | - | - | - | - | - | - | - | - | - |
+| **forceMount** | ✓ | ✓ | ✓ | - | - | - | - | - | - | - | - | - |
+| **disabled** | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | - | ✓ | ✓ | ✓ |
+| **Multiple Open** | - | - | - | - | - | ✓ | ✓ | ✓ | - | - | ✓ | ✓ |
+| **Accordion Mode** | - | - | - | - | - | ✓ | ✓ | ✓ | - | - | ✓ | ✓ |
+| **Nested Support** | ✓ | ✓ | ✓ | ✓ | ✓ | - | - | - | ✓ | ✓ | - | - |
+
+#### Comparativo de Props por Design System
+
+| Prop | ETUS | Radix | Chakra | MUI | Mantine | AntD | Headless |
+|------|:----:|:-----:|:------:|:---:|:-------:|:----:|:--------:|
+| `open` | ✓ | ✓ | `isOpen` | `in` | `in` | `activeKey` | ✓ |
+| `defaultOpen` | ✓ | ✓ | `defaultIsOpen` | - | - | `defaultActiveKey` | `defaultOpen` |
+| `onOpenChange` | ✓ | ✓ | `onClose` | - | - | `onChange` | ✓ |
+| `disabled` | ✓ | ✓ | `isDisabled` | - | - | ✓ | - |
+| `animation` | ✓ | - | - | `timeout` | `transitionDuration` | - | - |
+| `forceMount` | ✓ | ✓ | - | `unmountOnExit` | - | `destroyInactivePanel` | - |
+| `asChild` | ✓ | ✓ | - | - | - | - | `as` |
+
+#### Nomenclatura por Design System
+
+| Design System | Componente | Padrão |
+|---------------|------------|--------|
+| **ETUS** | `Collapsible`, `CollapsibleTrigger`, `CollapsibleContent` | Compound components |
+| **Shadcn/ui** | `Collapsible`, `CollapsibleTrigger`, `CollapsibleContent` | Radix-based |
+| **Radix UI** | `Collapsible.Root`, `Collapsible.Trigger`, `Collapsible.Content` | Primitivo |
+| **Chakra UI** | `Collapsible.Root`, `Collapsible.Trigger`, `Collapsible.Content` | v3 compound |
+| **MUI** | `Collapse` | Single component |
+| **Mantine** | `Collapse` | Single component |
+| **Ant Design** | `Collapse`, `Collapse.Panel` | Accordion-focused |
+| **NextUI** | `Accordion`, `AccordionItem` | Accordion-focused |
+| **Headless UI** | `Disclosure`, `DisclosureButton`, `DisclosurePanel` | Disclosure pattern |
+| **Ariakit** | `Disclosure`, `DisclosureContent` | Store pattern |
+| **Fluent UI** | `Accordion`, `AccordionItem`, `AccordionHeader`, `AccordionPanel` | Enterprise |
+| **Carbon** | `Accordion`, `AccordionItem` | IBM pattern |
+
+---
+
+## Acessibilidade (A11y)
+
+### ARIA Attributes
+
+| Atributo | Elemento | Uso |
+|----------|----------|-----|
+| `aria-expanded` | Trigger | Indica estado aberto (`true`) ou fechado (`false`) |
+| `aria-controls` | Trigger | Referencia o ID do content |
+| `aria-hidden` | Content | `true` quando fechado (se não forceMount) |
+| `role="button"` | Trigger | Identifica como controle interativo |
+| `id` | Content | Auto-gerado, referenciado por aria-controls |
+
+### Suporte a Teclado
+
+| Tecla | Ação |
+|-------|------|
+| `Tab` | Move foco para/do trigger |
+| `Enter` | Alterna estado aberto/fechado |
+| `Space` | Alterna estado aberto/fechado |
+
+### Focus Management
+
+```tsx
+// Focus visible apenas para navegação por teclado
+.collapsible-trigger:focus-visible {
+  outline: 2px solid var(--ring);
+  outline-offset: 2px;
+}
+```
+
+### Contraste de Cores
+
+O Collapsible é um componente estrutural sem cores próprias. Os elementos internos devem seguir WCAG 2.1 AA:
+
+| Elemento | Requisito |
+|----------|-----------|
+| Trigger text | ≥ 4.5:1 contra background |
+| Focus indicator | ≥ 3:1 contra adjacentes |
+| Content text | ≥ 4.5:1 contra background |
+
+### Screen Readers
+
+- Trigger anuncia "expanded" ou "collapsed" automaticamente
+- Content é ocultado de screen readers quando fechado (via `aria-hidden`)
+- Use `forceMount` com cuidado pois mantém content no DOM
+
+### Reduced Motion
+
+```css
+@media (prefers-reduced-motion: reduce) {
+  [data-slot="collapsible-content"] {
+    animation: none !important;
+    transition: none !important;
+  }
+}
+```
+
+### Comparativo A11y (12 Design Systems)
+
+| Feature | ETUS | React Aria | Radix | Ariakit | Headless | Chakra | MUI | Mantine | AntD | NextUI | Fluent | Carbon |
+|---------|:----:|:----------:|:-----:|:-------:|:--------:|:------:|:---:|:-------:|:----:|:------:|:------:|:------:|
+| **aria-expanded** | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | - | - | ✓ | ✓ | ✓ | ✓ |
+| **aria-controls** | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | - | - | ✓ | ✓ | ✓ | ✓ |
+| **aria-hidden** | ✓ | ✓ | ✓ | ✓ | ✓ | - | - | - | - | - | ✓ | ✓ |
+| **Keyboard nav** | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | - | - | ✓ | ✓ | ✓ | ✓ |
+| **Focus visible** | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | - | - | ✓ | ✓ | ✓ | ✓ |
+| **hidden="until-found"** | - | ✓ | - | - | - | - | - | - | - | - | - | - |
+| **Reduced motion** | ~ | ✓ | - | - | - | ✓ | ✓ | ✓ | - | ✓ | ✓ | ✓ |
+| **Screen reader tested** | ~ | ✓ | ✓ | ✓ | ✓ | ~ | ~ | ~ | ~ | ~ | ✓ | ✓ |
+
+**Legenda:** ✓ = Suporte completo | ~ = Parcial/Manual | - = Não suportado
+
+---
+
+## Exemplos
+
+### Uso Básico
+
+```tsx
+import { Collapsible, CollapsibleContent, CollapsibleTrigger } from "@etus/ui"
+
+function Example() {
+  return (
+    <Collapsible>
+      <CollapsibleTrigger>Clique para expandir</CollapsibleTrigger>
+      <CollapsibleContent>
+        <p>Conteúdo que pode ser expandido ou recolhido.</p>
+      </CollapsibleContent>
+    </Collapsible>
+  )
+}
+```
+
+### Controlado
+
+```tsx
+import { useState } from "react"
+import { Collapsible, CollapsibleContent, CollapsibleTrigger } from "@etus/ui"
+import { cn } from "@etus/ui"
+import { ChevronDown } from "lucide-react"
+
+function ControlledExample() {
+  const [isOpen, setIsOpen] = useState(false)
+
+  return (
+    <Collapsible open={isOpen} onOpenChange={setIsOpen}>
+      <CollapsibleTrigger className="flex items-center gap-2">
+        <span>Detalhes</span>
+        <ChevronDown
+          className={cn(
+            "size-4 transition-transform",
+            isOpen && "rotate-180"
+          )}
+        />
+      </CollapsibleTrigger>
+      <CollapsibleContent>
+        <div className="pt-2">
+          <p>Estado atual: {isOpen ? "Aberto" : "Fechado"}</p>
+        </div>
+      </CollapsibleContent>
+    </Collapsible>
+  )
+}
+```
+
+### Aberto por Padrão
+
+```tsx
+<Collapsible defaultOpen>
+  <CollapsibleTrigger>Já está aberto</CollapsibleTrigger>
+  <CollapsibleContent>
+    Este conteúdo aparece aberto inicialmente.
+  </CollapsibleContent>
+</Collapsible>
+```
+
+### Sem Animação
+
+```tsx
+<Collapsible>
+  <CollapsibleTrigger>Toggle Instantâneo</CollapsibleTrigger>
+  <CollapsibleContent animation="none">
+    Conteúdo aparece/desaparece sem animação.
+  </CollapsibleContent>
+</Collapsible>
+```
+
+### Desabilitado
+
+```tsx
+<Collapsible disabled>
+  <CollapsibleTrigger className="opacity-50 cursor-not-allowed">
+    Não pode ser expandido
+  </CollapsibleTrigger>
+  <CollapsibleContent>
+    Este conteúdo não será acessível.
+  </CollapsibleContent>
+</Collapsible>
+```
+
+### Com Ícone Animado
+
+```tsx
+import { ChevronRight } from "lucide-react"
+
+function CollapsibleWithIcon() {
+  return (
+    <Collapsible className="w-full">
+      <CollapsibleTrigger className="flex w-full items-center justify-between rounded-md bg-muted p-4">
+        <span className="font-medium">Configurações Avançadas</span>
+        <ChevronRight className="size-4 transition-transform duration-200 data-[state=open]:rotate-90" />
+      </CollapsibleTrigger>
+      <CollapsibleContent className="px-4 pt-2">
+        <div className="space-y-2">
+          <p>Opção 1: Configuração de cache</p>
+          <p>Opção 2: Configuração de debug</p>
+          <p>Opção 3: Configuração de logging</p>
+        </div>
+      </CollapsibleContent>
+    </Collapsible>
+  )
+}
+```
+
+### Polimorfismo com asChild
+
+```tsx
+import { Button } from "@etus/ui"
+import { ChevronDown } from "lucide-react"
+
+function CollapsibleWithButton() {
+  return (
+    <Collapsible>
+      <CollapsibleTrigger asChild>
+        <Button variant="outline">
+          <span>Mostrar mais</span>
+          <ChevronDown className="ml-2 size-4" />
+        </Button>
+      </CollapsibleTrigger>
+      <CollapsibleContent className="mt-4">
+        <p>Conteúdo adicional revelado pelo botão.</p>
+      </CollapsibleContent>
+    </Collapsible>
+  )
+}
+```
+
+### FAQ Section
+
+```tsx
+import { ChevronDown } from "lucide-react"
+
+function FAQSection() {
+  const faqs = [
+    { question: "Como funciona?", answer: "Explicação detalhada..." },
+    { question: "Quanto custa?", answer: "Informações de preço..." },
+    { question: "Posso cancelar?", answer: "Política de cancelamento..." },
+  ]
+
+  return (
+    <div className="space-y-2">
+      {faqs.map((faq, index) => (
+        <Collapsible key={index} className="rounded-lg border">
+          <CollapsibleTrigger className="flex w-full items-center justify-between p-4 font-medium hover:bg-muted/50">
+            {faq.question}
+            <ChevronDown className="size-4" />
+          </CollapsibleTrigger>
+          <CollapsibleContent className="border-t px-4 py-3">
+            {faq.answer}
+          </CollapsibleContent>
+        </Collapsible>
+      ))}
+    </div>
+  )
+}
+```
+
+### Sidebar com Seções Colapsáveis
+
+```tsx
+import { Folder, ChevronDown } from "lucide-react"
+
+function SidebarWithCollapsible() {
+  return (
+    <aside className="w-64 space-y-1">
+      <Collapsible defaultOpen>
+        <CollapsibleTrigger className="flex w-full items-center gap-2 rounded-md px-3 py-2 hover:bg-muted">
+          <Folder className="size-4" />
+          <span className="flex-1 text-left">Documentos</span>
+          <ChevronDown className="size-4" />
+        </CollapsibleTrigger>
+        <CollapsibleContent className="ml-6 space-y-1">
+          <a href="#" className="block rounded-md px-3 py-1 hover:bg-muted">
+            Relatórios
+          </a>
+          <a href="#" className="block rounded-md px-3 py-1 hover:bg-muted">
+            Contratos
+          </a>
+          <a href="#" className="block rounded-md px-3 py-1 hover:bg-muted">
+            Faturas
+          </a>
+        </CollapsibleContent>
+      </Collapsible>
+    </aside>
+  )
+}
+```
+
+### Com forceMount (SEO/Find-in-page)
+
+```tsx
+<Collapsible>
+  <CollapsibleTrigger>Conteúdo indexável</CollapsibleTrigger>
+  <CollapsibleContent forceMount className="data-[state=closed]:hidden">
+    Este conteúdo permanece no DOM mesmo quando fechado,
+    permitindo que buscadores e find-in-page encontrem o texto.
+  </CollapsibleContent>
+</Collapsible>
+```
+
+### Múltiplos Collapsibles Independentes
+
+```tsx
+function MultipleCollapsibles() {
+  return (
+    <div className="space-y-4">
+      <Collapsible>
+        <CollapsibleTrigger className="font-semibold">
+          Seção 1
+        </CollapsibleTrigger>
+        <CollapsibleContent>Conteúdo da seção 1</CollapsibleContent>
+      </Collapsible>
+
+      <Collapsible>
+        <CollapsibleTrigger className="font-semibold">
+          Seção 2
+        </CollapsibleTrigger>
+        <CollapsibleContent>Conteúdo da seção 2</CollapsibleContent>
+      </Collapsible>
+
+      <Collapsible>
+        <CollapsibleTrigger className="font-semibold">
+          Seção 3
+        </CollapsibleTrigger>
+        <CollapsibleContent>Conteúdo da seção 3</CollapsibleContent>
+      </Collapsible>
+    </div>
+  )
+}
+```
+
+---
+
+## Testes
+
+### Testes Unitários
+
+```tsx
+// Collapsible.test.tsx
+import { render, screen } from "@testing-library/react"
+import userEvent from "@testing-library/user-event"
+import { describe, expect, it, vi } from "vitest"
+import { Collapsible, CollapsibleContent, CollapsibleTrigger } from "./Collapsible"
+
+describe("Collapsible", () => {
+  it("renders trigger correctly", () => {
+    render(
+      <Collapsible>
+        <CollapsibleTrigger>Toggle</CollapsibleTrigger>
+        <CollapsibleContent>Content</CollapsibleContent>
+      </Collapsible>
+    )
+    expect(screen.getByRole("button", { name: "Toggle" })).toBeInTheDocument()
+  })
+
+  it("hides content by default", () => {
+    render(
+      <Collapsible>
+        <CollapsibleTrigger>Toggle</CollapsibleTrigger>
+        <CollapsibleContent>Hidden Content</CollapsibleContent>
+      </Collapsible>
+    )
+    expect(screen.queryByText("Hidden Content")).not.toBeVisible()
+  })
+
+  it("shows content when defaultOpen is true", () => {
+    render(
+      <Collapsible defaultOpen>
+        <CollapsibleTrigger>Toggle</CollapsibleTrigger>
+        <CollapsibleContent>Visible Content</CollapsibleContent>
+      </Collapsible>
+    )
+    expect(screen.getByText("Visible Content")).toBeVisible()
+  })
+
+  it("has data-slot attributes", () => {
+    render(
+      <Collapsible>
+        <CollapsibleTrigger>Toggle</CollapsibleTrigger>
+        <CollapsibleContent>Content</CollapsibleContent>
+      </Collapsible>
+    )
+    expect(screen.getByRole("button")).toHaveAttribute("data-slot", "collapsible-trigger")
+  })
+})
+```
+
+### Testes de Interação
+
+```tsx
+describe("Collapsible interactions", () => {
+  it("toggles content on click", async () => {
+    const user = userEvent.setup()
+    render(
+      <Collapsible>
+        <CollapsibleTrigger>Toggle</CollapsibleTrigger>
+        <CollapsibleContent>Content</CollapsibleContent>
+      </Collapsible>
+    )
+
+    const trigger = screen.getByRole("button")
+    expect(screen.queryByText("Content")).not.toBeVisible()
+
+    await user.click(trigger)
+    expect(screen.getByText("Content")).toBeVisible()
+
+    await user.click(trigger)
+    expect(screen.queryByText("Content")).not.toBeVisible()
+  })
+
+  it("calls onOpenChange when toggled", async () => {
+    const user = userEvent.setup()
+    const handleOpenChange = vi.fn()
+
+    render(
+      <Collapsible onOpenChange={handleOpenChange}>
+        <CollapsibleTrigger>Toggle</CollapsibleTrigger>
+        <CollapsibleContent>Content</CollapsibleContent>
+      </Collapsible>
+    )
+
+    await user.click(screen.getByRole("button"))
+    expect(handleOpenChange).toHaveBeenCalledWith(true)
+
+    await user.click(screen.getByRole("button"))
+    expect(handleOpenChange).toHaveBeenCalledWith(false)
+  })
+
+  it("toggles with keyboard", async () => {
+    const user = userEvent.setup()
+    render(
+      <Collapsible>
+        <CollapsibleTrigger>Toggle</CollapsibleTrigger>
+        <CollapsibleContent>Content</CollapsibleContent>
+      </Collapsible>
+    )
+
+    screen.getByRole("button").focus()
+
+    await user.keyboard("{Enter}")
+    expect(screen.getByText("Content")).toBeVisible()
+
+    await user.keyboard("{Space}")
+    expect(screen.queryByText("Content")).not.toBeVisible()
+  })
+
+  it("does not toggle when disabled", async () => {
+    const user = userEvent.setup()
+    const handleOpenChange = vi.fn()
+
+    render(
+      <Collapsible disabled onOpenChange={handleOpenChange}>
+        <CollapsibleTrigger>Toggle</CollapsibleTrigger>
+        <CollapsibleContent>Content</CollapsibleContent>
+      </Collapsible>
+    )
+
+    await user.click(screen.getByRole("button"))
+    expect(handleOpenChange).not.toHaveBeenCalled()
+  })
+})
+```
+
+### Testes de Acessibilidade
+
+```tsx
+import { axe, toHaveNoViolations } from "jest-axe"
+
+expect.extend(toHaveNoViolations)
+
+describe("Collapsible accessibility", () => {
+  it("has no accessibility violations when closed", async () => {
+    const { container } = render(
+      <Collapsible>
+        <CollapsibleTrigger>Toggle</CollapsibleTrigger>
+        <CollapsibleContent>Content</CollapsibleContent>
+      </Collapsible>
+    )
+    const results = await axe(container)
+    expect(results).toHaveNoViolations()
+  })
+
+  it("has no accessibility violations when open", async () => {
+    const { container } = render(
+      <Collapsible defaultOpen>
+        <CollapsibleTrigger>Toggle</CollapsibleTrigger>
+        <CollapsibleContent>Content</CollapsibleContent>
+      </Collapsible>
+    )
+    const results = await axe(container)
+    expect(results).toHaveNoViolations()
+  })
+
+  it("has correct aria-expanded attribute", async () => {
+    const user = userEvent.setup()
+    render(
+      <Collapsible>
+        <CollapsibleTrigger>Toggle</CollapsibleTrigger>
+        <CollapsibleContent>Content</CollapsibleContent>
+      </Collapsible>
+    )
+
+    const trigger = screen.getByRole("button")
+    expect(trigger).toHaveAttribute("aria-expanded", "false")
+
+    await user.click(trigger)
+    expect(trigger).toHaveAttribute("aria-expanded", "true")
+  })
+
+  it("trigger has aria-controls referencing content", () => {
+    render(
+      <Collapsible defaultOpen>
+        <CollapsibleTrigger>Toggle</CollapsibleTrigger>
+        <CollapsibleContent>Content</CollapsibleContent>
+      </Collapsible>
+    )
+
+    const trigger = screen.getByRole("button")
+    const contentId = trigger.getAttribute("aria-controls")
+    expect(document.getElementById(contentId!)).toBeInTheDocument()
+  })
+
+  it("is focusable via keyboard", () => {
+    render(
+      <Collapsible>
+        <CollapsibleTrigger>Toggle</CollapsibleTrigger>
+        <CollapsibleContent>Content</CollapsibleContent>
+      </Collapsible>
+    )
+
+    const trigger = screen.getByRole("button")
+    trigger.focus()
+    expect(trigger).toHaveFocus()
+  })
+})
+```
+
+### Testes de Composição (asChild)
+
+```tsx
+describe("Collapsible asChild", () => {
+  it("renders trigger as child element", () => {
+    render(
+      <Collapsible>
+        <CollapsibleTrigger asChild>
+          <button className="custom-button">Custom Trigger</button>
+        </CollapsibleTrigger>
+        <CollapsibleContent>Content</CollapsibleContent>
+      </Collapsible>
+    )
+
+    const trigger = screen.getByRole("button", { name: "Custom Trigger" })
+    expect(trigger).toHaveClass("custom-button")
+  })
+
+  it("maintains functionality with asChild", async () => {
+    const user = userEvent.setup()
+    render(
+      <Collapsible>
+        <CollapsibleTrigger asChild>
+          <div role="button" tabIndex={0}>Custom Element</div>
+        </CollapsibleTrigger>
+        <CollapsibleContent>Content</CollapsibleContent>
+      </Collapsible>
+    )
+
+    await user.click(screen.getByRole("button"))
+    expect(screen.getByText("Content")).toBeVisible()
+  })
+})
+```
+
+---
+
+## Roadmap / Features Futuras
+
+Baseado na análise comparativa com 14 design systems, as seguintes features são candidatas para implementação futura:
+
+### Prioridade Alta
+
+#### `CollapsibleGroup` (Accordion Mode)
+
+Permitir que apenas um Collapsible esteja aberto por vez em um grupo.
+
+```tsx
+// Proposta de API
+<CollapsibleGroup type="single" defaultValue="item-1">
+  <Collapsible value="item-1">
+    <CollapsibleTrigger>Item 1</CollapsibleTrigger>
+    <CollapsibleContent>Content 1</CollapsibleContent>
+  </Collapsible>
+  <Collapsible value="item-2">
+    <CollapsibleTrigger>Item 2</CollapsibleTrigger>
+    <CollapsibleContent>Content 2</CollapsibleContent>
+  </Collapsible>
+</CollapsibleGroup>
+```
+
+**Referências:** Radix Accordion, Chakra Accordion, AntD Collapse, Fluent Accordion
+
+#### `hidden="until-found"` Support
+
+Suporte para o atributo HTML `hidden="until-found"` que permite find-in-page e melhor SEO.
+
+```tsx
+// Proposta de API
+<CollapsibleContent searchable>
+  Conteúdo encontrável mesmo quando fechado
+</CollapsibleContent>
+```
+
+**Referências:** React Aria `useDisclosure`
+
+### Prioridade Média
+
+#### Customização de Animação
+
+Props para controlar duração e timing da animação.
+
+```tsx
+// Proposta de API
+<CollapsibleContent
+  animation="animated"
+  animationDuration={300}
+  animationTimingFunction="ease-out"
+>
+  Content
+</CollapsibleContent>
+```
+
+**Referências:** MUI (`timeout`), Mantine (`transitionDuration`)
+
+#### `unmountOnExit`
+
+Desmontar conteúdo do DOM quando fechado (performance).
+
+```tsx
+// Proposta de API
+<CollapsibleContent unmountOnExit>
+  Heavy content que será removido do DOM
+</CollapsibleContent>
+```
+
+**Referências:** Chakra (`unmountOnExit`), MUI (`unmountOnExit`)
+
+### Prioridade Baixa
+
+#### `CollapsibleIndicator`
+
+Componente dedicado para indicador de estado (chevron/plus/minus).
+
+```tsx
+// Proposta de API
+<Collapsible>
+  <CollapsibleTrigger>
+    <span>Title</span>
+    <CollapsibleIndicator />
+  </CollapsibleTrigger>
+</Collapsible>
+```
+
+**Referências:** Chakra (`Collapsible.Indicator`), NextUI (`indicator` prop)
+
+#### `orientation`
+
+Suporte para collapse horizontal.
+
+```tsx
+// Proposta de API
+<CollapsibleContent orientation="horizontal">
+  Sidebar content
+</CollapsibleContent>
+```
+
+**Referências:** MUI (`orientation`)
+
+### Decisões de Design
+
+| Feature | Recomendação | Justificativa |
+|---------|--------------|---------------|
+| `CollapsibleGroup` | ✅ Implementar | Alto uso, padrão comum para FAQ/acordeões |
+| `hidden="until-found"` | ✅ Implementar | Melhora SEO e find-in-page |
+| Animation customization | ⚠️ Avaliar | Pode usar CSS custom properties |
+| `unmountOnExit` | ⚠️ Avaliar | `forceMount={false}` já existe |
+| `CollapsibleIndicator` | ❌ Evitar | Usar children + CSS para flexibilidade |
+| `orientation` | ❌ Evitar | Caso de uso raro, usar Sheet para sidebars |
+
+---
+
+## Referências
+
+### Design Systems Analisados
+
+| Design System | Documentação | GitHub |
+|---------------|--------------|--------|
+| **Shadcn/ui** | [Collapsible](https://ui.shadcn.com/docs/components/collapsible) | [shadcn-ui/ui](https://github.com/shadcn-ui/ui) |
+| **Radix UI** | [Collapsible](https://www.radix-ui.com/primitives/docs/components/collapsible) | [radix-ui/primitives](https://github.com/radix-ui/primitives) |
+| **React Aria** | [Disclosure](https://react-spectrum.adobe.com/react-aria/Disclosure.html) | [adobe/react-spectrum](https://github.com/adobe/react-spectrum) |
+| **Chakra UI** | [Collapsible](https://chakra-ui.com/docs/components/collapsible) | [chakra-ui/chakra-ui](https://github.com/chakra-ui/chakra-ui) |
+| **MUI** | [Collapse](https://mui.com/material-ui/api/collapse/) | [mui/material-ui](https://github.com/mui/material-ui) |
+| **Mantine** | [Collapse](https://mantine.dev/core/collapse/) | [mantinedev/mantine](https://github.com/mantinedev/mantine) |
+| **Ant Design** | [Collapse](https://ant.design/components/collapse) | [ant-design/ant-design](https://github.com/ant-design/ant-design) |
+| **NextUI** | [Accordion](https://www.heroui.com/docs/components/accordion) | [nextui-org/nextui](https://github.com/nextui-org/nextui) |
+| **Headless UI** | [Disclosure](https://headlessui.com/react/disclosure) | [tailwindlabs/headlessui](https://github.com/tailwindlabs/headlessui) |
+| **Ariakit** | [Disclosure](https://ariakit.org/components/disclosure) | [ariakit/ariakit](https://github.com/ariakit/ariakit) |
+| **Fluent UI** | [Accordion](https://react.fluentui.dev/?path=/docs/components-accordion--default) | [microsoft/fluentui](https://github.com/microsoft/fluentui) |
+| **Carbon** | [Accordion](https://carbondesignsystem.com/components/accordion/code/) | [carbon-design-system/carbon](https://github.com/carbon-design-system/carbon) |
+| **Blueprint** | [Collapse](https://blueprintjs.com/docs/) | [palantir/blueprint](https://github.com/palantir/blueprint) |
+
+### Especificações e Padrões
+
+- [WAI-ARIA APG - Disclosure Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/disclosure/)
+- [WCAG 2.1 Success Criteria](https://www.w3.org/WAI/WCAG21/quickref/)
+- [MDN - aria-expanded](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-expanded)
+- [MDN - aria-controls](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-controls)
+- [MDN - hidden="until-found"](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/hidden)
+
+### Ferramentas Utilizadas
+
+- [CVA - Class Variance Authority](https://cva.style/docs)
+- [Tailwind CSS](https://tailwindcss.com/docs)
+- [Radix Collapsible](https://www.radix-ui.com/primitives/docs/components/collapsible)
+- [Lucide Icons](https://lucide.dev/icons/)