# Layout com o @rivocode/ui

Este arquivo diz onde as coisas cabem e como se adaptam à largura. **Como
decidir a forma da tela** (o arquétipo, o ponto focal, as proporções e a
crítica do print) está em [composicao.md](composicao.md): leia antes, e volte
aqui para montar.

## Conteúdo

- As classes de janela
- As larguras de página
- Os dois vãos
- Os layouts canônicos: lista e detalhe, painel de apoio, feed
- Os quatro esqueletos de página
- Grid ou flex, e a armadilha do `min-w-0`
- Alinhamento
- A largura do campo diz o tamanho do dado
- Densidade, e o que ela move
- Estreito primeiro
- Erros de layout que aparecem sempre

## As classes de janela

A largura não é um contínuo: são quatro classes, e cada uma decide três coisas
antes de qualquer classe CSS. Escreva a compacta primeiro e suba.

| Classe | Largura | Quantos painéis | Navegação | Onde mora a ação principal |
|---|---|---|---|---|
| Compacta | abaixo de 640px (sem prefixo) | um por vez; o apoio abre em `Sheet`, que sobe de baixo | a `Sidebar` vira folha, aberta pelo `SidebarTrigger` do cabeçalho; no app nativo, a barra de abas | no pé, em largura cheia, ao alcance do polegar |
| Média | de 640 a 1023px (`sm:`, `md:`) | um, com o apoio em `Sheet` pela direita | a `Sidebar` à vista, aberta ou recolhida | no cabeçalho da página, nas `actions` do `PageHeader` |
| Larga | de 1024px (`lg:`) | dois: lista e detalhe, ou conteúdo e apoio | a `Sidebar` aberta | no cabeçalho, à direita; no formulário, no fim |
| Ampla | de 1280px (`xl:`) | dois, e um terceiro só se for apoio fixo | a `Sidebar` aberta | igual à larga; a sobra vira margem, e não coluna nova |

Na ampla, a tentação é encher: cinco colunas de cartões porque cabem. A sobra de
largura é margem, pelo teto do `Container`, e não mais conteúdo.

## As larguras de página

Toda página tem **uma** largura, e ela tem nome. Escolha pelo que a página
faz, e não pelo que sobra da tela.

| Nome | Classe | Para |
|---|---|---|
| Leitura | `max-w-prose` | texto corrido, artigo, termo de uso, ajuda |
| Formulário | `max-w-3xl`, ou `<Container size="md">` | cadastro, wizard, configuração de uma coluna |
| Padrão | `<Container size="lg">`, 72rem | página com colunas: detalhe, produto, configurações em duas colunas |
| Larga | `<Container size="xl">`, 80rem | painel, listagem com filtro ao lado |
| Cheia | `<Container size="full">` | tabela de operação, calendário, quadro: a informação é a largura |

E uma densidade por página, decidida no `RivoProvider`: `compact` no que se
opera o dia inteiro, `comfortable` no resto.

## Os dois vãos

São dois papéis, e não uma escala inteira. O de dentro junta, o de fora separa,
e o de fora é **pelo menos o dobro** do de dentro: é essa diferença que agrupa
sem cartão.

| Vão | Medida | Classes | Onde |
|---|---|---|---|
| Dentro do grupo | de 8 a 16px | `gap-2`, `gap-3`, `gap-4`, `space-y-2`, `space-y-4` | ícone e texto, botões irmãos, filtros de uma barra, campos de uma seção, título e a frase dele |
| Entre seções | de 32 a 48px | `space-y-8`, `space-y-10`, `space-y-12`, `gap-8`, `gap-10` | entre assuntos da página, entre a coluna de conteúdo e a de apoio |

`space-y-6` (24px) é o vão de dentro de uma moldura (`Card`, `Sheet`,
`Dialog`), onde 32px não cabe. `p-4 sm:p-6` é o respiro da página. Dentro do
`Card`, use `CardContent` em vez de inventar `padding`: ele já traz o
`--rc-pad-panel`, que a densidade move junto.

**Uma distância só entre irmãos.** Se um bloco precisa de mais ar que o vizinho,
o problema quase sempre é falta de hierarquia, não falta de pixel.

## Os layouts canônicos

Três arranjos resolvem quase toda tela de dois painéis. Cada um tem uma regra
de adaptação, e é ela que se esquece.

### Lista e detalhe, e painel de apoio

A lista com o item escolhido ao lado, e o conteúdo com o que o apoia. **Lado a
lado só na larga**; na compacta e na média é um painel por vez, e o apoio que só
se consulta vira `Sheet`. O padrão inteiro, com o código, o endereço do item e o
caminho de volta, está em [lista-e-detalhe.md](lista-e-detalhe.md).

### Feed

Uma coluna que cresce para baixo: atividade, notificação, conversa, publicação.
A largura é a de leitura, e não a da tela: `mx-auto max-w-2xl`, com os itens em
`divide-y` ou `space-y-4`. Na larga, a sobra vira margem, ou uma coluna de apoio
pelo arranjo acima. Feed de cartões com imagem (produtos, imóveis) é a grade:

```tsx
<Grid minItemWidth="16rem" gap="lg" render={<ul />}>
  {products.map((product) => (
    <li key={product.id}>
      <ProductCard product={product} />
    </li>
  ))}
</Grid>
```

O `minItemWidth` desce para uma coluna no telefone e sobe sozinho na mesa, sem
media query.

## Os quatro esqueletos de página

São a moldura, e não a composição: quase toda tela de produto mora numa destas
quatro, e o que vai dentro dela é o arquétipo que você escolheu em
[composicao.md](composicao.md). Comece pela que se parece com o pedido e
ajuste, em vez de montar do zero.

### 1. Operação: barra lateral e área de trabalho

O padrão de sistema interno. A barra guarda a navegação, o `SidebarInset`
recebe a página.

```tsx
<SidebarProvider defaultOpen>
  <Sidebar>
    <SidebarHeader><SidebarBrand mark={<Waves size={18} />}>RivoCode</SidebarBrand></SidebarHeader>
    <SidebarContent>
      <SidebarGroup label="Operação">
        <SidebarMenu>{items}</SidebarMenu>
      </SidebarGroup>
    </SidebarContent>
  </Sidebar>

  <SidebarInset>
    <header className="sticky top-0 z-[var(--rc-z-sticky)] flex items-center gap-3 border-b border-border bg-bg/90 px-4 py-3 backdrop-blur-md">
      <SidebarTrigger />
      <Breadcrumb items={trilha} className="min-w-0" />
      <div className="ml-auto flex items-center gap-2">{actions}</div>
    </header>

    <div className="p-4 sm:p-6">{page}</div>
  </SidebarInset>
</SidebarProvider>
```

O `ml-auto` no bloco de ações é o que separa navegação de ação sem precisar de
`justify-between`, que brigaria com o `gap`.

**A barra flutuante**, solta da borda, com a página num cartão ao lado. Não é
variante da peça: são classes no mesmo esqueleto.

```tsx
<SidebarProvider defaultOpen className="sm:h-dvh sm:gap-3 sm:overflow-hidden sm:p-3">
  <Sidebar className="sm:h-full sm:rounded-xl sm:border">{nav}</Sidebar>

  <SidebarInset className="sm:h-full sm:overflow-y-auto sm:overscroll-contain sm:rounded-xl sm:border sm:border-border sm:bg-surface">
    <header className="... sm:rounded-t-xl">{bar}</header>
    <div className="p-4 sm:p-6">{page}</div>
  </SidebarInset>
</SidebarProvider>
```

O cartão solto da borda não combina com a rolagem da janela, e por isso a
casca tem a altura da janela (`h-dvh` com `overflow-hidden`) e o cartão rola
por dentro. Sem isso, com a página mais alta que a tela, o cartão passa da
janela e o canto de baixo só aparece no fim da rolagem, o conteúdo passa pela
fresta de 12px acima do cabeçalho fixo, e a barra estica até a altura da
página, levando o `SidebarFooter` para fora da tela. O `h-full` da barra e do
cartão é a altura da linha, que já desconta o `p-3`; o `overscroll-contain`
segura a rolagem no cartão quando ela chega ao fim. O `border` sem lado
contorna a barra inteira em vez de só a divisa. O prefixo `sm:` não é enfeite:
abaixo de 640px a `Sidebar` vira `Sheet`, a `className` dela vai para a folha,
que ficaria com cantos e contorno de cartão, e a página volta a rolar pela
janela. O `rounded-t-xl` no cabeçalho fixo é o que impede o canto reto dele de
vazar por cima do canto redondo do cartão.

Com o `AppShell`, o mesmo pelas partes:

```tsx
<AppShell
  className="sm:h-dvh sm:gap-3 sm:overflow-hidden sm:p-3"
  classNames={{
    sidebar: "sm:h-full sm:rounded-xl sm:border",
    column: "sm:h-full sm:overflow-y-auto sm:overscroll-contain sm:rounded-xl sm:border sm:border-border sm:bg-surface",
    header: "sm:rounded-t-xl sm:bg-surface",
  }}
  sidebar={nav}
  header={bar}
>
  {page}
</AppShell>
```

Na mesa, quem rola passa a ser o cartão, e não a janela. O que mede a rolagem
precisa apontar para ele: o `ScrollToTop` pelo `target`, e o
`TableOfContents` pelo `root` (com o `offset` da altura do cabeçalho fixo).
Passe o elemento, e não o ref:
`const [cartao, setCartao] = useState<HTMLElement | null>(null)` e
`ref={setCartao}` no `SidebarInset`. A coluna do `AppShell` não recebe ref:
quando a tela tem `ScrollToTop` ou `TableOfContents`, monte a casca pelo
`SidebarProvider`, como no primeiro bloco.

### 2. Listagem: filtros, tabela, paginação

```tsx
<div className="space-y-4">
  <div className="flex flex-wrap items-center gap-3">
    <SearchInput aria-label="Buscar cliente" placeholder="Nome, CNPJ ou cidade" className="min-w-60 flex-1" />
    {filters}
  </div>

  <DataTable {...} />

  <div className="flex justify-center">
    <Pagination page={page} pageCount={pageCount} onPageChange={setPage} />
  </div>
</div>
```

`flex-wrap` na barra de filtros, sempre. Sem ela, o quinto filtro empurra a
busca para fora da tela em vez de descer uma linha. E sem `Card` em volta: a
fileira já é um grupo pelo vão, e a moldura só abriria uma segunda borda
esquerda acima da tabela.

### 3. Formulário longo: régua de passos e o passo sem moldura

```tsx
<div className="mx-auto max-w-3xl space-y-8">
  <Steps steps={STEPS} step={wizard.step} onStepChange={wizard.goTo} />
  <section className="space-y-4">
    <h2 className="text-xl font-rc-strong text-fg">{stepQuestion}</h2>
    {fields}
  </section>
  <WizardFooter>{actions}</WizardFooter>
</div>
```

`max-w-3xl` e não a largura toda: formulário esticado numa tela de 1440 vira
campo de 1200px de largura para digitar um CNPJ.

### 4. Painel: um herói, a faixa, o gráfico

```tsx
<div className="space-y-10">
  <section className="grid gap-8 lg:grid-cols-[minmax(0,2fr)_minmax(0,1fr)]">
    <div className="min-w-0">{hero}</div>
    <aside className="min-w-0">{pending}</aside>
  </section>
  <dl className="grid divide-y divide-border border-y border-border sm:grid-cols-3 sm:divide-x sm:divide-y-0">
    {secondary}
  </dl>
  <ChartContainer config={config} className="h-64">{chart}</ChartContainer>
</div>
```

O número herói vem antes do gráfico porque responde em um segundo; o gráfico
pede dez. Os números de apoio ficam numa faixa sem moldura, e o gráfico sem
cartão. O painel inteiro, com as variações e o molde a evitar, está em
[composicao.md](composicao.md).

## Grid ou flex, e a armadilha do `min-w-0`

- **Grid** quando as colunas são a estrutura: painel, formulário de duas
  colunas, listagem com barra lateral de filtro.
- **Flex** quando os itens são uma fila que pode quebrar: ações, filtros,
  etiquetas.

A armadilha vale para os dois: **item de grid e item de flex têm
`min-width: auto`**, ou seja, nunca encolhem abaixo do próprio `min-content`.
Uma tabela larga dentro de uma coluna estica a coluna inteira, e o vizinho vai
junto para fora da tela.

```tsx
// A tabela volta a rolar dentro da própria caixa.
<div className="grid gap-4 lg:grid-cols-[16rem_1fr] [&>*]:min-w-0">
```

O mesmo vale para texto que promete cortar: `truncate` sem `min-w-0` não corta
nada, ele empurra.

```tsx
<span className="min-w-0 flex-1 truncate">{nome}</span>
```

Quando o conteúdo é largo por natureza, deixe **ele** rolar, e não a página:
`overflow-x-auto` na caixa dele. A `Table` já faz isso sozinha.

Cuidado com um efeito do CSS: num elemento com `overflow-y-auto`, o eixo X
deixa de ser `visible` e vira `auto` também. Uma área de página que rola
verticalmente rola de lado sem ninguém pedir, e o vazamento não aparece no
`scrollWidth` do documento.

## Alinhamento

- A largura de cada tipo de página está em "As larguras de página", acima.
  Linha de 200 caracteres não se lê.
- Número em tabela: `text-right` e `tabular-nums`. Alinhados à direita e com
  dígito de largura fixa, os valores se comparam na vertical sem esforço, sem a
  cara de terminal da `font-mono`.
- Rótulo acima do campo, nunca ao lado: no celular não cabe ao lado, e uma tela
  que muda de arranjo entre larguras custa mais do que ganha.
- Link para outra rota passa pelo router: `Link`, `Button` e
  `SidebarMenuItem` aceitam `render={<RouterLink to="/notas" />}`, e o `<a>`
  cru recarrega a página. Peça que recebe a lista por `items` leva o `render`
  em cada item: a migalha do `Breadcrumb` e a notificação do
  `NotificationCenter` (`{ label: 'Notas', render: <RouterLink to="/notas" /> }`).

## A largura do campo diz o tamanho do dado

Num formulário de duas colunas, todo campo ganha a mesma largura, e o CEP fica
do tamanho da razão social. A largura é uma pista: campo de CEP do tamanho de
um CEP diz "oito dígitos" antes de a pessoa ler o rótulo.

| Dado | Largura na mesa |
|---|---|
| CEP, UF, número, CVV, validade | `sm:max-w-40` |
| CPF, telefone, data, valor | `sm:max-w-60` |
| CNPJ, placa, cartão | `sm:max-w-72` |
| nome, e-mail, endereço, descrição | a coluna toda |

No celular todos ficam em largura cheia, que é onde o polegar acerta. O limite
entra só a partir do `sm:`, no `className` do campo, e nunca como altura.

```tsx
<FormField name="postalCode" label="CEP">
  {(field) => <MaskedInput {...forValue(field)} mask="cep" className="sm:max-w-40" />}
</FormField>
```

## Densidade, e o que ela move

`density="compact"` encolhe altura de controle, `--rc-item-y`, o respiro dos
painéis e o `gap` de `Stack` e `Grid`, que sai de `--rc-gap-*`. Ela **não** mexe
no `gap` nem no `padding` que você escreve à mão.

Por isso: altura de controle sempre por token.

```tsx
<div className="h-[var(--rc-control-md)]" />   // acompanha a densidade
<div className="h-10" />                        // não acompanha
```

Compacta é para tela de operação, onde caber mais linha vale mais do que o
respiro. Não use em cadastro nem em formulário longo.

## Estreito primeiro

Escreva a versão de celular e acrescente `sm:` e `lg:` por cima. O contrário
gera layout que "desmonta" ao encolher, porque o caso estreito nunca foi
pensado.

Cortes que a biblioteca já usa, e que vale acompanhar:

| Corte | O que muda |
|---|---|
| `sm` (640px) | a folha encosta embaixo, a barra lateral vira folha, o calendário mostra um mês |
| `lg` (1024px) | a segunda coluna aparece |
| `xl` (1280px) | o painel abre para três ou quatro colunas |

Quando a decisão não couber em classe, leia o mesmo corte que os componentes
leem, com `useMobile()`, em vez de escrever `640` de novo.

**O que é sobreposição decide pela janela; o que mora no fluxo pode decidir
pelo contêiner.** Folha, menu, diálogo e aviso cobrem a tela, então o celular é
a janela. Peça que vive dentro de `Card` ou de painel de `Splitter` decide pela
própria largura: o `Splitter`, o `ResizablePanelGroup` com `stackOnNarrow`, o
`Banner` e o `CookieConsent` (que tem `contained` para morar dentro de uma
caixa) já fazem isso. Na sua composição, `@container` no pai e
`@max-[40rem]:` no filho, em vez de `max-sm:`, quando a área é um painel.

No telefone, três coisas mudam de lugar:

- **Detalhe e filtro vão numa folha de baixo**: o `Sheet` sem `side` já sobe de
  baixo no telefone e entra pela direita na mesa; na mesa, `size` (`sm`, `md`,
  `lg`, `full`) dá a largura que o detalhe pede. O `Select`, o `Combobox`, o
  `Autocomplete`, o `Menu` e o painel do `NavigationMenu` também abrem em folha
  de baixo ali, sozinhos.
- **A ação principal desce**: no rodapé do formulário, em largura cheia
  (`w-full sm:w-auto`), onde o polegar alcança.
- **Coluna que não cabe some**, com `hideOnMobile` no `DataTable`, e o que ela
  dizia aparece no detalhe. Para escolher por largura, `showFrom` (`sm`, `md`,
  `lg`, `xl`) diz onde a coluna entra e `hideFrom` onde ela sai: um resumo só
  no celular, as colunas que decidem no tablet, todas na mesa.

## Erros de layout que aparecem sempre

- Item de grid ou de flex sem `min-w-0`, com conteúdo largo dentro.
- `truncate` sem `min-w-0`: promete cortar e empurra.
- Barra de filtros sem `flex-wrap`.
- Altura cravada em controle, quebrando a densidade compacta.
- Gráfico sem altura: `ChartContainer` sem `h-*` some.
- `justify-between` numa fila que tem `gap`: use `ml-auto` no que deve ir para
  a ponta.
- Página inteira com `overflow-hidden` para "resolver" vazamento lateral. Isso
  esconde o sintoma e corta menu e dica junto.
- Espaço vertical resolvido com `<br>` ou `mt-*` solto em vez de `space-y-*` no
  contêiner.
