Pular para o conteúdo
Estrutura

ResizablePanelGroup

/componentes/resizable-panel-group.mdmarkdown cru, para quem lê com agent em vez de olho

Três áreas, com a do meio dividida em pé

  • Caixa de entrada
  • Enviadas
  • Rascunhos
  • Arquivadas
Proposta de parceria · Renata Lins
Lida por Caio às 14:02.
Inspetor

Lateral que recolhe e lembra a medida

Filtros do período

Arraste a divisória além da metade do mínimo, ou aperte Enter nela, e os filtros recolhem.
Importar
import { ResizablePanelGroup } from '@rivocode/ui'

Quando usar

Áreas lado a lado, ou empilhadas, com divisórias que se arrastam: a árvore, o editor e o inspetor de uma ferramenta; as pastas, a mensagem e o histórico dela. Quantos painéis a tela pedir, e um grupo dentro do painel de outro quando uma das áreas também se divide.

A família tem três peças. O ResizablePanelGroup é a moldura e decide a direção por orientation; o ResizablePanel é cada área; o ResizableHandle é a divisória entre duas delas.

<ResizablePanelGroup autoSaveId="caixa-de-entrada">
  <ResizablePanel defaultSize={25} minSize={15} collapsible>
    <nav>Pastas</nav>
  </ResizablePanel>
  <ResizableHandle withHandle aria-label="Entre pastas e mensagem" />
  <ResizablePanel defaultSize={50}>
    <ResizablePanelGroup orientation="vertical">
      <ResizablePanel defaultSize={70}>
        <article>Mensagem</article>
      </ResizablePanel>
      <ResizableHandle aria-label="Entre mensagem e histórico" />
      <ResizablePanel>
        <section>Histórico</section>
      </ResizablePanel>
    </ResizablePanelGroup>
  </ResizablePanel>
  <ResizableHandle aria-label="Entre mensagem e inspetor" />
  <ResizablePanel minSize={15}>
    <aside>Inspetor</aside>
  </ResizablePanel>
</ResizablePanelGroup>

Toda medida é porcentagem do grupo: defaultSize, minSize, maxSize e collapsedSize do painel, o layout controlado e o que o onLayoutChange devolve. O painel sem defaultSize divide com os outros sem medida o que sobrou. O grupo ocupa a altura e a largura de quem o contém, então a moldura de fora precisa ter altura para o vertical ter o que dividir.

A divisória

Cada ResizableHandle é um separator de verdade, e as decisões são as mesmas do Splitter, que hoje é montado por cima desta família:

  • O valor diz a medida com unidade. aria-valuenow é a medida do painel ANTES da divisória, e o aria-valuetext diz "40%", porque o número pelado não é medida de coisa nenhuma. aria-valuemin e aria-valuemax são os extremos que ela alcança de verdade com os vizinhos de agora, e não o minSize e o maxSize crus.
  • Ela aponta para o painel que mede, por aria-controls. Sem a referência, o leitor de tela não tem como saber qual dos dois lados o valor descreve.
  • O nome mora nela. O aria-label que você escreve cai no nó que tem o papel. Sem nenhum, ela se chama "Redimensionar painéis", que é melhor que silêncio e pior que dizer quais áreas ela separa: com mais de uma divisória na tela, nomeie cada uma.
  • O alvo tem 25px e a linha desenha 1. A WCAG 2.5.8 pede 24, e um ::after transparente estica 12px para cada lado sem o desenho engordar. O withHandle põe a pegadinha no meio da linha, para quem precisa ver onde pegar; o alvo é o mesmo com ou sem ela.
  • A linha pinta em border-strong, e não em border. Ela é o único desenho de um controle que recebe foco, e a WCAG 1.4.11 pede 3:1 contra o fundo: border mede 1,23:1 e sumiria, border-strong passa nos dois temas.

O teclado é o do padrão de divisória de janela da WAI-ARIA:

Tecla O que faz
← → (em pé) ou ↑ ↓ (deitada) move 2%, e os dois vizinhos trocam a medida
Home leva o painel de antes ao menor tamanho que ele alcança; se ele recolhe, recolhe
End leva o painel de antes ao maior tamanho que os vizinhos deixam
Enter recolhe o painel colapsável vizinho, ou o devolve à medida de antes

A seta que passaria do mínimo para no mínimo; no mínimo, a próxima recolhe o painel colapsável. Com o mouse o recolher é pela metade: arrastado abaixo da metade do caminho entre collapsedSize e minSize, o painel recolhe, e acima dela fica no mínimo. Nenhum painel para num tamanho que ele não aceita.

Recolher

collapsible deixa o painel encolher até o collapsedSize (0 por padrão). Recolhido em 0, ele sai da tela e do Tab: o conteúdo fica inert, e ninguém tabula para dentro de uma coluna que não aparece. Com collapsedSize acima de 0, a faixa que sobra continua alcançável, para a coluna de ícones.

onCollapse e onExpand avisam a passagem, e o ref do painel dá a API imperativa, para o botão de mostrar e esconder que mora fora do grupo:

const filtros = useRef<ResizablePanelHandle>(null)

<Button onClick={() => filtros.current?.collapse()}>Esconder filtros</Button>
<ResizablePanel ref={filtros} collapsible minSize={20}>
  <form>Filtros</form>
</ResizablePanel>

São cinco: collapse(), expand() (volta à medida de antes de recolher), resize(size), getSize() e isCollapsed().

Guardar o layout

autoSaveId guarda o layout no localStorage sob essa chave e o devolve na próxima montagem. A leitura e a escrita estão em try: modo privado que lança ao tocar no localStorage, cota cheia ou valor corrompido não derrubam a tela, e o grupo volta ao defaultSize. Layout guardado que não cabe mais nos painéis de hoje (outra quantidade, medida fora do novo mínimo) também é descartado.

storage troca o lugar: sessionStorage, ou um objeto seu com getItem e setItem que grava no perfil da pessoa. Para ter o layout nas mãos, use layout controlado com onLayoutChange.

Sentido da escrita

Em dir="rtl" o primeiro painel fica à direita, o arraste mede a partir da borda onde a leitura começa e as setas andam para o lado que a pessoa vê. A direção vem do RivoProvider, como no resto do catálogo. Home e End continuam lógicos: o mínimo e o máximo do painel de antes.

No celular, e no painel estreito

O grupo não empilha sozinho, de propósito: se três colunas viram uma pilha ou uma tela por vez é decisão da sua tela, e não da moldura. Quando a decisão é empilhar, stackOnNarrow faz isso pela largura do contêiner, e não da janela: abaixo de 40rem os painéis viram uma coluna, cada um com a altura do próprio conteúdo, e a divisória some, porque não há o que arrastar. O mesmo grupo dentro de um Card estreito empilha numa tela larga, e o de tela cheia empilha no celular.

<ResizablePanelGroup stackOnNarrow>
  <ResizablePanel defaultSize={35}>
    <ul>Pacientes</ul>
  </ResizablePanel>
  <ResizableHandle aria-label="Entre a lista e a ficha" />
  <ResizablePanel>
    <article>Ficha</article>
  </ResizablePanel>
</ResizablePanelGroup>

Para isso o grupo ganha uma caixa @container em volta, que ocupa a altura e a largura do pai. Só vale na horizontal: o grupo vertical já é uma pilha. Quando o caso é exatamente lista e detalhe, o Splitter já faz isso por você.

Quando não usar

Para duas áreas, lista e detalhe, sem recolher nem guardar, use o Splitter: é uma linha, empilha sozinho no celular e tira a divisória de onde ela não teria função. O ResizablePanelGroup é para quando a tela precisa de mais de duas áreas, de grupo dentro de grupo, de painel que recolhe ou de layout que volta igual amanhã.

Para esconder e mostrar uma área inteira sem proporção a negociar, use a Sidebar ou o Collapsible.

No React Native

Não porta, pela mesma razão do Splitter, que no web é montado por cima desta família. Três colunas que se redimensionam pedem uma tela larga e um ponteiro fino: no celular em pé não há largura para dividir, e arrastar uma linha de 1px com o dedo não é gesto que exista. As áreas viram telas do router (Expo Router, React Navigation), e o painel que recolhe vira Sheet. O layout guardado por autoSaveId não tem o que guardar lá.

API

PropTipoPadrão
autoSaveId

Guarda o layout entre sessoes sob esta chave.

stringsem padrão
layout

Controlado: a medida de cada painel, em porcentagem e na ordem do documento, somando 100.

number[]sem padrão
onLayoutChange

O layout inteiro, em porcentagem, a cada mudanca: arraste, teclado, colapso ou chamada por ref.

((sizes: number[]) => void)sem padrão
orientation

`horizontal` poe os paineis lado a lado; `vertical` empilha, e a divisoria deita.

"horizontal" | "vertical""horizontal"
stackOnNarrow

Empilha os paineis quando o CONTEINER da peca fica abaixo de 40rem, e nao a janela: o mesmo grupo dentro de um `Card` estreito empilha numa tela larga.

booleanfalse
storage

Onde o `autoSaveId` guarda.

ResizableStoragesem padrão

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

Partes

ResizablePanelGroup se monta com estas peças. Todas vivem nesta página, porque separar cada uma num endereço obrigaria a abrir seis abas para montar uma tela.

ResizableHandle

/resizable-handle.md

A divisória entre dois painéis de um ResizablePanelGroup: um separator que anda pelas setas, com a medida do painel de antes em aria-valuetext e o alvo de 25px, acima dos 24 que a WCAG 2.5.8 pede.

withHandle desenha a pegadinha no meio da linha. Nomeie cada divisória por aria-label quando houver mais de uma na tela.

PropTipoPadrão
classNames

Classe por parte: `grip`, a pegadinha do `withHandle`.

Partial<Record<"grip", string>>sem padrão
withHandle

Desenha a pegadinha no meio da linha.

booleanfalse

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

ResizablePanel

/resizable-panel.md

Uma das áreas de um ResizablePanelGroup.

As medidas são porcentagem do grupo: defaultSize é onde ela começa, minSize e maxSize são os limites que a divisória respeita. collapsible deixa a área recolher até o collapsedSize, e recolhida em 0 ela sai do Tab. O ref dá collapse(), expand(), resize(size), getSize() e isCollapsed().

PropTipoPadrão
collapsedSize

A medida do painel recolhido, em porcentagem, padrao 0.

number0
collapsible

Deixa o painel recolher ate o `collapsedSize`: arrastando abaixo da metade do `minSize`, pela seta, por `Home` ou por `Enter` na divisoria.

booleanfalse
defaultSize

Medida inicial, em porcentagem do grupo.

numbersem padrão
maxSize

Maior medida, em porcentagem.

number100
minSize

Menor medida, em porcentagem.

number10
onCollapse(() => void)sem padrão
onExpand(() => void)sem padrão
onResize

A medida nova deste painel, em porcentagem, a cada mudanca.

((size: number) => void)sem padrão
ref

A API imperativa: `collapse()`, `expand()`, `resize(size)`, `getSize()` e `isCollapsed()`.

Ref<ResizablePanelHandle>sem padrão

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.