@softize/opus 12.10.0 → 13.0.0

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

@@ -1,6 +1,22 @@
-## Composição
+## Escolher a forma do diálogo
 
-Content é superfície pura; o espaço mora nos slots (body p-5; header/footer px-5 py-4): DialogHeader (fixo, com divisor), DialogBody (rola) e DialogFooter (faixa da casa — borda + fundo muted). DialogClose fecha sem estado manual.
+Use a família `Dialog` quando a pessoa precisar concluir uma tarefa ou responder sem perder o
+contexto da página. A forma escolhida depende do tipo de interrupção:
+
+| Necessidade | Escolha |
+|---|---|
+| Exibir uma tarefa ou conteúdo modal que pode ser fechado. | Componha `Dialog`. |
+| Exigir uma resposta e impedir o fechamento pelo clique externo. | Componha `Dialog mode="alert"`. |
+| Pedir reconhecimento, confirmação binária ou uma string sem montar a superfície. | Use `dialog.alert`, `dialog.confirm` ou `dialog.prompt`. |
+| Escolher entre vários resultados simples. | Use `dialog.choose`. |
+
+Para conteúdo ancorado e não modal, use `Popover`. Para uma lista de ações, use `Menu`.
+
+## Compor uma tarefa modal
+
+`DialogContent` delimita a superfície. `DialogHeader`, `DialogBody` e `DialogFooter` organizam
+título, conteúdo rolável e ações com o espaçamento da família. A superfície usa o fundo base,
+borda semântica, raio `xl` e elevação para permanecer distinta da página.
 
 ```tsx preview
 <Dialog>
@@ -13,48 +29,340 @@ Content é superfície pura; o espaço mora nos slots (body p-5; header/footer p
       <DialogDescription>O workspace agrupa os repositórios e agentes do cliente.</DialogDescription>
     </DialogHeader>
     <DialogBody className="space-y-2">
-      <Label htmlFor="ws-nome">Nome</Label>
-      <Input id="ws-nome" placeholder="Ex.: Empresa X" />
+      <Label htmlFor="workspace-name">Nome</Label>
+      <Input id="workspace-name" placeholder="Ex.: Empresa X" />
     </DialogBody>
     <DialogFooter>
       <DialogClose asChild>
-        <Button variant="ghost" size="sm">Cancelar</Button>
+        <Button variant="ghost">Cancelar</Button>
       </DialogClose>
-      <Button size="sm">Criar</Button>
+      <Button>Criar workspace</Button>
     </DialogFooter>
   </DialogContent>
 </Dialog>
 ```
 
-## Sem o X (ação obrigatória)
+O corpo cresce até o limite da janela e passa a rolar; cabeçalho e rodapé permanecem visíveis.
+`DialogClose` encerra o modal sem exigir estado controlado. Use `open` e `onOpenChange` quando outra
+parte da interface também precisar controlar a abertura.
+
+## Pedir uma resposta pela API imperativa
 
-showCloseButton={false} esconde o X: o usuário decide pelos botões — pra confirmação que não pode ser dispensada no escuro.
+Use `dialog.alert`, `dialog.confirm`, `dialog.prompt` e `dialog.choose` quando a resposta couber em
+um contrato pronto. As chamadas são assíncronas e resolvem somente depois da resposta.
 
 ```tsx preview
-<Dialog>
-  <DialogTrigger asChild>
-    <Button variant="destructive">Excluir sessão</Button>
-  </DialogTrigger>
-  <DialogContent showCloseButton={false}>
-    <DialogHeader>
-      <DialogTitle>Excluir a sessão?</DialogTitle>
-      <DialogDescription>O worktree e o preview desta sessão serão removidos.</DialogDescription>
-    </DialogHeader>
-    <DialogFooter>
-      <DialogClose asChild>
-        <Button variant="ghost" size="sm">Cancelar</Button>
-      </DialogClose>
-      <DialogClose asChild>
-        <Button variant="destructive" size="sm">Excluir</Button>
-      </DialogClose>
-    </DialogFooter>
-  </DialogContent>
-</Dialog>
+function Demo() {
+  const [result, setResult] = useState('Nenhuma resposta.')
+
+  return (
+    <div className="flex flex-wrap items-center gap-3">
+      <DialogHost />
+      <Button variant="outline" size="sm" onClick={async () => {
+        await dialog.alert({
+          title: 'Sessão expirada',
+          description: 'Entre novamente para continuar.',
+        })
+        setResult('Aviso reconhecido.')
+      }}>
+        Abrir aviso
+      </Button>
+      <Button variant="outline" size="sm" onClick={async () => {
+        const accepted = await dialog.confirm({
+          title: 'Excluir sessão?',
+          description: 'O worktree e o preview desta sessão serão removidos.',
+          action: 'Excluir',
+          context: 'danger',
+        })
+        setResult(accepted ? 'Sessão excluída.' : 'Sessão mantida.')
+      }}>
+        Confirmar exclusão
+      </Button>
+      <Button variant="outline" size="sm" onClick={async () => {
+        const name = await dialog.prompt({
+          title: 'Renomear snapshot',
+          action: 'Renomear',
+          placeholder: 'Ex.: versão final',
+        })
+        setResult(name === null ? 'Nome mantido.' : `Novo nome: ${name}`)
+      }}>
+        Renomear snapshot
+      </Button>
+      <Button variant="outline" size="sm" onClick={async () => {
+        const choice = await dialog.choose({
+          title: 'Fechar editor?',
+          description: 'O contrato possui alterações que ainda não foram salvas.',
+          actions: [
+            { result: 'continue', label: 'Continuar editando', initialFocus: true },
+            { result: 'discard', label: 'Descartar', variant: 'outline' },
+            { result: 'save', label: 'Salvar e fechar' },
+          ],
+        })
+        setResult(choice === null ? 'Editor mantido.' : `Resultado: ${choice}`)
+      }}>
+        Fechar editor
+      </Button>
+      <span className="text-sm text-muted-foreground">{result}</span>
+    </div>
+  )
+}
+
+render(<Demo />)
+```
+
+`dialog.alert` devolve `Promise<void>`, `dialog.confirm` devolve `Promise<boolean>`,
+`dialog.prompt` devolve `Promise<string | null>` e `dialog.choose` infere a união dos resultados
+declarados, acrescida de `null`. Fechar ou cancelar resolve a resposta negativa de cada operação,
+em vez de deixar a promise pendente. No aviso com uma ação, o botão ocupa toda a largura do rodapé;
+confirmações e prompts distribuem confirmar e cancelar em duas colunas.
+
+Em `dialog.choose`, declare pelo menos uma ação e marque exatamente uma ação habilitada com
+`initialFocus`. Essa ação representa a saída segura. Os valores de `result` precisam ser únicos.
+Por padrão, a última ação recebe contexto primário e variante sólida; as anteriores usam contexto
+neutro e variante ghost. Defina `context` ou `variant` na própria ação para substituir o padrão.
+
+### Montar o host
+
+Monte um `DialogHost` no shell do aplicativo, ao lado do `Toaster`:
+
+```tsx
+<>
+  {routes}
+  <Toaster />
+  <DialogHost />
+</>
+```
+
+Sem o host, a chamada lança um erro imediatamente. Solicitações concorrentes entram em uma fila e
+aparecem uma por vez, preservando a resposta de cada `await`.
+
+### Adicionar conteúdo próprio
+
+Use `body` quando a descrição não for suficiente, como em uma lista de recursos afetados:
+
+```tsx
+const accepted = await dialog.confirm({
+  title: 'Encerrar três sessões?',
+  description: 'Os agentes vinculados serão interrompidos.',
+  body: <AffectedSessions />,
+  action: 'Encerrar sessões',
+})
 ```
 
-## Props
+Use `ActionTrigger` quando a confirmação já pertencer ao contrato de uma action. Use
+`ActionFormDialog` para formulários com validação ou vários campos. `dialog.prompt` atende somente
+uma string livre. Componha `Dialog` quando uma ação precisar manter a superfície
+aberta para exibir carregamento, validação ou falha antes do fechamento.
+
+## Compor uma resposta personalizada
+
+`Dialog mode="alert"` deriva `role="alertdialog"`, mantém o foco dentro da superfície e não fecha
+com o clique externo. Prefira a API imperativa quando a resposta couber em `alert`, `confirm`,
+`prompt` ou `choose`. Componha o componente quando a resposta depender de estado próprio ou de um
+layout específico.
+
+```tsx preview
+function ResponseDialogDemo() {
+  const [result, setResult] = useState('Nenhuma resposta.')
+
+  return (
+    <div className="space-y-3">
+      <Dialog mode="alert" onResult={setResult}>
+        <DialogTrigger asChild>
+          <Button variant="outline">Fechar editor</Button>
+        </DialogTrigger>
+        <DialogContent>
+          <DialogHeader>
+            <DialogTitle>Fechar editor?</DialogTitle>
+            <DialogDescription>
+              O contrato possui alterações que ainda não foram salvas.
+            </DialogDescription>
+          </DialogHeader>
+          <DialogFooter className="grid-cols-3">
+            <DialogClose result="continue" initialFocus asChild>
+              <Button variant="ghost">Continuar editando</Button>
+            </DialogClose>
+            <DialogClose result="discard" asChild>
+              <Button variant="outline">Descartar</Button>
+            </DialogClose>
+            <DialogClose result="save" asChild>
+              <Button>Salvar e fechar</Button>
+            </DialogClose>
+          </DialogFooter>
+        </DialogContent>
+      </Dialog>
+      <p className="text-sm text-muted-foreground">{result}</p>
+    </div>
+  )
+}
+
+render(<ResponseDialogDemo />)
+```
+
+`DialogClose` fecha a superfície sem escolher a aparência. Use `asChild` e componha um `Button`;
+contexto, variante e tamanho pertencem ao botão. `result` identifica a resposta entregue a
+`Dialog onResult`. Marque com `initialFocus` a saída segura — normalmente `Cancelar`; em um aviso
+com uma única ação, marque essa ação. Para uma confirmação destrutiva, use `context="danger"` no
+botão. O texto informa o efeito real, como `Excluir`, `Revogar acesso` ou `Encerrar sessões`.
+
+## Acessibilidade
+
+- `DialogTitle` e `DialogDescription` nomeiam e descrevem a superfície para tecnologias assistivas.
+- O modo padrão permite fechamento externo; `mode="alert"` exige uma resposta explícita.
+- O comportamento selecionado por `mode` determina o papel de acessibilidade; `role` não configura
+  o comportamento.
+- O foco permanece dentro do diálogo aberto e retorna ao gatilho após o fechamento.
+- `DialogHost` apresenta uma solicitação por vez para que cada resposta tenha um alvo inequívoco.
+
+## Propriedades de Dialog
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `open` | `boolean` | | Controla a abertura. |
+| `defaultOpen` | `boolean` | `false` | Define a abertura inicial no modo não controlado. |
+| `onOpenChange` | `(open: boolean) => void` | | Recebe mudanças de abertura. |
+| `mode` | `'default' \| 'alert'` | `'default'` | Exige resposta explícita em `alert`; o componente deriva o papel de acessibilidade. |
+| `onResult` | `(result: string) => void` | | Recebe o resultado do `DialogClose` acionado. |
+| `modal` | `boolean` | `true` | No modo padrão, mantém foco e interação restritos à superfície aberta. |
+
+## Propriedades de DialogTrigger
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `asChild` | `boolean` | `false` | Usa o filho como gatilho sem criar outro elemento. |
+| `children` | `ReactNode` | | Controle que abre o diálogo. |
+
+## Propriedades de DialogContent
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `showCloseButton` | `boolean` | `true` | No modo padrão, exibe o botão de fechamento no canto; o modo de alerta exige uma resposta identificável. |
+| `className` | `string` | | Ajusta a superfície. |
+| `children` | `ReactNode` | | Cabeçalho, corpo, rodapé ou conteúdo próprio. |
+
+## Propriedades de DialogHeader
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `className` | `string` | | Ajusta a faixa superior. |
+| `children` | `ReactNode` | | Título, descrição e mídia opcional. |
+
+## Propriedades de DialogBody
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `className` | `string` | | Ajusta o corpo rolável do modo padrão ou o conteúdo próprio do alerta. |
+| `children` | `ReactNode` | | Conteúdo principal da tarefa. |
+
+## Propriedades de DialogFooter
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `className` | `string` | | Ajusta a faixa do modo padrão ou a grade de respostas do alerta. |
+| `children` | `ReactNode` | | Ações secundárias e principal. |
+
+## Propriedades de DialogTitle
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `className` | `string` | | Ajusta o título. |
+| `children` | `ReactNode` | | Nome da tarefa ou do conteúdo modal. |
+
+## Propriedades de DialogDescription
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `className` | `string` | | Ajusta a descrição. |
+| `children` | `ReactNode` | | Contexto, efeito ou consequência relevante. |
+
+## Propriedades de DialogMedia
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `className` | `string` | | Ajusta a moldura quadrada da mídia. |
+| `children` | `ReactNode` | | Ícone que reforça o contexto da resposta. |
+
+## Propriedades de DialogClose
 
-| Prop | Tipo | Default | Descrição |
+| Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
-| `Dialog.open / onOpenChange` | `boolean / (open: boolean) => void` | | Modo controlado (Radix) — pra abrir por código (ex.: depois de uma action). |
-| `DialogContent.showCloseButton` | `boolean` | `true` | Mostra o X de fechar no canto. Desligue pra modal que exige ação explícita. |
+| `initialFocus` | `boolean` | `false` | No modo de alerta, marca o controle como destino inicial seguro do foco. |
+| `result` | `string` | | Entrega esta resposta a `Dialog onResult` antes de fechar. |
+| `asChild` | `boolean` | `false` | Aplica o fechamento ao filho; use com `Button`. |
+| `children` | `ReactNode` | | Controle que fecha o diálogo. |
+
+## Propriedades de DialogOverlay
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `className` | `string` | | Ajusta a camada que cobre a página. |
+
+## Propriedades de DialogPortal
+
+`DialogContent` já monta portal e overlay. Use `DialogPortal` diretamente somente em uma composição
+avançada; ele recebe `children` e `container` conforme o portal do Radix.
+
+## Propriedades de DialogHost
+
+`DialogHost` não recebe propriedades. Monte uma instância no shell para atender toda a API
+imperativa. `ConfirmHost` permanece como alias de migração.
+
+## Opções de dialog.alert
+
+| Opção | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `title` | `ReactNode` | | Nomeia o aviso que exige reconhecimento. |
+| `description` | `ReactNode` | | Explica efeito, alcance ou próximo passo. |
+| `body` | `ReactNode` | | Acrescenta conteúdo próprio abaixo da descrição. |
+| `media` | `ReactNode` | | Exibe um ícone na moldura de `DialogMedia`. |
+| `action` | `string` | `'OK'` | Define o rótulo de reconhecimento. |
+
+## Opções de dialog.confirm
+
+| Opção | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `title` | `ReactNode` | | Nomeia a decisão. |
+| `description` | `ReactNode` | | Explica a consequência necessária para decidir. |
+| `body` | `ReactNode` | | Acrescenta conteúdo próprio abaixo da descrição. |
+| `media` | `ReactNode` | | Exibe um ícone na moldura de `DialogMedia`. |
+| `action` | `string` | `'Confirmar'` | Define o rótulo do resultado afirmativo. |
+| `cancel` | `string` | `'Cancelar'` | Define o rótulo da resposta negativa. |
+| `context` | `'primary' \| 'danger'` | `'primary'` | Define o contexto da ação afirmativa. |
+
+## Opções de dialog.prompt
+
+| Opção | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `title` | `ReactNode` | | Nomeia a informação solicitada. |
+| `description` | `ReactNode` | | Explica como a informação será usada. |
+| `body` | `ReactNode` | | Acrescenta conteúdo próprio abaixo da descrição. |
+| `media` | `ReactNode` | | Exibe um ícone na moldura de `DialogMedia`. |
+| `action` | `string` | `'Confirmar'` | Define o rótulo do resultado afirmativo. |
+| `cancel` | `string` | `'Cancelar'` | Define o rótulo da resposta negativa. |
+| `context` | `'primary' \| 'danger'` | `'primary'` | Define o contexto da ação afirmativa. |
+| `placeholder` | `string` | | Orienta o formato esperado quando um exemplo ajuda. |
+| `defaultValue` | `string` | | Define e seleciona o valor inicial do campo. |
+
+## Opções de dialog.choose
+
+| Opção | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `title` | `ReactNode` | | Nomeia a escolha. |
+| `description` | `ReactNode` | | Explica o contexto necessário para escolher. |
+| `body` | `ReactNode` | | Acrescenta conteúdo próprio antes das ações. |
+| `media` | `ReactNode` | | Exibe um ícone na moldura de `DialogMedia`. |
+| `actions` | `readonly DialogChoice[]` | | Declara os resultados disponíveis. |
+
+## Propriedades de DialogChoice
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `result` | `string` | | Valor único devolvido quando a ação for escolhida. |
+| `label` | `ReactNode` | | Rótulo que descreve o resultado da ação. |
+| `initialFocus` | `boolean` | `false` | Marca a única saída segura que recebe o foco inicial. |
+| `context` | `ButtonContext` | Última ação: `primary`; demais: `neutral` | Define o significado semântico. |
+| `variant` | `ButtonVariant` | Última ação: `solid`; demais: `ghost` | Define o tratamento visual. |
+| `disabled` | `boolean` | `false` | Impede a escolha desta ação. |
+
+`confirm()` e `ConfirmHost` continuam disponíveis apenas como aliases de migração para
+`dialog.confirm()` e `DialogHost`.

package/src/ui/docs/content/dictionary-value.md

@@ -1,7 +1,6 @@
-Um valor de dicionário (`t.dict`) apresentado do jeito que o **dicionário** declarou. A tela não
-decide se o valor vira badge, cor ou ícone: ela passa o dicionário e o código, e o renderer
-aplica os defaults da apresentação declarada. O rótulo está sempre presente como texto — cor e
-ícone nunca comunicam sozinhos.
+Use `DictionaryValue` para apresentar um valor de `t.dict` de acordo com o papel declarado pelo
+próprio dicionário. A tela fornece o dicionário e o código; o componente escolhe texto, badge e ícone
+sem perder o rótulo visível.
 
 ```tsx preview
 <DictionaryValue
@@ -9,11 +8,11 @@ aplica os defaults da apresentação declarada. O rótulo está sempre presente
   value="pj"
 />
 <DictionaryValue
-  dict={{ keys: ['prospect', 'customer'], entries: { prospect: { label: 'Prospect' }, customer: { label: 'Cliente', tone: 'success' } }, presentation: 'stage' }}
+  dict={{ keys: ['prospect', 'customer'], entries: { prospect: { label: 'Prospect' }, customer: { label: 'Cliente', context: 'success' } }, presentation: 'stage' }}
   value="customer"
 />
 <DictionaryValue
-  dict={{ keys: ['open', 'blocked'], entries: { open: { label: 'Aberto', tone: 'warning', icon: 'clock', description: 'Aguarda uma decisão da Fonte.' }, blocked: { label: 'Bloqueado', tone: 'danger' } }, presentation: 'status' }}
+  dict={{ keys: ['open', 'blocked'], entries: { open: { label: 'Aberto', context: 'warning', icon: 'clock', description: 'Aguarda uma decisão da Fonte.' }, blocked: { label: 'Bloqueado', context: 'danger' } }, presentation: 'status' }}
   value="open"
 />
 <DictionaryValue
@@ -39,23 +38,23 @@ export const customerKindDict = t.dict(
 export const customerStageDict = t.dict(
   {
     prospect: { label: 'Prospect', description: 'Relacionamento ainda em prospecção.' },
-    customer: { label: 'Cliente', tone: 'success' },
+    customer: { label: 'Cliente', context: 'success' },
   },
   { doc: 'Estágio comercial atual da parte.', presentation: 'stage' },
 )
 ```
 
-| Papel | Quando | Forma | Variante |
+| Papel | Quando | Forma | Contexto e variante |
 |---|---|---|---|
-| `classification` | Tipo, categoria, natureza — uma dimensão estável de comparação. | Badge | `outline`; ignora `tone`. |
-| `status` | Situação operacional que muda com o tempo. | Badge | Tonal pelo `tone` da entrada; `neutral` sem tom. Nunca `outline`. |
+| `classification` | Tipo, categoria, natureza — uma dimensão estável de comparação. | Badge | `neutral` + `outline`; ignora `context`. |
+| `status` | Situação operacional que muda com o tempo. | Badge | Contexto declarado pela entrada + `subtle`; `neutral` quando ausente. |
 | `stage` | Etapa de um ciclo ou funil. | Badge | Igual a `status`. |
 | `plain` ou ausente | Valor que só precisa ser legível. | Texto | — |
 
-## Por entrada: tom, ícone e descrição
+## Por entrada: contexto, ícone e descrição
 
-- `tone` (`neutral` · `info` · `success` · `warning` · `danger`) só existe em status e estágio;
-  `t.dict` rejeita o tom em classificação e em `plain`.
+- `context` (`neutral` · `info` · `success` · `warning` · `danger`) só existe em status e estágio;
+  `t.dict` rejeita o contexto em classificação e em `plain`.
 - `icon` é um nome do catálogo do Opus (`iconPickerIcons`). Nome fora do catálogo não renderiza
   ícone; o renderer não inventa. Vocabulário próprio entra por `icons`.
 - `description` é o texto curto para a pessoa e aparece em tooltip focável. Descrição igual ao
@@ -73,13 +72,14 @@ export const customerStageDict = t.dict(
 />
 ```
 
-## Override explícito
+## Substituição explícita
 
-Os defaults vêm do dicionário; a tela sobrepõe só quando tem um motivo, e sobrepõe às claras.
+Os padrões vêm do dicionário. Use as propriedades de apresentação somente quando esta ocorrência
+precisar de um tratamento diferente e a decisão estiver explícita na tela.
 
 ```tsx preview
 <DictionaryValue
-  dict={{ keys: ['customer'], entries: { customer: { label: 'Cliente', tone: 'success' } }, presentation: 'stage' }}
+  dict={{ keys: ['customer'], entries: { customer: { label: 'Cliente', context: 'success' } }, presentation: 'stage' }}
   value="customer"
   presentation="plain"
 />
@@ -106,13 +106,14 @@ dicionário registrado no provider: `{ key: 'source', label: 'Fonte', dictionary
 Dimensões independentes (tipo e estágio, por exemplo) ficam em colunas distintas; não empilhar
 uma sob a outra como texto secundário.
 
-## Props
+## Propriedades de DictionaryValue
 
-| Prop | Tipo | Default | Descrição |
+| Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
 | `dict` | `DictType \| LogicalTypeMeta \| DictionaryDescriptor` | — | O dicionário (`t.dict`), a meta lida do schema ou um descritor normalizado. |
 | `value` | `string \| null \| undefined` | — | O código. Vazio renderiza `fallback`. |
 | `presentation` | `'classification' \| 'status' \| 'stage' \| 'plain'` | do dicionário | Sobrepõe o papel só nesta ocorrência. |
+| `context` | contexto de `Badge` | pelo dicionário | Sobrepõe o significado semântico e promove texto a badge. |
 | `variant` | variante de `Badge` | pelo papel | Sobrepõe a variante e promove texto a badge. |
 | `icon` | `boolean \| ReactNode` | `true` | `false` esconde o ícone declarado; um nó substitui. |
 | `icons` | `Record<string, LucideIcon>` | `iconPickerIcons` | Catálogo nome → componente. |

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

@@ -32,11 +32,11 @@ esquerda.
 
 A divisória entre grupos pertence ao componente: o consumidor declara `DockGroup` e a linha
 aparece entre grupos consecutivos, nunca antes do primeiro. Agrupe por intenção — modo, criação,
-IA, publicação — em vez de espalhar ícones numa fileira única.
+IA, publicação — em vez de espalhar ícones em uma fileira única.
 
 ## Estado da superfície
 
-Estado não é ferramenta, e por isso não mora na barra: `SurfaceStatus` flutua num canto da mesma
+Estado não é ferramenta, e por isso não mora na barra: `SurfaceStatus` flutua em um canto da mesma
 superfície — `top-right` por padrão — e recebe salvamento, versão publicada, execução percorrida.
 A região é `role="status"` com `aria-live="polite"`, então a mudança é anunciada sem roubar o foco.
 Separar os dois preserva a barra como toolbar navegável e dá ao estado um lugar estável, que não
@@ -63,7 +63,7 @@ A barra é uma `toolbar`: as setas andam entre as ações e Home/End vão às po
 por tooltip, então `<TooltipProvider>` precisa existir na raiz do app — o esqueleto do `opus create`
 já monta.
 
-| Prop | Tipo | Default | O que faz |
+| Propriedade | Tipo | Padrão | Descrição |
 | --- | --- | --- | --- |
 | `position` | `'bottom' \| 'bottom-left' \| 'bottom-right'` | `'bottom'` | Aresta do contêiner onde a barra se ancora. |
 | `label` | `string` | | Nome acessível da barra. |

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

@@ -1,16 +1,16 @@
 # Dot
 
-Indicador visual compacto para estados que já têm contexto. O tamanho permanece fixo; `variant`
-seleciona somente a intenção semântica. Quando a cor carrega significado, `label` fornece o nome
+Indicador visual compacto para estados que já têm contexto. O tamanho permanece fixo; `context`
+seleciona o significado e `variant` escolhe ponto sólido ou contornado. Quando a cor reforça significado, `label` fornece o nome
 acessível. Sem `label`, o ponto é decorativo.
 
 ```tsx preview
 <div className="flex items-center gap-4">
-  <Dot variant="success" label="Ativo" />
-  <Dot variant="warning" label="Atenção" />
-  <Dot variant="destructive" label="Falhou" />
-  <Dot variant="info" label="Publicado" />
-  <Dot variant="secondary" aria-hidden />
+  <Dot context="success" label="Ativo" />
+  <Dot context="warning" label="Atenção" />
+  <Dot context="danger" label="Falhou" />
+  <Dot context="info" label="Publicado" />
+  <Dot context="neutral" aria-hidden />
 </div>
 ```
 

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

@@ -1,8 +1,8 @@
-## Painel de detalhe (à direita)
+## Painel lateral de detalhe
 
-O painel que desliza de uma borda da tela — modal, com overlay, trap de foco e ESC (o motor é o Dialog do Radix). A régua contra o irmão: conteúdo curto e CENTRADO → `Dialog`; painel na borda que preserva o contexto atrás → `Drawer`.
-
-side='right' desliza da borda direita. ESC, clique no overlay e o X fecham — sem estado manual. É o lugar de detalhe/edição lateral sem sair do contexto.
+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.
 
 ```tsx preview
 <Drawer>
@@ -14,14 +14,19 @@ side='right' desliza da borda direita. ESC, clique no overlay e o X fecham — s
       <DrawerTitle>criarTicket</DrawerTitle>
       <DrawerDescription>Ação · domínio Suporte</DrawerDescription>
     </DrawerHeader>
-    <div className="px-4 text-sm text-muted-foreground">Campos, entrada/saída, arquivo…</div>
+    <DrawerBody className="text-sm text-muted-foreground">
+      Campos, entrada/saída, arquivo…
+    </DrawerBody>
   </DrawerContent>
 </Drawer>
 ```
 
-## Edição com rodapé (à esquerda)
+## Edição com ações persistentes
 
-side aceita top|right|bottom|left. DrawerFooter ancora as ações no rodapé; DrawerClose fecha sem estado manual.
+`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 divisor superior sobre fundo sutil. O corpo preserva o
+mesmo alinhamento horizontal entre título, conteúdo e ações.
 
 ```tsx preview
 <Drawer>
@@ -32,24 +37,35 @@ side aceita top|right|bottom|left. DrawerFooter ancora as ações no rodapé; Dr
     <DrawerHeader>
       <DrawerTitle>Editar workspace</DrawerTitle>
     </DrawerHeader>
-    <div className="space-y-2 px-4">
+    <DrawerBody className="space-y-2">
       <Label htmlFor="ws-nome">Nome</Label>
       <Input id="ws-nome" defaultValue="Empresa X" />
-    </div>
+    </DrawerBody>
     <DrawerFooter>
       <DrawerClose asChild>
-        <Button variant="ghost" size="sm">Cancelar</Button>
+        <Button variant="ghost">Cancelar</Button>
       </DrawerClose>
-      <Button size="sm">Salvar alterações</Button>
+      <Button>Salvar alterações</Button>
     </DrawerFooter>
   </DrawerContent>
 </Drawer>
 ```
 
-## Props
+## Propriedades de Drawer
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `open` | `boolean` | | Estado no modo controlado. |
+| `onOpenChange` | `(open: boolean) => void` | | Atualiza o estado para permitir abertura ou fechamento por código. |
+
+## Propriedades de DrawerContent
 
-| Prop | Tipo | Default | Descrição |
+| Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
-| `DrawerContent.side` | `'top' \| 'right' \| 'bottom' \| 'left'` | `'right'` | Borda de onde o painel desliza. |
-| `DrawerContent.showCloseButton` | `boolean` | `true` | Mostra o X de fechar no canto. Desligue pra painel que exige ação explícita. |
-| `Drawer.open / onOpenChange` | `boolean / (open: boolean) => void` | | Modo controlado (Radix) — pra abrir/fechar por código (ex.: detalhe de um item selecionado). |
+| `side` | `'top' \| 'right' \| 'bottom' \| 'left'` | `'right'` | Borda de onde o painel aparece. |
+| `showCloseButton` | `boolean` | `true` | Exibe o botão de fechamento. Desative quando o painel exigir uma ação explícita. |
+
+## Propriedades de DrawerBody
+
+`DrawerBody` aceita os atributos de `HTMLDivElement` e ocupa a região flexível e rolável entre
+`DrawerHeader` e `DrawerFooter`.

package/src/ui/docs/content/empty-value.md

@@ -40,9 +40,9 @@ columns: [
 ]
 ```
 
-## Props
+## Propriedades de EmptyValue
 
-| Prop | Tipo | Default | Descrição |
+| Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
 | `label` | `string` | `'Não informado'` | O que a ausência significa neste domínio. |
 | `compact` | `boolean` | `false` | Célula compacta: travessão visível, rótulo só para leitura assistiva. |