ResizablePanelGroup
Três áreas, com a do meio dividida em pé
- Caixa de entrada
- Enviadas
- Rascunhos
- Arquivadas
Lateral que recolhe e lembra a medida
Filtros do período
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 oaria-valuetextdiz "40%", porque o número pelado não é medida de coisa nenhuma.aria-valueminearia-valuemaxsão os extremos que ela alcança de verdade com os vizinhos de agora, e não ominSizee omaxSizecrus. - 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-labelque 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
::aftertransparente estica 12px para cada lado sem o desenho engordar. OwithHandlepõ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 emborder. Ela é o único desenho de um controle que recebe foco, e a WCAG 1.4.11 pede 3:1 contra o fundo:bordermede 1,23:1 e sumiria,border-strongpassa 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
| Prop | Tipo | Padrão |
|---|---|---|
autoSaveIdGuarda o layout entre sessoes sob esta chave. | string | sem padrão |
layoutControlado: a medida de cada painel, em porcentagem e na ordem do documento, somando 100. | number[] | sem padrão |
onLayoutChangeO 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" |
stackOnNarrowEmpilha 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. | boolean | false |
storageOnde o `autoSaveId` guarda. | ResizableStorage | sem 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.mdA 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.
| Prop | Tipo | Padrão |
|---|---|---|
classNamesClasse por parte: `grip`, a pegadinha do `withHandle`. | Partial<Record<"grip", string>> | sem padrão |
withHandleDesenha a pegadinha no meio da linha. | boolean | false |
Além destas, a peça aceita className, style, id e children, repassados ao elemento de baixo.
ResizablePanel
/resizable-panel.mdUma 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().
| Prop | Tipo | Padrão |
|---|---|---|
collapsedSizeA medida do painel recolhido, em porcentagem, padrao 0. | number | 0 |
collapsibleDeixa o painel recolher ate o `collapsedSize`: arrastando abaixo da metade do `minSize`, pela seta, por `Home` ou por `Enter` na divisoria. | boolean | false |
defaultSizeMedida inicial, em porcentagem do grupo. | number | sem padrão |
maxSizeMaior medida, em porcentagem. | number | 100 |
minSizeMenor medida, em porcentagem. | number | 10 |
onCollapse | (() => void) | sem padrão |
onExpand | (() => void) | sem padrão |
onResizeA medida nova deste painel, em porcentagem, a cada mudanca. | ((size: number) => void) | sem padrão |
refA 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.