@softize/opus 13.0.0 → 14.0.0

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).
  */
 
@@ -16,6 +17,7 @@ import type { SimpleContract } from '../../../core/index.ts'
 import { useTriggerAction } from '../../drivers/react.tsx'
 import { toast } from '../primitives/sonner.tsx'
 import { cn } from '../../lib/cn.ts'
+import { humanizeActionError } from '../../lib/action-errors.ts'
 import { Button, type ButtonProps } from '../primitives/button.tsx'
 import { Tooltip, TooltipContent, TooltipTrigger } from '../primitives/tooltip.tsx'
 import {
@@ -48,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
@@ -71,16 +73,6 @@ export interface ActionTriggerProps<TInput, TData> {
   className?: string
 }
 
-/**
- * Categorias de erro cuja frase do SERVIDOR vence o rótulo do contrato: "Este agente tem 3
- * conversas — desabilite em vez de excluir" é acionável; "Falha ao excluir" não. É
- * ALLOWLIST de propósito — erro inesperado carrega texto técnico cru (uma violação de FK
- * viraria `violates foreign key constraint "user_unit_id_fkey"` no toast de quem só clicou
- * no botão), então categoria desconhecida cai no rótulo genérico, o lado seguro de errar.
- * `authorization` fica de fora: o runtime lança `Forbidden`, pior que a frase em pt-BR.
- */
-const BUSINESS_ERRORS = ['conflict', 'validation', 'not_found']
-
 export function ActionTrigger<TInput, TData>({
   action,
   input,
@@ -103,9 +95,9 @@ export function ActionTrigger<TInput, TData>({
       setOpen(false)
     },
     onError: (err) => {
-      const detail = err.message.trim()
-      const speakable = BUSINESS_ERRORS.includes(err.category as string) && detail !== ''
-      toast.error(speakable ? detail : msgText(action.messages?.error, err.message))
+      // A frase de negócio do servidor vence o rótulo do contrato (ver lib/action-errors.ts);
+      // fora da allowlist, vale o rótulo — nunca o texto técnico cru.
+      toast.error(humanizeActionError(err, msgText(action.messages?.error, 'Não foi possível concluir.')))
     },
   })
 
@@ -124,12 +116,19 @@ export function ActionTrigger<TInput, TData>({
         }
       : undefined)
   const destructive = spec?.destructive === true
-  // Com ícone o botão é chrome do item: fica ghost, e o vermelho aparece no hover — uma
-  // lixeira sólida vermelha em cada linha seria um campo minado visual.
+  /**
+   * Precedência de aparência:
+   * - Gatilho: `context` explícito vence `destructive`; sem ele, destrutivo é `danger`. Com
+   *   ícone o botão é chrome do item: fica ghost e o vermelho aparece no hover — uma lixeira
+   *   sólida vermelha em cada linha seria um campo minado visual.
+   * - Confirmar: `destructive` vence `context` (a pergunta é o momento de avisar o risco) e o
+   *   botão é sempre `solid` — não herda o `variant` do gatilho, que descreve o item, não a
+   *   decisão.
+   */
   const triggerContext = context ?? (destructive ? 'danger' : icon !== undefined ? 'neutral' : 'primary')
   const triggerVariant = variant ?? (icon !== undefined ? 'ghost' : 'solid')
   const confirmContext = destructive ? 'danger' : (context ?? 'primary')
-  const confirmVariant = variant ?? 'solid'
+  const confirmVariant = 'solid'
 
   const fire = () => {
     void trigger(input)
@@ -143,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}
@@ -151,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

@@ -9,9 +9,9 @@
 import type { ReactNode } from 'react'
 import type { ViewAction } from '../../../core/index.ts'
 import { useViewAction } from '../../drivers/react.tsx'
-import { Alert } from '../primitives/alert.tsx'
+import { isBusinessError, isRetryable } from '../../lib/action-errors.ts'
 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>
@@ -20,12 +20,17 @@ 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
-  /** Renderiza loading. Default: 3 skeletons stackados. */
-  loading?: ReactNode
-  /** Renderiza erro. Default: mensagem + botão "Tentar de novo". */
-  error?: (err: { code: string; message: string }, retry: () => Promise<void>) => 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: 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
 }
 
 export function ActionView<TInput, TData>({
@@ -34,6 +39,7 @@ export function ActionView<TInput, TData>({
   children,
   render,
   empty,
+  emptyMessage,
   loading,
   error,
 }: ActionViewProps<TInput, TData>) {
@@ -44,17 +50,16 @@ export function ActionView<TInput, TData>({
   }
 
   if (isLoading) {
-    return (
-      <div data-action={action.name}>
-        {loading ?? (
-          <div className="space-y-3">
-            <Skeleton className="h-6 w-1/3" />
-            <Skeleton className="h-4 w-2/3" />
-            <Skeleton className="h-4 w-1/2" />
-          </div>
-        )}
+    const defaultLoading = (
+      <div className="space-y-3">
+        <Skeleton className="h-6 w-1/3" />
+        <Skeleton className="h-4 w-2/3" />
+        <Skeleton className="h-4 w-1/2" />
       </div>
     )
+    const loadingNode =
+      typeof loading === 'boolean' ? (loading ? defaultLoading : null) : (loading ?? defaultLoading)
+    return <div data-action={action.name}>{loadingNode}</div>
   }
 
   if (isError && err !== undefined) {
@@ -63,17 +68,19 @@ export function ActionView<TInput, TData>({
     }
     return (
       <div data-action={action.name}>
-        <Alert context="danger" title={err.code} description={err.message}>
-          <Button variant="outline" size="sm" onClick={() => void refetch()}>
-            Tentar de novo
-          </Button>
-        </Alert>
+        <ErrorSurface
+          title="Não foi possível carregar"
+          description={isBusinessError(err) ? err.message.trim() : undefined}
+          {...(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>

package/src/ui/components/primitives/alert.tsx

@@ -8,12 +8,9 @@ import {
 
 export type AlertContext = Exclude<UiContext, "primary">;
 export type AlertVariant = "subtle" | "outline";
-export type LegacyAlertVariant =
-  "default" | "destructive" | "success" | "warning" | "info" | "danger";
-
 interface AlertStyleOptions {
   context?: AlertContext | null;
-  variant?: AlertVariant | LegacyAlertVariant | null;
+  variant?: AlertVariant | null;
 }
 
 interface AlertRootContextValue {
@@ -47,29 +44,6 @@ function resolveAlertStyle({ context, variant }: AlertStyleOptions = {}): {
   context: AlertContext;
   variant: AlertVariant;
 } {
-  const legacy =
-    variant === "default" ||
-    variant === "destructive" ||
-    variant === "success" ||
-    variant === "warning" ||
-    variant === "info" ||
-    variant === "danger";
-  if (context != null && legacy) {
-    throw new Error(
-      "Alert não permite combinar context com uma variante semântica legada.",
-    );
-  }
-  if (variant === "default") return { context: "neutral", variant: "subtle" };
-  if (variant === "destructive")
-    return { context: "danger", variant: "subtle" };
-  if (
-    variant === "success" ||
-    variant === "warning" ||
-    variant === "info" ||
-    variant === "danger"
-  ) {
-    return { context: variant, variant: "subtle" };
-  }
   return { context: context ?? "neutral", variant: variant ?? "subtle" };
 }
 

package/src/ui/components/primitives/ask.tsx

@@ -115,7 +115,7 @@ export function Ask({
                           type="button"
                           size="sm"
                           shape="pill"
-                          context={selected ? 'neutral' : 'primary'}
+                          context={selected ? 'primary' : 'neutral'}
                           variant={selected ? 'solid' : 'outline'}
                           role={question.multiSelect ? undefined : 'radio'}
                           aria-checked={question.multiSelect ? undefined : selected}
@@ -159,7 +159,7 @@ export function Ask({
                     disabled={locked}
                   />
                   {invalid && (
-                    <p id={errorId} className="text-sm text-destructive">
+                    <p id={errorId} className="text-sm text-context-danger-emphasis">
                       Escolha uma opção ou escreva uma resposta.
                     </p>
                   )}
@@ -169,7 +169,7 @@ export function Ask({
           </div>
         </TooltipProvider>
         {!validCount && (
-          <p role="alert" className="mt-3 text-sm text-destructive">
+          <p role="alert" className="mt-3 text-sm text-context-danger-emphasis">
             Ask aceita de 1 a 4 perguntas.
           </p>
         )}

package/src/ui/components/primitives/avatar.tsx

@@ -2,20 +2,26 @@ import * as React from "react"
 import { Avatar as AvatarPrimitive } from "radix-ui"
 
 import { cn } from '../../lib/cn.ts'
+import type { ControlSize } from './control.ts'
 
+/**
+ * Ejetado (14.0.0): `size` segue a escala de control.ts — o avatar de uma linha `sm` mede o
+ * mesmo que o controle `sm` ao lado (2rem); `xs` (1.5rem) é a lista densa; `default` (2.25rem)
+ * e `lg` (2.5rem) pareiam com Button/Input. O fallback e o selo acompanham o tamanho.
+ */
 function Avatar({
   className,
   size = "default",
   ...props
 }: React.ComponentProps<typeof AvatarPrimitive.Root> & {
-  size?: "default" | "sm" | "lg"
+  size?: ControlSize
 }) {
   return (
     <AvatarPrimitive.Root
       data-slot="avatar"
       data-size={size}
       className={cn(
-        "group/avatar relative flex size-8 shrink-0 overflow-hidden rounded-full select-none data-[size=lg]:size-10 data-[size=sm]:size-6",
+        "group/avatar relative flex shrink-0 overflow-hidden rounded-full select-none data-[size=xs]:size-6 data-[size=sm]:size-8 data-[size=default]:size-9 data-[size=lg]:size-10",
         className
       )}
       {...props}
@@ -44,7 +50,7 @@ function AvatarFallback({
     <AvatarPrimitive.Fallback
       data-slot="avatar-fallback"
       className={cn(
-        "flex size-full items-center justify-center rounded-full bg-muted text-sm text-muted-foreground group-data-[size=sm]/avatar:text-xs",
+        "flex size-full items-center justify-center rounded-full bg-muted text-sm text-muted-foreground group-data-[size=xs]/avatar:text-xs group-data-[size=sm]/avatar:text-xs",
         className
       )}
       {...props}
@@ -58,7 +64,8 @@ function AvatarBadge({ className, ...props }: React.ComponentProps<"span">) {
       data-slot="avatar-badge"
       className={cn(
         "absolute right-0 bottom-0 z-10 inline-flex items-center justify-center rounded-full bg-primary text-primary-foreground ring-2 ring-background select-none",
-        "group-data-[size=sm]/avatar:size-2 group-data-[size=sm]/avatar:[&>svg]:hidden",
+        "group-data-[size=xs]/avatar:size-2 group-data-[size=xs]/avatar:[&>svg]:hidden",
+        "group-data-[size=sm]/avatar:size-2.5 group-data-[size=sm]/avatar:[&>svg]:size-2",
         "group-data-[size=default]/avatar:size-2.5 group-data-[size=default]/avatar:[&>svg]:size-2",
         "group-data-[size=lg]/avatar:size-3 group-data-[size=lg]/avatar:[&>svg]:size-2",
         className
@@ -89,7 +96,10 @@ function AvatarGroupCount({
     <div
       data-slot="avatar-group-count"
       className={cn(
-        "relative flex size-8 shrink-0 items-center justify-center rounded-full bg-muted text-sm text-muted-foreground ring-2 ring-background group-has-data-[size=lg]/avatar-group:size-10 group-has-data-[size=sm]/avatar-group:size-6 [&>svg]:size-4 group-has-data-[size=lg]/avatar-group:[&>svg]:size-5 group-has-data-[size=sm]/avatar-group:[&>svg]:size-3",
+        "relative flex size-9 shrink-0 items-center justify-center rounded-full bg-muted text-sm text-muted-foreground ring-2 ring-background [&>svg]:size-4",
+        "group-has-data-[size=xs]/avatar-group:size-6 group-has-data-[size=xs]/avatar-group:[&>svg]:size-3",
+        "group-has-data-[size=sm]/avatar-group:size-8 group-has-data-[size=sm]/avatar-group:[&>svg]:size-3.5",
+        "group-has-data-[size=lg]/avatar-group:size-10 group-has-data-[size=lg]/avatar-group:[&>svg]:size-5",
         className
       )}
       {...props}

package/src/ui/components/primitives/badge.tsx

@@ -3,6 +3,7 @@ import { Slot } from '@radix-ui/react-slot'
 
 import type { UiContext } from '../../../core/ui-context.ts'
 import { cn } from '../../lib/cn.ts'
+import { focusRing } from './control.ts'
 import {
   semanticOutlineClasses,
   semanticSolidClasses,
@@ -11,56 +12,19 @@ import {
 
 export type BadgeContext = UiContext
 export type BadgeVariant = 'solid' | 'subtle' | 'outline'
-export type LegacyBadgeVariant =
-  | 'default'
-  | 'secondary'
-  | 'destructive'
-  | 'success'
-  | 'warning'
-  | 'info'
-  | 'danger'
-
 export interface BadgeStyleOptions {
   context?: BadgeContext | null
-  variant?: BadgeVariant | LegacyBadgeVariant | null
+  variant?: BadgeVariant | null
 }
 
 const baseClasses =
-  'inline-flex w-fit shrink-0 items-center justify-center gap-1 overflow-hidden whitespace-nowrap rounded-md border px-2 py-0.5 text-xs font-medium transition-[color,box-shadow] focus-visible:border-ring focus-visible:ring-2 focus-visible:ring-ring/50 aria-invalid:border-context-danger aria-invalid:ring-context-danger/20 [&>svg]:pointer-events-none [&>svg]:size-3'
+  'inline-flex w-fit shrink-0 items-center justify-center gap-1 overflow-hidden whitespace-nowrap rounded-md border px-2 py-0.5 text-xs font-medium transition-[color,box-shadow] aria-invalid:border-context-danger aria-invalid:ring-context-danger/20 [&>svg]:pointer-events-none [&>svg]:size-3'
 
 export function resolveBadgeStyle({
   context,
   variant,
 }: BadgeStyleOptions = {}): { context: BadgeContext; variant: BadgeVariant } {
-  const legacy =
-    variant === 'default' ||
-    variant === 'secondary' ||
-    variant === 'destructive' ||
-    variant === 'success' ||
-    variant === 'warning' ||
-    variant === 'info' ||
-    variant === 'danger'
-  if (context != null && legacy) {
-    throw new Error('Badge não permite combinar context com uma variante semântica legada.')
-  }
-  switch (variant) {
-    case 'default':
-      return { context: 'primary', variant: 'solid' }
-    case 'secondary':
-      return { context: 'neutral', variant: 'solid' }
-    case 'destructive':
-      return { context: 'danger', variant: 'solid' }
-    case 'success':
-    case 'warning':
-    case 'info':
-    case 'danger':
-      return { context: variant, variant: 'subtle' }
-    default:
-      return {
-        context: context ?? 'neutral',
-        variant: variant ?? 'subtle',
-      }
-  }
+  return { context: context ?? 'neutral', variant: variant ?? 'subtle' }
 }
 
 /** Classes do Badge. Contexto seleciona significado; variante seleciona o tratamento visual. */
@@ -72,7 +36,7 @@ export function badgeVariants(options: BadgeStyleOptions = {}): string {
       : resolved.variant === 'outline'
         ? semanticOutlineClasses[resolved.context]
         : semanticSubtleClasses[resolved.context]
-  return cn(baseClasses, classes)
+  return cn(baseClasses, focusRing, classes)
 }
 
 export interface BadgeProps extends React.ComponentProps<'span'>, BadgeStyleOptions {

package/src/ui/components/primitives/breadcrumb.tsx

@@ -5,7 +5,7 @@ import { Slot } from "radix-ui"
 import { cn } from '../../lib/cn.ts'
 
 function Breadcrumb({ ...props }: React.ComponentProps<"nav">) {
-  return <nav aria-label="breadcrumb" data-slot="breadcrumb" {...props} />
+  return <nav aria-label="Navegação estrutural" data-slot="breadcrumb" {...props} />
 }
 
 function BreadcrumbList({ className, ...props }: React.ComponentProps<"ol">) {
@@ -93,7 +93,7 @@ function BreadcrumbEllipsis({
       {...props}
     >
       <MoreHorizontal className="size-4" />
-      <span className="sr-only">More</span>
+      <span className="sr-only">Mais</span>
     </span>
   )
 }