@softize/opus 30.0.0 → 31.1.0

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

@@ -89,20 +89,15 @@ fundo sustenta o modal, mas não é uma etapa para onde voltar. Formulários mod
 rodapé pelo conteúdo, com `Cancelar` em `ghost` e a ação principal sólida.
 
 Dentro de [`PageShell`](/ui/page), a superfície `page` usa a anatomia real da aplicação. O
-`PageHeader` reúne navegação e ações globais; o título abre o corpo na intro, e `PageFooter`
-recebe ações de rodapé. Comandos textuais nos headers de todas as superfícies usam `sm`; retorno e assistente
-usam `icon-sm`. O rodapé preserva `default`.
+`PageHeader` reúne título, retorno e ações gerais, e `PageFooter`
+recebe ações de rodapé. Comandos textuais nos headers de todas as superfícies usam `default`; retorno e assistente
+usam `icon`. O rodapé preserva `default`.
 
-Uma Presentation de listagem exibida como página muda essa distribuição para manter a criação perto
-da coleção. O `PageBody` recebe um [`Surface`](/ui/surface) com a
-[`ActionList`](/ui/action-list), e o cabeçalho desse `Surface` recebe o título e os comandos
-declarados com `placement: "header"`, no extremo oposto ao título. Os comandos de cabeçalho usam o
-tamanho `sm` e permanecem textuais, mesmo quando a action declara um ícone: o que abre outra
-Presentation é um `Button` sólido, e uma action `simple` vira um
-[`ActionTrigger`](/ui/action-trigger) `ghost`. O rótulo vem do `label` da action, como `Criar workspace`.
-
-Não envolva a Presentation em um card para simular a página. Valide proporção, rolagem e ações no
-shell que efetivamente hospeda a rota.
+Em uma Presentation de listagem, comandos da coleção usam `placement: "toolbar"`
+e são enviados a `ActionList.toolbarActions`, depois dos controles da lista. Use `label: "Criar"`
+para abreviar apenas o botão; o contrato e a Presentation do formulário preservam o nome
+específico. Comandos gerais continuam em `header`; ações de conclusão permanecem em `footer`.
+A validação rejeita `toolbar` se o body não declarar uma action list.
 
 ## Assistência contextual
 
@@ -148,7 +143,8 @@ const workspaceList = definePresentation({
   actions: [
     {
       action: "workspace.create",
-      placement: "header",
+      placement: "toolbar",
+      label: "Criar",
       target: { presentation: "workspace.create", surface: "dialog" },
     },
   ],
@@ -185,15 +181,15 @@ O identificador de `component` vai para o manifest; o JSX, não. Uma Presentatio
 componente exige `children`, e uma com body de action os recusa: nos dois casos, a renderização
 lança um erro que nomeia a Presentation.
 
-Com `heading: "shell"`, o padrão, a casca emite o título da definição. Quando o conteúdo React já
-declara o heading principal da página, como um `Surface level={1}`, use `heading: "content"`: dentro
-de `PageShell`, a casca deixa de emitir o `PageHeader` com título e o documento continua com um único `h1`. Em
-Dialog e Drawer, o título continua no cabeçalho da superfície.
+Com `heading: "shell"`, o padrão, a casca emite o título da definição. Com
+`heading: "content"`, o consumidor fornece uma Page completa, com título no PageHeader
+ou pela forma curta `Page title`. A Presentation contribui com ações e rodapé sem criar
+outra Page. O runtime reprova conteúdo sem Page e rodapés concorrentes. Em Dialog e
+Drawer, o título continua no cabeçalho da superfície.
 
-Se o conteúdo precisa ocupar a altura da página e controlar a própria rolagem, como uma lista com
-cabeçalho fixo, passe `layout="fill"` ao `Presentation`. Com o padrão `flow`, a página rola como um
-documento. Uma [`ActionList`](/ui/action-list) filha direta do conteúdo React recebe essa altura e
-assume `fill` sozinha.
+Para uma lista ocupar a altura disponível, declare `layout="fill"`. Quando o conteúdo
+fornece a própria Page, declare fill também nela. Em flow, o body da Page rola e o header
+permanece fixo. ActionList recebe fill pela cadeia estrutural sem classes adicionais.
 
 ## Registrar as declarações
 
@@ -249,7 +245,10 @@ no manifest e concentre a inspeção na Lens em vez de criar um launcher flutuan
 | `className`          | `string`                                         |          | Classes adicionais da superfície.                                                                                                                                                 |
 | `bodyClassName`      | `string`                                         |          | Classes adicionais do body, aplicadas uma única vez.                                                                                                                              |
 | `layout`             | `'flow' \| 'fill'`                               | `'flow'` | Em `page`, `fill` limita a altura ao shell e entrega a rolagem ao conteúdo do body; a lista de um body `list` ocupa essa altura e rola só os resultados. Dialog e Drawer ignoram. |
-| `children`           | `ReactNode`                                      |          | Conteúdo React do body declarado com `body.component`. Obrigatório nesse caso e recusado com `body.action`.                                                                       |
+| `children`           | `ReactNode`                                      |          | Conteúdo React do body declarado com `body.component`. Obrigatório nesse caso e recusado nos demais tipos de body.                                                                       |
+| `compositionRuntime` | `PresentationCompositionRuntime` | | Slots, fontes, células, ícones, Presentations de abas e seleção controlada. |
+| `can` | `(permission: string) => boolean` | | Resolve permissões declaradas em `requires`. Ausência nega permissões explícitas. |
+| `embedded` | `boolean` | `false` | Renderiza conteúdo e ações sem título nem retorno de uma página hospedada em outra composição. |
 
 ## Propriedades de PresentationInspector
 
@@ -262,3 +261,352 @@ no manifest e concentre a inspeção na Lens em vez de criar um launcher flutuan
 | `triggerLabel` | `string`                   | `Ver JSON da Presentation` | Nome acessível e tooltip do botão.        |
 | `title`        | `string`                   | `JSON da Presentation`     | Título do dialog de inspeção.             |
 | `className`    | `string`                   |                            | Classes adicionais do gatilho.            |
+
+
+A Page usa uma única aparência aberta. `page.width` limita sua coluna, inclusive quando
+o conteúdo declara a Page. Uma Page completa pode substituir o limite com a prop `width`.
+`layout="flow"` rola título, corpo e rodapé juntos; `layout="fill"` entrega a altura restante
+ao conteúdo. Essas opções não alteram Dialog ou Drawer.
+
+## Compor uma página por seções
+
+Para descrever a estrutura interna de uma página, use `body.sections`. São aceitas
+seções de itens (`kind: "items"`), listas (`kind: "list"`) e controles específicos
+(`kind: "content"`). A ordem do array é a ordem da tela. Seções e itens possuem ids estáveis e únicos
+no seu grupo. Os mesmos Surface, ItemGroup e ActionList do catálogo fazem a renderização.
+
+```tsx
+const securityPresentation = definePresentation({
+  schemaVersion: 1,
+  id: "settings.security",
+  title: "Segurança",
+  page: { width: "default" },
+  body: {
+    sections: [
+      {
+        id: "access",
+        kind: "items",
+        title: "Acesso",
+        actions: "password.edit",
+        items: [{ id: "password", title: "Senha", content: "password.summary" }],
+      },
+      {
+        id: "devices",
+        kind: "list",
+        title: "Dispositivos conectados",
+        source: "account.sessions",
+        item: { title: "device", description: "since" },
+        emptyMessage: "Nenhuma sessão ativa.",
+      },
+    ],
+    overlays: ["password.dialog"],
+  },
+});
+```
+
+A definição contém somente JSON. `page.width` escolhe `narrow`, `default` ou `wide`.
+A largura da página não altera Dialog ou Drawer.
+
+`compositionRuntime` registra as extensões que a definição nomeia:
+
+- `slots` fornece ReactNode para ações de seção, conteúdo de item, feedback e overlays.
+  `null` representa uma extensão disponível, mas sem conteúdo naquele estado. Uma referência
+  sem registro gera erro antes de iniciar as consultas da composição.
+- `lists` associa cada `source` ao resultado de `bindPresentationList(source, actions)`.
+  O helper conserva a tipagem dos itens e aceita `toolbarActions` e `rowActions`, com o
+  contexto de consulta do ActionList. A definição escolhe título, campos e mensagens.
+
+Os adaptadores continuam em código confiável da aplicação. Não persistir callbacks, tokens,
+URLs de execução ou nomes de módulos no artefato. O JSON pode ser inspecionado e transportado,
+mas cada hospedeiro precisa registrar as extensões referenciadas. Formulários, views e listas
+baseados em actions continuam usando `body.action`; componentes específicos podem continuar
+usando `body.component`. Abas têm uma composição própria, descrita a seguir.
+
+### Cabeçalho, controles e painel lateral
+
+`page.layout` declara `flow` ou `fill`; a prop `layout` pode substituí-lo na invocação.
+`header.title`, `header.meta` e `header.actions` referenciam slots de dados dinâmicos.
+Sem `header.title`, o título continua vindo de `title`.
+
+Uma seção `content` usa um slot para um controle específico, como uma matriz de preferências.
+O título, as ações e a posição desse controle pertencem à declaração. Não esconder uma página
+inteira nesse slot: grupos estáticos devem usar `items`, e coleções devem usar `list`.
+
+Nos itens, `labelId` permite associar o controle ao título acessível; `placement: "actions"`
+posiciona switches e seletores em ItemActions. O padrão é ItemBody com dois terços da largura;
+`placement: "below"` coloca conteúdo extenso abaixo do título, ocupando a linha. `intro` e `feedback`
+referenciam conteúdos antes e depois do grupo. O título de seção é opcional.
+
+`bindPresentationActionList(contract, props)` registra uma lista de action, conservando filtros,
+células, callbacks e toolbar do ActionList. A declaração pode escolher `item` para linhas de
+itens; sem ele, vale a tabela do contrato. `bindPresentationList` continua atendendo fontes locais.
+
+`body.aside: { content: "test", label: "Teste do agente", width: "default" }` declara uma
+coluna lateral. As larguras são `narrow` (20rem), `default` (24rem) e `wide` (28rem).
+Em uma página `fill`, o conteúdo principal rola dentro da altura disponível e o painel conserva
+seu lugar. `compositionRuntime.asideOpen` controla sua visibilidade sem perder o estado montado.
+`compositionRuntime.state` substitui temporariamente o conteúdo durante carga, falha ou ausência;
+os slots que dependem dos dados só são exigidos quando esse estado termina.
+
+## Declarar um CRUD com ações por linha
+
+Uma lista convencional continua usando `body.action`, com rotas para as Presentations de
+criação e edição. A criação usa `placement: "toolbar"`. Para editar ou excluir um item,
+use `placement: "row"` e bindings `source: "item"`:
+
+```tsx
+const storesPresentation = definePresentation({
+  schemaVersion: 1,
+  id: "settings.stores",
+  title: "Lojas",
+  page: { width: "default" },
+  body: { action: "store.list", cells: "stores.cells", emptyMessage: "Nenhuma loja." },
+  actions: [{
+    action: "store.delete",
+    placement: "row",
+    label: "Excluir",
+    icon: "trash",
+    itemLabel: "name",
+    input: { id: { source: "item", field: "id" } },
+  }],
+});
+```
+
+Uma action `simple` executa por ActionTrigger, incluindo confirmação, mensagens e
+invalidação de consultas. Actions de formulário ou view declaram `target` para abrir outra
+Presentation. `itemLabel` identifica o campo usado no nome acessível e na confirmação;
+`icon` identifica um ReactNode em `compositionRuntime.icons`. Ambos são próprios do
+placement `row`. O bloqueio de linha é `action` e cada gatilho mantém sua execução isolada.
+
+`body.cells` referencia uma entrada de `compositionRuntime.cells`. Registre-a com
+`bindPresentationCells(listContract, cells)`: os callbacks recebem o item tipado, e o
+renderer recusa o adaptador de outra action. Essa extensão atende ícones e controles
+específicos sem mover funções para o JSON. O ActionList mantém consulta, estados, busca,
+ordenação e paginação. `body.emptyMessage` pode particularizar o vazio da coleção.
+
+
+## Abas declaradas
+
+Use `body.tabs` quando a estrutura da navegação precisa estar na definição. A página
+mantém título, abas e conteúdo na mesma coluna, com rolagem definida por `layout`.
+O renderer usa os headers e as abas nativas, inclusive em Dialog e Drawer.
+
+```ts
+const emails = definePresentation({
+  schemaVersion: 1,
+  id: 'settings.emails',
+  title: 'E-mails',
+  page: { width: 'default' },
+  body: {
+    tabLabel: 'Configurações de e-mail',
+    defaultTab: 'deliveries',
+    tabs: [
+      { id: 'deliveries', label: 'Envios', icon: 'mail', content: 'emails.deliveries', route: '/settings/emails' },
+      { id: 'senders', label: 'Remetentes', content: 'emails.senders', route: '/settings/emails/senders' },
+    ],
+  },
+})
+```
+
+Cada `content` referencia um slot de `compositionRuntime.slots`; cada `icon`, uma entrada
+em `compositionRuntime.icons`. As referências são conferidas antes da montagem e somente
+o conteúdo da aba ativa monta. Os ids devem ser únicos e `defaultTab` precisa existir.
+Rotas são opcionais, absolutas dentro da aplicação, sem parâmetros e únicas na composição;
+não representam URLs externas. O JSON não executa imports nem callbacks.
+
+Sem controle externo, a seleção usa estado local. Para acompanhar a URL, forneça
+`compositionRuntime.tabs: { value, onValueChange }`. O roteador da aplicação resolve a
+aba pelo endereço e usa `tab.route` para navegar; recargas e voltar do navegador atualizam
+`value`. A Presentation não presume como áreas, filtros ou subrotas de formulários funcionam.
+Os conteúdos registrados continuam responsáveis pelas listas, permissões e operações específicas.
+
+
+## Páginas sem componente específico
+
+Uma família de Presentations pode descrever a página e seus diálogos sem um arquivo React
+por recurso. `body.tabs[].presentation` referencia uma Presentation de action. O hospedeiro
+resolve essa referência e fornece `compositionRuntime.presentations`; `embedded` permite
+renderizar o conteúdo na aba sem outro cabeçalho de página. Declare apenas `content` ou
+`presentation` em cada aba. A aplicação ainda conecta o roteador, os contratos e os ícones.
+
+Listas podem declarar `body.columns`: `text` aceita `prefix`, `empty`, `labels`, `fallback` e
+`icon`; `switch` declara action, bindings, `valueField`, `label` e `itemLabel`. O switch usa a
+invalidação da action e bloqueia submissões concorrentes. `body.opens` oferece destinos em
+ordem de prioridade, com condições `when` sobre campos da linha: `eq`, `neq`, `in`, `notIn`.
+As comparações aceitam valores escalares JSON e todas as condições precisam ser atendidas.
+Campo ausente não atende uma condição. `open` e `opens` são mutuamente exclusivos.
+
+`requires`, na Presentation, no comando ou no switch, é resolvido pelo callback `can` do
+hospedeiro. Sem resolvedor, uma permissão explícita é negada. Isso controla a interface;
+a action continua responsável pela autorização do servidor. Comandos de linha podem usar
+`when`; confirmações específicas usam `confirm: { title, body?, actionLabel? }`.
+
+Formulários podem declarar `formFields` para selecionar campos, `lookups` com action list e
+`paginate: false`, campos `label`/`value`, e `defaultsFromRecord` para aproveitar o registro obtido pelo
+hospedeiro. Bindings explícitos prevalecem sobre os valores desse registro. Campos, validação,
+submissão e efeitos continuam pertencendo ao ActionForm. Lookups exibem carga e falha com
+retentativa usando os drivers existentes.
+
+Views aceitam `fields[].format` como `text`, `pre` ou `html`. O HTML é exibido em iframe
+com sandbox sem permissões, CSP que bloqueia scripts e recursos externos e sem referrer.
+Use para prévia de conteúdo, não para documentos que precisem de navegação ou scripts.
+`width: "wide"` amplia um diálogo para conteúdo extenso; `body.intro` acrescenta orientação
+visível. `route.parent` identifica a página de retorno; parâmetros de rota aceitam camelCase.
+
+O protocolo é serializável e validado contra o registro de actions e Presentations. Ele não
+executa expressões de JavaScript recebidas no JSON. A resolução de registros e a sincronização
+de URL continuam no hospedeiro; uma aplicação que consulte só a primeira página de uma lista
+precisa tornar essa limitação visível ou fornecer uma consulta própria por identidade.
+
+## Arquivos JSON e permissões
+
+Uma página pode ser mantida em `presentations/<recurso>-list.json` e importada pelo registro do
+domínio. Valide o import com `presentationSchema.parse` e o conjunto com `validatePresentations`.
+O JSON contém apenas dados: componentes e handlers continuam em registros confiáveis da aplicação.
+`opus copy` inclui esses arquivos no inventário e aponta textos para a linha do JSON autoral.
+
+O callback `can` resolve os requisitos da declaração e das actions. Quando ambos existem, ambos
+precisam ser atendidos; uma lista em `requires` aceita qualquer uma das permissões indicadas.
+Não fornecer `can` nega requisitos explícitos. Um roteador que carrega registros antes da renderização
+deve chamar `canAccessPresentation(definition, actions, can)` antes de iniciar essas consultas.
+Ocultar controles não substitui a autorização executada no servidor; restrições por registro podem
+continuar declaradas em `when`, usando capacidades devolvidas pela própria action.
+
+## Detalhe especializado ao selecionar uma linha
+
+Use `body.inspect: { component: "audit.detail" }` quando o detalhe é local e não muda a URL.
+Registre `details["audit.detail"] = bindPresentationDetail(auditList, (item, onClose) =>
+<AuditDetailDialog item={item} onClose={onClose} />)` no runtime. O adaptador recebe o item
+tipado pelo contrato. A seleção e o fechamento ficam com a Presentation; o componente só é
+montado após o clique. `requires` e `when` restringem a abertura e a permanência do detalhe.
+
+`inspect` só vale para lists e não pode coexistir com `open` ou `opens`. Para destinos navegáveis,
+continue usando esses últimos. Um adaptador ausente ou vinculado a outra action é recusado antes
+de carregar a lista. As actions consultadas dentro do detalhe mantêm sua autorização no servidor.
+
+## Opções e filtros de coleção
+
+`body.filterDefaults` passa os filtros iniciais ao ActionList; valores explícitos na URL continuam
+prevalecendo. Nos formulários, cada lookup aceita `prepend: [{ value: "*", label: "Todas as unidades" }]`.
+Essas opções aparecem antes das linhas retornadas pela action. Quando o rótulo precisa combinar
+dados, declare `format: "units.options"` e registre o adaptador com
+`bindPresentationOptions(unitList, unit => ({ value: unit.id, label: unit.name }))` em `runtime.options`.
+
+O formatador apenas apresenta a opção. A consulta continua sendo a action declarada no lookup,
+e seu `requires` é verificado antes da busca. O inventário de copy lê os rótulos de `prepend` no JSON.
+
+
+## Campos especializados e resumos de coleção
+
+Quando um campo exige um editor próprio, declare `body.fieldComponents` com o nome do campo e
+um identificador do registro. Por exemplo: `fieldComponents: { questions: "loss.questions" }`.
+Registre `fields["loss.questions"] = bindPresentationField(questionnaireUpdate, "questions",
+props => <QuestionnaireField {...props} />)` no runtime. O componente recebe `name` e `context`,
+pode ler os dados do registro e usa `useActionFormContext` para atualizar o campo e mostrar seus
+erros. ActionForm continua validando e enviando pelo contrato; o componente não cria outro form
+nem outro botão Salvar. A declaração não pode combinar lookup e componente no mesmo campo.
+
+Para cartões ou resumos antes da tabela, declare `body.beforeContent: "usage.summary"` e registre
+`listContent["usage.summary"] = bindPresentationListContent(usageList, input =>
+<UsageSummary input={input} />)`. O input vem do ActionList, com período, busca, filtros e escopo
+materializados, inclusive quando a lista usa estado interno. O resumo pode consultar seus totais
+por uma action própria, sem somar somente as linhas da página atual.
+
+As duas extensões são código confiável registrado pelo consumidor, não código transportado no
+JSON. O renderer verifica action e campo do adaptador antes da montagem, e não monta controles
+nem resumos quando a pessoa não pode acessar a Presentation.
+
+## Configurações com leitura e edição
+
+Use `source` quando seções ou formulários precisarem carregar um registro. Declare a action
+`view` e seus bindings de input. Para uma action `list`, declare também `record.field` e
+`record.param`: o renderer seleciona apenas entre os itens retornados nesse recorte.
+Loading, erro e ausência pertencem ao renderer; requisitos da fonte e da apresentação se somam.
+
+Itens de uma seção podem usar `value: { field, empty?, suffix? }`. Mensagens em `notices`
+usam `text` e condições `when`. Comandos `placement: "section"` são referenciados por `id`
+ou pelo nome da action em `section.actions`. `accessibleLabel` distingue botões com o mesmo
+texto visível. Ações de seção usam `ghost`. Declare `icon` para exibir somente o ícone,
+com tooltip e nome acessível; mantenha o texto quando ele for necessário para entender
+o efeito. Ícones também podem acompanhar comandos do cabeçalho.
+
+Formulários podem declarar `formGroups: [{ title, fields }]`. `initialValues` fornece o
+rascunho inicial; esse rascunho não precisa passar na validação antes do preenchimento.
+Os nomes dos campos devem existir no contrato, e ActionForm valida o envio. Bindings de
+input explícitos têm precedência sobre o rascunho.
+
+Registre controles e conteúdos específicos com `bindPresentationComponent(contract, render)`
+em `runtime.components`. O retorno do render é conteúdo React; hooks pertencem aos componentes
+retornados. O componente recebe contexto, input e controles de fechar a superfície e o aside.
+Use esses vínculos em slots ou em `body: { component, contract, input }`. O vínculo verifica
+acesso, mas não executa a action automaticamente. A estrutura da página permanece no JSON.
+
+Rotas com `record` podem declarar `alternatives` com condições e outra apresentação de mesma
+superfície, sem alternativas encadeadas. Isso permite preservar endereços legados que passam
+a abrir uma consulta conforme o registro. O host deve verificar a permissão do destino antes
+de montá-lo. `record.fallbackFields` identifica dados transitórios necessários a fluxos como
+criar e abrir permissões: o host aceita somente o retorno em memória, nunca parâmetros da URL.
+
+### Conta externa e navegação com filtros
+
+Use `externalSource` para ler dados de uma integração que já possua cliente próprio, como um
+provedor de identidade. Registre seu `load(input, { signal })` em `recordSources`. O renderer
+trata carga, falha e repetição, ignora respostas canceladas e verifica o acesso antes da leitura.
+O JSON contém apenas o identificador do adaptador. Não combine esse modo com `source`.
+
+Controles externos usam `bindPresentationContent`. Um formulário específico pode declarar
+`body.footer: true`, renderizar suas ações em `footerTarget` e informar seu envio por
+`onBusyChange`; a moldura continua pertencendo à apresentação. Actions Opus continuam usando
+`ActionForm` e seus contratos. Para navegação sem execução, declare `links` com identificador,
+rótulo, apresentação de destino, posição e bindings de input. Links de seção também usam
+`ghost` e aceitam `icon` do registro runtime; nesse caso, `label` fica no tooltip e no
+nome acessível. Declare `showLabel: true` para combinar ícone e texto visível.
+
+Em detalhes abertos na mesma URL da lista, declare, por exemplo,
+`route.query: { "param": "customer", "input": "id" }`. O host passa os parâmetros de busca a
+`matchPresentationRoute` e combina o caminho gerado com os filtros existentes. Ao fechar,
+remove o parâmetro de seleção. `body.rowKey` define a identidade da linha quando a chave pública
+da coleção difere de `id`, como em listas de revisões.
+
+
+### Conteúdo próprio em listas e regiões de trabalho
+
+Para apresentar os resultados em cards ou outra composição, declare
+`body.collection: "catalog.cards"` e registre o adaptador em `runtime.collections`
+com `bindPresentationCollection(contract, (items, controls) => ...)`.
+O ActionList conserva busca, estados e paginação; `items` contém a página atual.
+Use `controls.canOpen(item)` e `controls.onOpen(item)` para respeitar os destinos
+autorizados do JSON, e `controls.actions(item)` para manter os comandos declarados.
+`controls.refetch()` atualiza a consulta. O adaptador deve oferecer foco e nome
+acessível aos controles que desenhar.
+
+`body.rowContent` referencia `compositionRuntime.rowContent`, registrado com
+`bindPresentationRowContent(listContract, render)`. Use para uma linha específica do domínio;
+comandos declarados por linha continuam disponíveis. `body.toolbarContent` referencia uma
+entrada de `listContent`, registrada com `bindPresentationListContent`. Ambos precisam pertencer
+à mesma list action. Estados, busca e paginação continuam no ActionList.
+
+Uma seção `kind: "content"` pode declarar `layout: "fill"` para um canvas ocupar a altura restante.
+Use junto de `page.layout: "fill"`; `page.flush: true` deixa o conteúdo controlar seu recuo.
+`header.description` referencia um slot quando a orientação depende do registro carregado.
+
+`body.tabs` aceita `framed` e `distribution` (`content` ou `equal`), encaminhados ao Tabs nativo.
+O modo embedded mantém o contexto das abas mesmo sem renderizar o heading da página.
+`width: "wide"` também se aplica a Drawer; abrir seu assistente pode ampliar a superfície.
+
+Comandos podem declarar `successMessage`, apresentada somente após a operação bem-sucedida.
+Ela entra no inventário de copy como mensagem de sucesso; não substitui erro nem confirmação.
+
+Em rotas, `params` limita valores de parâmetros do caminho. `query` pode ser um seletor ou uma
+lista de seletores `{ param, input }`; todos precisam estar presentes para selecionar a rota.
+Os nomes de busca e seus destinos de binding devem ser distintos, inclusive dos parâmetros do
+caminho. A geração da URL também valida as restrições declaradas.
+
+Ao fornecer uma Page completa por `heading: "content"`, mantenha a Page montada também
+durante carregamento ou Suspense. Use PageState dentro dela para os estados integrais;
+o renderer precisa dessa estrutura para integrar cabeçalho e ações.
+
+No modo `embedded`, o formulário conserva seu botão de envio e ações declaradas ficam
+junto ao conteúdo da aba. O título e o retorno pertencem à página que hospeda as abas.
+`successMessage` substitui a notificação de comandos diretos; comandos com `target` usam
+o resultado e a mensagem do formulário de destino.

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

@@ -14,7 +14,7 @@ com regiões. A orientação horizontal fica entre blocos empilhados e ocupa tod
 
 Não use `Separator` entre cabeçalho, corpo e rodapé de [`Surface`](/ui/surface), [`Dialog`](/ui/dialog) ou
 [`Drawer`](/ui/drawer). Nessas superfícies, os divisores são derivados das regiões presentes: use
-`layout="sectioned"` no componente raiz.
+a composição das regiões no componente raiz.
 
 ## Vertical