Como construir
O contrato da biblioteca: o Provider, o vocabulário de classes e as regras que valem para toda peça.
/convencoes.mdComo construir com o @rivocode/ui
Biblioteca white-label da RivoCode. Nenhum componente conhece a cor da marca: ele pede um token semantico e o tema responde. Isso e o que permite a mesma peca servir a RivoCode num projeto e outro cliente no seguinte.
Envolva tudo no RivoProvider
Sem ele nada tem estilo, e Dialog, Menu, Select, Tooltip e os avisos
lancam erro, porque leem o contexto dele.
import { RivoProvider, Button } from '@rivocode/ui'
<RivoProvider theme="rivocode-dark" density="comfortable">
<Button>Salvar alteracoes</Button>
</RivoProvider>
theme:rivocode-dark(padrao),rivocode-lightousystem.density:comfortable(padrao) oucompact, para tela de operacao.scope:globalveste a pagina;localveste so esta arvore e pinta o fundo. Em preview e em cartao isolado uselocal, senao o conteudo fica claro sobre claro.
O Provider ja carrega por dentro o provedor de dica, a fiacao de aviso e um container de portal que leva o tema junto. Nao monte nenhum deles a mao.
Dentro do tema, a barra de rolagem de qualquer caixa sai fina e na cor da
borda (--rc-border-strong), clara ou escura com o tema. A regra mora na
camada base, entao uma classe sua vence: [scrollbar-width:none] esconde a
barra, como as abas e o carrossel ja fazem.
O vocabulario, que e o do Tailwind v4
Escreva layout com as mesmas classes que os componentes usam. Nunca escreva
cor literal nem z-index numerico.
| Familia | Classes |
|---|---|
| Superficie | bg-bg, bg-surface, bg-surface-raised, bg-overlay |
| Texto | text-fg, text-fg-muted, text-fg-subtle, text-fg-disabled |
| Acento | bg-accent, text-accent-fg, text-accent-text, bg-accent-subtle |
| Linha e foco | border-border, border-border-strong, ring-ring, e o anel focus-visible:ring-focus com ring-offset-focus, que leem --rc-ring-width e --rc-ring-offset |
| Estado | bg-success, text-success-text, bg-danger-subtle, e o mesmo para warning e info |
| Selecao e carga | bg-selected, bg-skeleton |
| Codigo lido por maquina | fill-code-ink, bg-code-paper, text-code-ink: escuro sobre claro com o mesmo valor em todo tema, e nao sao papel de tema |
| Palco de midia | bg-media-stage, bg-media-control, text-media-fg, text-media-fg-muted, border-media-border, text-media-disabled: escuro nos dois temas com o mesmo valor, e nao sao papel de tema. Sao do ImageViewer em tela cheia e do VideoPlayer |
| Papel da assinatura | bg-signature-paper, fill-signature-ink, text-signature-guide, stroke-signature-guide, text-signature-disabled: tinta escura sobre papel claro nos dois temas, e nao sao papel de tema. Sao do SignaturePad, para a assinatura exportada nao sair invertida |
| Forma | rounded-sm, rounded-md, rounded-lg, rounded-xl, rounded-pill |
| Texto | text-xs a text-3xl, font-sans, font-display, font-mono (só código), tabular-nums (número) |
| Peso | font-rc-regular, font-rc-medium, font-rc-strong, font-rc-bold, font-rc-display |
| Sombra | shadow-1, shadow-2, shadow-3 |
| Empilhamento | z-[var(--rc-z-sticky)], e os pares base, dropdown, overlay, dialog, popover, toast, tooltip |
| Entrada | animate-enter, animate-appear, animate-pop, animate-fill, animate-reveal, animate-draw, animate-draw-late |
Preencher e escrever texto sao tokens diferentes. bg-danger preenche e
recebe text-danger-fg por cima. text-danger-text e o vermelho que se le
sobre o fundo da pagina. Nenhuma cor serve para as duas funcoes. Vale igual
para o acento: bg-accent com text-accent-fg, ou text-accent-text solto.
Sao oito degraus de empilhamento, e os dois das pontas sao seus. Os seis do
meio pertencem as pecas - o Dialog sobe sozinho para o dialog, o Menu para
o dropdown - e voce raramente os escreve. Os que a sua tela escreve sao os
outros dois: --rc-z-base para trazer um elemento de volta ao plano do
conteudo, e --rc-z-sticky para cabecalho, coluna congelada e barra de acao
que gruda ao rolar. Cabecalho grudado com --rc-z-dropdown fica na frente do
menu que ele mesmo abre; e o erro que a falta desta linha ja produziu.
O que abre de dentro de uma camada fica acima dela. Um Select dentro de
um Dialog, um AlertDialog aberto por um botao dentro de um Popover, um
Menu dentro de uma Sheet: cada peca que abre camada le o degrau de quem a
abriu e fica um acima dele - max(<o proprio degrau>, <o de quem abriu> + 1),
sempre em cima dos --rc-z-*. Fora de qualquer camada, cada uma fica no
proprio degrau, como antes. A regra anda pela arvore do React: o flutuante tem
que ser montado DENTRO do conteudo da camada (DialogContent,
PopoverContent, SheetContent...), e nao ao lado dela. O Tour le tambem o
DOM: com o alvo dentro de um Dialog, a mascara sobe acima do dialogo e o
resto dele fica apagado e sem clique. Toast e Tooltip continuam por cima
de tudo.
As pecas entram na montagem, e a moldura nao. O que chega entra - o
grafico se desenha, a barra de progresso enche do zero, o Alert e o
EmptyState sobem 4px esmaecendo, o corpo do DataTable esmaece ao sair do
esqueleto - e o que e layout (Card, PageHeader, Sidebar) fica parado. As
classes de Entrada sao as mesmas que as pecas usam, para o que voce monta por
fora: todas duram um token, zeram com "reduzir movimento", rodam uma vez por
montagem e nao prendem estado depois de acabar. animate-none desliga numa
instancia.
Movimento tem nome de intencao. Duracao: duration-fast, duration-base,
duration-slow. Curva: ease-rc (padrao), ease-rc-enter (o que chega),
ease-rc-exit (o que sai). Mola, com a duracao do mesmo nome:
ease-rc-spatial duration-spatial para posicao e tamanho,
ease-rc-expressive duration-expressive para o mesmo com mais corpo, e
ease-rc-effects duration-effects para cor e opacidade, que nao podem passar do
alvo. Toda duracao zera com "reduzir movimento". Nunca duration-150 nem
ease-[cubic-bezier(...)].
Altura de controle vem da densidade, nunca cravada:
h-[var(--rc-control-md)], com sm e lg disponiveis.
A fonte é papel de tema, e vem em arquivo separado
font-sans, font-display e font-mono saem de --rc-font-sans,
--rc-font-display e --rc-font-mono, e os três são declarados pelo tema,
no mesmo seletor [data-rc-theme="..."] em que as cores estão. Não há valor de
:root por baixo: tema que não declara família fica sem família nenhuma, do
mesmo jeito que tema sem --rc-bg fica sem fundo.
As faces da RivoCode (Manrope, Poppins e JetBrains Mono) não viajam mais
no styles.css. Elas têm entrada própria, e só quem quer a marca a importa:
@import "@rivocode/ui/styles.css";
@import "@rivocode/ui/fonts.css"; /* opcional: as faces da RivoCode */
Para vestir a fonte de um cliente, instale a família dele e aponte os três
tokens no seletor do tema dele, junto com as cores. Sem
@rivocode/ui/fonts.css, nenhum .woff2 da RivoCode é baixado:
@import "@rivocode/ui/styles.css";
@import "@fontsource-variable/inter";
[data-rc-theme="cliente-acme"] {
--rc-font-sans: "Inter Variable", system-ui, sans-serif;
--rc-font-display: "Inter Variable", system-ui, sans-serif;
--rc-font-mono: ui-monospace, SFMono-Regular, monospace;
/* …e os cinquenta papéis de cor. */
}
É assim que dois clientes com fontes diferentes convivem na mesma aplicação:
cada data-rc-theme carrega a sua família, e a troca acontece por seletor,
como a de cor.
O peso também é token, e tem nome de intenção
As peças não escrevem font-medium nem font-semibold: escrevem a intenção, e
o número mora em --rc-weight-*, com o valor da casa em :root e opcional no
tema.
| Classe | Token | Casa | Quando |
|---|---|---|---|
font-rc-regular |
--rc-weight-regular |
400 | corpo |
font-rc-medium |
--rc-weight-medium |
500 | rótulo, botão, aba, cabeçalho de tabela |
font-rc-strong |
--rc-weight-strong |
600 | ênfase forte no corpo |
font-rc-bold |
--rc-weight-bold |
700 | negrito de texto rico, chamada de marketing |
font-rc-display |
--rc-weight-display |
600 | todo texto em font-display |
Na sua tela, use as mesmas quando o texto tem que seguir a fonte do cliente:
font-display font-rc-display num título montado à mão pega o peso que o tema
decidiu, e font-semibold fica cravado em 600 mesmo que a família não o tenha.
O tema que troca a fonte redefine o peso no mesmo seletor:
[data-rc-theme="cliente-acme"] {
--rc-font-display: "Lato", system-ui, sans-serif;
--rc-weight-display: 700;
}
O cn da biblioteca conhece as cinco classes: cn("font-rc-medium", className)
com font-rc-strong no className fica com a segunda, e font-display ao lado
de font-rc-display não se anulam. No React Native as cinco existem com os
mesmos valores, no theme.css do pacote.
Os subcaminhos
Alem do pacote principal, seis familias vivem em subcaminhos e chegam pelo mesmo global:
@rivocode/ui/form,Form,FormField,FormErrorSummary,FormSaveBar,useZodForme os adaptadoresforDate,forValue,forChecked: o nome diz o formato, e não a peça. OFormErrorSummary, primeiro filho doForm, lista no topo os erros do envio com link para cada campo. OFormSaveBar, ultimo filho, e aSaveBarligada aoformState: entra comisDirty, espera comisSubmitting, diz a hora do salvo e cai no erro posto emroot; depois de salvar,form.reset(values). O controle vem por funcao, nao por clonagem do filho:<FormField name="email" label="E-mail" description="Para onde vai a nota"> {(campo) => <Input {...campo} />} </FormField>@rivocode/ui/chart, a Recharts vestida pelo tema.A moldura e o
ChartContainer, que recebe tambem os quatro finais de uma consulta:isLoading,isError,onRetryeempty. A altura e sua, por classe: grafico sem altura definida some.A cor de cada serie vem do
confige vira variavel com o nome da serie:const config = { pagas: { label: "Pagas" } } <ChartContainer config={config} className="h-64"> <LineChart data={dados}> <ChartXAxis dataKey="mes" /> <ChartYAxis format="currencyShort" /> <ChartTooltip content={<ChartTooltipContent config={config} />} /> <Line dataKey="pagas" stroke="var(--color-pagas)" /> </LineChart> </ChartContainer>Peca Para que ChartXAxis,ChartYAxisEixos com o padrao ja certo, e formatpara o numeroChartTooltip,ChartTooltipContentA dica, com o nome do configChartLegend,ChartLegendContentA legenda. Com useSeriesToggleela vira filtroChartAreaGradient,areaGradient(id, serie)Gradiente de area. O ide seu, e precisa ser unico na paginaChartDonutRosca com o total no buraco, e lista de fatias embaixo ChartRadialO arco de uma medida so: meta, cota, conversao ChartGaugeMedidor de 0 a maxcom faixas (bom, atencao, critico) e o valor escrito no meioChartHeatmapGrade de linha por coluna, a cor dizendo o tamanho: emissoes por dia e hora ChartFunnelAs etapas de um caminho, com a taxa de conversao de uma para a seguinte ChartTreemapArea proporcional por categoria, com o rotulo que some quando nao cabe SparklineA linha miuda que cabe dentro de um indicador O
ChartContainercuida do movimento sozinho: toda marca que anima (Line,Bar,Area,Pie,Radar,RadialBar,Scatter) sai comanimationDurationde--rc-duration-slow,animationEasingde--rc-easeeisAnimationActiveligado antes de a marca montar, e desligado com "reduzir movimento". Na primeira vez que aparece com dados, o grafico se desenha, e quando o dado muda cada marca anda ate o valor novo. Marca comisAnimationActive={false}fica parada. OuseChartMotion()devolve o mesmo trio para quem desenha com a Recharts fora da moldura:const movimento = useChartMotion() <Line dataKey="pagas" stroke="var(--color-pagas)" {...movimento} />A
ChartDonute aChartRadialentram varrendo do zero e andam ate o valor novo do mesmo jeito; aSparklineso esmaece ao entrar, e nao anda na troca de dados, porque aparece as dezenas numa tabela.As quatro de baixo nao usam a Recharts e nao entram no
ChartContainer: os quatro finais de uma consulta vem doQueryBoundaryem volta delas. A escala doChartHeatmape uma cor de serie so, em cinco degraus de tinta; oChartTreemapescreve o rotulo emfgsobre a cor da categoria a 30%, par que a guarda de contraste mede nas oito series; e oChartGaugepinta as faixas com os papeissuccess-text,warning-textedanger-text. Nenhuma das quatro depende de cor sozinha: o numero esta na dica, numa tabela ou lista escondida da vista, ou escrito na tela.Os formatadores do eixo e da dica sao os mesmos do resto da biblioteca, e estao logo abaixo.
As pecas da Recharts que saem por aqui:
Area,AreaChart,Bar,BarChart,Line,LineChart,Pie,PieChart,Cell,Scatter,ScatterChart,Radar,RadarChart,RadialBar,RadialBarChart,PolarGrid,PolarAngleAxis,PolarRadiusAxis,CartesianGrid,XAxis,YAxis,ZAxis,LabelList,Rectangle,ReferenceLineeReferenceArea. OTooltipe oLegenddela nao: os nossos ja embrulham os dois, e o nome colidiria com oTooltipdo catalogo.
Paleta de serie: oito cores por tema, em var(--rc-chart-1) a
var(--rc-chart-8), mais var(--rc-chart-grid) para a grade. Aqui a variavel
vem antes da classe de propriedade: a folha que voce recebe e a compilada, e
uma classe utilitaria que nenhum componente usa nao existe nela. A variavel
sempre resolve.
@rivocode/ui/ai, as pecas de conversa com um assistente. Nao tem peer nenhum: ele e subcaminho pelo PESO, porque so app que conversa com um modelo precisa delas, e nao cobra de quem monta nota fiscal. Nenhuma conhece SDK de IA: a mensagem entra por prop, e o que a pessoa faz sai por evento. Quem fala com o modelo e a sua tela, com o SDK que ela ja usa.import { Conversation, Message, MessageMedia, PromptInput, ToolCall, AILabel, ShimmerText } from '@rivocode/ui/ai' <div className="flex h-[32rem] flex-col gap-3"> <Conversation className="flex-1" empty={vazio} onSuggestion={enviar}> {mensagens.map((m) => ( <Message key={m.id} role={m.role} streaming={m.streaming} copyValue={m.texto}> {m.texto} </Message> ))} </Conversation> <PromptInput streaming={respondendo} onSubmit={enviar} onStop={parar} /> </div>Peca Para que PromptInputO campo: cresce com o texto, Enter envia, Shift+Enter quebra a linha, e em streamingo enviar vira parar (onStop).dictationliga o microfone da Web Speech API, so onde ela existe; no nativo o ditado e do tecladoMessageUm turno: roleuser,assistantousystemdecide o desenho;streaminganunciaaria-busye esconde copiar e tentar de novo.replyTodesenha a citacao no topo do balao,onReplyliga o responder (no nativo, arrastar o balao para a direita). CommessageIddentro daConversation, tocar na citacao leva ate a original e a destaca;contextMenuabre as acoes ligadas no botao direito, so no webMessageMediaA foto ou o video no balao, na proporcao da midia; o video e miniatura com play e duracao, e o toque chama onOpen.kind="document"e o cartao do arquivo (icone do tipo,name, tipo esize, Baixar a direita) ekind="location"o cartao do lugar (name,address,onOpenabre o mapa,renderMapopcional). Filho direto daMessage, leva a hora por cima da foto e do video sem legenda, embaixo do cartao, e depois da legenda com elaConversationA lista rolavel: gruda no fim enquanto o texto chega, solta quando a pessoa rola para cima, e e role="log"educado.actionsRefrecebeConversationActions, oscrollToMessage(id)que leva ate aMessagede mesmomessageId(no nativo, a chave dokeyExtractor)ToolCallA chamada de ferramenta: cinco estados com icone e texto, entrada e saida no CodeBlock, e aprovar e recusar emapprovalAILabelO selo "IA" do conteudo gerado, com explicacao opcional num painel. aiLabelVariantssai junto, para quem precisa da classeShimmerTextA frase de espera que brilha ("Pensando…"): gradiente de fg-mutedafgrecortado na letra, parado emfg-mutedcom movimento reduzido. AMessageemstreamingsem conteudo ja a usaA altura da
Conversatione sua, por classe, como a do grafico: sem ela a conversa cresce e empurra a pagina.@rivocode/ui/dnd, arrastar e soltar. Peer opcional:@dnd-kit/coree@dnd-kit/sortable, instalados por quem importa este caminho, e por mais ninguem.npm install @dnd-kit/core @dnd-kit/sortableimport { Kanban, SortableList } from '@rivocode/ui/dnd' <SortableList items={notas} getKey={(nota) => nota.id} getLabel={(nota) => `Nota ${nota.numero}`} onReorder={setNotas} renderItem={(nota) => nota.cliente} />Peca Para que SortableListA lista que a pessoa ordena a mao: alca com o icone de pegar, vertical ou horizontal, e handle={false}comhandlePropspara a alca ser suaKanbanO quadro de colunas: cartao entre colunas e dentro delas, contagem, limitque avisa e nao tranca, coluna vazia que recebeAs duas sao controladas. A ordem nova sai pronta em
onReorder, e a mudanca do quadro sai emonMove({ itemId, from, to, index }); quem trocaitemsoucolumnse a sua tela. Sem trocar, o item volta ao lugar.O teclado nao e opcional: Espaco pega, setas movem, Espaco solta, Esc cancela, e cada passo e anunciado em portugues ("Item Nota 1043 movido para a posicao 3 de 8").
getLabelda o nome que o anuncio fala, elabelstroca qualquer frase. Os vizinhos andam com a mola espacial dos tokens, e com "reduzir movimento" trocam de lugar sem deslizar.@rivocode/ui/editor, o texto com formatacao, sobre o Tiptap 3. Os peers sao OPCIONAIS e so este caminho os cobra:@tiptap/react,@tiptap/pm,@tiptap/core,@tiptap/starter-kite@tiptap/extensions.import { RichTextEditor, RichTextView } from '@rivocode/ui/editor' <Field> <FieldLabel>Descrição do serviço</FieldLabel> <RichTextEditor value={html} onValueChange={setHtml} maxLength={2000} /> </Field> <RichTextView value={nota.descricao} empty="Sem descrição." />Peca Para que RichTextEditorO campo: barra de ferramentas com setas e aria-pressed, atalhos, link com painel,valueem HTML eonJsonChangeopcional,maxLengthcom contador, eeditorRefcom oRichTextEditorHandle(insertText,insertContent,focus) para escrever no cursor por fora. O editor em branco entrega"", e no formulario o adaptador e oforValuemais oonBlurRichTextViewExibe o HTML ou o JSON salvo com a mesma tipografia, sem innerHTMLe sem o Tiptap: so os blocos e marcas do editor, e link sohttp,https,mailto,telou relativohtmlToRichTextJsonConverte o HTML salvo no JSON do Tiptap, pelo mesmo leitor do RichTextView: sem o Tiptap e sem DOM, com o mesmo recorte seguroO editor nao monta no servidor (
immediatelyRender: false): no lugar dele sai o conteudo ja formatado, e ele vira editavel quando o JavaScript chega. O HTML que chega ao servidor e entrada de usuario como qualquer outra; exibido por outro caminho que nao oRichTextView, passe por sanitizador.@rivocode/ui/illustrations, os desenhos das telas de erro e de vazio. Nao tem peer; e caminho proprio pelo peso. Um desenho por situacao, e nao um por tela, todos pintados comvar(--rc-*): recolorem com o tema de cliente sem prop nenhuma.import { NotFound } from '@rivocode/ui/illustrations' <Result titleAs="h1" illustration={<NotFound size="lg" />} title="Não achamos esta página" description="O endereço pode ter mudado." actions={<Button>Voltar ao início</Button>} />Peca Situacao NotFoundO endereco ou o registro nao existe (404) ForbiddenO perfil nao ve esta tela (403) ServerErrorAlgo falhou do nosso lado (500) OfflineSem conexao, ou o servidor nao responde MaintenanceParado de proposito, com hora para voltar EmptyListPrimeiro uso, nada criado ainda NoResultsBusca ou filtro sem resultado EmptyInboxNotificacoes ou mensagens, tudo lido NoDataGrafico ou relatorio sem dado no periodo Illustrationrecebe oname(not-found,server-error...) quando a situacao chega como dado, eILLUSTRATION_NAMESlista os nove.sizeesm(96px, cartao),md(160px, o padrao) oulg(240px, so a pagina inteira). O desenho e decorativo (aria-hidden): quem diz o que houve e o que fazer e o titulo doResultou doEmptyStateque o recebe. A pagina de erro e oResultcomillustration, e nao uma peca a parte. Cada desenho toca uma cena curta ao montar, uma vez e em menos de 2,5 s (classesanimate-illustration-*); com reduzir movimento nasce no quadro final, eanimated={false}desliga.@rivocode/ui/audio, o player de audio com forma de onda e o gravador. Nao tem peer; e caminho proprio pelo peso, como o/ai: so app que toca ou grava mensagem de voz, gravacao ou aula precisa dele.import { AudioPlayer, audioPeaks } from '@rivocode/ui/audio' <AudioPlayer src={url} peaks={picos} duration={segundos} aria-label="Mensagem de voz de Ana" />Peca Para que AudioPlayerTocar e pausar, a onda que se enche, a busca ( role="slider", setas de 5 s, tempo por extenso noaria-valuetext), o tempo atual e o total, a velocidade (1x, 1,5x, 2x). Carregando recusa o segundo toque e e anunciado; o erro troca o tocar por "Tentar de novo" e volta a posicaoAudioRecorderGrava pelo MediaRecordervendo o nivel do microfone e o tempo: pedir permissao (carregando que recusa o segundo toque), gravar, pausar, parar, descartar, e a revisao numAudioPlayer.onCompleteentrega{ blob, mimeType, duration, peaks }: mande aduratione ospeaksjunto do arquivo. Com reduzir movimento, o medidor vira cinco degraus parados. O seletor de microfone e seu:onInputsChangeentrega a lista, edeviceIdescolheaudioPeaksCalcula os picos de um Blob,ArrayBufferou endereco, de 0 a 1. Baixa e decodifica o arquivo INTEIRO (a 8 kHz, uns 4 MB por minuto em estereo): calcule uma vez e guarde os numeros com a mensagemuseAudioSequenceO grupo de audios de uma conversa: passe o mesmo sequencea cadaAudioPlayer. Toca um por vez (tocar um pausa o outro) e, quando um termina, o seguinte abaixo dele na tela toca sozinho;useAudioSequence({ continuous: false })deixa so o um por vezSem
peaks, a busca e uma barra. A peca embrulha um<audio>e le dele o estado: nao haplayingpara guardar. Numa lista de mensagens, de a cada player o seuaria-label. O audio que a pessoa ainda nao ouviu levaunheard: um ponto de acento ao lado da duracao, falado "Não ouvido", que some no primeiro toque; oonHeardavisa uma vez, para o app gravar.const sequence = useAudioSequence() {audios.map((m) => ( <AudioPlayer key={m.id} src={m.url} sequence={sequence} unheard={!m.ouvido} onHeard={() => marcarOuvido(m.id)} /> ))}@rivocode/ui/mascot, o Bacalhau, mascote da RivoCode. Nao tem peer; e caminho proprio pelo peso (o desenho inteiro e dado, uns 15 KB em gzip), e a paleta e os quadros das animacoes viajam com ele, e nao nastyles.css.import { Bacalhau, BacalhauPeek } from '@rivocode/ui/mascot' <Bacalhau pose="celebrating" motion="bounce" confetti /> <BacalhauPeek hat="season" />Nome Para que BacalhauO mascote inteiro: pose(47),hat,motion,confetti,size(xs40 axl224 de altura),label. As partes da pose se mexem sozinhas (animated), e o que repete para em 5 s, a nao ser comloopBacalhauPeekEle espiando por cima de uma borda, so cabeca e maos: sobe com cautela ao montar, olha em volta, flutua e pisca. happy,hat,size(sm90,md144,lg198 de largura)MASCOT_POSESAs 36 poses, na ordem da galeria MASCOT_HATSparty,straw,santaenewyear;hat="season"escolhe pela dataMASCOT_MOTIONSbreathe,bounce,shake,swim,hopeflip, o movimento do corpo inteiroseasonHatO chapeu da data: Carnaval pela Pascoa, junho, 1 a 25/12 e 26/12 a 1/1; fora delas, nenhum Um por vez na tela. O desenho e decorativo (
aria-hidden) ate ganharlabel. As cores sao da marca e nao mudam com o tema; tela de erro no produto de um cliente e aIllustration, que muda. Com reduzir movimento, tudo nasce parado e o confete nao sai.@rivocode/ui/pure, o que nao desenha nada, sem React. Nao tem peer, e a promessa e o contrario das outras portas: o grafo inteiro a partir dele nao alcanca modulo de fora (ocheck:chartcobra). E o caminho do servidor, da rota da API e do teste que so confere um documento. Os nomes sao os mesmos da raiz, que continua exportando todos.import { isValidCnpj, buildPixPayload, currency } from '@rivocode/ui/pure'Nome Para que buildPixPayload,parsePixPayloadMontar e ler o Pix copia e cola, com o CRC isValidPixKey,normalizePixKeyConferir a chave Pix como a pessoa digita, e a forma que se grava isValidCpf,isValidCnpj,isValidCpfOrCnpjO digito verificador, com o CNPJ alfanumerico e a mascara aceitos isValidCnh,isValidVoterId,isValidPis,isValidRenavam,isValidPlateOs outros documentos isValidBoletoLine,boletoLineToBarcode,parseBoletoA linha digitavel do boleto matchesSearchA busca sem acento e sem caixa, a mesma regra do Highlightcurrency,currencyShort,currencyShortWords,compact,compactWords,integer,percent,monthShort,dayMonth,formattersOs formatadores de numero, dinheiro e data No nativo,
@rivocode/ui-native/puretem os mesmos nomes, e e o que obun testimporta sem carregar oreact-native.@rivocode/ui/theme, a derivacao do tema em tempo de execucao, para a marca que chega do banco e nao de um arquivo. E a mesma conta dorivocode-ui theme, e por isso fica fora da raiz: leva a conta de contraste e as tabelas de sementes, uns 15 KB em gzip que quem so usa as pecas nao baixa.import { checkTheme, deriveTheme, themeCss } from '@rivocode/ui/theme' const tema = deriveTheme({ bg, surface, fg, accent, success, warning, danger, info }) if (tema.failures.length > 0) avisarQueAMarcaNaoPassa(tema.failures) <style>{themeCss(tema)}</style> <RivoProvider theme={tema.base}>...</RivoProvider>Nome Para que deriveThemeDas oito sementes (e de qualquer outro papel escrito, sem o --rc-) deriva todos os papeis de cor e anda na luminosidade OKLCH o derivado que reprova. Devolvescheme,base(o tema da casa do mesmo esquema, que da fonte e sombra),vars(--rc-*com a cor final),fixesefailures: o par que sobra e semente escrita, e a peca nao muda a cor da marca calada. Semente que nao e cor cheia lanca errothemeCssO bloco CSS do tema. Sem seletor, veste por cima de [data-rc-theme="<base>"], com especificidade acima da folha da casa: o provider fica comtheme={tema.base}e o portal sai vestido juntocheckThemeMede varsja resolvidas, as de outro lugar:{ ok, failures }, uma linha por par reprovadoOs
varstambem servem nostylede uma caixa, para a previa de uma marca dentro da pagina; ali o portal (dialogo, menu, aviso) nao herda, porque mora fora da caixa.
Formatar o numero
Um vocabulario so, para o eixo, a dica, o indicador, a celula da tabela e o rotulo de um controle. Eles nasceram no subcaminho do grafico e saem hoje tambem pela raiz, porque formatar dinheiro numa celula nunca foi assunto de grafico:
import { currencyShort, percent, formatters } from '@rivocode/ui'
| Formatador | Escreve |
|---|---|
currency |
R$ 2.480,00 |
currencyShort |
R$ 2,5K |
currencyShortWords |
R$ 2,5 mil |
compact |
12,4K |
compactWords |
12,4 mil |
integer |
1.240 |
percent |
62%, do numero como ele esta no dado |
monthShort |
mar |
dayMonth |
12/03 |
compact abrevia com simbolo, que e a convencao de painel e cabe em menos
pixel. compactWords e currencyShortWords escrevem por extenso, que le melhor
em texto corrido. Nao misture as duas na mesma tela.
Dinheiro sai abreviado. Use currencyShort em indicador, tabela, eixo,
legenda e dica. O currency, que escreve por extenso, fica para o lugar onde o
centavo e o assunto: o valor que a pessoa confirma antes de emitir, e o
comprovante depois.
A prop format aceita o nome de um deles, ou uma funcao sua. Ela existe no
Meter, no Progress, no Slider, no ChartXAxis, no ChartYAxis e no
ChartDonut - o tipo e Format, e FormatName e so o nome. O objeto
formatters reune os nove, para quem monta a escolha em runtime. O
@rivocode/ui-native exporta os mesmos nove pela raiz, do mesmo arquivo, e o
format vale igual no Meter, no Progress, no Slider, no ChartDonut e no
deltaFormat do Stat de la:
<Meter value={72} format="percent" />
<ChartYAxis format="currencyShort" />
<Slider defaultValue={25} max={50} format={(valor) => `${valor} dias`} />
Data e mascara tem as suas, pelo mesmo motivo: formatDate, parseDate e
applyDateMask para dd/mm/aaaa, e applyMask, applyPattern,
applyCurrencyMask, unmask, toCents e phonePatternFor para os moldes de
MASKS. Formatar CPF numa celula de tabela nao precisa de um campo por perto.
isValidCpf e isValidCnpj conferem os digitos verificadores, com ou sem
pontuacao e com o CNPJ alfanumerico. isValidCnh, isValidVoterId (titulo de
eleitor), isValidPis (PIS, PASEP, NIT e NIS), isValidRenavam (o de 9 digitos
continua valendo) e isValidPlate (a antiga e a Mercosul) seguem o mesmo
molde: texto com ou sem pontuacao, true ou false, e nenhuma consulta a
cadastro. Todas existem tambem no nativo, pela mesma conta, e o guia
"Documentos brasileiros" do site diz o que cada uma confere.
O Pix tem as tres dele, nos dois pacotes e pela raiz: buildPixPayload monta
o copia e cola estatico no padrao BR Code do Banco Central, com o CRC16 no fim;
parsePixPayload le de volta e devolve null quando o CRC nao confere; e
isValidPixKey confere a chave como o DICT a guarda (CPF e CNPJ sem
pontuacao, e-mail em minusculas, celular com +55, chave aleatoria com os
hifens). O desenho e o PixCode.
Dinheiro digitado e o CurrencyInput: value e onValueChange em centavos
inteiros (number | null, vazio e null), min e max em centavos que so
marcam invalido, allowNegative e name que poe os centavos num campo
escondido. No FormField, {...forValue(field)}. O nativo tem o mesmo nome,
controlado.
Assinatura na tela e o SignaturePad: value e onValueChange com
SignatureValue | null (os tracos em kind: "drawn", ou o nome digitado em
kind: "typed"), vazio e null, e onValueChange chega ao fim de cada traco.
O modo de digitar o nome e a alternativa de quem nao desenha, e nao se desliga.
signatureToSvg e signatureToPng exportam com a tinta fixa, e
isSignatureEmpty responde se ha assinatura. No FormField,
{...forValue(field)}. No nativo mora em @rivocode/ui-native/chart, pelo
react-native-svg, e exporta so o SVG.
O boleto tem tres: isValidBoletoLine confere a linha digitavel inteira - a de
banco, de 47 digitos, com os tres campos no modulo 10 e o verificador geral no
11, e a de convenio, de 48 e comecando com 8, no modulo que a terceira casa
pede -, boletoLineToBarcode devolve os 44 digitos do codigo de barras ou
null, e parseBoleto devolve BoletoData (kind, bank, amount em
centavos, dueDate, segment, line e barcode) ou null. Ele aceita
tambem os 44 digitos do leitor otico. O fator de vencimento voltou a 1000 em
22/02/2025, e o mesmo fator serve a duas datas: parseBoleto escolhe a mais
perto de hoje, e { today } fixa o dia de referencia. MASKS ganha o molde
boleto, que troca para o de convenio quando o primeiro digito e 8, e o
MaskedInput nativo aceita o mesmo nome.
O que o CSS nao alcanca
useMobile() e verdadeiro abaixo do sm do Tailwind, no mesmo corte que a
barra lateral usa para virar folha e o calendario para mostrar um mes so. Ele
existe exportado para a aplicacao decidir junto, em vez de escrever o proprio
640 num canto: quando cada tela guarda o seu numero, uma delas muda e as duas
metades passam a discordar sobre o que e celular.
const isMobile = useMobile()
return isMobile ? <Sheet>{filtros}</Sheet> : <aside>{filtros}</aside>
useMediaQuery(query) e o geral, para qualquer outra pergunta que so o JS
responde. Layout continua sendo trabalho de classe utilitaria: trocar
grid-cols-3 por grid-cols-1 e assunto de sm:, e nao de hook. O hook e para
o que muda de peca, e nao de tamanho. No servidor ele devolve false, e nao um
palpite.
Dentro de um SidebarProvider, prefira useSidebar().isMobile: e o mesmo
valor, e evita um segundo assinante da mesma media query.
Hooks utilitarios
A raiz exporta os hooks que toda tela reescreve, sem dependencia nova. Antes de
escrever useEffect com setTimeout, addEventListener ou localStorage,
procure aqui. Todos limpam timer, escuta e observer no desmonte, e todos
renderizam no servidor sem tocar em window.
- Estado:
useDisclosure([aberto, { open, close, toggle }]),useToggle,useCounter(piso, teto, passo),useListState(append,prepend,insert,remove,reorder,swap,replace,update,filter, todos imutaveis),useSetState(mescla o parcial),usePrevious(o valor anterior DIFERENTE). - Tempo:
useDebouncedValue,useDebouncedCallback,useThrottledCallback(comcancel,flush,isPending; o desmonte cancela o pendente, e{ flushOnUnmount: true }o dispara, que é o que o salvar automático pede),useIntervaleuseTimeout(atrasonullpausa),useIdle. - Navegador:
useLocalStorageeuseSessionStorage(JSON, padrao no servidor, sincroniza entre abas pelo eventostorage, cai para memoria se o armazenamento lancar),useClickOutside,useHotkeys(mode Cmd no Mac e Ctrl fora; ignora campo de texto por padrao),useInfiniteScroll(sentinela,hasMore,loading),useIntersection,useElementSize,useClipboard(copiedvolta sozinho),useReducedMotion,useDocumentTitle,useNetworkStatus,useMounted,useIsFirstRender,useUnsavedChanges(beforeunloadenquanto ha mudanca, e oconfirmLeave(leave)para a navegacao do app; comprompt: "dialog"eblocker(ouseBlockerdo React Router ou do TanStack Router) devolveblocked,proceed,resetelabelspara oAlertDialog; no nativo,preventRemove: usePreventRemoveno Expo Router (o native stack nao emitebeforeRemove), obeforeRemoveda navegacao no stack em JavaScript ou o voltar do Android comonLeave, e a pergunta e SEMPRE oAlertDialogda casa: a tela o renderiza comopen={blocked}).
const [query, setQuery] = useState('')
const [settled] = useDebouncedValue(query, 300)
const [opened, { open, close }] = useDisclosure()
A peca vem antes do hook: Popover, Menu, Dialog e Sheet ja fecham no
clique fora, e o Clipboard ja e o botao de copiar. useFocusTrap nao existe
de proposito: a Base UI prende o foco nas sobreposicoes modais.
No nativo, a raiz exporta os doze que nao dependem do navegador, gerados da
mesma fonte do web: useDisclosure, useToggle, useCounter, useListState,
useSetState, usePrevious, useIsFirstRender, useDebouncedValue,
useDebouncedCallback, useThrottledCallback, useInterval e useTimeout.
O pacote nativo, e os subcaminhos dele
@rivocode/ui-native é o mesmo catálogo em React Native, publicado como
fonte: o vocabulário de classes acima é o mesmo, via NativeWind, sobre os
mesmos tokens. O que atravessa é a classe, o token e a escolha da peça: o
JSX se reescreve. No nativo tudo é controlado (sem defaultValue, sem
defaultChecked, sem defaultOpen; a exceção é Accordion e Collapsible,
que aceitam os dois modos) e a lista vem por items, e não por
composição: <Select items={…} value onValueChange label />, sem
SelectTrigger nem SelectItem.
A classe atravessa com o mesmo endereço. className veste a raiz, e a
peça nativa que aceita classNames usa as mesmas chaves da seção "Partes" da
página web: <Banner classNames={{ title: 'font-rc-strong' }} /> se escreve
igual nos dois pacotes, e a classe de quem usa vence a da peça. Parte que o
nativo não desenha fica fora do tipo, e não vira nó inventado (o pause do
Carousel, sem autoplay; o code do QRCode, que é Svg e não recebe
classe). No React Native a cor de texto não desce de View para Text: para
pintar texto, vista a parte que é o próprio texto. Não há prop
<parte>ClassName em nenhum dos dois pacotes: onde o web compõe peças e o
nativo desenha uma só, as peças viram partes (<InputGroup classNames={{ prefix }} />, <Menu classNames={{ trigger }} />). A exceção é o
contentContainerClassName do ScrollArea nativo, nome que a ScrollView já
dá ao conteúdo que rola.
A raiz cobra oito peers, e dois deles são os ícones. react,
react-native, nativewind, react-native-reanimated,
react-native-keyboard-controller, react-native-safe-area-context,
react-native-svg e lucide-react-native entram em todo app, pela linha que o
npx rivocode-ui-native-init imprime. O da área segura é o que deixa o
Sheet, o Dialog, o AlertDialog, o ImageViewer, o Tour e o toast
medirem o relógio e o indicador de início, em vez de adivinhar um número por
sistema; o SafeAreaProvider mora acima do RivoProvider (o expo-router já
monta um). Elas abrem num Modal, que cobre a janela, e medem a área do
aparelho que o RivoProvider da raiz guardou, e não a da tela: dentro de uma
tela com cabeçalho, a navegação zera a faixa que o cabeçalho cobre, e um
useSafeAreaInsets() ali mede top: 0. Acima de todo SafeAreaProvider, o
provider usa a medida do aparelho ao abrir o app (initialWindowMetrics):
npx expo install nativewind@preview react-native-css@rc react-native-reanimated react-native-keyboard-controller react-native-safe-area-context react-native-svg lucide-react-native
Todo ícone é do lucide, nos dois pacotes. As peças desenham com o
lucide-react-native o mesmo ícone que a peça irmã do web usa (o ChevronDown
do Select, o Check do Checkbox, o Star do Rating), e o app faz o
mesmo: nada de ícone desenhado à mão, com View, caractere (✓, ›, ★) ou
SVG próprio. Outro conjunto só entra quando o lucide não tem o desenho. A cor
não desce da View para o SVG: o ícone recebe color com o papel lido de
useRivo().colors, ou chega pela forma de função das peças que aceitam
icon, que entregam a cor e o tamanho.
O nome falado é label nas peças nativas, no lugar do aria-label do
web: o Checkbox e o Switch sem texto ao lado exigem label, e o
OTPField e o SignaturePad o aceitam. accessibilityLabel fica só onde a
peça é o TextInput da plataforma e no Item, cuja linha já tem texto.
Todo campo nativo tem a moldura do Input, no iOS e no Android. Vazio, ele
tem a altura do Input (h-12), o texto começa na mesma coluna (px-3.5
dentro da borda de 1 ponto) e fica centrado na vertical nos dois sistemas. Vale
para Input, MaskedInput, CurrencyInput, PostalCodeField,
PasswordInput, SearchInput, InputGroup, TagsInput, NumberField,
TimeField e para os gatilhos que abrem folha (Select, Combobox,
Autocomplete, TreeSelect, DatePicker, DateRangePicker,
DateTimePicker, TimePicker, MonthPicker); Textarea e PromptInput
seguem só a coluna. Com adorno na frente - a lupa do SearchInput, o R$ do
CurrencyInput, o prefixo do InputGroup - é o adorno que abre na coluna, e o
texto vem depois dele. O valor do gatilho fica numa linha só, com reticências,
e não empurra a seta. No iOS, o campo de uma linha deixa de lado a altura de
linha do text-base, que empurrava o texto para baixo do centro; um
lineHeight no style ainda vence. Trocar a altura ou o px pelo
className tira o campo do padrão: faça isso só quando a tela pede outra
coisa de propósito.
A regra que desenha o pacote é um subcaminho por peer, e não um por
assunto. Os peers opcionais são do Expo e do formulário, e é o peer que decide onde a
porta fica: no celular um módulo do Expo custa build, e não só bytes, e o
metro resolve import por arquivo. Então quem só quer um
Button não pode encontrar nenhum deles no índice da raiz. Juntar Clipboard
e FileUpload numa porta só, um /expo, cobraria o seletor de documentos de
quem apenas copia a chave de acesso de uma NF-e; por isso são duas. As
exceções escritas são o /ai, explicado mais abaixo, e o /chart, as
ilustrações e o mascote, que desenham com o react-native-svg - peer
obrigatório da raiz desde a 6.0 - e continuam em porta própria pelo peso.
| Subcaminho | O peer que ele custa | O que sai por ele |
|---|---|---|
@rivocode/ui-native/form |
react-hook-form, mais zod e @hookform/resolvers no useZodForm |
Form, FormField, FormErrorSummary, FormSaveBar (chama o submit do Form sozinho), useZodForm e os adaptadores forText, forValue, forFiles, forChecked, forDate |
@rivocode/ui-native/chart |
nenhum (o react-native-svg é peer da raiz desde a 6.0) |
ChartContainer, ChartDonut, ChartRadial, ChartGauge, ChartHeatmap, ChartFunnel, ChartTreemap, as marcas ChartBar e ChartLine, a PALETTE, e o QRCode e o PixCode, que desenham com o mesmo SVG |
@rivocode/ui-native/chart |
nenhum (o react-native-svg é peer da raiz desde a 6.0) |
ChartContainer, ChartDonut, ChartRadial, as marcas ChartBar e ChartLine, a PALETTE, o QRCode, o PixCode e o SignaturePad (com signatureToSvg e isSignatureEmpty), que desenham com o mesmo SVG |
@rivocode/ui-native/clipboard |
expo-clipboard |
Clipboard |
@rivocode/ui-native/file-upload |
expo-document-picker |
FileUpload, FileUploadList, FileUploadItem |
@rivocode/ui-native/illustrations |
nenhum (o react-native-svg é peer da raiz desde a 6.0) |
Illustration e as nove pelo nome (NotFound, Forbidden, ServerError, Offline, Maintenance, EmptyList, NoResults, EmptyInbox, NoData), com ILLUSTRATION_NAMES: a mesma geometria do web, pintada com useRivo().colors |
@rivocode/ui-native/mascot |
nenhum (o react-native-svg é peer da raiz desde a 6.0) |
Bacalhau, BacalhauPeek, MASCOT_POSES, MASCOT_HATS, MASCOT_MOTIONS e seasonHat, com a API do web: a mesma geometria, a paleta fixa de tokens.mascot e a coreografia tocada pelo react-native-reanimated |
@rivocode/ui-native/audio |
expo-audio |
AudioRecorder, com a API do web e a uri no lugar do Blob; AudioPlayer: a mesma API do web, com src no AudioSource do Expo (require ou { uri, headers }), a onda desenhada com View e os picos vindos prontos, porque o celular nao tem Web Audio; useAudioSequence, o mesmo grupo do web, que acha o seguinte pelo measureInWindow |
@rivocode/ui-native/pure |
nenhum, nem react nem react-native |
o Pix (buildPixPayload, parsePixPayload, isValidPixKey, normalizePixKey), os validadores de documento e de boleto, o matchesSearch e os formatadores (currency e irmaos), os mesmos do @rivocode/ui/pure: e o caminho do bun test e do servidor |
@rivocode/ui-native/video |
expo-video |
VideoPlayer: a mesma API do web, com src no VideoSource do Expo (require ou { uri, headers }), o quadro no VideoView sem os controles do sistema e a tela cheia do sistema; renderViewerVideo, o renderVideo pronto do ImageViewer, para o vídeo da conversa passar no mesmo visualizador das fotos; useVideoPreview, o primeiro quadro, a proporção e a duração de um vídeo sem player na tela, para a MessageMedia |
@rivocode/ui-native/media-library |
expo-media-library e expo-file-system |
saveToGallery: pede a permissão de escrita, baixa o src (endereço ou { uri, headers }) para o cache, salva na galeria e apaga o cache; cada falha sai como GalleryError, com reason unavailable (o módulo não roda neste ambiente: no Android, o Expo Go não dá acesso à galeria, e é preciso um build de desenvolvimento), permission, download ou save. É a função do download do ImageViewer |
npx expo install expo-clipboard expo-document-picker expo-audio expo-video expo-media-library expo-file-system
O formulário tem um adaptador a mais, o forText, porque no nativo o campo
não devolve evento: o TextInput entrega o texto direto, e forValue não
serve. E nada envia sozinho: sem <form>, sem type="submit" e sem
Enter, o Form entrega { submit, isSubmitting } por função. O rótulo viaja
no campo: sem for nem id, o FormField põe accessibilityLabel e
invalid na linha, e o adaptador os leva ao controle: como label nas peças,
que se nomeiam por ele, e como accessibilityLabel no Input e no Textarea,
que são o TextInput da plataforma.
import { Form, FormField, forText, useZodForm } from '@rivocode/ui-native/form'
O gráfico não tem Recharts, nem variável de CSS, nem contentor que meça. O
ChartContainer faz as três coisas à mão e entrega: children como função
recebe { width, height, colors }, no lugar de var(--color-série), e a
medida chega zerada no primeiro quadro. Os quatro finais de uma consulta
(isLoading, isError, onRetry, empty) atravessam com os mesmos nomes, e
a altura continua sendo sua, por classe.
A PALETTE é a lista dos oito papéis de série do tema (chart-1 a chart-8),
na ordem em que devem ser usados: série sem color no config recebe o
próximo da paleta, e é ela que o ChartDonut percorre fatia a fatia. Cor de
série aqui é papel de token, nunca hexadecimal. O web aceita qualquer cor de
CSS na mesma prop porque lá ela vira var(--color-série) e o tema continua no
comando; aqui a cor que a peça recebe é o valor final que vai para o desenho, e
um #22c55e escrito ali seria a única coisa da tela que não muda quando o
cliente troca de tema.
import { ChartBar, ChartContainer, ChartDonut, ChartLine, ChartRadial, PALETTE } from '@rivocode/ui-native/chart'
ChartBar e ChartLine são as marcas que andam: desenhe a barra e a linha com
elas, dentro da função da moldura, no lugar de Rect e Path crus. Na
montagem elas entram (a barra cresce da base, a linha sobe da baseline, ou do
ponto mais baixo) e, quando o dado muda, vão até o valor novo com os tokens de
movimento, pelo Reanimated; com "reduzir movimento", nascem no lugar e saltam.
A rosca e o arco fazem o mesmo sozinhos, e a Sparkline só esmaece ao entrar.
A Sparkline fica fora deste subcaminho, na raiz e desenhada com View: ela é
o slot chart do Stat, o Stat sai da raiz, e trazê-la para cá cobraria o
peso do gráfico de quem só queria um número num cartão.
Copiar confirma duas vezes. O Clipboard troca o nome do botão, como no
web, e dispara também um aviso: accessibilityLabel trocado num
Pressable que já está sob o foco não é reanunciado nem pelo VoiceOver nem
pelo TalkBack, e o aviso do RivoProvider é o único canal da tela que fala
sozinho (toast={false} desliga).
E a área de soltar não existe. No celular não há arrastar: o FileUpload
abre o seletor do sistema por um botão de altura de controle, com o hint
dentro do nome falado, e o accept fala MIME, que é o que o seletor sabe
filtrar. O que volta é um PickedFile com uri local: size pode faltar, e
maxSize só recusa o que mediu. A lista do que já entrou é a FileUploadList,
com um FileUploadItem por arquivo.
import { Clipboard } from '@rivocode/ui-native/clipboard'
import { FileUpload, FileUploadItem, FileUploadList } from '@rivocode/ui-native/file-upload'
O áudio toca pelo expo-audio, que mora no caminho dele. O AudioPlayer
tem a API do web; a busca é adjustable, com ações de 5 segundos no leitor de
tela, e os picos da onda vêm prontos: no celular não há audioPeaks. O
AudioRecorder grava pelo mesmo peer, com a API do web: o onComplete entrega
a uri do arquivo em vez do Blob, e o medidor lê o nível em dB do gravador.
O useAudioSequence é o do web: um áudio por vez no grupo, e o seguinte abaixo
na tela toca quando um termina.
import { AudioPlayer, AudioRecorder, useAudioSequence } from '@rivocode/ui-native/audio'
O vídeo toca pelo expo-video, num caminho só dele, e não no do áudio:
quem manda mensagem de voz não precisa reconstruir o app com o player de vídeo.
O VideoPlayer tem a API do web; o quadro é o VideoView sem os controles do
sistema, a faixa de baixo é a da casa, e a tela cheia é a do sistema.
import { VideoPlayer } from '@rivocode/ui-native/video'
Foto e vídeo da conversa passam no mesmo ImageViewer: o item com
kind: "video" toca no meio das fotos. No web o visualizador desenha o
VideoPlayer da raiz sozinho; no celular a raiz não importa o expo-video,
e o player entra pelo renderVideo, com o renderViewerVideo deste caminho.
import { renderViewerVideo } from '@rivocode/ui-native/video'
<ImageViewer images={midia} index={index} onIndexChange={setIndex} renderVideo={renderViewerVideo} />
O vídeo no balão sem poster pede o useVideoPreview deste caminho: ele abre
o arquivo num player mudo, com os headers do src, tira o primeiro quadro, a
proporção e a duração, e solta o player. Guarda os últimos 40 por endereço e
abre no máximo dois por vez. O quadro é um VideoThumbnail, que o Image do
core não abre: ele entra pelo renderPoster da MessageMedia, no Image do
expo-image. Sem o expo-image, passe só aspectRatio e duration.
import { useVideoPreview } from '@rivocode/ui-native/video'
const previa = useVideoPreview(video.src)
<MessageMedia kind="video" src={video.src} aspectRatio={previa.aspectRatio} duration={previa.duration} />
Salvar a mídia na galeria é o saveToGallery, num caminho só dele, atrás
do expo-media-library e do expo-file-system: quem só mostra foto não pede a
permissão de fotos nem reconstrói o app por causa deles. O download do
ImageViewer liga o botão Baixar ao lado do zoom; no web, download (ou
true) baixa pela própria peça, e no celular ele é só a função, que chama
este caminho. A promessa rejeitada mostra e anuncia a falha; o aviso de
sucesso fica com o app.
import { GalleryError, saveToGallery } from '@rivocode/ui-native/media-library'
<ImageViewer
images={midia}
index={index}
onIndexChange={setIndex}
download={(item) => saveToGallery(item.src, { name: item.alt, kind: item.kind })}
/>
As peças de IA moram em @rivocode/ui-native/ai, um dos dois caminhos sem
peer. A regra do peer continua valendo para os outros quatro; este existe
pelo peso. O metro não sacode árvore: importar um Button do índice da raiz
compila tudo o que ele alcança, e a conversa com um modelo não pode entrar no
aplicativo de quem só emite nota. É o mesmo caminho do web, trocando o nome do
pacote.
import { AILabel, Conversation, Message, MessageMedia, PromptInput, ShimmerText, ToolCall } from '@rivocode/ui-native/ai'
A Conversation vem por items, renderItem e keyExtractor, sobre uma
FlatList invertida; o PromptInput é controlado e envia só pelo botão,
porque o retorno do teclado do celular quebra a linha; a Message tem onCopy
no lugar do copyValue, porque copiar é do expo-clipboard; a explicação do
AILabel abre numa Sheet; o ShimmerText pulsa a cor inteira entre
fg-muted e fg, porque o React Native não recorta gradiente na letra; o
onReply da Message é arrastar o balão para a direita, sem contextMenu; a
citação leva até a original pela chave do keyExtractor, sem messageId; e a MessageMedia
mostra a miniatura do vídeo sem o expo-video.
A SortableList mora em @rivocode/ui-native/dnd, o outro caminho sem
peer. No web ela carrega o dnd-kit; aqui o gesto é o PanResponder do core,
o mesmo do Slider, e o react-native-gesture-handler não é pedido. O caminho
próprio existe para a linha de import ser a mesma nos dois pacotes. Só a
alça arrasta (44pt, e ela segura o gesto até o dedo sair), porque a linha
inteira como alça transformaria todo gesto de rolar num arrasto; o leitor de
tela move por duas ações, "Mover para cima" e "Mover para baixo", com os
mesmos anúncios do web.
import { SortableList } from '@rivocode/ui-native/dnd'
O Kanban não porta, por decisão. A 390px cabe uma coluna, e arrastar um
cartão para a coluna que não está na tela disputa o dedo com a rolagem. No
aplicativo, cada coluna vira uma lista (Tabs ou seções) e mudar de coluna é
um Menu com "Mover para"; o onMove do lado de quem guarda o estado é o
mesmo.
Tema de cliente aqui é decisão de BUILD, e não prop de runtime. Os dois
temas de casa trocam com a tela aberta, porque foram compilados como
light-dark() e o provider só gira o Appearance. A cor de um cliente, não: o
compilador do react-native-css crava o valor do token dentro da classe, e
<RivoProvider theme={{ light, dark }}> alcança só quem lê cor por JS (os
gráficos, o giro do Button, o trilho do Switch), deixando fundo, cartão,
botão, selo e borda com a cor da casa - a tela sai misturada, e não sem
marca. Vista o cliente sobrescrevendo os papéis num @theme do CSS do app antes
de compilar, e passe o mapa de tema junto para a metade de JS concordar. São
dois temas por build, porque light-dark() tem duas vagas. O passo a passo
está em https://ds.rivocode.com.br/temas.md.
O resto da paridade (o que traduz, o que muda de nome e o que não porta por decisão) está em https://ds.rivocode.com.br/react-native.md.
Onde esta a verdade
| O que | Onde |
|---|---|
| Indice de tudo | https://ds.rivocode.com.br/llms.txt |
| Uma peca, com props e exemplos | https://ds.rivocode.com.br/componentes/<nome-em-kebab>.md |
| Os papeis de um tema, todos | https://ds.rivocode.com.br/temas.md |
| Um sistema inteiro, montado | https://ds.rivocode.com.br/demonstracao |
Nunca invente prop. Se o .md da peca nao a lista, ela nao existe.
De onde se instala
Os três pacotes (@rivocode/ui, @rivocode/ui-native e @rivocode/ui-mcp)
são privados e moram no GitHub Packages, e não no npmjs.com. O projeto
precisa de um .npmrc na raiz:
@rivocode:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${RIVOCODE_NPM_TOKEN}
O RIVOCODE_NPM_TOKEN é um token do GitHub com read:packages, no ambiente da
máquina, da CI e do deploy. Sem ele, o npm install responde 401 ou 404,
e o 404 não quer dizer que o pacote não existe.
Versões
Da 1.0 em diante, o @rivocode/ui e o @rivocode/ui-native seguem
versionamento semântico à risca, cada um no seu número:
- Quebra só em versão maior. Tirar ou renomear prop, peça ou export, trocar o padrão de uma prop ou o formato de um callback é quebra, e só sai numa versão maior.
- Quebra entra direto, sem período de obsolescência. A lib é de uso privado: a prop antiga sai na mesma versão maior em que a nova entra, e o CHANGELOG diz o que muda no ponto de chamada.
- Prop nova e peça nova são versão menor.
- Correção é versão de correção.
Prop marcada @deprecated não se usa em código novo: o .md da peça diz o nome que fica.
Os nomes do estado
Cada ideia de estado tem um nome só, nos dois pacotes: o controlado, o inicial (onde a peça sabe se guardar sozinha) e o aviso.
| A ideia | O trio | Onde |
|---|---|---|
| aberto ou fechado | open, defaultOpen, onOpenChange |
Collapsible, AccordionItem, Spoiler, Tour, ToolCall, os Dialog; na Tree, a lista de galhos abertos |
| o passo de uma sequência | step, defaultStep, onStepChange |
Tour; o Steps só controlado, pelo useWizard |
| a posição numa coleção | index, defaultIndex, onIndexChange |
Carousel, ImageViewer |
| a página de uma lista paginada | page, onPageChange |
Pagination |
| o que foi escolhido ou digitado | value, defaultValue, onValueChange |
campos, Accordion, Tabs |
step e index contam de zero, porque são posição de programa. page conta
de um, porque é o número que a pessoa lê na tela e que o servidor recebe na
query: page={3} é a página 3, e converter nos dois sentidos em toda chamada
é onde nasce o erro de um a mais. step é passo de uma sequência que anda
para a frente; index é lugar numa coleção que se percorre em qualquer ordem,
como o slide do Carousel.
Não existe expanded, visible nem current para essas ideias. O
Accordion fica em value porque o que ele guarda é quais itens estão
abertos, e não se um está; com multiple ele deixa vários ao mesmo tempo, e
sem ela abre um por vez, nos dois pacotes.
O que o ref recebe
Por padrão, o ref de uma peça aponta para o nó de verdade da raiz dela: o
<button> do Button, o <a> do Link, o <input> do campo, e no nativo o
componente do React Native por baixo. É para medir, dar foco e ligar biblioteca
de terceiro, e nunca para mudar o que a peça mostra.
Ref imperativo, que entrega um objeto com métodos no lugar do nó, é exceção, e só existe quando a ação não é um estado que a tela possa guardar. Hoje são duas peças, as duas só no web:
| Peça | O handle | Por que não é prop |
|---|---|---|
VirtualList |
VirtualListHandle: scrollToIndex(index, { align }) |
rolar é um evento, e não um valor: o item fora da janela não está no DOM, e não há nó para o scrollIntoView alcançar |
ResizablePanel |
ResizablePanelHandle: collapse(), expand(), resize(size), getSize(), isCollapsed() |
a medida pertence ao arrasto, e muda a cada quadro; controlá-la por prop faria a tela renderizar junto com o ponteiro |
Peça nova só ganha handle se passar pelas três perguntas, nesta ordem:
- Cabe no trio de estado? Abrir, escolher, mudar de passo ou de página é
prop controlada (
open,value,step,page), e nunca método. UmdialogRef.current.open()esconde da tela o que ela está mostrando. - O nó da raiz resolve? Foco, medida e rolagem até um elemento que existe se fazem pelo nó, com a API do navegador.
- A ação é um evento que não deixa estado? Rolar até um item que ainda não existe, ou mexer num valor contínuo que é do gesto. Só então vale o handle.
Quando existe, o handle segue a mesma forma: o tipo se chama
<Peça>Handle e sai exportado do pacote, os métodos são verbos
(scrollToIndex, collapse), a leitura é get… ou is…, e o JSDoc da prop
ref lista os métodos. O handle não substitui o trio: o ResizablePanel
continua avisando por onResize, onCollapse e onExpand.
Rotulo de controle vem como filho
Checkbox, Radio e Switch aceitam o texto como filho e se embrulham num
<label>, entao clicar no texto tambem marca:
<Checkbox defaultChecked>ISS retido na fonte</Checkbox>
<Radio value="pix">Pix</Radio>
<Switch>Enviar o XML junto com o PDF</Switch>
Sem filho sai so o controle, para quando o rotulo tiver estrutura propria. Ai o
<label> em volta e seu.
O padrão do campo
Todo campo de texto da biblioteca segue uma regra só, e a vitrine mede cada um
no Chrome (bun run a11y, coluna data-rc-coluna-de-campos em
demo/campos.tsx):
- A mesma coluna. O texto e o placeholder começam no mesmo x do
Input: borda de 1px mais o respiro--rc-control-pad-*do tamanho. Vale paraMaskedInput,CurrencyInput,PasswordInput,SearchInput,InputGroup,TagsInput,Combobox,Autocomplete,Select,TreeSelect, os campos de data e de hora,PostalCodeField, o campo doColorPicker, oTextareae oPromptInput. - A mesma altura. Vazio, o campo tem a altura
--rc-control-sm|md|lgdoInputdo mesmosize, nas duas densidades. Só cresce o que quebra linha: oTextarea, e oTagsInpute oComboboxChipsquando as fichas não cabem numa linha. - O texto no meio. Uma linha só, centrada na altura. O valor longo do
Select, doTreeSelecte dos gatilhos de data termina em reticência, e o gatilho nunca passa da caixa em volta. - Com encosto na frente, ícone ou prefixo (a lupa, o
R$, a chave do Pix numInputPrefix), o encosto começa na coluna do texto, e o texto vem depois dele com o respiro da casa, 8px. Sem divisória entre os dois. O que fica atrás- sufixo, botão de mostrar senha - mora à direita.
- A exceção é o campo de passo. O
NumberField, e oTimeFieldcom os botões, vestem[−][valor][+]com o valor no meio, nos dois pacotes: um botão de cada lado, que o polegar acha sem mirar. A altura segue a regra.
A moldura é uma só, interna (src/lib/field-frame.ts): campo novo veste ela, e
o test/padrao-do-campo.test.tsx recusa arquivo que desenha campo de texto sem
estar na lista.
Texto de interface mora em labels
O texto que a peca escreve sozinha - o nome de um botao, o que o leitor de tela
ouve, uma frase fixa - se troca por um objeto so, labels, nos dois pacotes e
com as mesmas chaves. Passe so as chaves que mudam; o resto fica no padrao em
portugues:
<Popconfirm
trigger={<Button variant="ghost">Excluir</Button>}
title="Excluir a nota 4813?"
onConfirm={remove}
labels={{ confirm: "Excluir nota" }}
/>
<QueryBoundary data={data} isError={isError} onRetry={refetch} labels={{ retry: "Try again" }}>
{(invoices) => <InvoiceList invoices={invoices} />}
</QueryBoundary>
A excecao e o verbo de uma acao que a peca nao conhece: labels.confirm do
Popconfirm web e do AlertDialog nativo e obrigatorio, porque "Confirmar"
nao diz o que se confirma.
Nao existe prop solta terminada em Label para texto de interface: a chave e o
nome da prop antiga sem o Label (retry, dismiss, confirm, cancel,
busy, submit, stop, scroll, swatches, external, empty). O que fica
fora de labels e CONTEUDO, e continua prop: o label que da nome ao campo ou a
regiao, o title e o errorTitle de um aviso, o centerLabel de um grafico, o
deltaLabel de um Stat, o thumbLabel de um Slider, o placeholder.
Data tem duas metades. O nome do mes, do dia da semana e a hora saem do
locale (tag BCP 47), no EventCalendar e no Gantt; as palavras fixas em
volta - "Hoje", "+2 mais", "Dia inteiro", "12 a 18" - sao labels. No nativo
nao ha locale: o Calendar, o DatePicker e o DateRangePicker trocam o
mes escrito e as iniciais da semana por labels.caption e labels.weekdays.
As duas formas de aba
TabList tem variant. O risco embaixo, que e o padrao, diz "esta parte da
pagina". A caixinha, variant="segmented", diz "a mesma coisa, de outro jeito":
largura de tela, preview e codigo, escuro e claro. Trocar uma pela outra faz o
controle prometer o que ele nao faz.
Um exemplo do idioma
<RivoProvider theme="rivocode-dark">
<main className="min-h-screen bg-bg p-8 font-sans text-fg">
<h1 className="mb-6 font-display text-3xl">Notas fiscais</h1>
<Card>
<CardHeader>
<CardTitle>Resumo do mes</CardTitle>
<CardDescription>Agosto de 2026</CardDescription>
</CardHeader>
<CardContent className="text-fg-muted">
Doze notas processadas, tres pendentes.
</CardContent>
<CardFooter>
<Button size="sm">Ver detalhes</Button>
<Button size="sm" variant="ghost">Exportar</Button>
</CardFooter>
</Card>
</main>
</RivoProvider>
Botao em pilula (shape="pill") e o tamanho xl sao de pagina de marketing.
Em tela de produto o padrao e o canto de 8px.