Introduce CVA to html-extra

Author: WebMamba

Cva.php

@@ -0,0 +1,129 @@
+<?php
+
+/*
+ * This file is part of Twig.
+ *
+ * (c) Fabien Potencier
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Twig\Extra\Html;
+
+/**
+ * Class Variant Authority (CVA) resolver.
+ *
+ * @author Mathéo Daninos <matheo.daninos@gmail.com>
+ */
+final class Cva
+{
+    /**
+     * @var list<string|null>
+     */
+    private array $base;
+
+    /**
+     * @param string|list<string|null> $base The base classes to apply to the component
+     */
+    public function __construct(
+        string|array $base = [],
+        /**
+         * The variants to apply based on recipes.
+         *
+         * Format: [variantCategory => [variantName => classes]]
+         *
+         * Example:
+         *      'colors' => [
+         *          'primary' => 'bleu-8000',
+         *          'danger' => 'red-800 text-bold',
+         *       ],
+         *      'size' => [...],
+         *
+         * @var array<string, array<string, string|list<string>>>
+         */
+        private array $variants = [],
+
+        /**
+         * The compound variants to apply based on recipes.
+         *
+         * Format: [variantsCategory => ['variantName', 'variantName'], class: classes]
+         *
+         * Example:
+         *   [
+         *      'colors' => ['primary'],
+         *      'size' => ['small'],
+         *      'class' => 'text-red-500',
+         *   ],
+         *   [
+         *      'size' => ['large'],
+         *      'class' => 'font-weight-500',
+         *   ]
+         *
+         * @var array<array<string, string|array<string>>>
+         */
+        private array $compoundVariants = [],
+
+        /**
+         * The default variants to apply if specific recipes aren't provided.
+         *
+         * Format: [variantCategory => variantName]
+         *
+         * Example:
+         *     'colors' => 'primary',
+         *
+         * @var array<string, string>
+         */
+        private array $defaultVariants = [],
+    ) {
+        $this->base = (array) $base;
+    }
+
+    public function apply(array $recipes, ?string ...$additionalClasses): string
+    {
+        $classes = $this->base;
+
+        // Resolve recipes against variants
+        foreach ($recipes as $recipeName => $recipeValue) {
+            if (\is_bool($recipeValue)) {
+                $recipeValue = $recipeValue ? 'true' : 'false';
+            }
+            $recipeClasses = $this->variants[$recipeName][$recipeValue] ?? [];
+            $classes = [...$classes, ...(array) $recipeClasses];
+        }
+
+        // Resolve compound variants
+        foreach ($this->compoundVariants as $compound) {
+            $compoundClasses = $this->resolveCompoundVariant($compound, $recipes) ?? [];
+            $classes = [...$classes, ...$compoundClasses];
+        }
+
+        // Apply default variants if specific recipes aren't provided
+        foreach ($this->defaultVariants as $defaultVariantName => $defaultVariantValue) {
+            if (!isset($recipes[$defaultVariantName])) {
+                $variantClasses = $this->variants[$defaultVariantName][$defaultVariantValue] ?? [];
+                $classes = [...$classes, ...(array) $variantClasses];
+            }
+        }
+        $classes = [...$classes, ...array_values($additionalClasses)];
+
+        $classes = implode(' ', array_filter($classes, 'is_string'));
+        $classes = preg_split('#\s+#', $classes, -1, \PREG_SPLIT_NO_EMPTY) ?: [];
+
+        return implode(' ', array_unique($classes));
+    }
+
+    private function resolveCompoundVariant(array $compound, array $recipes): array
+    {
+        foreach ($compound as $compoundName => $compoundValues) {
+            if ('class' === $compoundName) {
+                continue;
+            }
+            if (!isset($recipes[$compoundName]) || !\in_array($recipes[$compoundName], (array) $compoundValues)) {
+                return [];
+            }
+        }
+
+        return (array) ($compound['class'] ?? []);
+    }
+}

HtmlExtension.php

@@ -37,6 +37,7 @@ public function getFunctions(): array
     {
         return [
             new TwigFunction('html_classes', [self::class, 'htmlClasses']),
+            new TwigFunction('html_cva', [self::class, 'htmlCva']),
         ];
     }
 
@@ -110,4 +111,17 @@ public static function htmlClasses(...$args): string
 
         return implode(' ', array_unique(array_filter($classes, static function ($v) { return '' !== $v; })));
     }
+
+    /**
+     * @param string|list<string|null> $base
+     * @param array<string, array<string, string|array<string>> $variants
+     * @param array<array<string, string|array<string>>> $compoundVariants
+     * @param array<string, string> $defaultVariant
+     *
+     * @internal
+     */
+    public static function htmlCva(array|string $base = [], array $variants = [], array $compoundVariants = [], array $defaultVariant = []): Cva
+    {
+        return new Cva($base, $variants, $compoundVariants, $defaultVariant);
+    }
 }

README.md

@@ -9,5 +9,8 @@ This package is a Twig extension that provides the following:
  * [`html_classes`][2] function: returns a string by conditionally joining class
    names together.
 
+ * [`html_cva`][3] function: returns a `Cva` object to handle class variants.
+
 [1]: https://twig.symfony.com/data_uri
 [2]: https://twig.symfony.com/html_classes
+[3]: https://twig.symfony.com/html_cva