st-circular-kpi 0.1.0

Un composant Streamlit pour afficher des KPI circulaires

🎯 Streamlit Circular KPI

Un composant Streamlit personnalisé pour afficher des indicateurs de performance clés (KPI) sous forme de graphiques circulaires élégants et interactifs.

✨ Fonctionnalités

• 📊 Graphiques circulaires animés avec dégradés de couleurs
• 📈 Statistiques visuelles (Min, Max, Moyenne) positionnées selon leur valeur
• 🎨 4 schémas de couleurs prédéfinis (bleu-violet, vert, rouge, orange)
• 🔧 Hautement personnalisable (taille, couleurs, unités, etc.)
• 📱 Responsive et adapté aux layouts Streamlit
• 🖱️ Interactif avec callbacks de clic
• 🎯 Police Urbanist pour un design moderne

🚀 Installation

pip install st-circular-kpi

📋 Démarrage rapide

import streamlit as st
from st_circular_kpi import circular_kpi

st.title("Mon Dashboard KPI")

# KPI simple
result = circular_kpi(
    value=85,
    label="Performance",
    unit="%",
    color_scheme="blue_purple"
)

🎨 Exemples d'utilisation

KPI avec statistiques complètes

circular_kpi(
    value=80,                    # Valeur principale
    label="Performance", 
    range=(0, 100),             # Range du cercle [0-100]
    min_value=50,               # Minimum affiché
    max_value=90,               # Maximum affiché
    mean_value=70,              # Moyenne affichée
    unit="%",
    color_scheme="blue_purple",
    size=200,
    background_color="transparent",
    key="perf"
)

Différents KPI en colonnes

col1, col2, col3, col4 = st.columns(4)

with col1:
    circular_kpi(
        value=1250,
        label="Ventes",
        range=(0, 2000),
        mean_value=1100,
        unit="€",
        color_scheme="green",
        key="sales"
    )

with col2:
    circular_kpi(
        value=12,
        label="Erreurs",
        range=(0, 50),
        mean_value=25,
        color_scheme="red",
        key="errors"
    )

with col3:
    circular_kpi(
        value=4.2,
        label="Satisfaction",
        range=(1, 5),
        mean_value=3.8,
        unit="/5",
        color_scheme="orange",
        key="satisfaction"
    )

🔧 API de référence

Paramètres

Paramètre	Type	Défaut	Description
value	float	80	Valeur principale du KPI
label	str	"KPI"	Libellé affiché sous la valeur
range	tuple	(0, 100)	Range min/max pour les calculs d'angles
min_value	float	None	Valeur minimale à afficher
max_value	float	None	Valeur maximale à afficher
mean_value	float	None	Valeur moyenne à afficher
unit	str	""	Unité affichée après la valeur
color_scheme	str	"blue_purple"	Schéma de couleurs
size	int	200	Taille du composant en pixels
show_stats	bool	True	Afficher/masquer les statistiques
background_color	str	"transparent"	Couleur de fond
percentage	float	80	Pourcentage de remplissage de l'arc
key	str	None	Clé unique pour Streamlit

Schémas de couleurs disponibles

• "blue_purple" : Dégradé bleu vers violet
• "green" : Tons de vert
• "red" : Tons de rouge
• "orange" : Tons d'orange

Valeur de retour

Le composant retourne un dictionnaire contenant :

{
    "value": 80,
    "label": "Performance", 
    "percentage": 80,
    "timestamp": "2024-01-15T10:30:00.000Z"
}

🎨 Personnalisation avancée

Couleurs personnalisées

Pour ajouter vos propres schémas de couleurs, modifiez le fichier CustomComponent.tsx :

const colorSchemes: Record<string, ColorScheme> = {
  // ... schémas existants
  custom: {
    primary: '#your-color',
    secondary: '#your-secondary-color', 
    background: 'transparent'
  }
}

Positionnement des statistiques

Les statistiques (Min, Max, Mean) sont positionnées automatiquement selon leur valeur dans le range défini :

• Position angulaire : ((valeur - min_range) / (max_range - min_range)) * 360°
• Texte extérieur : à radius + 10px du centre
• Indicateur "Mean" : à radius - 30px du centre

🛠️ Développement

Structure du projet

st_circular_kpi/
├── st_circular_kpi/
│   ├── __init__.py
│   └── frontend/
│       ├── src/
│       │   ├── CustomComponent.tsx  # Composant React principal
│       │   └── main.tsx
│       ├── package.json
│       └── index.html
├── example.py                       # Exemples d'utilisation
├── setup.py
└── README.md

Lancer l'exemple

cd st_circular_kpi
python -m streamlit run example.py

🤝 Contribution

Les contributions sont les bienvenues ! Pour contribuer :

1. Forkez le projet
2. Créez une branche feature (git checkout -b feature/nouvelle-fonctionnalite)
3. Committez vos changements (git commit -am 'Ajout nouvelle fonctionnalité')
4. Poussez vers la branche (git push origin feature/nouvelle-fonctionnalite)
5. Ouvrez une Pull Request

📄 Licence

Ce projet est sous licence MIT. Voir le fichier LICENSE pour plus de détails.

🚀 Versions

v0.1.0

• ✅ Composant KPI circulaire de base
• ✅ Schémas de couleurs prédéfinis
• ✅ Statistiques visuelles (Min/Max/Mean)
• ✅ Police Urbanist par défaut
• ✅ Arc de fond subtil pour la partie non complétée

---

Créé avec ❤️ par Antoine