@softize/opus 23.0.0 → 24.0.0

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>