# TableOfContents

O índice da página: a lista de títulos de um texto longo, com a seção que a
pessoa está lendo marcada enquanto ela rola. É a coluna "Nesta página" de um
guia, de uma política, de um relatório com várias partes.

```tsx
<div className="grid gap-8 lg:grid-cols-[1fr_14rem]">
  <article>…</article>
  <TableOfContents className="sticky top-6 self-start" />
</div>
```

Sem mais nada, a peça lê os `h2` e `h3` do documento, na ordem em que aparecem,
e o `h3` entra aninhado no `h2` que o antecede. O nível sai da tag; qualquer
outro elemento que case com o `selector` entra no nível do `aria-level`, ou no
nível 2 sem ele.

## A seção marcada

Uma linha imaginária a 30% do alto da janela decide qual seção está sendo
lida: a marcada é a do último título que já passou dela. Um
`IntersectionObserver` avisa quando um título cruza a faixa de cima, e a
rolagem mede de novo no máximo uma vez por quadro. Antes do primeiro título,
nenhuma linha fica marcada: a introdução não é seção.

**No fim da rolagem, a última seção visível fica marcada**, mesmo que o título
dela nunca chegue à linha: a última seção de uma página curta não sobe até os
30%, e sem isso ela nunca seria marcada.

A linha marcada leva `aria-current="location"`, que o leitor de tela anuncia
como "local atual". **O trilho segue o recuo de cada nível**: no subitem ele
entra numa diagonal até a altura do texto, e no item seguinte volta para fora,
então a linha mostra a hierarquia sem precisar de outra marca. **Um trecho na
cor de destaque corre por esse trilho até a seção atual** ao rolar, diagonais
incluídas, em vez de pular de linha em linha. O trilho mede cada link pela
caixa, então título que quebra em duas linhas ganha um trecho da altura dele. Com reduzir movimento, ele
troca de lugar sem deslizar, e fica fora do leitor de tela, que já ouve o
`aria-current`. `onActiveChange` recebe o `id` a cada troca, para quem quer
mostrar a seção em outro lugar.

## O clique

O clique rola até o título e **leva o foco para ele**, como um link de âncora
faz: o próximo Tab parte dali, e não do índice. O título ganha
`tabindex="-1"` só enquanto tem o foco, e o perde ao sair. A rolagem é suave,
e **vira salto** quando o sistema pede para reduzir movimento.

Depois do clique, a marcação fica presa na linha clicada até a pessoa rolar
por conta própria (roda do mouse, toque, tecla ou barra de rolagem). Sem isso,
a rolagem suave passaria piscando por todas as seções do caminho, e o salto do
movimento reduzido marcaria a seção de cima quando o título clicado não
consegue subir até a linha.

O `href` continua lá, então Ctrl+clique, clique do meio e "copiar endereço do
link" funcionam como em qualquer link. `updateHash` escreve o `#id` na barra de
endereço com `history.replaceState`, sem empilhar histórico; ele vem desligado
porque router com `#` no caminho brigaria com ele. `onItemClick` roda antes de
tudo, e `event.preventDefault()` ali devolve o link ao navegador.

## Cabeçalho fixo

Com um cabeçalho que gruda no topo, passe a altura dele em `offset`, em
pixels: o título para logo abaixo dele ao clicar, e só conta como visível
abaixo dele. Para o link que chega de fora (`/guia#frete` colado numa
conversa), quem desconta o cabeçalho é o CSS, e não a peça:

```css
html {
  scroll-padding-top: 4rem;
}
```

## Onde ler

`container` limita a leitura a um elemento, e é o que um exemplo dentro de uma
página maior precisa. Título que chega depois (seção carregada sob demanda,
exemplo que monta tarde) entra sozinho no índice: a peça observa o
`container` e lê de novo quando ele muda. Título sem `id` ganha um, tirado do
texto sem acento: "Política de troca" vira `#politica-de-troca`, e o repetido vira
`#politica-de-troca-2`.

`root` é a caixa que rola, quando não é a janela. É nela que a faixa é medida e
é ela que rola no clique.

```tsx
const [caixa, setCaixa] = useState<HTMLDivElement | null>(null)

<div ref={setCaixa} className="h-96 overflow-y-auto">…</div>
<TableOfContents container={caixa} root={caixa} selector="h3, h4" />
```

`items` dispensa a leitura: a lista vem pronta, com `id`, `label` e `level`, e
serve quando o texto do índice é mais curto que o título, ou quando os títulos
moram num componente que não deixa ler.

## Nome e título

O índice sai num `<nav>` com nome, "Nesta página" por padrão, e esse nome
aparece também como título visível acima da lista. `label` troca os dois.
`hideLabel` tira o título da tela e deixa o nome para o leitor de tela. Uma
página sem título nenhum não desenha o índice: navegação vazia é uma região
anunciada que não leva a lugar nenhum.

## Partes

`classNames` alcança cada nó pelo nome: `label` (o título visível), `list` (a
lista de fora, que desenha o trilho), `item` (cada `<li>`), `link` (cada
linha clicável) e `indicator` (o trecho que corre pelo trilho até a seção atual).

## Quando não usar

- **Navegar entre páginas da aplicação** é `Sidebar`. O índice anda dentro de
  uma página só; a barra lateral troca de rota.
- **A trilha de onde a página mora** é `Breadcrumb`. Ela olha para cima, até a
  raiz do site; o índice olha para dentro do texto.
- **Conteúdo que a pessoa escolhe ver, um de cada vez** é `Tabs`. Com abas, o
  que não está aberto não está na página; com o índice, tudo está e a pessoa
  pula.
- **Etapas de um processo** são `Steps`. O índice não tem ordem obrigatória nem
  etapa concluída.

## No React Native

Não porta, por decisão. O índice da página é idioma de mesa: ele mora numa coluna ao lado do texto, e no celular não há coluna ao lado. Texto longo numa tela de app se divide antes de chegar ao índice: cada seção vira uma tela do router aberta a partir de uma lista, ou uma aba do `Tabs`, e o título da tela diz onde a pessoa está.

O leitor de tela também já tem o próprio índice: o rotor do VoiceOver e os controles de leitura do TalkBack pulam de título em título em qualquer `Text` com `accessibilityRole="header"`, que é o que o `Heading` do pacote nativo escreve.

## Importação

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

## Exemplos

### Lendo os títulos da página

```tsx
import { TableOfContents } from '@rivocode/ui'
import { useState } from 'react'

const SECTIONS = [
  {
    id: 'guia-despacho',
    title: 'Despacho',
    children: [
      { id: 'guia-dados-do-destinatario', title: 'Dados do destinatário' },
      { id: 'guia-frete', title: 'Frete e prazos' },
    ],
  },
  {
    id: 'guia-envio',
    title: 'Envio ao cliente',
    children: [{ id: 'guia-rastreio', title: 'Código de rastreio' }],
  },
  { id: 'guia-cancelamento', title: 'Cancelamento', children: [] },
]

const FILLER =
  'O pacote sai com o endereço do destinatário, o peso e o frete que a transportadora ' +
  'cotou. Confira o endereço antes de despachar: depois da coleta, a correção é um novo ' +
  'envio e não uma edição.'

function Article({ prefix, onBox }: { prefix: string; onBox: (node: HTMLDivElement | null) => void }) {
  return (
    <div
      ref={onBox}
      tabIndex={0}
      aria-label="Guia de envio"
      className="h-72 overflow-y-auto rounded-md border border-border bg-surface p-4"
    >
      {SECTIONS.map((section) => (
        <section key={section.id} className="mb-6">
          <h4 id={`${prefix}-${section.id}`} className="mb-2 font-display text-lg text-fg">
            {section.title}
          </h4>
          <p className="text-sm text-fg-muted">{FILLER}</p>
          {section.children.map((child) => (
            <div key={child.id} className="mt-4">
              <h5 id={`${prefix}-${child.id}`} className="mb-1 text-sm font-medium text-fg">
                {child.title}
              </h5>
              <p className="text-sm text-fg-muted">{FILLER}</p>
              <p className="mt-2 text-sm text-fg-muted">{FILLER}</p>
            </div>
          ))}
        </section>
      ))}
    </div>
  )
}

export function ReadsHeadings() {
  const [box, setBox] = useState<HTMLDivElement | null>(null)

  return (
    <div className="grid gap-6 sm:grid-cols-[1fr_12rem]">
      <Article prefix="lendo" onBox={setBox} />
      <TableOfContents container={box} root={box} selector="h4, h5" />
    </div>
  )
}
```

### Lista pronta, sem título visível

```tsx
import { TableOfContents } from '@rivocode/ui'
import { useState } from 'react'

const SECTIONS = [
  {
    id: 'guia-despacho',
    title: 'Despacho',
    children: [
      { id: 'guia-dados-do-destinatario', title: 'Dados do destinatário' },
      { id: 'guia-frete', title: 'Frete e prazos' },
    ],
  },
  {
    id: 'guia-envio',
    title: 'Envio ao cliente',
    children: [{ id: 'guia-rastreio', title: 'Código de rastreio' }],
  },
  { id: 'guia-cancelamento', title: 'Cancelamento', children: [] },
]

const FILLER =
  'O pacote sai com o endereço do destinatário, o peso e o frete que a transportadora ' +
  'cotou. Confira o endereço antes de despachar: depois da coleta, a correção é um novo ' +
  'envio e não uma edição.'

function Article({ prefix, onBox }: { prefix: string; onBox: (node: HTMLDivElement | null) => void }) {
  return (
    <div
      ref={onBox}
      tabIndex={0}
      aria-label="Guia de envio"
      className="h-72 overflow-y-auto rounded-md border border-border bg-surface p-4"
    >
      {SECTIONS.map((section) => (
        <section key={section.id} className="mb-6">
          <h4 id={`${prefix}-${section.id}`} className="mb-2 font-display text-lg text-fg">
            {section.title}
          </h4>
          <p className="text-sm text-fg-muted">{FILLER}</p>
          {section.children.map((child) => (
            <div key={child.id} className="mt-4">
              <h5 id={`${prefix}-${child.id}`} className="mb-1 text-sm font-medium text-fg">
                {child.title}
              </h5>
              <p className="text-sm text-fg-muted">{FILLER}</p>
              <p className="mt-2 text-sm text-fg-muted">{FILLER}</p>
            </div>
          ))}
        </section>
      ))}
    </div>
  )
}

export function ReadyList() {
  const [box, setBox] = useState<HTMLDivElement | null>(null)
  const [active, setActive] = useState<string | null>(null)

  return (
    <div className="grid gap-6 sm:grid-cols-[1fr_12rem]">
      <Article prefix="pronta" onBox={setBox} />
      <div className="flex flex-col gap-3">
        <TableOfContents
          root={box}
          hideLabel
          label="Seções do guia"
          onActiveChange={setActive}
          items={SECTIONS.map((section) => ({ id: `pronta-${section.id}`, label: section.title, level: 1 }))}
        />
        <p className="text-xs text-fg-subtle">Seção atual: {active ?? 'nenhuma'}</p>
      </div>
    </div>
  )
}
```

## Props

| Prop | Tipo | Obrigatória | Padrão | Desde | O que faz |
| --- | --- | --- | --- | --- | --- |
| `classNames` | `Partial<Record<"indicator" \| "item" \| "label" \| "link" \| "list", string>>` |  |  | - | Classe por parte: `label`, `list`, `item`, `link` e `indicator`, o trecho que corre pelo trilho ate a secao atual (um `path` de SVG: pinte com `stroke-*`). |
| `container` | `HTMLElement \| null` |  |  | - | Onde procurar os titulos. |
| `hideLabel` | `boolean` |  | `false` | - | Esconde o titulo visivel. |
| `items` | `TableOfContentsItem[]` |  |  | - | A lista pronta. |
| `label` | `string` |  | `"Nesta página"` | - | O nome da regiao de navegacao, que tambem aparece como titulo do indice. |
| `offset` | `number` |  | `0` | - | A altura do que gruda no topo (cabecalho fixo), em pixels. |
| `onActiveChange` | `((id: string \| null) => void)` |  |  | - | Chamado quando a secao marcada muda: ao rolar ou ao clicar. |
| `onItemClick` | `((item: TableOfContentsItem, event: MouseEvent<HTMLAnchorElement, MouseEvent>) => void)` |  |  | - | Chamado no clique de uma linha, antes da rolagem. |
| `root` | `HTMLElement \| null` |  |  | - | A caixa que rola, quando nao e a janela. |
| `selector` | `string` |  | `"h2, h3"` | - | Quais titulos entram, quando a lista nao vem pronta. |
| `updateHash` | `boolean` |  | `false` | - | Escreve o `#id` na barra de endereco ao clicar, com `history.replaceState`, sem empilhar historico. |

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

## Ver também

- [Breadcrumb](/componentes/breadcrumb.md)
- [Command](/componentes/command.md)
- [Menu](/componentes/menu.md)
- [Menubar](/componentes/menubar.md)
- [NavigationMenu](/componentes/navigation-menu.md)
- [Pagination](/componentes/pagination.md)
- [Convenções da biblioteca](/convencoes.md): Provider, tokens e as regras que valem para toda peça
- [Índice completo](/llms.txt)
