@softize/opus 22.2.0 → 24.0.0

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

@@ -1,7 +1,7 @@
 ## Alternar painéis relacionados
 
-Use `Tabs` para alternar painéis relacionados no mesmo contexto. O `value` de cada `TabsTrigger`
-corresponde ao `TabsContent` que ele abre. `defaultValue` define a aba inicial no modo não
+Use `Tabs` para alternar painéis relacionados no mesmo contexto. O `value` de cada `TabsListItem`
+corresponde ao `TabsPanel` que ele abre. `defaultValue` define a aba inicial no modo não
 controlado.
 
 `icon` posiciona um ícone decorativo antes do rótulo e normaliza SVGs para `1rem`. Quando a aba
@@ -10,31 +10,31 @@ mostrar somente o ícone, declare `aria-label` para preservar seu nome acessíve
 ```tsx preview col
 <Tabs defaultValue="sessions">
   <TabsList>
-    <TabsTrigger value="overview" icon={<LayoutDashboard />}>
+    <TabsListItem value="overview" icon={<LayoutDashboard />}>
       Visão geral
-    </TabsTrigger>
-    <TabsTrigger value="sessions" icon={<History />}>
+    </TabsListItem>
+    <TabsListItem value="sessions" icon={<History />}>
       Sessões
-    </TabsTrigger>
-    <TabsTrigger value="skills" icon={<Settings />}>
+    </TabsListItem>
+    <TabsListItem value="skills" icon={<Settings />}>
       Skills
-    </TabsTrigger>
+    </TabsListItem>
   </TabsList>
-  <TabsContent value="overview">
+  <TabsPanel value="overview">
     <p className="text-sm text-muted-foreground">
       Resumo do workspace Empresa X.
     </p>
-  </TabsContent>
-  <TabsContent value="sessions">
+  </TabsPanel>
+  <TabsPanel value="sessions">
     <p className="text-sm text-muted-foreground">
       3 sessões nesta semana, 1 em andamento.
     </p>
-  </TabsContent>
-  <TabsContent value="skills">
+  </TabsPanel>
+  <TabsPanel value="skills">
     <p className="text-sm text-muted-foreground">
       6 skills vinculadas aos agentes do workspace.
     </p>
-  </TabsContent>
+  </TabsPanel>
 </Tabs>
 ```
 
@@ -42,25 +42,25 @@ mostrar somente o ícone, declare `aria-label` para preservar seu nome acessíve
 
 Use `framed` quando a navegação e seus painéis precisarem formar um único bloco. A propriedade
 reúne borda, raio e recorte no próprio `Tabs`, mas não aplica fundo: o bloco herda a
-superfície em que foi composto. Por isso, não envolva `Tabs` em um `Card` somente para obter essa
+superfície em que foi composto. Por isso, não envolva `Tabs` em um `Surface` somente para obter essa
 moldura.
 
 ```tsx preview col
 <Tabs defaultValue="overview" framed className="gap-0">
-  <TabsList variant="line" className="px-2 pt-2">
-    <TabsTrigger value="overview">Visão geral</TabsTrigger>
-    <TabsTrigger value="history">Histórico</TabsTrigger>
+  <TabsList>
+    <TabsListItem value="overview">Visão geral</TabsListItem>
+    <TabsListItem value="history">Histórico</TabsListItem>
   </TabsList>
-  <TabsContent value="overview" className="p-4">
+  <TabsPanel value="overview" className="p-4">
     <p className="text-sm text-muted-foreground">
       Resumo do workspace Empresa X.
     </p>
-  </TabsContent>
-  <TabsContent value="history" className="p-4">
+  </TabsPanel>
+  <TabsPanel value="history" className="p-4">
     <p className="text-sm text-muted-foreground">
       Alterações recentes do workspace.
     </p>
-  </TabsContent>
+  </TabsPanel>
 </Tabs>
 ```
 
@@ -73,127 +73,126 @@ altera os painéis associados.
 
 ```tsx preview col
 <Tabs defaultValue="overview" distribution="equal">
-  <TabsList variant="line">
-    <TabsTrigger value="overview">Visão geral</TabsTrigger>
-    <TabsTrigger value="contacts">Contatos</TabsTrigger>
-    <TabsTrigger value="history">Histórico</TabsTrigger>
+  <TabsList>
+    <TabsListItem value="overview">Visão geral</TabsListItem>
+    <TabsListItem value="contacts">Contatos</TabsListItem>
+    <TabsListItem value="history">Histórico</TabsListItem>
   </TabsList>
-  <TabsContent value="overview">Resumo do atendimento.</TabsContent>
-  <TabsContent value="contacts">Tentativas de contato.</TabsContent>
-  <TabsContent value="history">Alterações registradas.</TabsContent>
+  <TabsPanel value="overview">Resumo do atendimento.</TabsPanel>
+  <TabsPanel value="contacts">Tentativas de contato.</TabsPanel>
+  <TabsPanel value="history">Alterações registradas.</TabsPanel>
 </Tabs>
 ```
 
-## Variante line
+## Linha de navegação
 
-Use `variant="line"` em `TabsList` quando a navegação precisar de uma linha-base, como em um
-cabeçalho. Na orientação horizontal, a lista ocupa toda a largura disponível e a aba ativa é
-marcada sobre essa linha, em vez de usar uma superfície preenchida. A linha respeita o recuo do
-contêiner; dentro de `DrawerBody` e `DialogBody`, ela acompanha o alinhamento do restante do corpo
-sem alcançar as laterais da superfície.
+`TabsList` usa uma linha-base porque representa navegação entre painéis, não uma escolha de valor.
+Na orientação horizontal, a lista ocupa toda a largura disponível e a aba ativa é marcada sobre
+essa linha. A linha respeita o recuo do contêiner; dentro de `DrawerBody` e `DialogBody`, ela
+acompanha o alinhamento do restante do corpo sem alcançar as laterais da superfície.
 Cada item contém uma área interativa com a mesma altura de um Button do tamanho correspondente. A
 área permanece transparente e recebe fundo apenas no hover; a aba ativa é indicada pela linha
-primária inferior. Um respiro de `0.375rem` separa o controle dessa linha; em `Tabs framed`, ele
-aumenta para `0.5rem` e acompanha o padding superior da moldura.
+primária inferior. Um respiro de `0.375rem` separa o controle dessa linha. Em `Tabs framed`, a
+lista recebe `0.25rem` nas laterais e no topo, e a mesma medida separa o controle da linha.
 
 ```tsx preview col
 <Tabs defaultValue="agents">
-  <TabsList variant="line">
-    <TabsTrigger value="agents">Agentes</TabsTrigger>
-    <TabsTrigger value="repos">Repositórios</TabsTrigger>
-    <TabsTrigger value="settings">Configurações</TabsTrigger>
+  <TabsList>
+    <TabsListItem value="agents">Agentes</TabsListItem>
+    <TabsListItem value="repos">Repositórios</TabsListItem>
+    <TabsListItem value="settings">Configurações</TabsListItem>
   </TabsList>
-  <TabsContent value="agents">
+  <TabsPanel value="agents">
     <p className="text-sm text-muted-foreground">
       developer, reviewer e designer ativos.
     </p>
-  </TabsContent>
-  <TabsContent value="repos">
+  </TabsPanel>
+  <TabsPanel value="repos">
     <p className="text-sm text-muted-foreground">
       empresa-x-api e empresa-x-web vinculados.
     </p>
-  </TabsContent>
-  <TabsContent value="settings">
+  </TabsPanel>
+  <TabsPanel value="settings">
     <p className="text-sm text-muted-foreground">Preferências do workspace.</p>
-  </TabsContent>
+  </TabsPanel>
 </Tabs>
 ```
 
 ## Vertical
 
-Com `orientation="vertical"`, a lista forma uma coluna. O exemplo usa a variante padrão; com
-`variant="line"`, a marca da aba ativa passa para a lateral do gatilho.
+Com `orientation="vertical"`, a lista forma uma coluna e a marca da aba ativa passa para a lateral
+do gatilho.
 
 ```tsx preview col
 <Tabs defaultValue="prompt" orientation="vertical">
   <TabsList>
-    <TabsTrigger value="prompt">Prompt</TabsTrigger>
-    <TabsTrigger value="skills">Skills</TabsTrigger>
-    <TabsTrigger value="history">Histórico</TabsTrigger>
+    <TabsListItem value="prompt">Prompt</TabsListItem>
+    <TabsListItem value="skills">Skills</TabsListItem>
+    <TabsListItem value="history">Histórico</TabsListItem>
   </TabsList>
-  <TabsContent value="prompt">
+  <TabsPanel value="prompt">
     <p className="text-sm text-muted-foreground">
       O prompt do agente developer.
     </p>
-  </TabsContent>
-  <TabsContent value="skills">
+  </TabsPanel>
+  <TabsPanel value="skills">
     <p className="text-sm text-muted-foreground">
       Skills vinculadas a este agente.
     </p>
-  </TabsContent>
-  <TabsContent value="history">
+  </TabsPanel>
+  <TabsPanel value="history">
     <p className="text-sm text-muted-foreground">
       Sessões anteriores deste agente.
     </p>
-  </TabsContent>
+  </TabsPanel>
 </Tabs>
 ```
 
 ## Tamanho
 
-`size="sm"` no `Tabs` reduz a altura da lista de `2.25rem` para `2rem`. É o par do `sm` de `Button` e
-`Select` para uma fileira densa, como uma toolbar ou um cabeçalho, em que o segmento não deve ficar
-mais alto que os elementos vizinhos.
+`size="sm"` no `Tabs` reduz a área interativa de `2.25rem` para `2rem`. É o par do `sm` de `Button` e
+`Select` para uma fileira densa, como uma toolbar ou um cabeçalho.
 
 ```tsx preview col
 <Tabs defaultValue="preview" size="sm">
   <TabsList>
-    <TabsTrigger value="preview">Preview</TabsTrigger>
-    <TabsTrigger value="code">Código</TabsTrigger>
-    <TabsTrigger value="ai">IA</TabsTrigger>
+    <TabsListItem value="preview">Preview</TabsListItem>
+    <TabsListItem value="code">Código</TabsListItem>
+    <TabsListItem value="ai">IA</TabsListItem>
   </TabsList>
 </Tabs>
 ```
 
 ## Propriedades de Tabs
 
-| Propriedade     | Tipo                         | Padrão         | Descrição                                                                                                                                                |
-| --------------- | ---------------------------- | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `defaultValue`  | `string`                     |                | Aba inicial no modo não controlado.                                                                                                                      |
-| `value`         | `string`                     |                | Aba ativa no modo controlado. Use com `onValueChange`.                                                                                                   |
-| `onValueChange` | `(value: string) => void`    |                | Chamado quando a pessoa seleciona outra aba.                                                                                                             |
-| `size`          | `'default' \| 'sm'`          | `'default'`    | Altura da lista na escala única dos controles (2.25 e 2rem), aplicada em `TabsList`. Não altera a altura de `line` horizontal, que acompanha o conteúdo. |
-| `distribution`  | `'content' \| 'equal'`       | `'content'`    | Preserva a largura dos rótulos ou divide igualmente a largura disponível entre os gatilhos.                                                              |
-| `framed`        | `boolean`                    | `false`        | Aplica borda, raio e recorte ao conjunto sem definir fundo ou foreground.                                                                                |
-| `orientation`   | `'horizontal' \| 'vertical'` | `'horizontal'` | Direção da lista de abas.                                                                                                                                |
+| Propriedade     | Tipo                         | Padrão         | Descrição                                                                                     |
+| --------------- | ---------------------------- | -------------- | --------------------------------------------------------------------------------------------- |
+| `defaultValue`  | `string`                     |                | Aba inicial no modo não controlado.                                                           |
+| `value`         | `string`                     |                | Aba ativa no modo controlado. Use com `onValueChange`.                                        |
+| `onValueChange` | `(value: string) => void`    |                | Chamado quando a pessoa seleciona outra aba.                                                  |
+| `size`          | `'default' \| 'sm'`          | `'default'`    | Altura da área interativa na escala única dos controles (2.25 e 2rem), aplicada aos gatilhos. |
+| `distribution`  | `'content' \| 'equal'`       | `'content'`    | Preserva a largura dos rótulos ou divide igualmente a largura disponível entre os gatilhos.   |
+| `framed`        | `boolean`                    | `false`        | Aplica borda, raio e recorte ao conjunto sem definir fundo ou foreground.                     |
+| `orientation`   | `'horizontal' \| 'vertical'` | `'horizontal'` | Direção da lista de abas.                                                                     |
 
 ## Propriedades de TabsList
 
-| Propriedade | Tipo                  | Padrão      | Descrição                                                                                                                 |
-| ----------- | --------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------- |
-| `variant`   | `'default' \| 'line'` | `'default'` | `default` usa uma superfície preenchida; `line` cria uma linha-base horizontal de largura total e marca nela a aba ativa. |
+| Propriedade  | Tipo     | Padrão | Descrição                                                         |
+| ------------ | -------- | ------ | ----------------------------------------------------------------- |
+| `aria-label` | `string` |        | Nomeia a navegação quando não houver um rótulo visível associado. |
+| `className`  | `string` |        | Ajusta a composição externa sem substituir a linha de navegação.  |
 
-## Propriedades de TabsTrigger
+## Propriedades de TabsListItem
 
 | Propriedade | Tipo        | Padrão  | Descrição                                                                                       |
 | ----------- | ----------- | ------- | ----------------------------------------------------------------------------------------------- |
-| `value`     | `string`    |         | Identificador que associa o gatilho ao `TabsContent` correspondente.                            |
+| `value`     | `string`    |         | Identificador que associa o gatilho ao `TabsPanel` correspondente.                              |
 | `icon`      | `ReactNode` |         | Ícone decorativo antes do rótulo, em `1rem`. Em uma aba sem texto, declare também `aria-label`. |
 | `disabled`  | `boolean`   | `false` | Impede a seleção da aba.                                                                        |
 
-## Propriedades de TabsContent
+## Propriedades de TabsPanel
 
-| Propriedade  | Tipo     | Padrão | Descrição                                                              |
-| ------------ | -------- | ------ | ---------------------------------------------------------------------- |
-| `value`      | `string` |        | Identificador do painel, igual ao `value` do `TabsTrigger` que o abre. |
-| `forceMount` | `true`   |        | Mantém o painel montado mesmo quando outra aba está ativa.             |
+| Propriedade  | Tipo     | Padrão | Descrição                                                               |
+| ------------ | -------- | ------ | ----------------------------------------------------------------------- |
+| `value`      | `string` |        | Identificador do painel, igual ao `value` do `TabsListItem` que o abre. |
+| `forceMount` | `true`   |        | Mantém o painel montado mesmo quando outra aba está ativa.              |

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

@@ -90,9 +90,8 @@ expect(emitted).toEqual([{ event: 'task.done', data: { id: '1' } }])
 
 Os dados que o modo design mostra não são comportamento da action e não precisam de teste de
 unidade: o plugin `opusDesign()` os gera a partir do contrato (ver
-[Actions](/docs/actions)). Enquanto o `mockHandler` existir, obsoleto desde a 22.1.0,
-`runAction` com `OPUS_MODE=design` ainda o executa, como o runtime. Teste a action ligada ao
-handler em vez dele.
+[Actions](/docs/actions)). `runAction` executa somente a action ligada ao handler; use cenários do
+plugin para respostas específicas do modo design.
 
 ## memStorage
 

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

@@ -14,24 +14,20 @@ inicial no modo não controlado; o conteúdo pode ser texto ou ícone.
 Use `pressed` e `onPressedChange` quando o estado pertencer ao consumidor.
 
 ```tsx preview
-const [readOnly, setReadOnly] = useState(true)
+const [readOnly, setReadOnly] = useState(true);
 
 render(
-  <Toggle
-    variant="outline"
-    pressed={readOnly}
-    onPressedChange={setReadOnly}
-  >
+  <Toggle variant="outline" pressed={readOnly} onPressedChange={setReadOnly}>
     <Eye />
     Somente leitura
   </Toggle>,
-)
+);
 ```
 
 ## Variantes e tamanhos
 
-Na variante `default`, o fundo aparece somente quando o controle está ativo; `outline` mantém a
-borda. `size` ajusta a altura.
+Na variante `default`, o fundo aparece somente quando o controle está ativo. `outline` mantém a
+borda e usa um fundo sutil distinto dela no estado ativo. `size` ajusta a altura.
 
 ```tsx preview
 <Toggle aria-label="Quebra de linha">
@@ -64,15 +60,15 @@ borda. `size` ajusta a altura.
 
 ## Propriedades de Toggle
 
-| Propriedade | Tipo | Padrão | Descrição |
-|---|---|---|---|
-| `pressed` | `boolean` | | Estado no modo controlado. Use com `onPressedChange`. |
-| `onPressedChange` | `(pressed: boolean) => void` | | Chamado a cada alternância, com o novo estado. |
-| `defaultPressed` | `boolean` | `false` | Estado inicial no modo não controlado. |
-| `variant` | `'default' \| 'outline'` | `'default'` | `default` não tem borda e só ganha fundo quando ativo; `outline` mantém a borda. |
-| `size` | `'sm' \| 'default' \| 'lg'` | `'default'` | Altura na escala única dos controles (2 · 2.25 · 2.5rem) — sm para toolbar densa, lg para alvo mais confortável. |
-| `shape` | `'default' \| 'pill'` | `'default'` | Geometria do controle; `pill` arredonda as extremidades. |
-| `disabled` | `boolean` | `false` | Esmaece e bloqueia o clique, preservando o estado visual. |
+| Propriedade       | Tipo                         | Padrão      | Descrição                                                                                                        |
+| ----------------- | ---------------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------- |
+| `pressed`         | `boolean`                    |             | Estado no modo controlado. Use com `onPressedChange`.                                                            |
+| `onPressedChange` | `(pressed: boolean) => void` |             | Chamado a cada alternância, com o novo estado.                                                                   |
+| `defaultPressed`  | `boolean`                    | `false`     | Estado inicial no modo não controlado.                                                                           |
+| `variant`         | `'default' \| 'outline'`     | `'default'` | `default` não tem borda e só ganha fundo quando ativo; `outline` mantém a borda.                                 |
+| `size`            | `'sm' \| 'default' \| 'lg'`  | `'default'` | Altura na escala única dos controles (2 · 2.25 · 2.5rem) — sm para toolbar densa, lg para alvo mais confortável. |
+| `shape`           | `'default' \| 'pill'`        | `'default'` | Geometria do controle; `pill` arredonda as extremidades.                                                         |
+| `disabled`        | `boolean`                    | `false`     | Esmaece e bloqueia o clique, preservando o estado visual.                                                        |
 
 ## ToggleGroup
 
@@ -82,96 +78,157 @@ relacionados. `type="single"` mantém um item ativo; `type="multiple"` aceita v
 ### Escolha única
 
 ```tsx preview
-const [view, setView] = useState('sessions')
+const [view, setView] = useState("sessions");
 
 render(
-  <ToggleGroup type="single" value={view} onValueChange={(v) => v && setView(v)}>
-    <ToggleGroupItem value="overview">Visão geral</ToggleGroupItem>
-    <ToggleGroupItem value="sessions">Sessões</ToggleGroupItem>
-    <ToggleGroupItem value="skills">Habilidades</ToggleGroupItem>
+  <ToggleGroup
+    type="single"
+    value={view}
+    onValueChange={(v) => v && setView(v)}
+  >
+    <Toggle value="overview">Visão geral</Toggle>
+    <Toggle value="sessions">Sessões</Toggle>
+    <Toggle value="skills">Habilidades</Toggle>
   </ToggleGroup>,
-)
+);
 ```
 
 ### Escolha múltipla
 
 ```tsx preview
-const [marks, setMarks] = useState(['bold'])
+const [marks, setMarks] = useState(["bold"]);
 
 render(
   <ToggleGroup type="multiple" value={marks} onValueChange={setMarks}>
-    <ToggleGroupItem value="bold" aria-label="Negrito"><Bold /></ToggleGroupItem>
-    <ToggleGroupItem value="italic" aria-label="Itálico"><Italic /></ToggleGroupItem>
-    <ToggleGroupItem value="underline" aria-label="Sublinhado"><Underline /></ToggleGroupItem>
+    <Toggle value="bold" aria-label="Negrito">
+      <Bold />
+    </Toggle>
+    <Toggle value="italic" aria-label="Itálico">
+      <Italic />
+    </Toggle>
+    <Toggle value="underline" aria-label="Sublinhado">
+      <Underline />
+    </Toggle>
   </ToggleGroup>,
-)
+);
 ```
 
 ### Itens só com ícone e tooltip
 
 Quando o item mostra somente um ícone, mantenha o `aria-label` e acrescente uma dica visual. Envolva o
-`ToggleGroupItem` em `TooltipTrigger asChild`: o item preserva o estado selecionado e seus atributos,
+`Toggle` em `TooltipTrigger asChild`: o controle preserva o estado selecionado e seus atributos,
 e a dica aparece sem criar outro botão. O `TooltipProvider` da raiz do aplicativo continua necessário.
 
 ```tsx preview
-const [align, setAlign] = useState('left')
+const [align, setAlign] = useState("left");
 
 render(
-  <ToggleGroup type="single" value={align} onValueChange={(v) => v && setAlign(v)}>
+  <ToggleGroup
+    type="single"
+    value={align}
+    onValueChange={(v) => v && setAlign(v)}
+  >
     <Tooltip>
       <TooltipTrigger asChild>
-        <ToggleGroupItem value="left" aria-label="Alinhar à esquerda"><AlignLeft /></ToggleGroupItem>
+        <Toggle value="left" aria-label="Alinhar à esquerda">
+          <AlignLeft />
+        </Toggle>
       </TooltipTrigger>
       <TooltipContent>Alinhar à esquerda</TooltipContent>
     </Tooltip>
     <Tooltip>
       <TooltipTrigger asChild>
-        <ToggleGroupItem value="center" aria-label="Centralizar"><AlignCenter /></ToggleGroupItem>
+        <Toggle value="center" aria-label="Centralizar">
+          <AlignCenter />
+        </Toggle>
       </TooltipTrigger>
       <TooltipContent>Centralizar</TooltipContent>
     </Tooltip>
     <Tooltip>
       <TooltipTrigger asChild>
-        <ToggleGroupItem value="right" aria-label="Alinhar à direita"><AlignRight /></ToggleGroupItem>
+        <Toggle value="right" aria-label="Alinhar à direita">
+          <AlignRight />
+        </Toggle>
       </TooltipTrigger>
       <TooltipContent>Alinhar à direita</TooltipContent>
     </Tooltip>
   </ToggleGroup>,
-)
+);
 ```
 
-### Variante e espaçamento
+### Relação entre os controles
 
-`variant`, `size` e `shape` definidos no grupo chegam aos itens por contexto. `spacing` separa os
-itens; com zero, eles formam um bloco contínuo.
+`mode` segue a mesma gramática de `ButtonGroup`. `connected`, o padrão, une os controles e remove
+bordas internas duplicadas; `spaced` preserva cada controle com um pequeno intervalo; `divided`
+acrescenta divisores entre eles. `variant`, `size` e `shape` definidos no grupo chegam aos controles
+por contexto.
 
 ```tsx preview
-<ToggleGroup type="single" variant="outline" spacing={2} defaultValue="developer">
-  <ToggleGroupItem value="developer">developer</ToggleGroupItem>
-  <ToggleGroupItem value="reviewer">reviewer</ToggleGroupItem>
-  <ToggleGroupItem value="designer">designer</ToggleGroupItem>
+<ToggleGroup type="single" variant="outline" defaultValue="call">
+  <Toggle value="call">
+    <Phone /> Telefone
+  </Toggle>
+  <Toggle value="email">
+    <Mail /> E-mail
+  </Toggle>
+  <Toggle value="whatsapp">
+    <MessageCircle /> WhatsApp
+  </Toggle>
 </ToggleGroup>
 ```
 
+Use `mode="spaced"` quando cada controle precisar preservar sua própria borda e seu próprio raio.
+Use `mode="divided"` quando a separação também precisar ficar explícita por divisores.
+
+### Aparência segmentada
+
+Use `mode="segmented"` para escolhas curtas que precisam permanecer visíveis dentro de uma
+superfície compartilhada. O item ativo usa o mesmo fundo de uma superfície elevada; os demais
+permanecem no fundo do grupo. Segmentos inativos vizinhos recebem um divisor sutil; o divisor
+desaparece dos dois lados da seleção. Essa aparência escolhe um valor no contexto atual: para
+navegar entre painéis, use Tabs.
+
+```tsx preview
+<ToggleGroup type="single" mode="segmented" defaultValue="sessions">
+  <Toggle value="overview">
+    <LayoutGrid /> Visão geral
+  </Toggle>
+  <Toggle value="sessions">
+    <History /> Sessões
+  </Toggle>
+  <Toggle value="skills">
+    <Settings /> Habilidades
+  </Toggle>
+</ToggleGroup>
+```
+
+`mode` trata a relação visual entre os controles. `variant` continua tratando cada `Toggle`; por
+isso, a composição segmentada recomendada usa a variante padrão. O recuo fica dentro da altura da
+escala de controles: o conjunto mantém `2rem`, `2.25rem` ou `2.5rem` conforme `size`.
+
+### Distribuição e moldura
+
+`distribution="content"`, o padrão, preserva a largura dos rótulos. Use `equal` para dividir toda a
+largura disponível igualmente entre os controles. `framed` acrescenta borda e recuo estrutural sem
+mudar o modo de agrupamento.
+
 ### Propriedades de ToggleGroup
 
-| Propriedade | Tipo | Padrão | Descrição |
-|---|---|---|---|
-| `type` | `'single' \| 'multiple'` | | Define seleção única (`string`) ou múltipla (`string[]`). |
-| `value` | `string \| string[]` | | Seleção controlada; o tipo acompanha `type`. |
-| `onValueChange` | `(value: string \| string[]) => void` | | Informa a nova seleção. No modo single, uma string vazia representa nenhum item ativo. |
-| `defaultValue` | `string \| string[]` | | Seleção inicial no modo não controlado. |
-| `variant` | `'default' \| 'outline'` | `'default'` | Tratamento visual repassado aos itens. |
-| `size` | `'default' \| 'sm' \| 'lg'` | `'default'` | Tamanho repassado aos itens. |
-| `shape` | `'default' \| 'pill'` | `'default'` | Geometria do grupo e de suas extremidades. |
-| `spacing` | `number` | `0` | Distância entre os itens em unidades de spacing. |
-
-### Propriedades de ToggleGroupItem
-
-| Propriedade | Tipo | Padrão | Descrição |
-|---|---|---|---|
-| `value` | `string` | | Identificador que entra no valor do grupo quando o item é ativado. |
-| `disabled` | `boolean` | `false` | Bloqueia somente este item e preserva seu estado visual. |
-| `variant` | `'default' \| 'outline'` | `'default'` | Tratamento do item quando o grupo não declara `variant`; o valor do grupo prevalece. |
-| `size` | `'default' \| 'sm' \| 'lg'` | `'default'` | Tamanho do item quando o grupo não declara `size`; o valor do grupo prevalece. |
-| `shape` | `'default' \| 'pill'` | shape do grupo | Geometria deste item; quando informada, prevalece sobre a do grupo. |
+| Propriedade     | Tipo                                                  | Padrão         | Descrição                                                                                             |
+| --------------- | ----------------------------------------------------- | -------------- | ----------------------------------------------------------------------------------------------------- |
+| `type`          | `'single' \| 'multiple'`                              |                | Define seleção única (`string`) ou múltipla (`string[]`).                                             |
+| `value`         | `string \| string[]`                                  |                | Seleção controlada; o tipo acompanha `type`.                                                          |
+| `onValueChange` | `(value: string \| string[]) => void`                 |                | Informa a nova seleção. No modo single, uma string vazia representa nenhum item ativo.                |
+| `defaultValue`  | `string \| string[]`                                  |                | Seleção inicial no modo não controlado.                                                               |
+| `variant`       | `'default' \| 'outline'`                              | `'default'`    | Tratamento visual repassado aos itens. `outline` aplica borda a cada item.                            |
+| `size`          | `'default' \| 'sm' \| 'lg'`                           | `'default'`    | Tamanho repassado aos itens.                                                                          |
+| `shape`         | `'default' \| 'pill'`                                 | `'default'`    | Geometria do grupo e de suas extremidades.                                                            |
+| `mode`          | `'connected' \| 'spaced' \| 'divided' \| 'segmented'` | `'connected'`  | Define como os controles se relacionam; `segmented` cria uma superfície compartilhada para a seleção. |
+| `distribution`  | `'content' \| 'equal'`                                | `'content'`    | Preserva a largura dos rótulos ou reparte igualmente a largura disponível.                            |
+| `orientation`   | `'horizontal' \| 'vertical'`                          | `'horizontal'` | Organiza os controles e os divisores no eixo indicado.                                                |
+| `framed`        | `boolean`                                             | `false`        | Acrescenta borda, raio e recuo ao grupo sem alterar o modo.                                           |
+
+Dentro de `ToggleGroup`, cada `Toggle` exige `value`. O grupo controla o estado selecionado; props
+standalone como `pressed` e `onPressedChange` não participam dessa composição. `disabled`, `variant`,
+No grupo, `variant` e `size` pertencem ao conjunto e chegam a todos os controles. `shape` no item
+pode declarar uma pílula local dentro do grupo.