@softize/opus 8.6.6

package/src/ui/components/patterns/page.tsx

@@ -0,0 +1,46 @@
+/**
+ * <Page /> — o esqueleto de página do back-office.
+ *
+ * Padroniza o que toda página repete: <main> + container de largura CHEIA (o caso
+ * comum do back-office; quem quiser estreito passa `className="max-w-5xl"`) + header
+ * (título, descrição e a ação à direita — em geral o botão de criar). O conteúdo é
+ * children, sem nada imposto. Presentacional (sem contrato) de propósito: uma página
+ * agrega N fontes; o que é action-driven mora dentro (ActionList, listas query-backed).
+ */
+
+import type { ReactNode } from 'react'
+import { cn } from '../../lib/cn.ts'
+
+export interface PageProps {
+  title: string
+  /** Total de itens ao lado do título (o estilo do Maestro: mono, esmaecido). */
+  count?: number
+  /** Linha de contexto sob o título. */
+  description?: ReactNode
+  /** Ação à direita do header — em geral o botão de criar. */
+  actions?: ReactNode
+  /** Classes do container. Default: largura cheia; `max-w-5xl` estreita e centra. */
+  className?: string
+  children: ReactNode
+}
+
+export function Page({ title, count, description, actions, className, children }: PageProps): React.ReactElement {
+  return (
+    <main data-slot="page" className="min-w-0 flex-1">
+      <div className={cn('mx-auto px-8 py-8', className)}>
+        {/* As ações alinham com o TÍTULO; a descrição vem abaixo, em linha própria. */}
+        <div data-slot="page-header" className="mb-6">
+          <div className={cn(actions !== undefined && 'flex items-center justify-between gap-4')}>
+            <h1 className="flex items-baseline gap-2 text-2xl font-semibold tracking-tight">
+              {title}
+              {count !== undefined && <span className="font-mono text-base text-muted-foreground/60">{count}</span>}
+            </h1>
+            {actions}
+          </div>
+          {description !== undefined && <p className="mt-1 text-sm text-muted-foreground">{description}</p>}
+        </div>
+        {children}
+      </div>
+    </main>
+  )
+}

package/src/ui/components/patterns/section-shell.tsx

@@ -0,0 +1,246 @@
+/**
+ * <SectionShell /> — o terceiro nível do chrome: uma SEÇÃO com navegação própria.
+ *
+ * O vocabulário de layout tinha dois níveis (AppShell → Page) e faltava o do meio:
+ * seção que agrega N telas irmãs (Configurações, Relatórios, a doc) e quer a lista
+ * DENTRO do conteúdo, não pendurada na sidebar do app. Sem isso, cada seção
+ * redesenhava o mesmo casco `nav + painel` à mão — o DocBrowser, o site do Opus e o
+ * back-office da Empresa X chegaram nas mesmas classes por três caminhos.
+ *
+ * A nav é `w-56` de propósito: mais estreita que o `w-64` do AppShell, pra hierarquia
+ * ficar legível quando as duas aparecem lado a lado.
+ *
+ * Presentacional e CONTROLADO — mesma regra do AppShell: o shell é o quadro. Quem
+ * escolhe o item ativo, o que fazer no clique e o que renderizar no painel é o
+ * consumidor; roteamento (path, querystring, estado) fica de fora por decisão.
+ */
+
+import type { ReactNode } from 'react'
+import { cn } from '../../lib/cn.ts'
+import { ResizableHandle, ResizablePanel, ResizablePanelGroup } from '../primitives/resizable.tsx'
+
+export interface SectionNavItem {
+  /** Coordenada estável do item — é o que volta em `onSelect` e casa com `activeId`.
+   *  Único em TODA a nav (não só no grupo): `activeId` casa por id, então id repetido
+   *  marca dois itens como atuais e o painel não remonta ao alternar entre eles. */
+  id: string
+  label: string
+  /** Ícone à esquerda do label. */
+  icon?: ReactNode
+  /** Selo curto à direita (contagem, `beta`, subpath do SDK…). */
+  badge?: ReactNode
+  /** Visível mas inerte — a tela existe no mapa e ainda não abre. */
+  disabled?: boolean
+}
+
+/** Sub-rótulo DENTRO de um grupo (o 3º nível: sub-pasta na doc, família num catálogo).
+ *  Sai mais fraco e mais indentado que o rótulo do grupo. */
+export interface SectionNavSubgroup {
+  label?: string
+  items: SectionNavItem[]
+}
+
+export interface SectionNavGroup {
+  /** Cabeçalho do grupo. Ausente (ou vazio) = itens soltos, sem rótulo acima. */
+  label?: string
+  /** Itens direto no grupo. */
+  items?: SectionNavItem[]
+  /** Subgrupos rotulados, DEPOIS dos `items` soltos. A maioria das seções não precisa
+   *  — é o nível que a doc usa quando a pasta tem sub-pasta. */
+  subgroups?: SectionNavSubgroup[]
+}
+
+export interface SectionShellProps {
+  /** A navegação da seção: grupos (rotulados ou não) → itens. */
+  groups: SectionNavGroup[]
+  /** `id` do item ativo. Ausente = nenhum destacado (estado vazio, a cargo do consumidor). */
+  activeId?: string
+  onSelect: (id: string) => void
+  /** Topo da nav — título da seção, busca, botão de criar. */
+  navHeader?: ReactNode
+  /** Rodapé da nav, ancorado embaixo. */
+  navFooter?: ReactNode
+  /** Classes da raiz. Default: ocupa a altura disponível (`h-full`). */
+  className?: string
+  /** Classes da COLUNA da nav (o wrapper que empilha header + lista + rodapé), não da
+   *  `<nav>` de dentro. Default: `w-56 shrink-0 border-r`. */
+  navClassName?: string
+  /** Rótulo da landmark `<nav>` — o que o leitor de tela anuncia. Só importa de verdade
+   *  quando o app já tem outra nav na tela (a da sidebar): sem rótulo, as duas viram
+   *  "navigation" e não se distinguem. */
+  navLabel?: string
+  /** O que remonta o painel — e remontar é o que zera o scroll. Default: `activeId`
+   *  (trocar de tela volta ao topo, o esperado). Dois usos legítimos de sobrescrever:
+   *  uma chave CONSTANTE pra NUNCA remontar (a seção preserva o scroll ao trocar de
+   *  item), ou uma chave MAIS FINA que o `activeId` pra remontar também dentro da mesma
+   *  tela (ex.: `${activeId}/${recordId}` numa sub-rota que troca de registro). */
+  scrollResetKey?: string
+  /** Nav REDIMENSIONÁVEL pelo usuário (arrastar a divisa), como o `rail` do AppShell.
+   *  Opt-in: sem isto a nav é a coluna fixa `w-56` de sempre. Ligado, nav e painel viram
+   *  painéis (Resizable) e a largura passa a ser % — o `navClassName` de largura deixa
+   *  de valer (quem manda é `navDefaultSize`). */
+  resizable?: boolean
+  /** Largura inicial (%) da nav quando `resizable`. Default: 18 (≈ o w-56 num 1280). */
+  navDefaultSize?: number
+  /** Largura mínima (%) da nav quando `resizable`. Default: 12. */
+  navMinSize?: number
+  /** O painel: a tela do item ativo (em geral uma `<Page>`), ou o estado vazio. */
+  children: ReactNode
+}
+
+/** Rótulo só existe se tiver texto: vazio (ou só espaço) não vira cabeçalho fantasma —
+ *  a normalização mora AQUI pra não se repetir em cada consumidor. */
+const titled = (label?: string): boolean => (label ?? '').trim() !== ''
+
+/** Idem pro selo: vazio viraria uma pílula com borda e sem texto. `false` é o caso que
+ *  mais aparece — `badge={isBeta && 'beta'}` é idioma corrente. `0` CONTA (contagem
+ *  legítima), então truthy não serve. */
+const shown = (badge: ReactNode): boolean => {
+  if (badge === undefined || badge === null || badge === false || badge === '') return false
+  if (typeof badge === 'number' && Number.isNaN(badge)) return false
+  return !(Array.isArray(badge) && badge.length === 0)
+}
+
+/** Subgrupo só conta se tiver item: `items: []` (uma busca sem match, p.ex.) sairia
+ *  como sub-cabeçalho órfão. */
+const subFilled = (sub: SectionNavSubgroup): boolean => sub.items.length > 0
+
+/** Grupo sem NADA dentro (nem itens, nem subgrupo COM item) não vira `<div>` vazio: ele
+ *  consumiria um degrau do `space-y-5` do pai e abriria um buraco na nav — ou pior,
+ *  deixaria o rótulo do grupo pairando sobre nada. */
+const filled = (group: SectionNavGroup): boolean =>
+  (group.items?.length ?? 0) > 0 || (group.subgroups?.some(subFilled) ?? false)
+
+export function SectionShell({
+  groups,
+  activeId,
+  onSelect,
+  navHeader,
+  navFooter,
+  className,
+  navClassName,
+  navLabel = 'Navegação da seção',
+  scrollResetKey,
+  resizable = false,
+  navDefaultSize = 18,
+  navMinSize = 12,
+  children,
+}: SectionShellProps): React.ReactElement {
+  // `nested`: item de subgrupo ROTULADO — recua sob o rótulo da categoria, senão os três
+  // níveis (seção → categoria → página) sairiam todos na mesma margem.
+  const renderItem = (item: SectionNavItem, nested = false): React.ReactElement => {
+    const active = item.id === activeId
+    return (
+      <button
+        key={item.id}
+        type="button"
+        disabled={item.disabled}
+        // O destaque do ativo é visual; `aria-current` é o que o leitor de tela ouve —
+        // sem ele a nav é uma lista de botões indistintos.
+        aria-current={active ? 'page' : undefined}
+        onClick={() => onSelect(item.id)}
+        className={cn(
+          'flex w-full items-center gap-2 rounded-md py-1.5 pr-2.5 text-left text-sm transition-colors',
+          nested ? 'pl-6' : 'pl-4',
+          'disabled:pointer-events-none disabled:opacity-40',
+          active ? 'bg-muted font-medium text-foreground' : 'text-foreground/80 hover:bg-muted/60',
+        )}
+      >
+        {item.icon}
+        <span className="min-w-0 flex-1 truncate">{item.label}</span>
+        {shown(item.badge) && (
+          <span className="shrink-0 rounded border border-border/60 px-1 font-mono text-[10px] leading-tight text-muted-foreground/60">
+            {item.badge}
+          </span>
+        )}
+      </button>
+    )
+  }
+
+  // `div`, não `aside`: isto só empilha header/nav/rodapé. `aside` abriria uma landmark
+  // `complementary` anônima ao lado da `navigation` — ruído pro leitor de tela, já que a
+  // nav é quem carrega o sentido. Com `resizable`, a largura vem do painel (%), então a
+  // coluna perde o `w-56 shrink-0` e ocupa o painel inteiro.
+  const nav = (
+    <div
+      data-slot="section-shell-nav"
+      className={cn(
+        'flex flex-col border-r border-border',
+        resizable ? 'h-full min-w-0' : 'w-56 shrink-0',
+        navClassName,
+      )}
+    >
+        {navHeader}
+        <nav aria-label={navLabel} className="min-h-0 flex-1 space-y-5 overflow-y-auto px-3 py-5">
+          {/* Chave = POSIÇÃO. Rótulo não serve: ele é opcional e repetível (o catálogo
+              da doc tem DUAS seções com label vazio), e chave duplicada é reconciliação
+              indefinida. Aqui posição é estável e o conteúdo não guarda estado — os
+              botões têm chave própria (o id do item). */}
+          {groups.map((group, gi) =>
+            !filled(group) ? null : (
+              <div key={gi} className="space-y-0.5">
+                {titled(group.label) && (
+                  <div className="px-2.5 pb-1 text-xs font-semibold tracking-tight text-foreground/80">
+                    {group.label}
+                  </div>
+                )}
+                {group.items?.map((item) => renderItem(item))}
+                {group.subgroups?.map((sub, si) =>
+                  !subFilled(sub) ? null : (
+                    <div key={si} className="space-y-0.5">
+                      {titled(sub.label) && (
+                        <div className="pb-0.5 pl-4 pr-2.5 pt-1.5 text-[11px] font-medium text-muted-foreground/50">
+                          {sub.label}
+                        </div>
+                      )}
+                      {sub.items.map((item) => renderItem(item, titled(sub.label)))}
+                    </div>
+                  ),
+                )}
+              </div>
+            ),
+          )}
+      </nav>
+      {navFooter}
+    </div>
+  )
+
+  // key: trocar de tela remonta o painel — é o que zera o scroll (senão a tela nova abre
+  // na altura em que a anterior estava).
+  const main = (
+    <div
+      key={scrollResetKey ?? activeId}
+      data-slot="section-shell-main"
+      className={cn('min-h-0 overflow-y-auto', resizable ? 'h-full' : 'flex-1')}
+    >
+      {children}
+    </div>
+  )
+
+  // Redimensionável: nav e painel viram painéis com divisa arrastável — o mesmo
+  // mecanismo do `rail` do AppShell, agora no terceiro nível do chrome.
+  if (resizable) {
+    return (
+      <ResizablePanelGroup
+        orientation="horizontal"
+        data-slot="section-shell"
+        className={cn('h-full min-h-0', className)}
+      >
+        <ResizablePanel defaultSize={navDefaultSize} minSize={navMinSize}>
+          {nav}
+        </ResizablePanel>
+        <ResizableHandle />
+        <ResizablePanel defaultSize={100 - navDefaultSize} minSize={30}>
+          {main}
+        </ResizablePanel>
+      </ResizablePanelGroup>
+    )
+  }
+
+  return (
+    <div data-slot="section-shell" className={cn('flex h-full min-h-0', className)}>
+      {nav}
+      {main}
+    </div>
+  )
+}

package/src/ui/components/patterns/shell-nav.tsx

@@ -0,0 +1,150 @@
+/**
+ * <ShellNav /> — o menu como primitivo PIVOTÁVEL. Um nav (grupos → itens, com heading e
+ * âncora inferior) que serve os DOIS lares do chrome sem flag:
+ *
+ *   - na sidebar do <AppShell>  → recolhe pra ícone-só (com tooltip) quando a sidebar
+ *     recolhe, sozinho. Sabe que está NA sidebar (e se ela recolheu) pelo contexto de
+ *     slot do AppShell (`useSidebarSlot`) — o app não passa isso em duas mãos.
+ *   - dentro do conteúdo (o que o <SectionShell> faz) → sempre expandido (fora da sidebar,
+ *     `useSidebarSlot` é null).
+ *
+ * "Tanto faz onde": o componente se adapta ao lugar, sem "modo" configurado.
+ *
+ * Presentacional e CONTROLADO — o app é dono do `activeId`, do clique e do roteamento.
+ * v1 PLANA (grupos → itens); aninhamento (accordion/pasta) e DnD COMPOSTO entram quando o
+ * primeiro consumidor de árvore migrar — ver `docs/shellnav.md`.
+ */
+
+import type { ReactNode } from 'react'
+import { cn } from '../../lib/cn.ts'
+import { useSidebarSlot } from './app-shell.tsx'
+import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from '../primitives/tooltip.tsx'
+
+export interface ShellNavItem {
+  /** Coordenada estável — volta em `onSelect` e casa com `activeId`. Único em toda a nav. */
+  id: string
+  label: string
+  /** Ícone à esquerda (é o que sobra no modo recolhido — vira o alvo, com o label no tooltip). */
+  icon?: ReactNode
+  /** Selo à direita (contagem, `beta`). Some no recolhido. */
+  badge?: ReactNode
+  /** Visível mas inerte. */
+  disabled?: boolean
+}
+
+export interface ShellNavGroup {
+  /** Cabeçalho do grupo. Ausente/vazio = itens soltos, sem rótulo. Some no recolhido. */
+  label?: string
+  items: ShellNavItem[]
+}
+
+export interface ShellNavProps {
+  groups: ShellNavGroup[]
+  /** `id` do item ativo. Ausente = nenhum destacado. */
+  activeId?: string
+  onSelect: (id: string) => void
+  /** Topo do nav — título, busca, botão (ex.: o "+" do Relatórios). Some no recolhido. Ver <ShellNavHeading>. */
+  heading?: ReactNode
+  /** Grupos ANCORADOS embaixo (ex.: Configurações no app), mesmo renderer, separados por filete. */
+  footer?: ShellNavGroup[]
+  /** Rótulo da landmark `<nav>`. */
+  navLabel?: string
+  /** Classes da raiz (a coluna). A LARGURA vem do lar (sidebar do AppShell / SectionShell). */
+  className?: string
+}
+
+/** Rótulo só existe se tiver texto — vazio não vira cabeçalho fantasma. */
+const titled = (label?: string): boolean => (label ?? '').trim() !== ''
+
+/** Selo vazio não vira pílula sem texto. `0` conta (contagem legítima). */
+const shown = (badge: ReactNode): boolean => {
+  if (badge === undefined || badge === null || badge === false || badge === '') return false
+  if (typeof badge === 'number' && Number.isNaN(badge)) return false
+  return !(Array.isArray(badge) && badge.length === 0)
+}
+
+/** Grupo sem item não abre buraco no `space-y` nem deixa rótulo pairando sobre nada. */
+const filled = (group: ShellNavGroup): boolean => group.items.length > 0
+
+function renderItem(item: ShellNavItem, activeId: string | undefined, onSelect: (id: string) => void, railed: boolean): React.ReactElement {
+  const active = item.id === activeId
+  const button = (
+    <button
+      type="button"
+      disabled={item.disabled}
+      aria-current={active ? 'page' : undefined}
+      onClick={() => onSelect(item.id)}
+      className={cn(
+        'flex w-full items-center gap-2.5 rounded-md py-1.5 text-left text-sm transition-colors',
+        'disabled:pointer-events-none disabled:opacity-40',
+        railed ? 'justify-center px-0' : 'px-2.5',
+        active ? 'bg-muted font-medium text-foreground' : 'text-foreground/80 hover:bg-muted/60',
+      )}
+    >
+      {item.icon !== undefined && <span className="flex shrink-0">{item.icon}</span>}
+      {!railed && <span className="min-w-0 flex-1 truncate">{item.label}</span>}
+      {!railed && shown(item.badge) && <span className="shrink-0">{item.badge}</span>}
+    </button>
+  )
+  if (!railed) return <div key={item.id}>{button}</div>
+  // Recolhido: o label migra pro tooltip (à direita) — sem ele, a coluna vira ícones adivinháveis.
+  return (
+    <Tooltip key={item.id}>
+      <TooltipTrigger asChild>{button}</TooltipTrigger>
+      <TooltipContent side="right">{item.label}</TooltipContent>
+    </Tooltip>
+  )
+}
+
+function renderGroup(group: ShellNavGroup, gi: number, activeId: string | undefined, onSelect: (id: string) => void, railed: boolean): React.ReactElement | null {
+  if (!filled(group)) return null
+  return (
+    <div key={gi} className="space-y-0.5">
+      {!railed && titled(group.label) && (
+        <div className="px-2.5 pb-1 text-xs font-medium text-muted-foreground/70">{group.label}</div>
+      )}
+      {group.items.map((item) => renderItem(item, activeId, onSelect, railed))}
+    </div>
+  )
+}
+
+export function ShellNav({ groups, activeId, onSelect, heading, footer, navLabel = 'Navegação', className }: ShellNavProps): React.ReactElement {
+  // Recolhe SÓ na sidebar recolhida (o contexto de slot é null no conteúdo → sempre expandido).
+  const railed = useSidebarSlot()?.collapsed ?? false
+
+  const body = (
+    <div data-slot="shell-nav" className={cn('flex h-full min-h-0 flex-col', className)}>
+      {!railed && heading}
+      <nav aria-label={navLabel} className={cn('min-h-0 flex-1 space-y-4 overflow-y-auto p-2', railed && 'px-1.5')}>
+        {groups.map((group, gi) => renderGroup(group, gi, activeId, onSelect, railed))}
+      </nav>
+      {footer !== undefined && footer.some(filled) && (
+        <div className={cn('space-y-4 border-t border-border p-2', railed && 'px-1.5')}>
+          {footer.map((group, gi) => renderGroup(group, gi, activeId, onSelect, railed))}
+        </div>
+      )}
+    </div>
+  )
+
+  // Recolhido usa tooltips — garante um provider (nested é ok se o app já tem um).
+  return railed ? <TooltipProvider delayDuration={200}>{body}</TooltipProvider> : body
+}
+
+export interface ShellNavHeadingProps {
+  /** Título da seção. */
+  title: ReactNode
+  /** Ação à direita — em geral um botão (o "+" de criar). */
+  action?: ReactNode
+  className?: string
+}
+
+/** Cabeçalho padrão do ShellNav: título + espaço pra um botão. É o gesto que hoje cada
+ *  nav monta à mão (o "+" do Relatórios, o título de Configurações). */
+export function ShellNavHeading({ title, action, className }: ShellNavHeadingProps): React.ReactElement {
+  return (
+    <div className={cn('flex h-12 shrink-0 items-center gap-1.5 border-b border-border px-4', className)}>
+      <span className="min-w-0 flex-1 truncate text-sm font-semibold">{title}</span>
+      {action !== undefined && <span className="shrink-0">{action}</span>}
+    </div>
+  )
+}

package/src/ui/components/patterns/sidebar.tsx

@@ -0,0 +1,89 @@
+import { createContext, useContext, type ReactNode } from 'react'
+import { cn } from '../../lib/cn.ts'
+import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from '../primitives/tooltip.tsx'
+
+interface SidebarContextValue { collapsed: boolean }
+const SidebarContext = createContext<SidebarContextValue | null>(null)
+
+export interface SidebarProps {
+  collapsed?: boolean
+  /** Desliga a borda quando o Split já desenha a divisória. */
+  divider?: boolean
+  className?: string
+  children: ReactNode
+}
+
+/** Moldura composicional de uma barra lateral; o Split decide a posição, Sidebar o chrome. */
+export function Sidebar({ collapsed = false, divider = true, className, children }: SidebarProps): React.ReactElement {
+  return (
+    <SidebarContext.Provider value={{ collapsed }}>
+      <aside data-slot="sidebar" data-collapsed={String(collapsed)} className={cn('group/sidebar flex h-full min-h-0 shrink-0 flex-col transition-[width] duration-200 ease-out', divider && 'border-r border-border', collapsed ? 'w-14' : 'w-64', className)}>
+        {children}
+      </aside>
+    </SidebarContext.Provider>
+  )
+}
+
+/** Faixa fixa no topo de um pane — marca, contexto ou ações locais. */
+export function PaneHeader({ className, children }: { className?: string; children: ReactNode }): React.ReactElement {
+  return <div data-slot="pane-header" className={cn('shrink-0 border-b border-border', className)}>{children}</div>
+}
+
+/** Região rolável que ocupa o espaço restante de um pane. */
+export function PaneContent({ className, children }: { className?: string; children: ReactNode }): React.ReactElement {
+  return <div data-slot="pane-content" className={cn('min-h-0 flex-1 overflow-y-auto', className)}>{children}</div>
+}
+
+/** Faixa fixa no rodapé de um pane para ações persistentes. */
+export function PaneFooter({ className, children }: { className?: string; children: ReactNode }): React.ReactElement {
+  return <div data-slot="pane-footer" className={cn('shrink-0 border-t border-border p-2', className)}>{children}</div>
+}
+
+/** @deprecated Use PaneHeader. */
+export const SidebarHeader = PaneHeader
+/** @deprecated Use PaneContent. */
+export const SidebarContent = PaneContent
+/** @deprecated Use PaneFooter. */
+export const SidebarFooter = PaneFooter
+
+export interface SidebarItemProps {
+  label: string
+  icon?: ReactNode
+  badge?: ReactNode
+  active?: boolean
+  disabled?: boolean
+  onClick: () => void
+}
+
+/** Item de navegação que se adapta ao colapso da Sidebar em que está. */
+export function SidebarItem({ label, icon, badge, active = false, disabled = false, onClick }: SidebarItemProps): React.ReactElement {
+  const collapsed = useContext(SidebarContext)?.collapsed ?? false
+  const button = (
+    <button type="button" disabled={disabled} aria-current={active ? 'page' : undefined} onClick={onClick} className={cn('flex items-center gap-2.5 rounded-md transition-colors', 'disabled:pointer-events-none disabled:opacity-40', collapsed ? 'mx-auto size-9 justify-center p-0' : 'w-full px-2.5 py-1.5 text-left text-sm', active ? 'bg-muted font-medium text-foreground' : 'text-foreground/80 hover:bg-muted/60')}>
+      {icon !== undefined && <span className="flex shrink-0">{icon}</span>}
+      {!collapsed && <span className="min-w-0 flex-1 truncate">{label}</span>}
+      {!collapsed && badge !== undefined && <span className="shrink-0">{badge}</span>}
+    </button>
+  )
+  if (!collapsed) return button
+  return <Tooltip><TooltipTrigger asChild>{button}</TooltipTrigger><TooltipContent side="right">{label}</TooltipContent></Tooltip>
+}
+
+export interface SidebarNavGroup {
+  label?: string
+  items: Array<Omit<SidebarItemProps, 'active' | 'onClick'> & { id: string }>
+}
+
+/** Navegação controlada para Sidebar. Header/footer continuam slots explícitos do pai. */
+export function SidebarNav({ groups, activeId, onSelect, navLabel = 'Navegação', className }: { groups: SidebarNavGroup[]; activeId?: string; onSelect: (id: string) => void; navLabel?: string; className?: string }): React.ReactElement {
+  const collapsed = useContext(SidebarContext)?.collapsed ?? false
+  const body = (
+    <nav aria-label={navLabel} data-slot="sidebar-nav" className={cn('space-y-4 p-2', className)}>
+      {groups.map((group, gi) => <div key={gi} className="space-y-0.5">
+        {!collapsed && group.label?.trim() && <div className="px-2.5 pb-1 text-xs font-medium text-muted-foreground/70">{group.label}</div>}
+        {group.items.map(({ id, ...item }) => <SidebarItem key={id} {...item} active={id === activeId} onClick={() => onSelect(id)} />)}
+      </div>)}
+    </nav>
+  )
+  return collapsed ? <TooltipProvider delayDuration={200}>{body}</TooltipProvider> : body
+}

package/src/ui/components/patterns/split.tsx

@@ -0,0 +1,93 @@
+import { Children, isValidElement, type CSSProperties, type ReactElement, type ReactNode } from 'react'
+import { cn } from '../../lib/cn.ts'
+import { ResizableHandle, ResizablePanel, ResizablePanelGroup } from '../primitives/resizable.tsx'
+
+export interface PaneProps {
+  /** Fração inicial do split, em %. O pane que cresce recebe o restante. */
+  initialSize?: number
+  /** Fração mínima, em %, quando o split é redimensionável. */
+  minSize?: number
+  /** Fração máxima, em %, quando o split é redimensionável. */
+  maxSize?: number
+  /** Ocupa o espaço remanescente no layout simples. */
+  grow?: boolean
+  /** Respiro interno padrão. Use `none` para chrome, navegação ou conteúdo com inset próprio. */
+  inset?: 'none' | 'sm' | 'md' | 'lg'
+  className?: string
+  children: ReactNode
+}
+
+/** Um conteúdo encaixável. Sua posição é dada pela ordem dentro de <Split>. */
+export function Pane({ initialSize, grow = false, inset = 'md', className, children }: PaneProps): React.ReactElement {
+  const style: CSSProperties | undefined = initialSize === undefined ? undefined : { flexBasis: `${initialSize}%` }
+  const insets = { none: '', sm: 'p-2', md: 'p-4', lg: 'p-6' } as const
+  return (
+    <div data-slot="pane" data-inset={inset} className={cn('min-h-0 min-w-0 shrink-0', grow && 'flex-1', insets[inset], className)} style={style}>
+      {children}
+    </div>
+  )
+}
+
+export interface SplitProps {
+  direction?: 'horizontal' | 'vertical'
+  /** Quando ligado, cada fronteira ganha um handle e os tamanhos passam a ser percentuais. */
+  resizable?: boolean
+  handle?: boolean
+  className?: string
+  children: ReactNode
+}
+
+function panesOf(children: ReactNode): ReactElement<PaneProps>[] {
+  return Children.toArray(children).filter(
+    (child): child is ReactElement<PaneProps> => isValidElement<PaneProps>(child) && child.type === Pane,
+  )
+}
+
+// react-resizable-panels v4 interpreta `number` como pixels. O contrato de Split/Pane
+// é percentual (e o layout flex simples abaixo também usa `%`), então a unidade precisa
+// ser explícita na fronteira com o primitive.
+function percent(value: number | undefined): string | undefined {
+  return value === undefined ? undefined : `${value}%`
+}
+
+/**
+ * Relação espacial mínima: uma sequência de panes, horizontal ou vertical. Usa flex
+ * quando fixa e o primitive Resizable quando `resizable`; quem consome não troca de
+ * modelo de layout para ganhar arraste.
+ */
+export function Split({ direction = 'horizontal', resizable = false, handle = false, className, children }: SplitProps): React.ReactElement {
+  const panes = panesOf(children)
+  const vertical = direction === 'vertical'
+
+  if (!resizable) {
+    return (
+      <div data-slot="split" data-direction={direction} className={cn('flex min-h-0 min-w-0 flex-1', vertical && 'flex-col', className)}>
+        {panes}
+      </div>
+    )
+  }
+
+  const fixed = panes.reduce((sum, pane) => sum + (pane.props.initialSize ?? 0), 0)
+  const growing = panes.filter((pane) => pane.props.grow)
+  const rest = Math.max(0, 100 - fixed)
+  const fallback = panes.length === 0 ? 100 : 100 / panes.length
+
+  return (
+    <ResizablePanelGroup orientation={direction} data-slot="split" className={cn('min-h-0 min-w-0 flex-1', className)}>
+      {panes.flatMap((pane, index) => {
+        const size = pane.props.initialSize ?? (pane.props.grow ? rest / Math.max(1, growing.length) : fallback)
+        const panel = (
+          <ResizablePanel
+            key={pane.key ?? index}
+            defaultSize={percent(size)}
+            minSize={percent(pane.props.minSize)}
+            maxSize={percent(pane.props.maxSize)}
+          >
+            <Pane {...pane.props} className={cn('h-full w-full', pane.props.className)} />
+          </ResizablePanel>
+        )
+        return index === 0 ? [panel] : [<ResizableHandle key={`handle-${pane.key ?? index}`} withHandle={handle} />, panel]
+      })}
+    </ResizablePanelGroup>
+  )
+}