npm package: @kaberlo/lottie-brand-colors
Description: Transform Lottie animations with brand colors using sentinel color replacement
Author: Kevin Berthelot
Latest version: 1.1.1

# @kevin/lottie-brand-colors

Package pour transformer les animations Lottie avec des couleurs de marque en utilisant le remplacement de couleurs sentinelles.

## 🎯 Fonctionnalités

- **Transformation hybride** : Combine lottie-colorify avec un système de fallback personnalisé
- **9 patterns de couleurs** supportés (formats hex, RGB, et normalisés)
- **Calculs adaptatifs** : Génération automatique de variantes de couleurs (clair, foncé, texte)
- **Intégration React** : Hooks et composants prêts à l'emploi
- **API flexible** : Fonctions vanilla JS et intégrations React

## 📦 Installation

```bash
npm install @kevin/lottie-brand-colors
```

## 🚀 Utilisation rapide

### JavaScript vanilla

```javascript
import { transformLottieColors } from '@kevin/lottie-brand-colors';

// Transformer une animation Lottie
const lottieData = await fetch('animation.json').then(r => r.json());
const transformed = transformLottieColors(lottieData, '#6a0b5d');
```

### React Hook

```javascript
import { useLottieBrandColors } from '@kevin/lottie-brand-colors/react';

function MyComponent() {
  const { transformedData, isLoading } = useLottieBrandColors(
    'https://example.com/animation.json',
    '#6a0b5d'
  );
  
  return isLoading ? 'Chargement...' : 'Animation prête !';
}
```

### React Composant

```jsx
import { LottieBrandPreview } from '@kevin/lottie-brand-colors/react';

function MyApp() {
  return (
    <LottieBrandPreview
      url="https://example.com/animation.json"
      brandColor="#6a0b5d"
      autoPlay={true}
      className="w-64 h-64"
    />
  );
}
```

## 🎨 Couleurs sentinelles supportées

| Couleur | Hex | RGB | Usage |
|---------|-----|-----|-------|
| **Magenta** | `#ff00ff` | `[255,0,255]` | Couleur primaire |
| **Cyan** | `#00ffff` | `[0,255,255]` | Couleur claire |
| **Vert** | `#00ff00` | `[0,255,0]` | Couleur texte |
| **Bleu foncé** | `#031e9a` | `[3,30,154]` | Couleur foncée |
| **Jaune** | `#ffff00` | `[255,255,0]` | Complémentaire 1 (+120°) |
| **Rouge** | `#ff0000` | `[255,0,0]` | Complémentaire 2 (+240°) |

## 📚 API Documentation

### Fonctions principales

#### `transformLottieColors(lottieData, brandColor)`
Transforme une animation Lottie avec une couleur de marque.

**Paramètres :**
- `lottieData` (Object) - Données JSON de l'animation Lottie
- `brandColor` (string) - Couleur de marque au format hex (#rrggbb)

**Retourne :** Object - Animation transformée

#### `loadAndTransformLottie(url, brandColor, options)`
Charge et transforme une animation depuis une URL.

**Paramètres :**
- `url` (string) - URL du fichier JSON Lottie
- `brandColor` (string) - Couleur de marque hex
- `options` (Object) - Options de configuration

### Hooks React

#### `useLottieBrandColors(url, brandColor, options)`
Hook principal pour gérer les transformations avec état.

**Retourne :**
```javascript
{
  transformedData: Object,  // Animation transformée
  isLoading: boolean,       // État de chargement
  error: string,           // Message d'erreur
  reload: Function,        // Fonction de rechargement
  hasData: boolean,        // Données disponibles
  isReady: boolean        // Prêt à afficher
}
```

#### `useLottieColors(url, brandColor)`
Version simplifiée du hook principal.

### Composants React

#### `<LottieBrandPreview />`
Composant complet de prévisualisation Lottie avec transformation de couleurs.

**Props :**
- `url` (string) - URL de l'animation
- `brandColor` (string) - Couleur de marque hex
- `autoPlay` (boolean) - Lecture automatique (défaut: true)
- `loop` (boolean) - Animation en boucle (défaut: true)
- `className` (string) - Classes CSS
- `onLoad` (Function) - Callback de chargement réussi
- `onError` (Function) - Callback d'erreur

## 🔧 Configuration avancée

### Calcul des variantes de couleurs

```javascript
import { calculateBrandColorVariants } from '@kevin/lottie-brand-colors';

const colors = calculateBrandColorVariants('#6a0b5d');
console.log(colors);
// {
//   primary: '#6a0b5d',       // Couleur originale
//   light: '#b577a8',         // 50% plus claire
//   dark: '#5f0a53',          // 10% plus foncée
//   text: '#e8d4e5',          // Adaptée pour le texte
//   complement1: '#0b5d1f',   // Complémentaire triadique (+120°)
//   complement2: '#5d370b',   // Complémentaire triadique (+240°)
//   luminance: 0.15           // Luminance calculée
// }
```

### Triangle complémentaire (Schéma triadique)

Le système génère automatiquement **2 couleurs complémentaires harmonieuses** basées sur le cercle chromatique :

- **Complémentaire 1** : +120° sur le cercle chromatique
- **Complémentaire 2** : +240° sur le cercle chromatique

Ces couleurs forment un **triangle équilatéral** sur le cercle, garantissant une harmonie visuelle naturelle tout en offrant un contraste dynamique.

**Exemple avec violet `#6a0b5d` :**
- Primaire : `#6a0b5d` (Violet)
- Complémentaire 1 : `#0b5d1f` (Vert) - 120° plus loin
- Complémentaire 2 : `#5d370b` (Orange) - 240° plus loin

### Détection des couleurs sentinelles

```javascript
import { findRemainingSentinels } from '@kevin/lottie-brand-colors';

const sentinels = findRemainingSentinels(lottieData);
console.log('Sentinelles détectées:', sentinels);
```

## 🧪 Développement

### Structure du package

```
lottie-brand-colors/
├── src/
│   ├── core/                    # Logique principale
│   │   ├── colorTransformer.js  # Transformation hybride
│   │   ├── colorCalculator.js   # Calculs de couleurs
│   │   ├── fallbackProcessor.js # Fallback personnalisé
│   │   └── sentinelDetector.js  # Détection sentinelles
│   ├── integrations/
│   │   └── react/              # Intégrations React
│   └── index.js                # Point d'entrée
├── __tests__/                  # Tests unitaires
└── docs/                       # Documentation
```

### Tests

```bash
npm test                 # Tests unitaires
npm run test:watch      # Tests en mode watch
```

### Build

```bash
npm run build           # Build de production
npm run dev            # Build en mode watch
```

## 📄 Licence

MIT © Kevin Berthelot

## 🤝 Contribution

Les contributions sont les bienvenues ! Veuillez consulter le guide de contribution pour plus de détails.

## 📊 Performance

- **Approche hybride** : lottie-colorify + fallback personnalisé
- **13 patterns** de couleurs détectés (6 sentinelles × 2 formats + variants)
- **Calculs adaptatifs** : Luminance + schéma triadique
- **Gestion d'erreurs** robuste avec fallbacks

## 🎨 Guide Designers After Effects

### Palette de couleurs sentinelles à utiliser

Pour créer des animations Lottie compatibles avec la transformation automatique, utilisez **EXACTEMENT** ces couleurs dans After Effects :

#### Couleurs principales (monochromatiques)
1. **Magenta pur** `#ff00ff` → Devient la couleur primaire de marque
2. **Cyan pur** `#00ffff` → Devient la version claire (+50% luminosité)
3. **Vert pur** `#00ff00` → Devient le texte adaptatif (contraste)
4. **Bleu foncé** `#031e9a` → Devient la version foncée (-10% luminosité)

#### Couleurs complémentaires (schéma triadique)
5. **Jaune pur** `#ffff00` → Devient la complémentaire harmonieuse 1 (+120°)
6. **Rouge pur** `#ff0000` → Devient la complémentaire harmonieuse 2 (+240°)

### Recommandations créatives

**Pour des animations dynamiques et énergiques :**
- Utilisez les 6 couleurs pour un rendu coloré et harmonieux
- Le triangle complémentaire (Magenta + Jaune + Rouge → Primaire + Comp1 + Comp2) crée un équilibre visuel naturel

**Pour des animations sobres et corporate :**
- Limitez-vous aux 4 premières couleurs (variations monochromatiques)
- Évitez Jaune et Rouge pour rester dans la même famille chromatique

### ⚠️ Important
- N'utilisez **PAS** de variations proches (ex: `#ff00fe` ne sera pas détecté)
- Les couleurs doivent être **pures** et **exactes** pour être transformées
- Testez toujours avec différentes couleurs de marque (claires/foncées)