@softize/opus 14.0.0 → 15.0.0

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

@@ -2,13 +2,13 @@
  * 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.
+ * (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 { TriangleAlert } from 'lucide-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'
@@ -21,6 +21,12 @@ import {
   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.'
@@ -30,28 +36,46 @@ 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, className }: LoadingSurfaceProps): ReactElement {
+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)}
+      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">
+            <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">
+            <p
+              data-slot="state-description"
+              className="text-sm text-muted-foreground"
+            >
               {description}
             </p>
           )}
@@ -66,11 +90,15 @@ export interface ErrorSurfaceProps {
   title: ReactNode
   description?: ReactNode
   icon?: ReactNode
-  /** Recuperação: com `onRetry`, o botão entra nas ações do Alert. */
+  /** 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
 }
 
@@ -81,23 +109,98 @@ export function ErrorSurface({
   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 (
-    <Alert
-      context="danger"
-      icon={icon ?? <TriangleAlert />}
-      title={title}
-      description={description}
-      className={className}
+    <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,
+      )}
     >
-      {onRetry !== undefined && (
-        <Button context="neutral" variant="outline" size="sm" onClick={() => void onRetry()}>
-          {retryLabel}
-        </Button>
+      <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>
       )}
-      {children}
-    </Alert>
+    </div>
   )
 }
 
@@ -115,6 +218,8 @@ export interface EmptySurfaceProps {
   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
 }
 
@@ -125,6 +230,7 @@ export function EmptySurface({
   action,
   frame = 'region',
   compact = false,
+  titleLevel,
   className,
 }: EmptySurfaceProps): ReactElement {
   return (
@@ -139,8 +245,16 @@ export function EmptySurface({
     >
       <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>}
+        <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>

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

@@ -1,10 +1,9 @@
 /**
  * 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.
+ * Um título, metadata opcional, 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. Cada família escolhe quais slots
+ * expõe; layout, validação e classes vivem aqui, uma vez.
  */
 
 import {
@@ -40,8 +39,9 @@ export const surfaceHeaderClasses: Record<
 };
 
 interface SurfaceHeaderSlots {
+  leading?: ElementType | readonly ElementType[];
   title: ElementType;
-  count: ElementType;
+  count?: ElementType;
   description: ElementType;
   actions: ElementType;
 }
@@ -53,6 +53,10 @@ export interface SurfaceHeaderProps extends HTMLAttributes<HTMLDivElement> {
   slot: string;
   /** Os componentes de slot que este cabeçalho reconhece. */
   slots: SurfaceHeaderSlots;
+  /** Posição de um slot introdutório opcional, antes da linha ou dentro dela. */
+  leadingPlacement?: "above" | "inline";
+  /** Classes de um container interno quando a moldura precisa ocupar toda a largura. */
+  contentClassName?: string;
 }
 
 /** Expande fragments de primeiro nível: o shorthand monta os slots dentro de um `<>`. */
@@ -68,6 +72,8 @@ export function SurfaceHeader({
   name,
   slot,
   slots,
+  leadingPlacement = "above",
+  contentClassName,
   className,
   children,
   ...props
@@ -75,45 +81,124 @@ export function SurfaceHeader({
   const nodes = flatten(children);
   const of = (type: ElementType) =>
     nodes.filter((node) => isValidElement(node) && node.type === type);
+  const leadingTypes: readonly ElementType[] =
+    slots.leading === undefined
+      ? []
+      : Array.isArray(slots.leading)
+        ? slots.leading
+        : [slots.leading as ElementType];
+  const leading = leadingTypes.flatMap(of);
   const titles = of(slots.title);
-  const counts = of(slots.count);
+  const counts = slots.count === undefined ? [] : of(slots.count);
   const descriptions = of(slots.description);
   const actionSlots = of(slots.actions);
   const recognized =
-    titles.length + counts.length + descriptions.length + actionSlots.length;
+    leading.length +
+    titles.length +
+    counts.length +
+    descriptions.length +
+    actionSlots.length;
 
   if (
     titles.length !== 1 ||
+    leading.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 ?? "";
+      typeof type === "string"
+        ? type
+        : ((type as { name?: string }).name ?? "");
+    const optionalSlots = [
+      ...leadingTypes,
+      slots.description,
+      slots.count,
+      slots.actions,
+    ]
+      .filter((type): type is ElementType => type !== undefined)
+      .map(label)
+      .join(", ");
+    // A região introdutória aceita mais de um TIPO, mas só um por vez: a mensagem genérica
+    // ("no máximo um de cada") não diz que eles são alternativas entre si. O que distingue os
+    // dois erros é a quantidade de tipos distintos presentes — dois PageBack são repetição,
+    // não combinação, e merecem a mensagem genérica.
+    const distinctLeading = new Set(
+      leading.flatMap((node) => (isValidElement(node) ? [node.type as ElementType] : [])),
+    );
     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.`,
+      distinctLeading.size > 1
+        ? `${name} aceita ${[...distinctLeading].map(label).join(" ou ")} na região introdutória, nunca os dois na mesma superfície.`
+        : `${name} exige um ${label(slots.title)} e aceita no máximo um de cada: ${optionalSlots}.`,
     );
   }
 
+  const heading = (
+    <div
+      data-slot={`${slot}-heading`}
+      className={cn("min-w-0", leadingPlacement === "inline" && "flex-1")}
+    >
+      <div className="flex items-baseline gap-2">
+        {titles}
+        {counts}
+      </div>
+      {descriptions}
+    </div>
+  );
+  const row = (
+    <>
+      {leadingPlacement === "inline" && leading}
+      {heading}
+      {actionSlots}
+    </>
+  );
+  const layout =
+    leadingPlacement === "inline" ? (
+      <div className="flex min-w-0 items-center gap-3">{row}</div>
+    ) : leading.length > 0 ? (
+      <>
+        <div data-slot={`${slot}-navigation`} className="mb-4">
+          {leading}
+        </div>
+        <div
+          data-slot={`${slot}-header-row`}
+          className={cn(
+            actionSlots.length > 0 &&
+              "flex flex-col items-start gap-4 sm:flex-row sm:items-end sm:justify-between",
+          )}
+        >
+          {heading}
+          {actionSlots}
+        </div>
+      </>
+    ) : (
+      <>
+        {heading}
+        {actionSlots}
+      </>
+    );
+
   return (
     <div
       data-slot={`${slot}-header`}
       className={cn(
-        actionSlots.length > 0 &&
+        contentClassName === undefined &&
+          leadingPlacement !== "inline" &&
+          leading.length === 0 &&
+          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}
+      {contentClassName === undefined ? (
+        layout
+      ) : (
+        <div data-slot={`${slot}-header-content`} className={contentClassName}>
+          {layout}
         </div>
-        {descriptions}
-      </div>
-      {actionSlots}
+      )}
     </div>
   );
 }

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

@@ -5,9 +5,10 @@
  * - 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, 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.
+ * - `icon` faz o botão virar icon-only com tooltip, no quadrado `icon-xs` (1.5rem) da escala:
+ *   é a ação que mora NO item (linha, card). Uma composição que peça mais presença — a barra
+ *   do `PageHeader`, por exemplo — declara `size="icon-sm"`. Absorveu o antigo DeleteButton,
+ *   que era este componente com uma lixeira.
  * Emite `data-action="<action.name>"` na raiz (selector E2E).
  */
 
@@ -50,7 +51,7 @@ export interface ActionTriggerProps<TInput, TData> {
   context?: ButtonProps['context']
   /** Tratamento visual do Button. */
   variant?: ButtonProps['variant']
-  /** Tamanho do botão (escala de control.ts). Com `icon`, o botão é sempre `icon-sm`. */
+  /** Tamanho do botão (escala de control.ts). Com `icon`, o default é `icon-xs`. */
   size?: ButtonProps['size']
   /** Desabilita o botão independente de loading. */
   disabled?: boolean
@@ -79,7 +80,7 @@ export function ActionTrigger<TInput, TData>({
   label,
   context,
   variant,
-  size = 'default',
+  size,
   disabled = false,
   confirm: confirmProp,
   onSuccess,
@@ -142,7 +143,7 @@ export function ActionTrigger<TInput, TData>({
       <Button
         context={triggerContext}
         variant={triggerVariant}
-        size={icon !== undefined ? 'icon-sm' : size}
+        size={size ?? (icon !== undefined ? 'icon-xs' : 'default')}
         busy={isLoading}
         disabled={disabled}
         aria-label={icon !== undefined ? buttonLabel : undefined}

package/src/ui/components/primitives/button-group.tsx

@@ -9,10 +9,12 @@ const buttonGroupVariants = cva(
   {
     variants: {
       orientation: {
-        horizontal:
-          "[&>*:not(:first-child)]:rounded-l-none [&>*:not(:first-child)]:border-l-0 [&>*:not(:last-child)]:rounded-r-none",
-        vertical:
-          "flex-col [&>*:not(:first-child)]:rounded-t-none [&>*:not(:first-child)]:border-t-0 [&>*:not(:last-child)]:rounded-b-none",
+        horizontal: '',
+        vertical: 'flex-col',
+      },
+      mode: {
+        connected: '',
+        spaced: 'gap-1',
       },
       shape: {
         default: '',
@@ -22,17 +24,38 @@ const buttonGroupVariants = cva(
     compoundVariants: [
       {
         orientation: 'horizontal',
+        mode: 'connected',
+        className:
+          '[&>*:not(:first-child)]:rounded-l-none [&>*:not(:first-child)]:border-l-0 [&>*:not(:last-child)]:rounded-r-none',
+      },
+      {
+        orientation: 'vertical',
+        mode: 'connected',
+        className:
+          '[&>*:not(:first-child)]:rounded-t-none [&>*:not(:first-child)]:border-t-0 [&>*:not(:last-child)]:rounded-b-none',
+      },
+      {
+        orientation: 'horizontal',
+        mode: 'connected',
         shape: 'pill',
         className: '[&>*:first-child]:rounded-l-full [&>*:last-child]:rounded-r-full [&>[data-slot=select]:first-child_[data-slot=select-control]]:rounded-l-full [&>[data-slot=select]:last-child_[data-slot=select-control]]:rounded-r-full [&>[data-slot=select-wrapper]:first-child_[data-slot=select]]:rounded-l-full [&>[data-slot=select-wrapper]:last-child_[data-slot=select]]:rounded-r-full',
       },
       {
         orientation: 'vertical',
+        mode: 'connected',
         shape: 'pill',
         className: '[&>*:first-child]:rounded-t-full [&>*:last-child]:rounded-b-full [&>[data-slot=select]:first-child_[data-slot=select-control]]:rounded-t-full [&>[data-slot=select]:last-child_[data-slot=select-control]]:rounded-b-full [&>[data-slot=select-wrapper]:first-child_[data-slot=select]]:rounded-t-full [&>[data-slot=select-wrapper]:last-child_[data-slot=select]]:rounded-b-full',
       },
+      {
+        mode: 'spaced',
+        shape: 'pill',
+        className:
+          '[&>*]:rounded-full [&>[data-slot=select]_[data-slot=select-control]]:rounded-full [&>[data-slot=select-wrapper]_[data-slot=select]]:rounded-full',
+      },
     ],
     defaultVariants: {
       orientation: "horizontal",
+      mode: 'connected',
       shape: "default",
     },
   }
@@ -41,6 +64,7 @@ const buttonGroupVariants = cva(
 function ButtonGroup({
   className,
   orientation,
+  mode,
   shape,
   ...props
 }: React.ComponentProps<"div"> & VariantProps<typeof buttonGroupVariants>) {
@@ -49,12 +73,14 @@ function ButtonGroup({
       role="group"
       data-slot="button-group"
       data-orientation={orientation}
+      data-mode={mode}
       data-shape={shape}
       className={cn(
-        buttonGroupVariants({ orientation, shape }),
-        orientation === 'vertical'
-          ? '[&>[data-slot=select]:not(:first-child)_[data-slot=select-control]]:rounded-t-none [&>[data-slot=select]:not(:first-child)_[data-slot=select-control]]:border-t-0 [&>[data-slot=select]:not(:last-child)_[data-slot=select-control]]:rounded-b-none [&>[data-slot=select-wrapper]:not(:first-child)_[data-slot=select]]:rounded-t-none [&>[data-slot=select-wrapper]:not(:first-child)_[data-slot=select]]:border-t-0 [&>[data-slot=select-wrapper]:not(:last-child)_[data-slot=select]]:rounded-b-none'
-          : '[&>[data-slot=select]:not(:first-child)_[data-slot=select-control]]:rounded-l-none [&>[data-slot=select]:not(:first-child)_[data-slot=select-control]]:border-l-0 [&>[data-slot=select]:not(:last-child)_[data-slot=select-control]]:rounded-r-none [&>[data-slot=select-wrapper]:not(:first-child)_[data-slot=select]]:rounded-l-none [&>[data-slot=select-wrapper]:not(:first-child)_[data-slot=select]]:border-l-0 [&>[data-slot=select-wrapper]:not(:last-child)_[data-slot=select]]:rounded-r-none',
+        buttonGroupVariants({ orientation, mode, shape }),
+        mode !== 'spaced' &&
+          (orientation === 'vertical'
+            ? '[&>[data-slot=select]:not(:first-child)_[data-slot=select-control]]:rounded-t-none [&>[data-slot=select]:not(:first-child)_[data-slot=select-control]]:border-t-0 [&>[data-slot=select]:not(:last-child)_[data-slot=select-control]]:rounded-b-none [&>[data-slot=select-wrapper]:not(:first-child)_[data-slot=select]]:rounded-t-none [&>[data-slot=select-wrapper]:not(:first-child)_[data-slot=select]]:border-t-0 [&>[data-slot=select-wrapper]:not(:last-child)_[data-slot=select]]:rounded-b-none'
+            : '[&>[data-slot=select]:not(:first-child)_[data-slot=select-control]]:rounded-l-none [&>[data-slot=select]:not(:first-child)_[data-slot=select-control]]:border-l-0 [&>[data-slot=select]:not(:last-child)_[data-slot=select-control]]:rounded-r-none [&>[data-slot=select-wrapper]:not(:first-child)_[data-slot=select]]:rounded-l-none [&>[data-slot=select-wrapper]:not(:first-child)_[data-slot=select]]:border-l-0 [&>[data-slot=select-wrapper]:not(:last-child)_[data-slot=select]]:rounded-r-none'),
         className,
       )}
       {...props}

package/src/ui/components/primitives/control.ts

@@ -8,8 +8,8 @@ export type ControlShape = 'default' | 'pill'
  *
  * - Altura de linha (`xs` · `sm` · `default` · `lg`): 1.5 · 2 · 2.25 · 2.5rem.
  * - Quadrado só-ícone (`icon-xs` · `icon-sm` · `icon` · `icon-lg`): 1.5 · 1.75 · 2.25 · 2.5rem.
- *   `icon-sm` é 1.75rem de propósito: é o degrau da ação que mora dentro de uma linha densa
- *   (o que os consumidores forçavam com `size-7`), menor que o botão de texto `sm` ao lado.
+ *   `icon-xs` é o degrau da ação que mora dentro de uma linha densa. `icon-sm` atende
+ *   composições compactas que ainda precisam de mais presença.
  * - Glifo (o svg dentro do controle daquele tamanho): 0.875 · 0.875 · 1 · 1.25rem. O Spinner
  *   usa esta medida, por isso `busy` substitui o ícone sem mexer na largura do botão.
  */
@@ -38,6 +38,15 @@ export const controlGlyph: Record<ControlSize, string> = {
   lg: 'size-5',
 }
 
+// As classes completas precisam permanecer literais para o scanner do Tailwind gerar os seletores.
+// Montar `]:${controlGlyph[...]}` em runtime devolve o nome certo no DOM, mas deixa o CSS ausente.
+const controlGlyphSelector: Record<ControlSize, string> = {
+  xs: '[&_svg:not([class*=size-])]:size-3.5',
+  sm: '[&_svg:not([class*=size-])]:size-3.5',
+  default: '[&_svg:not([class*=size-])]:size-4',
+  lg: '[&_svg:not([class*=size-])]:size-5',
+}
+
 /** A altura de linha por trás de um tamanho da escala (`icon-sm` → `sm`). */
 export function controlBase(size: ControlScale | null | undefined): ControlSize {
   switch (size) {
@@ -58,7 +67,7 @@ export function controlBase(size: ControlScale | null | undefined): ControlSize
 
 /** Fallback de tamanho do svg descendente, respeitando um `size-*` explícito no próprio ícone. */
 export function controlGlyphClass(size: ControlScale | null | undefined): string {
-  return `[&_svg:not([class*=size-])]:${controlGlyph[controlBase(size)]}`
+  return controlGlyphSelector[controlBase(size)]
 }
 
 /**

package/src/ui/docs/content/action-list-dialog.md

@@ -69,5 +69,5 @@ corpo do modal.
 | `actions` | `ReactNode` | | Ação à direita da toolbar — em geral o botão de criar. |
 | `empty` | `(items) => boolean` | `items.length === 0` | Sobrepõe o vazio derivado. |
 | `loading` | `boolean` | | Carga extra agregada à do fetch (query irmã). |
-| `emptyMessage / errorMessage / retryLabel` | `string` | | Textos dos estados, repassados ao `ActionList` (e dele ao `DataState`). |
+| `emptyMessage / errorMessage / retryLabel` | `string` | | Textos dos estados; `retryLabel` nomeia a ação somente com ícone e seu tooltip. |
 | `className` | `string` | `sm:max-w-3xl` | Largura do DialogContent. |

package/src/ui/docs/content/action-list.md

@@ -7,6 +7,9 @@ os filtros aplicados permanecem visíveis como chips removíveis.
 
 A barra se adapta ao espaço disponível. A busca cede largura primeiro e filtros que deixam de caber
 migram para o modal; a linha só quebra quando nenhum controle restante puder ceder espaço.
+`toolbarActions` acrescenta ações do consumidor ao fim da barra. Recarregar e exibição formam um
+`ButtonGroup` espaçado; as ações do consumidor vêm depois, com um intervalo maior para preservar a
+hierarquia entre ferramentas e a ação principal.
 
 ```tsx preview col
 render(
@@ -18,6 +21,20 @@ render(
 )
 ```
 
+Uma ação icon-only mantém o nome no tooltip e no `aria-label`:
+
+```tsx
+<ActionList
+  action={workspaceList}
+  input={{}}
+  toolbarActions={
+    <Button context="primary" size="icon" aria-label="Novo workspace">
+      <Plus />
+    </Button>
+  }
+/>
+```
+
 ## Barra de filtros compartilhada
 
 `ActionFilterBar` expõe a mesma linguagem declarativa de busca, filtros e período para
@@ -235,6 +252,19 @@ render(
 )
 ```
 
+## Propriedades de ActionFilterBar
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `action` | `Pick<ListAction, 'filters' \| 'text' \| 'periods'>` | | Declara busca, filtros e períodos disponíveis. |
+| `state` | `ActionFilterState` | | Estado atual da barra. |
+| `onStateChange` | `(next) => void` | | Recebe o estado completo depois de cada alteração. |
+| `filterOptions` | `Record<string, SelectOption[]>` | | Fornece opções de runtime para filtros select e lookup. |
+| `onRefresh` | `() => Promise<void> \| void` | | Exibe a ação de recarregar e executa a consulta do consumidor. |
+| `refreshing` | `boolean` | `false` | Desabilita e anima a ação de recarregar durante a consulta. |
+| `controls` | `ReactNode` | | Controles auxiliares agrupados com recarregar em um `ButtonGroup` espaçado. |
+| `actions` | `ReactNode` | | Ações do consumidor exibidas depois do grupo de controles, com um intervalo maior. |
+
 ## Declaração na ListAction
 
 | Chave | O que declara |
@@ -268,7 +298,8 @@ chamar a action.
 | `pageSize` | `number` | `50` | Itens por página padrão (vira `limit`/`page` no input; handler devolve `total`). O usuário troca no popover de exibição. |
 | `state / onStateChange` | `ActionListState / (next) => void` | interno | Estado da toolbar controlado — para quem embala sincronizar com a URL. |
 | `emptyMessage` | `string` | `'Nenhum resultado.'` | Frase do estado vazio (o `Empty` do `DataState`). |
-| `errorMessage` | `string` | `'Não foi possível carregar.'` | Título do aviso de erro; o botão de tentar de novo refaz a consulta. |
-| `retryLabel` | `string` | `'Tentar de novo'` | Rótulo do botão de recuperação. |
+| `errorMessage` | `string` | `'Não foi possível carregar.'` | Título do aviso de erro; a ação de tentar de novo refaz a consulta. |
+| `retryLabel` | `string` | `'Tentar de novo'` | Nome acessível e tooltip da ação de recuperação. |
 | `onRowClick` | `(item: TItem) => void` | | Clique na linha (ex.: navegar para o detalhe) — só na tabela. |
-| `rowActions` | `(item: TItem) => ReactNode` | | Ações por linha (coluna final, à direita) — apresentação de quem chama, como `cells`; cliques ali não disparam o `onRowClick`. |
+| `toolbarActions` | `ReactNode` | | Ações do consumidor no fim da barra, separadas do grupo de controles. |
+| `rowActions` | `(item: TItem) => ReactNode` | | Ações por linha (coluna final, à direita), agrupadas automaticamente com intervalo compacto; cliques ali não disparam o `onRowClick`. |