@softize/opus 25.2.0 → 25.3.1

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

@@ -215,6 +215,37 @@ periods: [
 // presetRange('last7') → { from: 'YYYY-MM-DD', to: 'YYYY-MM-DD' } — o mesmo cálculo do pattern.
 ```
 
+## 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**.
+
+```ts
+filters: {
+  status: {
+    label: 'Status',
+    type: 'select',
+    options: { kind: 'dictionary', ref: 'workspace.status' },
+  },
+},
+grouping: { fields: ['status'] },
+paginate: 'offset',
+```
+
+O Opus consulta a mesma `ListAction` uma vez para cada opção, aplicando o valor ao filtro e
+preservando busca, período, demais filtros e ordenação. Por isso, o handler precisa devolver
+`total` e a action precisa usar `paginate: 'offset'`: o cabeçalho recolhível apresenta a contagem
+autoritativa, e **Carregar mais** expande apenas aquele grupo. A soma aparece no rodapé, sem paginador
+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**.
+
+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.
+
 ## Paginação e carregamento
 
 `ActionList` envia `limit`, definido por `pageSize`, e `page` no input. O handler aplica o recorte e
@@ -481,21 +512,23 @@ render(
 
 ## Declaração na ListAction
 
-| Chave     | O que declara                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
-| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `columns` | `{ key, label, type?, sortable?, fit?, hidden?, dateFormat?, dictionary?, empty? }` — a tabela. `hidden` nasce oculta e pode ser exibida pelo seletor de colunas; `dictionary` nomeia o dicionário do provider; `empty` dá o significado da ausência.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
-| `filters` | `{ [nome]: { label, type, options?, multiple?, presentation?, searchable?, allowEmpty?, placement?, section?, depends?, … } }` — a toolbar. `placement` classifica o controle como `inline`, `advanced` ou `external`; filtros avançados com `section` são agrupados no diálogo; `external` mantém estado e input, mas delega a apresentação ao consumidor. `presentation: 'toggle'` mostra todas as opções curtas de um `select` de escolha única em um `ToggleGroup`; sem a propriedade, o controle continua sendo `Select`. `searchable` habilita busca local em `select`; `allowEmpty: false` omite a opção vazia. `depends` desabilita/cascateia; options `kind: 'lookup'` busca em uma action. Valor aplicado entra no input com o mesmo nome. |
-| `text`    | `{ fields }` — liga a busca; convenção: param `q` no input. 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.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| Chave      | O que declara                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `columns`  | `{ key, label, type?, sortable?, fit?, hidden?, dateFormat?, dictionary?, empty? }` — a tabela. `hidden` nasce oculta e pode ser exibida pelo seletor de colunas; `dictionary` nomeia o dicionário do provider; `empty` dá o significado da ausência.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `filters`  | `{ [nome]: { label, type, options?, multiple?, presentation?, searchable?, allowEmpty?, placement?, section?, depends?, … } }` — a toolbar. `placement` classifica o controle como `inline`, `advanced` ou `external`; filtros avançados com `section` são agrupados no diálogo; `external` mantém estado e input, mas delega a apresentação ao consumidor. `presentation: 'toggle'` mostra todas as opções curtas de um `select` de escolha única em um `ToggleGroup`; sem a propriedade, o controle continua sendo `Select`. `searchable` habilita busca local em `select`; `allowEmpty: false` omite a opção vazia. `depends` desabilita/cascateia; options `kind: 'lookup'` busca em uma action. Valor aplicado entra no input com o mesmo nome. |
+| `text`     | `{ fields }` — liga a busca; convenção: param `q` no input. 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.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
 
 ## useListAction
 
-Quando o layout não cabe no `ActionList`, `useListAction(action, input)` entrega o mesmo fetch
+Quando o layout não cabe no `ActionList`, `useListAction(action, input, options?)` entrega o mesmo fetch
 declarativo (`items`, `total`, `error`, `isLoading`, `isFetching`, `refetch`) sob o
 `QueryClientProvider`, e `presetRange(preset)` materializa os presets de período (`today`, `last7`,
 `thisMonth`…) em `{ from, to }` no formato `YYYY-MM-DD` — o mesmo cálculo que o pattern faz antes de
-chamar a action.
+chamar a action. `options.enabled` suspende a consulta enquanto for `false`; sem a opção, vale
+`true`.
 
 ## Propriedades de ActionList
 

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/context.tsx

@@ -0,0 +1,50 @@
+import { createContext, useContext, useMemo, type ReactNode } from 'react'
+import type { ClientAdapter } from '../../core/index.ts'
+
+/**
+ * Dicionário estrutural pro resolvedor de opções: qualquer coisa com `options()`
+ * satisfaz o contrato sem este driver importar o driver de schema.
+ */
+export interface DictLike {
+  options(): Array<{ value: string; label: string; icon?: string }>
+}
+
+interface OpusContextValue {
+  client: ClientAdapter
+  dicts: Record<string, DictLike>
+}
+
+const OpusContext = createContext<OpusContextValue | null>(null)
+
+export interface OpusProviderProps {
+  client: ClientAdapter
+  /** Dicionários por ref usados por filtros e campos declarativos. */
+  dicts?: Record<string, DictLike>
+  children: ReactNode
+}
+
+export function OpusProvider({ client, dicts, children }: OpusProviderProps): ReactNode {
+  const value = useMemo<OpusContextValue>(() => ({ client, dicts: dicts ?? {} }), [client, dicts])
+  return <OpusContext.Provider value={value}>{children}</OpusContext.Provider>
+}
+
+/** Acesso interno ao adapter; não é reexportado por `@softize/opus/ui/react`. */
+export function useClient(hook: string): ClientAdapter {
+  const ctx = useContext(OpusContext)
+  if (ctx === null) {
+    throw new Error(
+      `${hook} foi chamado fora de um <OpusProvider> e não tem como executar a action. ` +
+        'Os hooks de action e os componentes que os usam, como ActionForm, ActionList e ActionView, ' +
+        'precisam de um <OpusProvider client={...}> acima deles na árvore. Envolva a aplicação no provider; ' +
+        'em testes e previews, envolva o componente renderizado.',
+    )
+  }
+  return ctx.client
+}
+
+const NO_DICTS: Record<string, DictLike> = {}
+
+/** Dicionários do provider; fora dele, o resolvedor usa os fallbacks do contrato. */
+export function useDicts(): Record<string, DictLike> {
+  return useContext(OpusContext)?.dicts ?? NO_DICTS
+}

package/src/ui/drivers/react.tsx

@@ -12,12 +12,9 @@
  */
 
 import {
-  createContext,
   useCallback,
-  useContext,
   useMemo,
   useState,
-  type ReactNode,
 } from 'react'
 import {
   useForm,
@@ -32,7 +29,6 @@ import type {
   ActionContract,
   ActionDef,
   ActionError,
-  ClientAdapter,
   FormContract,
   Paginated,
 } from '../../core/index.ts'
@@ -42,74 +38,16 @@ import {
   idleAction,
   idleLookup,
 } from '../index.ts'
+import { useClient } from './context.tsx'
+export {
+  OpusProvider,
+  useDicts,
+  type DictLike,
+  type OpusProviderProps,
+} from './context.tsx'
 import { zodErrorMapPtBr } from '../lib/zod-pt-br.ts'
 import { objectSchemaShape } from '../lib/object-schema.ts'
 
-// =============================================================================
-// Provider
-// =============================================================================
-
-/**
- * Dicionário estrutural pro resolvedor de `options: { kind: 'dictionary', ref }`:
- * qualquer coisa com `options()` → `{ value, label, icon? }`. O `DictType` do `t.dict`
- * satisfaz direto — sem este driver importar o driver de schema. A metadata opcional
- * continua sendo declarada pelo dicionário; o provider não inventa apresentação.
- */
-export interface DictLike {
-  options(): Array<{ value: string; label: string; icon?: string }>
-}
-
-interface OpusContextValue {
-  client: ClientAdapter
-  dicts: Record<string, DictLike>
-}
-
-const OpusContext = createContext<OpusContextValue | null>(null)
-
-export interface OpusProviderProps {
-  client: ClientAdapter
-  /** Dicionários por ref — resolvem `options: { kind: 'dictionary', ref }` de
-   *  filters/fields (ActionList/ActionForm). Campo de dict sem registro aqui ainda
-   *  resolve pelo fallback (a meta do `t.dict` viaja no schema do contrato). */
-  dicts?: Record<string, DictLike>
-  children: ReactNode
-}
-
-export function OpusProvider({
-  client,
-  dicts,
-  children,
-}: OpusProviderProps): ReactNode {
-  const value = useMemo<OpusContextValue>(() => ({ client, dicts: dicts ?? {} }), [client, dicts])
-  return <OpusContext.Provider value={value}>{children}</OpusContext.Provider>
-}
-
-/**
- * O adapter do provider. `hook` nomeia quem chamou, para a mensagem apontar o hook que a
- * pessoa vê no stack — muitas vezes chamado por dentro de ActionForm, ActionList ou
- * ActionView, e não diretamente pela tela.
- */
-function useClient(hook: string): ClientAdapter {
-  const ctx = useContext(OpusContext)
-  if (ctx === null) {
-    throw new Error(
-      `${hook} foi chamado fora de um <OpusProvider> e não tem como executar a action. ` +
-        'Os hooks de action e os componentes que os usam, como ActionForm, ActionList e ActionView, ' +
-        'precisam de um <OpusProvider client={...}> acima deles na árvore. Envolva a aplicação no provider; ' +
-        'em testes e previews, envolva o componente renderizado.',
-    )
-  }
-  return ctx.client
-}
-
-const NO_DICTS: Record<string, DictLike> = {}
-
-/** Dicts do provider. Default {} — inclusive fora do provider: o resolvedor cai
- *  nos fallbacks (estáticas do spec, meta do `t.dict`) sem exigir registry. */
-export function useDicts(): Record<string, DictLike> {
-  return useContext(OpusContext)?.dicts ?? NO_DICTS
-}
-
 // =============================================================================
 // useAction
 // =============================================================================
@@ -265,6 +203,7 @@ export interface UseListActionResult<TItem> {
 export function useListAction<TItem = unknown, TInput extends Record<string, unknown> = Record<string, unknown>>(
   action: { name: string; kind: 'list' },
   input?: TInput,
+  options?: { enabled?: boolean },
 ): UseListActionResult<TItem> {
   const client = useClient('useListAction')
 
@@ -278,6 +217,7 @@ export function useListAction<TItem = unknown, TInput extends Record<string, unk
     // Input mudou (filtro/página) → mantém os itens na tela enquanto busca: o
     // ActionList esmaece em vez de piscar skeleton. isPending = só o 1º load.
     placeholderData: keepPreviousData,
+    enabled: options?.enabled ?? true,
   })
 
   const refetch = useCallback(async () => {

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/meta.ts

@@ -388,7 +388,7 @@ export const componentMeta = {
     name: "action-list",
     ancestry: "opus",
     whenToUse:
-      "Apresente uma coleção pesquisável a partir de uma ListAction. O contrato declara colunas, filtros, período e busca; ActionList coordena visualizações, paginação, seleção em lote e sincronização com a URL. A tabela derivada não cria moldura própria. Em uma página, envolva a lista com Surface para manter título e criação junto da coleção. Para um único recurso, use ActionView.",
+      "Apresente uma coleção pesquisável a partir de uma ListAction. O contrato declara colunas, filtros, período, busca e dimensões fechadas de agrupamento; ActionList coordena visualizações, paginação, seleção em lote e sincronização com a URL. A tabela derivada não cria moldura própria. Em uma página, envolva a lista com Surface para manter título e criação junto da coleção. Para um único recurso, use ActionView.",
   },
   "action-trigger": {
     name: "action-trigger",