# Narzędzia klas

Budowanie atrybutów `class` w szablonach wymaga łączenia ciągów, przełączania klas zależnie od warunków i zapobiegania konfliktom późniejszych utility z wcześniejszymi (`p-2` i `p-4` nie powinny występować jednocześnie). W JavaScript zadania te rozdzielono między [clsx](https://github.com/lukeed/clsx) i [tailwind-merge](https://github.com/dcastil/tailwind-merge). TailwindPHP zawiera porty PHP obu narzędzi, dzięki czemu uzyskujesz takie samo działanie bez narzędzi Node.js i dodatkowych pakietów Composer.

Trzy funkcje obejmują cały zakres zastosowań: `cn()` tworzy i rozwiązuje konflikty, `merge()` tylko rozwiązuje konflikty, a `join()` jedynie łączy ciągi.

## cn()

Zalecana funkcja utility. Najpierw wykonuje warunkowe tworzenie w stylu clsx, a następnie rozwiązuje konflikty Tailwind za pomocą tailwind-merge — wygrywa więc ostatnie konfliktujące 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'
```

### Akceptowane argumenty

`cn()` przyjmuje dowolną liczbę argumentów. Każdy jest spłaszczany i filtrowany zgodnie z semantyką clsx:

| Argument | Działanie |
|----------|----------|
| `string` | Dodany bez zmian. |
| `int` / `float` | Konwertowane na ciąg i dodawane. |
| Tablica sekwencyjna | Każdy element jest przetwarzany rekurencyjnie. |
| Tablica `key => bool` | Każdy klucz jest dodawany, gdy jego wartość jest prawdziwa. |
| `null`, `false`, `0`, `''` | Pomijane. |

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

### Wzorzec komponentu

`cn()` umożliwia nadpisywanie komponentu: połącz jego własne klasy z klasami przekazanymi przez wywołującego, a konflikty zostaną rozstrzygnięte na korzyść wywołującego.

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

W przypadku deklaratywnych stylów komponentów o wielu osiach połącz `cn()` z [variants()](https://tailwindphp.inline0.dev/pl/docs/class-utilities/variants).

## merge()

Samo rozwiązywanie konfliktów — bez warunkowego tworzenia. Przekazuj ciągi klas; późniejsze klasy nadpisują wcześniejsze, jeśli dotyczą tej samej właściwości. Użyj tej funkcji, gdy dane wejściowe są już zwykłymi ciągami.

```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()` jest `merge()` opartym na clsx, więc sięgnij bezpośrednio po `merge()` tylko wtedy, gdy nie potrzebujesz składni tablic warunkowych.

## join()

Proste łączenie bez rozwiązywania konfliktów. Wartości fałszywe są pomijane, ale wszystkie konfliktujące utility zostają zachowane. Użyj tej funkcji, gdy wiesz, że nie ma konfliktów i zależy Ci na najtańszym rozwiązaniu.

```php
use function TailwindPHP\join;

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

## Której funkcji użyć?

| Funkcja | Tworzy (warunki, tablice) | Rozwiązuje konflikty | Użyj, gdy |
|----------|:---:|:---:|----------|
| `cn()`    | tak | tak | Domyślny wybór — do tworzenia ciągów klas, w których mogą występować konflikty. |
| `merge()` | nie  | tak | Dane wejściowe to zwykłe ciągi; potrzebujesz tylko rozwiązywania konfliktów. |
| `join()`  | tak | nie  | Wiesz, że nie ma konfliktów i chcesz wykonać jak najmniej pracy. |

## Importy

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

Wszystkie trzy funkcje znajdują się w głównej przestrzeni nazw `TailwindPHP` i są dołączone do pakietu. To porty PHP clsx (autorstwa Luke’a Edwardsa) i tailwind-merge (autorstwa Dany’ego Castillo).