# ItemGroup

A lista agrupada das telas de ajustes: um título em cima, as linhas numa caixa
só, separadas por traço fino, e uma nota embaixo.

É o desenho que toda tela de configurações repete, do celular ao painel do
navegador. Sem ele, cada projeto monta a caixa com `Card`, enfileira `Item`
com borda à mão e escreve o título num texto solto, e cada um acerta o canto e o
respiro de um jeito.

```tsx
<ItemGroup title="Preferências" footer="Vale para todos os aparelhos em que você entrou.">
  <Item interactive render={<a href="/ajustes/idioma" />}>
    <ItemContent>
      <ItemTitle>Idioma</ItemTitle>
    </ItemContent>
    <ItemValue>Português</ItemValue>
    <ItemChevron />
  </Item>
  <Switch checked={lembrete} onCheckedChange={setLembrete}>
    Lembrete de vencimento
  </Switch>
</ItemGroup>
```

**Cada filho é uma linha.** O grupo põe cada um num `<li>`, desenha o traço
entre eles e dá o canto da caixa só à primeira e à última. Dentro dele o `Item`
perde a moldura própria e ganha a altura de linha, que acompanha a densidade, e
o `Switch` com texto vira linha inteira, com o rótulo à esquerda e a chave à
direita: clicar em qualquer ponto da linha liga e desliga.

**A linha que abre outra tela** é um `Item` com `interactive` e `render` de
link ou botão, com `ItemValue` para o que está escolhido e `ItemChevron` para
a seta. O valor entra no nome falado depois do título, com uma pausa: o leitor
de tela diz "Idioma, Português", e a seta fica muda.

**O título é o nome da lista**, e a nota é a descrição dela: quem navega pelo
leitor de tela ouve "Preferências, lista, 2 itens". O título é texto apagado por
padrão, como nas telas de ajustes do sistema. Se a seção precisa aparecer no
roteiro de títulos da página, passe um `Heading` no `title`, com o nível que a
página pede: o grupo não adivinha nível.

## Partes

`classNames` alcança cada nó pelo nome: `title`, `list` (a caixa com borda, que
é o `<ul>`) e `footer`. O `className` veste a raiz, que segura as três.

## Quando não usar

- **Ficha de rótulo e valor que só se lê** é `DescriptionList`, que sai como
  `<dl>`. O `ItemGroup` é para linhas que se tocam ou que ligam alguma coisa; o
  número do pedido, o CNPJ e a data de emissão não abrem tela nenhuma.
- **Conteúdo com cabeçalho, corpo e ação** é `Card`. O cartão agrupa assunto,
  e o `ItemGroup` agrupa linhas iguais. Um cartão com uma lista de ajustes
  dentro é a forma que esta peça veio substituir.
- **Lista que vem de uma consulta**, com carregando, vazio e erro, é `DataList`
  no React Native e `DataTable` ou `Item` em `divide-y` no navegador. A tela de
  ajustes é escrita à mão e tem tamanho conhecido; registros do servidor não.
- **Formulário que se envia de uma vez** é `Fieldset` com `Field`. Ajuste que
  vale na hora fica aqui; o que precisa de "Salvar" vai para o formulário, com a
  `SaveBar`.

## No React Native

Traduz, e é a peça que a tela de ajustes de um app em Expo pedia: o título vira cabeçalho e nome da lista, a caixa recorta o canto da primeira e da última linha, e o traço fino separa as do meio. As linhas são os mesmos filhos do web, com a API do nativo: `Item` com `title`, `value`, `chevron` e `onPress`, e `Switch` com texto.

```tsx
<ItemGroup title="Preferências" footer="Vale para todos os aparelhos.">
  <Item title="Idioma" value="Português" chevron onPress={abrirIdioma} />
  <Switch checked={lembrete} onCheckedChange={setLembrete}>
    Lembrete de vencimento
  </Switch>
</ItemGroup>
```

**A linha que navega fala o valor**: o leitor de tela ouve “Idioma, Português, botão”, e a seta é o `ChevronRight` do `lucide-react-native`, o mesmo do web. **O `Switch` com texto é uma parada só**: o rótulo à esquerda, a chave à direita, e tocar em qualquer ponto da linha troca. `title` e `footer` são texto, e não nó, porque o título também é o `accessibilityLabel` da lista.

## Importação

```tsx
import { ItemGroup } from '@rivocode/ui'
```

## Exemplos

### Tela de ajustes

```tsx
import { useState } from 'react'
import {
  Item,
  ItemChevron,
  ItemContent,
  ItemDescription,
  ItemGroup,
  ItemTitle,
  ItemValue,
  Switch,
} from '@rivocode/ui'

export function SettingsScreen() {
  const [reminders, setReminders] = useState(true)
  const [summary, setSummary] = useState(false)

  return (
    <div className="flex w-full max-w-md flex-col gap-6">
      <ItemGroup title="Preferências" footer="Vale para todos os aparelhos em que você entrou.">
        <Item interactive render={<a href="#idioma" />}>
          <ItemContent>
            <ItemTitle>Idioma</ItemTitle>
          </ItemContent>
          <ItemValue>Português</ItemValue>
          <ItemChevron />
        </Item>
        <Item interactive render={<a href="#fuso" />}>
          <ItemContent>
            <ItemTitle>Fuso horário</ItemTitle>
          </ItemContent>
          <ItemValue>Brasília (GMT-3)</ItemValue>
          <ItemChevron />
        </Item>
      </ItemGroup>

      <ItemGroup
        title="Notificações"
        footer="O resumo chega toda segunda às 8h, com o que venceu na semana."
      >
        <Switch checked={reminders} onCheckedChange={setReminders}>
          Lembrete de vencimento
        </Switch>
        <Switch checked={summary} onCheckedChange={setSummary}>
          Resumo semanal por e-mail
        </Switch>
      </ItemGroup>
    </div>
  )
}
```

### Valor sem navegar

```tsx
import { useState } from 'react'
import {
  Item,
  ItemChevron,
  ItemContent,
  ItemDescription,
  ItemGroup,
  ItemTitle,
  ItemValue,
  Switch,
} from '@rivocode/ui'

export function ReadOnlyValues() {
  return (
    <ItemGroup title="Sobre" className="w-full max-w-md">
      <Item>
        <ItemContent>
          <ItemTitle>Versão</ItemTitle>
          <ItemDescription>Atualizada em 12/11</ItemDescription>
        </ItemContent>
        <ItemValue>4.2.0</ItemValue>
      </Item>
      <Item>
        <ItemContent>
          <ItemTitle>Plano</ItemTitle>
        </ItemContent>
        <ItemValue>Equipe, 8 lugares</ItemValue>
      </Item>
    </ItemGroup>
  )
}
```

## Props

| Prop | Tipo | Obrigatória | Padrão | Desde | O que faz |
| --- | --- | --- | --- | --- | --- |
| `classNames` | `Partial<Record<"footer" \| "list" \| "title", string>>` |  |  | - | Classe por parte: `title`, `list` (a caixa com borda, que e o `<ul>`) e `footer`. |
| `footer` | `ReactNode` |  |  | - | A nota embaixo da caixa, menor e apagada: o que acontece quando se liga, de onde vem o valor. |
| `title` | `ReactNode` |  |  | - | O nome da secao, acima da caixa: "Conta", "Notificacoes". |

Além dessas: repassa `className`, `style`, `id` e os demais atributos do elemento raiz.

## Ver também

- [Accordion](/componentes/accordion.md)
- [Affix](/componentes/affix.md)
- [AppShell](/componentes/app-shell.md)
- [AspectRatio](/componentes/aspect-ratio.md)
- [Avatar](/componentes/avatar.md)
- [Card](/componentes/card.md)
- [Convenções da biblioteca](/convencoes.md): Provider, tokens e as regras que valem para toda peça
- [Índice completo](/llms.txt)
