# ResizablePanelGroup

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

```tsx
<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:

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

```tsx
<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á.

## Importação

```tsx
import { ResizablePanelGroup } from '@rivocode/ui'
```

## Exemplos

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

```tsx
import { ResizableHandle, ResizablePanel, ResizablePanelGroup } from '@rivocode/ui'

const PASTAS = ['Caixa de entrada', 'Enviadas', 'Rascunhos', 'Arquivadas']

export function Workspace() {
  return (
    <div className="h-72 w-[40rem] overflow-hidden rounded-lg border border-border">
      <ResizablePanelGroup>
        <ResizablePanel defaultSize={25} minSize={15}>
          <ul className="flex flex-col py-2">
            {PASTAS.map((pasta) => (
              <li key={pasta} className="truncate px-3 py-1.5 text-sm text-fg-muted">
                {pasta}
              </li>
            ))}
          </ul>
        </ResizablePanel>
        <ResizableHandle withHandle aria-label="Entre pastas e mensagem" />
        <ResizablePanel defaultSize={50} minSize={30}>
          <ResizablePanelGroup orientation="vertical">
            <ResizablePanel defaultSize={65} minSize={30} className="p-3 text-base text-fg">
              Proposta de parceria · Renata Lins
            </ResizablePanel>
            <ResizableHandle aria-label="Entre mensagem e histórico" />
            <ResizablePanel minSize={20} className="p-3 text-sm text-fg-muted">
              Lida por Caio às 14:02.
            </ResizablePanel>
          </ResizablePanelGroup>
        </ResizablePanel>
        <ResizableHandle aria-label="Entre mensagem e inspetor" />
        <ResizablePanel minSize={15} className="p-3 text-sm text-fg-muted">
          Inspetor
        </ResizablePanel>
      </ResizablePanelGroup>
    </div>
  )
}
```

### Lateral que recolhe e lembra a medida

```tsx
import { ResizableHandle, ResizablePanel, ResizablePanelGroup } from '@rivocode/ui'

export function CollapsibleSidebar() {
  return (
    <div className="h-56 w-[36rem] overflow-hidden rounded-lg border border-border">
      <ResizablePanelGroup autoSaveId="exemplo-lateral">
        <ResizablePanel defaultSize={30} minSize={20} collapsible>
          <p className="p-3 text-sm text-fg-muted">Filtros do período</p>
        </ResizablePanel>
        <ResizableHandle withHandle aria-label="Largura dos filtros" />
        <ResizablePanel className="p-3 text-base text-fg">
          Arraste a divisória além da metade do mínimo, ou aperte Enter nela, e os filtros
          recolhem.
        </ResizablePanel>
      </ResizablePanelGroup>
    </div>
  )
}
```

## Props

| Prop | Tipo | Obrigatória | Padrão | Desde | O que faz |
| --- | --- | --- | --- | --- | --- |
| `autoSaveId` | `string` |  |  | - | Guarda o layout entre sessoes sob esta chave. |
| `layout` | `number[]` |  |  | - | Controlado: a medida de cada painel, em porcentagem e na ordem do documento, somando 100. |
| `onLayoutChange` | `((sizes: number[]) => void)` |  |  | - | O layout inteiro, em porcentagem, a cada mudanca: arraste, teclado, colapso ou chamada por ref. |
| `orientation` | `"horizontal" \| "vertical"` |  | `"horizontal"` | - | `horizontal` poe os paineis lado a lado; `vertical` empilha, e a divisoria deita. |
| `stackOnNarrow` | `boolean` |  | `false` | - | 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. |
| `storage` | `ResizableStorage` |  |  | - | Onde o `autoSaveId` guarda. |

Além dessas: repassa `className`, `style`, `id` e os demais atributos do elemento raiz.

## Partes

O componente se monta com as peças abaixo. Todas vêm de `@rivocode/ui`.

### ResizableHandle

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.

| Prop | Tipo | Obrigatória | Padrão | Desde | O que faz |
| --- | --- | --- | --- | --- | --- |
| `classNames` | `Partial<Record<"grip", string>>` |  |  | - | Classe por parte: `grip`, a pegadinha do `withHandle`. |
| `withHandle` | `boolean` |  | `false` | - | Desenha a pegadinha no meio da linha. |

### ResizablePanel

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()`.

| Prop | Tipo | Obrigatória | Padrão | Desde | O que faz |
| --- | --- | --- | --- | --- | --- |
| `collapsedSize` | `number` |  | `0` | - | A medida do painel recolhido, em porcentagem, padrao 0. |
| `collapsible` | `boolean` |  | `false` | - | Deixa o painel recolher ate o `collapsedSize`: arrastando abaixo da metade do `minSize`, pela seta, por `Home` ou por `Enter` na divisoria. |
| `defaultSize` | `number` |  |  | - | Medida inicial, em porcentagem do grupo. |
| `maxSize` | `number` |  | `100` | - | Maior medida, em porcentagem. |
| `minSize` | `number` |  | `10` | - | Menor medida, em porcentagem. |
| `onCollapse` | `(() => void)` |  |  | - |  |
| `onExpand` | `(() => void)` |  |  | - |  |
| `onResize` | `((size: number) => void)` |  |  | - | A medida nova deste painel, em porcentagem, a cada mudanca. |
| `ref` | `Ref<ResizablePanelHandle>` |  |  | - | A API imperativa: `collapse()`, `expand()`, `resize(size)`, `getSize()` e `isCollapsed()`. |

## Ver também

- [Accordion](/componentes/accordion.md)
- [Affix](/componentes/affix.md)
- [AppShell](/componentes/app-shell.md)
- [AspectRatio](/componentes/aspect-ratio.md)
- [Avatar](/componentes/avatar.md)
- [Card](/componentes/card.md)
- [Convenções da biblioteca](/convencoes.md): Provider, tokens e as regras que valem para toda peça
- [Índice completo](/llms.txt)
