BigPipe placeholder content can now be customized

What does this do?

Before this change: BigPipe placeholders were limited to being this : <span data-big-pipe-placeholder-id="(ID THAT BIGPIPE USES TO DETERMINE WHAT EVENTUALLY GOES THERE)"></span>, without the ability to put any additional content inside the span.
After this change: It is now possible to add "previews" inside the placeholder <span> element which can be customized on a per-LazyLoader basis.

How does it work

A new big_pipe_interface_preview theme hook has been added, which adds "preview" content inside of placeholder <span> elements. Default behavior is unchanged: the <span> contents are empty. Placeholder preview content can be added via render arrays or template overrides.

Adding preview content via render array

In the same array where a #lazy_builder is specified, the new '#lazy_builder_preview' property accepts a render array that will become the markup inside the placeholder <span> for that specific lazy builder

   [
     'user' => [
          '#lazy_builder' => ['user.toolbar_link_builder:renderDisplayName', []],
          '#create_placeholder' => TRUE,
          '#lazy_builder_preview' => [
              '#attributes' => ['id' => 'toolbar-link-preview'],
               '#type' => 'container',
               '#markup' => 'Waiting.... ... ... ',
          ],
        ],
     ]

This changes the placeholder output for that Lazy builder from <span data-big-pipe-placeholder-id="some id"></span>
to

   <span data-big-pipe-placeholder-id="some id">
    <div id="toolbar-link-preview">
         Waiting.... ... ... 
    </div>
</span>

Adding preview content via template override

Placeholder previews default to rendering via the big-pipe-interface-preview.html.twig template. Additional template suggestions are generated based on the lazy loader callback and the arguments it receives. For example the renderDisplayName toolbar link builder lazy callback can have its preview customized via a template named big-pipe-interface-preview--user-toolbar-link-builder-renderDisplayName.html.twig

The default preview template only renders the {{preview}} variable. {{preview}} corresponds to the render array added via '#lazy_builder_preview'

Example

See #2951268: Improve rendering account link in the toolbar.

No backwards compatibility concerns

This does not change how BigPipe and it's placeholders function on an existing site. However, there is now the ability to customize the contents of these placeholders when helpful, such as adding progress spinners or reflow-preventing placeholder content that consumes the same space as the element that will replace it.