Metadata-Version: 2.4
Name: xeolux-loadingkit
Version: 0.2.0
Summary: Loaders, skeleton screens, overlays et indicateurs HTMX pour Django.
Author-email: Xeolux <contact@xeolux.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/Xeolux-Corp/xeolux-loadingkit
Project-URL: Repository, https://github.com/Xeolux-Corp/xeolux-loadingkit
Project-URL: Bug Tracker, https://github.com/Xeolux-Corp/xeolux-loadingkit/issues
Keywords: django,loading,skeleton,htmx,spinner,overlay,xeolux
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Web Environment
Classifier: Framework :: Django
Classifier: Framework :: Django :: 4.2
Classifier: Framework :: Django :: 5.0
Classifier: Framework :: Django :: 5.1
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: django>=4.2
Dynamic: license-file

# xeolux-loadingkit

[![PyPI version](https://img.shields.io/pypi/v/xeolux-loadingkit)](https://pypi.org/project/xeolux-loadingkit/)
[![Python](https://img.shields.io/pypi/pyversions/xeolux-loadingkit)](https://pypi.org/project/xeolux-loadingkit/)
[![Django](https://img.shields.io/badge/django-4.2%2B-green)](https://www.djangoproject.com/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

> Package Django léger pour ajouter des loaders, skeleton screens, overlays et indicateurs HTMX dans n'importe quel projet.

Fait partie de la suite **Xeolux** — packages Django minimalistes et réutilisables.

---

## Fonctionnalités

| Template tag | Description |
|---|---|
| `{% xeolux_loadingkit_css %}` | Injecte la feuille CSS du package |
| `{% xeolux_loader %}` | Spinner animé (sm / md / lg) avec texte optionnel |
| `{% xeolux_overlay %}` | Overlay plein écran avec backdrop blur |
| `{% xeolux_skeleton %}` | Skeleton shimmer (text / card / avatar / table / form) |
| `{% xeolux_htmx_indicator %}` | Indicateur compatible HTMX |

---

## Installation

```bash
pip install xeolux-loadingkit
```

### Ajout dans `INSTALLED_APPS`

```python
# settings.py
INSTALLED_APPS = [
    ...
    "xeolux_loadingkit",
]
```

> `django.contrib.staticfiles` doit également être présent (il l'est par défaut).

---

## Utilisation

### 1. Injecter le CSS

Placez ce tag dans le `<head>` de votre template de base, **après** avoir chargé la bibliothèque :

```django
{% load xeolux_loadingkit %}

<head>
  {% xeolux_loadingkit_css %}
</head>
```

---

### 2. Loader (spinner)

```django
{# Taille par défaut (md) #}
{% xeolux_loader %}

{# Avec taille et texte #}
{% xeolux_loader size="sm" %}
{% xeolux_loader size="md" text="Chargement..." %}
{% xeolux_loader size="lg" text="Veuillez patienter" %}
```

**Paramètres :**

| Paramètre | Type | Défaut | Description |
|---|---|---|---|
| `size` | `str` | `"md"` | `"sm"`, `"md"` ou `"lg"` |
| `text` | `str\|None` | `None` | Texte affiché à côté du spinner |

---

### 3. Overlay

```django
{# Overlay inactif (caché) #}
{% xeolux_overlay %}

{# Overlay actif (visible) #}
{% xeolux_overlay text="Traitement en cours..." active=True %}
```

Pour l'activer dynamiquement via JavaScript :

```javascript
document.querySelector('.xlk-overlay').classList.add('xlk-overlay--active');
```

**Paramètres :**

| Paramètre | Type | Défaut | Description |
|---|---|---|---|
| `text` | `str` | `"Chargement en cours..."` | Texte de l'overlay |
| `active` | `bool` | `False` | Si `True`, l'overlay est visible au chargement |

---

### 4. Skeleton

```django
{# Texte (défaut) #}
{% xeolux_skeleton %}
{% xeolux_skeleton type="text" lines=4 %}

{# Card #}
{% xeolux_skeleton type="card" %}

{# Avatar #}
{% xeolux_skeleton type="avatar" %}

{# Tableau #}
{% xeolux_skeleton type="table" lines=4 rows=5 %}

{# Formulaire #}
{% xeolux_skeleton type="form" lines=3 %}
```

**Paramètres :**

| Paramètre | Type | Défaut | Description |
|---|---|---|---|
| `type` | `str` | `"text"` | `"text"`, `"card"`, `"avatar"`, `"table"`, `"form"` |
| `lines` | `int` | `3` | Nombre de lignes (text / form) ou colonnes (table) |
| `rows` | `int` | `4` | Nombre de lignes pour le type `"table"` |

---

### 5. Indicateur HTMX

```django
{% xeolux_htmx_indicator text="Chargement..." %}
```

L'indicateur est **masqué par défaut** et devient visible pendant une requête HTMX grâce à la classe `.htmx-indicator` standard.

#### Exemple complet avec HTMX

```django
<button
    hx-post="/save/"
    hx-target="#result"
    hx-indicator="#xeolux-htmx-loader">
    Enregistrer
</button>

{% xeolux_htmx_indicator text="Enregistrement..." %}
```

**Paramètres :**

| Paramètre | Type | Défaut | Description |
|---|---|---|---|
| `text` | `str` | `"Chargement..."` | Texte affiché pendant la requête |

---

## Personnalisation CSS

Toutes les valeurs visuelles sont contrôlées par des variables CSS. Surchargez-les dans votre propre feuille de style :

```css
:root {
  --xlk-primary:      #3b6cf7;   /* Couleur principale (spinner, accents) */
  --xlk-bg:           #ffffff;   /* Fond de l'overlay intérieur */
  --xlk-muted:        #e2e6f0;   /* Fond des skeletons et du spinner */
  --xlk-text:         #374151;   /* Couleur du texte */
  --xlk-overlay-bg:   rgba(15, 20, 40, 0.55); /* Fond de l'overlay plein écran */
  --xlk-radius:       0.5rem;    /* Border-radius global */
  --xlk-speed:        0.7s;      /* Vitesse des animations */
}
```

---

## Tester dans un projet Django

1. Installez le package en mode éditable depuis la racine du repo :

```bash
pip install -e /chemin/vers/xeolux-loadingkit
```

2. Ajoutez `"xeolux_loadingkit"` dans `INSTALLED_APPS`.

3. Dans n'importe quel template :

```django
{% load xeolux_loadingkit %}
{% xeolux_loadingkit_css %}
{% xeolux_loader size="md" text="Chargement..." %}
```

4. Lancez `python manage.py collectstatic` si vous êtes en production.

---

## Lancer les tests

```bash
# Depuis la racine du repo
pip install django pytest pytest-django
python -m pytest tests/ -v
```

---

## Build & Publication PyPI

### Build local

```bash
pip install build twine
python -m build
```

Les fichiers `.tar.gz` et `.whl` seront générés dans `dist/`.

### Vérifier le package

```bash
twine check dist/*
```

### Publier sur TestPyPI (recommandé avant la vraie publication)

```bash
twine upload --repository testpypi dist/*
```

Tester l'installation depuis TestPyPI :

```bash
pip install --index-url https://test.pypi.org/simple/ xeolux-loadingkit
```

### Publier sur PyPI

```bash
twine upload dist/*
```

> Vous aurez besoin d'un compte PyPI et d'un token API.  
> Configurez `~/.pypirc` ou utilisez la variable d'environnement `TWINE_PASSWORD`.

---

## Structure du projet

```
xeolux-loadingkit/
├── xeolux_loadingkit/
│   ├── __init__.py
│   ├── apps.py
│   ├── templatetags/
│   │   ├── __init__.py
│   │   └── xeolux_loadingkit.py
│   ├── templates/
│   │   └── xeolux_loadingkit/
│   │       ├── loader.html
│   │       ├── overlay.html
│   │       ├── skeleton.html
│   │       └── htmx_indicator.html
│   └── static/
│       └── xeolux_loadingkit/
│           └── css/
│               └── loadingkit.css
├── tests/
│   └── test_template_tags.py
├── README.md
├── pyproject.toml
├── LICENSE
└── MANIFEST.in
```

---

## Compatibilité

| Django | Python |
|--------|--------|
| 4.2    | 3.10, 3.11, 3.12 |
| 5.0    | 3.10, 3.11, 3.12 |
| 5.1    | 3.10, 3.11, 3.12 |

---

## Licence

MIT © [Xeolux](https://github.com/xeolux)
