@softize/opus 13.1.0 → 15.0.0

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

@@ -9,16 +9,38 @@ import {
   Children,
   createContext,
   isValidElement,
+  useCallback,
   useContext,
+  useRef,
+  useState,
   type HTMLAttributes,
+  type ComponentProps,
   type ReactElement,
   type ReactNode,
 } from "react";
 import { createPortal } from "react-dom";
+import { ArrowLeft } from "lucide-react";
 import { cn } from "../../lib/cn.ts";
+import { Button } from "../primitives/button.tsx";
+import {
+  Tooltip,
+  TooltipContent,
+  TooltipProvider,
+  TooltipTrigger,
+} from "../primitives/tooltip.tsx";
+import { SurfaceHeader, surfaceHeaderClasses } from "./surface-header.tsx";
+import { PageStatePresenceProvider } from "./page-state.tsx";
+
+export type PageHeaderVariant = "default" | "bar";
 
-const PageContext = createContext(false);
-const PageHeaderContext = createContext(false);
+interface PageContextValue {
+  headerVariant: PageHeaderVariant;
+  containerClassName?: string;
+}
+
+const PageContext = createContext<PageContextValue | null>(null);
+const PageHeaderContext = createContext<PageHeaderVariant | null>(null);
+const PageIntegralStateContext = createContext(false);
 const PageActionsTargetContext = createContext<HTMLElement | null>(null);
 
 export function PageActionsTarget({
@@ -53,8 +75,6 @@ interface PageBaseProps extends Omit<
 
 interface PageShorthandProps extends PageBaseProps {
   title: ReactNode;
-  /** Total de itens ao lado do título. */
-  count?: number;
   description?: ReactNode;
   actions?: ReactNode;
   children: ReactNode;
@@ -62,7 +82,6 @@ interface PageShorthandProps extends PageBaseProps {
 
 interface PageComposedProps extends PageBaseProps {
   title?: never;
-  count?: never;
   description?: never;
   actions?: never;
   children: ReactNode;
@@ -72,7 +91,6 @@ export type PageProps = PageShorthandProps | PageComposedProps;
 
 export function Page({
   title,
-  count,
   description,
   actions,
   className,
@@ -81,6 +99,25 @@ export function Page({
 }: PageProps): ReactElement {
   const shorthand = title !== undefined;
   const nodes = Children.toArray(children);
+  const headers = nodes.filter(
+    (node) => isValidElement(node) && node.type === PageHeader,
+  );
+  const bodies = nodes.filter(
+    (node) => isValidElement(node) && node.type === PageBody,
+  );
+  const activeStateCount = useRef(0);
+  const [integralState, setIntegralState] = useState(false);
+  const registerIntegralState = useCallback(() => {
+    activeStateCount.current += 1;
+    setIntegralState(true);
+    let registered = true;
+    return () => {
+      if (!registered) return;
+      registered = false;
+      activeStateCount.current = Math.max(0, activeStateCount.current - 1);
+      setIntegralState(activeStateCount.current > 0);
+    };
+  }, []);
   if (
     shorthand &&
     nodes.some((node) => isValidElement(node) && node.type === PageHeader)
@@ -90,12 +127,6 @@ export function Page({
     );
   }
   if (!shorthand) {
-    const headers = nodes.filter(
-      (node) => isValidElement(node) && node.type === PageHeader,
-    );
-    const bodies = nodes.filter(
-      (node) => isValidElement(node) && node.type === PageBody,
-    );
     if (
       headers.length !== 1 ||
       bodies.length !== 1 ||
@@ -106,86 +137,106 @@ export function Page({
       );
     }
   }
+  const headerVariant: PageHeaderVariant = shorthand
+    ? "default"
+    : ((headers[0] as ReactElement<PageHeaderProps> | undefined)?.props
+        .variant ?? "default");
+  const pageContext: PageContextValue = {
+    headerVariant,
+    containerClassName: className,
+  };
+
+  const content = shorthand ? (
+    <>
+      <PageHeader>
+        <PageTitle>{title}</PageTitle>
+        {description !== undefined && (
+          <PageDescription>{description}</PageDescription>
+        )}
+        {actions !== undefined && <PageActions>{actions}</PageActions>}
+      </PageHeader>
+      <PageBody>{children}</PageBody>
+    </>
+  ) : (
+    children
+  );
 
   return (
-    <PageContext.Provider value>
-      <main data-slot="page" className="min-w-0 flex-1" {...props}>
-        <div className={cn("mx-auto max-w-7xl px-8 py-8", className)}>
-          {shorthand ? (
-            <>
-              <PageHeader>
-                <PageTitle>{title}</PageTitle>
-                {count !== undefined && <PageMeta>{count}</PageMeta>}
-                {description !== undefined && (
-                  <PageDescription>{description}</PageDescription>
+    <PageContext.Provider value={pageContext}>
+      <PageIntegralStateContext.Provider value={integralState}>
+        <PageStatePresenceProvider register={registerIntegralState}>
+          <main
+            data-slot="page"
+            className={cn(
+              "min-w-0 flex-1",
+              headerVariant === "bar" && "flex min-h-0 flex-col",
+              integralState && "flex min-h-full flex-col",
+            )}
+            {...props}
+          >
+            {headerVariant === "bar" ? (
+              content
+            ) : (
+              <div
+                className={cn(
+                  "mx-auto max-w-7xl space-y-6 px-8 py-8",
+                  integralState &&
+                    "flex min-h-full w-full flex-1 flex-col space-y-0",
+                  className,
                 )}
-                {actions !== undefined && <PageActions>{actions}</PageActions>}
-              </PageHeader>
-              <PageBody>{children}</PageBody>
-            </>
-          ) : (
-            children
-          )}
-        </div>
-      </main>
+              >
+                {content}
+              </div>
+            )}
+          </main>
+        </PageStatePresenceProvider>
+      </PageIntegralStateContext.Provider>
     </PageContext.Provider>
   );
 }
 
+/** A anatomia é a de `SurfaceHeader`, a mesma de `ContentHeader`; só os slots mudam de nome. */
+export interface PageHeaderProps extends HTMLAttributes<HTMLDivElement> {
+  /** `default` fica no container; `bar` cria uma faixa compacta no topo da Page. */
+  variant?: PageHeaderVariant;
+}
+
 export function PageHeader({
+  variant = "default",
   className,
   children,
   ...props
-}: HTMLAttributes<HTMLDivElement>): ReactElement {
-  requireParent(useContext(PageContext), "PageHeader", "Page");
-  const nodes = Children.toArray(children);
-  const titles = nodes.filter(
-    (node) => isValidElement(node) && node.type === PageTitle,
-  );
-  const metas = nodes.filter(
-    (node) => isValidElement(node) && node.type === PageMeta,
-  );
-  const descriptions = nodes.filter(
-    (node) => isValidElement(node) && node.type === PageDescription,
-  );
-  const actionSlots = nodes.filter(
-    (node) => isValidElement(node) && node.type === PageActions,
-  );
-  const recognized =
-    titles.length + metas.length + descriptions.length + actionSlots.length;
-  if (
-    titles.length !== 1 ||
-    metas.length > 1 ||
-    descriptions.length > 1 ||
-    actionSlots.length > 1 ||
-    recognized !== nodes.length
-  ) {
-    throw new Error(
-      "PageHeader exige um PageTitle e aceita no máximo um PageDescription, PageMeta e PageActions como filhos diretos.",
-    );
-  }
-
+}: PageHeaderProps): ReactElement {
+  const page = useContext(PageContext);
+  const integralState = useContext(PageIntegralStateContext);
+  requireParent(page !== null, "PageHeader", "Page");
+  if (integralState) return <></>;
   return (
-    <PageHeaderContext.Provider value>
-      <div
-        data-slot="page-header"
+    <PageHeaderContext.Provider value={variant}>
+      <SurfaceHeader
+        name="PageHeader"
+        slot="page"
+        slots={{
+          leading: [PageBack, PageNavigation],
+          title: PageTitle,
+          description: PageDescription,
+          actions: PageActions,
+        }}
+        leadingPlacement={variant === "bar" ? "inline" : "above"}
+        contentClassName={
+          variant === "bar"
+            ? cn("mx-auto w-full max-w-7xl px-8 py-2", page?.containerClassName)
+            : undefined
+        }
         className={cn(
-          "mb-6",
-          actionSlots.length > 0 &&
-            "flex flex-col items-start gap-4 sm:flex-row sm:items-end sm:justify-between",
+          variant === "bar" &&
+            "shrink-0 border-b border-border bg-background text-foreground",
           className,
         )}
         {...props}
       >
-        <div data-slot="page-heading" className="min-w-0">
-          <div className="flex items-baseline gap-2">
-            {titles}
-            {metas}
-          </div>
-          {descriptions}
-        </div>
-        {actionSlots}
-      </div>
+        {children}
+      </SurfaceHeader>
     </PageHeaderContext.Provider>
   );
 }
@@ -194,11 +245,17 @@ export function PageTitle({
   className,
   ...props
 }: HTMLAttributes<HTMLHeadingElement>): ReactElement {
-  requireParent(useContext(PageHeaderContext), "PageTitle", "PageHeader");
+  const variant = useContext(PageHeaderContext);
+  requireParent(variant !== null, "PageTitle", "PageHeader");
   return (
     <h1
       data-slot="page-title"
-      className={cn("text-2xl font-semibold tracking-tight", className)}
+      className={cn(
+        variant === "bar"
+          ? "truncate text-sm font-semibold"
+          : surfaceHeaderClasses.page.title,
+        className,
+      )}
       {...props}
     />
   );
@@ -208,25 +265,17 @@ export function PageDescription({
   className,
   ...props
 }: HTMLAttributes<HTMLParagraphElement>): ReactElement {
-  requireParent(useContext(PageHeaderContext), "PageDescription", "PageHeader");
+  const variant = useContext(PageHeaderContext);
+  requireParent(variant !== null, "PageDescription", "PageHeader");
   return (
     <p
       data-slot="page-description"
-      className={cn("mt-1 truncate text-sm text-muted-foreground", className)}
-      {...props}
-    />
-  );
-}
-
-export function PageMeta({
-  className,
-  ...props
-}: HTMLAttributes<HTMLSpanElement>): ReactElement {
-  requireParent(useContext(PageHeaderContext), "PageMeta", "PageHeader");
-  return (
-    <span
-      data-slot="page-meta"
-      className={cn("font-mono text-base text-muted-foreground/60", className)}
+      className={cn(
+        variant === "bar"
+          ? "mt-0.5 truncate text-xs text-muted-foreground"
+          : surfaceHeaderClasses.page.description,
+        className,
+      )}
       {...props}
     />
   );
@@ -236,13 +285,16 @@ export function PageActions({
   className,
   ...props
 }: HTMLAttributes<HTMLDivElement>): ReactElement {
-  requireParent(useContext(PageHeaderContext), "PageActions", "PageHeader");
+  const variant = useContext(PageHeaderContext);
+  requireParent(variant !== null, "PageActions", "PageHeader");
   const target = useContext(PageActionsTargetContext);
   const actions = (
     <div
       data-slot="page-actions"
       className={cn(
-        "flex w-full shrink-0 items-center gap-4 sm:w-auto",
+        variant === "bar"
+          ? "flex shrink-0 items-center gap-2"
+          : surfaceHeaderClasses.page.actions,
         className,
       )}
       {...props}
@@ -251,10 +303,89 @@ export function PageActions({
   return target === null ? actions : createPortal(actions, target);
 }
 
+export interface PageBackProps extends Omit<ComponentProps<"a">, "children" | "href"> {
+  /** Nome do destino pai. Na barra, também alimenta tooltip e nome acessível. */
+  children: ReactNode;
+  /** Destino explícito. Obrigatório: sem `href` o elemento não é tabulável, não expõe
+   *  `role="link"` e o navegador descarta o nome acessível — na barra, onde não há texto
+   *  visível, o retorno simplesmente desapareceria para tecnologia assistiva. */
+  href: string;
+}
+
+/** Região introdutória para uma trilha estrutural com mais de um ancestral relevante. */
+export function PageNavigation({
+  className,
+  ...props
+}: HTMLAttributes<HTMLDivElement>): ReactElement {
+  requireParent(
+    useContext(PageHeaderContext) !== null,
+    "PageNavigation",
+    "PageHeader",
+  );
+  return (
+    <div
+      data-slot="page-navigation-content"
+      className={cn("min-w-0", className)}
+      {...props}
+    />
+  );
+}
+
+export function PageBack({
+  children,
+  className,
+  "aria-label": ariaLabel,
+  ...props
+}: PageBackProps): ReactElement {
+  const variant = useContext(PageHeaderContext);
+  requireParent(variant !== null, "PageBack", "PageHeader");
+  const destination =
+    typeof children === "string" ? children : "a página anterior";
+  const accessibleLabel = ariaLabel ?? `Voltar para ${destination}`;
+  const link = (
+    <Button asChild variant="ghost" size={variant === "bar" ? "icon-sm" : "sm"}>
+      <a
+        data-slot="page-back"
+        aria-label={accessibleLabel}
+        className={className}
+        {...props}
+      >
+        <ArrowLeft aria-hidden="true" />
+        {variant === "default" && <span>{children}</span>}
+      </a>
+    </Button>
+  );
+
+  return variant === "bar" ? (
+    <TooltipProvider delayDuration={200}>
+      <Tooltip>
+        <TooltipTrigger asChild>{link}</TooltipTrigger>
+        <TooltipContent>{accessibleLabel}</TooltipContent>
+      </Tooltip>
+    </TooltipProvider>
+  ) : (
+    link
+  );
+}
+
 export function PageBody({
   className,
   ...props
 }: HTMLAttributes<HTMLDivElement>): ReactElement {
-  requireParent(useContext(PageContext), "PageBody", "Page");
-  return <div data-slot="page-body" className={className} {...props} />;
+  const page = useContext(PageContext);
+  const integralState = useContext(PageIntegralStateContext);
+  requireParent(page !== null, "PageBody", "Page");
+  return (
+    <div
+      data-slot="page-body"
+      className={cn(
+        page?.headerVariant === "bar" &&
+          "mx-auto w-full max-w-7xl flex-1 px-8 py-8",
+        page?.headerVariant === "bar" && page.containerClassName,
+        integralState && "flex min-h-0 flex-1 flex-col",
+        className,
+      )}
+      {...props}
+    />
+  );
 }

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

@@ -0,0 +1,262 @@
+/**
+ * Superfícies de estado compartilhadas por DataState, PageState e ActionView (interno).
+ *
+ * Uma composição só para cada estado: carregar é um contêiner `role="status"` com o Spinner
+ * (decorativo — o status é um só); erro preserva `role="alert"` e escolhe entre aviso inline e
+ * estado central; vazio compõe `Empty*`. Os patterns públicos escolhem o enquadramento (bloco,
+ * linha de tabela, página inteira) e os textos. Não exportado no barrel: é anatomia, não API.
+ */
+
+import type { ReactElement, ReactNode } from 'react'
+import { RefreshCw, TriangleAlert } from 'lucide-react'
+import { cn } from '../../lib/cn.ts'
+import { Alert } from '../primitives/alert.tsx'
+import { Button } from '../primitives/button.tsx'
+import {
+  Empty,
+  EmptyActions,
+  EmptyDescription,
+  EmptyHeader,
+  EmptyMedia,
+  EmptyTitle,
+} from '../primitives/empty.tsx'
+import { Spinner } from '../primitives/spinner.tsx'
+import {
+  Tooltip,
+  TooltipContent,
+  TooltipProvider,
+  TooltipTrigger,
+} from '../primitives/tooltip.tsx'
+
+export const DEFAULT_EMPTY_MESSAGE = 'Nada por aqui.'
+export const DEFAULT_ERROR_MESSAGE = 'Não foi possível carregar.'
+export const DEFAULT_RETRY_LABEL = 'Tentar de novo'
+
+export interface LoadingSurfaceProps {
+  /** Texto visível ao lado do Spinner; sem ele, só o contêiner nomeia a espera. */
+  title?: ReactNode
+  description?: ReactNode
+  /** Nível semântico do título quando a superfície representa uma região nomeada. */
+  titleLevel?: 1 | 2 | 3 | 4 | 5 | 6
+  className?: string
+}
+
+/** O contêiner é o único `role="status"`; o Spinner dentro dele é decorativo. */
+export function LoadingSurface({
+  title,
+  description,
+  titleLevel,
+  className,
+}: LoadingSurfaceProps): ReactElement {
+  return (
+    <div
+      role="status"
+      aria-live="polite"
+      aria-label={title === undefined ? 'Carregando' : undefined}
+      className={cn(
+        'flex flex-col items-center justify-center gap-3 text-center text-muted-foreground',
+        className,
+      )}
+    >
+      <Spinner />
+      {(title !== undefined || description !== undefined) && (
+        <div className="max-w-md space-y-1">
+          {title !== undefined && (
+            <p
+              data-slot="state-title"
+              role={titleLevel === undefined ? undefined : 'heading'}
+              aria-level={titleLevel}
+              className="text-sm font-medium text-foreground"
+            >
+              {title}
+            </p>
+          )}
+          {description !== undefined && (
+            <p
+              data-slot="state-description"
+              className="text-sm text-muted-foreground"
+            >
+              {description}
+            </p>
+          )}
+        </div>
+      )}
+    </div>
+  )
+}
+
+export interface ErrorSurfaceProps {
+  /** A frase segura para a pessoa; o texto técnico fica no console e no `cause`. */
+  title: ReactNode
+  description?: ReactNode
+  icon?: ReactNode
+  /** Recuperação: com `onRetry`, uma ação somente com ícone entra nas ações do Alert. */
+  onRetry?: () => Promise<void> | void
+  retryLabel?: string
+  /** Outras ações do estado, ao lado do botão de recuperação. */
+  children?: ReactNode
+  /** `alert` preserva o aviso inline; `state` usa a composição central dos estados integrais. */
+  presentation?: 'alert' | 'state'
+  /** Nível semântico do título na apresentação de estado. */
+  titleLevel?: 1 | 2 | 3 | 4 | 5 | 6
+  className?: string
+}
+
+export function ErrorSurface({
+  title,
+  description,
+  icon,
+  onRetry,
+  retryLabel = DEFAULT_RETRY_LABEL,
+  children,
+  presentation = 'alert',
+  titleLevel,
+  className,
+}: ErrorSurfaceProps): ReactElement {
+  if (presentation === 'alert') {
+    return (
+      <Alert
+        context="danger"
+        icon={icon ?? <TriangleAlert />}
+        title={title}
+        description={description}
+        className={className}
+      >
+        {onRetry !== undefined && (
+          <TooltipProvider delayDuration={200}>
+            <Tooltip>
+              <TooltipTrigger asChild>
+                <Button
+                  context="neutral"
+                  variant="ghost"
+                  size="icon"
+                  aria-label={retryLabel}
+                  onClick={() => void onRetry()}
+                >
+                  <RefreshCw />
+                </Button>
+              </TooltipTrigger>
+              <TooltipContent>{retryLabel}</TooltipContent>
+            </Tooltip>
+          </TooltipProvider>
+        )}
+        {children}
+      </Alert>
+    )
+  }
+
+  return (
+    <div
+      data-slot="error-state"
+      role="alert"
+      className={cn(
+        'flex min-w-0 flex-col items-center justify-center gap-6 text-center text-balance',
+        className,
+      )}
+    >
+      <div
+        data-slot="state-header"
+        className="flex max-w-sm flex-col items-center gap-2 text-center"
+      >
+        <div
+          data-slot="state-icon"
+          aria-hidden="true"
+          className="mb-2 flex size-10 shrink-0 items-center justify-center rounded-lg bg-muted text-context-danger-emphasis [&_svg]:size-6 [&_svg]:shrink-0"
+        >
+          {icon ?? <TriangleAlert />}
+        </div>
+        <div
+          data-slot="state-title"
+          role={titleLevel === undefined ? undefined : 'heading'}
+          aria-level={titleLevel}
+          className="text-lg font-medium tracking-tight"
+        >
+          {title}
+        </div>
+        {description !== undefined && (
+          <div
+            data-slot="state-description"
+            className="text-sm/relaxed text-muted-foreground"
+          >
+            {description}
+          </div>
+        )}
+      </div>
+      {(onRetry !== undefined ||
+        (children !== undefined && children !== null)) && (
+        <div
+          data-slot="state-actions"
+          className="flex w-full max-w-sm items-center justify-center gap-2 text-sm"
+        >
+          {onRetry !== undefined && (
+            <Button
+              context="neutral"
+              variant="outline"
+              onClick={() => void onRetry()}
+            >
+              {retryLabel}
+            </Button>
+          )}
+          {children}
+        </div>
+      )}
+    </div>
+  )
+}
+
+export interface EmptySurfaceProps {
+  /** Situação reconhecível: a frase curta do vazio. */
+  title: ReactNode
+  description?: ReactNode
+  icon?: ReactNode
+  action?: ReactNode
+  /**
+   * `region`: a moldura tracejada de Empty (área disponível para criar ou vincular).
+   * `structural`: a moldura sólida de uma coleção sem registros; `bare`: sem moldura, quando a
+   * estrutura ao redor (tabela) já a fornece.
+   */
+  frame?: 'region' | 'structural' | 'bare'
+  /** Título como frase discreta (seção) em vez do título grande (página). */
+  compact?: boolean
+  /** Nível semântico do título quando a superfície representa uma região nomeada. */
+  titleLevel?: 1 | 2 | 3 | 4 | 5 | 6
+  className?: string
+}
+
+export function EmptySurface({
+  title,
+  description,
+  icon,
+  action,
+  frame = 'region',
+  compact = false,
+  titleLevel,
+  className,
+}: EmptySurfaceProps): ReactElement {
+  return (
+    <Empty
+      data-frame={frame}
+      className={cn(
+        frame === 'structural' && 'border-solid',
+        frame === 'bare' && 'border-0 p-0 md:p-0',
+        compact && 'gap-4 p-6 md:p-6',
+        className,
+      )}
+    >
+      <EmptyHeader>
+        {icon !== undefined && <EmptyMedia variant="icon">{icon}</EmptyMedia>}
+        <EmptyTitle
+          role={titleLevel === undefined ? undefined : 'heading'}
+          aria-level={titleLevel}
+          className={cn(compact && 'text-sm font-normal text-muted-foreground')}
+        >
+          {title}
+        </EmptyTitle>
+        {description !== undefined && (
+          <EmptyDescription>{description}</EmptyDescription>
+        )}
+      </EmptyHeader>
+      {action !== undefined && <EmptyActions>{action}</EmptyActions>}
+    </Empty>
+  )
+}