EzMouseTrail: Documentación

El ez-mouse-trail es un componente web de alto rendimiento diseñado para crear efectos de partículas interactivos. Aprovecha el sistema de fuentes variables Material Symbols y un motor de modificadores personalizados para permitir animaciones complejas como gravedad, fricción y trayectorias orbitales. (Pasa el ratón sobre el siguiente recuadro)

Implementación (Web-Component)

Después de haber instalado tu web-component, necesitas saber cómo añadir la estela de ratón a tu HTML.

Crucialmente, el ez-mouse-trail no escucha eventos de ratón globales. En su lugar, escucha los eventos de ratón de su contenedor padre. Esto te permite limitar el efecto de la estela a secciones específicas de tu interfaz o a páginas concretas sin interferencias.

Dado que la estela normalmente debe aparecer encima de tu contenido, necesitas apilarlos. Aunque position: absolute o flex son válidos, usar un apilamiento de CSS Grid es la forma más robusta de asegurar que tanto el contenido como la estela compartan exactamente el mismo espacio.

Patrón de Diseño: Superposición en Grid

<div
  style="display: grid; grid-template-columns: 1fr; width: 100%; height: 400px; border: 1px solid #333;"
>
  <div style="grid-area: 1 / 1; padding: 20px; z-index: 1;">
    <h1>Área Interactiva</h1>
    <p>
      La estela solo se activará al pasar el ratón dentro de este contenedor.
    </p>
    <button>Pásame el ratón</button>
  </div>

  <ez-mouse-trail
    style="grid-area: 1 / 1; pointer-events: none; z-index: 2;"
    icon-string="flare"
    modifier-string="vortex/50s50"
  >
  </ez-mouse-trail>
</div>

Consejo: No necesitas añadir pointer-events: none en el componente de la estela ya que lo hacemos automáticamente; sin embargo, puedes añadir otros pointer-events para anular este comportamiento.

Aunque Grid es el enfoque más moderno y limpio para apilar, existen varias otras formas de lograr el efecto de escucha en el padre dependiendo de la arquitectura CSS de tu proyecto.

Aquí tienes las alternativas comunes al apilamiento en Grid:

1. Posicionamiento Absoluto (La forma clásica)

Este es el método más común si tu contenedor ya tiene una altura definida o es parte de un diseño antiguo.

<div style="position: relative; width: 100%; height: 300px; overflow: hidden;">
  <div class="content">
    <h2>Contenedor Relativo</h2>
    <p>La estela llena el espacio absoluto de este padre.</p>
  </div>

  <ez-mouse-trail
    style="position: absolute; top: 0; left: 0; width: 100%; height: 100%; pointer-events: none;"
    ...props
  >
  </ez-mouse-trail>
</div>

2. Flexbox Stack (Enfoque de centrado)

Flexbox no está construido naturalmente para apilar en el eje Z, pero puedes usarlo para centrar contenido mientras una estela absoluta se sitúa detrás o delante.

<div
  style="display: flex; align-items: center; justify-content: center; position: relative; height: 300px;"
>
  <div style="z-index: 1;">
    <button>Botón Interactivo</button>
  </div>

  <ez-mouse-trail style="position: absolute; inset: 0; pointer-events: none;">
  </ez-mouse-trail>
</div>

3. Hack de Inset / Margen

Si no quieres usar width: 100%, puedes usar la abreviatura inset: 0 en un componente absoluto para forzarlo a coincidir exactamente con las dimensiones del padre. Aunque esto es algo inconsistente.

<div style="position: relative; padding: 50px; border: 2px dashed #444;">
  <p>Contenido de texto que dicta el tamaño del padre.</p>
  <ez-mouse-trail style="position: absolute; inset: 0;"></ez-mouse-trail>
</div>

Nota de Implementación: Por qué el padre importa

El componente vincula escuchadores (listeners) para mousemove, mousedown y mouseup directamente al parentElement.

1. Interacción Delimitada: Las partículas solo aparecen cuando el ratón está dentro de ese recuadro específico.

2. Limpieza Impecable: Si el padre se elimina del DOM, los escuchadores son recolectados por el recolector de basura automáticamente.

3. Consejo de Z-Index: Asegúrate siempre de que tu ez-mouse-trail tenga un z-index más alto que tu fondo pero pointer-events: none para que no bloquee los clics en tus elementos de la interfaz.

Propiedades

Los atributos se utilizan dentro de la etiqueta html de la siguiente manera:

<ez-mouse-trail nombre-propiedad="valor_propiedad"> </ez-mouse-trail>

Los tipos están ahí solo para aclaración; los web-components por defecto solo aceptan cadenas de texto (string), por lo que no pasarías propiedad=10 sino propiedad="10".

Configuración Principal

max-items

• Tipo: number
• Por defecto: 20
• Descripción: Limita el grupo de partículas activas. Una vez alcanzado este límite, no aparecerán nuevas partículas hasta que las antiguas desaparezcan. Valores altos (100+) pueden impactar en el rendimiento.

life-single

• Tipo: number (milisegundos)
• Por defecto: 1000
• Descripción: La duración que existe una partícula desde que aparece hasta que muere. Los modificadores pueden interactuar con este valor para crear efectos de desvanecimiento o escalado con el tiempo.

trail-behaviour

• Tipo: TrailBehaviour
• Por defecto: "hover"
• Valores válidos:
  • click: Genera partículas solo en el momento y lugar exacto de un clic del ratón.
  • hover: Genera partículas siguiendo el cursor del ratón mientras está dentro del contenedor.
  • drag: Las partículas solo aparecen si el botón del ratón se mantiene presionado mientras se mueve.
  • click_and_hover: Aparecen al pasar el ratón, pero crea una “fuente” persistente en los lugares donde se hace clic.
  • move: Similar a hover, pero requiere estrictamente que el ratón esté en movimiento para generarlas.
  • area: Ignora la posición del ratón; genera partículas aleatoriamente en cualquier lugar dentro de los límites del componente.

Lógica de Generación (Spawning)

spawn-behavior

• Tipo: SpawnBehavior
• Por defecto: "chance"
• Valores válidos:
  • timer: Genera partículas a un intervalo fijo.
  • chance: Genera basándose en una tirada de porcentaje calculada en cada frame.

spawn-variable

• Tipo: number
• Por defecto: 20
• Descripción: - Si spawn_behavior es timer: Representa partículas por segundo.
  • Si spawn_behavior es chance: Es la probabilidad en % (0-100) por cada frame.

click-duration

• Tipo: number (milisegundos)
• Por defecto: 1000
• Descripción: Específico para el comportamiento click_and_hover; determina cuánto tiempo permanece una coordenada clicada como punto de generación activo para nuevas partículas.

Sistema de Modificadores

modifier-string

• Tipo: string
• Por defecto: ""
• Descripción: Una lista de comportamientos separados por comas.
• Formato: nombre/principal/secundario
• Valores disponibles: el nombre es una cadena, tanto el principal como el secundario pueden ser positivos, negativos o cero. Para más información, consulta la parte de modificadores en esta página.
• Ejemplo: launch/10/45,friction/-10,bounds-bounce/100/5
• Nota: principal (normalmente de -100 a 100) y secundario (normalmente de 0 a 100) son parámetros que se pasan a las funciones matemáticas internas del modificador.

Visuales y Colores

icon-string

• Tipo: string
• Por defecto: ""
• Descripción: Una lista separada por comas de nombres de Material Icon (ej. heart,star,bolt). Si la cadena no es un nombre de icono válido, el componente renderizará el texto literal/unicode. En lugar de espacios (Ej: chevron right), los nombres usan guiones bajos (Ej: chevron_right).

icon-order

• Tipo: IconOrder
• Por defecto: "random"
• Valores válidos: random, sequence (sigue el orden definido en icon_string).

color-string

• Tipo: string
• Por defecto: ""
• Descripción: Una lista de colores hex separados por comas. El componente alterna entre estos al generar partículas. Soporta hex estándar o hex con alfa (ej. #FF000088).

default-color

• Tipo: string (Hex)
• Por defecto: "#ffffff"
• Descripción: El color de reserva utilizado si color_string está vacío.

icon-size

• Tipo: number (píxeles)
• Por defecto: 20
• Descripción: El tamaño base en píxeles CSS para los iconos renderizados.

icon-resolution

• Tipo: number
• Por defecto: 1.5
• Descripción: Escalado interno del lienzo (canvas) para los iconos. Valores más altos proporcionan iconos más nítidos pero requieren más memoria.

Tipografía (Estilo de Material Symbols)

font-style

• Tipo: FontStyle
• Por defecto: "Rounded"
• Valores válidos: Outlined, Rounded, Sharp.

font-type

• Tipo: FontType
• Por defecto: "fill"
• Valores válidos: fill (sólido), nofill (contorno).

font-optical-size

• Tipo: number
• Por defecto: 24
• Valores válidos: 20, 24, 40, 48.

font-weight

• Tipo: number
• Por defecto: 400
• Rango: 100 a 900.

font-grade

• Tipo: number
• Por defecto: 0
• Rango: Típicamente -25 a 200. Ajusta el grosor de los trazos del icono.

Modificadores

Los modificadores se aplican mediante la propiedad modifier_string. Formato: nombre_modificador/valor_principal/valor_secundario Ejemplo: launch/15/90,friction/5,gravity/10/-180

Modificadores direccionales:

launch

• Uso: launch/velocidad/direccion_grados
• Lógica: Un modificador de “un solo disparo” que otorga un impulso inicial de velocidad.
• Parámetros: principal es la velocidad (por defecto 10), secundario es el ángulo en grados (por defecto 0).

friction

• Uso: friction/cantidad
• Lógica: Reduce gradualmente la velocidad. Esencial para que “launch” o “influence” se sientan naturales.
• Parámetros: principal es el porcentaje de frenado (por defecto 5).

gravity

• Uso: gravity/fuerza/angulo
• Lógica: Empuje constante en una dirección específica.
• Parámetros: principal es la fuerza de aceleración, secundario es la dirección en grados (90 es hacia abajo).

drunken

• Uso: drunken/velocidad/factor
• Lógica: Añade un movimiento errático tipo browniano a las partículas.
• Parámetros: principal es la velocidad del movimiento, secundario es la frecuencia de los cambios de dirección.

jitter

• Uso: jitter/intensidad
• Lógica: Añade micro-vibraciones aleatorias a la posición de la partícula en cada frame.

Interacción con el Ratón

influence

• Uso: influence/fuerza/radio
• Lógica: Atrae o repele partículas cerca del ratón.
• Parámetros: principal es la fuerza (positivo para repeler, negativo para atraer), secundario es el radio de efecto.

vortex

• Uso: vortex/area/velocidad
• Lógica: Las partículas orbitan el cursor del ratón mientras son atraídas hacia adentro.

orbit

• Uso: orbit/velocidad/zona_muerta
• Lógica: Simula una gravedad planetaria hacia el cursor del ratón.

sticky_trail

• Uso: sticky_trail/velocidad/zona_limpia
• Lógica: Las partículas son “succionadas” por la estela del ratón mientras este se mueve.

Gestión de Vida y Estado

alive_always:

Mantiene las partículas al 100% de vida indefinidamente.

alive_mouseover:

Mantiene las partículas vivas solo mientras el ratón está dentro del componente.

alive_mousedown:

Mantiene las partículas vivas solo mientras el botón del ratón está presionado.

alive_mousemove:

Mantiene las partículas vivas solo mientras el ratón está en movimiento activo.

Comportamientos de Cadena y Seguimiento

chain

• Uso: chain/velocidad/friccion
• Lógica: Las partículas se siguen unas a otras en una cadena literal. El índice 0 sigue al ratón.

chain_rotate:

Los hijos en una cadena apuntan hacia su partícula “padre”; puede usarse sin el modificador chain.

chain_scale:

Encoge gradualmente las partículas basándose en su índice en la cadena; puede usarse sin el modificador chain.

chain_fade:

Desvanece gradualmente las partículas basándose en su índice en la cadena; puede usarse sin el modificador chain.

Oscilación y Forma

wave_h / wave_v

• Uso: wave_h/intensidad/frecuencia
• Lógica: Oscilación de onda senoidal en el eje horizontal (h) o vertical (v).

spiral

• Uso: spiral/velocidad/rango
• Lógica: Fuerza a las partículas a seguir una trayectoria espiral matemática desde su punto de origen.

pulse

• Uso: pulse/intensidad/frecuencia
• Lógica: Escalado rítmico (crecimiento y encogimiento).

flow_field

• Uso: flow_field/escala/fuerza
• Lógica: Mueve las partículas basándose en un campo trigonométrico de coordenadas (simula viento o agua).

Límites (Boundaries)

bounds_bounce

• Uso: bounds_bounce/elasticidad/relleno
• Lógica: Las partículas rebotan en los bordes del componente. principal es la elasticidad (0-100).

bounds_wrap

• Uso: bounds_wrap/relleno
• Lógica: Las partículas que salen por un lado reaparecen por el lado opuesto.

Estado Inicial (Un solo disparo)

Estos modificadores solo se ejecutan una vez cuando la partícula se crea por primera vez.

init_offset:

init_offset/x/y - Comienza la partícula en un desplazamiento fijo.

init_random:

init_random/rangoX/rangoY - Comienza la partícula dentro de un área aleatoria.

init_rotation:

init_rotation/angulo - Establece la rotación inicial.

init_rotation_random:

init_rotation_random/rango - Establece una rotación inicial aleatoria.

init_velocity_random:

init_velocity_random/grado_min/grado_max - Aleatoriza la dirección de la velocidad existente.

init_scale:

init_scale/valor - Establece el tamaño inicial.

init_scale_random:

init_scale_random/bajo/alto - Establece un tamaño inicial aleatorio.

Efectos Visuales

hue_cycle

• Uso: hue_cycle/velocidad/ajuste_saturacion
• Lógica: Alterna el color de la partícula a través del espectro HSL a lo largo de su vida.

rotate

• Uso: rotate/velocidad/aleatoriedad
• Lógica: Rotación continua. secundario determina la probabilidad (0-100) de girar en sentido antihorario.

size_drift

• Uso: size_drift/velocidad
• Lógica: Escala la partícula hacia arriba o hacia abajo; no usar con modificadores de tipo “alive” ya que podría crecer/encogerse para siempre.