@softize/opus 25.2.0 → 25.3.1

package/CHANGELOG.md

@@ -7,6 +7,44 @@ Depois de qualquer bump, rode os gates (`typecheck` · `test` · `opus check` ·
 `opus copy --check` · `base copy check` · `manifest:check`) — eles apontam o que a
 mudança cobra do seu código.
 
+## 25.3.1 — 2026-10-05
+
+Com um `Dialog` ou `Drawer` aberto e a pessoa numa `FloatingLayer` sem `onEscapeKeyDown`, o Esc
+fecha o modal. Antes, o Opus impedia o modal de fechar e chamava um handler que não existia: quem
+chegava ao botão do assistente pelo Tab e apertava Esc não via efeito nenhum. Com o handler, nada
+muda: a camada recebe a tecla e o modal continua aberto. Para que o Esc no botão feche o modal,
+passe `onEscapeKeyDown` só enquanto a camada tiver o que fechar, como com o painel aberto, e
+`undefined` no restante do tempo. A decisão está numa nota da seção 5 da ADR 0052.
+
+`assistantContextLeaves`, de `@softize/opus/assistant-schema`, passa a listar em `open` dois pontos
+por onde qualquer campo chega ao modelo e que antes ficavam de fora: o `$ref` que não resolve dentro
+do schema, que sumia do resultado, e o objeto que aceita chaves não declaradas
+(`additionalProperties: true`, do `.passthrough()` do zod), que aparece como `<caminho>.*`. A forma
+do resultado e a conferência do `opus gen` não mudam. Um teste de campos pessoais que reprova pontos
+abertos pode passar a acusar esses casos; reprove-os ou justifique cada um.
+
+A ADR 0052 e a página da `FloatingLayer` registram que o roteiro manual em Safari com VoiceOver e no
+Firefox não foi executado: na adoção pela Grand Brasil, o dono do produto o dispensou. A evidência
+é a dos testes de navegador no Chromium real, e o roteiro volta a ser exigido se surgir problema de
+leitor de tela, de Safari ou de Firefox.
+
+## 25.3.0 — 2026-10-05
+
+`ListAction.grouping` declara dimensões fechadas pelas quais a `ActionList` pode agrupar a tabela.
+Cada dimensão referencia um filtro `select` com até 12 opções estáticas ou de dicionário, e a
+action precisa usar `paginate: 'offset'` e devolver `total`. A pessoa escolhe o agrupamento em
+**Exibição**; cada grupo consulta o servidor separadamente, pode ser recolhido e carrega páginas
+adicionais sem descartar as anteriores. O agrupamento não altera views alternativas nem o modo de
+composição por `children`.
+
+O manifest e os stubs passam a projetar `grouping`. `ActionListState` e os helpers de URL preservam
+a dimensão em `group`; dimensões desconhecidas são ignoradas. A implementação das consultas por
+grupo permanece interna à `ActionList`, sem introduzir um hook público adicional.
+
+`useListAction(action, input, { enabled })` pode suspender a consulta declarativa sem desmontar o
+hook. O padrão é `true`; a `ActionList` usa essa opção internamente ao alternar entre a consulta
+plana e as consultas agrupadas.
+
 ## 25.2.0 — 2026-10-03
 
 Uma action `view` pode declarar o assistente do recurso que ela lê (ADR 0053). Com isso, a conversa

package/bin/lib/assistant-schema.d.mts

@@ -13,8 +13,9 @@ export interface AssistantContextLeaves {
   /** Os campos folha alcançados, com ponto e sem índice de lista; `*` marca a chave de um mapa. */
   leaves: string[]
   /**
-   * Pontos em que o schema não declara forma ou volta a si mesmo por `$ref`: qualquer campo abaixo
-   * deles pode ir ao modelo, e a conferência não alcança.
+   * Pontos por onde qualquer campo pode ir ao modelo sem que a conferência alcance: o schema que não
+   * declara forma, o `$ref` que volta a si mesmo ou que não resolve, e, como `<ponto>.*`, o objeto
+   * que aceita chaves não declaradas (`additionalProperties: true`, do `.passthrough()` do zod).
    */
   open: string[]
 }

package/bin/lib/assistant-schema.mjs

@@ -45,18 +45,26 @@ function isNullOnly(schema) {
 const NO_REFS = new Set();
 /** Marca o ponto em que um `$ref` volta a um schema que já está no caminho atual. */
 const CYCLE = Object.freeze({ cycle: true });
+/** Marca o ponto em que um `$ref` não resolve dentro do schema: não há forma a conferir ali. */
+const UNRESOLVED = Object.freeze({ unresolved: true });
+
+/** Um dos marcadores de `expand`, e não um schema de verdade. */
+function isMarker(schema) {
+  return schema === CYCLE || schema === UNRESOLVED;
+}
 
 /**
  * Os ramos concretos e não nulos de um schema, com `$ref` e combinadores expandidos. Cada ramo traz
  * os `$ref` percorridos no caminho atual; um `$ref` que se repete ali vira `CYCLE`, em vez de
- * expandir de novo.
+ * expandir de novo, e um `$ref` que não resolve vira `UNRESOLVED`, em vez de sumir.
  */
 function expand(schema, root, active = NO_REFS, depth = 0) {
   if (schema === null || typeof schema !== "object" || depth > MAX_DEPTH) return [];
   if (typeof schema.$ref === "string") {
     if (active.has(schema.$ref)) return [{ schema: CYCLE, active }];
     const target = resolveRef(root, schema.$ref);
-    return target === undefined ? [] : expand(target, root, new Set([...active, schema.$ref]), depth + 1);
+    if (target === undefined) return [{ schema: UNRESOLVED, active }];
+    return expand(target, root, new Set([...active, schema.$ref]), depth + 1);
   }
   const nested = COMBINATORS.flatMap((key) =>
     Array.isArray(schema[key]) ? schema[key].flatMap((branch) => expand(branch, root, active, depth + 1)) : [],
@@ -68,9 +76,9 @@ function expand(schema, root, active = NO_REFS, depth = 0) {
   return [{ schema, active }, ...nested];
 }
 
-/** Os ramos sem os ciclos, para quem só olha o tipo do próprio nó. */
+/** Os ramos sem os marcadores, para quem só olha o tipo do próprio nó. */
 function branches(schema, root) {
-  return expand(schema, root).flatMap(({ schema: branch }) => (branch === CYCLE ? [] : [branch]));
+  return expand(schema, root).flatMap(({ schema: branch }) => (isMarker(branch) ? [] : [branch]));
 }
 
 function isOpen(schema) {
@@ -89,7 +97,9 @@ function isArraySchema(schema) {
  * Os schemas alcançados por `segments` em todos os ramos não nulos. Um schema sem forma alcança
  * qualquer caminho abaixo dele e entra como está. Com `throughLists`, uma lista é atravessada. Um
  * ciclo de `$ref` sem avançar no caminho (por lista ou união) não leva a lugar nenhum; ao descer
- * por um campo, o caminho avança, e o mesmo `$ref` pode voltar, como numa árvore.
+ * por um campo, o caminho avança, e o mesmo `$ref` pode voltar, como numa árvore. Um `$ref` que não
+ * resolve antes do fim do caminho entra como `UNRESOLVED`: quem confere o caminho o descarta, e
+ * quem lista as folhas o marca como aberto.
  */
 function collectTargets(schema, segments, root, throughLists, out, active = NO_REFS, depth = 0) {
   if (depth > MAX_DEPTH) return;
@@ -99,7 +109,7 @@ function collectTargets(schema, segments, root, throughLists, out, active = NO_R
   }
   for (const { schema: branch, active: refs } of expand(schema, root, active)) {
     if (branch === CYCLE) continue;
-    if (isOpen(branch)) {
+    if (branch === UNRESOLVED || isOpen(branch)) {
       out.push(branch);
       continue;
     }
@@ -127,7 +137,7 @@ function collectTargets(schema, segments, root, throughLists, out, active = NO_R
 export function schemaHasPath(schema, segments, root = schema) {
   const targets = [];
   collectTargets(schema, segments, root, true, targets);
-  return targets.length > 0;
+  return targets.some((target) => target !== UNRESOLVED);
 }
 
 const TITLE_TYPES = new Set(["string", "number", "integer"]);
@@ -139,19 +149,24 @@ const TITLE_TYPES = new Set(["string", "number", "integer"]);
 export function schemaTitleIsText(schema, segments, root = schema) {
   const targets = [];
   collectTargets(schema, segments, root, false, targets);
-  return targets.some((target) =>
-    isOpen(target) ||
-    branches(target, root).some((branch) => {
-      if (isOpen(branch)) return true;
-      const types = Array.isArray(branch.type) ? branch.type : [branch.type];
-      return types.some((type) => TITLE_TYPES.has(type));
-    }),
+  return targets.some(
+    (target) =>
+      target !== UNRESOLVED &&
+      (isOpen(target) ||
+        branches(target, root).some((branch) => {
+          if (isOpen(branch)) return true;
+          const types = Array.isArray(branch.type) ? branch.type : [branch.type];
+          return types.some((type) => TITLE_TYPES.has(type));
+        })),
   );
 }
 
 /**
- * As folhas abaixo de `schema`. Um `$ref` que volta a um schema já no caminho atual (uma estrutura
- * recursiva) entra em `open` naquele ponto: abaixo dele, qualquer profundidade pode chegar ao modelo.
+ * As folhas abaixo de `schema`. Entram em `open`, no ponto em que aparecem, o schema sem forma, o
+ * `$ref` que volta a um schema já no caminho atual (uma estrutura recursiva) e o `$ref` que não
+ * resolve: abaixo deles, qualquer campo pode chegar ao modelo. Um objeto que aceita chaves não
+ * declaradas (`additionalProperties: true`, como o `.passthrough()` do zod) entra como `<ponto>.*`,
+ * a mesma marca da chave de um mapa, porque a projeção copia o objeto inteiro.
  */
 function collectLeaves(schema, prefix, root, leaves, open, active = NO_REFS, depth = 0) {
   if (depth > MAX_DEPTH) {
@@ -159,7 +174,7 @@ function collectLeaves(schema, prefix, root, leaves, open, active = NO_REFS, dep
     return;
   }
   for (const { schema: branch, active: refs } of expand(schema, root, active)) {
-    if (branch === CYCLE || isOpen(branch)) {
+    if (isMarker(branch) || isOpen(branch)) {
       open.add(prefix);
       continue;
     }
@@ -176,10 +191,13 @@ function collectLeaves(schema, prefix, root, leaves, open, active = NO_REFS, dep
       }
     }
     const additional = branch.additionalProperties;
-    if (additional !== null && typeof additional === "object") {
+    const hasAdditional = additional === true || (additional !== null && typeof additional === "object");
+    if (additional === true) {
+      open.add(`${prefix}.*`);
+    } else if (hasAdditional) {
       collectLeaves(additional, `${prefix}.*`, root, leaves, open, refs, depth + 1);
     }
-    if (!hasProperties && !(additional !== null && typeof additional === "object")) leaves.add(prefix);
+    if (!hasProperties && !hasAdditional) leaves.add(prefix);
   }
 }
 
@@ -190,8 +208,10 @@ function collectLeaves(schema, prefix, root, leaves, open, active = NO_REFS, dep
  * ao modelo por um caminho que termina num contêiner.
  *
  * - `leaves`: caminhos das folhas, com ponto e sem índice de lista; `*` marca a chave de um mapa;
- * - `open`: pontos em que o schema não declara forma (`z.unknown()`, `z.any()`) ou volta a si mesmo
- *   por `$ref`: qualquer campo abaixo deles pode ir ao modelo, e a conferência não alcança.
+ * - `open`: pontos por onde qualquer campo pode ir ao modelo sem que a conferência alcance: o schema
+ *   que não declara forma (`z.unknown()`, `z.any()`), o `$ref` que volta a si mesmo ou que não
+ *   resolve, e, como `<ponto>.*`, o objeto que aceita chaves não declaradas
+ *   (`additionalProperties: true`, do `.passthrough()` do zod).
  */
 export function assistantContextLeaves(output, context, root = output) {
   return context.map((path) => {

package/bin/lib/gen-manifest.mjs

@@ -80,6 +80,7 @@ function shapeAction(a) {
     out.paginate = a.paginate;
     out.text = a.text;
     out.periods = a.periods;
+    if (a.grouping !== undefined) out.grouping = a.grouping;
   }
   if (a.kind === "view") {
     out.projection = a.projection ?? [];

package/bin/lib/gen-runner.mjs

@@ -43,7 +43,7 @@
  *       input: JSONSchema,                    // zod-to-json-schema
  *       output: JSONSchema,                   // zod-to-json-schema
  *       fields?: Record<string, FieldSpecSerialized>,
- *       filters?, sort?, paginate?, text?, periods?,  // search
+ *       filters?, sort?, paginate?, text?, periods?, grouping?,  // list
  *       projection?, expand?,                          // view
  *       background?: boolean,
  *       emits?: string[],
@@ -433,6 +433,7 @@ function serializeAction(action, ctx) {
     base.paginate = action.paginate ?? null;
     base.text = action.text ?? null;
     base.periods = Array.isArray(action.periods) ? action.periods : [];
+    if (action.grouping !== undefined) base.grouping = action.grouping;
   }
 
   if (action.kind === "view") {

package/bin/lib/gen-stubs.mjs

@@ -149,6 +149,9 @@ function renderActionStub(action) {
       const filters = stripNullsFromFields(action.filters)
       lines.push(`  filters: ${formatObjectLiteral(filters, '  ')},`)
     }
+    if (action.grouping && Array.isArray(action.grouping.fields)) {
+      lines.push(`  grouping: ${JSON.stringify(action.grouping)},`)
+    }
   }
   if (Array.isArray(action.invalidates) && action.invalidates.length > 0) {
     lines.push(`  invalidates: ${JSON.stringify(action.invalidates)},`)

package/docs/adr/0052-floating-layer-coexists-with-modal-surfaces.md

@@ -225,6 +225,17 @@ camada uma vez. No modal, o Esc fecha o modal, como hoje. A alternativa de fecha
 está visualmente por cima foi descartada: quem preenche o modal e aperta Esc quer sair do modal, não
 do painel que nem está usando.
 
+*Nota (2026-10-05):* a regra vale para a camada que tem o que fechar. Uma camada sem
+`onEscapeKeyDown` não engole o Esc: com a pessoa nela, a tecla segue para o modal de trabalho, que
+fecha como fecharia com a pessoa nele. Antes, o Opus marcava o evento e chamava um handler ausente,
+e nem o modal nem a camada reagiam; quem chegava ao FAB pelo Tab e apertava Esc encontrava uma
+tecla sem efeito. Com o handler, nada muda: a camada recebe a tecla e o modal continua aberto. O
+consumidor que só tem o que fechar com o painel aberto passa o handler nesse estado e `undefined`
+com o FAB, como a Grand Brasil já faz. A revisão também apontou o handler presente que não tem o que
+fechar naquele momento; o Opus não consegue distinguir esse caso, e a forma de dizer “não há nada a
+fechar aqui” é não passar o handler. Os testes do pacote cobrem o FAB focado e o clique numa área
+sem foco da camada, com Dialog e Drawer, e o navegador real cobre o FAB alcançado pelo Tab.
+
 Antes dessa regra vale a do Radix: um `DismissableLayer` aberto depois do modal consome o Esc, onde
 quer que a pessoa esteja. Isso dá três exceções conhecidas e aceitas:
 
@@ -658,6 +669,12 @@ cada repositório, o que mantém uma só pilha de escopos e um só contexto de `
   navegadores. O roteiro manual acima fica para a adoção na Grand Brasil, executado no Mac do João
   (Safari com VoiceOver) e no Firefox antes de a adoção chegar à `main` da Grand Brasil, com o
   resultado registrado na entrega da adoção.
+
+  *Nota (2026-10-05):* o roteiro manual não foi executado. Na adoção pela Grand Brasil, o dono do
+  produto decidiu seguir sem ele. A evidência da camada é a dos testes de navegador do pacote, no
+  Chromium real, somada aos testes da adoção. Safari, Firefox e VoiceOver continuam sem
+  verificação. Se aparecer em uso um problema de leitor de tela, de Safari ou de Firefox com a
+  camada sobre um modal, o roteiro acima volta a ser exigido.
 - **Arquitetura:**
   - todo uso de portal em `src/ui` lê o contêiner da camada;
   - só `modal-layers.ts`, `dialog.tsx`, `drawer.tsx` e `floating-layer.tsx` aplicam as exceções;
@@ -666,3 +683,5 @@ cada repositório, o que mantém uma só pilha de escopos e um só contexto de `
   - o teste de numeração de ADRs continua passando.
 - **Na Grand Brasil:** um teste do shell confirma que o FAB e o painel ficam dentro de
   `[data-slot="floating-layer"]`, e o roteiro de navegador acima roda na pilha de desenvolvimento.
+  *Nota (2026-10-05):* o roteiro foi dispensado na adoção e não rodou; ver a nota da mesma data no
+  item **Navegador real**.

package/docs/adr/0053-read-action-declares-the-resource-assistant.md

@@ -355,7 +355,14 @@ aberto assim:
   `assistantContextLeaves(output, context)`: a partir do JSON Schema da saída, como o manifest o
   traz, devolve por caminho os campos folha alcançados e os pontos sem forma declarada ou em que um
   `$ref` volta a si mesmo, por onde qualquer campo pode passar. O subpath publica tipos
-  (`assistant-schema.d.mts`) para um teste em TypeScript estrito.
+  (`assistant-schema.d.mts`) para um teste em TypeScript estrito. *Nota (2026-10-05):* dois pontos
+  por onde qualquer campo passa ficavam fora de `open`. Um `$ref` que não resolve dentro do schema
+  sumia sem aparecer em `leaves` nem em `open`; agora entra em `open` no ponto em que aparece. Um
+  objeto que aceita chaves não declaradas (`additionalProperties: true`, que o `.passthrough()` do
+  zod produz) era tratado como fechado, embora a projeção copie o objeto inteiro; agora entra em
+  `open` como `<caminho>.*`, a mesma marca da chave de um mapa. A conferência do `opus gen` não
+  muda: um caminho abaixo de um `$ref` que não resolve continua recusado, e ele não vale como
+  `title`.
 
 ## Consequências
 

package/docs/adr/0054-action-list-grouping-is-a-declared-server-cut.md

@@ -0,0 +1,82 @@
+# ADR 0054 — Agrupamento da ActionList é um recorte declarado e consultado no servidor
+
+- **Status:** aceita.
+- **Data:** 2026-10-03.
+- **Relacionadas:** ADR 0013 (Presentation orientada a action) e ADR 0024 (preenchimento das
+  regiões de lista).
+
+## Contexto
+
+Listagens operacionais precisam, em alguns casos, comparar conjuntos dentro do mesmo recorte. A
+fila de eventos da Grand Brasil é o primeiro caso: a pessoa quer reunir os eventos por status sem
+perder busca, filtros, ordenação, contagens ou paginação.
+
+Agrupar apenas os itens carregados criaria uma representação falsa. Uma página de cinquenta itens
+não permite concluir quantos registros existem em cada grupo, e trocar de página faria grupos
+sumirem ou mudarem de tamanho. Acrescentar um envelope agregado ao protocolo resolveria isso com
+uma consulta, mas obrigaria todo handler e adapter a aprender uma segunda forma de resposta antes de
+existir evidência de que o custo compensa.
+
+O campo também não pode ser inferido de toda coluna ou filtro. Texto livre e lookup podem ter
+cardinalidade alta, data e número exigem faixas, e nem toda dimensão fechada faz sentido como
+organização da lista. A decisão precisa continuar no contrato de produto.
+
+## Decisão
+
+### 1. A action declara as dimensões permitidas
+
+Uma `ListAction` pode declarar:
+
+```ts
+grouping: {
+  fields: ['status', 'stage'],
+}
+```
+
+Cada nome referencia um filtro `select` com opções `static` ou `dictionary`. O controle do filtro
+pode aceitar uma ou várias opções; cada consulta de grupo envia um único valor na forma esperada
+pelo filtro. A declaração não define agrupamento inicial: a lista continua plana até a pessoa
+escolher “Agrupar por” em **Exibição**. O estado usa `groupBy` e a URL usa `group=<campo>`.
+
+O Opus rejeita dimensões ausentes, filtros de outro tipo, lookups, conjuntos estáticos sem opções
+fechadas e actions sem `paginate: 'offset'`. A interface oferece apenas dicionários resolvidos com
+até doze opções por dimensão; acima disso, a declaração não é adequada para agrupamento operacional.
+
+### 2. Cada grupo é uma consulta da mesma ListAction
+
+O agrupamento preserva o input base, a busca, o período, os demais filtros e a ordenação. Para cada
+opção da dimensão, o Opus executa a mesma action com o valor do grupo aplicado ao filtro. Um filtro
+já aplicado à dimensão restringe quais grupos aparecem; não é removido nem reinterpretado.
+
+Cada resposta precisa devolver `total`. A ausência desse dado vira o estado de erro da lista, sem
+lançar uma exceção durante o render. Esse total nomeia o grupo e governa sua paginação. O primeiro
+recorte usa o limite da lista; **Carregar mais** busca a página seguinte daquele grupo e acrescenta
+os itens, sem reiniciar os demais. A invalidação ou a atualização manual refaz todas as consultas.
+
+Essa primeira implementação aceita o custo de até doze consultas em paralelo. Um envelope de
+facetas ou uma action agregada só será introduzido quando medição real justificar outra fronteira.
+
+### 3. O agrupamento pertence à tabela
+
+A tabela mantém um único cabeçalho e abre um `tbody` por grupo. O cabeçalho do grupo é recolhível,
+expõe `aria-expanded`, apresenta o valor pelo dicionário quando houver e mostra a contagem correta,
+inclusive zero. O agrupamento não se aplica a `children` nem a views alternativas; ao sair da tabela,
+os dados voltam à consulta plana.
+
+Busca, filtros e período são aplicados antes do agrupamento; ordenação vale dentro de cada grupo. A
+seleção em lote cobre os itens carregados dos grupos abertos. Recolher um grupo remove da seleção os
+itens dele, para nenhuma ação operar sobre linhas invisíveis.
+
+Se uma consulta falhar, a lista apresenta o erro padrão e permite refazer o conjunto. Se todos os
+totais forem zero, há um único estado vazio. Não existe paginador global enquanto o agrupamento está
+ativo; o rodapé mostra apenas a soma dos totais.
+
+## Consequências
+
+- O contrato distingue capacidade de agrupamento de uma seleção corrente.
+- Contagens e páginas continuam autoritativas no servidor; não há agrupamento parcial silencioso.
+- O número de requisições cresce com as opções da dimensão, de forma explícita e limitada.
+- O primeiro consumidor deve testar que a soma dos totais agrupados coincide com o total da lista
+  plana para o mesmo recorte.
+- Uma futura otimização de protocolo pode preservar `grouping` e `groupBy`, trocando apenas como os
+  dados chegam ao cliente.

package/docs/protocol.md

@@ -129,6 +129,7 @@ type ListAction<In, Out> = ActionBase<In, Paginated<Out>> & {
   paginate?: 'cursor' | 'offset' | false
   text?:     { fields: string[] }
   periods?:  { value: string, label: I18nRef }[]
+  grouping?: { fields: string[] }
 }
 
 type ViewAction<In, Out> = ActionBase<In, Out> & {
@@ -205,7 +206,10 @@ type OptionsSpec =
 
 **`search`**
 - `filters?: Record<string, FilterSpec>` — filtros disponíveis (chave é nome).
-- `sort?`, `paginate?`, `text?`, `periods?` — ver tipos abaixo.
+- `sort?`, `paginate?`, `text?`, `periods?`, `grouping?` — ver tipos abaixo.
+- `grouping.fields` referencia filtros `select` com opções fechadas (`static` ou
+  `dictionary`). A interface consulta cada valor como um recorte da mesma action; não agrupa só a
+  página carregada.
 
 ```ts
 type FilterSpec = {
@@ -259,7 +263,10 @@ o dado necessário. A action `view` que lê o recurso declara as três coisas em
   um intermediário `null` aparece como `null`. Num campo anulável ou numa união, o `opus gen` aceita
   o caminho que existe em algum ramo não nulo. Um caminho que termina num objeto ou numa lista leva
   tudo abaixo dele (`assistantContextLeaves`, de `@softize/opus/assistant-schema`, lista o que cada
-  caminho alcança). `title` aponta para texto ou número, fora de lista.
+  caminho alcança: em `leaves`, as folhas; em `open`, os pontos por onde qualquer campo passa sem
+  conferência, como um schema sem forma, um `$ref` recursivo ou que não resolve e, como
+  `<caminho>.*`, um objeto com `additionalProperties: true`). `title` aponta para texto ou número,
+  fora de lista.
 - **Leitura.** `runtime.readResource(resource, id, base, { context? })` executa a action dona com
   `{ id }` pelo `execute`: autorização, loaders, auditoria, marca de dado pessoal e span são os da
   action. Devolve `{ ok: true, resource: { kind, id, title, label, skill }, context?, meta }` ou o

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softize/opus",
-  "version": "25.2.0",
+  "version": "25.3.1",
   "description": "End-to-end action protocol for TypeScript. Single package with subpath exports (core + adapters).",
   "license": "MIT",
   "type": "module",

package/src/core/actions.ts

@@ -9,8 +9,9 @@
  * resto server-only) — ver `contracts.ts`. `defineAction` continua válido e
  * suportado para action server-only, em que não há contrato a compartilhar.
  *
- * Validação estrutural acontece no `Runtime.register()`, não aqui. Esta função
- * é puramente sobre **declaração**.
+ * A factory valida contradições que existem inteiras na declaração, como um
+ * `grouping` que referencia um filtro incompatível. O runtime repete essas
+ * guardas para actions montadas sem a factory.
  *
  * Ver §2 do protocolo.
  */
@@ -22,6 +23,7 @@ import type {
   SimpleAction,
   ViewAction,
 } from './types.ts'
+import { assertValidListGrouping } from './list-grouping.ts'
 
 /* eslint-disable @typescript-eslint/no-explicit-any */
 
@@ -61,6 +63,7 @@ export function defineAction<In, Out, ParsedIn = In>(
 ): ViewAction<In, Out, ParsedIn>
 
 export function defineAction(spec: any): any {
+  if (spec.kind === 'list') assertValidListGrouping(spec)
   return spec
 }
 

package/src/core/contracts.ts

@@ -28,6 +28,7 @@ import type {
   SimpleAction,
   ViewAction,
 } from './types.ts'
+import { assertValidListGrouping } from './list-grouping.ts'
 
 /* eslint-disable @typescript-eslint/no-explicit-any */
 
@@ -117,6 +118,7 @@ export function defineContract<In, Out, ParsedIn = In>(
   contract: ViewContract<In, Out, ParsedIn>,
 ): ViewContract<In, Out, ParsedIn>
 export function defineContract(contract: any): any {
+  if (contract.kind === 'list') assertValidListGrouping(contract)
   return contract
 }
 

package/src/core/list-grouping.ts

@@ -0,0 +1,45 @@
+import type { ListAction } from './types.ts'
+
+const MAX_GROUP_OPTIONS = 12
+
+/** Valida a parte estrutural de `ListAction.grouping` no momento da declaração.
+ *  Dicionários são resolvidos pelo provider e têm a cardinalidade conferida pela UI. */
+export function assertValidListGrouping(
+  action: Pick<ListAction<unknown, unknown>, 'name' | 'filters' | 'grouping' | 'paginate'>,
+): void {
+  const fields = action.grouping?.fields
+  if (fields === undefined) return
+  if (fields.length === 0) {
+    throw new Error(`A action "${action.name}" declara grouping.fields vazio.`)
+  }
+  if (new Set(fields).size !== fields.length) {
+    throw new Error(`A action "${action.name}" repete uma dimensão em grouping.fields.`)
+  }
+  if (action.filters?.group !== undefined) {
+    throw new Error(`A action "${action.name}" usa o filtro reservado "group" enquanto declara grouping.`)
+  }
+  if (action.paginate !== 'offset') {
+    throw new Error(`A action "${action.name}" declara grouping, mas o agrupamento exige paginate: "offset".`)
+  }
+  for (const field of fields) {
+    const filter = action.filters?.[field]
+    if (filter === undefined) {
+      throw new Error(`A action "${action.name}" agrupa por "${field}", mas esse filtro não existe.`)
+    }
+    if (filter.type !== 'select' || (filter.options?.kind !== 'static' && filter.options?.kind !== 'dictionary')) {
+      throw new Error(
+        `A action "${action.name}" agrupa por "${field}", mas a dimensão precisa ser ` +
+          'um filtro select com opções static ou dictionary.',
+      )
+    }
+    if (
+      filter.options.kind === 'static' &&
+      (filter.options.items.length === 0 || filter.options.items.length > MAX_GROUP_OPTIONS)
+    ) {
+      throw new Error(
+        `A action "${action.name}" agrupa por "${field}", mas a dimensão precisa ter ` +
+          `entre 1 e ${MAX_GROUP_OPTIONS} opções.`,
+      )
+    }
+  }
+}

package/src/core/runtime.ts

@@ -13,6 +13,7 @@
 
 import { isReaction } from './reactions.ts'
 import { isBackgroundAction } from './actions.ts'
+import { assertValidListGrouping } from './list-grouping.ts'
 import { isSchedule } from './schedules.ts'
 import {
   collectDomainWarnings,
@@ -547,6 +548,7 @@ export class Runtime {
         })
       }
       this.claimAssistant(action)
+      if (action.kind === 'list') assertValidListGrouping(action)
       this.actions.set(action.name, action)
       if (this.config.dev) this.warnIgnoredExecutionFields(action)
     }

package/src/core/types.ts

@@ -924,6 +924,9 @@ export interface SearchFilters {
   paginate?: 'cursor' | 'offset' | false
   text?: { fields: string[]; placeholder?: I18nRef }
   periods?: PeriodSpec[]
+  /** Dimensões fechadas que a ActionList pode usar para agrupar a tabela. Cada nome
+   *  referencia um filtro select com opções static ou dictionary. */
+  grouping?: { fields: string[] }
   /**
    * Cláusula DSL aplicada **sempre** pelo repository do consumer (ex:
    * `'NOT archived'`). Runtime NÃO executa SQL — quem consome a search
@@ -956,6 +959,8 @@ export interface ListAction<In, Out, ParsedIn = In>
   paginate?: 'cursor' | 'offset' | false
   text?: { fields: string[]; placeholder?: I18nRef }
   periods?: PeriodSpec[]
+  /** Dimensões fechadas que a ActionList pode usar para agrupar a tabela. */
+  grouping?: { fields: string[] }
   /**
    * Ver `SearchFilters.where`. Baseline DSL aplicado pelo repository
    * via `compileWhere` (do `@softize/opus/dsl`). Runtime não executa SQL.

package/src/ui/components/patterns/grouped-list.ts

@@ -0,0 +1,88 @@
+import { useQueries } from '@tanstack/react-query'
+import { useRef } from 'react'
+import type { ActionDef, ActionError, Paginated } from '../../../core/index.ts'
+import { useClient } from '../../drivers/context.tsx'
+
+export interface ListActionGroup<TItem> {
+  value: string
+  items: TItem[]
+  total: number | undefined
+  error: ActionError | undefined
+  isLoading: boolean
+  isFetching: boolean
+  isError: boolean
+  refetch: () => Promise<void>
+}
+
+/** Implementação interna do ActionList para executar um recorte paginado por grupo. */
+export function useGroupedListAction<TItem = unknown, TInput extends Record<string, unknown> = Record<string, unknown>>(
+  action: { name: string; kind: 'list' },
+  input: TInput,
+  field: string | null,
+  values: string[],
+  multiple: boolean,
+  pages: Record<string, number>,
+  pageSize: number,
+): ListActionGroup<TItem>[] {
+  const client = useClient('ActionList grouping')
+  const previous = useRef<{
+    field: string | null
+    groups: Map<string, { items: TItem[]; total: number }>
+  }>({ field, groups: new Map() })
+  if (previous.current.field !== field) {
+    previous.current = { field, groups: new Map() }
+  }
+  const groupField = field ?? '__disabled_group__'
+  const requests =
+    field === null
+      ? []
+      : values.flatMap((value) =>
+          Array.from({ length: pages[value] ?? 1 }, (_, index) => ({
+            value,
+            page: index + 1,
+          })),
+        )
+  const queries = useQueries({
+    queries: requests.map(({ value, page }) => {
+      const groupInput = {
+        ...input,
+        [groupField]: multiple ? [value] : value,
+        page,
+        limit: pageSize,
+      }
+      return {
+        queryKey: [action.name, groupInput],
+        queryFn: async (): Promise<Paginated<TItem>> => {
+          const result = await client.run<Paginated<TItem>>(action as unknown as ActionDef, groupInput)
+          if (!result.ok) throw result.error
+          return result.data
+        },
+      }
+    }),
+  })
+
+  return values.map((value) => {
+    const groupQueries = queries.filter((_, index) => requests[index]?.value === value)
+    const items = groupQueries.flatMap((query) => query.data?.items ?? [])
+    const total = groupQueries.find((query) => query.data?.total !== undefined)?.data?.total
+    const isError = groupQueries.some((query) => query.isError)
+    const hasCompleteData = groupQueries.length > 0 && groupQueries.every((query) => query.data !== undefined)
+    if (hasCompleteData && !isError && total !== undefined) {
+      previous.current.groups.set(value, { items, total })
+    }
+    const fallback = previous.current.groups.get(value)
+    const hasCurrentData = groupQueries.some((query) => query.data !== undefined)
+    return {
+      value,
+      items: hasCurrentData ? items : (fallback?.items ?? []),
+      total: hasCurrentData ? total : fallback?.total,
+      error: (groupQueries.find((query) => query.error !== null)?.error as unknown as ActionError | null) ?? undefined,
+      isLoading: (groupQueries[0]?.isPending ?? true) && fallback === undefined,
+      isFetching: groupQueries.some((query) => query.isFetching),
+      isError,
+      refetch: async () => {
+        await Promise.all(groupQueries.map((query) => query.refetch()))
+      },
+    }
+  })
+}