@softize/opus 29.0.0 → 31.0.0

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

@@ -16,7 +16,11 @@ render(
     title="Dispositivos conectados"
     count={3}
     description="Sessões com acesso à sua conta."
-    actions={<Button variant="outline" size="sm">Encerrar outras sessões</Button>}
+    actions={
+      <Button variant="outline" size="sm">
+        Encerrar outras sessões
+      </Button>
+    }
   >
     <p className="text-sm text-muted-foreground">MacBook Pro · ativo agora</p>
   </Surface>,
@@ -43,17 +47,16 @@ Quando `aria-label` é informado, ele substitui a ligação com o título. Para
 
 ## Moldura, fundo e anatomia
 
-Três propriedades independentes definem a aparência:
+Moldura e fundo têm funções independentes:
 
 - `framed` acrescenta borda e raio.
 - `elevation="raised"` dá à superfície o fundo de um elemento elevado sobre a página.
-- `layout` escolhe entre o ritmo contínuo e as faixas com divisores.
 
 Uma superfície com moldura ou com fundo passa a aplicar o recuo de `1rem` nas suas regiões; você não
 escreve classes de padding no header, no corpo ou no rodapé. O header delimitado usa
-`1rem` em todos os lados e linha mínima de `2rem`, como Page, Dialog e Drawer.
-Declare `sm` para botões textuais e `icon-sm` para ícones; Pane usa a mesma geometria
-quando hospeda Surface. Seções sem moldura e legendas recortadas não ganham padding de barra.
+`1rem` em todos os lados e linha mínima de `2,25rem`, como Page, Dialog e Drawer.
+Declare `default` para botões textuais e `icon` para ícones; Pane usa a mesma geometria
+quando hospeda Surface. Seções sem moldura permanecem alinhadas ao hospedeiro.
 
 ```tsx preview col
 render(
@@ -130,12 +133,7 @@ ainda ter rodapé:
 
 ```tsx preview col
 render(
-  <Surface
-    as="section"
-    framed
-    title="Plano atual"
-    level={3}
-  >
+  <Surface as="section" framed title="Plano atual" level={3}>
     <SurfaceBody>
       <p className="text-sm text-muted-foreground">
         Renova em 12 de maio. Até 10 workspaces e 50 agentes.
@@ -163,56 +161,13 @@ A `Surface` reprova as composições que deixariam a estrutura ambígua:
 
 O `opus check` aponta os mesmos problemas antes da execução.
 
-## Contínuo ou seccionado
+## Divisores automáticos
 
-`layout` declara a anatomia da superfície inteira. No padrão, `continuous`, o espaço separa as
-regiões. Em `sectioned`, header e rodapé viram faixas e uma linha separa as regiões vizinhas.
-
-```tsx preview col
-render(
-  <div className="grid grid-cols-2 gap-4">
-    <Surface as="section" framed elevation="raised" title="Contínuo" level={3}>
-      <SurfaceBody>
-        <p className="text-sm text-muted-foreground">
-          Um assunto, lido de cima a baixo.
-        </p>
-      </SurfaceBody>
-      <SurfaceFooter>
-        <Button size="sm" variant="outline">
-          Abrir
-        </Button>
-      </SurfaceFooter>
-    </Surface>
-    <Surface
-      as="section"
-      framed
-      elevation="raised"
-      layout="sectioned"
-      title="Seccionado"
-      level={3}
-    >
-      <SurfaceBody>
-        <p className="text-sm text-muted-foreground">
-          Regiões com pesos diferentes.
-        </p>
-      </SurfaceBody>
-      <SurfaceFooter>
-        <Button size="sm" variant="outline">
-          Abrir
-        </Button>
-      </SurfaceFooter>
-    </Surface>
-  </div>,
-);
-```
-
-Use `continuous` para um bloco de leitura e `sectioned` para uma superfície de operação, com lista
-ou tabela no corpo e ações persistentes no rodapé. `sectioned` exige `framed` ou
-`elevation="raised"`: os divisores precisam de um limite para alcançar.
-
-Os divisores são derivados das regiões presentes. Um header sozinho não desenha linha, e um header
-seguido direto de um rodapé produz uma linha só. Por isso, não escreva `border-b` nem `border-t`
-nas regiões, e use `layout="continuous"` para uma superfície sem divisores.
+Em superfícies delimitadas, as regiões presentes determinam os divisores. Um header isolado não desenha linha; seguido
+pelo rodapé, produz uma linha só. O recuo de uma superfície delimitada é `1rem` em cada região.
+Sem moldura ou elevação, as regiões permanecem alinhadas ao hospedeiro e separadas por `1rem`,
+sem padding nem divisor de região. Abas no Header conservam a linha de seleção própria.
+Não há prop para alternar essa anatomia.
 
 ### Corpo de ponta a ponta
 
@@ -225,7 +180,6 @@ render(
   <Surface
     as="section"
     framed
-    layout="sectioned"
     title="Veículo"
     media={
       <IconTile size="xs">
@@ -328,9 +282,8 @@ render(
 );
 ```
 
-Com `framed`, a legenda ocupa a borda do grupo, como em um `fieldset` nativo. Com
-`layout="sectioned"`, ela passa a ser a faixa do header, dentro da moldura. Sem moldura, o grupo
-flui alinhado ao formulário.
+Em uma superfície delimitada, a legenda nativa ocupa a faixa do header. Sem moldura ou
+elevação, o grupo flui alinhado ao formulário.
 
 ## Superfície clicável
 
@@ -387,33 +340,16 @@ declaram, sem recuo nem espaçamento. O conteúdo e o recuo são seus.
 documento: uma superfície dentro de uma seção que já tem `h2` usa `level={3}`. Os níveis de 2 a 6
 têm a mesma aparência.
 
-O nível 1 é diferente: identifica o conteúdo principal da página e usa a escala do título de
-[`Page`](/ui/page). É o caso da página centrada em uma coleção.
+O nível 1 usa a escala do título de [`Page`](/ui/page), mas fica restrito a superfícies
+fora de Page, como o acesso à aplicação. Dentro da Page, o título principal pertence ao
+PageHeader e as Surfaces são seções subordinadas.
 
 ## Coleção nomeada
 
-Quando a região principal da página é uma coleção, a `Surface` nomeia essa coleção e a
-[`ActionList`](/ui/action-list) executa a consulta. Coloque criar, importar e outras ações sobre o
-conjunto completo nas ações da superfície. Busca, filtros, atualização e operações que dependem do
-recorte atual permanecem na toolbar da lista.
-
-```tsx preview col
-render(
-  <Surface
-    as="section"
-    level={1}
-    title="Clientes"
-    actions={<Button size="sm">Criar cliente</Button>}
-  >
-    <p className="text-sm text-muted-foreground">
-      A lista de clientes ocupa o corpo.
-    </p>
-  </Surface>,
-);
-```
-
-A criação usa um `Button` textual na variante padrão e no tamanho `sm`, sem ícone, nomeado
-`Criar {recurso}`; o diálogo aberto por ele repete esse título, e a edição usa `Editar {recurso}`.
+Uma coleção principal usa [`Page`](/ui/page) com [`ActionList`](/ui/action-list).
+Use Surface para nomear uma coleção subordinada. Criação, importação e exportação ficam em
+`ActionList.toolbarActions`, junto de busca e filtros. Ações gerais da superfície permanecem
+no header. O botão de criação mostra **Criar**, com nome acessível e título de formulário específicos.
 
 Em uma [`Page`](/ui/page) com `layout="fill"`, a coleção ocupa a altura da página e rola só os
 resultados. `Surface` e `SurfaceBody` repassam a altura até a `ActionList` sem classes adicionais;
@@ -432,32 +368,60 @@ faixa que cobre o conteúdo ao rolar — usa `bg-[var(--surface-background,var(-
 página, vale `--background`; dentro de uma superfície elevada, o fundo dela. Um contêiner da
 aplicação que pinte outro fundo declara a mesma variável com a cor que usa.
 
+## Metadados junto à identidade
+
+Use `SurfaceMeta` para badges, autoria e datas relacionados ao registro. A faixa fica
+abaixo da linha de título e ações, com espaço próprio; `SurfaceDescription` continua
+reservado à orientação textual breve. Os itens quebram em várias linhas quando necessário.
+
+```tsx preview col
+render(
+  <Surface
+    as="article"
+    title="Manual de atendimento"
+    meta={
+      <>
+        <Badge>Publicado</Badge>
+        <span>Por Ana</span>
+      </>
+    }
+  >
+    <p>Conteúdo do manual.</p>
+  </Surface>,
+);
+```
+
+A composição aceita um único `SurfaceMeta` e exige um `SurfaceTitle`. Na forma explícita, coloque-o em `SurfaceHeader`. Em `fieldset`, coloque os metadados no corpo; a legenda permanece restrita a título e mídia decorativa.
+
+O total da coleção continua ao lado do título: use `count` na forma curta ou `SurfaceCount` na explícita. Se um `SurfaceMeta` antigo representava esse total, migre para `SurfaceCount`.
+
 ## Propriedades de Surface
 
-| Propriedade   | Tipo                                            | Padrão         | Descrição                                                                                              |
-| ------------- | ----------------------------------------------- | -------------- | ------------------------------------------------------------------------------------------------------ |
-| `as`          | `'div' \| 'section' \| 'article' \| 'fieldset'` | `'div'`        | Elemento da superfície. Não combina com `asChild`.                                                     |
-| `asChild`     | `boolean`                                       | `false`        | Entrega a superfície ao único filho, como um `button` ou um link.                                      |
-| `framed`      | `boolean`                                       | `false`        | Acrescenta borda e raio, e recorta o conteúdo seccionado ou sem recuo.                                 |
-| `elevation`   | `'none' \| 'raised'`                            | `'none'`       | `raised` pinta o fundo de superfície elevada e mantém a altura do próprio conteúdo.                    |
-| `layout`      | `'continuous' \| 'sectioned'`                   | `'continuous'` | Anatomia das regiões. `sectioned` exige `framed` ou `elevation="raised"`.                              |
-| `level`       | `1 \| 2 \| 3 \| 4 \| 5 \| 6`                    | `2`            | Nível do heading do título. `1` identifica o conteúdo principal da página. Não se aplica a `fieldset`. |
-| `title`       | `ReactNode`                                     |                | Forma curta: título da superfície.                                                                     |
-| `media`       | `ReactNode`                                     |                | Forma curta: conteúdo do slot de mídia, antes do título. Exige `title`.                                |
-| `count`       | `number`                                        |                | Forma curta: total de itens ao lado do título. Exige `title`; indisponível em `fieldset`.              |
-| `description` | `ReactNode`                                     |                | Forma curta: frase de apoio sob o título. Exige `title`; indisponível em `fieldset`.                   |
-| `actions`     | `ReactNode`                                     |                | Forma curta: ações sobre a superfície inteira. Exige `title`; indisponível em `fieldset`.              |
-| `className`   | `string`                                        |                | Compõe sobre a superfície. Na caixa simples, é onde entra o recuo.                                     |
-| `children`    | `ReactNode`                                     |                | Filhos livres, que formam o corpo, ou os slots `SurfaceHeader`, `SurfaceBody` e `SurfaceFooter`.       |
+| Propriedade   | Tipo                                            | Padrão   | Descrição                                                                                              |
+| ------------- | ----------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------ |
+| `as`          | `'div' \| 'section' \| 'article' \| 'fieldset'` | `'div'`  | Elemento da superfície. Não combina com `asChild`.                                                     |
+| `asChild`     | `boolean`                                       | `false`  | Entrega a superfície ao único filho, como um `button` ou um link.                                      |
+| `framed`      | `boolean`                                       | `false`  | Acrescenta borda e raio, e recorta o conteúdo seccionado ou sem recuo.                                 |
+| `elevation`   | `'none' \| 'raised'`                            | `'none'` | `raised` pinta o fundo de superfície elevada e mantém a altura do próprio conteúdo.                    |
+| `level`       | `1 \| 2 \| 3 \| 4 \| 5 \| 6`                    | `2`      | Nível do heading do título. `1` identifica o conteúdo principal da página. Não se aplica a `fieldset`. |
+| `title`       | `ReactNode`                                     |          | Forma curta: título da superfície.                                                                     |
+| `media`       | `ReactNode`                                     |          | Forma curta: conteúdo do slot de mídia, antes do título. Exige `title`.                                |
+| `count`       | `number`                                        |          | Forma curta: total de itens ao lado do título. Exige `title`; indisponível em `fieldset`.              |
+| `description` | `ReactNode`                                     |          | Forma curta: frase de apoio sob o título. Exige `title`; indisponível em `fieldset`.                   |
+| `meta`        | `ReactNode`                                     |          | Forma curta: metadados sob o título e a orientação. Exige `title`; indisponível em `fieldset`.         |
+| `actions`     | `ReactNode`                                     |          | Forma curta: ações sobre a superfície inteira. Exige `title`; indisponível em `fieldset`.              |
+| `className`   | `string`                                        |          | Compõe sobre a superfície. Na caixa simples, é onde entra o recuo.                                     |
+| `children`    | `ReactNode`                                     |          | Filhos livres, que formam o corpo, ou os slots `SurfaceHeader`, `SurfaceBody` e `SurfaceFooter`.       |
 
 As demais propriedades são as nativas do elemento escolhido em `as`.
 
 ## Propriedades de SurfaceHeader
 
-| Propriedade | Tipo        | Padrão | Descrição                                                                                                                                                                                               |
-| ----------- | ----------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `children`  | `ReactNode` |        | No máximo um de cada: `SurfaceMedia`, `SurfaceTitle`, `SurfaceMeta`, `SurfaceDescription` e `SurfaceActions`. Em `fieldset`, o `SurfaceTitle` é obrigatório e somente ele e `SurfaceMedia` são aceitos. |
-| `className` | `string`    |        | Ajusta a região do header.                                                                                                                                                                              |
+| Propriedade | Tipo        | Padrão | Descrição                                                                                                                                                                                                               |
+| ----------- | ----------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `tabs`      | `ReactNode` |        | `TabsList` sob o título, controlado por um `Tabs` ancestral. Não disponível em fieldset.                                                                                                                                |
+| `children`  | `ReactNode` |        | No máximo um de cada: `SurfaceMedia`, `SurfaceTitle`, `SurfaceCount`, `SurfaceMeta`, `SurfaceDescription` e `SurfaceActions`. Em `fieldset`, o `SurfaceTitle` é obrigatório e somente ele e `SurfaceMedia` são aceitos. |
+| `className` | `string`    |        | Ajusta a região do header.                                                                                                                                                                                              |
 
 `SurfaceHeader` só existe como filho direto de `Surface`.
 
@@ -475,13 +439,6 @@ As demais propriedades são as nativas do elemento escolhido em `as`.
 | `children`  | `ReactNode` |        | Nome da superfície. O heading usa o `level` declarado em `Surface`. |
 | `className` | `string`    |        | Ajusta o título.                                                    |
 
-## Propriedades de SurfaceMeta
-
-| Propriedade | Tipo        | Padrão | Descrição                                                |
-| ----------- | ----------- | ------ | -------------------------------------------------------- |
-| `children`  | `ReactNode` |        | Metadado curto ao lado do título, como o total de itens. |
-| `className` | `string`    |        | Ajusta o metadado.                                       |
-
 ## Propriedades de SurfaceDescription
 
 | Propriedade | Tipo        | Padrão | Descrição                    |
@@ -517,6 +474,27 @@ um wrapper filho declara relações locais mais compactas.
 ## Subheading e regras de negócio
 
 `description` e `SurfaceDescription` apresentam brevemente a finalidade da região. A orientação
-é opcional e não repete o título. A mesma regra vale para uma página (`level={1}`), uma seção ou
+é opcional e não repete o título. A mesma regra vale para uma página, uma seção ou
 um card: condições, limites e consequências necessários à decisão ficam no corpo ou junto do
 controle correspondente. Pular o subheading não deve comprometer a tarefa.
+
+## Propriedades de SurfaceCount
+
+| Propriedade | Tipo        | Descrição                          |
+| ----------- | ----------- | ---------------------------------- |
+| `children`  | `ReactNode` | Contador ao lado do título.        |
+| `className` | `string`    | Ajusta a apresentação do contador. |
+
+Aceita atributos nativos de `span`. Deve estar em `SurfaceHeader`, fora de `fieldset`.
+
+## Propriedades de SurfaceMeta
+
+| Propriedade | Tipo        | Descrição                                               |
+| ----------- | ----------- | ------------------------------------------------------- |
+| `children`  | `ReactNode` | Badges, datas, autoria ou outros metadados do registro. |
+| `className` | `string`    | Ajusta a faixa de metadados.                            |
+
+Aceita atributos nativos de `div`. O intervalo superior é de 0,75rem; os itens têm
+0,75rem entre colunas e 0,5rem entre linhas. O componente não insere separadores nem
+carrega dados. Omitir o slot não reserva espaço. Metadados não substituem orientações
+ou condições necessárias à decisão e não substituem a descrição textual da região.

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

@@ -8,6 +8,13 @@ A variante padrão não possui borda externa; `TableBody` mantém somente as div
 Aplique `text-right` ao cabeçalho e às células quando o domínio pedir alinhamento numérico.
 `TableCaption` descreve a tabela abaixo do conteúdo.
 
+As células quebram texto entre palavras. Identificadores longos sem espaços podem exigir
+rolagem horizontal; aplique `wrap-anywhere` à célula quando quiser permitir quebra no meio
+desses valores. Use `whitespace-nowrap` para preservar valores inteiros, como números e datas.
+O contêiner limita a tabela ao espaço recebido e oferece rolagem horizontal quando o conteúdo
+ou larguras mínimas explícitas não cabem. Em uma composição flex ou grid, permita que o ancestral também
+encolha (`min-w-0`); a tabela não pode redefinir a largura de um ancestral.
+
 ```tsx preview col
 <Table>
   <TableCaption>Sessões recentes do workspace Empresa X.</TableCaption>

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

@@ -64,6 +64,10 @@ tom ao sair do canvas e entrar num card, porque `control` representa o resultado
 cor translúcida a ser misturada com o ancestral. Da mesma forma, hover, seleção e pressão usam
 papéis diferentes e preservam a mesma ordem comportamental nos dois temas.
 
+O fundo discreto (`muted`) também se distingue do hover nos dois temas. A calibração de base
+mantém essa diferença mesmo com Contraste em zero; aumentar esse ajuste amplia os degraus da
+escala. Use os tokens de interação para hover, seleção e pressão, sem criar opacidades por componente.
+
 ```tsx preview
 const NEUTRAL_STATES = [
   ["control", "Controle em repouso."],
@@ -87,6 +91,16 @@ render(
 );
 ```
 
+A navegação interna usa `bg-sidebar text-foreground`. No claro, ela é quase branca sobre
+conteúdo branco; no escuro, acompanha a camada elevada (`card`). A sidebar geral pode usar
+`bg-sidebar-global text-foreground` para acompanhar o canvas nos dois temas, mantendo continuidade visual sem transparência.
+Os tokens são opacos, e hover, seleção e
+pressão mantêm os papéis de interação compartilhados. O fundo da navegação global continua
+sendo escolhido pelo hospedeiro.
+
+No dark, a calibração aplica uma redução final de 5% à luminosidade HSL das superfícies,
+linhas e estados neutros. Textos e contextos semânticos mantêm seus valores para preservar a leitura.
+
 ### Ajuste de aparência
 
 Os tokens neutros desta seção não são valores fixos: o tema os calcula a partir de quatro eixos,
@@ -298,8 +312,8 @@ render(
 
 1. Formato HSL nos tokens (o upstream migrou para oklch), escolhido pela legibilidade.
 2. Hierarquia opaca de superfícies e estados nos dois temas: canvas, card/popover, controle, hover,
-   seleção e pressão têm papéis próprios. No light, o canvas quase branco sustenta superfícies
-   brancas; no dark, cards e popovers permanecem acima do canvas. A ADR 0043 registra os valores e
+   seleção e pressão têm papéis próprios. No preset light, canvas, controles, cards e popovers são brancos; bordas e elevação
+   distinguem as regiões; no dark, cards e popovers permanecem acima do canvas. A ADR 0043 registra os valores e
    as restrições de composição. A escala neutra é derivada dos eixos de aparência (ADR 0044); no
    preset, os valores são os calibrados.
 3. Radius mapeado (`xs` a `2xl`) preservando o sentido pré-v4 dos utilitários `rounded-*`. Esse
@@ -307,8 +321,8 @@ render(
    precisam revisar a transição para esse degrau nativo ao customizar `--radius`.
 4. Escala `shadow-*` recomposta em duas camadas claras e difusas — preserva os degraus do
    Tailwind e troca somente o peso visual. Componentes e consumidores usam diretamente a escala.
-5. Bordas mais leves no tema claro: `--border`/`--input` em `92.5%` (upstream `89.8%`) — par do canvas
-   quase-branco do body; superfícies elevadas usam essa mesma borda real.
+5. Bordas mais leves no tema claro: `--border`/`--input` em `92%` (upstream `89.8%`) — par do canvas
+   branco do body; superfícies elevadas usam essa mesma borda real.
 6. Radius base em `0.75rem` — superfícies principais ganham cantos mais presentes sem aproximar
    controles compactos de modais. A decisão detalhada acompanha o pacote em
    `docs/radius-scale.md`, com os defaults, o comportamento de superfícies aninhadas e as

package/src/ui/drivers/context.tsx

@@ -29,9 +29,12 @@ export function OpusProvider({ client, dicts, children }: OpusProviderProps): Re
 }
 
 /** Acesso interno ao adapter; não é reexportado por `@softize/opus/ui/react`. */
-export function useClient(hook: string): ClientAdapter {
-  const ctx = useContext(OpusContext)
-  if (ctx === null) {
+export function useOptionalClient(): ClientAdapter | null {
+  return useContext(OpusContext)?.client ?? null
+}
+
+export function requireClient(client: ClientAdapter | null, hook: string): ClientAdapter {
+  if (client === null) {
     throw new Error(
       `${hook} foi chamado fora de um <OpusProvider> e não tem como executar a action. ` +
         'Os hooks de action e os componentes que os usam, como ActionForm, ActionList e ActionView, ' +
@@ -39,7 +42,11 @@ export function useClient(hook: string): ClientAdapter {
         'em testes e previews, envolva o componente renderizado.',
     )
   }
-  return ctx.client
+  return client
+}
+
+export function useClient(hook: string): ClientAdapter {
+  return requireClient(useOptionalClient(), hook)
 }
 
 const NO_DICTS: Record<string, DictLike> = {}

package/src/ui/drivers/react.tsx

@@ -39,7 +39,7 @@ import {
   idleAction,
   idleLookup,
 } from '../index.ts'
-import { useClient } from './context.tsx'
+import { useClient, useOptionalClient, requireClient } from './context.tsx'
 export {
   OpusProvider,
   useDicts,
@@ -213,18 +213,37 @@ export function useListAction<TItem = unknown, TInput extends Record<string, unk
   input?: TInput,
   options?: { enabled?: boolean },
 ): UseListActionResult<TItem> {
-  const client = useClient('useListAction')
+  return useListResource<TItem, TInput>(action, input, options)
+}
+
+/** Fonte já governada por outro serviço; a chave inclui o escopo de acesso. */
+export interface ListDataSource<TItem> {
+  key: readonly string[]
+  load: (input: Record<string, unknown>, context: { signal: AbortSignal }) => Promise<Paginated<TItem>>
+}
+
+/** Consulta comum ao ActionList e ao hook público, sem duplicar estados de busca. */
+export function useListResource<TItem = unknown, TInput extends Record<string, unknown> = Record<string, unknown>>(
+  resource: { name: string; kind: 'list' } | ListDataSource<TItem>,
+  input?: TInput,
+  options?: { enabled?: boolean },
+): UseListActionResult<TItem> {
+  const providedClient = useOptionalClient()
+  const external = 'load' in resource
+  const client = external ? null : requireClient(providedClient, 'useListAction')
 
   const query = useQuery<Paginated<TItem>, ActionError>({
-    queryKey: [action.name, input ?? {}],
-    queryFn: async () => {
-      const result = await client.run<Paginated<TItem>>(action as unknown as ActionDef, input ?? {})
+    queryKey: external ? ['opus:list-source', ...resource.key, input ?? {}] : [resource.name, input ?? {}],
+    ...(external ? { gcTime: 0, retry: false } : {}),
+    queryFn: async (context) => {
+      if (external) return resource.load(input ?? {}, { signal: context.signal })
+      const result = await client!.run<Paginated<TItem>>(resource as unknown as ActionDef, input ?? {})
       if (!result.ok) throw result.error
       return result.data
     },
     // Input mudou (filtro/página) → mantém os itens na tela enquanto busca: o
     // ActionList esmaece em vez de piscar skeleton. isPending = só o 1º load.
-    placeholderData: keepPreviousData,
+    placeholderData: external ? undefined : keepPreviousData,
     enabled: options?.enabled ?? true,
   })
 
@@ -259,7 +278,8 @@ export function useGroupedListAction<
   pages: Record<string, number>,
   pageSize: number,
 ): ListActionGroup<TItem>[] {
-  const client = useClient('ActionList grouping')
+  const providedClient = useOptionalClient()
+  const client = field === null ? providedClient : requireClient(providedClient, 'ActionList grouping')
   return useGroupedListQueries<TItem, TInput>(
     client,
     action,

package/src/ui/meta.ts

@@ -15,7 +15,7 @@ export const componentMeta = {
     name: "surface",
     ancestry: "opus",
     whenToUse:
-      'Delimite e nomeie um trecho da tela: uma região da página, um grupo de campos, um registro, um item de grade ou um bloco clicável. `as` escolhe o elemento (`div`, `section`, `article` ou `fieldset`) e `asChild` entrega a superfície a um botão ou link. `framed` acrescenta a moldura, `elevation="raised"` dá fundo próprio e `layout` escolhe entre ritmo contínuo e faixas com divisores. No caso comum, declare `title`, `description`, `count`, `actions` e `media` na própria Surface; componha SurfaceHeader, SurfaceBody e SurfaceFooter quando precisar controlar a estrutura. Numa página centrada em uma coleção, `level={1}` faz da Surface o heading principal; nas demais, ele vem de PageTitle. Para um modal use Dialog, para um painel lateral use Drawer e para uma coluna de layout use Pane.',
+      'Delimite e nomeie um trecho da tela: uma região da página, um grupo de campos, um registro, um item de grade ou um bloco clicável. `as` escolhe o elemento (`div`, `section`, `article` ou `fieldset`) e `asChild` entrega a superfície a um botão ou link. `framed` acrescenta a moldura, `elevation="raised"` dá fundo próprio. Superfícies delimitadas derivam os divisores das regiões presentes; sem moldura, conservam o alinhamento e ritmo do hospedeiro. No caso comum, declare `title`, `description`, `count`, `actions` e `media` na própria Surface; componha SurfaceHeader, SurfaceBody e SurfaceFooter quando precisar controlar a estrutura. O título principal de Page vem de PageTitle; Surfaces internas usam níveis subordinados. `level={1}` fica restrito a superfícies fora de Page. Para um modal use Dialog, para um painel lateral use Drawer e para uma coluna de layout use Pane.',
   },
   ask: {
     name: "ask",
@@ -165,7 +165,7 @@ export const componentMeta = {
     name: "separator",
     ancestry: "shadcn",
     whenToUse:
-      'Marque a fronteira entre blocos de conteúdo que não pertencem a uma superfície com regiões. A linha horizontal fica entre blocos empilhados; com `orientation="vertical"`, ela separa itens lado a lado e herda a altura do contêiner. A linha é decorativa por padrão e fica fora da árvore de acessibilidade; use `decorative={false}` quando a divisão tiver significado. Não use Separator entre cabeçalho, corpo e rodapé de Surface, Dialog ou Drawer: nessas superfícies, os divisores são derivados das regiões com `layout="sectioned"`.',
+      'Marque a fronteira entre blocos de conteúdo que não pertencem a uma superfície com regiões. A linha horizontal fica entre blocos empilhados; com `orientation="vertical"`, ela separa itens lado a lado e herda a altura do contêiner. A linha é decorativa por padrão e fica fora da árvore de acessibilidade; use `decorative={false}` quando a divisão tiver significado. Não use Separator entre cabeçalho, corpo e rodapé de Surface, Dialog ou Drawer: nessas superfícies, os divisores são derivados das regiões automaticamente.',
   },
   skeleton: {
     name: "skeleton",
@@ -261,7 +261,7 @@ export const componentMeta = {
     name: "floating-layer",
     ancestry: "opus",
     whenToUse:
-      "Mantenha utilizável, por cima de qualquer Dialog ou Drawer aberto, uma região que acompanha a aplicação inteira, como o botão e o painel de um assistente. O modal continua aberto e intacto atrás; a camada recebe clique, foco, digitação, rolagem e Esc. Diálogos que exigem resposta, como `Dialog mode=\"alert\"` e `dialog.confirm`, continuam cobrindo a camada até a resposta. Cada filho se posiciona contra a janela, e o hospedeiro publica em `data-modal` e `data-modal-side` o Dialog ou Drawer aberto. Para ferramentas sobre uma única superfície, use Dock; para conteúdo preso a um gatilho, Popover.",
+      'Mantenha utilizável, por cima de qualquer Dialog ou Drawer aberto, uma região que acompanha a aplicação inteira, como o botão e o painel de um assistente. O modal continua aberto e intacto atrás; a camada recebe clique, foco, digitação, rolagem e Esc. Diálogos que exigem resposta, como `Dialog mode="alert"` e `dialog.confirm`, continuam cobrindo a camada até a resposta. Cada filho se posiciona contra a janela, e o hospedeiro publica em `data-modal` e `data-modal-side` o Dialog ou Drawer aberto. Para ferramentas sobre uma única superfície, use Dock; para conteúdo preso a um gatilho, Popover.',
   },
   drawer: {
     name: "drawer",
@@ -388,7 +388,7 @@ export const componentMeta = {
     name: "action-list",
     ancestry: "opus",
     whenToUse:
-      "Apresente uma coleção pesquisável a partir de uma ListAction. O contrato declara colunas, filtros, período, busca e dimensões fechadas de agrupamento; ActionList coordena visualizações, paginação, seleção em lote e sincronização com a URL. A tabela derivada não cria moldura própria. Em uma página, envolva a lista com Surface para manter título e criação junto da coleção. Para um único recurso, use ActionView.",
+      "Apresente uma coleção pesquisável a partir de uma ListAction. O contrato declara colunas, filtros, período, busca e dimensões fechadas de agrupamento; ActionList coordena visualizações, paginação, seleção em lote e sincronização com a URL. A tabela derivada não cria moldura própria. Use item com os campos title e description para uma lista de itens conectados; title da coleção reúne suas toolbarActions. Fontes externas já governadas por outro serviço usam source com chave de escopo e loader, preservando o transporte existente. Para um único recurso, use ActionView.",
   },
   "action-trigger": {
     name: "action-trigger",
@@ -406,7 +406,7 @@ export const componentMeta = {
     name: "page",
     ancestry: "opus",
     whenToUse:
-      "Estruture uma página com cabeçalho, estado e conteúdo na mesma anatomia. Page renderiza o `<main>` com header e viewport em largura total e conteúdo centralizado de até 80rem; surfaceLayout escolhe sectioned (padrão) ou continuous, independente de layout flow/fill; PageHeader reúne navegação e ações da superfície; PageIntro abre PageBody com título e orientação. A composição compacta mantém o título no header, sem intro. PageShell pode fornecer navegação e ações conhecidas pela aplicação sem criar uma barra visual. Uma região interna pode fornecer o heading principal com `Surface level={1}`. PageActionsTarget fica restrito a workspaces imersivos. PageState substitui o header e o conteúdo durante carregamento, falha ou ausência, por isso informações indispensáveis entram no corpo, como Alert ou texto. Para uma falha parcial, mantenha o estado na seção com DataState; para uma região disponível para criação ou vínculo, use Empty.",
+      "Estruture uma página aberta com título e ações no header, metadados abaixo e conteúdo na mesma coluna. Page usa padding de 2,5rem, título de 1,875rem, intervalo de 1,5rem após o cabeçalho e de 1rem entre as demais regiões, sem divisores. width escolhe narrow, default ou wide; sem opção, ocupa a largura disponível. Ações dos headers de Page, Drawer, Dialog e Surface usam default/icon e linha mínima de 2,25rem. PageHeader.tabs recebe TabsList; TabsPanel fica no body. PageBack é o primeiro ícone das ações, com destino explícito e tooltip. PageShell fornece ações sem criar outra barra. layout flow rola a página inteira; fill mantém o header visível e entrega a altura a listas ou à rolagem do body. Drawer e Dialog mantêm suas superfícies delimitadas e recuo de 1rem. PageState substitui o header e o conteúdo durante carregamento, falha ou ausência. Use DataState para falha parcial. Título e metadados pertencem ao PageHeader.",
   },
   presentation: {
     name: "presentation",

package/src/ui/react.tsx

@@ -25,6 +25,7 @@ export type {
   UseFormActionOptions,
   UseFormActionResult,
   UseListActionResult,
+  ListDataSource,
   UseLookupActionResult,
   UseTriggerActionOptions,
   UseTriggerActionResult,
@@ -175,8 +176,7 @@ export {
   DialogNavigation,
   DialogMedia,
   DialogActions,
-  DialogIntro,
-  DialogIntroActions,
+  DialogMeta,
   DialogBody,
   DialogFooter,
   DialogTitle,
@@ -194,7 +194,6 @@ export type { FloatingLayerProps } from "./components/primitives/floating-layer.
 
 // O pacote de anatomia que Surface, Dialog, Drawer e Pane declaram no root (ADR 0023). As
 // tabelas e o contexto continuam internos; o consumidor escolhe entre os dois nomes.
-export type { SurfaceLayout } from "./components/patterns/surface-anatomy.ts";
 
 export {
   Menu,
@@ -324,8 +323,7 @@ export {
 export {
   Drawer,
   DrawerActions,
-  DrawerIntro,
-  DrawerIntroActions,
+  DrawerMeta,
   DrawerClose,
   DrawerContent,
   DrawerFooter,
@@ -465,12 +463,15 @@ export {
   presetRange,
   listParamsToState,
   listStateToParams,
+  listStateToInput,
 } from "./components/patterns/list.tsx";
 export type {
   ActionFilterBarProps,
   ActionFilterState,
   AdvancedFiltersLayout,
   ActionListProps,
+  ActionListItemSpec,
+  ActionListContext,
   ActionListColumn,
   ActionListState,
   ActionListView,
@@ -515,9 +516,7 @@ export {
   PageShell,
   Page,
   PageHeader,
-  PageIntro,
-  PageIntroActions,
-  PageNavigation,
+  PageMeta,
   PageBack,
   PageTitle,
   PageDescription,
@@ -549,6 +548,7 @@ export {
   SurfaceTitle,
   SurfaceDescription,
   SurfaceMeta,
+  SurfaceCount,
   SurfaceActions,
   SurfaceBody,
   SurfaceFooter,
@@ -622,3 +622,33 @@ export type {
   DotContext,
   DotVariant,
 } from "./components/primitives/dot.tsx";
+
+export {
+  bindPresentationList,
+  bindPresentationActionList,
+  bindPresentationCells,
+  bindPresentationCollection,
+  bindPresentationDetail,
+  bindPresentationOptions,
+  bindPresentationField,
+  bindPresentationComponent,
+  bindPresentationContent,
+  type PresentationRecordSource,
+  type PresentationComponentProps,
+  type PresentationComponentAdapter,
+  bindPresentationListContent,
+  bindPresentationRowContent,
+} from "./components/patterns/presentation-sections.tsx";
+export type {
+  PresentationCompositionRuntime,
+  PresentationListAdapter,
+  PresentationCellsAdapter,
+  PresentationCollectionAdapter,
+  PresentationCollectionControls,
+  PresentationDetailAdapter,
+  PresentationOptionsAdapter,
+  PresentationFieldAdapter,
+  PresentationFieldProps,
+  PresentationListContentAdapter,
+  PresentationRowContentAdapter,
+} from "./components/patterns/presentation-sections.tsx";