@softize/opus 13.1.0 → 14.0.0

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

@@ -3,22 +3,18 @@
  *
  * Page continua responsável somente pelo esqueleto. Na forma curta, PageState pode ser escrito
  * como filho direto porque Page cria PageBody; na composição explícita, ele fica dentro de
- * PageBody. Estados de uma seção ou coleção continuam em DataState, ActionView e ActionList.
+ * PageBody. Estados de uma seção ou coleção continuam em DataState, ActionView e ActionList —
+ * as superfícies são as mesmas (state-surface.tsx), aqui na escala da página.
  */
 
 import type { ReactNode } from "react";
-import { TriangleAlert } from "lucide-react";
 import { cn } from "../../lib/cn.ts";
-import { Alert } from "../primitives/alert.tsx";
 import {
-  Empty,
-  EmptyActions,
-  EmptyDescription,
-  EmptyHeader,
-  EmptyMedia,
-  EmptyTitle,
-} from "../primitives/empty.tsx";
-import { Spinner } from "../primitives/spinner.tsx";
+  DEFAULT_RETRY_LABEL,
+  EmptySurface,
+  ErrorSurface,
+  LoadingSurface,
+} from "./state-surface.tsx";
 
 export type PageStateStatus = "loading" | "error" | "empty" | "ready";
 
@@ -30,8 +26,16 @@ export interface PageStateProps {
   description?: ReactNode;
   /** Ícone decorativo. Error usa TriangleAlert por default; empty não inventa um ícone. */
   icon?: ReactNode;
-  /** Ação aplicável ao estado, como tentar novamente, escolher ou criar. */
+  /** Ação aplicável ao estado, como escolher ou criar. */
   action?: ReactNode;
+  /** Título do vazio quando `title` não for informado. Default: "Nada por aqui". */
+  emptyMessage?: string;
+  /** Título do erro quando `title` não for informado. Default: "Não foi possível carregar esta página". */
+  errorMessage?: string;
+  /** Recuperação do erro: com `onRetry`, o botão de tentar de novo entra ao lado de `action`. */
+  onRetry?: () => Promise<void> | void;
+  /** Rótulo do botão de recuperação. Default: "Tentar de novo". */
+  retryLabel?: string;
   /** Conteúdo normal da página, renderizado somente em ready. */
   children?: ReactNode;
   className?: string;
@@ -43,6 +47,10 @@ export function PageState({
   description,
   icon,
   action,
+  emptyMessage = "Nada por aqui",
+  errorMessage = "Não foi possível carregar esta página",
+  onRetry,
+  retryLabel = DEFAULT_RETRY_LABEL,
   children,
   className,
 }: PageStateProps): React.ReactElement {
@@ -50,30 +58,12 @@ export function PageState({
 
   if (status === "loading") {
     return (
-      <div
-        data-slot="page-state"
-        data-status="loading"
-        role="status"
-        aria-live="polite"
-        className={cn(
-          "flex min-h-64 flex-col items-center justify-center gap-3 text-center",
-          className,
-        )}
-      >
-        <Spinner aria-hidden="true" aria-label={undefined} role="presentation" />
-        <div className="max-w-md space-y-1">
-          <p data-slot="page-state-title" className="text-sm font-medium">
-            {title ?? "Carregando…"}
-          </p>
-          {description !== undefined && (
-            <p
-              data-slot="page-state-description"
-              className="text-sm text-muted-foreground"
-            >
-              {description}
-            </p>
-          )}
-        </div>
+      <div data-slot="page-state" data-status="loading" className={className}>
+        <LoadingSurface
+          className="min-h-64"
+          title={title ?? "Carregando…"}
+          description={description}
+        />
       </div>
     );
   }
@@ -85,31 +75,29 @@ export function PageState({
         data-status="error"
         className={cn("flex min-h-64 items-center justify-center", className)}
       >
-        <Alert
+        <ErrorSurface
           className="max-w-xl"
-          context="danger"
-          icon={icon ?? <TriangleAlert />}
-          title={title ?? "Não foi possível carregar esta página"}
+          icon={icon}
+          title={title ?? errorMessage}
           description={description}
+          {...(onRetry !== undefined ? { onRetry } : {})}
+          retryLabel={retryLabel}
         >
           {action}
-        </Alert>
+        </ErrorSurface>
       </div>
     );
   }
 
   return (
     <div data-slot="page-state" data-status="empty" className={className}>
-      <Empty className="min-h-64">
-        <EmptyHeader>
-          {icon !== undefined && <EmptyMedia variant="icon">{icon}</EmptyMedia>}
-          <EmptyTitle>{title ?? "Nada por aqui"}</EmptyTitle>
-          {description !== undefined && (
-            <EmptyDescription>{description}</EmptyDescription>
-          )}
-        </EmptyHeader>
-        {action !== undefined && <EmptyActions>{action}</EmptyActions>}
-      </Empty>
+      <EmptySurface
+        className="min-h-64"
+        icon={icon}
+        title={title ?? emptyMessage}
+        description={description}
+        action={action}
+      />
     </div>
   );
 }

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

@@ -16,6 +16,7 @@ import {
 } from "react";
 import { createPortal } from "react-dom";
 import { cn } from "../../lib/cn.ts";
+import { SurfaceHeader, surfaceHeaderClasses } from "./surface-header.tsx";
 
 const PageContext = createContext(false);
 const PageHeaderContext = createContext(false);
@@ -110,7 +111,7 @@ export function Page({
   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)}>
+        <div className={cn("mx-auto max-w-7xl space-y-6 px-8 py-8", className)}>
           {shorthand ? (
             <>
               <PageHeader>
@@ -132,60 +133,27 @@ export function Page({
   );
 }
 
+/** A anatomia é a de `SurfaceHeader`, a mesma de `ContentHeader`; só os slots mudam de nome. */
 export function PageHeader({
-  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.",
-    );
-  }
-
   return (
     <PageHeaderContext.Provider value>
-      <div
-        data-slot="page-header"
-        className={cn(
-          "mb-6",
-          actionSlots.length > 0 &&
-            "flex flex-col items-start gap-4 sm:flex-row sm:items-end sm:justify-between",
-          className,
-        )}
+      <SurfaceHeader
+        name="PageHeader"
+        slot="page"
+        slots={{
+          title: PageTitle,
+          count: PageMeta,
+          description: PageDescription,
+          actions: PageActions,
+        }}
         {...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>
   );
 }
@@ -198,7 +166,7 @@ export function PageTitle({
   return (
     <h1
       data-slot="page-title"
-      className={cn("text-2xl font-semibold tracking-tight", className)}
+      className={cn(surfaceHeaderClasses.page.title, className)}
       {...props}
     />
   );
@@ -212,7 +180,7 @@ export function PageDescription({
   return (
     <p
       data-slot="page-description"
-      className={cn("mt-1 truncate text-sm text-muted-foreground", className)}
+      className={cn(surfaceHeaderClasses.page.description, className)}
       {...props}
     />
   );
@@ -226,7 +194,7 @@ export function PageMeta({
   return (
     <span
       data-slot="page-meta"
-      className={cn("font-mono text-base text-muted-foreground/60", className)}
+      className={cn(surfaceHeaderClasses.page.count, className)}
       {...props}
     />
   );
@@ -241,10 +209,7 @@ export function PageActions({
   const actions = (
     <div
       data-slot="page-actions"
-      className={cn(
-        "flex w-full shrink-0 items-center gap-4 sm:w-auto",
-        className,
-      )}
+      className={cn(surfaceHeaderClasses.page.actions, className)}
       {...props}
     />
   );

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

@@ -0,0 +1,148 @@
+/**
+ * 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 é `Alert context="danger"` com o botão de recuperação;
+ * vazio compõe `Empty*`. Os patterns públicos só 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 { 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'
+
+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
+  className?: string
+}
+
+/** O contêiner é o único `role="status"`; o Spinner dentro dele é decorativo. */
+export function LoadingSurface({ title, description, 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" 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`, o botão 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
+  className?: string
+}
+
+export function ErrorSurface({
+  title,
+  description,
+  icon,
+  onRetry,
+  retryLabel = DEFAULT_RETRY_LABEL,
+  children,
+  className,
+}: ErrorSurfaceProps): ReactElement {
+  return (
+    <Alert
+      context="danger"
+      icon={icon ?? <TriangleAlert />}
+      title={title}
+      description={description}
+      className={className}
+    >
+      {onRetry !== undefined && (
+        <Button context="neutral" variant="outline" size="sm" onClick={() => void onRetry()}>
+          {retryLabel}
+        </Button>
+      )}
+      {children}
+    </Alert>
+  )
+}
+
+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
+  className?: string
+}
+
+export function EmptySurface({
+  title,
+  description,
+  icon,
+  action,
+  frame = 'region',
+  compact = false,
+  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 className={cn(compact && 'text-sm font-normal text-muted-foreground')}>{title}</EmptyTitle>
+        {description !== undefined && <EmptyDescription>{description}</EmptyDescription>}
+      </EmptyHeader>
+      {action !== undefined && <EmptyActions>{action}</EmptyActions>}
+    </Empty>
+  )
+}

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

@@ -0,0 +1,119 @@
+/**
+ * Cabeçalho de superfície (interno): a anatomia que Page e Content compartilham.
+ *
+ * Um título, um contador opcional na mesma linha de base, uma descrição e uma região de ações
+ * que vai para o extremo oposto em larguras amplas e empilha abaixo do contexto nas estreitas.
+ * `PageHeader` e `ContentHeader` só nomeiam os slots (`page-*`, `content-*`) e a hierarquia
+ * visual (`page` ou `section`); layout, validação e classes vivem aqui, uma vez.
+ */
+
+import {
+  Children,
+  Fragment,
+  isValidElement,
+  type ElementType,
+  type HTMLAttributes,
+  type ReactElement,
+  type ReactNode,
+} from "react";
+import { cn } from "../../lib/cn.ts";
+
+export type SurfaceHeaderVariant = "page" | "section";
+
+/** As classes por slot, por hierarquia visual — PageTitle e ContentTitle(page) são o mesmo. */
+export const surfaceHeaderClasses: Record<
+  SurfaceHeaderVariant,
+  { title: string; description: string; count: string; actions: string }
+> = {
+  page: {
+    title: "text-2xl font-semibold tracking-tight",
+    description: "mt-1 truncate text-sm text-muted-foreground",
+    count: "font-mono text-base text-muted-foreground/60",
+    actions: "flex w-full shrink-0 items-center gap-4 sm:w-auto",
+  },
+  section: {
+    title: "text-sm font-semibold",
+    description: "mt-0.5 truncate text-xs text-muted-foreground",
+    count: "font-mono text-xs text-muted-foreground/60",
+    actions: "flex w-full shrink-0 items-center gap-2 sm:w-auto",
+  },
+};
+
+interface SurfaceHeaderSlots {
+  title: ElementType;
+  count: ElementType;
+  description: ElementType;
+  actions: ElementType;
+}
+
+export interface SurfaceHeaderProps extends HTMLAttributes<HTMLDivElement> {
+  /** Nome do componente público, para as mensagens de erro (`PageHeader`, `ContentHeader`). */
+  name: string;
+  /** Prefixo dos `data-slot` (`page` → `page-header`, `page-heading`). */
+  slot: string;
+  /** Os componentes de slot que este cabeçalho reconhece. */
+  slots: SurfaceHeaderSlots;
+}
+
+/** Expande fragments de primeiro nível: o shorthand monta os slots dentro de um `<>`. */
+function flatten(children: ReactNode): ReactNode[] {
+  return Children.toArray(children).flatMap((node) =>
+    isValidElement(node) && node.type === Fragment
+      ? Children.toArray((node.props as { children?: ReactNode }).children)
+      : [node],
+  );
+}
+
+export function SurfaceHeader({
+  name,
+  slot,
+  slots,
+  className,
+  children,
+  ...props
+}: SurfaceHeaderProps): ReactElement {
+  const nodes = flatten(children);
+  const of = (type: ElementType) =>
+    nodes.filter((node) => isValidElement(node) && node.type === type);
+  const titles = of(slots.title);
+  const counts = of(slots.count);
+  const descriptions = of(slots.description);
+  const actionSlots = of(slots.actions);
+  const recognized =
+    titles.length + counts.length + descriptions.length + actionSlots.length;
+
+  if (
+    titles.length !== 1 ||
+    counts.length > 1 ||
+    descriptions.length > 1 ||
+    actionSlots.length > 1 ||
+    recognized !== nodes.length
+  ) {
+    const label = (type: ElementType) =>
+      typeof type === "string" ? type : (type as { name?: string }).name ?? "";
+    throw new Error(
+      `${name} exige um ${label(slots.title)} e aceita no máximo um ${label(slots.description)}, ${label(slots.count)} e ${label(slots.actions)} como filhos diretos.`,
+    );
+  }
+
+  return (
+    <div
+      data-slot={`${slot}-header`}
+      className={cn(
+        actionSlots.length > 0 &&
+          "flex flex-col items-start gap-4 sm:flex-row sm:items-end sm:justify-between",
+        className,
+      )}
+      {...props}
+    >
+      <div data-slot={`${slot}-heading`} className="min-w-0">
+        <div className="flex items-baseline gap-2">
+          {titles}
+          {counts}
+        </div>
+        {descriptions}
+      </div>
+      {actionSlots}
+    </div>
+  );
+}

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

@@ -5,8 +5,9 @@
  * - Loading state automático (disabled + "..." enquanto roda).
  * - Toast em sucesso/erro; cache invalidation via action.invalidates.
  * - Confirmação opcional via <Dialog> (compacto, não fecha no clique fora) antes de disparar.
- * - `icon` faz o botão virar icon-only com tooltip: é a ação que mora NO item (linha,
- *   card). Absorveu o antigo DeleteButton, que era este componente com uma lixeira.
+ * - `icon` faz o botão virar icon-only com tooltip, no quadrado `icon-sm` (1.75rem) da escala:
+ *   é a ação que mora NO item (linha, card). Absorveu o antigo DeleteButton, que era este
+ *   componente com uma lixeira.
  * Emite `data-action="<action.name>"` na raiz (selector E2E).
  */
 
@@ -49,8 +50,8 @@ export interface ActionTriggerProps<TInput, TData> {
   context?: ButtonProps['context']
   /** Tratamento visual do Button. */
   variant?: ButtonProps['variant']
-  /** Tamanho do botão. */
-  size?: 'default' | 'sm' | 'lg' | 'icon'
+  /** Tamanho do botão (escala de control.ts). Com `icon`, o botão é sempre `icon-sm`. */
+  size?: ButtonProps['size']
   /** Desabilita o botão independente de loading. */
   disabled?: boolean
   /** Texto do confirm dialog. Default vem do `action.confirm` (ConfirmSpec do
@@ -141,7 +142,7 @@ export function ActionTrigger<TInput, TData>({
       <Button
         context={triggerContext}
         variant={triggerVariant}
-        size={icon !== undefined ? 'icon' : size}
+        size={icon !== undefined ? 'icon-sm' : size}
         busy={isLoading}
         disabled={disabled}
         aria-label={icon !== undefined ? buttonLabel : undefined}
@@ -149,10 +150,7 @@ export function ActionTrigger<TInput, TData>({
           e.stopPropagation()
           onClick()
         }}
-        className={cn(
-          icon !== undefined && 'size-7 shrink-0 text-muted-foreground/60',
-          className,
-        )}
+        className={cn(icon !== undefined && 'shrink-0 text-muted-foreground/60', className)}
         data-action={action.name}
       >
         {icon ?? buttonLabel}

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

@@ -10,9 +10,8 @@ import type { ReactNode } from 'react'
 import type { ViewAction } from '../../../core/index.ts'
 import { useViewAction } from '../../drivers/react.tsx'
 import { isBusinessError, isRetryable } from '../../lib/action-errors.ts'
-import { Alert } from '../primitives/alert.tsx'
 import { Skeleton } from '../primitives/skeleton.tsx'
-import { Button } from '../primitives/button.tsx'
+import { EmptySurface, ErrorSurface } from './state-surface.tsx'
 
 export interface ActionViewProps<TInput, TData> {
   action: ViewAction<TInput, TData>
@@ -21,14 +20,16 @@ export interface ActionViewProps<TInput, TData> {
   children?: (data: TData, refetch: () => Promise<void>) => ReactNode
   /** Alias de children (a API original). Children tem precedência. */
   render?: (data: TData, refetch: () => Promise<void>) => ReactNode
-  /** Renderiza estado vazio (200 mas sem dado). Default: nada. */
+  /** Renderiza estado vazio (200 mas sem dado). Default: `emptyMessage` ou nada. */
   empty?: ReactNode
+  /** Atalho do vazio: a frase na mesma superfície de DataState (Empty com moldura sólida). */
+  emptyMessage?: string
   /** Renderiza loading. Default (ou `true`): 3 skeletons empilhados; `false` não renderiza
    *  nada enquanto carrega — o contêiner `data-action` permanece. */
   loading?: ReactNode | boolean
-  /** Renderiza erro. Default: "Não foi possível carregar" + botão "Tentar de novo" (omitido em
-   *  falta de permissão ou sessão); a frase do servidor entra como descrição só quando está na
-   *  allowlist de lib/action-errors.ts. */
+  /** Renderiza erro. Default: a mesma superfície de DataState — "Não foi possível carregar" +
+   *  "Tentar de novo" (omitido em falta de permissão ou sessão); a frase do servidor entra como
+   *  descrição só quando está na allowlist de lib/action-errors.ts. */
   error?: (err: { code: string; message: string; category?: string }, retry: () => Promise<void>) => ReactNode
 }
 
@@ -38,6 +39,7 @@ export function ActionView<TInput, TData>({
   children,
   render,
   empty,
+  emptyMessage,
   loading,
   error,
 }: ActionViewProps<TInput, TData>) {
@@ -66,23 +68,19 @@ export function ActionView<TInput, TData>({
     }
     return (
       <div data-action={action.name}>
-        <Alert
-          context="danger"
+        <ErrorSurface
           title="Não foi possível carregar"
           description={isBusinessError(err) ? err.message.trim() : undefined}
-        >
-          {isRetryable(err) && (
-            <Button variant="outline" size="sm" onClick={() => void refetch()}>
-              Tentar de novo
-            </Button>
-          )}
-        </Alert>
+          {...(isRetryable(err) ? { onRetry: () => refetch() } : {})}
+        />
       </div>
     )
   }
 
   if (data === undefined) {
-    return <div data-action={action.name}>{empty ?? null}</div>
+    const emptyNode =
+      empty ?? (emptyMessage !== undefined ? <EmptySurface title={emptyMessage} compact frame="structural" /> : null)
+    return <div data-action={action.name}>{emptyNode}</div>
   }
 
   return <div data-action={action.name}>{renderData(data, refetch)}</div>