@softize/opus 13.0.0 → 14.0.0

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

@@ -67,18 +67,12 @@ function MenuItem({
   className,
   inset,
   context,
-  variant,
   ...props
 }: React.ComponentProps<typeof MenuPrimitive.Item> & {
   inset?: boolean
   context?: Extract<UiContext, 'neutral' | 'danger'>
-  /** @deprecated Use `context="danger"`. */
-  variant?: "default" | "destructive"
 }) {
-  if (context !== undefined && variant !== undefined) {
-    throw new Error('MenuItem não permite combinar context com uma variante semântica legada.')
-  }
-  const resolvedContext = context ?? (variant === 'destructive' ? 'danger' : 'neutral')
+  const resolvedContext = context ?? 'neutral'
   return (
     <MenuPrimitive.Item
       data-slot="menu-item"

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

@@ -3,6 +3,7 @@ import { ChevronLeftIcon, ChevronRightIcon, MoreHorizontalIcon } from 'lucide-re
 
 import { cn } from '../../lib/cn.ts'
 import { buttonVariants, type ButtonProps } from './button.tsx'
+import { controlSquare, type ControlIconSize } from './control.ts'
 
 function Pagination({ className, ...props }: React.ComponentProps<'nav'>) {
   return (
@@ -33,8 +34,8 @@ function PaginationItem({ ...props }: React.ComponentProps<'li'>) {
 export interface PaginationLinkProps extends Omit<React.ComponentProps<'a'>, 'children'> {
   /** Página atual: vira `outline` e ganha `aria-current="page"`. */
   isActive?: boolean
-  /** Escala do Button. `default` (números: altura fixa, largura mínima quadrada que cresce
-   *  com os dígitos) ou uma escala `icon*` (setas quadradas, sem padding horizontal). */
+  /** A escala de control.ts, via Button. `default` (números: altura fixa, largura mínima
+   *  quadrada que cresce com os dígitos) ou um `icon*` (setas quadradas, sem padding). */
   size?: ButtonProps['size']
   /** Número da página: dá o nome acessível (“Página N”) e o conteúdo, quando `children` falta. */
   page?: number
@@ -83,10 +84,11 @@ function PaginationLink({ className, isActive, page, disabled, href, size = 'def
 export interface PaginationControlProps extends Omit<PaginationLinkProps, 'page' | 'isActive'> {
   /** Nome acessível e texto visível. Default: “Página anterior” / “Próxima página”. */
   label?: string
-  /** Só a seta, quadrada (escala `icon`, `size-9`); o `label` continua como nome acessível. */
+  /** Só a seta, quadrada (`icon`, 2.25rem; `size="icon-sm"` para o rodapé denso); o `label`
+   *  continua como nome acessível. */
   iconOnly?: boolean
-  /** Classe do ícone (ex.: `size-3.5` na escala densa). Vai no próprio svg, porque o
-   *  fallback `[&_svg:not([class*='size-'])]:size-4` do Button vence qualquer seletor de fora. */
+  /** Classe do ícone, quando o glifo da escala não servir. Vai no próprio svg, porque o
+   *  fallback `[&_svg:not([class*=size-])]` do Button vence qualquer seletor de fora. */
   iconClassName?: string
 }
 
@@ -132,16 +134,22 @@ function PaginationNext({
   )
 }
 
+export interface PaginationEllipsisProps extends React.ComponentProps<'span'> {
+  /** O quadrado da escala de control.ts — o mesmo das setas ao lado. */
+  size?: ControlIconSize
+}
+
 /** Decorativa: `aria-hidden`; os números ao redor já dizem que há páginas no vão. */
-function PaginationEllipsis({ className, ...props }: React.ComponentProps<'span'>) {
+function PaginationEllipsis({ className, size = 'icon', ...props }: PaginationEllipsisProps) {
   return (
     <span
       aria-hidden
       data-slot="pagination-ellipsis"
-      className={cn('flex size-9 items-center justify-center', className)}
+      data-size={size}
+      className={cn('flex items-center justify-center', controlSquare[size], className)}
       {...props}
     >
-      <MoreHorizontalIcon className="size-4" />
+      <MoreHorizontalIcon className={size === 'icon-xs' || size === 'icon-sm' ? 'size-3.5' : 'size-4'} />
     </span>
   )
 }

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

@@ -1,25 +1,54 @@
 import * as React from "react"
 import { Progress as ProgressPrimitive } from "radix-ui"
 
+import type { UiContext } from '../../../core/ui-context.ts'
 import { cn } from '../../lib/cn.ts'
 
+export type ProgressContext = UiContext
+
+const trackClasses: Record<ProgressContext, string> = {
+  neutral: 'bg-context-neutral-subtle',
+  primary: 'bg-context-primary/20',
+  info: 'bg-context-info/20',
+  success: 'bg-context-success/20',
+  warning: 'bg-context-warning/20',
+  danger: 'bg-context-danger/20',
+}
+
+const indicatorClasses: Record<ProgressContext, string> = {
+  neutral: 'bg-context-neutral-emphasis',
+  primary: 'bg-context-primary',
+  info: 'bg-context-info',
+  success: 'bg-context-success',
+  warning: 'bg-context-warning',
+  danger: 'bg-context-danger',
+}
+
+export interface ProgressProps extends React.ComponentProps<typeof ProgressPrimitive.Root> {
+  /** O que o andamento comunica: `success` para meta atingida, `warning`/`danger` para atenção. */
+  context?: ProgressContext
+}
+
 function Progress({
   className,
   value,
+  context = 'primary',
   ...props
-}: React.ComponentProps<typeof ProgressPrimitive.Root>) {
+}: ProgressProps) {
   return (
     <ProgressPrimitive.Root
       data-slot="progress"
+      data-context={context}
       className={cn(
-        "relative h-2 w-full overflow-hidden rounded-full bg-primary/20",
+        "relative h-2 w-full overflow-hidden rounded-full",
+        trackClasses[context],
         className
       )}
       {...props}
     >
       <ProgressPrimitive.Indicator
         data-slot="progress-indicator"
-        className="h-full w-full flex-1 bg-primary transition-all"
+        className={cn("h-full w-full flex-1 transition-all", indicatorClasses[context])}
         style={{ transform: `translateX(-${100 - (value || 0)}%)` }}
       />
     </ProgressPrimitive.Root>

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

@@ -25,7 +25,7 @@ function RadioGroupItem({
     <RadioGroupPrimitive.Item
       data-slot="radio-group-item"
       className={cn(
-        "aspect-square size-4 shrink-0 rounded-full border border-input text-primary transition-[color,box-shadow] outline-none focus-visible:border-ring focus-visible:ring-[0.1875rem] focus-visible:ring-ring/50 disabled:cursor-not-allowed disabled:opacity-50 aria-invalid:border-destructive aria-invalid:ring-destructive/20 dark:bg-input/30 dark:aria-invalid:ring-destructive/40",
+        "aspect-square size-4 shrink-0 rounded-full border border-input text-primary transition-[color,box-shadow] outline-none focus-visible:border-ring focus-visible:ring-[0.1875rem] focus-visible:ring-ring/50 disabled:cursor-not-allowed disabled:opacity-50 aria-invalid:border-context-danger aria-invalid:ring-context-danger/20 dark:bg-input/30 dark:aria-invalid:ring-context-danger/40",
         className
       )}
       {...props}

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

@@ -2,6 +2,7 @@ import { GripVerticalIcon } from "lucide-react"
 import * as ResizablePrimitive from "react-resizable-panels"
 
 import { cn } from '../../lib/cn.ts'
+import { focusRing } from './control.ts'
 
 function ResizablePanelGroup({
   className,
@@ -34,7 +35,8 @@ function ResizableHandle({
     <ResizablePrimitive.Separator
       data-slot="resizable-handle"
       className={cn(
-        "relative flex w-px items-center justify-center bg-border after:absolute after:inset-y-0 after:left-1/2 after:w-1 after:-translate-x-1/2 focus-visible:ring-1 focus-visible:ring-ring focus-visible:ring-offset-1 focus-visible:outline-hidden aria-[orientation=horizontal]:h-px aria-[orientation=horizontal]:w-full aria-[orientation=horizontal]:after:left-0 aria-[orientation=horizontal]:after:h-1 aria-[orientation=horizontal]:after:w-full aria-[orientation=horizontal]:after:translate-x-0 aria-[orientation=horizontal]:after:-translate-y-1/2 [&[aria-orientation=horizontal]>div]:rotate-90",
+        "relative flex w-px items-center justify-center bg-border after:absolute after:inset-y-0 after:left-1/2 after:w-1 after:-translate-x-1/2 focus-visible:outline-hidden aria-[orientation=horizontal]:h-px aria-[orientation=horizontal]:w-full aria-[orientation=horizontal]:after:left-0 aria-[orientation=horizontal]:after:h-1 aria-[orientation=horizontal]:after:w-full aria-[orientation=horizontal]:after:translate-x-0 aria-[orientation=horizontal]:after:-translate-y-1/2 [&[aria-orientation=horizontal]>div]:rotate-90",
+        focusRing,
         className
       )}
       {...props}

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

@@ -25,7 +25,7 @@ import { Check, ChevronDownIcon, SearchIcon, X } from 'lucide-react'
 import { Command as CommandPrimitive } from 'cmdk'
 
 import { cn } from '../../lib/cn.ts'
-import type { ControlShape } from './control.ts'
+import { focusRing, focusRingWithin, type ControlShape, type ControlSize } from './control.ts'
 import { CommandEmpty, CommandGroup, CommandItem, CommandList } from './command.tsx'
 import { Popover, PopoverAnchor, PopoverContent } from './popover.tsx'
 
@@ -60,7 +60,7 @@ interface SelectBaseProps {
   'aria-invalid'?: boolean
   'aria-describedby'?: string
   /** Altura: `default` (h-9, a do Input/Button) ou `sm` (h-8) pra toolbar densa. */
-  size?: 'sm' | 'default'
+  size?: Extract<ControlSize, 'sm' | 'default'>
   /** Geometria do controle; `pill` preserva a variante visual escolhida. */
   shape?: ControlShape
   'aria-label'?: string
@@ -162,8 +162,8 @@ function NativeSelect({
         onChange={(e) => onChange(e.target.value)}
         className={cn(
           "h-9 w-full min-w-0 appearance-none rounded-md border border-input bg-transparent px-3 py-2 pr-9 text-sm transition-[color,box-shadow] outline-none selection:bg-primary selection:text-primary-foreground disabled:pointer-events-none disabled:cursor-not-allowed data-[size=sm]:h-8 data-[size=sm]:py-1 data-[shape=pill]:rounded-full dark:bg-input/30 dark:hover:bg-input/50",
-          'focus-visible:border-ring focus-visible:ring-[0.1875rem] focus-visible:ring-ring/50',
-          'aria-invalid:border-destructive aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40',
+          focusRing,
+          'aria-invalid:border-context-danger aria-invalid:ring-context-danger/20 dark:aria-invalid:ring-context-danger/40',
           icon ? 'pl-9' : '',
         )}
       >
@@ -359,8 +359,8 @@ function CustomSelect(props: Exclude<SelectProps, SelectNativeProps>): React.Rea
               className={cn(
                 'flex items-center gap-1.5 rounded-md outline-none transition-[color,box-shadow] data-[shape=pill]:rounded-full',
                 ghost
-                  ? 'min-h-9 px-3 py-1 text-muted-foreground hover:bg-muted hover:text-foreground focus-within:ring-2 focus-within:ring-ring/50 data-[size=sm]:min-h-8 data-[size=sm]:px-2'
-                  : "min-h-9 border border-input bg-transparent px-3 py-1 focus-within:border-ring focus-within:ring-2 focus-within:ring-ring/50 aria-invalid:border-destructive aria-invalid:ring-destructive/20 data-[size=sm]:min-h-8 data-[size=sm]:py-0.5 dark:bg-input/30 dark:aria-invalid:ring-destructive/40",
+                  ? cn('min-h-9 px-3 py-1 text-muted-foreground hover:bg-muted hover:text-foreground data-[size=sm]:min-h-8 data-[size=sm]:px-2', focusRingWithin)
+                  : cn('min-h-9 border border-input bg-transparent px-3 py-1 aria-invalid:border-context-danger aria-invalid:ring-context-danger/20 data-[size=sm]:min-h-8 data-[size=sm]:py-0.5 dark:bg-input/30 dark:aria-invalid:ring-context-danger/40', focusRingWithin),
                 variant === 'default' && 'flex-wrap',
                 outline && 'hover:bg-accent hover:text-accent-foreground dark:hover:bg-input/50',
                 "[&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",

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

@@ -2,6 +2,7 @@ import * as React from "react"
 import { Slider as SliderPrimitive } from "radix-ui"
 
 import { cn } from '../../lib/cn.ts'
+import { focusRing } from './control.ts'
 
 function Slider({
   className,
@@ -51,7 +52,10 @@ function Slider({
         <SliderPrimitive.Thumb
           data-slot="slider-thumb"
           key={index}
-          className="block size-4 shrink-0 rounded-full border border-primary bg-white shadow-sm ring-ring/50 transition-[color,box-shadow] hover:ring-4 focus-visible:ring-4 focus-visible:outline-hidden disabled:pointer-events-none disabled:opacity-50"
+          className={cn(
+            "block size-4 shrink-0 rounded-full border border-primary bg-background shadow-sm transition-[color,box-shadow] hover:ring-[0.1875rem] hover:ring-ring/50 focus-visible:outline-hidden disabled:pointer-events-none disabled:opacity-50",
+            focusRing,
+          )}
         />
       ))}
     </SliderPrimitive.Root>

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

@@ -170,6 +170,9 @@ export function Toaster({
     <Sonner
       data-slot="toaster"
       theme="system"
+      // O sonner 1.x só expõe o rótulo da região; o do botão de fechar ("Close toast") vem
+      // com o 2.x (`closeButtonAriaLabel`).
+      containerAriaLabel="Notificações"
       className={cn('toaster group', className)}
       icons={{
         success: (

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

@@ -1,28 +1,25 @@
 import * as React from 'react'
 import { Loader2Icon } from 'lucide-react'
-import { cva, type VariantProps } from 'class-variance-authority'
 import { cn } from '../../lib/cn.ts'
+import { controlGlyph, type ControlSize } from './control.ts'
 
-/** Tamanhos do spinner — divergência da casa (o shadcn atual só tem `size-4` fixo).
- *  Mantido aditivo pra cobrir botão (sm) e estados maiores (lg). */
-const spinnerVariants = cva('animate-spin', {
-  variants: {
-    size: { sm: 'size-3', default: 'size-4', lg: 'size-6' },
-  },
-  defaultVariants: { size: 'default' },
-})
-
-export interface SpinnerProps extends React.ComponentProps<'svg'>, VariantProps<typeof spinnerVariants> {}
+export interface SpinnerProps extends React.ComponentProps<'svg'> {
+  /** O glifo do controle daquele tamanho na escala de control.ts (`sm` cabe num Button sm). */
+  size?: ControlSize | null
+}
 
-/** Indicador de carregamento (Loader2Icon girando) — substitui o `<Loader2Icon className="animate-spin"/>`
- *  inline repetido. Tamanhos sm/default/lg. Pra placeholder de conteúdo, use Skeleton. */
+/**
+ * Indicador de carregamento (Loader2Icon girando) — substitui o `<Loader2Icon
+ * className="animate-spin"/>` inline repetido. É decorativo: quem nomeia a espera é o contêiner
+ * (`role="status"` em DataState, PageState ou no seu) ou o texto ao lado; assim a superfície
+ * carrega um status só, sem role duplicado. Pra placeholder de conteúdo, use Skeleton.
+ */
 export function Spinner({ className, size, ...props }: SpinnerProps): React.ReactElement {
   return (
     <Loader2Icon
       data-slot="spinner"
-      role="status"
-      aria-label="Carregando"
-      className={cn(spinnerVariants({ size }), className)}
+      aria-hidden="true"
+      className={cn('animate-spin', controlGlyph[size ?? 'default'], className)}
       {...props}
     />
   )

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

@@ -2,13 +2,16 @@ import * as React from "react"
 import { Switch as SwitchPrimitive } from "radix-ui"
 
 import { cn } from '../../lib/cn.ts'
+import type { ControlSize } from './control.ts'
 
+/** `size` usa os nomes da escala de control.ts; a chave é um trilho (não uma linha), então a
+ *  medida é a do glifo daquele tamanho: `sm` acompanha o svg de um controle sm (0.875rem). */
 function Switch({
   className,
   size = "default",
   ...props
 }: React.ComponentProps<typeof SwitchPrimitive.Root> & {
-  size?: "sm" | "default"
+  size?: Extract<ControlSize, "sm" | "default">
 }) {
   return (
     <SwitchPrimitive.Root
@@ -22,6 +25,7 @@ function Switch({
     >
       <SwitchPrimitive.Thumb
         data-slot="switch-thumb"
+        // px: o percurso do thumb desconta a borda (um pixel de cada lado) no calc do translate.
         className={cn(
           "pointer-events-none block rounded-full bg-background ring-0 transition-transform group-data-[size=default]/switch:size-4 group-data-[size=sm]/switch:size-3 data-[state=checked]:translate-x-[calc(100%-2px)] data-[state=unchecked]:translate-x-0 dark:data-[state=checked]:bg-primary-foreground dark:data-[state=unchecked]:bg-foreground"
         )}

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

@@ -3,11 +3,13 @@ import { cva, type VariantProps } from "class-variance-authority"
 import { Tabs as TabsPrimitive } from "radix-ui"
 
 import { cn } from '../../lib/cn.ts'
+import { controlHeight, type ControlSize } from './control.ts'
 
 // Divergência da casa (ejetado): o Tabs ganhou `size` — Button e Select têm `sm`, o Tabs
 // não tinha, e uma fileira densa ficava com o segmento 0.25rem mais alto
-// que os irmãos. O tamanho flui pra TabsList via contexto (a altura é dela).
-type TabsSize = "default" | "sm"
+// que os irmãos. O tamanho flui pra TabsList via contexto (a altura é dela) e a medida é a
+// da escala de control.ts.
+type TabsSize = Extract<ControlSize, "default" | "sm">
 const TabsSizeContext = React.createContext<TabsSize>("default")
 
 function Tabs({
@@ -64,7 +66,7 @@ function TabsList({
       data-slot="tabs-list"
       data-variant={variant}
       data-size={size}
-      className={cn(tabsListVariants({ variant }), size === "sm" ? "h-8" : "h-9", className)}
+      className={cn(tabsListVariants({ variant }), controlHeight[size], className)}
       {...props}
     />
   )
@@ -77,6 +79,7 @@ function TabsTrigger({
   return (
     <TabsPrimitive.Trigger
       data-slot="tabs-trigger"
+      // px: altura e indicador compensam a hairline do contêiner (um pixel físico, não escala).
       className={cn(
         "relative inline-flex h-[calc(100%-1px)] flex-1 items-center justify-center gap-1.5 rounded-md border border-transparent px-2 py-1 text-sm font-medium whitespace-nowrap text-foreground/60 transition-all group-data-[orientation=vertical]/tabs:w-full group-data-[orientation=vertical]/tabs:justify-start hover:text-foreground focus-visible:border-ring focus-visible:ring-[0.1875rem] focus-visible:ring-ring/50 focus-visible:outline-1 focus-visible:outline-ring disabled:pointer-events-none disabled:opacity-50 group-data-[variant=default]/tabs-list:data-[state=active]:shadow-sm group-data-[variant=line]/tabs-list:data-[state=active]:shadow-none dark:text-muted-foreground dark:hover:text-foreground [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
         "group-data-[variant=line]/tabs-list:bg-transparent group-data-[variant=line]/tabs-list:data-[state=active]:bg-transparent dark:group-data-[variant=line]/tabs-list:data-[state=active]:border-transparent dark:group-data-[variant=line]/tabs-list:data-[state=active]:bg-transparent",

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

@@ -7,7 +7,7 @@ function Textarea({ className, ...props }: React.ComponentProps<"textarea">) {
     <textarea
       data-slot="textarea"
       className={cn(
-        "flex field-sizing-content min-h-16 w-full rounded-md border border-input bg-transparent px-3 py-2 text-base transition-[color,box-shadow] outline-none placeholder:text-muted-foreground focus-visible:border-ring focus-visible:ring-[0.1875rem] focus-visible:ring-ring/50 disabled:cursor-not-allowed disabled:opacity-50 aria-invalid:border-destructive aria-invalid:ring-destructive/20 md:text-sm dark:bg-input/30 dark:aria-invalid:ring-destructive/40",
+        "flex field-sizing-content min-h-16 w-full rounded-md border border-input bg-transparent px-3 py-2 text-base transition-[color,box-shadow] outline-none placeholder:text-muted-foreground focus-visible:border-ring focus-visible:ring-[0.1875rem] focus-visible:ring-ring/50 disabled:cursor-not-allowed disabled:opacity-50 aria-invalid:border-context-danger aria-invalid:ring-context-danger/20 md:text-sm dark:bg-input/30 dark:aria-invalid:ring-context-danger/40",
         className
       )}
       {...props}

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

@@ -3,9 +3,13 @@ import { cva, type VariantProps } from "class-variance-authority"
 import { Toggle as TogglePrimitive } from "radix-ui"
 
 import { cn } from '../../lib/cn.ts'
+import { controlHeight, focusRing } from './control.ts'
 
 const toggleVariants = cva(
-  "inline-flex items-center justify-center gap-2 rounded-md text-sm font-medium whitespace-nowrap transition-[color,box-shadow] outline-none hover:bg-muted hover:text-muted-foreground focus-visible:border-ring focus-visible:ring-[0.1875rem] focus-visible:ring-ring/50 disabled:pointer-events-none disabled:opacity-50 aria-invalid:border-destructive aria-invalid:ring-destructive/20 data-[state=on]:bg-accent data-[state=on]:text-accent-foreground dark:aria-invalid:ring-destructive/40 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
+  [
+    "inline-flex items-center justify-center gap-2 rounded-md text-sm font-medium whitespace-nowrap transition-[color,box-shadow] outline-none hover:bg-muted hover:text-muted-foreground disabled:pointer-events-none disabled:opacity-50 aria-invalid:border-context-danger aria-invalid:ring-context-danger/20 data-[state=on]:bg-accent data-[state=on]:text-accent-foreground dark:aria-invalid:ring-context-danger/40 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
+    focusRing,
+  ],
   {
     variants: {
       variant: {
@@ -13,10 +17,11 @@ const toggleVariants = cva(
         outline:
           "border border-input bg-transparent hover:bg-accent hover:text-accent-foreground",
       },
+      // Alturas da escala de control.ts (`sm` = o mesmo h-8 de Button e Select).
       size: {
-        default: "h-9 min-w-9 px-2",
-        sm: "h-8 min-w-8 px-1.5",
-        lg: "h-10 min-w-10 px-2.5",
+        default: `${controlHeight.default} min-w-9 px-2`,
+        sm: `${controlHeight.sm} min-w-8 px-1.5`,
+        lg: `${controlHeight.lg} min-w-10 px-2.5`,
       },
       shape: {
         default: '',

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

@@ -46,6 +46,7 @@ function TooltipContent({
         {...props}
       >
         {children}
+        {/* px: a seta sobe dois pixels para encaixar na borda do conteúdo, independente da fonte. */}
         <TooltipPrimitive.Arrow className="z-50 size-2.5 translate-y-[calc(-50%_-_2px)] rotate-45 rounded-[0.125rem] bg-foreground fill-foreground" />
       </TooltipPrimitive.Content>
     </TooltipPrimitive.Portal>

package/src/ui/docs/changelog.tsx

@@ -54,7 +54,7 @@ export function ChangelogView({ source }: { source: string }): React.ReactElemen
             <div className="flex flex-wrap items-baseline gap-x-3 gap-y-1">
               <h2 className="text-xl font-semibold tracking-tight">{v.version}</h2>
               {v.date !== undefined && <span className="text-sm text-muted-foreground">{v.date}</span>}
-              {v.breaking !== undefined && <Badge context="danger" variant="solid">Breaking</Badge>}
+              {v.breaking !== undefined && <Badge context="danger" variant="solid">Incompatível</Badge>}
             </div>
             {v.body.length > 0 && (
               <div className="mt-3">

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

@@ -55,12 +55,19 @@ Monte os providers de consulta e execução uma vez na raiz do aplicativo:
 ```tsx
 /* main.tsx do app. */
 <QueryClientProvider client={queryClient}>
-  <TbdlibProvider client={apiClient}>
+  <OpusProvider client={apiClient}>
     <App />
-  </TbdlibProvider>
+  </OpusProvider>
 </QueryClientProvider>
 ```
 
+## useFormAction
+
+`ActionForm` é uma composição sobre `useFormAction(action, { defaultValues, onSuccess, onError })`,
+que devolve o `form` do react-hook-form já com o resolver Zod em pt-BR, `submit`, `isLoading`,
+`error`, `isSuccess` e `reset`. Use o hook direto quando o formulário precisar de um layout ou de um
+ciclo de vida que o pattern não cobre; validação e execução continuam iguais.
+
 ## Propriedades de ActionForm
 
 | Propriedade | Tipo | Padrão | Descrição |
@@ -81,11 +88,37 @@ Monte os providers de consulta e execução uma vez na raiz do aplicativo:
 | `options` | `SelectOption[]` | Opções por id de runtime — sobrepõe o fieldOptions do form e o z.enum. |
 | `className` | `string` | Classes do invólucro (ex.: `col-span-2` em uma grid). |
 
+## Ajuda na label
+
+`FieldSpec.help` aparece como um ícone junto à label, com o texto num tooltip. Escreva ali o
+critério, o efeito ou a limitação que a label não diz; ajuda que só repete a label deve ser omitida.
+Não existe texto auxiliar sob o campo: quem precisa de uma frase permanente abaixo do controle usa
+`FieldDescription` na composição própria.
+
+`LabelHelp` é esse mesmo ícone, exportado para um formulário sem contrato mostrar a ajuda no mesmo
+lugar:
+
+```tsx preview col md
+<Field>
+  <FieldLabel htmlFor="staff" className="items-center gap-1.5">
+    <span>Staff</span>
+    <LabelHelp help="Tem acesso ao back-office e a todos os workspaces." />
+  </FieldLabel>
+  <Input id="staff" placeholder="Empresa X" />
+</Field>
+```
+
+### Propriedades de LabelHelp
+
+| Propriedade | Tipo | Descrição |
+|---|---|---|
+| `help` | `string` | O texto do tooltip. Vazio ou ausente, o ícone não renderiza. |
+
 ## Origem das opções de seleção
 
 As opções seguem esta precedência: `options` no campo, `fieldOptions` no formulário, `options` no
 `FieldSpec`, metadata de `t.dict` no schema e, por último, as chaves de `z.enum`. Uma fonte mais
-específica substitui as seguintes. Dicionários registrados no `TbdlibProvider` resolvem rótulos por
+específica substitui as seguintes. Dicionários registrados no `OpusProvider` resolvem rótulos por
 referência; itens estáticos permanecem como declarados no contrato.
 
 ## Widgets declarativos

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

@@ -23,7 +23,7 @@ render(
           <Plus /> Workspace
         </Button>
       }
-      emptyText="Nenhum workspace."
+      emptyMessage="Nenhum workspace."
     >
       {(workspaces) => (
         <div className="space-y-2">
@@ -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ã). |
-| `emptyText / errorText` | `string` | | Textos dos estados (DataState). |
+| `emptyMessage / errorMessage / retryLabel` | `string` | | Textos dos estados, repassados ao `ActionList` (e dele ao `DataState`). |
 | `className` | `string` | `sm:max-w-3xl` | Largura do DialogContent. |

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

@@ -97,6 +97,7 @@ periods: [
   { value: 'thisMonth', label: 'Este mês' },
 ]
 // Presets computáveis: today · yesterday · last7 · last30 · thisMonth · lastMonth.
+// presetRange('last7') → { from: 'YYYY-MM-DD', to: 'YYYY-MM-DD' } — o mesmo cálculo do pattern.
 ```
 
 ## Paginação e carregamento
@@ -171,7 +172,7 @@ render(
 - **`depends: ['outroFiltro']`:** desabilita o filtro até que suas dependências tenham valor e o
   limpa quando uma delas muda.
 - **`options: { kind: 'dictionary', ref: 'sessionStatus' }`:** resolve opções e rótulos por um
-  dicionário registrado no `TbdlibProvider`. `filterOptions` substitui essa fonte quando informado.
+  dicionário registrado no `OpusProvider`. `filterOptions` substitui essa fonte quando informado.
 - **`options: { kind: 'lookup', source: 'x.lookup' }`:** consulta uma action com `{ q }` e os valores
   das dependências. A resposta segue o formato `{ value, label }`.
 
@@ -244,6 +245,14 @@ render(
 | `sort` | `{ fields, default }` — ordenação inicial; header ordenável escreve `sort: 'chave:dir'`. |
 | `periods` | `{ value, label }[]` — o controle de período (presets + Personalizado com calendário); materializa em `from`/`to` no input. |
 
+## useListAction
+
+Quando o layout não cabe no `ActionList`, `useListAction(action, input)` entrega o mesmo fetch
+declarativo (`items`, `total`, `error`, `isLoading`, `isFetching`, `refetch`) sob o
+`QueryClientProvider`, e `presetRange(preset)` materializa os presets de período (`today`, `last7`,
+`thisMonth`…) em `{ from, to }` no formato `YYYY-MM-DD` — o mesmo cálculo que o pattern faz antes de
+chamar a action.
+
 ## Propriedades de ActionList
 
 | Propriedade | Tipo | Padrão | Descrição |
@@ -258,6 +267,8 @@ render(
 | `rowId` | `(item) => string` | `item.id` | Identidade da linha para seleção. |
 | `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.'` | O texto do estado vazio. |
+| `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. |
 | `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`. |

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

@@ -37,9 +37,9 @@ confirm: {
 
 ## Ação somente com ícone
 
-Com `icon`, o botão exibe somente o ícone e usa `label`, ou `action.label`, no tooltip e no nome
-acessível. O clique não aciona o item clicável ao redor. `itemLabel` identifica o registro na
-mensagem de confirmação.
+Com `icon`, o botão exibe somente o ícone no quadrado `icon-sm` da escala (1.75rem, a ação que mora
+dentro de uma linha ou card) e usa `label`, ou `action.label`, no tooltip e no nome acessível. O clique
+não aciona o item clicável ao redor. `itemLabel` identifica o registro na mensagem de confirmação.
 
 ```tsx
 <ActionTrigger
@@ -64,6 +64,13 @@ negócio `conflict`, `validation` e `not_found`:
 Erros inesperados mantêm a mensagem genérica do contrato, evitando expor detalhes de banco ou
 infraestrutura. O servidor registra o detalhe técnico para diagnóstico.
 
+## useTriggerAction
+
+`ActionTrigger` é uma composição sobre `useTriggerAction(action, { onSuccess, onError })`, que
+devolve `trigger(input)`, `isLoading`, `error` e `reset`, e invalida o cache declarado em
+`action.invalidates`. Use o hook direto quando a execução parte de um gesto que não é um botão —
+um atalho, um arrastar, um item de menu.
+
 ## Propriedades de ActionTrigger
 
 | Propriedade | Tipo | Padrão | Descrição |
@@ -71,9 +78,9 @@ infraestrutura. O servidor registra o detalhe técnico para diagnóstico.
 | `action` | `SimpleContract<TInput, TData>` | | A SimpleAction do Opus — label, messages e confirm vêm do contrato. |
 | `input` | `TInput` | | O que a action recebe — geralmente { id }. |
 | `label` | `string` | `action.label` | Sobrepõe o texto do botão. |
-| `variant / size` | `variants do Button` | `'default' (ou 'destructive' se o confirm declarar) / 'default'` | Visual do botão — o destructive do ConfirmSpec já escolhe sozinho. |
+| `context / variant / size` | `do Button` | gatilho: `primary`/`solid`; `danger` quando a action é `destructive`; no modo ícone, `ghost` e `neutral` (ou `danger` se destrutiva) / `default` | Visual do gatilho; `context` explícito vence. O botão de confirmar é sempre `solid`: `danger` quando a action é `destructive`, senão a prop `context` do gatilho (ou `primary`). |
 | `confirm` | `{ title, description?, actionLabel?, cancelLabel? }` | | Confirmação via prop — sobrepõe o ConfirmSpec do contrato. |
 | `onSuccess` | `(data: TData) => void` | | Pós-sucesso (cache já invalidado pelo action.invalidates). |
 | `icon` | `React.ReactNode` | | Torna o botão icon-only: rótulo no tooltip e no `aria-label`, clique que não vaza para o item. |
 | `itemLabel` | `string` | | Nome do alvo na pergunta (sai entre aspas, em destaque, antes da mensagem do contrato). |
-| `className` | `string` | | Classes do botão (ex.: apertar o tamanho em uma linha densa). |
+| `className` | `string` | | Classes do botão. O tamanho vem de `size` (escala única); com `icon` é sempre `icon-sm`. |

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

@@ -21,7 +21,7 @@ render(
             <div className="space-y-1.5">
               <div className="flex items-center gap-2">
                 <h3 className="text-sm font-semibold">{ws.name}</h3>
-                <Badge variant={ws.status === 'active' ? 'success' : 'warning'}>{ws.status}</Badge>
+                <Badge context={ws.status === 'active' ? 'success' : 'warning'}>{ws.status}</Badge>
               </div>
               <p className="text-sm text-muted-foreground">
                 Cliente {ws.client} · {ws.agents} agentes vinculados.
@@ -35,6 +35,12 @@ render(
 )
 ```
 
+## useViewAction
+
+`ActionView` é uma composição sobre `useViewAction(action, input)`, que devolve `data`, `error`,
+`isLoading` e `refetch` sob o `QueryClientProvider`. Use o hook direto quando o recurso alimenta
+mais de uma região da tela ou quando o carregamento precisa ser orquestrado por outro componente.
+
 ## Propriedades de ActionView
 
 | Propriedade | Tipo | Padrão | Descrição |
@@ -43,5 +49,7 @@ render(
 | `input` | `TInput` | | Geralmente { id } — mudou, recarrega. |
 | `children` | `(data: TData, refetch) => ReactNode` | | Conteúdo apresentado quando os dados estão disponíveis. `refetch` permite recarregar por código. |
 | `render` | `(data: TData, refetch) => ReactNode` | | Alias de compatibilidade de `children`; `children` tem precedência. |
-| `loading / empty` | `ReactNode` | `3 skeletons / nada` | Sobrescreve os estados padrão quando o contexto pedir. |
-| `error` | `(err, retry) => ReactNode` | `mensagem + Tentar de novo` | Sobrescreve o estado de erro padrão. |
+| `loading` | `ReactNode \| boolean` | `3 skeletons` | Sobrescreve o carregamento: um nó próprio, `true` para o padrão ou `false` para não renderizar nada enquanto carrega. |
+| `empty` | `ReactNode` | `emptyMessage` ou nada | Sobrescreve o estado vazio (200 sem dado). |
+| `emptyMessage` | `string` | | Atalho do vazio: a frase na mesma superfície de `DataState` (`Empty` com moldura sólida). |
+| `error` | `(err, retry) => ReactNode` | `"Não foi possível carregar" + Tentar de novo` | Sobrescreve o estado de erro padrão. Sem ele, a frase do servidor só aparece quando é legível pela pessoa (`conflict`, `validation`, `not_found`, `authorization`, `authentication`); código técnico nunca vira título, e o botão de tentar de novo some quando o problema é de permissão ou sessão. |

package/src/ui/docs/content/ask.md

@@ -29,3 +29,14 @@ render(
 ```
 
 Cada pergunta exige pelo menos uma opção válida selecionada **ou** texto livre não vazio. `busy` mostra o progresso no botão e trava os controles; `disabled` apenas trava a interação. A ordem de `answers` acompanha a ordem de `questions`, e o `header` de cada resposta é derivado de `question.header` (ou do próprio enunciado quando o header estiver vazio).
+
+## Propriedades de Ask
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `questions` | `AskQuestion[]` | | Uma a quatro perguntas do contrato de elicitação; fora dessa faixa o envio é bloqueado. |
+| `answers` | `AskAnswer[]` | | Respostas controladas, na mesma ordem de `questions`; entradas ausentes contam como vazias. |
+| `onChange` | `(answers: AskAnswer[]) => void` | | Recebe a lista completa a cada alteração. |
+| `onSubmit` | `(answers: AskAnswer[]) => void` | | Dispara somente quando toda pergunta tem uma opção ou texto livre. |
+| `disabled` | `boolean` | `false` | Trava as opções e o envio. |
+| `busy` | `boolean` | `false` | Envio em andamento: o botão mostra o spinner e desabilita. |