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.
- npm:
ranui· código:packages/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>
<script setup>
import 'ranui';
</script>
<!-- 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
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 |
Compatibilidad con navegadores
La biblioteca funciona en todos los navegadores modernos: está construida sobre Custom Elements v1, Shadow DOM v1 y propiedades personalizadas de CSS. Internet Explorer no está soportado.
Colaboradores
Para seguir leyendo
Estándares sobre los que se apoya esta biblioteca: W3C · ECMA · RFC · Can I use
Referencias de diseño que conviene tener a mano: Checklist Design · Laws of UX · Geist · Ant Design · Element UI · Animista · WebGradients