@softize/opus 23.0.0 → 24.0.0

package/src/ui/docs/DocBrowser.tsx

@@ -12,40 +12,39 @@
  * Nos dois, navegar emite `popstate`: host que guarda o path por conta própria acompanha.
  * `basePath` adapta o prefixo das URLs (`/docs` no Maestro, `/__docs` nos apps).
  */
-import { useEffect, useState } from 'react'
-import { DOC_SECTIONS, type DocSection, type DocEntry } from './registry'
-import { Pane, Split } from '../components/patterns/split.tsx'
+import { useEffect, useState } from "react";
+import { DOC_SECTIONS, type DocSection, type DocEntry } from "./registry";
+import { Pane, Split } from "../components/patterns/split.tsx";
 import {
-  PaneBody,
   Sidebar,
   SidebarGroupLabel,
   SidebarItem,
   SidebarTreeGroup,
-} from '../components/patterns/sidebar.tsx'
-import { navigate, usePathname } from '../router.ts'
+} from "../components/patterns/sidebar.tsx";
+import { navigate, usePathname } from "../router.ts";
 
 function findPage(sections: DocSection[], slug: string): DocEntry | undefined {
   for (const s of sections) {
     for (const g of s.groups) {
-      const p = g.pages.find((p) => p.slug === slug)
-      if (p) return p
+      const p = g.pages.find((p) => p.slug === slug);
+      if (p) return p;
     }
   }
-  return undefined
+  return undefined;
 }
 
 export interface DocBrowserProps {
   /** Prefixo das rotas da doc. Default `/docs` (Maestro); `/__docs` na rota dev dos apps. */
-  basePath?: string
+  basePath?: string;
   /** Path controlado pelo host (modo Maestro). Ausente = standalone (gerencia o próprio). */
-  path?: string
+  path?: string;
   /** Seções a exibir (seção → grupo → página). Default = catálogo inteiro. */
-  sections?: DocSection[]
+  sections?: DocSection[];
   /** Slugs antigos que devem abrir e substituir a URL pela página canônica. */
-  redirects?: Readonly<Record<string, string>>
+  redirects?: Readonly<Record<string, string>>;
   /** Monta o `document.title` a partir do título da página atual (ex.: `(t) => `${t} · Opus``).
    *  Ausente = não mexe no title. */
-  documentTitle?: (pageTitle: string) => string
+  documentTitle?: (pageTitle: string) => string;
 }
 
 function DocSidebarTree({
@@ -53,67 +52,75 @@ function DocSidebarTree({
   activeSlug,
   onSelect,
 }: {
-  sections: DocSection[]
-  activeSlug?: string
-  onSelect: (slug: string) => void
+  sections: DocSection[];
+  activeSlug?: string;
+  onSelect: (slug: string) => void;
 }): React.ReactElement {
-  const [closedGroups, setClosedGroups] = useState<Set<string>>(() => new Set())
+  const [closedGroups, setClosedGroups] = useState<Set<string>>(
+    () => new Set(),
+  );
 
   useEffect(() => {
-    const activeGroup = sections.flatMap((section, sectionIndex) =>
-      section.groups.map((group, groupIndex) => ({
-        key: `${sectionIndex}:${groupIndex}`,
-        group,
-      })),
-    ).find(({ group }) => group.pages.some((page) => page.slug === activeSlug))
+    const activeGroup = sections
+      .flatMap((section, sectionIndex) =>
+        section.groups.map((group, groupIndex) => ({
+          key: `${sectionIndex}:${groupIndex}`,
+          group,
+        })),
+      )
+      .find(({ group }) =>
+        group.pages.some((page) => page.slug === activeSlug),
+      );
 
-    if (activeGroup === undefined) return
+    if (activeGroup === undefined) return;
     setClosedGroups((current) => {
-      if (!current.has(activeGroup.key)) return current
-      const next = new Set(current)
-      next.delete(activeGroup.key)
-      return next
-    })
-  }, [activeSlug, sections])
+      if (!current.has(activeGroup.key)) return current;
+      const next = new Set(current);
+      next.delete(activeGroup.key);
+      return next;
+    });
+  }, [activeSlug, sections]);
 
   const toggleGroup = (key: string): void => {
     setClosedGroups((current) => {
-      const next = new Set(current)
-      if (next.has(key)) next.delete(key)
-      else next.add(key)
-      return next
-    })
-  }
+      const next = new Set(current);
+      if (next.has(key)) next.delete(key);
+      else next.add(key);
+      return next;
+    });
+  };
 
   const renderPage = (page: DocEntry): React.ReactElement => (
     <SidebarItem
       key={page.slug}
       label={page.title}
-      badge={page.badge === undefined ? undefined : (
-        <span className="rounded border border-border/60 px-1 font-mono text-[0.625rem] leading-tight text-muted-foreground/60">
-          {page.badge}
-        </span>
-      )}
+      badge={
+        page.badge === undefined ? undefined : (
+          <span className="rounded border border-border/60 px-1 font-mono text-[0.625rem] leading-tight text-muted-foreground/60">
+            {page.badge}
+          </span>
+        )
+      }
       active={page.slug === activeSlug}
       onClick={() => onSelect(page.slug)}
     />
-  )
+  );
 
   return (
     <nav aria-label="Navegação da documentação" className="space-y-4 p-2">
       {sections.map((section, sectionIndex) => (
         <div key={`${section.label}:${sectionIndex}`} className="space-y-0.5">
-          {section.label.trim() !== '' && (
+          {section.label.trim() !== "" && (
             <SidebarGroupLabel>{section.label}</SidebarGroupLabel>
           )}
           {section.groups.map((group, groupIndex) => {
-            const key = `${sectionIndex}:${groupIndex}`
-            if (group.pages.length === 0) return null
-            if ((group.label ?? '').trim() === '') {
-              return group.pages.map((page) => renderPage(page))
+            const key = `${sectionIndex}:${groupIndex}`;
+            if (group.pages.length === 0) return null;
+            if ((group.label ?? "").trim() === "") {
+              return group.pages.map((page) => renderPage(page));
             }
 
-            const expanded = !closedGroups.has(key)
+            const expanded = !closedGroups.has(key);
             return (
               <div key={key} className="space-y-0.5">
                 <SidebarItem
@@ -129,16 +136,16 @@ function DocSidebarTree({
                   </SidebarTreeGroup>
                 )}
               </div>
-            )
+            );
           })}
         </div>
       ))}
     </nav>
-  )
+  );
 }
 
 export function DocBrowser({
-  basePath = '/docs',
+  basePath = "/docs",
   path: controlledPath,
   sections = DOC_SECTIONS,
   redirects = {},
@@ -147,46 +154,47 @@ export function DocBrowser({
   // Standalone: o path vem do router da casa (`usePathname` — pathname É o estado).
   // Controlado: o host manda, e este valor é ignorado. O hook roda sempre (regra dos
   // hooks); o que muda é quem vence no `??`.
-  const livePath = usePathname()
-  const path = controlledPath ?? livePath
+  const livePath = usePathname();
+  const path = controlledPath ?? livePath;
   // Default = 1ª página do 1º grupo da 1ª seção (a doc abre na 1ª página).
-  const defaultSlug = sections[0]?.groups[0]?.pages[0]?.slug ?? ''
+  const defaultSlug = sections[0]?.groups[0]?.pages[0]?.slug ?? "";
   // Slug = TODOS os segmentos após o basePath, unidos (rota aninhada: `/docs/guias/deploy`
   // → `guias/deploy`). Slug flat de 1 segmento continua igual (`join` de 1 elemento = ele).
-  const rel = path.startsWith(basePath) ? path.slice(basePath.length) : ''
-  const requestedSlug = rel.split('/').filter(Boolean).join('/') || defaultSlug
-  const slug = redirects[requestedSlug] ?? requestedSlug
-  const page = findPage(sections, slug) ?? findPage(sections, defaultSlug)
+  const rel = path.startsWith(basePath) ? path.slice(basePath.length) : "";
+  const requestedSlug = rel.split("/").filter(Boolean).join("/") || defaultSlug;
+  const slug = redirects[requestedSlug] ?? requestedSlug;
+  const page = findPage(sections, slug) ?? findPage(sections, defaultSlug);
 
   // `navigate` emite `popstate`, então o host é notificado nos dois modos — inclusive o
   // que ainda escuta o evento na unha, que era como este componente avisava antes.
-  const go = (to: string): void => navigate(to)
+  const go = (to: string): void => navigate(to);
 
   useEffect(() => {
-    if (requestedSlug !== slug) navigate(`${basePath}/${slug}`, { replace: true })
-  }, [basePath, requestedSlug, slug])
+    if (requestedSlug !== slug)
+      navigate(`${basePath}/${slug}`, { replace: true });
+  }, [basePath, requestedSlug, slug]);
 
   // O title da aba acompanha a página atual (quando o host fornece o formato).
   useEffect(() => {
-    if (page && documentTitle) document.title = documentTitle(page.title)
-  }, [page, documentTitle])
+    if (page && documentTitle) document.title = documentTitle(page.title);
+  }, [page, documentTitle]);
 
   return (
     <Split className="h-full">
-      <Pane initialSize="14rem" inset="none">
+      <Pane initialSize="14rem">
         <Sidebar className="w-full">
-          <PaneBody>
+          <div className="min-h-0 flex-1 overflow-y-auto px-3 py-6">
             <DocSidebarTree
               sections={sections}
               activeSlug={page?.slug}
               onSelect={(nextSlug) => go(`${basePath}/${nextSlug}`)}
             />
-          </PaneBody>
+          </div>
         </Sidebar>
       </Pane>
-      <Pane key={page?.slug} grow inset="none" className="overflow-y-auto">
+      <Pane key={page?.slug} grow className="overflow-y-auto">
         <div className="mx-auto max-w-3xl px-8 py-8">{page?.render()}</div>
       </Pane>
     </Split>
-  )
+  );
 }

package/src/ui/docs/content/action-form-card.md

@@ -1,7 +1,7 @@
 ## Formulário em uma seção
 
 Use `ActionFormCard` quando o formulário ocupar uma seção delimitada da página, ao lado de outros
-blocos. O componente aplica a estrutura e o espaçamento de [`Card`](/ui/card) ao
+blocos. O componente aplica a estrutura e o espaçamento de [`Surface`](/ui/surface) ao
 [`ActionForm`](/ui/action-form), sem a faixa de ações de um modal. O título é opcional e segue a
 mesma regra de um formulário modal: nomeia a operação e o recurso, como `Criar workspace`, enquanto
 a ação principal mantém `Salvar`.
@@ -16,7 +16,7 @@ As ações ficam alinhadas no fim do rodapé e preservam a largura do conteúdo.
 acrescenta `Cancelar`, os dois botões formam um `ButtonGroup` espaçado. Para interromper o fluxo
 com um modal, use [`ActionFormDialog`](/ui/action-form-dialog).
 
-O título do card é um heading `h3`, o nível padrão de `CardTitle`, adequado a uma seção dentro de
+O título do card é um heading `h3`, o nível padrão de `SurfaceTitle`, adequado a uma seção dentro de
 uma página que já tem o próprio título. Quando o card ocupar outro lugar na hierarquia — por
 exemplo, a seção principal logo abaixo do `h1` da página —, declare `titleLevel={2}`. O nível muda
 só a estrutura do documento, que leitores de tela usam para navegar; a aparência do título continua
@@ -24,11 +24,11 @@ a mesma.
 
 ## Propriedades de ActionFormCard
 
-| Propriedade        | Tipo                         | Padrão | Descrição                                                                                                                     |
-| ------------------ | ---------------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------- |
-| `title`            | `string`                     |        | Título do cabeçalho. Sem ele e sem `description`, o card começa diretamente pelo corpo.                                       |
-| `titleLevel`       | `1 \| 2 \| 3 \| 4 \| 5 \| 6`    | `3`    | Nível do heading do título. Muda a hierarquia do documento, não a escala visual.                                              |
-| `description`      | `string`                     |        | Texto de apoio abaixo do título.                                                                                              |
-| `cardClassName`    | `string`                     |        | Classes aplicadas à superfície do card.                                                                                       |
-| `className`        | `string`                     |        | Classes aplicadas ao `<form>` interno.                                                                                        |
+| Propriedade         | Tipo                         | Padrão | Descrição                                                                                                                                                                                                                                                                   |
+| ------------------- | ---------------------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `title`             | `string`                     |        | Título do cabeçalho. Sem ele e sem `description`, o card começa diretamente pelo corpo.                                                                                                                                                                                     |
+| `titleLevel`        | `1 \| 2 \| 3 \| 4 \| 5 \| 6` | `3`    | Nível do heading do título. Muda a hierarquia do documento, não a escala visual.                                                                                                                                                                                            |
+| `description`       | `string`                     |        | Texto de apoio abaixo do título.                                                                                                                                                                                                                                            |
+| `cardClassName`     | `string`                     |        | Classes aplicadas à superfície do card.                                                                                                                                                                                                                                     |
+| `className`         | `string`                     |        | Classes aplicadas ao `<form>` interno.                                                                                                                                                                                                                                      |
 | Demais propriedades | Propriedades de `ActionForm` |        | `action`, `defaultValues`, `fieldOptions`, `submitLabel`, `cancelLabel`, `cancelVariant`, `onCancel`, `onSuccess`, `disabled`, `onLoadingChange` e `children` mantêm o comportamento de `ActionForm`. `body` e `footer` não são aceitas: o card fornece o corpo e o rodapé. |

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

@@ -34,18 +34,19 @@ render(
 
 ## Coleção nomeada
 
-Em uma página, envolva a listagem com [`Content`](/ui/content). O título e a criação ocupam
+Em uma página, envolva a listagem com [`Surface`](/ui/surface). O título e a criação ocupam
 extremos opostos do cabeçalho da coleção; busca, filtros e atualização permanecem na toolbar do
 `ActionList`.
 
 ```tsx
-<Content
+<Surface
+  as="section"
   title="Workspaces"
   level={1}
   actions={<Button>Criar workspace</Button>}
 >
   <ActionList action={workspaceList} input={{}} />
-</Content>
+</Surface>
 ```
 
 Use `toolbarActions` somente quando a operação depender do recorte visível, como exportar os
@@ -94,12 +95,11 @@ ao modal “Filtros”; `external` mantém o filtro no estado navegável e no in
 apresentação para o consumidor, como cards de status acima da lista. No modal, filtros com a mesma
 `section` formam um grupo, e `advancedFilters.columns` distribui os grupos em até três colunas.
 Use `advancedFilters.sectionIcons` quando os grupos representarem dimensões recorrentes; a chave é
-o mesmo rótulo de `section`, e cada grupo usa `Content as="fieldset"` para manter uma legenda
-nativa. O ícone ocupa a mídia do grupo, antes do título, e recebe a moldura padrão: passe só o
-glifo. Um `IconTile` é adotado pela mídia com o que declara, e um ícone `null` não desenha nada.
-Quando os grupos precisarem de limites mais explícitos, `advancedFilters.sectionVariant: 'framed'`
-envolve cada seção e pede ao `Content` o acabamento `frameVariant="legend"`, integrando visualmente
-a legenda à borda sem atribuir esse design à semântica de `fieldset`.
+o mesmo rótulo de `section`, e cada grupo usa `Surface as="fieldset"` para manter uma legenda
+nativa. O ícone ocupa a mídia do grupo antes do título. Passe um `IconTile` quando quiser moldura;
+um glifo solto permanece sem decoração, e um ícone `null` não desenha nada. Quando os grupos
+precisarem de limites mais explícitos, `advancedFilters.sectionVariant: 'framed'` acrescenta a
+borda da `Surface` sem mudar a semântica do `fieldset`.
 Um filtro `select` pode declarar `searchable: true` quando a lista fechada for longa; a opção geral
 continua disponível e participa da busca. Campos de data avançados usam calendário. A antiga `advanced: true` continua aceita durante a
 migração e equivale a `placement: 'advanced'`.
@@ -229,7 +229,7 @@ Por padrão, a lista cresce com os resultados e a rolagem acontece na janela ou
 hospeda. Quando a coleção é a região principal de uma tela de altura fixa, a barra de filtros e o
 rodapé podem continuar visíveis enquanto só os resultados rolam. Para isso, declare
 `layout="fill"` na [`Page`](/ui/page) e componha a lista com `PageBody` e
-[`Content`](/ui/content), como no exemplo abaixo. Role a tabela para ver o cabeçalho fixo.
+[`Surface`](/ui/surface), como no exemplo abaixo. Role a tabela para ver o cabeçalho fixo.
 
 ```tsx preview col
 render(
@@ -237,17 +237,17 @@ render(
     <div className="h-80 w-full overflow-x-auto overflow-y-hidden rounded-lg border border-border">
       <Page layout="fill">
         <PageBody>
-          <Content level={1}>
-            <ContentHeader>
-              <ContentTitle>Workspaces</ContentTitle>
-              <ContentActions>
+          <Surface as="section" level={1}>
+            <SurfaceHeader>
+              <SurfaceTitle>Workspaces</SurfaceTitle>
+              <SurfaceActions>
                 <Button>Criar workspace</Button>
-              </ContentActions>
-            </ContentHeader>
-            <ContentBody>
+              </SurfaceActions>
+            </SurfaceHeader>
+            <SurfaceBody>
               <ActionList action={docWorkspaceList} input={{}} />
-            </ContentBody>
-          </Content>
+            </SurfaceBody>
+          </Surface>
         </PageBody>
       </Page>
     </div>
@@ -256,7 +256,7 @@ render(
 ```
 
 A página limita a própria altura à do contêiner que a hospeda, normalmente o shell, e `PageBody`,
-`Content` e `ContentBody` repassam essa altura até a lista, que passa a usar `layout="fill"` sem que
+`Surface` e `SurfaceBody` repassam essa altura até a lista, que passa a usar `layout="fill"` sem que
 você o declare. Em uma [`Presentation`](/ui/presentation) de lista, basta `layout="fill"` no
 próprio `Presentation`. Só as regiões que contêm a lista mudam: uma seção irmã, como um resumo acima
 da coleção, mantém a altura do próprio conteúdo. Os demais filhos de cada região que repassa a
@@ -269,16 +269,16 @@ rola, sobre a cor da superfície e com uma linha inferior, e a moldura dos estad
 erro e vazio ocupa a altura disponível. Em outras visualizações e em `children`, a rolagem interna
 continua, mas não existe cabeçalho fixo.
 
-A lista só assume `fill` sozinha quando é filha direta de `PageBody`, `ContentBody` ou do corpo de
+A lista só assume `fill` sozinha quando é filha direta de `PageBody`, `SurfaceBody` ou do corpo de
 uma `Presentation`, e a altura só chega até ela se não houver um contêiner próprio entre esses
 componentes no caminho. Nos demais casos, a decisão é sua:
 
 - Para a lista manter a altura dos resultados, como em uma seção secundária cuja rolagem pertence ao
   `PageBody`, declare `layout="flow"`.
-- Um contêiner próprio entre `ContentBody` e a lista, como um `TabsPanel`, não repassa a altura, e
+- Um contêiner próprio entre `SurfaceBody` e a lista, como um `TabsPanel`, não repassa a altura, e
   a lista volta a `flow`. Declare `layout="fill"` na lista e dê ao contêiner as classes
   `flex min-h-0 flex-1 flex-col`.
-- Dentro de [`Card`](/ui/card), [`Dialog`](/ui/dialog), [`Drawer`](/ui/drawer) ou
+- Dentro de [`Surface`](/ui/surface), [`Dialog`](/ui/dialog), [`Drawer`](/ui/drawer) ou
   [`Pane`](/ui/pane), a lista não herda o `fill` da página: a altura do corpo pertence à
   superfície.
 
@@ -335,17 +335,20 @@ render(
             render: (workspaces: Workspace[]) => (
               <div className="grid grid-cols-2 gap-3">
                 {workspaces.map((w) => (
-                  <Card key={w.id}>
-                    <CardHeader>
-                      <CardTitle>{w.name}</CardTitle>
-                      <CardDescription>
+                  <Surface framed elevation="raised" key={w.id}>
+                    <SurfaceHeader>
+                      <SurfaceTitle>{w.name}</SurfaceTitle>
+                      <SurfaceDescription>
                         {w.agents === 1 ? "1 agente" : `${w.agents} agentes`}
-                      </CardDescription>
-                      <CardAction>
-                        <DictionaryValue dict={docWorkspaceStatus} value={w.status} />
-                      </CardAction>
-                    </CardHeader>
-                  </Card>
+                      </SurfaceDescription>
+                      <SurfaceActions>
+                        <DictionaryValue
+                          dict={docWorkspaceStatus}
+                          value={w.status}
+                        />
+                      </SurfaceActions>
+                    </SurfaceHeader>
+                  </Surface>
                 ))}
               </div>
             ),
@@ -364,8 +367,8 @@ render(
 - **`depends: ['outroFiltro']`:** desabilita o filtro até que suas dependências tenham valor e o
   limpa quando uma delas muda.
 - **`presentation: 'toggle'`:** mantém visíveis as opções curtas de um `select` de escolha única;
-  estado, URL e input da action continuam iguais aos do controle padrão. Entradas de dicionário
-  com `icon` apresentam o ícone junto ao rótulo.
+  o `ToggleGroup` usa `mode="segmented"`, enquanto estado, URL e input da action continuam iguais
+  aos do controle padrão. Entradas de dicionário com `icon` apresentam o ícone junto ao rótulo.
 - **`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
@@ -442,7 +445,10 @@ render(
                     <ItemDescription>Cliente {w.client}.</ItemDescription>
                   </ItemHeader>
                   <ItemActions>
-                    <DictionaryValue dict={docWorkspaceStatus} value={w.status} />
+                    <DictionaryValue
+                      dict={docWorkspaceStatus}
+                      value={w.status}
+                    />
                   </ItemActions>
                 </Item>
               </React.Fragment>
@@ -475,13 +481,13 @@ 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.                                                                                                                                                                                                                                                                                                              |
+| 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.                                                                                                                                                                                                                                                                                                                                                               |
+| `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.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
 
 ## useListAction
 
@@ -493,31 +499,31 @@ chamar a action.
 
 ## Propriedades de ActionList
 
-| Propriedade             | Tipo                                                                                                        | Padrão                                    | Descrição                                                                                                                                                                    |
-| ----------------------- | ----------------------------------------------------------------------------------------------------------- | ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `action`                | `ListActionLike`                                                                                            |                                           | A ListAction do Opus (kind list, output = item). A paginação envia `limit`/`page` e usa o `total` devolvido.                                                                 |
-| `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`, `ContentBody` 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).                                                                                                    |
-| `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.                                                                   |
-| `periodPosition`        | `'before' \| 'after' \| { afterFilter: string }`                                                            | `'before'`                                | Posiciona o período antes, depois ou imediatamente após um filtro inline.                                                                                                    |
-| `period`                | `{ basisFilter: string }`                                                                                   |                                           | Reúne o período e o filtro inline indicado em um único controle.                                                                                                             |
-| `views`                 | `Record<string, ActionListView<TItem>>`                                                                     |                                           | Visualizações alternativas `{ label, icon?, render }`; o seletor alterna entre a tabela e estas.                                                                             |
-| `beforeContent`         | `ReactNode`                                                                                                 |                                           | Conteúdo entre a toolbar e o corpo, como um resumo que reage ao recorte atual.                                                                                               |
-| `columns`               | `ActionListColumn<TItem>[]`                                                                                 |                                           | Tabela explícita, que substitui as colunas declaradas no contrato.                                                                                                           |
-| `children`              | `(items, refetch) => ReactNode`                                                                             |                                           | Modo composição: layout livre; a toolbar segue. Tem precedência sobre columns.                                                                                               |
-| `batch`                 | `ActionListBatchAction[]`                                                                                   |                                           | Ações em lote: `{ label, can?, run, confirm?: { title, message? }, destructive? }` — liga a multi-seleção.                                                                   |
-| `rowId`                 | `(item) => string`                                                                                          | `item.id`                                 | Identidade da linha para seleção.                                                                                                                                            |
-| `pageSize`              | `number`                                                                                                    | `50`                                      | Itens por página padrão (vira `limit`/`page` no input; handler devolve `total`). O usuário troca no popover de exibição.                                                     |
-| `state / onStateChange` | `ActionListState / (next) => void`                                                                          | interno                                   | Estado da toolbar controlado — para quem embala sincronizar com a URL.                                                                                                       |
-| `empty`                 | `(items) => boolean`                                                                                        | `items.length === 0`                      | Sobrepõe o vazio derivado, por exemplo quando um formulário inline aberto conta como conteúdo.                                                                               |
-| `loading`               | `boolean`                                                                                                   |                                           | Carga extra agregada à da consulta, como uma query irmã de que os `children` dependem.                                                                                       |
-| `emptyMessage`          | `string`                                                                                                    | `'Nenhum resultado.'`                     | Frase do estado vazio (o `Empty` do `DataState`).                                                                                                                            |
-| `errorMessage`          | `string`                                                                                                    | `'Não foi possível carregar.'`            | Título do aviso de erro; a ação de tentar de novo refaz a consulta.                                                                                                          |
-| `retryLabel`            | `string`                                                                                                    | `'Tentar de novo'`                        | Nome acessível e tooltip da ação de recuperação.                                                                                                                             |
-| `onRowClick`            | `(item: TItem) => void`                                                                                     |                                           | Clique na linha (ex.: navegar para o detalhe) — só na tabela.                                                                                                                |
-| `toolbarActions`        | `ReactNode`                                                                                                 |                                           | Operações ligadas ao recorte atual, no fim da barra e separadas do grupo de controles. Os nós são renderizados como recebidos: nome acessível e tooltip de uma ação somente com ícone ficam com o consumidor. |
-| `rowActions`            | `(item: TItem) => ReactNode`                                                                                |                                           | Ações por linha (coluna final, à direita). A partir de duas, entram em um grupo com intervalo compacto; uma só fica solta, sem grupo. Cliques ali não disparam o `onRowClick`. |
+| Propriedade             | Tipo                                                                                                        | Padrão                                                                                                                                | Descrição                                                                                                                                                                                                     |
+| ----------------------- | ----------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `action`                | `ListActionLike`                                                                                            |                                                                                                                                       | A ListAction do Opus (kind list, output = item). A paginação envia `limit`/`page` e usa o `total` devolvido.                                                                                                  |
+| `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).                                                                                                                                     |
+| `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.                                                                                                    |
+| `periodPosition`        | `'before' \| 'after' \| { afterFilter: string }`                                                            | `'before'`                                                                                                                            | Posiciona o período antes, depois ou imediatamente após um filtro inline.                                                                                                                                     |
+| `period`                | `{ basisFilter: string }`                                                                                   |                                                                                                                                       | Reúne o período e o filtro inline indicado em um único controle.                                                                                                                                              |
+| `views`                 | `Record<string, ActionListView<TItem>>`                                                                     |                                                                                                                                       | Visualizações alternativas `{ label, icon?, render }`; o seletor alterna entre a tabela e estas.                                                                                                              |
+| `beforeContent`         | `ReactNode`                                                                                                 |                                                                                                                                       | Conteúdo entre a toolbar e o corpo, como um resumo que reage ao recorte atual.                                                                                                                                |
+| `columns`               | `ActionListColumn<TItem>[]`                                                                                 |                                                                                                                                       | Tabela explícita, que substitui as colunas declaradas no contrato.                                                                                                                                            |
+| `children`              | `(items, refetch) => ReactNode`                                                                             |                                                                                                                                       | Modo composição: layout livre; a toolbar segue. Tem precedência sobre columns.                                                                                                                                |
+| `batch`                 | `ActionListBatchAction[]`                                                                                   |                                                                                                                                       | Ações em lote: `{ label, can?, run, confirm?: { title, message? }, destructive? }` — liga a multi-seleção.                                                                                                    |
+| `rowId`                 | `(item) => string`                                                                                          | `item.id`                                                                                                                             | Identidade da linha para seleção.                                                                                                                                                                             |
+| `pageSize`              | `number`                                                                                                    | `50`                                                                                                                                  | Itens por página padrão (vira `limit`/`page` no input; handler devolve `total`). O usuário troca no popover de exibição.                                                                                      |
+| `state / onStateChange` | `ActionListState / (next) => void`                                                                          | interno                                                                                                                               | Estado da toolbar controlado — para quem embala sincronizar com a URL.                                                                                                                                        |
+| `empty`                 | `(items) => boolean`                                                                                        | `items.length === 0`                                                                                                                  | Sobrepõe o vazio derivado, por exemplo quando um formulário inline aberto conta como conteúdo.                                                                                                                |
+| `loading`               | `boolean`                                                                                                   |                                                                                                                                       | Carga extra agregada à da consulta, como uma query irmã de que os `children` dependem.                                                                                                                        |
+| `emptyMessage`          | `string`                                                                                                    | `'Nenhum resultado.'`                                                                                                                 | Frase do estado vazio (o `Empty` do `DataState`).                                                                                                                                                             |
+| `errorMessage`          | `string`                                                                                                    | `'Não foi possível carregar.'`                                                                                                        | Título do aviso de erro; a ação de tentar de novo refaz a consulta.                                                                                                                                           |
+| `retryLabel`            | `string`                                                                                                    | `'Tentar de novo'`                                                                                                                    | Nome acessível e tooltip da ação de recuperação.                                                                                                                                                              |
+| `onRowClick`            | `(item: TItem) => void`                                                                                     |                                                                                                                                       | Clique na linha (ex.: navegar para o detalhe) — só na tabela.                                                                                                                                                 |
+| `toolbarActions`        | `ReactNode`                                                                                                 |                                                                                                                                       | Operações ligadas ao recorte atual, no fim da barra e separadas do grupo de controles. Os nós são renderizados como recebidos: nome acessível e tooltip de uma ação somente com ícone ficam com o consumidor. |
+| `rowActions`            | `(item: TItem) => ReactNode`                                                                                |                                                                                                                                       | Ações por linha (coluna final, à direita). A partir de duas, entram em um grupo com intervalo compacto; uma só fica solta, sem grupo. Cliques ali não disparam o `onRowClick`.                                |