feature #1419 [Live][Stimulus] Prepping the LiveComponent Stable Release 🚀 (weaverryan)

This PR was squashed before being merged into the 2.x branch.

Discussion
----------

[Live][Stimulus] Prepping the LiveComponent Stable Release 🚀

| Q             | A
| ------------- | ---
| Bug fix?      | no
| New feature?  | yes
| Issues        | None
| License       | MIT

Hi!

LiveComponents has, really, been quite stable for a long time, but it's kept its experimental status. Removing that is really about deciding that we'll protect backwards-compatibility. It's time to do that :).

This is planned as the 2.15.0 release near the end of Feb (assuming we get the items below done before then).

TODOs:

* #1418
* Possibly remove Twig 2.x compat
* #1428
* #1392
* Moving `Idiomorph` to a peer dependency would be great, but blocked by bigskysoftware/idiomorph#35 - **still need a tag** for the PR merge
* #1426 as it may include some edge-case BC breaks.

If there's anything else on your mind before stable, now is the time to mention it :).

Cheers!

Commits
-------

7932a9d [Live][Stimulus] Prepping the LiveComponent Stable Release 🚀

Author: weaverryan

src/LiveComponent/README.md

@@ -1,15 +1,12 @@
 # Live Components
 
-**EXPERIMENTAL** This component is currently experimental and is
-likely to change, or even change drastically.
-
 Live components work with the [TwigComponent](https://symfony.com/bundles/ux-twig-component/current/index.html)
 library to give you the power to automatically update your
 Twig components on the frontend as the user interacts with them.
 Inspired by [Livewire](https://laravel-livewire.com/) and
 [Phoenix LiveView](https://hexdocs.pm/phoenix_live_view/Phoenix.LiveView.html).
 
-Want a demo? Check out https://github.com/weaverryan/live-demo.
+Want a demo? Check out https://ux.symfony.com/live-component.
 
 **This repository is a READ-ONLY sub-tree split**. See
 https://github.com/symfony/ux to create issues or submit pull requests.

src/LiveComponent/assets/dist/live_controller.js

@@ -1374,9 +1374,9 @@ function executeMorphdom(rootFromElement, rootToElement, modifiedFieldElements,
                     if (modifiedFieldElements.includes(fromEl)) {
                         setValueOnElement(toEl, getElementValue(fromEl));
                     }
-                    if (fromEl === document.activeElement
-                        && fromEl !== document.body
-                        && null !== getModelDirectiveFromElement(fromEl, false)) {
+                    if (fromEl === document.activeElement &&
+                        fromEl !== document.body &&
+                        null !== getModelDirectiveFromElement(fromEl, false)) {
                         setValueOnElement(toEl, getElementValue(fromEl));
                     }
                     const elementChanges = externalMutationTracker.getChangedElement(fromEl);

src/LiveComponent/assets/src/morphdom.ts

@@ -110,9 +110,10 @@ export function executeMorphdom(
                     // We skip this for non-model elements and allow this to either
                     // maintain the value if changed (see code above) or for the
                     // morphing process to update it to the value from the server.
-                    if (fromEl === document.activeElement
-                        && fromEl !== document.body
-                        && null !== getModelDirectiveFromElement(fromEl, false)
+                    if (
+                        fromEl === document.activeElement &&
+                        fromEl !== document.body &&
+                        null !== getModelDirectiveFromElement(fromEl, false)
                     ) {
                         setValueOnElement(toEl, getElementValue(fromEl));
                     }

src/LiveComponent/doc/index.rst

@@ -1,11 +1,6 @@
 Live Components
 ===============
 
-.. caution::
-
-    This component is currently experimental and is likely to change, or even
-    change drastically.
-
 Live components builds on top of the `TwigComponent`_ library
 to give you the power to automatically update your Twig components on
 the frontend as the user interacts with them. Inspired by
@@ -3528,8 +3523,10 @@ This bundle aims at following the same Backward Compatibility promise as
 the Symfony framework:
 https://symfony.com/doc/current/contributing/code/bc.html
 
-However it is currently considered `experimental`_, meaning it is not
-bound to Symfony's BC policy for the moment.
+For JavaScript files, the public API (i.e. documented features and exports
+from the main JavaScript file) is protected by the backward compatibility
+promise. However, any internal implementation in the JavaScript files
+(i.e. exports from internal files) is not protected.
 
 .. _`TwigComponent`: https://symfony.com/bundles/ux-twig-component/current/index.html
 .. _TwigComponent documentation: https://symfony.com/bundles/ux-twig-component/current/index.html
@@ -3538,7 +3535,6 @@ bound to Symfony's BC policy for the moment.
 .. _`Twig Component`: https://symfony.com/bundles/ux-twig-component/current/index.html
 .. _`Twig Component mount documentation`: https://symfony.com/bundles/ux-twig-component/current/index.html#the-mount-method
 .. _`Symfony form`: https://symfony.com/doc/current/forms.html
-.. _`experimental`: https://symfony.com/doc/current/contributing/code/experimental.html
 .. _`dependent form fields`: https://ux.symfony.com/live-component/demos/dependent-form-fields
 .. _StimulusBundle configured in your app: https://symfony.com/bundles/StimulusBundle/current/index.html
 .. _`attributes variable`: https://symfony.com/bundles/ux-twig-component/current/index.html#component-attributes

src/LiveComponent/src/Attribute/AsLiveComponent.php

@@ -20,8 +20,6 @@
  * @see https://symfony.com/bundles/ux-live-component
  *
  * @author Kevin Bond <[email protected]>
- *
- * @experimental
  */
 #[\Attribute(\Attribute::TARGET_CLASS)]
 final class AsLiveComponent extends AsTwigComponent

src/LiveComponent/src/Attribute/LiveAction.php

@@ -15,8 +15,6 @@
  * An attribute to register a LiveAction method.
  *
  * @see https://symfony.com/bundles/ux-live-component/current/index.html#actions
- *
- * @experimental
  */
 #[\Attribute(\Attribute::TARGET_METHOD)]
 class LiveAction

src/LiveComponent/src/Attribute/LiveArg.php

@@ -17,8 +17,6 @@
  * @see https://symfony.com/bundles/ux-live-component/current/index.html#actions-arguments
  *
  * @author Tomas Norkūnas <[email protected]>
- *
- * @experimental
  */
 #[\Attribute(\Attribute::TARGET_PARAMETER)]
 final class LiveArg

src/LiveComponent/src/Attribute/LiveListener.php

@@ -18,8 +18,6 @@
  * method and re-render the component.
  *
  * @see https://symfony.com/bundles/ux-live-component/current/index.html#listeners
- *
- * @experimental
  */
 #[\Attribute(\Attribute::TARGET_METHOD | \Attribute::IS_REPEATABLE)]
 class LiveListener extends LiveAction

src/LiveComponent/src/Attribute/LiveProp.php

@@ -15,8 +15,6 @@
  * An attribute to mark a property as a "LiveProp".
  *
  * @see https://symfony.com/bundles/ux-live-component/current/index.html#liveprops-stateful-component-properties
- *
- * @experimental
  */
 #[\Attribute(\Attribute::TARGET_PROPERTY)]
 final class LiveProp

src/LiveComponent/src/Attribute/PostHydrate.php

@@ -13,8 +13,6 @@
 
 /**
  * An attribute to register a PostHydrate hook.
- *
- * @experimental
  */
 #[\Attribute(\Attribute::TARGET_METHOD)]
 final class PostHydrate

src/LiveComponent/src/Attribute/PreDehydrate.php

@@ -13,8 +13,6 @@
 
 /**
  * An attribute to register a PreDehydrate hook.
- *
- * @experimental
  */
 #[\Attribute(\Attribute::TARGET_METHOD)]
 final class PreDehydrate

src/LiveComponent/src/Attribute/PreReRender.php

@@ -16,8 +16,6 @@
  *
  * This hook ONLY happens when rendering via HTTP: it does
  * not happen during the initial render of a component.
- *
- * @experimental
  */
 #[\Attribute(\Attribute::TARGET_METHOD)]
 final class PreReRender

src/LiveComponent/src/ComponentToolsTrait.php

@@ -17,8 +17,6 @@
  * Trait with shortcut methods useful for live components.
  *
  * @author Ryan Weaver <[email protected]>
- *
- * @experimental
  */
 trait ComponentToolsTrait
 {

src/LiveComponent/src/ComponentValidator.php

@@ -19,8 +19,6 @@
 /**
  * @author Ryan Weaver <[email protected]>
  *
- * @experimental
- *
  * @internal
  */
 class ComponentValidator implements ComponentValidatorInterface, ServiceSubscriberInterface

src/LiveComponent/src/ComponentValidatorInterface.php

@@ -15,8 +15,6 @@
 
 /**
  * @author Ryan Weaver <[email protected]>
- *
- * @experimental
  */
 interface ComponentValidatorInterface
 {

src/LiveComponent/src/ComponentWithFormTrait.php

@@ -23,8 +23,6 @@
 
 /**
  * @author Ryan Weaver <[email protected]>
- *
- * @experimental
  */
 trait ComponentWithFormTrait
 {

src/LiveComponent/src/DefaultActionTrait.php

@@ -13,8 +13,6 @@
 
 /**
  * @author Kevin Bond <[email protected]>
- *
- * @experimental
  */
 trait DefaultActionTrait
 {

src/LiveComponent/src/DependencyInjection/Compiler/ComponentDefaultActionPass.php

@@ -17,8 +17,6 @@
 /**
  * @author Kevin Bond <[email protected]>
  *
- * @experimental
- *
  * @internal
  */
 final class ComponentDefaultActionPass implements CompilerPassInterface

src/LiveComponent/src/DependencyInjection/Compiler/OptionalDependencyPass.php

@@ -21,8 +21,6 @@
 /**
  * @author Kevin Bond <[email protected]>
  *
- * @experimental
- *
  * @internal
  */
 final class OptionalDependencyPass implements CompilerPassInterface

src/LiveComponent/src/DependencyInjection/LiveComponentExtension.php

@@ -55,8 +55,6 @@
 /**
  * @author Kevin Bond <[email protected]>
  *
- * @experimental
- *
  * @internal
  */
 final class LiveComponentExtension extends Extension implements PrependExtensionInterface

src/LiveComponent/src/EventListener/AddLiveAttributesSubscriber.php

@@ -29,8 +29,6 @@
  *
  * @author Kevin Bond <[email protected]>
  *
- * @experimental
- *
  * @internal
  */
 final class AddLiveAttributesSubscriber implements EventSubscriberInterface, ServiceSubscriberInterface

src/LiveComponent/src/EventListener/DeferLiveComponentSubscriber.php

@@ -17,6 +17,11 @@
 use Symfony\UX\TwigComponent\Event\PostMountEvent;
 use Symfony\UX\TwigComponent\Event\PreRenderEvent;
 
+/**
+ * Handles the "defer" key, which causes the component to be rendered asynchronously.
+ *
+ * @internal
+ */
 final class DeferLiveComponentSubscriber implements EventSubscriberInterface
 {
     private const DEFAULT_LOADING_TAG = 'div';

src/LiveComponent/src/EventListener/InterceptChildComponentRenderSubscriber.php

@@ -25,8 +25,6 @@
  *
  * @author Ryan Weaver <[email protected]>
  *
- * @experimental
- *
  * @internal
  */
 class InterceptChildComponentRenderSubscriber implements EventSubscriberInterface, ServiceSubscriberInterface

src/LiveComponent/src/EventListener/LiveComponentSubscriber.php

@@ -42,8 +42,6 @@
  * @author Kevin Bond <[email protected]>
  * @author Ryan Weaver <[email protected]>
  *
- * @experimental
- *
  * @internal
  */
 class LiveComponentSubscriber implements EventSubscriberInterface, ServiceSubscriberInterface

src/LiveComponent/src/EventListener/QueryStringInitializeSubscriber.php

@@ -20,8 +20,6 @@
 /**
  * @author Nicolas Rigaud <[email protected]>
  *
- * @experimental
- *
  * @internal
  */
 class QueryStringInitializeSubscriber implements EventSubscriberInterface

src/LiveComponent/src/EventListener/ResetDeterministicIdSubscriber.php

@@ -36,8 +36,6 @@
  *
  * @author Ryan Weaver <[email protected]>
  *
- * @experimental
- *
  * @internal
  */
 final class ResetDeterministicIdSubscriber implements EventSubscriberInterface

src/LiveComponent/src/Exception/HydrationException.php

@@ -20,8 +20,6 @@
  *
  * @author Ryan Weaver <[email protected]>
  *
- * @experimental
- *
  * @internal
  */
 class HydrationException extends BadRequestHttpException

src/LiveComponent/src/Form/Type/LiveCollectionType.php

@@ -21,8 +21,6 @@
 
 /**
  * @author Gábor Egyed <[email protected]>
- *
- * @experimental
  */
 final class LiveCollectionType extends AbstractType
 {

src/LiveComponent/src/Hydration/DoctrineEntityHydrationExtension.php

@@ -15,6 +15,11 @@
 use Doctrine\Persistence\ManagerRegistry;
 use Doctrine\Persistence\ObjectManager;
 
+/**
+ * Handles hydration of Doctrine entities.
+ *
+ * @internal
+ */
 class DoctrineEntityHydrationExtension implements HydrationExtensionInterface
 {
     /**

src/LiveComponent/src/Hydration/HydrationExtensionInterface.php

@@ -11,6 +11,9 @@
 
 namespace Symfony\UX\LiveComponent\Hydration;
 
+/**
+ * Interface for custom hydration of objects.
+ */
 interface HydrationExtensionInterface
 {
     /**

src/LiveComponent/src/LiveCollectionTrait.php

@@ -17,8 +17,6 @@
 
 /**
  * @author Gábor Egyed <[email protected]>
- *
- * @experimental
  */
 trait LiveCollectionTrait
 {

src/LiveComponent/src/LiveComponentBundle.php

@@ -19,8 +19,6 @@
 
 /**
  * @author Kevin Bond <[email protected]>
- *
- * @experimental
  */
 final class LiveComponentBundle extends Bundle
 {

src/LiveComponent/src/LiveComponentHydrator.php

@@ -35,8 +35,6 @@
 /**
  * @author Kevin Bond <[email protected]>
  *
- * @experimental
- *
  * @internal
  */
 final class LiveComponentHydrator

src/LiveComponent/src/LiveResponder.php

@@ -12,8 +12,6 @@
 namespace Symfony\UX\LiveComponent;
 
 /**
- * @experimental
- *
  * @author Ryan Weaver <[email protected]>
  */
 final class LiveResponder

src/LiveComponent/src/Metadata/LiveComponentMetadata.php

@@ -16,8 +16,6 @@
 /**
  * @author Ryan Weaver <[email protected]>
  *
- * @experimental
- *
  * @internal
  */
 class LiveComponentMetadata

src/LiveComponent/src/Metadata/LiveComponentMetadataFactory.php

@@ -20,8 +20,6 @@
 /**
  * @author Ryan Weaver <[email protected]>
  *
- * @experimental
- *
  * @internal
  */
 class LiveComponentMetadataFactory implements ResetInterface

src/LiveComponent/src/Metadata/LivePropMetadata.php

@@ -17,8 +17,6 @@
 /**
  * @author Kevin Bond <[email protected]>
  *
- * @experimental
- *
  * @internal
  */
 final class LivePropMetadata

src/LiveComponent/src/Twig/DeterministicTwigIdCalculator.php

@@ -17,8 +17,6 @@
 /**
  * @author Ryan Weaver <[email protected]>
  *
- * @experimental
- *
  * @internal
  */
 class DeterministicTwigIdCalculator

src/LiveComponent/src/Twig/LiveComponentExtension.php

@@ -17,8 +17,6 @@
 /**
  * @author Kevin Bond <[email protected]>
  *
- * @experimental
- *
  * @internal
  */
 final class LiveComponentExtension extends AbstractExtension