@softize/opus 16.1.0 → 17.1.0

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

@@ -2,17 +2,16 @@
 
 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 fornece as ações e o título passa a
-`PageIntro` dentro do conteúdo.
+com `PageShell`: o shell fornece a navegação e a página projeta título e ações na barra.
 
 `PageHeader` mantém navegação, título e ações na mesma linha. 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`, enquanto envia as ações para a barra. A forma
-explícita permite escolher a região adequada: `PageHeader` reúne navegação e contexto; `PageIntro`
-dá mais presença ao título dentro do conteúdo. Contadores e outros indicadores pertencem ao
+`PageBody`. Dentro dele, cria `PageHeader` e `PageBody`, projetando o header na barra. A forma
+explícita permite acrescentar um `PageIntro` opcional no conteúdo sem duplicar o título estrutural.
+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
@@ -28,7 +27,6 @@ render(
   <div className="w-full overflow-hidden rounded-lg border border-border">
     <Page
       title="Workspaces"
-      description="Ambientes compartilhados pela equipe."
       actions={
         <Button>
           <Plus /> Novo workspace
@@ -54,7 +52,6 @@ controle aparece antes do título como ícone com nome acessível e tooltip deri
   <PageHeader>
     <PageBack href="/customers">Clientes</PageBack>
     <PageTitle>Qualidade da base</PageTitle>
-    <PageDescription>Revise conflitos e canais de contato.</PageDescription>
   </PageHeader>
   <PageBody>Conteúdo da análise.</PageBody>
 </Page>
@@ -67,8 +64,8 @@ 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 projeta `PageActions` na barra e
-transforma a introdução da forma curta em `PageIntro`.
+`PaneHeader` paralelo nem esconda slots de `Page` com CSS. O Opus projeta `PageTitle` e
+`PageActions` na barra.
 
 ```tsx preview col
 <PageShell
@@ -85,7 +82,7 @@ transforma a introdução da forma curta em `PageIntro`.
   <Page
     title="Clientes"
     actions={
-      <Button size="sm">
+      <Button>
         <Plus /> Novo cliente
       </Button>
     }
@@ -95,21 +92,20 @@ transforma a introdução da forma curta em `PageIntro`.
 </PageShell>
 ```
 
-A barra permanece visível durante `PageState`; somente a introdução desaparece. Se uma ação não
+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 dentro do shell, use `PageHeader` e `PageBody`:
 
 ```tsx preview col
 <PageShell navigation={<Breadcrumb>...</Breadcrumb>}>
   <Page>
-    <PageIntro>
+    <PageHeader>
       <PageTitle>Clientes</PageTitle>
-      <PageDescription>Cadastros disponíveis para atendimento.</PageDescription>
       <PageActions>
-        <Button size="sm">Novo cliente</Button>
+        <Button>Novo cliente</Button>
       </PageActions>
-    </PageIntro>
+    </PageHeader>
     <PageBody>Conteúdo da listagem.</PageBody>
   </Page>
 </PageShell>
@@ -125,7 +121,6 @@ render(
   <Page>
     <PageHeader>
       <PageTitle>Workspaces</PageTitle>
-      <PageDescription>Ambientes compartilhados pela equipe.</PageDescription>
       <PageActions>
         <Button>
           <Plus /> Novo workspace
@@ -141,9 +136,8 @@ render(
 );
 ```
 
-Use `PageIntro` no lugar de `PageHeader` quando a página precisar apenas de uma introdução no
-conteúdo, sem navegação própria. Dentro de `PageShell`, essa é a única composição explícita válida;
-fora dele, as duas formas são aceitas porque cumprem papéis diferentes.
+Use `PageIntro` somente quando o conteúdo precisar de uma introdução adicional. Ele não substitui
+o `PageHeader`, não repete o título da página e pode ser omitido.
 
 ## Estados integrais
 
@@ -195,7 +189,6 @@ estado na própria seção com `DataState`, `ActionView`, `ActionList` ou `Alert
 | Propriedade   | Tipo        | Padrão      | Descrição                                                                                       |
 | ------------- | ----------- | ----------- | ----------------------------------------------------------------------------------------------- |
 | `title`       | `ReactNode` |             | O h1 da página.                                                                                 |
-| `description` | `ReactNode` |             | Linha de contexto sob o título (ex.: "N no total · X ativos").                                  |
 | `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.                                          |
@@ -215,7 +208,7 @@ estado na própria seção com `DataState`, `ActionView`, `ActionList` ou `Alert
 
 | Propriedade | Tipo                          | Descrição                                                     |
 | ----------- | ----------------------------- | ------------------------------------------------------------- |
-| `children`  | `ReactNode`                   | Um `PageTitle` e, opcionalmente, `PageBack` ou `PageNavigation`, descrição e ações. |
+| `children`  | `ReactNode`                   | Conteúdo introdutório opcional do body.                       |
 | `className` | `string`                      | Classes adicionais da região introdutória.                    |
 | demais      | Atributos de `HTMLDivElement` | Atributos nativos repassados à região introdutória.           |
 
@@ -224,7 +217,7 @@ estado na própria seção com `DataState`, `ActionView`, `ActionList` ou `Alert
 | Propriedade | Tipo        | Descrição                                                                           |
 | ----------- | ----------- | ----------------------------------------------------------------------------------- |
 | `className` | `string`    | Classes adicionais da região externa do cabeçalho.                                  |
-| `children`  | `ReactNode` | Um `PageTitle` e, opcionalmente, `PageBack` ou `PageNavigation`, descrição e ações. |
+| `children`  | `ReactNode` | Um `PageTitle` e, opcionalmente, `PageBack` ou `PageNavigation` e ações. |
 
 ## Propriedades de PageBack
 
@@ -252,14 +245,6 @@ estado na própria seção com `DataState`, `ActionView`, `ActionList` ou `Alert
 | `className` | `string`                          | Classes adicionais do título.                   |
 | demais      | Atributos de `HTMLHeadingElement` | Atributos nativos repassados ao heading.        |
 
-## Propriedades de PageDescription
-
-| Propriedade | Tipo                                | Descrição                                  |
-| ----------- | ----------------------------------- | ------------------------------------------ |
-| `children`  | `ReactNode`                         | Contexto apresentado abaixo do título.     |
-| `className` | `string`                            | Classes adicionais da descrição.           |
-| demais      | Atributos de `HTMLParagraphElement` | Atributos nativos repassados ao parágrafo. |
-
 ## Propriedades de PageActions
 
 | Propriedade | Tipo                          | Descrição                                  |

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

@@ -1,25 +1,55 @@
-`Presentation` preserva a identidade de um recurso quando a experiência pede uma página, um dialog ou
+`Presentation` preserva a identidade de um recurso quando o contexto pede uma página, um dialog ou
 um drawer. A superfície decide quanto espaço ocupar; o recurso continua com a mesma navegação,
 cabeçalho, body e rodapé.
 
-Nas três superfícies, o cabeçalho usa a mesma ordem horizontal: navegação ou retorno, título e ações.
-Dialog e Drawer acrescentam o fechamento ao final. Uma Page pode apresentar um `PageIntro` separado
-no body quando o conteúdo realmente precisar de uma introdução; ele não substitui nem duplica o
-título estrutural da Presentation.
+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.
 
 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: o shell preserva sua
-barra, e a Presentation compõe `Page`, `PageIntro`, `PageBody` e, quando necessário, `PageFooter`.
+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.
 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.
 
 ```tsx live
+const workspaceUpdate = defineContract({
+  name: "workspace.update",
+  kind: "form",
+  label: "Salvar workspace",
+  input: z.object({ name: z.string() }),
+  output: z.object({ id: z.string() }),
+  fields: { name: { label: "Nome" } },
+});
+
+const workspacePresentation = definePresentation({
+  schemaVersion: 1,
+  id: "workspace.update",
+  title: "Workspace",
+  body: { action: workspaceUpdate.name },
+});
+
 function Example() {
-  const [surface, setSurface] = React.useState("page");
+  const [open, setOpen] = React.useState(true);
+  const [invocation, setInvocation] = React.useState(() =>
+    definePresentationInvocation({
+      schemaVersion: 1,
+      presentationId: workspacePresentation.id,
+      surface: "page",
+      input: {},
+    }),
+  );
 
   return (
     <div className="space-y-4">
@@ -28,8 +58,11 @@ function Example() {
           <Button
             key={value}
             size="sm"
-            variant={surface === value ? "solid" : "outline"}
-            onClick={() => setSurface(value)}
+            variant={invocation.surface === value ? "solid" : "outline"}
+            onClick={() => {
+              setInvocation({ ...invocation, surface: value });
+              setOpen(true);
+            }}
           >
             {value}
           </Button>
@@ -37,25 +70,17 @@ function Example() {
       </ButtonGroup>
 
       <Presentation
-        surface={surface}
-        title="Workspace"
-        headerActions={
-          <Button size="sm" variant="ghost">
-            Arquivar
-          </Button>
-        }
-        footerActions={
-          <>
-            <Button variant="outline">Cancelar</Button>
-            <Button context="primary">Salvar</Button>
-          </>
-        }
-      >
-        <Content title="Dados gerais">
-          O renderer injeta aqui o formulário, a lista ou a visualização ligada
-          à action.
-        </Content>
-      </Presentation>
+        definition={workspacePresentation}
+        definitions={[workspacePresentation]}
+        actions={{ [workspaceUpdate.name]: workspaceUpdate }}
+        invocation={invocation}
+        open={invocation.surface === "page" || open}
+        onOpenChange={setOpen}
+        onInvocationChange={(next) => {
+          if (next) setInvocation(next);
+          else setOpen(false);
+        }}
+      />
     </div>
   );
 }
@@ -66,7 +91,9 @@ render(<Example />);
 ## A declaração
 
 `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é. Actions que precisam de
+`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
 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.
 
@@ -121,35 +148,25 @@ refresh, deep link ou histórico.
 
 `PresentationInspector` renderiza um botão somente com ícone. Ao acioná-lo, reúne definição,
 invocação, bindings resolvidos e diagnósticos em um único JSON e oferece a cópia do conteúdo. Chaves
-sensíveis são mascaradas. Use a ferramenta em ambientes de desenvolvimento ou no Studio; a Lens
-expõe somente a definição estática e a ferramenta não faz parte da navegação do recurso para a
-pessoa usuária.
-
-Use `floating` quando o inspetor precisar ficar disponível sem ocupar o cabeçalho. O componente
-aplica tamanho, forma, borda e elevação de FAB; `className` define a âncora na superfície consumidora.
-Reserve espaço para outros controles flutuantes do shell em vez de sobrepô-los.
-
-Quando várias Presentations puderem estar montadas ao mesmo tempo, envolva o shell com
-`PresentationDevtoolsProvider`, anuncie cada recurso com `usePresentationRegistration` e renderize
-um único `PresentationDevtools`. O launcher abre a lista ativa e só cria o snapshot mascarado depois
-que uma Presentation é escolhida. Monte os três exclusivamente em desenvolvimento: o inventário
-inclui definição, invocação, bindings resolvidos e diagnósticos que não pertencem à experiência de
-produção.
+sensíveis são mascaradas. Use a ferramenta em uma bancada de desenvolvimento ou na Lens; ela não
+faz parte da navegação do recurso para a pessoa usuária. Na aplicação final, publique as definições
+no manifest e concentre a inspeção na Lens em vez de criar um launcher flutuante no shell.
 
 ## Propriedades de Presentation
 
-| Propriedade     | Tipo                             | Padrão | Descrição                                                             |
-| --------------- | -------------------------------- | ------ | --------------------------------------------------------------------- |
-| `surface`       | `'page' \| 'dialog' \| 'drawer'` |        | Superfície que hospeda o recurso.                                     |
-| `title`         | `ReactNode`                      |        | Nome da Presentation no cabeçalho.                                    |
-| `navigation`    | `ReactNode`                      |        | Voltar ou navegação relativa, quando existir.                         |
-| `headerActions` | `ReactNode`                      |        | Comandos contextuais no cabeçalho.                                    |
-| `footerActions` | `ReactNode`                      |        | Comandos de progressão; Dialog e Drawer dividem a largura disponível. |
-| `children`      | `ReactNode`                      |        | Formulário, lista ou visualização do body.                            |
-| `open`          | `boolean`                        |        | Estado controlado de Dialog ou Drawer; omitido, começa aberto e fecha internamente. |
-| `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.                                           |
+| 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
 
@@ -161,28 +178,4 @@ produção.
 | `diagnostics`  | `PresentationDiagnostic[]` |                            | Diagnósticos da definição ou execução.    |
 | `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.             |
-| `floating`     | `boolean`                  | `false`                    | Apresenta o gatilho com aparência de FAB. |
 | `className`    | `string`                   |                            | Classes adicionais do gatilho.            |
-
-## Propriedades de PresentationDevtoolsProvider
-
-| Propriedade | Tipo        | Descrição                                  |
-| ----------- | ----------- | ------------------------------------------ |
-| `children`  | `ReactNode` | Árvore que registra Presentations ativas.  |
-
-## Parâmetros de usePresentationRegistration
-
-| Propriedade   | Tipo                         | Padrão | Descrição                                              |
-| ------------- | ---------------------------- | ------ | ------------------------------------------------------ |
-| `definition`  | `PresentationDefinition`     |        | Definição estática da Presentation.                    |
-| `invocation`  | `unknown`                    |        | Estado vivo serializável, quando existir.              |
-| `resolved`    | `unknown`                    |        | Bindings resolvidos pelo renderer.                     |
-| `diagnostics` | `PresentationDiagnostic[]`   |        | Diagnósticos da definição ou execução.                 |
-| `enabled`     | `boolean`                    | `true` | Mantém ou retira o recurso do inventário ativo.        |
-
-## Propriedades de PresentationDevtools
-
-| Propriedade    | Tipo     | Padrão                           | Descrição                                      |
-| -------------- | -------- | -------------------------------- | ---------------------------------------------- |
-| `triggerLabel` | `string` | `Inspecionar Presentations ativas` | Nome acessível e tooltip do launcher.         |
-| `className`    | `string` |                                  | Classes adicionais; o shell define a posição. |

package/src/ui/meta.ts

@@ -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, descrição 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; título e descrição formam PageIntro no conteúdo. Fora dele, a forma explícita escolhe PageHeader para o cabeçalho completo ou PageIntro para uma introdução sem navegação. PageActionsTarget fica restrito a workspaces imersivos sem PageShell. PageState oculta o header da Page isolada ou somente PageIntro dentro de PageShell. 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`). 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 e recebe navegação, título e ações da Page. PageIntro é um bloco opcional de introdução no conteúdo. 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.",
   },
   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 inspeciona um recurso; PresentationDevtools reúne as Presentations ativas do shell em desenvolvimento. Ambos materializam snapshots mascarados somente sob demanda.",
+      "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.",
   },
   router: {
     name: "router",

package/src/ui/react.tsx

@@ -420,20 +420,14 @@ export type { DataStateProps } from "./components/patterns/data-state.tsx";
 
 export {
   Presentation,
-  PresentationDevtools,
-  PresentationDevtoolsProvider,
   PresentationInspector,
-  usePresentationRegistration,
 } from "./components/patterns/presentation.tsx";
 export type {
   PresentationProps,
-  PresentationDevtoolsProps,
-  PresentationDevtoolsProviderProps,
   PresentationInspectorProps,
-  PresentationRegistration,
 } from "./components/patterns/presentation.tsx";
 
-// Esqueleto de página do back-office (main + container + header título/descrição/ação).
+// Esqueleto de página do back-office (main + container + header com navegação, título e ações).
 export {
   PageShell,
   Page,
@@ -442,7 +436,6 @@ export {
   PageNavigation,
   PageBack,
   PageTitle,
-  PageDescription,
   PageActions,
   PageActionsTarget,
   PageBody,