Pular para o conteúdo
Navegação

TableOfContents

/componentes/table-of-contents.mdmarkdown cru, para quem lê com agent em vez de olho

Lendo os títulos da página

Despacho

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.

Dados do destinatário

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.

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.

Frete e prazos

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.

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.

Envio ao cliente

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.

Código de rastreio

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.

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.

Cancelamento

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.

Lista pronta, sem título visível

Despacho

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.

Dados do destinatário

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.

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.

Frete e prazos

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.

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.

Envio ao cliente

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.

Código de rastreio

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.

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.

Cancelamento

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.

Importar
import { TableOfContents } from '@rivocode/ui'

Quando usar

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.

<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:

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.

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.

API

PropTipoPadrão
classNames

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-*`).

Partial<Record<"indicator" | "item" | "label" | "link" | "list", string>>sem padrão
container

Onde procurar os titulos.

HTMLElement | nullsem padrão
hideLabel

Esconde o titulo visivel.

booleanfalse
items

A lista pronta.

TableOfContentsItem[]sem padrão
label

O nome da regiao de navegacao, que tambem aparece como titulo do indice.

string"Nesta página"
offset

A altura do que gruda no topo (cabecalho fixo), em pixels.

number0
onActiveChange

Chamado quando a secao marcada muda: ao rolar ou ao clicar.

((id: string | null) => void)sem padrão
onItemClick

Chamado no clique de uma linha, antes da rolagem.

((item: TableOfContentsItem, event: MouseEvent<HTMLAnchorElement, MouseEvent>) => void)sem padrão
root

A caixa que rola, quando nao e a janela.

HTMLElement | nullsem padrão
selector

Quais titulos entram, quando a lista nao vem pronta.

string"h2, h3"
updateHash

Escreve o `#id` na barra de endereco ao clicar, com `history.replaceState`, sem empilhar historico.

booleanfalse

Além destas, a peça aceita className, style, id e children, repassados ao elemento de baixo.

@rivocode/ui, 149 peças no catálogo. Esta página é gerada dos mesmos arquivos que alimentam o design system, então ela não envelhece sozinha.

Feito por RivoCode.