# バリアント

`variants()`は[CVA（Class Variance Authority）](https://github.com/joe-bell/cva)のPHP移植版です。base、名前付きのvariant軸、既定値からなる宣言的な設定を、propsをクラス文字列に変換する関数にします。サイズや意図など、組み合わせて使うスタイルの種類があるコンポーネントに適しています。

```php
use function TailwindPHP\variants;

$button = variants([
    'base' => 'btn font-semibold border rounded',
    'variants' => [
        'intent' => [
            'primary'   => 'bg-blue-500 text-white',
            'secondary' => 'bg-gray-200 text-gray-800',
        ],
        'size' => [
            'sm' => 'text-sm px-2 py-1',
            'md' => 'text-base px-4 py-2',
        ],
    ],
    'defaultVariants' => [
        'intent' => 'primary',
        'size'   => 'md',
    ],
]);

$button();
// => 'btn font-semibold border rounded bg-blue-500 text-white text-base px-4 py-2'
```

`variants()`は`callable`を返します。props配列を渡す（または何も渡さない）と、解決済みの文字列を取得できます。

## 設定

| キー | 型 | 用途 |
|-----|------|---------|
| `base` | `string` | すべての出力に適用されるクラス。 |
| `variants` | `array` | 名前付きの軸。それぞれの値の名前をクラス文字列に対応付けます。 |
| `compoundVariants` | `array` | 複数のvariant値が組み合わさった場合にのみ適用されるクラス文字列。 |
| `defaultVariants` | `array` | propが省略された場合に使う、軸ごとの値。 |

すべてのキーは省略可能です。`variants`がない場合、結果には`base`とカスタムクラスが含まれます。

```php
$x = variants(['base' => 'box']);
$x();                          // => 'box'
$x(['class' => 'p-4']);        // => 'box p-4'
```

variant値に`null`を指定すると何も追加されません。軸の明示的な「未設定」オプションとして便利です。

## 戻り値の呼び出し方

CVAと同じ形式で、props配列を1つ渡します。キーはvariant軸の名前に対応し、省略した軸には`defaultVariants`が適用されます。

```php
$button(['intent' => 'secondary']);
// => 'btn font-semibold border rounded bg-gray-200 text-gray-800 text-base px-4 py-2'

$button(['size' => 'sm', 'class' => 'mt-4']);
// => 'btn font-semibold border rounded bg-blue-500 text-white text-sm px-2 py-1 mt-4'
```

`class`キー（別名`className`）は出力の末尾に追加されます。追加するだけでは競合は解決されません。解決方法は以下のコンポーネントのパターンを参照してください。

## compoundVariants

`compoundVariants`の各項目は、variant条件の配列と、追加クラスを指定する`class`（または`className`）で構成されます。解決後のprops（既定値を含む）がすべての条件に一致する場合にのみ、クラスが適用されます。条件値には単一の文字列、または複数の値のいずれかに一致させる文字列配列を指定できます。

```php
$button = variants([
    'base' => 'btn',
    'variants' => [
        'intent' => [
            'primary' => 'bg-blue-500',
            'warning' => 'bg-yellow-500',
            'danger'  => 'bg-red-500',
        ],
        'size' => ['sm' => 'text-sm', 'md' => 'text-base'],
    ],
    'compoundVariants' => [
        // Applies only when intent=primary AND size=md
        ['intent' => 'primary', 'size' => 'md', 'class' => 'uppercase'],
        // Applies when intent is warning OR danger
        ['intent' => ['warning', 'danger'], 'class' => '!border-red-500'],
    ],
    'defaultVariants' => ['intent' => 'primary', 'size' => 'md'],
]);

$button();
// => 'btn bg-blue-500 text-base uppercase'

$button(['intent' => 'danger']);
// => 'btn bg-red-500 text-base !border-red-500'
```

## コンポーネントのパターン

`variants()`は`class`を追加するだけです。呼び出し側がvariantの既定値を実際に上書きできるようにするには、出力を[cn()](https://tailwindphp.inline0.dev/ja/docs/class-utilities)で囲み、競合時に呼び出し側の指定が優先されるようにしてください。

```php
use function TailwindPHP\variants;
use function TailwindPHP\cn;

function Button(array $props = []): string {
    static $styles = null;
    $styles ??= variants([
        'base' => 'inline-flex items-center justify-center rounded-md font-medium',
        'variants' => [
            'variant' => [
                'default' => 'bg-primary text-primary-foreground hover:bg-primary/90',
                'outline' => 'border border-input bg-background hover:bg-accent',
                'ghost'   => 'hover:bg-accent hover:text-accent-foreground',
            ],
            'size' => [
                'default' => 'h-10 px-4 py-2',
                'sm'      => 'h-9 px-3',
                'lg'      => 'h-11 px-8',
            ],
        ],
        'defaultVariants' => ['variant' => 'default', 'size' => 'default'],
    ]);

    // cn() merges variant output with custom classes, resolving conflicts
    $class = cn($styles($props), $props['class'] ?? null);
    $text  = $props['children'] ?? 'Button';
    return "<button class=\"{$class}\">{$text}</button>";
}

// The custom px-8 wins over the variant's px-3 via cn()
Button(['variant' => 'outline', 'size' => 'sm', 'class' => 'mt-4 px-8']);
```

`static $styles`キャッシュはvariant設定を一度構築し、呼び出し間で再利用します。

## compose()

`compose()`は複数のvariantコンポーネントを1つにまとめます。合成された関数は各propをすべてのコンポーネントに渡し、それぞれの出力を集めて、`class`/`className`も追加します。

```php
use function TailwindPHP\variants;
use function TailwindPHP\compose;

$box   = variants(['variants' => ['shadow' => ['sm' => 'shadow-sm', 'md' => 'shadow-md']]]);
$stack = variants(['variants' => ['gap' => ['1' => 'gap-1', '2' => 'gap-2']]]);
$card  = compose($box, $stack);

$card(['shadow' => 'md', 'gap' => '2']);
// => 'shadow-md gap-2'
```

これにより、再利用可能な軸（間隔、高さ、レイアウト）を別々に定義し、コンポーネントごとに組み合わせられます。

## インポート

```php
use function TailwindPHP\variants;
use function TailwindPHP\compose;
```

どちらもメインの`TailwindPHP`名前空間にあり、パッケージに同梱されています。Joe BellによるCVAのPHP移植版です。