@softize/opus 22.2.0 → 24.0.0

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

@@ -0,0 +1,620 @@
+/**
+ * Surface — a fundação pública para delimitar e nomear um trecho da tela: região de
+ * página, grupo de campos, entidade, item ou bloco clicável (ADR 0045).
+ *
+ * A semântica vem do elemento (`as` ou `asChild`), nunca do nome do componente. Três
+ * eixos visuais são independentes:
+ *
+ *   framed     borda, raio e recorte;
+ *   elevation  fundo próprio (`raised`) ou o fundo de quem hospeda (`none`);
+ *   layout     ritmo contínuo ou faixas com divisores derivados.
+ *
+ * Três formas de compor produzem a mesma anatomia:
+ *
+ *   Caixa simples:  <Surface framed className="p-4">…</Surface>
+ *   Forma curta:    <Surface as="section" title="Clientes" count={3}>…</Surface>
+ *   Explícita:      <Surface><SurfaceHeader>…</SurfaceHeader><SurfaceBody>…</SurfaceBody></Surface>
+ *
+ * O recuo das regiões deriva de a superfície ser delimitada (moldura ou elevação); sem
+ * delimitação, ela flui alinhada ao hospedeiro. As medidas vivem em `surface-anatomy.ts`.
+ */
+import {
+  Children,
+  Fragment,
+  createContext,
+  isValidElement,
+  useContext,
+  useId,
+  type ComponentProps,
+  type ElementType,
+  type HTMLAttributes,
+  type ReactElement,
+  type ReactNode,
+} from "react";
+import { Slot } from "@radix-ui/react-slot";
+import { cn } from "../../lib/cn.ts";
+import {
+  FillBoundary,
+  fillRegionClassName,
+  useFillRegion,
+} from "./fill-region.ts";
+import { headingTags, type HeadingLevel } from "./heading-level.ts";
+import { usePageHeadingPresence } from "./page-heading-context.tsx";
+import {
+  StructuralHeader,
+  structuralHeaderClasses,
+} from "./structural-header.tsx";
+import {
+  surfaceDescriptionClasses,
+  surfaceHeaderRowClasses,
+  surfaceLegendClasses,
+  surfaceRegionClasses,
+  surfaceTitleClasses,
+  type SurfaceLayout,
+} from "./surface-anatomy.ts";
+
+export type SurfaceElement = "div" | "section" | "article" | "fieldset";
+export type SurfaceElevation = "none" | "raised";
+
+interface SurfaceContextValue {
+  /** Elemento da raiz; `null` quando `asChild` entrega a superfície ao filho. */
+  element: SurfaceElement | null;
+  /** Tem moldura ou elevação: as regiões carregam o recuo. */
+  bounded: boolean;
+  framed: boolean;
+  layout: SurfaceLayout;
+  level: HeadingLevel;
+  titleId: string;
+  variant: "page" | "section";
+}
+
+const SurfaceContext = createContext<SurfaceContextValue | null>(null);
+const SurfaceHeaderContext = createContext<SurfaceContextValue | null>(null);
+
+function requiredContext<T>(
+  value: T | null,
+  component: string,
+  parent: string,
+): T {
+  if (value === null)
+    throw new Error(`${component} deve estar dentro de ${parent}.`);
+  return value;
+}
+
+/** Como a `legend` de um fieldset delimitado se relaciona com a moldura. */
+function legendPlacement(
+  surface: SurfaceContextValue,
+): "notch" | "band" | null {
+  if (surface.element !== "fieldset" || !surface.bounded) return null;
+  return surface.framed && surface.layout === "continuous" ? "notch" : "band";
+}
+
+interface SurfaceBaseProps {
+  /** Borda, raio e recorte. Não decide fundo nem semântica. */
+  framed?: boolean;
+  /**
+   * `raised` pinta o fundo de superfície elevada e decide a própria altura; `none` mostra
+   * o fundo de quem hospeda.
+   */
+  elevation?: SurfaceElevation;
+  /** Anatomia da superfície inteira: `continuous` (default) ou `sectioned`. */
+  layout?: SurfaceLayout;
+  className?: string;
+  children?: ReactNode;
+}
+
+interface SurfaceHeaderShorthandProps {
+  /** Forma curta: título da superfície. */
+  title: ReactNode;
+  /** Forma curta: conteúdo do slot de mídia, antes do título. */
+  media?: ReactNode;
+  /** Forma curta: total de itens ao lado do título. */
+  count?: number;
+  /** Forma curta: frase de apoio sob o título. */
+  description?: ReactNode;
+  /** Forma curta: ações sobre a superfície inteira, no extremo oposto ao título. */
+  actions?: ReactNode;
+}
+
+interface SurfaceLegendShorthandProps {
+  /** Forma curta: título do grupo de campos, renderizado como `legend`. */
+  title: ReactNode;
+  /** Forma curta: mídia decorativa que acompanha o título na legenda. */
+  media?: ReactNode;
+  count?: never;
+  description?: never;
+  actions?: never;
+}
+
+interface SurfaceNoShorthandProps {
+  title?: never;
+  media?: never;
+  count?: never;
+  description?: never;
+  actions?: never;
+}
+
+type NativeProps<T extends ElementType> = Omit<
+  ComponentProps<T>,
+  "title" | "children" | "className"
+>;
+
+type SurfaceDivProps = SurfaceBaseProps &
+  NativeProps<"div"> & {
+    /** Elemento da superfície. */
+    as?: "div";
+    asChild?: false;
+    /** Nível semântico do título; `1` é o heading principal da página. */
+    level?: HeadingLevel;
+  } & (SurfaceHeaderShorthandProps | SurfaceNoShorthandProps);
+
+type SurfaceSectioningProps = SurfaceBaseProps &
+  NativeProps<"section"> & {
+    /** Região nomeada pelo título (`section`) ou conteúdo autossuficiente (`article`). */
+    as: "section" | "article";
+    asChild?: false;
+    level?: HeadingLevel;
+  } & (SurfaceHeaderShorthandProps | SurfaceNoShorthandProps);
+
+type SurfaceFieldsetProps = SurfaceBaseProps &
+  NativeProps<"fieldset"> & {
+    /** Grupo de campos; o header vira a `legend` nativa. */
+    as: "fieldset";
+    asChild?: false;
+    level?: never;
+  } & (SurfaceLegendShorthandProps | SurfaceNoShorthandProps);
+
+type SurfaceAsChildProps = SurfaceBaseProps &
+  NativeProps<"div"> & {
+    as?: never;
+    /** Entrega a superfície ao único filho, como um `button` ou um link. */
+    asChild: true;
+    level?: HeadingLevel;
+  } & SurfaceNoShorthandProps;
+
+export type SurfaceProps =
+  | SurfaceDivProps
+  | SurfaceSectioningProps
+  | SurfaceFieldsetProps
+  | SurfaceAsChildProps;
+
+/** Expande fragments: a composição pode agrupar regiões em um `<>`. */
+function flatten(children: ReactNode): ReactNode[] {
+  return Children.toArray(children).flatMap((node) =>
+    isValidElement(node) && node.type === Fragment
+      ? flatten((node.props as { children?: ReactNode }).children)
+      : [node],
+  );
+}
+
+/** `null`, `false` e `undefined` não abrem o slot: uma mídia vazia não identifica nada. */
+function hasMedia(media: ReactNode): boolean {
+  return media !== undefined && media !== null && media !== false;
+}
+
+export function Surface({
+  as,
+  asChild = false,
+  framed = false,
+  elevation = "none",
+  layout = "continuous",
+  level = 2,
+  title,
+  media,
+  count,
+  description,
+  actions,
+  className,
+  children,
+  ...props
+}: SurfaceProps): ReactElement {
+  const titleId = useId();
+  const fill = useFillRegion();
+
+  if (asChild && as !== undefined) {
+    throw new Error("Surface não combina as com asChild: escolha um dos dois.");
+  }
+  const element: SurfaceElement | null = asChild ? null : (as ?? "div");
+  const raised = elevation === "raised";
+  const bounded = framed || raised;
+  if (layout === "sectioned" && !bounded) {
+    throw new Error(
+      'Surface layout="sectioned" exige framed ou elevation="raised".',
+    );
+  }
+
+  const shorthand = title !== undefined;
+  if (
+    !shorthand &&
+    (hasMedia(media) ||
+      count !== undefined ||
+      description !== undefined ||
+      actions !== undefined)
+  ) {
+    throw new Error(
+      "Surface exige title para usar media, count, description ou actions.",
+    );
+  }
+  if (asChild && shorthand) {
+    throw new Error(
+      "Surface asChild não aceita a forma curta: componha os slots dentro do filho.",
+    );
+  }
+  if (asChild && !isValidElement(children)) {
+    throw new Error("Surface asChild exige exatamente um elemento filho.");
+  }
+
+  // Com `asChild`, a anatomia é a dos filhos do elemento que recebe a superfície.
+  const nodes = flatten(
+    asChild
+      ? (children as ReactElement<{ children?: ReactNode }>).props.children
+      : children,
+  );
+  const of = (type: ElementType) =>
+    nodes.filter((node) => isValidElement(node) && node.type === type);
+  const headers = of(SurfaceHeader);
+  const bodies = of(SurfaceBody);
+  const footers = of(SurfaceFooter);
+  const regions = headers.length + bodies.length + footers.length;
+
+  if (regions > 0 && regions !== nodes.length) {
+    throw new Error(
+      "Surface não mistura slots estruturais com filhos livres: envolva o conteúdo em SurfaceBody.",
+    );
+  }
+  if (headers.length > 1 || bodies.length > 1 || footers.length > 1) {
+    throw new Error(
+      "Surface aceita no máximo um SurfaceHeader, um SurfaceBody e um SurfaceFooter como filhos diretos.",
+    );
+  }
+  if (shorthand && headers.length > 0) {
+    throw new Error(
+      "Surface não permite misturar a forma curta com SurfaceHeader explícito.",
+    );
+  }
+
+  const explicitTitle =
+    headers.length === 1 && isValidElement(headers[0])
+      ? flatten(
+          (headers[0] as ReactElement<{ children?: ReactNode }>).props.children,
+        ).find((node) => isValidElement(node) && node.type === SurfaceTitle)
+      : undefined;
+  const resolvedTitleId =
+    (isValidElement(explicitTitle)
+      ? (explicitTitle.props as { id?: string }).id
+      : undefined) ?? titleId;
+
+  // Caixa simples: sem título e sem slots, os filhos são livres e a raiz não impõe ritmo.
+  const structured = shorthand || regions > 0;
+  const variant = level === 1 && element !== "fieldset" ? "page" : "section";
+  const context: SurfaceContextValue = {
+    element,
+    bounded,
+    framed,
+    layout,
+    level,
+    titleId: resolvedTitleId,
+    variant,
+  };
+
+  const anatomy = shorthand ? (
+    <>
+      <SurfaceHeader>
+        {hasMedia(media) && <SurfaceMedia>{media}</SurfaceMedia>}
+        <SurfaceTitle>{title}</SurfaceTitle>
+        {count !== undefined && <SurfaceMeta>{count}</SurfaceMeta>}
+        {description !== undefined && (
+          <SurfaceDescription>{description}</SurfaceDescription>
+        )}
+        {actions !== undefined && <SurfaceActions>{actions}</SurfaceActions>}
+      </SurfaceHeader>
+      {regions > 0
+        ? children
+        : nodes.length > 0 && <SurfaceBody>{children}</SurfaceBody>}
+    </>
+  ) : (
+    children
+  );
+
+  // Uma superfície elevada decide a própria altura; a caixa simples não é um elo. As
+  // demais repassam a altura de `Page layout="fill"` até a lista (ADR 0024).
+  const link = structured && !raised;
+  const named =
+    (element === "section" ||
+      element === "article" ||
+      element === "fieldset") &&
+    (shorthand || explicitTitle !== undefined) &&
+    props["aria-label"] === undefined;
+
+  const Root: ElementType = element ?? Slot;
+  const root = (
+    <Root
+      data-slot="surface"
+      data-as={element ?? undefined}
+      data-framed={framed}
+      data-elevation={elevation}
+      data-layout={layout}
+      {...(link ? fill.attributes : {})}
+      aria-labelledby={named ? resolvedTitleId : undefined}
+      className={cn(
+        framed && "rounded-xl border border-border",
+        // O divisor e o conteúdo sem recuo encostam na borda: o raio precisa recortar.
+        framed && layout === "sectioned" && "overflow-hidden",
+        framed && "has-[>[data-flush=true]]:overflow-hidden",
+        raised &&
+          "bg-card text-card-foreground [--surface-background:var(--card)]",
+        structured &&
+          !bounded &&
+          (variant === "page" ? "space-y-6" : "space-y-3"),
+        link && fill.filling && fillRegionClassName,
+        className,
+      )}
+      {...props}
+    >
+      {anatomy}
+    </Root>
+  );
+
+  return (
+    <SurfaceContext.Provider value={context}>
+      {raised ? (
+        <FillBoundary>{root}</FillBoundary>
+      ) : link ? (
+        fill.provide(root)
+      ) : (
+        root
+      )}
+    </SurfaceContext.Provider>
+  );
+}
+
+export type SurfaceHeaderProps = Omit<HTMLAttributes<HTMLDivElement>, "title">;
+
+const legendInvalidMessage =
+  "SurfaceHeader de fieldset aceita somente SurfaceMedia e SurfaceTitle; contador, descrição e ações ficam fora da legenda.";
+
+/**
+ * Header da superfície; não existe fora dela. Monta a linha sozinho — mídia, título com
+ * contador e descrição de um lado, ações no extremo oposto —, qualquer que seja a ordem
+ * em que os slots são escritos. Em `fieldset`, é a `legend` nativa.
+ */
+export function SurfaceHeader({
+  className,
+  children,
+  ...props
+}: SurfaceHeaderProps): ReactElement {
+  const surface = requiredContext(
+    useContext(SurfaceContext),
+    "SurfaceHeader",
+    "Surface",
+  );
+  const legend = surface.element === "fieldset";
+  const placement = legendPlacement(surface);
+  return (
+    <SurfaceHeaderContext.Provider value={surface}>
+      <StructuralHeader
+        as={legend ? "legend" : "div"}
+        name="SurfaceHeader"
+        slot="surface"
+        slots={
+          legend
+            ? { media: SurfaceMedia, title: SurfaceTitle }
+            : {
+                media: SurfaceMedia,
+                title: SurfaceTitle,
+                count: SurfaceMeta,
+                description: SurfaceDescription,
+                actions: SurfaceActions,
+              }
+        }
+        leadingPlacement="inline"
+        titleRequired={legend}
+        rowClassName={surfaceHeaderRowClasses("surface")}
+        {...(legend ? { invalidMessage: legendInvalidMessage } : {})}
+        className={cn(
+          surface.bounded &&
+            placement !== "notch" &&
+            surfaceRegionClasses("surface", surface.layout, "header"),
+          placement !== null && surfaceLegendClasses[placement],
+          className,
+        )}
+        {...props}
+      >
+        {children}
+      </StructuralHeader>
+    </SurfaceHeaderContext.Provider>
+  );
+}
+
+export type SurfaceMediaProps = HTMLAttributes<HTMLElement>;
+
+/**
+ * Slot de mídia: reserva a posição que abre a linha do header e centraliza o conteúdo.
+ * Não desenha moldura: componha `IconTile` para um ícone emoldurado e passe `Avatar`,
+ * `img` ou um glifo diretamente.
+ */
+export function SurfaceMedia({
+  className,
+  ...props
+}: SurfaceMediaProps): ReactElement {
+  const surface = requiredContext(
+    useContext(SurfaceHeaderContext),
+    "SurfaceMedia",
+    "SurfaceHeader",
+  );
+  const legend = surface.element === "fieldset";
+  // Dentro de `legend` só cabe conteúdo de frase; fora dela, o slot hospeda blocos.
+  const Media = legend ? "span" : "div";
+  return (
+    <Media
+      data-slot="surface-media"
+      className={cn(
+        "flex shrink-0 items-center justify-center [&>svg:not([class*='size-'])]:size-4",
+        className,
+      )}
+      {...props}
+      // Na legenda, a mídia é sempre decorativa: o grupo é anunciado só pelo título.
+      aria-hidden={legend ? true : props["aria-hidden"]}
+    />
+  );
+}
+
+export function SurfaceTitle({
+  className,
+  id,
+  ...props
+}: HTMLAttributes<HTMLElement>): ReactElement {
+  const surface = requiredContext(
+    useContext(SurfaceHeaderContext),
+    "SurfaceTitle",
+    "SurfaceHeader",
+  );
+  const legend = surface.element === "fieldset";
+  const Heading = legend ? "span" : headingTags[surface.level];
+  usePageHeadingPresence(!legend && surface.level === 1);
+  return (
+    <Heading
+      id={id ?? surface.titleId}
+      data-slot="surface-title"
+      className={cn(
+        surface.variant === "page"
+          ? structuralHeaderClasses.page.title
+          : surfaceTitleClasses("surface", surface.layout),
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+export function SurfaceDescription({
+  className,
+  ...props
+}: HTMLAttributes<HTMLParagraphElement>): ReactElement {
+  const surface = requiredContext(
+    useContext(SurfaceHeaderContext),
+    "SurfaceDescription",
+    "SurfaceHeader",
+  );
+  return (
+    <p
+      data-slot="surface-description"
+      className={cn(
+        surface.variant === "page"
+          ? structuralHeaderClasses.page.description
+          : surfaceDescriptionClasses("surface"),
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+/** Metadado ao lado do título — o slot do `count` da forma curta. */
+export function SurfaceMeta({
+  className,
+  ...props
+}: HTMLAttributes<HTMLSpanElement>): ReactElement {
+  const surface = requiredContext(
+    useContext(SurfaceHeaderContext),
+    "SurfaceMeta",
+    "SurfaceHeader",
+  );
+  return (
+    <span
+      data-slot="surface-meta"
+      className={cn(structuralHeaderClasses[surface.variant].count, className)}
+      {...props}
+    />
+  );
+}
+
+/** Ações do header — a família as posiciona no extremo oposto ao título. */
+export function SurfaceActions({
+  className,
+  ...props
+}: HTMLAttributes<HTMLDivElement>): ReactElement {
+  const surface = requiredContext(
+    useContext(SurfaceHeaderContext),
+    "SurfaceActions",
+    "SurfaceHeader",
+  );
+  return (
+    <div
+      data-slot="surface-actions"
+      className={cn(
+        structuralHeaderClasses[surface.variant].actions,
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+export interface SurfaceBodyProps extends HTMLAttributes<HTMLDivElement> {
+  /**
+   * Entrega a largura inteira ao filho que já controla o próprio recuo, como
+   * `DetailGroup` com divisores, lista ou tabela.
+   */
+  flush?: boolean;
+}
+
+export function SurfaceBody({
+  flush = false,
+  className,
+  children,
+  ...props
+}: SurfaceBodyProps): ReactElement {
+  const surface = requiredContext(
+    useContext(SurfaceContext),
+    "SurfaceBody",
+    "Surface",
+  );
+  const fill = useFillRegion();
+  const placement = legendPlacement(surface);
+  return (
+    <div
+      data-slot="surface-body"
+      data-flush={flush ? "true" : undefined}
+      {...fill.attributes}
+      className={cn(
+        surfaceRegionClasses("surface", surface.layout, "body", {
+          flush: !surface.bounded || flush,
+        }),
+        placement === "notch" && surfaceLegendClasses.afterNotch,
+        placement === "band" && surfaceLegendClasses.afterBand,
+        fill.filling && fillRegionClassName,
+        className,
+      )}
+      {...props}
+    >
+      {fill.provide(children)}
+    </div>
+  );
+}
+
+/** Rodapé de ações persistentes; vale para regiões e para entidades. */
+export function SurfaceFooter({
+  className,
+  ...props
+}: HTMLAttributes<HTMLDivElement>): ReactElement {
+  const surface = requiredContext(
+    useContext(SurfaceContext),
+    "SurfaceFooter",
+    "Surface",
+  );
+  const placement = legendPlacement(surface);
+  return (
+    <div
+      data-slot="surface-footer"
+      className={cn(
+        "flex items-center justify-end gap-2",
+        surface.bounded &&
+          surfaceRegionClasses("surface", surface.layout, "footer"),
+        placement === "band" && surfaceLegendClasses.afterBand,
+        className,
+      )}
+      {...props}
+    />
+  );
+}

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

@@ -230,15 +230,17 @@ export function ActionTrigger<TInput, TData>({
               id={confirmBodyId}
               className="text-sm text-muted-foreground"
             >
-              {itemLabel !== undefined && (
-                <span className="font-medium text-foreground">
-                  “{itemLabel}”
-                </span>
-              )}
-              {itemLabel !== undefined && confirm.body !== undefined
-                ? " — "
-                : ""}
-              {confirm.body}
+              <div>
+                {itemLabel !== undefined && (
+                  <span className="font-medium text-foreground">
+                    “{itemLabel}”
+                  </span>
+                )}
+                {itemLabel !== undefined && confirm.body !== undefined
+                  ? " — "
+                  : ""}
+                {confirm.body}
+              </div>
             </DialogBody>
           )}
           <DialogFooter>