ranui

Uma biblioteca de UI construída sobre custom elements nativos. Cada componente é uma tag <r-*>, então funciona igual no React, no Vue, no Svelte, no Solid, no Astro ou num arquivo HTML puro. Não há adaptador nem versão de framework para casar. Tipos TypeScript, tema claro e escuro por design tokens, encapsulamento com Shadow DOM e renderização no servidor já vêm incluídos.

v0.5.0-alpha.7MITesm · cjs · iifepackages/ranui

O ranui está em alfa: as versões trazem mudanças incompatíveis. Fixe uma versão exata e leia o registro de alterações antes de atualizar.

Instalação

npm install ranui

<!-- ou de uma CDN, sem etapa de build -->
<script src="https://unpkg.com/ranui/dist/umd/index.umd.cjs"></script>

Como usar

Importar registra os elementos; depois disso você escreve tags.

import 'ranui'; // todos os componentes
import 'ranui/button'; // ou apenas um

<r-button type="primary">Publicar projeto</r-button>

É a mesma tag em todos os frameworks: o que muda é como cada um passa valores e liga eventos, algo que as diretrizes de código cobrem por inteiro:

<script src="https://unpkg.com/ranui/dist/umd/index.umd.cjs"></script>

<body>
  <r-button>Button</r-button>
</body>

import 'ranui';

export const App = () => <r-button type="primary">Deploy</r-button>;
// Valores complexos e listeners passam por um ref — veja as diretrizes de código.

<template>
  <r-button type="primary" @click="deploy">Deploy</r-button>
</template>

<!-- Acrescente `r-` a compilerOptions.isCustomElement na configuração de build. -->

import 'ranui';

const button = document.createElement('r-button');
button.textContent = 'Deploy';
document.body.appendChild(button);

Pontos de entrada

Cada entrada registra exatamente o que o nome diz, então uma página que só quer temas nunca paga pela biblioteca de componentes.

Import	Contém
`ranui`	Todos os componentes
`ranui/<component>`	Um componente: `ranui/button`, `ranui/select`, …
`ranui/theme`	Tema claro/escuro e sobrescrita de tokens; sem elementos
`ranui/i18n`	O motor de tradução; sem elementos
`ranui/fonts`	Geist Sans + Geist Mono auto-hospedadas
`ranui/style`	A folha de estilos, se a sua configuração não a pegar sozinha
`ranui/builder`	O construtor de DOM fluente com reatividade de granulação fina
`ranui/ssr`, `ranui/ssr-stream`	Renderização no servidor
`ranui/testing`	Auxiliares para alcançar um shadow root fechado a partir de um teste
`ranui/typings`	Tipos ambientais de elementos para JSX / TS

Componentes

40 elementos. Todos eles, com seus atributos, propriedades, eventos, slots e nomes de ::part(), estão na referência da API de elementos.

Comuns: Button · Icon · Loading

Entrada de dados: Input · CheckBox · Select · ColorPicker · Attachments · VoiceButton · Forms

Apresentação de dados: Card · Section · Tabs · Image · Progress · Radar · Player · Preview · Glass · Scratch · StateDot · DisclosureRow

Renderização de conteúdo: Markdown · Math · Mermaid

IA e chat: Conversation · Reasoning · ToolCard · TokenMeter

Camadas e avisos: Modal · Popover · Dropdown · Message · Skeleton

Navegação: Router · Route · Link

Fundamentos: Temas · ThemeSwitch · i18n

Cinco elementos não têm página própria porque só existem dentro de outro: <r-option> (Select), <r-tabs> (Tabs), <r-img> (Image), <r-dropdown-item> (Dropdown) e <r-content> (Popover). Eles estão na referência da API como todo o resto.

Ao vivo

Primary

Warning

Text

Default

Estilos

Os componentes são desenhados num shadow root fechado: o CSS da página não entra e os seletores não alcançam para dentro. Há quatro caminhos, em ordem de preferência.

1. Design tokens (propriedades personalizadas de CSS): eles são herdados através da fronteira, então defini-los no :root, num contêiner ou no próprio elemento funciona igual:

<r-progress
  percent="0.7"
  type="drag"
  style="--ran-progress-track-background: linear-gradient(to right, #f00, #ff0, #0f0, #0ff, #00f)"
></r-progress>

2. ::part() para ajustes estruturais que os tokens não cobrem · 3. o atributo sheet para injetar CSS no shadow root · 4. conteúdo em slots, que fica no seu documento e recebe o CSS da sua página.

Os nomes dos tokens são o design system; as regras para escolher entre eles são as diretrizes de design; a mecânica está nas diretrizes de código.

Eventos

Os componentes despacham CustomEvent com a carga em detail. Ligue o listener no elemento: se um evento borbulha é uma decisão por componente, e a referência da API informa isso para cada um:

<r-select id="env"></r-select>

<script>
  document.getElementById('env').addEventListener('change', (event) => {
    console.log(event.detail.value);
  });
</script>

A forma de atributo onchange="…" e a de propriedade el.onchange = … também funcionam, já que estes são elementos do DOM comuns, mas aceitam apenas um manipulador e não têm fase de captura, então addEventListener é o caminho a seguir.

Para onde ir em seguida

Se você quiser…	Leia
Consultar a API exata de um elemento	API de elementos
Saber qual token usar, e por quê	Design system
Montar uma tela que pareça um sistema só	Diretrizes de design
Integrar o ranui a um aplicativo corretamente	Diretrizes de código
Acrescentar claro/escuro, ou reestilizar tudo	Temas
Traduzir a interface	i18n
Renderizar num servidor	Renderização no servidor
Montar views reativas sem framework	Builder
Ver o que mudou antes de atualizar	Registro de alterações