ListDetail
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.
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, umdivcomrole="list", e oheaderfica acima dela, parado.ListDetailItemé cada item: um botão dentro de umrole="listitem", com ovalueque o identifica. O item aberto sai comaria-current="true", o fundoselectede o fio de acento à esquerda.rendertroca o botão pelo link do router sem perder a escolha.ListDetailPaneé o painel do detalhe. Com um item aberto mostra os filhos; sem, oemptyDetail. No estreito ele ganha a faixa do voltar em cima.ListDetailTitleé o título do detalhe: umHeading, com olevelque 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 é umaDataTablelarga e o detalhe é consultado de vez em quando. - Uma decisão curta sobre o item (confirmar, renomear, mover) é
Dialog. O detalhe doListDetailé 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
| Prop | Tipo | Padrão |
|---|---|---|
classNamesClasse por parte: `handle`, a divisoria do `resizable`. | Partial<Record<"handle", string>> | sem padrão |
defaultSelectedA escolha inicial, quando a peca guarda o estado sozinha. | string | null | null |
defaultSizeA largura inicial da lista com `resizable`, em porcentagem. | number | 35 |
emptyDetailO que o painel de detalhe mostra na larga quando nada esta aberto: um `EmptyState` que convida a escolher. | ReactNode | sem padrão |
labelsO 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 |
onSelectedChangeChamado 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 |
resizablePoe uma divisoria arrastavel entre a lista e o detalhe na larga. | boolean | false |
selectedO `value` do item aberto, ou `null` quando nenhum esta. | string | null | sem padrão |
stackBelowA largura da propria peca, em rem, abaixo da qual ela mostra um painel por vez. | number | 48 |
Além destas, a peça aceita className, style, id e children, repassados ao elemento de baixo.