@softize/opus 23.0.0 → 24.0.0

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

@@ -8,18 +8,6 @@ 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,
@@ -127,8 +115,8 @@ export function SidebarItem({
           "outline-none",
           focusRing,
           active
-            ? "bg-muted font-medium text-foreground"
-            : "text-foreground/80 hover:bg-muted/60",
+            ? "bg-interaction-selected font-medium text-foreground"
+            : "text-foreground/80 hover:bg-interaction-hover",
         )}
       >
         <span
@@ -159,8 +147,10 @@ export function SidebarItem({
       data-slot="sidebar-item"
       className={cn(
         "group/sidebar-item relative flex items-center rounded-md transition-colors",
-        disabled ? "text-muted-foreground/50 opacity-40" : "hover:bg-muted/60",
-        active && "bg-muted",
+        disabled
+          ? "text-muted-foreground/50 opacity-40"
+          : "hover:bg-interaction-hover",
+        active && "bg-interaction-selected",
         dropPosition === "inside" &&
           "bg-primary/5 ring-2 ring-inset ring-primary/60",
         className,
@@ -333,7 +323,7 @@ export function SidebarTreeGroup({
   );
 }
 
-/** Navegação controlada para Sidebar. Header/footer continuam slots explícitos do pai. */
+/** Navegação controlada para Sidebar. Chrome adicional pertence à composição hospedeira. */
 export function SidebarNav({
   groups,
   activeId,

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

@@ -1,33 +1,43 @@
-import { Children, cloneElement, Fragment, 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'
+import {
+  Children,
+  cloneElement,
+  Fragment,
+  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 }
+// Pane é a unidade espacial de Split; sua apresentação pertence ao filho (ADR 0047).
+export { Pane } from "./pane.tsx";
+export type { PaneProps, PaneSize };
 
-export type SplitLayout = Record<string, number>
+export type SplitLayout = Record<string, number>;
 export interface SplitLayoutChange {
-  isUserInteraction: boolean
+  isUserInteraction: boolean;
 }
 
 export interface SplitProps {
   /** Identidade estável do grupo redimensionável. */
-  id?: string
-  direction?: 'horizontal' | 'vertical'
+  id?: string;
+  direction?: "horizontal" | "vertical";
   /** Quando ligado, cada fronteira ganha um separador acessível e arrastável. */
-  resizable?: boolean
-  handle?: boolean
+  resizable?: boolean;
+  handle?: boolean;
   /** Layout percentual restaurado, indexado pelos ids dos panes. */
-  defaultLayout?: SplitLayout
+  defaultLayout?: SplitLayout;
   /** Chamado ao concluir uma mudança de layout; pode persistir o resultado em localStorage. */
-  onLayoutChanged?: (layout: SplitLayout, meta: SplitLayoutChange) => void
-  className?: string
+  onLayoutChanged?: (layout: SplitLayout, meta: SplitLayoutChange) => void;
+  className?: string;
   /** Identificador semântico opcional para testes e composição de patterns. */
-  'data-slot'?: string
-  children: ReactNode
+  "data-slot"?: string;
+  children: ReactNode;
 }
 
 /**
@@ -35,27 +45,36 @@ export interface SplitProps {
  * `Children.toArray` numera as chaves por nível, então o filho de um fragment herda a
  * chave do fragment como prefixo — sem isso, `.0` de dentro colidiria com `.0` de fora.
  */
-function flattenFragments(children: ReactNode, prefix = ''): ReactNode[] {
+function flattenFragments(children: ReactNode, prefix = ""): ReactNode[] {
   return Children.toArray(children).flatMap((node): ReactNode[] => {
     if (isValidElement(node) && node.type === Fragment)
-      return flattenFragments((node.props as { children?: ReactNode }).children, `${prefix}${String(node.key)}/`)
-    if (prefix !== '' && isValidElement(node)) return [cloneElement(node, { key: `${prefix}${String(node.key)}` })]
-    return [node]
-  })
+      return flattenFragments(
+        (node.props as { children?: ReactNode }).children,
+        `${prefix}${String(node.key)}/`,
+      );
+    if (prefix !== "" && isValidElement(node))
+      return [cloneElement(node, { key: `${prefix}${String(node.key)}` })];
+    return [node];
+  });
 }
 
 /** Nome legível do filho recusado, para a mensagem apontar o nó certo. */
 function describeChild(node: ReactNode): string {
-  if (typeof node === 'string' || typeof node === 'number' || typeof node === 'bigint') {
-    const text = String(node).trim()
-    return `o texto "${text.length > 40 ? `${text.slice(0, 40)}…` : text}"`
+  if (
+    typeof node === "string" ||
+    typeof node === "number" ||
+    typeof node === "bigint"
+  ) {
+    const text = String(node).trim();
+    return `o texto "${text.length > 40 ? `${text.slice(0, 40)}…` : text}"`;
   }
   if (isValidElement(node)) {
-    const type = node.type as string | { displayName?: string; name?: string }
-    const name = typeof type === 'string' ? type : (type.displayName ?? type.name ?? '')
-    return name === '' ? 'um componente sem nome' : `<${name}>`
+    const type = node.type as string | { displayName?: string; name?: string };
+    const name =
+      typeof type === "string" ? type : (type.displayName ?? type.name ?? "");
+    return name === "" ? "um componente sem nome" : `<${name}>`;
   }
-  return 'um nó que não é elemento React'
+  return "um nó que não é elemento React";
 }
 
 /**
@@ -65,27 +84,27 @@ function describeChild(node: ReactNode): string {
  */
 function panesOf(children: ReactNode): ReactElement<PaneProps>[] {
   return flattenFragments(children).flatMap((child) => {
-    if (isValidElement<PaneProps>(child) && child.type === Pane) return [child]
+    if (isValidElement<PaneProps>(child) && child.type === Pane) return [child];
     // Espaço em branco (um `{' '}` da formatação) não é conteúdo: nunca ocupou lugar.
-    if (typeof child === 'string' && child.trim() === '') return []
+    if (typeof child === "string" && child.trim() === "") return [];
     throw new Error(
       `Split recebeu ${describeChild(child)} como filho, mas só distribui <Pane>: esse conteúdo ficaria fora do layout. ` +
-        'Envolva-o em um <Pane>. Se ele vem de um componente que devolve um <Pane>, escreva o <Pane> dentro do Split e ' +
-        'passe o componente como filho dele: o Split lê o tamanho de cada pane antes de renderizá-lo.',
-    )
-  })
+        "Envolva-o em um <Pane>. Se ele vem de um componente que devolve um <Pane>, escreva o <Pane> dentro do Split e " +
+        "passe o componente como filho dele: o Split lê o tamanho de cada pane antes de renderizá-lo.",
+    );
+  });
 }
 
 // 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 resizableSize(value: PaneSize | undefined): string | undefined {
-  return value === undefined ? undefined : paneSizeToCss(value)
+  return value === undefined ? undefined : paneSizeToCss(value);
 }
 
 function percentage(value: PaneSize | undefined): number | undefined {
-  if (typeof value === 'number') return value
-  if (value?.endsWith('%')) return Number.parseFloat(value)
-  return undefined
+  if (typeof value === "number") return value;
+  if (value?.endsWith("%")) return Number.parseFloat(value);
+  return undefined;
 }
 
 /**
@@ -95,31 +114,47 @@ function percentage(value: PaneSize | undefined): number | undefined {
  */
 export function Split({
   id,
-  direction = 'horizontal',
+  direction = "horizontal",
   resizable = false,
   handle = false,
   defaultLayout,
   onLayoutChanged,
   className,
-  'data-slot': dataSlot = 'split',
+  "data-slot": dataSlot = "split",
   children,
 }: SplitProps): React.ReactElement {
-  const panes = panesOf(children)
-  const vertical = direction === 'vertical'
+  const panes = panesOf(children);
+  const vertical = direction === "vertical";
 
   if (!resizable) {
     return (
-      <div id={id === undefined ? undefined : String(id)} data-slot={dataSlot} data-direction={direction} className={cn('flex min-h-0 min-w-0 flex-1', vertical && 'flex-col', className)}>
+      <div
+        id={id === undefined ? undefined : String(id)}
+        data-slot={dataSlot}
+        data-direction={direction}
+        className={cn(
+          "flex min-h-0 min-w-0 flex-1",
+          vertical && "flex-col",
+          className,
+        )}
+      >
         {panes}
       </div>
-    )
+    );
   }
 
-  const fixed = panes.reduce((sum, pane) => sum + (percentage(pane.props.initialSize) ?? 0), 0)
-  const hasAbsoluteSize = panes.some((pane) => typeof pane.props.initialSize === 'string' && !pane.props.initialSize.endsWith('%'))
-  const growing = panes.filter((pane) => pane.props.grow)
-  const rest = Math.max(0, 100 - fixed)
-  const fallback = panes.length === 0 ? 100 : 100 / panes.length
+  const fixed = panes.reduce(
+    (sum, pane) => sum + (percentage(pane.props.initialSize) ?? 0),
+    0,
+  );
+  const hasAbsoluteSize = panes.some(
+    (pane) =>
+      typeof pane.props.initialSize === "string" &&
+      !pane.props.initialSize.endsWith("%"),
+  );
+  const growing = panes.filter((pane) => pane.props.grow);
+  const rest = Math.max(0, 100 - fixed);
+  const fallback = panes.length === 0 ? 100 : 100 / panes.length;
 
   return (
     <ResizablePanelGroup
@@ -128,11 +163,16 @@ export function Split({
       defaultLayout={defaultLayout}
       onLayoutChanged={onLayoutChanged}
       data-slot={dataSlot}
-      className={cn('min-h-0 min-w-0 flex-1', className)}
+      className={cn("min-h-0 min-w-0 flex-1", className)}
     >
       {panes.flatMap((pane, index) => {
-        const size = pane.props.initialSize
-          ?? (hasAbsoluteSize ? undefined : pane.props.grow ? rest / Math.max(1, growing.length) : fallback)
+        const size =
+          pane.props.initialSize ??
+          (hasAbsoluteSize
+            ? undefined
+            : pane.props.grow
+              ? rest / Math.max(1, growing.length)
+              : fallback);
         const panel = (
           <ResizablePanel
             key={pane.key ?? index}
@@ -141,11 +181,23 @@ export function Split({
             minSize={resizableSize(pane.props.minSize)}
             maxSize={resizableSize(pane.props.maxSize)}
           >
-            <Pane {...pane.props} id={undefined} className={cn('h-full w-full', pane.props.className)} />
+            <Pane
+              {...pane.props}
+              id={undefined}
+              className={cn("h-full w-full", pane.props.className)}
+            />
           </ResizablePanel>
-        )
-        return index === 0 ? [panel] : [<ResizableHandle key={`handle-${pane.key ?? index}`} withHandle={handle} />, panel]
+        );
+        return index === 0
+          ? [panel]
+          : [
+              <ResizableHandle
+                key={`handle-${pane.key ?? index}`}
+                withHandle={handle}
+              />,
+              panel,
+            ];
       })}
     </ResizablePanelGroup>
-  )
+  );
 }

package/src/ui/components/patterns/{surface-header.tsx → structural-header.tsx}

@@ -1,5 +1,6 @@
 /**
- * Cabeçalho de superfície (interno): a anatomia que Page e Content compartilham.
+ * Cabeçalho estrutural (interno): a anatomia que Page, Surface, Dialog, Drawer e Pane
+ * compartilham. O nome público `SurfaceHeader` pertence à família Surface (ADR 0045).
  *
  * Um título, metadata opcional e uma região de ações que vai para o extremo oposto
  * em larguras amplas e empilha abaixo do contexto nas estreitas. Cada família escolhe quais slots
@@ -17,11 +18,11 @@ import {
 } from "react";
 import { cn } from "../../lib/cn.ts";
 
-export type SurfaceHeaderVariant = "page" | "section";
+export type StructuralHeaderVariant = "page" | "section";
 
-/** As classes por slot, por hierarquia visual — PageTitle e ContentTitle(page) são o mesmo. */
-export const surfaceHeaderClasses: Record<
-  SurfaceHeaderVariant,
+/** As classes por slot, por hierarquia visual — PageTitle e SurfaceTitle no nível 1 são o mesmo. */
+export const structuralHeaderClasses: Record<
+  StructuralHeaderVariant,
   { title: string; description: string; count: string; actions: string }
 > = {
   page: {
@@ -38,7 +39,7 @@ export const surfaceHeaderClasses: Record<
   },
 };
 
-interface SurfaceHeaderSlots {
+interface StructuralHeaderSlots {
   leading?: ElementType | readonly ElementType[];
   /** Ícone ou imagem que abre a linha, antes do heading (ADR 0023). */
   media?: ElementType;
@@ -48,15 +49,15 @@ interface SurfaceHeaderSlots {
   actions?: ElementType;
 }
 
-export interface SurfaceHeaderProps extends HTMLAttributes<HTMLDivElement> {
+export interface StructuralHeaderProps extends HTMLAttributes<HTMLDivElement> {
   /** Elemento estrutural; `legend` preserva a mesma anatomia com wrappers phrasing. */
   as?: "div" | "legend";
-  /** Nome do componente público, para as mensagens de erro (`PageHeader`, `ContentHeader`). */
+  /** Nome do componente público, para as mensagens de erro (`PageHeader`, `SurfaceHeader`). */
   name: string;
   /** Prefixo dos `data-slot` (`page` → `page-header`, `page-heading`). */
   slot: string;
   /** Os componentes de slot que este cabeçalho reconhece. */
-  slots: SurfaceHeaderSlots;
+  slots: StructuralHeaderSlots;
   /** Posição de um slot introdutório opcional, antes da linha ou dentro dela. */
   leadingPlacement?: "above" | "inline";
   /** Mantém a mídia na linha geral ou a agrupa com o heading. */
@@ -72,7 +73,7 @@ export interface SurfaceHeaderProps extends HTMLAttributes<HTMLDivElement> {
   /**
    * Aceita conteúdo livre além dos slots. Vale para a superfície genérica — um pane
    * hospeda marca, busca ou chrome que não são título nem ação. As famílias que sempre
-   * NOMEIAM algo (Card, Dialog, Drawer, Page, Content) continuam estritas.
+   * NOMEIAM algo (Surface, Dialog, Drawer, Page) continuam estritas.
    */
   allowFreeContent?: boolean;
   /**
@@ -91,7 +92,7 @@ function flatten(children: ReactNode): ReactNode[] {
   );
 }
 
-export function SurfaceHeader({
+export function StructuralHeader({
   as: Root = "div",
   name,
   slot,
@@ -107,7 +108,7 @@ export function SurfaceHeader({
   className,
   children,
   ...props
-}: SurfaceHeaderProps): ReactElement {
+}: StructuralHeaderProps): ReactElement {
   const Wrapper = Root === "legend" ? "span" : "div";
   const nodes = flatten(children);
   const of = (type: ElementType) =>
@@ -124,8 +125,7 @@ export function SurfaceHeader({
   const counts = slots.count === undefined ? [] : of(slots.count);
   const descriptions =
     slots.description === undefined ? [] : of(slots.description);
-  const actionSlots =
-    slots.actions === undefined ? [] : of(slots.actions);
+  const actionSlots = slots.actions === undefined ? [] : of(slots.actions);
   const slotTypes = [
     ...leadingTypes,
     slots.media,
@@ -137,7 +137,9 @@ export function SurfaceHeader({
   const free = allowFreeContent
     ? nodes.filter(
         (node) =>
-          !(isValidElement(node) && slotTypes.includes(node.type as ElementType)),
+          !(
+            isValidElement(node) && slotTypes.includes(node.type as ElementType)
+          ),
       )
     : [];
   const recognized =
@@ -242,16 +244,26 @@ export function SurfaceHeader({
       )}
       {mediaPlacement === "row" && medias}
       {heading}
+      {!heading && leading.length === 0 && (
+        <Wrapper
+          data-slot={`${slot}-header-spacer`}
+          className="min-w-0 flex-1"
+          aria-hidden="true"
+        />
+      )}
       {actionSlots}
       {trailing}
     </>
   );
   const layout =
     leadingPlacement === "inline" ? (
-      <Wrapper className={cn("flex min-w-0 items-center gap-3", rowClassName)}>
+      <Wrapper
+        data-slot={`${slot}-header-row`}
+        className={cn("flex min-w-0 items-center gap-3", rowClassName)}
+      >
         {row}
       </Wrapper>
-    ) : leading.length > 0 ? (
+    ) : leading.length > 0 && heading ? (
       <>
         <Wrapper data-slot={`${slot}-navigation`} className="mb-4">
           {leading}
@@ -267,6 +279,19 @@ export function SurfaceHeader({
           {actionSlots}
         </Wrapper>
       </>
+    ) : leading.length > 0 ? (
+      <Wrapper
+        data-slot={`${slot}-header-row`}
+        className="flex min-w-0 items-center gap-4"
+      >
+        <Wrapper
+          data-slot={`${slot}-navigation`}
+          className="min-w-0 flex-1"
+        >
+          {leading}
+        </Wrapper>
+        {actionSlots}
+      </Wrapper>
     ) : (
       <>
         {heading}
@@ -282,7 +307,10 @@ export function SurfaceHeader({
           leadingPlacement !== "inline" &&
           leading.length === 0 &&
           actionSlots.length > 0 &&
-          "flex flex-row items-end justify-between gap-4",
+          cn(
+            "flex flex-row items-end gap-4",
+            heading ? "justify-between" : "justify-end",
+          ),
         className,
       )}
       {...props}
@@ -290,7 +318,10 @@ export function SurfaceHeader({
       {contentClassName === undefined ? (
         layout
       ) : (
-        <Wrapper data-slot={`${slot}-header-content`} className={contentClassName}>
+        <Wrapper
+          data-slot={`${slot}-header-content`}
+          className={contentClassName}
+        >
           {layout}
         </Wrapper>
       )}

package/src/ui/components/patterns/structural-media.tsx

@@ -0,0 +1,26 @@
+/**
+ * Slot de mídia estrutural (interno): abre a linha do header de Dialog, Drawer e Pane
+ * sem decidir a apresentação do conteúdo. A moldura, quando necessária, é composta
+ * explicitamente com `IconTile` pelo consumidor.
+ */
+import type { ReactElement } from "react";
+import { cn } from "../../lib/cn.ts";
+
+export interface StructuralMediaProps extends React.ComponentProps<"div"> {}
+
+export function StructuralMedia({
+  slot,
+  className,
+  ...props
+}: StructuralMediaProps & { slot: string }): ReactElement {
+  return (
+    <div
+      data-slot={slot}
+      className={cn(
+        "flex shrink-0 items-center justify-center [&>svg:not([class*='size-'])]:size-4",
+        className,
+      )}
+      {...props}
+    />
+  );
+}