@softize/opus 29.0.0 → 31.0.0

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

@@ -1,9 +1,9 @@
 /**
- * Cabeçalho estrutural (interno): a anatomia que Page, Surface, Dialog, Drawer e Pane
+ * Cabeçalho estrutural (interno): a anatomia que Page, Surface, Dialog e Drawer
  * compartilham. O nome público `SurfaceHeader` pertence à família Surface (ADR 0045).
  *
  * Um título, metadata opcional e uma região de ações que vai para o extremo oposto
- * em larguras amplas e empilha abaixo do contexto nas estreitas. Cada família escolhe quais slots
+ * da linha. Cada família escolhe quais slots
  * expõe; layout, validação e classes vivem aqui, uma vez.
  */
 
@@ -16,7 +16,13 @@ import {
   type ReactElement,
   type ReactNode,
 } from "react";
+import { structuralTitleClasses } from "./surface-anatomy.ts";
 import { cn } from "../../lib/cn.ts";
+import { TabsHeaderContext } from "../primitives/tabs.tsx";
+
+/** Metadados contextuais, separados da orientação textual e da linha de ações. */
+export const structuralMetaClasses =
+  "mt-3 flex min-w-0 flex-wrap items-center gap-x-3 gap-y-2 text-sm text-muted-foreground [overflow-wrap:anywhere] [&>*]:max-w-full";
 
 export type StructuralHeaderVariant = "page" | "section";
 
@@ -26,10 +32,10 @@ export const structuralHeaderClasses: Record<
   { title: string; description: string; count: string; actions: string }
 > = {
   page: {
-    title: "text-3xl font-semibold tracking-tight",
+    title: structuralTitleClasses,
     description: "mt-1 truncate text-sm text-muted-foreground",
     count: "font-mono text-base text-muted-foreground/60",
-    actions: "flex w-auto shrink-0 items-center gap-4",
+    actions: "flex w-auto shrink-0 items-center gap-2",
   },
   section: {
     title: "text-sm font-semibold",
@@ -46,6 +52,7 @@ interface StructuralHeaderSlots {
   title: ElementType;
   count?: ElementType;
   description?: ElementType;
+  meta?: ElementType;
   actions?: ElementType;
 }
 
@@ -68,6 +75,8 @@ export interface StructuralHeaderProps extends HTMLAttributes<HTMLDivElement> {
   titleRequired?: boolean;
   /** Classes da linha `inline` — as famílias com anatomia própria trazem a sua (ADR 0023). */
   rowClassName?: string;
+  /** Lista de abas sob o título; o Tabs ancestral governa seleção e painéis. */
+  tabs?: ReactNode;
   /** Nó interno acrescentado ao fim da linha, depois das ações (o botão de fechar). */
   trailing?: ReactNode;
   /**
@@ -103,12 +112,18 @@ export function StructuralHeader({
   titleRequired = true,
   rowClassName,
   trailing,
+  tabs,
   allowFreeContent = false,
   invalidMessage,
   className,
   children,
   ...props
 }: StructuralHeaderProps): ReactElement {
+  const hasTabs = tabs !== undefined && tabs !== null && tabs !== false;
+
+  if (hasTabs && Root === "legend") {
+    throw new Error("SurfaceHeader de fieldset não aceita abas.");
+  }
   const Wrapper = Root === "legend" ? "span" : "div";
   const nodes = flatten(children).filter(
     (node) => typeof node !== "string" || node.trim() !== "",
@@ -127,6 +142,7 @@ export function StructuralHeader({
   const counts = slots.count === undefined ? [] : of(slots.count);
   const descriptions =
     slots.description === undefined ? [] : of(slots.description);
+  const metas = slots.meta === undefined ? [] : of(slots.meta);
   const actionSlots = slots.actions === undefined ? [] : of(slots.actions);
   const slotTypes = [
     ...leadingTypes,
@@ -134,6 +150,7 @@ export function StructuralHeader({
     slots.title,
     slots.count,
     slots.description,
+    slots.meta,
     slots.actions,
   ].filter((type): type is ElementType => type !== undefined);
   const free = allowFreeContent
@@ -151,6 +168,7 @@ export function StructuralHeader({
     titles.length +
     counts.length +
     descriptions.length +
+    metas.length +
     actionSlots.length;
 
   if (
@@ -159,6 +177,7 @@ export function StructuralHeader({
     medias.length > 1 ||
     counts.length > 1 ||
     descriptions.length > 1 ||
+    metas.length > 1 ||
     actionSlots.length > 1 ||
     recognized !== nodes.length
   ) {
@@ -170,6 +189,7 @@ export function StructuralHeader({
       ...leadingTypes,
       slots.media,
       slots.description,
+      slots.meta,
       slots.count,
       slots.actions,
     ]
@@ -193,6 +213,10 @@ export function StructuralHeader({
     );
   }
 
+  if (metas.length > 0 && titles.length === 0) {
+    throw new Error(`${name} exige título para exibir metadados.`);
+  }
+
   const titleLine = titles.length + counts.length > 0 && (
     <Wrapper className="flex items-baseline gap-2">
       {titles}
@@ -267,8 +291,7 @@ export function StructuralHeader({
       {inlineContext === null &&
         leadingPlacement === "inline" &&
         leading.length > 0 && (
-          // `min-w-0` aqui é o que deixa a trilha do PageNavigation ceder e truncar; sem ele o
-          // wrapper assume o min-content do breadcrumb e a compressão toda cai sobre o título.
+          // A região de navegação pode ceder espaço sem comprimir o título além do container.
           <Wrapper
             data-slot={`${slot}-navigation`}
             className={cn("flex min-w-0 items-center", !heading && "flex-1")}
@@ -342,11 +365,20 @@ export function StructuralHeader({
       </>
     );
 
+  const withMeta = (
+    <>
+      {layout}
+      {metas}
+    </>
+  );
+
   return (
     <Root
       data-slot={`${slot}-header`}
       className={cn(
-        contentClassName === undefined &&
+        !hasTabs &&
+          metas.length === 0 &&
+          contentClassName === undefined &&
           leadingPlacement !== "inline" &&
           leading.length === 0 &&
           actionSlots.length > 0 &&
@@ -355,44 +387,25 @@ export function StructuralHeader({
             heading ? "justify-between" : "justify-end",
           ),
         className,
+        hasTabs && "block border-b pb-0",
       )}
       {...props}
     >
       {contentClassName === undefined ? (
-        layout
+        withMeta
       ) : (
         <Wrapper
           data-slot={`${slot}-header-content`}
           className={contentClassName}
         >
-          {layout}
+          {withMeta}
         </Wrapper>
       )}
+      {hasTabs && (
+        <div data-slot={`${slot}-header-tabs`} className="mt-4 min-w-0">
+          <TabsHeaderContext.Provider value>{tabs}</TabsHeaderContext.Provider>
+        </div>
+      )}
     </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

@@ -1,43 +1,7 @@
-/**
- * Anatomia de superfície (interno): as medidas que Surface, Dialog e Drawer
- * compartilham — ADRs 0023, 0045 e 0047.
- *
- * 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. É a superfície 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.
- */
-
-import {
-  createContext,
-  createElement,
-  useContext,
-  type ReactElement,
-  type ReactNode,
-} from "react";
-import { FillBoundary } from "./fill-region.ts";
-
+/** Anatomia única de Page, Surface, Dialog e Drawer — ADR 0060. */
 export type SurfaceFamily = "surface" | "dialog" | "drawer" | "page";
-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",
@@ -49,238 +13,84 @@ const headerDivider = [
 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 (ADR 0059 inclui subheadings opcionais em modais). */
+  title: string;
   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.
- * 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";
+export const structuralTitleClasses = "text-lg font-semibold leading-tight";
 
-const sectionedRegions: RegionAnatomy = {
-  header: structuralHeaderPadding,
-  body: "p-4",
-  footer: "p-4",
-};
-
-/**
- * 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.
- */
 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",
-    },
+    title: structuralTitleClasses,
     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: {
-      // No contínuo, a região anterior fornece o intervalo; a primeira abre o recuo.
-      continuous: {
-        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: structuralHeaderPadding,
-        body: "p-4",
-        footer: "p-4",
-      },
-    },
-    // Uma escala só: o nível 1 troca a apresentação inteira (ADR 0038), nunca o layout.
-    title: {
-      continuous: "text-sm font-semibold",
-      sectioned: "text-sm font-semibold",
-    },
+    title: "text-sm font-semibold",
     description: "mt-0.5 text-xs text-muted-foreground",
     headerGap: "gap-2",
-    headerMinHeight: structuralHeaderMinHeight,
     footerBand: "",
   },
   dialog: {
-    regions: {
-      continuous: {
-        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,
-    },
-    title: {
-      continuous: "text-lg font-semibold leading-none",
-      sectioned: "text-lg font-semibold leading-none",
-    },
+    title: structuralTitleClasses,
     description: "text-sm text-muted-foreground",
     headerGap: "gap-4",
-    headerMinHeight: structuralHeaderMinHeight,
     footerBand: "bg-muted/20 dark:bg-input/20",
   },
   drawer: {
-    regions: {
-      continuous: {
-        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,
-    },
-    title: {
-      continuous: "text-lg font-semibold leading-none",
-      sectioned: "text-lg font-semibold leading-none",
-    },
+    title: structuralTitleClasses,
     description: "text-sm text-muted-foreground",
     headerGap: "gap-4",
-    headerMinHeight: structuralHeaderMinHeight,
     footerBand: "bg-muted/20 dark:bg-input/20",
   },
 };
 
-/** Classes da região, já com o divisor que o layout deriva da vizinhança. */
+/** Recuo da região e divisor automático quando existe uma região vizinha. */
 export function surfaceRegionClasses(
   family: SurfaceFamily,
-  layout: SurfaceLayout,
   region: SurfaceRegion,
-  { flush = false }: { flush?: boolean } = {},
+  {
+    flush = false,
+    bounded = true,
+  }: { flush?: boolean; bounded?: boolean } = {},
 ): string {
-  const anatomy = surfaceAnatomy[family];
-  const base =
-    region === "body" && flush
-      ? structuralBodyRhythm
-      : anatomy.regions[layout][region];
-  const regionClasses =
-    region === "body" && !flush ? `${base} ${structuralBodyRhythm}` : base;
-  if (layout !== "sectioned") return regionClasses;
-  if (region === "header") return `${regionClasses} ${headerDivider}`;
-  if (region === "footer")
-    return [regionClasses, footerDivider, anatomy.footerBand]
-      .filter(Boolean)
-      .join(" ");
-  return regionClasses;
+  const padding = bounded && !(region === "body" && flush) ? "p-4" : "";
+  return [
+    padding,
+    region === "body" && structuralBodyRhythm,
+    bounded && region === "header" && headerDivider,
+    bounded && region === "footer" && footerDivider,
+    region === "footer" && bounded && surfaceAnatomy[family].footerBand,
+  ]
+    .filter(Boolean)
+    .join(" ");
 }
 
-/** 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 surfaceTitleClasses(family: SurfaceFamily): string {
+  return surfaceAnatomy[family].title;
 }
 
 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` mantém o heading como região elástica e as ações no extremo oposto.
- */
+/** Reserva a altura de um botão normal também quando o header não possui ações. */
 export function surfaceHeaderRowClasses(family: SurfaceFamily): string {
-  return `flex min-w-0 flex-1 items-center ${surfaceAnatomy[family].headerGap} ${surfaceAnatomy[family].headerMinHeight}`;
+  return `flex min-w-0 flex-1 items-center ${surfaceAnatomy[family].headerGap} min-h-9`;
 }
 
-/** 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";
 
-/**
- * A `legend` de uma Surface `fieldset` delimitada (ADR 0045).
- *
- * - `notch`: moldura contínua. A legend nativa ocupa a borda, afastada do canto pelo
- *   mesmo recuo lateral das regiões; a região seguinte recebe o intervalo que a legend
- *   não tem como declarar.
- * - `band`: a legend é a faixa do header dentro da superfície. Uma legend só ocupa a
- *   largura inteira fora do fluxo de borda, e a região seguinte precisa limpar o float.
- */
+/** A legend delimitada ocupa uma faixa inteira; a próxima região limpa o float. */
 export const surfaceLegendClasses = {
-  notch: "ml-2 w-auto px-2",
-  afterNotch: "pt-4",
   band: "float-left w-full",
   afterBand: "clear-left",
 } as const;
-
-/**
- * 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> = {
-  page: "sectioned",
-  surface: "continuous",
-  dialog: "sectioned",
-  drawer: "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];
-}