@softize/opus 18.5.0 → 20.0.0

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

@@ -4,14 +4,40 @@ import { Slider as SliderPrimitive } from "radix-ui"
 import { cn } from '../../lib/cn.ts'
 import { focusRing } from './control.ts'
 
+export interface SliderProps extends React.ComponentProps<typeof SliderPrimitive.Root> {
+  /**
+   * Nome de cada thumb, na ordem de `value`. Use em intervalos, em que cada controle precisa de
+   * um nome próprio (`['Custo mínimo', 'Custo máximo']`). Prevalece sobre `aria-label` e
+   * `aria-labelledby` no thumb correspondente.
+   */
+  thumbLabels?: readonly string[]
+}
+
+// Quem recebe foco e anuncia o valor é o thumb (`role="slider"`), não a raiz. Por isso
+// `aria-label` e `aria-labelledby` vão para os thumbs, como o Select faz com o campo interno;
+// na raiz, sem papel, não nomeariam nada. Em intervalo, `thumbLabels` dá um nome a cada controle.
+// Sem nome declarado, o Radix usaria "Minimum"/"Maximum": o fallback fica em português. Em
+// intervalo sem `thumbLabels`, o nome comum se compõe com o fallback ("Preço, mínimo"), senão os
+// dois thumbs teriam o mesmo nome; com `aria-labelledby`, o fallback entra por um span oculto
+// referenciado junto (`hidden` sai da tela, mas continua valendo como rótulo referenciado).
+function thumbFallback(index: number, total: number): string | undefined {
+  if (total > 2) return `Valor ${index + 1} de ${total}`
+  if (total === 2) return index === 0 ? 'Mínimo' : 'Máximo'
+  return undefined
+}
+
 function Slider({
   className,
   defaultValue,
   value,
   min = 0,
   max = 100,
+  thumbLabels,
+  'aria-label': ariaLabel,
+  'aria-labelledby': ariaLabelledby,
   ...props
-}: React.ComponentProps<typeof SliderPrimitive.Root>) {
+}: SliderProps) {
+  const fallbackIdBase = React.useId()
   const _values = React.useMemo(
     () =>
       Array.isArray(value)
@@ -48,16 +74,41 @@ function Slider({
           )}
         />
       </SliderPrimitive.Track>
-      {Array.from({ length: _values.length }, (_, index) => (
-        <SliderPrimitive.Thumb
-          data-slot="slider-thumb"
-          key={index}
-          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,
-          )}
-        />
-      ))}
+      {Array.from({ length: _values.length }, (_, index) => {
+        const thumbLabel = thumbLabels?.[index]
+        const fallback = thumbFallback(index, _values.length)
+        const fallbackId = `${fallbackIdBase}-thumb-${index}`
+        const composeLabelledby = thumbLabel === undefined && ariaLabelledby !== undefined && fallback !== undefined
+        const label =
+          thumbLabel ??
+          (ariaLabel !== undefined && fallback !== undefined
+            ? `${ariaLabel}, ${fallback.toLowerCase()}`
+            : ariaLabel ?? fallback)
+        return (
+          <React.Fragment key={index}>
+            {composeLabelledby && (
+              <span id={fallbackId} hidden>
+                {fallback}
+              </span>
+            )}
+            <SliderPrimitive.Thumb
+              data-slot="slider-thumb"
+              aria-label={composeLabelledby ? undefined : label}
+              aria-labelledby={
+                thumbLabel !== undefined
+                  ? undefined
+                  : composeLabelledby
+                    ? `${ariaLabelledby} ${fallbackId}`
+                    : ariaLabelledby
+              }
+              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,
+              )}
+            />
+          </React.Fragment>
+        )
+      })}
     </SliderPrimitive.Root>
   )
 }

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

@@ -2,6 +2,7 @@ import * as React from 'react'
 import { Tooltip, TooltipContent, TooltipTrigger } from './tooltip.tsx'
 import { useOverflowing } from '../../lib/overflow.ts'
 import { cn } from '../../lib/cn.ts'
+import { focusRing } from './control.ts'
 
 export interface TruncateProps extends React.ComponentProps<'span'> {
   /** Conteúdo do tooltip quando transborda. Default: os próprios children. */
@@ -17,13 +18,21 @@ export interface TruncateProps extends React.ComponentProps<'span'> {
  * Requer `<TooltipProvider>` na raiz do app (o esqueleto do `opus create` já monta).
  * Com `fade`, a mesma medição decide quando esmaecer o fim da linha em vez de cortar
  * em reticências — sem transbordo, nada é aplicado.
+ * Com o texto cortado, o span entra na ordem de tabulação para que o teclado alcance a dica;
+ * sem corte, fica fora dela, porque não há nada escondido para revelar.
  */
 export function Truncate({ tooltip, fade = false, children, className, ...props }: TruncateProps): React.ReactElement {
   const { ref, overflowing } = useOverflowing<HTMLSpanElement>(children)
   const cut = fade ? (overflowing ? 'truncate-fade' : 'overflow-hidden whitespace-nowrap') : 'truncate'
 
   const span = (
-    <span ref={ref} data-slot="truncate" className={cn('block', cut, className)} {...props}>
+    <span
+      ref={ref}
+      data-slot="truncate"
+      tabIndex={overflowing ? 0 : undefined}
+      className={cn('block', cut, overflowing && ['rounded-sm outline-none', focusRing], className)}
+      {...props}
+    >
       {children}
     </span>
   )

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

@@ -1,7 +1,11 @@
 ## Um painel por vez
 
+Use `Accordion` para dividir um conteúdo longo em painéis que a pessoa expande sob demanda, cada um
+com seu título. Para um único bloco recolhível, use [`Collapsible`](/ui/collapsible).
+
 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.
+também pode fechar o painel atual; sem essa propriedade, depois que um item é aberto, sempre haverá
+um item expandido.
 `defaultValue` define o item inicialmente aberto no modo não controlado.
 
 ```tsx preview
@@ -9,41 +13,43 @@ também pode fechar o painel atual; sem essa propriedade, um item permanece expa
   <AccordionItem value="overview">
     <AccordionTrigger>Visão geral</AccordionTrigger>
     <AccordionContent>
-      <p className="text-muted-foreground">Resumo do workspace Empresa X.</p>
+      <p className="text-muted-foreground">Corolla XEi 2022, placa ABC-1D23.</p>
     </AccordionContent>
   </AccordionItem>
-  <AccordionItem value="agents">
-    <AccordionTrigger>Agentes</AccordionTrigger>
+  <AccordionItem value="services">
+    <AccordionTrigger>Serviços</AccordionTrigger>
     <AccordionContent>
-      <p className="text-muted-foreground">developer, reviewer e designer ativos.</p>
+      <p className="text-muted-foreground">Troca de óleo, filtro de ar e alinhamento.</p>
     </AccordionContent>
   </AccordionItem>
-  <AccordionItem value="repos">
-    <AccordionTrigger>Repositórios</AccordionTrigger>
+  <AccordionItem value="parts">
+    <AccordionTrigger>Peças</AccordionTrigger>
     <AccordionContent>
-      <p className="text-muted-foreground">empresa-x-api e empresa-x-web vinculados.</p>
+      <p className="text-muted-foreground">Filtro de óleo e pastilhas de freio.</p>
     </AccordionContent>
   </AccordionItem>
 </Accordion>
 ```
 
+O `AccordionTrigger` já traz o ícone que gira conforme o estado; não acrescente outro.
+
 ## Múltiplos abertos
 
 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">
-  <AccordionItem value="prompt">
-    <AccordionTrigger>Prompt</AccordionTrigger>
+<Accordion type="multiple" defaultValue={['notes', 'parts']} className="w-full">
+  <AccordionItem value="notes">
+    <AccordionTrigger>Observações</AccordionTrigger>
     <AccordionContent>
-      <p className="text-muted-foreground">O prompt do agente developer.</p>
+      <p className="text-muted-foreground">O cliente relatou ruído ao frear.</p>
     </AccordionContent>
   </AccordionItem>
-  <AccordionItem value="skills">
-    <AccordionTrigger>Skills</AccordionTrigger>
+  <AccordionItem value="parts">
+    <AccordionTrigger>Peças</AccordionTrigger>
     <AccordionContent>
-      <p className="text-muted-foreground">clean-code, code-style, ddd e test vinculadas.</p>
+      <p className="text-muted-foreground">Pastilhas de freio substituídas.</p>
     </AccordionContent>
   </AccordionItem>
 </Accordion>
@@ -55,38 +61,79 @@ Use `value` e `onValueChange` quando outro elemento ou estado do aplicativo tamb
 controlar o painel aberto.
 
 ```tsx preview
-const [open, setOpen] = React.useState('developer')
+const [open, setOpen] = React.useState('diagnosis')
 
 render(
   <Accordion type="single" collapsible value={open} onValueChange={setOpen} className="w-full">
-    <AccordionItem value="developer">
-      <AccordionTrigger>Agente developer</AccordionTrigger>
+    <AccordionItem value="diagnosis">
+      <AccordionTrigger>Diagnóstico</AccordionTrigger>
       <AccordionContent>
-        <p className="text-muted-foreground">Implementa a task no worktree da sessão.</p>
+        <p className="text-muted-foreground">Identifica a causa do ruído relatado pelo cliente.</p>
       </AccordionContent>
     </AccordionItem>
-    <AccordionItem value="reviewer">
-      <AccordionTrigger>Agente reviewer</AccordionTrigger>
+    <AccordionItem value="execution">
+      <AccordionTrigger>Execução</AccordionTrigger>
       <AccordionContent>
-        <p className="text-muted-foreground">Revisa o handoff e carimba o diff.</p>
+        <p className="text-muted-foreground">Substitui as peças aprovadas no orçamento.</p>
       </AccordionContent>
     </AccordionItem>
   </Accordion>,
 )
 ```
 
+## Item indisponível
+
+Use `disabled` no `AccordionItem` quando um painel existe, mas ainda não pode ser aberto. O gatilho
+fica esmaecido e não responde ao clique nem ao teclado.
+
+```tsx preview
+<Accordion type="single" collapsible className="w-full">
+  <AccordionItem value="quote">
+    <AccordionTrigger>Orçamento</AccordionTrigger>
+    <AccordionContent>
+      <p className="text-muted-foreground">Aprovado pelo cliente em 12 de maio.</p>
+    </AccordionContent>
+  </AccordionItem>
+  <AccordionItem value="invoice" disabled>
+    <AccordionTrigger>Nota fiscal</AccordionTrigger>
+    <AccordionContent>
+      <p className="text-muted-foreground">Emitida depois da entrega do veículo.</p>
+    </AccordionContent>
+  </AccordionItem>
+</Accordion>
+```
+
 ## Propriedades de Accordion
 
 | Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
-| `type` | `'single' \| 'multiple'` | | `single` abre um painel por vez; `multiple` permite manter vários abertos. |
+| `type` | `'single' \| 'multiple'` | | Obrigatório. `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. |
+| `defaultValue` | `string` em `single`; `string[]` em `multiple` | | Item ou itens inicialmente abertos no modo não controlado. |
+| `value` | `string` em `single`; `string[]` em `multiple` | | Item ou itens abertos no modo controlado. Use com `onValueChange`. |
+| `onValueChange` | `(value: string) => void` em `single`; `(value: string[]) => void` em `multiple` | | Chamado quando a pessoa abre ou fecha um item. Em `single`, recebe `''` quando o item aberto é fechado. |
+| `disabled` | `boolean` | `false` | Desabilita todos os itens. |
+| `className` | `string` | | Ajusta o contêiner. |
 
 ## Propriedades de AccordionItem
 
 | Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
-| `value` | `string` | | Identificador usado por `defaultValue` e `value` no `Accordion`. |
+| `value` | `string` | | Obrigatório. Identificador usado por `defaultValue` e `value` no `Accordion`. |
+| `disabled` | `boolean` | `false` | Impede abrir ou fechar este item. |
+| `className` | `string` | | Ajusta o item, que traz um divisor inferior exceto no último. |
+
+## Propriedades de AccordionTrigger
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `children` | `ReactNode` | | Rótulo do painel. O ícone de estado é acrescentado depois dele. |
+| `className` | `string` | | Ajusta o botão do gatilho. |
+
+## Propriedades de AccordionContent
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `children` | `ReactNode` | | Conteúdo do painel. |
+| `className` | `string` | | Ajusta o recuo interno do conteúdo, aplicado a um contêiner dentro da região animada. |
+| `forceMount` | `boolean` | `false` | Mantém o conteúdo montado mesmo fechado. |

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

@@ -1,25 +1,34 @@
 ## Formulário em uma seção
 
-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.
-Quando `onCancel` acrescenta uma segunda ação, o componente organiza os botões em um
-`ButtonGroup` espaçado sem forçar a divisão 50/50 do modal.
+Use `ActionFormCard` quando o formulário ocupar uma seção delimitada da página, ao lado de outros
+blocos. O componente aplica a estrutura e o espaçamento de [`Card`](/ui/card) ao
+[`ActionForm`](/ui/action-form), sem a faixa de ações de um modal. O título é opcional e segue a
+mesma regra de um formulário modal: nomeia a operação e o recurso, como `Criar workspace`, enquanto
+a ação principal mantém `Salvar`.
 
 ```tsx preview col md
 <DocBrowserActionProvider>
-  <ActionFormCard
-    title="Editar workspace"
-    action={docWorkspaceCreate}
-    defaultValues={{ name: "Empresa X", status: "active" }}
-  />
+  <ActionFormCard title="Criar workspace" action={docWorkspaceCreate} />
 </DocBrowserActionProvider>
 ```
 
+As ações ficam alinhadas no fim do rodapé e preservam a largura do conteúdo. Quando `onCancel`
+acrescenta `Cancelar`, os dois botões formam um `ButtonGroup` espaçado. Para interromper o fluxo
+com um modal, use [`ActionFormDialog`](/ui/action-form-dialog).
+
+O título do card é um heading `h3`, o nível padrão de `CardTitle`, adequado a uma seção dentro de
+uma página que já tem o próprio título. Quando o card ocupar outro lugar na hierarquia — por
+exemplo, a seção principal logo abaixo do `h1` da página —, declare `titleLevel={2}`. O nível muda
+só a estrutura do documento, que leitores de tela usam para navegar; a aparência do título continua
+a mesma.
+
 ## Propriedades de ActionFormCard
 
-| Propriedade                                                                  | Tipo                         | Padrão | Descrição                                                                                |
-| ---------------------------------------------------------------------------- | ---------------------------- | ------ | ---------------------------------------------------------------------------------------- |
-| `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` | 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>`. |
+| Propriedade        | Tipo                         | Padrão | Descrição                                                                                                                     |
+| ------------------ | ---------------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------- |
+| `title`            | `string`                     |        | Título do cabeçalho. Sem ele e sem `description`, o card começa diretamente pelo corpo.                                       |
+| `titleLevel`       | `1 \| 2 \| 3 \| 4 \| 5 \| 6`    | `3`    | Nível do heading do título. Muda a hierarquia do documento, não a escala visual.                                              |
+| `description`      | `string`                     |        | Texto de apoio abaixo do título.                                                                                              |
+| `cardClassName`    | `string`                     |        | Classes aplicadas à superfície do card.                                                                                       |
+| `className`        | `string`                     |        | Classes aplicadas ao `<form>` interno.                                                                                        |
+| Demais propriedades | Propriedades de `ActionForm` |        | `action`, `defaultValues`, `fieldOptions`, `submitLabel`, `cancelLabel`, `cancelVariant`, `onCancel`, `onSuccess`, `disabled`, `onLoadingChange` e `children` mantêm o comportamento de `ActionForm`. `body` e `footer` não são aceitas: o card fornece o corpo e o rodapé. |

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

@@ -2,12 +2,12 @@
 
 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.
-O rodapé agrupa as decisões em um `ButtonGroup` cuja largura acompanha o conteúdo: `Cancelar`
-aparece em `ghost` e a ação principal permanece `solid`, ambas no tamanho normal de uma decisão
-modal. `Cancelar` está sempre presente; sem `onCancel` próprio, ele fecha o modal.
-Com `footerDistribution="equal"`, as duas decisões dividem a faixa e `Cancelar` passa a `outline`,
-salvo escolha explícita em `cancelVariant`.
+fecha o modal. O cabeçalho e o rodapé permanecem visíveis enquanto os campos rolam.
+
+O título nomeia a operação e o recurso: `Criar workspace` em uma criação e `Editar workspace` em uma
+edição. Nos dois casos, a ação principal mantém o rótulo padrão `Salvar`, porque o título já
+distingue a operação. `submitLabel` fica para efeitos que `Salvar` não descreve, como `Renomear` ou
+`Criar nova versão`.
 
 ```tsx preview
 const [open, setOpen] = useState(false);
@@ -25,12 +25,22 @@ render(
 );
 ```
 
+## Ações do rodapé
+
+O rodapé agrupa as decisões em um `ButtonGroup` cuja largura acompanha o conteúdo: `Cancelar`
+aparece em `ghost` e a ação principal permanece `solid`, ambas no tamanho normal de uma decisão
+modal. `Cancelar` está sempre presente; sem `onCancel` próprio, ele fecha o modal. Com
+`footerDistribution="equal"`, as duas decisões dividem a faixa e `Cancelar` passa a `outline`,
+salvo escolha explícita em `cancelVariant`.
+
+Para consultar uma coleção no mesmo formato de modal, use [`ActionListDialog`](/ui/action-list-dialog).
+
 ## Propriedades de ActionFormDialog
 
 | Propriedade           | Tipo                                              | Padrão     | Descrição                                                                                                                                                                   |
 | --------------------- | ------------------------------------------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `open / onOpenChange` | `boolean / (open: boolean) => void`               |            | Estado controlado do modal. `onOpenChange(false)` é chamado no sucesso e, quando não há `onCancel` próprio, ao cancelar.                                                                                       |
-| `title`               | `string`                                          |            | Nome da tarefa exibido no cabeçalho.                                                                                                                                        |
+| `title`               | `string`                                          |            | Operação e recurso exibidos no cabeçalho, como `Criar workspace` ou `Editar workspace`. |
 | `intro`               | `ReactNode`                                       |            | Contexto relevante no início do corpo, como texto ou `Alert`.                                                                                                               |
 | `submitLabel`         | `string`                                          | `'Salvar'` | Resultado da ação principal. Preserve o padrão em criação e edição comuns; sobrescreva apenas quando a operação tiver outro efeito, como `Renomear` ou `Criar nova versão`. |
 | `footerDistribution`  | `'content' \| 'equal'`                            | `'content'` | Mantém a largura das ações pelo conteúdo ou divide a faixa igualmente. |

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

@@ -1,8 +1,28 @@
+## Pré-requisitos
+
+`ActionForm` executa a action pelo cliente registrado no `OpusProvider` e usa o React Query para
+invalidar as consultas afetadas. Monte os dois providers uma vez na raiz do aplicativo; todos os
+exemplos desta página pressupõem essa montagem.
+
+```tsx
+/* main.tsx do app. */
+<QueryClientProvider client={queryClient}>
+  <OpusProvider client={apiClient}>
+    <App />
+  </OpusProvider>
+</QueryClientProvider>
+```
+
 ## Formulário derivado do contrato
 
 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.
+`children`, o componente monta um campo para cada chave declarada em `fields` no contrato, na ordem
+dessa declaração, e escolhe o controle pelo tipo do campo no schema de input. Um campo presente no
+schema, mas sem entrada em `fields`, não aparece no modo automático: declare-o em `fields` ou
+posicione-o com `ActionFormField`, como mostra a próxima seção.
+
+A ação principal permanece desabilitada até que algum valor mude. No exemplo, preencha o nome para
+habilitá-la; o valor “Softize” simula um erro devolvido pelo servidor.
 
 ```tsx preview col md
 <DocBrowserActionProvider>
@@ -13,36 +33,43 @@ no contrato. No exemplo, altere um valor para habilitar a ação principal.
 ## Composição dos campos
 
 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`.
+`ActionFormField` mantém rótulo, ajuda, controle, obrigatoriedade e erro derivados do contrato; o
+consumidor define apenas a grade e as condições. O espaçamento vertical entre os filhos vem do
+`FieldGroup` que o formulário já aplica. Execução, validação, toast e invalidação continuam sob
+responsabilidade de `ActionForm`.
+
+Nesse modo, qualquer campo do schema de input pode ser posicionado, mesmo sem entrada em `fields`;
+nesse caso, o rótulo exibido é o próprio nome técnico do campo e não há ajuda. Declare o campo em
+`fields` para nomeá-lo.
 
 ```tsx preview col md
 <DocBrowserActionProvider>
   <ActionForm action={docWorkspaceCreate}>
-    <div className="space-y-6">
-      <div className="grid grid-cols-2 gap-4">
-        <ActionFormField name="name" />
-        <ActionFormField name="status" />
-      </div>
-      <ActionFormField name="contact" />
-      <ActionFormField name="notes" />
+    <div className="grid grid-cols-2 gap-4">
+      <ActionFormField name="name" />
+      <ActionFormField name="status" />
     </div>
+    <ActionFormField name="contact" />
+    <ActionFormField name="notes" />
   </ActionForm>
 </DocBrowserActionProvider>
 ```
 
 ## Valores iniciais e rótulos
 
-`defaultValues` preenche o formulário para edição. Criação e edição comuns mantêm o rótulo padrão
-`Salvar`; use `submitLabel` somente quando a operação pedir outro verbo, como `Renomear`.
-`onCancel` devolve ao consumidor a decisão de fechar um painel ou navegar para outra página.
+`defaultValues` preenche o formulário antes da primeira alteração. Em uma edição, carregue ali os
+valores atuais do registro; em uma criação, use-o para sugerir um ponto de partida, como o status
+inicial do exemplo. A ação principal continua desabilitada até que a pessoa altere algum campo.
+
+Criação e edição comuns mantêm o rótulo padrão `Salvar`; use `submitLabel` somente quando a
+operação pedir outro verbo, como `Renomear`. `onCancel` acrescenta `Cancelar` e devolve ao
+consumidor a decisão de fechar um painel ou navegar para outra página.
 
 ```tsx preview col md
 <DocBrowserActionProvider>
   <ActionForm
     action={docWorkspaceCreate}
-    defaultValues={{ name: "Empresa X", status: "active" }}
+    defaultValues={{ status: "active" }}
     onCancel={() => undefined}
   />
 </DocBrowserActionProvider>
@@ -50,58 +77,17 @@ invalidação continuam sob responsabilidade de `ActionForm`.
 
 ## Formulário modal
 
-[`ActionFormDialog`](/ui/action-form-dialog) acrescenta a moldura, o corpo rolável e o footer ao formulário. Por padrão, as
-ações ficam alinhadas no fim da faixa e preservam a largura do conteúdo; `Cancelar` usa `ghost`.
-Use `footerDistribution="equal"` somente quando as duas decisões precisarem do mesmo peso visual.
-Nesse caso, o cancelamento muda para `outline`, salvo escolha explícita em `cancelVariant`.
-As propriedades do wrapper estão documentadas na página dele.
-
-## Pré-requisitos
-
-Monte os providers de consulta e execução uma vez na raiz do aplicativo:
+[`ActionFormDialog`](/ui/action-form-dialog) acrescenta a moldura, o corpo rolável e o rodapé ao
+formulário. Por padrão, as ações ficam alinhadas no fim da faixa e preservam a largura do conteúdo;
+`Cancelar` usa `ghost`. Use `footerDistribution="equal"` somente quando as duas decisões precisarem
+do mesmo peso visual. Nesse caso, o cancelamento muda para `outline`, salvo escolha explícita em
+`cancelVariant`. Para apresentar o formulário como uma seção delimitada da página, use
+[`ActionFormCard`](/ui/action-form-card). As propriedades de cada wrapper estão na página dele.
 
-```tsx
-/* main.tsx do app. */
-<QueryClientProvider client={queryClient}>
-  <OpusProvider client={apiClient}>
-    <App />
-  </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                                                                                                                                                                               |
-| ------------------------------------------------------ | ----------------------------------------------------- | --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `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 / cancelVariant / onCancel` | `string / string / 'ghost' \| 'outline' / () => void` | `'Salvar' / 'Cancelar' / 'ghost'` | Rodapé do form — o Cancelar só aparece com onCancel. Fora de um modal, mantenha `ghost`; o `ActionFormDialog` usa `outline` somente com `footerDistribution="equal"`.                                                                    |
-| `disabled`                                             | `boolean`                                             | `false`                           | Bloqueia campos e ações sem desmontar o formulário. |
-| `onLoadingChange`                                      | `(loading: boolean) => void`                          |                                   | Informa início e fim da execução a quem coordena ações como um grupo. |
-| `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 automático monta todos os campos na ordem do contrato.                                                        |
+## Ajuda no rótulo
 
-## Propriedades de ActionFormField
-
-| 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` 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.
+`FieldSpec.help` aparece como um ícone junto ao rótulo, com o texto em um tooltip. Escreva ali o
+critério, o efeito ou a limitação que o rótulo não diz; ajuda que só repete o rótulo 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.
 
@@ -110,20 +96,14 @@ 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 htmlFor="billing-contact" className="items-center gap-1.5">
+    <span>Contato</span>
+    <LabelHelp help="Recebe os avisos de faturamento e de integração do workspace." />
   </FieldLabel>
-  <Input id="staff" placeholder="Empresa X" />
+  <Input id="billing-contact" type="email" placeholder="email@cliente.com" />
 </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
@@ -137,7 +117,7 @@ referência; itens estáticos permanecem como declarados no contrato.
 O literal canônico do grupo de escolhas é sempre kebab-case: `widget: 'toggle-group'`. Em enum ele
 renderiza seleção única; em array de enum, seleção múltipla. As opções seguem a mesma precedência e
 o mesmo `SelectOption` rico dos selects. Use esse widget quando cada opção funcionar como uma
-escolha rica em card, com conteúdo de apoio; para uma lista textual comum, prefira `RadioGroup`.
+escolha rica em card, com conteúdo de apoio; para uma lista textual comum, prefira [`RadioGroup`](/ui/radio-group).
 Outros identificadores continuam válidos como metadado
 para renderers próprios; o `ActionForm` aplica sua inferência normal quando não reconhece o widget.
 
@@ -170,3 +150,38 @@ function PermissionGrid() {
 
 O contexto também expõe `shape` (Zod por campo), `fields` (FieldSpec) e `fieldOptions`.
 Fora de um `<ActionForm>`, o hook lança um erro que informa o provider ausente.
+
+## 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                                                                                                                                                                               |
+| ------------------------------------------------------ | ----------------------------------------------------- | --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `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: os dados atuais do registro em uma edição ou uma sugestão em uma criação. Não contam como alteração para habilitar a ação principal. |
+| `onSuccess`                                            | `(data: TData) => void`                               |                                   | Pós-sucesso (o toast e a invalidação de cache já aconteceram).                                                                                                                          |
+| `submitLabel / cancelLabel / cancelVariant / onCancel` | `string / string / 'ghost' \| 'outline' / () => void` | `'Salvar' / 'Cancelar' / 'ghost'` | Rodapé do form — o Cancelar só aparece com onCancel. Fora de um modal, mantenha `ghost`; o `ActionFormDialog` usa `outline` somente com `footerDistribution="equal"`.                                                                    |
+| `disabled`                                             | `boolean`                                             | `false`                           | Bloqueia campos e ações sem desmontar o formulário. |
+| `onLoadingChange`                                      | `(loading: boolean) => void`                          |                                   | Informa início e fim da execução a quem coordena ações como um grupo. |
+| `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 modo automático monta um campo por chave de `fields`, na ordem declarada; campo sem entrada em `fields` não aparece. |
+
+## Propriedades de ActionFormField
+
+| Propriedade | Tipo             | Descrição                                                                      |
+| ----------- | ---------------- | ------------------------------------------------------------------------------ |
+| `name`      | `string`         | O campo do schema de input. Sem entrada em `fields`, usa o nome técnico como rótulo; 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` em uma grid).                          |
+
+## Propriedades de LabelHelp
+
+| Propriedade | Tipo     | Descrição                                                    |
+| ----------- | -------- | ------------------------------------------------------------ |
+| `help`      | `string` | O texto do tooltip. Vazio ou ausente, o ícone não renderiza. |