RivoProvider
import { RivoProvider } from '@rivocode/ui'Quando usar
Raiz obrigatória. Sem ele nada tem estilo.
theme: rivocode-dark (padrão), rivocode-light ou system.
density: comfortable (padrão) ou compact, que encolhe todo controle.
scope: global veste a página inteira; local veste só esta árvore e pinta o
fundo, para quando o design system entra num projeto que já existe.
Carrega por dentro o provedor de dica, a fiação de aviso e o container de portal que leva o tema junto. Não monte nenhum deles à mão.
Os tipos do tema
RivoTheme são os dois temas de casa, rivocode-dark e rivocode-light.
RivoThemeSetting é o que a prop theme aceita: os dois de casa, system, ou
o nome do tema de um cliente. RivoResolvedTheme é o tema depois que system
já virou um dos dois.
A união aceita nome livre de propósito. Sem isso, vestir um cliente terminava
num erro de tipo, e o projeto começava escrevendo as no ponto de entrada do
sistema, que é o pior lugar possível para ensinar que casting é normal.
RivoDensity é comfortable ou compact. Os dois tipos aparecem quando a
escolha vem de fora, de uma preferência salva ou da configuração do cliente:
const [theme, setTheme] = useState<RivoThemeSetting>('system')
const density: RivoDensity = usuario.prefereCompacto ? 'compact' : 'comfortable'
<RivoProvider theme={theme} density={density}>
Seguir o sistema com os temas do cliente
system alterna entre os dois temas da casa. Com schemes, alterna entre os
do cliente: o par claro e escuro que o rivocode-ui theme escreve, por
exemplo.
<RivoProvider theme="system" schemes={{ light: 'acme-light', dark: 'acme-dark' }}>
No servidor não há preferência para ler, e o HTML sai com o escuro. Para quem
está no claro não ver o escuro piscar antes da hidratação, ponha o
RivoThemeScript no <head>, com as mesmas theme, schemes e density do
provider. Ele escreve data-rc-theme e data-rc-density no elemento raiz do
documento antes de a página pintar, e o provider, no modo global, lê a
preferência na hora em vez de repetir o palpite do servidor. O elemento raiz do
layout leva suppressHydrationWarning, porque o atributo que o script escreveu
não estava no HTML do servidor:
<head>
<RivoThemeScript theme="system" schemes={{ light: 'acme-light', dark: 'acme-dark' }} />
</head>
<body>
<RivoProvider theme="system" schemes={{ light: 'acme-light', dark: 'acme-dark' }}>
{children}
</RivoProvider>
</body>
Quem monta o <head> sem React usa themeScript({ theme, schemes, density }),
que devolve o mesmo texto do script. Se a página exige nonce em todo script,
passe nonce ao RivoThemeScript. No scope="local" não há script que alcance
o elemento antes da hidratação: o primeiro quadro sai no escuro e troca no
seguinte.
Mais contraste
Quem pede mais contraste no sistema (prefers-contrast: more) recebe, nos dois
temas da casa, borda, borda forte, borda desabilitada, border-hover, texto
secundário e terciário e a linha escolhida mais fortes. Vem no preset, sem prop
nenhuma, e cada papel trocado é medido de novo pelo check:contrast. Tema de
cliente não herda: escreva o seu próprio bloco
@media (prefers-contrast: more) com o mesmo seletor. No React Native o
sinal existe, mas o tema não troca: a seção do nativo, no fim desta página, diz
por quê e o que fazer com useRivo().contrast.
Sentido da escrita
dir="rtl" espelha o que depende de lado: qual seta abre o submenu, para onde o
Select alinha, de onde a folha lateral entra e para onde o gesto de fechar
vai. O provider escreve o dir no elemento raiz e no container de portal, então
o que renderiza em portal também vira.
O layout continua com você, e pelas classes lógicas do Tailwind: ps-* e pe-*
no lugar de pl-* e pr-*, text-start no lugar de text-left. Componente
espelhado dentro de página que ainda mede da esquerda fica pior do que página
inteira sem espelhar nenhum.
Ler o que o provider decidiu
useRivoContext() devolve o tema já resolvido, a densidade e o container de
portal. Serve para a tela que precisa concordar com a escolha (o logotipo que
troca entre claro e escuro, o mapa de terceiro que recebe a cor por prop, o
portal de uma peça de fora que precisa nascer vestida):
const { theme, density, portalContainer } = useRivoContext()
Fora do provider ele lança erro, com o nome do provider na mensagem. É de propósito: o silêncio aqui vira uma tela sem estilo que ninguém sabe explicar.
Quando não usar
Não monte um por tela, nem um em volta de cada peça. Cada RivoProvider traz o
próprio container de portal, e dois com scope="global" disputam o tema que
fica escrito na raiz do documento. Um só, no ponto de entrada.
O aninhado com scope="local" serve para uma área com outra densidade ou outro
tema. Sem theme, ele herda o tema e o schemes do de fora; com theme, usa o
dele. Ele não monta região de avisos própria: o useToast de dentro empurra
para a fila do provider de cima, e o toastPosition e o toastLabels só valem
lá. O aviso, porém, sai vestido com o tema e a densidade do provider de onde
ele foi disparado, e não com os do de cima: a área clara dentro da página
escura avisa em claro. Em desenvolvimento, um theme que nenhuma folha carregada define (o
"dark" no lugar de "rivocode-dark", o tema de cliente sem o CSS dele) avisa
no console.
Para saber o tema ou a densidade de dentro de uma tela, a resposta é o
useRivoContext, e não um provider novo. O scope="local" existe para quando
o design system entra num projeto que já existe e não pode vazar para o resto
da página.
No React Native
Traduz, e ganha uma prop que no web não existe: fonts. No navegador as três famílias chegam pelo CSS de tokens; no celular não há CSS de fonte, e carregar arquivo de fonte é decisão do app, não da biblioteca. O app carrega com o expo-font e declara os nomes uma vez (<RivoProvider fonts={{ sans: 'Manrope', display: 'Poppins', mono: 'JetBrainsMono', script: 'DancingScript' }}>), e o catálogo inteiro passa a vesti-los. Passe junto o isFontLoaded={isLoaded} do expo-font: nome de fonte ausente falha calado no React Native, e é esse retorno que faz o provider avisar em __DEV__.
Declare a sans: sem ela, iOS e Android não saem iguais. A fonte do sistema é a SF Pro num e a Roboto no outro, com larguras diferentes, e a mesma tela quebra linha em pontos diferentes. display cai na sans quando falta. mono e script caem na letra de cada sistema (Menlo e Snell Roundhand no iOS, monospace e cursive no Android), para o código continuar de largura fixa e o nome continuar cursivo: declare as duas para saírem iguais. Em __DEV__ o provider avisa uma vez quando a sans falta, e a mono e a script avisam quando alguma peça pede por elas. A da casa é a Manrope, a mesma --rc-font-sans do web.
Com fonte própria, registre um arquivo por peso (400, 500, 600 e 700) no plugin do expo-font, com o peso de cada um. O iOS acha o peso sozinho; o Android, sem o registro, mostra tudo no regular ou num negrito falso, e os títulos saem diferentes nos dois. Fonte variável não serve aqui: o fontWeight não anda pelo eixo dela no Android.
No Expo Go, declare o mapa por peso. Lá não há plugin: a fonte chega pelo useFonts (de @expo-google-fonts/manrope, por exemplo), e cada peso vira uma família com nome próprio. Cada papel de fonts aceita, no lugar do nome, o mapa { 400, 500, 600, 700 }:
<RivoProvider
fonts={{
sans: {
400: 'Manrope_400Regular',
500: 'Manrope_500Medium',
600: 'Manrope_600SemiBold',
700: 'Manrope_700Bold',
},
}}
isFontLoaded={isLoaded}
>
{app}
</RivoProvider>
Com o mapa, o Text e o TextInput escolhem a família pelo peso pedido (o fontWeight do estilo, a classe font-rc-* ou a prop weight, e o do Text de fora quando ele está aninhado) e não põem fontWeight por cima, que no Android desenharia um negrito falso: o iOS e o Android saem iguais. O peso que faltar cai no declarado mais próximo. useRivoFonts() devolve, para cada papel, o nome do 400 (ou do mais próximo dele). O isFontLoaded confere cada nome do mapa, e o aviso diz qual peso não chegou.
density não existe aqui, e não é omissão de paridade. Alvo de toque não encolhe em tela de dedo: comfortable é a única altura, e a prop saiu da API.
E theme troca a tela inteira apenas entre os dois temas de casa. rivocode-dark, rivocode-light e system trocam no mesmo quadro, porque as cores foram compiladas como light-dark() e o provider só gira o esquema do Appearance. Tema de cliente não troca cor de classe nenhuma em runtime: o compilador do react-native-css crava o hex dentro da regra (.bg-accent vira {"backgroundColor":"#d4f34a"}, literal), e nos 56 KB de CSS compilado não sobra uma ocorrência de --. Não existe variável viva para redefinir depois do build.
O mapa de tema saiu do provider. Ele alcançava só quem lê cor por JS - ChartDonut, ChartRadial, o giro do Button, o trilho do Switch -, e saía donut de um tema e botão de outro, lado a lado. Uma metade que discorda da outra é pior do que nenhuma: o provider passou a resolver os 49 papéis lendo o CSS compilado, uma classe bg- por papel, então contexto e classe dizem sempre a mesma cor. A releitura acontece inclusive quando o app declara o esquema dentro de um efeito, depois da montagem - antes disso a paleta era lida uma vez e congelava, e saía meia tela num esquema e meia no outro. Com o mapa sem função, ele foi removido: theme aceita só rivocode-dark, rivocode-light e system, e a prop scheme saiu junto, porque era ela que escolhia o esquema do mapa.
Só o provider de fora manda no esquema. No celular o esquema é um só para o app inteiro, então não existe o scope="local" do web: um RivoProvider dentro de outro herda o tema, o contexto e o useToast do de fora, não monta outra camada de fundo, e só troca as famílias quando recebe fonts. O theme passado ao aninhado é ignorado, com aviso em __DEV__ quando diverge do de fora - antes ele escurecia o app inteiro, porque o padrão rivocode-dark girava o Appearance global. O padrão continua rivocode-dark na raiz, como no web, e a raiz devolve o esquema ao aparelho quando desmonta.
O caminho que funciona é o CSS do app, antes de compilar - e agora ele veste a tela inteira, gráfico incluído: sobrescreva os papéis num @theme do seu global.css, depois do @rivocode/ui-native/theme.css, e rode npx rivocode-ui-native-css de novo. Ele tem um teto de arquitetura: light-dark() tem duas vagas, então são dois temas por build, um claro e um escuro. Um app de um cliente cabe folgado; uma vitrine de cinco temas, como a do web, pede cinco bundles. O guia de temas tem o passo a passo.
Mais contraste chega como sinal, e não como tema. O aparelho diz quando a pessoa pediu mais contraste ("Aumentar contraste" no iOS, "Texto em alto contraste" no Android, prefers-contrast: more no navegador), e o provider entrega isso em useRivo().contrast, que vale "more" ou "standard" e acompanha a troca sem reabrir o app. O que o web faz com o sinal, trocar borda e texto secundário por valores mais fortes, aqui não dá: o compilador do react-native-css não conhece a media query prefers-contrast e não deixa variável viva, então nenhuma classe muda de cor depois do build. Trocar só o que se lê por JS repetiria o mapa que saiu do provider, com metade da tela num contraste e metade no outro. Use o sinal no que a tela desenha: border-border-strong no lugar de border-border, text-fg no lugar de text-fg-muted.
No iOS e no Android. O provider liga o contraste alto pelo ajuste de cada sistema: “Aumentar contraste” no iOS e “Texto em alto contraste” no Android. São ajustes com nome e alcance diferentes; o tema que sai é o mesmo. A barra de abas e o cabeçalho nativos (NativeTabs, a pilha nativa) são desenhados pelo sistema e não saem iguais; para desenho igual, use as Tabs do router com peças da casa.
API
| Prop | Tipo | Padrão |
|---|---|---|
density0.4.0 | RivoDensity | "comfortable" |
dir0.4.0Sentido da escrita. | "ltr" | "rtl" | "ltr" |
schemesO par de temas que o `theme="system"` alterna. | RivoSchemes | sem padrão |
scope0.4.0`global` veste a pagina inteira, para projeto novo. | "global" | "local" | "global" |
theme0.4.0`system` segue a preferencia do sistema operacional. | RivoThemeSetting | sem padrão |
toastLabelsOs textos dos avisos, para trocar o idioma: `dismiss` e o nome do xis de cada aviso, "Fechar aviso" sem ele; `region` e o nome da regiao dos avisos, "Notificações" sem ele. | Partial<ToastLabels> | sem padrão |
toastPosition0.4.0Em que canto os avisos aparecem. | ToastPosition | "bottom-right" |
Além destas, a peça aceita className, style, id e children, repassados ao elemento de baixo.
Esta peça ainda não tem exemplo que roda: a prosa e a tabela de props abaixo são o que existe hoje. É uma lacuna nossa, e não uma característica dela.