wisspop

wisspop

Modales y dropdowns con animaciones ancladas al origen: el panel no aparece de la nada, nace del elemento que lo abrió y vuelve a él al cerrarse.

Un motor core sin framework (JS + GSAP) con adaptadores finos para Vue 3 y Vanilla JS (utilizable en cualquier framework o web vanilla).

Instalación

pnpm add wisspop gsap
# o con npm / yarn
npm install wisspop gsap

gsap (≥3.12) es dependencia requerida. vue (≥3.4) solo es necesaria si utilizas el wrapper de Vue.

Matriz de imports

Importación de CSS

import "wisspop/styles.css";

O en tu archivo CSS global:

@import "wisspop/styles.css";

El CSS no es decorativo, provee el posicionamiento position: fixed, gestión de recortes y apilado que el motor requiere. La apariencia (colores, bordes, sombras, tipografía) es 100% controlada por ti mediante tus clases CSS (modalClass, overlayClass).

Los z-index predeterminados pueden ajustarse mediante variables CSS:

:root {
  --wisspop-z-overlay: 40;
  --wisspop-z-box: 50;
  --wisspop-z-flying: 51;
  --wisspop-z-close: 101;
}

Tipos de Modales y Cuándo Usar Cada Uno

Buenas Prácticas y Rendimiento Móvil (60-120 FPS) ⚡📱

1. Aplica estilos en modalClass: Wisspop anima directamente su propio contenedor .wisspop-box. Pasa el fondo, bordes, redondeo y sombra a modalClass en lugar de crear una segunda caja contenedora en el slot.
2. flyingTextClass es exclusivo de WissPopPill: En WissPopMorph, usa encabezados HTML normales <h3> sin data-wisspop-title.
3. Define un ancho en el contenido: Para que GSAP calcule la geometría con precisión, dale un ancho explícito o responsivo (ej. style="width: min(24rem, calc(100vw - 2rem));").
4. Colores de fondo armónicos en el botón: WissPop interpola el backgroundColor del botón hacia el modal al abrir y de vuelta al cerrar. Mantén el botón en tonos armónicos/neutros y coloca los colores llamativos en iconos o badges.
5. Evita sombras difusas (box-shadow) en pantalla completa: Clases como shadow-2xl fuerzan el cálculo de 50px de blur perimetral que no es visible en 100vw. Usa sombras responsivas: class="shadow-none sm:shadow-2xl".
6. Usa h-full en lugar de min-h-[100dvh] dentro del slot: WissPop ya calcula y ajusta la altura exacta de la caja; usar 100dvh fuerza consultas redundantes al viewport dinámico móvil. Usa class="h-full sm:h-auto flex flex-col justify-between".

🚀 Arquitectura de Alto Rendimiento (GPU / CPU / VRAM)

WissPop incluye optimizaciones de bajo nivel para garantizar fluidez nativa a 60-120 FPS en dispositivos móviles:

• Aceleración por Capa GPU: .wisspop-box opera con transform: translateZ(0) y backface-visibility: hidden para que el navegador cree un contexto de composición independiente.
• Contención de Layout (contain: layout paint): Aísla el reflow durante la animación para que las mutaciones de geometría no invaliden el árbol DOM exterior (fondos, gradientes, textos).
• Gestión Dinámica de VRAM (will-change): La propiedad will-change se activa exclusivamente durante la interpolación activa y se libera a "auto" al completarse, garantizando cero consumo residual de memoria gráfica.
• Suavizado Inteligente de Curvas en Viewport Móvil: Al expandir a pantalla completa (fullscreenOnMobile), las curvas elásticas con overshoot (back.out) conmutan automáticamente a desaceleraciones suaves (power3.out) para evitar vibraciones del motor de scroll.
• contentBlur: false por Defecto: Elimina filtros de convolución gaussiana en tiempo real durante la expansión de la caja, liberando el fill-rate de la GPU móvil.

Guía de Uso

1. Vue 3 (Wrapper Nativo)

WissPop incluye componentes nativos para Vue 3 (WissPopMorph, WissPopPill, WissPopFlip):

<script setup>
import { ref } from 'vue';
import { WissPopMorph } from 'wisspop/vue';
import 'wisspop/styles.css';

const btn = ref(null);
const abierto = ref(false);
</script>

<template>
  <button ref="btn" @click="abierto = true">Abrir</button>

  <WissPopMorph
    v-model="abierto"
    :origin-ref="btn"
    placement="bottom"
    align="center"
    modalClass="panel"
  >
    <template #default="{ close }">
      <div class="panel-body" style="width: min(22rem, calc(100vw - 2rem));">
        <p>Contenido del modal</p>
        <button @click="close">Cerrar</button>
      </div>
    </template>
  </WissPopMorph>
</template>

2. Vanilla JS / Agnóstico

Puedes usar wisspop/vanilla en cualquier proyecto sin framework (o dentro de Astro, React, Svelte, etc.):

import { createModal } from 'wisspop/vanilla';
import 'wisspop/styles.css';

const modal = createModal({
  content: '<div class="p-6" style="width: min(22rem, calc(100vw - 2rem));">Contenido...</div>',
  placement: 'bottom',
  align: 'center',
  modalClass: 'panel',
  closeButton: true,
});

document.querySelector('#btn').addEventListener('click', (e) => {
  modal.open(e.currentTarget);
});

Texto e Icono Viajero (PillModal)

El segundo argumento de open() es el elemento o texto que viaja hacia data-wisspop-title:

modal.open(boton, "Crear cuenta");                    // Solo texto
modal.open(boton, boton.querySelector(".con-icono")); // Texto + icono
modal.open(boton, boton.querySelector("svg"));        // Solo icono (modo box)
modal.open(boton, boton.querySelector("img"));        // Imagen (modo box)

Métodos de la API

La instancia devuelta por createModal(), createMorph(), createFlipModal() o expuesta en las refs de los wrappers expone los siguientes métodos:

Opciones de Configuración

Accesibilidad (A11Y)

WissPop integra accesibilidad nativa lista para usar:

• Escape: Presionar la tecla Escape cierra el panel.
• Trampa de Foco: El foco del teclado queda atrapado en el modal activo.
• Restauración de Foco: El foco retorna automáticamente al elemento disparador al cerrar.
• Semántica ARIA: Inyección automática de role="dialog", aria-modal="true", y aria-labelledby.
• prefers-reduced-motion: Si el usuario activó movimiento reducido en el SO, la librería salta directamente a la geometría final sin animar.

Alcance — Lo que NO hace

• No es un sistema de diseño: No incluye colores, sombras ni tipografía predeterminadas.
• No gestiona notificaciones / toasts globales: wisspop está enfocado en modales y paneles anclados al origen.
• No reemplaza a <dialog> estático: Si solo requieres una ventana estática sin animación anclada espacialmente, <dialog> nativo es una alternativa válida.