@softize/opus 17.2.0 → 18.0.1

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

@@ -41,7 +41,7 @@ invalidação continuam sob responsabilidade de `ActionForm`.
 <DocBrowserActionProvider>
   <ActionForm
     action={docWorkspaceCreate}
-    defaultValues={{ name: 'Empresa X', status: 'active' }}
+    defaultValues={{ name: "Empresa X", status: "active" }}
     submitLabel="Atualizar"
     onCancel={() => undefined}
   />
@@ -70,23 +70,23 @@ ciclo de vida que o pattern não cobre; validação e execução continuam iguai
 
 ## 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 automático monta todos os campos na ordem do contrato. |
+| 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 / cancelVariant / onCancel` | `string / string / 'ghost' \| 'outline' / () => void` | `'Salvar' / 'Cancelar' / 'ghost'` | Rodapé do form — o Cancelar só aparece com onCancel. Use `outline` quando ele dividir o footer com a ação principal.                                                                    |
+| `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 automático monta todos os campos na ordem do contrato.                                                        |
 
 ## Propriedades de ActionFormField
 
-| 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` em uma grid). |
+| 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` em uma grid).                          |
 
 ## Ajuda na label
 
@@ -110,9 +110,9 @@ lugar:
 
 ### Propriedades de LabelHelp
 
-| Propriedade | Tipo | Descrição |
-|---|---|---|
-| `help` | `string` | O texto do tooltip. Vazio ou ausente, o ícone não renderiza. |
+| Propriedade | Tipo     | Descrição                                                    |
+| ----------- | -------- | ------------------------------------------------------------ |
+| `help`      | `string` | O texto do tooltip. Vazio ou ausente, o ícone não renderiza. |
 
 ## Origem das opções de seleção
 
@@ -137,25 +137,25 @@ Quando nenhum widget atender ao campo, use `useActionFormContext` no modo de com
 próprio participa da mesma validação e execução sem abandonar o `ActionForm`:
 
 ```tsx
-import { useActionFormContext } from '@softize/opus/ui/react'
+import { useActionFormContext } from "@softize/opus/ui/react";
 
 function PermissionGrid() {
-  const { form } = useActionFormContext()
-  const perms = (form.watch('permissions') as string[] | undefined) ?? []
+  const { form } = useActionFormContext();
+  const perms = (form.watch("permissions") as string[] | undefined) ?? [];
   const toggle = (p: string) =>
     form.setValue(
-      'permissions',
+      "permissions",
       perms.includes(p) ? perms.filter((x) => x !== p) : [...perms, p],
       { shouldValidate: true, shouldDirty: true },
-    )
-  const error = form.formState.errors['permissions']
+    );
+  const error = form.formState.errors["permissions"];
   // …sua grade; zod-resolver, erro inline e submit continuam do contrato.
 }
 
 <ActionForm action={roleUpdate}>
   <ActionFormField name="name" />
   <PermissionGrid />
-</ActionForm>
+</ActionForm>;
 ```
 
 O contexto também expõe `shape` (Zod por campo), `fields` (FieldSpec) e `fieldOptions`.

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

@@ -7,34 +7,43 @@ 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.
-`toolbarActions` acrescenta ações do consumidor ao fim da barra. Recarregar e exibição formam um
-`ButtonGroup` espaçado; as ações do consumidor vêm depois, com um intervalo maior para preservar a
-hierarquia entre ferramentas e a ação principal.
+`toolbarActions` acrescenta operações ligadas ao recorte atual no fim da barra. Recarregar e
+exibição formam um `ButtonGroup` espaçado; as ações do consumidor vêm depois, com um intervalo
+maior para preservar a hierarquia entre controles e operações do recorte.
 
 ```tsx preview col
 render(
   <DocBrowserActionProvider>
     <div className="w-full">
-      <ActionList action={docWorkspaceList} input={{}} emptyMessage="Nenhum workspace." />
+      <ActionList
+        action={docWorkspaceList}
+        input={{}}
+        emptyMessage="Nenhum workspace."
+      />
     </div>
   </DocBrowserActionProvider>,
-)
+);
 ```
 
-Uma ação icon-only mantém o nome no tooltip e no `aria-label`:
+## Coleção nomeada
+
+Em uma página, envolva a listagem com `Content`. O título e a criação ocupam extremos opostos do
+cabeçalho da coleção; busca, filtros e atualização permanecem na toolbar do `ActionList`.
 
 ```tsx
-<ActionList
-  action={workspaceList}
-  input={{}}
-  toolbarActions={
-    <Button context="primary" size="icon" aria-label="Novo workspace">
-      <Plus />
-    </Button>
-  }
-/>
+<Content
+  title="Workspaces"
+  level={1}
+  variant="page"
+  actions={<Button>Criar workspace</Button>}
+>
+  <ActionList action={workspaceList} input={{}} />
+</Content>
 ```
 
+Use `toolbarActions` somente quando a operação depender do recorte visível, como exportar os
+resultados filtrados. Uma ação icon-only nessa região mantém o nome no tooltip e no `aria-label`.
+
 ## Barra de filtros compartilhada
 
 `ActionFilterBar` expõe a mesma linguagem declarativa de busca, filtros e período para
@@ -89,7 +98,11 @@ render(
         input={{}}
         cells={{
           name: (w) => (
-            <a href="#" onClick={(e) => e.preventDefault()} className="font-medium underline-offset-4 hover:underline">
+            <a
+              href="#"
+              onClick={(e) => e.preventDefault()}
+              className="font-medium underline-offset-4 hover:underline"
+            >
               {w.name}
             </a>
           ),
@@ -97,7 +110,7 @@ render(
       />
     </div>
   </DocBrowserActionProvider>,
-)
+);
 ```
 
 ## Período obrigatório
@@ -109,10 +122,10 @@ como `?period=2026-07-01..2026-07-07`, e chega ao handler pelos parâmetros `fro
 
 ```tsx
 periods: [
-  { value: 'today', label: 'Hoje' },
-  { value: 'last7', label: 'Últimos 7 dias' },
-  { value: 'thisMonth', label: 'Este mês' },
-]
+  { value: "today", label: "Hoje" },
+  { value: "last7", label: "Últimos 7 dias" },
+  { 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.
 ```
@@ -133,13 +146,19 @@ apenas essa seleção. Com `confirm`, o componente pede confirmação antes de e
 seleção é limpa e a consulta é refeita.
 
 ```tsx
-<ActionList action={runList} input={{}}
-  batch={[{
-    label: 'Reprocessar',
-    can: (run) => run.status === 'failed',
-    confirm: { title: 'Reprocessar as execuções?' },
-    run: async (runs) => { await Promise.all(runs.map((r) => api.retry(r.id))) },
-  }]}
+<ActionList
+  action={runList}
+  input={{}}
+  batch={[
+    {
+      label: "Reprocessar",
+      can: (run) => run.status === "failed",
+      confirm: { title: "Reprocessar as execuções?" },
+      run: async (runs) => {
+        await Promise.all(runs.map((r) => api.retry(r.id)));
+      },
+    },
+  ]}
 />
 ```
 
@@ -159,17 +178,25 @@ render(
         input={{}}
         views={{
           gallery: {
-            label: 'Galeria',
+            label: "Galeria",
             icon: <LayoutGrid />,
             render: (workspaces) => (
               <div className="grid grid-cols-2 gap-3">
                 {workspaces.map((w) => (
-                  <div key={w.id} className="rounded-lg border border-border p-3">
+                  <div
+                    key={w.id}
+                    className="rounded-lg border border-border p-3"
+                  >
                     <div className="flex items-center gap-2">
                       <span className="text-sm font-semibold">{w.name}</span>
-                      <DictionaryValue dict={docWorkspaceStatus} value={w.status} />
+                      <DictionaryValue
+                        dict={docWorkspaceStatus}
+                        value={w.status}
+                      />
                     </div>
-                    <p className="mt-1 text-xs text-muted-foreground">{w.agents} agentes.</p>
+                    <p className="mt-1 text-xs text-muted-foreground">
+                      {w.agents} agentes.
+                    </p>
                   </div>
                 ))}
               </div>
@@ -179,7 +206,7 @@ render(
       />
     </div>
   </DocBrowserActionProvider>,
-)
+);
 ```
 
 ## Filtros dependentes e opções remotas
@@ -217,7 +244,9 @@ podem ser serializados na query string pelos helpers do componente:
   action={contract}
   input={{}}
   state={listParamsToState(params, contract)}
-  onStateChange={(next) => navigate(`/rota${listStateToParams(next, contract)}`)}
+  onStateChange={(next) =>
+    navigate(`/rota${listStateToParams(next, contract)}`)
+  }
 />
 ```
 
@@ -241,7 +270,9 @@ render(
                   <span className="text-sm font-semibold">{w.name}</span>
                   <DictionaryValue dict={docWorkspaceStatus} value={w.status} />
                 </div>
-                <p className="mt-1 text-xs text-muted-foreground">{w.agents} agentes.</p>
+                <p className="mt-1 text-xs text-muted-foreground">
+                  {w.agents} agentes.
+                </p>
               </div>
             ))}
           </div>
@@ -249,31 +280,31 @@ render(
       </ActionList>
     </div>
   </DocBrowserActionProvider>,
-)
+);
 ```
 
 ## Propriedades de ActionFilterBar
 
-| Propriedade | Tipo | Padrão | Descrição |
-|---|---|---|---|
-| `action` | `Pick<ListAction, 'filters' \| 'text' \| 'periods'>` | | Declara busca, filtros e períodos disponíveis. |
-| `state` | `ActionFilterState` | | Estado atual da barra. |
-| `onStateChange` | `(next) => void` | | Recebe o estado completo depois de cada alteração. |
-| `filterOptions` | `Record<string, SelectOption[]>` | | Fornece opções de runtime para filtros select e lookup. |
-| `onRefresh` | `() => Promise<void> \| void` | | Exibe a ação de recarregar e executa a consulta do consumidor. |
-| `refreshing` | `boolean` | `false` | Desabilita e anima a ação de recarregar durante a consulta. |
-| `controls` | `ReactNode` | | Controles auxiliares agrupados com recarregar em um `ButtonGroup` espaçado. |
-| `actions` | `ReactNode` | | Ações do consumidor exibidas depois do grupo de controles, com um intervalo maior. |
+| Propriedade     | Tipo                                                 | Padrão  | Descrição                                                                          |
+| --------------- | ---------------------------------------------------- | ------- | ---------------------------------------------------------------------------------- |
+| `action`        | `Pick<ListAction, 'filters' \| 'text' \| 'periods'>` |         | Declara busca, filtros e períodos disponíveis.                                     |
+| `state`         | `ActionFilterState`                                  |         | Estado atual da barra.                                                             |
+| `onStateChange` | `(next) => void`                                     |         | Recebe o estado completo depois de cada alteração.                                 |
+| `filterOptions` | `Record<string, SelectOption[]>`                     |         | Fornece opções de runtime para filtros select e lookup.                            |
+| `onRefresh`     | `() => Promise<void> \| void`                        |         | Exibe a ação de recarregar e executa a consulta do consumidor.                     |
+| `refreshing`    | `boolean`                                            | `false` | Desabilita e anima a ação de recarregar durante a consulta.                        |
+| `controls`      | `ReactNode`                                          |         | Controles auxiliares agrupados com recarregar em um `ButtonGroup` espaçado.        |
+| `actions`       | `ReactNode`                                          |         | Ações do consumidor exibidas depois do grupo de controles, com um intervalo maior. |
 
 ## 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. |
+| 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 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. |
+| `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.                                                                                                                        |
 
 ## useListAction
 
@@ -285,21 +316,21 @@ chamar a action.
 
 ## Propriedades de ActionList
 
-| 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 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. |
-| `batch` | `ActionListBatchAction[]` | | Ações em lote: `{ label, can?, run, confirm?, destructive? }` — liga a multi-seleção. |
-| `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.'` | Frase do estado vazio (o `Empty` do `DataState`). |
-| `errorMessage` | `string` | `'Não foi possível carregar.'` | Título do aviso de erro; a ação de tentar de novo refaz a consulta. |
-| `retryLabel` | `string` | `'Tentar de novo'` | Nome acessível e tooltip da ação de recuperação. |
-| `onRowClick` | `(item: TItem) => void` | | Clique na linha (ex.: navegar para o detalhe) — só na tabela. |
-| `toolbarActions` | `ReactNode` | | Ações do consumidor no fim da barra, separadas do grupo de controles. |
-| `rowActions` | `(item: TItem) => ReactNode` | | Ações por linha (coluna final, à direita). A partir de duas, entram num grupo com intervalo compacto; uma só fica solta, sem grupo. Cliques ali não disparam o `onRowClick`. |
+| 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 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.                                                                                               |
+| `batch`                 | `ActionListBatchAction[]`             |                                | Ações em lote: `{ label, can?, run, confirm?, destructive? }` — liga a multi-seleção.                                                                                        |
+| `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.'`          | Frase do estado vazio (o `Empty` do `DataState`).                                                                                                                            |
+| `errorMessage`          | `string`                              | `'Não foi possível carregar.'` | Título do aviso de erro; a ação de tentar de novo refaz a consulta.                                                                                                          |
+| `retryLabel`            | `string`                              | `'Tentar de novo'`             | Nome acessível e tooltip da ação de recuperação.                                                                                                                             |
+| `onRowClick`            | `(item: TItem) => void`               |                                | Clique na linha (ex.: navegar para o detalhe) — só na tabela.                                                                                                                |
+| `toolbarActions`        | `ReactNode`                           |                                | Operações ligadas ao recorte atual, no fim da barra e separadas do grupo de controles.                                                                                       |
+| `rowActions`            | `(item: TItem) => ReactNode`          |                                | Ações por linha (coluna final, à direita). A partir de duas, entram num grupo com intervalo compacto; uma só fica solta, sem grupo. Cliques ali não disparam o `onRowClick`. |

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

@@ -39,7 +39,7 @@ confirm: {
 
 Com `icon`, o botão exibe somente o ícone no quadrado `icon-xs` da escala (1.5rem, a ação que mora
 dentro de uma linha ou card) e usa `label`, ou `action.label`, no tooltip e no nome acessível. Uma
-composição que peça mais presença, como a barra do `PageHeader`, declara `size="icon-sm"`. O clique
+composição que peça mais presença, como a barra do `PageHeader`, declara `size="icon"`. O clique
 não aciona o item clicável ao redor. `itemLabel` identifica o registro na mensagem de confirmação.
 
 ```tsx
@@ -79,7 +79,7 @@ um atalho, um arrastar, um item de menu.
 | `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. |
-| `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`). |
+| `context / variant / size` | `do Button` | gatilho: `primary`/`solid`; `danger` quando a action é `destructive`; no modo ícone, `ghost` e `neutral` (ou `danger` se destrutiva) / `icon-xs` | 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 para o item. |

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

@@ -35,7 +35,7 @@ há texto visível. O glifo dentro do controle acompanha o tamanho (0.875rem em
 Escolha o tamanho pela região, não pela importância visual: `variant` e `context` resolvem a
 hierarquia da ação. Headers de Page e footers de Dialog/Drawer usam `default`; ações operacionais
 de seção, toolbar e coleção usam `sm`; ações dentro de linha ou célula usam `xs` ou `icon-xs`.
-Controles de chrome, como voltar e fechar, usam `icon-sm`. Assim a mesma decisão mantém a mesma
+Controles de chrome, como voltar e fechar, usam `icon`. Assim a mesma decisão mantém a mesma
 altura mesmo quando uma superfície troca uma ação secundária por uma primária.
 
 ```tsx preview

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

@@ -93,9 +93,9 @@ componente ao trocar de conversa. O rótulo do indicador é customizável por
 `humanizeTool={(name) => '…'}`.
 
 Itens controlados podem carregar `id` e `createdAt`. O Chat os projeta no elemento da
-mensagem e oferece `renderMessageActions` para ações contextuais discretas. O slot não
-busca nem conhece detalhes: o app deve carregar informação complementar somente após a
-interação da pessoa e aplicar novamente sua autorização.
+mensagem e oferece `renderMessageActions` para ações contextuais discretas tanto nas mensagens
+enviadas quanto nas recebidas. O slot não busca nem conhece detalhes: o app deve carregar
+informação complementar somente após a interação da pessoa e aplicar novamente sua autorização.
 
 ## Propriedades de Chat
 
@@ -105,7 +105,7 @@ interação da pessoa e aplicar novamente sua autorização.
 | `messages` | `ChatTranscriptItem[]` | | Modo controlado: o transcript vem do app; com ele, `onSend`, `busy` e `activity` assumem. |
 | `onSend` | `(text: string) => void \| boolean \| Promise<void \| boolean>` | | Modo controlado: recebe o texto enviado; retornar `false` devolve o texto ao composer. |
 | `busy` | `boolean` | | Modo controlado: trava o composer enquanto o turno corre. |
-| `activity` | `string \| null` | `undefined` | Indicador vivo: `null` mostra “Pensando…”, string mostra o rótulo; `undefined` esconde. |
+| `activity` | `string \| null` | `undefined` | Indicador vivo: `null` mostra “Pensando…”, string mostra o rótulo, `''` centraliza somente os pontos; `undefined` esconde. |
 | `notice` | `ReactNode` | | Aviso do app acima do composer (credencial, agente desatualizado…). |
 | `composerActions` | `ReactNode` | | Seletores discretos na barra do composer (agente, app, escopo). |
 | `composerClassName` | `string` | | Ajusta o contêiner externo do composer sem alcançar o DOM interno. |

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

@@ -13,9 +13,11 @@ render(
     description="Sessões com acesso à sua conta."
     actions={<Button variant="outline">Encerrar outras sessões</Button>}
   >
-    <div className="rounded-lg border border-border p-4">MacBook Para o · ativo agora</div>
+    <div className="rounded-lg border border-border p-4">
+      MacBook Para o · ativo agora
+    </div>
   </Content>,
-)
+);
 ```
 
 ## Composição explícita
@@ -32,28 +34,42 @@ render(
       <ContentTitle>Dispositivos conectados</ContentTitle>
       <ContentMeta>3</ContentMeta>
       <ContentDescription>Sessões com acesso à sua conta.</ContentDescription>
-      <ContentActions><Button variant="outline">Atualizar</Button></ContentActions>
+      <ContentActions>
+        <Button variant="outline">Atualizar</Button>
+      </ContentActions>
     </ContentHeader>
     <ContentBody>
-      <div className="rounded-lg border border-border p-4">MacBook Para o · ativo agora</div>
+      <div className="rounded-lg border border-border p-4">
+        MacBook Para o · ativo agora
+      </div>
     </ContentBody>
   </Content>,
-)
+);
 ```
 
 As duas formas geram os mesmos elementos, estilos e `data-slot`. `opus check` reprova slots fora
 do pai correto, filhos estruturais indiretos e a mistura de shorthand com composição explícita.
 
+## Coleção nomeada
+
+Quando a região principal da página é uma coleção, `Content` nomeia e governa essa coleção, enquanto
+`ActionList` executa a consulta. Coloque criar, importar e outras ações sobre o conjunto completo em
+`ContentActions`. Busca, filtros, atualização e operações dependentes do recorte atual permanecem na
+toolbar da lista. Essa divisão aproxima cada comando do objeto que ele afeta sem criar uma família
+paralela de componentes `List*`. Na variante `page`, as ações ficam no extremo oposto ao título. A
+criação usa um botão textual `default`, sem ícone, nomeado `Criar recurso`; o diálogo aberto pelo
+gatilho repete esse título e a edição usa `Editar recurso`.
+
 ## Propriedades de Content
 
-| Propriedade | Tipo | Padrão | Descrição |
-|---|---|---|---|
-| `title` | `ReactNode` | | Forma curta: título da região (vira o heading ligado à `section`). |
-| `count` | `number` | | Forma curta: total de itens ao lado do título da região. |
-| `description` | `ReactNode` | | Forma curta: frase de apoio sob o título. |
-| `actions` | `ReactNode` | | Forma curta: ações alinhadas à direita do header. |
-| `level` | `1 \| 2 \| 3 \| 4 \| 5 \| 6` | herdado | Nível semântico do heading, independente do destaque visual. |
-| `variant` | `'page' \| 'section'` | `'section'` | Hierarquia visual: `page` reproduz o cabeçalho de `Page`; `section` é a região dentro de uma superfície. |
+| Propriedade   | Tipo                         | Padrão      | Descrição                                                                                                |
+| ------------- | ---------------------------- | ----------- | -------------------------------------------------------------------------------------------------------- |
+| `title`       | `ReactNode`                  |             | Forma curta: título da região (vira o heading ligado à `section`).                                       |
+| `count`       | `number`                     |             | Forma curta: total de itens ao lado do título da região.                                                 |
+| `description` | `ReactNode`                  |             | Forma curta: frase de apoio sob o título.                                                                |
+| `actions`     | `ReactNode`                  |             | Forma curta: ações sobre a região inteira; em `page`, ficam no extremo oposto ao título.                 |
+| `level`       | `1 \| 2 \| 3 \| 4 \| 5 \| 6` | herdado     | Nível semântico do heading, independente do destaque visual.                                             |
+| `variant`     | `'page' \| 'section'`        | `'section'` | Hierarquia visual: `page` reproduz o cabeçalho de `Page`; `section` é a região dentro de uma superfície. |
 
 Na composição explícita, `ContentHeader` recebe `ContentTitle`, `ContentMeta`, `ContentDescription` e
 `ContentActions`, e `ContentBody` recebe o conteúdo; nenhum desses slots aceita `title` ou `level`

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

@@ -21,27 +21,31 @@ borda semântica, raio `xl` e elevação para permanecer distinta da página.
 ```tsx preview
 <Dialog>
   <DialogTrigger asChild>
-    <Button variant="outline">Novo workspace</Button>
+    <Button>Criar workspace</Button>
   </DialogTrigger>
   <DialogContent>
     <DialogHeader>
-      <DialogTitle>Novo workspace</DialogTitle>
+      <DialogTitle>Criar workspace</DialogTitle>
     </DialogHeader>
     <DialogBody className="space-y-2">
       <Label htmlFor="workspace-name">Nome</Label>
       <Input id="workspace-name" placeholder="Ex.: Empresa X" />
     </DialogBody>
     <DialogFooter>
-      <DialogClose asChild>
-        <Button variant="ghost">Cancelar</Button>
-      </DialogClose>
-      <Button>Criar workspace</Button>
+      <ButtonGroup mode="spaced" distribution="equal">
+        <DialogClose asChild>
+          <Button variant="outline">Cancelar</Button>
+        </DialogClose>
+        <Button>Criar workspace</Button>
+      </ButtonGroup>
     </DialogFooter>
   </DialogContent>
 </Dialog>
 ```
 
 O corpo cresce até o limite da janela e passa a rolar; cabeçalho e rodapé permanecem visíveis.
+O `ButtonGroup` divide o espaço entre decisões equivalentes no rodapé. O `DialogFooter` organiza
+a faixa, mas não decide a distribuição nem a aparência dos botões.
 `DialogClose` encerra o modal sem exigir estado controlado. Use `open` e `onOpenChange` quando outra
 parte da interface também precisar controlar a abertura.
 
@@ -207,16 +211,18 @@ function ResponseDialogDemo() {
               O contrato possui alterações que ainda não foram salvas.
             </p>
           </DialogBody>
-          <DialogFooter className="grid-cols-3">
-            <DialogClose result="continue" initialFocus asChild>
-              <Button variant="ghost">Continuar editando</Button>
-            </DialogClose>
-            <DialogClose result="discard" asChild>
-              <Button variant="outline">Descartar</Button>
-            </DialogClose>
-            <DialogClose result="save" asChild>
-              <Button>Salvar e fechar</Button>
-            </DialogClose>
+          <DialogFooter>
+            <ButtonGroup mode="spaced" distribution="equal">
+              <DialogClose result="continue" initialFocus asChild>
+                <Button variant="outline">Continuar editando</Button>
+              </DialogClose>
+              <DialogClose result="discard" asChild>
+                <Button variant="outline">Descartar</Button>
+              </DialogClose>
+              <DialogClose result="save" asChild>
+                <Button>Salvar e fechar</Button>
+              </DialogClose>
+            </ButtonGroup>
           </DialogFooter>
         </DialogContent>
       </Dialog>
@@ -286,10 +292,10 @@ botão. O texto informa o efeito real, como `Excluir`, `Revogar acesso` ou `Ence
 
 ## Propriedades de DialogFooter
 
-| Propriedade | Tipo        | Padrão | Descrição                                                        |
-| ----------- | ----------- | ------ | ---------------------------------------------------------------- |
-| `className` | `string`    |        | Ajusta a faixa do modo padrão ou a grade de respostas do alerta. |
-| `children`  | `ReactNode` |        | Ações secundárias e principal.                                   |
+| Propriedade | Tipo        | Padrão | Descrição                                   |
+| ----------- | ----------- | ------ | ------------------------------------------- |
+| `className` | `string`    |        | Ajusta a faixa do modo padrão ou do alerta. |
+| `children`  | `ReactNode` |        | Ações secundárias e principal.              |
 
 ## Propriedades de DialogTitle
 
@@ -380,5 +386,5 @@ imperativa.
 | `label`        | `ReactNode`     |                                           | Rótulo que descreve o resultado da ação.              |
 | `initialFocus` | `boolean`       | `false`                                   | Marca a única saída segura que recebe o foco inicial. |
 | `context`      | `ButtonContext` | Última ação: `primary`; demais: `neutral` | Define o significado semântico.                       |
-| `variant`      | `ButtonVariant` | Última ação: `solid`; demais: `ghost`     | Define o tratamento visual.                           |
+| `variant`      | `ButtonVariant` | Última ação: `solid`; demais: `outline`   | Define o tratamento visual.                           |
 | `disabled`     | `boolean`       | `false`                                   | Impede a escolha desta ação.                          |

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

@@ -25,8 +25,8 @@ entra pela direita e pode ser fechado por Esc, pelo overlay ou pelo botão de fe
 
 `side` aceita `top`, `right`, `bottom` e `left`. `DrawerFooter` mantém as ações no rodapé;
 `DrawerClose` fecha o painel sem exigir controle manual de estado. Como no `Dialog`, o cabeçalho
-recebe um divisor inferior e o rodapé usa divisor superior sobre fundo sutil. O corpo preserva o
-mesmo alinhamento horizontal entre título, conteúdo e ações.
+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.
 
 ```tsx preview
 <Drawer>
@@ -42,10 +42,12 @@ mesmo alinhamento horizontal entre título, conteúdo e ações.
       <Input id="ws-nome" defaultValue="Empresa X" />
     </DrawerBody>
     <DrawerFooter>
-      <DrawerClose asChild>
-        <Button variant="ghost">Cancelar</Button>
-      </DrawerClose>
-      <Button>Salvar alterações</Button>
+      <ButtonGroup mode="spaced" distribution="equal">
+        <DrawerClose asChild>
+          <Button variant="outline">Cancelar</Button>
+        </DrawerClose>
+        <Button>Salvar</Button>
+      </ButtonGroup>
     </DrawerFooter>
   </DrawerContent>
 </Drawer>