@softize/opus 17.0.0 → 17.1.0

package/CHANGELOG.md

@@ -7,6 +7,17 @@ Depois de qualquer bump, rode os gates (`typecheck` · `test` · `opus check` ·
 `opus copy --check` · `base copy check` · `manifest:check`) — eles apontam o que a
 mudança cobra do seu código.
 
+## 17.1.0 — 2026-09-12
+
+Formulários de `Presentation` em Dialog e Drawer passam a oferecer `Cancelar` ao lado da ação
+principal. O retorno no header modal aparece somente quando a surface anterior também é um Dialog
+ou Drawer; a Page mantida ao fundo não cria uma etapa de navegação.
+
+Em Page hospedada por `PageShell`, a `Presentation` mantém navegação e ações na barra e apresenta o
+título no `PageIntro`. Ações que abrem outra Presentation usam o botão default para assumir a
+hierarquia primária do fluxo. Ações textuais de header e footer usam o tamanho `default`; `sm` fica
+reservado às operações densas de toolbar, seção e coleção.
+
 ## 17.0.0 — 2026-09-11
 
 A inspeção de `Presentation` passa a pertencer exclusivamente à Lens, que lê as definições estáticas

package/docs/adr/0013-presentation-is-a-portable-action-oriented-artifact.md

@@ -19,11 +19,12 @@ capacidades em uma apresentação verificável.
 `Presentation` é o artefato declarativo que descreve um recurso independentemente da superfície em
 que aparece. `Surface` escolhe `page`, `dialog` ou `drawer` no momento da renderização.
 
-A anatomia portátil é `Header + Body + Footer?`. O header organiza horizontalmente
-`Navigation? + Title + Actions?`; o body contém o recurso; o footer contém ações de conclusão.
-Dialog e Drawer acrescentam o fechamento ao final das ações do header. Em Page, `PageShell` hospeda
-o mesmo header na barra persistente; uma introdução opcional pode existir no body sem mover nem
-duplicar o título estrutural.
+A anatomia portátil é `Header + Body + Footer?`, mas cada surface materializa seu header de acordo
+com o espaço disponível. Dialog e Drawer organizam horizontalmente
+`Navigation? + Title + Actions? + Close` e mantêm as ações de conclusão no footer. Em Page
+hospedada por `PageShell`, a barra persistente reúne navegação e ações; o título inicia o conteúdo
+em `PageIntro`, sem repetir a página atual ao lado do breadcrumb. Fora do shell, a Page materializa
+seu header completo no próprio container.
 
 Uma action assume um de dois papéis:
 
@@ -48,12 +49,15 @@ estática, publicável no manifest e inspecionável pela Lens. A invocação é
 uma execução: identifica a Presentation, escolhe a surface, carrega somente input JSON e mantém a
 pilha de frames necessária para voltar. Ela não é publicada no manifest.
 
-`back` restaura o último frame da pilha. `close` encerra apenas dialog ou drawer e é inválido para
-page. `navigate` abre outra invocação por push ou substitui a atual; sincronizar esse estado com URL
-é responsabilidade do adaptador da aplicação quando refresh, deep link ou histórico forem
-necessários. O inspetor de desenvolvimento reúne definição, invocação, bindings resolvidos e
-diagnósticos, mascarando chaves sensíveis antes de expor o JSON. O inventário estático e seu JSON
-ficam disponíveis na Lens; a aplicação não adiciona um launcher flutuante ao shell.
+`back` restaura o último frame da pilha. Em Dialog ou Drawer, ele só é apresentado quando o frame
+anterior também é modal; a Page mantida ao fundo não cria uma etapa intermediária. `close` encerra
+apenas dialog ou drawer e é inválido para page. Formulários modais oferecem `Cancelar` como ação de
+abandono no footer, ao lado da conclusão. `navigate` abre outra invocação por push ou substitui a
+atual; sincronizar esse estado com URL é responsabilidade do adaptador da aplicação quando refresh,
+deep link ou histórico forem necessários. O inspetor de desenvolvimento reúne definição,
+invocação, bindings resolvidos e diagnósticos, mascarando chaves sensíveis antes de expor o JSON. O
+inventário estático e seu JSON ficam disponíveis na Lens; a aplicação não adiciona um launcher
+flutuante ao shell.
 
 ## Consequências
 
@@ -90,6 +94,8 @@ Foi descartada porque compatibilidade exige delegar cada kind ao pattern canôni
 - o manifest projeta Presentations sem callbacks nem dados server-only;
 - a lens lista e expõe o JSON integral de cada Presentation;
 - testes de invocação cobrem push, replace, back, close e rejeição de input não JSON;
+- testes do renderer cobrem a ausência de retorno entre Page e modal, o retorno entre modais e as
+  ações Cancelar/concluir do formulário;
 - o inspetor mascara segredo, token, cookie, autorização, senha e chave de API;
 - a Lens lista as definições registradas e abre o JSON integral sem depender da árvore React;
 - uma aplicação consumidora usa o pacote local por symlink durante a migração página por página.

package/docs/adr/0015-action-size-follows-interaction-density.md

@@ -0,0 +1,64 @@
+# ADR 0015 — O tamanho da ação acompanha a densidade da interação
+
+- **Status:** aceita.
+- **Data:** 2026-09-12.
+
+## Contexto
+
+O uso de `default` e `sm` passou a variar entre headers de Page, footers de Dialog e Drawer,
+toolbars e ações de listagem. Como tamanho também era usado para sugerir importância, duas decisões
+equivalentes podiam ganhar alturas diferentes, enquanto ações repetitivas ocupavam o mesmo espaço
+de uma conclusão da superfície.
+
+O Opus já separa contexto semântico, variante visual e tamanho. Misturar esses eixos impede que a
+mesma regra funcione quando uma ação muda de secundária para primária ou quando um recurso troca de
+Page para Dialog ou Drawer.
+
+## Decisão
+
+O tamanho comunica densidade e alcance da interação; `context` e `variant` comunicam hierarquia e
+risco.
+
+- ações textuais que decidem a superfície usam `default`: header de Page e footer de Page, Dialog
+  ou Drawer;
+- ações operacionais em toolbar, header de seção ou coleção densa usam `sm`;
+- ações internas de linha, célula ou campo usam `xs` ou `icon-xs`;
+- ações somente com ícone que pertencem ao chrome da superfície, como voltar e fechar, usam
+  `icon-sm`;
+- `lg` fica reservado a chamadas que deliberadamente precisam de uma área de toque maior, não a
+  uma ação primária comum.
+
+Patterns que conhecem a região aplicam o tamanho. Componentes estruturais genéricos não clonam nem
+reescrevem filhos arbitrários: em composição manual, o consumidor segue a mesma matriz. Alterar a
+ênfase de uma ação não altera seu tamanho dentro da região.
+
+## Consequências
+
+- Page, Dialog e Drawer mantêm proporção equivalente nas decisões principais;
+- toolbars e grids preservam densidade sem reduzir ações de conclusão;
+- `primary`, `neutral` e `danger` podem mudar sem provocar salto de altura;
+- exemplos e skills deixam de recomendar `sm` por todo cabeçalho compacto.
+
+## Alternativas consideradas
+
+### Usar `sm` em toda barra ou header
+
+Preservaria a menor altura possível, mas trataria uma decisão da página como operação repetitiva e
+criaria diferença em relação ao footer modal do mesmo recurso.
+
+### Fazer a ação primária sempre maior
+
+Reforçaria hierarquia, mas misturaria importância com densidade. A variante `solid` e o contexto
+`primary` já comunicam essa relação sem deslocar o layout.
+
+### Fazer `ButtonGroup` redimensionar qualquer filho
+
+Centralizaria parte da aparência, mas introduziria comportamento implícito e frágil para filhos que
+não são `Button`. A região ou o pattern conhece melhor o tamanho adequado.
+
+## Verificação
+
+- testes da `Presentation` conferem `default` em ações textuais do header e do footer;
+- testes de `ActionList` continuam cobrindo `sm` em toolbar e `icon-xs` nas ações de linha;
+- a documentação de Button e Page apresenta a mesma matriz;
+- revisão de consumidor trata divergência como exceção explícita, não como novo default.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softize/opus",
-  "version": "17.0.0",
+  "version": "17.1.0",
   "description": "End-to-end action protocol for TypeScript. Single package with subpath exports (core + adapters).",
   "license": "MIT",
   "type": "module",

package/registry/skills/build-opus-ui/references/ui-patterns.md

@@ -21,8 +21,10 @@ PageActions?) + PageBody`; `title` e `actions` no próprio `Page` são a abrevia
 - Quando shell e rota conhecem partes diferentes da mesma página, use `PageShell` ao redor da rota.
   O shell é o único responsável pela barra: fornece `navigation`; a `Page` descendente continua
   declarando `title` e `actions`. O Opus mantém a barra de `3rem` e projeta título e ações nela.
-  Ações com texto na barra
-  usam `Button size="sm"`; ações somente com ícone usam `icon-sm`. Na forma explícita dentro do
+  Ações com texto na barra usam o tamanho `default`, como as ações de footer de Dialog e Drawer;
+  ações somente com ícone de chrome usam `icon-sm`. O tamanho `sm` fica para ações operacionais em
+  toolbar, seção ou coleção densa, e `xs`/`icon-xs` para ações internas de linha ou célula. Contexto
+  e variante resolvem a hierarquia visual sem alterar essa medida. Na forma explícita dentro do
   shell, use `Page > PageHeader (PageNavigation?, PageTitle, PageActions?) + PageBody`, com
   `PageIntro` opcional antes do body. Não monte
   `PaneHeader`, portal ou seletor global para reconstruir essa composição.

package/src/ui/components/patterns/form.tsx

@@ -719,7 +719,13 @@ export function ActionForm<TInput extends Record<string, unknown>, TData>({
         {wrapFooter(
           <>
             {onCancel !== undefined && (
-              <Button type="button" form={formId} variant="ghost" onClick={onCancel}>
+              <Button
+                type="button"
+                form={formId}
+                variant="ghost"
+                disabled={disabled || isLoading}
+                onClick={onCancel}
+              >
                 {cancelLabel}
               </Button>
             )}

package/src/ui/components/patterns/presentation.tsx

@@ -29,7 +29,11 @@ import type {
   ViewContract,
 } from "../../../core/contracts.ts";
 import { cn } from "../../lib/cn.ts";
-import { Button, buttonVariants } from "../primitives/button.tsx";
+import {
+  Button,
+  buttonVariants,
+  type ButtonSize,
+} from "../primitives/button.tsx";
 import { ButtonGroup } from "../primitives/button-group.tsx";
 import { Copyable } from "../primitives/copyable.tsx";
 import { DetailField, DetailGroup } from "../primitives/detail.tsx";
@@ -55,6 +59,7 @@ import {
   PageBody,
   PageFooter,
   PageHeader,
+  PageIntro,
   PageNavigation,
   PageTitle,
   useInsidePageShell,
@@ -147,13 +152,15 @@ function PresentationFrame({
             {navigation === undefined ? null : (
               <PageNavigation>{navigation}</PageNavigation>
             )}
-            <PageTitle>{title}</PageTitle>
             {headerActions === undefined ? null : (
               <PageActions>
                 <PresentationActions>{headerActions}</PresentationActions>
               </PageActions>
             )}
           </PageHeader>
+          <PageIntro>
+            <PageTitle>{title}</PageTitle>
+          </PageIntro>
           <PageBody className="min-h-0 flex-1 overflow-y-auto">{body}</PageBody>
           {hasFooter ? <PageFooter>{renderFooterActions()}</PageFooter> : null}
         </Page>
@@ -298,6 +305,7 @@ function PresentationCommandTrigger({
   command,
   action,
   input,
+  size,
   disabled,
   onLoadingChange,
   onSuccess,
@@ -305,6 +313,7 @@ function PresentationCommandTrigger({
   command: PresentationCommand;
   action: SimpleContract<Record<string, unknown>, unknown>;
   input: Record<string, unknown>;
+  size: ButtonSize;
   disabled: boolean;
   onLoadingChange: (command: PresentationCommand, loading: boolean) => void;
   onSuccess: (data: unknown) => void;
@@ -318,6 +327,7 @@ function PresentationCommandTrigger({
       action={action}
       input={input}
       variant="ghost"
+      size={size}
       disabled={disabled}
       onLoadingChange={reportLoading}
       onSuccess={onSuccess}
@@ -374,6 +384,11 @@ export function Presentation({
     [context, invocation, onInvocationChange, onRefresh],
   );
 
+  const closeSurface = useCallback((): void => {
+    onOpenChange?.(false);
+    applyEffects([{ effect: "close" }]);
+  }, [applyEffects, onOpenChange]);
+
   const reportLoading = useCallback(
     (command: PresentationCommand, loading: boolean): void => {
       setLoadingCommands((current) => {
@@ -429,6 +444,10 @@ export function Presentation({
       string,
       unknown
     >;
+    // Header e footer são regiões de decisão da superfície, não toolbars operacionais.
+    // Seus comandos textuais usam a linha padrão; listas e grids continuam donos da
+    // densidade compacta de suas próprias ações.
+    const size: ButtonSize = "default";
     if (action.kind === "simple") {
       return (
         <PresentationCommandTrigger
@@ -436,6 +455,7 @@ export function Presentation({
           command={command}
           action={action as SimpleContract<Record<string, unknown>, unknown>}
           input={input}
+          size={size}
           disabled={isBlocked(command)}
           onLoadingChange={reportLoading}
           onSuccess={(data) => applyEffects(command.onSuccess, data)}
@@ -450,7 +470,7 @@ export function Presentation({
     return (
       <Button
         key={`${command.placement}:${command.action}`}
-        variant="ghost"
+        size={size}
         disabled={isBlocked(command)}
         onClick={() =>
           openTarget(
@@ -480,6 +500,11 @@ export function Presentation({
           action={bodyAction as FormContract<Record<string, unknown>, unknown>}
           defaultValues={bodyInput}
           submitLabel={definition.body.submitLabel}
+          onCancel={
+            invocation.surface === "page"
+              ? undefined
+              : closeSurface
+          }
           onSuccess={(data) => applyEffects(definition.body.onSuccess, data)}
           disabled={hasSurfaceBlock}
           onLoadingChange={setBodyLoading}
@@ -544,8 +569,12 @@ export function Presentation({
   const footerActions = definition.actions
     .filter((command) => command.placement === "footer")
     .map(renderCommand);
+  const parentSurface = invocation.stack.at(-1)?.surface;
+  const canGoBack =
+    parentSurface !== undefined &&
+    (invocation.surface === "page" || parentSurface !== "page");
   const navigation =
-    invocation.stack.length === 0 ? undefined : (
+    !canGoBack ? undefined : (
       <Button
         size="icon-sm"
         variant="ghost"
@@ -567,10 +596,11 @@ export function Presentation({
       footerActions={footerActions.length === 0 ? undefined : footerActions}
       open={open}
       onOpenChange={(nextOpen) => {
-        onOpenChange?.(nextOpen);
         if (!nextOpen && invocation.surface !== "page") {
-          applyEffects([{ effect: "close" }]);
+          closeSurface();
+          return;
         }
+        onOpenChange?.(nextOpen);
       }}
       className={className}
       bodyClassName={bodyClassNameProp}

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

@@ -24,14 +24,20 @@ há texto visível. O glifo dentro do controle acompanha o tamanho (0.875rem em
 | Nome      | Medida  | Uso                                                                                                                              |
 | --------- | ------- | -------------------------------------------------------------------------------------------------------------------------------- |
 | `xs`      | 1.5rem  | Ação dentro de um campo (`InputGroupButton`).                                                                                    |
-| `sm`      | 2rem    | Toolbar e cabeçalho densos, ao lado de `Select` e `Tabs` `sm`.                                                                   |
-| `default` | 2.25rem | A linha padrão, a mesma de `Input`.                                                                                              |
+| `sm`      | 2rem    | Ação operacional em toolbar, seção ou coleção densa, ao lado de `Select` e `Tabs` `sm`.                                         |
+| `default` | 2.25rem | Decisão da superfície em header de Page ou footer de Dialog/Drawer; é também a linha padrão de `Input`.                         |
 | `lg`      | 2.5rem  | Chamada principal com mais área de toque.                                                                                        |
 | `icon-xs` | 1.5rem  | Ação só de ícone dentro de um campo ou de uma linha densa; é o quadrado de `ActionTrigger` com `icon`.                           |
 | `icon-sm` | 1.75rem | Ação só de ícone em composições compactas que precisam de mais presença; também é o quadrado das setas do pager de `ActionList`. |
 | `icon`    | 2.25rem | Ação só de ícone na linha padrão.                                                                                                |
 | `icon-lg` | 2.5rem  | Ação só de ícone ao lado de um `lg`.                                                                                             |
 
+Escolha o tamanho pela região, não pela importância visual: `variant` e `context` resolvem a
+hierarquia da ação. Headers de Page e footers de Dialog/Drawer usam `default`; ações operacionais
+de seção, toolbar e coleção usam `sm`; ações dentro de linha ou célula usam `xs` ou `icon-xs`.
+Controles de chrome, como voltar e fechar, usam `icon-sm`. Assim a mesma decisão mantém a mesma
+altura mesmo quando uma superfície troca uma ação secundária por uma primária.
+
 ```tsx preview
 <Button size="xs">Mínimo</Button>
 <Button size="sm">Pequeno</Button>

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

@@ -82,7 +82,7 @@ Use `PageShell` quando o shell conhece o breadcrumb e a rota conhece título e a
   <Page
     title="Clientes"
     actions={
-      <Button size="sm">
+      <Button>
         <Plus /> Novo cliente
       </Button>
     }
@@ -103,7 +103,7 @@ Na composição explícita dentro do shell, use `PageHeader` e `PageBody`:
     <PageHeader>
       <PageTitle>Clientes</PageTitle>
       <PageActions>
-        <Button size="sm">Novo cliente</Button>
+        <Button>Novo cliente</Button>
       </PageActions>
     </PageHeader>
     <PageBody>Conteúdo da listagem.</PageBody>

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

@@ -2,17 +2,23 @@
 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: a Presentation projeta
-navigation, title e actions no header da barra e compõe `PageBody` e, quando necessário, `PageFooter`.
+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.
@@ -35,6 +41,7 @@ const workspacePresentation = definePresentation({
 });
 
 function Example() {
+  const [open, setOpen] = React.useState(true);
   const [invocation, setInvocation] = React.useState(() =>
     definePresentationInvocation({
       schemaVersion: 1,
@@ -52,7 +59,10 @@ function Example() {
             key={value}
             size="sm"
             variant={invocation.surface === value ? "solid" : "outline"}
-            onClick={() => setInvocation({ ...invocation, surface: value })}
+            onClick={() => {
+              setInvocation({ ...invocation, surface: value });
+              setOpen(true);
+            }}
           >
             {value}
           </Button>
@@ -64,7 +74,12 @@ function Example() {
         definitions={[workspacePresentation]}
         actions={{ [workspaceUpdate.name]: workspaceUpdate }}
         invocation={invocation}
-        onInvocationChange={(next) => next && setInvocation(next)}
+        open={invocation.surface === "page" || open}
+        onOpenChange={setOpen}
+        onInvocationChange={(next) => {
+          if (next) setInvocation(next);
+          else setOpen(false);
+        }}
       />
     </div>
   );