@softize/opus 13.1.0 → 15.0.0

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

@@ -74,6 +74,7 @@ import {
   PaginationPrevious,
 } from "../primitives/pagination.tsx";
 import { Button } from "../primitives/button.tsx";
+import { ButtonGroup } from "../primitives/button-group.tsx";
 import { Calendar } from "../primitives/calendar.tsx";
 import { Checkbox } from "../primitives/checkbox.tsx";
 import {
@@ -262,7 +263,9 @@ export interface ActionFilterBarProps {
   filterOptions?: Record<string, SelectOption[]>;
   onRefresh?: () => Promise<void> | void;
   refreshing?: boolean;
-  /** Ações de apresentação do consumidor, renderizadas depois do refresh. */
+  /** Controles auxiliares, agrupados com o refresh em um ButtonGroup espaçado. */
+  controls?: ReactNode;
+  /** Ações do consumidor, separadas do grupo de controles. */
   actions?: ReactNode;
 }
 
@@ -293,6 +296,8 @@ export interface ActionListProps<TInput, TItem> {
   action: ListActionLike;
   /** Input BASE (escopo fixo, ex.: { workspaceId }) — a toolbar soma por cima. */
   input: TInput;
+  /** Ações do consumidor no fim da barra de filtros, depois dos controles de exibição. */
+  toolbarActions?: ReactNode;
   /** Tabela explícita — sobrepõe as colunas do contrato. */
   columns?: ActionListColumn<TItem>[];
   /** Células custom POR CIMA das colunas do contrato (chave = column.key). */
@@ -309,8 +314,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;
@@ -900,6 +909,7 @@ export function ActionFilterBar({
   filterOptions,
   onRefresh,
   refreshing = false,
+  controls,
   actions,
 }: ActionFilterBarProps): React.ReactElement {
   const dicts = useDicts();
@@ -1043,7 +1053,7 @@ export function ActionFilterBar({
             <Tooltip>
               <TooltipTrigger asChild>
                 <Button
-                  variant="outline"
+                  variant="ghost"
                   size="icon"
                   className="shrink-0"
                   aria-label="Filtros"
@@ -1057,27 +1067,32 @@ export function ActionFilterBar({
           )}
           <div className="ml-auto flex min-w-0 items-center gap-2">
             {!searchFirst && searchBox}
-            {onRefresh !== undefined && (
-              <Tooltip>
-                <TooltipTrigger asChild>
-                  <Button
-                    variant="outline"
-                    size="icon"
-                    className="shrink-0"
-                    aria-label="Recarregar"
-                    onClick={() => void onRefresh()}
-                    disabled={refreshing}
-                  >
-                    <RefreshCw
-                      className={cn(
-                        "h-3.5 w-3.5",
-                        refreshing && "animate-spin",
-                      )}
-                    />
-                  </Button>
-                </TooltipTrigger>
-                <TooltipContent>Recarregar</TooltipContent>
-              </Tooltip>
+            {(onRefresh !== undefined || controls !== undefined) && (
+              <ButtonGroup mode="spaced">
+                {onRefresh !== undefined && (
+                  <Tooltip>
+                    <TooltipTrigger asChild>
+                      <Button
+                        variant="ghost"
+                        size="icon"
+                        className="shrink-0"
+                        aria-label="Recarregar"
+                        onClick={() => void onRefresh()}
+                        disabled={refreshing}
+                      >
+                        <RefreshCw
+                          className={cn(
+                            "h-3.5 w-3.5",
+                            refreshing && "animate-spin",
+                          )}
+                        />
+                      </Button>
+                    </TooltipTrigger>
+                    <TooltipContent>Recarregar</TooltipContent>
+                  </Tooltip>
+                )}
+                {controls}
+              </ButtonGroup>
             )}
             {actions}
           </div>
@@ -1130,6 +1145,7 @@ export function ActionFilterBar({
 export function ActionList<TInput, TItem>({
   action,
   input,
+  toolbarActions,
   columns,
   cells,
   filterOptions,
@@ -1138,6 +1154,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,
@@ -1388,7 +1406,7 @@ export function ActionList<TInput, TItem>({
         filterOptions={filterOptions}
         onRefresh={() => refetch()}
         refreshing={isLoading}
-        actions={
+        controls={
           <>
             {hasSegment && (
               <ToggleGroup
@@ -1427,7 +1445,7 @@ export function ActionList<TInput, TItem>({
                 <TooltipTrigger asChild>
                   <PopoverTrigger asChild>
                     <Button
-                      variant="outline"
+                      variant="ghost"
                       size="icon"
                       className="shrink-0"
                       aria-label="Exibição"
@@ -1511,6 +1529,7 @@ export function ActionList<TInput, TItem>({
             </Popover>
           </>
         }
+        actions={toolbarActions}
       />
     </div>
   ) : null;
@@ -1615,7 +1634,9 @@ export function ActionList<TInput, TItem>({
                   className="w-px whitespace-nowrap text-right"
                   onClick={(e) => e.stopPropagation()}
                 >
-                  {rowActions(item)}
+                  <ButtonGroup mode="spaced" className="ml-auto">
+                    {rowActions(item)}
+                  </ButtonGroup>
                 </TableCell>
               )}
             </TableRow>
@@ -1629,7 +1650,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}
@@ -1697,15 +1720,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)}
                 />
@@ -1714,7 +1736,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}>
@@ -1730,8 +1752,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)}
                 />

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

@@ -3,25 +3,43 @@
  *
  * 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 {
+  createContext,
+  useContext,
+  useLayoutEffect,
+  type ReactNode,
+} from "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";
 
+const PageStatePresenceContext = createContext<(() => () => void) | null>(null);
+
+/** Integração interna: permite que Page reconheça um PageState mesmo dentro de outro componente. */
+export function PageStatePresenceProvider({
+  register,
+  children,
+}: {
+  register: () => () => void;
+  children: ReactNode;
+}): React.ReactElement {
+  return (
+    <PageStatePresenceContext.Provider value={register}>
+      {children}
+    </PageStatePresenceContext.Provider>
+  );
+}
+
 export interface PageStateProps {
   status: PageStateStatus;
   /** Título específico do estado. Defaults seguros existem para loading, error e empty. */
@@ -30,8 +48,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,37 +69,39 @@ 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 {
+  const registerPresence = useContext(PageStatePresenceContext);
+  useLayoutEffect(() => {
+    if (status === "ready" || registerPresence === null) return;
+    return registerPresence();
+  }, [registerPresence, status]);
+
   if (status === "ready") return <>{children}</>;
 
+  const stateClassName = cn(
+    "flex min-h-64 flex-1 items-center justify-center",
+    className,
+  );
+
   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,
-        )}
+        className={stateClassName}
       >
-        <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>
+        <LoadingSurface
+          className="w-full min-h-64"
+          title={title ?? "Carregando…"}
+          description={description}
+          titleLevel={1}
+        />
       </div>
     );
   }
@@ -83,33 +111,35 @@ export function PageState({
       <div
         data-slot="page-state"
         data-status="error"
-        className={cn("flex min-h-64 items-center justify-center", className)}
+        className={stateClassName}
       >
-        <Alert
-          className="max-w-xl"
-          context="danger"
-          icon={icon ?? <TriangleAlert />}
-          title={title ?? "Não foi possível carregar esta página"}
+        <ErrorSurface
+          presentation="state"
+          className="w-full max-w-xl"
+          titleLevel={1}
+          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>
+    <div data-slot="page-state" data-status="empty" className={stateClassName}>
+      <EmptySurface
+        frame="bare"
+        className="min-h-64"
+        titleLevel={1}
+        icon={icon}
+        title={title ?? emptyMessage}
+        description={description}
+        action={action}
+      />
     </div>
   );
 }