@softize/opus 25.3.0 → 25.4.0

package/CHANGELOG.md

@@ -7,6 +7,43 @@ 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.4.0 — 2026-10-05
+
+`ListAction.grouping.fields` passa a aceitar filtros `select` ou `lookup` cujas opções completas
+sejam fornecidas em runtime por `ActionList.filterOptions`. A dimensão só aparece em **Agrupar por**
+com 1 a 12 opções; catálogo ausente, vazio ou maior mantém a lista plana, sem agrupar uma amostra.
+A ADR 0055 registra essa extensão da decisão original.
+
+As preferências de ordenação passam para **Exibição**, com a direção como ação dentro do próprio
+campo. O botão sinaliza quando ordenação, agrupamento, colunas ou quantidade por página diferem do
+padrão, e o rodapé explicita **Agrupado por** e **Ordenado por** quando aplicáveis.
+
+Também corrige a `ActionList` agrupada em aplicações Vite que consomem o código-fonte TypeScript do
+Opus. Ao ativar um agrupamento, a lista podia deixar de reconhecer o `OpusProvider` já presente na
+aplicação e interromper a renderização. O agrupamento agora usa o mesmo driver React dos demais
+hooks de action. Não há migração para o consumidor.
+
+## 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.

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/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

@@ -1,9 +1,10 @@
 # ADR 0054 — Agrupamento da ActionList é um recorte declarado e consultado no servidor
 
-- **Status:** aceita.
+- **Status:** aceita, com a fonte de opções ampliada pela ADR 0055.
 - **Data:** 2026-10-03.
 - **Relacionadas:** ADR 0013 (Presentation orientada a action) e ADR 0024 (preenchimento das
-  regiões de lista).
+  regiões de lista). A ADR 0055 substitui somente a restrição desta decisão a opções estáticas ou
+  de dicionário; recorte no servidor, limite de cardinalidade e demais garantias permanecem.
 
 ## Contexto
 

package/docs/adr/0055-runtime-options-can-form-bounded-list-groups.md

@@ -0,0 +1,57 @@
+# ADR 0055 — Opções resolvidas em runtime podem formar grupos limitados da ActionList
+
+- **Status:** aceita.
+- **Data:** 2026-10-05.
+- **Relacionada:** ADR 0054 (agrupamento da ActionList é um recorte declarado e consultado no
+  servidor).
+
+## Contexto
+
+A ADR 0054 limitou `grouping.fields` a filtros `select` com opções estáticas ou de dicionário. A
+restrição garantia que a interface conhecesse todos os grupos antes de consultar a listagem e que o
+custo não passasse de doze requisições paralelas.
+
+Alguns catálogos fechados, porém administráveis, chegam ao consumidor como opções resolvidas em
+runtime. Equipe, unidade e serviço são exemplos: continuam sendo dimensões enumeráveis no recorte
+da tela, mas não pertencem ao contrato como literais nem a um dicionário versionado. Proibir esses
+campos força o produto a duplicar dados administráveis no contrato; aceitar qualquer lookup, por
+outro lado, permitiria agrupar por resultados parciais de uma busca e produziria contagens
+enganosas.
+
+## Decisão
+
+### 1. O contrato aceita filtros enumeráveis de runtime
+
+Um campo declarado em `grouping.fields` pode referenciar um filtro `select` ou `lookup`. As opções
+estáticas continuam sendo validadas na declaração e precisam conter entre uma e doze entradas.
+Filtros sem opções estáticas são estruturalmente válidos porque sua cardinalidade só é conhecida na
+interface.
+
+### 2. `filterOptions` precisa representar o catálogo completo do recorte
+
+A `ActionList` só oferece a dimensão quando consegue resolver entre uma e doze opções. Para
+`lookup`, isso exige que o consumidor forneça explicitamente em `filterOptions[campo]` o catálogo
+completo aplicável à tela; os resultados transitórios da busca do próprio lookup não são usados
+como grupos.
+
+Se as opções estiverem ausentes, vazias ou acima do limite, a dimensão não aparece em **Agrupar
+por** e um `groupBy` recebido por estado ou URL é ignorado. Não há agrupamento parcial silencioso.
+
+### 3. O protocolo de consulta não muda
+
+Cada opção continua produzindo um recorte da mesma `ListAction`, como definido na ADR 0054. O
+limite de doze consultas paralelas, a exigência de `paginate: 'offset'`, o `total` autoritativo e a
+paginação independente por grupo permanecem iguais.
+
+Catálogos maiores precisam de uma futura fronteira agregada no servidor; esta decisão não antecipa
+esse protocolo.
+
+## Consequências
+
+- Produtos podem agrupar por catálogos administráveis sem copiá-los para o contrato.
+- O consumidor assume explicitamente que `filterOptions[campo]` é exaustivo para o recorte atual.
+- Um lookup pesquisável ou de alta cardinalidade não se torna uma dimensão de agrupamento apenas
+  por estar declarado.
+- Serviço deixa de ser oferecido como agrupamento quando o catálogo resolvido tiver mais de doze
+  opções; isso é uma limitação visível e segura, não uma amostra dos primeiros resultados.
+

package/docs/protocol.md

@@ -207,9 +207,11 @@ type OptionsSpec =
 **`search`**
 - `filters?: Record<string, FilterSpec>` — filtros disponíveis (chave é nome).
 - `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.
+- `grouping.fields` referencia filtros enumeráveis `select` ou `lookup`. Opções estáticas e de
+  dicionário podem vir da declaração/provider; catálogos administráveis vêm de `filterOptions` no
+  consumidor. A interface só oferece dimensões com 1 a 12 opções completas e consulta cada valor
+  como um recorte da mesma action; não agrupa só a página carregada nem resultados parciais de uma
+  busca.
 
 ```ts
 type FilterSpec = {
@@ -263,7 +265,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.3.0",
+  "version": "25.4.0",
   "description": "End-to-end action protocol for TypeScript. Single package with subpath exports (core + adapters).",
   "license": "MIT",
   "type": "module",

package/src/core/list-grouping.ts

@@ -3,7 +3,7 @@ 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. */
+ *  Dicionários e opções resolvidas em runtime têm a cardinalidade conferida pela UI. */
 export function assertValidListGrouping(
   action: Pick<ListAction<unknown, unknown>, 'name' | 'filters' | 'grouping' | 'paginate'>,
 ): void {
@@ -26,14 +26,14 @@ export function assertValidListGrouping(
     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')) {
+    if (filter.type !== 'select' && filter.type !== 'lookup') {
       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.',
+          'um filtro select ou lookup com opções enumeráveis.',
       )
     }
     if (
-      filter.options.kind === 'static' &&
+      filter.options?.kind === 'static' &&
       (filter.options.items.length === 0 || filter.options.items.length > MAX_GROUP_OPTIONS)
     ) {
       throw new Error(

package/src/core/types.ts

@@ -924,8 +924,8 @@ 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. */
+  /** Dimensões enumeráveis que a ActionList pode usar para agrupar a tabela. Cada nome
+   *  referencia um filtro select/lookup com até 12 opções declaradas ou resolvidas em runtime. */
   grouping?: { fields: string[] }
   /**
    * Cláusula DSL aplicada **sempre** pelo repository do consumer (ex:
@@ -959,7 +959,7 @@ 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. */
+  /** Dimensões enumeráveis que a ActionList pode usar para agrupar a tabela. */
   grouping?: { fields: string[] }
   /**
    * Ver `SearchFilters.where`. Baseline DSL aplicado pelo repository

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

@@ -1,7 +1,6 @@
 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'
+import type { ActionDef, ActionError, ClientAdapter, Paginated } from '../../../core/index.ts'
 
 export interface ListActionGroup<TItem> {
   value: string
@@ -15,7 +14,8 @@ export interface ListActionGroup<TItem> {
 }
 
 /** 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>>(
+export function useGroupedListQueries<TItem = unknown, TInput extends Record<string, unknown> = Record<string, unknown>>(
+  client: ClientAdapter,
   action: { name: string; kind: 'list' },
   input: TInput,
   field: string | null,
@@ -24,7 +24,6 @@ export function useGroupedListAction<TItem = unknown, TInput extends Record<stri
   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 }>

package/src/ui/components/patterns/list.tsx

@@ -62,11 +62,11 @@ import {
 } from "../../../core/index.ts";
 import {
   useDicts,
+  useGroupedListAction,
   useListAction,
   useLookupAction,
   type DictLike,
 } from "../../drivers/react.tsx";
-import { useGroupedListAction } from "./grouped-list.ts";
 import { cn } from "../../lib/cn.ts";
 import { FillBoundary, useFillLeaf } from "./fill-region.ts";
 import { objectSchemaShape } from "../../lib/object-schema.ts";
@@ -1779,6 +1779,7 @@ export function ActionList<TInput, TItem>({
   const raw = controlledState ?? internal;
   const state: ActionListState = {
     ...raw,
+    sort: raw.sort ?? defaultSort,
     period: raw.period ?? null,
     from: raw.from ?? null,
     to: raw.to ?? null,
@@ -1818,11 +1819,7 @@ export function ActionList<TInput, TItem>({
   const availableGroupingFields = groupingFields.filter((field) => {
     if (action.filters?.group !== undefined) return false;
     const spec = action.filters?.[field];
-    if (
-      spec?.type !== "select" ||
-      (spec.options?.kind !== "static" && spec.options?.kind !== "dictionary")
-    )
-      return false;
+    if (spec?.type !== "select" && spec?.type !== "lookup") return false;
     const options = [
       ...optionsFor(field, spec, filterOptions),
       ...dictOptionsFor(spec, dicts),
@@ -1841,6 +1838,10 @@ export function ActionList<TInput, TItem>({
     availableGroupingFields.includes(requestedGroupBy)
       ? requestedGroupBy
       : null;
+  const activeGroupingLabel =
+    activeGroupBy === null
+      ? null
+      : text(action.filters?.[activeGroupBy]?.label, activeGroupBy);
   const hasSegment = children === undefined && viewEntries.length > 1;
   const periods = action.periods ?? [];
   const hasToolbar =
@@ -2090,6 +2091,34 @@ export function ActionList<TInput, TItem>({
       state.sort?.field === key && state.sort.dir === "asc" ? "desc" : "asc";
     setStateResetPage({ ...state, sort: { field: key, dir } });
   };
+  const activeSort = state.sort;
+  const sortLabelFor = (field: string): string | null => {
+    const declared = action.columns?.find((column) => column.key === field);
+    if (declared !== undefined) return text(declared.label, field);
+    const explicit = columns?.find((column) => column.key === field)?.header;
+    return typeof explicit === "string" ? explicit : null;
+  };
+  const sortableFields = (action.sort?.fields ?? []).flatMap((field) => {
+    const label = sortLabelFor(field);
+    return label === null ? [] : [{ value: field, label }];
+  });
+  const activeSortLabel =
+    activeSort === null
+      ? null
+      : sortLabelFor(activeSort.field);
+  const activeSortDirection =
+    activeSort?.dir === "asc" ? "crescente" : "decrescente";
+  const sortCustomized =
+    activeSort?.field !== defaultSort?.field ||
+    activeSort?.dir !== defaultSort?.dir;
+  const displayCustomized =
+    activeGroupBy !== null ||
+    state.columns !== null ||
+    state.limit !== null ||
+    sortCustomized;
+  const displayLabel = displayCustomized
+    ? "Exibição personalizada"
+    : "Exibição";
 
   // — Multi-seleção (batch): `can` de QUALQUER ação torna a linha marcável; nenhuma
   //   elegível na página → a coluna de checkbox nem aparece. Seleção é transitória
@@ -2180,14 +2209,20 @@ export function ActionList<TInput, TItem>({
                     <Button
                       variant="ghost"
                       size="icon"
-                      className="shrink-0"
-                      aria-label="Exibição"
+                      className="relative shrink-0"
+                      aria-label={displayLabel}
                     >
                       <Settings2 className="h-3.5 w-3.5" />
+                      {displayCustomized && (
+                        <Dot
+                          context="primary"
+                          className="absolute top-1 right-1 ring-2 ring-background"
+                        />
+                      )}
                     </Button>
                   </PopoverTrigger>
                 </TooltipTrigger>
-                <TooltipContent>Exibição</TooltipContent>
+                <TooltipContent>{displayLabel}</TooltipContent>
               </Tooltip>
               <PopoverContent
                 align="end"
@@ -2195,6 +2230,93 @@ export function ActionList<TInput, TItem>({
                 data-slot="action-list-display"
               >
                 <div className="space-y-3">
+                  {children === undefined &&
+                    activeView === "table" &&
+                    sortableFields.length > 0 && (
+                      <>
+                        <div className="space-y-2">
+                          <div className="flex items-center justify-between">
+                            <span className="text-xs font-medium text-muted-foreground">
+                              Ordenação
+                            </span>
+                            {sortCustomized && (
+                              <button
+                                type="button"
+                                onClick={() =>
+                                  setState({ ...state, sort: defaultSort, page: 1 })
+                                }
+                                className="inline-flex items-center gap-1 text-xs text-muted-foreground transition-colors hover:text-foreground"
+                              >
+                                <Eraser className="size-3" />
+                                Padrão
+                              </button>
+                            )}
+                          </div>
+                          <Select
+                            aria-label="Ordenar por"
+                            size="sm"
+                            className="w-full"
+                            value={activeSort?.field ?? "__none__"}
+                            onChange={(field) =>
+                              setState({
+                                ...state,
+                                sort:
+                                  field === "__none__"
+                                    ? null
+                                    : {
+                                        field,
+                                        dir:
+                                          activeSort?.field === field
+                                            ? activeSort.dir
+                                            : "asc",
+                                      },
+                                page: 1,
+                              })
+                            }
+                            options={[
+                              ...(defaultSort === null
+                                ? [{ value: "__none__", label: "Sem ordenação" }]
+                                : []),
+                              ...sortableFields,
+                            ]}
+                            trailing={
+                              activeSort !== null ? (
+                                <Button
+                                  type="button"
+                                  variant="ghost"
+                                  size="icon-xs"
+                                  aria-label={
+                                    activeSort.dir === "asc"
+                                      ? "Ordem crescente. Alterar para decrescente"
+                                      : "Ordem decrescente. Alterar para crescente"
+                                  }
+                                  onClick={() =>
+                                    setState({
+                                      ...state,
+                                      sort: {
+                                        ...activeSort,
+                                        dir:
+                                          activeSort.dir === "asc"
+                                            ? "desc"
+                                            : "asc",
+                                      },
+                                      page: 1,
+                                    })
+                                  }
+                                >
+                                  {activeSort.dir === "asc" ? (
+                                    <ArrowUp aria-hidden="true" />
+                                  ) : (
+                                    <ArrowDown aria-hidden="true" />
+                                  )}
+                                </Button>
+                              ) : undefined
+                            }
+                          />
+                        </div>
+                        <Separator />
+                      </>
+                    )}
                   {children === undefined &&
                     activeView === "table" &&
                     availableGroupingFields.length > 0 && (
@@ -2676,21 +2798,49 @@ export function ActionList<TInput, TItem>({
       ? Math.max(1, Math.ceil(total / (state.limit ?? pageSize)))
       : 1;
   const goTo = (page: number): void => setState({ ...state, page });
+  const displaySummary =
+    activeGroupingLabel !== null || activeSortLabel !== null ? (
+      <span
+        data-slot="action-list-display-summary"
+        className="flex min-w-0 flex-wrap items-center gap-x-2 gap-y-1"
+      >
+        {activeGroupingLabel !== null && (
+          <span className="min-w-0 break-words">
+            Agrupado por {activeGroupingLabel}
+          </span>
+        )}
+        {activeGroupingLabel !== null && activeSortLabel !== null && (
+          <span aria-hidden="true">·</span>
+        )}
+        {activeSortLabel !== null && (
+          <span className="min-w-0 break-words">
+            Ordenado por {activeSortLabel} ({activeSortDirection})
+          </span>
+        )}
+      </span>
+    ) : null;
   const footer =
     total !== undefined && !isError && activeGroupBy !== null ? (
       <div
         data-slot="action-list-footer"
-        className="flex min-h-10 items-center justify-end border-t border-border px-3 py-1 text-xs text-muted-foreground"
+        className="flex min-h-10 flex-wrap items-center justify-between gap-3 border-t border-border px-3 py-1 text-xs text-muted-foreground"
       >
-        {total} {total === 1 ? "item" : "itens"} no total
+        {displaySummary}
+        <span className={cn(displaySummary === null && "ml-auto")}>
+          {total} {total === 1 ? "item" : "itens"} no total
+        </span>
       </div>
     ) : total !== undefined && !isError ? (
       <div
         data-slot="action-list-footer"
-        className="grid min-h-10 grid-cols-[1fr_auto_1fr] items-center gap-3 border-t border-border px-3 py-1 text-xs text-muted-foreground"
+        className="grid min-h-10 grid-cols-[minmax(0,1fr)_auto_minmax(0,1fr)] items-center gap-3 border-t border-border px-3 py-1 text-xs text-muted-foreground"
       >
-        <span>
-          Página {state.page} de {pages}
+        <span className="flex min-w-0 flex-wrap items-center gap-x-3 gap-y-1">
+          <span className="whitespace-nowrap">
+            Página {state.page} de {pages}
+          </span>
+          {displaySummary !== null && <span aria-hidden="true">·</span>}
+          {displaySummary}
         </span>
         {pages > 1 && (
           // A primitiva pública na escala densa do rodapé: setas no quadrado `icon-sm`,
@@ -2735,7 +2885,7 @@ export function ActionList<TInput, TItem>({
         )}
         {/* Com 1 página o pager some; o placeholder segura a coluna do meio. */}
         {pages <= 1 && <span />}
-        <span className="justify-self-end">
+        <span className="justify-self-end whitespace-nowrap">
           {total} {total === 1 ? "item" : "itens"} no total
         </span>
       </div>

package/src/ui/components/primitives/floating-layer.tsx

@@ -14,7 +14,9 @@ export interface FloatingLayerProps {
   /**
    * Esc enquanto a pessoa está na camada, com ou sem modal aberto. É chamado uma vez por tecla.
    * Nenhum modal fecha nesse caso, e o Opus não fecha a camada sozinho, porque o estado de aberto
-   * pertence ao consumidor.
+   * pertence ao consumidor. Sem o handler, o Esc com a pessoa na camada fecha o modal de trabalho
+   * aberto: passe `undefined` enquanto a camada não tiver o que fechar, como com o painel fechado e
+   * só o botão que o abre.
    */
   onEscapeKeyDown?: (event: KeyboardEvent) => void;
 }
@@ -49,9 +51,7 @@ export function FloatingLayer({
     const element = document.createElement("div");
     element.setAttribute("data-slot", "floating-layer");
     document.body.appendChild(element);
-    const unregister = registerFloatingLayer(element, (event) =>
-      escapeRef.current?.(event),
-    );
+    const unregister = registerFloatingLayer(element, () => escapeRef.current);
     setHost(element);
     // Desfaz o registro, retira o hospedeiro e, se o foco estava nele com um modal aberto,
     // devolve o foco ao modal.

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

@@ -217,11 +217,11 @@ periods: [
 
 ## Agrupamento
 
-Declare `grouping.fields` quando uma dimensão fechada puder organizar a tabela sem mudar o recorte
-de negócio. Cada campo precisa ser um filtro `select` com opções `static` ou `dictionary`; texto,
-número, data e lookup não são dimensões de agrupamento. O filtro pode aceitar uma ou várias opções:
-cada consulta de grupo envia um único valor na forma declarada. A lista continua plana por padrão,
-e a pessoa escolhe **Agrupar por** em **Exibição**.
+Declare `grouping.fields` quando uma dimensão enumerável puder organizar a tabela sem mudar o
+recorte de negócio. Cada campo precisa ser um filtro `select` ou `lookup`; texto, número e data não
+são dimensões de agrupamento. O filtro pode aceitar uma ou várias opções: cada consulta de grupo
+envia um único valor na forma declarada. A lista continua plana por padrão, e a pessoa escolhe
+**Agrupar por** em **Exibição**.
 
 ```ts
 filters: {
@@ -242,6 +242,12 @@ autoritativa, e **Carregar mais** expande apenas aquele grupo. A soma aparece no
 global. O limite é de doze opções por dimensão. Se um dicionário não estiver disponível ou exceder
 esse limite, a dimensão não é oferecida em **Agrupar por**.
 
+Opções administráveis também podem chegar por `filterOptions`. Nesse caso, o consumidor precisa
+fornecer o catálogo completo aplicável ao recorte — não apenas os resultados correntes de uma busca.
+Um `lookup` só é oferecido para agrupamento quando `filterOptions[campo]` contém de uma a doze
+opções. Sem opções, ou acima desse limite, a dimensão e qualquer `groupBy` recebido pela URL são
+ignorados; a lista nunca agrupa uma amostra parcial.
+
 O agrupamento pertence à tabela derivada. Views alternativas e o modo `children` continuam planos.
 `groupBy` integra `ActionListState`; `listStateToParams` o serializa como `group=<campo>`, e filtros
 aplicados à mesma dimensão restringem os grupos exibidos.
@@ -427,9 +433,17 @@ filters: {
 ## Exibição e estado na URL
 
 O botão de exibição abre as preferências da listagem em qualquer visualização. Na tabela, permite
-mostrar ou ocultar colunas, inclusive as declaradas com `hidden`; em todas as visualizações, permite
-alterar a quantidade de itens por página. Busca, ordenação, filtros, visualização, colunas e limite
-podem ser serializados na query string pelos helpers do componente:
+escolher a ordenação, inverter sua direção, agrupar e mostrar ou ocultar colunas, inclusive as
+declaradas com `hidden`; em todas as visualizações, permite alterar a quantidade de itens por
+página. Um ponto sinaliza quando alguma preferência diverge do padrão. O rodapé explicita a
+ordenação e o agrupamento ativos junto da paginação e do total. Busca, ordenação, filtros,
+visualização, colunas e limite podem ser serializados na query string pelos helpers do componente:
+
+Cada campo de `sort.fields` precisa de uma coluna com rótulo textual para aparecer no seletor e no
+resumo do rodapé; a coluna pode estar `hidden`. Campos sem coluna continuam válidos para o handler e
+para uma ordenação padrão, mas o Opus não expõe seu identificador técnico na interface. **Sem
+ordenação** só aparece quando o contrato não declara `sort.default`; com padrão, use **Padrão** para
+restaurá-lo.
 
 ```tsx
 <ActionList
@@ -519,7 +533,7 @@ render(
 | `text`     | `{ fields }` — liga a busca; convenção: param `q` no input. Ela aparece depois dos filtros inline e imediatamente antes do acesso aos filtros avançados. A busca participa da contagem de controles inline: com mais de um controle, a barra exibe as labels; quando ela é o único recorte, sua label é omitida.                                                                                                                                                                                                                                                                                                                                                                                                                                     |
 | `sort`     | `{ fields, default }` — ordenação inicial; header ordenável escreve `sort: 'chave:dir'`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
 | `periods`  | `{ value, label, default? }[]` — o controle de período (presets + Personalizado com calendário); `default: true` marca o preset inicial, senão vale o primeiro; materializa em `from`/`to` no input.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
-| `grouping` | `{ fields }` — dimensões fechadas disponíveis em **Agrupar por**. Cada nome referencia um filtro `select` com opções estáticas ou de dicionário. Não define agrupamento inicial.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| `grouping` | `{ fields }` — dimensões enumeráveis disponíveis em **Agrupar por**. Cada nome referencia um filtro `select` ou `lookup` com até 12 opções declaradas ou resolvidas por `filterOptions`. Não define agrupamento inicial.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
 
 ## useListAction
 
@@ -538,7 +552,7 @@ chamar a action. `options.enabled` suspende a consulta enquanto for `false`; sem
 | `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`, `SurfaceBody` 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).                                                                                                                                     |
+| `filterOptions`         | `Record<string, SelectOption[]>`                                                                            |                                                                                                                                       | Opções de runtime para filtros select/lookup. Em uma dimensão de agrupamento, a coleção precisa ser completa e ter de 1 a 12 itens.                                                                            |
 | `filterDefaults`        | `Record<string, string>`                                                                                    |                                                                                                                                       | Valores de repouso aplicados à consulta; o `X` só aparece quando o filtro diverge deles e retorna a eles.                                                                                                     |
 | `filterIcons`           | `Record<string, ReactNode>`                                                                                 |                                                                                                                                       | Ícones leading dos filtros, indexados pelo nome declarado no contrato.                                                                                                                                        |
 | `advancedFilters`       | `{ columns?: 1 \| 2 \| 3; sectionIcons?: Record<string, ReactNode>; sectionVariant?: 'plain' \| 'framed' }` | `{ columns: 1, sectionVariant: 'plain' }`                                                                                             | Define as colunas, os ícones e o tratamento dos grupos; o Opus deriva a largura correspondente do diálogo.                                                                                                    |

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

@@ -225,7 +225,12 @@ caminho que passa por uma lista vale para cada item, e um campo intermediário `
 endereço, e o nome já vai como `title`. Um caminho que termina num objeto ou numa lista leva tudo o
 que está abaixo dele, inclusive campos acrescentados depois à saída; para conferir num teste o que
 cada caminho alcança, use `assistantContextLeaves`, de `@softize/opus/assistant-schema`, sobre o
-schema de saída do manifest. O `title` precisa apontar para texto ou número.
+schema de saída do manifest. Ela devolve, por caminho, as folhas em `leaves` e, em `open`, os pontos
+que a conferência não alcança e por onde qualquer campo pode passar: um campo sem forma declarada
+(`z.unknown()`, `z.any()`), uma estrutura recursiva, uma referência que não resolve e, como
+`<caminho>.*`, um objeto que aceita chaves não declaradas (`.passthrough()`). Num teste que reprova
+campo pessoal, trate também `open`: reprove cada ponto aberto ou justifique por que ele não leva dado
+pessoal. O `title` precisa apontar para texto ou número.
 
 O `opus check` cobra a forma da declaração (regra `assistant-declaration`), o `opus gen` recusa
 `title`, caminho de `context` ou entrada que não conferem com os schemas, e o registro recusa duas

package/src/ui/docs/content/floating-layer.md

@@ -38,7 +38,7 @@ function AssistantDemo() {
         </DialogContent>
       </Dialog>
       {editing && (
-        <FloatingLayer onEscapeKeyDown={() => setAssistant(false)}>
+        <FloatingLayer onEscapeKeyDown={assistant ? () => setAssistant(false) : undefined}>
           {assistant ? (
             <aside
               aria-label="Assistente"
@@ -126,6 +126,11 @@ não recebe foco, nenhum modal fecha e o Opus chama `onEscapeKeyDown` uma vez po
 no modal, o Esc fecha o modal, como sempre. Sem modal aberto, `onEscapeKeyDown` também é chamado
 quando a pessoa está na camada.
 
+Passe `onEscapeKeyDown` só enquanto a camada tiver o que fechar. Sem ele, o Esc com a pessoa na
+camada segue para o modal aberto, que fecha. É o que permite a quem chega ao botão do assistente
+pelo Tab sair do modal com o Esc. No exemplo acima, o handler só existe com o painel aberto: com o
+painel, o Esc fecha o painel; com o botão, fecha o formulário.
+
 Trate o Esc da camada só por `onEscapeKeyDown`. Para impedir que o modal feche, o Opus marca o evento
 com `preventDefault` antes de ele chegar aos elementos da camada; um `onKeyDown` próprio para Esc no
 painel trataria a tecla duas vezes ou leria um evento já marcado.
@@ -164,15 +169,17 @@ você.
 - O hospedeiro carrega `aria-live="off"`, o valor padrão do atributo: a camada não anuncia mudanças
   por conta própria, e regiões vivas de dentro dela, como a de um [`Ask`](/ui/ask), mantêm o próprio
   comportamento. O atributo é o que mantém a camada visível ao leitor de tela com um modal aberto.
-- O foco e o Tab descritos acima são verificados em Chromium por testes automatizados. Safari,
-  Firefox e a leitura com VoiceOver ainda não foram verificados: o roteiro manual da ADR 0052 roda
-  na adoção pela Grand Brasil, em Safari com VoiceOver e no Firefox, antes de ela chegar à versão
-  principal da plataforma. Leitores de tela do Windows, como o NVDA, ficam fora dessa verificação.
+- O foco, o Tab e o Esc descritos acima são verificados em Chromium por testes automatizados.
+  Safari, Firefox e a leitura com VoiceOver não foram verificados. Em 2026-10-05, na adoção pela
+  Grand Brasil, o dono do produto dispensou o roteiro manual da ADR 0052 para esses navegadores, e
+  ele não foi executado. Se surgir um problema de leitor de tela, de Safari ou de Firefox com a
+  camada sobre um modal, o roteiro volta a ser exigido. Leitores de tela do Windows, como o NVDA,
+  ficam fora dessa verificação.
 
 ## Propriedades de FloatingLayer
 
-| Propriedade       | Tipo                             | Padrão | Descrição                                                                                                                                            |
-| ----------------- | -------------------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `children`        | `ReactNode`                      |        | Elementos da camada. Cada filho direto recebe clique e se posiciona contra a janela.                                                                 |
-| `className`       | `string`                         |        | Classes do hospedeiro. A posição de cada filho continua sendo sua.                                                                                   |
-| `onEscapeKeyDown` | `(event: KeyboardEvent) => void` |        | Chamado uma vez por tecla quando a pessoa aperta Esc na camada, com ou sem modal aberto. Nenhum modal fecha nesse caso, e o Opus não fecha a camada. |
+| Propriedade       | Tipo                             | Padrão | Descrição                                                                                                                                                                                           |
+| ----------------- | -------------------------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `children`        | `ReactNode`                      |        | Elementos da camada. Cada filho direto recebe clique e se posiciona contra a janela.                                                                                                                |
+| `className`       | `string`                         |        | Classes do hospedeiro. A posição de cada filho continua sendo sua.                                                                                                                                  |
+| `onEscapeKeyDown` | `(event: KeyboardEvent) => void` |        | Chamado uma vez por tecla quando a pessoa aperta Esc na camada, com ou sem modal aberto. Nenhum modal fecha nesse caso, e o Opus não fecha a camada. Sem ele, o Esc na camada fecha o modal aberto. |

package/src/ui/drivers/react.tsx

@@ -47,6 +47,10 @@ export {
 } from './context.tsx'
 import { zodErrorMapPtBr } from '../lib/zod-pt-br.ts'
 import { objectSchemaShape } from '../lib/object-schema.ts'
+import {
+  useGroupedListQueries,
+  type ListActionGroup,
+} from '../components/patterns/grouped-list.ts'
 
 // =============================================================================
 // useAction
@@ -238,6 +242,32 @@ export function useListAction<TItem = unknown, TInput extends Record<string, unk
   }
 }
 
+/** Implementação interna do ActionList para executar recortes paginados 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')
+  return useGroupedListQueries<TItem, TInput>(
+    client,
+    action,
+    input,
+    field,
+    values,
+    multiple,
+    pages,
+    pageSize,
+  )
+}
+
 // =============================================================================
 // useFormAction
 // =============================================================================

package/src/ui/lib/modal-layers.ts

@@ -12,7 +12,8 @@ import * as React from "react";
  * - um único ouvinte no `body`, em borbulha, impede que `focusin`, `focusout`, `wheel` e `touchmove`
  *   ligados ao hospedeiro cheguem ao documento, onde a trava de foco do Radix e a trava de rolagem
  *   os veriam;
- * - o Esc age onde a pessoa está: na camada, chama o `onEscapeKeyDown` dela e não fecha o modal;
+ * - o Esc age onde a pessoa está: na camada que tem `onEscapeKeyDown`, chama esse handler e não
+ *   fecha o modal; na camada sem handler, segue para o modal, que fecha como sempre;
  * - o Tab passa do último elemento do modal para a camada e da camada de volta ao modal;
  * - quando o elemento focado da camada some, o foco volta ao modal;
  * - o hospedeiro carrega `aria-live="off"`, que faz o `hideOthers` do Radix preservá-lo.
@@ -37,9 +38,12 @@ interface ModalEntry {
   content: HTMLElement | null;
 }
 
+/** O `onEscapeKeyDown` corrente da camada; `undefined` quando ela não tem o que fechar. */
+export type LayerEscape = () => ((event: KeyboardEvent) => void) | undefined;
+
 interface LayerRecord {
   host: HTMLElement;
-  escape: (event: KeyboardEvent) => void;
+  escape: LayerEscape;
   dispose: () => void;
 }
 
@@ -328,7 +332,7 @@ function removeGlobalListeners(): void {
  */
 export function registerFloatingLayer(
   host: HTMLElement,
-  escape: (event: KeyboardEvent) => void,
+  escape: LayerEscape,
 ): () => void {
   const onPointerDown = (event: PointerEvent): void => {
     // Pertença decidida no aperto: no fim do clique, o elemento apertado pode já ter sumido.
@@ -354,7 +358,7 @@ export function registerFloatingLayer(
   const onDocumentKeyDown = (event: KeyboardEvent): void => {
     // Com um modal de trabalho aberto, a composição do modal já tratou o Esc e o marcou.
     if (event.key !== "Escape" || event.defaultPrevented) return;
-    if (layerWherePersonIs() === record) escape(event);
+    if (layerWherePersonIs() === record) escape()?.(event);
   };
   const observer = new MutationObserver(() => {
     if (pointerAnchor !== null && pointerAnchor.parentNode !== pointerLayer?.host) {
@@ -424,16 +428,20 @@ export function isLayerInteraction(event: {
 }
 
 /**
- * Esc no modal de trabalho do topo com a pessoa na camada: nenhum modal fecha e a camada recebe a
- * tecla uma única vez. O `preventDefault` impede o Radix de fechar e marca o evento para o ouvinte
- * da própria camada, que ignora eventos já tratados.
+ * Esc no modal de trabalho do topo com a pessoa numa camada que tem `onEscapeKeyDown`: nenhum modal
+ * fecha e a camada recebe a tecla uma única vez. O `preventDefault` impede o Radix de fechar e marca
+ * o evento para o ouvinte da própria camada, que ignora eventos já tratados.
+ *
+ * Numa camada sem handler, a camada não tem o que fechar, e o Esc segue para o modal (nota de
+ * 2026-10-05 na seção 5 da ADR 0052): engolir a tecla deixaria quem chega ao FAB pelo Tab sem
+ * nenhum efeito.
  */
 export function routeEscapeToLayer(event: KeyboardEvent): boolean {
   if (!layerExemptionsActive()) return false;
-  const layer = layerWherePersonIs();
-  if (layer === null) return false;
+  const escape = layerWherePersonIs()?.escape();
+  if (escape === undefined) return false;
   event.preventDefault();
-  layer.escape(event);
+  escape(event);
   return true;
 }
 

package/src/ui/react.tsx

@@ -5,7 +5,31 @@
  * `meta` de cada componente NÃO é re-exportado aqui de propósito — é metadado de
  * build-time (lido pelo manifesto/MCP da fonte), fora do bundle de runtime.
  */
-export * from "./drivers/react.tsx";
+export {
+  OpusProvider,
+  useAction,
+  useDicts,
+  useFormAction,
+  useListAction,
+  useLookupAction,
+  useTriggerAction,
+  useViewAction,
+} from "./drivers/react.tsx";
+export type {
+  ActionError,
+  ActionState,
+  DictLike,
+  ListState,
+  OpusProviderProps,
+  UseActionResult,
+  UseFormActionOptions,
+  UseFormActionResult,
+  UseListActionResult,
+  UseLookupActionResult,
+  UseTriggerActionOptions,
+  UseTriggerActionResult,
+  UseViewActionResult,
+} from "./drivers/react.tsx";
 
 // Utilitário
 export { cn } from "./lib/cn.ts";