@softize/opus 19.0.0 → 20.1.0

package/src/ui/components/patterns/action-form-card.tsx

@@ -13,6 +13,7 @@ import {
   CardTitle,
 } from "../primitives/card.tsx";
 import { ActionForm, type ActionFormProps } from "./form.tsx";
+import type { HeadingLevel } from "./heading-level.ts";
 import { ButtonGroup } from "../primitives/button-group.tsx";
 
 export interface ActionFormCardProps<
@@ -21,6 +22,12 @@ export interface ActionFormCardProps<
 > extends Omit<ActionFormProps<TInput, TData>, "body" | "footer"> {
   /** Título do header do card. Sem ele, o card começa direto no conteúdo. */
   title?: string;
+  /**
+   * Nível semântico do título (`h1`–`h6`), repassado ao `CardTitle` como `level`. Sem
+   * ele vale o `h3` do Card. Muda só a hierarquia do documento; a escala visual continua
+   * a do Card.
+   */
+  titleLevel?: HeadingLevel;
   /** Subtítulo opcional, abaixo do título. */
   description?: string;
   /** Classes do Card (a superfície). `className` vai pro <form>. */
@@ -29,6 +36,7 @@ export interface ActionFormCardProps<
 
 export function ActionFormCard<TInput extends Record<string, unknown>, TData>({
   title,
+  titleLevel,
   description,
   cardClassName,
   ...rest
@@ -37,7 +45,9 @@ export function ActionFormCard<TInput extends Record<string, unknown>, TData>({
     <Card className={cardClassName}>
       {(title !== undefined || description !== undefined) && (
         <CardHeader>
-          {title !== undefined && <CardTitle>{title}</CardTitle>}
+          {title !== undefined && (
+            <CardTitle level={titleLevel}>{title}</CardTitle>
+          )}
           {description !== undefined && (
             <CardDescription>{description}</CardDescription>
           )}

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

@@ -10,8 +10,14 @@ import {
   type ReactNode,
 } from "react";
 import { cn } from "../../lib/cn.ts";
+import { IconTile, type IconTileProps } from "../primitives/icon-tile.tsx";
+import { fillRegionClassName, useFillRegion } from "./fill-region.ts";
 import { headingTags } from "./heading-level.ts";
 import { usePageHeadingPresence } from "./page-heading-context.tsx";
+import {
+  SurfaceMedia,
+  type SurfaceMediaProps,
+} from "./surface-media.tsx";
 import {
   SurfaceHeader,
   surfaceHeaderClasses,
@@ -58,7 +64,8 @@ interface ContentSectionBaseProps
     Omit<ComponentProps<"section">, "children" | "title"> {
   /** Elemento semântico da região. */
   as?: "section";
-  frameVariant?: "default";
+  /** Tratamento visual da moldura: contínua (default) ou integrada ao header. */
+  frameVariant?: ContentFrameVariant;
   /** Nível semântico do heading, independente de seu destaque visual. */
   level?: ContentHeaderLevel;
 }
@@ -77,6 +84,8 @@ interface ContentFieldsetBaseProps
 
 interface ContentSectionShorthandProps extends ContentSectionBaseProps {
   title: ReactNode;
+  /** Ícone ou imagem que identifica a região, antes do título. */
+  media?: ReactNode;
   /** Total de itens ao lado do título da seção. A página não carrega contador (ADR 0009). */
   count?: number;
   description?: ReactNode;
@@ -86,6 +95,8 @@ interface ContentSectionShorthandProps extends ContentSectionBaseProps {
 
 interface ContentFieldsetShorthandProps extends ContentFieldsetBaseProps {
   title: ReactNode;
+  /** Ícone ou imagem decorativa que acompanha o título dentro da legenda. */
+  media?: ReactNode;
   count?: never;
   description?: never;
   actions?: never;
@@ -94,6 +105,7 @@ interface ContentFieldsetShorthandProps extends ContentFieldsetBaseProps {
 
 interface ContentComposedProps {
   title?: never;
+  media?: never;
   count?: never;
   description?: never;
   actions?: never;
@@ -110,6 +122,7 @@ export type ContentProps =
 export function Content({
   as = "section",
   title,
+  media,
   count,
   description,
   actions,
@@ -122,6 +135,7 @@ export function Content({
   ...props
 }: ContentProps): ReactElement {
   const titleId = useId();
+  const fill = useFillRegion();
   const context = {
     element: as,
     frameVariant,
@@ -162,6 +176,7 @@ export function Content({
   const anatomy = shorthand ? (
     <>
       <ContentHeader>
+        {hasContentMedia(media) && <ContentMedia>{media}</ContentMedia>}
         <ContentTitle>{title}</ContentTitle>
         {count !== undefined && <ContentMeta>{count}</ContentMeta>}
         {description !== undefined && (
@@ -185,6 +200,7 @@ export function Content({
           data-as="fieldset"
           data-framed={framed}
           data-frame-variant={frameVariant}
+          {...fill.attributes}
           aria-labelledby={ariaLabelledBy}
           className={cn(
             !framed && "space-y-3",
@@ -194,11 +210,12 @@ export function Content({
             framed &&
               frameVariant === "legend" &&
               "space-y-3 rounded-lg border border-border px-4 pb-4",
+            fill.filling && fillRegionClassName,
             className,
           )}
           {...(props as ComponentProps<"fieldset">)}
         >
-          {anatomy}
+          {fill.provide(anatomy)}
         </fieldset>
       ) : (
         <section
@@ -206,15 +223,22 @@ export function Content({
           data-as="section"
           data-framed={framed}
           data-frame-variant={frameVariant}
+          {...fill.attributes}
           aria-labelledby={ariaLabelledBy}
           className={cn(
             "space-y-3",
-            framed && "rounded-lg border border-border p-4",
+            framed &&
+              frameVariant === "default" &&
+              "rounded-lg border border-border p-4",
+            framed &&
+              frameVariant === "legend" &&
+              "rounded-lg border border-border px-4 pb-4",
+            fill.filling && fillRegionClassName,
             className,
           )}
           {...(props as ComponentProps<"section">)}
         >
-          {anatomy}
+          {fill.provide(anatomy)}
         </section>
       )}
     </ContentContext.Provider>
@@ -238,20 +262,15 @@ export function ContentHeader({
     "Content",
   );
   if (content.element === "fieldset") {
-    const nodes = Children.toArray(children);
-    if (
-      nodes.length !== 1 ||
-      !isValidElement(nodes[0]) ||
-      nodes[0].type !== ContentTitle
-    ) {
-      throw new Error(
-        "ContentHeader de fieldset exige somente um ContentTitle; contador, descrição e ações ficam fora da legenda.",
-      );
-    }
     return (
       <ContentHeaderContext.Provider value={content}>
-        <legend
-          data-slot="content-header"
+        <SurfaceHeader
+          as="legend"
+          name="ContentHeader"
+          slot="content"
+          slots={{ media: ContentMedia, title: ContentTitle }}
+          mediaPlacement="heading"
+          invalidMessage="ContentHeader de fieldset aceita somente ContentMedia e ContentTitle; contador, descrição e ações ficam fora da legenda."
           className={cn(
             content.framed &&
               content.frameVariant === "default" &&
@@ -264,7 +283,7 @@ export function ContentHeader({
           {...props}
         >
           {children}
-        </legend>
+        </SurfaceHeader>
       </ContentHeaderContext.Provider>
     );
   }
@@ -274,12 +293,25 @@ export function ContentHeader({
         name="ContentHeader"
         slot="content"
         slots={{
+          media: ContentMedia,
           title: ContentTitle,
           count: ContentMeta,
           description: ContentDescription,
           actions: ContentActions,
         }}
+        mediaPlacement="heading"
         className={cn(
+          content.framed &&
+            content.frameVariant === "legend" &&
+            "flex items-center [&>[data-slot=content-actions]]:-mr-2 [&>[data-slot=content-actions]]:bg-[var(--surface-background,var(--background))] [&>[data-slot=content-actions]]:px-2 [&>[data-slot=content-heading]]:-ml-2 [&>[data-slot=content-heading]]:w-fit [&>[data-slot=content-heading]]:max-w-full [&>[data-slot=content-heading]]:bg-[var(--surface-background,var(--background))] [&>[data-slot=content-heading]]:px-2",
+          content.framed &&
+            content.frameVariant === "legend" &&
+            content.variant === "section" &&
+            "-mt-4 min-h-8",
+          content.framed &&
+            content.frameVariant === "legend" &&
+            content.variant === "page" &&
+            "-mt-5 min-h-10",
           content.variant === "page" &&
             "flex-row items-center justify-start gap-3",
           className,
@@ -292,6 +324,59 @@ export function ContentHeader({
   );
 }
 
+/** `null`, `false` e `undefined` não desenham mídia: uma moldura vazia não identifica nada. */
+function hasContentMedia(media: ReactNode): boolean {
+  return media !== undefined && media !== null && media !== false;
+}
+
+/**
+ * Um `IconTile` recebido como filho não vira uma segunda moldura: o slot assume o lugar dele e
+ * herda o que ele declara (`size`, `context`, `variant`, demais props), somando as classes.
+ */
+function adoptIconTile(props: SurfaceMediaProps): SurfaceMediaProps {
+  const { children, asChild, className } = props;
+  if (asChild) return props;
+  // `toArray`, não `only`: um array com um único item (de um `map`/`filter`) é válido aqui.
+  const nodes = Children.toArray(children);
+  if (nodes.length !== 1) return props;
+  const child = nodes[0];
+  if (!isValidElement<IconTileProps>(child) || child.type !== IconTile) {
+    return props;
+  }
+  // `null` em size/context/variant significa "use o padrão" no IconTile: fica o do slot.
+  const declared = Object.fromEntries(
+    Object.entries(child.props).filter(([, value]) => value != null),
+  ) as SurfaceMediaProps;
+  return {
+    ...props,
+    ...declared,
+    className: cn(className, declared.className),
+    children: declared.children,
+  };
+}
+
+/** Moldura de ícone ou imagem que identifica a região nomeada. */
+export function ContentMedia({
+  size = "xs",
+  ...rest
+}: SurfaceMediaProps): ReactElement {
+  const context = requiredContext(
+    useContext(ContentHeaderContext),
+    "ContentMedia",
+    "ContentHeader",
+  );
+  const props = adoptIconTile({ size, ...rest });
+  return (
+    <SurfaceMedia
+      slot="content-media"
+      {...props}
+      aria-hidden={
+        context.element === "fieldset" ? true : props["aria-hidden"]
+      }
+    />
+  );
+}
+
 export function ContentTitle({
   className,
   id,
@@ -379,6 +464,7 @@ export function ContentActions({
 
 export function ContentBody({
   className,
+  children,
   ...props
 }: HTMLAttributes<HTMLDivElement>): ReactElement {
   const content = requiredContext(
@@ -386,18 +472,23 @@ export function ContentBody({
     "ContentBody",
     "Content",
   );
+  const fill = useFillRegion();
   return (
     <div
       data-slot="content-body"
+      {...fill.attributes}
       className={cn(
         content.element === "fieldset" && "space-y-3",
         content.element === "fieldset" &&
           content.framed &&
           content.frameVariant === "default" &&
           "clear-left pt-3",
+        fill.filling && fillRegionClassName,
         className,
       )}
       {...props}
-    />
+    >
+      {fill.provide(children)}
+    </div>
   );
 }

package/src/ui/components/patterns/fill-region.ts

@@ -0,0 +1,150 @@
+/**
+ * Propagação da ocupação de altura (interno) — ADR 0024.
+ *
+ * `Page layout="fill"` limita a página à altura do shell; a `Presentation` em página herda
+ * esse limite pela `Page` que ela monta. Para uma região interna ocupar a folga e rolar
+ * sozinha, cada elemento entre a raiz limitada e essa região precisa repassar a altura como
+ * coluna flexível. Este módulo faz essa cadeia se formar sem classes no consumidor:
+ *
+ * - a raiz (`FillRoot`) publica o contexto;
+ * - os elos canônicos (`PageBody`, `Content`, `ContentBody`, o corpo da `Presentation`)
+ *   leem o contexto com `useFillRegion` e o republicam para os filhos;
+ * - a folha (`ActionList`) usa `useFillLeaf`: assume `fill` por padrão quando o elemento
+ *   pai é um elo e se registra na cadeia;
+ * - um elo só vira coluna flexível quando uma folha se registrou abaixo dele. Irmãos sem
+ *   folha mantêm a altura do próprio conteúdo, e uma página `fill` sem lista não muda;
+ * - superfícies com anatomia própria (Card, Dialog, Drawer, Pane) cortam a cadeia com
+ *   `FillBoundary`: a altura delas é decisão delas, inclusive quando um portal as renderiza
+ *   dentro de uma página `fill`.
+ *
+ * O registro acontece em `useLayoutEffect`, então as classes chegam antes da primeira pintura.
+ */
+
+import {
+  createContext,
+  createElement,
+  useContext,
+  useLayoutEffect,
+  useMemo,
+  useRef,
+  useState,
+  type ReactElement,
+  type ReactNode,
+  type RefObject,
+} from "react";
+
+export type FillLayout = "flow" | "fill";
+
+interface FillChain {
+  /** Anuncia uma folha abaixo deste elo; devolve a retirada do anúncio. */
+  register(): () => void;
+}
+
+const FillChainContext = createContext<FillChain | null>(null);
+
+/** A raiz já tem altura limitada: não há o que propagar acima dela. */
+const rootChain: FillChain = { register: () => () => {} };
+
+/** Classes de um elo que repassa a altura à folha registrada abaixo dele. */
+export const fillRegionClassName = "flex min-h-0 flex-1 flex-col";
+
+/**
+ * Atributo que marca um elo da cadeia no DOM: `"true"` quando repassa a altura, `"false"`
+ * quando está na cadeia sem folha abaixo. A folha só assume `fill` implícito quando o
+ * elemento pai o carrega — um contêiner próprio no meio não repassa a altura.
+ */
+export const fillRegionAttribute = "data-fill";
+
+/** Publica a cadeia quando `active`; caso contrário a interrompe. */
+export function FillRoot({
+  active,
+  children,
+}: {
+  active: boolean;
+  children?: ReactNode;
+}): ReactElement {
+  return createElement(
+    FillChainContext.Provider,
+    { value: active ? rootChain : null },
+    children,
+  );
+}
+
+/** Interrompe a cadeia: o conteúdo abaixo decide a própria altura. */
+export function FillBoundary({
+  children,
+}: {
+  children?: ReactNode;
+}): ReactElement {
+  return createElement(FillChainContext.Provider, { value: null }, children);
+}
+
+export interface FillRegion {
+  /** O elo está em uma cadeia `fill`, com ou sem folha abaixo. */
+  inChain: boolean;
+  /** Uma folha se registrou abaixo: o elo deve repassar a altura. */
+  filling: boolean;
+  /** Atributos do elemento do elo. */
+  attributes: { "data-fill"?: "true" | "false" };
+  /** Republica a cadeia para os filhos do elo. */
+  provide(children: ReactNode): ReactElement;
+}
+
+/** Elo da cadeia: lê o contexto, conta as folhas abaixo e o republica. */
+export function useFillRegion(): FillRegion {
+  const parent = useContext(FillChainContext);
+  const [leaves, setLeaves] = useState(0);
+  const chain = useMemo<FillChain | null>(
+    () =>
+      parent === null
+        ? null
+        : {
+            register() {
+              setLeaves((count) => count + 1);
+              const releaseParent = parent.register();
+              let registered = true;
+              return () => {
+                if (!registered) return;
+                registered = false;
+                setLeaves((count) => Math.max(0, count - 1));
+                releaseParent();
+              };
+            },
+          },
+    [parent],
+  );
+  const inChain = parent !== null;
+  const filling = inChain && leaves > 0;
+  return {
+    inChain,
+    filling,
+    attributes: inChain ? { "data-fill": filling ? "true" : "false" } : {},
+    provide: (children) =>
+      createElement(FillChainContext.Provider, { value: chain }, children),
+  };
+}
+
+/**
+ * Folha da cadeia. Sem `layout` explícito, assume `fill` quando o elemento pai é um elo;
+ * com `layout="fill"` explícito, registra-se mesmo sob um contêiner próprio, que passa a
+ * ser responsabilidade de quem o escreveu. `layout="flow"` nunca se registra.
+ */
+export function useFillLeaf<TElement extends HTMLElement>(
+  layout: FillLayout | undefined,
+): { layout: FillLayout; ref: RefObject<TElement | null> } {
+  const chain = useContext(FillChainContext);
+  const ref = useRef<TElement | null>(null);
+  const [linked, setLinked] = useState(false);
+  useLayoutEffect(() => {
+    setLinked(
+      chain !== null &&
+        ref.current?.parentElement?.hasAttribute(fillRegionAttribute) === true,
+    );
+  }, [chain]);
+  const resolved = layout ?? (linked ? "fill" : "flow");
+  useLayoutEffect(() => {
+    if (chain === null || resolved !== "fill") return undefined;
+    return chain.register();
+  }, [chain, resolved]);
+  return { layout: resolved, ref };
+}