@softize/opus 12.10.0 → 13.0.0

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,54 @@ 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"
+      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 +214,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/table.tsx

@@ -78,7 +78,7 @@ function TableHead({ className, ...props }: React.ComponentProps<"th">) {
     <th
       data-slot="table-head"
       className={cn(
-        "h-10 px-2 text-left align-middle font-medium whitespace-nowrap text-foreground [&:has([role=checkbox])]:pr-0 [&>[role=checkbox]]:translate-y-[0.125rem]",
+        "h-10 px-3 text-left align-middle font-medium whitespace-nowrap text-muted-foreground [&:has([role=checkbox])]:pr-0 [&>[role=checkbox]]:translate-y-[0.125rem]",
         className
       )}
       {...props}
@@ -91,7 +91,7 @@ function TableCell({ className, ...props }: React.ComponentProps<"td">) {
     <td
       data-slot="table-cell"
       className={cn(
-        "p-2 align-middle whitespace-nowrap [&:has([role=checkbox])]:pr-0 [&>[role=checkbox]]:translate-y-[0.125rem]",
+        "px-3 py-2 align-middle whitespace-nowrap [&:has([role=checkbox])]:pr-0 [&>[role=checkbox]]:translate-y-[0.125rem]",
         className
       )}
       {...props}

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 { PaneContent, 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,33 +171,17 @@ 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">
-          <PaneContent>
-            <SidebarNav
-              groups={navGroups}
-              activeId={page?.slug}
-              navLabel="Navegação da documentação"
-              onSelect={(slug) => go(`${basePath}/${slug}`)}
+          <PaneBody>
+            <DocSidebarTree
+              sections={sections}
+              activeSlug={page?.slug}
+              onSelect={(nextSlug) => go(`${basePath}/${nextSlug}`)}
             />
-          </PaneContent>
+          </PaneBody>
         </Sidebar>
       </Pane>
       <Pane key={page?.slug} grow inset="none" className="overflow-y-auto">

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 variant="destructive">Breaking</Badge>}
+              {v.breaking !== undefined && <Badge context="danger" variant="solid">Breaking</Badge>}
             </div>
             {v.body.length > 0 && (
               <div className="mt-3">

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

@@ -1,7 +1,8 @@
-## Padrão (single)
+## Um painel por vez
 
-`type=single` abre um painel por vez. `collapsible` deixa fechar o que está aberto — sem ele,
-sempre fica um item expandido. `defaultValue` deixa o estado com o componente.
+Use `type="single"` quando somente um painel deve permanecer aberto. Com `collapsible`, a pessoa
+também pode fechar o painel atual; sem essa propriedade, um item permanece expandido.
+`defaultValue` define o item inicialmente aberto no modo não controlado.
 
 ```tsx preview
 <Accordion type="single" collapsible defaultValue="overview" className="w-full">
@@ -28,8 +29,8 @@ sempre fica um item expandido. `defaultValue` deixa o estado com o componente.
 
 ## Múltiplos abertos
 
-`type=multiple` permite vários painéis expandidos ao mesmo tempo — `defaultValue` vira um
-array com os itens abertos de saída.
+Use `type="multiple"` quando os painéis puderem permanecer abertos ao mesmo tempo. Nesse modo,
+`defaultValue` recebe um array com os itens inicialmente expandidos.
 
 ```tsx preview
 <Accordion type="multiple" defaultValue={['skills', 'prompt']} className="w-full">
@@ -48,10 +49,10 @@ array com os itens abertos de saída.
 </Accordion>
 ```
 
-## Controlado (com estado)
+## Estado controlado
 
-No modo `single`, `value`/`onValueChange` tiram o estado do componente — dá pra abrir um item
-de fora. Exemplo **com estado** (o `render()` deixa o hook rodar):
+Use `value` e `onValueChange` quando outro elemento ou estado do aplicativo também precisar
+controlar o painel aberto.
 
 ```tsx preview
 const [open, setOpen] = React.useState('developer')
@@ -74,13 +75,18 @@ render(
 )
 ```
 
-## Props
+## Propriedades de Accordion
 
-| Prop | Tipo | Default | Descrição |
+| Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
-| `type` (Accordion) | `'single' \| 'multiple'` | | single abre um painel por vez; multiple permite vários. |
-| `collapsible` (Accordion) | `boolean` | `false` | Só no single — permite fechar o item aberto. |
-| `defaultValue` (Accordion) | `string \| string[]` | | Item(ns) aberto(s) no modo não controlado. |
-| `value` (Accordion) | `string \| string[]` | | Item(ns) aberto(s) no modo controlado — pareie com onValueChange. |
-| `onValueChange` (Accordion) | `(value) => void` | | Chamado quando o usuário abre ou fecha um item. |
-| `value` (AccordionItem) | `string` | | Identificador do item — é o que defaultValue/value referenciam. |
+| `type` | `'single' \| 'multiple'` | | `single` abre um painel por vez; `multiple` permite manter vários abertos. |
+| `collapsible` | `boolean` | `false` | No modo `single`, permite fechar o item aberto. |
+| `defaultValue` | `string \| string[]` | | Item ou itens inicialmente abertos no modo não controlado. |
+| `value` | `string \| string[]` | | Item ou itens abertos no modo controlado. Use com `onValueChange`. |
+| `onValueChange` | `(value) => void` | | Chamado quando a pessoa abre ou fecha um item. |
+
+## Propriedades de AccordionItem
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `value` | `string` | | Identificador usado por `defaultValue` e `value` no `Accordion`. |

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

@@ -1,7 +1,7 @@
-## Form como card
+## Formulário em uma seção
 
-O ActionForm dentro de um Card — header, conteúdo e rodapé, no respiro do Card (sem divisor nem
-faixa de modal). Pra estruturar uma seção da página como painel. O título é opcional.
+Use `ActionFormCard` para apresentar um `ActionForm` como seção delimitada da página. O componente
+aplica a estrutura e o espaçamento de `Card`, sem a faixa de ações de um modal. O título é opcional.
 
 ```tsx preview col md
 <DocBrowserActionProvider>
@@ -14,11 +14,11 @@ faixa de modal). Pra estruturar uma seção da página como painel. O título é
 </DocBrowserActionProvider>
 ```
 
-## Props
+## Propriedades de ActionFormCard
 
-| Prop | Tipo | Default | Descrição |
+| Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
-| `title` | `string` | | Título do header (com divisor embaixo). Sem ele, o card começa direto no corpo. |
+| `title` | `string` | | Título do cabeçalho. Sem ele, o card começa diretamente pelo corpo. |
 | `description` | `string` | | Subtítulo opcional, abaixo do título. |
-| `action / defaultValues / fieldOptions / submitLabel / onSuccess / onCancel` | `— (iguais ao ActionForm)` | | O resto é o ActionForm — o card injeta o conteúdo (CardContent) e o rodapé (CardFooter) por baixo. |
-| `cardClassName` | `string` | | Classes da SUPERFÍCIE do card (ex.: largura). `className` vai pro `<form>`. |
+| `action / defaultValues / fieldOptions / submitLabel / onSuccess / onCancel` | Propriedades de `ActionForm` | | Mantêm o mesmo comportamento do formulário interno. |
+| `cardClassName` | `string` | | Classes aplicadas à superfície do card. `className` continua sendo aplicado ao `<form>`. |

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

@@ -1,8 +1,8 @@
-## Form em modal
+## Formulário em um modal
 
-O open é de quem orquestra; o fechamento no sucesso é do pattern. Header e X fixos, os campos
-scrollam, o rodapé é a faixa da casa. O preview roda num client de mentira — no app, o contrato
-vem do spec.
+Use `ActionFormDialog` quando o formulário precisar interromper o fluxo atual sem levar a pessoa
+para outra página. O consumidor controla `open`; depois de uma execução bem-sucedida, o componente
+fecha o modal. O cabeçalho e o rodapé permanecem visíveis enquanto os campos podem rolar.
 
 ```tsx preview
 const [open, setOpen] = useState(false)
@@ -22,11 +22,11 @@ render(
 )
 ```
 
-## Props
+## Propriedades de ActionFormDialog
 
-| Prop | Tipo | Default | Descrição |
+| Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
-| `open / onOpenChange` | `boolean / (open: boolean) => void` | | Controle do modal — o pattern chama onOpenChange(false) no sucesso e no Cancelar. |
-| `title / description` | `string` | | O DialogHeader fixo — description é opcional. |
+| `open / onOpenChange` | `boolean / (open: boolean) => void` | | Estado controlado do modal. `onOpenChange(false)` é chamado no sucesso e ao cancelar. |
+| `title / description` | `string` | | Conteúdo do cabeçalho; `description` é opcional. |
 | `submitLabel` | `string` | `'Salvar'` | Resultado da ação principal. Em criação, informe `Criar {recurso}`; em edição, `Salvar alterações`. |
-| `…ActionFormProps` | `action, defaultValues, onSuccess, fieldOptions…` | | Todo o resto desce pro ActionForm interno — mesma API da página dele. |
+| `…ActionFormProps` | `action, defaultValues, onSuccess, fieldOptions…` | | Demais propriedades repassadas ao `ActionForm` interno. |

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

@@ -1,8 +1,8 @@
-## Form derivado do contrato
+## Formulário derivado do contrato
 
-Zero JSX de campo: enum vira Select, string longa vira Textarea, obrigatório ganha o asterisco. O
-preview roda num client de mentira — digite "Softize" no nome pra ver o erro de servidor inline; o
-submit só habilita com mudança real (dirty).
+Use `ActionForm` para gerar campos, validação e mensagens a partir de uma `FormAction`. Sem
+`children`, o componente escolhe o controle adequado para cada campo e preserva a ordem declarada
+no contrato. No exemplo, altere um valor para habilitar a ação principal.
 
 ```tsx preview col md
 <DocBrowserActionProvider>
@@ -10,13 +10,12 @@ submit só habilita com mudança real (dirty).
 </DocBrowserActionProvider>
 ```
 
-## Composição (diagramação livre)
+## Composição dos campos
 
-Com children, o AUTO desliga e você diagrama: `<ActionFormField name />` coloca cada campo — com
-label, hint, widget, erro e asterisco derivados do contrato — onde quiser. Condicional é JSX;
-opções de runtime entram por prop no campo. O comportamento (submit, validação, toast,
-invalidação) continua encapsulado — e o espaçamento é 100% seu: o campo não impõe margem
-(quem diagrama usa grid/gap/space-y como quiser).
+Passe `children` quando a disposição automática não atender ao formulário. Cada
+`ActionFormField` mantém rótulo, ajuda, controle, obrigatoriedade e erro derivados do contrato;
+o consumidor define apenas a grade, as condições e o espaçamento. Execução, validação, toast e
+invalidação continuam sob responsabilidade de `ActionForm`.
 
 ```tsx preview col md
 <DocBrowserActionProvider>
@@ -35,8 +34,8 @@ invalidação) continua encapsulado — e o espaçamento é 100% seu: o campo n
 
 ## Valores iniciais e rótulos
 
-defaultValues pré-carrega (modo edição); submitLabel/cancelLabel trocam o rodapé. O onCancel é de
-quem orquestra (fechar drawer, voltar…).
+`defaultValues` preenche o formulário para edição. `submitLabel` e `cancelLabel` nomeiam as ações;
+`onCancel` devolve ao consumidor a decisão de fechar um painel ou navegar para outra página.
 
 ```tsx preview col md
 <DocBrowserActionProvider>
@@ -51,8 +50,7 @@ quem orquestra (fechar drawer, voltar…).
 
 ## Pré-requisitos
 
-O driver precisa dos dois providers no root — exatamente o wiring do admin (o consumidor
-canônico).
+Monte os providers de consulta e execução uma vez na raiz do aplicativo:
 
 ```tsx
 /* main.tsx do app. */
@@ -63,35 +61,32 @@ canônico).
 </QueryClientProvider>
 ```
 
-## Props
+## Propriedades de ActionForm
 
-| Prop | Tipo | Default | Descrição |
+| Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
 | `action` | `FormContract<TInput, TData>` | | O contrato da FormAction — dele saem campos (input Zod + fields), mensagens e invalidação de cache. |
 | `defaultValues` | `Partial<TInput>` | | Valores iniciais — o modo edição de um update/patch. |
 | `onSuccess` | `(data: TData) => void` | | Pós-sucesso (o toast e a invalidação de cache já aconteceram). |
 | `submitLabel / cancelLabel / onCancel` | `string / string / () => void` | `'Salvar' / 'Cancelar'` | Rodapé do form — o Cancelar só aparece com onCancel. |
 | `fieldOptions` | `Record<string, SelectOption[]>` | | Opções de runtime por campo (ex.: ids de skills) — sobrepõe as inferidas do z.enum. |
-| `className / body / footer` | `string / (node) => node / (node) => node` | | className = classes do `<form>`. body/footer = SLOTS: recebem os campos / os botões e escolhem o invólucro — é como o ActionFormDialog injeta DialogBody/DialogFooter (scroll + faixa). |
-| `children` | `ReactNode` | | Modo COMPOSIÇÃO: diagrame com `<ActionFormField name />`. Sem children, o AUTO monta todos os campos na ordem do contrato. |
+| `className / body / footer` | `string / (node) => node / (node) => node` | | className = classes do `<form>`. body/footer = slots: recebem os campos / os botões e escolhem o invólucro — é como o ActionFormDialog injeta DialogBody/DialogFooter (scroll + faixa). |
+| `children` | `ReactNode` | | Modo composição: diagrame com `<ActionFormField name />`. Sem children, o automático monta todos os campos na ordem do contrato. |
 
-## ActionFormField
+## Propriedades de ActionFormField
 
-| Prop | Tipo | Descrição |
+| Propriedade | Tipo | Descrição |
 |---|---|---|
 | `name` | `string` | O campo do contrato (chave em `fields`/schema). Fora do schema, não renderiza. |
 | `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` numa grid). |
+| `className` | `string` | Classes do invólucro (ex.: `col-span-2` em uma grid). |
 
-## De onde vêm as opções de um select
+## Origem das opções de seleção
 
-Precedência, da mais específica pra mais automática: **prop `options` do campo** >
-**`fieldOptions` do form** > **`options` do FieldSpec no contrato** (`{ kind: 'dictionary',
-ref }` resolve pelos dicts do `<TbdlibProvider dicts={{ ref: meuDict }}>` — o `DictType` do
-`t.dict` encaixa direto; `{ kind: 'static', items }` renderiza como declarado) > **meta do
-`t.dict` no schema** (zero-config: campo `meuDict.zod()` — ou multiselect com elemento dict —
-resolve value→label pela meta que viaja no contrato, sem registry) > **chaves cruas do
-z.enum**. Campo texto com opções declaradas (runtime ou spec) vira single-select por-id.
+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
+referência; itens estáticos permanecem como declarados no contrato.
 
 ## Widgets declarativos
 
@@ -103,11 +98,10 @@ escolha rica em card, com conteúdo de apoio; para uma lista textual comum, pref
 Outros identificadores continuam válidos como metadado
 para renderers próprios; o `ActionForm` aplica sua inferência normal quando não reconhece o widget.
 
-## Controle custom: useActionFormContext
+## Controle próprio com useActionFormContext
 
-Campo com UI própria (grade de permissões, canvas…) que nenhum widget cobre? No modo
-composição, o hook dá acesso ao form do contrato — o campo custom participa do submit
-sem abandonar o `<ActionForm>`:
+Quando nenhum widget atender ao campo, use `useActionFormContext` no modo de composição. O controle
+próprio participa da mesma validação e execução sem abandonar o `ActionForm`:
 
 ```tsx
 import { useActionFormContext } from '@softize/opus/ui/react'
@@ -132,4 +126,4 @@ function PermissionGrid() {
 ```
 
 O contexto também expõe `shape` (Zod por campo), `fields` (FieldSpec) e `fieldOptions`.
-Fora de um `<ActionForm>`, o hook explode com mensagem clara — igual ao `ActionFormField`.
+Fora de um `<ActionForm>`, o hook lança um erro que informa o provider ausente.