react-season-effects/README.md

Uma biblioteca React/TypeScript com efeitos visuais sazonais automáticos

# React Season Effects 🎨✨

Uma biblioteca React/TypeScript com efeitos visuais sazonais automáticos que adiciona magia às suas aplicações durante diferentes épocas do ano.

[![npm version](https://badge.fury.io/js/react-season-effects.svg)](https://badge.fury.io/js/react-season-effects)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## 🌟 Características

- 🎯 **Automático**: Detecta automaticamente a estação/época do ano
- 🎨 **Customizável**: Permite forçar efeitos específicos
- ⚡ **Leve**: Construído com performance em mente
- 📱 **Responsivo**: Funciona em desktop e mobile
- 🔧 **TypeScript**: Totalmente tipado
- 🎭 **Modular**: Use efeitos individuais ou o componente principal

## 🎪 Efeitos Disponíveis

- ❄️ **Snowflakes** - Flocos de neve para o inverno
- 🎆 **Fireworks** - Fogos de artifício para Ano Novo
- 👻 **GhostEffect** - Fantasmas flutuantes para Halloween
- 🦋 **Butterflies** - Borboletas voando na primavera
- 🥚 **EasterEggs** - Ovos coloridos para Páscoa
- ☀️ **SummerHat** - Chapéu de verão
- 🎂 **Birthday** - Confete para aniversários
- 🌌 **Aurora** - Aurora boreal mística

## 📦 Instalação

```bash
npm install react-season-effects
# ou
yarn add react-season-effects
# ou
pnpm add react-season-effects
```

**Dependência**: Esta biblioteca requer `canvas-confetti` para alguns efeitos:

```bash
npm install canvas-confetti
```

## 🚀 Uso Básico

### Efeitos Automáticos

```tsx
import { SeasonEffects } from 'react-season-effects';

function App() {
  return (
    <div>
      <SeasonEffects />
      {/* Seu conteúdo aqui */}
    </div>
  );
}
```

### Forçar Efeito Específico

```tsx
import { SeasonEffects } from 'react-season-effects';

function App() {
  return (
    <div>
      <SeasonEffects forceSeason="winter" />
      {/* Flocos de neve aparecerão independente da data */}
    </div>
  );
}
```

### Usando Efeitos Individuais

```tsx
import { Snowflakes, Fireworks, Butterflies } from 'react-season-effects';

function App() {
  return (
    <div>
      <Snowflakes />
      <Fireworks />
      <Butterflies />
    </div>
  );
}
```

## 🎛️ API

### SeasonEffects

| Prop | Tipo | Padrão | Descrição |
|------|------|--------|-----------|
| `forceSeason` | `Season \| null` | `null` | Força um efeito específico |

### Tipos de Season

```typescript
type Season = 'newYear' | 'spring' | 'easter' | 'summer' | 'halloween' | 'winter' | 'birthday' | 'aurora' | null;
```

### Utilitários

```tsx
import { getCurrentSeason } from 'react-season-effects';

const currentSeason = getCurrentSeason(); // Retorna a estação atual
```

## 📅 Calendário Automático

A biblioteca detecta automaticamente as seguintes datas:

- **Ano Novo**: 31 Dez - 1 Jan
- **Primavera**: 20 Mar - 20 Jun
- **Páscoa**: ~13-27 Abr (aproximação)
- **Verão**: 21 Jun - 22 Set
- **Halloween**: 25-31 Out
- **Inverno**: 21 Dez - 19 Mar
- **Aniversário**: 10 Out (customizável)
- **Aurora**: 20-22 Dez (Solstício)

## 🎨 Customização

Os efeitos são otimizados para não interferir na performance da sua aplicação. Eles são renderizados em camadas absolutas que não afetam o layout.

## 🛠️ Desenvolvimento

```bash
# Instalar dependências
npm install

# Modo desenvolvimento
npm run dev

# Build da biblioteca
npm run build:lib

# Lint
npm run lint

# Formatação
npm run format
```

## 📝 Licença

MIT © React Season Effects Team

## 🤝 Contribuindo

Contribuições são bem-vindas! Sinta-se à vontade para abrir issues e pull requests.

## 🔗 Links

- [GitHub](https://github.com/react-season-effects/season-effects)
- [NPM](https://www.npmjs.com/package/react-season-effects)

---

Feito com ❤️ para adicionar um toque de magia às suas aplicações React!