minor #2144 [TwigComponent] Deprecate cva twig function (Kocal)

This PR was merged into the 2.x branch.

Discussion
----------

[TwigComponent] Deprecate `cva` twig function

| Q             | A
| ------------- | ---
| Bug fix?      | no
| New feature?  | no <!-- please update src/**/CHANGELOG.md files -->
| Issues        | Fix #2070 <!-- prefix each issue number with "Fix #", no need to create an issue if none exist, explain below instead -->
| License       | MIT

<!--
Replace this notice by a description of your feature/bugfix.
This will help reviewers and should be a good start for the documentation.

Additionally (see https://symfony.com/releases):
 - Always add tests and ensure they pass.
 - For new features, provide some code snippets to help understand usage.
 - Features and deprecations must be submitted against branch main.
 - Changelog entry should follow https://symfony.com/doc/current/contributing/code/conventions.html#writing-a-changelog-entry
 - Never break backward compatibility (see https://symfony.com/bc).
-->

Use the new `Twig\DeprecatedCallableInfo` added in twigphp/Twig#4291, it help us to specify the package where the alternative can be found, which was not the case before.

Commits
-------

e310074 [TwigComponent] Deprecate `cva` twig function

Author: Kocal

src/Map/src/Twig/MapExtension.php

@@ -12,6 +12,7 @@
 namespace Symfony\UX\Map\Twig;
 
 use Symfony\UX\Map\Renderer\Renderers;
+use Twig\DeprecatedCallableInfo;
 use Twig\Extension\AbstractExtension;
 use Twig\TwigFunction;
 
@@ -27,9 +28,9 @@ public function getFunctions(): array
         return [
             new TwigFunction('render_map', [Renderers::class, 'renderMap'], [
                 'is_safe' => ['html'],
-                'deprecated' => '2.20',
-                'deprecating_package' => 'symfony/ux-map',
-                'alternative' => 'ux_map',
+                ...(class_exists(DeprecatedCallableInfo::class)
+                    ? ['deprecation_info' => new DeprecatedCallableInfo('symfony/ux-map', '2.20', 'ux_map')]
+                    : ['deprecated' => '2.20', 'deprecating_package' => 'symfony/ux-map', 'alternative' => 'ux_map']),
             ]),
             new TwigFunction('ux_map', [Renderers::class, 'renderMap'], ['is_safe' => ['html']]),
         ];

src/TwigComponent/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
 

src/TwigComponent/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/TwigComponent/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/TwigComponent/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'] ?? [],

src/TwigComponent/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>

src/TwigComponent/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);

src/TwigComponent/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
 {