@softize/opus 15.0.0 → 15.0.1

package/CHANGELOG.md

@@ -7,6 +7,38 @@ 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.
 
+## 15.0.1 — 2026-09-09
+
+Correções sobre a 15.0.0, publicada horas antes, todas vindas da revisão dela. Nenhuma novidade de
+API: nada entrou, saiu ou mudou de nome.
+
+As ações de uma linha do `ActionList` só entram no `ButtonGroup` a partir de duas. Com uma só, o
+grupo não é materializado: um `role="group"` sem nome por linha enchia a árvore de acessibilidade
+sem informar nada, e o espaçamento não tinha o que espaçar. Fragmento devolvido pelo consumidor
+conta como as ações que carrega, não como um filho só.
+
+**Migração:** quem escreveu seletor contra o `[data-slot="button-group"]` da linha na 15.0.0
+precisa mirar a célula. Com uma ação só, não há mais grupo.
+
+A região introdutória do `PageHeader` — `PageBack` ou `PageNavigation` — passa a carregar
+`data-slot="page-navigation"` também na apresentação em barra. Antes o marcador existia só no
+header padrão, então um seletor de teste ou de CSS que funcionasse num não funcionava no outro.
+
+`Page` deixa de emitir `min-h-0` e `min-h-full` ao mesmo tempo quando a barra encontra um estado
+integral. O resultado dependia da ordem do CSS gerado; agora o estado integral declara a altura
+que precisa e a barra só contém a rolagem quando não há estado.
+
+`opus check` para de acrescentar um segundo diagnóstico sobre a forma de composição quando o
+problema é uma propriedade removida. A prop já diz o que corrigir; a mensagem seguinte era
+verdadeira e enganosa ao mesmo tempo.
+
+A ADR 0004 ganha, no adendo, o motivo que sustenta a alternativa descartada — antes ela se apoiava
+numa citação que não sustentava a conclusão — e a segunda consequência da decisão: `PageHeader`
+desiste antes de validar os filhos, então um cabeçalho inválido só lança quando a página chega em
+`ready` — o `opus check` continua pegando isso estaticamente. A guidance de UI e a doc de `Page`
+passam a avisar que o retorno some junto com o cabeçalho e que a saída, nesse caso, é o `action` do
+próprio `PageState`.
+
 ## 15.0.0 — 2026-09-09
 
 `PageHeader` passa a oferecer `variant="bar"`, uma apresentação compacta da mesma região de título,

package/bin/lib/check.mjs

@@ -950,8 +950,10 @@ export function checkUiStructure(file, text) {
               : [],
           ),
         );
+        let removedProp = false;
         for (const [attribute, hint] of root.removed ?? []) {
           if (attributes.has(attribute)) {
+            removedProp = true;
             add(
               node,
               component,
@@ -967,7 +969,15 @@ export function checkUiStructure(file, text) {
         const structural =
           children.names.includes(root.header) ||
           children.names.includes(root.body);
-        if (shorthand && structural) {
+        // A prop removida saiu do `shorthand`, então sozinha ela não marca o nó como forma curta:
+        // ele cai no ramo explícito, que cobra header e body — uma segunda mensagem inteiramente
+        // induzida pela prop. Sem filhos estruturais essa cobrança dispara de qualquer jeito, e
+        // some aqui.
+        // Com filhos estruturais, o que as regras de forma acham é defeito independente: misturar
+        // shorthand com slots, ou um filho inesperado, não some quando a prop sai.
+        if (removedProp && !structural) {
+          // Nada a acrescentar; os filhos seguem sendo visitados no fim de `visit`.
+        } else if (shorthand && structural) {
           add(
             node,
             component,

package/docs/adr/0004-page-content-state-is-composed.md

@@ -90,10 +90,17 @@ superfície de estado carrega `role="heading"` com `aria-level={1}`.
 
 **Alternativa descartada.** Ocultar apenas título, descrição e ações, preservando a região
 introdutória. Foi descartada para esta versão porque partiria o cabeçalho em duas regras de
-visibilidade e deixaria a barra materializada só para um botão, contrariando "um header sem
-conteúdo útil não é materializado" da ADR 0010.
+visibilidade — uma para o retorno, outra para o resto —, e um cabeçalho que aparece pela metade
+é mais difícil de prever do que um que some inteiro. Não é uma decisão confortável: ver
+"O que se perde".
 
 **O que se perde, e é conhecido.** Some junto o `PageBack`, então uma subpágina em erro fica sem o
 retorno in-page para o pai — justamente quando a pessoa mais precisa sair. Enquanto esta ADR não
 for revista, uma subpágina que dependa desse retorno oferece a saída pelo `action` do próprio
 `PageState`. Reavaliar se o custo aparecer em uso real.
+
+Uma segunda consequência é da mesma decisão: como `PageHeader` desiste antes de validar seus
+filhos, um cabeçalho estruturalmente inválido — dois `PageBack`, ou sem `PageTitle` — deixa de
+lançar enquanto a página está em estado integral, e só lança quando ela chega em `ready`. O
+`opus check` continua pegando isso estaticamente, então o erro não passa despercebido até
+produção; o que muda é o momento em que aparece no desenvolvimento.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softize/opus",
-  "version": "15.0.0",
+  "version": "15.0.1",
   "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

@@ -19,12 +19,13 @@
   `PageActionsTarget` fica reservado a workspaces imersivos que já possuam chrome próprio.
 - `PageState` substitui todo o conteúdo principal quando a página carrega, falha ou está vazia. Na
   forma curta ele pode ser escrito como filho direto de `Page`, que cria o `PageBody`; na forma
-  explícita, fica sozinho dentro de `PageBody`. Nos três estados ativos, o cabeçalho some, o estado
-  ocupa a área disponível e seu título assume o heading principal, inclusive quando um componente
-  intermediário renderiza o estado. O erro mantém `role="alert"`, usa a mesma composição central e
-  sem moldura dos demais estados e apresenta a recuperação como botão `outline` textual. Estados de
-  seção ou coleção continuam em `DataState`, `ActionView`, `ActionList` ou `Alert`; não elevar uma
-  falha parcial a estado da página.
+  explícita, fica sozinho dentro de `PageBody`. Nos três estados ativos, o cabeçalho some inteiro —
+  incluindo o `PageBack` —, o estado ocupa a área disponível e seu título assume o heading
+  principal, inclusive quando um componente intermediário renderiza o estado. Uma subpágina que
+  dependa do retorno ao pai oferece essa saída pelo `action` do próprio `PageState`. O erro mantém
+  `role="alert"`, usa a mesma composição central e sem moldura dos demais estados e apresenta a
+  recuperação como botão `outline` textual. Estados de seção ou coleção continuam em `DataState`,
+  `ActionView`, `ActionList` ou `Alert`; não elevar uma falha parcial a estado da página.
 - `Content` delimita uma seção e segue a mesma anatomia: `Content > ContentHeader (ContentTitle,
   ContentDescription, ContentMeta, ContentActions) + ContentBody`. `ContentHeader` nunca fica
   solto. `title`, `description`, `count` e `actions` no `Content` são a abreviação para o caso

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

@@ -20,6 +20,9 @@
  */
 
 import {
+  Children,
+  Fragment,
+  isValidElement,
   useEffect,
   useLayoutEffect,
   useMemo,
@@ -1142,6 +1145,31 @@ export function ActionFilterBar({
 // ActionList
 // =============================================================================
 
+/**
+ * Ações de uma linha da tabela. Com duas ou mais, agrupa e espaça; com uma só, não
+ * materializa o `ButtonGroup` — um `role="group"` sem nome por linha enche a árvore de
+ * acessibilidade sem informar nada, e `mode="spaced"` não teria o que espaçar.
+ */
+function RowActions({ children }: { children: ReactNode }) {
+  // O consumidor costuma devolver as ações dentro de um fragment, que conta como UM filho —
+  // e às vezes dentro de fragments aninhados. Expandir recursivamente, e contar só elementos,
+  // evita tanto tratar duas ações como uma quanto deixar um espaço em branco virar ação.
+  const expand = (node: ReactNode): ReactNode[] =>
+    Children.toArray(node).flatMap((child) =>
+      isValidElement(child) && child.type === Fragment
+        ? expand((child.props as { children?: ReactNode }).children)
+        : [child],
+    );
+  const alone = expand(children).filter(isValidElement).length < 2;
+  return alone ? (
+    <div className="flex justify-end">{children}</div>
+  ) : (
+    <ButtonGroup mode="spaced" className="ml-auto">
+      {children}
+    </ButtonGroup>
+  );
+}
+
 export function ActionList<TInput, TItem>({
   action,
   input,
@@ -1634,9 +1662,7 @@ export function ActionList<TInput, TItem>({
                   className="w-px whitespace-nowrap text-right"
                   onClick={(e) => e.stopPropagation()}
                 >
-                  <ButtonGroup mode="spaced" className="ml-auto">
-                    {rowActions(item)}
-                  </ButtonGroup>
+                  <RowActions>{rowActions(item)}</RowActions>
                 </TableCell>
               )}
             </TableRow>

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

@@ -169,8 +169,11 @@ export function Page({
             data-slot="page"
             className={cn(
               "min-w-0 flex-1",
-              headerVariant === "bar" && "flex min-h-0 flex-col",
-              integralState && "flex min-h-full flex-col",
+              (headerVariant === "bar" || integralState) && "flex flex-col",
+              // A barra contém a rolagem (`min-h-0`); o estado integral ocupa a altura
+              // disponível (`min-h-full`). Emitir os dois juntos deixava o resultado por
+              // conta da ordem do CSS gerado — no estado integral, quem manda é ele.
+              integralState ? "min-h-full" : headerVariant === "bar" && "min-h-0",
             )}
             {...props}
           >

package/src/ui/components/patterns/surface-header.tsx

@@ -146,9 +146,17 @@ export function SurfaceHeader({
       {descriptions}
     </div>
   );
+  // A região introdutória carrega o mesmo `data-slot` nas duas apresentações: seletor de teste
+  // ou de CSS que funcione no header padrão precisa funcionar na barra.
   const row = (
     <>
-      {leadingPlacement === "inline" && leading}
+      {leadingPlacement === "inline" && leading.length > 0 && (
+        // `min-w-0` aqui é o que deixa a trilha do PageNavigation ceder e truncar; sem ele o
+        // wrapper assume o min-content do breadcrumb e a compressão toda cai sobre o título.
+        <div data-slot={`${slot}-navigation`} className="flex min-w-0 items-center">
+          {leading}
+        </div>
+      )}
       {heading}
       {actionSlots}
     </>

package/src/ui/docs/content/action-list.md

@@ -302,4 +302,4 @@ chamar a action.
 | `retryLabel` | `string` | `'Tentar de novo'` | Nome acessível e tooltip da ação de recuperação. |
 | `onRowClick` | `(item: TItem) => void` | | Clique na linha (ex.: navegar para o detalhe) — só na tabela. |
 | `toolbarActions` | `ReactNode` | | Ações do consumidor no fim da barra, separadas do grupo de controles. |
-| `rowActions` | `(item: TItem) => ReactNode` | | Ações por linha (coluna final, à direita), agrupadas automaticamente com intervalo compacto; cliques ali não disparam o `onRowClick`. |
+| `rowActions` | `(item: TItem) => ReactNode` | | Ações por linha (coluna final, à direita). A partir de duas, entram num grupo com intervalo compacto; uma só fica solta, sem grupo. Cliques ali não disparam o `onRowClick`. |

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

@@ -123,10 +123,11 @@ render(
 Use `PageState` quando carregamento, falha ou ausência substituírem todo o conteúdo principal. Na
 forma curta ele pode ser escrito como filho direto de `Page`, que cria o `PageBody`; na forma
 explícita, coloque-o sozinho dentro de `PageBody`. Enquanto `status` for `loading`, `error` ou
-`empty`, `Page` oculta o cabeçalho e o estado ocupa a altura disponível. O título do estado assume o
-heading principal. Esse registro também funciona quando um componente intermediário decide qual
-`PageState` renderizar. Em `ready`, o cabeçalho e o conteúdo voltam à composição normal. O cabeçalho some inteiro, incluindo o `PageBack`: uma subpágina que dependa desse retorno
-oferece a saída pelo `action` do próprio `PageState` (ADR 0004, adendo).
+`empty`, `Page` oculta o cabeçalho inteiro — incluindo o `PageBack` — e o estado ocupa a altura
+disponível. Uma subpágina que dependa desse retorno oferece a saída pelo `action` do próprio
+`PageState`. O título do estado assume o heading principal. Esse registro também funciona quando um
+componente intermediário decide qual `PageState` renderizar. Em `ready`, o cabeçalho e o conteúdo
+voltam à composição normal.
 
 ```tsx preview col
 <Page title="Relatório">
@@ -244,7 +245,7 @@ estado na própria seção com `DataState`, `ActionView`, `ActionList` ou `Alert
 | `title`        | `ReactNode`                                  | Texto seguro por estado                   | Situação reconhecível pela pessoa.                                                              |
 | `description`  | `ReactNode`                                  |                                           | Impacto ou próximo passo aplicável.                                                             |
 | `icon`         | `ReactNode`                                  | Alerta no erro                            | Ícone decorativo do estado.                                                                     |
-| `action`       | `ReactNode`                                  |                                           | Seleção ou criação aplicável ao estado.                                                         |
+| `action`       | `ReactNode`                                  |                                           | Seleção, criação ou saída aplicável ao estado — inclusive o retorno ao pai, já que o cabeçalho está oculto. |
 | `emptyMessage` | `string`                                     | `'Nada por aqui'`                         | Título do vazio quando `title` não é informado.                                                 |
 | `errorMessage` | `string`                                     | `'Não foi possível carregar esta página'` | Título do erro quando `title` não é informado.                                                  |
 | `onRetry`      | `() => void \| Promise<void>`                |                                           | Recuperação do erro: acrescenta um botão `outline` textual ao lado de `action`.                 |