wissfort

Introducción

Librería de notificaciones toast headless y sin dependencias de runtime. El núcleo (wiss) es un "cerebro" de TypeScript puro —estado, cola, timers— que no sabe nada del DOM ni de ningún framework. La capa visual es intercambiable: por defecto trae sus propios temas (light y dark) o puedes optar por heredar el tema de tu proyecto vía daisyUI o shadcn/ui para que se adapte a tu diseño actual.

Instalación

pnpm add wissfort

pnpm add wissfort

Sonido e Interacciones

wissfort utiliza con gran énfasis cuelume para su sistema de sonido. Esta increíble librería sintetiza el audio en vivo sin usar pesados archivos .mp3, manteniendo el impacto en el rendimiento completamente nulo (menos de 40 KB descomprimida).

El sonido viene activado por defecto, pero si deseas desactivarlo globalmente, puedes hacerlo en la configuración:

import { toaster } from 'wissfort';

toaster({ sound: false });

import { toaster } from 'wissfort';

toaster({ sound: false });

También puedes personalizar el sonido que se reproduce al lanzar una notificación individual pasando el nombre del sonido en la opción sound:

toast.info('Notificación con sonido especial', { sound: 'sparkle' });

toast.info('Notificación con sonido especial', { sound: 'sparkle' });

Sonidos por defecto:

Cada tipo de toast trae un sonido de cuelume preasignado que encaja perfectamente con su intención:

success: success
error: press
warning: chime
info: droplet
loading: bloom

Catálogo de Sonidos Interactivo

Explora todos los sonidos disponibles haciendo clic en los siguientes botones. Cada uno ejecutará un toast de información pero con su respectivo sonido personalizado.

import { toast } from 'wissfort';

// Prueba cualquier sonido personalizado
toast.info('Chime sonando', { sound: 'chime' });
toast.info('Mensaje discreto', { sound: 'whisper' });
toast.info('Error mecánico', { sound: 'toggle' });

import { toast } from 'wissfort';

// Prueba cualquier sonido personalizado
toast.info('Chime sonando', { sound: 'chime' });
toast.info('Mensaje discreto', { sound: 'whisper' });
toast.info('Error mecánico', { sound: 'toggle' });

Uso básico

Importa la función toast para lanzar notificaciones de diferentes tipos.

Notificaciones Simples

import { toast } from 'wissfort';

toast.success('Usuario creado');
toast.error('Algo salió mal');
toast.warning('Revisa este campo');
toast.info('Nueva actualización disponible');

import { toast } from 'wissfort';

toast.success('Usuario creado');
toast.error('Algo salió mal');
toast.warning('Revisa este campo');
toast.info('Nueva actualización disponible');

💡 Puedes editar el código de cualquier ejemplo en su pestaña "Code" y ejecutarlo en vivo.

Toast con Acción (Action)

import { toast } from 'wissfort';

toast.show('Elemento eliminado', { 
  action: { 
    label: 'Deshacer', 
    onClick: () => toast.success('Acción deshecha correctamente') 
  } 
});

import { toast } from 'wissfort';

toast.show('Elemento eliminado', { 
  action: { 
    label: 'Deshacer', 
    onClick: () => toast.success('Acción deshecha correctamente') 
  } 
});

Toast con Promesa (Promise)

import { toast } from 'wissfort';

toast.promise(
  fetch('/api/users'),
  {
    loading: 'Cargando usuarios...',
    success: 'Usuarios cargados correctamente',
    error: 'Error al cargar usuarios',
  }
);

import { toast } from 'wissfort';

toast.promise(
  fetch('/api/users'),
  {
    loading: 'Cargando usuarios...',
    success: 'Usuarios cargados correctamente',
    error: 'Error al cargar usuarios',
  }
);

Opciones por Toast

Puedes pasar un objeto de configuración como segundo parámetro a cualquier método para personalizar un toast individual.

Toast con Descripción

import { toast } from 'wissfort';

toast.success('¡Archivo guardado!', {
  description: 'El archivo se guardó correctamente en tu carpeta local.'
});

import { toast } from 'wissfort';

toast.success('¡Archivo guardado!', {
  description: 'El archivo se guardó correctamente en tu carpeta local.'
});

Cambio de Icono

O elige un icono para probar:

import { toast } from 'wissfort';

toast.info('Nueva actualización', {
  icon: '🚀' // Puedes pasar un string, HTML o SVG
});

import { toast } from 'wissfort';

toast.info('Nueva actualización', {
  icon: '🚀' // Puedes pasar un string, HTML o SVG
});

Barra de Progreso

import { toast } from 'wissfort';

toast.info('Descargando archivo...', {
  duration: 5000,
  progressBar: true
});

import { toast } from 'wissfort';

toast.info('Descargando archivo...', {
  duration: 5000,
  progressBar: true
});

Historial

Wissfort mantiene un registro de los toasts que han aparecido en pantalla. Puedes acceder a ellos o limpiarlos mediante la API.

import { toast } from 'wissfort';

const historial = toast.history();
console.log(historial); // Array con los toasts anteriores

// Para limpiar el historial:
// toast.clearHistory();

import { toast } from 'wissfort';

const historial = toast.history();
console.log(historial); // Array con los toasts anteriores

// Para limpiar el historial:
// toast.clearHistory();

Configuración Global

La función toaster() acepta un objeto para configurar el comportamiento global de todos los toasts.

Modo Oscuro / Claro

import { toaster } from 'wissfort/vanilla';

// Cambia globalmente el tema visual
toaster({ theme: 'neon' }); // 'light' | 'dark' | 'neon' | 'pastel' | 'brutal' | 'pop' | 'shadcn'

import { toaster } from 'wissfort/vanilla';

// Cambia globalmente el tema visual
toaster({ theme: 'neon' }); // 'light' | 'dark' | 'neon' | 'pastel' | 'brutal' | 'pop' | 'shadcn'

Formato de Diseño (Wiss vs Island)

Puedes cambiar la estética de las notificaciones entre un diseño clásico o de tipo "isla dinámica".

import { toaster } from 'wissfort/vanilla';

// wiss: Bordes definidos
// island: Diseño más suave e integrado
toaster({ format: 'island' });

import { toaster } from 'wissfort/vanilla';

// wiss: Bordes definidos
// island: Diseño más suave e integrado
toaster({ format: 'island' });

Límite de Toasts

import { toaster } from 'wissfort/vanilla';

// Máximo de toasts visibles al mismo tiempo
toaster({ maxToasts: 2 });

import { toaster } from 'wissfort/vanilla';

// Máximo de toasts visibles al mismo tiempo
toaster({ maxToasts: 2 });

Comportamiento (Replace Behavior)

Controla qué sucede cuando se alcanza el límite. normal apila las notificaciones, wiss reemplaza visualmente la más antigua con una animación.

import { toaster } from 'wissfort/vanilla';

toaster({ replaceBehavior: 'wiss' }); // 'normal' | 'wiss'

import { toaster } from 'wissfort/vanilla';

toaster({ replaceBehavior: 'wiss' }); // 'normal' | 'wiss'

Uso en Astro

---
// Layout.astro
---
<slot />
<script>
  import { toaster } from 'wissfort/vanilla';
  toaster();
</script>

---
// Layout.astro
---
<slot />
<script>
  import { toaster } from 'wissfort/vanilla';
  toaster();
</script>

Luego, desde cualquier componente o script del cliente:

import { toast } from 'wissfort';
toast.success('¡Listo!');

import { toast } from 'wissfort';
toast.success('¡Listo!');

Temas, daisyUI y shadcn/ui

Por defecto, la librería utiliza sus propios temas (light y dark) construidos con Tailwind. Esto permite que los toasts se vean bien automáticamente.

Integración con shadcn/ui

Si usas shadcn/ui (en Tailwind v4 o usando variables de colores absolutas/hex/oklch), wiss ahora incluye soporte nativo. Configura theme: 'shadcn' y los toasts mapearán automáticamente sus colores a las variables de tu proyecto (como --background, --foreground, --primary, --destructive, etc.):

import { toaster } from 'wissfort/vanilla';

toaster({
  theme: 'shadcn',
  position: 'bottom-right',
  duration: 4000,
});

import { toaster } from 'wissfort/vanilla';

toaster({
  theme: 'shadcn',
  position: 'bottom-right',
  duration: 4000,
});

Nota: Si estás usando una versión más antigua de shadcn donde las variables solo exportan los valores HSL sueltos (ej. 0 0% 100%), puedes seguir usando theme: 'light' o 'dark' y mapear las variables --wiss-* en tu archivo globals.css envolviéndolas en la función hsl().

Integración con daisyUI

Si prefieres que los toasts hereden el estilo activo de daisyUI (claro, oscuro, cyberpunk, etc.), puedes usar theme: 'daisy':

import { toaster } from 'wissfort/vanilla';

toaster({
  theme: 'daisy', // 'dark' (default) | 'light' | 'shadcn' | 'daisy'
  position: 'bottom-right',
  duration: 4000,
  offset: 16,
});

import { toaster } from 'wissfort/vanilla';

toaster({
  theme: 'daisy', // 'dark' (default) | 'light' | 'shadcn' | 'daisy'
  position: 'bottom-right',
  duration: 4000,
  offset: 16,
});

Con theme: 'daisy', wiss inyecta las clases de daisyUI (alert, alert-success, alert-error, ...) en vez de las suyas propias. Así, el color final lo resuelve el tema de daisyUI configurado en tu proyecto.

Si no necesitas integrarlo con daisyUI o prefieres los estilos que trae wiss de base, simplemente no envíes la propiedad theme (o usa 'light'/'dark') y usará el tema predeterminado.

Configuración de Tailwind CSS

Los temas de wiss traen clases utilitarias integradas en el código de la librería (node_modules). Para que los estilos se apliquen correctamente, debes indicarle a Tailwind que procese estos archivos.

Para Tailwind CSS v4 (y DaisyUI 5)

En la versión 4, Tailwind utiliza una configuración basada en CSS. Simplemente añade la directiva @source en tu archivo CSS principal (donde importas tailwind) apuntando a la librería:

/* app.css o globals.css */
@import "tailwindcss";
@source "../node_modules/wiss"; /* Ajusta la ruta si es necesario */

/* app.css o globals.css */
@import "tailwindcss";
@source "../node_modules/wiss"; /* Ajusta la ruta si es necesario */

Para Tailwind CSS v3 (y DaisyUI 4)

Si sigues usando la versión 3 de Tailwind, debes agregar la ruta de wiss al array content en tu archivo de configuración:

// tailwind.config.js
export default {
  content: [
    './src/**/*.{astro,html,js,ts,vue,svelte,tsx}',
    './node_modules/wiss/dist/**/*.{js,mjs}',
  ],
  // ...
};

// tailwind.config.js
export default {
  content: [
    './src/**/*.{astro,html,js,ts,vue,svelte,tsx}',
    './node_modules/wiss/dist/**/*.{js,mjs}',
  ],
  // ...
};

Uso en React

import { Toaster } from 'wissfort/react';
import { toast } from 'wissfort';

function App() {
  return (
    <>
      <Toaster position="bottom-right" theme="dark" />
      <button onClick={() => toast.success('¡Hecho!')}>Notify</button>
    </>
  );
}

import { Toaster } from 'wissfort/react';
import { toast } from 'wissfort';

function App() {
  return (
    <>
      <Toaster position="bottom-right" theme="dark" />
      <button onClick={() => toast.success('¡Hecho!')}>Notify</button>
    </>
  );
}

Uso en Vue

<script setup>
import { Toaster } from 'wissfort/vue';
import { toast } from 'wissfort';
</script>

<template>
  <Toaster position="bottom-right" theme="dark" />
  <button @click="toast.success('¡Hecho!')">Notify</button>
</template>

<script setup>
import { Toaster } from 'wissfort/vue';
import { toast } from 'wissfort';
</script>

<template>
  <Toaster position="bottom-right" theme="dark" />
  <button @click="toast.success('¡Hecho!')">Notify</button>
</template>

Uso en Svelte

Para Svelte 5:

<script>
  import { toaster } from 'wissfort/svelte';
  import { toast } from 'wissfort';

  $effect(() => toaster({ position: 'bottom-right', theme: 'dark' }));
</script>

<button onclick={() => toast.success('¡Hecho!')}>Notify</button>

<script>
  import { toaster } from 'wissfort/svelte';
  import { toast } from 'wissfort';

  $effect(() => toaster({ position: 'bottom-right', theme: 'dark' }));
</script>

<button onclick={() => toast.success('¡Hecho!')}>Notify</button>

Para Svelte 3/4:

<script>
  import { onMount } from 'svelte';
  import { toaster } from 'wissfort/svelte';
  import { toast } from 'wissfort';

  onMount(() => toaster({ position: 'bottom-right', theme: 'dark' }));
</script>

<button on:click={() => toast.success('¡Hecho!')}>Notify</button>

<script>
  import { onMount } from 'svelte';
  import { toaster } from 'wissfort/svelte';
  import { toast } from 'wissfort';

  onMount(() => toaster({ position: 'bottom-right', theme: 'dark' }));
</script>

<button on:click={() => toast.success('¡Hecho!')}>Notify</button>

Roadmap

Fuera de alcance en esta fase, planeado para más adelante:

Mejora del sitio web/Docs
Demo de uso de los adaptadores para frameworks.
Añadir nuevos formatos: customizados para usuarios que no usan daisyui ni shadcn/ui.
Añadir nuevas animaciones y que estén en la documentación.
Implementar mejoras en el rendimiento.
Añadir nuevos iconos para las notificaciones.
Añadir nuevos sonidos para las notificaciones.

Créditos

Diseño Visual: La estética base (con efectos de glassmorphism y bordes suaves) está inspirada en el diseño de Sileo UI (GitHub).
Sonido de notificación: los mini sonidos de las notificaciones son de Cuelume (GitHub).

wissfort.