Pular para o conteúdo

Padrões de UX / Dados e listas

Lista e detalhe, e o painel de apoio

Lado a lado só na tela larga, um painel por vez no resto, e o item escolhido no endereço.

/padroes/lista-e-detalhe.mdo mesmo arquivo que a skill entrega ao agente

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.

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.

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.

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

@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.