@etus/ui 0.1.0

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

@@ -0,0 +1,861 @@
+# Panel
+
+## Visão Geral
+
+O **Panel** é um componente de layout container que cria áreas de conteúdo delimitadas e estilizadas, frequentemente usado para sidebars, painéis de inspeção, áreas de filtros, e seções de navegação. Como elemento de layout, o Panel organiza e agrupa conteúdo relacionado em regiões visualmente distintas dentro da interface.
+
+### Casos de Uso
+
+- Sidebars de navegação principal ou secundária
+- Painéis de propriedades/inspector em editores
+- Áreas de filtros e controles em dashboards
+- Painéis de preview de conteúdo
+- Seções de configuração e preferências
+- Áreas de detalhes em split views
+- Navegação lateral em aplicações desktop-like
+
+### Classificação
+
+**Categoria:** Layout/Container
+**Dependências:** `class-variance-authority`, `@etus/tokens`
+
+---
+
+## Design Specs
+
+### Variantes (`variant`)
+
+| Variante | Uso | Tokens |
+|----------|-----|--------|
+| `default` | Sidebar padrão, áreas de navegação | `bg-background`, `border` |
+| `subtle` | Painéis secundários, filtros | `bg-muted` |
+| `outlined` | Painéis destacados, seções de formulário | `border`, `bg-transparent` |
+| `elevated` | Painéis flutuantes, inspectors | `bg-background`, `shadow-md` |
+| `inset` | Áreas embutidas, wells | `bg-muted/50`, `shadow-inner` |
+
+### Tamanhos (`size`)
+
+| Tamanho | Largura | Padding | Uso |
+|---------|---------|---------|-----|
+| `xs` | 240px (w-60) | `px-4 py-3` | Sidebar compacta, mobile |
+| `sm` | 280px (w-70) | `px-4 py-3` | Sidebar padrão |
+| `md` | 320px (w-80) | `px-4 py-3` | Panel médio |
+| `lg` | 400px (w-100) | `px-4 py-3` | Panel largo, inspectors |
+| `xl` | 480px (w-120) | `px-4 py-3` | Panel extra largo |
+| `auto` | auto | `px-4 py-3` | Tamanho do conteúdo |
+| `full` | 100% | `px-4 py-3` | Largura total |
+
+### Posições (`position`)
+
+| Posição | Borda | Uso |
+|---------|-------|-----|
+| `left` | `border-r` | Sidebar esquerda |
+| `right` | `border-l` | Inspector direita |
+| `top` | `border-b` | Panel superior |
+| `bottom` | `border-t` | Panel inferior |
+| `center` | - | Panel centralizado |
+
+### Estados
+
+| Estado | Classes/Atributos | Comportamento |
+|--------|-------------------|---------------|
+| Default | - | Aparência base |
+| Hover | Definido pelo usuário | Opcional para cards clicáveis |
+| Collapsible | `data-collapsible` | Panel pode ser colapsado |
+| Collapsed | `data-collapsed`, `data-state="collapsed"` | Panel no estado colapsado |
+| Expanded | `data-state="expanded"` | Panel no estado expandido |
+
+### Tokens Utilizados
+
+```css
+/* Cores */
+--color-background    /* bg-background */
+--color-muted         /* bg-muted */
+--color-border        /* border */
+
+/* Espaçamento */
+--spacing-3           /* py-3 (12px) */
+--spacing-4           /* px-4 (16px) */
+
+/* Bordas */
+border-width: 1px     /* border */
+
+/* Sombras */
+--shadow-md           /* elevated variant */
+--shadow-inner        /* inset variant */
+
+/* Transições */
+transition-all duration-200  /* collapse animation */
+```
+
+### data-slot
+
+```html
+<div data-slot="panel">
+  <div data-slot="panel-header">...</div>
+  <div data-slot="panel-content">...</div>
+  <div data-slot="panel-footer">...</div>
+</div>
+```
+
+---
+
+## API
+
+### Props
+
+| Prop | Tipo | Padrão | Descrição |
+|------|------|--------|-----------|
+| `variant` | `"default" \| "subtle" \| "outlined" \| "elevated" \| "inset"` | `"default"` | Estilo visual do panel |
+| `size` | `"xs" \| "sm" \| "md" \| "lg" \| "xl" \| "auto" \| "full"` | `"auto"` | Largura do panel |
+| `position` | `"left" \| "right" \| "top" \| "bottom" \| "center"` | - | Posição do panel |
+| `as` | `"div" \| "aside" \| "nav" \| "section"` | `"div"` | Elemento semântico a renderizar |
+| `collapsible` | `boolean` | `false` | Permite colapsar o panel |
+| `collapsed` | `boolean` | `false` | Estado colapsado (controlado) |
+| `onCollapse` | `(collapsed: boolean) => void` | - | Callback ao mudar estado de collapse |
+| `className` | `string` | - | Classes CSS adicionais |
+| `children` | `ReactNode` | - | Conteúdo |
+| `ref` | `Ref<HTMLDivElement>` | - | Referência ao elemento DOM |
+
+> Herda todas as props de `React.ComponentProps<"div">`
+
+### Subcomponentes
+
+| Componente | Props Especiais | Descrição |
+|------------|-----------------|-----------|
+| `PanelHeader` | `showToggle?: boolean` | Cabeçalho do panel |
+| `PanelContent` | `scrollable?: boolean` | Área de conteúdo principal |
+| `PanelFooter` | - | Rodapé do panel |
+
+### Callbacks
+
+| Callback | Tipo | Descrição |
+|----------|------|-----------|
+| `onCollapse` | `(collapsed: boolean) => void` | Disparado quando o estado de collapse muda |
+
+### TypeScript
+
+```typescript
+import { type VariantProps } from "class-variance-authority"
+import type { ComponentProps } from "react"
+
+// Variants exportadas
+const panelVariants = cva(/* ... */)
+const panelHeaderVariants = cva(/* ... */)
+const panelContentVariants = cva(/* ... */)
+const panelFooterVariants = cva(/* ... */)
+
+// Props do componente principal
+interface PanelProps
+  extends ComponentProps<"div">,
+    VariantProps<typeof panelVariants> {
+  as?: "aside" | "div" | "nav" | "section"
+  collapsed?: boolean
+  collapsible?: boolean
+  onCollapse?: (collapsed: boolean) => void
+}
+
+// Props dos subcomponentes
+interface PanelHeaderProps extends ComponentProps<"div"> {
+  showToggle?: boolean
+}
+
+interface PanelContentProps extends ComponentProps<"div"> {
+  scrollable?: boolean
+}
+
+interface PanelFooterProps extends ComponentProps<"div"> {}
+
+// Tipos derivados úteis
+type PanelVariant = NonNullable<VariantProps<typeof panelVariants>["variant"]>
+type PanelSize = NonNullable<VariantProps<typeof panelVariants>["size"]>
+type PanelPosition = NonNullable<VariantProps<typeof panelVariants>["position"]>
+```
+
+### 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 | ✓ | ~ | - | - | - | - | ✓ | ✓ | - | - | ✓ | ✓ |
+| Variantes visuais | ✓ | - | - | - | ✓ | ✓ | - | ✓ | - | - | ✓ | ✓ |
+| Collapse/Expand | ✓ | - | - | - | - | - | ✓ | - | - | ✓ | ✓ | ✓ |
+| Posições | ✓ | - | - | - | - | - | ✓ | - | - | - | ✓ | ✓ |
+| Tamanhos predefinidos | ✓ | - | - | - | - | - | - | - | - | - | ✓ | - |
+| Polimorfismo (as) | ✓ | - | - | ✓ | ✓ | ✓ | - | ✓ | ✓ | - | ✓ | - |
+| data-slot | ✓ | ✓ | ✓ | - | - | - | - | - | - | - | - | - |
+| Scrollable content | ✓ | - | - | - | - | - | - | - | - | - | ✓ | - |
+| Responsive breakpoints | ~ | - | - | ✓ | - | - | ✓ | - | - | - | ✓ | ✓ |
+| Elevation/Shadow | ✓ | - | - | - | ✓ | ✓ | - | ✓ | - | - | - | - |
+| Animation support | ~ | - | - | - | - | - | - | - | - | ✓ | ✓ | ✓ |
+| Resizable | - | - | - | - | - | - | - | - | - | - | ✓ | - |
+
+**Legenda:** ✓ = Suporte completo | ~ = Parcial/Básico | - = Não suportado
+
+#### Comparativo de Props por Design System
+
+| Prop | ETUS | Chakra | MUI | Mantine | AntD | NextUI | Fluent |
+|------|:----:|:------:|:---:|:-------:|:----:|:------:|:------:|
+| `variant` | ✓ | - | `variant` | `shadow` | - | `variant` | `appearance` |
+| `size` | ✓ | - | - | - | - | - | `size` |
+| `position` | ✓ | - | - | - | - | - | `position` |
+| `collapsed` | ✓ | - | - | - | `collapsed` | - | `isOpen` |
+| `collapsible` | ✓ | - | - | - | `collapsible` | - | - |
+| `as` | ✓ | ✓ | `component` | `component` | - | `as` | `as` |
+| `scrollable` | ✓ | - | - | - | - | - | `isScrollable` |
+| `elevation` | via variant | - | ✓ | ✓ | - | - | - |
+
+---
+
+## Acessibilidade (A11y)
+
+### ARIA Attributes
+
+| Atributo | Uso |
+|----------|-----|
+| `role="region"` | Quando panel tem título identificável |
+| `role="complementary"` | Quando usar `as="aside"` para sidebars |
+| `role="navigation"` | Quando usar `as="nav"` para navegação |
+| `aria-labelledby` | Referencia título do panel |
+| `aria-expanded` | Indica estado de collapse (true/false) |
+| `aria-controls` | Referencia o conteúdo controlado |
+| `aria-label` | Quando não há título visível |
+
+### Suporte a Teclado
+
+| Tecla | Ação |
+|-------|------|
+| `Tab` | Navega para elementos focáveis dentro do panel |
+| `Enter` / `Space` | Ativa botão de toggle quando focado |
+| `Escape` | Pode ser usado para fechar panel overlay (Sheet) |
+
+### Focus Management
+
+```tsx
+// Focus visible apenas para navegação por teclado
+focus-visible:border-ring
+focus-visible:ring-ring/50
+focus-visible:ring-[3px]
+```
+
+### Contraste de Cores
+
+Todos os pares de cores seguem WCAG 2.1 AA (mínimo 4.5:1):
+
+| Variante | Foreground | Background | Ratio |
+|----------|------------|------------|-------|
+| `default` | `--foreground` | `--background` | > 4.5:1 |
+| `subtle` | `--foreground` | `--muted` | > 4.5:1 |
+| `outlined` | `--foreground` | transparent | > 4.5:1 |
+| `elevated` | `--foreground` | `--background` | > 4.5:1 |
+| `inset` | `--foreground` | `--muted/50` | > 4.5:1 |
+
+### Screen Readers
+
+- Use `as="aside"` para sidebars - anuncia como "complementary" landmark
+- Use `as="nav"` para navegação - anuncia como "navigation" landmark
+- Use `as="section"` com `aria-label` para regiões genéricas
+- Adicione `aria-expanded` para indicar estado de collapse
+
+### Reduced Motion
+
+```tsx
+// Respeitar preferência do usuário
+motion-reduce:transition-none
+```
+
+### Comparativo A11y (12 Design Systems)
+
+| Feature | ETUS | React Aria | Radix | Ariakit | Headless | Chakra | MUI | Mantine | AntD | NextUI | Fluent | Carbon |
+|---------|:----:|:----------:|:-----:|:-------:|:--------:|:------:|:---:|:-------:|:----:|:------:|:------:|:------:|
+| ARIA landmarks | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ~ | ✓ | ~ | ~ | ✓ | ✓ |
+| Keyboard navigation | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
+| Focus management | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ~ | ~ | ✓ | ✓ |
+| Screen reader | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ~ | ~ | ✓ | ✓ |
+| Reduced motion | ✓ | ✓ | ✓ | ✓ | ~ | ✓ | ✓ | ✓ | ~ | ~ | ✓ | ✓ |
+| High contrast | ~ | ✓ | ~ | ✓ | - | ~ | ✓ | ~ | ~ | ~ | ✓ | ✓ |
+
+**Legenda:** ✓ = Suporte completo | ~ = Parcial/Manual | - = Não suportado
+
+---
+
+## Exemplos
+
+### Uso Básico
+
+```tsx
+import { Panel, PanelHeader, PanelContent } from "@etus/ui"
+
+function Example() {
+  return (
+    <Panel>
+      <PanelHeader>
+        <h2 className="font-semibold">Título do Panel</h2>
+      </PanelHeader>
+      <PanelContent>
+        <p>Conteúdo do panel aqui.</p>
+      </PanelContent>
+    </Panel>
+  )
+}
+```
+
+### Variantes
+
+```tsx
+import { Panel, PanelHeader, PanelContent } from "@etus/ui"
+
+function VariantsExample() {
+  return (
+    <div className="flex gap-4">
+      <Panel variant="default">
+        <PanelHeader>Default</PanelHeader>
+        <PanelContent>Background com borda</PanelContent>
+      </Panel>
+
+      <Panel variant="subtle">
+        <PanelHeader>Subtle</PanelHeader>
+        <PanelContent>Background muted</PanelContent>
+      </Panel>
+
+      <Panel variant="outlined">
+        <PanelHeader>Outlined</PanelHeader>
+        <PanelContent>Apenas borda</PanelContent>
+      </Panel>
+
+      <Panel variant="elevated">
+        <PanelHeader>Elevated</PanelHeader>
+        <PanelContent>Com sombra</PanelContent>
+      </Panel>
+
+      <Panel variant="inset">
+        <PanelHeader>Inset</PanelHeader>
+        <PanelContent>Shadow interno</PanelContent>
+      </Panel>
+    </div>
+  )
+}
+```
+
+### Tamanhos
+
+```tsx
+import { Panel, PanelContent } from "@etus/ui"
+
+function SizesExample() {
+  return (
+    <div className="flex gap-4">
+      <Panel size="xs"><PanelContent>Extra Small (240px)</PanelContent></Panel>
+      <Panel size="sm"><PanelContent>Small (280px)</PanelContent></Panel>
+      <Panel size="md"><PanelContent>Medium (320px)</PanelContent></Panel>
+      <Panel size="lg"><PanelContent>Large (400px)</PanelContent></Panel>
+      <Panel size="xl"><PanelContent>Extra Large (480px)</PanelContent></Panel>
+    </div>
+  )
+}
+```
+
+### Sidebar de Navegação
+
+```tsx
+import { Panel, PanelHeader, PanelContent, PanelFooter } from "@etus/ui"
+import { Home, Settings, Users, HelpCircle } from "lucide-react"
+
+function Sidebar() {
+  const navItems = [
+    { icon: Home, label: "Início", href: "/" },
+    { icon: Users, label: "Usuários", href: "/users" },
+    { icon: Settings, label: "Configurações", href: "/settings" },
+  ]
+
+  return (
+    <Panel
+      as="aside"
+      variant="subtle"
+      size="sm"
+      position="left"
+      className="h-screen"
+    >
+      <PanelHeader className="border-b">
+        <h1 className="text-lg font-bold">App Name</h1>
+      </PanelHeader>
+
+      <PanelContent scrollable className="flex-1">
+        <nav className="space-y-1 p-2">
+          {navItems.map((item) => (
+            <a
+              key={item.href}
+              href={item.href}
+              className="flex items-center gap-3 px-3 py-2 rounded-md hover:bg-muted/50"
+            >
+              <item.icon className="size-5" />
+              <span>{item.label}</span>
+            </a>
+          ))}
+        </nav>
+      </PanelContent>
+
+      <PanelFooter className="border-t">
+        <a
+          href="/help"
+          className="flex items-center gap-3 px-3 py-2 text-muted-foreground"
+        >
+          <HelpCircle className="size-5" />
+          <span>Ajuda</span>
+        </a>
+      </PanelFooter>
+    </Panel>
+  )
+}
+```
+
+### Panel Colapsável
+
+```tsx
+import { useState } from "react"
+import { Panel, PanelHeader, PanelContent } from "@etus/ui"
+import { Button } from "@etus/ui"
+import { ChevronLeft, ChevronRight } from "lucide-react"
+
+function CollapsiblePanel() {
+  const [collapsed, setCollapsed] = useState(false)
+
+  return (
+    <Panel
+      variant="outlined"
+      size={collapsed ? "xs" : "md"}
+      collapsible
+      collapsed={collapsed}
+      onCollapse={setCollapsed}
+      className="transition-all duration-200"
+    >
+      <PanelHeader className="flex items-center justify-between">
+        {!collapsed && <span className="font-medium">Filtros</span>}
+        <Button
+          variant="ghost"
+          size="icon"
+          onClick={() => setCollapsed(!collapsed)}
+          aria-expanded={!collapsed}
+          aria-label={collapsed ? "Expandir filtros" : "Colapsar filtros"}
+        >
+          {collapsed ? (
+            <ChevronRight className="size-4" />
+          ) : (
+            <ChevronLeft className="size-4" />
+          )}
+        </Button>
+      </PanelHeader>
+
+      {!collapsed && (
+        <PanelContent className="space-y-4 p-4">
+          <div>
+            <label className="text-sm font-medium">Categoria</label>
+            <select className="w-full mt-1 rounded-md border p-2">
+              <option>Todas</option>
+              <option>Categoria 1</option>
+              <option>Categoria 2</option>
+            </select>
+          </div>
+        </PanelContent>
+      )}
+    </Panel>
+  )
+}
+```
+
+### Inspector Panel (Direita)
+
+```tsx
+import { Panel, PanelHeader, PanelContent } from "@etus/ui"
+import { Button, ScrollArea } from "@etus/ui"
+import { X } from "lucide-react"
+
+interface InspectorProps {
+  item: { name: string; properties: Record<string, string> }
+  onClose: () => void
+}
+
+function InspectorPanel({ item, onClose }: InspectorProps) {
+  return (
+    <Panel
+      as="aside"
+      variant="default"
+      size="md"
+      position="right"
+      className="h-full"
+      aria-label="Painel de detalhes"
+    >
+      <PanelHeader className="flex items-center justify-between border-b">
+        <span className="font-medium">{item.name}</span>
+        <Button variant="ghost" size="icon" onClick={onClose} aria-label="Fechar">
+          <X className="size-4" />
+        </Button>
+      </PanelHeader>
+
+      <PanelContent scrollable className="flex-1">
+        <ScrollArea className="h-full">
+          <div className="space-y-4 p-4">
+            {Object.entries(item.properties).map(([key, value]) => (
+              <div key={key}>
+                <label className="text-sm text-muted-foreground">{key}</label>
+                <p className="font-mono text-sm">{value}</p>
+              </div>
+            ))}
+          </div>
+        </ScrollArea>
+      </PanelContent>
+    </Panel>
+  )
+}
+```
+
+### Com Semântica ARIA
+
+```tsx
+import { Panel, PanelHeader, PanelContent } from "@etus/ui"
+
+function AccessiblePanel() {
+  return (
+    <Panel
+      as="section"
+      variant="elevated"
+      aria-labelledby="panel-title"
+    >
+      <PanelHeader>
+        <h2 id="panel-title" className="font-semibold">
+          Configurações de Notificação
+        </h2>
+      </PanelHeader>
+      <PanelContent>
+        <p>Gerencie suas preferências de notificação.</p>
+      </PanelContent>
+    </Panel>
+  )
+}
+```
+
+### Split View com ResizablePanels
+
+```tsx
+import { Panel, PanelContent } from "@etus/ui"
+import { ResizablePanelGroup, ResizablePanel, ResizableHandle } from "@etus/ui"
+
+function SplitView() {
+  return (
+    <ResizablePanelGroup direction="horizontal" className="h-screen">
+      <ResizablePanel defaultSize={25} minSize={15}>
+        <Panel variant="subtle" size="full" className="h-full">
+          <PanelContent className="p-4">
+            <p>Navegação / Lista</p>
+          </PanelContent>
+        </Panel>
+      </ResizablePanel>
+
+      <ResizableHandle />
+
+      <ResizablePanel defaultSize={50}>
+        <Panel variant="default" size="full" className="h-full">
+          <PanelContent className="p-4">
+            <p>Conteúdo Principal</p>
+          </PanelContent>
+        </Panel>
+      </ResizablePanel>
+
+      <ResizableHandle />
+
+      <ResizablePanel defaultSize={25} minSize={15}>
+        <Panel variant="subtle" size="full" className="h-full">
+          <PanelContent className="p-4">
+            <p>Inspector / Detalhes</p>
+          </PanelContent>
+        </Panel>
+      </ResizablePanel>
+    </ResizablePanelGroup>
+  )
+}
+```
+
+### Responsivo com Mobile Drawer
+
+```tsx
+import { useState } from "react"
+import { Panel, PanelHeader, PanelContent } from "@etus/ui"
+import { Sheet, SheetContent, SheetTrigger } from "@etus/ui"
+import { Button } from "@etus/ui"
+import { Menu } from "lucide-react"
+
+function ResponsivePanel() {
+  const panelContent = (
+    <>
+      <PanelHeader className="border-b">
+        <h2 className="font-semibold">Navegação</h2>
+      </PanelHeader>
+      <PanelContent className="p-4">
+        <nav className="space-y-2">
+          <a href="/" className="block p-2 hover:bg-muted rounded">Home</a>
+          <a href="/about" className="block p-2 hover:bg-muted rounded">Sobre</a>
+        </nav>
+      </PanelContent>
+    </>
+  )
+
+  return (
+    <>
+      {/* Desktop: Panel fixo */}
+      <Panel
+        as="aside"
+        variant="subtle"
+        size="sm"
+        position="left"
+        className="hidden md:flex h-screen"
+      >
+        {panelContent}
+      </Panel>
+
+      {/* Mobile: Sheet/Drawer */}
+      <Sheet>
+        <SheetTrigger asChild>
+          <Button variant="ghost" size="icon" className="md:hidden">
+            <Menu className="size-5" />
+          </Button>
+        </SheetTrigger>
+        <SheetContent side="left" className="p-0">
+          <Panel variant="subtle" size="full" className="h-full">
+            {panelContent}
+          </Panel>
+        </SheetContent>
+      </Sheet>
+    </>
+  )
+}
+```
+
+---
+
+## Testes
+
+### Testes Unitários
+
+```tsx
+// Panel.test.tsx
+import { render, screen } from "@testing-library/react"
+import userEvent from "@testing-library/user-event"
+import { describe, expect, it, vi } from "vitest"
+import { Panel, PanelContent, PanelFooter, PanelHeader } from "./Panel"
+
+describe("Panel", () => {
+  it("renders children correctly", () => {
+    render(<Panel>Panel Content</Panel>)
+    expect(screen.getByText("Panel Content")).toBeInTheDocument()
+  })
+
+  it("applies variant classes", () => {
+    render(<Panel variant="elevated" data-testid="panel">Test</Panel>)
+    expect(screen.getByTestId("panel")).toHaveClass("shadow-md")
+  })
+
+  it("has data-slot attribute", () => {
+    render(<Panel data-testid="panel">Test</Panel>)
+    expect(screen.getByTestId("panel")).toHaveAttribute("data-slot", "panel")
+  })
+
+  it("renders as aside element", () => {
+    render(<Panel as="aside">Sidebar</Panel>)
+    expect(screen.getByRole("complementary")).toBeInTheDocument()
+  })
+
+  it("renders as nav element", () => {
+    render(<Panel as="nav">Navigation</Panel>)
+    expect(screen.getByRole("navigation")).toBeInTheDocument()
+  })
+})
+```
+
+### Testes de Interação
+
+```tsx
+describe("Panel interactions", () => {
+  it("handles collapse state", async () => {
+    const handleCollapse = vi.fn()
+    const user = userEvent.setup()
+
+    render(
+      <Panel collapsible collapsed={false} onCollapse={handleCollapse}>
+        <PanelHeader>
+          <button onClick={() => handleCollapse(true)}>Collapse</button>
+        </PanelHeader>
+        <PanelContent>Content</PanelContent>
+      </Panel>
+    )
+
+    await user.click(screen.getByText("Collapse"))
+    expect(handleCollapse).toHaveBeenCalledWith(true)
+  })
+
+  it("sets data-state for collapsible panels", () => {
+    render(
+      <Panel collapsible collapsed={false} data-testid="panel">
+        <PanelContent>Content</PanelContent>
+      </Panel>
+    )
+    expect(screen.getByTestId("panel")).toHaveAttribute("data-state", "expanded")
+  })
+})
+```
+
+### Testes de Acessibilidade
+
+```tsx
+import { axe, toHaveNoViolations } from "jest-axe"
+
+expect.extend(toHaveNoViolations)
+
+describe("Panel accessibility", () => {
+  it("has no accessibility violations", async () => {
+    const { container } = render(
+      <Panel>
+        <PanelHeader>Header</PanelHeader>
+        <PanelContent>Content</PanelContent>
+        <PanelFooter>Footer</PanelFooter>
+      </Panel>
+    )
+    const results = await axe(container)
+    expect(results).toHaveNoViolations()
+  })
+
+  it("aside panel has correct role", async () => {
+    const { container } = render(
+      <Panel as="aside">
+        <PanelHeader>Sidebar</PanelHeader>
+        <PanelContent>Navigation content</PanelContent>
+      </Panel>
+    )
+    expect(screen.getByRole("complementary")).toBeInTheDocument()
+    const results = await axe(container)
+    expect(results).toHaveNoViolations()
+  })
+
+  it("nav panel has correct role", async () => {
+    const { container } = render(
+      <Panel as="nav" aria-label="Main navigation">
+        <PanelContent>
+          <ul>
+            <li><a href="/">Home</a></li>
+          </ul>
+        </PanelContent>
+      </Panel>
+    )
+    expect(screen.getByRole("navigation")).toBeInTheDocument()
+    const results = await axe(container)
+    expect(results).toHaveNoViolations()
+  })
+})
+```
+
+### Testes de Composição
+
+```tsx
+describe("Panel composition", () => {
+  it("renders all compound components", () => {
+    render(
+      <Panel>
+        <PanelHeader data-testid="header">Header</PanelHeader>
+        <PanelContent data-testid="content">Content</PanelContent>
+        <PanelFooter data-testid="footer">Footer</PanelFooter>
+      </Panel>
+    )
+
+    expect(screen.getByTestId("header")).toHaveAttribute("data-slot", "panel-header")
+    expect(screen.getByTestId("content")).toHaveAttribute("data-slot", "panel-content")
+    expect(screen.getByTestId("footer")).toHaveAttribute("data-slot", "panel-footer")
+  })
+
+  it("PanelContent supports scrollable prop", () => {
+    render(
+      <PanelContent scrollable data-testid="content">
+        Long content
+      </PanelContent>
+    )
+    expect(screen.getByTestId("content")).toHaveClass("overflow-auto")
+  })
+})
+```
+
+---
+
+## Roadmap / Features Futuras
+
+Baseado na análise comparativa com 14 design systems, as seguintes features são candidatas para implementação futura:
+
+### Prioridade Alta
+
+| Feature | Referências | Justificativa |
+|---------|-------------|---------------|
+| **Animated collapse** | Fluent UI, Carbon, Ariakit | UX mais fluida para transições |
+| **Responsive breakpoints** | Ant Design, Carbon, Fluent | Colapso automático em mobile |
+| **ResizablePanel integration** | Blueprint, Fluent | Suporte nativo a resize |
+
+### Prioridade Média
+
+| Feature | Referências | Justificativa |
+|---------|-------------|---------------|
+| **Sticky header/footer** | Ant Design, Fluent | Melhor UX para conteúdo longo |
+| **Loading state** | Chakra, MUI | Skeleton durante carregamento |
+| **Draggable** | Blueprint | Reordenação de panels |
+
+### Prioridade Baixa
+
+| Feature | Referências | Justificativa |
+|---------|-------------|---------------|
+| **Floating mode** | Fluent | Panel desacoplado como overlay |
+| **Multi-level panels** | Blueprint PanelStack | Navegação em pilha |
+| **Docking system** | VS Code, Fluent | Layouts avançados de IDE |
+
+### Decisões de Design
+
+| Feature | Recomendação | Justificativa |
+|---------|--------------|---------------|
+| Animations | Usar CSS transitions | Performance e reduced motion |
+| Resize | Integrar com ResizablePanels | Já existe no design system |
+| Mobile | Converter para Sheet | Pattern estabelecido |
+| Multiple panels | Usar Grid/Flex | Composição sobre configuração |
+
+---
+
+## Referências
+
+### Design Systems Analisados
+
+| Design System | Documentação | GitHub |
+|---------------|--------------|--------|
+| **Shadcn/ui** | [Card](https://ui.shadcn.com/docs/components/card) | [shadcn-ui/ui](https://github.com/shadcn-ui/ui) |
+| **Radix UI** | [Box](https://www.radix-ui.com/themes/docs/components/box) | [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** | [Box](https://chakra-ui.com/docs/components/box) | [chakra-ui/chakra-ui](https://github.com/chakra-ui/chakra-ui) |
+| **MUI** | [Paper](https://mui.com/material-ui/react-paper/) | [mui/material-ui](https://github.com/mui/material-ui) |
+| **Mantine** | [Paper](https://mantine.dev/core/paper/) | [mantinedev/mantine](https://github.com/mantinedev/mantine) |
+| **Ant Design** | [Layout](https://ant.design/components/layout/) | [ant-design/ant-design](https://github.com/ant-design/ant-design) |
+| **NextUI** | [Card](https://nextui.org/docs/components/card) | [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** | [Panel](https://react.fluentui.dev/?path=/docs/components-panel) | [microsoft/fluentui](https://github.com/microsoft/fluentui) |
+| **Carbon** | [UI Shell Left Panel](https://carbondesignsystem.com/components/UI-shell-left-panel/code/) | [carbon-design-system/carbon](https://github.com/carbon-design-system/carbon) |
+| **Blueprint** | [Card](https://blueprintjs.com/docs/#core/components/card) | [palantir/blueprint](https://github.com/palantir/blueprint) |
+| **PrimeReact** | [Panel](https://primereact.org/panel/) | [primefaces/primereact](https://github.com/primefaces/primereact) |
+
+### Especificações e Padrões
+
+- [WAI-ARIA APG - Disclosure Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/disclosure/)
+- [WAI-ARIA APG - Landmark Regions](https://www.w3.org/WAI/ARIA/apg/patterns/landmarks/)
+- [WCAG 2.1 Success Criteria](https://www.w3.org/WAI/WCAG21/quickref/)
+- [MDN - aside Element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/aside)
+- [MDN - nav Element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/nav)
+- [MDN - section Element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/section)
+
+### Ferramentas Utilizadas
+
+- [CVA - Class Variance Authority](https://cva.style/docs)
+- [Tailwind CSS](https://tailwindcss.com/docs)
+- [Every Layout - Sidebar](https://every-layout.dev/layouts/sidebar/)
+- [Lucide Icons](https://lucide.dev/icons/)