@softize/opus 23.0.0 → 24.0.0

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

@@ -1,320 +1,71 @@
-## A coluna encaixada em um layout
+## Uma unidade de layout do Split
 
-Use `Pane` para a coluna ou faixa que ocupa uma das posições de um [`Split`](/ui/split): a
-navegação à esquerda, o inspetor à direita, a lista que abre o detalhe ao lado. O `Split` decide a
-relação espacial e o redimensionamento; o `Pane` decide o que existe dentro da área recebida.
-
-No formato mais simples, o pane é uma caixa com recuo e o conteúdo é seu.
+Use `Pane` somente para declarar uma coluna ou faixa dentro de [`Split`](/ui/split). Ele informa
+identidade e limites de tamanho, mas não cria superfície, recuo, borda, fundo, rolagem ou regiões
+internas. Essa separação mantém o redimensionamento independente da apresentação.
 
 ```tsx preview
 render(
   <div className="h-56 overflow-hidden rounded-lg border border-border">
     <Split>
-      <Pane initialSize="16rem" className="bg-muted/30">
-        <p className="text-sm text-muted-foreground">Navegação.</p>
+      <Pane initialSize="16rem">
+        <Surface framed className="h-full">
+          <SurfaceBody>
+            <p className="text-sm text-muted-foreground">Navegação.</p>
+          </SurfaceBody>
+        </Surface>
       </Pane>
       <Pane grow>
-        <p className="text-sm text-muted-foreground">Conteúdo.</p>
+        <main className="h-full overflow-y-auto p-6">
+          <p className="text-sm text-muted-foreground">Conteúdo.</p>
+        </main>
       </Pane>
     </Split>
   </div>,
 );
 ```
 
-## Cabeçalho, corpo e rodapé
-
-Quando a área precisa de regiões fixas e de um corpo que rola, componha os slots. `PaneHeader`
-nomeia a região, `PaneBody` ocupa o espaço restante e concentra a rolagem vertical, e `PaneFooter`
-mantém à vista o que não pode sair da tela.
-
-```tsx preview
-render(
-  <div className="h-72 overflow-hidden rounded-lg border border-border">
-    <Split>
-      <Pane initialSize="18rem">
-        <PaneHeader>
-          <PaneMedia>
-            <MessagesSquare />
-          </PaneMedia>
-          <PaneTitle>Conversas</PaneTitle>
-          <PaneActions>
-            <Button variant="ghost" size="icon-sm" aria-label="Nova conversa">
-              <SquarePen />
-            </Button>
-          </PaneActions>
-        </PaneHeader>
-        <PaneBody className="space-y-1">
-          <p className="text-sm">Revisão do contrato</p>
-          <p className="text-sm text-muted-foreground">
-            Importação de clientes
-          </p>
-          <p className="text-sm text-muted-foreground">Fila de execuções</p>
-        </PaneBody>
-        <PaneFooter>
-          <Button variant="ghost" size="sm">
-            Ver arquivadas
-          </Button>
-        </PaneFooter>
-      </Pane>
-      <Pane grow>
-        <p className="text-sm text-muted-foreground">Conversa selecionada.</p>
-      </Pane>
-    </Split>
-  </div>,
-);
-```
-
-O cabeçalho reconhece quatro slots — `PaneMedia`, `PaneTitle`, `PaneDescription` e `PaneActions` —
-e monta a linha sozinho: mídia, título e descrição de um lado, ações no extremo oposto. A ordem em
-que os slots são escritos não altera a posição. Cada slot aparece no máximo uma vez: repetir um
-deles interrompe a renderização com um erro que lista os slots aceitos.
-
-Título e descrição truncam quando a coluna encolhe, em vez de quebrar a altura da faixa.
+Quando a região precisa de cabeçalho, corpo, rodapé ou aparência elevada, componha uma
+[`Surface`](/ui/surface) dentro do pane. Quando o filho já é uma estrutura completa, como
+`Sidebar`, ele pode ocupar o pane diretamente.
 
-Nas ações do cabeçalho, use `Button` `ghost` no tamanho `icon-sm` (1.75rem), como nos exemplos. O
-pane é uma superfície densa, com título e descrição em escala menor, e o quadrado menor acompanha
-essa escala. [`Dialog`](/ui/dialog) e [`Drawer`](/ui/drawer) usam `icon` (2.25rem) no voltar e nas
-ações do cabeçalho, e a [`Presentation`](/ui/presentation) usa o mesmo tamanho no voltar e no botão
-que abre o assistente.
+## Redimensionamento
 
-## Busca ou marca no cabeçalho
-
-Uma coluna às vezes precisa, no topo, de algo que não é título nem ação: uma busca que filtra a
-lista, a marca de uma barra lateral. Escreva esse conteúdo direto dentro do `PaneHeader`, ao lado
-dos slots. Só o `Pane` aceita conteúdo livre no cabeçalho; os headers de `Card`, `Dialog` e `Drawer`
-aceitam apenas os próprios slots.
+Em um `Split` redimensionável, use `id` estável em cada pane. Números representam porcentagens;
+strings preservam unidades explícitas.
 
 ```tsx preview
 render(
   <div className="h-56 overflow-hidden rounded-lg border border-border">
-    <Split>
-      <Pane initialSize="18rem">
-        <PaneHeader>
-          <Input
-            icon={<Search />}
-            placeholder="Buscar conversa"
-            aria-label="Buscar conversa"
+    <Split id="workspace" resizable>
+      <Pane id="navigation" initialSize="18rem" minSize="14rem" maxSize="28rem">
+        <Sidebar className="w-full">
+          <SidebarNav
+            navLabel="Projeto"
+            activeId="overview"
+            groups={[{ items: [{ id: "overview", label: "Visão geral" }] }]}
           />
-          <PaneActions>
-            <Button variant="ghost" size="icon-sm" aria-label="Nova conversa">
-              <SquarePen />
-            </Button>
-          </PaneActions>
-        </PaneHeader>
-        <PaneBody className="space-y-1">
-          <p className="text-sm">Revisão do contrato</p>
-          <p className="text-sm text-muted-foreground">
-            Importação de clientes
-          </p>
-        </PaneBody>
+        </Sidebar>
       </Pane>
-      <Pane grow>
-        <p className="text-sm text-muted-foreground">Conversa selecionada.</p>
+      <Pane id="content" grow minSize="20rem">
+        <main className="h-full overflow-y-auto p-6">Conteúdo principal.</main>
       </Pane>
     </Split>
   </div>,
 );
 ```
 
-O conteúdo livre ocupa o lugar do título e absorve a largura disponível, por isso as ações
-continuam no extremo oposto. Quando há título, o conteúdo livre vem sempre depois do título e da descrição,
-qualquer que seja a ordem no JSX: uma busca escrita junto de um `PaneTitle` aparece abaixo dele, não
-ao lado. Para algo antes do título, use `PaneMedia`; para algo ao lado, use `PaneActions`.
-
-## Escolher entre seccionado e contínuo
-
-`layout` declara a anatomia da superfície inteira e fica no root; os slots leem esse valor e não o
-recebem. Cada valor é um pacote de recuo, ritmo vertical e divisores.
-
-| Aspecto            | `sectioned` (padrão)      | `continuous`                     |
-| ------------------ | ------------------------- | -------------------------------- |
-| Divisores          | entre as regiões vizinhas | nenhum                           |
-| Faixa do cabeçalho | altura fixa de `3.75rem`  | acompanha o conteúdo             |
-| Ritmo vertical     | regiões simétricas        | o cabeçalho se aproxima do corpo |
-
-O padrão `sectioned` é o pane de operação: a faixa do cabeçalho preserva uma medida fixa para que
-painéis irmãos mantenham o mesmo ritmo. Use `continuous` quando o pane for um bloco de leitura
-contínuo, sem fronteiras a marcar.
-
-Os divisores são derivados da vizinhança: cada região desenha a linha quando há uma região do outro
-lado. Um cabeçalho sem corpo não fecha nada, e um cabeçalho seguido direto de um rodapé produz uma
-linha só. A tela não escreve `border-b` nem `border-t`.
-
-No `continuous`, um cabeçalho sem corpo nem rodapé fecha o pane com o mesmo recuo que tem em cima.
-Uma classe `pb-*` no `PaneHeader` não altera esse recuo: a regra só vale quando o cabeçalho é a
-última região e tem precedência sobre o `className`. No `sectioned`, a faixa tem altura fixa e
-centraliza a linha, então não há recuo de baixo a ajustar.
-
-## Recuo do pane e recuo das regiões
-
-`inset` é o respiro interno do pane sem slots: `md` por padrão, com `none`, `sm` e `lg`
-disponíveis. Quando `PaneHeader`, `PaneBody` ou `PaneFooter` são filhos **diretos** do pane, o recuo
-passa a ser de cada região e o `inset` vira `none` sozinho — é o que permite ao divisor alcançar a
-borda da coluna.
-
-O ajuste enxerga só o primeiro nível. Se os slots vierem dentro de outro componente — é o caso da
-`Sidebar`, que traz a superfície e o colapso —, o pane não sabe que eles existem: declare
-`inset="none"` você mesmo, ou a coluna ganha um recuo que empurra o divisor para dentro.
-
-## A matriz de layouts e slots
-
-As regiões são independentes: a coluna usa só as que precisa, nos dois layouts, e os divisores
-acompanham as regiões presentes.
-
-```tsx preview col
-render(
-  <div className="grid grid-cols-2 gap-4">
-    <div className="h-56 overflow-hidden rounded-lg border border-border">
-      <Pane className="h-full">
-        <PaneHeader>
-          <PaneTitle>Seccionado</PaneTitle>
-          <PaneActions>
-            <Button variant="ghost" size="icon-sm" aria-label="Mais ações">
-              <Ellipsis />
-            </Button>
-          </PaneActions>
-        </PaneHeader>
-        <PaneBody>
-          <p className="text-sm text-muted-foreground">
-            Cabeçalho, corpo e rodapé.
-          </p>
-        </PaneBody>
-        <PaneFooter>
-          <Button variant="ghost" size="sm">
-            Configurações
-          </Button>
-        </PaneFooter>
-      </Pane>
-    </div>
-    <div className="h-56 overflow-hidden rounded-lg border border-border">
-      <Pane layout="continuous" className="h-full">
-        <PaneHeader>
-          <PaneMedia>
-            <ChartNoAxesColumn />
-          </PaneMedia>
-          <PaneTitle>Contínuo com mídia</PaneTitle>
-          <PaneDescription>O espaço separa as regiões.</PaneDescription>
-        </PaneHeader>
-        <PaneBody>
-          <p className="text-sm text-muted-foreground">
-            Sem rodapé e sem divisores.
-          </p>
-        </PaneBody>
-      </Pane>
-    </div>
-    <div className="h-56 overflow-hidden rounded-lg border border-border">
-      <Pane className="h-full">
-        <PaneBody>
-          <p className="text-sm text-muted-foreground">
-            Só corpo: nenhuma fronteira a marcar.
-          </p>
-        </PaneBody>
-      </Pane>
-    </div>
-    <div className="h-56 overflow-hidden rounded-lg border border-border">
-      <Pane className="h-full">
-        <PaneHeader>
-          <PaneMedia context="primary">
-            <Folder />
-          </PaneMedia>
-          <PaneTitle>Sem corpo</PaneTitle>
-        </PaneHeader>
-        <PaneFooter>
-          <Button variant="ghost" size="sm">
-            Ação persistente
-          </Button>
-        </PaneFooter>
-      </Pane>
-    </div>
-  </div>,
-);
-```
-
-## Onde termina o Pane
-
-Três componentes dividem a responsabilidade de uma coluna, e trocá-los de papel é a origem mais
-comum de layout duplicado:
-
-| Componente               | Responsabilidade                                                            |
-| ------------------------ | --------------------------------------------------------------------------- |
-| [`Split`](/ui/split)     | Relação espacial entre as áreas e, com `resizable`, o arraste da fronteira. |
-| `Pane`                   | Tamanho recebido, recuo e as regiões internas: cabeçalho, corpo e rodapé.   |
-| [`Sidebar`](/ui/sidebar) | Superfície da navegação lateral e o estado de colapso dos destinos.         |
-
-Tamanho inicial, limites e persistência do layout são declarados no `Pane` e operados pelo `Split`
-— a [página do Split](/ui/split) trata deles. Uma `Sidebar` é composta dentro de um `Pane` e usa os
-mesmos slots para o próprio cabeçalho e rodapé; ela não tem regiões próprias.
-
-## Hierarquia do título
-
-`PaneTitle` é um heading. `level` escolhe a hierarquia do documento, de `1` a `6`, com `2` como
-padrão. O tamanho visual vem da família e do `layout`, não do nível, então corrigir a estrutura do
-documento não muda a aparência da faixa.
-
-## Propriedades de Pane
-
-| Propriedade           | Tipo                             | Padrão                                | Descrição                                                                                 |
-| --------------------- | -------------------------------- | ------------------------------------- | ----------------------------------------------------------------------------------------- |
-| `layout`              | `'continuous' \| 'sectioned'`    | `'sectioned'`                         | Anatomia da superfície inteira; os slots leem esse valor e não o recebem.                 |
-| `inset`               | `'none' \| 'sm' \| 'md' \| 'lg'` | `'md'`, ou `'none'` com slots diretos | Respiro interno do pane sem slots; slots dentro de outro componente exigem declarar.      |
-| `id`                  | `string`                         |                                       | Identidade estável usada pelo layout redimensionável e persistido.                        |
-| `initialSize`         | `number \| string`               |                                       | Tamanho inicial; número é porcentagem, string aceita `%`, `rem`, `em`, `vh`, `vw` e `px`. |
-| `minSize` / `maxSize` | `number \| string`               |                                       | Limites aplicados pelo `Split` quando ele é redimensionável.                              |
-| `grow`                | `boolean`                        | `false`                               | Ocupa o espaço remanescente no layout simples.                                            |
-| `className`           | `string`                         |                                       | Ajusta a coluna.                                                                          |
-| `children`            | `ReactNode`                      |                                       | Conteúdo direto ou os slots estruturais.                                                  |
-
-## Propriedades de PaneHeader
-
-| Propriedade | Tipo        | Padrão | Descrição                                                                                                                                         |
-| ----------- | ----------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `children`  | `ReactNode` |        | `PaneMedia`, `PaneTitle`, `PaneDescription` e `PaneActions`, no máximo um de cada, e conteúdo livre, que aparece depois do título e da descrição. |
-| `className` | `string`    |        | Ajusta a faixa fixa sobre o recuo do layout.                                                                                                      |
-
-## Propriedades de PaneMedia
-
-| Propriedade | Tipo                                                                     | Padrão      | Descrição                                                                                                                  |
-| ----------- | ------------------------------------------------------------------------ | ----------- | -------------------------------------------------------------------------------------------------------------------------- |
-| `size`      | `'xs' \| 'sm' \| 'default' \| 'lg'`                                      | `'xs'`      | Tamanho da moldura e do glifo na escala compartilhada.                                                                     |
-| `context`   | `'neutral' \| 'primary' \| 'info' \| 'success' \| 'warning' \| 'danger'` | `'neutral'` | Declara o significado da cor.                                                                                              |
-| `variant`   | `'subtle' \| 'outline'`                                                  | `'subtle'`  | Usa preenchimento tonal ou acrescenta borda.                                                                               |
-| `className` | `string`                                                                 |             | Ajusta a moldura sem substituir a escala.                                                                                  |
-| `asChild`   | `boolean`                                                                | `false`     | Cede o elemento para uma marca com visual próprio — um orbe, um logotipo — que ocupa o slot sem ganhar a moldura por cima. |
-
-## Propriedades de PaneTitle
-
-| Propriedade | Tipo                         | Padrão | Descrição                                                           |
-| ----------- | ---------------------------- | ------ | ------------------------------------------------------------------- |
-| `level`     | `1 \| 2 \| 3 \| 4 \| 5 \| 6` | `2`    | Hierarquia do documento. O tamanho vem do `layout`, nunca do nível. |
-| `className` | `string`                     |        | Ajusta o título, que trunca quando não cabe.                        |
-
-## Propriedades de PaneDescription
-
-| Propriedade | Tipo        | Padrão | Descrição                                                  |
-| ----------- | ----------- | ------ | ---------------------------------------------------------- |
-| `children`  | `ReactNode` |        | Frase curta de apoio sob o título; trunca quando não cabe. |
-| `className` | `string`    |        | Ajusta a descrição.                                        |
-
-## Propriedades de PaneActions
-
-| Propriedade | Tipo        | Padrão | Descrição                              |
-| ----------- | ----------- | ------ | -------------------------------------- |
-| `children`  | `ReactNode` |        | Controles no extremo oposto ao título. |
-| `className` | `string`    |        | Ajusta o agrupamento das ações.        |
-
-## Propriedades de PaneBody
-
-| Propriedade | Tipo        | Padrão | Descrição                                             |
-| ----------- | ----------- | ------ | ----------------------------------------------------- |
-| `children`  | `ReactNode` |        | Conteúdo que ocupa o espaço entre cabeçalho e rodapé. |
-| `className` | `string`    |        | Ajusta a região flexível e rolável.                   |
-
-`PaneContent` continua exportado como alias depreciado de `PaneBody` e sai em uma próxima versão
-maior. Código novo usa `PaneBody`.
+## Propriedades
 
-## Propriedades de PaneFooter
+| Propriedade   | Tipo                                               | Padrão  | Descrição                                                                |
+| ------------- | -------------------------------------------------- | ------- | ------------------------------------------------------------------------ |
+| `id`          | `string`                                           |         | Identidade estável dentro do grupo, necessária para persistir o layout.  |
+| `initialSize` | `number \| \`${number}%\` \| rem, em, vh, vw ou px |         | Tamanho inicial. Números representam porcentagens.                       |
+| `minSize`     | mesmo tipo de `initialSize`                        |         | Limite mínimo durante o redimensionamento.                               |
+| `maxSize`     | mesmo tipo de `initialSize`                        |         | Limite máximo durante o redimensionamento.                               |
+| `grow`        | `boolean`                                          | `false` | Faz a região ocupar o espaço remanescente no layout simples.             |
+| `className`   | `string`                                           |         | Ajustes de layout da unidade, sem substituir a superfície do conteúdo.   |
+| `children`    | `ReactNode`                                        |         | Estrutura responsável pela apresentação e organização interna da região. |
 
-| Propriedade | Tipo        | Padrão | Descrição                                                        |
-| ----------- | ----------- | ------ | ---------------------------------------------------------------- |
-| `children`  | `ReactNode` |        | Navegação ou ações que precisam permanecer acessíveis no rodapé. |
-| `className` | `string`    |        | Ajusta a faixa fixa sobre o recuo do layout.                     |
+`Pane` não possui slots. APIs antigas como `PaneHeader`, `PaneBody` e `PaneFooter` foram removidas;
+use a anatomia de `Surface` quando essas regiões forem necessárias.

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

@@ -93,8 +93,8 @@ Dentro de [`PageShell`](/ui/page), a superfície `page` usa a anatomia real da a
 com `PageFooter` quando há ações de rodapé.
 
 Uma Presentation de listagem exibida como página muda essa distribuição para manter a criação perto
-da coleção. O `PageBody` recebe um [`Content`](/ui/content) com a
-[`ActionList`](/ui/action-list), e o cabeçalho desse `Content` recebe o título e os comandos
+da coleção. O `PageBody` recebe um [`Surface`](/ui/surface) com a
+[`ActionList`](/ui/action-list), e o cabeçalho desse `Surface` recebe o título e os comandos
 declarados com `placement: "header"`, no extremo oposto ao título. Os comandos de cabeçalho usam o
 tamanho `default` e permanecem textuais, mesmo quando a action declara um ícone: o que abre outra
 Presentation é um `Button` sólido, e uma action `simple` vira um
@@ -185,7 +185,7 @@ componente exige `children`, e uma com body de action os recusa: nos dois casos,
 lança um erro que nomeia a Presentation.
 
 Com `heading: "shell"`, o padrão, a casca emite o título da definição. Quando o conteúdo React já
-declara o heading principal da página, como um `Content level={1}`, use `heading: "content"`: dentro
+declara o heading principal da página, como um `Surface level={1}`, use `heading: "content"`: dentro
 de `PageShell`, a casca deixa de emitir o `PageHeader` com título e o documento continua com um único `h1`. Em
 Dialog e Drawer, o título continua no cabeçalho da superfície.
 

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

@@ -12,7 +12,7 @@ com regiões. A orientação horizontal fica entre blocos empilhados e ocupa tod
 <p className="text-sm text-muted-foreground">Próximo horário livre hoje, às 14h.</p>
 ```
 
-Não use `Separator` entre cabeçalho, corpo e rodapé de [`Card`](/ui/card), [`Dialog`](/ui/dialog) ou
+Não use `Separator` entre cabeçalho, corpo e rodapé de [`Surface`](/ui/surface), [`Dialog`](/ui/dialog) ou
 [`Drawer`](/ui/drawer). Nessas superfícies, os divisores são derivados das regiões presentes: use
 `layout="sectioned"` no componente raiz.
 
@@ -32,8 +32,8 @@ Use a orientação vertical entre itens lado a lado. A linha herda a altura do c
 
 ## Propriedades de Separator
 
-| Propriedade | Tipo | Padrão | Descrição |
-|---|---|---|---|
-| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | Direção da linha. A vertical precisa de altura vinda do contêiner. |
-| `decorative` | `boolean` | `true` | Uma linha decorativa fica fora da árvore de acessibilidade. Use `false` quando a divisão tiver significado e precisar ser anunciada. |
-| `className` | `string` | | Ajusta a linha, como o espaçamento ao redor. |
+| Propriedade   | Tipo                         | Padrão         | Descrição                                                                                                                            |
+| ------------- | ---------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | Direção da linha. A vertical precisa de altura vinda do contêiner.                                                                   |
+| `decorative`  | `boolean`                    | `true`         | Uma linha decorativa fica fora da árvore de acessibilidade. Use `false` quando a divisão tiver significado e precisar ser anunciada. |
+| `className`   | `string`                     |                | Ajusta a linha, como o espaçamento ao redor.                                                                                         |