@softize/opus 27.1.0 → 29.0.0

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

@@ -31,15 +31,27 @@ import {
 } from "./page-heading-context.tsx";
 import {
   StructuralHeader,
+  validateSurfaceIntro,
   structuralHeaderClasses,
 } from "./structural-header.tsx";
 import { PageState, PageStatePresenceProvider } from "./page-state.tsx";
-import { FillRoot, fillRegionClassName, useFillRegion } from "./fill-region.ts";
+import { FillRoot, useFillRegion } from "./fill-region.ts";
 
-interface PageContextValue {}
+import {
+  surfaceHeaderRowClasses,
+  surfaceRegionClasses,
+  type SurfaceLayout,
+} from "./surface-anatomy.ts";
+
+interface PageContextValue {
+  surfaceLayout: SurfaceLayout;
+  contentClassName?: string;
+}
 
 const PageContext = createContext<PageContextValue | null>(null);
 const PageHeaderContext = createContext(false);
+const PageIntroContext = createContext(false);
+const PageBodyContext = createContext(false);
 const PageIntegralStateContext = createContext(false);
 const PageActionsTargetContext = createContext<HTMLElement | null>(null);
 interface PageShellContextValue {
@@ -101,7 +113,7 @@ export function PageShell({
       <PageShellContext.Provider value={shell}>
         <div
           data-slot="page-shell-content"
-          className="min-h-0 min-w-0 flex-1 overflow-auto [&>*]:min-w-[64rem]"
+          className="flex min-h-0 min-w-0 flex-1 flex-col overflow-x-auto overflow-y-auto [&>*]:min-w-[64rem]"
         >
           {children}
         </div>
@@ -136,13 +148,17 @@ interface PageBaseProps extends Omit<
   HTMLAttributes<HTMLElement>,
   "children" | "title"
 > {
-  /** Classes do container. Default: centralizado com `max-w-7xl` (80rem). */
+  /** Classes do container externo. O conteúdo do Body mantém o teto de 80rem. */
   className?: string;
+  /** Classes do conteúdo centralizado, incluindo largura máxima e alinhamento. */
+  contentClassName?: string;
   /**
-   * `fill` limita a página à altura do shell para que regiões internas assumam a rolagem.
+   * `flow` mantém a rolagem no body; `fill` permite que regiões internas assumam a rolagem.
    * A altura chega sozinha a uma `ActionList` composta por `PageBody` e `Surface` (ADR 0024).
    */
   layout?: "flow" | "fill";
+  /** Divisão visual das regiões, independente da distribuição de altura. */
+  surfaceLayout?: SurfaceLayout;
 }
 
 interface PageShorthandProps extends PageBaseProps {
@@ -183,6 +199,7 @@ function countDirectChildrenOfType(
 
 function countPageBodyHeadings(node: ReactNode): {
   content: number;
+  intro: number;
   state: number;
 } {
   return Children.toArray(node).reduce(
@@ -196,6 +213,7 @@ function countPageBodyHeadings(node: ReactNode): {
       if (child.type === PageState && props.status !== "ready") {
         return {
           content: total.content,
+          intro: total.intro,
           state: total.state + 1,
         };
       }
@@ -205,10 +223,11 @@ function countPageBodyHeadings(node: ReactNode): {
           total.content +
           (child.type === Surface && props.level === 1 ? 1 : 0) +
           nested.content,
+        intro: total.intro + (child.type === PageIntro ? 1 : 0) + nested.intro,
         state: total.state + nested.state,
       };
     },
-    { content: 0, state: 0 },
+    { content: 0, intro: 0, state: 0 },
   );
 }
 
@@ -229,12 +248,13 @@ export function Page({
   description,
   actions,
   layout = "flow",
+  surfaceLayout = "sectioned",
+  contentClassName,
   className,
   children,
   ...props
 }: PageProps): ReactElement {
   const shell = useContext(PageShellContext);
-  const insideShell = shell !== null;
   const shorthand = title !== undefined;
   const nodes = flattenPageHeaderChildren(children);
   const headers = nodes.filter(
@@ -298,6 +318,7 @@ export function Page({
       );
     }
     const bodyHeadingSources = bodies.reduce<{
+      intro: number;
       content: number;
       state: number;
     }>(
@@ -307,17 +328,20 @@ export function Page({
         );
         return {
           content: total.content + count.content,
+          intro: total.intro + count.intro,
           state: total.state + count.state,
         };
       },
-      { content: 0, state: 0 },
+      { content: 0, intro: 0, state: 0 },
     );
     const structuralHeadingSources =
       headers.reduce<number>(
         (total, header) =>
           total + countDirectChildrenOfType(header as ReactElement, PageTitle),
         0,
-      ) + bodyHeadingSources.content;
+      ) +
+      bodyHeadingSources.content +
+      bodyHeadingSources.intro;
     const headingSources =
       bodyHeadingSources.state > 0
         ? bodyHeadingSources.state + bodyHeadingSources.content
@@ -329,7 +353,7 @@ export function Page({
     );
     if (headingSources > 1 || (headingSources === 0 && !hasOpaqueBodyContent)) {
       throw new Error(
-        "Page explícito exige exatamente um heading principal em PageHeader, Surface level={1} ou PageState ativo dentro de PageBody.",
+        "Page explícito exige exatamente um heading principal em PageHeader, PageIntro, Surface level={1} ou PageState ativo dentro de PageBody.",
       );
     }
   }
@@ -338,20 +362,24 @@ export function Page({
     if (integralState !== hasActiveIntegralState) return;
     if (headingCount.current !== 1) {
       throw new Error(
-        "Page explícito exige exatamente um heading principal em PageHeader, Surface level={1} ou PageState ativo dentro de PageBody.",
+        "Page explícito exige exatamente um heading principal em PageHeader, PageIntro, Surface level={1} ou PageState ativo dentro de PageBody.",
       );
     }
   });
   const content = shorthand ? (
     <>
       <PageHeader>
-        <PageTitle>{title}</PageTitle>
-        {description !== undefined && (
-          <PageDescription>{description}</PageDescription>
-        )}
         {actions !== undefined && <PageActions>{actions}</PageActions>}
       </PageHeader>
-      <PageBody>{children}</PageBody>
+      <PageBody>
+        <PageIntro>
+          <PageTitle>{title}</PageTitle>
+          {description !== undefined && (
+            <PageDescription>{description}</PageDescription>
+          )}
+        </PageIntro>
+        {children}
+      </PageBody>
     </>
   ) : (
     <>
@@ -364,29 +392,22 @@ export function Page({
   );
 
   return (
-    <PageContext.Provider value={{}}>
+    <PageContext.Provider value={{ surfaceLayout, contentClassName }}>
       <PageIntegralStateContext.Provider value={integralState}>
         <PageStatePresenceProvider register={registerIntegralState}>
           <PageHeadingPresenceProvider register={registerHeading}>
             <main
               data-slot="page"
               data-layout={layout}
+              data-surface-layout={surfaceLayout}
               className={cn(
-                "min-w-[64rem] flex-1",
-                insideShell && "min-h-full",
-                layout === "fill" &&
-                  "flex h-full min-h-0 flex-col overflow-hidden",
-                integralState && "flex min-h-full flex-col",
+                "flex h-full min-h-0 min-w-[64rem] flex-1 flex-col overflow-hidden",
               )}
               {...props}
             >
               <div
                 className={cn(
-                  "mx-auto max-w-7xl space-y-6 px-8 py-8",
-                  layout === "fill" &&
-                    "flex h-full min-h-0 w-full flex-1 flex-col",
-                  integralState &&
-                    "flex min-h-full w-full flex-1 flex-col space-y-0",
+                  "flex h-full min-h-0 w-full flex-1 flex-col",
                   className,
                 )}
               >
@@ -455,6 +476,7 @@ export function PageHeader({
   if (
     structuralChildren.length === 0 &&
     mergedActions === null &&
+    localNavigation.length === 0 &&
     shell?.navigation === undefined
   ) {
     return <></>;
@@ -470,9 +492,25 @@ export function PageHeader({
           description: PageDescription,
           actions: PageActions,
         }}
-        leadingPlacement="above"
+        leadingPlacement={
+          nodes.some(
+            (node) => isValidElement(node) && node.type === PageTitle,
+          ) ||
+          (localNavigation.length === 0 &&
+            shell?.navigation === undefined &&
+            !nodes.some(
+              (node) => isValidElement(node) && node.type === PageBack,
+            ))
+            ? "above"
+            : "inline"
+        }
         titleRequired={false}
-        className={className}
+        rowClassName={surfaceHeaderRowClasses("page")}
+        className={cn(
+          "shrink-0",
+          surfaceRegionClasses("page", page!.surfaceLayout, "header"),
+          className,
+        )}
         {...props}
       >
         {shell?.navigation === undefined ? (
@@ -487,12 +525,62 @@ export function PageHeader({
   );
 }
 
+/** Primeiro bloco do corpo, separado dos controles do cabeçalho. */
+export function PageIntro({
+  className,
+  children,
+  ...props
+}: HTMLAttributes<HTMLDivElement>): ReactElement {
+  requireParent(useContext(PageBodyContext), "PageIntro", "PageBody");
+  const integralState = useContext(PageIntegralStateContext);
+  if (integralState) return <></>;
+  return (
+    <PageIntroContext.Provider value>
+      <StructuralHeader
+        name="PageIntro"
+        slot="page-intro"
+        slots={{
+          title: PageTitle,
+          description: PageDescription,
+          actions: PageIntroActions,
+        }}
+        leadingPlacement="inline"
+        titleRequired
+        className={className}
+        {...props}
+      >
+        {children}
+      </StructuralHeader>
+    </PageIntroContext.Provider>
+  );
+}
+
+/** Ações locais do conteúdo, distintas das ações da superfície em PageActions. */
+export function PageIntroActions({
+  className,
+  ...props
+}: HTMLAttributes<HTMLDivElement>): ReactElement {
+  requireParent(useContext(PageIntroContext), "PageIntroActions", "PageIntro");
+  return (
+    <div
+      data-slot="page-intro-actions"
+      className={cn(structuralHeaderClasses.page.actions, className)}
+      {...props}
+    />
+  );
+}
+
 export function PageTitle({
   className,
   ...props
 }: HTMLAttributes<HTMLHeadingElement>): ReactElement {
   const insideHeader = useContext(PageHeaderContext);
-  requireParent(insideHeader, "PageTitle", "PageHeader");
+  const insideIntro = useContext(PageIntroContext);
+  requireParent(
+    insideHeader || insideIntro,
+    "PageTitle",
+    "PageHeader ou PageIntro",
+  );
   usePageHeadingPresence();
   return (
     <h1
@@ -508,7 +596,9 @@ export function PageDescription({
   className,
   ...props
 }: HTMLAttributes<HTMLParagraphElement>): ReactElement {
-  requireParent(useContext(PageHeaderContext), "PageDescription", "PageHeader");
+  const header = useContext(PageHeaderContext);
+  const intro = useContext(PageIntroContext);
+  requireParent(header || intro, "PageDescription", "PageHeader ou PageIntro");
   return (
     <p
       data-slot="page-description"
@@ -574,7 +664,7 @@ export function PageBack({
     typeof children === "string" ? children : "a página anterior";
   const accessibleLabel = ariaLabel ?? `Voltar para ${destination}`;
   const back = (
-    <Button asChild variant="ghost" size="icon">
+    <Button asChild variant="ghost" size="icon-sm">
       <a
         data-slot="page-back"
         aria-label={accessibleLabel}
@@ -592,25 +682,42 @@ export function PageBack({
 
 export function PageBody({
   className,
+  contentClassName,
   children,
   ...props
-}: HTMLAttributes<HTMLDivElement>): ReactElement {
+}: HTMLAttributes<HTMLDivElement> & {
+  contentClassName?: string;
+}): ReactElement {
   const page = useContext(PageContext);
-  const integralState = useContext(PageIntegralStateContext);
   const fill = useFillRegion();
   requireParent(page !== null, "PageBody", "Page");
+  validateSurfaceIntro(children, PageIntro, "PageBody");
   return (
     <div
       data-slot="page-body"
       {...fill.attributes}
       className={cn(
-        "flex flex-col gap-6 *:shrink-0",
-        (integralState || fill.filling) && fillRegionClassName,
+        "flex min-h-0 flex-1 flex-col",
+        fill.filling ? "overflow-hidden" : "overflow-y-auto",
         className,
       )}
       {...props}
     >
-      {fill.provide(children)}
+      <PageBodyContext.Provider value>
+        <div
+          data-slot="page-body-content"
+          {...fill.attributes}
+          className={cn(
+            "mx-auto w-full max-w-7xl",
+            surfaceRegionClasses("page", page!.surfaceLayout, "body"),
+            fill.filling ? "min-h-0 flex-1" : "min-h-full shrink-0",
+            page!.contentClassName,
+            contentClassName,
+          )}
+        >
+          {fill.provide(children)}
+        </div>
+      </PageBodyContext.Provider>
     </div>
   );
 }
@@ -625,7 +732,8 @@ export function PageFooter({
     <div
       data-slot="page-footer"
       className={cn(
-        "mt-auto flex h-[3.75rem] shrink-0 items-center justify-end border-t bg-muted/30 p-3",
+        "mt-auto flex min-h-[3.75rem] shrink-0 items-center justify-end",
+        surfaceRegionClasses("page", page!.surfaceLayout, "footer"),
         className,
       )}
       {...props}

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}