ranui

Una biblioteca de UI construida sobre custom elements nativos. Cada componente es una etiqueta <r-*>, así que funciona igual en React, Vue, Svelte, Solid, Astro o en un archivo HTML a secas. No hay adaptador ni versión de framework que hacer coincidir. Incluye tipos TypeScript, tema claro y oscuro mediante design tokens, encapsulación con Shadow DOM y renderizado en servidor.

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

ranui está en alfa: las versiones traen cambios incompatibles. Fija una versión exacta y lee el registro de cambios antes de actualizar.

Instalación

npm install ranui

<!-- o desde una CDN, sin paso de compilación -->
<script src="https://unpkg.com/ranui/dist/umd/index.umd.cjs"></script>

Cómo se usa

Importar registra los elementos; a partir de ahí escribes etiquetas.

import 'ranui'; // todos los componentes
import 'ranui/button'; // o solo uno

<r-button type="primary">Desplegar proyecto</r-button>

Es la misma etiqueta en todos los frameworks: lo que cambia es cómo cada uno pasa valores y enlaza eventos, algo que la guía de código cubre por completo:

<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>;
// Los valores complejos y los listeners van por un ref — consulta la guía de código.

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

<!-- Añade `r-` a compilerOptions.isCustomElement en la configuración de build. -->

import 'ranui';

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

Puntos de entrada

Cada entrada registra exactamente lo que dice su nombre, así que una página que solo quiere temas nunca paga por la biblioteca de componentes.

Import	Contiene
`ranui`	Todos los componentes
`ranui/<component>`	Un componente: `ranui/button`, `ranui/select`, …
`ranui/theme`	Tema claro/oscuro y sobrescritura de tokens; sin elementos
`ranui/i18n`	El motor de traducción; sin elementos
`ranui/fonts`	Geist Sans + Geist Mono autoalojadas
`ranui/style`	La hoja de estilos, si tu configuración no la recoge sola
`ranui/builder`	El constructor de DOM fluido con reactividad de grano fino
`ranui/ssr`, `ranui/ssr-stream`	Renderizado en servidor
`ranui/testing`	Ayudas para entrar en un shadow root cerrado desde una prueba
`ranui/typings`	Tipos ambientales de elementos para JSX / TS

Componentes

40 elementos. Todos ellos, con sus atributos, propiedades, eventos, slots y nombres de ::part(), están en la referencia de la API de elementos.

Comunes: Button · Icon · Loading

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

Presentación de datos: Card · Section · Tabs · Image · Progress · Radar · Player · Preview · Glass · Scratch · StateDot · DisclosureRow

Renderizado de contenido: Markdown · Math · Mermaid

IA y chat: Conversation · Reasoning · ToolCard · TokenMeter

Capas y avisos: Modal · Popover · Dropdown · Message · Skeleton

Navegación: Router · Route · Link

Fundamentos: Temas · ThemeSwitch · i18n

Cinco elementos no tienen página propia porque solo existen dentro de otro: <r-option> (Select), <r-tabs> (Tabs), <r-img> (Image), <r-dropdown-item> (Dropdown) y <r-content> (Popover). Están en la referencia de la API como todo lo demás.

En vivo

Primary

Warning

Text

Default

Estilos

Los componentes se dibujan en un shadow root cerrado: el CSS de la página no se cuela dentro y los selectores no alcanzan hacia adentro. Hay cuatro vías, por orden de preferencia.

1. Design tokens (propiedades personalizadas de CSS): se heredan a través del límite, así que definirlos en :root, en un contenedor o en el propio 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 retoques estructurales que los tokens no cubren · 3. el atributo sheet para inyectar CSS en el shadow root · 4. contenido en slots, que se queda en tu documento y toma el CSS de tu página.

Los nombres de los tokens son el sistema de diseño; las reglas para elegir entre ellos son la guía de diseño; la mecánica está en la guía de código.

Eventos

Los componentes despachan CustomEvent con la carga en detail. Enlaza en el elemento: que un evento burbujee es una decisión por componente, y la referencia de la API lo indica para cada uno:

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

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

La forma de atributo onchange="…" y la de propiedad el.onchange = … también funcionan, ya que son elementos del DOM normales, pero solo admiten un manejador y no tienen fase de captura, así que addEventListener es la vía a la que recurrir.

Adónde ir después

Si quieres…	Lee
Consultar la API exacta de un elemento	API de elementos
Saber qué token usar, y por qué	Sistema de diseño
Construir una pantalla que parezca un solo sistema	Guía de diseño
Integrar ranui en una aplicación correctamente	Guía de código
Añadir claro/oscuro, o rehacer todo el estilo	Temas
Traducir la interfaz	i18n
Renderizar en un servidor	Renderizado en servidor
Construir vistas reactivas sin framework	Builder
Ver qué cambió antes de actualizar	Registro de cambios