# iconify_lustre

[![Package Version](https://img.shields.io/hexpm/v/iconify_lustre)](https://hex.pm/packages/iconify_lustre)
[![Hex Docs](https://img.shields.io/badge/hex-docs-ffaff3)](https://hexdocs.pm/iconify_lustre/)

A build-time tool that downloads SVG icons from [Iconify](https://iconify.design) and generates
Lustre-compatible Gleam source code. Each icon becomes a reusable `Element(msg)` function with
zero runtime overhead.

## Installation

```sh
gleam add iconify_lustre --dev
```

## Configuration

Defaults can be set in your project's `gleam.toml` under `[tools.iconify_lustre]`:

```toml
[tools.iconify_lustre]
iconset = "tabler"
module  = "iconify/*/"
```

| Key       | Default    | Description                                  |
|-----------|------------|----------------------------------------------|
| `iconset` | `lucide`   | Default Iconify icon set name                |
| `module`  | `*`        | Module path template (see [Usage](#usage))   |

## Usage

```
gleam run -m iconify_lustre/add -- [-m module]... [-s set]... <[set/]name>...
```

Icons which were added in a previous invocation are updated in place, leaving the
target module as much as possible in the same.

### Arguments

| Argument              | Description                                                              |
|-----------------------|--------------------------------------------------------------------------|
| `<name>`              | Icon name from the current icon set.                                     |
| `<set/name>`          | Icon prefixed with its icon set (overrides `-s` for that icon).          |
| `-s <set>`            | Iconify set name (e.g. `lucide`, `tabler`, `mdi`). Default: `lucide`.    |
| `-m <module>`         | Target module path. Default: `*` (replaced with the icon set name).      |

All three can be repeated and are processed left-to-right. `-s` and `-m` set the
active configuration for **subsequent** icons on the same command line.

```sh
# home from lucide (default), settings and info from tabler
gleam run -m iconify_lustre/add -- home -s tabler settings info
```

When multiple `-s` or `-m` flags are interleaved with icon names, each icon
uses the most recent `-s` and `-m` values at that position:

### The `-m` (module) placeholder

The `*` character in the module path is replaced with the sanitised icon set name.

| Pattern                    | Result for `lucide/home`                       |
|----------------------------|------------------------------------------------|
| `*`                        | `src/lucide.gleam` → `fn home()`               |
| `iconify/*/`               | `src/iconify/lucide/home.gleam` → `fn home()`  |
| `iconify/*`                | `src/iconify/lucide.gleam` → `fn home()`       |
| `custom/icons`             | `src/custom/icons.gleam` → `fn home()`         |

When the module ends with `/`, the icon name is appended as the file name.

### Examples

```sh
# Single icon from the default set (lucide)
gleam run -m iconify_lustre/add -- home

# Explicit set and module directory, the modules will be icons/tabler/home.gleam
# and icons/tabler/settings.gleam
gleam run -m iconify_lustre/add -- -s tabler -m "icons/tabler/" home settings

# Mixed notation – first uses default set, second overrides the set with the `tabler' set
gleam run -m iconify_lustre/add -- home tabler/settings

# Multiple icons
gleam run -m iconify_lustre/add -- home mail user
```

### Usage in lustre view

Running `gleam run -m iconify_lustre/add -- -m icons home` creates `src/icons.gleam`
with a function `fn home(attributes: List(attribute.Attribute))`. This can
then be used as:

```gleam
import icons.{home}
import lucide/element.{type Element}
import lucide/attributes.{attribute}

pub fn view() -> Element(msg) {
  home([attribute("class", "icon icon--large")])
}
```

The `attributes`-argument can be used to override default attributes or add new
attributes giving you some additional flexibility.