@softize/opus 23.0.0 → 24.0.0

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

@@ -0,0 +1,513 @@
+## Região nomeada
+
+Use `Surface` para delimitar e nomear um trecho da tela: uma seção da página, um grupo de campos, um
+registro, um item de uma grade ou um bloco clicável. Para uma janela modal, use
+[`Dialog`](/ui/dialog); para um painel lateral, [`Drawer`](/ui/drawer); para uma coluna de layout,
+[`Pane`](/ui/pane).
+
+O caso mais comum é uma seção com título dentro de uma página. Declare `as="section"` e as
+propriedades do header na própria `Surface`; os filhos formam o corpo. `count` mostra o total de
+itens ao lado do título.
+
+```tsx preview col
+render(
+  <Surface
+    as="section"
+    title="Dispositivos conectados"
+    count={3}
+    description="Sessões com acesso à sua conta."
+    actions={<Button variant="outline">Encerrar outras sessões</Button>}
+  >
+    <p className="text-sm text-muted-foreground">MacBook Pro · ativo agora</p>
+  </Surface>,
+);
+```
+
+Sem moldura e sem fundo, a superfície não aplica recuo: título e corpo ficam alinhados ao conteúdo
+ao redor. A `section` é ligada ao título por `aria-labelledby`, então leitores de tela anunciam a
+região pelo nome.
+
+## Escolher o elemento
+
+`as` decide o que a superfície é para o documento. A aparência não muda com o elemento.
+
+| `as`           | Quando usar                                                                            | Efeito                                  |
+| -------------- | -------------------------------------------------------------------------------------- | --------------------------------------- |
+| `div` (padrão) | Agrupamento visual sem papel próprio no documento.                                     | Nenhum nome acessível é atribuído.      |
+| `section`      | Região da página identificada por um título.                                           | `aria-labelledby` aponta para o título. |
+| `article`      | Conteúdo que faz sentido sozinho, como um registro ou um item de uma lista de cartões. | `aria-labelledby` aponta para o título. |
+| `fieldset`     | Grupo de campos de formulário.                                                         | O header vira a `legend` nativa.        |
+
+Quando `aria-label` é informado, ele substitui a ligação com o título. Para um bloco clicável, use
+`asChild` em vez de `as`, como mostra a seção “Superfície clicável”.
+
+## Moldura, fundo e anatomia
+
+Três propriedades independentes definem a aparência:
+
+- `framed` acrescenta borda e raio.
+- `elevation="raised"` dá à superfície o fundo de um elemento elevado sobre a página.
+- `layout` escolhe entre o ritmo contínuo e as faixas com divisores.
+
+Uma superfície com moldura ou com fundo passa a aplicar o recuo de `1rem` nas suas regiões; você não
+escreve classes de padding no header, no corpo ou no rodapé.
+
+```tsx preview col
+render(
+  <div className="grid grid-cols-3 gap-4">
+    <Surface as="section" framed title="Com moldura" level={3}>
+      <p className="text-sm text-muted-foreground">
+        Mostra o fundo de quem a hospeda.
+      </p>
+    </Surface>
+    <Surface as="section" elevation="raised" title="Com fundo" level={3}>
+      <p className="text-sm text-muted-foreground">Fundo próprio, sem borda.</p>
+    </Surface>
+    <Surface
+      as="section"
+      framed
+      elevation="raised"
+      title="Com moldura e fundo"
+      level={3}
+    >
+      <p className="text-sm text-muted-foreground">
+        O registro destacado sobre a página.
+      </p>
+    </Surface>
+  </div>,
+);
+```
+
+Use a moldura para separar blocos vizinhos e o fundo elevado para destacar um registro ou um item
+sobre a página. Quando a hierarquia pedir sombra, declare a intensidade em `className`, por exemplo
+`shadow-sm`.
+
+## Cabeçalho, corpo e rodapé
+
+Quando a superfície precisa de rodapé ou de controle sobre cada região, componha os slots.
+`SurfaceHeader` monta a linha sozinho: mídia, título com contador e descrição de um lado, ações no
+extremo oposto. A ordem em que os slots são escritos não altera a posição.
+
+```tsx preview col
+render(
+  <Surface as="article" framed elevation="raised" level={3}>
+    <SurfaceHeader>
+      <SurfaceTitle>Oficina Centro</SurfaceTitle>
+      <SurfaceDescription>
+        4 boxes · 2 consultores de plantão.
+      </SurfaceDescription>
+      <SurfaceActions>
+        <Button size="sm" variant="ghost">
+          Editar
+        </Button>
+      </SurfaceActions>
+    </SurfaceHeader>
+    <SurfaceBody>
+      <p className="text-sm text-muted-foreground">
+        Próximo horário livre hoje, às 14h.
+      </p>
+    </SurfaceBody>
+    <SurfaceFooter>
+      <Button size="sm" variant="outline">
+        Ver agenda
+      </Button>
+      <Button size="sm">Agendar revisão</Button>
+    </SurfaceFooter>
+  </Surface>,
+);
+```
+
+Cada região é opcional, e o ritmo acompanha as que estão presentes: a última fecha a superfície com
+o mesmo respiro do topo. O rodapé alinha as ações no fim da linha e vale para qualquer superfície,
+inclusive uma região de página sem moldura.
+
+A forma curta e a composição explícita produzem os mesmos elementos. Na forma curta, os filhos
+também podem ser `SurfaceBody` e `SurfaceFooter`, o que permite declarar o header por propriedades e
+ainda ter rodapé:
+
+```tsx preview col
+render(
+  <Surface
+    as="section"
+    framed
+    title="Plano atual"
+    description="Renova em 12 de maio."
+    level={3}
+  >
+    <SurfaceBody>
+      <p className="text-sm text-muted-foreground">
+        Até 10 workspaces e 50 agentes.
+      </p>
+    </SurfaceBody>
+    <SurfaceFooter>
+      <Button size="sm" variant="outline">
+        Alterar plano
+      </Button>
+    </SurfaceFooter>
+  </Surface>,
+);
+```
+
+### Composições que interrompem a renderização
+
+A `Surface` reprova as composições que deixariam a estrutura ambígua:
+
+- slots estruturais misturados com filhos livres: envolva o conteúdo em `SurfaceBody`;
+- mais de um `SurfaceHeader`, `SurfaceBody` ou `SurfaceFooter`;
+- propriedades da forma curta junto com `SurfaceHeader`;
+- `media`, `count`, `description` ou `actions` sem `title`;
+- um nó dentro de `SurfaceHeader` que não seja um dos seus slots;
+- um `SurfaceHeader` de `fieldset` sem `SurfaceTitle`, necessário para nomear o grupo.
+
+O `opus check` aponta os mesmos problemas antes da execução.
+
+## Contínuo ou seccionado
+
+`layout` declara a anatomia da superfície inteira. No padrão, `continuous`, o espaço separa as
+regiões. Em `sectioned`, header e rodapé viram faixas e uma linha separa as regiões vizinhas.
+
+```tsx preview col
+render(
+  <div className="grid grid-cols-2 gap-4">
+    <Surface as="section" framed elevation="raised" title="Contínuo" level={3}>
+      <SurfaceBody>
+        <p className="text-sm text-muted-foreground">
+          Um assunto, lido de cima a baixo.
+        </p>
+      </SurfaceBody>
+      <SurfaceFooter>
+        <Button size="sm" variant="outline">
+          Abrir
+        </Button>
+      </SurfaceFooter>
+    </Surface>
+    <Surface
+      as="section"
+      framed
+      elevation="raised"
+      layout="sectioned"
+      title="Seccionado"
+      level={3}
+    >
+      <SurfaceBody>
+        <p className="text-sm text-muted-foreground">
+          Regiões com pesos diferentes.
+        </p>
+      </SurfaceBody>
+      <SurfaceFooter>
+        <Button size="sm" variant="outline">
+          Abrir
+        </Button>
+      </SurfaceFooter>
+    </Surface>
+  </div>,
+);
+```
+
+Use `continuous` para um bloco de leitura e `sectioned` para uma superfície de operação, com lista
+ou tabela no corpo e ações persistentes no rodapé. `sectioned` exige `framed` ou
+`elevation="raised"`: os divisores precisam de um limite para alcançar.
+
+Os divisores são derivados das regiões presentes. Um header sozinho não desenha linha, e um header
+seguido direto de um rodapé produz uma linha só. Por isso, não escreva `border-b` nem `border-t`
+nas regiões, e use `layout="continuous"` para uma superfície sem divisores.
+
+### Corpo de ponta a ponta
+
+Quando o filho do corpo já controla o próprio recuo, como `DetailGroup` com divisores, uma lista ou
+uma tabela, declare `flush` em `SurfaceBody`. O corpo entrega a largura inteira ao filho e a moldura
+recorta os cantos.
+
+```tsx preview col
+render(
+  <Surface
+    as="section"
+    framed
+    layout="sectioned"
+    title="Veículo"
+    media={
+      <IconTile size="xs">
+        <CarFront />
+      </IconTile>
+    }
+  >
+    <SurfaceBody flush>
+      <DetailGroup dividers columns={2} orientation="horizontal">
+        <DetailField label="Marca" value="Toyota" />
+        <DetailField label="Modelo" value="Yaris XLS" />
+        <DetailField label="Ano/modelo" value="2021" />
+        <DetailField label="Placa" value="EVT0012" />
+      </DetailGroup>
+    </SurfaceBody>
+  </Surface>,
+);
+```
+
+## Mídia
+
+`SurfaceMedia`, ou `media` na forma curta, reserva a posição que abre a linha do header. O slot não
+desenha moldura e não altera o que recebe: o conteúdo entra como foi escrito.
+
+- Para um ícone com moldura, componha [`IconTile`](/ui/icon-tile) e escolha nele `size`, `context` e
+  `variant`.
+- Para uma pessoa ou uma marca, passe [`Avatar`](/ui/avatar) ou `img` diretamente.
+- Um glifo solto aparece sem moldura, no tamanho de `1rem`; uma classe `size-*` no ícone prevalece.
+
+```tsx preview col
+render(
+  <div className="grid grid-cols-3 gap-4">
+    <Surface as="article" framed elevation="raised" level={3}>
+      <SurfaceHeader>
+        <SurfaceMedia>
+          <IconTile size="sm" context="primary">
+            <CarFront />
+          </IconTile>
+        </SurfaceMedia>
+        <SurfaceTitle>Revisão dos 20.000 km</SurfaceTitle>
+        <SurfaceDescription>12 de maio, às 9h.</SurfaceDescription>
+      </SurfaceHeader>
+    </Surface>
+    <Surface as="article" framed elevation="raised" level={3}>
+      <SurfaceHeader>
+        <SurfaceMedia>
+          <Avatar>
+            <AvatarFallback>MA</AvatarFallback>
+          </Avatar>
+        </SurfaceMedia>
+        <SurfaceTitle>Marina Alves</SurfaceTitle>
+        <SurfaceDescription>Consultora responsável.</SurfaceDescription>
+      </SurfaceHeader>
+    </Surface>
+    <Surface as="article" framed elevation="raised" level={3}>
+      <SurfaceHeader>
+        <SurfaceMedia>
+          <ShieldCheck aria-hidden="true" />
+        </SurfaceMedia>
+        <SurfaceTitle>Garantia ativa</SurfaceTitle>
+        <SurfaceDescription>Até março de 2027.</SurfaceDescription>
+      </SurfaceHeader>
+    </Surface>
+  </div>,
+);
+```
+
+`media` com `null` ou `false` não abre o slot.
+
+## Grupo de campos
+
+Quando a superfície nomear um conjunto de campos relacionados, use `as="fieldset"`. O título vira a
+`legend` nativa e as propriedades de `fieldset`, como `disabled`, continuam disponíveis. A legenda
+aceita somente título e mídia; contador, descrição e ações não fazem parte do nome do grupo. A
+mídia da legenda é decorativa e fica oculta dos leitores de tela.
+
+```tsx preview col
+render(
+  <Surface
+    as="fieldset"
+    framed
+    title="Proprietário"
+    media={
+      <IconTile size="xs">
+        <UserRound />
+      </IconTile>
+    }
+  >
+    <FieldGroup>
+      <Field>
+        <FieldLabel htmlFor="owner-name">Nome</FieldLabel>
+        <Input id="owner-name" />
+      </Field>
+      <Field>
+        <FieldLabel htmlFor="owner-document">CPF/CNPJ</FieldLabel>
+        <Input id="owner-document" />
+      </Field>
+    </FieldGroup>
+  </Surface>,
+);
+```
+
+Com `framed`, a legenda ocupa a borda do grupo, como em um `fieldset` nativo. Com
+`layout="sectioned"`, ela passa a ser a faixa do header, dentro da moldura. Sem moldura, o grupo
+flui alinhado ao formulário.
+
+## Superfície clicável
+
+Quando o bloco inteiro leva a outro lugar ou dispara uma ação, use `asChild`: o filho — um `button`
+ou um link — recebe a moldura e o fundo e mantém a própria semântica. `asChild` não combina com
+`as` nem com a forma curta; componha os slots dentro do filho.
+
+```tsx preview col
+render(
+  <Surface
+    asChild
+    framed
+    elevation="raised"
+    level={3}
+    className="w-full cursor-pointer text-left transition-colors hover:bg-muted"
+  >
+    <button type="button">
+      <SurfaceHeader>
+        <SurfaceTitle>Camada de dados</SurfaceTitle>
+        <SurfaceDescription>
+          Entidades, consultas e migrações.
+        </SurfaceDescription>
+        <SurfaceActions>
+          <ArrowRight
+            aria-hidden="true"
+            className="size-4 text-muted-foreground"
+          />
+        </SurfaceActions>
+      </SurfaceHeader>
+    </button>
+  </Surface>,
+);
+```
+
+Os estados de hover e de foco pertencem ao elemento interativo e são declarados em `className`. Não
+coloque outro controle interativo dentro de uma superfície clicável.
+
+## Caixa simples
+
+Sem título e sem slots, a `Surface` é uma caixa: aplica somente o que `framed` e `elevation`
+declaram, sem recuo nem espaçamento. O conteúdo e o recuo são seus.
+
+```tsx preview col
+<Surface framed elevation="raised" className="p-4">
+  <p className="text-sm text-muted-foreground">
+    3 veículos aguardando retirada.
+  </p>
+</Surface>
+```
+
+## Hierarquia do título
+
+`level` escolhe o heading, de `1` a `6`, com `2` como padrão. Ajuste o nível pela estrutura do
+documento: uma superfície dentro de uma seção que já tem `h2` usa `level={3}`. Os níveis de 2 a 6
+têm a mesma aparência.
+
+O nível 1 é diferente: identifica o conteúdo principal da página e usa a escala do título de
+[`Page`](/ui/page). É o caso da página centrada em uma coleção.
+
+## Coleção nomeada
+
+Quando a região principal da página é uma coleção, a `Surface` nomeia essa coleção e a
+[`ActionList`](/ui/action-list) executa a consulta. Coloque criar, importar e outras ações sobre o
+conjunto completo nas ações da superfície. Busca, filtros, atualização e operações que dependem do
+recorte atual permanecem na toolbar da lista.
+
+```tsx preview col
+render(
+  <Surface
+    as="section"
+    level={1}
+    title="Clientes"
+    actions={<Button>Criar cliente</Button>}
+  >
+    <p className="text-sm text-muted-foreground">
+      A lista de clientes ocupa o corpo.
+    </p>
+  </Surface>,
+);
+```
+
+A criação usa um `Button` textual na variante padrão e no tamanho `default`, sem ícone, nomeado
+`Criar {recurso}`; o diálogo aberto por ele repete esse título, e a edição usa `Editar {recurso}`.
+
+Em uma [`Page`](/ui/page) com `layout="fill"`, a coleção ocupa a altura da página e rola só os
+resultados. `Surface` e `SurfaceBody` repassam a altura até a `ActionList` sem classes adicionais;
+uma superfície irmã, sem lista, mantém a altura do próprio conteúdo. Uma superfície com
+`elevation="raised"` não repassa a altura: ela mantém a altura do próprio conteúdo. A seção
+“Ocupar a altura disponível” da `ActionList` mostra a composição completa.
+
+## Fundo e aninhamento
+
+`elevation="none"` não pinta fundo: a superfície mostra o fundo de quem a hospeda, em qualquer nível
+de aninhamento. `elevation="raised"` pinta o fundo de superfície elevada e o publica na variável CSS
+`--surface-background`, que `Dialog` e `Drawer` também declaram.
+
+Um elemento seu que precise de uma cor opaca igual à do fundo visível — um cabeçalho fixo ou uma
+faixa que cobre o conteúdo ao rolar — usa `bg-[var(--surface-background,var(--background))]`. Na
+página, vale `--background`; dentro de uma superfície elevada, o fundo dela. Um contêiner da
+aplicação que pinte outro fundo declara a mesma variável com a cor que usa.
+
+## Propriedades de Surface
+
+| Propriedade   | Tipo                                            | Padrão         | Descrição                                                                                              |
+| ------------- | ----------------------------------------------- | -------------- | ------------------------------------------------------------------------------------------------------ |
+| `as`          | `'div' \| 'section' \| 'article' \| 'fieldset'` | `'div'`        | Elemento da superfície. Não combina com `asChild`.                                                     |
+| `asChild`     | `boolean`                                       | `false`        | Entrega a superfície ao único filho, como um `button` ou um link.                                      |
+| `framed`      | `boolean`                                       | `false`        | Acrescenta borda e raio, e recorta o conteúdo seccionado ou sem recuo.                                 |
+| `elevation`   | `'none' \| 'raised'`                            | `'none'`       | `raised` pinta o fundo de superfície elevada e mantém a altura do próprio conteúdo.                    |
+| `layout`      | `'continuous' \| 'sectioned'`                   | `'continuous'` | Anatomia das regiões. `sectioned` exige `framed` ou `elevation="raised"`.                              |
+| `level`       | `1 \| 2 \| 3 \| 4 \| 5 \| 6`                    | `2`            | Nível do heading do título. `1` identifica o conteúdo principal da página. Não se aplica a `fieldset`. |
+| `title`       | `ReactNode`                                     |                | Forma curta: título da superfície.                                                                     |
+| `media`       | `ReactNode`                                     |                | Forma curta: conteúdo do slot de mídia, antes do título. Exige `title`.                                |
+| `count`       | `number`                                        |                | Forma curta: total de itens ao lado do título. Exige `title`; indisponível em `fieldset`.              |
+| `description` | `ReactNode`                                     |                | Forma curta: frase de apoio sob o título. Exige `title`; indisponível em `fieldset`.                   |
+| `actions`     | `ReactNode`                                     |                | Forma curta: ações sobre a superfície inteira. Exige `title`; indisponível em `fieldset`.              |
+| `className`   | `string`                                        |                | Compõe sobre a superfície. Na caixa simples, é onde entra o recuo.                                     |
+| `children`    | `ReactNode`                                     |                | Filhos livres, que formam o corpo, ou os slots `SurfaceHeader`, `SurfaceBody` e `SurfaceFooter`.       |
+
+As demais propriedades são as nativas do elemento escolhido em `as`.
+
+## Propriedades de SurfaceHeader
+
+| Propriedade | Tipo        | Padrão | Descrição                                                                                                                                                                                               |
+| ----------- | ----------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `children`  | `ReactNode` |        | No máximo um de cada: `SurfaceMedia`, `SurfaceTitle`, `SurfaceMeta`, `SurfaceDescription` e `SurfaceActions`. Em `fieldset`, o `SurfaceTitle` é obrigatório e somente ele e `SurfaceMedia` são aceitos. |
+| `className` | `string`    |        | Ajusta a região do header.                                                                                                                                                                              |
+
+`SurfaceHeader` só existe como filho direto de `Surface`.
+
+## Propriedades de SurfaceMedia
+
+| Propriedade | Tipo        | Padrão | Descrição                                                               |
+| ----------- | ----------- | ------ | ----------------------------------------------------------------------- |
+| `children`  | `ReactNode` |        | `IconTile`, `Avatar`, `img` ou um glifo. O slot não acrescenta moldura. |
+| `className` | `string`    |        | Ajusta o alinhamento do slot.                                           |
+
+## Propriedades de SurfaceTitle
+
+| Propriedade | Tipo        | Padrão | Descrição                                                           |
+| ----------- | ----------- | ------ | ------------------------------------------------------------------- |
+| `children`  | `ReactNode` |        | Nome da superfície. O heading usa o `level` declarado em `Surface`. |
+| `className` | `string`    |        | Ajusta o título.                                                    |
+
+## Propriedades de SurfaceMeta
+
+| Propriedade | Tipo        | Padrão | Descrição                                                |
+| ----------- | ----------- | ------ | -------------------------------------------------------- |
+| `children`  | `ReactNode` |        | Metadado curto ao lado do título, como o total de itens. |
+| `className` | `string`    |        | Ajusta o metadado.                                       |
+
+## Propriedades de SurfaceDescription
+
+| Propriedade | Tipo        | Padrão | Descrição                    |
+| ----------- | ----------- | ------ | ---------------------------- |
+| `children`  | `ReactNode` |        | Frase de apoio sob o título. |
+| `className` | `string`    |        | Ajusta a descrição.          |
+
+## Propriedades de SurfaceActions
+
+| Propriedade | Tipo        | Padrão | Descrição                                                        |
+| ----------- | ----------- | ------ | ---------------------------------------------------------------- |
+| `children`  | `ReactNode` |        | Controles no extremo oposto ao título, como um botão ou um menu. |
+| `className` | `string`    |        | Ajusta o agrupamento das ações.                                  |
+
+## Propriedades de SurfaceBody
+
+Os filhos diretos recebem o ritmo estrutural de `1.5rem`. O layout da `Surface` decide o inset;
+um wrapper filho declara relações locais mais compactas.
+
+| Propriedade | Tipo        | Padrão  | Descrição                                                              |
+| ----------- | ----------- | ------- | ---------------------------------------------------------------------- |
+| `flush`     | `boolean`   | `false` | Remove o recuo do corpo para um filho que já controla o próprio recuo. |
+| `children`  | `ReactNode` |         | Blocos principais, separados pelo ritmo estrutural.                    |
+| `className` | `string`    |         | Ajusta ocupação, overflow, alinhamento ou tipografia.                  |
+
+## Propriedades de SurfaceFooter
+
+| Propriedade | Tipo        | Padrão | Descrição                                            |
+| ----------- | ----------- | ------ | ---------------------------------------------------- |
+| `children`  | `ReactNode` |        | Ações persistentes, alinhadas no fim da linha.       |
+| `className` | `string`    |        | Ajusta o rodapé, inclusive a distribuição das ações. |

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

@@ -42,12 +42,12 @@ 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 className="px-2 pt-2">
+  <TabsList>
     <TabsListItem value="overview">Visão geral</TabsListItem>
     <TabsListItem value="history">Histórico</TabsListItem>
   </TabsList>
@@ -92,8 +92,8 @@ essa linha. A linha respeita o recuo do contêiner; dentro de `DrawerBody` e `Di
 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">
@@ -165,34 +165,34 @@ do gatilho.
 
 ## 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 á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.                                                                                                                                |
+| 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                                                       |
-| ------------ | -------- | ------ | --------------------------------------------------------------- |
+| 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. |
+| `className`  | `string` |        | Ajusta a composição externa sem substituir a linha de navegação.  |
 
 ## Propriedades de TabsListItem
 
 | Propriedade | Tipo        | Padrão  | Descrição                                                                                       |
 | ----------- | ----------- | ------- | ----------------------------------------------------------------------------------------------- |
-| `value`     | `string`    |         | Identificador que associa o gatilho ao `TabsPanel` 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 TabsPanel
 
-| Propriedade  | Tipo     | Padrão | Descrição                                                              |
-| ------------ | -------- | ------ | ---------------------------------------------------------------------- |
+| 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.             |
+| `forceMount` | `true`   |        | Mantém o painel montado mesmo quando outra aba está ativa.              |