@softize/opus 27.1.0 → 29.0.0

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

@@ -110,7 +110,9 @@ export function StructuralHeader({
   ...props
 }: StructuralHeaderProps): ReactElement {
   const Wrapper = Root === "legend" ? "span" : "div";
-  const nodes = flatten(children);
+  const nodes = flatten(children).filter(
+    (node) => typeof node !== "string" || node.trim() !== "",
+  );
   const of = (type: ElementType) =>
     nodes.filter((node) => isValidElement(node) && node.type === type);
   const leadingTypes: readonly ElementType[] =
@@ -305,6 +307,7 @@ export function StructuralHeader({
           className={cn(
             actionSlots.length > 0 &&
               "flex flex-row items-end justify-between gap-4",
+            rowClassName,
           )}
         >
           {heading}
@@ -314,16 +317,24 @@ export function StructuralHeader({
     ) : leading.length > 0 ? (
       <Wrapper
         data-slot={`${slot}-header-row`}
-        className="flex min-w-0 items-center gap-4"
+        className={cn("flex min-w-0 items-center gap-4", rowClassName)}
       >
-        <Wrapper
-          data-slot={`${slot}-navigation`}
-          className="min-w-0 flex-1"
-        >
+        <Wrapper data-slot={`${slot}-navigation`} className="min-w-0 flex-1">
           {leading}
         </Wrapper>
         {actionSlots}
       </Wrapper>
+    ) : rowClassName !== undefined ? (
+      <Wrapper
+        data-slot={`${slot}-header-row`}
+        className={cn(
+          rowClassName,
+          heading ? "justify-between" : "justify-end",
+        )}
+      >
+        {heading}
+        {actionSlots}
+      </Wrapper>
     ) : (
       <>
         {heading}
@@ -360,3 +371,28 @@ export function StructuralHeader({
     </Root>
   );
 }
+
+/** A intro visível abre o corpo; wrappers opacos são verificados quando materializam seus slots. */
+export function validateSurfaceIntro(
+  children: ReactNode,
+  intro: ElementType,
+  name: string,
+): void {
+  const flatten = (nodes: ReactNode): ReactNode[] =>
+    Children.toArray(nodes).flatMap((node) =>
+      isValidElement(node) && node.type === Fragment
+        ? flatten((node.props as { children?: ReactNode }).children)
+        : [node],
+    );
+  const nodes = flatten(children).filter(
+    (node) => typeof node !== "string" || node.trim() !== "",
+  );
+  const indexes = nodes.flatMap((node, index) =>
+    isValidElement(node) && node.type === intro ? [index] : [],
+  );
+  if (indexes.length > 1 || (indexes.length === 1 && indexes[0] !== 0)) {
+    throw new Error(
+      `${name} aceita uma única intro como primeiro bloco do corpo.`,
+    );
+  }
+}

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

@@ -27,7 +27,7 @@ import {
 } from "react";
 import { FillBoundary } from "./fill-region.ts";
 
-export type SurfaceFamily = "surface" | "dialog" | "drawer";
+export type SurfaceFamily = "surface" | "dialog" | "drawer" | "page";
 export type SurfaceLayout = "continuous" | "sectioned";
 export type SurfaceRegion = "header" | "body" | "footer";
 
@@ -64,18 +64,22 @@ interface FamilyAnatomy {
   description: string;
   /** Espaço entre mídia, título e ações na linha do header. */
   headerGap: string;
+  /** Altura mínima da linha, equivalente ao controle padrão da família. */
+  headerMinHeight: string;
   /** Faixa do rodapé no layout seccionado, quando a família declara uma. */
   footerBand: string;
 }
 
 /**
  * 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.
+ * O header é comum à família; corpos e rodapés conservam o ritmo de cada superfície.
  */
+const structuralHeaderPadding = "p-4";
+const structuralHeaderMinHeight = "min-h-8";
+
 const sectionedRegions: RegionAnatomy = {
-  header: "p-4",
-  body: "px-4 py-6",
+  header: structuralHeaderPadding,
+  body: "p-4",
   footer: "p-4",
 };
 
@@ -83,25 +87,47 @@ const sectionedRegions: RegionAnatomy = {
  * 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 structuralBodyRhythm = "flex flex-col gap-4 *:shrink-0";
+export const structuralRegionSpacing = "space-y-4";
+export const structuralRegionGap = "gap-4";
 
 export const surfaceAnatomy: Record<SurfaceFamily, FamilyAnatomy> = {
+  page: {
+    regions: {
+      continuous: {
+        header: structuralHeaderPadding,
+        body: "px-8 pt-0 pb-0 [[data-slot=page-body]:first-child>&]:pt-4",
+        footer: "px-8 py-4",
+      },
+      sectioned: {
+        header: sectionedRegions.header,
+        body: "px-8 pt-4 pb-0 [[data-slot=page-body]:has(+[data-slot=page-footer])>&]:pb-4",
+        footer: "px-8 py-4",
+      },
+    },
+    title: {
+      continuous: "text-2xl font-semibold",
+      sectioned: "text-2xl font-semibold",
+    },
+    description: "text-sm text-muted-foreground",
+    headerGap: "gap-4",
+    headerMinHeight: structuralHeaderMinHeight,
+    footerBand: "bg-muted/30",
+  },
   // 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 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.
+      // No contínuo, a região anterior fornece o intervalo; a primeira abre o recuo.
       continuous: {
-        header: "px-4 pt-4 pb-6 [&:last-child]:pb-4",
-        body: "px-4 pt-0 pb-6 [&:first-child]:pt-6",
+        header: structuralHeaderPadding,
+        body: "px-4 pt-0 pb-4 [&:first-child]:pt-4",
         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",
+        header: structuralHeaderPadding,
+        body: "p-4",
+        footer: "p-4",
       },
     },
     // Uma escala só: o nível 1 troca a apresentação inteira (ADR 0038), nunca o layout.
@@ -111,14 +137,15 @@ export const surfaceAnatomy: Record<SurfaceFamily, FamilyAnatomy> = {
     },
     description: "mt-0.5 text-xs text-muted-foreground",
     headerGap: "gap-2",
+    headerMinHeight: structuralHeaderMinHeight,
     footerBand: "",
   },
   dialog: {
     regions: {
       continuous: {
-        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",
+        header: structuralHeaderPadding,
+        body: "px-4 pt-0 pb-4 [&:first-child]:pt-4",
+        footer: "px-4 pt-0 pb-4 [&:first-child]:pt-4",
       },
       sectioned: sectionedRegions,
     },
@@ -128,14 +155,15 @@ export const surfaceAnatomy: Record<SurfaceFamily, FamilyAnatomy> = {
     },
     description: "text-sm text-muted-foreground",
     headerGap: "gap-4",
+    headerMinHeight: structuralHeaderMinHeight,
     footerBand: "bg-muted/20 dark:bg-input/20",
   },
   drawer: {
     regions: {
       continuous: {
-        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",
+        header: structuralHeaderPadding,
+        body: "px-4 pt-0 pb-4 [&:first-child]:pt-4",
+        footer: "px-4 pt-0 pb-4 [&:first-child]:pt-4",
       },
       sectioned: sectionedRegions,
     },
@@ -145,6 +173,7 @@ export const surfaceAnatomy: Record<SurfaceFamily, FamilyAnatomy> = {
     },
     description: "text-sm text-muted-foreground",
     headerGap: "gap-4",
+    headerMinHeight: structuralHeaderMinHeight,
     footerBand: "bg-muted/20 dark:bg-input/20",
   },
 };
@@ -190,7 +219,7 @@ export function surfaceDescriptionClasses(family: SurfaceFamily): string {
  * `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}`;
+  return `flex min-w-0 flex-1 items-center ${surfaceAnatomy[family].headerGap} ${surfaceAnatomy[family].headerMinHeight}`;
 }
 
 /** Ações do header e do footer: fora do fluxo de compressão, na escala densa. */
@@ -207,7 +236,7 @@ export const surfaceActionsClasses = "flex shrink-0 items-center gap-2";
  */
 export const surfaceLegendClasses = {
   notch: "ml-2 w-auto px-2",
-  afterNotch: "pt-3",
+  afterNotch: "pt-4",
   band: "float-left w-full",
   afterBand: "clear-left",
 } as const;
@@ -241,6 +270,7 @@ export function SurfaceLayoutProvider({
 }
 
 const familyDefaultLayout: Record<SurfaceFamily, SurfaceLayout> = {
+  page: "sectioned",
   surface: "continuous",
   dialog: "sectioned",
   drawer: "sectioned",

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

@@ -49,6 +49,7 @@ import {
   surfaceHeaderRowClasses,
   surfaceLegendClasses,
   surfaceRegionClasses,
+  structuralRegionSpacing,
   surfaceTitleClasses,
   type SurfaceLayout,
 } from "./surface-anatomy.ts";
@@ -343,9 +344,7 @@ export function Surface({
         framed && "has-[>[data-flush=true]]:overflow-hidden",
         raised &&
           "bg-card text-card-foreground [--surface-background:var(--card)]",
-        structured &&
-          !bounded &&
-          (variant === "page" ? "space-y-6" : "space-y-3"),
+        structured && !bounded && structuralRegionSpacing,
         link && fill.filling && fillRegionClassName,
         className,
       )}

package/src/ui/components/primitives/control.ts

@@ -7,7 +7,7 @@ export type ControlShape = 'default' | 'pill'
  * Cada componente aceita o subconjunto coerente com seu papel, nunca um nome com outra medida.
  *
  * - Altura de linha (`xs` · `sm` · `default` · `lg`): 1.5 · 2 · 2.25 · 2.5rem.
- * - Quadrado só-ícone (`icon-xs` · `icon-sm` · `icon` · `icon-lg`): 1.5 · 1.75 · 2.25 · 2.5rem.
+ * - Quadrado só-ícone (`icon-xs` · `icon-sm` · `icon` · `icon-lg`): 1.5 · 2 · 2.25 · 2.5rem.
  *   `icon-xs` é o degrau da ação que mora dentro de uma linha densa. `icon-sm` atende
  *   composições compactas que ainda precisam de mais presença.
  * - Glifo (o svg dentro do controle daquele tamanho): 0.875 · 0.875 · 1 · 1.25rem. O quadrado
@@ -27,7 +27,7 @@ export const controlHeight: Record<ControlSize, string> = {
 
 export const controlSquare: Record<ControlIconSize, string> = {
   'icon-xs': 'size-6',
-  'icon-sm': 'size-7',
+  'icon-sm': 'size-8',
   icon: 'size-9',
   'icon-lg': 'size-10',
 }

package/src/ui/components/primitives/dialog.tsx

@@ -14,7 +14,11 @@ import {
 } from "../patterns/surface-anatomy.ts";
 import { FillBoundary } from "../patterns/fill-region.ts";
 import { headingTags, type HeadingLevel } from "../patterns/heading-level.ts";
-import { StructuralHeader } from "../patterns/structural-header.tsx";
+import {
+  StructuralHeader,
+  structuralHeaderClasses,
+  validateSurfaceIntro,
+} from "../patterns/structural-header.tsx";
 import {
   StructuralMedia,
   type StructuralMediaProps,
@@ -698,6 +702,7 @@ export function DialogBody({
 }: React.ComponentProps<"div"> & { flush?: boolean }) {
   const { mode } = useDialogContext();
   const layout = useSurfaceLayout("dialog");
+  validateSurfaceIntro(props.children, DialogIntro, "DialogBody");
   return (
     <div
       data-slot="dialog-body"
@@ -761,7 +766,7 @@ export function DialogTitle({
         ? "min-w-0 whitespace-normal"
         : "min-w-0 truncate",
     intro
-      ? "text-xl font-semibold leading-tight tracking-tight"
+      ? structuralHeaderClasses.page.title
       : surfaceTitleClasses("dialog", layout),
     className,
   );

package/src/ui/components/primitives/drawer.tsx

@@ -13,7 +13,11 @@ import {
   type SurfaceLayout,
 } from "../patterns/surface-anatomy.ts";
 import { headingTags, type HeadingLevel } from "../patterns/heading-level.ts";
-import { StructuralHeader } from "../patterns/structural-header.tsx";
+import {
+  StructuralHeader,
+  structuralHeaderClasses,
+  validateSurfaceIntro,
+} from "../patterns/structural-header.tsx";
 import {
   StructuralMedia,
   type StructuralMediaProps,
@@ -361,6 +365,7 @@ function DrawerBody({
   ...props
 }: React.ComponentProps<"div"> & { flush?: boolean }) {
   const layout = useSurfaceLayout("drawer");
+  validateSurfaceIntro(props.children, DrawerIntro, "DrawerBody");
   return (
     <div
       data-slot="drawer-body"
@@ -408,7 +413,7 @@ function DrawerTitle({
   const classes = cn(
     intro ? "min-w-0 whitespace-normal" : "min-w-0 truncate",
     intro
-      ? "text-xl font-semibold leading-tight tracking-tight"
+      ? structuralHeaderClasses.page.title
       : surfaceTitleClasses("drawer", layout),
     className,
   );