diff --git a/UPGRADE-3.0.md b/UPGRADE-3.0.md new file mode 100644 index 00000000000..7ae847d5c02 --- /dev/null +++ b/UPGRADE-3.0.md @@ -0,0 +1,125 @@ +# UPGRADE FROM `2.x` TO `3.0` + +Symfony UX follows Symfony's release process, 2.x and 3.0 have the same +features, but Symfony UX 3.0 doesn't include any deprecated features. To +upgrade, make sure to resolve all deprecation notices. Read more about this in +the [Symfony documentation](https://symfony.com/doc/6.4/setup/upgrade_major.html#upgrade-major-symfony-deprecations). + +> [!NOTE] +> Requires PHP `8.2` or higher. +> +> Requires Symfony `6.4` or higher. + +## LazyImage + +* The package has been removed, see the [previous README](https://raw.githubusercontent.com/symfony/ux/refs/heads/2.x/src/LazyImage/README.md) + for migration steps + +## LiveComponent + +* Remove `csrf` argument from `AsLiveComponent` in favor of same-origin/CORS: +```diff +- #[AsLiveComponent(csrf: true)] ++ #[AsLiveComponent] +class MyLiveComponent { + // ... +} +``` + +## Map + +* The Twig function `render_map()` has been removed, use `ux_map()` instead +* The option `title` from `Polygon`, `Polyline`, `Rectangle` and `Circle`, has been removed, use option `infoWindow` instead +* The property `rawOptions` from `ux:map:*:before-create` events has been removed, use `bridgeOptions` instead + +## Swup + +* The package has been removed, see the [previous README](https://raw.githubusercontent.com/symfony/ux/refs/heads/2.x/src/Turbo/README.md) + for migration steps + +## TogglePassword + +* The package has been removed, see the [previous README](https://raw.githubusercontent.com/symfony/ux/refs/heads/2.x/src/TogglePassword/README.md) + for migration steps + +## TwigComponent + +* The configuration `twig_component.defaults` is now mandatory and must contain at least one namespace/directory pair: +```diff +# config/packages/twig_component.yaml +twig_component: + anonymous_template_directory: 'components/' ++ defaults: ++ # Namespace & directory for components ++ App\Twig\Components\: 'components/' +``` + +* Remove method `PreCreateForRenderEvent::getProps()` in favor of `PreCreateForRenderEvent::getInputProps()` +```diff +class HookIntoTwigPreCreateForRenderSubscriber implements EventSubscriberInterface +{ + public function onPreCreateForRender(PreCreateForRenderEvent $event): void + { +- $event->getProps(); ++ $event->getInputProps(); + } + + public static function getSubscribedEvents(): array + { + return [PreCreateForRenderEvent::class => 'onPreCreateForRender']; + } +} +``` + +* Remove `cva` Twig function in favor of [`html_cva` Twig function from `twig/html-extra:^3.12`](https://twig.symfony.com/html_cva) + +**Before:** +```twig +{% set alert = cva({ + base: 'alert', + variants: { + color: { blue: 'bg-blue', red: 'bg-red', green: 'bg-green' }, + size: { sm: 'text-sm', md: 'text-md', lg: 'text-lg' } + }, + defaultVariants: { size: 'md', color: 'blue' }, + compoundVariants: [{ + color: ['red'], + size: ['lg'], + class: 'font-bold' + }], + defaultVariants: { + rounded: 'md' + } +}) %} + +
+ {% block content %}{% endblock %} +
+``` +**After:** +```twig +{% set alert = html_cva( + base: 'alert', + variants: { + color: { blue: 'bg-blue', red: 'bg-red', green: 'bg-green' }, + size: { sm: 'text-sm', md: 'text-md', lg: 'text-lg' } + }, + compound_variants: [{ + color: ['red'], + size: ['lg'], + class: 'font-bold' + }], + default_variants: { + rounded: 'md' + } +) %} + +
+ {% block content %}{% endblock %} +
+``` + +## Typed + +* The package has been removed, see the [previous README](https://raw.githubusercontent.com/symfony/ux/refs/heads/2.x/src/Typed/README.md) + for migration steps diff --git a/src/LiveComponent/CHANGELOG.md b/src/LiveComponent/CHANGELOG.md index d43b1e6f3c7..6fa65f4c79d 100644 --- a/src/LiveComponent/CHANGELOG.md +++ b/src/LiveComponent/CHANGELOG.md @@ -4,6 +4,7 @@ - Minimum required Symfony version is now 6.4 - Minimum required PHP version is now 8.2 +- Remove `csrf` argument from `AsLiveComponent` in favor of same-origin/CORS ## 2.30 diff --git a/src/TwigComponent/CHANGELOG.md b/src/TwigComponent/CHANGELOG.md index 07e754e23f1..59e27295b50 100644 --- a/src/TwigComponent/CHANGELOG.md +++ b/src/TwigComponent/CHANGELOG.md @@ -4,6 +4,13 @@ - Minimum required Symfony version is now 6.4 - Minimum required PHP version is now 8.2 +- The configuration `twig_component.defaults` could not be nullable anymore +- Remove method `PreCreateForRenderEvent::getProps()` in favor of `PreCreateForRenderEvent::getInputProps()` +- Remove `cva` Twig function in favor of [`html_cva` Twig function from `twig/html-extra`](https://twig.symfony.com/html_cva) +- Passing `null` as an attribute value when using `ComponentAttributes` (or `attributes` Twig variable) will now throw an exception, use `remove()` instead +- Remove method `ComponentAttributes::add()`, use `{{ attributes.defaults(stimulus_controller('...')) }}` instead +- The `ComponentTemplateFinder` does not accept `Twig\Environment` as first argument anymore, pass a `LoaderInterface` instead +- The `ComponentTemplateFinder` does not accept a nullable `directory` argument anymore, pass a string instead ## 2.30 diff --git a/src/TwigComponent/doc/index.rst b/src/TwigComponent/doc/index.rst index 363b516ccc3..3676b9d54a1 100644 --- a/src/TwigComponent/doc/index.rst +++ b/src/TwigComponent/doc/index.rst @@ -1216,58 +1216,41 @@ The nesting is recursive so you could potentially do something like this: row:widget:class="ui-form-widget" /> -Component with Complex Variants (CVA) -------------------------------------- - -.. deprecated:: 2.20 +Class Variant Authority +----------------------- - 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)`_ originates from the JavaScript ecosystem. It -enables reusable, customizable components by managing variants (e.g., color, size). -The ``cva()`` Twig function defines ``base`` classes (always applied) and variant-specific -classes: +`CVA (Class Variant Authority)`_ originates from the JavaScript ecosystem. +It enables reusable, customizable components by managing variants (e.g., color, size). +The `html_cva()`_ Twig function from ``twig/html-extra:^3.12`` defines ``base`` classes (always applied) +and variant-specific classes: .. code-block:: html+twig - {# templates/components/Alert.html.twig #} - {% props color = 'blue', size = 'md' %} - - {% set alert = cva({ - base: 'alert', + {% set button = html_cva( + base: 'btn', variants: { - color: { - blue: 'bg-blue', - red: 'bg-red', - green: 'bg-green', - }, - size: { - sm: 'text-sm', - md: 'text-md', - lg: 'text-lg', - } - } - }) %} + color: { primary: 'btn-primary', secondary: 'btn-secondary' }, + size: { sm: 'btn-sm', md: 'btn-md', lg: 'btn-lg' } + }, + default_variant: { color: 'primary', size: 'md' } + ) %} -
- {% block content %}{% endblock %} -
+ -Then use the ``color`` and ``size`` variants to select the classes needed: +When rendering the component, pass the desired variants: .. code-block:: html+twig - - ... - + {# renders as: