@softize/opus 25.3.1 → 25.4.1

package/CHANGELOG.md

@@ -7,6 +7,34 @@ Depois de qualquer bump, rode os gates (`typecheck` · `test` · `opus check` ·
 `opus copy --check` · `base copy check` · `manifest:check`) — eles apontam o que a
 mudança cobra do seu código.
 
+## 25.4.1 — 2026-10-05
+
+Corrige a busca remota de filtros `lookup` quando a `ActionList` também recebe opções iniciais em
+`filterOptions`, como nas dimensões disponíveis para agrupamento. Enquanto há um termo de busca, as
+opções iniciais agora são filtradas localmente e combinadas com o resultado do servidor; antes,
+elas permaneciam todas visíveis e podiam esconder o efeito da busca. Não há migração para o
+consumidor. Valores já selecionados preservam o rótulo durante e depois da busca, inclusive quando
+a opção veio apenas do servidor. Fechar o seletor limpa o termo também no lookup remoto. No
+`Select` com `onSearch`, esse reset é comunicado imediatamente com `""` apenas quando uma busca não
+vazia chegou a ser enviada; abrir e fechar sem digitar não repete a consulta inicial. Respostas
+remotas fora de ordem não substituem mais o resultado da consulta mais recente.
+
+## 25.4.0 — 2026-10-05
+
+`ListAction.grouping.fields` passa a aceitar filtros `select` ou `lookup` cujas opções completas
+sejam fornecidas em runtime por `ActionList.filterOptions`. A dimensão só aparece em **Agrupar por**
+com 1 a 12 opções; catálogo ausente, vazio ou maior mantém a lista plana, sem agrupar uma amostra.
+A ADR 0055 registra essa extensão da decisão original.
+
+As preferências de ordenação passam para **Exibição**, com a direção como ação dentro do próprio
+campo. O botão sinaliza quando ordenação, agrupamento, colunas ou quantidade por página diferem do
+padrão, e o rodapé explicita **Agrupado por** e **Ordenado por** quando aplicáveis.
+
+Também corrige a `ActionList` agrupada em aplicações Vite que consomem o código-fonte TypeScript do
+Opus. Ao ativar um agrupamento, a lista podia deixar de reconhecer o `OpusProvider` já presente na
+aplicação e interromper a renderização. O agrupamento agora usa o mesmo driver React dos demais
+hooks de action. Não há migração para o consumidor.
+
 ## 25.3.1 — 2026-10-05
 
 Com um `Dialog` ou `Drawer` aberto e a pessoa numa `FloatingLayer` sem `onEscapeKeyDown`, o Esc

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

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

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

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

package/docs/protocol.md

@@ -207,9 +207,11 @@ type OptionsSpec =
 **`search`**
 - `filters?: Record<string, FilterSpec>` — filtros disponíveis (chave é nome).
 - `sort?`, `paginate?`, `text?`, `periods?`, `grouping?` — ver tipos abaixo.
-- `grouping.fields` referencia filtros `select` com opções fechadas (`static` ou
-  `dictionary`). A interface consulta cada valor como um recorte da mesma action; não agrupa só a
-  página carregada.
+- `grouping.fields` referencia filtros enumeráveis `select` ou `lookup`. Opções estáticas e de
+  dicionário podem vir da declaração/provider; catálogos administráveis vêm de `filterOptions` no
+  consumidor. A interface só oferece dimensões com 1 a 12 opções completas e consulta cada valor
+  como um recorte da mesma action; não agrupa só a página carregada nem resultados parciais de uma
+  busca.
 
 ```ts
 type FilterSpec = {

package/package.json

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

package/src/core/list-grouping.ts

@@ -3,7 +3,7 @@ import type { ListAction } from './types.ts'
 const MAX_GROUP_OPTIONS = 12
 
 /** Valida a parte estrutural de `ListAction.grouping` no momento da declaração.
- *  Dicionários são resolvidos pelo provider e têm a cardinalidade conferida pela UI. */
+ *  Dicionários e opções resolvidas em runtime têm a cardinalidade conferida pela UI. */
 export function assertValidListGrouping(
   action: Pick<ListAction<unknown, unknown>, 'name' | 'filters' | 'grouping' | 'paginate'>,
 ): void {
@@ -26,14 +26,14 @@ export function assertValidListGrouping(
     if (filter === undefined) {
       throw new Error(`A action "${action.name}" agrupa por "${field}", mas esse filtro não existe.`)
     }
-    if (filter.type !== 'select' || (filter.options?.kind !== 'static' && filter.options?.kind !== 'dictionary')) {
+    if (filter.type !== 'select' && filter.type !== 'lookup') {
       throw new Error(
         `A action "${action.name}" agrupa por "${field}", mas a dimensão precisa ser ` +
-          'um filtro select com opções static ou dictionary.',
+          'um filtro select ou lookup com opções enumeráveis.',
       )
     }
     if (
-      filter.options.kind === 'static' &&
+      filter.options?.kind === 'static' &&
       (filter.options.items.length === 0 || filter.options.items.length > MAX_GROUP_OPTIONS)
     ) {
       throw new Error(

package/src/core/types.ts

@@ -924,8 +924,8 @@ export interface SearchFilters {
   paginate?: 'cursor' | 'offset' | false
   text?: { fields: string[]; placeholder?: I18nRef }
   periods?: PeriodSpec[]
-  /** Dimensões fechadas que a ActionList pode usar para agrupar a tabela. Cada nome
-   *  referencia um filtro select com opções static ou dictionary. */
+  /** Dimensões enumeráveis que a ActionList pode usar para agrupar a tabela. Cada nome
+   *  referencia um filtro select/lookup com até 12 opções declaradas ou resolvidas em runtime. */
   grouping?: { fields: string[] }
   /**
    * Cláusula DSL aplicada **sempre** pelo repository do consumer (ex:
@@ -959,7 +959,7 @@ export interface ListAction<In, Out, ParsedIn = In>
   paginate?: 'cursor' | 'offset' | false
   text?: { fields: string[]; placeholder?: I18nRef }
   periods?: PeriodSpec[]
-  /** Dimensões fechadas que a ActionList pode usar para agrupar a tabela. */
+  /** Dimensões enumeráveis que a ActionList pode usar para agrupar a tabela. */
   grouping?: { fields: string[] }
   /**
    * Ver `SearchFilters.where`. Baseline DSL aplicado pelo repository

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

@@ -1,7 +1,6 @@
 import { useQueries } from '@tanstack/react-query'
 import { useRef } from 'react'
-import type { ActionDef, ActionError, Paginated } from '../../../core/index.ts'
-import { useClient } from '../../drivers/context.tsx'
+import type { ActionDef, ActionError, ClientAdapter, Paginated } from '../../../core/index.ts'
 
 export interface ListActionGroup<TItem> {
   value: string
@@ -15,7 +14,8 @@ export interface ListActionGroup<TItem> {
 }
 
 /** Implementação interna do ActionList para executar um recorte paginado por grupo. */
-export function useGroupedListAction<TItem = unknown, TInput extends Record<string, unknown> = Record<string, unknown>>(
+export function useGroupedListQueries<TItem = unknown, TInput extends Record<string, unknown> = Record<string, unknown>>(
+  client: ClientAdapter,
   action: { name: string; kind: 'list' },
   input: TInput,
   field: string | null,
@@ -24,7 +24,6 @@ export function useGroupedListAction<TItem = unknown, TInput extends Record<stri
   pages: Record<string, number>,
   pageSize: number,
 ): ListActionGroup<TItem>[] {
-  const client = useClient('ActionList grouping')
   const previous = useRef<{
     field: string | null
     groups: Map<string, { items: TItem[]; total: number }>

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

@@ -62,11 +62,11 @@ import {
 } from "../../../core/index.ts";
 import {
   useDicts,
+  useGroupedListAction,
   useListAction,
   useLookupAction,
   type DictLike,
 } from "../../drivers/react.tsx";
-import { useGroupedListAction } from "./grouped-list.ts";
 import { cn } from "../../lib/cn.ts";
 import { FillBoundary, useFillLeaf } from "./fill-region.ts";
 import { objectSchemaShape } from "../../lib/object-schema.ts";
@@ -516,14 +516,16 @@ function useLookupOptions(
 ): {
   options: SelectOption[];
   loading: boolean;
+  query: string;
   onSearch?: (q: string) => void;
 } {
+  const [query, setQuery] = useState("");
   const lookup = spec.options?.kind === "lookup" ? spec.options : undefined;
   const search = useLookupAction<Record<string, unknown>, SelectOption>({
     name: lookup?.source ?? "noop",
     kind: "list",
   } as unknown as ActionDef);
-  if (lookup === undefined) return { options: [], loading: false };
+  if (lookup === undefined) return { options: [], loading: false, query: "" };
   const depInput: Record<string, unknown> = {};
   for (const d of lookup.depends ?? []) {
     if (!isEmptyValue(allValues[d])) depInput[d] = allValues[d];
@@ -534,7 +536,9 @@ function useLookupOptions(
       label: i.label,
     })),
     loading: search.isLoading,
+    query,
     onSearch: (q: string) => {
+      setQuery(q);
       void search.run({ ...(q !== "" ? { q } : {}), ...depInput });
     },
   };
@@ -577,21 +581,66 @@ function FilterField({
   );
   const lookup = useLookupOptions(spec, allValues);
   const dicts = useDicts();
+  const resolvedOptionByValue = useRef(new Map<string, SelectOption>());
   // Precedência: runtime/estáticas (prop `options`) > dictionary do provider;
   // sem nenhuma, as do lookup (server-side).
   const base = options.length > 0 ? options : dictOptionsFor(spec, dicts);
+  const baseByValue = new Map(base.map((option) => [option.value, option]));
+  const canonicalLookupOptions = lookup.options.map(
+    (option) => baseByValue.get(option.value) ?? option,
+  );
+  for (const option of canonicalLookupOptions) {
+    if (!resolvedOptionByValue.current.has(option.value)) {
+      resolvedOptionByValue.current.set(option.value, option);
+    }
+  }
+  for (const option of base) {
+    resolvedOptionByValue.current.set(option.value, option);
+  }
+  const selectedValues = new Set(
+    Array.isArray(value)
+      ? value.filter((item): item is string => typeof item === "string")
+      : typeof value === "string"
+        ? value === ""
+          ? []
+          : [value]
+        : defaultValue === ""
+          ? []
+          : [defaultValue],
+  );
+  const runtimeOptions =
+    lookup.onSearch !== undefined && lookup.query !== ""
+      ? base.filter((option) =>
+          selectedValues.has(option.value) ||
+          option.label
+            .toLocaleLowerCase()
+            .includes(lookup.query.toLocaleLowerCase()),
+        )
+      : base;
+  const selectedResolvedOptions = [...selectedValues]
+    .map((selectedValue) => resolvedOptionByValue.current.get(selectedValue))
+    .filter((option): option is SelectOption => option !== undefined);
+  const mergeUniqueOptions = (
+    ...groups: SelectOption[][]
+  ): SelectOption[] => {
+    const merged = new Map<string, SelectOption>();
+    for (const group of groups) {
+      for (const option of group) {
+        if (!merged.has(option.value)) merged.set(option.value, option);
+      }
+    }
+    return [...merged.values()];
+  };
   const effOptions =
     lookup.onSearch !== undefined && base.length > 0
-      ? [
-          ...base,
-          ...lookup.options.filter(
-            (candidate) =>
-              !base.some((option) => option.value === candidate.value),
-          ),
-        ]
+      ? mergeUniqueOptions(
+          runtimeOptions,
+          canonicalLookupOptions,
+          selectedResolvedOptions,
+        )
       : base.length > 0
         ? base
-        : lookup.options;
+        : mergeUniqueOptions(canonicalLookupOptions, selectedResolvedOptions);
   const singleValue = (value as string | undefined) ?? defaultValue;
   const changedFromDefault = singleValue !== defaultValue;
   const acceptsEmptyValue = spec.allowEmpty !== false;
@@ -1779,6 +1828,7 @@ export function ActionList<TInput, TItem>({
   const raw = controlledState ?? internal;
   const state: ActionListState = {
     ...raw,
+    sort: raw.sort ?? defaultSort,
     period: raw.period ?? null,
     from: raw.from ?? null,
     to: raw.to ?? null,
@@ -1818,11 +1868,7 @@ export function ActionList<TInput, TItem>({
   const availableGroupingFields = groupingFields.filter((field) => {
     if (action.filters?.group !== undefined) return false;
     const spec = action.filters?.[field];
-    if (
-      spec?.type !== "select" ||
-      (spec.options?.kind !== "static" && spec.options?.kind !== "dictionary")
-    )
-      return false;
+    if (spec?.type !== "select" && spec?.type !== "lookup") return false;
     const options = [
       ...optionsFor(field, spec, filterOptions),
       ...dictOptionsFor(spec, dicts),
@@ -1841,6 +1887,10 @@ export function ActionList<TInput, TItem>({
     availableGroupingFields.includes(requestedGroupBy)
       ? requestedGroupBy
       : null;
+  const activeGroupingLabel =
+    activeGroupBy === null
+      ? null
+      : text(action.filters?.[activeGroupBy]?.label, activeGroupBy);
   const hasSegment = children === undefined && viewEntries.length > 1;
   const periods = action.periods ?? [];
   const hasToolbar =
@@ -2090,6 +2140,34 @@ export function ActionList<TInput, TItem>({
       state.sort?.field === key && state.sort.dir === "asc" ? "desc" : "asc";
     setStateResetPage({ ...state, sort: { field: key, dir } });
   };
+  const activeSort = state.sort;
+  const sortLabelFor = (field: string): string | null => {
+    const declared = action.columns?.find((column) => column.key === field);
+    if (declared !== undefined) return text(declared.label, field);
+    const explicit = columns?.find((column) => column.key === field)?.header;
+    return typeof explicit === "string" ? explicit : null;
+  };
+  const sortableFields = (action.sort?.fields ?? []).flatMap((field) => {
+    const label = sortLabelFor(field);
+    return label === null ? [] : [{ value: field, label }];
+  });
+  const activeSortLabel =
+    activeSort === null
+      ? null
+      : sortLabelFor(activeSort.field);
+  const activeSortDirection =
+    activeSort?.dir === "asc" ? "crescente" : "decrescente";
+  const sortCustomized =
+    activeSort?.field !== defaultSort?.field ||
+    activeSort?.dir !== defaultSort?.dir;
+  const displayCustomized =
+    activeGroupBy !== null ||
+    state.columns !== null ||
+    state.limit !== null ||
+    sortCustomized;
+  const displayLabel = displayCustomized
+    ? "Exibição personalizada"
+    : "Exibição";
 
   // — Multi-seleção (batch): `can` de QUALQUER ação torna a linha marcável; nenhuma
   //   elegível na página → a coluna de checkbox nem aparece. Seleção é transitória
@@ -2180,14 +2258,20 @@ export function ActionList<TInput, TItem>({
                     <Button
                       variant="ghost"
                       size="icon"
-                      className="shrink-0"
-                      aria-label="Exibição"
+                      className="relative shrink-0"
+                      aria-label={displayLabel}
                     >
                       <Settings2 className="h-3.5 w-3.5" />
+                      {displayCustomized && (
+                        <Dot
+                          context="primary"
+                          className="absolute top-1 right-1 ring-2 ring-background"
+                        />
+                      )}
                     </Button>
                   </PopoverTrigger>
                 </TooltipTrigger>
-                <TooltipContent>Exibição</TooltipContent>
+                <TooltipContent>{displayLabel}</TooltipContent>
               </Tooltip>
               <PopoverContent
                 align="end"
@@ -2195,6 +2279,93 @@ export function ActionList<TInput, TItem>({
                 data-slot="action-list-display"
               >
                 <div className="space-y-3">
+                  {children === undefined &&
+                    activeView === "table" &&
+                    sortableFields.length > 0 && (
+                      <>
+                        <div className="space-y-2">
+                          <div className="flex items-center justify-between">
+                            <span className="text-xs font-medium text-muted-foreground">
+                              Ordenação
+                            </span>
+                            {sortCustomized && (
+                              <button
+                                type="button"
+                                onClick={() =>
+                                  setState({ ...state, sort: defaultSort, page: 1 })
+                                }
+                                className="inline-flex items-center gap-1 text-xs text-muted-foreground transition-colors hover:text-foreground"
+                              >
+                                <Eraser className="size-3" />
+                                Padrão
+                              </button>
+                            )}
+                          </div>
+                          <Select
+                            aria-label="Ordenar por"
+                            size="sm"
+                            className="w-full"
+                            value={activeSort?.field ?? "__none__"}
+                            onChange={(field) =>
+                              setState({
+                                ...state,
+                                sort:
+                                  field === "__none__"
+                                    ? null
+                                    : {
+                                        field,
+                                        dir:
+                                          activeSort?.field === field
+                                            ? activeSort.dir
+                                            : "asc",
+                                      },
+                                page: 1,
+                              })
+                            }
+                            options={[
+                              ...(defaultSort === null
+                                ? [{ value: "__none__", label: "Sem ordenação" }]
+                                : []),
+                              ...sortableFields,
+                            ]}
+                            trailing={
+                              activeSort !== null ? (
+                                <Button
+                                  type="button"
+                                  variant="ghost"
+                                  size="icon-xs"
+                                  aria-label={
+                                    activeSort.dir === "asc"
+                                      ? "Ordem crescente. Alterar para decrescente"
+                                      : "Ordem decrescente. Alterar para crescente"
+                                  }
+                                  onClick={() =>
+                                    setState({
+                                      ...state,
+                                      sort: {
+                                        ...activeSort,
+                                        dir:
+                                          activeSort.dir === "asc"
+                                            ? "desc"
+                                            : "asc",
+                                      },
+                                      page: 1,
+                                    })
+                                  }
+                                >
+                                  {activeSort.dir === "asc" ? (
+                                    <ArrowUp aria-hidden="true" />
+                                  ) : (
+                                    <ArrowDown aria-hidden="true" />
+                                  )}
+                                </Button>
+                              ) : undefined
+                            }
+                          />
+                        </div>
+                        <Separator />
+                      </>
+                    )}
                   {children === undefined &&
                     activeView === "table" &&
                     availableGroupingFields.length > 0 && (
@@ -2676,21 +2847,49 @@ export function ActionList<TInput, TItem>({
       ? Math.max(1, Math.ceil(total / (state.limit ?? pageSize)))
       : 1;
   const goTo = (page: number): void => setState({ ...state, page });
+  const displaySummary =
+    activeGroupingLabel !== null || activeSortLabel !== null ? (
+      <span
+        data-slot="action-list-display-summary"
+        className="flex min-w-0 flex-wrap items-center gap-x-2 gap-y-1"
+      >
+        {activeGroupingLabel !== null && (
+          <span className="min-w-0 break-words">
+            Agrupado por {activeGroupingLabel}
+          </span>
+        )}
+        {activeGroupingLabel !== null && activeSortLabel !== null && (
+          <span aria-hidden="true">·</span>
+        )}
+        {activeSortLabel !== null && (
+          <span className="min-w-0 break-words">
+            Ordenado por {activeSortLabel} ({activeSortDirection})
+          </span>
+        )}
+      </span>
+    ) : null;
   const footer =
     total !== undefined && !isError && activeGroupBy !== null ? (
       <div
         data-slot="action-list-footer"
-        className="flex min-h-10 items-center justify-end border-t border-border px-3 py-1 text-xs text-muted-foreground"
+        className="flex min-h-10 flex-wrap items-center justify-between gap-3 border-t border-border px-3 py-1 text-xs text-muted-foreground"
       >
-        {total} {total === 1 ? "item" : "itens"} no total
+        {displaySummary}
+        <span className={cn(displaySummary === null && "ml-auto")}>
+          {total} {total === 1 ? "item" : "itens"} no total
+        </span>
       </div>
     ) : total !== undefined && !isError ? (
       <div
         data-slot="action-list-footer"
-        className="grid min-h-10 grid-cols-[1fr_auto_1fr] items-center gap-3 border-t border-border px-3 py-1 text-xs text-muted-foreground"
+        className="grid min-h-10 grid-cols-[minmax(0,1fr)_auto_minmax(0,1fr)] items-center gap-3 border-t border-border px-3 py-1 text-xs text-muted-foreground"
       >
-        <span>
-          Página {state.page} de {pages}
+        <span className="flex min-w-0 flex-wrap items-center gap-x-3 gap-y-1">
+          <span className="whitespace-nowrap">
+            Página {state.page} de {pages}
+          </span>
+          {displaySummary !== null && <span aria-hidden="true">·</span>}
+          {displaySummary}
         </span>
         {pages > 1 && (
           // A primitiva pública na escala densa do rodapé: setas no quadrado `icon-sm`,
@@ -2735,7 +2934,7 @@ export function ActionList<TInput, TItem>({
         )}
         {/* Com 1 página o pager some; o placeholder segura a coluna do meio. */}
         {pages <= 1 && <span />}
-        <span className="justify-self-end">
+        <span className="justify-self-end whitespace-nowrap">
           {total} {total === 1 ? "item" : "itens"} no total
         </span>
       </div>

package/src/ui/components/primitives/select.tsx

@@ -95,7 +95,7 @@ interface SelectCustomBase extends SelectBaseProps {
   /** Liga a busca no próprio campo (lista longa/que cresce). */
   searchable?: boolean;
   /** Busca SERVER-SIDE (debounced): quando definida, o filtro local desliga e o pai
-   *  atualiza `options`. Implica `searchable`. */
+   *  atualiza `options`. Implica `searchable`; ao fechar, limpa uma busca enviada. */
   onSearch?: (query: string) => void;
   /** "Buscando…" enquanto o fetch corre (use com `onSearch`). */
   loading?: boolean;
@@ -279,6 +279,10 @@ function CustomSelect(
   /** Fechando por Esc: o foco volta pro gatilho, e focar abre. Marca pra ignorar UM foco. */
   const closingRef = React.useRef(false);
   const searchRef = React.useRef<HTMLInputElement>(null);
+  const wasOpenRef = React.useRef(false);
+  const lastSearchedQueryRef = React.useRef("");
+  const onSearchRef = React.useRef(onSearch);
+  onSearchRef.current = onSearch;
 
   const selectedOption = options.find((o) => o.value === singleValue);
 
@@ -303,7 +307,14 @@ function CustomSelect(
    * reabrir filtrada por algo que a pessoa procurou minutos antes e já esqueceu.
    */
   React.useEffect(() => {
-    if (!open) setQuery("");
+    if (!open && wasOpenRef.current) {
+      setQuery("");
+      if (lastSearchedQueryRef.current !== "") {
+        lastSearchedQueryRef.current = "";
+        onSearchRef.current?.("");
+      }
+    }
+    wasOpenRef.current = open;
   }, [open]);
 
   // O cmdk carimba o id DELE no input (a11y interna) e descarta o nosso — reaplicamos por
@@ -312,11 +323,13 @@ function CustomSelect(
     if (id !== undefined && inputRef.current !== null) inputRef.current.id = id;
   }, [id]);
 
-  const onSearchRef = React.useRef(onSearch);
-  onSearchRef.current = onSearch;
   React.useEffect(() => {
     if (onSearchRef.current === undefined || !open) return;
-    const t = setTimeout(() => onSearchRef.current?.(query.trim()), 200);
+    const t = setTimeout(() => {
+      const normalizedQuery = query.trim();
+      lastSearchedQueryRef.current = normalizedQuery;
+      onSearchRef.current?.(normalizedQuery);
+    }, 200);
     return () => clearTimeout(t);
   }, [query, open]);
 

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

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

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

@@ -140,8 +140,10 @@ render(
 
 ## Busca no servidor
 
-Com `onSearch`, o consumidor consulta as opções ao abrir e ao digitar, com debounce. Atualize
-`options` com a resposta e use `loading` durante a consulta. Esse modo já habilita o campo de busca.
+Com `onSearch`, o consumidor consulta as opções ao abrir e ao digitar, com debounce. Ao fechar o
+seletor depois de uma busca, recebe `""` imediatamente para restaurar as opções iniciais; abrir e
+fechar sem digitar não repete a consulta vazia. Atualize `options` com a resposta e use `loading`
+durante a consulta. Esse modo já habilita o campo de busca.
 
 ```tsx preview col md
 const ASSIGNEES = [
@@ -395,7 +397,7 @@ render(
 | `placeholder` | `string` | `'Selecione…'`; sem padrão com `native` | Texto do campo vazio. Com `native`, só existe quando declarado e vira uma opção desabilitada no início da lista. |
 | `searchPlaceholder` | `string` | `'Buscar…'` | Placeholder da linha de busca dentro da lista. |
 | `emptyText` | `string` | `'Nada encontrado.'` | Mensagem quando a busca não acha nada. |
-| `onSearch` | `(query: string) => void` | | Busca no servidor, chamada ao abrir a lista e depois de uma breve pausa na digitação. Desliga o filtro local; o consumidor atualiza `options` com a resposta. |
+| `onSearch` | `(query: string) => void` | | Busca no servidor, chamada ao abrir a lista e depois de uma breve pausa na digitação. Ao fechar depois de uma busca enviada, recebe `""` imediatamente para restaurar as opções iniciais. Desliga o filtro local; o consumidor atualiza `options` com a resposta. |
 | `loading` | `boolean` | | Mostra “Buscando…” enquanto a consulta de `onSearch` está em andamento. |
 | `clearable` | `boolean` | `false` | Mostra, quando há seleção, uma ação que limpa o valor sem abrir a lista. |
 | `icon` | `React.ReactNode` | | Ícone decorativo no início do controle, em `1rem` e no tom atenuado. |

package/src/ui/drivers/react.tsx

@@ -14,6 +14,7 @@
 import {
   useCallback,
   useMemo,
+  useRef,
   useState,
 } from 'react'
 import {
@@ -47,6 +48,10 @@ export {
 } from './context.tsx'
 import { zodErrorMapPtBr } from '../lib/zod-pt-br.ts'
 import { objectSchemaShape } from '../lib/object-schema.ts'
+import {
+  useGroupedListQueries,
+  type ListActionGroup,
+} from '../components/patterns/grouped-list.ts'
 
 // =============================================================================
 // useAction
@@ -122,9 +127,11 @@ export function useLookupAction<TInput = unknown, TItem = unknown>(
 ): UseLookupActionResult<TInput, TItem> {
   const client = useClient('useLookupAction')
   const [state, setState] = useState<ListState<TItem>>(() => idleLookup<TItem>())
+  const latestRunRef = useRef(0)
 
   const run = useCallback(
     async (input: TInput): Promise<ListState<TItem>> => {
+      const runId = ++latestRunRef.current
       setState((prev) => ({
         ...prev,
         error: undefined,
@@ -158,13 +165,14 @@ export function useLookupAction<TInput = unknown, TItem = unknown>(
             isError: true,
           }
 
-      setState(next)
+      if (runId === latestRunRef.current) setState(next)
       return next
     },
     [client, action],
   )
 
   const reset = useCallback(() => {
+    latestRunRef.current += 1
     setState(idleLookup<TItem>())
   }, [])
 
@@ -238,6 +246,32 @@ export function useListAction<TItem = unknown, TInput extends Record<string, unk
   }
 }
 
+/** Implementação interna do ActionList para executar recortes paginados por grupo. */
+export function useGroupedListAction<
+  TItem = unknown,
+  TInput extends Record<string, unknown> = Record<string, unknown>,
+>(
+  action: { name: string; kind: 'list' },
+  input: TInput,
+  field: string | null,
+  values: string[],
+  multiple: boolean,
+  pages: Record<string, number>,
+  pageSize: number,
+): ListActionGroup<TItem>[] {
+  const client = useClient('ActionList grouping')
+  return useGroupedListQueries<TItem, TInput>(
+    client,
+    action,
+    input,
+    field,
+    values,
+    multiple,
+    pages,
+    pageSize,
+  )
+}
+
 // =============================================================================
 // useFormAction
 // =============================================================================

package/src/ui/react.tsx

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