Metadata-Version: 2.4
Name: xeolux-iconkit
Version: 1.1.0
Summary: A reusable Django icon library with 300+ SVG icons — outline, solid, minimal, brand + thematic packs.
Home-page: https://github.com/xeolux/xeolux-iconkit
Author: Xeolux
Author-email: contact@xeolux.com
License: MIT
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Framework :: Django
Classifier: Framework :: Django :: 3.2
Classifier: Framework :: Django :: 4.0
Classifier: Framework :: Django :: 4.1
Classifier: Framework :: Django :: 4.2
Classifier: Framework :: Django :: 5.0
Classifier: Framework :: Django :: 5.1
Classifier: Framework :: Django :: 5.2
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: Django>=3.2
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# Xeolux IconKit

> A professional, reusable SVG icon library for Django — outline · solid · minimal · brand

[![PyPI version](https://img.shields.io/pypi/v/xeolux-iconkit.svg)](https://pypi.org/project/xeolux-iconkit/)
[![Python](https://img.shields.io/pypi/pyversions/xeolux-iconkit.svg)](https://pypi.org/project/xeolux-iconkit/)
[![Django](https://img.shields.io/pypi/djversions/xeolux-iconkit.svg)](https://pypi.org/project/xeolux-iconkit/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

---

## Features

- **Inline SVG** — no fonts, no external requests, fully offline
- **4 icon styles** — `outline`, `solid`, `minimal`, `brand`
- **Django template tag** — simple, expressive syntax
- **Customisable** — size, color, CSS class, and any HTML attribute
- **Bootstrap & TailwindCSS compatible** — uses `currentColor` throughout
- **Accessible** — `aria-hidden` by default, supports `aria_label`
- **Zero JavaScript** — pure server-side rendering

---

## Installation

```bash
pip install xeolux-iconkit
```

Add to `INSTALLED_APPS` in your Django settings:

```python
INSTALLED_APPS = [
    ...
    "xeolux_iconkit",
]
```

---

## Quick Start

Load the template tag at the top of any template:

```django
{% load iconkit %}
```

Then use the `{% icon %}` tag:

```django
{# Basic usage #}
{% icon "home" %}

{# With size (number = px, or CSS units) #}
{% icon "user" size="24" %}
{% icon "settings" size="1.5rem" %}

{# With CSS class #}
{% icon "settings" class="text-primary" %}

{# Choose style #}
{% icon "phone" style="outline" %}
{% icon "phone" style="solid" %}
{% icon "phone" style="minimal" %}
{% icon "github" style="brand" %}

{# Custom color #}
{% icon "star" color="#f59e0b" %}

{# Full customisation #}
{% icon "bell" size="20" style="solid" class="icon-bell" aria_label="Notifications" %}

{# Dynamic name from context variable #}
{% icon icon_name size="24" %}
```

---

## Template Tag Reference

```
{% icon NAME [size=VALUE] [style=STYLE] [color=HEX] [class=CSS] [ATTR=VALUE ...] %}
```

| Argument | Type | Default | Description |
|---|---|---|---|
| `NAME` | string / variable | — | Icon name (e.g. `"home"`) |
| `size` | string | — | Width & height — plain number (`"24"` → `24px`) or CSS unit (`"1.5rem"`) |
| `style` | string | `outline` | Icon variant: `outline`, `solid`, `minimal`, `brand` |
| `color` | string | — | CSS `color` property (works with `currentColor` fills) |
| `class` | string | — | Extra CSS classes on the `<svg>` element |
| `aria_label` | string | — | Renders as `aria-label` attribute (any `_` becomes `-`) |
| any other | string | — | Passed as sanitised HTML attribute |

---

## Global Configuration

In your Django settings you can override the default style:

```python
# settings.py
XEOLUX_ICONKIT_DEFAULT_STYLE = "solid"   # default: "outline"
```

---

## Available Icons

### Outline / Solid / Minimal
| Name | Category |
|---|---|
| `home` | Navigation |
| `user` | User |
| `settings` | UI |
| `phone` | Contact |
| `mail` | Contact |
| `search` | UI |
| `bell` | UI |
| `cart` | E-commerce |
| `menu` | Navigation |
| `close` | UI |
| `plus` | UI |
| `trash` | UI |
| `edit` | UI |
| `star` | UI |
| `warning` | Status |
| `check-circle` | Status |
| `chart` | Dashboard |
| `lock` | Security |

### Brand
| Name |
|---|
| `github` |
| `twitter` |
| `linkedin` |
| `django` |

> **Adding your own icons:** drop a `.svg` file in the appropriate style folder:
> `xeolux_iconkit/static/xeolux_iconkit/icons/<style>/<name>.svg`

---

## Integration Examples

### Bootstrap button with icon

```django
{% load iconkit %}

<button class="btn btn-primary d-flex align-items-center gap-2">
  {% icon "plus" size="16" %} Ajouter
</button>

<button class="btn btn-danger d-flex align-items-center gap-2">
  {% icon "trash" size="16" %} Supprimer
</button>
```

### TailwindCSS

```django
{% load iconkit %}

<button class="flex items-center gap-2 px-4 py-2 bg-blue-600 text-white rounded-lg">
  {% icon "plus" size="16" class="text-white" %} Nouveau
</button>
```

### Navbar

```django
{% load iconkit %}

<nav>
  <a href="/">{% icon "home" size="20" %} Accueil</a>
  <a href="/profile/">{% icon "user" size="20" %} Profil</a>
  <a href="/settings/">{% icon "settings" size="20" %} Paramètres</a>
</nav>
```

### Dashboard card

```django
{% load iconkit %}

<div class="card p-4 flex gap-3">
  <div class="text-indigo-500">{% icon "chart" size="32" %}</div>
  <div>
    <h3>Statistiques</h3>
    <p>Vue globale de vos données</p>
  </div>
</div>
```

### Django Admin (custom header)

```python
# admin.py
from django.contrib import admin
from django.utils.safestring import mark_safe
from xeolux_iconkit.registry import get_icon_svg

class MyModelAdmin(admin.ModelAdmin):
    def get_list_display(self, request):
        return ["icon_col", "name"]

    def icon_col(self, obj):
        svg = get_icon_svg("star", style="solid")
        return mark_safe(f'<span style="color:#f59e0b">{svg}</span>')
    icon_col.short_description = "Icône"
```

---

## Running the Demo

```bash
cd example
pip install -e ..
python manage.py runserver
# → http://127.0.0.1:8000/
```

---

## Running Tests

```bash
pip install pytest pytest-django django
pytest tests/ -v
```

---

## Project Structure

```
xeolux-iconkit/
├── xeolux_iconkit/                  # Django application
│   ├── __init__.py
│   ├── apps.py
│   ├── registry.py                  # Icon resolution logic
│   ├── templatetags/
│   │   ├── __init__.py
│   │   └── iconkit.py               # {% icon %} template tag
│   └── static/
│       └── xeolux_iconkit/
│           └── icons/
│               ├── outline/         # Stroke icons (1.5px)
│               ├── solid/           # Filled icons
│               ├── minimal/         # Ultra-thin icons (1px)
│               └── brand/           # Brand / logo icons
├── example/                         # Demo Django project
│   ├── demo_project/
│   └── demo/
│       └── templates/demo/index.html
├── tests/
│   └── test_iconkit.py
├── setup.py
├── setup.cfg
├── pyproject.toml
├── MANIFEST.in
├── LICENSE
└── README.md
```

---

## Contributing

1. Fork the repository
2. Add your SVG icon to the correct style folder
3. Follow the naming convention: `kebab-case.svg`
4. Ensure the SVG uses `currentColor` for stroke/fill
5. Open a Pull Request

---

## License

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