@softize/opus 18.4.0 → 19.0.0

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

@@ -0,0 +1,294 @@
+/**
+ * Pane — a superfície encaixável de um Split: a coluna ou faixa que hospeda navegação,
+ * lista ou conteúdo, com regiões fixas no topo e no rodapé e um corpo que rola.
+ *
+ * Até a ADR 0023 esta família vivia partida: a raiz em `split.tsx`, os slots em
+ * `sidebar.tsx`, sem validação entre eles e com padding assimétrico (header sem recuo,
+ * footer com `p-2`). Agora raiz e slots moram aqui e derivam a anatomia da mesma tabela
+ * das demais famílias.
+ *
+ *   <Pane>
+ *     <PaneHeader><PaneMedia>…</PaneMedia><PaneTitle>Conversas</PaneTitle><PaneActions>…</PaneActions></PaneHeader>
+ *     <PaneBody>…</PaneBody>
+ *     <PaneFooter>…</PaneFooter>
+ *   </Pane>
+ *
+ * `inset` continua existindo para o pane que NÃO usa slots — a caixa simples que recebe
+ * conteúdo direto. Quando há slots, o recuo é de cada região, e o inset do pane vira
+ * `none` sozinho: o divisor precisa alcançar a borda.
+ */
+import {
+  Children,
+  Fragment,
+  isValidElement,
+  type CSSProperties,
+  type ReactElement,
+  type ReactNode,
+} from "react";
+
+import { cn } from "../../lib/cn.ts";
+import { headingTags, type HeadingLevel } from "./heading-level.ts";
+import {
+  SurfaceLayoutProvider,
+  surfaceActionsClasses,
+  surfaceDescriptionClasses,
+  surfaceHeaderRowClasses,
+  surfaceRegionClasses,
+  surfaceTitleClasses,
+  useSurfaceLayout,
+  type SurfaceLayout,
+} from "./surface-anatomy.ts";
+import { SurfaceHeader } from "./surface-header.tsx";
+import { SurfaceMedia, type SurfaceMediaProps } from "./surface-media.tsx";
+
+export type PaneSize =
+  | number
+  | `${number}%`
+  | `${number}rem`
+  | `${number}em`
+  | `${number}vh`
+  | `${number}vw`
+  | `${number}px`;
+
+// Números continuam percentuais por compatibilidade com Split/Pane. Strings preservam
+// a unidade explícita para layouts que precisam de um limite físico, como `28rem`.
+export function paneSizeToCss(value: PaneSize): string {
+  return typeof value === "number" ? `${value}%` : value;
+}
+
+export interface PaneProps {
+  /** Identidade estável do painel dentro do grupo. */
+  id?: string;
+  /** Tamanho inicial. Números representam porcentagens; strings aceitam %, rem, em, vh, vw e px. */
+  initialSize?: PaneSize;
+  /** Tamanho mínimo quando o split é redimensionável. */
+  minSize?: PaneSize;
+  /** Tamanho máximo quando o split é redimensionável. */
+  maxSize?: PaneSize;
+  /** Ocupa o espaço remanescente no layout simples. */
+  grow?: boolean;
+  /**
+   * Respiro interno do pane sem slots. Com header, body ou footer como filhos DIRETOS o
+   * default passa a `none`, porque aí o recuo é de cada região. Quando os slots vêm
+   * dentro de outro componente — a `Sidebar`, por exemplo —, o pane não os enxerga:
+   * declare `inset="none"` você mesmo.
+   */
+  inset?: "none" | "sm" | "md" | "lg";
+  /** Anatomia das regiões: `sectioned` (default) ou `continuous` — ADR 0023. */
+  layout?: SurfaceLayout;
+  className?: string;
+  children: ReactNode;
+}
+
+const insets = { none: "", sm: "p-2", md: "p-4", lg: "p-6" } as const;
+
+/** Expande fragments de primeiro nível antes de procurar os slots. */
+function flatten(children: ReactNode): ReactNode[] {
+  return Children.toArray(children).flatMap((node) =>
+    isValidElement(node) && node.type === Fragment
+      ? Children.toArray((node.props as { children?: ReactNode }).children)
+      : [node],
+  );
+}
+
+function hasStructuralSlots(children: ReactNode): boolean {
+  return flatten(children).some(
+    (node) =>
+      isValidElement(node) &&
+      (node.type === PaneHeader ||
+        node.type === PaneBody ||
+        node.type === PaneContent ||
+        node.type === PaneFooter),
+  );
+}
+
+/** Um conteúdo encaixável. Sua posição é dada pela ordem dentro de <Split>. */
+export function Pane({
+  id,
+  initialSize,
+  grow = false,
+  inset,
+  layout = "sectioned",
+  className,
+  children,
+}: PaneProps): ReactElement {
+  const style: CSSProperties | undefined =
+    initialSize === undefined
+      ? undefined
+      : { flexBasis: paneSizeToCss(initialSize) };
+  const structural = hasStructuralSlots(children);
+  const resolvedInset = inset ?? (structural ? "none" : "md");
+  return (
+    <SurfaceLayoutProvider value={layout}>
+      <div
+        id={id === undefined ? undefined : String(id)}
+        data-slot="pane"
+        data-inset={resolvedInset}
+        data-layout={layout}
+        className={cn(
+          "min-h-0 min-w-0 shrink-0",
+          grow && "flex-1",
+          // Com slots o pane é uma coluna: header fixo, corpo que rola, footer fixo.
+          structural && "flex flex-col",
+          insets[resolvedInset],
+          className,
+        )}
+        style={style}
+      >
+        {children}
+      </div>
+    </SurfaceLayoutProvider>
+  );
+}
+
+/** Faixa fixa no topo de um pane — marca, contexto ou ações locais. */
+export function PaneHeader({
+  className,
+  children,
+  ...props
+}: React.ComponentProps<"div">): ReactElement {
+  const layout = useSurfaceLayout("pane");
+  return (
+    <SurfaceHeader
+      name="PaneHeader"
+      slot="pane"
+      slots={{
+        media: PaneMedia,
+        title: PaneTitle,
+        description: PaneDescription,
+        actions: PaneActions,
+      }}
+      leadingPlacement="inline"
+      titleRequired={false}
+      // O pane é a superfície genérica: além dos slots, o header hospeda marca, busca ou
+      // chrome que não são título nem ação (ADR 0023).
+      allowFreeContent
+      rowClassName={surfaceHeaderRowClasses("pane")}
+      className={cn(surfaceRegionClasses("pane", layout, "header"), className)}
+      {...props}
+    >
+      {children}
+    </SurfaceHeader>
+  );
+}
+
+/** Moldura de ícone ou imagem que abre a linha do header. */
+export function PaneMedia(props: SurfaceMediaProps): ReactElement {
+  return <SurfaceMedia slot="pane-media" size="xs" {...props} />;
+}
+
+export function PaneTitle({
+  className,
+  level = 2,
+  ...props
+}: React.ComponentProps<"h2"> & {
+  /** Hierarquia do documento (`h1`–`h6`). O tamanho vem do layout, nunca do nível. */
+  level?: HeadingLevel;
+}): ReactElement {
+  const layout = useSurfaceLayout("pane");
+  const Comp = headingTags[level];
+  return (
+    <Comp
+      data-slot="pane-title"
+      className={cn(
+        "min-w-0 truncate",
+        surfaceTitleClasses("pane", layout),
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+export function PaneDescription({
+  className,
+  ...props
+}: React.ComponentProps<"p">): ReactElement {
+  return (
+    <p
+      data-slot="pane-description"
+      className={cn("truncate", surfaceDescriptionClasses("pane"), className)}
+      {...props}
+    />
+  );
+}
+
+/** Ações do header — a família posiciona no extremo oposto ao título. */
+export function PaneActions({
+  className,
+  ...props
+}: React.ComponentProps<"div">): ReactElement {
+  return (
+    <div
+      data-slot="pane-actions"
+      className={cn(surfaceActionsClasses, className)}
+      {...props}
+    />
+  );
+}
+
+/** Região rolável que ocupa o espaço restante de um pane. */
+export function PaneBody({
+  className,
+  children,
+  ...props
+}: React.ComponentProps<"div">): ReactElement {
+  const layout = useSurfaceLayout("pane");
+  return (
+    <div
+      data-slot="pane-body"
+      className={cn(
+        "min-h-0 flex-1 overflow-y-auto",
+        surfaceRegionClasses("pane", layout, "body"),
+        className,
+      )}
+      {...props}
+    >
+      {children}
+    </div>
+  );
+}
+
+/** @deprecated Use PaneBody. Alias mantido para migração; sai numa próxima versão major. */
+export function PaneContent({
+  className,
+  children,
+  ...props
+}: React.ComponentProps<"div">): ReactElement {
+  const layout = useSurfaceLayout("pane");
+  return (
+    <div
+      data-slot="pane-content"
+      className={cn(
+        "min-h-0 flex-1 overflow-y-auto",
+        surfaceRegionClasses("pane", layout, "body"),
+        className,
+      )}
+      {...props}
+    >
+      {children}
+    </div>
+  );
+}
+
+/** Faixa fixa no rodapé de um pane para ações persistentes. */
+export function PaneFooter({
+  className,
+  children,
+  ...props
+}: React.ComponentProps<"div">): ReactElement {
+  const layout = useSurfaceLayout("pane");
+  return (
+    <div
+      data-slot="pane-footer"
+      className={cn(
+        "shrink-0",
+        surfaceRegionClasses("pane", layout, "footer"),
+        className,
+      )}
+      {...props}
+    >
+      {children}
+    </div>
+  );
+}

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

@@ -42,18 +42,22 @@ import { Copyable } from "../primitives/copyable.tsx";
 import { DetailField, DetailGroup } from "../primitives/detail.tsx";
 import {
   Dialog,
+  DialogActions,
   DialogBody,
   DialogContent,
   DialogFooter,
   DialogHeader,
+  DialogNavigation,
   DialogTitle,
 } from "../primitives/dialog.tsx";
 import {
   Drawer,
+  DrawerActions,
   DrawerBody,
   DrawerContent,
   DrawerFooter,
   DrawerHeader,
+  DrawerNavigation,
   DrawerTitle,
 } from "../primitives/drawer.tsx";
 import {
@@ -253,6 +257,11 @@ function PresentationFrame({
               )}
             </PageHeader>
           )}
+          {contentOwnsHeading ? null : (
+            <PageIntro>
+              <PageTitle>{title}</PageTitle>
+            </PageIntro>
+          )}
           <PageBody className="min-h-0 flex-1 overflow-hidden">
             {withAssistant(
               <div
@@ -261,11 +270,6 @@ function PresentationFrame({
                   layout === "fill" ? "overflow-y-hidden" : "overflow-y-auto",
                 )}
               >
-                {contentOwnsHeading ? null : (
-                  <PageIntro>
-                    <PageTitle>{title}</PageTitle>
-                  </PageIntro>
-                )}
                 {body}
               </div>,
             )}
@@ -334,14 +338,18 @@ function PresentationFrame({
         >
           <div className="flex h-full min-h-0 flex-col">
             <DialogHeader>
-              {navigation}
-              <DialogTitle className="truncate">{title}</DialogTitle>
+              {navigation === undefined ? null : (
+                <DialogNavigation>{navigation}</DialogNavigation>
+              )}
+              <DialogTitle>{title}</DialogTitle>
               {headerActions === undefined &&
               assistantAction === undefined ? null : (
-                <PresentationActions>
-                  {headerActions}
-                  {assistantAction}
-                </PresentationActions>
+                <DialogActions>
+                  <PresentationActions>
+                    {headerActions}
+                    {assistantAction}
+                  </PresentationActions>
+                </DialogActions>
               )}
             </DialogHeader>
             {withAssistant(<DialogBody>{body}</DialogBody>)}
@@ -380,14 +388,18 @@ function PresentationFrame({
       >
         <div className="flex h-full min-h-0 flex-col">
           <DrawerHeader>
-            {navigation}
-            <DrawerTitle className="truncate">{title}</DrawerTitle>
+            {navigation === undefined ? null : (
+              <DrawerNavigation>{navigation}</DrawerNavigation>
+            )}
+            <DrawerTitle>{title}</DrawerTitle>
             {headerActions === undefined &&
             assistantAction === undefined ? null : (
-              <PresentationActions>
-                {headerActions}
-                {assistantAction}
-              </PresentationActions>
+              <DrawerActions>
+                <PresentationActions>
+                  {headerActions}
+                  {assistantAction}
+                </PresentationActions>
+              </DrawerActions>
             )}
           </DrawerHeader>
           {withAssistant(<DrawerBody>{body}</DrawerBody>)}

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

@@ -7,6 +7,19 @@ import {
 import { ChevronRight } from "lucide-react";
 import { useOverflowing } from "../../lib/overflow.ts";
 import { cn } from "../../lib/cn.ts";
+
+// Os slots de Pane moram em `pane.tsx` desde a ADR 0023. A Sidebar continua sendo uma
+// das superfícies que os compõe, então reexporta o que antes definia.
+export {
+  PaneActions,
+  PaneBody,
+  PaneContent,
+  PaneDescription,
+  PaneFooter,
+  PaneHeader,
+  PaneMedia,
+  PaneTitle,
+} from "./pane.tsx";
 import { focusRing } from "../primitives/control.ts";
 import {
   Tooltip,
@@ -58,78 +71,6 @@ export function Sidebar({
   );
 }
 
-/** Faixa fixa no topo de um pane — marca, contexto ou ações locais. */
-export function PaneHeader({
-  className,
-  children,
-}: {
-  className?: string;
-  children: ReactNode;
-}): React.ReactElement {
-  return (
-    <div
-      data-slot="pane-header"
-      className={cn("shrink-0 border-b border-border", className)}
-    >
-      {children}
-    </div>
-  );
-}
-
-/** Região rolável que ocupa o espaço restante de um pane. */
-export function PaneBody({
-  className,
-  children,
-}: {
-  className?: string;
-  children: ReactNode;
-}): React.ReactElement {
-  return (
-    <div
-      data-slot="pane-body"
-      className={cn("min-h-0 flex-1 overflow-y-auto", className)}
-    >
-      {children}
-    </div>
-  );
-}
-
-/** @deprecated Use PaneBody. Alias mantido para migração; sai numa próxima versão major. */
-export function PaneContent({
-  className,
-  children,
-}: {
-  className?: string;
-  children: ReactNode;
-}): React.ReactElement {
-  return (
-    <div
-      data-slot="pane-content"
-      className={cn("min-h-0 flex-1 overflow-y-auto", className)}
-    >
-      {children}
-    </div>
-  );
-}
-
-/** Faixa fixa no rodapé de um pane para ações persistentes. */
-export function PaneFooter({
-  className,
-  children,
-}: {
-  className?: string;
-  children: ReactNode;
-}): React.ReactElement {
-  return (
-    <div
-      data-slot="pane-footer"
-      className={cn("shrink-0 border-t border-border p-2", className)}
-    >
-      {children}
-    </div>
-  );
-}
-
 export interface SidebarItemProps {
   label: string;
   icon?: ReactNode;

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

@@ -1,41 +1,18 @@
-import { Children, isValidElement, type CSSProperties, type ReactElement, type ReactNode } from 'react'
+import { Children, isValidElement, type ReactElement, type ReactNode } from 'react'
 import { cn } from '../../lib/cn.ts'
 import { ResizableHandle, ResizablePanel, ResizablePanelGroup } from '../primitives/resizable.tsx'
+import { Pane, paneSizeToCss, type PaneProps, type PaneSize } from './pane.tsx'
+
+// A família Pane mora em `pane.tsx` desde a ADR 0023; o Split continua sendo sua casa
+// pública, então reexporta o que já era importado daqui.
+export { Pane, PaneActions, PaneBody, PaneContent, PaneDescription, PaneFooter, PaneHeader, PaneMedia, PaneTitle } from './pane.tsx'
+export type { PaneProps, PaneSize }
 
-export type PaneSize = number | `${number}%` | `${number}rem` | `${number}em` | `${number}vh` | `${number}vw` | `${number}px`
 export type SplitLayout = Record<string, number>
 export interface SplitLayoutChange {
   isUserInteraction: boolean
 }
 
-export interface PaneProps {
-  /** Identidade estável usada pelo layout redimensionável e por layouts persistidos. */
-  id?: string
-  /** Tamanho inicial. Números representam porcentagens; strings aceitam %, rem, em, vh, vw e px. */
-  initialSize?: PaneSize
-  /** Tamanho mínimo quando o split é redimensionável. */
-  minSize?: PaneSize
-  /** Tamanho máximo quando o split é redimensionável. */
-  maxSize?: PaneSize
-  /** Ocupa o espaço remanescente no layout simples. */
-  grow?: boolean
-  /** Respiro interno padrão. Use `none` para chrome, navegação ou conteúdo com inset próprio. */
-  inset?: 'none' | 'sm' | 'md' | 'lg'
-  className?: string
-  children: ReactNode
-}
-
-/** Um conteúdo encaixável. Sua posição é dada pela ordem dentro de <Split>. */
-export function Pane({ id, initialSize, grow = false, inset = 'md', className, children }: PaneProps): React.ReactElement {
-  const style: CSSProperties | undefined = initialSize === undefined ? undefined : { flexBasis: sizeToCss(initialSize) }
-  const insets = { none: '', sm: 'p-2', md: 'p-4', lg: 'p-6' } as const
-  return (
-    <div id={id === undefined ? undefined : String(id)} data-slot="pane" data-inset={inset} className={cn('min-h-0 min-w-0 shrink-0', grow && 'flex-1', insets[inset], className)} style={style}>
-      {children}
-    </div>
-  )
-}
-
 export interface SplitProps {
   /** Identidade estável do grupo redimensionável. */
   id?: string
@@ -61,12 +38,8 @@ function panesOf(children: ReactNode): ReactElement<PaneProps>[] {
 
 // Números continuam percentuais por compatibilidade com Split/Pane. Strings preservam
 // a unidade explícita para layouts que precisam de um limite físico, como `28rem`.
-function sizeToCss(value: PaneSize): string {
-  return typeof value === 'number' ? `${value}%` : value
-}
-
 function resizableSize(value: PaneSize | undefined): string | undefined {
-  return value === undefined ? undefined : sizeToCss(value)
+  return value === undefined ? undefined : paneSizeToCss(value)
 }
 
 function percentage(value: PaneSize | undefined): number | undefined {