@thecoderzeus/scroll-reveal-fx/README.MD

Uma suíte de animação de alta performance, modular e sem dependências, para criar interações ricas e elegantes baseadas no scroll e no mouse.

# @thecoderzeus/scroll-reveal-fx

[![NPM Version](https://img.shields.io/npm/v/@thecoderzeus/scroll-reveal-fx.svg)](https://www.npmjs.com/package/@thecoderzeus/scroll-reveal-fx)
[![License](https://img.shields.io/npm/l/@thecoderzeus/scroll-reveal-fx.svg)](https://github.com/thecoderzeus/scroll-reveal-fx/blob/main/LICENSE)

Uma suíte de animação de alta performance, modular e sem dependências, para criar interações ricas e elegantes baseadas no scroll e no mouse.

## Features

- **Animação de Revelação:** Efeitos de `fade`, `slide`, `scale`, `blur`, `flip`, `rotate`, `roll` e `flicker`.
- **Animação de Texto Avançada:** Modos de `typewriter`, ordem aleatória e múltiplos efeitos.
- **Animação de SVG:** Efeito de desenho de SVGs.
- **Animação Scrub:** Vincule o progresso de uma animação diretamente à posição do scroll.
- **Engine de Timeline:** Orquestre sequências de animações complexas com facilidade.
- **Efeitos de Mouse:** Adicione interatividade com efeitos como `tilt`.
- **Efeito Parallax:** Crie uma ilusão de profundidade com scroll.
- **Gatilhos e Callbacks:** Controle preciso sobre quando e como as animações acontecem.

## Installation

```bash
npm install @thecoderzeus/scroll-reveal-fx
# ou
yarn add @thecoderzeus/scroll-reveal-fx
```

## API e Módulos

A biblioteca é modular. Você pode importar somente o que precisa.

---

### 1. `revealOnScroll` (Core)

A função principal para animar elementos quando eles entram na tela.

**Importação:**
```javascript
import { revealOnScroll } from '@thecoderzeus/scroll-reveal-fx';
```

**Uso Básico:**
```javascript
revealOnScroll({
  selector: '.my-element',
  effect: 'slide',
  direction: 'up'
});
```

**Opções do Core:**

| Opção | Tipo | Padrão | Descrição |
| :--- | :--- | :--- | :--- |
| `selector` | `string` | `'.reveal'` | Seletor CSS para os elementos a serem animados. |
| `trigger` | `string | HTMLElement` | `null` | Seletor ou elemento que dispara a animação. Se `null`, o próprio elemento é o gatilho. |
| `effect` | `string` | `'fade'` | Efeito: `'fade'`, `'slide'`, `'scale'`, `'blur'`, `'flip'`, `'rotate'`, `'roll'`, `'flicker'`. |
| `threshold` | `number` | `0.25` | Porcentagem de visibilidade (0-1) para disparar a animação. |
| `duration` | `number` | `800` | Duração da animação em ms. |
| `delay` | `number` | `0` | Atraso inicial da animação em ms. |
| `stagger` | `number` | `150` | Atraso em ms entre cada elemento da sequência. |
| `easing` | `string` | `'cubic-bezier(0.5, 0, 0, 1)'` | Função de `easing` do CSS. |
| `once` | `boolean` | `true` | Se `true`, a animação ocorre apenas uma vez. |
| `reset` | `boolean` | `false` | Se `once: false`, reseta o elemento ao sair da tela. |
| `onReveal` | `function` | `null` | Callback executado quando a animação inicia. Recebe o elemento como argumento. |
| `onComplete`| `function` | `null` | Callback executado quando a animação termina. |
| `onReset` | `function` | `null` | Callback executado quando o elemento é resetado. |
| `customClassName` | `string` | `'is-visible'` | Classe CSS a ser aplicada quando `effect` é `'custom'`. |

**Usando `effect: 'custom'`**

Para controle total, você pode definir suas próprias animações em CSS. Ao usar `effect: 'custom'`, a biblioteca apenas adiciona a classe definida em `customClassName` ao elemento quando ele se torna visível.

**CSS:**
```css
/* Defina sua animação */
@keyframes fadeInRight {
  from {
    opacity: 0;
    transform: translateX(50px);
  }
  to {
    opacity: 1;
    transform: translateX(0);
  }
}

/* Oculte o elemento inicialmente */
.my-custom-animation {
  opacity: 0;
}

/* Aplique a animação quando a classe for adicionada */
.my-custom-animation.is-visible {
  animation: fadeInRight 1s forwards;
}
```

**JavaScript:**
```javascript
revealOnScroll({
  selector: '.my-custom-animation',
  effect: 'custom',
  // customClassName: 'is-visible' // Opcional, usa o padrão
});
```

---

### 2. `animateText`

Para animar texto com múltiplos efeitos.

**Importação:**
```javascript
import { animateText } from '@thecoderzeus/scroll-reveal-fx';
```

**Uso:**

**1. Efeitos Padrão (Fade, Slide, etc.)**
```javascript
// Anima cada letra com um efeito de 'fade' e ordem aleatória
animateText({
  selector: '.my-title',
  splitType: 'chars', // 'chars' ou 'words'
  effect: 'fade',     // Qualquer efeito do core: slide, scale, etc.
  randomOrder: true,  // Opcional: revela em ordem aleatória
  stagger: 30
});
```

**2. Efeito Máquina de Escrever (Typewriter)**
```javascript
// Simula o texto sendo digitado
animateText({
  selector: '.my-paragraph',
  effect: 'typewriter',
  typewriterSpeed: 40, // Velocidade em ms por caractere
  once: false,         // Opcional: repete a animação
  reset: true
});
```

**Opções Adicionais:**

| Opção | Tipo | Padrão | Descrição |
| :--- | :--- | :--- | :--- |
| `splitType`| `string` | `'chars'` | Como dividir o texto: `'chars'` ou `'words'`. Não se aplica ao `typewriter`. |
| `randomOrder`| `boolean` | `false` | Se `true`, revela as partes em ordem aleatória. Não se aplica ao `typewriter`.|
| `effect`| `string` | `'slide'` | Além dos efeitos do core, aceita `'typewriter'` para o modo especial. |
| `typewriterSpeed`| `number` | `50` | Velocidade em ms entre cada caractere no modo `typewriter`. |

*(Herda todas as outras opções do `revealOnScroll` para os efeitos padrão)*

---

### 3. `drawSVG`

Anima o traçado de caminhos (`<path>`) dentro de um SVG.

**Importação:**
```javascript
import { drawSVG } from '@thecoderzeus/scroll-reveal-fx';
```

**Uso:**
```html
<svg id="my-logo" ...>
  <path d="..."/>
  <path d="..."/>
</svg>
```
```javascript
drawSVG({
  selector: '#my-logo',
  duration: 3000,
  stagger: 300,
  once: false,
  reset: true
});
```
*(Herda opções de duração, stagger, delay, once, reset, etc.)*

---

### 4. `applyParallax`

Aplica um efeito de parallax a um elemento durante o scroll.

**Importação:**
```javascript
import { applyParallax } from '@thecoderzeus/scroll-reveal-fx';
```

**Uso:**
```javascript
applyParallax({
  selector: '.parallax-bg',
  intensity: 0.3
});
```

**Opções:**

| Opção | Tipo | Padrão | Descrição |
| :--- | :--- | :--- | :--- |
| `selector` | `string` | `'.parallax'` | Seletor para os elementos. |
| `intensity`| `number` | `0.2` | Força do efeito. Positivo = mais lento. Negativo = mais rápido. |
| `threshold`| `number` | `100` | Distância em px do viewport para iniciar o cálculo. |

---

### 5. `scrubAnimation`

Vincula o progresso de uma animação diretamente à posição da barra de rolagem.

**Importação:**
```javascript
import { scrubAnimation } from '@thecoderzeus/scroll-reveal-fx';
```

**Uso:**
```javascript
scrubAnimation({
  trigger: '#track',
  target: '.my-element',
  from: { rotate: 0, scale: 0.5 },
  to: { rotate: 180, scale: 1 },
  startOffset: 100, // Começa 100px depois do topo do trigger
  endOffset: -100   // Termina 100px antes do fundo do trigger
});
```

**Opções:**

| Opção | Tipo | Obrigatório | Descrição |
| :--- | :--- | :--- | :--- |
| `trigger` | `string|HTMLElement` | Sim | O elemento que serve como "pista" para o scroll. |
| `target` | `string|HTMLElement` | Sim | O elemento a ser animado. |
| `from` | `object` | Sim | Objeto com os estilos CSS iniciais. |
| `to` | `object` | Sim | Objeto com os estilos CSS finais. |
| `startOffset`| `number` | Não | Offset em pixels para o início da animação. |
| `endOffset`| `number` | Não | Offset em pixels para o fim da animação. |

---

### 6. `createTimeline`

Orquestra múltiplas animações a partir de um único gatilho.

**Importação:**
```javascript
import { createTimeline } from '@thecoderzeus/scroll-reveal-fx';
```

**Uso:**
```javascript
const myTimeline = createTimeline({ trigger: '#start-sequence' });

myTimeline
  .add({ selector: '.title', effect: 'slide', direction: 'down' })
  .add({ selector: '.subtitle', effect: 'fade' })
  .add({ selector: '.card', effect: 'scale', stagger: 100, once: false });
```

**Opções (`createTimeline`):**

| Opção | Tipo | Padrão | Descrição |
| :--- | :--- | :--- | :--- |
| `trigger` | `string|HTMLElement` | - | **Obrigatório.** O elemento que dispara a timeline. |
| `once` | `boolean` | `true` | Se a timeline deve rodar apenas uma vez. |
| `threshold`| `number` | `0.25` | Visibilidade para disparar a timeline. |

A função `.add()` aceita qualquer opção válida para `revealOnScroll`.

---

### 7. `createScrollSpy`

Cria um "espião de rolagem" que aplica uma classe ativa nos links de navegação conforme a seção correspondente entra no campo de visão.

**Importação:**
```javascript
import { createScrollSpy } from '@thecoderzeus/scroll-reveal-fx';
```

**Uso:**
```html
<nav>
  <a href="#section1" class="nav-link">Section 1</a>
  <a href="#section2" class="nav-link">Section 2</a>
</nav>
<main>
  <section id="section1" class="content-section">...</section>
  <section id="section2" class="content-section">...</section>
</main>
```
```javascript
createScrollSpy({
  links: '.nav-link',
  sections: '.content-section',
  activeClassName: 'is-active' // opcional
});
```

**Opções:**

| Opção | Tipo | Padrão | Descrição |
| :--- | :--- | :--- | :--- |
| `links` | `string` | - | **Obrigatório.** Seletor CSS para os links de navegação. |
| `sections` | `string` | - | **Obrigatório.** Seletor CSS para as seções de conteúdo. |
| `activeClassName` | `string` | `'active'` | A classe CSS a ser aplicada no link de navegação ativo. |
| `rootMargin`| `string` | `'-50% 0px -50% 0px'` | `rootMargin` do `IntersectionObserver`. O padrão detecta quando a seção está no meio da tela. |

---

### 8. `applyTilt`

Aplica um efeito de inclinação 3D interativo baseado no mouse.

**Importação:**
```javascript
import { applyTilt } from '@thecoderzeus/scroll-reveal-fx';
```

**Uso:**
```javascript
applyTilt({
  selector: '.interactive-card',
  intensity: 15,
  scale: 1.05
});
```

*(Herda opções de easing e reset)*

---

### 9. `applyMagnetism`

Cria um efeito "magnético" onde um elemento é atraído pelo cursor do mouse quando ele se aproxima.

**Importação:**
```javascript
import { applyMagnetism } from '@thecoderzeus/scroll-reveal-fx';
```

**Uso:**
```javascript
applyMagnetism({
  selector: '.magnetic-button',
  intensity: 0.3,
  threshold: 80
});
```

**Opções:**

| Opção | Tipo | Padrão | Descrição |
| :--- | :--- | :--- | :--- |
| `selector` | `string` | `'.magnetic'` | Seletor para os elementos. |
| `intensity`| `number` | `0.2` | Força da atração. Valores entre 0 e 1. |
| `threshold`| `number` | `100` | Distância em pixels para o efeito começar. |
| `scale` | `number` | `1.1` | Quanto o elemento aumenta de tamanho no hover. |
| `easing` | `string` | `'cubic-bezier(.03,.98,.52,.99)'` | Função de easing para as transições. |

## License

Este projeto está licenciado sob a [Licença MIT](https://github.com/TheCoderZeus/scroll-reveal-fx/blob/main/LICENSE).

---

## Novos Módulos de Animação

### applyWaveReveal

Revela elementos com um movimento vertical em forma de onda combinado com um fade de opacidade ao rolar a página.

**Importação:**
```javascript
import { applyWaveReveal } from '@thecoderzeus/scroll-reveal-fx';
```

**Uso:**
```javascript
applyWaveReveal({
  selector: '.wave-reveal',
  duration: 800,
  stagger: 100,
  easing: 'ease-out',
  once: true
});
```

**Opções:**

| Opção | Tipo | Padrão | Descrição |
| :--- | :--- | :--- | :--- |
| `selector` | `string` | `'.wave-reveal'` | Seletor CSS para os elementos a revelar. |
| `duration` | `number` | `800` | Duração da animação em milissegundos. |
| `stagger` | `number` | `100` | Atraso entre a animação de cada elemento em milissegundos. |
| `easing` | `string` | `'ease-out'` | Função de easing CSS para a animação. |
| `once` | `boolean` | `true` | Se a animação deve ocorrer apenas uma vez. |

---

### applyFlip3D

Revela elementos com uma animação de flip 3D ao rolar a página.

**Importação:**
```javascript
import { applyFlip3D } from '@thecoderzeus/scroll-reveal-fx';
```

**Uso:**
```javascript
applyFlip3D({
  selector: '.flip3d-reveal',
  duration: 700,
  easing: 'ease-in-out',
  once: true
});
```

**Opções:**

| Opção | Tipo | Padrão | Descrição |
| :--- | :--- | :--- | :--- |
| `selector` | `string` | `'.flip3d-reveal'` | Seletor CSS para os elementos a revelar. |
| `duration` | `number` | `700` | Duração da animação em milissegundos. |
| `easing` | `string` | `'ease-in-out'` | Função de easing CSS para a animação. |
| `once` | `boolean` | `true` | Se a animação deve ocorrer apenas uma vez. |

---

### applyColorPulse

Revela elementos com uma animação suave de pulso de cor ao rolar a página.

**Importação:**
```javascript
import { applyColorPulse } from '@thecoderzeus/scroll-reveal-fx';
```

**Uso:**
```javascript
applyColorPulse({
  selector: '.color-pulse',
  pulseColor: '#ff4081',
  duration: 1000,
  once: true
});
```

**Opções:**

| Opção | Tipo | Padrão | Descrição |
| :--- | :--- | :--- | :--- |
| `selector` | `string` | `'.color-pulse'` | Seletor CSS para os elementos a revelar. |
| `pulseColor` | `string` | `'#ff4081'` | Cor para o pulso da animação. |
| `duration` | `number` | `1000` | Duração de um ciclo de pulso em milissegundos. |
| `once` | `boolean` | `true` | Se a animação deve ocorrer apenas uma vez. |

---

### applyZoomBlur

Revela elementos com um efeito de zoom com desfoque que desaparece ao completar a animação.

**Importação:**
```javascript
import { applyZoomBlur } from '@thecoderzeus/scroll-reveal-fx';
```

**Uso:**
```javascript
applyZoomBlur({
  selector: '.zoom-blur',
  duration: 700,
  easing: 'ease-out',
  once: true
});
```

**Opções:**

| Opção | Tipo | Padrão | Descrição |
| :--- | :--- | :--- | :--- |
| `selector` | `string` | `'.zoom-blur'` | Seletor CSS para os elementos a revelar. |
| `duration` | `number` | `700` | Duração da animação em milissegundos. |
| `easing` | `string` | `'ease-out'` | Função de easing CSS para a animação. |
| `once` | `boolean` | `true` | Se a animação deve ocorrer apenas uma vez. |

---

### applySkewReveal

Revela elementos com um leve `skew` e `slide`, voltando ao estado normal no fim.

**Importação:**
```javascript
import { applySkewReveal } from '@thecoderzeus/scroll-reveal-fx';
```

**Uso:**
```javascript
applySkewReveal({
  selector: '.skew-reveal',
  axis: 'y',     // 'x' ou 'y'
  angle: 10,     // graus
  distance: 20,  // px
  duration: 700,
  easing: 'ease-out',
  once: true
});
```

**Opções:**

| Opção | Tipo | Padrão | Descrição |
| :--- | :--- | :--- | :--- |
| `selector` | `string` | `'.skew-reveal'` | Seletor dos elementos. |
| `axis` | `'x'|'y'` | `'y'` | Eixo do skew. |
| `angle` | `number` | `10` | Ângulo do skew em graus. |
| `distance` | `number` | `20` | Deslocamento inicial em px. |
| `duration` | `number` | `700` | Duração da animação. |
| `easing` | `string` | `'ease-out'` | Easing CSS. |
| `once` | `boolean` | `true` | Executa apenas uma vez. |

---

### applyMaskWipe

Revela elementos com um “wipe” direcional usando `clip-path`.

**Importação:**
```javascript
import { applyMaskWipe } from '@thecoderzeus/scroll-reveal-fx';
```

**Uso:**
```javascript
applyMaskWipe({
  selector: '.mask-wipe',
  direction: 'left', // 'right' | 'top' | 'bottom'
  duration: 800,
  easing: 'ease-in-out',
  once: true
});
```

**Opções:**

| Opção | Tipo | Padrão | Descrição |
| :--- | :--- | :--- | :--- |
| `selector` | `string` | `'.mask-wipe'` | Seletor dos elementos. |
| `direction` | `'left'|'right'|'top'|'bottom'` | `'left'` | Direção do wipe. |
| `duration` | `number` | `800` | Duração da animação. |
| `easing` | `string` | `'ease-in-out'` | Easing CSS. |
| `once` | `boolean` | `true` | Executa apenas uma vez. |

---

### applyCascadeReveal

Revela os filhos de um contêiner em sequência com `stagger`.

**Importação:**
```javascript
import { applyCascadeReveal } from '@thecoderzeus/scroll-reveal-fx';
```

**Uso:**
```javascript
applyCascadeReveal({
  selector: '.cascade',
  childSelector: '.cascade-item',
  duration: 600,
  stagger: 120,
  easing: 'ease-out',
  once: true
});
```

**Opções:**

| Opção | Tipo | Padrão | Descrição |
| :--- | :--- | :--- | :--- |
| `selector` | `string` | `'.cascade'` | Seletor do contêiner. |
| `childSelector` | `string` | `'.cascade-item'` | Seletor dos filhos a animar. |
| `duration` | `number` | `600` | Duração de cada item. |
| `stagger` | `number` | `120` | Atraso entre itens. |
| `easing` | `string` | `'ease-out'` | Easing CSS. |
| `once` | `boolean` | `true` | Executa apenas uma vez. |

---

## Contribuição

Quer pedir um ajuste, corrigir um bug ou propor um novo efeito? Fique à vontade para abrir um Pull Request.

### Como contribuir

- **Faça um fork** do repositório: [GitHub - scroll-reveal-fx](https://github.com/TheCoderZeus/scroll-reveal-fx)
- **Crie uma branch** descritiva: `feat/nome-do-efeito` ou `fix/descricao-breve`
- **Implemente e teste** seguindo a estrutura de pastas:
  - `src/core/*`, `src/effects/*`, `src/mouse/*`
- **Siga o estilo do código** (nomes claros, sem dependências externas)
- **Abra um PR** descrevendo:
  - O problema que resolve ou o novo efeito
  - Um exemplo de uso (código) e breve explicação
  - Antes/Depois se for correção

Se preferir, **abra uma Issue** descrevendo o que precisa ser ajustado.