@softize/opus 25.2.0 → 25.3.0

package/CHANGELOG.md

@@ -7,6 +7,23 @@ 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.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/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/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 = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softize/opus",
-  "version": "25.2.0",
+  "version": "25.3.0",
   "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()))
+      },
+    }
+  })
+}

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

@@ -38,6 +38,7 @@ import {
   Calendar as CalendarIcon,
   Check,
   ChevronDown,
+  ChevronRight,
   Eraser,
   Filter,
   RotateCw,
@@ -65,6 +66,7 @@ import {
   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";
@@ -82,6 +84,7 @@ import {
   PaginationPrevious,
 } from "../primitives/pagination.tsx";
 import { Button } from "../primitives/button.tsx";
+import { focusRing } from "../primitives/control.ts";
 import { ButtonGroup } from "../primitives/button-group.tsx";
 import { Calendar } from "../primitives/calendar.tsx";
 import { Checkbox } from "../primitives/checkbox.tsx";
@@ -205,6 +208,8 @@ export interface ActionListState {
   limit: number | null;
   /** Página atual (1-based). Mudar filtro/busca/sort/período volta pra 1. */
   page: number;
+  /** Dimensão ativa de agrupamento. null mantém a listagem plana. */
+  groupBy?: string | null;
 }
 
 /** Um estado vazio/default — útil pra montar o inicial em quem controla. */
@@ -220,6 +225,7 @@ export function emptyListState(): ActionListState {
     columns: null,
     limit: null,
     page: 1,
+    groupBy: null,
   };
 }
 
@@ -270,6 +276,7 @@ export interface ListActionLike {
   sort?: { fields: string[]; default?: SortSpec[] } | undefined;
   text?: { fields: string[]; placeholder?: unknown } | undefined;
   periods?: PeriodSpec[] | undefined;
+  grouping?: { fields: string[] } | undefined;
 }
 
 /** Estado compartilhado pelos filtros declarativos, independente da listagem. */
@@ -1750,6 +1757,7 @@ export function ActionList<TInput, TItem>({
   onStateChange,
 }: ActionListProps<TInput, TItem>) {
   const confirmBodyId = useId();
+  const groupRegionId = useId();
   const { layout, ref: rootRef } = useFillLeaf<HTMLDivElement>(layoutProp);
   // Query-backed (useListAction): busca declarativa por [name, input] E refetch
   // automático quando um form/trigger invalida a action (`invalidates: ['x.list']`).
@@ -1778,6 +1786,7 @@ export function ActionList<TInput, TItem>({
     columns: raw.columns ?? null,
     limit: raw.limit ?? null,
     page: raw.page ?? 1,
+    groupBy: raw.groupBy ?? null,
   };
   const setState = (next: ActionListState): void => {
     if (onStateChange !== undefined) onStateChange(next);
@@ -1804,6 +1813,34 @@ export function ActionList<TInput, TItem>({
     ),
   ];
   const activeView = state.view ?? viewEntries[0]?.[0] ?? "table";
+  const groupingFields = action.grouping?.fields ?? [];
+  const dicts = useDicts();
+  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;
+    const options = [
+      ...optionsFor(field, spec, filterOptions),
+      ...dictOptionsFor(spec, dicts),
+    ].filter(
+      (option, index, all) =>
+        all.findIndex((candidate) => candidate.value === option.value) ===
+        index,
+    );
+    return options.length > 0 && options.length <= 12;
+  });
+  const requestedGroupBy = state.groupBy ?? null;
+  const activeGroupBy =
+    children === undefined &&
+    activeView === "table" &&
+    requestedGroupBy !== null &&
+    availableGroupingFields.includes(requestedGroupBy)
+      ? requestedGroupBy
+      : null;
   const hasSegment = children === undefined && viewEntries.length > 1;
   const periods = action.periods ?? [];
   const hasToolbar =
@@ -1860,16 +1897,109 @@ export function ActionList<TInput, TItem>({
     } as TInput;
   }, [input, state, pageSize, filterDefaults]);
 
-  const inputKey = JSON.stringify(effectiveInput);
-  const { items, total, isLoading, isFetching, isError, error, refetch } =
-    useListAction<TItem, Record<string, unknown>>(
-      action as unknown as { name: string; kind: "list" },
-      effectiveInput as Record<string, unknown>,
+  const inputKey = JSON.stringify([effectiveInput, activeGroupBy]);
+  const groupSpec =
+    activeGroupBy === null ? undefined : action.filters?.[activeGroupBy];
+  const declaredGroupOptions =
+    groupSpec === undefined
+      ? []
+      : [
+          ...optionsFor(activeGroupBy ?? "", groupSpec, filterOptions),
+          ...dictOptionsFor(groupSpec, dicts),
+        ].filter(
+          (option, index, all) =>
+            all.findIndex((candidate) => candidate.value === option.value) ===
+            index,
+        );
+  const selectedGroupFilter =
+    activeGroupBy === null
+      ? undefined
+      : (state.filters[activeGroupBy] ?? filterDefaults?.[activeGroupBy]);
+  const groupOptions = declaredGroupOptions.filter((option) =>
+    Array.isArray(selectedGroupFilter) && selectedGroupFilter.length > 0
+      ? selectedGroupFilter.includes(option.value)
+      : typeof selectedGroupFilter === "string" && selectedGroupFilter !== ""
+        ? selectedGroupFilter === option.value
+        : true,
+  );
+  const [groupPaging, setGroupPaging] = useState<{
+    key: string;
+    pages: Record<string, number>;
+  }>({ key: "", pages: {} });
+  const groupPages = groupPaging.key === inputKey ? groupPaging.pages : {};
+  const [groupCollapse, setGroupCollapse] = useState<{
+    key: string;
+    values: Set<string>;
+  }>({ key: "", values: new Set() });
+  const collapsedGroups =
+    groupCollapse.key === inputKey ? groupCollapse.values : new Set<string>();
+  const flat = useListAction<TItem, Record<string, unknown>>(
+    action as unknown as { name: string; kind: "list" },
+    effectiveInput as Record<string, unknown>,
+    { enabled: activeGroupBy === null },
+  );
+  const grouped = useGroupedListAction<TItem, Record<string, unknown>>(
+    action as unknown as { name: string; kind: "list" },
+    effectiveInput as Record<string, unknown>,
+    activeGroupBy,
+    groupOptions.map((option) => option.value),
+    groupSpec?.multiple === true,
+    groupPages,
+    state.limit ?? pageSize,
+  );
+  const items =
+    activeGroupBy === null
+      ? flat.items
+      : grouped.flatMap((group) => group.items);
+  const visibleItems =
+    activeGroupBy === null
+      ? items
+      : grouped
+          .filter((group) => !collapsedGroups.has(group.value))
+          .flatMap((group) => group.items);
+  const total =
+    activeGroupBy === null
+      ? flat.total
+      : grouped.every((group) => group.total !== undefined)
+        ? grouped.reduce((sum, group) => sum + (group.total ?? 0), 0)
+        : undefined;
+  const isLoading =
+    activeGroupBy === null
+      ? flat.isLoading
+      : grouped.length > 0 && grouped.some((group) => group.isLoading);
+  const isFetching =
+    activeGroupBy === null
+      ? flat.isFetching
+      : grouped.some((group) => group.isFetching);
+  const missingGroupTotal =
+    activeGroupBy !== null &&
+    grouped.some(
+      (group) =>
+        !group.isLoading && !group.isError && group.total === undefined,
     );
+  const isError =
+    activeGroupBy === null
+      ? flat.isError
+      : missingGroupTotal || grouped.some((group) => group.isError);
+  const error =
+    activeGroupBy === null
+      ? flat.error
+      : missingGroupTotal
+        ? {
+            code: "action_list.grouping_total_missing",
+            category: "internal" as const,
+            message: "Não foi possível carregar os grupos desta lista.",
+            severity: "error" as const,
+            retriable: false,
+          }
+        : grouped.find((group) => group.error !== undefined)?.error;
+  const refetch = async (): Promise<void> => {
+    if (activeGroupBy === null) return flat.refetch();
+    await Promise.all(grouped.map((group) => group.refetch()));
+  };
   // — Colunas: prop explícita > derivadas do contrato (+ células custom). O column
   //   picker (state.columns) escolhe o subconjunto visível; null = o default (!hidden).
   const visibleKeys = state.columns;
-  const dicts = useDicts();
   const derived: Array<ActionListColumn<TItem> & { spec?: ListColumnSpec }> =
     useMemo(() => {
       if (columns !== undefined) return columns;
@@ -1972,7 +2102,7 @@ export function ActionList<TInput, TItem>({
   const selectable = (item: TItem): boolean =>
     batchActions.some((a) => a.can?.(item) ?? true);
   const selectableItems =
-    batchActions.length > 0 ? items.filter(selectable) : [];
+    batchActions.length > 0 ? visibleItems.filter(selectable) : [];
   const hasSelection =
     batchActions.length > 0 &&
     selectableItems.length > 0 &&
@@ -1981,7 +2111,7 @@ export function ActionList<TInput, TItem>({
     // Página/recorte novo → seleção limpa (os ids podem nem estar mais na tela).
     setSelected(new Set());
   }, [inputKey]);
-  const selectedItems = items.filter((it) => selected.has(rowId(it)));
+  const selectedItems = visibleItems.filter((it) => selected.has(rowId(it)));
   const eligibleFor = (a: ActionListBatchAction<TItem>): TItem[] =>
     selectedItems.filter((it) => a.can?.(it) ?? true);
   const runBatch = async (a: ActionListBatchAction<TItem>): Promise<void> => {
@@ -2065,6 +2195,41 @@ export function ActionList<TInput, TItem>({
                 data-slot="action-list-display"
               >
                 <div className="space-y-3">
+                  {children === undefined &&
+                    activeView === "table" &&
+                    availableGroupingFields.length > 0 && (
+                      <>
+                        <div className="space-y-2">
+                          <span className="text-xs font-medium text-muted-foreground">
+                            Agrupar por
+                          </span>
+                          <Select
+                            aria-label="Agrupar por"
+                            size="sm"
+                            className="w-full"
+                            value={activeGroupBy ?? "__none__"}
+                            onChange={(value) =>
+                              setState({
+                                ...state,
+                                groupBy: value === "__none__" ? null : value,
+                                page: 1,
+                              })
+                            }
+                            options={[
+                              { value: "__none__", label: "Sem agrupamento" },
+                              ...availableGroupingFields.map((field) => ({
+                                value: field,
+                                label: text(
+                                  action.filters?.[field]?.label,
+                                  field,
+                                ),
+                              })),
+                            ]}
+                          />
+                        </div>
+                        <Separator />
+                      </>
+                    )}
                   {activeView === "table" && pickerColumns.length > 0 && (
                     <>
                       <div className="space-y-2">
@@ -2107,7 +2272,9 @@ export function ActionList<TInput, TItem>({
                   )}
                   <div className="space-y-2">
                     <span className="text-xs font-medium text-muted-foreground">
-                      Itens por página
+                      {activeGroupBy === null
+                        ? "Itens por página"
+                        : "Itens por grupo"}
                     </span>
                     <Select
                       size="sm"
@@ -2152,43 +2319,54 @@ export function ActionList<TInput, TItem>({
       (hasSelection ? 1 : 0) +
       (rowActions !== undefined ? 1 : 0),
   );
-  const tableRows = items.map((item, idx) => (
-    <TableRow
-      // eslint-disable-next-line react/no-array-index-key
-      key={idx}
-      className={onRowClick !== undefined ? "cursor-pointer" : undefined}
-      onClick={onRowClick !== undefined ? () => onRowClick(item) : undefined}
-    >
-      {hasSelection && (
-        <TableCell className="w-px" onClick={(e) => e.stopPropagation()}>
-          <Checkbox
-            aria-label="Selecionar linha"
-            disabled={!selectable(item)}
-            checked={selected.has(rowId(item))}
-            onCheckedChange={(v) => {
-              const next = new Set(selected);
-              if (v === true) next.add(rowId(item));
-              else next.delete(rowId(item));
-              setSelected(next);
-            }}
-          />
-        </TableCell>
-      )}
-      {derived.map((col) => (
-        <TableCell key={col.key} className={col.className}>
-          {col.cell(item)}
-        </TableCell>
-      ))}
-      {rowActions !== undefined && (
-        <TableCell
-          className="w-px whitespace-nowrap text-right"
-          onClick={(e) => e.stopPropagation()}
-        >
-          <RowActions>{rowActions(item)}</RowActions>
-        </TableCell>
-      )}
-    </TableRow>
-  ));
+  const renderTableRows = (
+    rows: TItem[],
+    options?: { hidden?: boolean; idPrefix?: string },
+  ) =>
+    rows.map((item, idx) => (
+      <TableRow
+        // eslint-disable-next-line react/no-array-index-key
+        key={idx}
+        id={
+          options?.idPrefix === undefined
+            ? undefined
+            : `${options.idPrefix}-${idx}`
+        }
+        hidden={options?.hidden}
+        className={onRowClick !== undefined ? "cursor-pointer" : undefined}
+        onClick={onRowClick !== undefined ? () => onRowClick(item) : undefined}
+      >
+        {hasSelection && (
+          <TableCell className="w-px" onClick={(e) => e.stopPropagation()}>
+            <Checkbox
+              aria-label="Selecionar linha"
+              disabled={!selectable(item)}
+              checked={selected.has(rowId(item))}
+              onCheckedChange={(v) => {
+                const next = new Set(selected);
+                if (v === true) next.add(rowId(item));
+                else next.delete(rowId(item));
+                setSelected(next);
+              }}
+            />
+          </TableCell>
+        )}
+        {derived.map((col) => (
+          <TableCell key={col.key} className={col.className}>
+            {col.cell(item)}
+          </TableCell>
+        ))}
+        {rowActions !== undefined && (
+          <TableCell
+            className="w-px whitespace-nowrap text-right"
+            onClick={(e) => e.stopPropagation()}
+          >
+            <RowActions>{rowActions(item)}</RowActions>
+          </TableCell>
+        )}
+      </TableRow>
+    ));
+  const tableRows = renderTableRows(items);
   let content: ReactNode;
   if (children !== undefined) {
     // Modo COMPOSIÇÃO: o layout é de quem compõe; a toolbar e os estados seguem daqui.
@@ -2263,14 +2441,33 @@ export function ActionList<TInput, TItem>({
             {rowActions !== undefined && <TableHead className="w-px" />}
           </TableRow>
         </TableHeader>
-        <TableBody
-          className={
-            tableStateActive
-              ? "h-full [&_[data-slot=data-state]]:h-full"
-              : undefined
-          }
-        >
-          {tableFillsAvailableHeight ? (
+        {activeGroupBy === null ? (
+          <TableBody
+            className={
+              tableStateActive
+                ? "h-full [&_[data-slot=data-state]]:h-full"
+                : undefined
+            }
+          >
+            {tableFillsAvailableHeight ? (
+              <DataState
+                loading={initialLoading}
+                error={isError ? error : null}
+                empty={isEmpty}
+                emptyMessage={emptyMessage}
+                {...(errorMessage !== undefined ? { errorMessage } : {})}
+                {...(retryLabel !== undefined ? { retryLabel } : {})}
+                onRetry={() => refetch()}
+                colSpan={tableColumnCount}
+              >
+                {tableRows}
+              </DataState>
+            ) : (
+              tableRows
+            )}
+          </TableBody>
+        ) : tableFillsAvailableHeight && tableStateActive ? (
+          <TableBody className="h-full [&_[data-slot=data-state]]:h-full">
             <DataState
               loading={initialLoading}
               error={isError ? error : null}
@@ -2281,12 +2478,127 @@ export function ActionList<TInput, TItem>({
               onRetry={() => refetch()}
               colSpan={tableColumnCount}
             >
-              {tableRows}
+              {null}
             </DataState>
-          ) : (
-            tableRows
-          )}
-        </TableBody>
+          </TableBody>
+        ) : (
+          grouped.map((group, groupIndex) => {
+            const option = groupOptions.find(
+              (candidate) => candidate.value === group.value,
+            );
+            const collapsed = collapsedGroups.has(group.value);
+            const loadedPages = groupPages[group.value] ?? 1;
+            const canLoadMore =
+              group.total !== undefined && group.items.length < group.total;
+            const groupLabel = option?.label ?? group.value;
+            const groupId = `${groupRegionId}-${groupIndex}-${group.value.replace(
+              /[^a-zA-Z0-9_-]/g,
+              "-",
+            )}`;
+            const bodyId = `${groupId}-body`;
+            const controlledIds = [
+              ...group.items.map((_, index) => `${bodyId}-${index}`),
+              ...(canLoadMore ? [`${bodyId}-load-more`] : []),
+            ];
+            return (
+              <TableBody
+                key={group.value}
+                data-group={group.value}
+                aria-labelledby={`${groupId}-label`}
+              >
+                <TableRow className="!bg-muted/40 hover:!bg-muted/60">
+                  <TableHead
+                    id={`${groupId}-label`}
+                    scope="rowgroup"
+                    colSpan={tableColumnCount}
+                    className="h-auto py-1.5 text-foreground"
+                  >
+                    <button
+                      type="button"
+                      aria-expanded={!collapsed}
+                      aria-controls={
+                        controlledIds.length > 0
+                          ? controlledIds.join(" ")
+                          : undefined
+                      }
+                      aria-label={`${groupLabel}, ${
+                        group.total === undefined
+                          ? "carregando"
+                          : `${group.total} ${group.total === 1 ? "item" : "itens"}`
+                      }`}
+                      className={cn(
+                        "flex w-full items-center gap-2 rounded-sm text-left font-medium outline-none",
+                        focusRing,
+                      )}
+                      onClick={() => {
+                        const next = new Set(collapsedGroups);
+                        if (collapsed) next.delete(group.value);
+                        else {
+                          next.add(group.value);
+                          const hidden = new Set(group.items.map(rowId));
+                          setSelected(
+                            new Set(
+                              [...selected].filter((id) => !hidden.has(id)),
+                            ),
+                          );
+                        }
+                        setGroupCollapse({ key: inputKey, values: next });
+                      }}
+                    >
+                      {collapsed ? (
+                        <ChevronRight className="size-4" />
+                      ) : (
+                        <ChevronDown className="size-4" />
+                      )}
+                      <span className="flex items-center gap-1.5">
+                        {option?.content ?? option?.label ?? group.value}
+                      </span>
+                      <span className="text-muted-foreground">
+                        {group.total ?? "…"}
+                      </span>
+                    </button>
+                  </TableHead>
+                </TableRow>
+                {renderTableRows(group.items, {
+                  hidden: collapsed,
+                  idPrefix: bodyId,
+                })}
+                {canLoadMore && (
+                  <TableRow
+                    id={`${bodyId}-load-more`}
+                    hidden={collapsed}
+                    className="hover:bg-transparent"
+                  >
+                    <TableCell
+                      colSpan={tableColumnCount}
+                      className="text-center"
+                    >
+                      <Button
+                        size="sm"
+                        variant="ghost"
+                        aria-label={`Carregar mais de ${groupLabel}`}
+                        busy={group.isFetching}
+                        onClick={() =>
+                          setGroupPaging((current) => ({
+                            key: inputKey,
+                            pages: {
+                              ...(current.key === inputKey
+                                ? current.pages
+                                : {}),
+                              [group.value]: loadedPages + 1,
+                            },
+                          }))
+                        }
+                      >
+                        Carregar mais
+                      </Button>
+                    </TableCell>
+                  </TableRow>
+                )}
+              </TableBody>
+            );
+          })
+        )}
       </Table>
     );
   }
@@ -2365,7 +2677,14 @@ export function ActionList<TInput, TItem>({
       : 1;
   const goTo = (page: number): void => setState({ ...state, page });
   const footer =
-    total !== undefined && !isError ? (
+    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"
+      >
+        {total} {total === 1 ? "item" : "itens"} no total
+      </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"
@@ -2459,7 +2778,9 @@ export function ActionList<TInput, TItem>({
               className={cn(
                 "min-h-0",
                 layout === "fill" && "overflow-auto",
-                busy && items.length > 0 && "pointer-events-none opacity-60",
+                busy &&
+                  items.length > 0 &&
+                  "pointer-events-none opacity-60",
               )}
             >
               {body}
@@ -2568,6 +2889,11 @@ export function listParamsToState(
   const periodParam = params.get("period");
   const range =
     periodParam?.match(/^(\d{4}-\d{2}-\d{2})\.\.(\d{4}-\d{2}-\d{2})$/) ?? null;
+  const groupParam = params.get("group");
+  const groupBy =
+    groupParam !== null && (action.grouping?.fields ?? []).includes(groupParam)
+      ? groupParam
+      : null;
   return {
     q: params.get("q") ?? "",
     sort,
@@ -2579,6 +2905,7 @@ export function listParamsToState(
     columns: cols !== null && cols !== "" ? cols.split(",") : null,
     limit: Number.isInteger(limitParam) && limitParam > 0 ? limitParam : null,
     page: Number.isInteger(page) && page > 1 ? page : 1,
+    groupBy,
   };
 }
 
@@ -2622,6 +2949,13 @@ export function listStateToParams(
   if (state.columns !== null) qs.set("cols", state.columns.join(","));
   if (state.limit !== null) qs.set("limit", String(state.limit));
   if (state.page > 1) qs.set("page", String(state.page));
+  if (
+    state.groupBy !== undefined &&
+    state.groupBy !== null &&
+    (action.grouping?.fields ?? []).includes(state.groupBy)
+  ) {
+    qs.set("group", state.groupBy);
+  }
   const s = qs.toString();
   return s === "" ? "" : `?${s}`;
 }

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