@softize/opus 18.5.0 → 19.0.0

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

@@ -1,8 +1,8 @@
 ## Navegação dentro de um layout
 
 Use `Sidebar` para apresentar navegação global ou contextual em uma coluna lateral. O componente
-organiza a superfície e compartilha o estado de colapso; posição e largura pertencem a um `Pane`
-dentro de `Split`.
+organiza a superfície e compartilha o estado de colapso; posição e largura pertencem a um
+[`Pane`](/ui/pane) dentro de [`Split`](/ui/split).
 
 O exemplo canônico mantém a largura inicial em `rem`, deixa a navegação rolar e preserva o
 cabeçalho e o rodapé nas extremidades.
@@ -13,8 +13,8 @@ render(
     <Split>
       <Pane initialSize="16rem" inset="none">
         <Sidebar className="w-full">
-          <PaneHeader className="px-4 py-3 text-sm font-semibold">
-            Projeto
+          <PaneHeader>
+            <PaneTitle>Projeto</PaneTitle>
           </PaneHeader>
           <PaneBody>
             <SidebarNav
@@ -50,22 +50,17 @@ divisória ao lado do handle.
 
 ## Anatomia e responsabilidades
 
-Cada parte possui uma responsabilidade única. Essa separação permite reutilizar os mesmos slots em
-uma sidebar fixa, redimensionável ou recolhida.
+A `Sidebar` não tem regiões próprias: o cabeçalho, o corpo rolável e o rodapé são os slots do
+`Pane` que a hospeda, com a anatomia e as propriedades descritas na
+[página da família](/ui/pane).
 
 | Parte | Responsabilidade |
 |---|---|
-| `Split` | Define a relação espacial e, opcionalmente, o redimensionamento. |
-| `Pane` | Define largura, limites e espaçamento interno da coluna. |
+| [`Split`](/ui/split) | Define a relação espacial e, opcionalmente, o redimensionamento. |
+| [`Pane`](/ui/pane) | Define largura e limites da coluna e estrutura suas regiões. |
 | `Sidebar` | Desenha a superfície lateral e fornece o estado de colapso. |
-| `PaneHeader` | Mantém identidade, contexto ou ações no topo. |
-| `PaneBody` | Ocupa o espaço restante e concentra a rolagem vertical. |
-| `PaneFooter` | Mantém ações persistentes no rodapé. |
 | `SidebarNav` | Apresenta e controla os destinos de navegação. |
 
-`PaneContent` continua exportado como alias depreciado de `PaneBody`. Código novo usa
-`PaneBody`.
-
 ## Escolher a navegação
 
 Use `SidebarNav` para grupos planos de destinos. Ele recebe dados e produz `SidebarItem` com a mesma
@@ -151,15 +146,17 @@ const [collapsed, setCollapsed] = useState(false)
 render(
   <div className="flex h-64 overflow-hidden rounded-lg border border-border">
     <Sidebar collapsed={collapsed}>
-      <PaneHeader className="flex h-12 items-center justify-center">
-        <Button
-          variant="ghost"
-          size="icon-sm"
-          aria-label={collapsed ? 'Expandir navegação' : 'Recolher navegação'}
-          onClick={() => setCollapsed((current) => !current)}
-        >
-          <PanelLeftClose className={collapsed ? 'rotate-180' : ''} />
-        </Button>
+      <PaneHeader>
+        <PaneActions>
+          <Button
+            variant="ghost"
+            size="icon-sm"
+            aria-label={collapsed ? 'Expandir navegação' : 'Recolher navegação'}
+            onClick={() => setCollapsed((current) => !current)}
+          >
+            <PanelLeftClose className={collapsed ? 'rotate-180' : ''} />
+          </Button>
+        </PaneActions>
       </PaneHeader>
       <PaneBody>
         <SidebarNav
@@ -241,26 +238,8 @@ O driver de drag-and-drop continua externo e fornece seus atributos por `dragPro
 | `className` | `string` | | Ajusta a raiz. A largura externa deve continuar pertencendo ao `Pane`. |
 | `children` | `ReactNode` | | Cabeçalho, corpo, rodapé ou uma navegação que gerencie a própria estrutura. |
 
-## Propriedades de PaneHeader
-
-| Propriedade | Tipo | Padrão | Descrição |
-|---|---|---|---|
-| `className` | `string` | | Ajusta a faixa fixa e seu espaçamento. |
-| `children` | `ReactNode` | | Identidade, contexto ou ações apresentadas no topo. |
-
-## Propriedades de PaneBody
-
-| Propriedade | Tipo | Padrão | Descrição |
-|---|---|---|---|
-| `className` | `string` | | Ajusta a região flexível e rolável. |
-| `children` | `ReactNode` | | Conteúdo que ocupa o espaço entre cabeçalho e rodapé. |
-
-## Propriedades de PaneFooter
-
-| Propriedade | Tipo | Padrão | Descrição |
-|---|---|---|---|
-| `className` | `string` | | Ajusta a faixa fixa e seu espaçamento. |
-| `children` | `ReactNode` | | Navegação ou ações que precisam permanecer acessíveis no rodapé. |
+`PaneHeader`, `PaneBody` e `PaneFooter` são os slots da família `Pane`; a referência deles está na
+[página do Pane](/ui/pane).
 
 ## Propriedades de SidebarNav
 

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

@@ -15,15 +15,19 @@ avatares e barras com dimensões próximas às linhas de texto esperadas.
 
 ## Card em carregamento
 
-O esqueleto reproduz o layout final do card — título, descrição, conteúdo e ações — para a tela não pular quando os dados chegarem.
+O esqueleto reproduz o layout final do card — título, conteúdo e ações — para a tela não pular
+quando os dados chegarem. O título entra pelo slot do cabeçalho com `asChild`, porque o
+`CardHeader` só aceita os próprios slots.
 
 ```tsx preview col
 <Card>
   <CardHeader>
-    <Skeleton className="h-5 w-40" />
-    <Skeleton className="h-4 w-56" />
+    <CardTitle asChild>
+      <Skeleton className="h-5 w-40" />
+    </CardTitle>
   </CardHeader>
   <CardBody className="space-y-2">
+    <Skeleton className="h-4 w-56" />
     <Skeleton className="h-4 w-full" />
     <Skeleton className="h-4 w-3/4" />
   </CardBody>

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

@@ -8,10 +8,10 @@ layout permanece estático.
 render(
   <div className="h-72 overflow-hidden rounded-lg border border-border">
     <Split resizable>
-      <Pane initialSize={30} minSize={20} inset="none" className="bg-muted/30">
-        <div className="p-4 text-sm">Navegação</div>
+      <Pane initialSize={30} minSize={20} className="bg-muted/30">
+        <p className="text-sm">Navegação</p>
       </Pane>
-      <Pane grow inset="lg">
+      <Pane grow>
         <p className="text-sm text-muted-foreground">
           Conteúdo. Arraste a divisória.
         </p>
@@ -21,26 +21,31 @@ render(
 );
 ```
 
-## Espaçamento interno
+O `Split` responde pela relação espacial e pelo arraste. O que existe dentro de cada área — o
+cabeçalho, o corpo rolável, o rodapé, o recuo e a escolha entre regiões seccionadas e contínuas —
+pertence ao [`Pane`](/ui/pane) e está documentado na página da família.
 
-`Pane` usa `inset="md"` por padrão. Use `none` para navegação e conteúdo que já controla o próprio
-espaçamento; `sm` e `lg` atendem outras densidades.
+## Tamanho de cada pane
 
-## Largura inicial
-
-Quando uma área precisa continuar legível em telas largas, use uma unidade absoluta para o tamanho inicial ou mínimo. Números continuam representando porcentagens; strings aceitam `%`, `rem`, `em`, `vh`, `vw` e `px`. Prefira `rem` para acompanhar a escala tipográfica configurada pela aplicação.
+Cada `Pane` declara o próprio tamanho e o `Split` o aplica. Números representam porcentagens;
+strings aceitam `%`, `rem`, `em`, `vh`, `vw` e `px`. Quando uma área precisa continuar legível em
+telas largas, use uma unidade absoluta no tamanho inicial ou mínimo, de preferência `rem`, para
+acompanhar a escala tipográfica configurada pela aplicação. `grow` entrega o espaço remanescente.
 
 ```tsx
 <Split resizable>
-  <Pane grow inset="none">
+  <Pane grow>
     <Main />
   </Pane>
-  <Pane initialSize="28rem" minSize="20rem" inset="none">
+  <Pane initialSize="28rem" minSize="20rem">
     <Inspector />
   </Pane>
 </Split>
 ```
 
+`minSize` e `maxSize` valem enquanto o `Split` é redimensionável; sem `resizable` eles não limitam
+nada.
+
 ## Persistência
 
 Um layout pode ser restaurado sem acoplar `Split` a um mecanismo específico de armazenamento. Dê um `id` estável a cada `Pane`, leia o valor salvo para formar `defaultLayout` e persista apenas mudanças concluídas pela pessoa.
@@ -135,16 +140,6 @@ render(<Example />);
 | `defaultLayout`   | `Record<string, number>`                  |                | Layout percentual restaurado, indexado pelos ids dos panes.             |
 | `onLayoutChanged` | `(layout, { isUserInteraction }) => void` |                | Chamado ao concluir uma mudança de layout; persista onde fizer sentido. |
 
-## Propriedades de Pane
-
-| Propriedade           | Tipo                             | Padrão  | Descrição                                                                                 |
-| --------------------- | -------------------------------- | ------- | ----------------------------------------------------------------------------------------- |
-| `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 quando o split é redimensionável.                                                 |
-| `grow`                | `boolean`                        | `false` | Ocupa o espaço remanescente no layout simples.                                            |
-| `inset`               | `'none' \| 'sm' \| 'md' \| 'lg'` | `'md'`  | Respiro interno; `none` para chrome, navegação ou conteúdo com inset próprio.             |
-
 ## Propriedades de SurfaceAssistant
 
 | Propriedade      | Tipo        | Padrão  | Descrição                                               |

package/src/ui/docs/registry.tsx

@@ -125,6 +125,7 @@ import actionSearchDialogMd from "./content/action-list-dialog.md?raw";
 import pageMd from "./content/page.md?raw";
 import presentationMd from "./content/presentation.md?raw";
 import contentMd from "./content/content.md?raw";
+import paneMd from "./content/pane.md?raw";
 import sidebarMd from "./content/sidebar.md?raw";
 import splitMd from "./content/split.md?raw";
 import routerMd from "./content/router.md?raw";
@@ -418,8 +419,13 @@ export const UI_SECTIONS: DocSection[] = [
         pages: [
           {
             slug: "split",
-            title: "Split & Pane",
-            render: pattern("Split & Pane", "split", splitMd),
+            title: "Split",
+            render: pattern("Split", "split", splitMd),
+          },
+          {
+            slug: "pane",
+            title: "Pane",
+            render: pattern("Pane", "pane", paneMd),
           },
           {
             slug: "sidebar",

package/src/ui/meta.ts

@@ -327,13 +327,19 @@ export const componentMeta = {
     name: "split",
     ancestry: "opus",
     whenToUse:
-      "Divide uma área em panes em sequência horizontal ou vertical. Use `resizable` quando a pessoa deve ajustar a fronteira; o mesmo `<Split>` vira flex simples sem ele. Cada `<Pane>` declara tamanho inicial/mínimo e inset. SurfaceAssistant especializa esse layout para assistência contextual dentro de Page, Dialog ou Drawer.",
+      "Divide uma área em panes em sequência horizontal ou vertical. Use `resizable` quando a pessoa deve ajustar a fronteira; o mesmo `<Split>` vira flex simples sem ele. Cada `<Pane>` declara tamanho inicial e mínimo; a anatomia do pane tem página própria. SurfaceAssistant especializa esse layout para assistência contextual dentro de Page, Dialog ou Drawer.",
   },
   sidebar: {
     name: "sidebar",
     ancestry: "opus",
     whenToUse:
-      "Organize navegação global ou contextual em uma coluna lateral. Split e Pane definem posição e largura; Sidebar fornece a superfície e o colapso, enquanto PaneHeader, PaneBody e PaneFooter estruturam as regiões fixa e rolável. Use SidebarNav para grupos planos e componha árvores com SidebarItem e SidebarTreeGroup; cabeçalho e rodapé próprios ficam em PaneHeader e PaneFooter.",
+      "Organize navegação global ou contextual em uma coluna lateral. Split e Pane definem posição e largura; Sidebar fornece a superfície e o colapso. Use SidebarNav para grupos planos e componha árvores com SidebarItem e SidebarTreeGroup; cabeçalho e rodapé próprios são do Pane que a hospeda.",
+  },
+  pane: {
+    name: "pane",
+    ancestry: "opus",
+    whenToUse:
+      "Estruture a coluna ou faixa encaixada num Split: PaneHeader nomeia a região e leva mídia e ações, PaneBody rola e PaneFooter fixa o que precisa ficar à vista. `layout` escolhe entre regiões seccionadas, com divisores derivados da vizinhança, e o fluxo contínuo. O `inset` vale para o pane sem slots; com eles, o recuo é de cada região.",
   },
   "scroll-area": {
     name: "scroll-area",

package/src/ui/react.tsx

@@ -93,6 +93,7 @@ export type {
 export {
   Card,
   CardHeader,
+  CardMedia,
   CardTitle,
   CardDescription,
   CardAction,
@@ -132,7 +133,9 @@ export {
   DialogOverlay,
   DialogContent,
   DialogHeader,
+  DialogNavigation,
   DialogMedia,
+  DialogActions,
   DialogBody,
   DialogFooter,
   DialogTitle,
@@ -143,6 +146,10 @@ export type {
   DialogMode,
 } from "./components/primitives/dialog.tsx";
 
+// O pacote de anatomia que Card, Dialog, Drawer e Pane declaram no root (ADR 0023). As
+// tabelas e o contexto continuam internos; o consumidor escolhe entre os dois nomes.
+export type { SurfaceLayout } from "./components/patterns/surface-anatomy.ts";
+
 export {
   Menu,
   MenuTrigger,
@@ -270,10 +277,13 @@ export {
 } from "./components/primitives/collapsible.tsx";
 export {
   Drawer,
+  DrawerActions,
   DrawerClose,
   DrawerContent,
   DrawerFooter,
   DrawerHeader,
+  DrawerMedia,
+  DrawerNavigation,
   DrawerBody,
   DrawerTitle,
   DrawerTrigger,
@@ -522,7 +532,11 @@ export type {
 
 // Barra lateral composicional: header/conteúdo/footer e navegação, sem possuir o layout.
 export {
+  PaneActions,
+  PaneDescription,
   PaneHeader,
+  PaneMedia,
+  PaneTitle,
   PaneBody,
   PaneContent,
   PaneFooter,