@softize/opus 19.0.0 → 20.0.0

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

@@ -37,7 +37,12 @@ function InputGroup({ className, shape = 'default', ...props }: React.ComponentP
 }
 
 const inputGroupAddonVariants = cva(
-  "flex h-auto cursor-text items-center justify-center gap-2 py-1.5 text-sm font-medium text-muted-foreground select-none group-data-[disabled=true]/input-group:opacity-50 [&>kbd]:rounded-[calc(var(--radius)-0.3125rem)] [&>svg:not([class*='size-'])]:size-4",
+  [
+    "flex h-auto cursor-text items-center justify-center gap-2 py-1.5 text-sm font-medium text-muted-foreground select-none group-data-[disabled=true]/input-group:opacity-50 [&>kbd]:rounded-[calc(var(--radius)-0.3125rem)] [&>svg:not([class*='size-'])]:size-4",
+    // O addon acompanha o controle desabilitado sem depender do `data-disabled` manual. Só o
+    // controle conta: um InputGroupButton desabilitado não apaga o grupo inteiro.
+    "group-has-[[data-slot=input-group-control]:disabled]/input-group:opacity-50",
+  ],
   {
     variants: {
       align: {
@@ -72,7 +77,9 @@ function InputGroupAddon({
         if ((e.target as HTMLElement).closest("button")) {
           return
         }
-        e.currentTarget.parentElement?.querySelector("input")?.focus()
+        e.currentTarget.parentElement
+          ?.querySelector<HTMLElement>("input, textarea")
+          ?.focus()
       }}
       {...props}
     />

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

@@ -49,7 +49,7 @@ function InputOTPSlot({
       data-slot="input-otp-slot"
       data-active={isActive}
       className={cn(
-        "relative flex h-9 w-9 items-center justify-center border-y border-r border-input text-sm transition-all outline-none first:rounded-l-md first:border-l last:rounded-r-md aria-invalid:border-context-danger data-[active=true]:z-10 data-[active=true]:border-ring data-[active=true]:ring-[0.1875rem] data-[active=true]:ring-ring/50 data-[active=true]:aria-invalid:border-context-danger data-[active=true]:aria-invalid:ring-context-danger/20 dark:bg-input/30 dark:data-[active=true]:aria-invalid:ring-context-danger/40",
+        "relative flex h-9 w-9 items-center justify-center border-y border-r border-input bg-muted/30 text-sm transition-all outline-none first:rounded-l-md first:border-l last:rounded-r-md aria-invalid:border-context-danger data-[active=true]:z-10 data-[active=true]:border-ring data-[active=true]:ring-[0.1875rem] data-[active=true]:ring-ring/50 data-[active=true]:aria-invalid:border-context-danger data-[active=true]:aria-invalid:ring-context-danger/20 dark:bg-input/30 dark:data-[active=true]:aria-invalid:ring-context-danger/40",
         className
       )}
       {...props}

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

@@ -15,7 +15,7 @@ function Kbd({ className, ...props }: React.ComponentProps<"kbd">) {
   )
 }
 
-function KbdGroup({ className, ...props }: React.ComponentProps<"div">) {
+function KbdGroup({ className, ...props }: React.ComponentProps<"kbd">) {
   return (
     <kbd
       data-slot="kbd-group"

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

@@ -12,6 +12,9 @@ function Label({
       data-slot="label"
       className={cn(
         "flex items-center gap-2 text-sm leading-none font-medium select-none group-data-[disabled=true]:pointer-events-none group-data-[disabled=true]:opacity-50 peer-disabled:cursor-not-allowed peer-disabled:opacity-50",
+        // O Field declara o grupo nomeado `group/field`: sem o sufixo, o Label não enxerga o
+        // `data-disabled` dele e continua aceso ao lado de um controle desabilitado.
+        "group-data-[disabled=true]/field:pointer-events-none group-data-[disabled=true]/field:opacity-50",
         className
       )}
       {...props}

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

@@ -12,6 +12,11 @@ function Menu({
   return <MenuPrimitive.Root data-slot="menu" {...props} />
 }
 
+/**
+ * @deprecated `MenuContent` já renderiza o painel num portal próprio, então envolvê-lo com
+ * `MenuPortal` não muda onde o painel aparece. Use `MenuContent` diretamente. Sai do pacote numa
+ * próxima versão major.
+ */
 function MenuPortal({
   ...props
 }: React.ComponentProps<typeof MenuPrimitive.Portal>) {

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

@@ -59,7 +59,7 @@ function PopoverHeader({ className, ...props }: React.ComponentProps<"div">) {
   )
 }
 
-function PopoverTitle({ className, ...props }: React.ComponentProps<"h2">) {
+function PopoverTitle({ className, ...props }: React.ComponentProps<"div">) {
   return (
     <div
       data-slot="popover-title"

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

@@ -32,13 +32,21 @@ export interface ProgressProps extends React.ComponentProps<typeof ProgressPrimi
 function Progress({
   className,
   value,
+  max = 100,
   context = 'primary',
   ...props
 }: ProgressProps) {
+  // A largura é a fração de `max`, não de 100: `value={3} max={4}` enche três quartos. Um `max`
+  // não positivo cai em 100, como o Radix faz no Root.
+  const scale = max > 0 ? max : 100
+  const percent = ((value ?? 0) / scale) * 100
   return (
     <ProgressPrimitive.Root
       data-slot="progress"
       data-context={context}
+      // O Root precisa do `value` para anunciar o andamento (aria-valuenow, data-state).
+      value={value}
+      max={max}
       className={cn(
         "relative h-2 w-full overflow-hidden rounded-full",
         trackClasses[context],
@@ -49,7 +57,7 @@ function Progress({
       <ProgressPrimitive.Indicator
         data-slot="progress-indicator"
         className={cn("h-full w-full flex-1 transition-all", indicatorClasses[context])}
-        style={{ transform: `translateX(-${100 - (value || 0)}%)` }}
+        style={{ transform: `translateX(-${100 - percent}%)` }}
       />
     </ProgressPrimitive.Root>
   )

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