@softize/opus 12.11.0 → 13.0.0

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

@@ -1,6 +1,8 @@
-## Básico
+## Informação complementar
 
-Texto auxiliar, nunca essencial — quem navega por toque não vê tooltip. Em botão só de ícone, o aria-label continua obrigatório.
+Use `Tooltip` para informação curta e complementar. Como a dica não está disponível em todas as
+formas de interação, ela não pode conter informação essencial. Botões somente com ícone continuam
+precisando de `aria-label`.
 
 ```tsx preview
 <Tooltip>
@@ -13,7 +15,7 @@ Texto auxiliar, nunca essencial — quem navega por toque não vê tooltip. Em b
 
 ## Lados
 
-side escolhe o lado preferido; o Radix inverte sozinho quando falta espaço.
+`side` define o lado preferido; o Radix reposiciona a dica quando não há espaço.
 
 ```tsx preview
 <Tooltip>
@@ -30,9 +32,10 @@ side escolhe o lado preferido; o Radix inverte sozinho quando falta espaço.
 </Tooltip>
 ```
 
-## Provider no root
+## Provider na raiz
 
-O TooltipProvider embrulha o app uma vez (delay compartilhado); cada Tooltip dispensa provider próprio. Este app já monta o seu no main.tsx.
+Monte um único `TooltipProvider` na raiz para compartilhar o atraso de exibição. Cada `Tooltip` não
+precisa de um provider próprio.
 
 ```tsx
 /* main.tsx do app — uma vez, no root. */
@@ -54,11 +57,16 @@ default nos formulários.
 </Tooltip>
 ```
 
-## Props
+## Propriedades de TooltipProvider
 
-| Prop | Tipo | Default | Descrição |
+| Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
-| `TooltipProvider.delayDuration` | `number` | `0` | Atraso (ms) até aparecer — compartilhado por todos os tooltips do app. |
-| `TooltipContent.side` | `'top' \| 'right' \| 'bottom' \| 'left'` | `'top'` | Lado preferido; inverte sozinho sem espaço (Radix). |
-| `TooltipContent.sideOffset` | `number` | `0` | Distância (px) entre gatilho e dica. |
-| `TooltipContent.className` | `string` | `max-w-sm text-pretty` | Permite substituir o limite e a distribuição de linha quando necessário. |
+| `delayDuration` | `number` | `0` | Atraso antes da exibição, compartilhado pelos tooltips do aplicativo. |
+
+## Propriedades de TooltipContent
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `side` | `'top' \| 'right' \| 'bottom' \| 'left'` | `'top'` | Lado preferido; o Radix reposiciona a dica quando não há espaço. |
+| `sideOffset` | `number` | `0` | Distância entre o gatilho e a dica. |
+| `className` | `string` | `max-w-sm text-pretty` | Classes para ajustar o limite e a distribuição do texto. |

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

@@ -1,8 +1,7 @@
-## Básico
+## Truncar somente quando necessário
 
-Trunca numa linha e mostra tooltip **só quando o texto realmente corta** (medição do
-overflow, re-medida em resize). Texto que cabe não ganha dica — diferente do `title`
-sempre presente, que vira ruído.
+Use `Truncate` para limitar um texto a uma linha e mostrar a dica somente quando houver transbordo.
+O componente mede novamente o conteúdo quando o tamanho muda. Se o texto couber, não cria tooltip.
 
 ```tsx preview
 <div className="w-48 rounded-md border p-2">
@@ -10,9 +9,9 @@ sempre presente, que vira ruído.
 </div>
 ```
 
-## Quando cabe, nada acontece
+## Texto sem transbordo
 
-O mesmo componente, com espaço de sobra: sem tooltip, sem atributo, só o texto.
+Quando há espaço suficiente, o componente mantém apenas o texto visível.
 
 ```tsx preview
 <div className="w-96 rounded-md border p-2">
@@ -48,8 +47,8 @@ const { ref, overflowing } = useOverflowing<HTMLSpanElement>(label)
 
 ## Conteúdo da dica
 
-`tooltip` sobrepõe o conteúdo mostrado no hover (default: os próprios children) — útil
-quando a dica precisa de mais contexto que o texto cortado.
+`tooltip` substitui o conteúdo da dica, cujo padrão são os próprios `children`. Use essa propriedade
+quando o texto completo ainda não oferecer contexto suficiente.
 
 ```tsx preview
 <div className="w-48 rounded-md border p-2">

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

@@ -4,21 +4,22 @@ title: Como consumir
 
 # Como consumir a UI
 
-A verdade visual da casa: os componentes do `@softize/opus/ui` renderizados com o nosso tema. O
-que você vê aqui é o que os apps entregam — a referência é esta doc, não o site do shadcn.
+Esta documentação é a referência visual e de uso de `@softize/opus/ui`. Os exemplos são renderizados
+com o tema e o contrato entregues aos aplicativos.
 
 ## Por que esta doc existe
 
-> O site do shadcn é catálogo do que existe lá; os exemplos de lá decoram composições que não
-> existem no nosso registry. A expectativa visual e de uso nasce aqui.
+O catálogo do shadcn documenta seu próprio código e pode mostrar composições que não fazem parte do
+Opus. Consulte estas páginas para conhecer os componentes, as variações e os comportamentos
+suportados pelo pacote.
 
-Cada página de componente mostra exemplos vivos por variante (renderizados com o tema da casa), o
-snippet de como se escreve e as props que importam. O texto de quando usar vem do próprio
-componente (o `meta` co-localizado na fonte) — a doc deriva, não duplica.
+Cada página combina exemplos vivos, código e uma referência de propriedades por componente. A
+orientação inicial vem de `componentMeta`, a mesma fonte usada pelo catálogo e pelas ferramentas.
 
 ## Como consumir
 
-> Um barrel só pra componentes e hooks; o tema entra por CSS. Nada de copiar componente pra dentro do app.
+Importe componentes e hooks de `@softize/opus/ui/react` e o tema por CSS. Não copie a implementação
+para o aplicativo quando a API pública já atender ao caso.
 
 ```tsx
 // Componentes e hooks — tudo do mesmo barrel.
@@ -36,5 +37,5 @@ import { Button, Dialog, useAction } from '@softize/opus/ui/react'
 - **Origem shadcn** — port curado do shadcn (Radix + cmdk). Toda divergência do upstream é
   DECLARADA no componente ou no tema — o que diverge sem declaração é drift e deve ser
   sincronizado (skill `build-opus-ui`).
-- **Nativo do Opus** — nasceu aqui (os patterns de action). Não tem upstream pra acompanhar; a
+- **Nativo do Opus** — nasceu aqui (os patterns de action). Não tem upstream para acompanhar; a
   referência é esta doc.

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

@@ -4,11 +4,10 @@ title: Atualizar o Opus
 
 # Atualizar o Opus
 
-Projeto em produção fica meses sem tocar no Opus — e um dia precisa pular várias
-versões de uma vez. O ritual é o mesmo para humano e IA, e não depende de memória:
-cada etapa está documentada ou é verificada por um gate que informa o que precisa ser corrigido.
+Use este fluxo para atualizar o Opus por uma ou várias versões. O changelog explica as mudanças e os
+gates apontam as adaptações necessárias no projeto.
 
-## 1. Saber que está atrás
+## 1. Identificar a versão disponível
 
 O **Maestro** compara o pin (`opus.json`) com a versão instalada e com a fonte a cada
 sessão — o alerta no rodapé diz a distância (`v2.9.0 → v2.15.2`) e o **Atualizar** faz
@@ -16,7 +15,7 @@ a parte mecânica: bump da dependência, re-materialização da camada de IA (sk
 hooks, agentes) e re-sync do bloco gerenciado do CLAUDE.md. Fora do Maestro:
 `pnpm outdated @softize/opus`.
 
-## 2. Saber o que mudou
+## 2. Ler as mudanças acumuladas
 
 O changelog **viaja no pacote** — depois do bump, está em
 `node_modules/@softize/opus/CHANGELOG.md`. Uma entrada por versão; quando quebra,
@@ -26,7 +25,7 @@ A esteira de release **recusa** publicar versão sem entrada — o arquivo não
 - **minor** (2.9 → 2.10): compatível; leia por curiosidade.
 - **major** (2.x → 3.0): pare nas seções Breaking de cada versão pulada, na ordem.
 
-## 3. Deixar os gates cobrarem o resto
+## 3. Executar as verificações
 
 O Opus ship source: o que quebrou aparece com arquivo e linha. Rode, na ordem:
 
@@ -38,8 +37,8 @@ pnpm manifest:check   # a spec projetada ficou fresca?
 opus db migrate       # schema em dia (drift-check embutido)
 ```
 
-Verde em tudo = atualizado de verdade. O bump entra no PR como qualquer mudança de
-código — atualização de base passa por review, não por fé.
+Com todas as verificações verdes, revise a atualização como qualquer outra mudança de código antes
+de entregá-la.
 
 ## Pulou muitas versões?
 

package/src/ui/docs/registry.tsx

@@ -27,6 +27,7 @@ import authMd from "./content/auth.md?raw";
 import auditMd from "./content/audit.md?raw";
 import eventsMd from "./content/events.md?raw";
 import logMd from "./content/log.md?raw";
+import observabilityMd from "./content/observability.md?raw";
 import queueMd from "./content/queue.md?raw";
 import schedulerMd from "./content/scheduler.md?raw";
 import actionsMd from "./content/actions.md?raw";
@@ -46,8 +47,6 @@ import customizationMd from "./content/customization.md?raw";
 // — Componentes —
 import accordionMd from "./content/accordion.md?raw";
 import alertMd from "./content/alert.md?raw";
-import alertDialogMd from "./content/alert-dialog.md?raw";
-import confirmMd from "./content/confirm.md?raw";
 import aspectRatioMd from "./content/aspect-ratio.md?raw";
 import avatarMd from "./content/avatar.md?raw";
 import badgeMd from "./content/badge.md?raw";
@@ -55,7 +54,6 @@ import dotMd from "./content/dot.md?raw";
 import dockMd from "./content/dock.md?raw";
 import breadcrumbMd from "./content/breadcrumb.md?raw";
 import buttonMd from "./content/button.md?raw";
-import buttonGroupMd from "./content/button-group.md?raw";
 import calendarMd from "./content/calendar.md?raw";
 import cardMd from "./content/card.md?raw";
 import metricCardMd from "./content/metric-card.md?raw";
@@ -77,7 +75,6 @@ import menuMd from "./content/menu.md?raw";
 import emptyMd from "./content/empty.md?raw";
 import fieldMd from "./content/field.md?raw";
 import inputMd from "./content/input.md?raw";
-import inputGroupMd from "./content/input-group.md?raw";
 import inputOtpMd from "./content/input-otp.md?raw";
 import itemMd from "./content/item.md?raw";
 import kbdMd from "./content/kbd.md?raw";
@@ -99,7 +96,6 @@ import tabsMd from "./content/tabs.md?raw";
 import textareaMd from "./content/textarea.md?raw";
 import toastMd from "./content/toast.md?raw";
 import toggleMd from "./content/toggle.md?raw";
-import toggleGroupMd from "./content/toggle-group.md?raw";
 import tooltipMd from "./content/tooltip.md?raw";
 import truncateMd from "./content/truncate.md?raw";
 
@@ -122,7 +118,6 @@ import actionTriggerMd from "./content/action-trigger.md?raw";
 import actionSearchDialogMd from "./content/action-list-dialog.md?raw";
 import pageMd from "./content/page.md?raw";
 import contentMd from "./content/content.md?raw";
-import pageStateMd from "./content/page-state.md?raw";
 import sidebarMd from "./content/sidebar.md?raw";
 import splitMd from "./content/split.md?raw";
 import routerMd from "./content/router.md?raw";
@@ -139,6 +134,8 @@ export interface DocEntry {
 export interface DocGroup {
   /** Sub-rótulo opcional dentro da seção (ex.: Primitivos). Ausente = páginas direto na seção. */
   label?: string;
+  /** Ícone opcional apresentado no nó expansível do grupo. */
+  icon?: React.ReactNode;
   pages: DocEntry[];
 }
 
@@ -178,7 +175,7 @@ const comp =
     </DocPage>
   );
 
-/** O palco dos patterns no scope dos previews: ícones + client fake + contratos de mentira. */
+/** O palco dos patterns no scope dos previews: ícones, cliente simulado e contratos de exemplo. */
 const patternScope = {
   ...iconScope,
   DocBrowserActionProvider,
@@ -291,6 +288,12 @@ export const PROTOCOL_SECTIONS: DocSection[] = [
             render: doc(eventsMd),
           },
           { slug: "log", title: "Log", badge: "log", render: doc(logMd) },
+          {
+            slug: "observability",
+            title: "Observabilidade",
+            badge: "observability",
+            render: doc(observabilityMd),
+          },
           {
             slug: "queue",
             title: "Filas",
@@ -371,6 +374,7 @@ export const UI_SECTIONS: DocSection[] = [
     groups: [
       {
         label: "Fundamentos",
+        icon: <lucideIcons.Blocks className="size-4" />,
         pages: [
           {
             slug: "router",
@@ -381,6 +385,7 @@ export const UI_SECTIONS: DocSection[] = [
       },
       {
         label: "Layout",
+        icon: <lucideIcons.PanelsTopLeft className="size-4" />,
         pages: [
           {
             slug: "split",
@@ -402,11 +407,6 @@ export const UI_SECTIONS: DocSection[] = [
             title: "Content",
             render: pattern("Content", "content", contentMd),
           },
-          {
-            slug: "page-state",
-            title: "Page State",
-            render: pattern("Page State", "page-state", pageStateMd),
-          },
           {
             slug: "accordion",
             title: "Accordion",
@@ -442,6 +442,7 @@ export const UI_SECTIONS: DocSection[] = [
       },
       {
         label: "Actions",
+        icon: <lucideIcons.Zap className="size-4" />,
         pages: [
           {
             slug: "action-form",
@@ -498,6 +499,7 @@ export const UI_SECTIONS: DocSection[] = [
       },
       {
         label: "IA",
+        icon: <lucideIcons.Sparkles className="size-4" />,
         pages: [
           { slug: "ask", title: "Ask", render: comp("Ask", "ask", askMd) },
           { slug: "chat", title: "Chat", render: comp("Chat", "chat", chatMd) },
@@ -510,6 +512,7 @@ export const UI_SECTIONS: DocSection[] = [
       },
       {
         label: "Formulário",
+        icon: <lucideIcons.TextCursorInput className="size-4" />,
         pages: [
           {
             slug: "calendar",
@@ -536,11 +539,6 @@ export const UI_SECTIONS: DocSection[] = [
             title: "Input",
             render: comp("Input", "input", inputMd),
           },
-          {
-            slug: "input-group",
-            title: "Input Group",
-            render: comp("Input Group", "input-group", inputGroupMd),
-          },
           {
             slug: "input-otp",
             title: "Input OTP",
@@ -580,31 +578,23 @@ export const UI_SECTIONS: DocSection[] = [
       },
       {
         label: "Botões",
+        icon: <lucideIcons.MousePointerClick className="size-4" />,
         pages: [
           {
             slug: "button",
             title: "Button",
             render: comp("Button", "button", buttonMd),
           },
-          {
-            slug: "button-group",
-            title: "Button Group",
-            render: comp("Button Group", "button-group", buttonGroupMd),
-          },
           {
             slug: "toggle",
             title: "Toggle",
             render: comp("Toggle", "toggle", toggleMd),
           },
-          {
-            slug: "toggle-group",
-            title: "Toggle Group",
-            render: comp("Toggle Group", "toggle-group", toggleGroupMd),
-          },
         ],
       },
       {
         label: "Navegação",
+        icon: <lucideIcons.Compass className="size-4" />,
         pages: [
           {
             slug: "breadcrumb",
@@ -626,6 +616,7 @@ export const UI_SECTIONS: DocSection[] = [
       },
       {
         label: "Exibição",
+        icon: <lucideIcons.Eye className="size-4" />,
         pages: [
           {
             slug: "avatar",
@@ -689,17 +680,13 @@ export const UI_SECTIONS: DocSection[] = [
       },
       {
         label: "Feedback",
+        icon: <lucideIcons.MessageCircleWarning className="size-4" />,
         pages: [
           {
             slug: "alert",
             title: "Alert",
             render: comp("Alert", "alert", alertMd),
           },
-          {
-            slug: "confirm",
-            title: "Dialog (imperativo)",
-            render: comp("Dialog (imperativo)", "confirm", confirmMd),
-          },
           {
             slug: "data-state",
             title: "Data State",
@@ -734,12 +721,8 @@ export const UI_SECTIONS: DocSection[] = [
       },
       {
         label: "Sobreposição",
+        icon: <lucideIcons.Layers className="size-4" />,
         pages: [
-          {
-            slug: "alert-dialog",
-            title: "Alert Dialog",
-            render: comp("Alert Dialog", "alert-dialog", alertDialogMd),
-          },
           {
             slug: "dialog",
             title: "Dialog",