# AppShell

O esqueleto da aplicação: cabeçalho fixo, barra lateral, conteúdo, e, quando
a tela pede, uma coluna ao lado e um rodapé. É a primeira peça de uma
aplicação nova, e a que dá a cada região o landmark certo sem ninguém
precisar lembrar.

```tsx
<AppShell
  sidebar={
    <SidebarContent>
      <SidebarMenu>
        <SidebarMenuItem href="/projetos" active>Projetos</SidebarMenuItem>
        <SidebarMenuItem href="/equipe">Equipe</SidebarMenuItem>
      </SidebarMenu>
    </SidebarContent>
  }
  header={<SearchInput placeholder="Buscar projetos" />}
  container
>
  <PageHeader title="Projetos" />
</AppShell>
```

## As regiões, e o que o leitor de tela ouve

| Prop       | Sai como                   | Landmark                                   |
| ---------- | -------------------------- | ------------------------------------------ |
| `header`   | `<header>`, fixo no topo   | banner                                     |
| `sidebar`  | `<nav>` dentro do `Sidebar` | navigation, "Navegação principal"         |
| `children` | `<main>`                   | main                                       |
| `aside`    | `<aside>`                  | complementary, "Informações complementares" |
| `footer`   | `<footer>`                 | contentinfo                                |

Cada região só existe quando a prop vem. A `<aside>` que o `Sidebar` desenha
por dentro sai com `role="none"`: a barra lateral é navegação, e anunciá-la
também como complementar daria duas regiões para a mesma coisa.

**O primeiro foco da página é o link "Pular para o conteúdo".** Ele fica
escondido até receber o foco, aparece no canto de cima, e leva o foco ao
`<main>` sem mudar o endereço da página, o que não atrapalha o router. Quem
navega por teclado deixa de atravessar a barra inteira em toda tela nova.

## A barra lateral

`sidebar` recebe o miolo do `Sidebar` da casa (`SidebarHeader`,
`SidebarContent`, `SidebarMenu`, `SidebarFooter`), e a casca monta o resto: o
`SidebarProvider` na raiz, o `Sidebar` com o `<nav>` dentro, e o
`SidebarTrigger` na frente do cabeçalho. Tudo o que a barra já faz continua
valendo: encolhe até a coluna de ícones na mesa, abre e fecha por Ctrl+B, e **no
celular vira a folha** que desliza da borda, fechada ao carregar e fechada de
novo quando a pessoa escolhe um destino.

`defaultOpen`, `open`, `onOpenChange` e `shortcut` vão direto para o
`SidebarProvider`. `sidebarSide="right"` põe a barra do outro lado. O
`useSidebar()` funciona em qualquer lugar dentro da casca.

## O conteúdo

Sem `container`, o conteúdo encosta nas bordas do `<main>`: é o que uma
listagem de ponta a ponta quer. Com `container`, ele vai num `Container` da
casa, com a largura máxima, o respiro lateral e o respiro de cima e de baixo
do painel. `true` usa o `lg`; um tamanho (`sm`, `md`, `xl`, `full`) escolhe
outro.

`aside` fica à direita do conteúdo a partir de `lg`, na largura da barra
lateral, e embaixo do conteúdo antes disso. `footer` fecha a coluna.

## Dentro de uma caixa

A casca ocupa a janela: a barra lateral gruda na altura da tela e a página
rola na janela. `contained` troca a janela pela caixa do pai, e a barra e a
coluna de conteúdo passam a rolar por dentro. É o jeito de montar a casca num
painel, num `Splitter` ou num exemplo de documentação.

Contida, a casca não é a página, e por isso não fala como página: sai sem o
link de pular e sem marco nenhum. O `<main>`, a `<nav>`, o `<header>`, o
`<aside>` e o `<footer>` viram `div`, com o mesmo desenho, porque o marco
principal é da página que a embrulha, e um `main` dentro de outro confunde quem
navega por marcos.

```tsx
<div className="h-[32rem]">
  <AppShell contained sidebar={menu} header={busca}>…</AppShell>
</div>
```

## Partes

`classNames` alcança cada nó pelo nome: `skipLink`, `sidebar`, `column` (a
coluna à direita da barra), `header`, `body` (a linha do conteúdo e da coluna
ao lado), `main`, `aside` e `footer`.

## Textos

`labels` troca o texto do link de pular (`skipLink`) e os nomes que o leitor de
tela anuncia para a navegação (`navigation`) e para a coluna ao lado (`aside`).
`mainId` fixa o `id` do `<main>`, quando outra parte da página precisa apontar
para ele.

## Quando não usar

- **O topo de uma tela** é `PageHeader`. A casca é a aplicação inteira e
  aparece uma vez; o `PageHeader` é o título, a trilha e as ações de cada
  rota, e mora dentro do `children` dela.
- **Só a barra lateral, num layout que você já tem** é o `Sidebar` com o
  `SidebarProvider` e o `SidebarInset`. A casca é o `Sidebar` mais as outras
  regiões; se as outras já existem, ela sobra.
- **Largura de leitura sem esqueleto de aplicação** (página de login,
  formulário público) é `Container`. Ali não há navegação para organizar.
- **Painéis lado a lado que a pessoa redimensiona** é `Splitter`. A `aside`
  da casca tem largura fixa e não se arrasta.

## No React Native

Não porta, por decisão. No celular o esqueleto da aplicação não é desenhado pela biblioteca de componentes: é o router (Expo Router, React Navigation) que monta a tab bar, o drawer, a barra de título de cada tela e a área segura, com o gesto de voltar, o histórico e o estado de cada aba de graça. Uma casca nossa por cima disso seria um segundo esqueleto disputando as mesmas bordas da tela.

O que a casca do web resolve para a acessibilidade também já vem do sistema: o VoiceOver e o TalkBack anunciam a tab bar e o título da tela, e não existe link de pular para quem navega pelo toque. O topo de cada tela continua sendo o `PageHeader`, que traduz.

## Importação

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

## Exemplos

### Aplicação completa

```tsx
import {
  AppShell,
  Badge,
  Button,
  PageHeader,
  SearchInput,
  SidebarBrand,
  SidebarContent,
  SidebarFooter,
  SidebarGroup,
  SidebarHeader,
  SidebarMenu,
  SidebarMenuItem,
} from '@rivocode/ui'
import { FolderKanban, Home, Settings, Users, Waves } from 'lucide-react'

const NAVIGATION = (
  <>
    <SidebarHeader>
      <SidebarBrand mark={<Waves size={18} className="text-accent-text" />}>RivoCode</SidebarBrand>
    </SidebarHeader>
    <SidebarContent>
      <SidebarGroup label="Operação">
        <SidebarMenu>
          <SidebarMenuItem href="#" icon={<Home size={16} />}>
            Painel
          </SidebarMenuItem>
          <SidebarMenuItem
            href="#"
            icon={<FolderKanban size={16} />}
            active
            badge={<Badge size="sm">4</Badge>}
          >
            Projetos
          </SidebarMenuItem>
          <SidebarMenuItem href="#" icon={<Users size={16} />}>
            Equipe
          </SidebarMenuItem>
        </SidebarMenu>
      </SidebarGroup>
    </SidebarContent>
    <SidebarFooter>
      <SidebarMenu>
        <SidebarMenuItem href="#" icon={<Settings size={16} />}>
          Preferências
        </SidebarMenuItem>
      </SidebarMenu>
    </SidebarFooter>
  </>
)

export function Complete() {
  return (
    <div className="h-[32rem] overflow-hidden rounded-lg border border-border">
      <AppShell
        contained
        container="md"
        sidebar={NAVIGATION}
        header={
          <>
            <SearchInput placeholder="Buscar projetos" className="max-w-xs" />
            <Button size="sm" className="ml-auto">
              Novo projeto
            </Button>
          </>
        }
        footer="RivoCode · Gestão de projetos"
      >
        <PageHeader
          titleAs="h2"
          title="Projetos"
          description="Os projetos ativos da equipe, do mais recente para o mais antigo."
        />
        <p className="mt-6 text-sm text-fg-muted">
          Tab a partir do topo da página: o primeiro foco é o link “Pular para o conteúdo”.
        </p>
      </AppShell>
    </div>
  )
}
```

### Com coluna ao lado

```tsx
import {
  AppShell,
  Badge,
  Button,
  PageHeader,
  SearchInput,
  SidebarBrand,
  SidebarContent,
  SidebarFooter,
  SidebarGroup,
  SidebarHeader,
  SidebarMenu,
  SidebarMenuItem,
} from '@rivocode/ui'
import { FolderKanban, Home, Settings, Users, Waves } from 'lucide-react'

export function WithAside() {
  return (
    <div className="h-[28rem] overflow-hidden rounded-lg border border-border">
      <AppShell
        contained
        container
        header={<span className="font-display text-lg text-fg">RivoCode</span>}
        aside={
          <div className="flex flex-col gap-2 text-sm">
            <p className="font-medium text-fg">Resumo do mês</p>
            <p className="text-fg-muted">42 tarefas concluídas, 3 atrasadas.</p>
          </div>
        }
        labels={{ aside: 'Resumo do mês' }}
      >
        <PageHeader titleAs="h2" title="Painel" description="O que aconteceu hoje na conta." />
      </AppShell>
    </div>
  )
}
```

## Props

| Prop | Tipo | Obrigatória | Padrão | Desde | O que faz |
| --- | --- | --- | --- | --- | --- |
| `aside` | `ReactNode` |  |  | - | Coluna ao lado do conteudo: ajuda, resumo, atividade recente. |
| `classNames` | `Partial<Record<"aside" \| "body" \| "column" \| "footer" \| "header" \| "main" \| "sidebar" \| "skipLink", string>>` |  |  | - |  |
| `contained` | `boolean` |  | `false` | - | Ocupa a caixa do pai em vez da janela: a barra lateral e a coluna de conteudo passam a rolar por dentro. |
| `container` | `"full" \| "lg" \| "md" \| "sm" \| "xl" \| boolean` |  |  | - | Poe o conteudo num `Container` da casa, com a largura maxima e o respiro lateral dele e o respiro de cima e de baixo do painel. |
| `defaultOpen` | `boolean` |  |  | - | Comeca aberta na mesa. |
| `footer` | `ReactNode` |  |  | - | O rodape da aplicacao, embaixo do conteudo. |
| `header` | `ReactNode` |  |  | - | O que mora no cabecalho fixo: marca, busca, sininho, menu da conta. |
| `labels` | `Partial<AppShellLabels>` |  |  | - | Os textos do link de pular e os nomes das regioes que o leitor de tela anuncia. |
| `mainId` | `string` |  |  | - | O `id` do `<main>`, alvo do link de pular. |
| `onOpenChange` | `((open: boolean) => void)` |  |  | - | Chamado quando a barra abre ou fecha na mesa. |
| `onOpenMobileChange` | `((open: boolean) => void)` |  |  | - | Chamado quando a folha do celular abre ou fecha. |
| `open` | `boolean` |  |  | - | Aberta na mesa, controlado. |
| `openMobile` | `boolean` |  |  | - | A folha do celular, controlada. |
| `shortcut` | `string \| null` |  |  | - | Atalho de teclado que abre e fecha, com Ctrl ou Cmd. |
| `sidebar` | `ReactNode` |  |  | - | O miolo da barra lateral: `SidebarHeader`, `SidebarContent`, `SidebarFooter` e o resto da familia do `Sidebar`. |
| `sidebarSide` | `"left" \| "right"` |  | `"left"` | - | De que lado mora a barra lateral. |

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

## Ver também

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