@softize/opus 12.11.0 → 13.1.0

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

@@ -1,7 +1,8 @@
-## Padrão (single)
+## Um painel por vez
 
-`type=single` abre um painel por vez. `collapsible` deixa fechar o que está aberto — sem ele,
-sempre fica um item expandido. `defaultValue` deixa o estado com o componente.
+Use `type="single"` quando somente um painel deve permanecer aberto. Com `collapsible`, a pessoa
+também pode fechar o painel atual; sem essa propriedade, um item permanece expandido.
+`defaultValue` define o item inicialmente aberto no modo não controlado.
 
 ```tsx preview
 <Accordion type="single" collapsible defaultValue="overview" className="w-full">
@@ -28,8 +29,8 @@ sempre fica um item expandido. `defaultValue` deixa o estado com o componente.
 
 ## Múltiplos abertos
 
-`type=multiple` permite vários painéis expandidos ao mesmo tempo — `defaultValue` vira um
-array com os itens abertos de saída.
+Use `type="multiple"` quando os painéis puderem permanecer abertos ao mesmo tempo. Nesse modo,
+`defaultValue` recebe um array com os itens inicialmente expandidos.
 
 ```tsx preview
 <Accordion type="multiple" defaultValue={['skills', 'prompt']} className="w-full">
@@ -48,10 +49,10 @@ array com os itens abertos de saída.
 </Accordion>
 ```
 
-## Controlado (com estado)
+## Estado controlado
 
-No modo `single`, `value`/`onValueChange` tiram o estado do componente — dá pra abrir um item
-de fora. Exemplo **com estado** (o `render()` deixa o hook rodar):
+Use `value` e `onValueChange` quando outro elemento ou estado do aplicativo também precisar
+controlar o painel aberto.
 
 ```tsx preview
 const [open, setOpen] = React.useState('developer')
@@ -74,13 +75,18 @@ render(
 )
 ```
 
-## Props
+## Propriedades de Accordion
 
-| Prop | Tipo | Default | Descrição |
+| Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
-| `type` (Accordion) | `'single' \| 'multiple'` | | single abre um painel por vez; multiple permite vários. |
-| `collapsible` (Accordion) | `boolean` | `false` | Só no single — permite fechar o item aberto. |
-| `defaultValue` (Accordion) | `string \| string[]` | | Item(ns) aberto(s) no modo não controlado. |
-| `value` (Accordion) | `string \| string[]` | | Item(ns) aberto(s) no modo controlado — pareie com onValueChange. |
-| `onValueChange` (Accordion) | `(value) => void` | | Chamado quando o usuário abre ou fecha um item. |
-| `value` (AccordionItem) | `string` | | Identificador do item — é o que defaultValue/value referenciam. |
+| `type` | `'single' \| 'multiple'` | | `single` abre um painel por vez; `multiple` permite manter vários abertos. |
+| `collapsible` | `boolean` | `false` | No modo `single`, permite fechar o item aberto. |
+| `defaultValue` | `string \| string[]` | | Item ou itens inicialmente abertos no modo não controlado. |
+| `value` | `string \| string[]` | | Item ou itens abertos no modo controlado. Use com `onValueChange`. |
+| `onValueChange` | `(value) => void` | | Chamado quando a pessoa abre ou fecha um item. |
+
+## Propriedades de AccordionItem
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `value` | `string` | | Identificador usado por `defaultValue` e `value` no `Accordion`. |

package/src/ui/docs/content/action-form-card.md

@@ -1,7 +1,7 @@
-## Form como card
+## Formulário em uma seção
 
-O ActionForm dentro de um Card — header, conteúdo e rodapé, no respiro do Card (sem divisor nem
-faixa de modal). Pra estruturar uma seção da página como painel. O título é opcional.
+Use `ActionFormCard` para apresentar um `ActionForm` como seção delimitada da página. O componente
+aplica a estrutura e o espaçamento de `Card`, sem a faixa de ações de um modal. O título é opcional.
 
 ```tsx preview col md
 <DocBrowserActionProvider>
@@ -14,11 +14,11 @@ faixa de modal). Pra estruturar uma seção da página como painel. O título é
 </DocBrowserActionProvider>
 ```
 
-## Props
+## Propriedades de ActionFormCard
 
-| Prop | Tipo | Default | Descrição |
+| Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
-| `title` | `string` | | Título do header (com divisor embaixo). Sem ele, o card começa direto no corpo. |
+| `title` | `string` | | Título do cabeçalho. Sem ele, o card começa diretamente pelo corpo. |
 | `description` | `string` | | Subtítulo opcional, abaixo do título. |
-| `action / defaultValues / fieldOptions / submitLabel / onSuccess / onCancel` | `— (iguais ao ActionForm)` | | O resto é o ActionForm — o card injeta o corpo (CardBody) e o rodapé (CardFooter) por baixo. |
-| `cardClassName` | `string` | | Classes da SUPERFÍCIE do card (ex.: largura). `className` vai pro `<form>`. |
+| `action / defaultValues / fieldOptions / submitLabel / onSuccess / onCancel` | Propriedades de `ActionForm` | | Mantêm o mesmo comportamento do formulário interno. |
+| `cardClassName` | `string` | | Classes aplicadas à superfície do card. `className` continua sendo aplicado ao `<form>`. |

package/src/ui/docs/content/action-form-dialog.md

@@ -1,8 +1,8 @@
-## Form em modal
+## Formulário em um modal
 
-O open é de quem orquestra; o fechamento no sucesso é do pattern. Header e X fixos, os campos
-scrollam, o rodapé é a faixa da casa. O preview roda num client de mentira — no app, o contrato
-vem do spec.
+Use `ActionFormDialog` quando o formulário precisar interromper o fluxo atual sem levar a pessoa
+para outra página. O consumidor controla `open`; depois de uma execução bem-sucedida, o componente
+fecha o modal. O cabeçalho e o rodapé permanecem visíveis enquanto os campos podem rolar.
 
 ```tsx preview
 const [open, setOpen] = useState(false)
@@ -22,11 +22,11 @@ render(
 )
 ```
 
-## Props
+## Propriedades de ActionFormDialog
 
-| Prop | Tipo | Default | Descrição |
+| Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
-| `open / onOpenChange` | `boolean / (open: boolean) => void` | | Controle do modal — o pattern chama onOpenChange(false) no sucesso e no Cancelar. |
-| `title / description` | `string` | | O DialogHeader fixo — description é opcional. |
+| `open / onOpenChange` | `boolean / (open: boolean) => void` | | Estado controlado do modal. `onOpenChange(false)` é chamado no sucesso e ao cancelar. |
+| `title / description` | `string` | | Conteúdo do cabeçalho; `description` é opcional. |
 | `submitLabel` | `string` | `'Salvar'` | Resultado da ação principal. Em criação, informe `Criar {recurso}`; em edição, `Salvar alterações`. |
-| `…ActionFormProps` | `action, defaultValues, onSuccess, fieldOptions…` | | Todo o resto desce pro ActionForm interno — mesma API da página dele. |
+| `…ActionFormProps` | `action, defaultValues, onSuccess, fieldOptions…` | | Demais propriedades repassadas ao `ActionForm` interno. |

package/src/ui/docs/content/action-form.md

@@ -1,8 +1,8 @@
-## Form derivado do contrato
+## Formulário derivado do contrato
 
-Zero JSX de campo: enum vira Select, string longa vira Textarea, obrigatório ganha o asterisco. O
-preview roda num client de mentira — digite "Softize" no nome pra ver o erro de servidor inline; o
-submit só habilita com mudança real (dirty).
+Use `ActionForm` para gerar campos, validação e mensagens a partir de uma `FormAction`. Sem
+`children`, o componente escolhe o controle adequado para cada campo e preserva a ordem declarada
+no contrato. No exemplo, altere um valor para habilitar a ação principal.
 
 ```tsx preview col md
 <DocBrowserActionProvider>
@@ -10,13 +10,12 @@ submit só habilita com mudança real (dirty).
 </DocBrowserActionProvider>
 ```
 
-## Composição (diagramação livre)
+## Composição dos campos
 
-Com children, o AUTO desliga e você diagrama: `<ActionFormField name />` coloca cada campo — com
-label, hint, widget, erro e asterisco derivados do contrato — onde quiser. Condicional é JSX;
-opções de runtime entram por prop no campo. O comportamento (submit, validação, toast,
-invalidação) continua encapsulado — e o espaçamento é 100% seu: o campo não impõe margem
-(quem diagrama usa grid/gap/space-y como quiser).
+Passe `children` quando a disposição automática não atender ao formulário. Cada
+`ActionFormField` mantém rótulo, ajuda, controle, obrigatoriedade e erro derivados do contrato;
+o consumidor define apenas a grade, as condições e o espaçamento. Execução, validação, toast e
+invalidação continuam sob responsabilidade de `ActionForm`.
 
 ```tsx preview col md
 <DocBrowserActionProvider>
@@ -35,8 +34,8 @@ invalidação) continua encapsulado — e o espaçamento é 100% seu: o campo n
 
 ## Valores iniciais e rótulos
 
-defaultValues pré-carrega (modo edição); submitLabel/cancelLabel trocam o rodapé. O onCancel é de
-quem orquestra (fechar drawer, voltar…).
+`defaultValues` preenche o formulário para edição. `submitLabel` e `cancelLabel` nomeiam as ações;
+`onCancel` devolve ao consumidor a decisão de fechar um painel ou navegar para outra página.
 
 ```tsx preview col md
 <DocBrowserActionProvider>
@@ -51,47 +50,50 @@ quem orquestra (fechar drawer, voltar…).
 
 ## Pré-requisitos
 
-O driver precisa dos dois providers no root — exatamente o wiring do admin (o consumidor
-canônico).
+Monte os providers de consulta e execução uma vez na raiz do aplicativo:
 
 ```tsx
 /* main.tsx do app. */
 <QueryClientProvider client={queryClient}>
-  <TbdlibProvider client={apiClient}>
+  <OpusProvider client={apiClient}>
     <App />
-  </TbdlibProvider>
+  </OpusProvider>
 </QueryClientProvider>
 ```
 
-## Props
+## useFormAction
 
-| Prop | Tipo | Default | Descrição |
+`ActionForm` é uma composição sobre `useFormAction(action, { defaultValues, onSuccess, onError })`,
+que devolve o `form` do react-hook-form já com o resolver Zod em pt-BR, `submit`, `isLoading`,
+`error`, `isSuccess` e `reset`. Use o hook direto quando o formulário precisar de um layout ou de um
+ciclo de vida que o pattern não cobre; validação e execução continuam iguais.
+
+## Propriedades de ActionForm
+
+| Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
 | `action` | `FormContract<TInput, TData>` | | O contrato da FormAction — dele saem campos (input Zod + fields), mensagens e invalidação de cache. |
 | `defaultValues` | `Partial<TInput>` | | Valores iniciais — o modo edição de um update/patch. |
 | `onSuccess` | `(data: TData) => void` | | Pós-sucesso (o toast e a invalidação de cache já aconteceram). |
 | `submitLabel / cancelLabel / onCancel` | `string / string / () => void` | `'Salvar' / 'Cancelar'` | Rodapé do form — o Cancelar só aparece com onCancel. |
 | `fieldOptions` | `Record<string, SelectOption[]>` | | Opções de runtime por campo (ex.: ids de skills) — sobrepõe as inferidas do z.enum. |
-| `className / body / footer` | `string / (node) => node / (node) => node` | | className = classes do `<form>`. body/footer = SLOTS: recebem os campos / os botões e escolhem o invólucro — é como o ActionFormDialog injeta DialogBody/DialogFooter (scroll + faixa). |
-| `children` | `ReactNode` | | Modo COMPOSIÇÃO: diagrame com `<ActionFormField name />`. Sem children, o AUTO monta todos os campos na ordem do contrato. |
+| `className / body / footer` | `string / (node) => node / (node) => node` | | className = classes do `<form>`. body/footer = slots: recebem os campos / os botões e escolhem o invólucro — é como o ActionFormDialog injeta DialogBody/DialogFooter (scroll + faixa). |
+| `children` | `ReactNode` | | Modo composição: diagrame com `<ActionFormField name />`. Sem children, o automático monta todos os campos na ordem do contrato. |
 
-## ActionFormField
+## Propriedades de ActionFormField
 
-| Prop | Tipo | Descrição |
+| Propriedade | Tipo | Descrição |
 |---|---|---|
 | `name` | `string` | O campo do contrato (chave em `fields`/schema). Fora do schema, não renderiza. |
 | `options` | `SelectOption[]` | Opções por id de runtime — sobrepõe o fieldOptions do form e o z.enum. |
-| `className` | `string` | Classes do invólucro (ex.: `col-span-2` numa grid). |
+| `className` | `string` | Classes do invólucro (ex.: `col-span-2` em uma grid). |
 
-## De onde vêm as opções de um select
+## Origem das opções de seleção
 
-Precedência, da mais específica pra mais automática: **prop `options` do campo** >
-**`fieldOptions` do form** > **`options` do FieldSpec no contrato** (`{ kind: 'dictionary',
-ref }` resolve pelos dicts do `<TbdlibProvider dicts={{ ref: meuDict }}>` — o `DictType` do
-`t.dict` encaixa direto; `{ kind: 'static', items }` renderiza como declarado) > **meta do
-`t.dict` no schema** (zero-config: campo `meuDict.zod()` — ou multiselect com elemento dict —
-resolve value→label pela meta que viaja no contrato, sem registry) > **chaves cruas do
-z.enum**. Campo texto com opções declaradas (runtime ou spec) vira single-select por-id.
+As opções seguem esta precedência: `options` no campo, `fieldOptions` no formulário, `options` no
+`FieldSpec`, metadata de `t.dict` no schema e, por último, as chaves de `z.enum`. Uma fonte mais
+específica substitui as seguintes. Dicionários registrados no `OpusProvider` resolvem rótulos por
+referência; itens estáticos permanecem como declarados no contrato.
 
 ## Widgets declarativos
 
@@ -103,11 +105,10 @@ escolha rica em card, com conteúdo de apoio; para uma lista textual comum, pref
 Outros identificadores continuam válidos como metadado
 para renderers próprios; o `ActionForm` aplica sua inferência normal quando não reconhece o widget.
 
-## Controle custom: useActionFormContext
+## Controle próprio com useActionFormContext
 
-Campo com UI própria (grade de permissões, canvas…) que nenhum widget cobre? No modo
-composição, o hook dá acesso ao form do contrato — o campo custom participa do submit
-sem abandonar o `<ActionForm>`:
+Quando nenhum widget atender ao campo, use `useActionFormContext` no modo de composição. O controle
+próprio participa da mesma validação e execução sem abandonar o `ActionForm`:
 
 ```tsx
 import { useActionFormContext } from '@softize/opus/ui/react'
@@ -132,4 +133,4 @@ function PermissionGrid() {
 ```
 
 O contexto também expõe `shape` (Zod por campo), `fields` (FieldSpec) e `fieldOptions`.
-Fora de um `<ActionForm>`, o hook explode com mensagem clara — igual ao `ActionFormField`.
+Fora de um `<ActionForm>`, o hook lança um erro que informa o provider ausente.

package/src/ui/docs/content/action-list-dialog.md

@@ -1,6 +1,9 @@
-## ListAction em modal
+## Listagem em um modal
 
-O modo modal da listagem, action-driven: a lista é query-backed (busca no mount, re-busca quando o input muda e refaz sozinha quando um form/trigger invalida a action), os estados derivam do fetch, e a nota da toolbar já vem com o "N no total". Children diagrama os itens — composição, como nos irmãos.
+Use `ActionListDialog` para consultar e apresentar uma `ListAction` sem sair do contexto atual. A
+lista carrega ao abrir, refaz a consulta quando `input` muda e acompanha invalidações declaradas por
+outras actions. O consumidor compõe os itens por `children`; o modal mantém os estados e a barra de
+ações.
 
 ```tsx preview col
 const [open, setOpen] = useState(false)
@@ -38,9 +41,11 @@ render(
 )
 ```
 
-## O que o contrato não sabe
+## Estado adicional do consumidor
 
-Dois escape hatches, pros casos em que o modal agrega mais de uma fonte: `loading` soma a carga de uma query irmã (ex.: os papéis que os cards precisam pra rotular) e `empty` sobrepõe o vazio derivado (ex.: com o form inline de criar aberto, a lista vazia mostra o form, não o emptyText).
+Quando o modal depender de outra consulta, `loading` combina esse carregamento ao estado da lista.
+Use `empty` para substituir a regra de vazio, por exemplo enquanto um formulário de criação ocupa o
+corpo do modal.
 
 ```tsx
 <ActionListDialog
@@ -52,9 +57,9 @@ Dois escape hatches, pros casos em que o modal agrega mais de uma fonte: `loadin
 />
 ```
 
-## Props
+## Propriedades de ActionListDialog
 
-| Prop | Tipo | Default | Descrição |
+| Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
 | `action / input` | `ListAction / TInput` | | O contrato e os filtros — mudou o input, re-busca; `invalidates` de forms/triggers refaz sozinho. |
 | `open / onOpenChange` | `boolean / (open) => void` | | Controle do modal — de quem orquestra. |

package/src/ui/docs/content/action-list.md

@@ -1,6 +1,12 @@
-## Declarativo pelo contrato (a diagramação da casa)
+## Listagem derivada do contrato
 
-O contrato descreve, a UI deriva — zero configuração no call site. `columns` vira a tabela emoldurada (o datagrid da casa; tipos text/number/date/badge, `fit`, `hidden`, headers ordenáveis que escrevem `sort: 'chave:dir'` no input); `filters` vira a toolbar (os não-avançados inline, os `advanced: true` no modal "Filtros" com contador); `text` liga a busca (param `q`); filtros do modal aplicados viram chips removíveis. A linha é RESPONSIVA: a busca tem largura auto (encolhe primeiro) e filtro inline que não cabe migra pro modal — medição real, re-avaliada no resize; só no caso extremo (nada mais a ceder) a linha quebra. O handler implementa o que o input diz (orderBy, where) — mesmo modelo do resto do Opus.
+Use `ActionList` para apresentar uma coleção pesquisável descrita por uma `ListAction`. O contrato
+define colunas, busca, filtros, período, ordenação e paginação; a interface materializa esses
+recursos e envia o estado correspondente no input. Filtros avançados aparecem no modal “Filtros” e
+os filtros aplicados permanecem visíveis como chips removíveis.
+
+A barra se adapta ao espaço disponível. A busca cede largura primeiro e filtros que deixam de caber
+migram para o modal; a linha só quebra quando nenhum controle restante puder ceder espaço.
 
 ```tsx preview col
 render(
@@ -28,18 +34,16 @@ superfícies que não são listagens, como relatórios. O estado é controlado p
 />
 ```
 
-Selects inline têm largura fixa e previsível (`w-40`; lookup e múltiplo `w-52`): nem a label nem
-o valor selecionado alargam o controle — o rótulo trunca e a opção inteira continua na lista. No
-modal de filtros avançados, o select ocupa a largura toda. Busca e filtros são renderizados
-somente quando declarados. Períodos incluem os presets do
-contrato e o intervalo personalizado no mesmo calendário usado pela `ActionList`.
+Seletores inline mantêm largura previsível (`w-40`; lookup e múltiplo usam `w-52`). Rótulos longos
+são truncados no controle, mas permanecem completos na lista. No modal de filtros avançados, o
+seletor ocupa toda a largura. Busca, filtros e período aparecem somente quando declarados.
 
 ## Colunas de dicionário
 
-Coluna cujo campo no schema de saída é um `t.dict().zod()` renderiza `DictionaryValue` com a
-apresentação que o dicionário declarou (`presentation`: classificação em badge `outline`, status
-e estágio em badge tonal, `plain` ou ausente como texto). Nada a configurar na tela. Quando o
-campo de saída é uma string comum, a coluna nomeia o dicionário registrado no provider:
+Quando o campo de saída usa `t.dict().zod()`, a coluna apresenta o valor com `DictionaryValue` e
+respeita o papel declarado pelo dicionário. Classificações usam badge `outline`; status e estágio
+usam badge tonal; `plain` e papéis ausentes permanecem como texto. Para um campo `string`, a coluna
+pode indicar um dicionário registrado no provider:
 `{ key: 'source', label: 'Fonte', dictionary: 'customerSource' }`. Dimensões independentes, como
 tipo e estágio, ficam em colunas distintas — a leitura de comparação depende disso. `type:
 'badge'` continua sendo o chip `outline` legado; com dicionário, ele mostra o rótulo em vez do
@@ -56,7 +60,8 @@ Renderer customizado reutiliza `EmptyValue`.
 
 ## Células custom (cells)
 
-As colunas do contrato descrevem DADOS; apresentação especial entra por cima com `cells` (chave = key da coluna). É onde vivem links, composições e a coluna de ações; valor de dicionário já resolve sozinho pela coluna, sem `cells`.
+Use `cells` somente quando uma coluna precisar de apresentação própria, como link, composição ou
+ação. A chave corresponde à `key` da coluna. Valores de dicionário não precisam desse override.
 
 ```tsx preview col
 render(
@@ -78,9 +83,12 @@ render(
 )
 ```
 
-## Período (o campo dinâmico)
+## Período obrigatório
 
-Com `periods` no contrato, a toolbar ganha o controle de período: um popover com os presets e, no "Personalizado", o calendário de range ali mesmo. Período é recorte OBRIGATÓRIO do caso de uso: o default (o preset com `default: true`, ou o primeiro) já vem aplicado e não existe "sem período". O preset fica RELATIVO na URL (`?period=last7`; o default é omitido); no custom o range vai direto no param (`?period=2026-07-01..2026-07-07` — o "custom" é implícito). No fetch, o pattern materializa o range nos params `from`/`to` — o handler implementa o recorte.
+Quando o contrato declara `periods`, a listagem sempre possui um recorte temporal. O preset marcado
+com `default: true`, ou o primeiro da coleção, começa aplicado. Presets usam um valor relativo na
+URL, como `?period=last7`; o padrão é omitido. Um intervalo personalizado usa diretamente as datas,
+como `?period=2026-07-01..2026-07-07`, e chega ao handler pelos parâmetros `from` e `to`.
 
 ```tsx
 periods: [
@@ -89,15 +97,23 @@ periods: [
   { value: 'thisMonth', label: 'Este mês' },
 ]
 // Presets computáveis: today · yesterday · last7 · last30 · thisMonth · lastMonth.
+// presetRange('last7') → { from: 'YYYY-MM-DD', to: 'YYYY-MM-DD' } — o mesmo cálculo do pattern.
 ```
 
-## Paginação e loading
+## Paginação e carregamento
 
-O pattern manda `limit` (= `pageSize`, default 50) e `page` no input; o handler implementa o OFFSET e devolve `total` no Paginated. O rodapé (Página X de Y · páginas numeradas com reticências · "N itens no total") compõe a primitiva `Pagination` na escala densa — números com largura mínima que cresce com os dígitos, setas quadradas, nome acessível por página — e aparece sempre que há total; mudar filtro/busca/sort/período volta pra página 1 (a página vive na URL: `?page=2`). No primeiro carregamento, `DataState` centraliza o spinner; no refetch com a lista já na tela, o corpo esmaece (`aria-busy`) até os dados chegarem.
+`ActionList` envia `limit`, definido por `pageSize`, e `page` no input. O handler aplica o recorte e
+devolve `total` na resposta paginada. Quando existe total, o rodapé mostra a página atual, os links
+disponíveis e a quantidade de itens. Alterar busca, filtro, ordenação ou período retorna à primeira
+página. Durante a primeira consulta, `DataState` apresenta o carregamento; em atualizações
+posteriores, a lista permanece visível com `aria-busy`.
 
-## Multi-seleção com can (batch)
+## Ações em lote
 
-`batch` liga a coluna de checkbox na tabela. O `can(item)` é a fonte única de elegibilidade: linha inelegível não marca, o "selecionar todos" pega só os elegíveis, o botão mostra quantos dos selecionados valem e o `run` recebe apenas esses. Com `confirm`, um dialog pede confirmação; ao resolver, a seleção limpa e a lista refaz.
+`batch` acrescenta seleção à tabela. `can(item)` determina quais linhas podem participar: itens
+inelegíveis não são selecionáveis, “Selecionar todos” inclui somente os elegíveis e `run` recebe
+apenas essa seleção. Com `confirm`, o componente pede confirmação antes de executar. Ao concluir, a
+seleção é limpa e a consulta é refeita.
 
 ```tsx
 <ActionList action={runList} input={{}}
@@ -110,9 +126,12 @@ O pattern manda `limit` (= `pageSize`, default 50) e `page` no input; o handler
 />
 ```
 
-## Views (a mesma listagem, outro renderer)
+## Outras visualizações
 
-Nem toda listagem é tabela: board, galeria, lista, calendário… A view é APRESENTAÇÃO de quem chama (`render`); o pattern dá o segment na toolbar (ToggleGroup, ICON-ONLY: declare `icon` — o label vira title/aria; sem ícone cai pro texto), o estado (`view` na URL) e os dados — a mesma fonte, os mesmos filtros. A tabela ('Tabela') participa quando há columns.
+Uma coleção também pode aparecer como quadro, galeria, lista ou calendário. Cada entrada de `views`
+fornece um `render`; `ActionList` preserva a mesma fonte de dados, filtros e estado na URL. Declare
+`icon` para controles somente com ícone; sem ele, o rótulo permanece visível. A visualização
+“Tabela” aparece quando existem colunas.
 
 ```tsx preview col
 render(
@@ -146,13 +165,16 @@ render(
 )
 ```
 
-## Filtros dependentes, dictionary e lookup
+## Filtros dependentes e opções remotas
 
-Três recursos do FilterSpec que a toolbar honra:
+`FilterSpec` também cobre dependências, dicionários e consultas remotas:
 
-- **`depends: ['outroFiltro']`** — o filtro dependente fica DESABILITADO até o pai ter valor, e mudar o pai limpa o dependente em cascata (o recorte perde o sentido quando o pai muda). Vale inline e no modal.
-- **`options: { kind: 'dictionary', ref: 'sessionStatus' }`** — as opções vêm de um DICT registrado no `<TbdlibProvider dicts={{ sessionStatus: statusDict }}>` (o `DictType` do `t.dict` encaixa direto). Labels do vocabulário no filtro E nos chips; runtime (`filterOptions`) sobrepõe.
-- **`options: { kind: 'lookup', source: 'x.lookup' }`** — as opções vêm de uma ACTION (server-side): o campo vira Select typeahead que chama a `source` (debounced) com `{ q }` — e com os valores dos `depends` no input. Convenção: a action de lookup devolve itens `{ value, label }`. Com valor aplicado mas opções ainda não carregadas (URL, chip), o chip mostra o próprio value.
+- **`depends: ['outroFiltro']`:** desabilita o filtro até que suas dependências tenham valor e o
+  limpa quando uma delas muda.
+- **`options: { kind: 'dictionary', ref: 'sessionStatus' }`:** resolve opções e rótulos por um
+  dicionário registrado no `OpusProvider`. `filterOptions` substitui essa fonte quando informado.
+- **`options: { kind: 'lookup', source: 'x.lookup' }`:** consulta uma action com `{ q }` e os valores
+  das dependências. A resposta segue o formato `{ value, label }`.
 
 ```tsx
 filters: {
@@ -166,9 +188,12 @@ filters: {
 }
 ```
 
-## Exibição e URL sync
+## Exibição e estado na URL
 
-O botão de exibição (engrenagem) abre o popover de configuração da listagem — presente em QUALQUER view: colunas (liga/desliga, incluindo as `hidden` do contrato; só com a tabela ativa) e itens por página (o default do caller fica fora da URL) — e é a casa do que vier depois. E o estado inteiro da toolbar (q, sort, filtros, view, colunas, limit) serializa pra querystring com os helpers padrão:
+O botão de exibição abre as preferências da listagem em qualquer visualização. Na tabela, permite
+mostrar ou ocultar colunas, inclusive as declaradas com `hidden`; em todas as visualizações, permite
+alterar a quantidade de itens por página. Busca, ordenação, filtros, visualização, colunas e limite
+podem ser serializados na query string pelos helpers do componente:
 
 ```tsx
 <ActionList
@@ -181,9 +206,10 @@ O botão de exibição (engrenagem) abre o popover de configuração da listagem
 
 Convenção compacta (defaults omitidos): `?q=…&sort=chave:dir&status=…&view=board&cols=a,b,c&limit=25`.
 
-## Composição (layout livre)
+## Composição dos itens
 
-Com children, a tabela sai de cena e o layout dos itens é seu (cards, grid, o que for) — a toolbar declarativa e os estados (skeleton/erro/vazio) seguem daqui. Mesmo princípio do ActionForm com children.
+Passe `children` para substituir a tabela por uma composição própria. A barra de filtros e os
+estados de carregamento, erro e vazio continuam sendo tratados por `ActionList`.
 
 ```tsx preview col
 render(
@@ -209,30 +235,38 @@ render(
 )
 ```
 
-## No contrato (ListAction)
+## Declaração na ListAction
 
 | Chave | O que declara |
 |---|---|
 | `columns` | `{ key, label, type?, sortable?, fit?, hidden?, dateFormat?, dictionary?, empty? }` — a tabela. `hidden` fica fora (base do futuro column picker); `dictionary` nomeia o dicionário do provider; `empty` dá o significado da ausência. |
-| `filters` | `{ [nome]: { label, type, options?, multiple?, advanced?, depends?, … } }` — a toolbar. `advanced` vai pro modal; `depends` desabilita/cascateia; options `kind: 'lookup'` busca numa action. Valor aplicado entra no input com o MESMO nome. |
+| `filters` | `{ [nome]: { label, type, options?, multiple?, advanced?, depends?, … } }` — a toolbar. `advanced` vai para o modal; `depends` desabilita/cascateia; options `kind: 'lookup'` busca em uma action. Valor aplicado entra no input com o mesmo nome. |
 | `text` | `{ fields }` — liga a busca; convenção: param `q` no input. Com período/filtros no contrato ela fica à direita; sendo a ÚNICA forma de recorte, abre a linha. |
 | `sort` | `{ fields, default }` — ordenação inicial; header ordenável escreve `sort: 'chave:dir'`. |
 | `periods` | `{ value, label }[]` — o controle de período (presets + Personalizado com calendário); materializa em `from`/`to` no input. |
 
-## Props
+## useListAction
+
+Quando o layout não cabe no `ActionList`, `useListAction(action, input)` entrega o mesmo fetch
+declarativo (`items`, `total`, `error`, `isLoading`, `isFetching`, `refetch`) sob o
+`QueryClientProvider`, e `presetRange(preset)` materializa os presets de período (`today`, `last7`,
+`thisMonth`…) em `{ from, to }` no formato `YYYY-MM-DD` — o mesmo cálculo que o pattern faz antes de
+chamar a action.
+
+## Propriedades de ActionList
 
-| Prop | Tipo | Default | Descrição |
+| Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
 | `action` | `ListAction<TInput, TItem>` | | A ListAction do Opus (kind list, output = item, paginate cursor). |
 | `input` | `TInput` | | O ESCOPO BASE (ex.: { workspaceId }) — a toolbar soma por cima, nunca sobrescreve. |
 | `cells` | `Record<string, (item) => ReactNode>` | | Células custom por cima das colunas do contrato (chave = column.key). |
-| `filterOptions` | `Record<string, SelectOption[]>` | | Opções de runtime pros filtros select/lookup (chave = nome do filtro). |
+| `filterOptions` | `Record<string, SelectOption[]>` | | Opções de runtime para os filtros select/lookup (chave = nome do filtro). |
 | `columns` | `ActionListColumn<TItem>[]` | | Tabela EXPLÍCITA — sobrepõe as colunas do contrato (escape hatch). |
-| `children` | `(items, refetch) => ReactNode` | | Modo COMPOSIÇÃO: layout livre; a toolbar segue. Tem precedência sobre columns. |
+| `children` | `(items, refetch) => ReactNode` | | Modo composição: layout livre; a toolbar segue. Tem precedência sobre columns. |
 | `batch` | `ActionListBatchAction[]` | | Ações em lote: `{ label, can?, run, confirm?, destructive? }` — liga a multi-seleção. |
-| `rowId` | `(item) => string` | `item.id` | Identidade da linha pra seleção. |
-| `pageSize` | `number` | `50` | Itens por página DEFAULT (vira `limit`/`page` no input; handler devolve `total`). O usuário troca no popover de exibição. |
-| `state / onStateChange` | `ActionListState / (next) => void` | interno | Estado da toolbar controlado — pra quem embala sincronizar com a URL. |
+| `rowId` | `(item) => string` | `item.id` | Identidade da linha para seleção. |
+| `pageSize` | `number` | `50` | Itens por página padrão (vira `limit`/`page` no input; handler devolve `total`). O usuário troca no popover de exibição. |
+| `state / onStateChange` | `ActionListState / (next) => void` | interno | Estado da toolbar controlado — para quem embala sincronizar com a URL. |
 | `emptyMessage` | `string` | `'Nenhum resultado.'` | O texto do estado vazio. |
-| `onRowClick` | `(item: TItem) => void` | | Clique na linha (ex.: navegar pro detalhe) — só na tabela. |
+| `onRowClick` | `(item: TItem) => void` | | Clique na linha (ex.: navegar para o detalhe) — só na tabela. |
 | `rowActions` | `(item: TItem) => ReactNode` | | Ações por linha (coluna final, à direita) — apresentação de quem chama, como `cells`; cliques ali não disparam o `onRowClick`. |

package/src/ui/docs/content/action-trigger.md

@@ -1,7 +1,8 @@
-## Disparo direto
+## Executar uma action
 
-Sem confirm, dispara no clique: desabilita enquanto roda e toca o toast do contrato
-(messages.success/error). O label default vem do action.label.
+Use `ActionTrigger` para executar uma `SimpleAction` a partir de um botão. Sem confirmação, o clique
+inicia a operação, desabilita o controle durante a execução e apresenta as mensagens do contrato em
+um toast. O rótulo padrão vem de `action.label`.
 
 ```tsx preview
 <DocBrowserActionProvider>
@@ -11,8 +12,9 @@ Sem confirm, dispara no clique: desabilita enquanto roda e toca o toast do contr
 
 ## Confirmação declarada no contrato
 
-O ConfirmSpec mora na action (title/message/destructive) — o pattern monta o Dialog sozinho e o
-destructive já tonaliza o botão. Prop confirm sobrepõe quando a tela precisar de outro texto.
+Quando a action declara `confirm`, o componente monta o diálogo e aplica o contexto `danger` se a
+operação for destrutiva. Use a propriedade `confirm` somente quando esta ocorrência precisar de uma
+mensagem diferente da declarada no contrato.
 
 ```tsx preview
 <DocBrowserActionProvider>
@@ -33,9 +35,11 @@ confirm: {
 <ActionTrigger action={sessionDeleteContract} input={{ id: session.id }} />
 ```
 
-## A ação que mora no item (icon)
+## Ação somente com ícone
 
-Com `icon`, o botão vira icon-only: o `label` (ou o `action.label`) migra pro tooltip e pro `aria-label`, o visual fica discreto (ghost, e vermelho no hover quando o contrato marca `destructive`) e o clique **não vaza** pro item em volta — é o que permite viver dentro de uma linha ou card clicável. `itemLabel` nomeia o alvo na pergunta.
+Com `icon`, o botão exibe somente o ícone e usa `label`, ou `action.label`, no tooltip e no nome
+acessível. O clique não aciona o item clicável ao redor. `itemLabel` identifica o registro na
+mensagem de confirmação.
 
 ```tsx
 <ActionTrigger
@@ -47,26 +51,36 @@ Com `icon`, o botão vira icon-only: o `label` (ou o `action.label`) migra pro t
 />
 ```
 
-> Isto absorveu o antigo `DeleteButton` (7.0.0), que era exatamente este componente com uma lixeira dentro. Se você tinha `<DeleteButton action input itemLabel />`, troque por `<ActionTrigger … icon={<Trash2 />} />` — **e confira se o contrato declara `confirm`**: sem ele o disparo é direto, e o DeleteButton perguntava sempre.
+> `ActionTrigger` substitui o antigo `DeleteButton`. Ao migrar, declare `confirm` no contrato para
+> preservar a confirmação que o componente anterior sempre apresentava.
 
 ## Erro que a pessoa entende
 
-Quando a action falha, a frase do SERVIDOR só vence o rótulo do contrato se o erro for de negócio — `conflict`, `validation`, `not_found`:
+Quando a action falha, uma mensagem do servidor substitui o texto genérico somente nos erros de
+negócio `conflict`, `validation` e `not_found`:
 
 > Este agente tem 3 conversas — desabilite em vez de excluir.
 
-Isso é acionável. Erro inesperado carrega texto técnico cru: sem a allowlist, uma violação de FK viraria `violates foreign key constraint "user_unit_id_fkey"` no toast de quem só clicou num botão. Por isso allowlist e não denylist — categoria desconhecida cai no rótulo genérico, que é o lado seguro de errar.
+Erros inesperados mantêm a mensagem genérica do contrato, evitando expor detalhes de banco ou
+infraestrutura. O servidor registra o detalhe técnico para diagnóstico.
 
-## Props
+## useTriggerAction
 
-| Prop | Tipo | Default | Descrição |
+`ActionTrigger` é uma composição sobre `useTriggerAction(action, { onSuccess, onError })`, que
+devolve `trigger(input)`, `isLoading`, `error` e `reset`, e invalida o cache declarado em
+`action.invalidates`. Use o hook direto quando a execução parte de um gesto que não é um botão —
+um atalho, um arrastar, um item de menu.
+
+## Propriedades de ActionTrigger
+
+| Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
 | `action` | `SimpleContract<TInput, TData>` | | A SimpleAction do Opus — label, messages e confirm vêm do contrato. |
 | `input` | `TInput` | | O que a action recebe — geralmente { id }. |
 | `label` | `string` | `action.label` | Sobrepõe o texto do botão. |
-| `variant / size` | `variants do Button` | `'default' (ou 'destructive' se o confirm declarar) / 'default'` | Visual do botão — o destructive do ConfirmSpec já escolhe sozinho. |
+| `context / variant / size` | `do Button` | gatilho: `primary`/`solid`; `danger` quando a action é `destructive`; no modo ícone, `ghost` e `neutral` (ou `danger` se destrutiva) / `default` | Visual do gatilho; `context` explícito vence. O botão de confirmar é sempre `solid`: `danger` quando a action é `destructive`, senão a prop `context` do gatilho (ou `primary`). |
 | `confirm` | `{ title, description?, actionLabel?, cancelLabel? }` | | Confirmação via prop — sobrepõe o ConfirmSpec do contrato. |
 | `onSuccess` | `(data: TData) => void` | | Pós-sucesso (cache já invalidado pelo action.invalidates). |
-| `icon` | `React.ReactNode` | | Torna o botão icon-only: rótulo no tooltip e no `aria-label`, clique que não vaza pro item. |
+| `icon` | `React.ReactNode` | | Torna o botão icon-only: rótulo no tooltip e no `aria-label`, clique que não vaza para o item. |
 | `itemLabel` | `string` | | Nome do alvo na pergunta (sai entre aspas, em destaque, antes da mensagem do contrato). |
-| `className` | `string` | | Classes do botão (ex.: apertar o tamanho numa linha densa). |
+| `className` | `string` | | Classes do botão (ex.: apertar o tamanho em uma linha densa). |