@softize/opus 12.11.0 → 13.0.0

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

@@ -1,6 +1,7 @@
-## Básico
+## Escolha em lista
 
-Um componente para toda escolha em lista. As opções são DADO (`options`), não JSX: `{ value, label }` — o `label` é o que o campo mostra, o que a busca casa e o que o leitor de tela lê. O `id` pareia com o `htmlFor` do Label.
+Use `Select` para escolhas em lista. Declare as opções como dados em `options`; `label` é usado no
+campo, na busca e na leitura assistiva. Associe `id` ao `htmlFor` de `Label` em formulários.
 
 ```tsx preview col md
 const [role, setRole] = useState('')
@@ -23,9 +24,10 @@ render(
 )
 ```
 
-## Com busca (searchable)
+## Lista pesquisável
 
-`searchable` transforma o próprio campo na busca: digitou, a lista filtra embaixo (fuzzy do cmdk, casando label, hint e value). É o que resolve a **achabilidade** — a régua é essa, não performance: 200 itens sem busca é embaçado, achar é rolar até cansar.
+Use `searchable` quando a quantidade ou os rótulos dificultarem encontrar uma opção. O próprio
+campo passa a filtrar `label`, `hint` e `value` com a busca do cmdk.
 
 ```tsx preview col md
 const [issue, setIssue] = useState('')
@@ -49,9 +51,11 @@ render(
 )
 ```
 
-## Múltiplo (chips)
+## Seleção múltipla
 
-`multiple` muda o contrato (`value` e `onChange` viram `string[]`): os escolhidos viram chips removíveis e a lista fica aberta pra seleção em sequência. Com a busca vazia, o topo do dropdown oferece Selecionar tudo / Limpar seleção (só no modo client — com filtro ativo ou `onSearch`, "tudo" seria ambíguo).
+Com `multiple`, `value` e `onChange` usam `string[]`. As opções escolhidas aparecem como chips
+removíveis e a lista permanece aberta para escolhas sucessivas. “Selecionar tudo” fica disponível
+somente quando todas as opções estão carregadas localmente e a busca está vazia.
 
 ```tsx preview col md
 const [skills, setSkills] = useState<string[]>(['clean-code'])
@@ -77,9 +81,10 @@ render(
 )
 ```
 
-## Nativo (native)
+## Controle nativo
 
-`native` renderiza o `<select>` do sistema (só com a seta restilizada — a nativa cola na borda e ignora o tema). Ganha o picker do próprio SO: roda de scroll no iOS, teclado do Android, zero JS. Use em **lista curta e sabida** (2–8 itens que a pessoa já conhece: Sim/Não, prioridade, ambiente). Item rico, busca ou multi não existem aqui — pra isso, o modo default.
+Use `native` para uma lista curta e conhecida, como prioridade ou ambiente. O sistema operacional
+controla a interação do `<select>`. Busca, seleção múltipla e conteúdo rico exigem o modo padrão.
 
 ```tsx preview col md
 const [env, setEnv] = useState('preview')
@@ -104,7 +109,8 @@ render(
 
 ## Grupos
 
-`group` na opção agrupa a lista — bloco nomeado nos dois modos (`<optgroup>` no nativo, heading no custom). Pra listas com origens distintas (membros × agentes).
+`group` reúne opções sob um título nos dois modos. Use grupos quando a lista combinar conjuntos com
+origens ou papéis distintos.
 
 ```tsx preview col md
 const [reviewer, setReviewer] = useState('')
@@ -124,9 +130,10 @@ render(
 )
 ```
 
-## Busca server-side
+## Busca no servidor
 
-Com `onSearch` o filtro do cmdk desliga: o pai busca (debounced, ao abrir e ao digitar) e devolve `options`; `loading` mostra Buscando… enquanto o fetch corre. Implica campo buscável (não precisa repetir `searchable`).
+Com `onSearch`, o consumidor consulta as opções ao abrir e ao digitar, com debounce. Atualize
+`options` com a resposta e use `loading` durante a consulta. Esse modo já habilita o campo de busca.
 
 ```tsx preview col md
 const ASSIGNEES = [
@@ -163,7 +170,8 @@ render(
 
 ## Ícone dentro do campo
 
-`icon` põe o ícone DENTRO do controle, antes do texto (e dos chips, no multi) — identifica o campo numa barra de filtros. Ícone AO LADO do campo é o antipadrão: desalinha na quebra de linha e some no responsivo. Vale nos dois modos.
+`icon` posiciona um ícone decorativo antes do texto ou dos chips. Use-o para reforçar a identidade do
+campo sem criar um elemento separado ao lado do controle.
 
 ```tsx preview col-start
 const [task, setTask] = useState('')
@@ -182,9 +190,10 @@ render(
 )
 ```
 
-## Densidade (size)
+## Tamanho
 
-O controle segue a altura do design system: default é h-9 (a mesma do Input e do Button) e `size="sm"` dá h-8 pra barra de filtros/toolbar densa.
+O tamanho padrão acompanha `Input` e `Button`. Use `size="sm"` em barras de filtros e outras
+composições densas.
 
 ```tsx preview col-start
 const [a, setA] = useState('gra-2')
@@ -203,9 +212,10 @@ render(
 )
 ```
 
-## Limpar (clearable)
+## Limpar a seleção
 
-`clearable` põe o X no controle quando há seleção — limpa num clique (single volta a vazio, multi a `[]`), sem abrir a lista. Bom pra filtro, onde "sem valor" é um estado de uso frequente; os filtros do ActionList já vêm assim.
+`clearable` acrescenta uma ação que limpa o valor sem abrir a lista. No modo simples, o valor volta
+a vazio; no múltiplo, volta a `[]`. Os filtros de `ActionList` já habilitam esse comportamento.
 
 ```tsx preview col md
 function Demo() {
@@ -229,9 +239,10 @@ function Demo() {
 render(<Demo />)
 ```
 
-## Item rico (content)
+## Conteúdo rico nas opções
 
-`label` é sempre string (é o que o campo mostra e a busca casa); `content` é o render RICO do item na lista — ícone, avatar, duas linhas. Assim o item pode ser elaborado sem estragar busca nem a11y.
+Mantenha `label` como string para busca e leitura assistiva. Use `content` para acrescentar ícone,
+avatar ou texto complementar à opção apresentada na lista.
 
 ```tsx preview col md
 const [agent, setAgent] = useState('developer')
@@ -271,9 +282,10 @@ render(
 )
 ```
 
-## Barra do composer (variant ghost)
+## Select na barra do Composer
 
-`variant="ghost"` tira moldura e padding: o seletor discreto que vive na barra de ações do Composer/Chat (app, task, agente), à esquerda do enviar. `triggerLabel` na opção encurta o gatilho quando o rótulo da lista é longo (o título inteiro fica só na lista).
+Use `variant="ghost"` para integrar o seletor à barra de ações de `Composer`. `triggerLabel` pode
+encurtar somente o texto do gatilho; a lista continua exibindo o `label` completo.
 
 ```tsx preview col-start
 const [task, setTask] = useState('GB-42')
@@ -292,9 +304,10 @@ render(
 )
 ```
 
-## Ação no fim do campo (trailing)
+## Ação no fim do campo
 
-`trailing` põe uma ação custom DENTRO do controle, no fim (antes do chevron) — um botão que age sobre o valor escolhido, sem virar um irmão solto ao lado do campo. O clique no trailing **não** abre a lista (o slot para a propagação).
+`trailing` posiciona uma ação relacionada ao valor antes do chevron. Interagir com essa região não
+abre a lista.
 
 ```tsx preview col-start
 const [task, setTask] = useState('gra-2')
@@ -318,9 +331,9 @@ render(
 )
 ```
 
-## Props
+## Propriedades de Select
 
-| Prop | Tipo | Default | Descrição |
+| Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
 | `options` | `SelectOption[]` | | As opções: `{ value, label, hint?, content?, triggerLabel?, group?, disabled? }`. |
 | `value` | `string \| string[]` | | O selecionado: string no single, string[] no multiple. |
@@ -328,16 +341,16 @@ render(
 | `native` | `boolean` | `false` | Renderiza o `<select>` do sistema. Exclui busca, multi e ghost (o browser é quem desenha a lista). |
 | `searchable` | `boolean` | `false` | O campo vira busca: filtra a lista enquanto digita. |
 | `multiple` | `boolean` | `false` | Chips removíveis, lista que permanece aberta e Selecionar tudo. |
-| `variant` | `'default' \| 'ghost'` | `'default'` | `ghost` = sem moldura, pra barra do composer. |
+| `variant` | `'default' \| 'ghost'` | `'default'` | `ghost` = sem moldura, para barra do composer. |
 | `placeholder` | `string` | `'Selecione…'` | Texto do campo vazio. |
-| `searchPlaceholder` | `string` | | Placeholder enquanto busca; cai pro `placeholder` se ausente. |
+| `searchPlaceholder` | `string` | | Placeholder enquanto busca; cai para o `placeholder` se ausente. |
 | `emptyText` | `string` | `'Nada encontrado.'` | Mensagem quando a busca não acha nada. |
 | `onSearch` | `(query: string) => void` | | Busca server-side (debounced, ao abrir e ao digitar): desliga o filtro do cmdk — o pai atualiza `options`. |
 | `loading` | `boolean` | | Mostra Buscando… enquanto o fetch corre (use com `onSearch`). |
-| `clearable` | `boolean` | `false` | X no controle quando há seleção — limpa num clique. |
+| `clearable` | `boolean` | `false` | X no controle quando há seleção — limpa em um clique. |
 | `icon` | `React.ReactNode` | | Ícone leading DENTRO do controle (decorativo) — herda `size-4` e o tom muted. |
 | `trailing` | `React.ReactNode` | | Ação custom no FIM do controle (antes do chevron) — o clique não abre a lista. |
-| `size` | `'default' \| 'sm'` | `'default'` | Altura: default (h-9, a do Input e do Button) ou sm (h-8) pra toolbar densa. |
+| `size` | `'default' \| 'sm'` | `'default'` | Altura: default (h-9, a do Input e do Button) ou sm (h-8) para toolbar densa. |
 | `disabled` | `boolean` | `false` | Esmaece e trava o controle. |
-| `id` | `string` | | Vai pro campo — pra parear com o `htmlFor` do Label. |
+| `id` | `string` | | Vai para o campo — para parear com o `htmlFor` do Label. |
 | `className` | `string` | | Classes da raiz do controle, incluindo campo, ícones e ações, em todos os modos. |

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

@@ -1,6 +1,6 @@
-## Horizontal
+## Separar blocos empilhados
 
-Divide blocos empilhados — ocupa a largura toda do contêiner.
+Use a orientação horizontal entre blocos empilhados. A linha ocupa toda a largura disponível.
 
 ```tsx preview col
 <div>
@@ -13,7 +13,7 @@ Divide blocos empilhados — ocupa a largura toda do contêiner.
 
 ## Vertical
 
-Entre itens de uma linha. O vertical herda a altura do contêiner — dê altura à linha (ex.: h-4 no flex).
+Use a orientação vertical entre itens lado a lado. A linha herda a altura do contêiner.
 
 ```tsx preview
 <div className="flex h-4 items-center gap-3 text-sm">
@@ -25,9 +25,9 @@ Entre itens de uma linha. O vertical herda a altura do contêiner — dê altura
 </div>
 ```
 
-## Props
+## Propriedades de Separator
 
-| Prop | Tipo | Default | Descrição |
+| Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
 | `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | Direção da linha. Vertical precisa de altura vinda do contêiner. |
 | `decorative` | `boolean` | `true` | Decorativa some da árvore de acessibilidade. Use false quando a divisão é semântica. |

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

@@ -1,79 +1,348 @@
-## Sidebar
+## Navegação dentro de um layout
 
-`Sidebar` é uma coluna de chrome e navegação. Ela não escolhe a posição: entra em qualquer `Pane` de um `Split`. A mesma forma serve para a sidebar global do app e a navegação interna de Configurações.
+Use `Sidebar` para apresentar navegação global ou contextual em uma coluna lateral. O componente
+organiza a superfície e compartilha o estado de colapso; posição e largura pertencem a um `Pane`
+dentro de `Split`.
+
+O exemplo canônico mantém a largura inicial em `rem`, deixa a navegação rolar e preserva o
+cabeçalho e o rodapé nas extremidades.
 
 ```tsx preview
 render(
-  <div className="h-72 overflow-hidden rounded-lg border border-border">
-    <Split resizable>
-      <Pane initialSize={32} minSize={20} inset="none">
-        <Sidebar divider={false} className="w-full">
-          <PaneHeader className="px-4 py-3 text-sm font-semibold">Projeto</PaneHeader>
+  <div className="h-80 overflow-hidden rounded-lg border border-border">
+    <Split>
+      <Pane initialSize="16rem" inset="none">
+        <Sidebar className="w-full">
+          <PaneHeader className="px-4 py-3 text-sm font-semibold">
+            Projeto
+          </PaneHeader>
           <PaneBody>
             <SidebarNav
-              groups={[{ label: 'Design', items: [{ id: 'preview', label: 'Preview' }, { id: 'code', label: 'Código' }] }]}
-              activeId="preview"
+              groups={[
+                {
+                  label: 'Workspace',
+                  items: [
+                    { id: 'overview', label: 'Visão geral', icon: <LayoutDashboard /> },
+                    { id: 'sessions', label: 'Sessões', icon: <MessagesSquare /> },
+                  ],
+                },
+              ]}
+              activeId="overview"
               onSelect={() => {}}
             />
           </PaneBody>
-          <PaneFooter><span className="text-xs text-muted-foreground">Configurações</span></PaneFooter>
+          <PaneFooter>
+            <SidebarItem label="Configurações" icon={<Settings />} onClick={() => {}} />
+          </PaneFooter>
         </Sidebar>
       </Pane>
-      <Pane grow inset="lg"><p className="text-sm text-muted-foreground">Conteúdo da tela.</p></Pane>
+      <Pane grow inset="lg">
+        <p className="text-sm text-muted-foreground">Conteúdo da página.</p>
+      </Pane>
     </Split>
   </div>,
 )
 ```
 
-## Colapso
-
-`collapsed` pertence à própria `Sidebar`; `SidebarItem`, `SidebarNav` e `ShellNav` adaptam-se automaticamente para botões `size-9` centralizados, ícones e tooltips. `PaneHeader`, `PaneBody` e `PaneFooter` são os slots do pane: a aplicação mantém a identidade e ações que lhe pertencem sem atribuí-las artificialmente à sidebar.
-
-`SidebarItem` também é a linha de árvores de navegação. `actions` e o controle formado por
-`onToggle`/`expanded` são irmãos do botão principal, portanto menus e chevrons não criam
-controles interativos aninhados. No modo recolhido, a linha conserva somente o destino com
-ícone e tooltip. No modo aberto, o chevron ocupa o lugar do ícone da pasta durante o hover da própria linha ou
-foco, e as ações ficam sobrepostas à extremidade direita: controles invisíveis não reduzem o
-espaço disponível para o rótulo. O foco comum no destino não mantém o chevron aberto;
-somente o foco visível no próprio controle o revela para navegação por teclado.
-As ações aparecem no hover da própria linha, no foco visível do próprio controle ou enquanto o menu está
-aberto; focar o destino da linha não revela as reticências.
-O rótulo que não cabe na linha desaparece num gradiente até a borda, em vez de terminar em
-reticências; a linha mede o próprio transbordo, então o rótulo que cabe inteiro fica intacto.
-O foco visível usa o mesmo anel do `Button` (`ring-2 ring-ring/50`), na linha aberta, no botão do
-rail recolhido e no chevron — sem ele a navegação por teclado cairia no anel padrão do navegador,
-que destoa do tema.
-Durante drag-and-drop, `dropPosition="before"` e `"after"` desenham uma linha sobreposta ao
-limite do item; `"inside"` realça a superfície da pasta. O indicador nunca reserva espaço.
-
-Árvores montadas por composição usam `SidebarGroupLabel` para os mesmos rótulos discretos
-que o `SidebarNav` desenha automaticamente. O heading permanece `text-sm`; hierarquia vem
-do peso médio e da cor atenuada, não de reduzir legibilidade.
+Use `resizable` no `Split` somente quando ajustar a largura fizer parte da tarefa. Nesse caso, o
+`Pane` também declara `minSize`, e `divider={false}` evita que `Sidebar` desenhe uma segunda
+divisória ao lado do handle.
+
+## Anatomia e responsabilidades
+
+Cada parte possui uma responsabilidade única. Essa separação permite reutilizar os mesmos slots em
+uma sidebar fixa, redimensionável ou recolhida.
+
+| Parte | Responsabilidade |
+|---|---|
+| `Split` | Define a relação espacial e, opcionalmente, o redimensionamento. |
+| `Pane` | Define largura, limites e espaçamento interno da coluna. |
+| `Sidebar` | Desenha a superfície lateral e fornece o estado de colapso. |
+| `PaneHeader` | Mantém identidade, contexto ou ações no topo. |
+| `PaneBody` | Ocupa o espaço restante e concentra a rolagem vertical. |
+| `PaneFooter` | Mantém ações persistentes no rodapé. |
+| `SidebarNav` ou `ShellNav` | Apresenta e controla os destinos de navegação. |
+
+`PaneContent` permanece como alias temporário de `PaneBody` durante a versão 12. Código novo usa
+`PaneBody`.
+
+## Escolher a navegação
+
+Use `SidebarNav` para grupos planos de destinos. Ele recebe dados e produz `SidebarItem` com a mesma
+semântica usada na composição manual.
+
+```tsx preview
+<div className="h-72 w-64 overflow-hidden rounded-lg border border-border">
+  <Sidebar className="w-full">
+    <PaneBody>
+      <SidebarNav
+        groups={[
+          {
+            label: 'Configurações',
+            items: [
+              { id: 'users', label: 'Usuários', icon: <Users /> },
+              { id: 'roles', label: 'Papéis', icon: <ShieldCheck /> },
+              { id: 'imports', label: 'Importações', icon: <Database /> },
+            ],
+          },
+        ]}
+        activeId="users"
+        onSelect={() => {}}
+      />
+    </PaneBody>
+  </Sidebar>
+</div>
+```
+
+## Compor uma árvore
+
+Uma árvore não pertence ao contrato de `SidebarNav`: profundidade, carregamento e expansão variam
+por produto. Componha cada nó com `SidebarItem`, envolva seus descendentes em `SidebarTreeGroup` e
+mantenha o estado no consumidor. O grupo aplica o recuo e desenha a guia vertical; o destino
+principal e o controle de expansão permanecem irmãos acessíveis.
+
+```tsx preview
+const [open, setOpen] = useState(true)
+
+render(
+  <div className="h-72 w-64 overflow-hidden rounded-lg border border-border">
+    <Sidebar className="w-full">
+      <PaneBody className="p-2">
+        <SidebarGroupLabel>Documentação</SidebarGroupLabel>
+        <SidebarItem
+          label="Componentes"
+          icon={<Folder />}
+          expanded={open}
+          onToggle={() => setOpen((current) => !current)}
+          onClick={() => setOpen((current) => !current)}
+        />
+        {open && (
+          <SidebarTreeGroup>
+            <SidebarItem label="Layout" icon={<Folder />} expanded onToggle={() => {}} onClick={() => {}} />
+            <SidebarTreeGroup>
+              <SidebarItem label="Sidebar" icon={<PanelLeft />} active onClick={() => {}} />
+              <SidebarItem label="Page" icon={<PanelsTopLeft />} onClick={() => {}} />
+            </SidebarTreeGroup>
+          </SidebarTreeGroup>
+        )}
+      </PaneBody>
+    </Sidebar>
+  </div>,
+)
+```
+
+Esse é o padrão usado pelo `DocBrowser`: seções são rótulos, grupos nomeados são nós expansíveis e
+páginas são folhas. Um grupo começa aberto e volta a abrir quando contém a página ativa.
+
+Use `ShellNav` para uma navegação plana que precisa de cabeçalho próprio e grupos ancorados no
+rodapé. Ele gerencia a rolagem internamente e se adapta quando estiver dentro de uma `Sidebar`
+recolhida.
 
 ```tsx
 <Sidebar collapsed={collapsed}>
-  <PaneHeader><MySidebarHeader onToggle={() => setCollapsed(!collapsed)} /></PaneHeader>
-  <PaneBody><SidebarNav groups={groups} activeId={active} onSelect={go} /></PaneBody>
-  <PaneFooter><UserMenu /></PaneFooter>
+  <ShellNav
+    heading={<ShellNavHeading title="Relatórios" action={<CreateReportButton />} />}
+    groups={reportGroups}
+    footer={settingsGroups}
+    activeId={activeId}
+    onSelect={navigateToReport}
+  />
 </Sidebar>
 ```
 
-## Navegação contextual
+## Recolher a coluna
 
-`SidebarNav` aceita grupos e subgrupos. Isso cobre tanto a navegação global quanto seções internas, como Configurações ou documentação, sem outro shell especializado.
+`collapsed` pertence à `Sidebar`. Nesse estado, `SidebarItem`, `SidebarNav` e `ShellNav` mantêm
+somente os ícones e expõem os rótulos em tooltips. Por isso, todo destino que aparece no modo
+recolhido precisa de um ícone reconhecível e de um `label` completo.
 
-```tsx
-<SidebarNav
-  groups={[
-    {
-      label: 'Configurações',
-      subgroups: [
-        { label: 'Acesso', items: [{ id: 'users', label: 'Usuários' }] },
-        { label: 'Dados', items: [{ id: 'imports', label: 'Importações' }] },
-      ],
-    },
-  ]}
-  activeId={active}
-  onSelect={go}
-/>
+```tsx preview
+const [collapsed, setCollapsed] = useState(false)
+
+render(
+  <div className="flex h-64 overflow-hidden rounded-lg border border-border">
+    <Sidebar collapsed={collapsed}>
+      <PaneHeader className="flex h-12 items-center justify-center">
+        <Button
+          variant="ghost"
+          size="icon-sm"
+          aria-label={collapsed ? 'Expandir navegação' : 'Recolher navegação'}
+          onClick={() => setCollapsed((current) => !current)}
+        >
+          <PanelLeftClose className={collapsed ? 'rotate-180' : ''} />
+        </Button>
+      </PaneHeader>
+      <PaneBody>
+        <SidebarNav
+          groups={[
+            {
+              items: [
+                { id: 'home', label: 'Início', icon: <House /> },
+                { id: 'reports', label: 'Relatórios', icon: <ChartNoAxesColumn /> },
+              ],
+            },
+          ]}
+          activeId="home"
+          onSelect={() => {}}
+        />
+      </PaneBody>
+    </Sidebar>
+    <div className="flex-1 p-4 text-sm text-muted-foreground">
+      O conteúdo ocupa o espaço liberado pela sidebar.
+    </div>
+  </div>,
+)
+```
+
+O consumidor controla o estado e decide onde colocar o gatilho. A transição de largura pertence à
+`Sidebar`; a aplicação não precisa trocar a árvore de componentes.
+
+## Itens com expansão e ações
+
+`SidebarItem` mantém o destino principal, a expansão e as ações como controles irmãos. Essa
+estrutura evita botões aninhados e permite que cada controle receba foco de forma independente.
+
+```tsx preview
+<div className="w-72 rounded-lg border border-border p-2">
+  <SidebarItem
+    label="Contratos"
+    icon={<Folder />}
+    expanded
+    onToggle={() => {}}
+    actions={
+      <Button variant="ghost" size="icon-xs" aria-label="Mais ações">
+        <Ellipsis />
+      </Button>
+    }
+    onClick={() => {}}
+  />
+  <SidebarItem
+    label="Criar workspace"
+    icon={<FilePlus2 />}
+    className="pl-6"
+    onClick={() => {}}
+  />
+</div>
 ```
+
+Quando o rótulo não cabe, ele termina em um gradiente. As ações aparecem ao passar o ponteiro, ao
+receber foco visível ou enquanto um menu permanece aberto; como são sobrepostas, não reduzem o
+espaço disponível para o texto.
+
+Para árvores arrastáveis, `dropPosition` comunica o destino visual sem reservar espaço:
+`before` e `after` desenham uma linha na fronteira, enquanto `inside` realça a superfície do item.
+O driver de drag-and-drop continua externo e fornece seus atributos por `dragProps`.
+
+## Acessibilidade
+
+- `activeId` resulta em `aria-current="page"` no destino atual.
+- `navLabel` nomeia a landmark de navegação.
+- O controle de expansão informa `aria-expanded` e recebe um rótulo baseado no item.
+- Itens desabilitados continuam visíveis, mas não respondem à interação.
+- O foco visível usa o anel semântico do tema no destino, nas ações e no controle de expansão.
+- No modo recolhido, o tooltip preserva o nome que deixou de aparecer visualmente.
+
+## Propriedades de Sidebar
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `collapsed` | `boolean` | `false` | Recolhe a coluna e publica esse estado para as navegações descendentes. |
+| `divider` | `boolean` | `true` | Desenha a borda na lateral. Desative quando o `Split` já fornecer o handle. |
+| `className` | `string` | | Ajusta a raiz. A largura externa deve continuar pertencendo ao `Pane`. |
+| `children` | `ReactNode` | | Cabeçalho, corpo, rodapé ou uma navegação que gerencie a própria estrutura. |
+
+## Propriedades de PaneHeader
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `className` | `string` | | Ajusta a faixa fixa e seu espaçamento. |
+| `children` | `ReactNode` | | Identidade, contexto ou ações apresentadas no topo. |
+
+## Propriedades de PaneBody
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `className` | `string` | | Ajusta a região flexível e rolável. |
+| `children` | `ReactNode` | | Conteúdo que ocupa o espaço entre cabeçalho e rodapé. |
+
+## Propriedades de PaneFooter
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `className` | `string` | | Ajusta a faixa fixa e seu espaçamento. |
+| `children` | `ReactNode` | | Navegação ou ações que precisam permanecer acessíveis no rodapé. |
+
+## Propriedades de SidebarNav
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `groups` | `SidebarNavGroup[]` | | Grupos e itens apresentados na ordem recebida. Grupos vazios são omitidos. |
+| `activeId` | `string` | | Identificador do destino atual. |
+| `onSelect` | `(id: string) => void` | | Recebe o identificador selecionado; roteamento permanece com o consumidor. |
+| `navLabel` | `string` | `'Navegação'` | Nome acessível da landmark `nav`. |
+| `className` | `string` | | Ajusta a raiz da navegação. |
+
+### Estrutura de SidebarNavGroup
+
+| Campo | Tipo | Descrição |
+|---|---|---|
+| `label` | `string` | Rótulo opcional do grupo. Rótulos vazios não reservam espaço. |
+| `items` | `SidebarNavItem[]` | Itens diretos do grupo. |
+
+`SidebarNavItem` acrescenta `id` às propriedades de `SidebarItem`. Para mais níveis, componha
+`SidebarItem` e `SidebarTreeGroup` diretamente.
+
+## Propriedades de SidebarItem
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `label` | `string` | | Nome visível do destino e conteúdo do tooltip no modo recolhido. |
+| `icon` | `ReactNode` | | Ícone apresentado antes do rótulo e preservado no modo recolhido. |
+| `badge` | `ReactNode` | | Informação curta no fim da linha, como contagem ou estado. |
+| `active` | `boolean` | `false` | Destaca o destino e aplica `aria-current="page"`. |
+| `disabled` | `boolean` | `false` | Mantém o item visível sem permitir interação. |
+| `actions` | `ReactNode` | | Controles relacionados exibidos no fim da linha. |
+| `onToggle` | `() => void` | | Adiciona o controle independente de expansão. |
+| `expanded` | `boolean` | `false` | Define o estado acessível e a rotação do controle de expansão. |
+| `dropPosition` | `'before' \| 'inside' \| 'after'` | | Indica visualmente onde um item arrastado será solto. |
+| `dragProps` | `HTMLAttributes<HTMLDivElement>` | | Encaminha atributos fornecidos pelo driver de drag-and-drop para a linha. |
+| `tooltipHint` | `ReactNode` | | Acrescenta contexto ao tooltip do modo recolhido. |
+| `className` | `string` | | Ajusta a linha nos estados aberto e recolhido. |
+| `onClick` | `() => void` | | Executa a navegação principal do item. |
+
+## Propriedades de SidebarGroupLabel
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `className` | `string` | | Ajusta o rótulo discreto do grupo. |
+| `children` | `ReactNode` | | Nome do conjunto de destinos. |
+
+## Propriedades de SidebarTreeGroup
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `className` | `string` | | Ajusta o grupo sem substituir o recuo, o espaçamento e a guia vertical padrão. |
+| `children` | `ReactNode` | | Itens ou grupos que descendem do nó anterior. |
+
+## Propriedades de ShellNav
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `groups` | `ShellNavGroup[]` | | Grupos planos exibidos na região rolável. Grupos vazios são omitidos. |
+| `activeId` | `string` | | Identificador do destino atual. |
+| `onSelect` | `(id: string) => void` | | Recebe o identificador selecionado. |
+| `heading` | `ReactNode` | | Conteúdo fixo acima da navegação; fica oculto no modo recolhido. |
+| `footer` | `ShellNavGroup[]` | | Grupos ancorados abaixo da região rolável. |
+| `navLabel` | `string` | `'Navegação'` | Nome acessível da landmark `nav`. |
+| `className` | `string` | | Ajusta a coluna da navegação. A largura vem do contêiner. |
+
+Cada `ShellNavGroup` recebe `label` opcional e `items`. Um `ShellNavItem` declara `id`, `label`,
+`icon`, `badge` e `disabled`.
+
+## Propriedades de ShellNavHeading
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `title` | `ReactNode` | | Título da navegação. |
+| `action` | `ReactNode` | | Ação relacionada apresentada no extremo oposto. |
+| `className` | `string` | | Ajusta a faixa de cabeçalho. |

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

@@ -1,6 +1,7 @@
 ## Linha de lista com avatar
 
-O skeleton imita a forma do conteúdo: círculo pro avatar (rounded-full), barras com a largura aproximada do texto.
+Use `Skeleton` para preservar a forma do conteúdo durante o carregamento. Combine círculos para
+avatares e barras com dimensões próximas às linhas de texto esperadas.
 
 ```tsx preview col
 <div className="flex items-center gap-3">
@@ -14,7 +15,7 @@ O skeleton imita a forma do conteúdo: círculo pro avatar (rounded-full), barra
 
 ## Card em carregamento
 
-O esqueleto reproduz o layout final do card — título, descrição, conteúdo e ações — pra tela não pular quando os dados chegarem.
+O esqueleto reproduz o layout final do card — título, descrição, conteúdo e ações — para tela não pular quando os dados chegarem.
 
 ```tsx preview col
 <Card>