Variante

Vizualizați ca Markdown Editați pe GitHub Documentație la 3843abd

variants() este o portare PHP a CVA (Class Variance Authority). Transformă o configurație declarativă — o clasă de bază, axe cu variante denumite și valori implicite — într-o funcție apelabilă care convertește proprietățile în șir de clase. Folosiți-o când o componentă are dimensiuni de stil precum mărimea și intenția, care se combină.

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() returnează un callable; apelați-l cu un array de proprietăți (sau fără argumente) pentru a obține șirul rezolvat.

Configurație

Cheie	Tip	Scop
`base`	`string`	Clase aplicate fiecărui rezultat.
`variants`	`array`	Axe denumite, fiecare mapând valorile la șiruri de clase.
`compoundVariants`	`array`	Șiruri de clase aplicate doar când se combină mai multe valori de variante.
`defaultVariants`	`array`	Valoarea fiecărei axe folosită când o proprietate este omisă.

Toate cheile sunt opționale. Dacă nu există variants, rezultatul conține base și orice clase personalizate:

PHP

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

O valoare de variantă poate fi mapată la null pentru a nu adăuga nimic — utilă ca opțiune explicită de „dezactivare” pentru o axă.

Apelarea rezultatului

Transmiteți un singur array de proprietăți, după modelul CVA. Cheile corespund numelor axelor de variante; axele omise folosesc valoarea implicită 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'

Cheia class (și aliasul său className) este adăugată la sfârșitul rezultatului. Adăugarea, de una singură, nu rezolvă conflictele — consultați mai jos modelul pentru componente.

compoundVariants

Fiecare element din compoundVariants este un array cu condițiile variantelor și un class (sau className) de clase suplimentare. Clasele se aplică doar când toate condițiile corespund proprietăților rezolvate, inclusiv celor implicite. Valoarea unei condiții poate fi un singur șir sau un array de șiruri pentru a corespunde oricăreia dintre mai multe valori.

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'

Model pentru componente

variants() doar adaugă class; pentru a le permite apelanților să suprascrie cu adevărat valorile implicite ale variantelor, încadrați rezultatul în cn(), astfel încât conflictele să se rezolve în favoarea apelantului.

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']);

Cache-ul static $styles construiește configurația variantelor o singură dată și o reutilizează la apelurile următoare.

compose()

compose() combină mai multe componente cu variante într-una singură. Funcția compusă transmite fiecare proprietate tuturor componentelor, colectează rezultatele acestora și adaugă orice 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'

Astfel, axele reutilizabile (spațiere, elevație, aspect) rămân în definiții separate și pot fi combinate pentru fiecare componentă.

Importuri

PHP

use function TailwindPHP\variants;
use function TailwindPHP\compose;

Ambele se află în spațiul de nume principal TailwindPHP și sunt incluse în pachet — o portare PHP a CVA, de Joe Bell.