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.
- npm:
ranui· código:packages/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>
<script setup>
import 'ranui';
</script>
<!-- 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
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 |
Suporte a navegadores
A biblioteca funciona em todos os navegadores modernos: ela é construída sobre Custom Elements v1, Shadow DOM v1 e propriedades personalizadas de CSS. O Internet Explorer não é suportado.
Contribuidores
Leitura adicional
Padrões sobre os quais esta biblioteca se apoia: W3C · ECMA · RFCs · Can I use
Referências de design que vale manter à mão: Checklist Design · Laws of UX · Geist · Ant Design · Element UI · Animista · WebGradients