@softize/opus 19.0.0 → 20.1.0

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

@@ -1,9 +1,12 @@
 ## Navegação entre páginas
 
-Componha `Pagination`, `PaginationContent` e um `PaginationItem` para cada link. `page` fornece o
+Use `Pagination` quando uma coleção for dividida em páginas e a pessoa precisar saltar entre elas.
+Em uma listagem derivada de uma action, [`ActionList`](/ui/action-list) já monta esta paginação no
+rodapé; componha-a diretamente apenas em coleções próprias.
+
+Monte `Pagination`, `PaginationContent` e um `PaginationItem` para cada link. `page` fornece o
 número e o nome acessível; `isActive` identifica a página atual. Os controles mantêm altura fixa e
-a largura cresce quando o número precisa de mais espaço. `ActionList` usa esta mesma primitiva no
-rodapé.
+a largura cresce quando o número precisa de mais espaço.
 
 ```tsx preview
 <Pagination>
@@ -30,8 +33,9 @@ rodapé.
 ## Números longos
 
 A largura mínima é quadrada e cresce conforme o conteúdo. Na escala densa de um rodapé, as setas e a
-elipse usam `size="icon-sm"` (o quadrado de 1.75rem da escala única, com o glifo de 0.875rem); os
-números, que não têm um degrau de 1.75rem na escala, ajustam por `className` (`h-7 min-w-7 text-xs`).
+elipse usam `size="icon-sm"`, o quadrado de `1.75rem` da escala única, com ícone de `0.875rem`. Os
+números não têm um degrau textual de `1.75rem` na escala e, por isso, recebem a mesma medida por
+`className`, como no exemplo.
 
 ```tsx preview
 <Pagination>
@@ -148,3 +152,7 @@ render(
 |---|---|---|---|
 | `size` | `'icon-xs' \| 'icon-sm' \| 'icon' \| 'icon-lg'` | `'icon'` | Quadrado da escala única; use o mesmo tamanho das setas ao lado. |
 | `className` | `string` | | Classes adicionais aplicadas à elipse. |
+
+`Pagination` renderiza um `<nav>` com o nome acessível “Paginação”, `PaginationContent` um `<ul>` e
+`PaginationItem` um `<li>`. Os três não têm propriedades próprias e aceitam as props nativas do
+respectivo elemento, incluindo `className`.

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

@@ -62,11 +62,55 @@ render(
 
 O cabeçalho reconhece quatro slots — `PaneMedia`, `PaneTitle`, `PaneDescription` e `PaneActions` —
 e monta a linha sozinho: mídia, título e descrição de um lado, ações no extremo oposto. A ordem em
-que os slots são escritos não altera a posição, e um nó que não seja um desses slots interrompe a
-renderização com um erro. Conteúdo livre vai para `PaneBody`.
+que os slots são escritos não altera a posição. Cada slot aparece no máximo uma vez: repetir um
+deles interrompe a renderização com um erro que lista os slots aceitos.
 
 Título e descrição truncam quando a coluna encolhe, em vez de quebrar a altura da faixa.
 
+Nas ações do cabeçalho, use `Button` `ghost` no tamanho `icon-sm` (1.75rem), como nos exemplos. O
+pane é uma superfície densa, com título e descrição em escala menor, e o quadrado menor acompanha
+essa escala. [`Dialog`](/ui/dialog) e [`Drawer`](/ui/drawer) usam `icon` (2.25rem) no voltar e nas
+ações do cabeçalho, e a [`Presentation`](/ui/presentation) usa o mesmo tamanho no voltar e no botão
+que abre o assistente.
+
+## Busca ou marca no cabeçalho
+
+Uma coluna às vezes precisa, no topo, de algo que não é título nem ação: uma busca que filtra a
+lista, a marca de uma barra lateral. Escreva esse conteúdo direto dentro do `PaneHeader`, ao lado
+dos slots. Só o `Pane` aceita conteúdo livre no cabeçalho; os headers de `Card`, `Dialog` e `Drawer`
+aceitam apenas os próprios slots.
+
+```tsx preview
+render(
+  <div className="h-56 overflow-hidden rounded-lg border border-border">
+    <Split>
+      <Pane initialSize="18rem">
+        <PaneHeader>
+          <Input icon={<Search />} placeholder="Buscar conversa" aria-label="Buscar conversa" />
+          <PaneActions>
+            <Button variant="ghost" size="icon-sm" aria-label="Nova conversa">
+              <SquarePen />
+            </Button>
+          </PaneActions>
+        </PaneHeader>
+        <PaneBody className="space-y-1">
+          <p className="text-sm">Revisão do contrato</p>
+          <p className="text-sm text-muted-foreground">Importação de clientes</p>
+        </PaneBody>
+      </Pane>
+      <Pane grow>
+        <p className="text-sm text-muted-foreground">Conversa selecionada.</p>
+      </Pane>
+    </Split>
+  </div>,
+);
+```
+
+O conteúdo livre ocupa o lugar do título e absorve a largura disponível, por isso as ações
+continuam no extremo oposto. Quando há título, o conteúdo livre vem sempre depois do título e da descrição,
+qualquer que seja a ordem no JSX: uma busca escrita junto de um `PaneTitle` aparece abaixo dele, não
+ao lado. Para algo antes do título, use `PaneMedia`; para algo ao lado, use `PaneActions`.
+
 ## Escolher entre seccionado e contínuo
 
 `layout` declara a anatomia da superfície inteira e fica no root; os slots leem esse valor e não o
@@ -86,6 +130,11 @@ Os divisores são derivados da vizinhança: cada região desenha a linha quando
 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`.
 
+No `continuous`, um cabeçalho sem corpo nem rodapé fecha o pane com o mesmo recuo que tem em cima.
+Uma classe `pb-*` no `PaneHeader` não altera esse recuo: a regra só vale quando o cabeçalho é a
+última região e tem precedência sobre o `className`. No `sectioned`, a faixa tem altura fixa e
+centraliza a linha, então não há recuo de baixo a ajustar.
+
 ## Recuo do pane e recuo das regiões
 
 `inset` é o respiro interno do pane sem slots: `md` por padrão, com `none`, `sm` e `lg`
@@ -99,11 +148,12 @@ O ajuste enxerga só o primeiro nível. Se os slots vierem dentro de outro compo
 
 ## A matriz de layouts e slots
 
-As regiões são independentes e o recuo se ajusta a cada combinação, nos dois layouts.
+As regiões são independentes: a coluna usa só as que precisa, nos dois layouts, e os divisores
+acompanham as regiões presentes.
 
 ```tsx preview col
 render(
-  <div className="grid gap-4 md:grid-cols-2">
+  <div className="grid grid-cols-2 gap-4">
     <div className="h-56 overflow-hidden rounded-lg border border-border">
       <Pane className="h-full">
         <PaneHeader>
@@ -198,7 +248,7 @@ documento não muda a aparência da faixa.
 
 | Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
-| `children` | `ReactNode` | | Somente `PaneMedia`, `PaneTitle`, `PaneDescription` e `PaneActions`, no máximo um de cada. |
+| `children` | `ReactNode` | | `PaneMedia`, `PaneTitle`, `PaneDescription` e `PaneActions`, no máximo um de cada, e conteúdo livre, que aparece depois do título e da descrição. |
 | `className` | `string` | | Ajusta a faixa fixa sobre o recuo do layout. |
 
 ## Propriedades de PaneMedia

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

@@ -2,7 +2,8 @@
 
 Use `Popover` para apresentar conteúdo livre junto a um gatilho, sem abrir um modal.
 `PopoverHeader` agrupa título e descrição; o restante do painel aceita formulários curtos ou
-detalhes.
+detalhes. Para uma lista de ações, use [`Menu`](/ui/menu); para uma dica curta ao passar o ponteiro,
+use [`Tooltip`](/ui/tooltip).
 
 ```tsx preview
 <Popover>
@@ -12,7 +13,7 @@ detalhes.
   <PopoverContent align="start">
     <PopoverHeader>
       <PopoverTitle>Renomear</PopoverTitle>
-      <PopoverDescription>O slug técnico não muda — só o título.</PopoverDescription>
+      <PopoverDescription>O endereço da sessão continua o mesmo; só o título muda.</PopoverDescription>
     </PopoverHeader>
     <div className="mt-3 space-y-2">
       <Label htmlFor="pop-titulo">Título</Label>
@@ -23,9 +24,14 @@ detalhes.
 </Popover>
 ```
 
-## Alinhamento
+O painel mede `18rem` de largura por padrão e abre abaixo do gatilho. Clicar fora ou pressionar
+Esc fecha o painel.
 
-`align` posiciona o painel em relação ao gatilho e `sideOffset` define a distância entre eles.
+## Posição e largura
+
+`side` escolhe o lado preferido, `align` alinha o painel ao gatilho e `sideOffset` define a
+distância entre eles. Quando não há espaço no lado escolhido, o painel abre no lado oposto. Ajuste
+a largura com `className`, como `w-56` para `14rem`.
 
 ```tsx preview
 <Popover>
@@ -40,6 +46,12 @@ detalhes.
     <PopoverDescription>Alinhado à borda direita do gatilho.</PopoverDescription>
   </PopoverContent>
 </Popover>
+<Popover>
+  <PopoverTrigger asChild><Button variant="ghost">À direita</Button></PopoverTrigger>
+  <PopoverContent side="right" className="w-56">
+    <PopoverDescription>Abre ao lado direito do gatilho.</PopoverDescription>
+  </PopoverContent>
+</Popover>
 ```
 
 ## Propriedades de Popover
@@ -47,7 +59,15 @@ detalhes.
 | 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. |
+| `onOpenChange` | `(open: boolean) => void` | | Chamado quando o painel abre ou fecha; atualize `open` com o valor recebido. |
+| `defaultOpen` | `boolean` | `false` | Estado inicial no modo não controlado. |
+| `modal` | `boolean` | `false` | Com `true`, prende o foco no painel e bloqueia a interação com o restante da página enquanto ele está aberto. |
+
+## Propriedades de PopoverTrigger
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `asChild` | `boolean` | `false` | Faz do filho (por exemplo, um `Button`) o gatilho, em vez de renderizar outro `<button>`. |
 
 ## Propriedades de PopoverAnchor
 
@@ -59,5 +79,22 @@ não introduzir um nó extra; sem ele, o `PopoverTrigger` é a âncora.
 
 | Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
+| `side` | `'top' \| 'right' \| 'bottom' \| 'left'` | `'bottom'` | Lado preferido do painel; sem espaço, ele abre no lado oposto. |
 | `align` | `'start' \| 'center' \| 'end'` | `'center'` | Alinhamento do painel em relação ao gatilho. |
 | `sideOffset` | `number` | `4` | Distância entre o gatilho e o painel. |
+| `className` | `string` | | Classes do painel. A largura padrão é `w-72` (`18rem`). |
+
+## Propriedades de PopoverHeader
+
+`PopoverHeader` empilha `PopoverTitle` e `PopoverDescription` com espaçamento curto. Não tem props
+próprias; aceita as de um elemento `div`.
+
+## Propriedades de PopoverTitle
+
+`PopoverTitle` destaca o nome do painel com peso médio. Ele renderiza um `div`, sem nível de
+heading. Não tem props próprias; aceita as de um elemento `div`.
+
+## Propriedades de PopoverDescription
+
+`PopoverDescription` apresenta o texto de apoio em cor atenuada. Não tem props próprias; aceita as
+de um elemento `p`.

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

@@ -1,45 +1,11 @@
-`Presentation` preserva a identidade de um recurso quando o contexto pede uma página, um dialog ou
-um drawer. A superfície decide quanto espaço ocupar; o recurso continua com a mesma navegação,
-cabeçalho, body e rodapé.
-
-Dialog e Drawer mantêm no cabeçalho a ordem horizontal de navegação ou retorno, título e ações.
-O retorno aparece em uma surface modal somente
-quando ela foi aberta sobre outro Dialog ou Drawer; a Page ao fundo sustenta o modal, mas não cria
-uma etapa de navegação. Formulários modais dimensionam o footer pelo conteúdo, com `Cancelar` em
-`ghost` e a ação principal sólida.
-Em Page hospedada por `PageShell`, a barra concentra navegação e ações globais. Uma Presentation
-de listagem materializa título e comandos de header no `Content` que envolve o `ActionList`; assim
-a criação permanece próxima da coleção. Esses comandos usam o tamanho `default`: o que abre outra
-Presentation é um `Button` na variante padrão (`solid`), e uma action `simple` vira um
-`ActionTrigger` na variante `ghost`. Nas demais Presentations, o título abre o conteúdo em
-`PageIntro` e os comandos da superfície seguem a mesma regra.
-
-Use esse padrão quando uma lista puder abrir um detalhe lateral, quando a mesma edição precisar
-funcionar em modal e em rota própria ou quando um fluxo começar compacto e crescer sem ganhar uma
-segunda implementação.
-
-Dentro de `PageShell`, a superfície `page` usa a anatomia real da aplicação: a Presentation projeta
-navigation e actions globais por `PageHeader`, mantém a introdução no conteúdo quando existir e
-compõe `PageBody` e, quando necessário, `PageFooter`. Para uma action `list`, `PageBody` recebe
-`Content + ActionList`; o header da coleção recebe o título e os comandos declarados no placement
-`header`. Dialog e Drawer continuam usando o header da própria superfície.
-Os comandos da coleção ficam no extremo oposto ao título e permanecem textuais, mesmo quando a
-action declara um ícone. A criação usa `Criar recurso`, sem ícone, em um `Button` na variante
-padrão (`solid`) e no tamanho `default`.
-Não envolva a Presentation em um card para simular a página; valide proporção, rolagem e ações no
-shell que efetivamente hospeda a rota.
+Use `Presentation` quando o mesmo recurso precisa aparecer ora como página, ora como dialog, ora
+como drawer: uma lista que abre o detalhe ao lado, uma edição que funciona em modal e em rota
+própria, um fluxo que começa compacto e cresce sem ganhar uma segunda implementação. A superfície
+decide quanto espaço ocupar; o recurso mantém a mesma navegação, cabeçalho, corpo e rodapé.
 
-O exemplo declara a Presentation sobre um contrato de formulário e alterna a superfície. O
+O exemplo declara uma Presentation sobre um contrato de formulário e alterna a superfície. O
 `DocBrowserActionProvider` simula o cliente de actions; na aplicação, esse papel é do provider real.
 
-Quando o recurso aceita assistência contextual, declare somente o gatilho serializável em
-`assistant`. O renderer coloca esse gatilho no cabeçalho e abre o painel à direita do body da
-própria Page, Dialog ou Drawer. Cabeçalho e rodapé continuam ocupando toda a largura da superfície;
-enquanto o painel está aberto, o gatilho sai do cabeçalho e o próprio painel assume sua identidade
-visual. O dado vivo do recurso não entra na definição: a página que o carregou fornece
-`assistant.render`, captura identidade, nome e demais dados autorizados e monta o chat. Assim,
-contexto de conversa não vira autorização nem dado persistido no manifest.
-
 ```tsx live
 const workspacePresentation = definePresentation({
   schemaVersion: 1,
@@ -64,7 +30,7 @@ function Example() {
     <DocBrowserActionProvider>
       <div className="space-y-4">
         <ButtonGroup mode="spaced">
-          {["page", "dialog", "drawer"].map((value) => (
+          {(["page", "dialog", "drawer"] as const).map((value) => (
             <Button
               key={value}
               size="sm"
@@ -115,14 +81,48 @@ function Example() {
 render(<Example />);
 ```
 
+## Como cada superfície apresenta o recurso
+
+Em Dialog e Drawer, o cabeçalho da própria superfície reúne, nesta ordem, o retorno, o título e as
+ações. O retorno só aparece quando o modal foi aberto sobre outro Dialog ou Drawer: a página ao
+fundo sustenta o modal, mas não é uma etapa para onde voltar. Formulários modais dimensionam o
+rodapé pelo conteúdo, com `Cancelar` em `ghost` e a ação principal sólida.
+
+Dentro de [`PageShell`](/ui/page), a superfície `page` usa a anatomia real da aplicação. O
+`PageHeader` recebe só a navegação e as ações globais; o título abre o conteúdo em `PageIntro`, e o
+corpo vai para `PageBody`, com `PageFooter` quando há ações de rodapé.
+
+Uma Presentation de listagem exibida como página muda essa distribuição para manter a criação perto
+da coleção. O `PageBody` recebe um [`Content`](/ui/content) com a
+[`ActionList`](/ui/action-list), e o cabeçalho desse `Content` recebe o título e os comandos
+declarados com `placement: "header"`, no extremo oposto ao título. Os comandos de cabeçalho usam o
+tamanho `default` e permanecem textuais, mesmo quando a action declara um ícone: o que abre outra
+Presentation é um `Button` sólido, e uma action `simple` vira um
+[`ActionTrigger`](/ui/action-trigger) `ghost`. O rótulo vem do `label` da action, como `Criar workspace`.
+
+Não envolva a Presentation em um card para simular a página. Valide proporção, rolagem e ações no
+shell que efetivamente hospeda a rota.
+
+## Assistência contextual
+
+Quando o recurso aceita uma conversa sobre ele, declare em `assistant` somente o gatilho
+serializável, como no exemplo acima. O renderer coloca o gatilho no cabeçalho e abre o painel à
+direita do corpo da própria página, dialog ou drawer. Cabeçalho e rodapé continuam ocupando toda a
+largura; enquanto o painel está aberto, o gatilho sai do cabeçalho e o painel assume a identidade
+visual da assistência.
+
+O dado vivo do recurso não entra na definição. A página que carregou o recurso fornece
+`assistant.render`, reúne identidade, nome e demais dados autorizados e monta o chat. Assim, o
+contexto da conversa não vira autorização nem dado persistido no manifest.
+
 ## A declaração
 
 `definePresentation` cria o artefato serializável. O body recebe uma action `form`, `list` ou
-`view`; uma action `simple` aparece como comando no cabeçalho ou no rodapé. Em formulário,
-`body.submitLabel` sobrescreve o padrão “Salvar” quando a operação tem outro resultado observável,
-como “Renomear” ou “Criar nova versão”. Actions que precisam de
-interface abrem outra Presentation. Bindings fornecem valores vindos da rota, do registro, da
-seleção, da sessão ou do resultado anterior sem guardar callbacks no JSON.
+`view`, ou um componente React, descrito em “Conteúdo React no body”; uma action `simple` aparece
+como comando no cabeçalho ou no rodapé. Em formulário, `body.submitLabel` sobrescreve o padrão
+“Salvar” quando a operação tem outro resultado observável, como “Renomear” ou “Criar nova versão”.
+Actions que precisam de interface abrem outra Presentation. Bindings fornecem valores vindos da
+rota, do registro, da seleção, da sessão ou do resultado anterior sem guardar callbacks no JSON.
 
 Quando a exibição precisa sobreviver a refresh, deep link ou histórico, declare `route` na própria
 Presentation. O `path` aceita segmentos fixos e parâmetros como `:id`; `surface` determina como a
@@ -154,6 +154,48 @@ const workspaceList = definePresentation({
 });
 ```
 
+## Conteúdo React no body
+
+Uma tela que já existe em React pode adotar a casca da Presentation — rota, superfície, título,
+navegação e ações — sem migrar o miolo para actions declarativas de uma vez. Declare
+`body: { component }` com um identificador estável para esse conteúdo e passe o conteúdo como
+`children` do `Presentation`:
+
+```tsx
+const appearance = definePresentation({
+  schemaVersion: 1,
+  id: "settings.appearance",
+  title: "Aparência",
+  route: { path: "/settings/appearance", surface: "page" },
+  body: { component: "settings.appearance.content" },
+});
+
+<Presentation
+  definition={appearance}
+  definitions={[appearance]}
+  actions={{}}
+  invocation={invocation}
+>
+  <AppearanceSettings />
+</Presentation>;
+```
+
+O identificador de `component` vai para o manifest; o JSX, não. Uma Presentation com body de
+componente exige `children`, e uma com body de action os recusa: nos dois casos, a renderização
+lança um erro que nomeia a Presentation.
+
+Com `heading: "shell"`, o padrão, a casca emite o título da definição. Quando o conteúdo React já
+declara o heading principal da página, como um `Content level={1}`, use `heading: "content"`: dentro
+de `PageShell`, a casca deixa de emitir o `PageIntro` e o documento continua com um único `h1`. Em
+Dialog e Drawer, o título continua no cabeçalho da superfície.
+
+Se o conteúdo precisa ocupar a altura da página e controlar a própria rolagem, como uma lista com
+cabeçalho fixo, passe `layout="fill"` ao `Presentation`. Com o padrão `flow`, a página rola como um
+documento. Uma [`ActionList`](/ui/action-list) filha direta do conteúdo React recebe essa altura e
+assume `fill` sozinha.
+
+## Registrar as declarações
+
 Registre as declarações em `presentations` no `opus.config.ts`. `opus gen` valida as referências e
 projeta o JSON no manifest; a Lens pode então exibir o artefato completo sem reconstruí-lo a partir
 do JSX.
@@ -161,7 +203,7 @@ do JSX.
 ## A invocação
 
 `definePresentationInvocation` cria o estado vivo de uma exibição. Ele contém somente valores JSON,
-a surface atual e a pilha necessária para voltar. A definição continua estática no manifest; input
+a superfície atual e a pilha necessária para voltar. A definição continua estática no manifest; input
 de rota, sessão e resultado existe apenas na invocação.
 
 ```ts
@@ -194,7 +236,7 @@ no manifest e concentre a inspeção na Lens em vez de criar um launcher flutuan
 | `definition`         | `PresentationDefinition`                         |        | Artefato estático que descreve o recurso.                                                           |
 | `definitions`        | `PresentationDefinition[]`                       |        | Registry alcançável por navegação, abertura e retorno.                                              |
 | `actions`            | `PresentationActionRegistry`                     |        | Contratos compartilháveis referenciados pelo artefato.                                              |
-| `invocation`         | `PresentationInvocation`                         |        | Surface, input e pilha da exibição atual.                                                           |
+| `invocation`         | `PresentationInvocation`                         |        | Superfície, input e pilha da exibição atual.                                                        |
 | `bindingContext`     | `PresentationBindingContext`                     |        | Rota, item, seleção, sessão e resultado disponíveis.                                                |
 | `assistant`          | `PresentationAssistantRuntime`                   |        | Painel contextual fornecido pela superfície hospedeira.                                             |
 | `onInvocationChange` | `(next: PresentationInvocation \| null) => void` |        | Recebe navegação, retorno e fechamento.                                                             |
@@ -205,6 +247,8 @@ no manifest e concentre a inspeção na Lens em vez de criar um launcher flutuan
 | `onOpenChange`       | `(open: boolean) => void`                        |        | Notifica abertura e fechamento da superfície modal.                                                 |
 | `className`          | `string`                                         |        | Classes adicionais da superfície.                                                                   |
 | `bodyClassName`      | `string`                                         |        | Classes adicionais do body, aplicadas uma única vez.                                                |
+| `layout`             | `'flow' \| 'fill'`                               | `'flow'` | Em `page`, `fill` limita a altura ao shell e entrega a rolagem ao conteúdo do body; a lista de um body `list` ocupa essa altura e rola só os resultados. Dialog e Drawer ignoram. |
+| `children`           | `ReactNode`                                      |        | Conteúdo React do body declarado com `body.component`. Obrigatório nesse caso e recusado com `body.action`. |
 
 ## Propriedades de PresentationInspector
 

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

@@ -1,18 +1,26 @@
 ## Progresso determinado
 
-Use `Progress` quando a tarefa informar uma porcentagem de conclusão. `value` aceita valores de 0 a
-100 e anima o preenchimento a cada mudança. Sem valor, a barra permanece vazia.
+Use `Progress` quando a tarefa informar quanto já foi concluído. `value` aceita valores de 0 a
+`max`, que por padrão é 100, e anima o preenchimento a cada mudança. Para contar etapas, declare
+`max` com o total: `value={3} max={4}` preenche três quartos da barra. Quando a duração da espera
+não é conhecida, use [`Spinner`](/ui/spinner).
+
+A barra é exposta aos leitores de tela como `progressbar`, com o valor atual, mas o texto ao lado
+dela não a nomeia automaticamente. Ligue o rótulo visível à barra com `aria-labelledby` ou, sem
+rótulo visível, passe `aria-label`.
 
 ```tsx preview col
 <div className="w-full max-w-sm space-y-2">
   <div className="flex items-center justify-between text-sm">
-    <span>opus check</span>
+    <span id="progress-check">opus check</span>
     <span className="text-muted-foreground">65%</span>
   </div>
-  <Progress value={65} />
+  <Progress value={65} aria-labelledby="progress-check" />
 </div>
 ```
 
+Sem `value`, ou com `null`, a barra fica vazia e é exposta como progresso indeterminado.
+
 ## Controlado
 
 Controle `value` externamente quando o progresso acompanhar uma tarefa em andamento. No exemplo,
@@ -20,15 +28,16 @@ cada clique avança uma etapa da sincronização.
 
 ```tsx preview col
 const [step, setStep] = useState(40)
+const labelId = useId()
 const advance = (): void => setStep((prev) => Math.min(prev + 20, 100))
 
 render(
   <div className="w-full max-w-sm space-y-3">
     <div className="flex items-center justify-between text-sm">
-      <span>Sincronizar Empresa X</span>
+      <span id={labelId}>Sincronizar Empresa X</span>
       <span className="text-muted-foreground">{step}%</span>
     </div>
-    <Progress value={step} />
+    <Progress value={step} aria-labelledby={labelId} />
     <Button variant="outline" size="sm" onClick={advance}>
       Avançar etapa
     </Button>
@@ -39,18 +48,19 @@ render(
 ## Altura e contexto
 
 `context` diz o que o andamento comunica — `success` para meta atingida, `warning` ou `danger`
-para atenção — e tinge trilha e preenchimento com a família semântica. `className` compõe sobre o
-padrão para ajustar a altura.
+para atenção — e tinge trilha e preenchimento com a família semântica. A cor reforça o significado,
+mas não o substitui: mantenha o rótulo e o valor legíveis. `className` compõe sobre o padrão para
+ajustar a altura.
 
 ```tsx preview col
 <div className="w-full max-w-sm space-y-4">
   <div className="space-y-1.5">
-    <span className="text-sm">Cobertura de testes</span>
-    <Progress value={92} context="success" className="h-1.5" />
+    <span id="progress-coverage" className="text-sm">Cobertura de testes</span>
+    <Progress value={92} context="success" className="h-1.5" aria-labelledby="progress-coverage" />
   </div>
   <div className="space-y-1.5">
-    <span className="text-sm">Skills cobertas pelo revisor</span>
-    <Progress value={45} context="warning" className="h-3" />
+    <span id="progress-review" className="text-sm">Skills cobertas pelo revisor</span>
+    <Progress value={45} context="warning" className="h-3" aria-labelledby="progress-review" />
   </div>
 </div>
 ```
@@ -59,6 +69,9 @@ padrão para ajustar a altura.
 
 | Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
-| `value` | `number \| null` | | O progresso de 0 a 100. O preenchimento anima a cada mudança; null/ausente deixa a barra vazia. |
+| `value` | `number \| null` | | O progresso de 0 a `max`. O preenchimento anima a cada mudança; sem valor, a barra fica vazia e indeterminada. |
+| `max` | `number` | `100` | O valor que representa a conclusão. O preenchimento é a fração `value / max`. |
 | `context` | `'neutral' \| 'primary' \| 'info' \| 'success' \| 'warning' \| 'danger'` | `'primary'` | O que o andamento comunica; tinge trilha e preenchimento pela família `--context-*`. |
-| `className` | `string` | | Compõe sobre o padrão — ajuste a altura (h-1.5/h-3). |
+| `aria-label` | `string` | | Nome acessível da barra quando não há rótulo visível. |
+| `aria-labelledby` | `string` | | `id` do rótulo visível que nomeia a barra. |
+| `className` | `string` | | Compõe sobre o padrão — ajuste a altura (`h-1.5`, `h-3`). |

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

@@ -5,7 +5,7 @@ title: Filas
 # Filas
 
 Use uma action em background quando a operação não puder manter a requisição aberta. O
-`QueueAdapter` enfileira o trabalho e devolve um `JobHandle` para acompanhamento pelo cliente.
+`QueueAdapter` enfileira o trabalho e devolve um `JobHandle` para acompanhar o andamento.
 
 ## O contrato
 
@@ -21,18 +21,21 @@ interface JobHandle<T = unknown> {
   jobId: string
   action: string
   status: 'queued' | 'running' | 'done' | 'failed' | 'cancelled'
-  progress?: { percent?: number; message?: string }
+  progress?: { percent?: number; message?: string; data?: unknown }
   data?: T
   error?: ActionError
+  enqueuedAt: string
+  startedAt?: string
+  finishedAt?: string
   attempts: number
   trace?: TraceContext
 }
 ```
 
-`runtime.execute()` valida a chamada, cria o `JobSpec` e inclui o trace efetivo, request ID e
-provenance original. O adapter persiste o envelope; o handle também expõe esse trace. No
-worker, `runtime.executeJob()` revalida o envelope e executa um span filho, preservando a
-cadeia request → enqueue → job sem aceitar baggage ou campos extras no carrier.
+`runtime.execute()` valida a chamada, cria o `JobSpec` e inclui o trace efetivo, o request ID e a
+provenance original. O adapter persiste esse envelope, e o handle também expõe o trace. No worker,
+`runtime.executeJob()` revalida o envelope e executa um span filho, preservando a cadeia requisição
+→ enfileiramento → job sem aceitar baggage ou campos extras.
 
 ## Driver
 
@@ -43,26 +46,41 @@ import { bullmqQueue } from '@softize/opus/queue/bullmq'
 const queue = bullmqQueue({ queue: new Queue('opus', { connection: { host: 'localhost' } }) })
 ```
 
-Redis-backed (durável, entre-processos, retries). Peers opcionais (`bullmq`, `ioredis`) só
-para quem usa o driver.
+O driver usa Redis por meio do BullMQ, com durabilidade, entrega entre processos e novas tentativas.
+`bullmq` é dependência opcional: só precisa ser instalado por quem usa o driver.
 
-## No runtime
+## Declarar a action em background
+
+Configure a fila no runtime e declare `background` no binding da action:
 
 ```ts
 const runtime = createRuntime({
   // …server/data…
   queue,
 })
+
+export const relatorioGerar = bindAction(relatorioGerarContract, {
+  background: { enabled: true, retry: { attempts: 3 }, progress: true },
+  handler: async (ctx, input, loaded, progress) => {
+    await progress?.report({ percent: 50, message: 'Consultando dados' })
+    return gerarRelatorio(input)
+  },
+})
 ```
 
-A action declara `background: { enabled: true }` (+ retry/priority no contrato); chamá-la devolve um
-`JobHandle` em vez do resultado, e o cliente pola `status(jobId)` (ou `subscribe`) até
-`done`/`failed`.
+Só actions `simple` e `form` executam em background; além de `retry` e `progress`, a configuração
+aceita `queue`, `priority` e `timeout`. Em uma action `list` ou `view`, o tipo do binding aceita
+`background`, mas o runtime o ignora e executa a action na própria requisição. Para evitar essa
+surpresa, o runtime avisa ao registrar a action fora de produção (`runtime.action_field_ignored`), e
+o [`opus check`](/docs/cli) aponta a regra `ignored-by-kind`. Sem `QueueAdapter`, a chamada falha com
+`runtime.queue_required`. Chamar a action devolve um `JobHandle` em vez do resultado. O Opus não
+monta uma rota de acompanhamento: exponha `queue.status(jobId)` ou `queue.subscribe` por uma action
+ou rota do próprio app até o job chegar a `done` ou `failed`.
 
 ## Worker BullMQ
 
-O app continua dono do `Worker` e da reidratação de autenticação. O processor chama
-`executeJob()` — nunca `execute()`, que criaria outro job:
+O app continua dono do `Worker` e de reconstruir a autenticação de quem enfileirou. O processor
+chama `executeJob()`, e não `execute()`, que criaria outro job:
 
 ```ts
 new Worker('opus', async (job) => {
@@ -76,13 +94,13 @@ new Worker('opus', async (job) => {
 }, { connection })
 ```
 
-O runtime confirma que o actor reidratado corresponde a `spec.ctx.userId`; tenant, request,
-trace e provenance vêm do envelope. O driver mapeia `attempts`, backoff nativo e prioridade.
-Multiplicador exponencial diferente de 2 ou `maxMs` exige `backoffStrategy` custom do worker e
-é rejeitado pelo driver em vez de ser silenciosamente ignorado. `timeout` permanece no
-envelope para o worker aplicar, pois não é uma opção de execução do `Queue.add`.
+O runtime confirma que o usuário reconstruído corresponde a `spec.ctx.userId`; tenant, request,
+trace e provenance vêm do envelope. O driver traduz `attempts`, o backoff nativo e a prioridade para
+o BullMQ. Um backoff exponencial com multiplicador diferente de 2 ou com `maxMs` exige uma
+`backoffStrategy` própria no worker, e o driver o recusa em vez de ignorá-lo em silêncio. `timeout`
+permanece no envelope para o worker aplicar, porque não é uma opção de execução do `Queue.add`.
 
 ## Limites atuais
 
-Driver hoje: `bullmq` (Redis). In-memory para dev e outros backends (SQS, pg-boss…) entram
-por reincidência.
+O único driver é o `bullmq`. Uma fila em memória para desenvolvimento e outros backends, como SQS e
+pg-boss, ainda não existem.