@softize/opus 12.11.0 → 13.1.0

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

@@ -14,7 +14,7 @@ export interface InputProps extends React.ComponentProps<"input"> {
 
 // O <input> CRU (sem adorno): ELE é o campo — borda, foco, ref e className moram nele.
 const bareInput =
-  "h-9 w-full min-w-0 rounded-md border border-input bg-transparent px-3 py-1 text-base transition-[color,box-shadow] outline-none selection:bg-primary selection:text-primary-foreground file:inline-flex file:h-7 file:border-0 file:bg-transparent file:text-sm file:font-medium file:text-foreground placeholder:text-muted-foreground disabled:pointer-events-none disabled:cursor-not-allowed disabled:opacity-50 md:text-sm dark:bg-input/30 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"
+  "h-9 w-full min-w-0 rounded-md border border-input bg-transparent px-3 py-1 text-base transition-[color,box-shadow] outline-none selection:bg-primary selection:text-primary-foreground file:inline-flex file:h-7 file:border-0 file:bg-transparent file:text-sm file:font-medium file:text-foreground placeholder:text-muted-foreground disabled:pointer-events-none disabled:cursor-not-allowed disabled:opacity-50 md:text-sm dark:bg-input/30 focus-visible:border-ring focus-visible:ring-[0.1875rem] focus-visible:ring-ring/50 aria-invalid:border-context-danger aria-invalid:ring-context-danger/20 dark:aria-invalid:ring-context-danger/40"
 
 function Input({ className, type, icon, trailing, ...props }: InputProps) {
   // Sem adorno: o <input> cru de sempre — retrocompatível (refs, forms, InputGroupInput).
@@ -33,7 +33,7 @@ function Input({ className, type, icon, trailing, ...props }: InputProps) {
       className={cn(
         "flex h-9 w-full min-w-0 items-center gap-1.5 rounded-md border border-input bg-transparent px-3 text-base transition-[color,box-shadow] outline-none md:text-sm dark:bg-input/30",
         "has-[input:focus-visible]:border-ring has-[input:focus-visible]:ring-[0.1875rem] has-[input:focus-visible]:ring-ring/50",
-        "has-[input[aria-invalid=true]]:border-destructive has-[input[aria-invalid=true]]:ring-destructive/20 dark:has-[input[aria-invalid=true]]:ring-destructive/40",
+        "has-[input[aria-invalid=true]]:border-context-danger has-[input[aria-invalid=true]]:ring-context-danger/20 dark:has-[input[aria-invalid=true]]:ring-context-danger/40",
         "has-[input:disabled]:pointer-events-none has-[input:disabled]:opacity-50",
         className,
       )}

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

@@ -116,14 +116,14 @@ function Item({
 }
 
 const itemMediaVariants = cva(
-  "flex shrink-0 self-stretch items-center justify-center gap-2 [&_svg]:pointer-events-none",
+  "flex shrink-0 self-start items-center justify-center gap-2 [&_svg]:pointer-events-none",
   {
     variants: {
       variant: {
         default: "bg-transparent",
-        icon: "min-h-8 w-8 rounded-sm border bg-muted [&_svg:not([class*='size-'])]:size-4",
+        icon: "size-8 rounded-sm border bg-muted [&_svg:not([class*='size-'])]:size-4",
         image:
-          "min-h-10 w-10 overflow-hidden rounded-sm [&_img]:size-full [&_img]:object-cover",
+          "size-10 overflow-hidden rounded-sm [&_img]:size-full [&_img]:object-cover",
       },
     },
     defaultVariants: { variant: "default" },

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 } from './control.ts'
 import { CommandEmpty, CommandGroup, CommandItem, CommandList } from './command.tsx'
 import { Popover, PopoverAnchor, PopoverContent } from './popover.tsx'
 
@@ -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

@@ -6,7 +6,149 @@ import {
   OctagonXIcon,
   TriangleAlertIcon,
 } from 'lucide-react'
-import { Toaster as Sonner, toast, type ToasterProps } from 'sonner'
+import {
+  Toaster as Sonner,
+  toast as sonnerToast,
+  type ExternalToast,
+  type ToasterProps,
+} from 'sonner'
+import { cn } from '../../lib/cn.ts'
+import {
+  Button,
+  type ButtonContext,
+  type ButtonVariant,
+} from './button.tsx'
+
+type ToastId = string | number
+type ToastMessage = React.ReactNode | (() => React.ReactNode)
+
+export interface ToastAction {
+  key?: React.Key
+  label: React.ReactNode
+  onClick: (event: React.MouseEvent<HTMLButtonElement>) => void
+  context?: ButtonContext
+  variant?: ButtonVariant
+  disabled?: boolean
+}
+
+export interface ToastOptions extends Omit<ExternalToast, 'action' | 'cancel'> {
+  actions?: readonly ToastAction[]
+}
+
+interface ToastApi {
+  (message: ToastMessage, options?: ToastOptions): ToastId
+  success: (message: ToastMessage, options?: ToastOptions) => ToastId
+  info: (message: ToastMessage, options?: ToastOptions) => ToastId
+  warning: (message: ToastMessage, options?: ToastOptions) => ToastId
+  error: (message: ToastMessage, options?: ToastOptions) => ToastId
+  message: (message: ToastMessage, options?: ToastOptions) => ToastId
+  loading: (message: ToastMessage, options?: ToastOptions) => ToastId
+  custom: typeof sonnerToast.custom
+  promise: typeof sonnerToast.promise
+  dismiss: typeof sonnerToast.dismiss
+  getHistory: typeof sonnerToast.getHistory
+  getToasts: typeof sonnerToast.getToasts
+}
+
+interface ToastMediaProps {
+  children: React.ReactNode
+  className: string
+}
+
+function ToastMedia({ children, className }: ToastMediaProps): React.ReactElement {
+  return (
+    <span
+      className={cn(
+        'flex size-9 items-center justify-center rounded-md bg-current/10 [&_svg]:size-5',
+        className,
+      )}
+    >
+      {children}
+    </span>
+  )
+}
+
+interface ToastActionsProps {
+  actions: readonly ToastAction[]
+  getToastId: () => ToastId | undefined
+}
+
+function ToastActions({ actions, getToastId }: ToastActionsProps): React.ReactElement {
+  return (
+    <div data-slot="toast-actions" className="ms-auto flex shrink-0 items-center gap-2">
+      {actions.map((action, index) => {
+        const primary = index === actions.length - 1
+        return (
+          <Button
+            key={action.key ?? index}
+            type="button"
+            size="sm"
+            context={action.context ?? (primary ? 'primary' : 'neutral')}
+            variant={action.variant ?? (primary ? 'solid' : 'ghost')}
+            disabled={action.disabled}
+            onClick={(event) => {
+              action.onClick(event)
+              if (!event.defaultPrevented) {
+                const toastId = getToastId()
+                if (toastId !== undefined) sonnerToast.dismiss(toastId)
+              }
+            }}
+          >
+            {action.label}
+          </Button>
+        )
+      })}
+    </div>
+  )
+}
+
+function toSonnerOptions(
+  options: ToastOptions | undefined,
+  getToastId: () => ToastId | undefined,
+): ExternalToast | undefined {
+  if (options === undefined) return undefined
+  const { actions, ...rest } = options
+  if (actions === undefined) return rest
+  return {
+    ...rest,
+    action: actions.length > 0 ? <ToastActions actions={actions} getToastId={getToastId} /> : undefined,
+  }
+}
+
+type SonnerToastMethod = (message: ToastMessage, options?: ExternalToast) => ToastId
+
+function dispatchToast(
+  method: SonnerToastMethod,
+  message: ToastMessage,
+  options?: ToastOptions,
+): ToastId {
+  let toastId: ToastId | undefined
+  toastId = method(message, toSonnerOptions(options, () => toastId))
+  return toastId
+}
+
+const toast: ToastApi = Object.assign(
+  (message: ToastMessage, options?: ToastOptions) => dispatchToast(sonnerToast, message, options),
+  {
+    success: (message: ToastMessage, options?: ToastOptions) =>
+      dispatchToast(sonnerToast.success, message, options),
+    info: (message: ToastMessage, options?: ToastOptions) =>
+      dispatchToast(sonnerToast.info, message, options),
+    warning: (message: ToastMessage, options?: ToastOptions) =>
+      dispatchToast(sonnerToast.warning, message, options),
+    error: (message: ToastMessage, options?: ToastOptions) =>
+      dispatchToast(sonnerToast.error, message, options),
+    message: (message: ToastMessage, options?: ToastOptions) =>
+      dispatchToast(sonnerToast.message, message, options),
+    loading: (message: ToastMessage, options?: ToastOptions) =>
+      dispatchToast(sonnerToast.loading, message, options),
+    custom: sonnerToast.custom,
+    promise: sonnerToast.promise,
+    dismiss: sonnerToast.dismiss,
+    getHistory: sonnerToast.getHistory,
+    getToasts: sonnerToast.getToasts,
+  },
+)
 
 /**
  * Toaster temático (sonner) — monte 1x no root do app. Os toasts saem estilizados
@@ -17,18 +159,57 @@ import { Toaster as Sonner, toast, type ToasterProps } from 'sonner'
  * usamos next-themes — passe `theme` por prop se precisar forçar (default 'system').
  * Elevação dark preservada: `--normal-bg` aponta pro popover (não pro background).
  */
-export function Toaster({ ...props }: ToasterProps): React.ReactElement {
+export function Toaster({
+  className,
+  icons,
+  style,
+  toastOptions,
+  ...props
+}: ToasterProps): React.ReactElement {
   return (
     <Sonner
       data-slot="toaster"
       theme="system"
-      className="toaster group"
+      // 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: <CircleCheckIcon className="size-4" />,
-        info: <InfoIcon className="size-4" />,
-        warning: <TriangleAlertIcon className="size-4" />,
-        error: <OctagonXIcon className="size-4" />,
-        loading: <Loader2Icon className="size-4 animate-spin" />,
+        success: (
+          <ToastMedia className="text-context-success-emphasis">
+            <CircleCheckIcon />
+          </ToastMedia>
+        ),
+        info: (
+          <ToastMedia className="text-context-info-emphasis">
+            <InfoIcon />
+          </ToastMedia>
+        ),
+        warning: (
+          <ToastMedia className="text-context-warning-emphasis">
+            <TriangleAlertIcon />
+          </ToastMedia>
+        ),
+        error: (
+          <ToastMedia className="text-context-danger-emphasis">
+            <OctagonXIcon />
+          </ToastMedia>
+        ),
+        loading: (
+          <ToastMedia className="text-context-neutral-emphasis">
+            <Loader2Icon className="animate-spin" />
+          </ToastMedia>
+        ),
+        ...icons,
+      }}
+      toastOptions={{
+        ...toastOptions,
+        classNames: {
+          ...toastOptions?.classNames,
+          toast: cn('opus-toast', toastOptions?.classNames?.toast),
+          icon: cn('opus-toast-icon', toastOptions?.classNames?.icon),
+          closeButton: cn('opus-toast-close', toastOptions?.classNames?.closeButton),
+        },
       }}
       style={
         {
@@ -36,6 +217,7 @@ export function Toaster({ ...props }: ToasterProps): React.ReactElement {
           '--normal-text': 'var(--popover-foreground)',
           '--normal-border': 'var(--border)',
           '--border-radius': 'var(--radius)',
+          ...style,
         } as React.CSSProperties
       }
       {...props}

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

@@ -22,6 +22,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

@@ -77,6 +77,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

@@ -5,7 +5,7 @@ import { Toggle as TogglePrimitive } from "radix-ui"
 import { cn } from '../../lib/cn.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 focus-visible:border-ring focus-visible:ring-[0.1875rem] focus-visible:ring-ring/50 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",
   {
     variants: {
       variant: {

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/DocBrowser.tsx

@@ -12,10 +12,16 @@
  * Nos dois, navegar emite `popstate`: host que guarda o path por conta própria acompanha.
  * `basePath` adapta o prefixo das URLs (`/docs` no Maestro, `/__docs` nos apps).
  */
-import { useEffect } from 'react'
+import { useEffect, useState } from 'react'
 import { DOC_SECTIONS, type DocSection, type DocEntry } from './registry'
 import { Pane, Split } from '../components/patterns/split.tsx'
-import { PaneBody, Sidebar, SidebarNav, type SidebarNavGroup } from '../components/patterns/sidebar.tsx'
+import {
+  PaneBody,
+  Sidebar,
+  SidebarGroupLabel,
+  SidebarItem,
+  SidebarTreeGroup,
+} from '../components/patterns/sidebar.tsx'
 import { navigate, usePathname } from '../router.ts'
 
 function findPage(sections: DocSection[], slug: string): DocEntry | undefined {
@@ -42,6 +48,95 @@ export interface DocBrowserProps {
   documentTitle?: (pageTitle: string) => string
 }
 
+function DocSidebarTree({
+  sections,
+  activeSlug,
+  onSelect,
+}: {
+  sections: DocSection[]
+  activeSlug?: string
+  onSelect: (slug: string) => void
+}): React.ReactElement {
+  const [closedGroups, setClosedGroups] = useState<Set<string>>(() => new Set())
+
+  useEffect(() => {
+    const activeGroup = sections.flatMap((section, sectionIndex) =>
+      section.groups.map((group, groupIndex) => ({
+        key: `${sectionIndex}:${groupIndex}`,
+        group,
+      })),
+    ).find(({ group }) => group.pages.some((page) => page.slug === activeSlug))
+
+    if (activeGroup === undefined) return
+    setClosedGroups((current) => {
+      if (!current.has(activeGroup.key)) return current
+      const next = new Set(current)
+      next.delete(activeGroup.key)
+      return next
+    })
+  }, [activeSlug, sections])
+
+  const toggleGroup = (key: string): void => {
+    setClosedGroups((current) => {
+      const next = new Set(current)
+      if (next.has(key)) next.delete(key)
+      else next.add(key)
+      return next
+    })
+  }
+
+  const renderPage = (page: DocEntry): React.ReactElement => (
+    <SidebarItem
+      key={page.slug}
+      label={page.title}
+      badge={page.badge === undefined ? undefined : (
+        <span className="rounded border border-border/60 px-1 font-mono text-[0.625rem] leading-tight text-muted-foreground/60">
+          {page.badge}
+        </span>
+      )}
+      active={page.slug === activeSlug}
+      onClick={() => onSelect(page.slug)}
+    />
+  )
+
+  return (
+    <nav aria-label="Navegação da documentação" className="space-y-4 p-2">
+      {sections.map((section, sectionIndex) => (
+        <div key={`${section.label}:${sectionIndex}`} className="space-y-0.5">
+          {section.label.trim() !== '' && (
+            <SidebarGroupLabel>{section.label}</SidebarGroupLabel>
+          )}
+          {section.groups.map((group, groupIndex) => {
+            const key = `${sectionIndex}:${groupIndex}`
+            if (group.pages.length === 0) return null
+            if ((group.label ?? '').trim() === '') {
+              return group.pages.map((page) => renderPage(page))
+            }
+
+            const expanded = !closedGroups.has(key)
+            return (
+              <div key={key} className="space-y-0.5">
+                <SidebarItem
+                  label={group.label!}
+                  icon={group.icon}
+                  expanded={expanded}
+                  onToggle={() => toggleGroup(key)}
+                  onClick={() => toggleGroup(key)}
+                />
+                {expanded && (
+                  <SidebarTreeGroup>
+                    {group.pages.map((page) => renderPage(page))}
+                  </SidebarTreeGroup>
+                )}
+              </div>
+            )
+          })}
+        </div>
+      ))}
+    </nav>
+  )
+}
+
 export function DocBrowser({
   basePath = '/docs',
   path: controlledPath,
@@ -76,31 +171,15 @@ export function DocBrowser({
     if (page && documentTitle) document.title = documentTitle(page.title)
   }, [page, documentTitle])
 
-  // Seção → grupo, e os grupos da seção → subgrupos. O tier do meio NÃO pode ser
-  // achatado: `docSectionsFromFolder` o preenche a partir de sub-pasta (ou do
-  // frontmatter `group:`), que é o caminho do `opusDocs({ source })`.
-  const navGroups: SidebarNavGroup[] = sections.map((section) => ({
-    label: section.label,
-    subgroups: section.groups.map((g) => ({
-      label: g.label,
-      items: g.pages.map((p) => ({
-        id: p.slug,
-        label: p.title,
-        badge: p.badge === undefined ? undefined : <span className="rounded border border-border/60 px-1 font-mono text-[0.625rem] leading-tight text-muted-foreground/60">{p.badge}</span>,
-      })),
-    })),
-  }))
-
   return (
     <Split className="h-full">
-      <Pane inset="none" className="w-56">
+      <Pane initialSize="14rem" inset="none">
         <Sidebar className="w-full">
           <PaneBody>
-            <SidebarNav
-              groups={navGroups}
-              activeId={page?.slug}
-              navLabel="Navegação da documentação"
-              onSelect={(slug) => go(`${basePath}/${slug}`)}
+            <DocSidebarTree
+              sections={sections}
+              activeSlug={page?.slug}
+              onSelect={(nextSlug) => go(`${basePath}/${nextSlug}`)}
             />
           </PaneBody>
         </Sidebar>

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">