@softize/opus 21.0.1 → 22.1.0

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

@@ -1,12 +1,13 @@
 /**
  * <Page /> — esqueleto composto de página do back-office.
  *
- * A forma curta cobre o caso comum; PageShell coordena a barra persistente quando shell e rota
- * conhecem partes diferentes. Todas preservam o container centralizado com teto de 80rem.
+ * A forma curta cobre o caso comum; PageShell coordena contexto conhecido pelo shell sem criar
+ * uma segunda região visual. Todas preservam o container centralizado com teto de 80rem.
  */
 
 import {
   Children,
+  Fragment,
   createContext,
   isValidElement,
   useCallback,
@@ -30,80 +31,35 @@ import {
 } from "./page-heading-context.tsx";
 import { SurfaceHeader, surfaceHeaderClasses } from "./surface-header.tsx";
 import { PageState, PageStatePresenceProvider } from "./page-state.tsx";
-import {
-  FillRoot,
-  fillRegionClassName,
-  useFillRegion,
-} from "./fill-region.ts";
+import { FillRoot, fillRegionClassName, useFillRegion } from "./fill-region.ts";
 
 interface PageContextValue {}
 
 const PageContext = createContext<PageContextValue | null>(null);
-type PageHeadingRegion = "header" | "intro";
-
-const PageHeaderContext = createContext<PageHeadingRegion | null>(null);
+const PageHeaderContext = createContext(false);
 const PageIntegralStateContext = createContext(false);
 const PageActionsTargetContext = createContext<HTMLElement | null>(null);
-const PageNavigationTargetContext = createContext<HTMLElement | null>(null);
-const PageShellContext = createContext(false);
-const pageBarClassName =
-  "flex h-[3.75rem] shrink-0 items-center border-b border-border bg-background text-foreground";
-const pageBarContentClassName = "w-full p-3";
-
-/** Uso interno de patterns que precisam adaptar a Page ao shell sem duplicar sua anatomia. */
-export function useInsidePageShell(): boolean {
-  return useContext(PageShellContext);
-}
-
-function PageShellNavigationSlot({
-  targetRef,
-  className,
-  ...props
-}: HTMLAttributes<HTMLDivElement> & {
-  targetRef?: (target: HTMLDivElement | null) => void;
-}): ReactElement {
-  return (
-    <div
-      ref={targetRef}
-      data-slot="page-shell-navigation"
-      className={cn("min-w-0 shrink-0 overflow-hidden", className)}
-      {...props}
-    />
-  );
+interface PageShellContextValue {
+  navigation?: ReactNode;
+  actions?: ReactNode;
 }
+const PageShellContext = createContext<PageShellContextValue | null>(null);
 
-function PageShellTitleSlot({
-  targetRef,
-  className,
-  ...props
-}: HTMLAttributes<HTMLDivElement> & {
-  targetRef?: (target: HTMLDivElement | null) => void;
-}): ReactElement {
-  return (
-    <div
-      ref={targetRef}
-      data-slot="page-shell-title"
-      className={cn("min-w-0 flex-1", className)}
-      {...props}
-    />
-  );
+function hasRenderableNode(node: ReactNode): boolean {
+  if (node === null || node === undefined || typeof node === "boolean") {
+    return false;
+  }
+  if (typeof node === "string") return node.trim().length > 0;
+  if (Array.isArray(node)) return node.some(hasRenderableNode);
+  if (isValidElement(node) && node.type === Fragment) {
+    return hasRenderableNode((node.props as { children?: ReactNode }).children);
+  }
+  return true;
 }
 
-function PageShellActionsSlot({
-  targetRef,
-  className,
-  ...props
-}: HTMLAttributes<HTMLDivElement> & {
-  targetRef: (target: HTMLDivElement | null) => void;
-}): ReactElement {
-  return (
-    <div
-      ref={targetRef}
-      data-slot="page-shell-actions"
-      className={cn("flex shrink-0 items-center gap-2", className)}
-      {...props}
-    />
-  );
+/** Uso interno de patterns que precisam adaptar a Page ao shell sem duplicar sua anatomia. */
+export function useInsidePageShell(): boolean {
+  return useContext(PageShellContext) !== null;
 }
 
 export interface PageShellProps extends Omit<
@@ -116,25 +72,20 @@ export interface PageShellProps extends Omit<
   actions?: ReactNode;
   /** Uma Page descendente, diretamente ou através da rota ativa. */
   children: ReactNode;
-  /** Classes do container interno da barra. */
-  headerClassName?: string;
 }
 
-/** Moldura persistente que coordena navegação do shell e ações da Page ativa. */
+/** Moldura que coordena contexto do shell com o PageHeader da página ativa. */
 export function PageShell({
   navigation,
   actions,
   children,
   className,
-  headerClassName,
   ...props
 }: PageShellProps): ReactElement {
-  const [actionsTarget, setActionsTarget] = useState<HTMLDivElement | null>(
-    null,
-  );
-  const [navigationTarget, setNavigationTarget] =
-    useState<HTMLDivElement | null>(null);
-
+  const shell = {
+    ...(hasRenderableNode(navigation) ? { navigation } : {}),
+    ...(hasRenderableNode(actions) ? { actions } : {}),
+  };
   return (
     <div
       data-slot="page-shell"
@@ -144,39 +95,13 @@ export function PageShell({
       )}
       {...props}
     >
-      <SurfaceHeader
-        name="PageShell"
-        slot="page"
-        slots={{
-          leading: PageShellNavigationSlot,
-          title: PageShellTitleSlot,
-          actions: PageShellActionsSlot,
-        }}
-        leadingPlacement="inline"
-        titleRequired={false}
-        contentClassName={cn(pageBarContentClassName, "px-3", headerClassName)}
-        className={pageBarClassName}
-        data-variant="bar"
-      >
-        <PageShellNavigationSlot targetRef={setNavigationTarget}>
-          {navigation}
-        </PageShellNavigationSlot>
-        <PageShellTitleSlot />
-        <PageShellActionsSlot targetRef={setActionsTarget}>
-          {actions}
-        </PageShellActionsSlot>
-      </SurfaceHeader>
-      <PageShellContext.Provider value>
-        <PageNavigationTargetContext.Provider value={navigationTarget}>
-          <PageActionsTarget target={actionsTarget}>
-            <div
-              data-slot="page-shell-content"
-              className="min-h-0 min-w-0 flex-1 overflow-auto [&>*]:min-w-[64rem]"
-            >
-              {children}
-            </div>
-          </PageActionsTarget>
-        </PageNavigationTargetContext.Provider>
+      <PageShellContext.Provider value={shell}>
+        <div
+          data-slot="page-shell-content"
+          className="min-h-0 min-w-0 flex-1 overflow-auto [&>*]:min-w-[64rem]"
+        >
+          {children}
+        </div>
       </PageShellContext.Provider>
     </div>
   );
@@ -232,11 +157,21 @@ interface PageComposedProps extends PageBaseProps {
 
 export type PageProps = PageShorthandProps | PageComposedProps;
 
+function flattenPageHeaderChildren(node: ReactNode): ReactNode[] {
+  return Children.toArray(node).flatMap((child) =>
+    isValidElement(child) && child.type === Fragment
+      ? flattenPageHeaderChildren(
+          (child.props as { children?: ReactNode }).children,
+        )
+      : [child],
+  );
+}
+
 function countDirectChildrenOfType(
   node: ReactElement,
   type: typeof PageTitle,
 ): number {
-  return Children.toArray(
+  return flattenPageHeaderChildren(
     (node.props as { children?: ReactNode }).children,
   ).filter((child) => isValidElement(child) && child.type === type).length;
 }
@@ -292,9 +227,10 @@ export function Page({
   children,
   ...props
 }: PageProps): ReactElement {
-  const insideShell = useContext(PageShellContext);
+  const shell = useContext(PageShellContext);
+  const insideShell = shell !== null;
   const shorthand = title !== undefined;
-  const nodes = Children.toArray(children);
+  const nodes = flattenPageHeaderChildren(children);
   const headers = nodes.filter(
     (node) => isValidElement(node) && node.type === PageHeader,
   );
@@ -304,9 +240,6 @@ export function Page({
   const footers = nodes.filter(
     (node) => isValidElement(node) && node.type === PageFooter,
   );
-  const intros = nodes.filter(
-    (node) => isValidElement(node) && node.type === PageIntro,
-  );
   const activeStateCount = useRef(0);
   const headingCount = useRef(0);
   const [integralState, setIntegralState] = useState(false);
@@ -338,7 +271,7 @@ export function Page({
     nodes.some(
       (node) =>
         isValidElement(node) &&
-        [PageHeader, PageIntro, PageBody, PageFooter].includes(
+        [PageHeader, PageBody, PageFooter].includes(
           node.type as typeof PageHeader,
         ),
     )
@@ -350,14 +283,12 @@ export function Page({
   if (!shorthand) {
     const validComposition =
       headers.length <= 1 &&
-      intros.length <= 1 &&
       bodies.length === 1 &&
       footers.length <= 1 &&
-      headers.length + intros.length + bodies.length + footers.length ===
-        nodes.length;
+      headers.length + bodies.length + footers.length === nodes.length;
     if (!validComposition) {
       throw new Error(
-        "Page explícito exige um PageBody e aceita no máximo um PageHeader, um PageIntro e um PageFooter como filhos diretos.",
+        "Page explícito exige um PageBody e aceita no máximo um PageHeader e um PageFooter como filhos diretos.",
       );
     }
     const bodyHeadingSources = bodies.reduce<{
@@ -380,13 +311,7 @@ export function Page({
         (total, header) =>
           total + countDirectChildrenOfType(header as ReactElement, PageTitle),
         0,
-      ) +
-      intros.reduce<number>(
-        (total, intro) =>
-          total + countDirectChildrenOfType(intro as ReactElement, PageTitle),
-        0,
-      ) +
-      bodyHeadingSources.content;
+      ) + bodyHeadingSources.content;
     const headingSources =
       bodyHeadingSources.state > 0
         ? bodyHeadingSources.state + bodyHeadingSources.content
@@ -398,7 +323,7 @@ export function Page({
     );
     if (headingSources > 1 || (headingSources === 0 && !hasOpaqueBodyContent)) {
       throw new Error(
-        "Page explícito exige exatamente um heading principal em PageHeader, PageIntro, Content level={1} ou PageState ativo dentro de PageBody.",
+        "Page explícito exige exatamente um heading principal em PageHeader, Content level={1} ou PageState ativo dentro de PageBody.",
       );
     }
   }
@@ -407,34 +332,27 @@ export function Page({
     if (integralState !== hasActiveIntegralState) return;
     if (headingCount.current !== 1) {
       throw new Error(
-        "Page explícito exige exatamente um heading principal em PageHeader, PageIntro, Content level={1} ou PageState ativo dentro de PageBody.",
+        "Page explícito exige exatamente um heading principal em PageHeader, Content level={1} ou PageState ativo dentro de PageBody.",
       );
     }
   });
-  const content =
-    shorthand && insideShell ? (
-      <>
-        {actions !== undefined && (
-          <PageHeader>
-            <PageActions>{actions}</PageActions>
-          </PageHeader>
-        )}
-        <PageIntro>
-          <PageTitle>{title}</PageTitle>
-        </PageIntro>
-        <PageBody>{children}</PageBody>
-      </>
-    ) : shorthand ? (
-      <>
-        <PageHeader>
-          <PageTitle>{title}</PageTitle>
-          {actions !== undefined && <PageActions>{actions}</PageActions>}
-        </PageHeader>
-        <PageBody>{children}</PageBody>
-      </>
-    ) : (
-      children
-    );
+  const content = shorthand ? (
+    <>
+      <PageHeader>
+        <PageTitle>{title}</PageTitle>
+        {actions !== undefined && <PageActions>{actions}</PageActions>}
+      </PageHeader>
+      <PageBody>{children}</PageBody>
+    </>
+  ) : (
+    <>
+      {headers.length === 0 &&
+      (shell?.navigation !== undefined || shell?.actions !== undefined) ? (
+        <PageHeader />
+      ) : null}
+      {children}
+    </>
+  );
 
   return (
     <PageContext.Provider value={{}}>
@@ -473,56 +391,7 @@ export function Page({
   );
 }
 
-/** Título estrutural no conteúdo de PageShell ou introdução opcional de uma Page isolada. */
-export function PageIntro({
-  className,
-  children,
-  ...props
-}: HTMLAttributes<HTMLDivElement>): ReactElement {
-  const page = useContext(PageContext);
-  const insideShell = useContext(PageShellContext);
-  const integralState = useContext(PageIntegralStateContext);
-  requireParent(page !== null, "PageIntro", "Page");
-  if (integralState) {
-    if (!insideShell) return <></>;
-    const persistentSlots = Children.toArray(children).filter(
-      (node) =>
-        isValidElement(node) &&
-        [PageBack, PageNavigation, PageActions].includes(
-          node.type as typeof PageBack,
-        ),
-    );
-    return (
-      <PageHeaderContext.Provider value="intro">
-        {persistentSlots}
-      </PageHeaderContext.Provider>
-    );
-  }
-
-  return (
-    <PageHeaderContext.Provider value="intro">
-      <SurfaceHeader
-        name="PageIntro"
-        slot="page-intro"
-        slots={{
-          leading: [PageBack, PageNavigation],
-          title: PageTitle,
-          actions: PageActions,
-        }}
-        leadingPlacement="inline"
-        className={className}
-        {...props}
-      >
-        {children}
-      </SurfaceHeader>
-    </PageHeaderContext.Provider>
-  );
-}
-
-/**
- * Chrome da Page: navegação e ações persistentes. Fora de PageShell também pode
- * carregar o título; dentro dele, os slots são projetados na barra do shell.
- */
+/** Cabeçalho único da Page: navegação contextual, título e ações. */
 export interface PageHeaderProps extends HTMLAttributes<HTMLDivElement> {}
 
 export function PageHeader({
@@ -531,19 +400,58 @@ export function PageHeader({
   ...props
 }: PageHeaderProps): ReactElement {
   const page = useContext(PageContext);
-  const insideShell = useContext(PageShellContext);
+  const shell = useContext(PageShellContext);
   const integralState = useContext(PageIntegralStateContext);
   requireParent(page !== null, "PageHeader", "Page");
-  if (integralState && !insideShell) return <></>;
-  if (insideShell) {
-    return (
-      <PageHeaderContext.Provider value="header">
-        {children}
-      </PageHeaderContext.Provider>
+  if (integralState) return <></>;
+
+  const nodes = flattenPageHeaderChildren(children);
+  const localNavigation = nodes.filter(
+    (node) =>
+      isValidElement(node) &&
+      node.type === PageNavigation &&
+      hasRenderableNode((node.props as { children?: ReactNode }).children),
+  );
+  const localActions = nodes.filter(
+    (node) =>
+      isValidElement(node) &&
+      node.type === PageActions &&
+      hasRenderableNode((node.props as { children?: ReactNode }).children),
+  ) as ReactElement<HTMLAttributes<HTMLDivElement>>[];
+  if (shell?.navigation !== undefined && localNavigation.length > 0) {
+    throw new Error(
+      "PageHeader não combina a navegação de PageShell com PageNavigation local.",
     );
   }
+  if (localActions.length > 1) {
+    throw new Error("PageHeader aceita no máximo um PageActions.");
+  }
+  const structuralChildren = nodes.filter(
+    (node) =>
+      !(
+        isValidElement(node) &&
+        [PageNavigation, PageActions].includes(
+          node.type as typeof PageNavigation,
+        )
+      ),
+  );
+  const pageActions = localActions[0];
+  const mergedActions =
+    shell?.actions === undefined && pageActions === undefined ? null : (
+      <PageActions {...pageActions?.props}>
+        {shell?.actions}
+        {pageActions?.props.children}
+      </PageActions>
+    );
+  if (
+    structuralChildren.length === 0 &&
+    mergedActions === null &&
+    shell?.navigation === undefined
+  ) {
+    return <></>;
+  }
   return (
-    <PageHeaderContext.Provider value="header">
+    <PageHeaderContext.Provider value>
       <SurfaceHeader
         name="PageHeader"
         slot="page"
@@ -552,15 +460,18 @@ export function PageHeader({
           title: PageTitle,
           actions: PageActions,
         }}
-        leadingPlacement="inline"
+        leadingPlacement="above"
         titleRequired={false}
-        className={cn(
-          "flex h-[3.75rem] items-center border-b p-3 [&>*]:w-full",
-          className,
-        )}
+        className={className}
         {...props}
       >
-        {children}
+        {shell?.navigation === undefined ? (
+          localNavigation
+        ) : (
+          <PageNavigation>{shell.navigation}</PageNavigation>
+        )}
+        {structuralChildren}
+        {mergedActions}
       </SurfaceHeader>
     </PageHeaderContext.Provider>
   );
@@ -570,18 +481,13 @@ export function PageTitle({
   className,
   ...props
 }: HTMLAttributes<HTMLHeadingElement>): ReactElement {
-  const variant = useContext(PageHeaderContext);
-  requireParent(variant !== null, "PageTitle", "PageHeader ou PageIntro");
+  const insideHeader = useContext(PageHeaderContext);
+  requireParent(insideHeader, "PageTitle", "PageHeader");
   usePageHeadingPresence();
   return (
     <h1
       data-slot="page-title"
-      className={cn(
-        variant === "intro"
-          ? "text-3xl font-semibold tracking-tight"
-          : surfaceHeaderClasses.page.title,
-        className,
-      )}
+      className={cn(surfaceHeaderClasses.page.title, className)}
       {...props}
     />
   );
@@ -591,23 +497,16 @@ export function PageActions({
   className,
   ...props
 }: HTMLAttributes<HTMLDivElement>): ReactElement {
-  const variant = useContext(PageHeaderContext);
-  requireParent(variant !== null, "PageActions", "PageHeader ou PageIntro");
+  const insideHeader = useContext(PageHeaderContext);
+  requireParent(insideHeader, "PageActions", "PageHeader");
   const target = useContext(PageActionsTargetContext);
-  const insideShell = useContext(PageShellContext);
   const actions = (
     <div
       data-slot="page-actions"
-      className={cn(
-        insideShell || variant === "header"
-          ? "flex shrink-0 items-center gap-2"
-          : surfaceHeaderClasses.page.actions,
-        className,
-      )}
+      className={cn(surfaceHeaderClasses.page.actions, className)}
       {...props}
     />
   );
-  if (insideShell && target === null) return <></>;
   return target === null ? actions : createPortal(actions, target);
 }
 
@@ -627,21 +526,15 @@ export function PageNavigation({
   className,
   ...props
 }: HTMLAttributes<HTMLDivElement>): ReactElement {
-  const variant = useContext(PageHeaderContext);
-  const insideShell = useContext(PageShellContext);
-  const target = useContext(PageNavigationTargetContext);
-  requireParent(variant !== null, "PageNavigation", "PageHeader ou PageIntro");
-  const navigation = (
+  const insideHeader = useContext(PageHeaderContext);
+  requireParent(insideHeader, "PageNavigation", "PageHeader");
+  return (
     <div
       data-slot="page-navigation-content"
       className={cn("min-w-0", className)}
       {...props}
     />
   );
-  if (insideShell) {
-    return target === null ? <></> : createPortal(navigation, target);
-  }
-  return navigation;
 }
 
 export function PageBack({
@@ -650,10 +543,8 @@ export function PageBack({
   "aria-label": ariaLabel,
   ...props
 }: PageBackProps): ReactElement {
-  const variant = useContext(PageHeaderContext);
-  const insideShell = useContext(PageShellContext);
-  const target = useContext(PageNavigationTargetContext);
-  requireParent(variant !== null, "PageBack", "PageHeader ou PageIntro");
+  const insideHeader = useContext(PageHeaderContext);
+  requireParent(insideHeader, "PageBack", "PageHeader");
   const destination =
     typeof children === "string" ? children : "a página anterior";
   const accessibleLabel = ariaLabel ?? `Voltar para ${destination}`;
@@ -671,9 +562,6 @@ export function PageBack({
       </a>
     </Button>
   );
-  if (insideShell) {
-    return target === null ? <></> : createPortal(back, target);
-  }
   return back;
 }
 

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

@@ -66,7 +66,6 @@ import {
   PageBody,
   PageFooter,
   PageHeader,
-  PageIntro,
   PageNavigation,
   PageTitle,
   useInsidePageShell,
@@ -272,12 +271,14 @@ function PresentationFrame({
           className={cn("flex min-h-full flex-col", className)}
         >
           {navigation === undefined &&
+          contentOwnsHeading &&
           headerActions === undefined &&
           assistantAction === undefined ? null : (
             <PageHeader>
               {navigation === undefined ? null : (
                 <PageNavigation>{navigation}</PageNavigation>
               )}
+              {contentOwnsHeading ? null : <PageTitle>{title}</PageTitle>}
               {headerActions === undefined &&
               assistantAction === undefined ? null : (
                 <PageActions>
@@ -289,11 +290,6 @@ function PresentationFrame({
               )}
             </PageHeader>
           )}
-          {contentOwnsHeading ? null : (
-            <PageIntro>
-              <PageTitle>{title}</PageTitle>
-            </PageIntro>
-          )}
           <PageBody className="min-h-0 flex-1 overflow-hidden">
             {withAssistant(
               <div