npm package: @frederico-kluser/matrix-rain
Description: Customizable Matrix-style digital rain effect for web applications. Works with vanilla JavaScript/TypeScript or React.
Author: Vibe God
Latest version: 1.0.1

# @frederico-kluser/matrix-rain

Uma biblioteca customizavel para criar o icônico efeito "Matrix Rain" (chuva digital) em aplicações web. Funciona com JavaScript/TypeScript puro ou React.

![Matrix Rain Demo](https://img.shields.io/badge/Effect-Matrix%20Rain-00FF41?style=for-the-badge&logo=matrix)
![TypeScript](https://img.shields.io/badge/TypeScript-Ready-3178C6?style=for-the-badge&logo=typescript)
![React](https://img.shields.io/badge/React-Compatible-61DAFB?style=for-the-badge&logo=react)
![License](https://img.shields.io/badge/License-MIT-green?style=for-the-badge)

## Caracteristicas

- **Zero Dependencias** - A versão vanilla não requer nenhuma biblioteca externa
- **TypeScript First** - Totalmente tipado com tipos exportados
- **React Ready** - Componente React pronto para uso
- **Altamente Customizavel** - Cores, velocidade, caracteres e muito mais
- **Performance Otimizada** - Usa Canvas API para renderização eficiente
- **Responsivo** - Adapta-se automaticamente ao redimensionamento
- **Sem Scroll** - O efeito permanece fixo, não interferindo na rolagem da página

## Instalação

```bash
# npm
npm install @frederico-kluser/matrix-rain

# yarn
yarn add @frederico-kluser/matrix-rain

# pnpm
pnpm add @frederico-kluser/matrix-rain
```

## Uso Rápido

### JavaScript/TypeScript Vanilla

```typescript
import { MatrixRain } from '@frederico-kluser/matrix-rain';

// Selecione o container
const container = document.getElementById('matrix-container');

// Crie a instância
const rain = new MatrixRain(container);

// Inicie o efeito
rain.start();

// Para parar/destruir quando necessário
rain.destroy();
```

### React

```tsx
import { MatrixRainBackground } from '@frederico-kluser/matrix-rain';

function App() {
  return (
    <div>
      {/* Background fullscreen */}
      <MatrixRainBackground fullscreen />

      {/* Seu conteúdo aqui */}
      <main style={{ position: 'relative', zIndex: 1 }}>
        <h1>Meu Site</h1>
      </main>
    </div>
  );
}
```

## Guia Completo

### 1. Background Fullscreen (Tela Inteira)

O uso mais comum - um background Matrix que cobre toda a tela sem interferir no scroll.

#### HTML/JavaScript

```html
<!DOCTYPE html>
<html>
<head>
  <style>
    /* Container fixo para o efeito */
    #matrix-background {
      position: fixed;
      top: 0;
      left: 0;
      width: 100vw;
      height: 100vh;
      z-index: 0;
      pointer-events: none;
    }

    /* Seu conteúdo fica acima */
    .content {
      position: relative;
      z-index: 1;
    }
  </style>
</head>
<body>
  <div id="matrix-background"></div>

  <div class="content">
    <h1>Seu conteúdo aqui</h1>
    <!-- Scroll funciona normalmente -->
  </div>

  <script type="module">
    import { MatrixRain } from '@frederico-kluser/matrix-rain';

    const container = document.getElementById('matrix-background');
    const rain = new MatrixRain(container, {
      opacity: 0.5, // Transparência do canvas
    });
    rain.start();
  </script>
</body>
</html>
```

#### React

```tsx
import { MatrixRainBackground } from '@frederico-kluser/matrix-rain';

function App() {
  return (
    <>
      {/* fullscreen + zIndex baixo = background perfeito */}
      <MatrixRainBackground fullscreen zIndex={0} opacity={0.5} />

      {/* Conteúdo com z-index maior */}
      <main style={{ position: 'relative', zIndex: 1 }}>
        <h1>Bem-vindo</h1>
        <p>O scroll funciona normalmente!</p>
      </main>
    </>
  );
}
```

### 2. Dentro de um Container Específico

Renderize o efeito dentro de uma div com dimensões definidas.

#### HTML/JavaScript

```html
<div id="matrix-box" style="width: 400px; height: 300px;"></div>

<script type="module">
  import { MatrixRain } from '@frederico-kluser/matrix-rain';

  const container = document.getElementById('matrix-box');
  const rain = new MatrixRain(container, {
    opacity: 0.8,
    fontSize: 12,
  });
  rain.start();
</script>
```

#### React

```tsx
function MatrixCard() {
  return (
    <div style={{ width: '400px', height: '300px', position: 'relative' }}>
      <MatrixRainBackground opacity={0.8} fontSize={12} />

      {/* Conteúdo dentro do card */}
      <div style={{ position: 'relative', zIndex: 1, padding: '1rem' }}>
        <h2>Card com Matrix</h2>
      </div>
    </div>
  );
}
```

### 3. Cores Personalizadas

Mude as cores para criar temas diferentes.

```typescript
const rain = new MatrixRain(container, {
  colors: {
    head: '#FF00FF',       // Cor do caractere líder (cabeça)
    trailBright: '#CC00CC', // Trail brilhante
    trailMedium: '#990099', // Trail médio
    trailDark: '#660066',   // Trail escuro
    background: '#1a001a',  // Cor de fundo
  },
});
```

#### Temas Prontos

```typescript
// Tema Clássico (Verde - padrão)
const classicTheme = {
  head: '#FFFFFF',
  trailBright: '#00FF41',
  trailMedium: '#008F11',
  trailDark: '#003B00',
  background: '#000000',
};

// Tema Cyberpunk (Roxo/Rosa)
const cyberpunkTheme = {
  head: '#FF00FF',
  trailBright: '#CC00CC',
  trailMedium: '#990099',
  trailDark: '#660066',
  background: '#0d001a',
};

// Tema Azul
const blueTheme = {
  head: '#FFFFFF',
  trailBright: '#00BFFF',
  trailMedium: '#0080AA',
  trailDark: '#004466',
  background: '#000011',
};

// Tema Vermelho (Alerta)
const redTheme = {
  head: '#FFFFFF',
  trailBright: '#FF4444',
  trailMedium: '#AA2222',
  trailDark: '#661111',
  background: '#110000',
};

// Tema Dourado
const goldTheme = {
  head: '#FFFFFF',
  trailBright: '#FFD700',
  trailMedium: '#CC9900',
  trailDark: '#806600',
  background: '#0d0d00',
};
```

### 4. Caracteres Personalizados

Troque os caracteres exibidos na chuva.

```typescript
// Apenas números
const rain = new MatrixRain(container, {
  characters: '0123456789',
});

// Apenas símbolos
const rain = new MatrixRain(container, {
  characters: '@#$%^&*()!?<>{}[]',
});

// Katakana japonês (original do filme)
const rain = new MatrixRain(container, {
  characters: 'アイウエオカキクケコサシスセソタチツテトナニヌネノハヒフヘホマミムメモヤユヨラリルレロワヲン',
});

// Binário
const rain = new MatrixRain(container, {
  characters: '01',
});

// Hexadecimal
const rain = new MatrixRain(container, {
  characters: '0123456789ABCDEF',
});
```

### 5. Controles de Velocidade e Performance

```typescript
const rain = new MatrixRain(container, {
  // Tamanho da fonte (afeta densidade)
  fontSize: 14,

  // Intervalo entre frames em ms (menor = mais rápido, mais CPU)
  frameInterval: 50, // ~20 FPS (padrão)

  // Duração do fade em ms (maior = trails mais longos)
  fadeDuration: 8000, // 8 segundos

  // Intervalo mínimo entre criação de caracteres (frames)
  minDropInterval: 1,

  // Intervalo máximo entre criação de caracteres (frames)
  maxDropInterval: 3,

  // Opacidade do trail (menor = trails mais longos)
  trailOpacity: 0.05,
});
```

### 6. Controlando a Animação

```typescript
const rain = new MatrixRain(container);

// Inicia a animação
rain.start();

// Pausa a animação
rain.pause();
// ou
rain.stop();

// Resume a animação
rain.resume();
// ou
rain.start();

// Limpa o canvas (mantém instância)
rain.clear();

// Verifica se está rodando
if (rain.isActive()) {
  console.log('Animação está rodando');
}

// Atualiza configurações em tempo real
rain.setOptions({
  opacity: 0.8,
  fontSize: 16,
});

// Obtém configurações atuais
const config = rain.getOptions();
console.log(config);

// Destrói completamente (remove canvas do DOM)
rain.destroy();
```

## API Reference

### Classe `MatrixRain`

#### Constructor

```typescript
new MatrixRain(container: HTMLElement, options?: MatrixRainOptions)
```

#### Métodos

| Método | Descrição |
|--------|-----------|
| `start()` | Inicia a animação |
| `stop()` | Para a animação |
| `pause()` | Alias para `stop()` |
| `resume()` | Alias para `start()` |
| `clear()` | Limpa o canvas |
| `destroy()` | Remove o canvas e limpa recursos |
| `isActive()` | Retorna `true` se animação está rodando |
| `setOptions(options)` | Atualiza configurações |
| `getOptions()` | Retorna configurações atuais |

### Componente `MatrixRainBackground` (React)

```tsx
<MatrixRainBackground
  // Layout
  fullscreen?: boolean    // Se true, usa position: fixed (default: false)
  zIndex?: number         // Z-index do container (default: 0)
  className?: string      // Classe CSS adicional
  style?: CSSProperties   // Estilos inline adicionais

  // Aparência
  opacity?: number        // Opacidade do canvas 0-1 (default: 0.5)
  fontSize?: number       // Tamanho da fonte em px (default: 14)
  characters?: string     // Caracteres a usar

  // Cores
  colors?: {
    head?: string         // Cor da cabeça (default: '#FFFFFF')
    trailBright?: string  // Trail brilhante (default: '#00FF41')
    trailMedium?: string  // Trail médio (default: '#008F11')
    trailDark?: string    // Trail escuro (default: '#003B00')
    background?: string   // Fundo (default: '#000000')
  }

  // Performance
  frameInterval?: number  // ms entre frames (default: 50)
  fadeDuration?: number   // ms de fade (default: 8000)
  trailOpacity?: number   // Opacidade do trail (default: 0.05)
  minDropInterval?: number // Min frames entre drops (default: 1)
  maxDropInterval?: number // Max frames entre drops (default: 3)
/>
```

### Interface `MatrixRainOptions`

```typescript
interface MatrixRainOptions {
  fontSize?: number;        // default: 14
  characters?: string;      // default: Katakana + Alphanumeric
  frameInterval?: number;   // default: 50
  fadeDuration?: number;    // default: 8000
  opacity?: number;         // default: 0.5
  colors?: MatrixColors;
  minDropInterval?: number; // default: 1
  maxDropInterval?: number; // default: 3
  trailOpacity?: number;    // default: 0.05
}

interface MatrixColors {
  head?: string;        // default: '#FFFFFF'
  trailBright?: string; // default: '#00FF41'
  trailMedium?: string; // default: '#008F11'
  trailDark?: string;   // default: '#003B00'
  background?: string;  // default: '#000000'
}
```

## Dicas de Performance

1. **Use `opacity` baixo** - Valores menores (0.3-0.5) reduzem a carga visual e melhoram performance em dispositivos mais lentos.

2. **Aumente `frameInterval`** - O padrão é 50ms (~20 FPS). Para economizar CPU, use 100ms (~10 FPS).

3. **Aumente `fontSize`** - Fontes maiores = menos colunas = menos cálculos.

4. **Use em containers menores** - Fullscreen em monitores 4K pode ser pesado. Considere usar em áreas específicas.

5. **Destrua quando não visível** - Se o usuário navegar para outra página/aba, destrua a instância.

```typescript
// Exemplo: destruir quando não visível
document.addEventListener('visibilitychange', () => {
  if (document.hidden) {
    rain.pause();
  } else {
    rain.resume();
  }
});
```

## Compatibilidade com Navegadores

- Chrome 60+
- Firefox 55+
- Safari 11+
- Edge 79+

Requer suporte a:
- Canvas 2D API
- ES6 Classes
- ResizeObserver

## Estrutura do Projeto

```
matrix-rain/
├── src/
│   ├── core/
│   │   ├── MatrixRain.ts     # Classe principal
│   │   ├── types.ts          # Tipos TypeScript
│   │   ├── constants.ts      # Constantes (cores, caracteres)
│   │   ├── utils.ts          # Funções utilitárias
│   │   └── index.ts          # Exports do core
│   ├── react/
│   │   ├── MatrixRainBackground.tsx  # Componente React
│   │   └── index.ts          # Exports do React
│   └── index.ts              # Entry point principal
├── examples/
│   ├── vanilla.html          # Exemplo JavaScript puro
│   └── react-example.tsx     # Exemplo React
├── package.json
├── tsconfig.json
├── README.md
└── LICENSE
```

## Desenvolvimento Local

```bash
# Clone o repositório
git clone https://github.com/frederico-kluser/vibe_god.git
cd vibe_god/matrix-rain

# Instale dependências
npm install

# Build
npm run build

# Watch mode
npm run dev
```

## Contribuindo

Contribuições são bem-vindas! Por favor:

1. Faça fork do projeto
2. Crie uma branch para sua feature (`git checkout -b feature/nova-feature`)
3. Commit suas mudanças (`git commit -m 'feat: adiciona nova feature'`)
4. Push para a branch (`git push origin feature/nova-feature`)
5. Abra um Pull Request

## Licença

MIT License - veja o arquivo [LICENSE](LICENSE) para detalhes.

## Créditos

Inspirado pelo icônico efeito visual do filme "The Matrix" (1999).

---

Feito com 💚 por [Vibe God](https://github.com/frederico-kluser)