@softize/opus 12.11.0 → 13.1.0

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

@@ -1,8 +1,8 @@
-## Painel de detalhe (à direita)
+## Painel lateral de detalhe
 
-O painel que desliza de uma borda da tela — modal, com overlay, trap de foco e ESC (o motor é o Dialog do Radix). A régua contra o irmão: conteúdo curto e CENTRADO → `Dialog`; painel na borda que preserva o contexto atrás → `Drawer`.
-
-side='right' desliza da borda direita. ESC, clique no overlay e o X fecham — sem estado manual. É o lugar de detalhe/edição lateral sem sair do contexto.
+Use `Drawer` para abrir detalhes ou edição junto a uma borda, preservando a referência visual da
+tela ao fundo. Para conteúdo curto e centralizado, prefira `Dialog`. Com `side="right"`, o painel
+entra pela direita e pode ser fechado por Esc, pelo overlay ou pelo botão de fechamento.
 
 ```tsx preview
 <Drawer>
@@ -21,9 +21,12 @@ side='right' desliza da borda direita. ESC, clique no overlay e o X fecham — s
 </Drawer>
 ```
 
-## Edição com rodapé (à esquerda)
+## Edição com ações persistentes
 
-side aceita top|right|bottom|left. DrawerFooter ancora as ações no rodapé; DrawerClose fecha sem estado manual.
+`side` aceita `top`, `right`, `bottom` e `left`. `DrawerFooter` mantém as ações no rodapé;
+`DrawerClose` fecha o painel sem exigir controle manual de estado. Como no `Dialog`, o cabeçalho
+recebe um divisor inferior e o rodapé usa divisor superior sobre fundo sutil. O corpo preserva o
+mesmo alinhamento horizontal entre título, conteúdo e ações.
 
 ```tsx preview
 <Drawer>
@@ -40,19 +43,29 @@ side aceita top|right|bottom|left. DrawerFooter ancora as ações no rodapé; Dr
     </DrawerBody>
     <DrawerFooter>
       <DrawerClose asChild>
-        <Button variant="ghost" size="sm">Cancelar</Button>
+        <Button variant="ghost">Cancelar</Button>
       </DrawerClose>
-      <Button size="sm">Salvar alterações</Button>
+      <Button>Salvar alterações</Button>
     </DrawerFooter>
   </DrawerContent>
 </Drawer>
 ```
 
-## Props
+## Propriedades de Drawer
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `open` | `boolean` | | Estado no modo controlado. |
+| `onOpenChange` | `(open: boolean) => void` | | Atualiza o estado para permitir abertura ou fechamento por código. |
+
+## Propriedades de DrawerContent
 
-| Prop | Tipo | Default | Descrição |
+| Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
-| `DrawerContent.side` | `'top' \| 'right' \| 'bottom' \| 'left'` | `'right'` | Borda de onde o painel desliza. |
-| `DrawerContent.showCloseButton` | `boolean` | `true` | Mostra o X de fechar no canto. Desligue pra painel que exige ação explícita. |
-| `DrawerBody` | `HTMLAttributes<HTMLDivElement>` | Região flexível e rolável | Corpo principal entre header e footer. |
-| `Drawer.open / onOpenChange` | `boolean / (open: boolean) => void` | | Modo controlado (Radix) — pra abrir/fechar por código (ex.: detalhe de um item selecionado). |
+| `side` | `'top' \| 'right' \| 'bottom' \| 'left'` | `'right'` | Borda de onde o painel aparece. |
+| `showCloseButton` | `boolean` | `true` | Exibe o botão de fechamento. Desative quando o painel exigir uma ação explícita. |
+
+## Propriedades de DrawerBody
+
+`DrawerBody` aceita os atributos de `HTMLDivElement` e ocupa a região flexível e rolável entre
+`DrawerHeader` e `DrawerFooter`.

package/src/ui/docs/content/empty-value.md

@@ -40,9 +40,9 @@ columns: [
 ]
 ```
 
-## Props
+## Propriedades de EmptyValue
 
-| Prop | Tipo | Default | Descrição |
+| Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
 | `label` | `string` | `'Não informado'` | O que a ausência significa neste domínio. |
 | `compact` | `boolean` | `false` | Célula compacta: travessão visível, rótulo só para leitura assistiva. |

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

@@ -10,7 +10,8 @@ no pai para evitar uma moldura dupla.
 
 ## Com ícone
 
-EmptyMedia variant=icon desenha o quadrado de fundo muted atrás do ícone; o EmptyHeader agrupa mídia, título e descrição no centro.
+`EmptyMedia variant="icon"` aplica uma moldura quadrada e muted ao ícone. `EmptyHeader` mantém mídia,
+título e descrição agrupados no centro.
 
 ```tsx preview col
 <Empty>
@@ -20,7 +21,7 @@ EmptyMedia variant=icon desenha o quadrado de fundo muted atrás do ícone; o Em
     </EmptyMedia>
     <EmptyTitle>Nenhum repositório vinculado</EmptyTitle>
     <EmptyDescription>
-      O workspace Empresa X ainda não tem repositórios. Vincule um pra abrir sessões.
+      O workspace Empresa X ainda não tem repositórios. Vincule um para abrir sessões.
     </EmptyDescription>
   </EmptyHeader>
 </Empty>
@@ -28,7 +29,7 @@ EmptyMedia variant=icon desenha o quadrado de fundo muted atrás do ícone; o Em
 
 ## Com ação
 
-EmptyContent guarda os botões abaixo do header — é o lugar da chamada pra ação que resolve o vazio.
+`EmptyActions` organiza abaixo do cabeçalho as ações que permitem sair do estado vazio.
 
 ```tsx preview col
 <Empty>
@@ -38,21 +39,22 @@ EmptyContent guarda os botões abaixo do header — é o lugar da chamada pra a
     </EmptyMedia>
     <EmptyTitle>Sem skills neste agente</EmptyTitle>
     <EmptyDescription>
-      O agente developer não tem skills anexadas. Adicione clean-code ou test pra começar.
+      O agente developer não tem skills anexadas. Adicione clean-code ou test para começar.
     </EmptyDescription>
   </EmptyHeader>
-  <EmptyContent>
+  <EmptyActions>
     <Button>
       <Plus />
       Anexar skill
     </Button>
-  </EmptyContent>
+  </EmptyActions>
 </Empty>
 ```
 
-## Mídia default
+## Mídia sem moldura
 
-EmptyMedia variant=default (o padrão) não desenha fundo — bom pra uma ilustração ou um ícone maior que se sustenta sozinho.
+`EmptyMedia` sem `variant` (o padrão, `default`) não desenha fundo. Use essa forma para ilustrações
+ou mídias que tenham presença visual própria.
 
 ```tsx preview col
 <Empty>
@@ -68,9 +70,14 @@ EmptyMedia variant=default (o padrão) não desenha fundo — bom pra uma ilustr
 </Empty>
 ```
 
-## Props
+## Propriedades de Empty
 
-| Prop | Tipo | Default | Descrição |
+| Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
-| `variant (EmptyMedia)` | `'default' \| 'icon'` | `'default'` | icon desenha o quadrado de fundo muted atrás da mídia; default não desenha fundo. |
-| `className (Empty)` | `string` | | A moldura já vem tracejada e centrada — ajuste espaçamento ou borda por aqui. |
+| `className` | `string` | | Classes aplicadas à moldura tracejada e centralizada. |
+
+## Propriedades de EmptyMedia
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `variant` | `'default' \| 'icon'` | `'default'` | `icon` aplica uma moldura quadrada e muted; `default` exibe a mídia sem fundo. |

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

@@ -4,9 +4,9 @@ title: Eventos
 
 # Eventos
 
-O handler anuncia que algo aconteceu (`ctx.emit`) sem saber quem escuta. Reactions (e
-integrações) assinam e reagem. O barramento é um adapter do core (`EventBusAdapter`); o
-formato do evento é preservado de ponta a ponta.
+Use eventos quando uma action precisar anunciar um fato sem conhecer seus consumidores.
+`ctx.emit` publica o evento; reactions e integrações podem assiná-lo pelo `EventBusAdapter`. O
+formato declarado permanece o mesmo durante todo o fluxo.
 
 ## O contrato
 
@@ -55,7 +55,7 @@ Actions declaram no contrato o que emitem (`emits: ['nota.emitida']`); o runtime
 o handler emitir algo não-declarado (`emitMode`). Uma reaction assina `nota.emitida` e roda
 como sua própria action rastreável (provenance `reaction`).
 
-## Limites (por enquanto)
+## Limites atuais
 
 O driver `mitt` é in-process — sem durabilidade nem entre-processos. Barramentos duráveis/
 distribuídos (Redis, NATS…) entram por reincidência de caso real.

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

@@ -1,6 +1,8 @@
-## Campo vertical
+## Campo empilhado
 
-A composição base: FieldLabel (htmlFor↔id), o controle e FieldDescription como ajuda — empilhados, com o respiro do Field. O rótulo usa a mesma hierarquia compacta de `DetailField`; quando o campo é inválido, muda explicitamente para o tom destrutivo.
+Use `Field` para manter rótulo, controle, ajuda e erro com espaçamento consistente. Na orientação
+vertical, `FieldLabel`, o controle e `FieldDescription` ficam empilhados. Quando o controle usa
+`aria-invalid`, o rótulo acompanha o contexto de erro.
 
 ```tsx preview col md
 <Field>
@@ -12,7 +14,8 @@ A composição base: FieldLabel (htmlFor↔id), o controle e FieldDescription co
 
 ## Horizontal com toggle
 
-orientation=horizontal põe o controle na lateral e a label à esquerda. FieldContent agrupa título e descrição num bloco; FieldTitle é o rótulo de texto quando o controle não é um <label>.
+`orientation="horizontal"` posiciona o controle ao lado do texto. `FieldContent` agrupa título e
+descrição; `FieldTitle` nomeia o campo quando o texto não puder ser um `<label>`.
 
 ```tsx preview col md
 <Field orientation="horizontal">
@@ -26,7 +29,8 @@ orientation=horizontal põe o controle na lateral e a label à esquerda. FieldCo
 
 ## Conjunto com legenda e erro
 
-FieldSet agrupa campos sob uma FieldLegend; FieldGroup dá o espaçamento entre eles; FieldSeparator marca uma divisão. FieldError mostra a mensagem só quando há erro (aria-invalid no controle casa o visual).
+`FieldSet` agrupa campos sob uma `FieldLegend`; `FieldGroup` define o espaçamento e
+`FieldSeparator` marca uma divisão. `FieldError` aparece somente quando existe mensagem de erro.
 
 ```tsx preview col md
 <FieldSet>
@@ -35,7 +39,7 @@ FieldSet agrupa campos sob uma FieldLegend; FieldGroup dá o espaçamento entre
     <Field>
       <FieldLabel htmlFor="agent-name">Nome</FieldLabel>
       <Input id="agent-name" defaultValue="" aria-invalid placeholder="Ex.: developer" />
-      <FieldError>Informe um nome pro agente.</FieldError>
+      <FieldError>Informe um nome para o agente.</FieldError>
     </Field>
     <FieldSeparator />
     <Field>
@@ -47,12 +51,30 @@ FieldSet agrupa campos sob uma FieldLegend; FieldGroup dá o espaçamento entre
 </FieldSet>
 ```
 
-## Props
+## Propriedades de Field
 
-| Prop | Tipo | Default | Descrição |
+| Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
-| `orientation` (Field) | `'vertical' \| 'horizontal' \| 'responsive'` | `'vertical'` | Direção do campo: vertical empilha; horizontal põe o controle ao lado (bom pra toggle); responsive vira horizontal a partir de @md. |
-| `variant` (FieldLegend) | `'legend' \| 'label'` | `'legend'` | Tamanho da legenda do FieldSet — legend é o título da seção; label encolhe pro porte de rótulo. |
-| `errors` (FieldError) | `Array<{ message?: string }>` | | Lista de erros (ex.: do react-hook-form) — deduplica e vira uma lista. Sem children e sem erros, o FieldError não renderiza. |
-| `children` (FieldError) | `React.ReactNode` | | Mensagem de erro literal — tem prioridade sobre errors quando passada. |
-| `children` (FieldSeparator) | `React.ReactNode` | | Rótulo opcional no meio da linha divisória (ex.: "ou") — sem filhos, é só a linha. |
+| `orientation` | `'vertical' \| 'horizontal' \| 'responsive'` | `'vertical'` | Direção do campo; `responsive` se torna horizontal a partir do container médio. |
+
+## Propriedades de FieldLegend
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `variant` | `'legend' \| 'label'` | `'legend'` | Define o porte de título de seção ou de rótulo compacto. |
+
+## Propriedades de FieldError
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `errors` | `Array<{ message?: string }>` | | Deduplica e apresenta uma lista de erros; sem conteúdo, o componente não renderiza. |
+| `children` | `ReactNode` | | Mensagem literal, com prioridade sobre `errors`. |
+
+## Propriedades de FieldSeparator
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `children` | `ReactNode` | | Rótulo opcional no centro da divisão; sem conteúdo, exibe somente a linha. |
+
+`FieldSet`, `FieldGroup`, `FieldContent`, `FieldLabel`, `FieldTitle` e `FieldDescription` aceitam as
+props nativas dos respectivos elementos e não adicionam propriedades próprias.

package/src/ui/docs/content/getting-started.md

@@ -1,8 +1,8 @@
 ---
-title: Getting started
+title: Primeiros passos
 ---
 
-# Getting started
+# Primeiros passos
 
 O Opus ajuda cliente e servidor a preservar as mesmas regras à medida que uma aplicação
 evolui. Entidades e contratos de action ficam em uma camada compartilhada; o runtime, a UI e
@@ -59,7 +59,7 @@ cd meu-cliente && git init
 pnpm dlx @softize/opus create apps/portal              # o app (modo detectado)
 ```
 
-## Carregar o Opus num projeto existente
+## Carregar o Opus em um projeto existente
 
 > O `opus.json` registra a versão usada pelo projeto. Se o arquivo ainda não existe, o setup
 > cria a estrutura necessária antes das demais etapas.

package/src/ui/docs/content/icon-picker.md

@@ -1,6 +1,8 @@
-O value é o **nome** do ícone (kebab-case, chave da paleta) — quem consome renderiza com a mesma paleta: `iconPickerIcons[name] ?? FallbackIcon`. Selecionar o já-escolhido desmarca (volta a `''`).
+Use `IconPicker` para selecionar um ícone por seu nome em kebab-case. O consumidor renderiza o
+valor com a mesma paleta, por exemplo `iconPickerIcons[name] ?? FallbackIcon`. Selecionar novamente o
+ícone atual limpa o valor.
 
-## Básico
+## Escolher na paleta padrão
 
 ```tsx preview col md
 const [icon, setIcon] = useState('chart-line')
@@ -15,7 +17,8 @@ render(
 
 ## Renderizando o escolhido
 
-A paleta default é exportada (`iconPickerIcons`) — use-a pra desenhar o ícone salvo onde ele aparece (item de lista, card, árvore).
+A paleta padrão é exportada como `iconPickerIcons`. Use a mesma coleção para apresentar o ícone
+salvo em listas, cards e árvores.
 
 ```tsx preview col md
 const [icon, setIcon] = useState('store')
@@ -34,7 +37,8 @@ render(
 
 ## Paleta própria
 
-`icons` troca o vocabulário (nome → componente lucide). A paleta default é curta de propósito — cada ícone importado entra no bundle; monte a sua com o que faz sentido no domínio.
+`icons` substitui a coleção de nomes e componentes Lucide. Mantenha somente os ícones relevantes ao
+domínio, pois cada importação participa do bundle.
 
 ```tsx preview col md
 const [icon, setIcon] = useState('')
@@ -49,3 +53,14 @@ render(
   />,
 )
 ```
+
+## Propriedades de IconPicker
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `value` | `string` | | Nome do ícone selecionado (chave da paleta); `''` é nenhum. |
+| `onChange` | `(name: string) => void` | | Recebe o nome escolhido. |
+| `icons` | `Record<string, LucideIcon>` | `iconPickerIcons` | Paleta nome → componente. |
+| `placeholder` | `string` | `'Selecione um ícone…'` | Texto do gatilho sem seleção. |
+| `disabled` | `boolean` | | Desabilita o gatilho. |
+| `id`, `aria-invalid`, `aria-describedby` | | | Integração com `Field`/`ActionForm`: o gatilho recebe a identidade e o estado de erro do campo. |

package/src/ui/docs/content/input-otp.md

@@ -1,6 +1,7 @@
-## Básico
+## Código em uma sequência
 
-maxLength define quantas casas existem; cada InputOTPSlot recebe o index da sua posição. Um InputOTPGroup envolve as casas.
+`maxLength` define o comprimento do código. Cada `InputOTPSlot` recebe o índice de uma posição e
+`InputOTPGroup` mantém a sequência agrupada.
 
 ```tsx preview
 <InputOTP maxLength={6}>
@@ -17,7 +18,8 @@ maxLength define quantas casas existem; cada InputOTPSlot recebe o index da sua
 
 ## Com separador
 
-Vários grupos com InputOTPSeparator entre eles quebram o código em blocos — os index seguem contínuos (0–5) por cima da divisão visual.
+Use `InputOTPSeparator` entre grupos para dividir visualmente o código. Os índices continuam em uma
+única sequência apesar da separação.
 
 ```tsx preview
 <InputOTP maxLength={6}>
@@ -37,7 +39,8 @@ Vários grupos com InputOTPSeparator entre eles quebram o código em blocos —
 
 ## Controlado
 
-value + onChange deixam o código no seu estado — bom pra liberar a ação só quando todas as casas estão preenchidas.
+Use `value` e `onChange` quando o estado externo precisar validar o comprimento antes de liberar a
+próxima ação.
 
 ```tsx preview col-start
 const [code, setCode] = useState('')
@@ -55,18 +58,23 @@ render(
       </InputOTPGroup>
     </InputOTP>
     <p className="text-sm text-muted-foreground">
-      {code.length === 6 ? 'Código pronto pra confirmar o acesso ao workspace.' : 'Digite o código de 6 dígitos.'}
+      {code.length === 6 ? 'Código pronto para confirmar o acesso ao workspace.' : 'Digite o código de 6 dígitos.'}
     </p>
   </>,
 )
 ```
 
-## Props
+## Propriedades de InputOTP
 
-| Prop | Tipo | Default | Descrição |
+| Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
-| `maxLength` (InputOTP) | `number` | | Quantas casas o código tem — defina um InputOTPSlot por posição. |
-| `value` (InputOTP) | `string` | | O código no modo controlado — parear com onChange. |
-| `onChange` (InputOTP) | `(value: string) => void` | | Chamado a cada dígito; recebe o código acumulado. |
-| `disabled` (InputOTP) | `boolean` | `false` | Esmaece e bloqueia a digitação do conjunto inteiro. |
-| `index` (InputOTPSlot) | `number` | | A posição da casa (0-based); liga o slot ao dígito correspondente. |
+| `maxLength` | `number` | | Quantidade de posições do código. Defina um `InputOTPSlot` para cada posição. |
+| `value` | `string` | | Código no modo controlado. Use com `onChange`. |
+| `onChange` | `(value: string) => void` | | Chamado a cada entrada com o código acumulado. |
+| `disabled` | `boolean` | `false` | Desabilita a digitação em todo o conjunto. |
+
+## Propriedades de InputOTPSlot
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `index` | `number` | | Posição do caractere, começando em zero. |

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

@@ -1,6 +1,7 @@
-## Básico
+## Campo de uma linha
 
-Placeholder orienta o formato, não substitui o rótulo — em formulário de verdade, pareie com Label.
+Use `Input` para texto de uma linha. O placeholder pode sugerir formato ou exemplo, mas não substitui
+o rótulo; em formulários, associe o campo a `Label`.
 
 ```tsx preview col md
 <Input placeholder="Ex.: empresa-x" />
@@ -8,7 +9,8 @@ Placeholder orienta o formato, não substitui o rótulo — em formulário de ve
 
 ## Ícone dentro do campo
 
-`icon` põe um ícone LEADING dentro do campo — identidade (calendário na data, prédio na filial). É a MESMA prop do Select e do Alert: adorno de campo é **prop**, não composição à mão nem ícone jogado ao lado (que desalinha na quebra de linha e some no responsivo). Decorativo — quem nomeia é o Label.
+`icon` posiciona um ícone decorativo no início do campo. Use-o para reforçar a natureza do valor,
+como calendário em uma data; o `Label` continua responsável pelo nome acessível.
 
 ```tsx preview col md
 <div className="grid gap-2">
@@ -17,12 +19,13 @@ Placeholder orienta o formato, não substitui o rótulo — em formulário de ve
 </div>
 ```
 
-Pra mais que um ícone — um botão no fim, um prefixo de texto, adorno em bloco — aí é `InputGroup` (a composição rica). Só o ícone leading é a prop.
+Quando o campo precisar combinar vários adornos, prefixos ou botões, use `InputGroup`.
 
 
 ## Ação no fim do campo (trailing)
 
-`trailing` é o par do `icon`: uma ação DENTRO do campo, no fim — um botão que age sobre o valor (limpar, mostrar senha). Igual ao Select. Diferente do ícone (decorativo), o trailing é interativo.
+`trailing` posiciona no fim do campo uma ação relacionada ao valor, como limpar ou mostrar uma
+senha. Diferentemente de `icon`, essa região pode ser interativa.
 
 ```tsx preview col md
 function Demo() {
@@ -45,11 +48,11 @@ function Demo() {
 render(<Demo />)
 ```
 
-Pra MAIS de um adorno junto (ícone + botão + prefixo de texto), aí é `InputGroup`. Um ícone e/ou uma ação → props.
+Para combinar mais de um adorno, use `InputGroup`.
 
 ## Com Label
 
-htmlFor aponta pro id do campo — clicar no rótulo foca o input.
+Associe `htmlFor` no `Label` ao `id` do campo para que o clique no rótulo mova o foco.
 
 ```tsx preview col md
 <div className="grid gap-2">
@@ -60,7 +63,8 @@ htmlFor aponta pro id do campo — clicar no rótulo foca o input.
 
 ## Tipos nativos
 
-type é o atributo nativo de <input> — teclado, máscara e validação vêm do browser de graça.
+`type` é repassado ao `<input>` nativo, permitindo que o navegador escolha teclado e validação
+adequados.
 
 ```tsx preview col md
 <Input type="email" placeholder="Ex.: joao@softize.com.br" />
@@ -70,9 +74,117 @@ type é o atributo nativo de <input> — teclado, máscara e validação vêm do
 
 ## Estados
 
-Inválido é aria-invalid (borda e anel destructive) — semântica e visual na mesma prop, sem classe de erro à parte. disabled esmaece e bloqueia.
+Use `aria-invalid` para comunicar e apresentar o estado inválido. `disabled` impede interação e
+aplica o tratamento visual correspondente.
 
 ```tsx preview col md
 <Input aria-invalid defaultValue="empresa x" placeholder="Slug do workspace" />
 <Input disabled defaultValue="softize-multica" />
 ```
+
+## Propriedades de Input
+
+Além das props abaixo, `Input` aceita os atributos nativos de `<input>`.
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `icon` | `ReactNode` | | Ícone decorativo no início do campo. |
+| `trailing` | `ReactNode` | | Ação interativa no fim do campo. |
+| `type` | `string` | | Tipo nativo do campo, como `text`, `email`, `password` ou `number`. |
+
+## InputGroup
+
+Use `InputGroup` quando o campo precisar combinar vários adornos, prefixos, sufixos ou ações em uma
+única moldura. Para somente um ícone ou uma ação no fim, continue usando `icon` ou `trailing` em
+`Input`.
+
+### Com ícone e ação
+
+`InputGroupAddon` ancora os adornos nas extremidades. O clique em uma área inerte do addon transfere
+o foco para o campo.
+
+```tsx preview col
+<InputGroup>
+  <InputGroupAddon><Search /></InputGroupAddon>
+  <InputGroupInput placeholder="Buscar agente" defaultValue="reviewer" />
+  <InputGroupAddon align="inline-end">
+    <InputGroupButton size="icon-xs" aria-label="Limpar filtro"><X /></InputGroupButton>
+  </InputGroupAddon>
+</InputGroup>
+```
+
+### Prefixo e sufixo
+
+`InputGroupText` apresenta texto inerte dentro da moldura.
+
+```tsx preview col
+<InputGroup>
+  <InputGroupAddon>
+    <GitBranch />
+    <InputGroupText>github.com/softize/</InputGroupText>
+  </InputGroupAddon>
+  <InputGroupInput placeholder="empresa-x-api" />
+  <InputGroupAddon align="inline-end"><InputGroupText>.git</InputGroupText></InputGroupAddon>
+</InputGroup>
+```
+
+### Composer com rodapé
+
+Com `InputGroupTextarea`, um addon em `block-end` forma uma região de ações abaixo do texto.
+
+```tsx preview col
+<InputGroup>
+  <InputGroupTextarea placeholder="Descreva a tarefa para o agente developer" rows={3} />
+  <InputGroupAddon align="block-end">
+    <InputGroupText><Sparkles /> Título gerado pela IA</InputGroupText>
+    <InputGroupButton
+      size="sm"
+      context="primary"
+      variant="solid"
+      className="ml-auto"
+      aria-label="Enviar tarefa"
+    >
+      Enviar <ArrowUp />
+    </InputGroupButton>
+  </InputGroupAddon>
+</InputGroup>
+```
+
+### Propriedades de InputGroup
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `shape` | `'default' \| 'pill'` | `'default'` | Geometria da moldura compartilhada. |
+
+### Propriedades de InputGroupAddon
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `align` | `'inline-start' \| 'inline-end' \| 'block-start' \| 'block-end'` | `'inline-start'` | Posição do addon nas laterais ou acima/abaixo do controle. |
+
+### Propriedades de InputGroupButton
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `size` | `'xs' \| 'sm' \| 'icon-xs' \| 'icon-sm'` | `'xs'` | Tamanho do botão embutido; as variantes `icon-*` são quadradas. |
+| `context` | `'neutral' \| 'primary' \| 'danger'` | `'primary'` | Contexto semântico herdado de Button. |
+| `variant` | `'solid' \| 'subtle' \| 'outline' \| 'ghost' \| 'link'` | `'ghost'` | Tratamento visual; use `solid` quando a ação precisar de ênfase. |
+
+### Propriedades de InputGroupInput
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `value` / `defaultValue` | `string` | | Valor controlado ou inicial do `<input>`. |
+| `placeholder` | `string` | | Exemplo ou formato esperado quando o campo está vazio. |
+
+### Propriedades de InputGroupTextarea
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `value` / `defaultValue` | `string` | | Valor controlado ou inicial do `<textarea>`. |
+| `placeholder` | `string` | | Exemplo ou orientação exibida quando o campo está vazio. |
+| `rows` | `number` | | Número inicial de linhas visíveis. |
+
+### Propriedades de InputGroupText
+
+`InputGroupText` aceita as props nativas de `<span>` e não adiciona propriedades próprias.

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

@@ -1,8 +1,8 @@
-## Básico
+## Linha composta
 
 A composição completa usa `ItemMedia` à esquerda, `ItemHeader` (`ItemTitle` +
-`ItemDescription`) no meio e `ItemActions` à direita. A mídia acompanha a altura útil do header,
-mantendo ícone, imagem ou avatar centralizado. `variant="outline"` desenha a borda.
+`ItemDescription`) no meio e `ItemActions` à direita. Ícone e imagem mantêm uma moldura quadrada
+alinhada ao topo, mesmo quando a descrição ocupa mais linhas. `variant="outline"` desenha a borda.
 
 ```tsx preview col
 <Item variant="outline">
@@ -25,7 +25,7 @@ mantendo ícone, imagem ou avatar centralizado. `variant="outline"` desenha a bo
 
 ## Lista emoldurada
 
-`ItemGroup variant="framed"` aplica a superfície canônica. Os divisores continuam explícitos com `ItemSeparator`, tanto no modo `framed` quanto no `plain` — o padrão pra listas de repositórios, agentes ou sessões.
+`ItemGroup variant="framed"` aplica a superfície canônica. Os divisores continuam explícitos com `ItemSeparator`, tanto no modo `framed` quanto no `plain` — o padrão para listas de repositórios, agentes ou sessões.
 
 ```tsx preview col
 <ItemGroup variant="framed">
@@ -59,7 +59,7 @@ mantendo ícone, imagem ou avatar centralizado. `variant="outline"` desenha a bo
 
 ## Clicável e compacto
 
-asChild funde o Item num <a> — a linha inteira vira alvo (hover no fundo). size=sm aperta o respiro; ItemMedia variant=image ancora um avatar.
+asChild funde o Item em um <a> — a linha inteira vira alvo (hover no fundo). size=sm aperta o respiro; ItemMedia variant=image ancora um avatar.
 
 ```tsx preview col
 <Item asChild size="sm" variant="outline">
@@ -100,12 +100,26 @@ Use `ItemBody` quando a linha também apresenta um valor ou controle que não pe
 `ItemContent` permanece exportado somente para compatibilidade durante a versão 12. Código novo
 usa `ItemHeader` ou `ItemBody` conforme o papel do conteúdo.
 
-## Props
+## Propriedades de Item
 
-| Prop                  | Tipo                                | Default     | Descrição                                                                                                                               |
-| --------------------- | ----------------------------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------- |
-| `variant` (ItemGroup) | `'plain' \| 'framed'`               | `'plain'`   | `framed` aplica moldura e superfície; `plain` mantém a composição livre. Os divisores são explícitos nos dois modos.                    |
-| `variant` (Item)      | `'default' \| 'outline' \| 'muted'` | `'default'` | O fundo da linha — default transparente, outline com borda, muted levemente tingido.                                                    |
-| `size` (Item)         | `'default' \| 'sm'`                 | `'default'` | O respiro interno — sm aperta o padding pra listas densas.                                                                              |
-| `asChild` (Item)      | `boolean`                           | `false`     | Funde o Item no filho (ex.: <a> ou <button>) — a linha inteira vira o alvo.                                                             |
-| `variant` (ItemMedia) | `'default' \| 'icon' \| 'image'`    | `'default'` | A moldura da mídia — `icon` tem largura estável e acompanha a altura do header; `image` recorta a imagem; `default` não adiciona fundo. |
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `variant` | `'default' \| 'outline' \| 'muted'` | `'default'` | O fundo da linha: transparente, com borda ou levemente tingido. |
+| `size` | `'default' \| 'sm'` | `'default'` | O respiro interno; `sm` atende listas densas. |
+| `asChild` | `boolean` | `false` | Funde o Item no filho para que a linha inteira assuma sua semântica. |
+
+## Propriedades de ItemGroup
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `variant` | `'plain' \| 'framed'` | `'plain'` | `framed` aplica moldura e superfície; os divisores permanecem explícitos nos dois modos. |
+
+## Propriedades de ItemMedia
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `variant` | `'default' \| 'icon' \| 'image'` | `'default'` | Define mídia livre ou uma moldura quadrada para ícone ou imagem. |
+
+`ItemHeader`, `ItemTitle`, `ItemDescription`, `ItemBody`, `ItemActions`, `ItemFooter` e
+`ItemSeparator` aceitam as props nativas dos respectivos elementos e não adicionam propriedades
+próprias. `ItemContent` preserva esse mesmo contrato somente durante a migração da versão 12.