# Lista e detalhe, e o painel de apoio

Dois arranjos de dois painéis: a lista com o item escolhido ao lado, e o
conteúdo com o que o apoia. Lado a lado só na tela larga; no resto, um painel
por vez.

## O problema

Empilhar uma lista inteira em cima de um detalhe no celular faz a pessoa rolar
cem conversas para chegar à que abriu. Abrir cada item numa página nova na mesa
faz ela ir e voltar o dia inteiro, perdendo a posição na lista a cada volta. E
o painel de apoio que ocupa coluna no telefone espreme o conteúdo até ninguém
ler nenhum dos dois.

## Quando usar

| Arranjo | Quando | Exemplos |
|---|---|---|
| Lista e detalhe | a pessoa percorre itens parecidos e abre um de cada vez, voltando à lista | caixa de entrada, conversas, chamados, pedidos, clientes |
| Painel de apoio | um conteúdo principal e o que ajuda a lê-lo ou editá-lo | o resumo do pedido no checkout, os fatos de um registro, as propriedades do item selecionado num editor |

## Quando não usar

- **Item que se abre e não se compara** (um relatório, um contrato longo) é
  uma página própria, com o `Breadcrumb` de volta.
- **Detalhe de duas linhas** não pede painel: cabe na linha da lista, ou num
  `Collapsible` dentro dela.
- **Listagem de operação com colunas** (`DataTable`) não vira lista e detalhe
  só para mostrar o registro: o clique na linha abre uma `Sheet`, e a tabela
  continua inteira.
- **Feed** é uma coluna só, e não este arranjo: está em [layout.md](https://ds.rivocode.com.br/skill/reference/layout.md).

## As peças

- `ListDetail`: o arranjo inteiro de lista e detalhe, com a troca entre lado a
  lado e um painel por vez, o vazio do detalhe e o caminho de volta.
- `ListDetail` com `resizable`: o divisor que se arrasta na larga. O `Splitter`
  é para duas áreas sempre visíveis, e empilha no estreito.
- `EmptyState`: o detalhe antes da primeira escolha.
- `Sheet` sem `side`: o painel de apoio que é consultado e não lido.

## Comportamento

### Lista e detalhe

A lista à esquerda, o item escolhido à direita. **Lado a lado só na larga**; na
compacta e na média é um painel por vez, e ao estreitar com um item aberto fica
o detalhe, com o caminho de volta à lista.

O `ListDetail` faz a troca, o foco e o caminho de volta. Não monte à mão com
`Splitter` e `useMediaQuery`.

```tsx
const [selected, setSelected] = useState<string | null>(null)

<div className="h-[calc(100dvh-4rem)]">
  <ListDetail
    selected={selected}
    onSelectedChange={setSelected}
    emptyDetail={<EmptyState title="Escolha uma conversa" description="A conversa abre aqui, com o histórico inteiro." />}
  >
    <ListDetailList header={<SearchInput aria-label="Buscar conversa" />}>
      {conversations.map((entry) => (
        <ListDetailItem key={entry.id} value={entry.id}>{entry.name}</ListDetailItem>
      ))}
    </ListDetailList>
    <ListDetailPane>
      {selected && <ListDetailTitle level={2}>{title}</ListDetailTitle>}
    </ListDetailPane>
  </ListDetail>
</div>
```

- **O item escolhido mora no endereço** quando ele tem um (pedido, conversa,
  cliente): `/conversas/482`. Recarregar abre o mesmo, o link se compartilha, e
  no celular o "Voltar" do navegador volta à lista.
- **A lista da rede entra pelo `QueryBoundary` dentro da `ListDetailList`**,
  e não em volta dela: a busca do `header` fica parada enquanto carrega, e o
  carregando, o erro e o vazio ocupam o lugar dos itens. A lista é um `div`
  com `role="list"` justamente para essa composição sair em HTML válido.
- **A lista guarda a posição.** Voltar do detalhe devolve a mesma rolagem e o
  mesmo item marcado.
- **O detalhe vazio diz o que fazer**: "Escolha uma conversa", e não uma área
  em branco.
- O `Splitter`, e o `ResizablePanelGroup` com `stackOnNarrow`, empilham abaixo de 640px de contêiner (a largura
  da área onde ele mora, e não a da janela), e empilhar uma lista
  inteira em cima de um detalhe não é o que a pessoa quer: no estreito, a troca
  é de painel, e não de pilha.

### Painel de apoio

Na larga é 70/30, com a coluna de apoio de largura fixa; abaixo disso o apoio
desce para depois do conteúdo, ou vira uma `Sheet` quando ele só é consultado
de vez em quando.

```tsx
<div className="grid gap-8 lg:grid-cols-[minmax(0,1fr)_20rem] lg:gap-10">
  <main className="min-w-0 space-y-8">{content}</main>
  <aside className="min-w-0 lg:sticky lg:top-24 lg:self-start">{support}</aside>
</div>
```

Quando o apoio é consultado e não lido (as propriedades de um item, o filtro
fino), ele não ocupa coluna no celular: abre numa `Sheet` sem `side`, que sobe
de baixo no telefone e entra pela direita na mesa.

## Texto

- O vazio do detalhe nomeia o item: "Escolha uma conversa", "Escolha um
  pedido para ver os itens".
- O caminho de volta no estreito nomeia a lista: "Voltar às conversas", e não
  só uma seta.
- O "Voltar" do estreito vem do `labels` do `ListDetail` ("Voltar para a
  lista" por padrão); troque pelo nome da lista: "Voltar às conversas".

## Acessibilidade

- A lista e o detalhe são duas regiões com nome (`aria-label` ou o título de
  cada uma): o leitor de tela pula de uma para a outra por marco.
- Escolher um item no lado a lado não leva o foco embora da lista: a pessoa
  continua descendo pelas setas, e o detalhe se lê quando ela quiser. No
  estreito, a troca de painel leva o foco ao título do detalhe, e voltar
  devolve o foco ao item de onde saiu.
- O divisor do `ListDetail resizable` se move pelo teclado, com as setas.
- A coluna de apoio grudada (`lg:sticky`) não pode passar da altura da janela,
  senão o fim dela fica inalcançável sem rolar a página inteira.

## No celular e no nativo

No celular são duas telas: a lista e o detalhe, com o detalhe numa rota
própria e o voltar do aparelho devolvendo a lista na mesma posição. O
detalhe com endereço continua sendo pilha do router. O `ListDetail` do
`@rivocode/ui-native` resolve a mesma tela virando duas colunas quando o tablet
deita: lado a lado a partir de 840 de largura da janela, um painel por vez
abaixo disso, e o voltar do Android fechando o detalhe. O painel de apoio vira `Sheet` de baixo, que é o único modo da `Sheet`
nativa.

## Os blocos que o aplicam

Nenhum bloco do site é lista e detalhe ainda. As larguras, os vãos e as classes
de janela que estes arranjos usam estão em [layout.md](https://ds.rivocode.com.br/skill/reference/layout.md).
