@softize/opus 19.0.0 → 20.0.0

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

@@ -6,14 +6,17 @@ recursos e envia o estado correspondente no input. Filtros avançados aparecem n
 os filtros aplicados permanecem visíveis como chips removíveis.
 
 A tabela derivada não cria uma moldura própria. A superfície que recebe o `ActionList` define os
-limites visuais da coleção; use `Table` diretamente quando a composição precisar da variante
-`framed`.
-
-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 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.
+limites visuais da coleção; use [`Table`](/ui/table) diretamente quando a composição precisar da
+variante `framed`. Carregamento, erro e vazio usam o mesmo [`DataState`](/ui/data-state) das
+demais coleções.
+
+A barra mantém em uma única linha os controles declarados como `inline`: ela não quebra e não move
+filtros para o modal por falta de espaço. Seletores de valor único acompanham o valor escolhido até
+`20rem` e truncam o excedente; a busca varia entre `8rem` e `16rem` conforme a largura
+disponível. Quando a barra ficar longa demais, declare como `advanced` os filtros que não precisam
+ficar sempre à vista, como descreve a seção “Onde cada filtro aparece”. Recarregar e
+exibição formam um `ButtonGroup` espaçado; `toolbarActions` acrescenta, depois deles, operações
+ligadas ao recorte atual.
 
 ```tsx preview col
 render(
@@ -31,8 +34,9 @@ render(
 
 ## 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`.
+Em uma página, envolva a listagem com [`Content`](/ui/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
 <Content
@@ -46,7 +50,8 @@ cabeçalho da coleção; busca, filtros e atualização permanecem na toolbar do
 ```
 
 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`.
+resultados filtrados. A propriedade recebe os nós já prontos: em uma ação somente com ícone, forneça
+você mesmo o `aria-label` e o `Tooltip` com o nome da operação.
 
 ## Barra de filtros compartilhada
 
@@ -64,9 +69,9 @@ superfícies que não são listagens, como relatórios. O estado é controlado p
 />
 ```
 
-Seletores inline de valor único abraçam o valor selecionado até `max-w-80`. Valores maiores são
+Seletores inline de valor único acompanham o valor selecionado até `20rem`. Valores maiores são
 truncados no controle, enquanto o dropdown pode crescer além dele para preservar a opção.
-Multiseletores mantêm `w-52`; no modal de filtros avançados, o seletor ocupa toda a largura.
+Multiseletores mantêm `13rem`; no modal de filtros avançados, o seletor ocupa toda a largura.
 `filterIcons` associa um ícone leading ao nome do filtro quando a superfície precisa reforçar
 dimensões recorrentes, sem substituir o rótulo. Busca, filtros e período aparecem somente quando
 declarados.
@@ -79,7 +84,7 @@ simples usam o valor vazio como padrão; por isso, opções como “Todos” tam
 Use `periodPosition` para manter o período antes ou depois dos filtros inline. Quando ele precisa
 apenas aparecer depois de um filtro específico, use `{ afterFilter: 'dateBasis' }`. Se tipo de data
 e período formam uma única decisão, declare `period={{ basisFilter: 'dateBasis' }}`: o Opus os reúne
-num só controle, com ícone no início e uma única ação de limpar no fim. Quando a pessoa muda o tipo
+em um só controle, com ícone no início e uma única ação de limpar no fim. Quando a pessoa muda o tipo
 ou o período padrão, essa ação aparece e restaura os dois valores. Se a âncora de `periodPosition`
 não existir, o período permanece visível no fim dos filtros inline.
 
@@ -177,7 +182,7 @@ render(
         action={docWorkspaceList}
         input={{}}
         cells={{
-          name: (w) => (
+          name: (w: { name: string }) => (
             <a
               href="#"
               onClick={(e) => e.preventDefault()}
@@ -218,6 +223,65 @@ disponíveis e a quantidade de itens. Alterar busca, filtro, ordenação ou per
 página. Durante a primeira consulta, `DataState` apresenta o carregamento; em atualizações
 posteriores, a lista permanece visível com `aria-busy`.
 
+## Ocupar a altura disponível
+
+Por padrão, a lista cresce com os resultados e a rolagem acontece na janela ou no contêiner que a
+hospeda. Quando a coleção é a região principal de uma tela de altura fixa, a barra de filtros e o
+rodapé podem continuar visíveis enquanto só os resultados rolam. Para isso, declare
+`layout="fill"` na [`Page`](/ui/page) e componha a lista com `PageBody` e
+[`Content`](/ui/content), como no exemplo abaixo. Role a tabela para ver o cabeçalho fixo.
+
+```tsx preview col
+render(
+  <DocBrowserActionProvider>
+    <div className="h-80 w-full overflow-x-auto overflow-y-hidden rounded-lg border border-border">
+      <Page layout="fill">
+        <PageBody>
+          <Content level={1} variant="page">
+            <ContentHeader>
+              <ContentTitle>Workspaces</ContentTitle>
+              <ContentActions>
+                <Button>Criar workspace</Button>
+              </ContentActions>
+            </ContentHeader>
+            <ContentBody>
+              <ActionList action={docWorkspaceList} input={{}} />
+            </ContentBody>
+          </Content>
+        </PageBody>
+      </Page>
+    </div>
+  </DocBrowserActionProvider>,
+);
+```
+
+A página limita a própria altura à do contêiner que a hospeda, normalmente o shell, e `PageBody`,
+`Content` e `ContentBody` repassam essa altura até a lista, que passa a usar `layout="fill"` sem que
+você o declare. Em uma [`Presentation`](/ui/presentation) de lista, basta `layout="fill"` no
+próprio `Presentation`. Só as regiões que contêm a lista mudam: uma seção irmã, como um resumo acima
+da coleção, mantém a altura do próprio conteúdo. Os demais filhos de cada região que repassa a
+altura se esticam à largura dela; dê `self-start` a um botão que deva manter a largura do conteúdo.
+
+Com a altura limitada, a barra de filtros, o `beforeContent` e o rodapé mantêm a própria altura. A
+região de resultados ocupa o espaço restante e rola nos dois eixos; o rodapé se mede pelo conteúdo
+e mantém a mesma altura com e sem paginador. Na tabela, o cabeçalho fica fixo no topo da região que
+rola, sobre a cor da superfície e com uma linha inferior, e a moldura dos estados de carregamento,
+erro e vazio ocupa a altura disponível. Em outras visualizações e em `children`, a rolagem interna
+continua, mas não existe cabeçalho fixo.
+
+A lista só assume `fill` sozinha quando é filha direta de `PageBody`, `ContentBody` ou do corpo de
+uma `Presentation`, e a altura só chega até ela se não houver um contêiner próprio entre esses
+componentes no caminho. Nos demais casos, a decisão é sua:
+
+- Para a lista manter a altura dos resultados, como em uma seção secundária cuja rolagem pertence ao
+  `PageBody`, declare `layout="flow"`.
+- Um contêiner próprio entre `ContentBody` e a lista, como um `TabsContent`, não repassa a altura, e
+  a lista volta a `flow`. Declare `layout="fill"` na lista e dê ao contêiner as classes
+  `flex min-h-0 flex-1 flex-col`.
+- Dentro de [`Card`](/ui/card), [`Dialog`](/ui/dialog), [`Drawer`](/ui/drawer) ou
+  [`Pane`](/ui/pane), a lista não herda o `fill` da página: a altura do corpo pertence à
+  superfície.
+
 ## Ações em lote
 
 `batch` acrescenta seleção à tabela. `can(item)` determina quais linhas podem participar: itens
@@ -250,6 +314,14 @@ fornece um `render`; `ActionList` preserva a mesma fonte de dados, filtros e est
 “Tabela” aparece quando existem colunas.
 
 ```tsx preview col
+type Workspace = {
+  id: string;
+  name: string;
+  client: string;
+  status: "active" | "onboarding" | "paused";
+  agents: number;
+};
+
 render(
   <DocBrowserActionProvider>
     <div className="w-full">
@@ -260,24 +332,20 @@ render(
           gallery: {
             label: "Galeria",
             icon: <LayoutGrid />,
-            render: (workspaces) => (
+            render: (workspaces: Workspace[]) => (
               <div className="grid grid-cols-2 gap-3">
                 {workspaces.map((w) => (
-                  <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}
-                      />
-                    </div>
-                    <p className="mt-1 text-xs text-muted-foreground">
-                      {w.agents} agentes.
-                    </p>
-                  </div>
+                  <Card key={w.id}>
+                    <CardHeader>
+                      <CardTitle>{w.name}</CardTitle>
+                      <CardDescription>
+                        {w.agents === 1 ? "1 agente" : `${w.agents} agentes`}
+                      </CardDescription>
+                      <CardAction>
+                        <DictionaryValue dict={docWorkspaceStatus} value={w.status} />
+                      </CardAction>
+                    </CardHeader>
+                  </Card>
                 ))}
               </div>
             ),
@@ -334,28 +402,42 @@ Convenção compacta (defaults omitidos): `?q=…&sort=chave:dir&status=…&view
 
 ## Composição dos itens
 
-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`.
+Passe `children` para substituir a tabela por uma composição própria, como uma lista de
+[`Item`](/ui/item). A barra de filtros e os estados de carregamento, erro e vazio continuam sendo
+tratados por `ActionList`. O contrato não leva o tipo do item até o componente: anote o parâmetro de
+`children` (ou de `render`, em uma visualização) ou declare os genéricos, como em
+`<ActionList<Input, Workspace>>`. Sem uma das duas formas, os itens chegam como `unknown`.
 
 ```tsx preview col
+type Workspace = {
+  id: string;
+  name: string;
+  client: string;
+  status: "active" | "onboarding" | "paused";
+  agents: number;
+};
+
 render(
   <DocBrowserActionProvider>
     <div className="w-full">
       <ActionList action={docWorkspaceList} input={{}}>
-        {(workspaces) => (
-          <div className="grid w-full grid-cols-2 gap-3">
-            {workspaces.map((w) => (
-              <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} />
-                </div>
-                <p className="mt-1 text-xs text-muted-foreground">
-                  {w.agents} agentes.
-                </p>
-              </div>
+        {(workspaces: Workspace[]) => (
+          <ItemGroup variant="framed">
+            {workspaces.map((w, index) => (
+              <React.Fragment key={w.id}>
+                {index > 0 && <ItemSeparator />}
+                <Item>
+                  <ItemHeader>
+                    <ItemTitle>{w.name}</ItemTitle>
+                    <ItemDescription>Cliente {w.client}.</ItemDescription>
+                  </ItemHeader>
+                  <ItemActions>
+                    <DictionaryValue dict={docWorkspaceStatus} value={w.status} />
+                  </ItemActions>
+                </Item>
+              </React.Fragment>
             ))}
-          </div>
+          </ItemGroup>
         )}
       </ActionList>
     </div>
@@ -403,9 +485,9 @@ chamar a action.
 
 | Propriedade             | Tipo                                                                                                        | Padrão                                    | Descrição                                                                                                                                                                    |
 | ----------------------- | ----------------------------------------------------------------------------------------------------------- | ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `action`                | `ListAction<TInput, TItem>`                                                                                 |                                           | A ListAction do Opus (kind list, output = item). A paginação envia `limit`/`page` e usa o `total` devolvido.                                                                 |
-| `input`                 | `TInput`                                                                                                    |                                           | O ESCOPO BASE (ex.: { workspaceId }) — a toolbar soma por cima, nunca sobrescreve.                                                                                           |
-| `layout`                | `'flow' \| 'fill'`                                                                                          | `'flow'`                                  | Em `fill`, ocupa a altura disponível e mantém a rolagem dentro da região de resultados.                                                                                      |
+| `action`                | `ListActionLike`                                                                                            |                                           | A ListAction do Opus (kind list, output = item). A paginação envia `limit`/`page` e usa o `total` devolvido.                                                                 |
+| `input`                 | `TInput`                                                                                                    |                                           | O escopo base, como `{ workspaceId }`. A toolbar acrescenta busca, filtros e paginação sem sobrescrever essas chaves. |
+| `layout`                | `'flow' \| 'fill'`                                                                                          | `'fill'` como filha direta de `PageBody`, `ContentBody` ou do corpo da `Presentation` em uma página `fill`; `'flow'` nos demais casos | Em `fill`, ocupa a altura de um ancestral limitado e rola somente a região de resultados; na tabela, o cabeçalho fica fixo. Sem ancestral limitado, equivale a `flow`. |
 | `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).                                                                                                    |
 | `filterDefaults`        | `Record<string, string>`                                                                                    |                                           | Valores de repouso aplicados à consulta; o `X` só aparece quando o filtro diverge deles e retorna a eles.                                                                    |
@@ -415,7 +497,7 @@ chamar a action.
 | `period`                | `{ basisFilter: string }`                                                                                   |                                           | Reúne o período e o filtro inline indicado em um único controle.                                                                                                             |
 | `views`                 | `Record<string, ActionListView<TItem>>`                                                                     |                                           | Visualizações alternativas `{ label, icon?, render }`; o seletor alterna entre a tabela e estas.                                                                             |
 | `beforeContent`         | `ReactNode`                                                                                                 |                                           | Conteúdo entre a toolbar e o corpo, como um resumo que reage ao recorte atual.                                                                                               |
-| `columns`               | `ActionListColumn<TItem>[]`                                                                                 |                                           | Tabela EXPLÍCITA — sobrepõe as colunas do contrato (escape hatch).                                                                                                           |
+| `columns`               | `ActionListColumn<TItem>[]`                                                                                 |                                           | Tabela explícita, que substitui as colunas declaradas no contrato.                                                                                                           |
 | `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?: { title, message? }, destructive? }` — liga a multi-seleção.                                                                   |
 | `rowId`                 | `(item) => string`                                                                                          | `item.id`                                 | Identidade da linha para seleção.                                                                                                                                            |
@@ -427,5 +509,5 @@ chamar a action.
 | `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`. |
+| `toolbarActions`        | `ReactNode`                                                                                                 |                                           | Operações ligadas ao recorte atual, no fim da barra e separadas do grupo de controles. Os nós são renderizados como recebidos: nome acessível e tooltip de uma ação somente com ícone ficam com o consumidor. |
+| `rowActions`            | `(item: TItem) => ReactNode`                                                                                |                                           | Ações por linha (coluna final, à direita). A partir de duas, entram em um 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

@@ -13,9 +13,11 @@ de tradução ou estiver ausente, o botão usa `action.name`.
 
 ## Confirmação declarada no contrato
 
-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.
+Quando a action declara `confirm`, o componente monta o diálogo antes de executar. Com
+`confirm.destructive: true` no contrato, o gatilho e o botão de confirmação usam o contexto
+`danger`. Use a propriedade `confirm` somente quando esta ocorrência precisar de uma mensagem
+diferente da declarada no contrato; ela substitui os textos, mas o caráter destrutivo continua
+vindo do contrato.
 
 ```tsx preview
 <DocBrowserActionProvider>
@@ -41,20 +43,35 @@ 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"`. O clique
-não aciona o item clicável ao redor. `itemLabel` identifica o registro na mensagem de confirmação.
+não aciona o item clicável ao redor.
+
+Em uma lista, várias linhas repetem a mesma ação. Inclua o alvo em `label`, como `Excluir Unidade
+Centro`, para que cada botão tenha um nome acessível distinto. `itemLabel` identifica o registro na
+pergunta de confirmação.
 
 ```tsx
+// No contrato:
+confirm: {
+  title: 'Excluir a unidade?',
+  message: 'Os agendamentos desta unidade também serão removidos.',
+  confirmLabel: 'Excluir',
+  destructive: true,
+}
+
+// Na linha da lista:
 <ActionTrigger
   action={unitDeleteContract}
   input={{ id: unit.id }}
   icon={<Trash2 />}
-  label="Excluir"
+  label={`Excluir ${unit.name}`}
   itemLabel={unit.name}
 />
 ```
 
-> `ActionTrigger` substitui o antigo `DeleteButton`. Ao migrar, declare `confirm` no contrato para
-> preservar a confirmação que o componente anterior sempre apresentava.
+Sem `confirmLabel` no contrato ou `actionLabel` na propriedade `confirm`, o botão de confirmação
+usa o `label` da action, como `Excluir`. O nome longo passado em `label` serve à linha; na pergunta,
+o alvo já aparece por `itemLabel`. O `label` do gatilho só nomeia o botão de confirmação quando a
+action não declara `label`.
 
 ## Erro que a pessoa entende
 
@@ -80,9 +97,9 @@ 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` quando é texto; senão `action.name` | 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`, ou `icon-xs` com `icon` | 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, body?, actionLabel?, cancelLabel? }` | | Confirmação via prop — sobrepõe o ConfirmSpec do contrato. |
+| `label` | `string` | `action.label` quando é texto; senão `action.name` | Texto do botão ou, com `icon`, seu nome acessível e tooltip. Só vira o botão de confirmação quando a action não declara `label` e nem o contrato nem `confirm` declaram outro rótulo. |
+| `context / variant / size` | `do Button` | gatilho: `primary`/`solid`; `danger` quando `action.confirm.destructive` é `true`; no modo ícone, `ghost` e `neutral` (ou `danger` se destrutiva) / `default`, ou `icon-xs` com `icon` | Visual do gatilho; `context` explícito vence. O botão de confirmar é sempre `solid`: `danger` quando `action.confirm.destructive` é `true`, senão a prop `context` do gatilho (ou `primary`). |
+| `confirm` | `{ title, body?, actionLabel?, cancelLabel? }` | | Confirmação para esta ocorrência; substitui os textos do `confirm` do contrato. Sem `actionLabel`, o botão de confirmar usa `action.label`. O contexto `danger` continua dependendo de `action.confirm.destructive`. |
 | `disabled` | `boolean` | `false` | Desabilita o botão independentemente da execução em andamento. |
 | `onSuccess` | `(data: TData) => void` | | Pós-sucesso (cache já invalidado pelo action.invalidates). |
 | `onLoadingChange` | `(loading: boolean) => void` | | Informa início e fim da execução a quem coordena bloqueio entre várias actions. |

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

@@ -2,7 +2,8 @@
 
 Use `ActionView` para carregar um recurso por uma `ViewAction` e manter carregamento e erro no
 mesmo fluxo. No exemplo, alterne entre os workspaces para observar o carregamento e a recuperação de
-erro. O consumidor compõe somente o conteúdo disponível.
+erro. O consumidor compõe somente o conteúdo disponível, aqui com [`Detail`](/ui/detail). Para uma
+coleção, use [`ActionList`](/ui/action-list).
 
 ```tsx preview col
 const [id, setId] = useState('empresa-x')
@@ -10,26 +11,25 @@ const [id, setId] = useState('empresa-x')
 render(
   <DocBrowserActionProvider>
     <div className="w-full space-y-3">
-      <div className="flex flex-wrap gap-2">
+      <ButtonGroup mode="spaced">
         <Button variant="outline" size="sm" onClick={() => setId('empresa-x')}>Empresa X</Button>
         <Button variant="outline" size="sm" onClick={() => setId('empresa-y')}>Empresa Y</Button>
         <Button variant="outline" size="sm" onClick={() => setId('sessao-fantasma')}>Inexistente (erro)</Button>
-      </div>
-      <div className="rounded-lg border border-border p-4">
+      </ButtonGroup>
+      <Card className="p-4">
         <ActionView action={docWorkspaceView} input={{ id }}>
           {(ws) => (
-            <div className="space-y-1.5">
-              <div className="flex items-center gap-2">
-                <h3 className="text-sm font-semibold">{ws.name}</h3>
-                <DictionaryValue dict={docWorkspaceStatus} value={ws.status} />
-              </div>
-              <p className="text-sm text-muted-foreground">
-                Cliente {ws.client} · {ws.agents} agentes vinculados.
-              </p>
-            </div>
+            <DetailGroup columns={3}>
+              <DetailField label="Workspace" value={ws.name} />
+              <DetailField label="Cliente" value={ws.client} />
+              <DetailField
+                label="Status"
+                value={<DictionaryValue dict={docWorkspaceStatus} value={ws.status} />}
+              />
+            </DetailGroup>
           )}
         </ActionView>
-      </div>
+      </Card>
     </div>
   </DocBrowserActionProvider>,
 )