# Utility per le classi

Creare attributi `class` nei template significa unire stringhe, attivare o disattivare classi in base a condizioni e impedire che le utility successive entrino in conflitto con quelle precedenti (`p-2` e `p-4` non dovrebbero essere presenti entrambe). In JavaScript questo lavoro è suddiviso tra [clsx](https://github.com/lukeed/clsx) e [tailwind-merge](https://github.com/dcastil/tailwind-merge). TailwindPHP include port di PHP entrambe, per ottenere lo stesso comportamento senza toolchain Node.js e senza pacchetti Composer aggiuntivi.

Tre funzioni coprono tutte le esigenze: `cn()` crea e risolve i conflitti, `merge()` risolve solo i conflitti e `join()` concatena soltanto.

## cn()

L'utility consigliata. Prima crea le classi condizionali con la sintassi di clsx, poi risolve i conflitti Tailwind con tailwind-merge: in caso di conflitto, prevale l'ultima utility.

```php
use function TailwindPHP\cn;

// Conflicts are resolved — px-4 overrides px-2
cn('px-2 py-1', 'px-4');
// => 'py-1 px-4'

// Conditional classes via a key => bool array
cn('btn', ['btn-primary' => true, 'btn-disabled' => false]);
// => 'btn btn-primary'
```

### Argomenti accettati

`cn()` accetta un numero qualsiasi di argomenti. Ognuno viene appiattito e filtrato secondo la semantica di clsx:

| Argomento | Comportamento |
|----------|----------|
| `string` | Aggiunto così com'è. |
| `int` / `float` | Convertiti in stringa e aggiunti. |
| Array sequenziale | Ogni elemento viene elaborato ricorsivamente. |
| Array `key => bool` | Ogni chiave viene aggiunta se il relativo valore è truthy. |
| `null`, `false`, `0`, `''` | Ignorati. |

```php
cn('flex', ['items-center' => true], ['p-4', ['gap-2']], null);
// => 'flex items-center p-4 gap-2'
```

### Schema del componente

`cn()` permette di sovrascrivere un componente: unite le classi del componente a quelle passate da chi lo richiama; in caso di conflitto prevalgono quelle del chiamante.

```php
use function TailwindPHP\cn;

function Card(array $props = []): string {
    $class = cn(
        'rounded-lg border bg-card text-card-foreground shadow-sm',
        $props['class'] ?? null
    );
    return "<div class=\"{$class}\">" . ($props['children'] ?? '') . "</div>";
}

Card(['class' => 'p-6', 'children' => 'Content']);
// <div class="rounded-lg border bg-card text-card-foreground shadow-sm p-6">Content</div>
```

Per stili di componenti dichiarativi con più assi, abbinate `cn()` a [variants()](https://tailwindphp.inline0.dev/it/docs/class-utilities/variants).

## merge()

Solo risoluzione dei conflitti, senza creazione condizionale. Passate stringhe di classi; quelle successive sovrascrivono le precedenti quando agiscono sulla stessa proprietà. Usatela quando l'input è già composto da semplici stringhe.

```php
use function TailwindPHP\merge;

merge('px-2 py-1 bg-red-500', 'px-4 bg-blue-500');
// => 'py-1 px-4 bg-blue-500'

// Conflict resolution is variant-aware
merge('hover:bg-red-500', 'hover:bg-blue-500');
// => 'hover:bg-blue-500'
```

`cn()` è `merge()` costruito sopra clsx; usate direttamente `merge()` solo se non vi serve la sintassi condizionale degli array.

## join()

Semplice concatenazione senza risoluzione dei conflitti. I valori falsy vengono eliminati, ma le utility in conflitto vengono mantenute tutte. Usatela quando sapete che non ci sono conflitti e volete l'opzione più leggera.

```php
use function TailwindPHP\join;

join('foo', 'bar', null, 'baz');
// => 'foo bar baz'
```

## Quale scegliere?

| Funzione | Crea (condizioni, array) | Risolve i conflitti | Da usare quando |
|----------|:---:|:---:|----------|
| `cn()`    | sì | sì | Scelta predefinita: per creare stringhe di classi che potrebbero entrare in conflitto. |
| `merge()` | no  | sì | L'input è composto da semplici stringhe e serve solo risolvere i conflitti. |
| `join()`  | sì | no  | Sapete che non ci sono conflitti e volete ridurre al minimo le operazioni. |

## Importazioni

```php
use function TailwindPHP\cn;
use function TailwindPHP\merge;
use function TailwindPHP\join;
```

Tutte e tre sono disponibili nello spazio dei nomi principale `TailwindPHP` e sono incluse nel pacchetto. Sono port PHP di clsx (di Luke Edwards) e tailwind-merge (di Dany Castillo).