@softize/opus 18.5.0 → 20.0.0

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

@@ -1,21 +1,22 @@
 ## Painel lateral de detalhe
 
 Use `Drawer` para abrir detalhes ou edição junto a uma borda, preservando a referência visual da
-tela ao fundo. Para conteúdo curto e centralizado, prefira `Dialog`. Com `side="right"`, o painel
-entra pela direita e pode ser fechado por Esc, pelo overlay ou pelo botão de fechamento.
+tela ao fundo. Para conteúdo curto e centralizado, prefira [`Dialog`](/ui/dialog). Com
+`side="right"`, o painel entra pela direita e pode ser fechado por Esc, pelo overlay ou pelo botão
+de fechamento.
 
 ```tsx preview
 <Drawer>
   <DrawerTrigger asChild>
-    <Button variant="outline">Ver detalhe</Button>
+    <Button variant="outline">Ver veículo</Button>
   </DrawerTrigger>
   <DrawerContent side="right">
     <DrawerHeader>
-      <DrawerTitle>Criar ticket</DrawerTitle>
+      <DrawerTitle>ABC-1D23</DrawerTitle>
     </DrawerHeader>
-    <DrawerBody className="text-sm text-muted-foreground">
-      <p>Ação · domínio Suporte</p>
-      <p>Campos, entrada/saída, arquivo…</p>
+    <DrawerBody className="space-y-1 text-sm text-muted-foreground">
+      <p>Corolla XEi 2022 · 38.400 km</p>
+      <p>Última revisão em 12 de maio.</p>
     </DrawerBody>
   </DrawerContent>
 </Drawer>
@@ -23,11 +24,10 @@ entra pela direita e pode ser fechado por Esc, pelo overlay ou pelo botão de fe
 
 ## Edição com ações persistentes
 
-`side` aceita `top`, `right`, `bottom` e `left`. `DrawerFooter` mantém as ações no rodapé;
-`DrawerClose` fecha o painel sem exigir controle manual de estado. Como no `Dialog`, o cabeçalho
-recebe um divisor inferior e o rodapé usa um divisor superior. O corpo preserva o mesmo alinhamento
-horizontal entre título, conteúdo e ações. O fechamento do cabeçalho usa uma ação circular neutra
-e sutil; `closeSize` escolhe entre `xs` e `sm`, com `sm` como padrão.
+`side` aceita `top`, `right`, `bottom` e `left`. `DrawerFooter` mantém as ações no rodapé e
+`DrawerClose` fecha o painel sem exigir controle manual de estado. O corpo preserva o mesmo
+alinhamento horizontal do cabeçalho e do rodapé. O fechamento do cabeçalho usa uma ação circular
+neutra e sutil; `closeSize` escolhe entre `xs` e `sm`, com `sm` como padrão.
 
 ```tsx preview
 <Drawer>
@@ -36,11 +36,11 @@ e sutil; `closeSize` escolhe entre `xs` e `sm`, com `sm` como padrão.
   </DrawerTrigger>
   <DrawerContent side="left">
     <DrawerHeader>
-      <DrawerTitle>Editar workspace</DrawerTitle>
+      <DrawerTitle>Editar veículo</DrawerTitle>
     </DrawerHeader>
     <DrawerBody className="space-y-2">
-      <Label htmlFor="ws-nome">Nome</Label>
-      <Input id="ws-nome" defaultValue="Empresa X" />
+      <Label htmlFor="vehicle-owner">Responsável</Label>
+      <Input id="vehicle-owner" defaultValue="Marina Alves" />
     </DrawerBody>
     <DrawerFooter>
       <ButtonGroup mode="spaced">
@@ -54,24 +54,195 @@ e sutil; `closeSize` escolhe entre `xs` e `sm`, com `sm` como padrão.
 </Drawer>
 ```
 
+O rodapé usa a mesma faixa sutil do [`Dialog`](/ui/dialog). As duas famílias compartilham a
+anatomia, então um fluxo que começa em um modal e continua em um painel não muda de aparência no
+meio.
+
+## Regiões separadas ou contínuas
+
+`layout` declara a anatomia da superfície inteira e fica em `DrawerContent`; os slots leem esse
+valor e não o recebem. O padrão é `sectioned`: recuo igual nas três regiões, faixa no rodapé e
+divisor entre as regiões vizinhas. É o painel de trabalho, em que o corpo rola sob um cabeçalho e um
+rodapé fixos.
+
+Use `layout="continuous"` quando o painel apresentar um único bloco de leitura e a linha virar
+ruído.
+
+```tsx preview
+<Drawer>
+  <DrawerTrigger asChild>
+    <Button variant="outline">Ver resumo</Button>
+  </DrawerTrigger>
+  <DrawerContent layout="continuous">
+    <DrawerHeader>
+      <DrawerTitle>Resumo da revisão</DrawerTitle>
+    </DrawerHeader>
+    <DrawerBody>
+      <p className="text-sm text-muted-foreground">
+        Concluída em 2 horas, sem pendências registradas.
+      </p>
+    </DrawerBody>
+  </DrawerContent>
+</Drawer>
+```
+
+Os divisores do modo seccionado são derivados da vizinhança: cada região desenha a linha quando há
+uma região do outro lado. Um cabeçalho sem corpo não fecha nada, e um cabeçalho seguido direto de um
+rodapé produz uma linha só. A tela não escreve `border-b` nem `border-t`.
+
+## Mídia, ações e navegação no cabeçalho
+
+O cabeçalho reconhece quatro slots — `DrawerNavigation`, `DrawerMedia`, `DrawerTitle` e
+`DrawerActions` — e posiciona cada um: a navegação abre a linha, a mídia vem antes do título, o
+título ocupa a folga, as ações vão para o extremo oposto e o botão de fechar entra depois delas. Um
+nó que não seja um desses slots interrompe a renderização com um erro; contexto e conteúdo
+pertencem ao `DrawerBody`.
+
+`DrawerMedia` é a moldura de ícone do Opus — o mesmo [`IconTile`](/ui/icon-tile) —, útil para
+identificar o tipo do recurso aberto. `DrawerNavigation` carrega o retorno de um fluxo encadeado,
+em que o painel permanece aberto e troca de etapa.
+
+```tsx preview
+<Drawer>
+  <DrawerTrigger asChild>
+    <Button variant="outline">Abrir veículo</Button>
+  </DrawerTrigger>
+  <DrawerContent side="right">
+    <DrawerHeader>
+      <DrawerNavigation>
+        <Button variant="ghost" size="icon" aria-label="Voltar para a lista">
+          <ArrowLeft />
+        </Button>
+      </DrawerNavigation>
+      <DrawerMedia context="primary">
+        <CarFront />
+      </DrawerMedia>
+      <DrawerTitle>ABC-1D23</DrawerTitle>
+      <DrawerActions>
+        <Button variant="ghost" size="icon" aria-label="Mais ações">
+          <Ellipsis />
+        </Button>
+      </DrawerActions>
+    </DrawerHeader>
+    <DrawerBody>
+      <p className="text-sm text-muted-foreground">Histórico de passagens na oficina.</p>
+    </DrawerBody>
+  </DrawerContent>
+</Drawer>
+```
+
+Voltar e ações do cabeçalho usam `Button` `ghost` no tamanho `icon` (2.25rem), o mesmo que a
+[`Presentation`](/ui/presentation) usa no voltar. O botão de fechar é menor: um `CloseButton` no
+quadrado `icon-sm` (1.75rem) por padrão.
+
+O cabeçalho não recebe descrição: o painel já nomeia o recurso, e o contexto que ajuda a decidir
+aparece no começo do corpo, como texto ou `Alert`.
+
+## Impedir o fechamento durante uma operação
+
+Esc, o clique no overlay e o botão de fechar encerram o painel. Enquanto uma operação não puder ser
+interrompida, passe `closeDisabled` a `DrawerContent`: o botão de fechar continua visível, mas
+desabilitado, e Esc e o clique no overlay deixam de fechar o painel. Se você também passar
+`onEscapeKeyDown`, `onPointerDownOutside` ou `onInteractOutside`, esses handlers continuam sendo
+chamados antes do bloqueio.
+
+`closeDisabled` não alcança as ações que você compõe no painel, como um `Cancelar` com
+`DrawerClose`; desabilite-as pelo mesmo estado da operação. Quando a pessoa precisar responder antes
+de continuar, use [`Dialog mode="alert"`](/ui/dialog), que não fecha pelo clique externo.
+
+## Acessibilidade
+
+- `DrawerTitle` nomeia o painel para tecnologias assistivas. Quando um texto conciso do corpo também
+  precisar descrevê-lo, relacione seu `id` por `aria-describedby` em `DrawerContent`.
+- Com `modal` ativo, o padrão, o foco permanece dentro do painel e o restante da página fica
+  inacessível até o fechamento.
+- Ao fechar, o foco retorna ao gatilho.
+- O botão de fechar tem o nome acessível `Fechar`. Botões só com ícone no cabeçalho precisam de
+  `aria-label`.
+
 ## 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. |
+| Propriedade    | Tipo                      | Padrão  | Descrição                                                                    |
+| -------------- | ------------------------- | ------- | ---------------------------------------------------------------------------- |
+| `open`         | `boolean`                 |         | Estado no modo controlado.                                                   |
+| `defaultOpen`  | `boolean`                 | `false` | Abertura inicial no modo não controlado.                                     |
+| `onOpenChange` | `(open: boolean) => void` |         | Recebe as mudanças de abertura, inclusive Esc, overlay e botão de fechar.    |
+| `modal`        | `boolean`                 | `true`  | Mantém foco e interação restritos ao painel aberto e exibe o overlay.        |
+
+## Propriedades de DrawerTrigger
+
+| Propriedade | Tipo        | Padrão  | Descrição                                          |
+| ----------- | ----------- | ------- | -------------------------------------------------- |
+| `asChild`   | `boolean`   | `false` | Usa o filho como gatilho sem criar outro elemento. |
+| `children`  | `ReactNode` |         | Controle que abre o painel.                        |
+
+## Propriedades de DrawerClose
+
+| Propriedade | Tipo        | Padrão  | Descrição                                                   |
+| ----------- | ----------- | ------- | ----------------------------------------------------------- |
+| `asChild`   | `boolean`   | `false` | Aplica o fechamento ao filho; use com `Button`.             |
+| `children`  | `ReactNode` |         | Controle que fecha o painel, como o `Cancelar` do rodapé.   |
 
 ## Propriedades de DrawerContent
 
 | Propriedade       | Tipo                                     | Padrão    | Descrição                                                                                  |
 | ----------------- | ---------------------------------------- | --------- | ------------------------------------------------------------------------------------------ |
 | `side`            | `'top' \| 'right' \| 'bottom' \| 'left'` | `'right'` | Borda de onde o painel aparece.                                                            |
-| `showCloseButton` | `boolean`                                | `true`    | Inclui a ação de fechamento no header. Desative quando o painel exigir uma ação explícita. |
-| `closeDisabled`   | `boolean`                                | `false`   | Mantém a ação visível e impede fechar enquanto o painel está bloqueado.                    |
-| `closeSize`       | `"xs" \| "sm"`                         | `"sm"`   | Define o tamanho da ação circular de fechar.                                               |
+| `layout`          | `'continuous' \| 'sectioned'`            | `'sectioned'` | Anatomia da superfície inteira; os slots leem esse valor e não o recebem.              |
+| `showCloseButton` | `boolean`                                | `true`    | Inclui o botão de fechar no cabeçalho. Sem ele, Esc e o overlay continuam fechando o painel. |
+| `closeDisabled`   | `boolean`                                | `false`   | Mantém o botão de fechar visível e desabilitado e impede que Esc e o clique no overlay fechem o painel. |
+| `closeSize`       | `"xs" \| "sm"`                           | `"sm"`    | Define o tamanho da ação circular de fechar.                                               |
+| `className`       | `string`                                 |           | Ajusta o painel, como a largura.                                                           |
+| `children`        | `ReactNode`                              |           | Cabeçalho, corpo e rodapé.                                                                 |
+
+## Propriedades de DrawerHeader
+
+| Propriedade | Tipo        | Padrão | Descrição                                                                                  |
+| ----------- | ----------- | ------ | ------------------------------------------------------------------------------------------ |
+| `className` | `string`    |        | Ajusta a faixa superior sobre o recuo do layout.                                           |
+| `children`  | `ReactNode` |        | Somente `DrawerNavigation`, `DrawerMedia`, `DrawerTitle` e `DrawerActions`, no máximo um de cada; o fechamento padrão entra depois deles. |
+
+## Propriedades de DrawerMedia
+
+| Propriedade | Tipo                                                                     | Padrão      | Descrição                                                     |
+| ----------- | ------------------------------------------------------------------------ | ----------- | ------------------------------------------------------------- |
+| `size`      | `'xs' \| 'sm' \| 'default' \| 'lg'`                                      | `'sm'`      | Tamanho da moldura e do glifo na escala compartilhada.        |
+| `context`   | `'neutral' \| 'primary' \| 'info' \| 'success' \| 'warning' \| 'danger'` | `'neutral'` | Declara o significado da cor.                                 |
+| `variant`   | `'subtle' \| 'outline'`                                                  | `'subtle'`  | Usa preenchimento tonal ou acrescenta borda.                  |
+| `className` | `string`                                                                 |             | Ajusta a moldura sem substituir a escala.                     |
+| `asChild` | `boolean` | `false` | Cede o elemento para uma marca com visual próprio — um orbe, um logotipo — que ocupa o slot sem ganhar a moldura por cima. |
+
+## Propriedades de DrawerNavigation
+
+| Propriedade | Tipo        | Padrão | Descrição                                             |
+| ----------- | ----------- | ------ | ----------------------------------------------------- |
+| `className` | `string`    |        | Ajusta a região introdutória da linha.                |
+| `children`  | `ReactNode` |        | Retorno de um fluxo encadeado, antes do título.       |
+
+## Propriedades de DrawerActions
+
+| Propriedade | Tipo        | Padrão | Descrição                                                |
+| ----------- | ----------- | ------ | -------------------------------------------------------- |
+| `className` | `string`    |        | Ajusta o agrupamento das ações.                          |
+| `children`  | `ReactNode` |        | Ações da tela no cabeçalho, antes do botão de fechar.    |
+
+## Propriedades de DrawerTitle
+
+| Propriedade | Tipo        | Padrão | Descrição                                                           |
+| ----------- | ----------- | ------ | ------------------------------------------------------------------- |
+| `level`     | `1 \| 2 \| 3 \| 4 \| 5 \| 6` | `h2` da primitiva | Hierarquia do documento. O tamanho vem do `layout`, nunca do nível. |
+| `className` | `string`    |        | Ajusta o título, que trunca quando não cabe na linha.               |
+| `children`  | `ReactNode` |        | Nome do recurso ou da tarefa; nomeia a superfície para leitores de tela. |
 
 ## Propriedades de DrawerBody
 
 `DrawerBody` aceita os atributos de `HTMLDivElement` e ocupa a região flexível e rolável entre
 `DrawerHeader` e `DrawerFooter`. O cabeçalho nomeia o painel; contexto relevante entra no começo
 do corpo como texto ou `Alert`.
+
+## Propriedades de DrawerFooter
+
+| Propriedade | Tipo        | Padrão | Descrição                                                              |
+| ----------- | ----------- | ------ | ---------------------------------------------------------------------- |
+| `className` | `string`    |        | Ajusta a faixa do rodapé, inclusive a distribuição das ações.          |
+| `children`  | `ReactNode` |        | Ações persistentes, normalmente dentro de um `ButtonGroup`.            |

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

@@ -1,7 +1,7 @@
-Valor ausente tem uma representação padrão. Nas células de tabela e nos pares de `DetailField`
-aparece o travessão, enquanto a leitura assistiva recebe “Não informado”. As colunas de
-`ActionList` e o `DetailField` já fazem isso sozinhos; um renderer customizado reutiliza a
-primitiva em vez de repetir a condicional.
+Valor ausente tem uma representação padrão. Nas células de tabela e nos pares de
+[`DetailField`](/ui/detail) aparece o travessão, enquanto a leitura assistiva recebe “Não
+informado”. As colunas de [`ActionList`](/ui/action-list) e o `DetailField` já fazem isso sozinhos;
+uma célula ou um componente próprio usa `EmptyValue` em vez de repetir a condicional.
 
 ```tsx preview
 <div className="flex items-center gap-6 text-sm">
@@ -15,8 +15,19 @@ primitiva em vez de repetir a condicional.
 ## O que conta como ausência
 
 `null`, `undefined`, string vazia e string só com espaços. `0`, `false` e coleções vazias são
-valores legítimos: quem apresenta booleanos e listas decide a própria forma. `isAbsentValue`
-exporta a mesma regra para renderers customizados.
+valores legítimos: quem apresenta booleanos e listas decide a própria forma. `isAbsentValue` aplica
+a mesma regra em células e componentes próprios.
+
+```ts
+function isAbsentValue(value: unknown): boolean
+```
+
+```tsx
+import { EmptyValue, isAbsentValue } from '@softize/opus/ui/react'
+
+// Em uma célula própria:
+isAbsentValue(row.phone) ? <EmptyValue compact /> : formatPhone(row.phone)
+```
 
 ## O domínio dá o significado
 
@@ -46,3 +57,6 @@ columns: [
 |---|---|---|---|
 | `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. |
+
+Os demais atributos, como `className`, vão para o elemento `span`. `EmptyValue` não aceita
+`children`: o texto entra por `label`.

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

@@ -4,9 +4,9 @@ Use `Empty` quando a própria região está disponível para receber ou criar co
 tracejada diferencia esse espaço de uma estrutura de dados já estabelecida e pode combinar título,
 descrição, mídia e ação.
 
-Para uma lista ou tabela carregada, mas sem registros, use `DataState` ou `ActionList`: a moldura
-sólida preserva a estrutura. Se a região já estiver emoldurada pelo pai, mantenha a borda somente
-no pai para evitar uma moldura dupla.
+Para uma lista ou tabela carregada, mas sem registros, use [`DataState`](/ui/data-state) ou
+[`ActionList`](/ui/action-list): a moldura sólida preserva a estrutura. Se a região já estiver
+emoldurada pelo pai, mantenha a borda somente no pai para evitar uma moldura dupla.
 
 ## Com ícone
 
@@ -78,3 +78,24 @@ ou mídias que tenham presença visual própria.
 | Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
 | `variant` | `'default' \| 'icon'` | `'default'` | `icon` aplica uma moldura quadrada e muted; `default` exibe a mídia sem fundo. |
+
+## Propriedades de EmptyHeader
+
+`EmptyHeader` agrupa mídia, título e descrição no centro, com largura limitada para a leitura. Não
+tem props próprias; aceita as de um elemento `div`.
+
+## Propriedades de EmptyTitle
+
+`EmptyTitle` exibe a situação em destaque. Ele renderiza um `div`, sem nível de heading; quando a
+região precisar de um título na estrutura da página, passe `role="heading"` e `aria-level`. Não tem
+props próprias; aceita as de um elemento `div`.
+
+## Propriedades de EmptyDescription
+
+`EmptyDescription` apresenta a explicação em cor atenuada e sublinha os links filhos diretos. Não
+tem props próprias; aceita as de um elemento `div`.
+
+## Propriedades de EmptyActions
+
+`EmptyActions` empilha e centraliza as ações abaixo do cabeçalho. Não tem props próprias; aceita as
+de um elemento `div`.

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

@@ -4,9 +4,9 @@ title: Eventos
 
 # Eventos
 
-Use eventos quando uma action precisar anunciar um fato sem conhecer seus consumidores.
-`ctx.emit` publica o evento; reactions e integrações podem assiná-lo pelo `EventBusAdapter`. O
-formato declarado permanece o mesmo durante todo o fluxo.
+Use eventos quando uma action precisar anunciar um fato sem conhecer quem vai reagir a ele.
+`ctx.emit` publica o evento; reactions e integrações o recebem pelo `EventBusAdapter`. O formato do
+evento é o mesmo do handler que emite até quem consome.
 
 ## O contrato
 
@@ -24,6 +24,8 @@ interface DomainEvent<T = unknown> {
   tenant?: string | null
   data: T
   source: { action: string; actionId: string; correlation?: string }
+  trace?: TraceContext                           // trace da execução que emitiu
+  meta?: Record<string, unknown>                 // o terceiro argumento de ctx.emit
 }
 ```
 
@@ -32,10 +34,15 @@ interface DomainEvent<T = unknown> {
 ```ts
 import { mittEvents } from '@softize/opus/events/mitt'
 
-const bus = mittEvents()   // in-process (mesmo processo do runtime)
+const bus = mittEvents() // no mesmo processo do runtime
 ```
 
-## No runtime
+O `mitt` entrega pelo nome exato do evento ou por `*`, que recebe todos. Padrões parciais, como
+`nota.*`, não são reconhecidos: assine `*` e filtre no handler.
+
+## Emitir de uma action
+
+Configure o barramento no runtime e declare no binding os eventos que a action emite:
 
 ```ts
 const runtime = createRuntime({
@@ -43,19 +50,72 @@ const runtime = createRuntime({
   eventBus: bus,
 })
 
-// No handler: emite pelo tipo declarado; o core preenche id/timestamp/actor/source.
-handler: async (ctx, input) => {
-  const nota = await repo.create(input)
-  await ctx.emit('nota.emitida', { id: nota.id, valor: nota.valor })
-  return nota
-}
+export const notaEmitir = bindAction(notaEmitirContract, {
+  emits: ['nota.emitida'],
+  handler: async (ctx, input) => {
+    const nota = await repo.create(input)
+    // O runtime preenche id, timestamp, actor, tenant, source e trace.
+    await ctx.emit('nota.emitida', { id: nota.id, valor: nota.valor })
+    return nota
+  },
+})
 ```
 
-Actions declaram no contrato o que emitem (`emits: ['nota.emitida']`); o runtime avisa se
-o handler emitir algo não-declarado (`emitMode`). Uma reaction assina `nota.emitida` e roda
-como sua própria action rastreável (provenance `reaction`).
+`emits` pertence ao binding, como `handler`, e o runtime só o considera em actions `simple` e
+`form`. Quando uma delas declara `emits` e o handler emite um evento fora da lista, o runtime
+registra um aviso no log. Esse aviso vem de `config.warnUndeclaredEmits`, ativo por padrão fora de produção. Sem `emits`
+declarado, nenhum aviso é gerado.
+
+Em uma action `list` ou `view`, o tipo do binding aceita `emits`, mas a lista não entra no manifest
+nem na conferência dos eventos emitidos. Para que a declaração não pareça ter efeito, o runtime
+registra o aviso `runtime.action_field_ignored` quando a action é registrada com `config.dev` ativo,
+o padrão sempre que `config.env` não é `'production'`. O [`opus check`](/docs/cli) aponta o mesmo
+caso com a regra `ignored-by-kind`. Se a operação anuncia um fato, declare-a como `simple` ou `form`.
+
+`config.emitMode` decide o que acontece quando a publicação não é possível. No padrão, `lenient`, a
+falta de `EventBusAdapter` e uma falha de `publish` viram aviso no log e o handler segue. Em
+`strict`, as duas situações interrompem a action com `emit.no_bus` ou `emit.failed`.
+
+## Reagir a um evento
+
+Uma reaction executa código quando um evento é publicado. Como nas actions, a declaração pode ficar
+no código compartilhado e o efeito, no servidor:
+
+```ts
+import { bindReaction, defineReactionContract } from '@softize/opus/core'
+
+// shared/ — qual evento e o que a reação significa.
+export const notaAvisarFinanceiro = defineReactionContract<{ id: string; valor: number }>({
+  name: 'nota.avisar-financeiro',
+  on: 'nota.emitida',
+  description: 'Avisa o financeiro quando uma nota é emitida.',
+})
+
+// api/ — o efeito.
+export const notaAvisarFinanceiroImpl = bindReaction(notaAvisarFinanceiro, {
+  handler: async (ctx, event) => {
+    ctx.log.info('nota emitida', { id: event.data.id, valor: event.data.valor })
+  },
+})
+```
+
+Registre a reaction com as actions, em `defineDomain({ reactions: [notaAvisarFinanceiroImpl] })`
+ou em `runtime.register`. Com reactions registradas, o `start()` exige um `EventBusAdapter` e falha
+com `runtime.eventbus_required` quando ele não existe. `defineReaction` declara tudo num objeto só,
+quando não há separação entre cliente e servidor.
+
+A reaction roda com provenance `reaction`; `ctx.user` traz somente o `id` do autor do evento, e
+`ctx.tenantId`, o tenant do evento. O contexto não tem `can`: a decisão fica no `authorize(ctx, event)` opcional, e uma resposta `false` descarta o evento
+sem erro. Uma falha no handler é registrada no log e não chega à action que emitiu.
 
 ## Limites atuais
 
-O driver `mitt` é in-process — sem durabilidade nem entre-processos. Barramentos duráveis/
-distribuídos (Redis, NATS…) entram por reincidência de caso real.
+O driver `mitt` funciona no mesmo processo, sem durabilidade nem entrega entre processos.
+
+Uma reaction não encadeia outra por evento: dentro dela, `ctx.emit` descarta o evento sem publicá-lo.
+Com `config.dev` ativo, cada descarte registra o aviso `runtime.reaction_emit_ignored` no log, com o
+nome da reaction e do evento; em produção, o descarte continua silencioso. Quando outro consumidor
+precisa desse fato, emita o evento no handler da action que o produz e declare-o em `emits`.
+
+`retry`, `timeout`, `dedup` e `concurrency` são aceitos na declaração, mas o runtime ainda não os
+aplica: uma reaction que falha não é repetida.

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

@@ -9,7 +9,7 @@ O módulo é experimental e opt-in: instalar o Opus não passa a descobrir crons
 O executor continua dono do estado; este recurso mantém uma fotografia para consulta.
 
 Para colocar trabalho em segundo plano, use [Filas](/docs/queue). Para acompanhar trabalho já
-existente, adapte seu executor à projeção abaixo. Não usar a projeção para decidir reenvio ou retry.
+existente, adapte seu executor à projeção abaixo. Não use a projeção para decidir reenvio ou retry.
 
 ## Publicar uma fotografia
 
@@ -43,8 +43,8 @@ Cron que enfileira trabalho continua com
 `trigger: 'schedule'`; entrar na fila não cria outra execução. Retomada mantém o ID e avança
 revisão/tentativa conforme o executor. A projeção não valida transições de negócio.
 
-Uma falha de projeção lança erro para o adaptador tratar. Registrar essa falha e reconciliar
-depois a partir do executor; não deixar o erro provocar retry de um efeito já realizado.
+Uma falha de projeção lança erro para o adaptador tratar. Registre essa falha e reconcilie
+depois a partir do executor; não deixe o erro provocar retry de um efeito já realizado.
 `observe` não contém proteção automática para o fluxo de negócio do consumidor.
 
 ## Persistência e processos separados
@@ -60,7 +60,7 @@ durável; o aviso não é histórico nem fila de entrega.
 
 `pgExecutionChanges({ connect, onError, channel?, reconnectMs? })` compartilha uma conexão
 LISTEN entre seus assinantes. `connect` deve entregar uma conexão nova, já conectada, dedicada
-e com timeout de conexão configurado. Não fornecer uma conexão emprestada por um pooler
+e com timeout de conexão configurado. Não forneça uma conexão emprestada por um pooler
 transacional. O driver fecha a conexão quando sai o último assinante, registra falhas por
 `onError` e tenta reconectar após `reconnectMs` (padrão: 1.000 ms; mínimo: 100 ms).
 
@@ -87,15 +87,15 @@ async function openProgress(
 }
 ```
 
-Para `authorize(null)`, verificar sessão e direito de acompanhar. Para um aviso, verificar
+Para `authorize(null)`, verifique a sessão e o direito de acompanhar. Para um aviso, verifique
 também tenant, operação e recurso exato. Essa verificação ocorre novamente durante o stream,
 inclusive nos heartbeats e antes de emitir uma invalidação. Heartbeats revalidam a sessão
 independentemente da fila de avisos: a função pode receber um aviso e `null` concorrentemente.
 As actions de leitura devem aplicar a mesma política: filtrar a
 consulta por tenant não substitui autorização.
 
-O cliente recebe somente `event: invalidate` com `{}`. Ao recebê-lo, invalidar as queries das
-actions autorizadas. Manter uma conexão compartilhada no provider da aplicação, não uma por
+O cliente recebe somente `event: invalidate` com `{}`. Ao recebê-lo, invalide as queries das
+actions autorizadas. Mantenha uma conexão compartilhada no provider da aplicação, não uma por
 card. A primeira invalidação e a reconexão exigem nova fotografia; não há `Last-Event-ID` nem
 replay. O navegador pode usar `EventSource` com cookies same-origin e sua reconexão nativa.
 
@@ -105,9 +105,9 @@ de 128 avisos pendentes e 16 frames na saída; excedê-los encerra a conexão pa
 sem acumular um log em memória. Sessão é reavaliada no máximo a cada heartbeat enquanto a
 autorização responde; configure timeout no serviço de autorização para não mantê-la pendente.
 
-IDs, tenant e operação nos avisos são metadados operacionais internos. Não usar CPF, telefone,
+IDs, tenant e operação nos avisos são metadados operacionais internos. Não use CPF, telefone,
 e-mail ou segredo nesses identificadores. PostgreSQL NOTIFY não é uma fronteira de autorização:
-restringir as credenciais e o acesso ao banco. Nada do aviso é copiado para o SSE.
+restrinja as credenciais e o acesso ao banco. Nada do aviso é copiado para o SSE.
 
 ## Detectar ausência de sinal
 

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

@@ -1,9 +1,11 @@
 ## Campo empilhado
 
-Use `Field` para manter rótulo, controle, ajuda e erro com espaçamento consistente. Na orientação
-vertical, `FieldLabel` e o controle ficam empilhados. A ajuda fica junto ao rótulo, com `LabelHelp`,
-o mesmo ícone que o `ActionForm` usa para `FieldSpec.help`. Use `FieldDescription` somente quando a
-frase precisar ficar visível o tempo todo abaixo do controle.
+Use `Field` para manter rótulo, controle, ajuda e erro com espaçamento consistente em um formulário
+montado à mão. Quando o formulário executa uma action, prefira [`ActionForm`](/ui/action-form), que
+monta os mesmos campos a partir do contrato. Na orientação vertical, `FieldLabel` e o controle ficam
+empilhados. A ajuda fica junto ao rótulo, com [`LabelHelp`](/ui/action-form), o mesmo ícone que o
+`ActionForm` usa para `FieldSpec.help`. Use `FieldDescription` somente quando a frase precisar
+ficar visível o tempo todo abaixo do controle.
 
 ```tsx preview col md
 <Field>
@@ -15,7 +17,7 @@ frase precisar ficar visível o tempo todo abaixo do controle.
 </Field>
 ```
 
-## Horizontal com toggle
+## Horizontal com Switch
 
 `orientation="horizontal"` posiciona o controle ao lado do texto. `FieldContent` agrupa título e
 descrição; `FieldTitle` exibe o título quando o texto não puder ser um `<label>`. Como ele não se
@@ -35,7 +37,7 @@ vincula ao controle, ligue-o ao controle por `aria-labelledby` para manter o nom
 
 ## Conjunto com legenda e erro
 
-Use `Content as="fieldset"` para nomear um conjunto de campos relacionados. O título vira a legenda
+Use [`Content`](/ui/content) com `as="fieldset"` para nomear um conjunto de campos relacionados. O título vira a legenda
 nativa, enquanto `FieldGroup` define o espaçamento e `FieldSeparator` marca uma divisão.
 `FieldError` aparece somente quando existe mensagem de erro. Declare `data-invalid="true"` no
 `Field` para que o rótulo acompanhe o contexto de erro; `aria-invalid` marca apenas o controle. O
@@ -70,6 +72,18 @@ nativa, enquanto `FieldGroup` define o espaçamento e `FieldSeparator` marca uma
 </Content>
 ```
 
+## Campo desabilitado
+
+Declare `disabled` no controle para bloquear a edição. Para que o rótulo acompanhe o estado,
+declare também `data-disabled="true"` no `Field`: `FieldLabel` e `FieldTitle` esmaecem junto.
+
+```tsx preview col md
+<Field data-disabled="true">
+  <FieldLabel htmlFor="workspace-client">Cliente</FieldLabel>
+  <Input id="workspace-client" defaultValue="Empresa X" disabled />
+</Field>
+```
+
 ## Conjunto com moldura
 
 Use a moldura para distinguir grupos vizinhos que continuem pertencendo ao mesmo formulário. O
@@ -117,6 +131,7 @@ demais regiões nomeadas. A migração pode ser gradual porque os controles e o
 | -------------- | -------------------------------------------- | ------------ | ----------------------------------------------------------------------------------------------------- |
 | `orientation`  | `'vertical' \| 'horizontal' \| 'responsive'` | `'vertical'` | Direção fixa do campo. `responsive` permanece como alias compatível de `horizontal`.                  |
 | `data-invalid` | `boolean \| 'true' \| 'false'`               |              | Com `true`, aplica o contexto de erro ao campo e ao rótulo. O `ActionForm` define o atributo sozinho. |
+| `data-disabled` | `'true' \| 'false'`                         |              | Com `true`, esmaece `FieldLabel` e `FieldTitle`. Declare `disabled` também no controle. |
 
 ## Propriedades de FieldLegend