# Utilitários de classes

Criar atributos `class` em templates significa combinar strings, alternar classes conforme condições e impedir que utilitários posteriores entrem em conflito com os anteriores (`p-2` e `p-4` não devem coexistir). Em JavaScript, esse trabalho é dividido entre [clsx](https://github.com/lukeed/clsx) e [tailwind-merge](https://github.com/dcastil/tailwind-merge). TailwindPHP inclui PHP implementações de ambos, para que você tenha o mesmo comportamento sem cadeia de ferramentas Node.js e sem pacotes Composer adicionais.

Três funções cobrem todos os casos: `cn()` cria e resolve conflitos, `merge()` apenas resolve conflitos e `join()` apenas concatena.

## cn()

O utilitário recomendado. Primeiro, executa a criação condicional no estilo clsx e, em seguida, resolve conflitos Tailwind com tailwind-merge — assim, o último utilitário conflitante prevalece.

```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'
```

### Argumentos aceitos

`cn()` aceita qualquer número de argumentos. Cada um é nivelado e filtrado seguindo a semântica de clsx:

| Argumento | Comportamento |
|----------|----------|
| `string` | Adicionado como está. |
| `int` / `float` | Convertidos em strings e adicionados. |
| Array sequencial | Cada elemento é processado recursivamente. |
| Array `key => bool` | Cada chave é adicionada quando seu valor é verdadeiro. |
| `null`, `false`, `0`, `''` | Ignorados. |

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

### Padrão de componente

`cn()` permite sobrescrever um componente: combine as classes do próprio componente com as fornecidas por quem o chama, e os conflitos serão resolvidos a favor de quem o chama.

```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>
```

Para estilos declarativos de componentes com múltiplos eixos, combine `cn()` com [variants()](https://tailwindphp.inline0.dev/pt/docs/class-utilities/variants).

## merge()

Apenas resolução de conflitos — sem criação condicional. Passe strings de classe; as classes posteriores sobrescrevem as anteriores quando visam a mesma propriedade. Use quando sua entrada já consistir em strings simples.

```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()` construído sobre clsx; portanto, use `merge()` diretamente apenas quando não precisar da sintaxe condicional de arrays.

## join()

Concatenação simples, sem resolução de conflitos. Valores falsos são descartados, mas todos os utilitários conflitantes são mantidos. Use quando souber que não há conflitos e quiser a opção mais econômica.

```php
use function TailwindPHP\join;

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

## Qual devo usar?

| Função | Cria (condições, arrays) | Resolve conflitos | Use quando |
|----------|:---:|:---:|----------|
| `cn()`    | sim | sim | Opção padrão — ao criar strings de classe que podem entrar em conflito. |
| `merge()` | não  | sim | A entrada consiste em strings simples; você só precisa resolver conflitos. |
| `join()`  | sim | não  | Você sabe que não há conflitos e quer fazer o mínimo possível. |

## Importações

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

As três ficam no namespace principal `TailwindPHP` e são incluídas no pacote. São implementações PHP de clsx (de Luke Edwards) e tailwind-merge (de Dany Castillo).