Sileo

Qué es

Sileo muestra una cápsula con el estado y el título. Al pasar el cursor por encima se despliega el mensaje: la cápsula y el panel se funden en una sola forma, sin costuras, gracias a un filtro SVG de metaballs.

Cuando hay varias notificaciones a la vez forman una fila de pestañas solapadas a la altura del título. Solo la enfocada muestra su texto; las demás quedan como círculos con su icono. Ver La fila de tabs.

El JavaScript solo mantiene el estado, crea el DOM, mide dos cosas (ancho de la cápsula y alto del panel) y coloca las tabs. Todo el movimiento —el spring, el morphing, la entrada y la salida— es CSS.

Instalación

Con bundler (npm, pnpm, yarn)

npm i sileojs

import { sileo, createToaster } from "sileojs";
import "sileojs/styles.css";

Sin build, desde el navegador

Es un módulo ES sin dependencias, así que se puede importar tal cual:

<link rel="stylesheet" href="/ruta/a/sileojs/src/sileo.css">

<script type="module">
  import { sileo, createToaster } from "/ruta/a/sileojs/src/sileo.js";
  createToaster({ position: "top-right" });
  sileo.success({ title: "Listo" });
</script>

Qué trae el paquete

Inicio rápido

Dos pasos: montar el toaster una vez y llamar a sileo.*() desde donde sea.

import { sileo, createToaster } from "sileojs";
import "sileojs/styles.css";

// una sola vez, al arrancar la app
createToaster({ position: "top-right", theme: "system" });

// desde cualquier parte
sileo.success({
  title: "Guardado",
  description: "Tus cambios se sincronizaron con el servidor.",
});

createToaster() es opcional: si no lo llamas, el primer sileo.*() monta uno con los valores por defecto. Llámalo si quieres fijar posición, tema o márgenes.

JavaScript / vanilla

El core no sabe nada de frameworks. El patrón es siempre el mismo: montar el toaster al arrancar, destruirlo si tu vista desaparece.

import { sileo, createToaster } from "sileojs";
import "sileojs/styles.css";

const toaster = createToaster({
  position: "bottom-center",
  theme: "system",
  offset: 24,
});

document.querySelector("#guardar").addEventListener("click", async () => {
  await sileo.promise(guardar(), {
    loading: { id: "guardar", title: "Guardando", description: "Un momento…" },
    success: () => ({ title: "Guardado", description: "Todo listo." }),
    error: (err) => ({ title: "Error", description: String(err.message) }),
  });
});

// al salir de la página / desmontar el widget
toaster.destroy();

Vue 3

Hay dos formas. La global es la más cómoda si vas a usarlo en toda la app.

Sin componente: plugin y $sileo global

El plugin monta el toaster al arrancar y deja $sileo disponible en todas las plantillas. No hace falta poner ningún componente ni importar nada en cada archivo.

// main.js
import { createApp } from "vue";
import { SileoPlugin } from "sileojs/vue";
import "sileojs/styles.css";
import App from "./App.vue";

createApp(App)
  .use(SileoPlugin, {
    position: "top-right",
    theme: "light",
    options: { roundness: 14, styles: { toast: "top-90" } },
  })
  .mount("#app");

<!-- cualquier componente, sin imports -->
<template>
  <button @click="$sileo.success({ title: 'Guardado' })">
    Guardar
  </button>
</template>

Al plugin le puedes pasar las mismas opciones que a createToaster(). Con { mount: false } registra $sileo y el componente, pero no monta nada: el toaster lo montas tú.

Con componente

Útil si quieres que el toaster viva y muera con una vista concreta, o cambiar sus props de forma reactiva.

<script setup>
import { SileoToaster, useSileo } from "sileojs/vue";
import "sileojs/styles.css";

const sileo = useSileo();
</script>

<template>
  <SileoToaster position="top-right" theme="system" />

  <button @click="sileo.success({ title: 'Guardado' })">
    Guardar
  </button>
</template>

Props: position, theme, offset, visibleToasts, options y styles (atajo de options.styles). Cambiarlas reconfigura el toaster en caliente.

<SileoToaster position="top-right" theme="light" :styles="{ toast: 'top-90' }" />

Config reactiva: useSileoConfig()

Devuelve un objeto reactivo compartido por toda la app. Mutarlo reconfigura el toaster al vuelo — tema, posición y estilos incluidos, y también sobre los toasts que ya están en pantalla. En plantillas está como $sileoConfig.

<script setup>
import { useSileoConfig } from "sileojs/vue";

const cfg = useSileoConfig();

const oscuro = () => (cfg.theme = "dark");
const abajo  = () => (cfg.position = "bottom-center");
const gordo  = () => (cfg.styles.title = "text-lg font-bold");
</script>

<template>
  <select v-model="cfg.theme">
    <option>light</option><option>dark</option><option>system</option>
  </select>
</template>

React

import { useEffect } from "react";
import { sileo, createToaster } from "sileojs";
import "sileojs/styles.css";

export default function App() {
  useEffect(() => {
    const toaster = createToaster({ position: "top-right", theme: "system" });
    return () => toaster.destroy();
  }, []);

  return (
    <button onClick={() => sileo.success({ title: "Guardado" })}>
      Guardar
    </button>
  );
}

En React 18 con StrictMode el efecto se monta, se limpia y se vuelve a montar en desarrollo. No pasa nada: el segundo createToaster() crea uno nuevo tras el destroy() del primero.

Svelte

<script>
  import { onMount } from "svelte";
  import { sileo, createToaster } from "sileojs";
  import "sileojs/styles.css";

  onMount(() => {
    const toaster = createToaster({ position: "top-right" });
    return () => toaster.destroy();
  });
</script>

<button on:click={() => sileo.success({ title: "Guardado" })}>
  Guardar
</button>

Angular

La hoja de estilos va en angular.json:

"styles": ["node_modules/sileojs/src/sileo.css"]

import { Component, OnInit, OnDestroy } from "@angular/core";
import { sileo, createToaster } from "sileojs";

@Component({
  selector: "app-root",
  template: `<button (click)="guardar()">Guardar</button>`,
})
export class AppComponent implements OnInit, OnDestroy {
  private toaster?: ReturnType<typeof createToaster>;

  ngOnInit() {
    this.toaster = createToaster({ position: "top-right" });
  }

  ngOnDestroy() {
    this.toaster?.destroy();
  }

  guardar() {
    sileo.success({ title: "Guardado" });
  }
}

SSR y sin build

El core toca document en cuanto montas el toaster, así que en Next, Nuxt, SvelteKit o Astro hay que montarlo solo en el cliente: dentro de useEffect, onMounted, onMount o un <script> de cliente. Importar el módulo por sí solo no ejecuta nada.

Sin bundler puedes resolver el nombre del paquete con un import map:

<script type="importmap">
{ "imports": { "sileojs": "/vendor/sileojs/src/sileo.js" } }
</script>

<script type="module">
  import { sileo, createToaster } from "sileojs";
  createToaster();
  window.sileo = sileo;   // si lo quieres global de verdad
</script>

API · sileo.*

sileo.promise()

Acepta una promesa o una función que la devuelva. Muestra el estado loading (sin auto-cierre y sin desplegarse) y lo cambia al resolverse. Devuelve la misma promesa, así que puedes seguir encadenando —y capturando— con normalidad.

sileo.promise(() => subirArchivo(file), {
  loading: { id: "subida", title: "Subiendo", description: "Enviando archivo…" },
  success: (data) => ({ title: "Subido", description: data.nombre }),
  error:   (err)  => ({ title: "Falló", description: String(err.message) }),

  // opcional: en vez de success, un estado "action" con botón
  action: (data) => ({
    title: "Reporte listo",
    description: "Ya puedes descargarlo.",
    button: { title: "Descargar", onClick: () => descargar(data.url) },
  }),
});

Opciones del toast

Contenido enriquecido

description e icon aceptan un nodo del DOM o { html }. Un string siempre se inserta como texto plano, así que no hay riesgo de inyección al pintar datos de usuario.

sileo.info({
  id: "gracias",
  title: "Gracias",
  icon: { html: '<svg viewBox="0 0 24 24" …></svg>' },
  description: nodoDelDom,
  styles: { title: "mi-titulo", description: "mi-texto" },
});

Opciones del toaster

const toaster = createToaster({
  position: "top-right",     // las 6 posiciones
  theme: "system",           // "light" | "dark" | "system"
  offset: 24,                // número, string, o { top, right, bottom, left }
  visibleToasts: 3,          // tabs visibles en la fila
  options: {                 // valores por defecto para todos los toasts
    duration: 4000,
    roundness: 20,
    styles: { toast: "top-90" },
  },
  styles: { title: "font-bold" },  // atajo de options.styles
  container: document.body,  // dónde montar los viewports
});

toaster.set({ position: "bottom-center" });   // reconfigurar en caliente
toaster.set({ theme: "dark" });
toaster.set({ styles: { badge: "ring-1" } }); // se mezcla con lo que hubiera
toaster.config;                               // la config actual
toaster.destroy();                            // desmontar y limpiar

Cada posición es un stack independiente, con su propia fila de tabs y su propio foco.

Exports

Y desde sileojs/vue:

Interacción

• Cursor encima → se abre el panel y se pausa el auto-cierre de todos los toasts.
• Cursor ya quieto ahí → cuenta igual. Si el toast nace debajo del puntero no hay pointerenter que valga, así que Sileo mira dónde está el cursor al montar y al recolocar: el panel se queda abierto hasta que salga.
• Cursor a otra tab → el enfoque salta a esa: se ensancha, muestra su título y abre su mensaje.
• Arrastrar en vertical más de 30 px → se descarta.
• Teclado → cada toast es enfocable; al recibir el foco se comporta como si tuviera el cursor encima.
• prefers-reduced-motion → se desactiva todo el movimiento.

El toast de estado loading nunca se despliega ni se auto-cierra: está esperando a que lo actualices.

La fila de tabs

Varias notificaciones en la misma posición no se apilan como lista: forman una fila de pestañas solapadas a la altura del título. Solo baja el panel de la enfocada.

• Las tabs de atrás enseñan solo su icono, y el icono se arrima al borde por el que asoma la tab —en las posiciones de la derecha la fila crece hacia dentro y asoma el lado izquierdo; en las de la izquierda y el centro, el derecho—. Vale igual en reposo y con el cursor encima.
• El enfoque es la tab del borde de la pantalla, el toast más nuevo. Un toast nuevo se lleva el enfoque.
• Al entrar el cursor la baraja se abre: aparecen todas las notificaciones —el corte de tres es solo para el reposo— y la del frente abre su panel.
• Solo la tab enfocada se ensancha; las demás se quedan en su icono. Pero se ensancha siempre al mismo ancho, el de la más ancha del stack: así lo que crece compensa lo que se corre y la tab que señalas no se escapa del puntero. Si midiera lo suyo, al enfocar una de título corto el foco saltaría a la vecina.
• La enfocada conserva su z-index natural: va por debajo de las que tiene delante y por encima de las de atrás, como una pestaña. Si se pusiera encima de todo, al enfocar una del medio se comería a las que quedan entre ella y el borde. Su contenido arranca pasado el trozo que le tapa la de delante, para que el icono y el título se vean enteros.
• Si la fila no cabe, se recorta primero el ancho de la enfocada y luego lo que asoma de cada icono: una tab fuera del viewport quedaría fuera de la zona de hover.
• En reposo se ven 3 tabs (--sileo-stack-max o visibleToasts) y, si hay más, aparece un + al final del mazo: solo avisa de que quedan otras, el número exacto se ve al abrir la fila. La enfocada nunca se oculta, aunque lleguen toasts nuevos.

Las posiciones salen de una sola recurrencia, del borde hacia dentro:

x[0]     = 0
x[i+1]   = x[i] + ancho(i) - tab-overlap

// en reposo
ancho(i) = (i enfocada ? ancho de su cápsula : alto del toast)

// la enfocada, siempre al mismo ancho
ancho(i) = (i enfocada ? max(ancho de cada cápsula) : alto del toast)
//          ^ acotado para que la fila quepa en el viewport

Autopilot

Un toast nuevo se abre solo un momento para que se lea el mensaje, y se cierra pasados unos segundos. Por defecto se abre a los 150 ms y se cierra a los 4 s (siempre dentro de su duration).

sileo.info({ title: "Sin autopilot", autopilot: false });

sileo.info({
  title: "A mi ritmo",
  description: "Se abre en seguida y se queda 8 segundos.",
  duration: 10000,
  autopilot: { expand: 0, collapse: 8000 },
});

Variables CSS

Todo se ajusta con custom properties; sobrescríbelas donde quieras.

:root {
  /* forma */
  --sileo-width: 350px;
  --sileo-height: 40px;
  --sileo-roundness: 16px;
  --sileo-gap: 12px;              /* separación del borde de la pantalla */

  /* movimiento */
  --sileo-duration: 600ms;
  --sileo-spring-easing: linear(…);   /* el spring, ya linealizado */
  --sileo-ease-flat: cubic-bezier(0.32, 0.72, 0, 1);

  /* fila de tabs */
  --sileo-tab-overlap: 18px;      /* solape en reposo */
  --sileo-tab-overlap-hot: 12px;  /* solape con el cursor dentro */
  --sileo-stack-max: 3;           /* tabs visibles */
  --sileo-shadow: drop-shadow(0 2px 8px rgb(0 0 0 / 0.18));

  /* color */
  --sileo-fill: #ffffff;
  --sileo-state-success: oklch(0.723 0.219 142.136);
  --sileo-state-error:   oklch(0.637 0.237 25.331);
  --sileo-state-warning: oklch(0.795 0.184 86.047);
  --sileo-state-info:    oklch(0.685 0.169 237.323);
  --sileo-state-action:  oklch(0.623 0.214 259.815);
  --sileo-state-loading: oklch(0.556 0 0);
}

Temas

Con theme el toaster elige el relleno: en tema claro la cápsula es oscura y al revés. "system" sigue a prefers-color-scheme y reacciona a los cambios.

createToaster({ theme: "system" });   // "light" | "dark" | "system"

Si no pasas theme, manda el CSS: el relleno es --sileo-fill. Y siempre puedes fijarlo por toast con fill.

Estilos por parte

styles es un objeto parte → estilo. No hay nada de ningún framework en él: lo que le pasas son clases, propiedades CSS, o las dos. Va por toast (styles) o para todos (options.styles del toaster).

Tres formas, y se pueden mezclar entre partes:

createToaster({
  position: "top-right",
  options: {
    roundness: 14,
    styles: { toast: "top-90" },   // para todos los toasts
  },
});

sileo.success({
  title: "Guardado",
  description: "Todo listo.",
  styles: {
    toast: "rounded-2xl shadow-lg",                     // clases
    description: { color: "#64748b", fontSize: "13px" }, // propiedades CSS
    badge: { class: "ring-1", style: { "--sileo-roundness": "20px" } },
  },
});

Si prefieres apuntar al DOM, cada parte tiene su atributo: [data-sileo-toast], [data-sileo-header], [data-sileo-badge], [data-sileo-title], [data-sileo-description], [data-sileo-button].

Cambios en caliente

Tema, posición y estilos se pueden cambiar en cualquier momento, y lo que ya está en pantalla se reajusta: los toasts cambian de relleno, se mudan al viewport nuevo y se repintan con los estilos nuevos. configure() no necesita el toaster ni ningún adaptador, así que sirve igual en vanilla, React, Svelte o Angular.

import { configure, sileo } from "sileojs";

configure({ theme: "dark" });                 // o sileo.setTheme("dark")
configure({ position: "bottom-center" });     // o sileo.setPosition(…)
configure({ styles: { toast: "top-90" } });   // o sileo.setStyles(…)

sileo.getConfig();  // { position, theme, resolvedTheme, offset, options, styles }

Accesibilidad

• Cada posición es un <section role="status" aria-live="polite">: los lectores de pantalla anuncian el toast al aparecer, sin interrumpir.
• La raíz de cada toast es un <button> enfocable, con aria-label igual al título.
• Al recibir el foco por teclado se abre el panel, igual que con el cursor.
• Las tabs que pasan del máximo visible se ocultan con visibility: hidden, así que salen del orden de tabulación.
• Con prefers-reduced-motion: reduce no queda ninguna animación ni transición.

Compatibilidad

Chrome/Edge 113+, Safari 16.4+ y Firefox 128+. Sin build step y sin dependencias.

Cómo funciona

El efecto de fundido son dos rectángulos y un filtro SVG:

• La cápsula y el panel son dos div con border-radius, dentro de una capa filtrada.
• El filtro difumina y luego sube el contraste del alfa (×20 −10): eso convierte el blur en un borde duro, y ahí es donde dos formas cercanas se funden.
• El color del puente no sale del blur —en sRGB sin premultiplicar lo transparente es negro y saldría gris—: se inunda con --sileo-fill y se recorta con el alfa del umbral.
• Al abrirse, la cápsula crece hacia el panel para provocar el solape.
• Las posiciones de abajo reusan la misma geometría con scaleY(-1).
• La sombra va después del filtro en la cadena, sobre la silueta ya fundida.

El JS solo publica medidas —--_pw (ancho de la cápsula), --_ch (alto del contenido), --_tx (sitio en la fila)— y el CSS deriva de ahí toda la geometría con calc() y max().