Sheet
Folha de baixo
Lateral
Ações presas embaixo
import { Sheet } from '@rivocode/ui'Quando usar
Folha que desliza da borda da tela, com gesto de arrastar.
Compõe com SheetTrigger, SheetContent, SheetTitle, SheetDescription,
SheetHandle, SheetFooter e SheetClose.
side decide de onde ela entra, e o gesto de fechar segue o lado. É a peça de
navegação no celular e o painel de ações onde o polegar alcança. O tipo é
SheetSide, e são três lados: bottom, left e right. Não há top, porque
folha que desce do alto disputa com a barra de status do celular e com todo
cabeçalho fixo.
Sem side, o lado sai da largura: bottom abaixo de 640px, onde a ação
fica ao alcance do polegar, e right acima, ao lado do conteúdo que a folha
detalha. O detalhe de uma consulta ou o filtro de uma listagem não precisa de mais
nada. Passe o lado quando ele não pode mudar: left na navegação, bottom no
painel de ações que é de baixo em toda largura. O SheetHandle é de folha de
baixo, e só desenha nela: na folha lateral ele não renderiza nada, então a
mesma árvore com SheetHandle serve para a folha que é de baixo no celular e
da direita na mesa.
<Sheet open={open} onOpenChange={setOpen}>
<SheetContent>
<SheetTitle>Consulta de 05/08</SheetTitle>
</SheetContent>
</Sheet>
As ações vão no SheetFooter, por último. Ele gruda na borda de baixo
enquanto o conteúdo rola, e a ação fica ao alcance mesmo no detalhe comprido.
Rodapé feito à mão com sticky bottom-0 gruda acima do respiro do painel, e o
que rola aparece na fresta embaixo dele.
<SheetContent>
<SheetTitle>Pedido #1044</SheetTitle>
<DescriptionList>
<DescriptionItem label="Cliente">Marina Albuquerque</DescriptionItem>
<DescriptionItem label="Total">R$ 63,00</DescriptionItem>
</DescriptionList>
<SheetFooter>
<SheetClose render={<Button variant="secondary" />}>Fechar</SheetClose>
<Button>Confirmar pedido</Button>
</SheetFooter>
</SheetContent>
A tarja de fundo clareia junto com o dedo: puxar pela metade mostra metade do que está atrás.
O espaço entre os filhos vai em classNames.content. O className do
SheetContent veste o painel: o fundo, a borda, o respiro. Os filhos moram
numa caixa dentro dele, então flex flex-col gap-6 no className não chega
ao título nem ao formulário, e o título encosta no primeiro campo. O layout dos
filhos vai na caixa deles:
<SheetContent classNames={{ content: 'flex flex-col gap-6' }}>
<SheetTitle>Novo cliente</SheetTitle>
<Field>
<FieldLabel>Nome</FieldLabel>
<Input name="nome" />
</Field>
<SheetFooter>
<Button>Salvar cliente</Button>
</SheetFooter>
</SheetContent>
A largura
size mede a folha de lado: sm 20rem (o padrão), md 28rem, lg 40rem e
full, a janela inteira. As três primeiras param em 85% da janela (90% no
lg), para sobrar a borda da página e o toque de fora que fecha. O tipo é
SheetSize. md serve o detalhe com uma tabela curta ou um formulário de duas
colunas; lg, a ficha que o usuário compara com a lista atrás; full, o
fluxo que toma a tela sem deixar de ser folha.
<Sheet side="right" size="lg">
<SheetContent>
<SheetTitle>Pedido #1044</SheetTitle>
</SheetContent>
</Sheet>
Na folha de baixo a largura já é a da tela, então só o full muda alguma coisa:
ela ocupa a altura inteira em vez de parar em 85%, sem o canto arredondado.
Quando não usar
Para uma decisão curta, use Dialog, e para o que não tem volta,
AlertDialog. A folha é para o detalhe e o trabalho ao lado do conteúdo, e não
para uma pergunta.
Quando lista e detalhe ficam sempre lado a lado, é Splitter, que não cobre
nada. Painel pequeno preso a um botão, como o filtro de dois campos na mesa, é
Popover. E tarefa que ocupa a tela inteira merece página própria.
No React Native
Traduz: só o comportamento de baixo, que já era o modo estreito do web, e por isso sem o size da folha de lado. Sobe deslizando, e sem transição quando o sistema pede para reduzir movimento; com campo dentro, a folha sobe junto com o teclado. title é opcional, com label no lugar quando o Result toma a folha, e scrollable faz o conteúdo rolar com o título parado.
Arrastar para baixo fecha, como no web. O painel segue o dedo e o fundo clareia junto; ao soltar depois de 30% da altura da folha, ou num peteleco rápido, ela chama onOpenChange(false), e antes disso volta para o lugar. Para cima ela não cresce. O arrasto nasce só do puxador e do cabeçalho, e nunca do corpo, para não disputar com a lista que rola dentro dela. Com reduzir movimento o painel não acompanha o dedo, e o arrasto longo fecha do mesmo jeito. Select, Combobox, Menu e os seletores de data ganham o gesto sem prop nenhuma.
swipeToClose={false} desliga o gesto, para quando o topo da folha já tem gesto próprio na vertical. O fundo, o voltar do Android e o gesto de escape do VoiceOver continuam fechando, e o puxador continua sendo desenho, sem foco.
No iOS e no Android. A peça cobre a tela inteira, por cima da barra de status e da de navegação, e mede a área segura do aparelho com o react-native-safe-area-context, o mesmo número nos dois, e não a da tela, que a navegação zera embaixo do cabeçalho. No Android, o voltar do sistema fecha a folha. O iOS não tem voltar: fecha-se pelo fundo, arrastando a folha para baixo ou pelo gesto de escape do VoiceOver.
API
| Prop | Tipo | Padrão |
|---|---|---|
actionsRef0.4.0Uma ref para as ações imperativas. | RefObject<DrawerRootActions | null> | sem padrão |
defaultOpen0.4.0Se a gaveta começa aberta. | boolean | false |
defaultSnapPoint0.4.0O ponto de parada inicial, no modo não controlado. | DrawerSnapPoint | null | sem padrão |
defaultTriggerId0.4.0ID do gatilho ao qual a gaveta está associada. | string | null | sem padrão |
disablePointerDismissal0.4.0Se a gaveta não fecha com o toque de fora. | boolean | false |
handle0.4.0Um identificador que associa a gaveta a um gatilho. | DrawerHandle<unknown> | sem padrão |
modal0.4.0Se a gaveta aberta fica em estado modal. | "trap-focus" | boolean | true |
onOpenChange0.4.0Chamado quando a gaveta abre ou fecha. | ((open: boolean, eventDetails: DrawerRootChangeEventDetails) => void) | sem padrão |
onOpenChangeComplete0.4.0Chamado depois que as animações terminam, quando a gaveta abre ou fecha. | ((open: boolean) => void) | sem padrão |
onSnapPointChange0.4.0Chamado quando o ponto de parada muda. | ((snapPoint: DrawerSnapPoint | null, eventDetails: DrawerRootSnapPointChangeEventDetails) => void) | sem padrão |
open0.4.0Se a gaveta está aberta agora. | boolean | sem padrão |
side0.4.0De onde a folha entra. | SheetSide | sem padrão |
sizeA largura da folha de lado: `sm` 20rem, o padrao, `md` 28rem, `lg` 40rem, todas presas a 85vw (90vw no `lg`) para sobrar a borda da pagina, e `full` a janela inteira. | SheetSize | "sm" |
snapPoint0.4.0O ponto de parada ativo agora. | DrawerSnapPoint | null | sem padrão |
snapPoints0.4.0Os pontos de parada onde a gaveta pode assentar. | DrawerSnapPoint[] | sem padrão |
snapToSequentialPoints0.4.0Desliga o pulo de parada pela velocidade, e a distância do arraste decide o próximo ponto. | boolean | false |
triggerId0.4.0ID do gatilho ao qual a gaveta está associada. | string | null | sem padrão |
Partes
Sheet 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.
SheetClose
/sheet-close.mdFecha a folha de dentro dela. Use render para emprestar o comportamento ao
botão que já existe no rodapé, em vez de somar mais um.
| Prop | Tipo | Padrão |
|---|---|---|
nativeButton0.4.0Se a peça renderiza um `<button>` nativo quando é trocada pela prop `render`. | boolean | true |
render0.4.0Troca o elemento HTML da peça por outra tag, ou a compõe com outro componente. | ComponentRenderFn<HTMLProps, DrawerCloseState> | ReactElement<unknown, string | JSXElementConstructor<any>> | sem padrão |
Além destas, a peça aceita className, style, id e children, repassados ao elemento de baixo.
SheetContent
/sheet-content.mdO painel, com a tarja de fundo e o portal por dentro.
Monta em portal no container do RivoProvider, então o tema vale ali dentro.
Não recebe side: o lado mora na raiz, porque o gesto de fechar tem que
concordar com a direção de onde a folha entrou.
A tarja é irmã do painel dentro do portal, então nem className nem variante de
descendente alcançam ela. Para vestir as duas, use classNames com as partes
backdrop e viewport.
| Prop | Tipo |
|---|---|
classNames0.5.0Classe por parte: `backdrop`, `viewport` e `content`. | Partial<Record<"backdrop" | "content" | "viewport", string>> |
finalFocus0.4.0O elemento que recebe o foco quando a gaveta fecha. | booleanRefObject<HTMLElement | null>((closeType: InteractionType) => void | boolean | HTMLElement | null) |
initialFocus0.4.0O elemento que recebe o foco quando a gaveta abre. | booleanRefObject<HTMLElement | null>((openType: InteractionType) => void | boolean | HTMLElement | null) |
render0.4.0Troca o elemento HTML da peça por outra tag, ou a compõe com outro componente. | ComponentRenderFn<HTMLProps, DrawerPopupState> | ReactElement<unknown, string | JSXElementConstructor<any>> |
Além destas, a peça aceita className, style, id e children, repassados ao elemento de baixo.
SheetDescription
/sheet-description.mdA linha de contexto embaixo do título, ligada ao painel por aria-describedby.
| Prop | Tipo |
|---|---|
render0.4.0Troca o elemento HTML da peça por outra tag, ou a compõe com outro componente. | ComponentRenderFn<HTMLProps, DrawerDescriptionState> | ReactElement<unknown, string | JSXElementConstructor<any>> |
Além destas, a peça aceita className, style, id e children, repassados ao elemento de baixo.
SheetFooter
/sheet-footer.mdA fila de ações da folha, presa na borda de baixo enquanto o conteúdo rola.
Vai por último dentro do SheetContent. O detalhe comprido rola por baixo
dele, e a ação continua ao alcance do polegar sem a pessoa descer até o fim.
Ele encosta na borda de verdade, por cima do respiro do painel e da área do
gesto do celular: o rodapé escrito à mão com sticky bottom-0 gruda acima do
respiro, e o que rola aparece na fresta embaixo dele.
A ação que confirma vai por último na marcação. No celular os botões empilham
em largura cheia e a ordem se inverte, com quem confirma no alto e quem fecha
rente ao polegar: o mesmo comportamento do DialogFooter.
Sem prop própria: repassa ao elemento de baixo o que você mandar.
SheetHandle
/sheet-handle.mdA barrinha de pegar, só na folha de baixo.
É o único aviso de que dá para arrastar. Sem ela o gesto continua existindo e ninguém descobre, e aí a única saída visível é o clique fora, que na folha de baixo fica no meio do conteúdo que a pessoa veio ler.
Sai escondida do leitor de tela: quem navega por teclado fecha com Esc, e uma barra decorativa anunciada só atrapalha.
Sem prop própria: repassa ao elemento de baixo o que você mandar.
SheetTitle
/sheet-title.mdO título da folha, e o nome dela para o leitor de tela.
Folha sem título é um painel que se abre sem dizer o que é: quem usa leitor de
tela ouve só "diálogo". Quando o desenho não comporta título visível, o
aria-label no SheetContent faz o papel.
| Prop | Tipo |
|---|---|
render0.4.0Troca o elemento HTML da peça por outra tag, ou a compõe com outro componente. | ComponentRenderFn<HTMLProps, DrawerTitleState> | ReactElement<unknown, string | JSXElementConstructor<any>> |
Além destas, a peça aceita className, style, id e children, repassados ao elemento de baixo.
SheetTrigger
/sheet-trigger.mdO que abre a folha. Use render para emprestar o gatilho a um Button, em vez
de aninhar um botão dentro de outro.
| Prop | Tipo | Padrão |
|---|---|---|
handle0.4.0Um identificador que associa o gatilho a uma gaveta. | DrawerHandle<Payload> | sem padrão |
nativeButton0.4.0Se a peça renderiza um `<button>` nativo quando é trocada pela prop `render`. | boolean | true |
payload0.4.0Um dado a entregar à gaveta quando ela abre. | Payload | sem padrão |
render0.4.0Troca o elemento HTML da peça por outra tag, ou a compõe com outro componente. | ComponentRenderFn<HTMLProps, DrawerTriggerState> | ReactElement<unknown, string | JSXElementConstructor<any>> | sem padrão |
Além destas, a peça aceita className, style, id e children, repassados ao elemento de baixo.