@softize/opus 18.5.0 → 20.0.0

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

@@ -42,18 +42,22 @@ import { Copyable } from "../primitives/copyable.tsx";
 import { DetailField, DetailGroup } from "../primitives/detail.tsx";
 import {
   Dialog,
+  DialogActions,
   DialogBody,
   DialogContent,
   DialogFooter,
   DialogHeader,
+  DialogNavigation,
   DialogTitle,
 } from "../primitives/dialog.tsx";
 import {
   Drawer,
+  DrawerActions,
   DrawerBody,
   DrawerContent,
   DrawerFooter,
   DrawerHeader,
+  DrawerNavigation,
   DrawerTitle,
 } from "../primitives/drawer.tsx";
 import {
@@ -79,6 +83,7 @@ import {
   ContentTitle,
 } from "./content-header.tsx";
 import { SurfaceAssistant } from "./surface-assistant.tsx";
+import { fillRegionClassName, useFillRegion } from "./fill-region.ts";
 
 interface PresentationFrameProps {
   surface: PresentationSurface;
@@ -105,6 +110,35 @@ interface PresentationFrameProps {
 const bodyClassName =
   "h-full min-h-full [&>[data-slot=data-state]]:flex [&>[data-slot=data-state]]:min-h-full [&>[data-slot=data-state]]:items-center [&>[data-slot=data-state]]:justify-center";
 
+/**
+ * Corpo da Presentation. Em página `fill`, é o último elo da cadeia de altura (ADR 0024):
+ * a lista do body é filha direta dele e assume `fill` sem classe no consumidor.
+ */
+function PresentationBody({
+  layout,
+  className,
+  children,
+}: {
+  layout: "flow" | "fill";
+  className?: string;
+  children: ReactNode;
+}): ReactElement {
+  const fill = useFillRegion();
+  return (
+    <div
+      data-slot="presentation-body"
+      {...fill.attributes}
+      className={cn(
+        bodyClassName,
+        (layout === "fill" || fill.filling) && fillRegionClassName,
+        className,
+      )}
+    >
+      {fill.provide(children)}
+    </div>
+  );
+}
+
 function PresentationActions({
   children,
   equal = false,
@@ -162,17 +196,14 @@ function PresentationFrame({
     </PresentationActions>
   );
   const body = (
-    <div
-      data-slot="presentation-body"
-      className={cn(
-        bodyClassName,
-        layout === "fill" && "flex min-h-0 flex-1 flex-col",
-        bodyClassNameProp,
-      )}
-    >
+    <PresentationBody layout={layout} className={bodyClassNameProp}>
       {typeof children === "function" ? children(footerTarget) : children}
-    </div>
+    </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
@@ -220,7 +251,12 @@ function PresentationFrame({
           )}
           <PageBody className="min-h-0 flex-1 overflow-hidden">
             {withAssistant(
-              <div className="h-full overflow-x-hidden overflow-y-auto">
+              <div
+                className={cn(
+                  "h-full overflow-x-hidden overflow-y-auto",
+                  viewportFillClassName,
+                )}
+              >
                 {content}
               </div>,
             )}
@@ -253,19 +289,20 @@ function PresentationFrame({
               )}
             </PageHeader>
           )}
+          {contentOwnsHeading ? null : (
+            <PageIntro>
+              <PageTitle>{title}</PageTitle>
+            </PageIntro>
+          )}
           <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,
                 )}
               >
-                {contentOwnsHeading ? null : (
-                  <PageIntro>
-                    <PageTitle>{title}</PageTitle>
-                  </PageIntro>
-                )}
                 {body}
               </div>,
             )}
@@ -299,7 +336,12 @@ function PresentationFrame({
         </PageHeader>
         <PageBody className="min-h-0 flex-1 overflow-hidden">
           {withAssistant(
-            <div className="h-full overflow-x-hidden overflow-y-auto px-8 py-8">
+            <div
+              className={cn(
+                "h-full overflow-x-hidden overflow-y-auto px-8 py-8",
+                viewportFillClassName,
+              )}
+            >
               {body}
             </div>,
           )}
@@ -311,37 +353,30 @@ function PresentationFrame({
 
   if (surface === "dialog") {
     return (
-      <Dialog
-        open={open}
-        onOpenChange={(nextOpen) => {
-          if (!nextOpen && blocked) return;
-          onOpenChange?.(nextOpen);
-        }}
-      >
+      <Dialog open={open} onOpenChange={onOpenChange}>
         <DialogContent
           className={cn(
             assistantOpen ? "h-[min(48rem,85vh)] max-w-5xl" : undefined,
             className,
           )}
           aria-describedby={undefined}
+          // `closeDisabled` bloqueia o botão de fechar, o Esc e o clique fora da superfície.
           closeDisabled={blocked}
-          onEscapeKeyDown={(event) => {
-            if (blocked) event.preventDefault();
-          }}
-          onPointerDownOutside={(event) => {
-            if (blocked) event.preventDefault();
-          }}
         >
           <div className="flex h-full min-h-0 flex-col">
             <DialogHeader>
-              {navigation}
-              <DialogTitle className="truncate">{title}</DialogTitle>
+              {navigation === undefined ? null : (
+                <DialogNavigation>{navigation}</DialogNavigation>
+              )}
+              <DialogTitle>{title}</DialogTitle>
               {headerActions === undefined &&
               assistantAction === undefined ? null : (
-                <PresentationActions>
-                  {headerActions}
-                  {assistantAction}
-                </PresentationActions>
+                <DialogActions>
+                  <PresentationActions>
+                    {headerActions}
+                    {assistantAction}
+                  </PresentationActions>
+                </DialogActions>
               )}
             </DialogHeader>
             {withAssistant(<DialogBody>{body}</DialogBody>)}
@@ -355,13 +390,7 @@ function PresentationFrame({
   }
 
   return (
-    <Drawer
-      open={open}
-      onOpenChange={(nextOpen) => {
-        if (!nextOpen && blocked) return;
-        onOpenChange?.(nextOpen);
-      }}
-    >
+    <Drawer open={open} onOpenChange={onOpenChange}>
       <DrawerContent
         className={cn(
           assistantOpen
@@ -371,23 +400,21 @@ function PresentationFrame({
         )}
         aria-describedby={undefined}
         closeDisabled={blocked}
-        onEscapeKeyDown={(event) => {
-          if (blocked) event.preventDefault();
-        }}
-        onPointerDownOutside={(event) => {
-          if (blocked) event.preventDefault();
-        }}
       >
         <div className="flex h-full min-h-0 flex-col">
           <DrawerHeader>
-            {navigation}
-            <DrawerTitle className="truncate">{title}</DrawerTitle>
+            {navigation === undefined ? null : (
+              <DrawerNavigation>{navigation}</DrawerNavigation>
+            )}
+            <DrawerTitle>{title}</DrawerTitle>
             {headerActions === undefined &&
             assistantAction === undefined ? null : (
-              <PresentationActions>
-                {headerActions}
-                {assistantAction}
-              </PresentationActions>
+              <DrawerActions>
+                <PresentationActions>
+                  {headerActions}
+                  {assistantAction}
+                </PresentationActions>
+              </DrawerActions>
             )}
           </DrawerHeader>
           {withAssistant(<DrawerBody>{body}</DrawerBody>)}

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

@@ -7,6 +7,19 @@ import {
 import { ChevronRight } from "lucide-react";
 import { useOverflowing } from "../../lib/overflow.ts";
 import { cn } from "../../lib/cn.ts";
+
+// Os slots de Pane moram em `pane.tsx` desde a ADR 0023. A Sidebar continua sendo uma
+// das superfícies que os compõe, então reexporta o que antes definia.
+export {
+  PaneActions,
+  PaneBody,
+  PaneContent,
+  PaneDescription,
+  PaneFooter,
+  PaneHeader,
+  PaneMedia,
+  PaneTitle,
+} from "./pane.tsx";
 import { focusRing } from "../primitives/control.ts";
 import {
   Tooltip,
@@ -58,78 +71,6 @@ export function Sidebar({
   );
 }
 
-/** Faixa fixa no topo de um pane — marca, contexto ou ações locais. */
-export function PaneHeader({
-  className,
-  children,
-}: {
-  className?: string;
-  children: ReactNode;
-}): React.ReactElement {
-  return (
-    <div
-      data-slot="pane-header"
-      className={cn("shrink-0 border-b border-border", className)}
-    >
-      {children}
-    </div>
-  );
-}
-
-/** Região rolável que ocupa o espaço restante de um pane. */
-export function PaneBody({
-  className,
-  children,
-}: {
-  className?: string;
-  children: ReactNode;
-}): React.ReactElement {
-  return (
-    <div
-      data-slot="pane-body"
-      className={cn("min-h-0 flex-1 overflow-y-auto", className)}
-    >
-      {children}
-    </div>
-  );
-}
-
-/** @deprecated Use PaneBody. Alias mantido para migração; sai numa próxima versão major. */
-export function PaneContent({
-  className,
-  children,
-}: {
-  className?: string;
-  children: ReactNode;
-}): React.ReactElement {
-  return (
-    <div
-      data-slot="pane-content"
-      className={cn("min-h-0 flex-1 overflow-y-auto", className)}
-    >
-      {children}
-    </div>
-  );
-}
-
-/** Faixa fixa no rodapé de um pane para ações persistentes. */
-export function PaneFooter({
-  className,
-  children,
-}: {
-  className?: string;
-  children: ReactNode;
-}): React.ReactElement {
-  return (
-    <div
-      data-slot="pane-footer"
-      className={cn("shrink-0 border-t border-border p-2", className)}
-    >
-      {children}
-    </div>
-  );
-}
-
 export interface SidebarItemProps {
   label: string;
   icon?: ReactNode;

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

@@ -1,41 +1,18 @@
-import { Children, isValidElement, type CSSProperties, type ReactElement, type ReactNode } from 'react'
+import { Children, cloneElement, Fragment, isValidElement, type ReactElement, type ReactNode } from 'react'
 import { cn } from '../../lib/cn.ts'
 import { ResizableHandle, ResizablePanel, ResizablePanelGroup } from '../primitives/resizable.tsx'
+import { Pane, paneSizeToCss, type PaneProps, type PaneSize } from './pane.tsx'
+
+// A família Pane mora em `pane.tsx` desde a ADR 0023; o Split continua sendo sua casa
+// pública, então reexporta o que já era importado daqui.
+export { Pane, PaneActions, PaneBody, PaneContent, PaneDescription, PaneFooter, PaneHeader, PaneMedia, PaneTitle } from './pane.tsx'
+export type { PaneProps, PaneSize }
 
-export type PaneSize = number | `${number}%` | `${number}rem` | `${number}em` | `${number}vh` | `${number}vw` | `${number}px`
 export type SplitLayout = Record<string, number>
 export interface SplitLayoutChange {
   isUserInteraction: boolean
 }
 
-export interface PaneProps {
-  /** Identidade estável usada pelo layout redimensionável e por layouts persistidos. */
-  id?: string
-  /** Tamanho inicial. Números representam porcentagens; strings aceitam %, rem, em, vh, vw e px. */
-  initialSize?: PaneSize
-  /** Tamanho mínimo quando o split é redimensionável. */
-  minSize?: PaneSize
-  /** Tamanho máximo quando o split é redimensionável. */
-  maxSize?: PaneSize
-  /** Ocupa o espaço remanescente no layout simples. */
-  grow?: boolean
-  /** Respiro interno padrão. Use `none` para chrome, navegação ou conteúdo com inset próprio. */
-  inset?: 'none' | 'sm' | 'md' | 'lg'
-  className?: string
-  children: ReactNode
-}
-
-/** Um conteúdo encaixável. Sua posição é dada pela ordem dentro de <Split>. */
-export function Pane({ id, initialSize, grow = false, inset = 'md', className, children }: PaneProps): React.ReactElement {
-  const style: CSSProperties | undefined = initialSize === undefined ? undefined : { flexBasis: sizeToCss(initialSize) }
-  const insets = { none: '', sm: 'p-2', md: 'p-4', lg: 'p-6' } as const
-  return (
-    <div id={id === undefined ? undefined : String(id)} data-slot="pane" data-inset={inset} className={cn('min-h-0 min-w-0 shrink-0', grow && 'flex-1', insets[inset], className)} style={style}>
-      {children}
-    </div>
-  )
-}
-
 export interface SplitProps {
   /** Identidade estável do grupo redimensionável. */
   id?: string
@@ -53,20 +30,56 @@ export interface SplitProps {
   children: ReactNode
 }
 
+/**
+ * Expande fragments em qualquer profundidade, como quem escreve `<>{a}{b}</>` espera.
+ * `Children.toArray` numera as chaves por nível, então o filho de um fragment herda a
+ * chave do fragment como prefixo — sem isso, `.0` de dentro colidiria com `.0` de fora.
+ */
+function flattenFragments(children: ReactNode, prefix = ''): ReactNode[] {
+  return Children.toArray(children).flatMap((node): ReactNode[] => {
+    if (isValidElement(node) && node.type === Fragment)
+      return flattenFragments((node.props as { children?: ReactNode }).children, `${prefix}${String(node.key)}/`)
+    if (prefix !== '' && isValidElement(node)) return [cloneElement(node, { key: `${prefix}${String(node.key)}` })]
+    return [node]
+  })
+}
+
+/** Nome legível do filho recusado, para a mensagem apontar o nó certo. */
+function describeChild(node: ReactNode): string {
+  if (typeof node === 'string' || typeof node === 'number' || typeof node === 'bigint') {
+    const text = String(node).trim()
+    return `o texto "${text.length > 40 ? `${text.slice(0, 40)}…` : text}"`
+  }
+  if (isValidElement(node)) {
+    const type = node.type as string | { displayName?: string; name?: string }
+    const name = typeof type === 'string' ? type : (type.displayName ?? type.name ?? '')
+    return name === '' ? 'um componente sem nome' : `<${name}>`
+  }
+  return 'um nó que não é elemento React'
+}
+
+/**
+ * O Split lê `initialSize`, `minSize`, `grow` e `id` de cada Pane ANTES de renderizá-lo,
+ * então só enxerga um `<Pane>` escrito diretamente (ou dentro de fragment). Qualquer outro
+ * filho seria descartado sem aviso — a tela perderia uma região e ninguém saberia por quê.
+ */
 function panesOf(children: ReactNode): ReactElement<PaneProps>[] {
-  return Children.toArray(children).filter(
-    (child): child is ReactElement<PaneProps> => isValidElement<PaneProps>(child) && child.type === Pane,
-  )
+  return flattenFragments(children).flatMap((child) => {
+    if (isValidElement<PaneProps>(child) && child.type === Pane) return [child]
+    // Espaço em branco (um `{' '}` da formatação) não é conteúdo: nunca ocupou lugar.
+    if (typeof child === 'string' && child.trim() === '') return []
+    throw new Error(
+      `Split recebeu ${describeChild(child)} como filho, mas só distribui <Pane>: esse conteúdo ficaria fora do layout. ` +
+        'Envolva-o em um <Pane>. Se ele vem de um componente que devolve um <Pane>, escreva o <Pane> dentro do Split e ' +
+        'passe o componente como filho dele: o Split lê o tamanho de cada pane antes de renderizá-lo.',
+    )
+  })
 }
 
 // Números continuam percentuais por compatibilidade com Split/Pane. Strings preservam
 // a unidade explícita para layouts que precisam de um limite físico, como `28rem`.
-function sizeToCss(value: PaneSize): string {
-  return typeof value === 'number' ? `${value}%` : value
-}
-
 function resizableSize(value: PaneSize | undefined): string | undefined {
-  return value === undefined ? undefined : sizeToCss(value)
+  return value === undefined ? undefined : paneSizeToCss(value)
 }
 
 function percentage(value: PaneSize | undefined): number | undefined {

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

@@ -0,0 +1,246 @@
+/**
+ * Anatomia de superfície (interno): as medidas que Card, Dialog, Drawer e Pane
+ * compartilham — ADR 0023.
+ *
+ * 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
+ * consomem estas tabelas; nenhuma reescreve as classes.
+ *
+ * Dois layouts, e cada um é um pacote indivisível:
+ *
+ * - `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.
+ * - `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.
+ */
+
+import {
+  createContext,
+  createElement,
+  useContext,
+  type ReactElement,
+  type ReactNode,
+} from "react";
+import { FillBoundary } from "./fill-region.ts";
+
+export type SurfaceFamily = "card" | "dialog" | "drawer" | "pane";
+export type SurfaceLayout = "continuous" | "sectioned";
+export type SurfaceRegion = "header" | "body" | "footer";
+
+/**
+ * Divisores: a região desenha a própria linha quando existe uma vizinha do outro lado.
+ * Um header sozinho não fecha nada; um footer que é a única região também não.
+ *
+ * O header suprime a própria linha quando o vizinho imediato é um footer — os dois
+ * juntos desenhariam duas bordas encostadas, uma sobre a outra.
+ */
+const headerDivider = [
+  "[&:not(:last-child)]:border-b",
+  "[&:not(:last-child)]:border-border",
+  // A supressão precisa VENCER a regra acima na cascata, e não só vir depois dela: as
+  // duas nascem com a mesma especificidade e a ordem na folha é do Tailwind, não nossa.
+  // Repetir o `:not(:last-child)` aqui acrescenta uma pseudoclasse e desempata.
+  "[&:not(:last-child):has(+[data-slot$=-footer])]:border-b-0",
+].join(" ");
+const footerDivider =
+  "[&:not(:first-child)]:border-t [&:not(:first-child)]:border-border";
+
+interface RegionAnatomy {
+  header: string;
+  body: string;
+  footer: string;
+}
+
+interface FamilyAnatomy {
+  /** Recuo e ritmo por layout. O recuo lateral é comum às três regiões. */
+  regions: Record<SurfaceLayout, RegionAnatomy>;
+  /** Escala visual do título. O nível semântico do heading é escolhido à parte. */
+  title: Record<SurfaceLayout, string>;
+  /** Descrição no header, quando a família a oferece (ADRs 0014 e 0018 excluem modais). */
+  description: string;
+  /** Espaço entre mídia, título e ações na linha do header. */
+  headerGap: string;
+  /** Faixa do rodapé no layout seccionado, quando a família declara uma. */
+  footerBand: string;
+}
+
+/**
+ * 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.
+ */
+const sectionedRegions: RegionAnatomy = {
+  header: "p-4",
+  body: "p-4",
+  footer: "p-4",
+};
+
+export const surfaceAnatomy: Record<SurfaceFamily, FamilyAnatomy> = {
+  card: {
+    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.
+      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",
+      },
+      sectioned: sectionedRegions,
+    },
+    title: {
+      continuous: "text-base font-semibold leading-none",
+      sectioned: "text-sm font-semibold leading-none",
+    },
+    description: "text-sm text-muted-foreground",
+    headerGap: "gap-3",
+    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",
+      },
+      sectioned: sectionedRegions,
+    },
+    title: {
+      continuous: "text-lg font-semibold leading-none",
+      sectioned: "text-lg font-semibold leading-none",
+    },
+    description: "text-sm text-muted-foreground",
+    headerGap: "gap-4",
+    footerBand: "bg-muted/20 dark:bg-input/20",
+  },
+  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",
+      },
+      sectioned: sectionedRegions,
+    },
+    title: {
+      continuous: "text-lg font-semibold leading-none",
+      sectioned: "text-lg font-semibold leading-none",
+    },
+    description: "text-sm text-muted-foreground",
+    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. */
+export function surfaceRegionClasses(
+  family: SurfaceFamily,
+  layout: SurfaceLayout,
+  region: SurfaceRegion,
+): string {
+  const anatomy = surfaceAnatomy[family];
+  const base = anatomy.regions[layout][region];
+  if (layout !== "sectioned") return base;
+  if (region === "header") return `${base} ${headerDivider}`;
+  if (region === "footer")
+    return [base, footerDivider, anatomy.footerBand].filter(Boolean).join(" ");
+  return base;
+}
+
+/** Escala visual do título — o nível do heading vem da composição, nunca daqui. */
+export function surfaceTitleClasses(
+  family: SurfaceFamily,
+  layout: SurfaceLayout,
+): string {
+  return surfaceAnatomy[family].title[layout];
+}
+
+export function surfaceDescriptionClasses(family: SurfaceFamily): string {
+  return surfaceAnatomy[family].description;
+}
+
+/**
+ * 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.
+ */
+export function surfaceHeaderRowClasses(family: SurfaceFamily): string {
+  return `flex min-w-0 flex-1 items-center ${surfaceAnatomy[family].headerGap}`;
+}
+
+/** 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";
+
+/**
+ * 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
+ * para a superfície inteira.
+ *
+ * O default por família preserva o que ela já entregava antes desta ADR.
+ */
+const SurfaceLayoutContext = createContext<SurfaceLayout | null>(null);
+
+/**
+ * Publica o layout da superfície para os slots. A superfície também interrompe a
+ * propagação de `layout="fill"` da página (ADR 0024): a altura do seu corpo é decisão dela,
+ * inclusive quando um portal a renderiza dentro de uma página `fill`.
+ */
+export function SurfaceLayoutProvider({
+  value,
+  children,
+}: {
+  value: SurfaceLayout;
+  children?: ReactNode;
+}): ReactElement {
+  return createElement(
+    SurfaceLayoutContext.Provider,
+    { value },
+    createElement(FillBoundary, null, children),
+  );
+}
+
+const familyDefaultLayout: Record<SurfaceFamily, SurfaceLayout> = {
+  card: "continuous",
+  dialog: "sectioned",
+  drawer: "sectioned",
+  pane: "sectioned",
+};
+
+/** O layout vigente: o declarado pelo root da superfície, ou o default da família. */
+export function useSurfaceLayout(family: SurfaceFamily): SurfaceLayout {
+  return useContext(SurfaceLayoutContext) ?? familyDefaultLayout[family];
+}
+
+export function defaultSurfaceLayout(family: SurfaceFamily): SurfaceLayout {
+  return familyDefaultLayout[family];
+}