@softize/opus 27.1.0 → 28.0.0

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

@@ -47,6 +47,7 @@ import {
   DialogContent,
   DialogFooter,
   DialogHeader,
+  DialogIntro,
   DialogNavigation,
   DialogTitle,
 } from "../primitives/dialog.tsx";
@@ -57,6 +58,7 @@ import {
   DrawerContent,
   DrawerFooter,
   DrawerHeader,
+  DrawerIntro,
   DrawerNavigation,
   DrawerTitle,
 } from "../primitives/drawer.tsx";
@@ -66,6 +68,7 @@ import {
   PageBody,
   PageFooter,
   PageHeader,
+  PageIntro,
   PageNavigation,
   PageTitle,
   useInsidePageShell,
@@ -114,11 +117,13 @@ const bodyClassName =
  * a lista do body é filha direta dele e assume `fill` sem classe no consumidor.
  */
 function PresentationBody({
+  page = false,
   layout,
   className,
   children,
 }: {
   layout: "flow" | "fill";
+  page?: boolean;
   className?: string;
   children: ReactNode;
 }): ReactElement {
@@ -128,7 +133,7 @@ function PresentationBody({
       data-slot="presentation-body"
       {...fill.attributes}
       className={cn(
-        bodyClassName,
+        !page && bodyClassName,
         (layout === "fill" || fill.filling) && fillRegionClassName,
         className,
       )}
@@ -195,14 +200,14 @@ function PresentationFrame({
     </PresentationActions>
   );
   const body = (
-    <PresentationBody layout={layout} className={bodyClassNameProp}>
+    <PresentationBody
+      page={surface === "page"}
+      layout={layout}
+      className={bodyClassNameProp}
+    >
       {typeof children === "function" ? children(footerTarget) : children}
     </PresentationBody>
   );
-  // Viewport entre o PageBody e o conteúdo. Em `fill`, é coluna flexível para a altura
-  // chegar ao conteúdo; a rolagem continua disponível como recurso de última instância.
-  const viewportFillClassName =
-    layout === "fill" ? fillRegionClassName : undefined;
   const withAssistant = (content: ReactElement): ReactElement =>
     assistantLabel === undefined || assistantPanel === undefined ? (
       content
@@ -248,18 +253,7 @@ function PresentationFrame({
               )}
             </PageHeader>
           )}
-          <PageBody className="min-h-0 flex-1 overflow-hidden">
-            {withAssistant(
-              <div
-                className={cn(
-                  "h-full overflow-x-hidden overflow-y-auto",
-                  viewportFillClassName,
-                )}
-              >
-                {content}
-              </div>,
-            )}
-          </PageBody>
+          <PageBody>{withAssistant(content)}</PageBody>
           {hasFooter ? <PageFooter>{renderFooterActions()}</PageFooter> : null}
         </Page>
       );
@@ -278,7 +272,6 @@ function PresentationFrame({
               {navigation === undefined ? null : (
                 <PageNavigation>{navigation}</PageNavigation>
               )}
-              {contentOwnsHeading ? null : <PageTitle>{title}</PageTitle>}
               {headerActions === undefined &&
               assistantAction === undefined ? null : (
                 <PageActions>
@@ -290,36 +283,24 @@ function PresentationFrame({
               )}
             </PageHeader>
           )}
-          <PageBody className="min-h-0 flex-1 overflow-hidden">
-            {withAssistant(
-              <div
-                className={cn(
-                  "flex h-full min-h-0 flex-col overflow-x-hidden",
-                  layout === "fill" ? "overflow-y-hidden" : "overflow-y-auto",
-                  viewportFillClassName,
-                )}
-              >
-                {body}
-              </div>,
+          <PageBody>
+            {contentOwnsHeading ? null : (
+              <PageIntro>
+                <PageTitle>{title}</PageTitle>
+              </PageIntro>
             )}
+            {withAssistant(body)}
           </PageBody>
           {hasFooter ? <PageFooter>{renderFooterActions()}</PageFooter> : null}
         </Page>
       );
     }
     return (
-      <Page
-        layout={layout}
-        className={cn(
-          "flex min-h-full max-w-none flex-col space-y-0 px-0 py-0",
-          className,
-        )}
-      >
+      <Page layout={layout} className={className} contentClassName="max-w-none">
         <PageHeader>
           {navigation === undefined ? null : (
             <PageNavigation>{navigation}</PageNavigation>
           )}
-          <PageTitle className="text-lg leading-none">{title}</PageTitle>
           {headerActions === undefined &&
           assistantAction === undefined ? null : (
             <PageActions>
@@ -330,17 +311,11 @@ function PresentationFrame({
             </PageActions>
           )}
         </PageHeader>
-        <PageBody className="min-h-0 flex-1 overflow-hidden">
-          {withAssistant(
-            <div
-              className={cn(
-                "h-full overflow-x-hidden overflow-y-auto px-8 py-8",
-                viewportFillClassName,
-              )}
-            >
-              {body}
-            </div>,
-          )}
+        <PageBody>
+          <PageIntro>
+            <PageTitle>{title}</PageTitle>
+          </PageIntro>
+          {withAssistant(body)}
         </PageBody>
         {hasFooter ? <PageFooter>{renderFooterActions()}</PageFooter> : null}
       </Page>
@@ -364,7 +339,6 @@ function PresentationFrame({
               {navigation === undefined ? null : (
                 <DialogNavigation>{navigation}</DialogNavigation>
               )}
-              <DialogTitle>{title}</DialogTitle>
               {headerActions === undefined &&
               assistantAction === undefined ? null : (
                 <DialogActions>
@@ -375,7 +349,14 @@ function PresentationFrame({
                 </DialogActions>
               )}
             </DialogHeader>
-            {withAssistant(<DialogBody>{body}</DialogBody>)}
+            {withAssistant(
+              <DialogBody>
+                <DialogIntro>
+                  <DialogTitle>{title}</DialogTitle>
+                </DialogIntro>
+                {body}
+              </DialogBody>,
+            )}
             {hasFooter ? (
               <DialogFooter>{renderFooterActions()}</DialogFooter>
             ) : null}
@@ -402,7 +383,6 @@ function PresentationFrame({
             {navigation === undefined ? null : (
               <DrawerNavigation>{navigation}</DrawerNavigation>
             )}
-            <DrawerTitle>{title}</DrawerTitle>
             {headerActions === undefined &&
             assistantAction === undefined ? null : (
               <DrawerActions>
@@ -413,7 +393,14 @@ function PresentationFrame({
               </DrawerActions>
             )}
           </DrawerHeader>
-          {withAssistant(<DrawerBody>{body}</DrawerBody>)}
+          {withAssistant(
+            <DrawerBody>
+              <DrawerIntro>
+                <DrawerTitle>{title}</DrawerTitle>
+              </DrawerIntro>
+              {body}
+            </DrawerBody>,
+          )}
           {hasFooter ? (
             <DrawerFooter>{renderFooterActions()}</DrawerFooter>
           ) : null}
@@ -635,9 +622,7 @@ export function Presentation({
       string,
       unknown
     >;
-    // Header e footer são regiões de decisão da superfície, não toolbars operacionais.
-    // Seus comandos textuais usam a linha padrão; listas e grids continuam donos da
-    // densidade compacta de suas próprias ações.
+    // A região chamadora escolhe a escala; o footer conserva o botão padrão.
     if (action.kind === "simple") {
       return (
         <PresentationCommandTrigger
@@ -784,7 +769,7 @@ export function Presentation({
 
   const headerActions = definition.actions
     .filter((command) => command.placement === "header")
-    .map((command) => renderCommand(command));
+    .map((command) => renderCommand(command, "sm"));
   const footerActions = definition.actions
     .filter((command) => command.placement === "footer")
     .map((command) => renderCommand(command));
@@ -794,7 +779,7 @@ export function Presentation({
     (invocation.surface === "page" || parentSurface !== "page");
   const navigation = !canGoBack ? undefined : (
     <Button
-      size="icon"
+      size="icon-sm"
       variant="ghost"
       disabled={surfaceBlocked}
       aria-label="Voltar"
@@ -807,7 +792,7 @@ export function Presentation({
   const assistantAction =
     definition.assistant === undefined || assistantOpen ? undefined : (
       <Button
-        size="icon"
+        size="icon-sm"
         variant="ghost"
         aria-label={definition.assistant.triggerLabel}
         title={definition.assistant.triggerLabel}

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,
   );