[TwigComponent] Deprecate cva twig function

Author: Kocal

CHANGELOG.md

@@ -3,6 +3,7 @@
 ## 2.20.0
 
 -  Add Anonymous Component support for 3rd-party bundles #2019
+-  Deprecate `cva` Twig function in favor of [`html_cva` from `twig/html-extra`](https://twig.symfony.com/html_cva) #2144
 
 ## 2.17.0
 

doc/index.rst

@@ -1158,6 +1158,11 @@ Component with Complex Variants (CVA)
 
     The ``cva`` function was added in TwigComponents 2.16.
 
+.. deprecated:: 2.20
+
+    The ``cva`` function was deprecated in TwigComponents 2.20, and will be removed in 3.0.
+    The function is now provided by the ``twig/html-extra:^3.12`` package under the name `html_cva`_.
+
 `CVA (Class Variant Authority)`_ is a concept from the JavaScript world and used
 by the well-known `shadcn/ui`_.
 CVA allows you to display a component with different variants (color, size, etc.),
@@ -1763,6 +1768,7 @@ https://symfony.com/doc/current/contributing/code/bc.html
 .. _`Passing Blocks to Live Components`: https://symfony.com/bundles/ux-live-component/current/index.html#passing-blocks
 .. _`Stimulus controller`: https://symfony.com/bundles/StimulusBundle/current/index.html
 .. _`CVA (Class Variant Authority)`: https://cva.style/docs/getting-started/variants
+.. _`html_cva`: https://twig.symfony.com/doc/3.x/functions/html_cva.html
 .. _`shadcn/ui`: https://ui.shadcn.com
 .. _`tales-from-a-dev/twig-tailwind-extra`: https://github.com/tales-from-a-dev/twig-tailwind-extra
-.. _`ignore not defined options`: https://symfony.com/doc/current/components/options_resolver.html#ignore-not-defined-options
+.. _`ignore not defined options`: https://symfony.com/doc/current/components/options_resolver.html#ignore-not-defined-options

src/CVA.php

@@ -24,6 +24,8 @@
  * @author Mathéo Daninos <[email protected]>
  *
  * @experimental
+ *
+ * @deprecated since TwigComponent 2.20, use CVA from the "twig/html-extra:^3.12.0" package instead.
  */
 final class CVA
 {

src/Twig/ComponentExtension.php

@@ -16,6 +16,7 @@
 use Symfony\UX\TwigComponent\ComponentRenderer;
 use Symfony\UX\TwigComponent\CVA;
 use Symfony\UX\TwigComponent\Event\PreRenderEvent;
+use Twig\DeprecatedCallableInfo;
 use Twig\Error\RuntimeError;
 use Twig\Extension\AbstractExtension;
 use Twig\TwigFunction;
@@ -42,7 +43,11 @@ public function getFunctions(): array
     {
         return [
             new TwigFunction('component', [$this, 'render'], ['is_safe' => ['all']]),
-            new TwigFunction('cva', [$this, 'cva']),
+            new TwigFunction('cva', [$this, 'cva'], [
+                ...(class_exists(DeprecatedCallableInfo::class)
+                    ? ['deprecation_info' => new DeprecatedCallableInfo('symfony/ux-twig-component', '2.20', 'html_cva', 'twig/html-extra')]
+                    : ['deprecated' => '2.20', 'deprecating_package' => 'symfony/ux-twig-component', 'alternative' => 'html_cva']),
+            ]),
         ];
     }
 
@@ -105,6 +110,8 @@ public function finishEmbeddedComponentRender(): void
      */
     public function cva(array $cva): CVA
     {
+        trigger_deprecation('symfony/ux-twig-component', '2.20', 'Twig Function "cva" is deprecated; use "html_cva" from the "twig/html-extra" package (available since version 3.12) instead.');
+
         return new CVA(
             $cva['base'] ?? '',
             $cva['variants'] ?? [],

tests/Fixtures/templates/components/Alert.html.twig

@@ -33,4 +33,4 @@
 <div class="{{ alert.apply({color, size}, attributes.render('class'), 'flex p-4') }}">
     {% block content %}
     {% endblock %}
-</div>
+</div>

tests/Integration/ComponentExtensionTest.php

@@ -11,6 +11,7 @@
 
 namespace Symfony\UX\TwigComponent\Tests\Integration;
 
+use Symfony\Bridge\PhpUnit\ExpectDeprecationTrait;
 use Symfony\Bundle\FrameworkBundle\Test\KernelTestCase;
 use Symfony\UX\TwigComponent\Tests\Fixtures\User;
 use Twig\Environment;
@@ -21,6 +22,8 @@
  */
 final class ComponentExtensionTest extends KernelTestCase
 {
+    use ExpectDeprecationTrait;
+
     public function testCanRenderComponent(): void
     {
         $output = $this->renderComponent('component_a', [
@@ -264,8 +267,13 @@ class="block"
         ];
     }
 
+    /**
+     * @group legacy
+     */
     public function testComponentWithClassMerge(): void
     {
+        $this->expectDeprecation('Since symfony/ux-twig-component 2.20: Twig Function "cva" is deprecated; use "html_cva" from the "twig/html-extra" package (available since version 3.12) instead.');
+
         $output = self::getContainer()->get(Environment::class)->render('class_merge.html.twig');
 
         $this->assertStringContainsString('class="alert alert-red alert-lg font-semibold rounded-md dark:bg-gray-600 flex p-4"', $output);
@@ -373,8 +381,13 @@ public function testComponentWithEmptyProps(): void
         $this->assertStringContainsString('I have an empty props tag', $output);
     }
 
+    /**
+     * @group legacy
+     */
     public function testAnonymousComponentWithPropsOverwriteParentsProps(): void
     {
+        $this->expectDeprecation('Since symfony/ux-twig-component 2.20: Twig Function "cva" is deprecated; use "html_cva" from the "twig/html-extra" package (available since version 3.12) instead.');
+
         $output = self::getContainer()->get(Environment::class)->render('anonymous_component_with_props_overwrite_parents_props.html.twig');
 
         $this->assertStringContainsString('I am an icon', $output);

tests/Unit/CVATest.php

@@ -15,7 +15,11 @@
 use Symfony\UX\TwigComponent\CVA;
 
 /**
+ * To remove in TwigComponent 3.0.
+ *
  * @author Mathéo Daninos <[email protected]>
+ *
+ * @group legacy
  */
 class CVATest extends TestCase
 {