@thecoderzeus/scroll-reveal-fx

Suite de animações para scroll e mouse, sem dependências, focada em performance e API direta.

O que mudou na v1.2.0

• Correção de gatilhos (trigger) no revealOnScroll para funcionar com múltiplos elementos.
• Correção de efeitos que falhavam em sequência (wave, cascade, colorPulse, typewriter, magnetism).
• Hardening de segurança/estabilidade com validação de seletor, cor CSS e valores numéricos.
• Todas as funções agora retornam controller com destroy() para limpar listeners/observers.
• Novos efeitos: applyElasticReveal e applyGlowReveal.
• Documentação reorganizada e simplificada.

Instalação

npm install @thecoderzeus/scroll-reveal-fx

Uso rápido

import { revealOnScroll, applyElasticReveal } from '@thecoderzeus/scroll-reveal-fx';

revealOnScroll({
  selector: '.feature-card',
  effect: 'slide',
  direction: 'up',
  stagger: 120
});

applyElasticReveal({
  selector: '.hero-title',
  duration: 900
});

Exportações

import {
  revealOnScroll,
  animateText,
  drawSVG,
  applyParallax,
  scrubAnimation,
  createTimeline,
  createScrollSpy,
  applyTilt,
  applyMagnetism,
  applyWaveReveal,
  applyFlip3D,
  applyColorPulse,
  applyZoomBlur,
  applySkewReveal,
  applyMaskWipe,
  applyCascadeReveal,
  applyElasticReveal,
  applyGlowReveal
} from '@thecoderzeus/scroll-reveal-fx';

API principal

revealOnScroll(options)

Efeitos disponíveis em effect:

• fade
• slide
• scale
• blur
• flip
• rotate
• roll
• flicker
• pop
• swing
• custom

Opções:

| Opção | Tipo | Padrão | | :--- | :--- | :--- | | selector | string | '.reveal' | | trigger | string \| HTMLElement | null | | effect | string | 'fade' | | direction | 'up' \| 'down' \| 'left' \| 'right' | 'up' | | threshold | number | 0.25 | | duration | number | 800 | | delay | number | 0 | | stagger | number | 150 | | easing | string | 'cubic-bezier(0.5, 0, 0, 1)' | | once | boolean | true | | reset | boolean | false | | onReveal | (el: HTMLElement) => void | null | | onComplete | (el: HTMLElement) => void | null | | onReset | (el: HTMLElement) => void | null | | customClassName | string | 'is-visible' | | indexAttribute | string \| null | null |

Retorno:

const controller = revealOnScroll({ selector: '.card' });
controller.destroy();

animateText(options)

• Divide por chars ou words
• Suporta randomOrder
• Suporta modo especial typewriter

animateText({
  selector: '.headline',
  splitType: 'chars',
  effect: 'pop',
  randomOrder: true,
  stagger: 25
});

animateText({
  selector: '.terminal-line',
  effect: 'typewriter',
  typewriterSpeed: 32,
  once: false
});

drawSVG(options)

drawSVG({
  selector: '#logo',
  duration: 2200,
  stagger: 180,
  once: true
});

applyParallax(options)

applyParallax({
  selector: '.parallax-layer',
  intensity: 0.25,
  threshold: 120
});

scrubAnimation(options)

scrubAnimation({
  trigger: '#track',
  target: '.cube',
  from: { rotate: 0, scale: 0.7, opacity: 0.2 },
  to: { rotate: 180, scale: 1, opacity: 1 },
  startOffset: 100,
  endOffset: -50
});

createTimeline(options)

const tl = createTimeline({ trigger: '#hero', once: true });

tl
  .add({ selector: '.hero-title', effect: 'slide', direction: 'up' })
  .add({ selector: '.hero-subtitle', effect: 'fade', delay: 120 })
  .add({ selector: '.hero-cta', effect: 'pop', delay: 80 });

createScrollSpy(options)

createScrollSpy({
  links: '.nav-link',
  sections: '.content-section',
  activeClassName: 'is-active',
  rootMargin: '-45% 0px -45% 0px'
});

Efeitos de elemento

Todos os efeitos abaixo seguem o mesmo padrão:

• selector
• duration
• easing
• once
• reset
• threshold

applyWaveReveal

applyWaveReveal({ selector: '.wave-item', stagger: 90 });

applyFlip3D

applyFlip3D({ selector: '.flip-card' });

applyColorPulse

applyColorPulse({ selector: '.pulse-box', pulseColor: '#14d9a6', once: false, reset: true });

applyZoomBlur

applyZoomBlur({ selector: '.zoom-item', blur: 6, scale: 0.84 });

applySkewReveal

applySkewReveal({ selector: '.skew-item', axis: 'x', angle: 8, distance: 24 });

applyMaskWipe

applyMaskWipe({ selector: '.wipe-item', direction: 'left' });

applyCascadeReveal

applyCascadeReveal({
  selector: '.list',
  childSelector: '.list-item',
  stagger: 110
});

applyElasticReveal (novo)

applyElasticReveal({
  selector: '.elastic-block',
  distance: 30,
  duration: 900
});

applyGlowReveal (novo)

applyGlowReveal({
  selector: '.neon-title',
  glowColor: 'rgba(80, 220, 255, 0.7)',
  glowSize: 28
});

Efeitos de mouse

applyTilt

applyTilt({ selector: '.tilt-card', intensity: 14, perspective: 1200 });

applyMagnetism

applyMagnetism({ selector: '.magnetic-btn', intensity: 0.25, threshold: 120, scale: 1.08 });

Segurança e robustez

• Seletores inválidos não quebram mais a execução da biblioteca.
• Valores numéricos críticos agora são normalizados e limitados.
• Cores customizadas passam por validação (CSS.supports) quando disponível.
• Typewriter usa textContent para evitar parsing HTML acidental.
• Cada módulo expõe destroy() para limpeza de observers/listeners.

Contribuição

PRs e issues são bem-vindos.

1. Faça fork do projeto.
2. Crie uma branch (feat/nome ou fix/nome).
3. Adicione testes/exemplo de uso quando possível.
4. Abra PR com contexto objetivo do problema e solução.

Licença

MIT