Pular para o conteúdo
Fundação

RivoProvider

/componentes/rivo-provider.mdmarkdown cru, para quem lê com agent em vez de olho
Importar
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

PropTipoPadrão
density0.4.0RivoDensity"comfortable"
dir0.4.0

Sentido da escrita.

"ltr" | "rtl""ltr"
schemes

O par de temas que o `theme="system"` alterna.

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

RivoThemeSettingsem padrão
toastLabels

Os 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.0

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

@rivocode/ui, 149 peças no catálogo. Esta página é gerada dos mesmos arquivos que alimentam o design system, então ela não envelhece sozinha.

Feito por RivoCode.