Pular para o conteúdo
Estrutura

ListDetail

/componentes/list-detail.mdmarkdown cru, para quem lê com agent em vez de olho

Pedidos da loja

5 pedidos nesta semana

Pedido 4820

Rafael Antunes · Curitiba, PR

Situação
Em separação
Feito em
hoje, 08:15
Itens
1
Total
R$ 1.249,00
Entrega
Sedex · 2 dias úteis

Caixa de entrada, com a divisória arrastável

Nenhuma mensagem aberta

Escolha uma mensagem na lista para ler aqui.

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

Quando usar

O layout canônico de lista e detalhe: a caixa de entrada, os pedidos, os clientes, os chamados. A lista à esquerda, o item escolhido à direita, e a regra de adaptação, que é a parte que se esquece, já decidida.

Largura da peça O que aparece
A peça com 768px ou mais os dois lado a lado; sem escolha, o detalhe mostra o emptyDetail
Abaixo de 768px um painel por vez: a lista, ou o detalhe com o botão “Voltar para a lista”

A medida é a largura da própria peça, e não a da janela: ao lado da barra lateral da casca, ela decide pelo espaço que tem. stackBelow muda o corte, em rem (padrão 48).

A largura é a da própria peça, e não a da janela. Num painel de 600px de uma tela de 1440px, ela mostra um painel por vez, porque é o espaço que ela tem. Antes de a peça se medir - a primeira pintura do servidor -, vale a largura da janela, por CSS, então a página inteira já sai no arranjo certo; a medida assume em seguida, e só muda alguma coisa quando a peça é mais estreita que a janela.

Ao estreitar com um item aberto, fica o detalhe, e o voltar leva à lista. Ao alargar, a lista volta marcando o item aberto, ou o detalhe vazio convida a escolher.

const [selected, setSelected] = useState<string | null>(null)
const order = orders.find((entry) => entry.id === selected)

<div className="h-[calc(100dvh-4rem)]">
  <ListDetail
    selected={selected}
    onSelectedChange={setSelected}
    emptyDetail={
      <EmptyState title="Escolha um pedido" description="O pedido abre aqui, com a entrega e o que falta fazer." />
    }
  >
    <ListDetailList header={<SearchInput aria-label="Buscar pedido" placeholder="Cliente ou número" />}>
      {orders.map((entry) => (
        <ListDetailItem key={entry.id} value={entry.id}>
          {entry.customer} · Pedido {entry.id}
        </ListDetailItem>
      ))}
    </ListDetailList>
    <ListDetailPane>
      {order && (
        <div className="space-y-6 p-[var(--rc-pad-panel)]">
          <ListDetailTitle level={2}>Pedido {order.id}</ListDetailTitle>
          <DescriptionList>…</DescriptionList>
        </div>
      )}
    </ListDetailPane>
  </ListDetail>
</div>

A peça ocupa a altura do pai, e cada painel rola sozinho: a lista desce sem levar o detalhe junto, e o header da lista fica parado no topo. Dê a altura ao pai: a da janela menos o cabeçalho da aplicação, ou a do painel em que ela mora.

As partes

  • ListDetail é a raiz: guarda a escolha, lê a largura e decide o que aparece.
  • ListDetailList é o painel da lista, uma região chamada “Lista”. Os filhos saem numa lista que rola, um div com role="list", e o header fica acima dela, parado.
  • ListDetailItem é cada item: um botão dentro de um role="listitem", com o value que o identifica. O item aberto sai com aria-current="true", o fundo selected e o fio de acento à esquerda. render troca o botão pelo link do router sem perder a escolha.
  • ListDetailPane é o painel do detalhe. Com um item aberto mostra os filhos; sem, o emptyDetail. No estreito ele ganha a faixa do voltar em cima.
  • ListDetailTitle é o título do detalhe: um Heading, com o level que a página pede. Ele dá nome à região do detalhe e é o alvo do foco.

A escolha mora onde o app quiser

selected e onSelectedChange são controlados, e o value de cada item é uma string, que é o que cabe num endereço. Sem selected, a peça guarda a escolha sozinha a partir do defaultSelected. onSelectedChange chega com o value do item escolhido, e com null quando a pessoa volta para a lista no estreito.

Ponha a escolha na URL quando o detalhe tem endereço. O link copiado abre o mesmo pedido, e o “Voltar” do navegador volta à lista sem código nenhum, porque a URL mudou e o selected veio junto. No Next, com o searchParams:

'use client'

const params = useSearchParams()
const router = useRouter()
const pathname = usePathname()

<ListDetail
  selected={params.get('pedido')}
  onSelectedChange={(id) => router.push(id ? `${pathname}?pedido=${id}` : pathname)}
>
  …
</ListDetail>

No React Router, o mesmo gesto com o useSearchParams dele:

const [params, setParams] = useSearchParams()

<ListDetail
  selected={params.get('pedido')}
  onSelectedChange={(id) => setParams(id ? { pedido: id } : {})}
>
  …
</ListDetail>

router.push e setParams empilham no histórico, e é isso que se quer: cada pedido aberto é um passo que o “Voltar” desfaz. Para trocar de item sem encher o histórico, use router.replace ou setParams(…, { replace: true }).

Com o QueryBoundary

A lista que chega da rede entra pelo QueryBoundary dentro da ListDetailList, e não em volta dela: o header com a busca fica parado enquanto carrega, e o carregando, o erro e o vazio ocupam o lugar dos itens.

<ListDetailList header={<SearchInput aria-label="Buscar pedido" />}>
  <QueryBoundary
    data={pedidos.data}
    isLoading={pedidos.isLoading}
    isError={pedidos.isError}
    onRetry={pedidos.refetch}
    empty={{ title: 'Nenhum pedido ainda' }}
  >
    {(lista) =>
      lista.map((pedido) => (
        <ListDetailItem key={pedido.id} value={pedido.id}>
          {pedido.cliente}
        </ListDetailItem>
      ))
    }
  </QueryBoundary>
</ListDetailList>

A lista é um div com role="list", e não um <ul>, por causa dessa composição: o QueryBoundary desenha div, e um div filho direto de <ul> é HTML inválido. Os itens continuam anunciados como lista, com a contagem.

Foco e leitor de tela

Lista e detalhe são duas regiões com nome: “Lista”, e o título do detalhe aberto, ou “Detalhe” quando não há título. Quem navega por região salta de uma para a outra.

No estreito, o foco acompanha o painel. Escolher um item leva o foco ao ListDetailTitle, e o leitor de tela anuncia o título do que abriu; sem título, o foco vai à região do detalhe. Voltar devolve o foco ao item que estava aberto, e a lista volta na mesma rolagem, porque ela não desmonta enquanto o detalhe está na frente. Estreitar a janela com o foco na lista leva o foco ao título, para ele não cair num painel que sumiu.

Na larga o foco fica onde está. Escolher na lista não o tira do item: quem desce pelas setas da lista continua descendo, e o detalhe ao lado muda junto.

A divisória

resizable põe uma divisória arrastável entre os painéis na larga, a do ResizablePanelGroup, que anda pelas setas e diz a medida em porcentagem. defaultSize é a largura inicial da lista, em porcentagem, e o padrão é 35. No estreito não há divisória, porque só um painel aparece. Sem resizable, a lista tem 20rem fixos, que é o que serve à maioria das caixas de entrada.

O painel de apoio fica fora, e é receita

O outro layout canônico de dois painéis, o de apoio (o resumo ao lado do checkout, as propriedades do item num editor), não é prop desta peça. Ele não tem escolha, nem um painel por vez: o apoio acompanha o conteúdo, 70/30 na larga, e no celular desce para depois dele ou abre numa folha. A peça ganharia props que não conversam com o selected, e o arranjo já se escreve em três linhas:

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

Quando o apoio é consultado e não lido, ele vai numa Sheet sem side, que sobe de baixo no telefone e entra pela direita na mesa.

Partes

classNames alcança cada nó pelo nome. Na raiz, handle é a divisória do resizable. Na ListDetailList, header é o topo parado e items a lista que rola. Na ListDetailPane, bar é a faixa do voltar no estreito, back o botão, body a área que rola e empty a moldura do emptyDetail.

Textos

labels troca o texto do botão de voltar (back, “Voltar para a lista”), os nomes das regiões (list, “Lista”; detail, “Detalhe”) e o nome da divisória (handle). Numa caixa de entrada, back: 'Voltar para a caixa de entrada' diz mais que o padrão.

Quando não usar

  • Duas áreas sempre visíveis, com a proporção como decisão é Splitter. Ele não sabe de escolha nem de um painel por vez: abaixo de 640px empilha os dois, e empilhar a lista inteira em cima do detalhe não é o que a pessoa quer numa caixa de entrada.
  • Abrir o detalhe por cima da listagem, sem trocar de arranjo é Sheet. A folha mantém a tabela inteira atrás, na largura toda, e é a escolha quando a listagem é uma DataTable larga e o detalhe é consultado de vez em quando.
  • Uma decisão curta sobre o item (confirmar, renomear, mover) é Dialog. O detalhe do ListDetail é lugar de ler e trabalhar; o diálogo pede uma resposta e fecha.
  • Esconder e mostrar a navegação é a Sidebar. A lista aqui é o conteúdo, e não o menu da aplicação.

iOS e Android

O puxar para atualizar da lista (onRefresh e refreshing) é desenhado pelo sistema: no iOS o giro aparece acima da lista enquanto ela estica; no Android um disco desce por cima da lista. A cor é a da casa nos dois: o giro em accent-text e, no Android, o disco em surface-raised.

No React Native

Traduz, e o caso que justifica a peça no celular é o tablet. No telefone, lista e detalhe com endereço próprio (o pedido, a conversa, o cliente) continuam sendo duas telas do router, numa pilha: o gesto de voltar, o histórico e o título da barra vêm de graça, e é isso que a pessoa espera. O que o router não dá é a mesma tela virando duas colunas quando o iPad deita, e é aí que o ListDetail mora.

O corte é a janela, por useWindowDimensions, e é 840 e não o 1024 do web. É a classe expandida do Material: o iPad em pé (de 744 a 834) fica com um painel por vez, e deitado ganha os dois. Como a medida é da janela, a tela dividida do iPad volta a um painel sozinha. Abaixo do corte vale a regra do web: escolher na lista mostra o detalhe no lugar dela, o botão “Voltar para a lista” devolve a lista, e o voltar do Android também, enquanto um detalhe estiver aberto. Com a lista na tela, o voltar segue para o router.

A lista vem por items e o detalhe por renderDetail, como em todo o pacote. Cada item tem title, description, media e meta, os lugares do Item; o título do detalhe é o title do item, desenhado em cima como cabeçalho. Ao abrir no estreito, o leitor de tela vai a esse título; ao voltar, ao item que estava aberto. A lista fica montada por baixo do detalhe, e volta na mesma rolagem.

<ListDetail
  items={pedidos}
  selected={id}
  onSelectedChange={setId}
  renderDetail={(pedido) => <DescriptionList>…</DescriptionList>}
  emptyDetail={<EmptyState title="Escolha um pedido" description="O pedido abre aqui." />}
/>

Não há resizable. Arrastar uma borda de um pixel com o dedo não é gesto que exista, pela mesma razão de o Splitter não portar; a lista tem largura fixa de 320.

A lista tem os quatro finais do DataList, com os mesmos nomes, porque aqui ela vem por items e não há onde a tela os pôr: isLoading põe o esqueleto debaixo do header, isError o aviso com a errorMessage e o "Tentar de novo" do onRetry, e empty o EmptyState quando items volta vazio. onRefresh e refreshing ligam o puxar para atualizar. bottomInset dá o respiro embaixo da lista e do detalhe, para a última linha não nascer atrás da barra de abas.

O detalhe sobe com o teclado, e o renderDetailFooter é o rodapé parado embaixo do que rola: os botões da ação do item aberto. detailScrollEnabled={false} tira a rolagem do detalhe, para o renderDetail que já traz a própria lista.

No iOS e no Android. No telefone, o voltar do Android volta do detalhe para a lista. O iOS não tem voltar: volta-se pelo botão “Voltar” da barra do detalhe ou pelo gesto de escape do VoiceOver. Ao chegar no fim da rolagem, o iOS estica com mola e o Android estica a borda (Android 12 ou mais novo) ou mostra o brilho (até o 11). É o gesto do sistema, e a peça não o troca.

API

PropTipoPadrão
classNames

Classe por parte: `handle`, a divisoria do `resizable`.

Partial<Record<"handle", string>>sem padrão
defaultSelected

A escolha inicial, quando a peca guarda o estado sozinha.

string | nullnull
defaultSize

A largura inicial da lista com `resizable`, em porcentagem.

number35
emptyDetail

O que o painel de detalhe mostra na larga quando nada esta aberto: um `EmptyState` que convida a escolher.

ReactNodesem padrão
labels

O texto do botao de voltar e os nomes que o leitor de tela anuncia para cada painel e para a divisoria.

Partial<ListDetailLabels>sem padrão
onSelectedChange

Chamado com o `value` do item escolhido, e com `null` quando a pessoa volta para a lista no estreito.

((value: string | null) => void)sem padrão
resizable

Poe uma divisoria arrastavel entre a lista e o detalhe na larga.

booleanfalse
selected

O `value` do item aberto, ou `null` quando nenhum esta.

string | nullsem padrão
stackBelow

A largura da propria peca, em rem, abaixo da qual ela mostra um painel por vez.

number48

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.