@softize/opus 18.5.0 → 19.0.0

package/src/ui/docs/content/drawer.md

@@ -1,8 +1,9 @@
 ## Painel lateral de detalhe
 
 Use `Drawer` para abrir detalhes ou edição junto a uma borda, preservando a referência visual da
-tela ao fundo. Para conteúdo curto e centralizado, prefira `Dialog`. Com `side="right"`, o painel
-entra pela direita e pode ser fechado por Esc, pelo overlay ou pelo botão de fechamento.
+tela ao fundo. Para conteúdo curto e centralizado, prefira [`Dialog`](/ui/dialog). Com
+`side="right"`, o painel entra pela direita e pode ser fechado por Esc, pelo overlay ou pelo botão
+de fechamento.
 
 ```tsx preview
 <Drawer>
@@ -23,11 +24,10 @@ entra pela direita e pode ser fechado por Esc, pelo overlay ou pelo botão de fe
 
 ## Edição com ações persistentes
 
-`side` aceita `top`, `right`, `bottom` e `left`. `DrawerFooter` mantém as ações no rodapé;
-`DrawerClose` fecha o painel sem exigir controle manual de estado. Como no `Dialog`, o cabeçalho
-recebe um divisor inferior e o rodapé usa um divisor superior. O corpo preserva o mesmo alinhamento
-horizontal entre título, conteúdo e ações. O fechamento do cabeçalho usa uma ação circular neutra
-e sutil; `closeSize` escolhe entre `xs` e `sm`, com `sm` como padrão.
+`side` aceita `top`, `right`, `bottom` e `left`. `DrawerFooter` mantém as ações no rodapé e
+`DrawerClose` fecha o painel sem exigir controle manual de estado. O corpo preserva o mesmo
+alinhamento horizontal do cabeçalho e do rodapé. O fechamento do cabeçalho usa uma ação circular
+neutra e sutil; `closeSize` escolhe entre `xs` e `sm`, com `sm` como padrão.
 
 ```tsx preview
 <Drawer>
@@ -54,6 +54,86 @@ e sutil; `closeSize` escolhe entre `xs` e `sm`, com `sm` como padrão.
 </Drawer>
 ```
 
+O rodapé usa a mesma faixa sutil do [`Dialog`](/ui/dialog). As duas famílias compartilham a
+anatomia, então um fluxo que começa em um modal e continua em um painel não muda de aparência no
+meio.
+
+## Regiões separadas ou contínuas
+
+`layout` declara a anatomia da superfície inteira e fica em `DrawerContent`; os slots leem esse
+valor e não o recebem. O padrão é `sectioned`: recuo igual nas três regiões, faixa no rodapé e
+divisor entre as regiões vizinhas. É o painel de trabalho, em que o corpo rola sob um cabeçalho e um
+rodapé fixos.
+
+Use `layout="continuous"` quando o painel apresentar um único bloco de leitura e a linha virar
+ruído.
+
+```tsx preview
+<Drawer>
+  <DrawerTrigger asChild>
+    <Button variant="outline">Ver resumo</Button>
+  </DrawerTrigger>
+  <DrawerContent layout="continuous">
+    <DrawerHeader>
+      <DrawerTitle>Resumo da execução</DrawerTitle>
+    </DrawerHeader>
+    <DrawerBody>
+      <p className="text-sm text-muted-foreground">
+        Concluída em 2 minutos, sem falhas registradas.
+      </p>
+    </DrawerBody>
+  </DrawerContent>
+</Drawer>
+```
+
+Os divisores do modo seccionado são derivados da vizinhança: cada região desenha a linha quando há
+uma região do outro lado. Um cabeçalho sem corpo não fecha nada, e um cabeçalho seguido direto de um
+rodapé produz uma linha só. A tela não escreve `border-b` nem `border-t`.
+
+## Mídia, ações e navegação no cabeçalho
+
+O cabeçalho reconhece quatro slots — `DrawerNavigation`, `DrawerMedia`, `DrawerTitle` e
+`DrawerActions` — e posiciona cada um: a navegação abre a linha, a mídia vem antes do título, o
+título ocupa a folga, as ações vão para o extremo oposto e o botão de fechar entra depois delas. Um
+nó que não seja um desses slots interrompe a renderização com um erro; contexto e conteúdo
+pertencem ao `DrawerBody`.
+
+`DrawerMedia` é a moldura de ícone da casa — o mesmo [`IconTile`](/ui/icon-tile) —, útil para
+identificar o tipo do recurso aberto. `DrawerNavigation` carrega o retorno de um fluxo encadeado,
+em que o painel permanece aberto e troca de etapa.
+
+```tsx preview
+<Drawer>
+  <DrawerTrigger asChild>
+    <Button variant="outline">Abrir veículo</Button>
+  </DrawerTrigger>
+  <DrawerContent side="right">
+    <DrawerHeader>
+      <DrawerNavigation>
+        <Button variant="ghost" size="icon-sm" aria-label="Voltar para a lista">
+          <ArrowLeft />
+        </Button>
+      </DrawerNavigation>
+      <DrawerMedia context="primary">
+        <CarFront />
+      </DrawerMedia>
+      <DrawerTitle>ABC-1D23</DrawerTitle>
+      <DrawerActions>
+        <Button variant="ghost" size="icon-sm" aria-label="Mais ações">
+          <Ellipsis />
+        </Button>
+      </DrawerActions>
+    </DrawerHeader>
+    <DrawerBody>
+      <p className="text-sm text-muted-foreground">Histórico de passagens na oficina.</p>
+    </DrawerBody>
+  </DrawerContent>
+</Drawer>
+```
+
+O cabeçalho não recebe descrição: o painel já nomeia o recurso, e o contexto que ajuda a decidir
+aparece no começo do corpo, como texto ou `Alert`.
+
 ## Propriedades de Drawer
 
 | Propriedade    | Tipo                      | Padrão | Descrição                                                          |
@@ -66,12 +146,59 @@ e sutil; `closeSize` escolhe entre `xs` e `sm`, com `sm` como padrão.
 | Propriedade       | Tipo                                     | Padrão    | Descrição                                                                                  |
 | ----------------- | ---------------------------------------- | --------- | ------------------------------------------------------------------------------------------ |
 | `side`            | `'top' \| 'right' \| 'bottom' \| 'left'` | `'right'` | Borda de onde o painel aparece.                                                            |
-| `showCloseButton` | `boolean`                                | `true`    | Inclui a ação de fechamento no header. Desative quando o painel exigir uma ação explícita. |
+| `layout`          | `'continuous' \| 'sectioned'`            | `'sectioned'` | Anatomia da superfície inteira; os slots leem esse valor e não o recebem.              |
+| `showCloseButton` | `boolean`                                | `true`    | Inclui a ação de fechamento no cabeçalho. Desative quando o painel exigir uma ação explícita. |
 | `closeDisabled`   | `boolean`                                | `false`   | Mantém a ação visível e impede fechar enquanto o painel está bloqueado.                    |
-| `closeSize`       | `"xs" \| "sm"`                         | `"sm"`   | Define o tamanho da ação circular de fechar.                                               |
+| `closeSize`       | `"xs" \| "sm"`                           | `"sm"`    | Define o tamanho da ação circular de fechar.                                               |
+
+## Propriedades de DrawerHeader
+
+| Propriedade | Tipo        | Padrão | Descrição                                                                                  |
+| ----------- | ----------- | ------ | ------------------------------------------------------------------------------------------ |
+| `className` | `string`    |        | Ajusta a faixa superior sobre o recuo do layout.                                           |
+| `children`  | `ReactNode` |        | Somente `DrawerNavigation`, `DrawerMedia`, `DrawerTitle` e `DrawerActions`, no máximo um de cada; o fechamento padrão entra depois deles. |
+
+## Propriedades de DrawerMedia
+
+| Propriedade | Tipo                                                                     | Padrão      | Descrição                                                     |
+| ----------- | ------------------------------------------------------------------------ | ----------- | ------------------------------------------------------------- |
+| `size`      | `'xs' \| 'sm' \| 'default' \| 'lg'`                                      | `'sm'`      | Tamanho da moldura e do glifo na escala compartilhada.        |
+| `context`   | `'neutral' \| 'primary' \| 'info' \| 'success' \| 'warning' \| 'danger'` | `'neutral'` | Declara o significado da cor.                                 |
+| `variant`   | `'subtle' \| 'outline'`                                                  | `'subtle'`  | Usa preenchimento tonal ou acrescenta borda.                  |
+| `className` | `string`                                                                 |             | Ajusta a moldura sem substituir a escala.                     |
+| `asChild` | `boolean` | `false` | Cede o elemento para uma marca com visual próprio — um orbe, um logotipo — que ocupa o slot sem ganhar a moldura por cima. |
+
+## Propriedades de DrawerNavigation
+
+| Propriedade | Tipo        | Padrão | Descrição                                             |
+| ----------- | ----------- | ------ | ----------------------------------------------------- |
+| `className` | `string`    |        | Ajusta a região introdutória da linha.                |
+| `children`  | `ReactNode` |        | Retorno de um fluxo encadeado, antes do título.       |
+
+## Propriedades de DrawerActions
+
+| Propriedade | Tipo        | Padrão | Descrição                                                |
+| ----------- | ----------- | ------ | -------------------------------------------------------- |
+| `className` | `string`    |        | Ajusta o agrupamento das ações.                          |
+| `children`  | `ReactNode` |        | Ações da tela no cabeçalho, antes do botão de fechar.    |
+
+## Propriedades de DrawerTitle
+
+| Propriedade | Tipo        | Padrão | Descrição                                                           |
+| ----------- | ----------- | ------ | ------------------------------------------------------------------- |
+| `level`     | `1 \| 2 \| 3 \| 4 \| 5 \| 6` | `h2` da primitiva | Hierarquia do documento. O tamanho vem do `layout`, nunca do nível. |
+| `className` | `string`    |        | Ajusta o título, que trunca quando não cabe na linha.               |
+| `children`  | `ReactNode` |        | Nome do recurso ou da tarefa; nomeia a superfície para leitores de tela. |
 
 ## Propriedades de DrawerBody
 
 `DrawerBody` aceita os atributos de `HTMLDivElement` e ocupa a região flexível e rolável entre
 `DrawerHeader` e `DrawerFooter`. O cabeçalho nomeia o painel; contexto relevante entra no começo
 do corpo como texto ou `Alert`.
+
+## Propriedades de DrawerFooter
+
+| Propriedade | Tipo        | Padrão | Descrição                                                              |
+| ----------- | ----------- | ------ | ---------------------------------------------------------------------- |
+| `className` | `string`    |        | Ajusta a faixa do rodapé, inclusive a distribuição das ações.          |
+| `children`  | `ReactNode` |        | Ações persistentes, normalmente dentro de um `ButtonGroup`.            |

package/src/ui/docs/content/metric-card.md

@@ -45,7 +45,9 @@ apresente dois cards independentes.
   labelAction={
     <Tooltip>
       <TooltipTrigger asChild>
-        <Button size="icon-xs" variant="ghost" aria-label="Sobre Agendados"><Info /></Button>
+        <Button size="icon-xs" variant="ghost" aria-label="Sobre Agendados">
+          <Info />
+        </Button>
       </TooltipTrigger>
       <TooltipContent>Eventos atualmente agendados.</TooltipContent>
     </Tooltip>
@@ -56,7 +58,9 @@ apresente dois cards independentes.
     labelAction: (
       <Tooltip>
         <TooltipTrigger asChild>
-          <Button size="icon-xs" variant="ghost" aria-label="Sobre o período"><Info /></Button>
+          <Button size="icon-xs" variant="ghost" aria-label="Sobre o período">
+            <Info />
+          </Button>
         </TooltipTrigger>
         <TooltipContent>Agendamentos registrados dentro do período.</TooltipContent>
       </Tooltip>
@@ -65,6 +69,38 @@ apresente dois cards independentes.
 />
 ```
 
+## Como filtro ou seleção
+
+Use a ativação controlada quando escolher uma métrica também precisar aplicar um recorte. O card
+expõe o estado por `aria-pressed` e preserva controles complementares, como o tooltip do rótulo,
+sem disparar a ativação.
+
+```tsx preview col
+const [metric, setMetric] = useState('scheduled')
+
+render(
+  <div className="grid grid-cols-2 gap-3">
+    <MetricCard
+      label="Agendados"
+      value="18"
+      active={metric === 'scheduled'}
+      activationLabel="Filtrar por Agendados"
+      onActivate={() => setMetric('scheduled')}
+    />
+    <MetricCard
+      label="Efetivados"
+      value="11"
+      active={metric === 'completed'}
+      activationLabel="Filtrar por Efetivados"
+      onActivate={() => setMetric('completed')}
+    />
+  </div>,
+)
+```
+
+`active`, `activationLabel` e `onActivate` formam uma capacidade única: informe as três propriedades
+para tornar o card ativável. O consumidor continua responsável pelo estado e pelo recorte aplicado.
+
 ## Carregamento
 
 `loading` preserva a geometria do card com placeholders e marca a superfície como ocupada para
@@ -76,22 +112,25 @@ tecnologias assistivas. O contêiner da coleção continua responsável pela men
 
 ## Propriedades de MetricCard
 
-| Propriedade | Tipo | Padrão | Descrição |
-|---|---|---|---|
-| `label` | `ReactNode` | | O nome da medida. |
-| `value` | `ReactNode` | | O valor já formatado pelo consumidor. |
-| `loading` | `boolean` | `false` | Substitui rótulo e valor por skeletons e marca `aria-busy`. |
-| `labelAction` | `ReactNode` | | Controle ao lado do rótulo, como uma explicação em tooltip. |
-| `description` | `ReactNode` | | Contexto que explica recorte, proporção ou significado do valor. |
-| `secondaryMetric` | `MetricCardSecondaryMetric` | | Medida complementar exibida como uma lâmina posterior sob o card principal. |
-| `icon` | `ReactNode` | | Ícone decorativo que identifica a natureza da medida. |
-| `context` | `'neutral' \| 'info' \| 'success' \| 'warning' \| 'danger'` | `'neutral'` | Contexto semântico do ícone; não altera a superfície do card. |
-| `action` | `ReactNode` | | Ação relacionada diretamente à medida. |
+| Propriedade       | Tipo                                                        | Padrão      | Descrição                                                                                          |
+| ----------------- | ----------------------------------------------------------- | ----------- | -------------------------------------------------------------------------------------------------- |
+| `label`           | `ReactNode`                                                 |             | O nome da medida.                                                                                  |
+| `value`           | `ReactNode`                                                 |             | O valor já formatado pelo consumidor.                                                              |
+| `loading`         | `boolean`                                                   | `false`     | Substitui rótulo e valor por skeletons e marca `aria-busy`.                                        |
+| `labelAction`     | `ReactNode`                                                 |             | Controle ao lado do rótulo, como uma explicação em tooltip.                                        |
+| `description`     | `ReactNode`                                                 |             | Contexto que explica recorte, proporção ou significado do valor.                                   |
+| `secondaryMetric` | `MetricCardSecondaryMetric`                                 |             | Medida complementar exibida como uma lâmina posterior sob o card principal.                        |
+| `icon`            | `ReactNode`                                                 |             | Ícone decorativo que identifica a natureza da medida.                                              |
+| `context`         | `'neutral' \| 'info' \| 'success' \| 'warning' \| 'danger'` | `'neutral'` | Contexto semântico do ícone; não altera a superfície do card.                                      |
+| `action`          | `ReactNode`                                                 |             | Ação relacionada diretamente à medida.                                                             |
+| `active`          | `boolean`                                                   |             | Indica se a medida controla o recorte atualmente aplicado. Exige `activationLabel` e `onActivate`. |
+| `activationLabel` | `string`                                                    |             | Nome acessível da ativação. Exige `active` e `onActivate`.                                         |
+| `onActivate`      | `() => void`                                                |             | Ativa a medida como recorte ou seleção. Exige `active` e `activationLabel`.                        |
 
 ## Propriedades de MetricCardSecondaryMetric
 
-| Propriedade | Tipo | Padrão | Descrição |
-|---|---|---|---|
-| `label` | `ReactNode` | | O nome da medida complementar. |
-| `value` | `ReactNode` | | O valor complementar já formatado pelo consumidor. |
-| `labelAction` | `ReactNode` | | Controle próprio ao lado do rótulo, como uma explicação em tooltip. |
+| Propriedade   | Tipo        | Padrão | Descrição                                                           |
+| ------------- | ----------- | ------ | ------------------------------------------------------------------- |
+| `label`       | `ReactNode` |        | O nome da medida complementar.                                      |
+| `value`       | `ReactNode` |        | O valor complementar já formatado pelo consumidor.                  |
+| `labelAction` | `ReactNode` |        | Controle próprio ao lado do rótulo, como uma explicação em tooltip. |

package/src/ui/docs/content/page.md

@@ -17,6 +17,13 @@ introdução podem ser omitidos quando o próprio conteúdo nomeia a página.
 Contadores e outros indicadores pertencem ao
 conteúdo que os explica.
 
+A `Page` é contínua por definição: separar o chrome do conteúdo é trabalho do shell, e não há
+divisores entre regiões para declarar. O `layout` da `Page` não é a anatomia de superfície de
+[`Card`](/ui/card), [`Dialog`](/ui/dialog), [`Drawer`](/ui/drawer) e [`Pane`](/ui/pane) — aqui ele
+decide a ocupação de altura. `flow`, o padrão, deixa a página crescer e a rolagem acontecer na
+janela; `fill` limita a página à altura do shell para que uma região interna, como uma tabela longa
+ou um split, assuma a rolagem.
+
 `PageShell` não inclui sidebar nem inventa breadcrumb. Ele ocupa o painel principal já delimitado e
 mantém a barra com `3.75rem`, mesmo quando o conteúdo muda de estado. Tabs ficam reservados a recortes
 da mesma superfície. Canvas e outros workspaces espaciais imersivos podem usar um shell próprio.
@@ -196,6 +203,7 @@ estado na própria seção com `DataState`, `ActionView`, `ActionList` ou `Alert
 | ----------- | ----------- | ----------- | ----------------------------------------------------------------------------------------------- |
 | `title`     | `ReactNode` |             | O h1 da página.                                                                                 |
 | `actions`   | `ReactNode` |             | Ações contextuais no extremo oposto do cabeçalho. |
+| `layout`    | `'flow' \| 'fill'` | `'flow'` | Ocupação de altura, não anatomia: `fill` limita a página ao shell para que uma região interna role. |
 | `className` | `string`    | `max-w-7xl` | Classes do container para substituir o teto padrão de `80rem`.                                  |
 | `children`  | `ReactNode` |             | O body da página — espaçamento e diagramação são seus.                                          |
 

package/src/ui/docs/content/pane.md

@@ -0,0 +1,250 @@
+## A coluna encaixada em um layout
+
+Use `Pane` para a coluna ou faixa que ocupa uma das posições de um [`Split`](/ui/split): a
+navegação à esquerda, o inspetor à direita, a lista que abre o detalhe ao lado. O `Split` decide a
+relação espacial e o redimensionamento; o `Pane` decide o que existe dentro da área recebida.
+
+No formato mais simples, o pane é uma caixa com recuo e o conteúdo é seu.
+
+```tsx preview
+render(
+  <div className="h-56 overflow-hidden rounded-lg border border-border">
+    <Split>
+      <Pane initialSize="16rem" className="bg-muted/30">
+        <p className="text-sm text-muted-foreground">Navegação.</p>
+      </Pane>
+      <Pane grow>
+        <p className="text-sm text-muted-foreground">Conteúdo.</p>
+      </Pane>
+    </Split>
+  </div>,
+);
+```
+
+## Cabeçalho, corpo e rodapé
+
+Quando a área precisa de regiões fixas e de um corpo que rola, componha os slots. `PaneHeader`
+nomeia a região, `PaneBody` ocupa o espaço restante e concentra a rolagem vertical, e `PaneFooter`
+mantém à vista o que não pode sair da tela.
+
+```tsx preview
+render(
+  <div className="h-72 overflow-hidden rounded-lg border border-border">
+    <Split>
+      <Pane initialSize="18rem">
+        <PaneHeader>
+          <PaneMedia>
+            <MessagesSquare />
+          </PaneMedia>
+          <PaneTitle>Conversas</PaneTitle>
+          <PaneActions>
+            <Button variant="ghost" size="icon-sm" aria-label="Nova conversa">
+              <SquarePen />
+            </Button>
+          </PaneActions>
+        </PaneHeader>
+        <PaneBody className="space-y-1">
+          <p className="text-sm">Revisão do contrato</p>
+          <p className="text-sm text-muted-foreground">Importação de clientes</p>
+          <p className="text-sm text-muted-foreground">Fila de execuções</p>
+        </PaneBody>
+        <PaneFooter>
+          <Button variant="ghost" size="sm">Ver arquivadas</Button>
+        </PaneFooter>
+      </Pane>
+      <Pane grow>
+        <p className="text-sm text-muted-foreground">Conversa selecionada.</p>
+      </Pane>
+    </Split>
+  </div>,
+);
+```
+
+O cabeçalho reconhece quatro slots — `PaneMedia`, `PaneTitle`, `PaneDescription` e `PaneActions` —
+e monta a linha sozinho: mídia, título e descrição de um lado, ações no extremo oposto. A ordem em
+que os slots são escritos não altera a posição, e um nó que não seja um desses slots interrompe a
+renderização com um erro. Conteúdo livre vai para `PaneBody`.
+
+Título e descrição truncam quando a coluna encolhe, em vez de quebrar a altura da faixa.
+
+## Escolher entre seccionado e contínuo
+
+`layout` declara a anatomia da superfície inteira e fica no root; os slots leem esse valor e não o
+recebem. Cada valor é um pacote de recuo, ritmo vertical e divisores.
+
+| Aspecto | `sectioned` (padrão) | `continuous` |
+| --- | --- | --- |
+| Divisores | entre as regiões vizinhas | nenhum |
+| Faixa do cabeçalho | altura fixa de `3.75rem` | acompanha o conteúdo |
+| Ritmo vertical | regiões simétricas | o cabeçalho se aproxima do corpo |
+
+O padrão `sectioned` é o pane de operação: a faixa do cabeçalho tem a mesma altura da barra do
+[`PageShell`](/ui/page), então uma navegação lateral e o chrome da página se alinham na mesma
+linha. Use `continuous` quando o pane for um bloco de leitura contínuo, sem fronteiras a marcar.
+
+Os divisores são derivados da vizinhança: cada região desenha a linha quando há uma região do outro
+lado. Um cabeçalho sem corpo não fecha nada, e um cabeçalho seguido direto de um rodapé produz uma
+linha só. A tela não escreve `border-b` nem `border-t`.
+
+## Recuo do pane e recuo das regiões
+
+`inset` é o respiro interno do pane sem slots: `md` por padrão, com `none`, `sm` e `lg`
+disponíveis. Quando `PaneHeader`, `PaneBody` ou `PaneFooter` são filhos **diretos** do pane, o recuo
+passa a ser de cada região e o `inset` vira `none` sozinho — é o que permite ao divisor alcançar a
+borda da coluna.
+
+O ajuste enxerga só o primeiro nível. Se os slots vierem dentro de outro componente — é o caso da
+`Sidebar`, que traz a superfície e o colapso —, o pane não sabe que eles existem: declare
+`inset="none"` você mesmo, ou a coluna ganha um recuo que empurra o divisor para dentro.
+
+## A matriz de layouts e slots
+
+As regiões são independentes e o recuo se ajusta a cada combinação, nos dois layouts.
+
+```tsx preview col
+render(
+  <div className="grid gap-4 md:grid-cols-2">
+    <div className="h-56 overflow-hidden rounded-lg border border-border">
+      <Pane className="h-full">
+        <PaneHeader>
+          <PaneTitle>Seccionado</PaneTitle>
+          <PaneActions>
+            <Button variant="ghost" size="icon-sm" aria-label="Mais ações">
+              <Ellipsis />
+            </Button>
+          </PaneActions>
+        </PaneHeader>
+        <PaneBody>
+          <p className="text-sm text-muted-foreground">Cabeçalho, corpo e rodapé.</p>
+        </PaneBody>
+        <PaneFooter>
+          <Button variant="ghost" size="sm">Configurações</Button>
+        </PaneFooter>
+      </Pane>
+    </div>
+    <div className="h-56 overflow-hidden rounded-lg border border-border">
+      <Pane layout="continuous" className="h-full">
+        <PaneHeader>
+          <PaneMedia>
+            <ChartNoAxesColumn />
+          </PaneMedia>
+          <PaneTitle>Contínuo com mídia</PaneTitle>
+          <PaneDescription>O espaço separa as regiões.</PaneDescription>
+        </PaneHeader>
+        <PaneBody>
+          <p className="text-sm text-muted-foreground">Sem rodapé e sem divisores.</p>
+        </PaneBody>
+      </Pane>
+    </div>
+    <div className="h-56 overflow-hidden rounded-lg border border-border">
+      <Pane className="h-full">
+        <PaneBody>
+          <p className="text-sm text-muted-foreground">Só corpo: nenhuma fronteira a marcar.</p>
+        </PaneBody>
+      </Pane>
+    </div>
+    <div className="h-56 overflow-hidden rounded-lg border border-border">
+      <Pane className="h-full">
+        <PaneHeader>
+          <PaneMedia context="primary">
+            <Folder />
+          </PaneMedia>
+          <PaneTitle>Sem corpo</PaneTitle>
+        </PaneHeader>
+        <PaneFooter>
+          <Button variant="ghost" size="sm">Ação persistente</Button>
+        </PaneFooter>
+      </Pane>
+    </div>
+  </div>,
+);
+```
+
+## Onde termina o Pane
+
+Três componentes dividem a responsabilidade de uma coluna, e trocá-los de papel é a origem mais
+comum de layout duplicado:
+
+| Componente | Responsabilidade |
+| --- | --- |
+| [`Split`](/ui/split) | Relação espacial entre as áreas e, com `resizable`, o arraste da fronteira. |
+| `Pane` | Tamanho recebido, recuo e as regiões internas: cabeçalho, corpo e rodapé. |
+| [`Sidebar`](/ui/sidebar) | Superfície da navegação lateral e o estado de colapso dos destinos. |
+
+Tamanho inicial, limites e persistência do layout são declarados no `Pane` e operados pelo `Split`
+— a [página do Split](/ui/split) trata deles. Uma `Sidebar` é composta dentro de um `Pane` e usa os
+mesmos slots para o próprio cabeçalho e rodapé; ela não tem regiões próprias.
+
+## Hierarquia do título
+
+`PaneTitle` é um heading. `level` escolhe a hierarquia do documento, de `1` a `6`, com `2` como
+padrão. O tamanho visual vem da família e do `layout`, não do nível, então corrigir a estrutura do
+documento não muda a aparência da faixa.
+
+## Propriedades de Pane
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `layout` | `'continuous' \| 'sectioned'` | `'sectioned'` | Anatomia da superfície inteira; os slots leem esse valor e não o recebem. |
+| `inset` | `'none' \| 'sm' \| 'md' \| 'lg'` | `'md'`, ou `'none'` com slots diretos | Respiro interno do pane sem slots; slots dentro de outro componente exigem declarar. |
+| `id` | `string` | | Identidade estável usada pelo layout redimensionável e persistido. |
+| `initialSize` | `number \| string` | | Tamanho inicial; número é porcentagem, string aceita `%`, `rem`, `em`, `vh`, `vw` e `px`. |
+| `minSize` / `maxSize` | `number \| string` | | Limites aplicados pelo `Split` quando ele é redimensionável. |
+| `grow` | `boolean` | `false` | Ocupa o espaço remanescente no layout simples. |
+| `className` | `string` | | Ajusta a coluna. |
+| `children` | `ReactNode` | | Conteúdo direto ou os slots estruturais. |
+
+## Propriedades de PaneHeader
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `children` | `ReactNode` | | Somente `PaneMedia`, `PaneTitle`, `PaneDescription` e `PaneActions`, no máximo um de cada. |
+| `className` | `string` | | Ajusta a faixa fixa sobre o recuo do layout. |
+
+## Propriedades de PaneMedia
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `size` | `'xs' \| 'sm' \| 'default' \| 'lg'` | `'xs'` | Tamanho da moldura e do glifo na escala compartilhada. |
+| `context` | `'neutral' \| 'primary' \| 'info' \| 'success' \| 'warning' \| 'danger'` | `'neutral'` | Declara o significado da cor. |
+| `variant` | `'subtle' \| 'outline'` | `'subtle'` | Usa preenchimento tonal ou acrescenta borda. |
+| `className` | `string` | | Ajusta a moldura sem substituir a escala. |
+| `asChild` | `boolean` | `false` | Cede o elemento para uma marca com visual próprio — um orbe, um logotipo — que ocupa o slot sem ganhar a moldura por cima. |
+
+## Propriedades de PaneTitle
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `level` | `1 \| 2 \| 3 \| 4 \| 5 \| 6` | `2` | Hierarquia do documento. O tamanho vem do `layout`, nunca do nível. |
+| `className` | `string` | | Ajusta o título, que trunca quando não cabe. |
+
+## Propriedades de PaneDescription
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `children` | `ReactNode` | | Frase curta de apoio sob o título; trunca quando não cabe. |
+| `className` | `string` | | Ajusta a descrição. |
+
+## Propriedades de PaneActions
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `children` | `ReactNode` | | Controles no extremo oposto ao título. |
+| `className` | `string` | | Ajusta o agrupamento das ações. |
+
+## Propriedades de PaneBody
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `children` | `ReactNode` | | Conteúdo que ocupa o espaço entre cabeçalho e rodapé. |
+| `className` | `string` | | Ajusta a região flexível e rolável. |
+
+`PaneContent` continua exportado como alias depreciado de `PaneBody` e sai em uma próxima versão
+maior. Código novo usa `PaneBody`.
+
+## Propriedades de PaneFooter
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `children` | `ReactNode` | | Navegação ou ações que precisam permanecer acessíveis no rodapé. |
+| `className` | `string` | | Ajusta a faixa fixa sobre o recuo do layout. |