@softize/opus 30.0.0 → 31.0.0

package/CHANGELOG.md

@@ -7,6 +7,122 @@ 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.
 
+## 31.0.0 — 2026-10-20
+
+- `PageBack` aceita `onBack` e `disabled` para retorno controlado por uma pilha. `href` continua disponível para destinos navegáveis; `PageBackProps` é uma união que impede combinar as duas formas.
+
+- Apresentações embutidas preservam ações de cabeçalho, rodapé e envio de formulário. `successMessage` pertence somente a comandos de execução direta.
+
+- `ActionList` omite o rodapé quando o total é zero, removendo a paginação sem resultados e o divisor adicional junto da moldura vazia.
+
+- A Page aberta passa a separar cabeçalho e conteúdo por `1,5rem`. As demais regiões e as superfícies com moldura preservam o espaçamento atual.
+
+- `FieldDescription`, usado pelos hints dos formulários, passa a usar `text-xs` (`0,75rem`). Rótulos, controles e mensagens de erro preservam seus tamanhos.
+
+- `PageActions` passa a compor `ButtonGroup` no modo espaçado. Voltar e ações da página compartilham o grupo, preservando a ordem e adotando o espaçamento padrão de `0,25rem`.
+
+- O título da Page aberta passa de `1,5rem` para `1,875rem`. Títulos de Surface, Drawer e Dialog mantêm a escala atual.
+
+- As superfícies, bordas e estados neutros do dark recebem uma redução proporcional de 5% na luminosidade HSL sobre a calibração de referência. Texto, cores semânticas e tema claro permanecem iguais.
+
+- O dark usa conteúdo `#171717`, sidebar interna `#1c1c1c` e borda `#333333`, após a redução de luminosidade. `sidebar-global` acompanha o canvas nos dois temas, dando continuidade visual à navegação geral sem transparência.
+
+- O token `sidebar` oferece fundo opaco para navegação interna: `#fcfcfc` no light e o degrau de `card` no dark. No light, hover, seleção e pressão usam `#f4f4f4`, `#f0f0f0` e `#e8e8e8`. A navegação global usa `sidebar-global`, que acompanha o canvas.
+
+- O tema claro usa branco puro (`#fff`) no fundo geral, nos controles, cards e popovers. Sidebar, estados neutros e bordas preservam os tons calibrados.
+
+- A escala neutra tem mais contraste de base em fundos discretos, estados de interação e bordas no tema claro. No escuro, hover se distingue de `muted` e as bordas ficam mais definidas. Os tokens neutros preservam os papéis de superfície e interação; a calibração padrão diferencia os temas claro e escuro.
+
+- DetailField vertical usa o mesmo espaço de `0,375rem` entre rótulo e valor que Field usa entre rótulo e controle.
+
+- Cabeçalhos de tabela preservam `0,5rem` de padding vertical ao quebrar texto em mais de uma linha. A altura acompanha o conteúdo, mantendo o cabeçalho fixo durante a rolagem de ActionList.
+
+- O rodapé de ActionList usa padding vertical de `0,75rem`. Pagination destaca a página atual com fundo neutro suave e peso semibold, sem borda; os demais controles permanecem ghost.
+
+- Dialog e Drawer usam `xs` (`1,5rem`) no botão de fechar, com o tratamento neutro `subtle` e seus estados de interação, preservando a escala normal das demais ações do cabeçalho.
+
+- ActionList uniformiza em `1rem` o espaçamento entre toolbar e resultados em tabelas, cards e listas de itens.
+
+- Consolida Presentation com conteúdo de linha e toolbar tipados, regiões fill, abas embedded,
+  fontes externas isoladas por adaptador e seletores compostos de rota. Preserva o observador
+  durante refetch e aplica largura ampla ao Drawer; comandos admitem mensagem de sucesso.
+
+- Presentation admite campos especializados vinculados ao contrato e resumos que recebem o input efetivo de ActionList; validação e autorização permanecem nos patterns existentes.
+
+`listStateToInput` compartilha com os hospedeiros a materialização do recorte usado pelo ActionList,
+preservando filtros e paginação ao carregar detalhes roteados.
+
+Presentation permite detalhe local de linha por adaptador tipado (`body.inspect`), filtros iniciais
+(`body.filterDefaults`) e opções de lookup com rótulos compostos e opções estáticas anteriores.
+Lookups exigem actions com `paginate: false`, garantindo opções completas.
+O renderer verifica a permissão da consulta de lookup antes de executá-la. ActionForm aceita
+`widget: 'password'` para cadastro e redefinição de senha. Comandos de linha usam o rótulo do
+dicionário do contrato quando o identificador apresentado é um código.
+
+Presentation aceita arquivo autoral `presentations/*.json`, validado pelo schema público e
+rastreado por `opus copy`. A extração preserva o caminho e as linhas do JSON.
+
+**Breaking:** o renderer agora considera também `requires` da action, sem depender da repetição
+no layout. Forneça `can` ao host para as permissões explícitas; sem esse callback os controles e
+corpos protegidos não montam. `requires` da apresentação admite alternativas em array e continua
+cumulativo com o contrato. `canAccessPresentation` permite verificar rotas antes de buscar dados.
+
+Presentation amplia as seções declarativas para controles específicos, listas de actions,
+metadados e ações de cabeçalho, controles à direita dos itens e painel lateral. `page.layout`
+transporta a escolha de rolagem no JSON. Abas podem referenciar seções declaradas, além de actions.
+Os adaptadores runtime preservam handlers e dados; a declaração determina a anatomia.
+
+Page usa uma única aparência aberta: padding de 2,5rem, título de 1,875rem e intervalo de
+1,5rem após o cabeçalho e 1rem entre as demais regiões, sem divisores. `flow` rola a página inteira; `fill` preserva o header
+e a altura disponível às listas. Drawer e Dialog mantêm suas superfícies delimitadas.
+
+Page aceita width narrow/default/wide, também declarado em Presentation.page.width. O limite
+se aplica à coluna inteira. Sem a opção, a página ocupa a largura disponível.
+
+Presentation permite declarar colunas de texto e switch, lookups de formulário, defaults de
+registro, destinos condicionais de linha e confirmações. Abas podem referenciar outras
+Presentations; `requires` recebe um resolvedor de permissões da aplicação, sem substituir a
+autorização das actions. Views aceitam texto e HTML isolado; rotas de diálogos declaram pai.
+
+Presentation aceita `body.tabs`, com seleção local ou controlada, referências a conteúdos e
+ícones registrados e rotas declaradas para o roteador consumidor. Somente a aba ativa monta.
+
+Presentation aceita comandos por linha e adaptadores nomeados de células. Comandos de linha
+reutilizam confirmação e invalidação do contrato; ícones vêm do registro runtime do consumidor.
+
+Presentation ganha composição declarativa por `body.sections`.
+Seções de itens e listas externas reutilizam os patterns existentes; extensões runtime são
+registradas por nome. O inventário de copy cobre os textos da nova declaração.
+
+ActionList ganha apresentação nativa de itens, título junto das ações e fonte externa com
+cache isolado. Itens usam moldura conectada e exibem paginação somente quando necessária.
+
+Headers de Page, Drawer, Dialog e Surface aceitam abas integradas. TabsPanel repassa a
+altura disponível às listas. Ações da coleção ficam em ActionList.toolbarActions; Presentation
+aceita placement toolbar e label contextual com nome acessível específico.
+
+Cabeçalhos usam controles default/icon e linha mínima de 2,25rem. PageBack ocupa a
+primeira ação, por ícone com tooltip e destino nomeado.
+
+O inventário de copy valida o aria-label dinâmico de botões de ícone sem exigir um
+segundo texto nos filhos decorativos. O nome acessível continua exigindo declaração.
+
+### Breaking
+
+Removidos surfaceLayout da Page, layout visual de Surface/DialogContent/DrawerContent,
+PageShell.navigation, PageNavigation e as famílias PageIntro/DialogIntro/DrawerIntro
+(incluindo IntroActions). Mova título, descrição, metadados e ações gerais para o Header.
+Divisores são automáticos nas superfícies delimitadas; Surface sem moldura mantém o
+alinhamento do hospedeiro e ritmo de 1rem, sem recuo ou divisor de região.
+Surface nível 1 deixa de substituir o PageHeader dentro da Page; use níveis subordinados
+no body. O nível 1 continua disponível em superfícies fora da Page.
+Page.layout flow/fill permanece como controle de ocupação.
+
+Presentation com heading de conteúdo requer uma Page completa. Não combine PageFooter
+próprio com comandos de footer declarados na Presentation. Ações da coleção usam
+ActionList.toolbarActions. PageBack e o retorno da Presentation
+requerem TooltipProvider no aplicativo.
+
 ## 30.0.0 — 2026-10-16
 
 PageMeta, DrawerMeta, DialogMeta e SurfaceMeta organizam badges, datas e autoria em

package/bin/lib/check.mjs

@@ -154,14 +154,11 @@ const UI_SURFACE_PAIRS = new Map([
 const UI_STRUCTURAL_PARENTS = new Map([
   ["PageHeader", new Set(["Page"])],
   ["PageBody", new Set(["Page"])],
-  ["PageIntro", new Set(["PageBody"])],
-  ["PageIntroActions", new Set(["PageIntro"])],
   ["PageFooter", new Set(["Page"])],
-  ["PageTitle", new Set(["PageHeader", "PageIntro"])],
-  ["PageDescription", new Set(["PageHeader", "PageIntro"])],
-  ["PageMeta", new Set(["PageHeader", "PageIntro"])],
-  ["PageBack", new Set(["PageHeader"])],
-  ["PageNavigation", new Set(["PageHeader"])],
+  ["PageTitle", new Set(["PageHeader"])],
+  ["PageDescription", new Set(["PageHeader"])],
+  ["PageMeta", new Set(["PageHeader"])],
+  ["PageBack", new Set(["PageHeader", "PageActions", "PageShell"])],
   ["PageActions", new Set(["PageHeader"])],
   // As regiões de Surface não são estritas: com `asChild`, elas ficam dentro do elemento que
   // recebe a superfície (ADR 0045). Os slots do header são filhos diretos dele.
@@ -177,24 +174,20 @@ const UI_STRUCTURAL_PARENTS = new Map([
   ["DialogHeader", new Set(["DialogContent"])],
   ["DialogBody", new Set(["DialogContent"])],
   ["DialogFooter", new Set(["DialogContent"])],
-  ["DialogIntro", new Set(["DialogBody"])],
-  ["DialogIntroActions", new Set(["DialogIntro"])],
   ["DialogNavigation", new Set(["DialogHeader"])],
   ["DialogMedia", new Set(["DialogHeader"])],
-  ["DialogTitle", new Set(["DialogHeader", "DialogIntro"])],
-  ["DialogDescription", new Set(["DialogHeader", "DialogIntro"])],
-  ["DialogMeta", new Set(["DialogHeader", "DialogIntro"])],
+  ["DialogTitle", new Set(["DialogHeader"])],
+  ["DialogDescription", new Set(["DialogHeader"])],
+  ["DialogMeta", new Set(["DialogHeader"])],
   ["DialogActions", new Set(["DialogHeader"])],
   ["DrawerHeader", new Set(["DrawerContent"])],
   ["DrawerBody", new Set(["DrawerContent"])],
   ["DrawerFooter", new Set(["DrawerContent"])],
-  ["DrawerIntro", new Set(["DrawerBody"])],
-  ["DrawerIntroActions", new Set(["DrawerIntro"])],
   ["DrawerNavigation", new Set(["DrawerHeader"])],
   ["DrawerMedia", new Set(["DrawerHeader"])],
-  ["DrawerTitle", new Set(["DrawerHeader", "DrawerIntro"])],
-  ["DrawerDescription", new Set(["DrawerHeader", "DrawerIntro"])],
-  ["DrawerMeta", new Set(["DrawerHeader", "DrawerIntro"])],
+  ["DrawerTitle", new Set(["DrawerHeader"])],
+  ["DrawerDescription", new Set(["DrawerHeader"])],
+  ["DrawerMeta", new Set(["DrawerHeader"])],
   ["DrawerActions", new Set(["DrawerHeader"])],
   ["AlertMedia", new Set(["Alert"])],
   ["AlertHeader", new Set(["Alert"])],
@@ -294,14 +287,45 @@ const UI_STRUCTURAL_BODIES = new Set([
 const UI_BODY_RHYTHM_CLASS =
   /(?:^|:)(?:!?-?)(?:space-[xy]|gap(?:-[xy])?|p|px|py|pt|pr|pb|pl|ps|pe)-/;
 
-const UI_FLUSH_BODIES = new Set(["SurfaceBody", "DialogBody", "DrawerBody"]);
+const UI_FLUSH_BODIES = new Set([
+  "SurfaceBody",
+  "DialogBody",
+  "DrawerBody",
+  "PageBody",
+]);
 
 const UI_REMOVED_PROPS = new Map([
+  [
+    "Page",
+    new Map([
+      ["surfaceLayout", "os divisores são automáticos"],
+      ["compact", "o título pertence ao header"],
+      ["sectioned", "os divisores são automáticos"],
+    ]),
+  ],
+  ["PageShell", new Map([["navigation", "use PageBack nas ações"]])],
+  ...["Surface", "DialogContent", "DrawerContent"].map((component) => [
+    component,
+    new Map([
+      ["layout", "as regiões têm uma anatomia única"],
+      ["compact", "o título pertence ao header"],
+      ["sectioned", "os divisores são automáticos"],
+    ]),
+  ]),
+  ...["SurfaceHeader", "DialogHeader", "DrawerHeader"].map((component) => [
+    component,
+    new Map([
+      [
+        "tabsActions",
+        "mova as ações da coleção para ActionList.toolbarActions",
+      ],
+    ]),
+  ]),
   [
     "Pane",
     new Map([
       ["inset", "mova o recuo para o conteúdo ou para uma `Surface` filha"],
-      ["layout", "use `Surface` para anatomia visual contínua ou seccionada"],
+      ["layout", "use `Surface` para a anatomia visual"],
     ]),
   ],
   [
@@ -325,12 +349,24 @@ const UI_REMOVED_PROPS = new Map([
   [
     "PageHeader",
     new Map([
-      ["variant", "o cabeçalho da página tem uma única apresentação rolável"],
+      [
+        "tabsActions",
+        "mova as ações da coleção para ActionList.toolbarActions",
+      ],
+      ["variant", "o cabeçalho da página tem uma única apresentação fixa"],
     ]),
   ],
 ]);
 
 const UI_REMOVED_COMPONENTS = new Map([
+  ...["Page", "Dialog", "Drawer"].flatMap((family) => [
+    [`${family}Intro`, `mova título e metadados para ${family}Header`],
+    [
+      `${family}IntroActions`,
+      `use ${family}Actions ou ActionList.toolbarActions para a coleção`,
+    ],
+  ]),
+  ["PageNavigation", "use PageBack em PageActions"],
   ["PaneHeader", "use `SurfaceHeader` dentro de uma `Surface`"],
   ["PaneBody", "use `SurfaceBody` ou um contêiner próprio do conteúdo"],
   ["PaneContent", "use `SurfaceBody` ou um contêiner próprio do conteúdo"],
@@ -371,54 +407,35 @@ const UI_REMOVED_COMPONENTS = new Map([
 const UI_STRUCTURAL_CONTAINERS = new Set(["PageShell"]);
 
 const UI_STRUCTURAL_HEADERS = new Map([
-  [
-    "PageIntro",
-    {
-      title: "PageTitle",
-      optional: new Set(["PageIntroActions", "PageDescription", "PageMeta"]),
-      shorthand: new Set(),
-    },
-  ],
-  [
-    "DialogIntro",
-    {
-      title: "DialogTitle",
-      optional: new Set([
-        "DialogIntroActions",
-        "DialogDescription",
-        "DialogMeta",
-      ]),
-      shorthand: new Set(),
-    },
-  ],
-  [
-    "DrawerIntro",
-    {
-      title: "DrawerTitle",
-      optional: new Set([
-        "DrawerIntroActions",
-        "DrawerDescription",
-        "DrawerMeta",
-      ]),
-      shorthand: new Set(),
-    },
-  ],
   [
     "PageHeader",
     {
       title: "PageTitle",
       optional: new Set([
         "PageBack",
-        "PageNavigation",
         "PageActions",
         "PageDescription",
         "PageMeta",
       ]),
-      exclusive: [new Set(["PageBack", "PageNavigation"])],
       shorthand: new Set(),
-      titleRequired: false,
+      titleRequired: true,
     },
   ],
+  ...["Dialog", "Drawer"].map((family) => [
+    `${family}Header`,
+    {
+      title: `${family}Title`,
+      optional: new Set([
+        `${family}Navigation`,
+        `${family}Media`,
+        `${family}Description`,
+        `${family}Meta`,
+        `${family}Actions`,
+      ]),
+      shorthand: new Set(),
+      allowOpaque: true,
+    },
+  ]),
   [
     "SurfaceHeader",
     {
@@ -2042,11 +2059,10 @@ function countPageHeadingSources(page, imports) {
           local !== null &&
           ((imports.get(local) === "Surface" &&
             jsxNumericAttribute(node, "level") === 1) ||
-            imports.get(local) === "PageIntro" ||
             imports.get(local) === "PageState")
         ) {
           if (imports.get(local) === "PageState") states += 1;
-          else count += 1;
+          else return;
         }
       }
       ts.forEachChild(node, visit);
@@ -2110,6 +2126,23 @@ export function checkUiStructure(file, text) {
     if (ts.isJsxElement(node) || ts.isJsxSelfClosingElement(node)) {
       const local = jsxLocalName(node);
       const component = local === null ? null : imports.get(local);
+      if (component === "Surface" && jsxNumericAttribute(node, "level") === 1) {
+        let ancestor = node.parent;
+        while (ancestor) {
+          if (
+            ts.isJsxElement(ancestor) &&
+            imports.get(jsxLocalName(ancestor)) === "Page"
+          ) {
+            add(
+              node,
+              component,
+              "Surface dentro de Page é uma seção subordinada. Use PageHeader com PageTitle para o título principal.",
+            );
+            break;
+          }
+          ancestor = ancestor.parent;
+        }
+      }
       if (component === "Split" && ts.isJsxElement(node)) {
         for (const child of invalidSplitChildren(
           node,
@@ -2165,9 +2198,11 @@ export function checkUiStructure(file, text) {
         component === null ? undefined : UI_STRUCTURAL_PARENTS.get(component);
       if (parents !== undefined) {
         const strict = UI_STRICT_DIRECT_COMPONENTS.has(component);
-        const parent = strict
-          ? directJsxParentName(node, imports)
-          : structuralJsxAncestorName(node, imports);
+        // PageBack também chega pelas actions de PageShell, atravessando atributo e fragmento.
+        const parent =
+          strict && component !== "PageBack"
+            ? directJsxParentName(node, imports)
+            : structuralJsxAncestorName(node, imports);
         // Slots das famílias históricas podem ser a raiz de um componente wrapper. Quando há
         // uma superfície estrutural visível no mesmo JSX, porém, ela precisa ser a família certa.
         if (
@@ -2205,41 +2240,6 @@ export function checkUiStructure(file, text) {
         }
       }
 
-      if (["PageBody", "DialogBody", "DrawerBody"].includes(component)) {
-        const intro = component.replace("Body", "Intro");
-        const visible = (children) =>
-          children.flatMap((child) => {
-            if (ts.isJsxText(child)) return child.text.trim() ? [child] : [];
-            if (ts.isJsxFragment(child)) return visible(child.children);
-            if (
-              ts.isJsxExpression(child) &&
-              (!child.expression ||
-                [
-                  ts.SyntaxKind.NullKeyword,
-                  ts.SyntaxKind.FalseKeyword,
-                  ts.SyntaxKind.TrueKeyword,
-                ].includes(child.expression.kind))
-            )
-              return [];
-            return [child];
-          });
-        const children = ts.isJsxElement(node) ? visible(node.children) : [];
-        const indexes = children.flatMap((child, index) =>
-          (ts.isJsxElement(child) || ts.isJsxSelfClosingElement(child)) &&
-          imports.get(jsxLocalName(child)) === intro
-            ? [index]
-            : [],
-        );
-        if (indexes.length > 1 || (indexes.length === 1 && indexes[0] !== 0)) {
-          add(
-            node,
-            component,
-            `${intro} deve ser o primeiro e único bloco introdutório de ${component}.`,
-            "ui-structure-intro-order",
-          );
-        }
-      }
-
       if (
         component !== null &&
         (UI_STRUCTURAL_BODIES.has(component) || component === "Page")
@@ -2273,7 +2273,7 @@ export function checkUiStructure(file, text) {
           add(
             node,
             component,
-            `${component} aceita um único ${title}: mantenha o título no header ou na intro, nunca nos dois.`,
+            `${component} aceita um único ${title}: mantenha o título no header.`,
             "ui-structure-duplicate-title",
           );
         }
@@ -2282,11 +2282,8 @@ export function checkUiStructure(file, text) {
       if (
         [
           "PageHeader",
-          "PageIntro",
           "DialogHeader",
-          "DialogIntro",
           "DrawerHeader",
-          "DrawerIntro",
           "SurfaceHeader",
         ].includes(component)
       ) {
@@ -2351,7 +2348,18 @@ export function checkUiStructure(file, text) {
               children.names.filter((name) => group.has(name)).length > 1,
           );
           const titleValid =
-            header.titleRequired === false ? titles <= 1 : titles === 1;
+            header.titleRequired === false
+              ? titles <= 1
+              : titles === 1 ||
+                (titles === 0 &&
+                  header.allowOpaque &&
+                  children.hasOpaque &&
+                  ts.isJsxElement(node) &&
+                  node.children.some(
+                    (child) =>
+                      ts.isJsxExpression(child) &&
+                      child.expression !== undefined,
+                  ));
           const recognizedContent =
             titles +
             children.names.filter((name) => header.optional.has(name)).length;
@@ -2496,7 +2504,7 @@ export function checkUiStructure(file, text) {
               add(
                 node,
                 component,
-                "Page explícito exige exatamente um heading principal em PageHeader, Surface level={1} ou PageState dentro de PageBody.",
+                "Page explícito exige exatamente um heading principal em PageHeader ou PageState ativo dentro de PageBody.",
               );
             }
           }