@softize/opus 15.0.1 → 15.2.0

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

@@ -1,22 +1,24 @@
 ## Esqueleto de página
 
-Use `Page` para manter navegação contextual, título, ações e conteúdo na mesma anatomia. O
-`PageHeader` padrão acompanha o conteúdo dentro do container; `variant="bar"` transforma o mesmo
-cabeçalho em uma faixa compacta no topo. Não monte um chrome paralelo para repetir essas regiões.
+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.
 
 Em larguras amplas, as ações ficam no extremo oposto e acompanham a base do título e da descrição;
 em larguras estreitas, passam para uma linha abaixo. 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. Ela cria internamente `PageHeader` e `PageBody`;
-portanto, não produz uma estrutura visual ou semântica diferente da forma explícita. O cabeçalho é a
-mesma base estrutural de `Content`, mas reconhece somente título, descrição e ações. Contadores e
-outros indicadores pertencem ao conteúdo que os explica.
+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
+conteúdo que os explica.
 
-`Page` também pode ocupar o painel principal de um shell com sidebar. Tabs ficam reservados a
-recortes da mesma superfície. Canvas e outros workspaces espaciais imersivos podem usar um shell
-próprio quando o cabeçalho reduzir a área útil ou duplicar controles persistentes.
+`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
+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`,
 detalhado abaixo. `Page` não recebe flags de dados: uma página pode agregar fontes independentes e
@@ -63,13 +65,63 @@ Não combine `PageBack` com breadcrumb. Use o retorno para um único pai conheci
 mais de um ancestral relevante, envolva o `Breadcrumb` em `PageNavigation`; ele ocupa a mesma
 posição introdutória sem transformar a trilha em ação.
 
-## Cabeçalho em barra
+## Barra persistente do shell
 
-Use `variant="bar"` quando título, retorno e ações precisarem formar uma faixa compacta e persistente
-no topo da página. `Page` estende a borda por toda a largura e mantém o conteúdo da barra alinhado ao
-mesmo teto do body. Nesse modo, `PageBack` vira icon-only e recebe tooltip e nome acessível “Voltar
-para {destino}”. Mantenha também as ações compactas: use `sm` em botões com texto e `icon-sm` em
-botões que exibem somente um ícone.
+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`.
+
+```tsx preview col
+<PageShell
+  navigation={
+    <Breadcrumb>
+      <BreadcrumbList>
+        <BreadcrumbItem>Vendas</BreadcrumbItem>
+        <BreadcrumbSeparator />
+        <BreadcrumbPage>Clientes</BreadcrumbPage>
+      </BreadcrumbList>
+    </Breadcrumb>
+  }
+>
+  <Page
+    title="Clientes"
+    actions={
+      <Button size="sm">
+        <Plus /> Novo cliente
+      </Button>
+    }
+  >
+    Conteúdo da listagem.
+  </Page>
+</PageShell>
+```
+
+A barra permanece visível durante `PageState`; somente a introdução 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`:
+
+```tsx preview col
+<PageShell navigation={<Breadcrumb>...</Breadcrumb>}>
+  <Page>
+    <PageIntro>
+      <PageTitle>Clientes</PageTitle>
+      <PageDescription>Cadastros disponíveis para atendimento.</PageDescription>
+      <PageActions>
+        <Button size="sm">Novo cliente</Button>
+      </PageActions>
+    </PageIntro>
+    <PageBody>Conteúdo da listagem.</PageBody>
+  </Page>
+</PageShell>
+```
+
+## Cabeçalho em barra da própria Page
+
+Use `PageHeader variant="bar"` quando uma página autocontida conhecer título, retorno e ações. Essa
+forma continua útil fora de um shell persistente. `PageBack` vira icon-only e recebe tooltip e nome
+acessível “Voltar para {destino}”. Use `sm` em botões com texto e `icon-sm` em botões somente com
+ícone.
 
 ```tsx preview col
 <Page className="max-w-none">
@@ -86,11 +138,8 @@ botões que exibem somente um ícone.
 </Page>
 ```
 
-Uma página comum não ganha a barra apenas por estar dentro de um shell. Escolha essa variante quando
-a faixa acrescentar contexto ou ações persistentes; sem isso, mantenha o header padrão.
-
-`PageActionsTarget` continua disponível para um workspace imersivo que já possua um chrome próprio.
-Ele projeta somente `PageActions` no elemento informado; não cria uma segunda região de cabeçalho.
+Não aninhe essa variante em `PageShell`, que já possui a barra. `PageActionsTarget` continua
+disponível para um workspace imersivo que tenha chrome próprio e não use `PageShell`.
 
 ## Composição explícita
 
@@ -118,16 +167,21 @@ 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.
+
 ## Estados integrais
 
 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 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
+`empty`, uma `Page` isolada oculta o cabeçalho inteiro — incluindo `PageBack` — e o estado ocupa a
+altura disponível. Dentro de `PageShell`, a barra persistente permanece e somente `PageIntro` é
+ocultado. Uma subpágina isolada que dependa do 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.
+componente intermediário decide qual `PageState` renderizar. Em `ready`, o cabeçalho ou a introdução
+e o conteúdo voltam à composição normal.
 
 ```tsx preview col
 <Page title="Relatório">
@@ -172,6 +226,25 @@ estado na própria seção com `DataState`, `ActionView`, `ActionList` ou `Alert
 | `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
+
+| Propriedade       | Tipo                          | Descrição                                                              |
+| ----------------- | ----------------------------- | ---------------------------------------------------------------------- |
+| `navigation`      | `ReactNode`                   | Navegação contextual da barra, normalmente um `Breadcrumb`.            |
+| `actions`         | `ReactNode`                   | Ações conhecidas pelo shell, antes das ações declaradas pela `Page`.    |
+| `children`        | `ReactNode`                   | Rota que renderiza uma `Page` descendente.                              |
+| `headerClassName` | `string`                      | Classes adicionais do container interno da barra.                      |
+| `className`       | `string`                      | Classes adicionais da moldura.                                         |
+| demais            | Atributos de `HTMLDivElement` | Atributos nativos repassados à moldura.                                 |
+
+## Propriedades de PageIntro
+
+| Propriedade | Tipo                          | Descrição                                                        |
+| ----------- | ----------------------------- | ---------------------------------------------------------------- |
+| `children`  | `ReactNode`                   | Um `PageTitle` e, opcionalmente, descrição e ações da página.     |
+| `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                   | Padrão      | Descrição                                                        |
@@ -202,7 +275,7 @@ estado na própria seção com `DataState`, `ActionView`, `ActionList` ou `Alert
 
 | Propriedade | Tipo                              | Descrição                                              |
 | ----------- | --------------------------------- | ------------------------------------------------------ |
-| `children`  | `ReactNode`                       | Título principal `h1`; compacto na variante `bar`.     |
+| `children`  | `ReactNode`                       | Título principal `h1`; compacto na barra e ampliado em `PageIntro`. |
 | `className` | `string`                          | Classes adicionais do título.                          |
 | demais      | Atributos de `HTMLHeadingElement` | Atributos nativos repassados ao heading.                |
 

package/src/ui/meta.ts

@@ -400,7 +400,7 @@ 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; a forma explícita acrescenta PageBack para retorno simples ou PageNavigation para uma trilha e permite `PageHeader variant=\"bar\"` quando a mesma anatomia precisar virar uma faixa compacta. No header padrão, PageBack fica acima do título; na barra, vira icon-only com tooltip. PageActionsTarget fica restrito a workspaces imersivos com chrome próprio. Quando todo o body estiver carregando, falhar ou estiver vazio, use PageState: ele oculta o header e ocupa a área disponível, centralizado e sem moldura. 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, 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; `PageHeader variant=\"bar\"` atende uma página autocontida. 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.",
   },
   router: {
     name: "router",

package/src/ui/react.tsx

@@ -33,6 +33,7 @@ export type {
   ChatMessage,
   ChatArtifact,
   ChatTranscriptItem,
+  ChatTranscriptMessage,
 } from "./components/primitives/chat.tsx";
 export { Ask } from "./components/primitives/ask.tsx";
 export type { AskProps } from "./components/primitives/ask.tsx";
@@ -421,8 +422,10 @@ export type { DataStateProps } from "./components/patterns/data-state.tsx";
 
 // Esqueleto de página do back-office (main + container + header título/descrição/ação).
 export {
+  PageShell,
   Page,
   PageHeader,
+  PageIntro,
   PageNavigation,
   PageBack,
   PageTitle,
@@ -433,6 +436,7 @@ export {
 } from "./components/patterns/page.tsx";
 export type {
   PageProps,
+  PageShellProps,
   PageBackProps,
   PageHeaderProps,
   PageHeaderVariant,