@softize/opus 17.2.0 → 18.0.0

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

@@ -1,23 +1,24 @@
 ## Esqueleto de página
 
-Use `Page` para manter título, ações, estado e conteúdo na mesma anatomia. Sozinha, ela apresenta
-`PageHeader` dentro do container. Quando a aplicação possui uma barra persistente, envolva a rota
-com `PageShell`: o shell fornece a navegação, a página projeta as ações na barra e o título inicia
-o conteúdo.
+Use `Page` para manter chrome, introdução, estado e conteúdo na mesma anatomia. `PageHeader`
+declara navegação e ações globais; `PageIntro` apresenta um título introdutório quando ele for
+necessário. Quando a aplicação possui uma barra persistente, `PageShell` projeta os slots do
+`PageHeader` nessa barra.
 
-`PageHeader` mantém navegação, título e ações na mesma linha. O container é centralizado e ocupa a
+Fora do shell, `PageHeader` também pode receber `PageTitle`. O container é centralizado e ocupa a
 largura disponível até `80rem` (`max-w-7xl`). Use `className` somente quando a composição pedir
 outro teto ou largura total.
 
 A forma curta é o padrão para páginas comuns. Fora de `PageShell`, ela cria `PageHeader` e
-`PageBody`. Dentro dele, cria `PageIntro` e `PageBody`: o título fica na introdução e as ações são
-projetadas na barra. A forma explícita segue a mesma anatomia, sem duplicar o título ao lado do
-breadcrumb.
+`PageBody`. Dentro dele, cria `PageHeader` para as ações, `PageIntro` para o título e `PageBody`.
+A forma explícita exige exatamente um heading principal. Use `PageTitle` no header ou intro,
+`Content level={1}` no body, ou deixe um `PageState` ativo assumir esse papel. Assim, header e
+introdução podem ser omitidos quando o próprio conteúdo nomeia a página.
 Contadores e outros indicadores pertencem ao
 conteúdo que os explica.
 
 `PageShell` não inclui sidebar nem inventa breadcrumb. Ele ocupa o painel principal já delimitado e
-mantém a barra com `3rem`, mesmo quando o conteúdo muda de estado. Tabs ficam reservados a recortes
+mantém a barra com `3.75rem`, mesmo quando o conteúdo muda de estado. Tabs ficam reservados a recortes
 da mesma superfície. Canvas e outros workspaces espaciais imersivos podem usar um shell próprio.
 
 Estados integrais de carregamento, falha ou ausência são compostos no body com `PageState`,
@@ -29,11 +30,7 @@ render(
   <div className="w-full overflow-hidden rounded-lg border border-border">
     <Page
       title="Workspaces"
-      actions={
-        <Button>
-          <Plus /> Novo workspace
-        </Button>
-      }
+      actions={<Button variant="outline">Exportar</Button>}
     >
       <div className="rounded-lg border border-dashed border-border p-10 text-center text-sm text-muted-foreground">
         O conteúdo da página (tabela, cards, grid…).
@@ -65,9 +62,10 @@ posição introdutória sem transformar a trilha em ação.
 
 ## Barra persistente do shell
 
-Use `PageShell` quando o shell conhece o breadcrumb e a rota conhece título e ações. Não crie um
-`PaneHeader` paralelo nem esconda slots de `Page` com CSS. O Opus mantém o `PageTitle` no início do
-conteúdo e projeta somente navegação contextual e `PageActions` na barra.
+Use `PageShell` quando o shell conhece o breadcrumb e a rota conhece ações globais ou uma
+introdução. Não crie um `PaneHeader` paralelo nem esconda slots de `Page` com CSS. O Opus projeta
+`PageNavigation`, `PageBack` e `PageActions` do `PageHeader` na barra; `PageIntro` permanece no
+conteúdo.
 
 ```tsx preview col
 <PageShell
@@ -81,14 +79,7 @@ conteúdo e projeta somente navegação contextual e `PageActions` na barra.
     </Breadcrumb>
   }
 >
-  <Page
-    title="Clientes"
-    actions={
-      <Button>
-        <Plus /> Novo cliente
-      </Button>
-    }
-  >
+  <Page title="Clientes" actions={<Button variant="outline">Exportar</Button>}>
     Conteúdo da listagem.
   </Page>
 </PageShell>
@@ -97,16 +88,19 @@ conteúdo e projeta somente navegação contextual e `PageActions` na barra.
 A barra permanece visível durante `PageState`; uma introdução opcional desaparece. Se uma ação não
 puder ser executada sem o conteúdo, a própria rota deve omiti-la naquele estado.
 
-Na composição explícita dentro do shell, use `PageIntro` e `PageBody`:
+Na composição explícita, combine somente as regiões necessárias. Este exemplo usa o header para
+uma ação global e o intro para o título:
 
 ```tsx preview col
 <PageShell navigation={<Breadcrumb>...</Breadcrumb>}>
   <Page>
-    <PageIntro>
-      <PageTitle>Clientes</PageTitle>
+    <PageHeader>
       <PageActions>
-        <Button>Novo cliente</Button>
+        <Button>Exportar</Button>
       </PageActions>
+    </PageHeader>
+    <PageIntro>
+      <PageTitle>Clientes</PageTitle>
     </PageIntro>
     <PageBody>Conteúdo da listagem.</PageBody>
   </Page>
@@ -124,9 +118,7 @@ render(
     <PageHeader>
       <PageTitle>Workspaces</PageTitle>
       <PageActions>
-        <Button>
-          <Plus /> Novo workspace
-        </Button>
+        <Button variant="outline">Exportar</Button>
       </PageActions>
     </PageHeader>
     <PageBody>
@@ -138,9 +130,10 @@ render(
 );
 ```
 
-Fora de `PageShell`, use `PageIntro` somente quando o conteúdo precisar de uma introdução em vez do
-header convencional. Dentro do shell, ele é a região estrutural do título e não deve ser combinado
-com `PageHeader`.
+Fora de `PageShell`, use `PageIntro` quando o conteúdo precisar de uma introdução separada do
+chrome. Dentro do shell, ele pode ser combinado com `PageHeader`: o primeiro permanece no conteúdo
+e o segundo alimenta a barra. Em uma página de listagem, `Content` pode fornecer o título e as ações
+da coleção, deixando `Page` apenas com `PageBody`.
 
 ## Estados integrais
 
@@ -189,12 +182,12 @@ estado na própria seção com `DataState`, `ActionView`, `ActionList` ou `Alert
 
 ## Propriedades de Page
 
-| Propriedade   | Tipo        | Padrão      | Descrição                                                                                       |
-| ------------- | ----------- | ----------- | ----------------------------------------------------------------------------------------------- |
-| `title`       | `ReactNode` |             | O h1 da página.                                                                                 |
-| `actions`     | `ReactNode` |             | Ações contextuais no extremo oposto do cabeçalho; em telas estreitas, ficam abaixo do contexto. |
-| `className`   | `string`    | `max-w-7xl` | Classes do container para substituir o teto padrão de `80rem`.                                  |
-| `children`    | `ReactNode` |             | O body da página — espaçamento e diagramação são seus.                                          |
+| Propriedade | Tipo        | Padrão      | Descrição                                                                                       |
+| ----------- | ----------- | ----------- | ----------------------------------------------------------------------------------------------- |
+| `title`     | `ReactNode` |             | O h1 da página.                                                                                 |
+| `actions`   | `ReactNode` |             | Ações contextuais no extremo oposto do cabeçalho; em telas estreitas, ficam abaixo do contexto. |
+| `className` | `string`    | `max-w-7xl` | Classes do container para substituir o teto padrão de `80rem`.                                  |
+| `children`  | `ReactNode` |             | O body da página — espaçamento e diagramação são seus.                                          |
 
 ## Propriedades de PageShell
 
@@ -209,18 +202,18 @@ estado na própria seção com `DataState`, `ActionView`, `ActionList` ou `Alert
 
 ## Propriedades de PageIntro
 
-| Propriedade | Tipo                          | Descrição                                                     |
-| ----------- | ----------------------------- | ------------------------------------------------------------- |
-| `children`  | `ReactNode`                   | Título e ações da página dentro de `PageShell`, ou introdução de uma página isolada. |
-| `className` | `string`                      | Classes adicionais da região introdutória.                    |
-| demais      | Atributos de `HTMLDivElement` | Atributos nativos repassados à região introdutória.           |
+| Propriedade | Tipo                          | Descrição                                                             |
+| ----------- | ----------------------------- | --------------------------------------------------------------------- |
+| `children`  | `ReactNode`                   | Título introdutório e, quando necessário, ações ligadas à introdução. |
+| `className` | `string`                      | Classes adicionais da região introdutória.                            |
+| demais      | Atributos de `HTMLDivElement` | Atributos nativos repassados à região introdutória.                   |
 
 ## Propriedades de PageHeader
 
-| Propriedade | Tipo        | Descrição                                                                           |
-| ----------- | ----------- | ----------------------------------------------------------------------------------- |
-| `className` | `string`    | Classes adicionais da região externa do cabeçalho.                                  |
-| `children`  | `ReactNode` | Um `PageTitle` e, opcionalmente, `PageBack` ou `PageNavigation` e ações. |
+| Propriedade | Tipo        | Descrição                                                                                |
+| ----------- | ----------- | ---------------------------------------------------------------------------------------- |
+| `className` | `string`    | Classes adicionais da região externa do cabeçalho.                                       |
+| `children`  | `ReactNode` | `PageBack` ou `PageNavigation`, `PageActions` e, fora do shell, um `PageTitle` opcional. |
 
 ## Propriedades de PageBack
 

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

@@ -5,21 +5,24 @@ cabeçalho, body e rodapé.
 Dialog e Drawer mantêm no cabeçalho a ordem horizontal de navegação ou retorno, título e ações.
 O retorno aparece em uma surface modal somente
 quando ela foi aberta sobre outro Dialog ou Drawer; a Page ao fundo sustenta o modal, mas não cria
-uma etapa de navegação. Formulários modais encerram o footer com `Cancelar` e a ação principal.
-Em Page hospedada por `PageShell`, a barra concentra navegação e ações, enquanto o título abre o
-conteúdo em um `PageIntro`. Assim o breadcrumb não disputa espaço nem repete o título na mesma linha.
-Ações textuais de header e footer usam o tamanho `default`, pois pertencem à decisão da superfície;
-o tamanho `sm` permanece reservado às operações densas de toolbar, seção e coleção. Contexto e
-variante continuam definindo hierarquia visual sem alterar essa medida.
+uma etapa de navegação. Formulários modais encerram o footer dividido igualmente entre `Cancelar`
+em `outline` e a ação principal.
+Em Page hospedada por `PageShell`, a barra concentra navegação e ações globais. Uma Presentation
+de listagem materializa título e comandos de header no `Content` que envolve o `ActionList`; assim
+a criação permanece próxima da coleção. Esses comandos usam `default`. Nas demais Presentations, o
+título abre o conteúdo em `PageIntro` e comandos da superfície usam `default`.
 
 Use esse padrão quando uma lista puder abrir um detalhe lateral, quando a mesma edição precisar
 funcionar em modal e em rota própria ou quando um fluxo começar compacto e crescer sem ganhar uma
 segunda implementação.
 
 Dentro de `PageShell`, a superfície `page` usa a anatomia real da aplicação: a Presentation projeta
-navigation e actions no header da barra, apresenta o título em `PageIntro` e compõe `PageBody` e,
-quando necessário, `PageFooter`.
-Fora do shell, ela materializa o `PageHeader` completo para exemplos e superfícies independentes.
+navigation e actions globais por `PageHeader`, mantém a introdução no conteúdo quando existir e
+compõe `PageBody` e, quando necessário, `PageFooter`. Para uma action `list`, `PageBody` recebe
+`Content + ActionList`; o header da coleção recebe o título e os comandos declarados no placement
+`header`. Dialog e Drawer continuam usando o header da própria superfície.
+Os comandos da coleção ficam no extremo oposto ao título e permanecem textuais, mesmo quando a
+action declara um ícone. A criação usa `Criar recurso`, sem ícone, em um botão `default`.
 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.
 
@@ -27,7 +30,7 @@ shell que efetivamente hospeda a rota.
 const workspaceUpdate = defineContract({
   name: "workspace.update",
   kind: "form",
-  label: "Salvar workspace",
+  label: "Editar workspace",
   input: z.object({ name: z.string() }),
   output: z.object({ id: z.string() }),
   fields: { name: { label: "Nome" } },
@@ -36,7 +39,7 @@ const workspaceUpdate = defineContract({
 const workspacePresentation = definePresentation({
   schemaVersion: 1,
   id: "workspace.update",
-  title: "Workspace",
+  title: "Editar workspace",
   body: { action: workspaceUpdate.name },
 });
 
@@ -92,16 +95,23 @@ render(<Example />);
 
 `definePresentation` cria o artefato serializável. O body recebe uma action `form`, `list` ou
 `view`; uma action `simple` aparece como comando no cabeçalho ou no rodapé. Em formulário,
-`body.submitLabel` nomeia a ação conforme o resultado esperado, como “Criar departamento” ou
-“Salvar alterações”. Actions que precisam de
+`body.submitLabel` sobrescreve o padrão “Salvar” quando a operação tem outro resultado observável,
+como “Renomear” ou “Criar nova versão”. Actions que precisam de
 interface abrem outra Presentation. Bindings fornecem valores vindos da rota, do registro, da
 seleção, da sessão ou do resultado anterior sem guardar callbacks no JSON.
 
+Quando a exibição precisa sobreviver a refresh, deep link ou histórico, declare `route` na própria
+Presentation. O `path` aceita segmentos fixos e parâmetros como `:id`; `surface` determina como a
+URL abre o recurso. Em uma rota de edição, `record` indica qual Presentation de lista fornece o
+registro e qual campo corresponde ao parâmetro. Um adaptador de rota pode então reconstruir a
+invocação sem repetir uma árvore condicional no componente da página.
+
 ```ts
 const workspaceList = definePresentation({
   schemaVersion: 1,
   id: "workspace.list",
   title: "Workspaces",
+  route: { path: "/workspaces", surface: "page" },
   body: {
     action: "workspace.list",
     open: {
@@ -141,8 +151,9 @@ const invocation = definePresentationInvocation({
 
 `openPresentation` empilha a exibição atual; `backPresentation` restaura o frame anterior.
 `closePresentation` encerra dialog ou drawer e recusa page. Efeitos `navigate` escolhem `push` ou
-`replace`. A aplicação sincroniza a invocação com a URL apenas quando ela precisar sobreviver a
-refresh, deep link ou histórico.
+`replace`. `matchPresentationRoute` resolve a definição e os parâmetros de uma URL declarada;
+`pathForPresentationInvocation` faz o caminho inverso. A aplicação continua responsável apenas por
+ligar esse estado ao router que hospeda a Presentation.
 
 ## Inspecionar o JSON
 
@@ -154,19 +165,19 @@ no manifest e concentre a inspeção na Lens em vez de criar um launcher flutuan
 
 ## Propriedades de Presentation
 
-| Propriedade          | Tipo                                      | Padrão | Descrição                                                   |
-| -------------------- | ----------------------------------------- | ------ | ----------------------------------------------------------- |
-| `definition`         | `PresentationDefinition`                  |        | Artefato estático que descreve o recurso.                   |
-| `definitions`        | `PresentationDefinition[]`                |        | Registry alcançável por navegação, abertura e retorno.      |
-| `actions`            | `PresentationActionRegistry`              |        | Contratos compartilháveis referenciados pelo artefato.      |
-| `invocation`         | `PresentationInvocation`                  |        | Surface, input e pilha da exibição atual.                   |
-| `bindingContext`     | `PresentationBindingContext`              |        | Rota, item, seleção, sessão e resultado disponíveis.        |
-| `onInvocationChange` | `(next: PresentationInvocation \| null) => void` |        | Recebe navegação, retorno e fechamento.                     |
-| `onRefresh`          | `(action: string \| null) => void`        |        | Recebe invalidações declaradas após sucesso.                |
-| `open`               | `boolean`                                 | `true` | Estado controlado de Dialog ou Drawer.                      |
-| `onOpenChange`       | `(open: boolean) => void`                 |        | Notifica abertura e fechamento da superfície modal.         |
-| `className`          | `string`                                  |        | Classes adicionais da superfície.                           |
-| `bodyClassName`      | `string`                                  |        | Classes adicionais do body, aplicadas uma única vez.        |
+| Propriedade          | Tipo                                             | Padrão | Descrição                                              |
+| -------------------- | ------------------------------------------------ | ------ | ------------------------------------------------------ |
+| `definition`         | `PresentationDefinition`                         |        | Artefato estático que descreve o recurso.              |
+| `definitions`        | `PresentationDefinition[]`                       |        | Registry alcançável por navegação, abertura e retorno. |
+| `actions`            | `PresentationActionRegistry`                     |        | Contratos compartilháveis referenciados pelo artefato. |
+| `invocation`         | `PresentationInvocation`                         |        | Surface, input e pilha da exibição atual.              |
+| `bindingContext`     | `PresentationBindingContext`                     |        | Rota, item, seleção, sessão e resultado disponíveis.   |
+| `onInvocationChange` | `(next: PresentationInvocation \| null) => void` |        | Recebe navegação, retorno e fechamento.                |
+| `onRefresh`          | `(action: string \| null) => void`               |        | Recebe invalidações declaradas após sucesso.           |
+| `open`               | `boolean`                                        | `true` | Estado controlado de Dialog ou Drawer.                 |
+| `onOpenChange`       | `(open: boolean) => void`                        |        | Notifica abertura e fechamento da superfície modal.    |
+| `className`          | `string`                                         |        | Classes adicionais da superfície.                      |
+| `bodyClassName`      | `string`                                         |        | Classes adicionais do body, aplicadas uma única vez.   |
 
 ## Propriedades de PresentationInspector
 

package/src/ui/docs/doc-client.tsx

@@ -49,7 +49,7 @@ const workspaceStatus = attachLogicalType(z.enum(STATUS), docWorkspaceStatus)
 export const docWorkspaceCreate = defineContract({
   name: 'workspace.create',
   kind: 'form',
-  label: 'Novo workspace',
+  label: 'Criar workspace',
   messages: { success: 'Workspace criado', error: 'Falha ao criar workspace' },
   input: z.object({
     name: z.string().min(2).max(120),

package/src/ui/meta.ts

@@ -117,7 +117,7 @@ export const componentMeta = {
     name: "content-header",
     ancestry: "opus",
     whenToUse:
-      "Estruture uma região de conteúdo com título, contador, descrição e ações. No caso comum, declare esses valores diretamente em Content; componha ContentHeader apenas quando precisar controlar a anatomia. Contadores pertencem a Content e não ao título da Page.",
+      "Estruture uma região de conteúdo com título, contador, descrição e ações. No caso comum, declare esses valores diretamente em Content; componha ContentHeader apenas quando precisar controlar a anatomia. Em coleções, Content mantém título e criação junto do ActionList. Contadores pertencem a Content e não ao título da Page.",
   },
   copyable: {
     name: "copyable",
@@ -382,7 +382,7 @@ export const componentMeta = {
     name: "action-list",
     ancestry: "opus",
     whenToUse:
-      "Apresente uma coleção pesquisável a partir de uma ListAction. O contrato declara colunas, filtros, período e busca; ActionList coordena visualizações, paginação, seleção em lote e sincronização com a URL. Para um único recurso, use ActionView.",
+      "Apresente uma coleção pesquisável a partir de uma ListAction. O contrato declara colunas, filtros, período e busca; ActionList coordena visualizações, paginação, seleção em lote e sincronização com a URL. Em uma página, envolva a lista com Content para manter título e criação junto da coleção. Para um único recurso, use ActionView.",
   },
   "action-trigger": {
     name: "action-trigger",
@@ -400,13 +400,13 @@ export const componentMeta = {
     name: "page",
     ancestry: "opus",
     whenToUse:
-      "O esqueleto de página do back-office: <main> + container centralizado com teto padrão de 80rem (`max-w-7xl`). O shorthand cobre título e ações. Quando shell e rota conhecem partes diferentes da página, PageShell mantém a barra de 3rem, recebe a navegação e projeta as ações da Page; o título inicia o conteúdo em PageIntro. Fora do shell, a forma explícita usa PageHeader para o cabeçalho completo. PageActionsTarget fica restrito a workspaces imersivos sem PageShell. PageState oculta somente PageIntro; informações importantes entram no corpo como Alert ou texto. Para uma região disponível à criação ou vínculo, use Empty.",
+      "O esqueleto de página do back-office: <main> + container centralizado com teto padrão de 80rem (`max-w-7xl`). PageHeader declara navegação e ações globais; PageIntro é a introdução opcional; PageBody recebe o conteúdo. PageShell mantém a barra de 3.75rem e projeta os slots do PageHeader. Uma região interna pode fornecer o heading principal com Content. PageActionsTarget fica restrito a workspaces imersivos sem PageShell. PageState oculta PageIntro; informações importantes entram no corpo como Alert ou texto. Para uma região disponível à criação ou vínculo, use Empty.",
   },
   presentation: {
     name: "presentation",
     ancestry: "opus",
     whenToUse:
-      "Descreva um recurso que precisa manter a mesma anatomia ao aparecer como Page, Dialog ou Drawer. Presentation organiza navegação, título, ações de cabeçalho, body e ações de rodapé sem redefinir o conteúdo para cada superfície. A definição persistente liga esses slots a actions Opus; a invocação carrega o estado JSON da execução. PresentationInspector abre um snapshot isolado, enquanto a Lens apresenta o inventário estático projetado no manifest.",
+      "Descreva um recurso que precisa manter a mesma anatomia ao aparecer como Page, Dialog ou Drawer. Presentation organiza navegação, título, ações de cabeçalho, body e ações de rodapé sem redefinir o conteúdo para cada superfície. Em Page de listagem, Content mantém título e ações junto do ActionList; modais usam o header da superfície. Route pode declarar URL, surface e origem do registro para deep links. A definição persistente liga esses slots a actions Opus; a invocação carrega o estado JSON da execução. PresentationInspector abre um snapshot isolado, enquanto a Lens apresenta o inventário estático projetado no manifest.",
   },
   router: {
     name: "router",