[Turbo] Add <turbo-mercure-stream-source> custom element

[seb-jean]

Q	A
Bug fix?	no
New feature?	yes
Deprecations?	yes
Documentation?	yes
Issues	Fix #2460
License	MIT

Summary

This PR introduces a native HTML custom element <turbo-mercure-stream-source> to replace the mercure-turbo-stream Stimulus controller for subscribing to Mercure topics and receiving Turbo Stream updates.

What's new

• <turbo-mercure-stream-source> custom element (mercure_stream_source_element.js): manages the EventSource lifecycle (connect, disconnect, reconnect on attribute change) and sets a connected attribute when the SSE connection is established
• StreamSourceUrlGenerator interface: decouples URL generation from rendering, making custom transports easier to implement
• MercureStreamSourceUrlGenerator: Mercure implementation, delegates authorization cookie handling to the Mercure Bundle for private topics
• turbo_stream_from() Twig function and <twig:Turbo:Stream:From> Twig component: the new way to subscribe to Mercure topics in templates

{# Before #}
<div id="books" {{ turbo_stream_listen('App\\Entity\\Book') }}></div>

{# After - Twig component #}
<twig:Turbo:Stream:From topics="App\\Entity\\Book" />
<div id="books"></div>

{# After - Twig function #}
{{ turbo_stream_from('App\\Entity\\Book') }}
<div id="books"></div>

{# Private topic #}
<twig:Turbo:Stream:From topics="App\\Entity\\Book" private />
{{ turbo_stream_from('App\\Entity\\Book', private=true) }}

{# Specific transport #}
<twig:Turbo:Stream:From topics="App\\Entity\\Book" transport="hub2" />
{{ turbo_stream_from('App\\Entity\\Book', transport='hub2') }}

{# Multiple topics #}
<twig:Turbo:Stream:From :topics="['topic_a', 'topic_b']" />
{{ turbo_stream_from(['topic_a', 'topic_b']) }}

Deprecations

• turbo_stream_listen() Twig function → use turbo_stream_from() or <twig:Turbo:Stream:From>
• TurboStreamListenRendererInterface → implement StreamSourceUrlGenerator instead
• TurboStreamListenRenderer → use MercureStreamSourceUrlGenerator
• TopicSet
• mercure-turbo-stream Stimulus controller → replaced by the <turbo-mercure-stream-source> custom element, auto-imported via turbo-core

Thanks to @smnandre for opening issue #2460, which inspired this PR. 🙏

[github-actions]

📊 Packages dist files size difference

Thanks for the PR! Here is the difference in size of the packages dist files between the base branch and the PR.
Please review the changes and make sure they are expected.

File	Before (Size / Gzip)	After (Size / Gzip)
Turbo
mercure_stream_source_element.d.ts	Added	11 B / 66 B
mercure_stream_source_element.js	Added	963 B / 427 B
turbo_stream_controller.js	1.11 kB / 545 B	1.47 kB+32% 📈 / 721 B+32% 📈

[Kocal]

Few (and maybe stupid) comments, I don't have such experience with UX Turbo, I trust you here 🤞🏻

[Kocal]

AFAIK there is no need to add both @deprecated and trigger_deprecation(), you must only use @deprecated

[seb-jean]

The Symfony conventions require both @deprecated and trigger_deprecation(): https://symfony.com/doc/current/contributing/code/conventions.html#deprecating-code

[Kocal]

I don't see where it requires to have both @deprecated and trigger_deprecation() on the same method, it only show an example about deprecating a whole class 🤔

But it looks like you're right, I found one example on current Symfony version: https://github.com/symfony/symfony/blob/8e8f87c6fa5f47a431fc2f49bdbe601f6769e19d/src/Symfony/Component/Serializer/Exception/PartialDenormalizationException.php#L47-L52

Maybe our documentation could be improved

[seb-jean]

For me, the documentation refers to both classes and methods. But as you pointed out, the documentation isn't very clear.
I think that with the example you cited, we can be sure we can include both.

[seb-jean]

I'm getting an error related to the .doctor-rst.yaml file.

src/Turbo/doc/index.rst ✘

722: You are not allowed to use version "3.1". Only major version "2" is allowed.

-> .. deprecated:: 3.1

Should I modify src/Turbo/doc/index.rst to remove .. deprecated:: 3.1, or should I modify the .doctor-rst.yaml file?

[Kocal]

Following @MrYamous's work in #3493, I think we must update the following rules:

    deprecated_directive_major_version:
        major_version: 3
    deprecated_directive_min_version:
        min_version: '3.0'

[Kocal]

I just merged #3515, you can rebase this one 🙏🏻

[seb-jean]

I just rebased