pluracore-comps/README.md

Librairie de 20 composants React ultra-personnalisables pour sites vitrines modernes - Button, Card, Hero, Navigation, Input, Modal, Badge, Accordion, Tabs, Toast, Slider, Progress, Avatar, Pagination, Rating, Breadcrumb, Banner, Grid, Section, Gallery

# Pluracore Components

Une librairie de composants React ultra-personnalisables pour créer des sites vitrines modernes et attractifs. **16 composants** sophistiqués avec des centaines d'options de personnalisation.

## Installation

```bash
npm install pluracore-comps
```

## Composants Disponibles

### 🔘 Button
Bouton hyper-personnalisable avec 8 variantes de couleurs, 4 tailles, et de nombreux effets.

```jsx
import { Button } from 'pluracore-comps';

<Button 
  variant="primary" 
  size="large" 
  glow 
  pulse
  onClick={handleClick}
>
  Cliquez-moi
</Button>
```

**Props principales :**
- `variant`: primary, secondary, success, danger, warning, info, light, dark
- `size`: small, medium, large, xl
- `glow`, `pulse`, `bounce`, `shake`, `float`: Effets d'animation
- `gradient`, `outline`, `shadow`: Styles visuels
- `loading`: État de chargement avec spinner

### 🎴 Card
Cartes flexibles pour afficher du contenu avec différents layouts et styles.

```jsx
import { Card } from 'pluracore-comps';

<Card
  variant="elevated"
  size="medium"
  hover
  headerTitle="Mon titre"
  headerSubtitle="Sous-titre"
  footerContent={<Button>Action</Button>}
>
  Contenu de la carte
</Card>
```

**Props principales :**
- `variant`: default, elevated, outlined, flat, glass
- `layout`: default, centered, image-top, image-left, horizontal
- `hover`: Effets au survol
- `headerTitle`, `headerSubtitle`: En-tête automatique

### 🦸 Hero
Section héro avec backgrounds dynamiques, particules et effets visuels.

```jsx
import { Hero } from 'pluracore-comps';

<Hero
  title="Bienvenue sur notre site"
  subtitle="Découvrez nos services exceptionnels"
  backgroundType="gradient"
  particleEffect
  parallax
  actions={[
    { label: "Commencer", onClick: handleStart, variant: "primary" },
    { label: "En savoir plus", onClick: handleLearn, variant: "outline" }
  ]}
/>
```

**Props principales :**
- `backgroundType`: gradient, image, video, pattern
- `particleEffect`: Effet de particules animées
- `parallax`: Effet parallaxe
- `actions`: Boutons d'action automatiques

### 🧭 Navigation
Navigation responsive avec dropdowns, mega-menus et animations.

```jsx
import { Navigation } from 'pluracore-comps';

<Navigation
  logo={{ src: "/logo.png", alt: "Mon Site" }}
  variant="glass"
  sticky
  items={[
    { label: "Accueil", href: "/" },
    { 
      label: "Services", 
      dropdown: [
        { label: "Web Design", href: "/web" },
        { label: "SEO", href: "/seo" }
      ]
    }
  ]}
/>
```

**Props principales :**
- `variant`: default, glass, solid, minimal
- `sticky`: Navigation fixe au scroll
- `dropdown`: Menus déroulants
- `megaMenu`: Mega-menus avec colonnes

### 📝 Input
Champs de saisie avec labels flottants, validation et indicateurs visuels.

```jsx
import { Input } from 'pluracore-comps';

<Input
  label="Email"
  type="email"
  variant="floating"
  validation="email"
  required
  icon={<EmailIcon />}
  helperText="Nous ne partagerons jamais votre email"
/>
```

**Props principales :**
- `variant`: default, floating, outlined, minimal
- `validation`: email, phone, url, custom
- `icon`: Icône à gauche ou droite
- `helperText`, `errorText`: Textes d'aide

### 🪟 Modal
Modales avec animations, gestion du focus et types prédéfinis.

```jsx
import { Modal } from 'pluracore-comps';

<Modal
  isOpen={isOpen}
  onClose={onClose}
  title="Confirmation"
  variant="confirmation"
  animation="slideUp"
  size="medium"
  actions={[
    { label: "Annuler", onClick: onClose, variant: "outline" },
    { label: "Confirmer", onClick: onConfirm, variant: "primary" }
  ]}
>
  Êtes-vous sûr de vouloir continuer ?
</Modal>
```

**Props principales :**
- `variant`: default, confirmation, form, fullscreen, drawer
- `animation`: fadeIn, slideUp, slideDown, slideLeft, slideRight, zoom
- `size`: small, medium, large, xl, full
- `actions`: Boutons automatiques

### 🏷️ Badge
Badges colorés avec variantes, effets et options de fermeture.

```jsx
import { Badge } from 'pluracore-comps';

<Badge
  variant="success"
  size="medium"
  glow
  pulse
  closable
  onClose={handleClose}
  icon={<CheckIcon />}
>
  Nouveau
</Badge>
```

**Props principales :**
- `variant`: primary, secondary, success, danger, warning, info, light, dark
- `size`: small, medium, large
- `outline`, `glow`, `pulse`: Effets visuels
- `dot`: Badge avec point coloré
- `closable`: Badge fermable

### 📋 Accordion
Accordéons pour FAQ et contenu pliable avec animations fluides.

```jsx
import { Accordion } from 'pluracore-comps';

<Accordion
  variant="bordered"
  allowMultiple
  defaultExpanded={[0]}
  items={[
    {
      title: "Comment ça marche ?",
      content: "Voici l'explication détaillée...",
      icon: <QuestionIcon />
    },
    {
      title: "Tarification",
      content: "Nos tarifs sont transparents..."
    }
  ]}
/>
```

**Props principales :**
- `variant`: default, bordered, filled, minimal
- `allowMultiple`: Plusieurs sections ouvertes
- `defaultExpanded`: Sections ouvertes par défaut
- `items`: Array avec title, content, icon

### 📑 Tabs
Système d'onglets avec 5 variantes et lazy loading.

```jsx
import { Tabs } from 'pluracore-comps';

<Tabs
  variant="pills"
  orientation="horizontal"
  lazyLoad
  closable
  defaultTab={0}
  tabs={[
    {
      label: "Aperçu",
      content: <Overview />,
      badge: 3,
      icon: <EyeIcon />
    },
    {
      label: "Détails",
      content: <Details />,
      disabled: false
    }
  ]}
/>
```

**Props principales :**
- `variant`: default, pills, underline, buttons, minimal
- `orientation`: horizontal, vertical
- `lazyLoad`: Chargement paresseux du contenu
- `closable`: Onglets fermables

### 🍞 Toast
Système de notifications global avec API simple.

```jsx
import { toast } from 'pluracore-comps';

// Utilisation simple
toast.success("Opération réussie !");
toast.error("Erreur survenue");
toast.info("Information importante");
toast.warning("Attention requise");

// Utilisation avancée
toast.custom("Message personnalisé", {
  duration: 5000,
  position: "top-right",
  variant: "success",
  closable: true,
  actions: [
    { label: "Annuler", onClick: handleUndo }
  ]
});
```

**Positions disponibles :**
- `top-left`, `top-center`, `top-right`
- `bottom-left`, `bottom-center`, `bottom-right`

### 🎠 Slider
Carrousel tactile avec autoplay et overlays de contenu.

```jsx
import { Slider } from 'pluracore-comps';

<Slider
  autoPlay
  duration={5000}
  infinite
  showDots
  showArrows
  touchEnabled
  variant="fade"
  slides={[
    {
      image: "/slide1.jpg",
      title: "Slide 1",
      description: "Description...",
      overlay: true,
      link: "/page1"
    }
  ]}
/>
```

**Props principales :**
- `variant`: slide, fade, zoom
- `autoPlay`: Lecture automatique
- `touchEnabled`: Support tactile
- `infinite`: Boucle infinie

### 📊 Progress
Barres de progression avec mode circulaire et animations.

```jsx
import { Progress } from 'pluracore-comps';

<Progress
  value={75}
  variant="circular"
  color="success"
  size="large"
  striped
  animated
  showLabel
  showPercentage
  label="Téléchargement en cours"
/>
```

**Props principales :**
- `variant`: default, thin, thick, circular
- `color`: primary, secondary, success, danger, warning, info
- `striped`, `animated`: Effets visuels
- `showLabel`, `showPercentage`: Affichage des infos

### 👤 Avatar
Avatars individuels et groupes avec badges et états.

```jsx
import { Avatar, AvatarGroup } from 'pluracore-comps';

<Avatar
  src="/user.jpg"
  name="John Doe"
  size="large"
  variant="circle"
  badge={3}
  badgeColor="danger"
  showBorder
  clickable
  onClick={handleClick}
/>

<AvatarGroup
  avatars={users}
  max={5}
  size="medium"
  spacing="normal"
  showRemaining
/>
```

**Props principales :**
- `variant`: circle, square, rounded
- `size`: xs, small, medium, large, xl, 2xl
- `badge`: Notification badge
- `clickable`: Avatar cliquable

### 📄 Pagination
Navigation de pages intelligente avec ellipses automatiques.

```jsx
import { Pagination } from 'pluracore-comps';

<Pagination
  currentPage={currentPage}
  totalPages={totalPages}
  onPageChange={handlePageChange}
  variant="rounded"
  size="medium"
  showInfo
  totalItems={1000}
  itemsPerPage={20}
  maxVisible={7}
/>
```

**Props principales :**
- `variant`: default, minimal, rounded, outlined
- `maxVisible`: Nombre max de pages visibles
- `showInfo`: Affichage des infos d'éléments
- `showFirstLast`, `showPrevNext`: Navigation étendue

### ⭐ Rating
Système de notation avec demi-étoiles et interactions.

```jsx
import { Rating } from 'pluracore-comps';

<Rating
  value={4.5}
  maxRating={5}
  allowHalf
  size="large"
  color="warning"
  icon="star"
  showValue
  showCount
  count={1250}
  onChange={handleRatingChange}
  readonly={false}
/>
```

**Props principales :**
- `icon`: star, heart, thumb
- `allowHalf`: Support des demi-étoiles
- `variant`: filled, outlined
- `showValue`, `showCount`: Affichage des infos

### 🍞 Breadcrumb
Fil d'Ariane avec navigation hiérarchique.

```jsx
import { Breadcrumb } from 'pluracore-comps';

<Breadcrumb
  items={[
    { label: "Produits", href: "/products" },
    { label: "Électronique", href: "/products/electronics" },
    { label: "Smartphones", href: "/products/electronics/phones" },
    { label: "iPhone 15" }
  ]}
  separator="chevron"
  variant="default"
  showHome
  homeIcon
  maxItems={5}
  onItemClick={handleBreadcrumbClick}
/>
```

**Props principales :**
- `separator`: chevron, slash, arrow, dot
- `variant`: default, pills, underlined
- `showHome`: Ajout automatique d'accueil
- `maxItems`: Truncature intelligente

## Personnalisation CSS

Tous les composants utilisent des variables CSS personnalisables :

```css
:root {
  --primary-color: #3b82f6;
  --secondary-color: #8b5cf6;
  --success-color: #22c55e;
  --danger-color: #ef4444;
  --warning-color: #f59e0b;
  --info-color: #06b6d4;
  --text-color: #374151;
  --bg-color: #ffffff;
  --border-color: #e5e7eb;
  /* ... autres variables */
}
```

## Responsive Design

Tous les composants sont entièrement responsive et s'adaptent automatiquement aux différentes tailles d'écran avec des breakpoints optimisés.

## Accessibilité

Chaque composant respecte les standards WCAG 2.1 avec :
- Support clavier complet
- Labels ARIA appropriés
- Contrastes de couleur optimaux
- Focus management intelligent

## Performance

- **Tree-shaking** : Importez seulement les composants utilisés
- **CSS optimisé** : Variables CSS natives pour les performances
- **Lazy loading** : Support intégré pour certains composants
- **Bundle size** : Optimisé pour la production

## Exemples d'Usage

### Site vitrine complet
```jsx
import { 
  Navigation, Hero, Card, Button, 
  Badge, Accordion, Toast, Rating 
} from 'pluracore-comps';

function App() {
  return (
    <>
      <Navigation logo={logo} items={navItems} sticky />
      
      <Hero
        title="Bienvenue"
        backgroundType="gradient"
        particleEffect
        actions={heroActions}
      />
      
      <section className="services">
        {services.map(service => (
          <Card
            key={service.id}
            variant="elevated"
            hover
            headerTitle={service.title}
          >
            <p>{service.description}</p>
            <Rating value={service.rating} readonly />
            <Button variant="primary">En savoir plus</Button>
          </Card>
        ))}
      </section>
      
      <Accordion items={faqItems} variant="bordered" />
    </>
  );
}
```

### Système de notifications
```jsx
import { toast } from 'pluracore-comps';

function handleFormSubmit() {
  try {
    // Logique de soumission
    toast.success("Formulaire envoyé avec succès !");
  } catch (error) {
    toast.error("Erreur lors de l'envoi", {
      actions: [
        { label: "Réessayer", onClick: handleFormSubmit }
      ]
    });
  }
}
```

## Support TypeScript

La librairie inclut des définitions TypeScript complètes pour une expérience de développement optimale avec auto-complétion et vérification de types.

## Contribution

Les contributions sont les bienvenues ! Consultez le fichier CONTRIBUTING.md pour les guidelines.

## Licence

MIT - Libre d'utilisation pour tous projets commerciaux et personnels.
  image="/path/to/image.jpg"
  imagePosition="top"
>
  Contenu de la carte
</Card>
```

**Props principales :**
- `variant`: default, elevated, outlined, filled
- `shadow`: none, small, medium, large, xl
- `hover`: Effet de survol
- `glass`, `neon`, `tilt`: Effets spéciaux
- `image`, `imagePosition`: Gestion des images
- `headerTitle`, `headerSubtitle`, `footerContent`: Sections de la carte

### 🦸 Hero
Section héro complète avec arrière-plans, animations et layouts flexibles.

```jsx
import { Hero } from 'pluracore-comps';

<Hero
  title="Bienvenue sur notre site"
  subtitle="La meilleure solution pour vos besoins"
  description="Description détaillée de votre offre"
  backgroundImage="/hero-bg.jpg"
  overlay
  particles
  primaryAction={<Button variant="primary">Commencer</Button>}
  secondaryAction={<Button variant="outline">En savoir plus</Button>}
  height="large"
  animated
/>
```

**Props principales :**
- `backgroundType`: color, image, video, gradient
- `height`: small, medium, large, xl, full
- `alignment`: left, center, right
- `particles`, `parallax`, `glassmorphism`: Effets visuels
- `split`: Layout en deux colonnes
- `overlay`: Superposition avec opacité personnalisable

### 🧭 Navigation
Barre de navigation responsive avec dropdowns et animations.

```jsx
import { Navigation } from 'pluracore-comps';

const navItems = [
  { label: 'Accueil', href: '/', active: true },
  { label: 'Services', href: '/services' },
  {
    label: 'Produits',
    dropdown: [
      { label: 'Produit 1', href: '/produit1' },
      { label: 'Produit 2', href: '/produit2' }
    ]
  }
];

<Navigation
  logo="/logo.png"
  logoText="Mon Site"
  items={navItems}
  variant="default"
  background="white"
  shadow
  sticky
  actions={<Button variant="primary">Contact</Button>}
/>
```

**Props principales :**
- `variant`: default, minimal, bold, glass
- `position`: static, fixed, absolute
- `background`: white, dark, primary, transparent
- `blur`, `shadow`, `sticky`: Effets visuels
- `items`: Array d'éléments avec support des dropdowns

### 📝 Input
Champs de saisie avec validation, états et styles multiples.

```jsx
import { Input } from 'pluracore-comps';

<Input
  label="Email"
  type="email"
  placeholder="votre@email.com"
  variant="outlined"
  size="medium"
  floating
  leftIcon={<EmailIcon />}
  error="Email invalide"
  required
  fullWidth
/>
```

**Props principales :**
- `variant`: default, filled, outlined, minimal
- `size`: small, medium, large
- `floating`: Label flottant
- `leftIcon`, `rightIcon`, `prefix`, `suffix`: Éléments additionnels
- `error`, `success`, `warning`, `helper`: Messages d'état
- `multiline`: Mode textarea

### 🪟 Modal
Modales flexibles avec animations et positionnement personnalisable.

```jsx
import { Modal } from 'pluracore-comps';

<Modal
  isOpen={isModalOpen}
  onClose={closeModal}
  title="Mon Modal"
  size="medium"
  animation="scale"
  overlay
  overlayBlur
  footer={
    <>
      <Button variant="outline" onClick={closeModal}>Annuler</Button>
      <Button variant="primary">Confirmer</Button>
    </>
  }
>
  Contenu du modal
</Modal>
```

**Props principales :**
- `size`: small, medium, large, xl, auto
- `animation`: fade, slide, scale, slideUp, slideDown
- `position`: center, top, bottom
- `variant`: default, clean, glass, bordered
- `overlay`, `overlayBlur`: Gestion de la superposition

### 🏷️ Badge
Badges informatifs avec styles et animations variés.

```jsx
import { Badge } from 'pluracore-comps';

<Badge
  variant="success"
  size="medium"
  glow
  pulse
  closable
  onClose={handleClose}
  icon={<CheckIcon />}
>
  Nouveau
</Badge>
```

**Props principales :**
- `variant`: primary, secondary, success, danger, warning, info, light, dark
- `size`: small, medium, large
- `outline`, `glow`, `pulse`: Effets visuels
- `dot`: Badge avec point coloré
- `closable`: Badge fermable

## Personnalisation CSS

Tous les composants utilisent des variables CSS personnalisables :

```css
:root {
  --color-primary: #3b82f6;
  --color-secondary: #8b5cf6;
  --color-success: #22c55e;
  --color-danger: #ef4444;
  --color-warning: #f59e0b;
  --color-info: #06b6d4;
  /* ... autres variables */
}
```

## Responsive Design

Tous les composants sont entièrement responsive et s'adaptent automatiquement aux différentes tailles d'écran.

## Support TypeScript

La librairie inclut des définitions TypeScript pour une meilleure expérience de développement.

## Exemples Complets

Consultez le dossier `/examples` pour des exemples d'utilisation complets de chaque composant.

## Licence

MIT