@softize/opus 23.0.0 → 24.0.1

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 =
@@ -228,30 +230,72 @@ export function SurfaceHeader({
   );
   // A região introdutória carrega o mesmo `data-slot` nas duas apresentações: seletor de teste
   // ou de CSS que funcione no header padrão precisa funcionar na barra.
-  const row = (
-    <>
-      {leadingPlacement === "inline" && leading.length > 0 && (
-        // `min-w-0` aqui é o que deixa a trilha do PageNavigation ceder e truncar; sem ele o
-        // wrapper assume o min-content do breadcrumb e a compressão toda cai sobre o título.
+  // Navegação e título formam um contexto com intervalo de 0,5rem (ADR 0049). O intervalo da
+  // linha continua separando esse contexto das ações, e a mídia mantém, até o título, o mesmo
+  // intervalo que teria sem navegação.
+  const rowMedias = mediaPlacement === "row" ? medias : [];
+  const inlineContext =
+    leadingPlacement === "inline" && leading.length > 0 && heading ? (
+      <Wrapper
+        data-slot={`${slot}-header-context`}
+        className="flex min-w-0 flex-1 items-center gap-2"
+      >
         <Wrapper
           data-slot={`${slot}-navigation`}
-          className={cn("flex min-w-0 items-center", !heading && "flex-1")}
+          className="flex min-w-0 items-center"
         >
           {leading}
         </Wrapper>
+        {rowMedias.length > 0 ? (
+          <Wrapper
+            data-slot={`${slot}-header-identity`}
+            className={cn("flex min-w-0 items-center gap-3", rowClassName)}
+          >
+            {rowMedias}
+            {heading}
+          </Wrapper>
+        ) : (
+          heading
+        )}
+      </Wrapper>
+    ) : null;
+  const row = (
+    <>
+      {inlineContext}
+      {inlineContext === null &&
+        leadingPlacement === "inline" &&
+        leading.length > 0 && (
+          // `min-w-0` aqui é o que deixa a trilha do PageNavigation ceder e truncar; sem ele o
+          // wrapper assume o min-content do breadcrumb e a compressão toda cai sobre o título.
+          <Wrapper
+            data-slot={`${slot}-navigation`}
+            className={cn("flex min-w-0 items-center", !heading && "flex-1")}
+          >
+            {leading}
+          </Wrapper>
+        )}
+      {inlineContext === null && mediaPlacement === "row" && medias}
+      {inlineContext === null && heading}
+      {!heading && leading.length === 0 && (
+        <Wrapper
+          data-slot={`${slot}-header-spacer`}
+          className="min-w-0 flex-1"
+          aria-hidden="true"
+        />
       )}
-      {mediaPlacement === "row" && medias}
-      {heading}
       {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 +311,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 +339,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 +350,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}
+    />
+  );
+}

package/src/ui/components/patterns/surface-anatomy.ts

@@ -1,6 +1,6 @@
 /**
- * Anatomia de superfície (interno): as medidas que Card, Dialog, Drawer e Pane
- * compartilham — ADR 0023.
+ * Anatomia de superfície (interno): as medidas que Surface, Dialog e Drawer
+ * compartilham — ADRs 0023, 0045 e 0047.
  *
  * Aqui mora o que antes era escrito seis vezes: recuo de cada região, ritmo vertical,
  * escala do título, posição das ações e a regra dos divisores. As famílias públicas
@@ -10,13 +10,12 @@
  *
  * - `continuous` — sem divisores. O ritmo separa: o header se aproxima do corpo e a
  *   última região — seja ela o header, o body ou o footer — fecha o espaço de baixo com
- *   o mesmo respiro do topo. É o card de leitura.
+ *   o mesmo respiro do topo. É a superfície de leitura.
  * - `sectioned` — regiões simétricas, com divisor entre as que forem adjacentes. É o
  *   modal, o drawer e o painel.
  *
  * O recuo lateral é o mesmo nas três regiões da mesma superfície; é isso que a suíte
- * transversal verifica. Entre famílias diferentes ele pode divergir: o card de leitura
- * é mais folgado que um painel de operação.
+ * transversal verifica.
  */
 
 import {
@@ -28,7 +27,7 @@ import {
 } from "react";
 import { FillBoundary } from "./fill-region.ts";
 
-export type SurfaceFamily = "card" | "dialog" | "drawer" | "pane";
+export type SurfaceFamily = "surface" | "dialog" | "drawer";
 export type SurfaceLayout = "continuous" | "sectioned";
 export type SurfaceRegion = "header" | "body" | "footer";
 
@@ -70,44 +69,56 @@ interface FamilyAnatomy {
 }
 
 /**
- * O recuo seccionado de Card, Dialog e Drawer: 1rem, a densidade das superfícies de
- * operação, e o que permite um card seccionado conviver com um drawer sem degrau
- * visível. O pane tem a sua (`px-3`, a do chrome), declarada na tabela abaixo.
+ * O recuo seccionado de Dialog e Drawer: 1rem, a densidade das superfícies de operação.
+ * A Surface usa o mesmo recuo lateral, para conviver com um drawer sem degrau visível, e
+ * faixas de header e footer mais baixas.
  */
 const sectionedRegions: RegionAnatomy = {
   header: "p-4",
-  body: "p-4",
+  body: "px-4 py-6",
   footer: "p-4",
 };
 
+/**
+ * Ritmo entre blocos diretos do conteúdo; relações internas pertencem a um wrapper filho.
+ * Os blocos não encolhem: o body é quem rola quando a família tem altura limitada.
+ */
+const structuralBodyRhythm = "flex flex-col gap-6 *:shrink-0";
+
 export const surfaceAnatomy: Record<SurfaceFamily, FamilyAnatomy> = {
-  card: {
+  // Medidas da Surface delimitada (com moldura ou elevação). Sem delimitação, as regiões
+  // não recebem recuo: a superfície flui alinhada ao hospedeiro (ADR 0045).
+  surface: {
     regions: {
-      // O `pb-3` do header e do body encurtam a distância até a região seguinte; quando
-      // a região é a última, ela reassume o respiro de baixo (`[&:last-child]:pb-5`) —
-      // inclusive o header sozinho, que sem isso fecharia o card mais apertado embaixo
-      // do que em cima.
+      // O espaço entre regiões soma o ritmo estrutural. Quando o header fica sozinho, ele
+      // reassume o respiro compacto da faixa; quando o body abre ou fecha a superfície,
+      // recebe o respiro inteiro do conteúdo.
       continuous: {
-        header: "px-5 pt-5 pb-3 [&:last-child]:pb-5",
-        body: "px-5 py-3 [&:last-child]:pb-5 [&:first-child]:pt-5",
-        footer: "px-5 pt-3 pb-5",
+        header: "px-4 pt-4 pb-6 [&:last-child]:pb-4",
+        body: "px-4 pt-0 pb-6 [&:first-child]:pt-6",
+        footer: "px-4 pt-0 pb-4 [&:first-child]:pt-4",
+      },
+      sectioned: {
+        header: "px-4 py-3",
+        body: "px-4 py-6",
+        footer: "px-4 py-3",
       },
-      sectioned: sectionedRegions,
     },
+    // Uma escala só: o nível 1 troca a apresentação inteira (ADR 0038), nunca o layout.
     title: {
-      continuous: "text-base font-semibold leading-none",
-      sectioned: "text-sm font-semibold leading-none",
+      continuous: "text-sm font-semibold",
+      sectioned: "text-sm font-semibold",
     },
-    description: "text-sm text-muted-foreground",
-    headerGap: "gap-3",
+    description: "mt-0.5 text-xs text-muted-foreground",
+    headerGap: "gap-2",
     footerBand: "",
   },
   dialog: {
     regions: {
       continuous: {
-        header: "p-4 pb-2 [&:last-child]:pb-4",
-        body: "p-4 py-2 [&:last-child]:pb-4 [&:first-child]:pt-4",
-        footer: "p-4 pt-2",
+        header: "p-4 pb-3 [&:last-child]:pb-4",
+        body: "px-4 py-3 [&:last-child]:pb-6 [&:first-child]:pt-6",
+        footer: "p-4 pt-3",
       },
       sectioned: sectionedRegions,
     },
@@ -122,9 +133,9 @@ export const surfaceAnatomy: Record<SurfaceFamily, FamilyAnatomy> = {
   drawer: {
     regions: {
       continuous: {
-        header: "p-4 pb-2 [&:last-child]:pb-4",
-        body: "p-4 py-2 [&:last-child]:pb-4 [&:first-child]:pt-4",
-        footer: "p-4 pt-2",
+        header: "p-4 pb-3 [&:last-child]:pb-4",
+        body: "px-4 py-3 [&:last-child]:pb-6 [&:first-child]:pt-6",
+        footer: "p-4 pt-3",
       },
       sectioned: sectionedRegions,
     },
@@ -136,29 +147,6 @@ export const surfaceAnatomy: Record<SurfaceFamily, FamilyAnatomy> = {
     headerGap: "gap-4",
     footerBand: "bg-muted/20 dark:bg-input/20",
   },
-  pane: {
-    regions: {
-      continuous: {
-        header: "flex shrink-0 items-center px-3 pt-3 pb-2 [&:last-child]:pb-3",
-        body: "p-3 [&:first-child]:pt-3",
-        footer: "px-3 pt-2 pb-3",
-      },
-      sectioned: {
-        // A faixa tem a altura da barra do shell; `flex items-center` centraliza a linha
-        // dentro dela, e `shrink-0` impede que um corpo longo comprima a faixa.
-        header: "flex h-[3.75rem] shrink-0 items-center px-3",
-        body: "p-3",
-        footer: "px-3 py-2",
-      },
-    },
-    title: {
-      continuous: "text-sm font-semibold leading-none",
-      sectioned: "text-sm font-semibold leading-none",
-    },
-    description: "text-xs text-muted-foreground",
-    headerGap: "gap-2",
-    footerBand: "",
-  },
 };
 
 /** Classes da região, já com o divisor que o layout deriva da vizinhança. */
@@ -166,14 +154,22 @@ export function surfaceRegionClasses(
   family: SurfaceFamily,
   layout: SurfaceLayout,
   region: SurfaceRegion,
+  { flush = false }: { flush?: boolean } = {},
 ): string {
   const anatomy = surfaceAnatomy[family];
-  const base = anatomy.regions[layout][region];
-  if (layout !== "sectioned") return base;
-  if (region === "header") return `${base} ${headerDivider}`;
+  const base =
+    region === "body" && flush
+      ? structuralBodyRhythm
+      : anatomy.regions[layout][region];
+  const regionClasses =
+    region === "body" && !flush ? `${base} ${structuralBodyRhythm}` : base;
+  if (layout !== "sectioned") return regionClasses;
+  if (region === "header") return `${regionClasses} ${headerDivider}`;
   if (region === "footer")
-    return [base, footerDivider, anatomy.footerBand].filter(Boolean).join(" ");
-  return base;
+    return [regionClasses, footerDivider, anatomy.footerBand]
+      .filter(Boolean)
+      .join(" ");
+  return regionClasses;
 }
 
 /** Escala visual do título — o nível do heading vem da composição, nunca daqui. */
@@ -191,8 +187,7 @@ export function surfaceDescriptionClasses(family: SurfaceFamily): string {
 /**
  * A linha do header: mídia, heading que absorve a folga, ações no extremo oposto.
  *
- * `flex-1` não é decoração: quando a própria região é flex — o pane, que tem altura de
- * barra —, a linha vira um item que se mede pelo conteúdo e as ações param no meio.
+ * `flex-1` mantém o heading como região elástica e as ações no extremo oposto.
  */
 export function surfaceHeaderRowClasses(family: SurfaceFamily): string {
   return `flex min-w-0 flex-1 items-center ${surfaceAnatomy[family].headerGap}`;
@@ -201,6 +196,22 @@ export function surfaceHeaderRowClasses(family: SurfaceFamily): string {
 /** Ações do header e do footer: fora do fluxo de compressão, na escala densa. */
 export const surfaceActionsClasses = "flex shrink-0 items-center gap-2";
 
+/**
+ * A `legend` de uma Surface `fieldset` delimitada (ADR 0045).
+ *
+ * - `notch`: moldura contínua. A legend nativa ocupa a borda, afastada do canto pelo
+ *   mesmo recuo lateral das regiões; a região seguinte recebe o intervalo que a legend
+ *   não tem como declarar.
+ * - `band`: a legend é a faixa do header dentro da superfície. Uma legend só ocupa a
+ *   largura inteira fora do fluxo de borda, e a região seguinte precisa limpar o float.
+ */
+export const surfaceLegendClasses = {
+  notch: "ml-2 w-auto px-2",
+  afterNotch: "pt-3",
+  band: "float-left w-full",
+  afterBand: "clear-left",
+} as const;
+
 /**
  * O layout é do root e chega aos slots por contexto — ADR 0023. Slot não recebe
  * `layout`: o divisor depende de quem está do outro lado, então a decisão precisa valer
@@ -230,10 +241,9 @@ export function SurfaceLayoutProvider({
 }
 
 const familyDefaultLayout: Record<SurfaceFamily, SurfaceLayout> = {
-  card: "continuous",
+  surface: "continuous",
   dialog: "sectioned",
   drawer: "sectioned",
-  pane: "sectioned",
 };
 
 /** O layout vigente: o declarado pelo root da superfície, ou o default da família. */

package/src/ui/components/patterns/surface-assistant.tsx

@@ -45,7 +45,6 @@ export function SurfaceAssistant({
         key="surface-content"
         id="surface-content"
         grow
-        inset="none"
         className={cn("h-full", contentClassName)}
       >
         {children}
@@ -57,13 +56,12 @@ export function SurfaceAssistant({
           initialSize={initialSize}
           minSize={minSize}
           maxSize={maxSize}
-          inset="none"
-          className={cn("h-full bg-background", assistantClassName)}
+          className={cn("h-full", assistantClassName)}
         >
           <aside
             data-slot="surface-assistant-panel"
             aria-label={assistantLabel}
-            className="h-full min-w-0 overflow-hidden"
+            className="h-full min-w-0 overflow-hidden bg-background"
           >
             {assistant}
           </aside>