@softize/opus 13.0.0 → 14.0.0

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

@@ -309,8 +309,12 @@ export interface ActionListProps<TInput, TItem> {
   /** Itens por página (o pattern manda `limit` e `page` no input; o handler implementa
    *  o OFFSET e devolve `total`). O rodapé mostra o total e o pager quando transborda. */
   pageSize?: number;
-  /** Mensagem de empty state. Default: "Nenhum resultado." */
+  /** Mensagem do estado vazio. Default: "Nenhum resultado." */
   emptyMessage?: string;
+  /** Mensagem do estado de erro (calma, sem o texto técnico). Default do DataState. */
+  errorMessage?: string;
+  /** Rótulo do botão de recuperação no erro. Default: "Tentar de novo". */
+  retryLabel?: string;
   /** Sobrepõe o vazio derivado (items.length === 0) — ex.: form inline aberto conta
    *  como conteúdo, então os children devem renderizar mesmo com a lista vazia. */
   empty?: (items: TItem[]) => boolean;
@@ -754,7 +758,7 @@ function PeriodControl({
               <Button
                 key={p.value}
                 size="sm"
-                context={period === p.value ? "neutral" : "primary"}
+                context={period === p.value ? "primary" : "neutral"}
                 variant={period === p.value ? "solid" : "ghost"}
                 className="justify-start"
                 onClick={() => {
@@ -1138,6 +1142,8 @@ export function ActionList<TInput, TItem>({
   rowId = (item: TItem) => String((item as { id?: unknown }).id ?? ""),
   pageSize = 50,
   emptyMessage = "Nenhum resultado.",
+  errorMessage,
+  retryLabel,
   empty,
   loading: extraLoading,
   onRowClick,
@@ -1428,6 +1434,7 @@ export function ActionList<TInput, TItem>({
                   <PopoverTrigger asChild>
                     <Button
                       variant="outline"
+                      size="icon"
                       className="shrink-0"
                       aria-label="Exibição"
                     >
@@ -1628,7 +1635,9 @@ export function ActionList<TInput, TItem>({
       loading={busy && items.length === 0 && !(empty !== undefined && !isEmpty)}
       error={isError ? error : null}
       empty={isEmpty}
-      emptyText={emptyMessage}
+      emptyMessage={emptyMessage}
+      {...(errorMessage !== undefined ? { errorMessage } : {})}
+      {...(retryLabel !== undefined ? { retryLabel } : {})}
       onRetry={() => refetch()}
     >
       {content}
@@ -1696,15 +1705,14 @@ export function ActionList<TInput, TItem>({
           Página {state.page} de {pages}
         </span>
         {pages > 1 && (
-          // A primitiva pública na escala densa do rodapé: setas quadradas `size-7`,
+          // A primitiva pública na escala densa do rodapé: setas no quadrado `icon-sm`,
           // números `h-7 min-w-7` que crescem com os dígitos (5726 e 5727 não se colam).
           <Pagination className="mx-0 w-auto">
             <PaginationContent className="gap-0.5">
               <PaginationItem>
                 <PaginationPrevious
                   iconOnly
-                  className="size-7"
-                  iconClassName="size-3.5"
+                  size="icon-sm"
                   disabled={state.page <= 1}
                   onClick={() => goTo(state.page - 1)}
                 />
@@ -1713,7 +1721,7 @@ export function ActionList<TInput, TItem>({
                 n === "…" ? (
                   // eslint-disable-next-line react/no-array-index-key
                   <PaginationItem key={`e${i}`}>
-                    <PaginationEllipsis className="size-7" />
+                    <PaginationEllipsis size="icon-sm" />
                   </PaginationItem>
                 ) : (
                   <PaginationItem key={n}>
@@ -1729,8 +1737,7 @@ export function ActionList<TInput, TItem>({
               <PaginationItem>
                 <PaginationNext
                   iconOnly
-                  className="size-7"
-                  iconClassName="size-3.5"
+                  size="icon-sm"
                   disabled={state.page >= pages}
                   onClick={() => goTo(state.page + 1)}
                 />
@@ -1790,9 +1797,8 @@ export function ActionList<TInput, TItem>({
                 <DialogClose asChild>
                   <Button
                     size="sm"
-                    variant={
-                      confirming.destructive === true ? "destructive" : "default"
-                    }
+                    context={confirming.destructive === true ? "danger" : "primary"}
+                    variant="solid"
                     onClick={() => {
                       const a = confirming;
                       setConfirming(null);

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

@@ -14,10 +14,27 @@ import {
   type ReactElement,
   type ReactNode,
 } 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);
+const PageActionsTargetContext = createContext<HTMLElement | null>(null);
+
+export function PageActionsTarget({
+  target,
+  children,
+}: {
+  target: HTMLElement | null;
+  children: ReactNode;
+}): ReactElement {
+  return (
+    <PageActionsTargetContext.Provider value={target}>
+      {children}
+    </PageActionsTargetContext.Provider>
+  );
+}
 
 function requireParent(
   inside: boolean,
@@ -94,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>
@@ -116,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>
   );
 }
@@ -182,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}
     />
   );
@@ -196,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}
     />
   );
@@ -210,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}
     />
   );
@@ -221,16 +205,15 @@ export function PageActions({
   ...props
 }: HTMLAttributes<HTMLDivElement>): ReactElement {
   requireParent(useContext(PageHeaderContext), "PageActions", "PageHeader");
-  return (
+  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",
-        className,
-      )}
+      className={cn(surfaceHeaderClasses.page.actions, className)}
       {...props}
     />
   );
+  return target === null ? actions : createPortal(actions, target);
 }
 
 export function PageBody({

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

@@ -7,6 +7,7 @@ import {
 import { ChevronRight } from "lucide-react";
 import { useOverflowing } from "../../lib/overflow.ts";
 import { cn } from "../../lib/cn.ts";
+import { focusRing } from "../primitives/control.ts";
 import {
   Tooltip,
   TooltipContent,
@@ -177,17 +178,24 @@ export function SidebarItem({
       <button
         type="button"
         disabled={disabled}
+        aria-label={label}
         aria-current={active ? "page" : undefined}
         onClick={onClick}
         className={cn(
           "mx-auto grid size-9 place-items-center rounded-md transition-colors disabled:pointer-events-none disabled:opacity-40",
-          "outline-none focus-visible:ring-2 focus-visible:ring-ring/50",
+          "outline-none",
+          focusRing,
           active
             ? "bg-muted font-medium text-foreground"
             : "text-foreground/80 hover:bg-muted/60",
         )}
       >
-        {icon}
+        <span
+          data-slot="sidebar-item-icon"
+          className="grid size-4 shrink-0 place-items-center [&_svg]:size-4"
+        >
+          {icon}
+        </span>
       </button>
     );
     // `className` vai no MESMO elemento nos dois modos — a linha —, senão a prop mudaria de alvo
@@ -235,8 +243,9 @@ export function SidebarItem({
           {/* Sem ícone, o chevron não se esconde: ele é o único ocupante do lugar. */}
           {icon !== undefined && (
             <span
+              data-slot="sidebar-item-icon"
               className={cn(
-                "absolute inset-0 flex items-center justify-center transition-opacity",
+                "absolute inset-0 flex items-center justify-center transition-opacity [&_svg]:size-4",
                 onToggle !== undefined &&
                   "group-hover/sidebar-item:opacity-0 group-has-[[data-slot=sidebar-item-toggle]:focus-visible]/sidebar-item:opacity-0",
               )}
@@ -252,7 +261,8 @@ export function SidebarItem({
               aria-label={expanded ? `Fechar ${label}` : `Abrir ${label}`}
               aria-expanded={expanded}
               className={cn(
-                "absolute inset-0 grid place-items-center rounded-sm text-muted-foreground transition-[color,opacity] outline-none hover:text-foreground focus-visible:pointer-events-auto focus-visible:opacity-100 focus-visible:ring-2 focus-visible:ring-ring/50",
+                "absolute inset-0 grid place-items-center rounded-sm text-muted-foreground transition-[color,opacity] outline-none hover:text-foreground focus-visible:pointer-events-auto focus-visible:opacity-100",
+                focusRing,
                 icon === undefined
                   ? "pointer-events-auto opacity-100"
                   : "pointer-events-none opacity-0 group-hover/sidebar-item:pointer-events-auto group-hover/sidebar-item:opacity-100",
@@ -275,7 +285,8 @@ export function SidebarItem({
         onClick={onClick}
         className={cn(
           "flex min-w-0 flex-1 items-center gap-2.5 rounded-md px-2.5 py-1.5 text-left text-sm disabled:pointer-events-none",
-          "outline-none focus-visible:ring-2 focus-visible:ring-ring/50",
+          "outline-none",
+          focusRing,
           disabled
             ? "text-muted-foreground/50"
             : active
@@ -349,7 +360,7 @@ export function SidebarGroupLabel({
     <div
       data-slot="sidebar-group-label"
       className={cn(
-        "px-2.5 pb-1 text-sm font-medium text-muted-foreground/70",
+        "px-2.5 py-1 text-sm font-medium text-muted-foreground/70",
         className,
       )}
     >

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>
+  )
+}