# PCM Badge Bundle

Create badges from objects or as standalone elements.

![PCM Badge Bundle showcase](docs/showcase.png)

```twig
<twig:Pcm:Badge :obj="job.kind">{{ job.kind.label }}</twig:Pcm:Badge>

<twig:Pcm:Badge :obj="job.kind" outline>{{ job.kind.label }}</twig:Pcm:Badge>

<twig:Pcm:Badge colour="green">Sale 20% off</twig:Pcm:Badge>

<twig:Pcm:Badge class="text-xl p-8" colour="maroon" outline>Danger!</twig:Pcm:Badge>
```

<br>

# Creating badges with `BadgeableInterface`

Any object that you would like to be able to be turned into a badge must implement `BadgeableInterface`.

You can use `BadgeableTrait` to get a default implementation.

The interface specifies two methods:

- `getBadgeColour(): BadgeColour` — returns the enum case that determines the badge's colour.
- `getBadgeIcon(): ?string` — returns an [Iconify](https://iconify.design) icon name (e.g. `material-symbols:add-alert`), or `null` for no icon.

Either method can contain as much logic as you like:

```php
// Job.php

public function getBadgeColour(): BadgeColour
{
    return match ($this->getKind()) {
        JobKind::Investigation => BadgeColour::BLUE,
        JobKind::Interrogation => BadgeColour::RED,
        JobKind::Shootout      => BadgeColour::BLACK,
        JobKind::SipWhiskey    => BadgeColour::FOREST,
        default                => BadgeColour::GREY
    };
}

public function getBadgeIcon(): ?string
{
    return null;
}
```

You then specify the object using the `:obj` prop when rendering the badge:

```twig
{# job.html.twig #}

<twig:Pcm:Badge :obj="job">{{ job.kind.value }}</twig:Pcm:Badge>
```

## Using `BadgeableTrait`

If you only care about one of the interface methods, use `BadgeableTrait` for sensible defaults (`BadgeColour::DEFAULT` and no icon) and override only what you need:

```php
use Pcm\BadgeBundle\Interface\BadgeableInterface;
use Pcm\BadgeBundle\Trait\BadgeableTrait;

class Job implements BadgeableInterface
{
    use BadgeableTrait;

    public function getBadgeColour(): BadgeColour
    {
        return BadgeColour::BLUE;
    }
    // getBadgeIcon() inherited from the trait — returns null
}
```

<br>

# Standalone badges

If you just want a badge of a certain colour instead of associating it with an object, you can specify a `colour` prop instead.

```twig
<twig:Pcm:Badge colour="red">Danger</twig:Pcm:Badge>
```

<br>

# Props overview

A badge must contain either an `obj` or a `colour`, but not both.

`obj` - An instance of an object that implements `BadgeableInterface`. You can use either of the follow syntaxes:
```twig
:obj="job.kind"

obj="{{ job.kind }}"
```

`colour` - One of the available colours specified by the `BadgeColour` enum. The palette covers the usual primaries plus tones like `cyan`, `indigo`, `purple`, `slate`, `stone`, `teal` and `violet` — see `src/Enum/BadgeColour.php` for the full list, or pass an invalid value and read the exception message.

`outline` - A boolean attribute that changes the style of the badge to an outline.

`glossy` - A boolean attribute that adds a gradient sheen to the badge. Cannot be combined with `outline` — passing both will throw an exception.

`icon` - Render an icon to the left of the label. Pass an [Iconify](https://iconify.design) name (e.g. `icon="material-symbols:add-alert"`) to use a specific icon, or pass it as a boolean (`icon`) when using `:obj` to use the icon returned by `getBadgeIcon()`. Requires `symfony/ux-icons` in the host project.

`class` - Extra classes you want to add to the badge element. These are merged with the badge base classes taking priority in case of conflicts.

`label` - Badge label text. Content inside the content block will be prioritised over the label attribute if present.
```php
{# Both of these render the same markup. #}

<twig:Pcm:Badge colour="red" label="Warning!" />

<twig:Pcm:Badge colour="red">Warning!<twig:Pcm:Badge>
```

<br>

# Config

```yaml
pcm_badge:
    base_classes: "base classes here"
```

<br>

# Local development

The bundle ships with a small Symfony preview app under `dev/` that renders many different badge variants.

```bash
just composer_install   # install dependencies
just serve              # start the preview at http://localhost:8000
```

Edit `dev/templates/showcase.html.twig` to add or tweak variants — changes are picked up on refresh. Other handy recipes (see `justfile`):