[2.0.0-beta5] Allow library wrappers around stories

Can we "adopt" https://www.drupal.org/project/storybook (411 installs) format ?

The deep purpose of this module (stories as Twig templates) is far away from UI Patterns philosophy (stories as Drupal renderable), however:

• they allow the file to be in the component folder ({component_id}.stories.twig) while we plan to use hook_theme templates from templates/ directory
• we will be able to show those stories if the theme is using them instead of UI Patterns one

{# some/path/in/your/code/base/my-card.stories.twig #}
{% stories my_card %}
  {% story default } %}
   The stuff we want to add to the story, like wrappers.
   {{ component(...) }}
  {% endstory %}
{% endstories %}

Let's list SDC themes using this format in drupal.org first

https://www.drupal.org/project/dsfr4drupal (39 installs)

no stories: https://git.drupalcode.org/project/dsfr4drupal/-/tree/1.x/components/acc...

https://www.drupal.org/project/etc (1 installs)

cl_server YAML format: https://git.drupalcode.org/project/etc/-/blob/1.0.x/components/content/l...

https://www.drupal.org/project/governor (6 installs)

no stories: https://git.drupalcode.org/project/governor/-/tree/1.0.x/components/uswd...

https://www.drupal.org/project/kinetic (2 installs)

???

https://www.drupal.org/project/prototype (branch 5.x only) (17 installs)

no stories: https://git.drupalcode.org/project/prototype/-/tree/5.x/components/accor...?

https://github.com/danny-englander/quartz/

cl_server YAML format: https://github.com/danny-englander/quartz/blob/dev/components/Organisms/...

https://www.drupal.org/project/radix (branch 6.x only)

no stories: https://git.drupalcode.org/project/radix/-/tree/6.0.x/components/accordion

umami (in Core)

no stories, I guess

https://www.drupal.org/project/starlight (branch 2.x only) (310 installs)

no stories: https://git.drupalcode.org/project/starlight/-/tree/2.x/components/block...

https://www.drupal.org/project/nttdata_theme

no stories: https://git.drupalcode.org/project/nttdata_theme/-/tree/main/components/...

https://www.drupal.org/project/varbase_components (105 installs)

cl_server JSON format: https://git.drupalcode.org/project/varbase_components/-/tree/2.0.x/compo...

Here are all the preview templates of the public U Suite :

ui_suite_bootstrap

• badge/pattern-badge--preview.html.twig >> ✅ "addClass", so doable in UIP2 stories
• card_body/pattern-card-body--preview.html.twig >> ⚠️ HTML wrapper, because sub-component
• card_overlay/pattern-card-overlay--preview.html.twig >> ✅ "addClass", so doable in UIP2 stories
• card/pattern-card--preview.html.twig >> ✅ "setAttribute" and little safe stuff, so doable in UIP2 stories
• carousel_item/pattern-carousel-item--preview.html.twig >> ⚠️ HTML wrapper, because sub-component
• close_button/pattern-close-button--preview.html.twig >> ⚠️ A weird stuff with "bg-dark", do we still need that?
• modal/pattern-modal--preview.html.twig >> ❌ Add a button, so we may still need a template
• navbar/pattern-navbar--preview.html.twig >> ✅ "addClass", so doable in UIP2 stories. It may be 2 different stories
• nav_item/pattern-nav-item--preview.html.twig >> ⚠️ HTML wrapper, because sub-component
• offcanvas/pattern-offcanvas--preview.html.twig > ❌ Add a button, so we may still need a template
• toast_container/pattern-toast-container--preview.html.twig >> ✅ "addClass", so doable in UIP2 stories
• toast/pattern-toast--preview.html.twig >> ❌ HTML wrapper for 'position-static", so we may still need a template

ui_suite_dsfr

• consent_banner/pattern-consent-banner--preview.html.twig >> ✅ "setAttribute", so doable in UIP2 stories
• display/pattern-display--preview.html.twig >> ❌ Add a button, so we may still need a template
• modal/pattern-modal--preview.html.twig >> ❌ Add a button, so we may still need a template

ui_suite_material

• card/pattern-card--preview.html.twig >> ✅ "setAttribute", so doable in UIP2 stories

ui_suite_uswds

• accordion_item/pattern-accordion-item--preview.html.twig >> ✅ "No preview", so no stories in UIP2
• card/pattern-card--variant-flag--preview.html.twig >> ✅ "addClass", so doable in UIP2 stories
• character_count/pattern-character-count--preview.html.twig >> ✅ Empty
• checkbox/pattern-checkbox--preview.html.twig >> ❌ careful: Some logic
• combo_box/pattern-combo-box--preview.html.twig >> ✅ Empty
• date_picker/pattern-date-picker--preview.html.twig >> ✅ "setAttribute", so doable in UIP2 stories
• header/pattern-header--preview.html.twig >> ✅ "No preview", so no stories in UIP2
• in_page_nav/pattern-in-page-nav--preview.html.twig >> ✅ "No preview", so no stories in UIP2
• input_prefix_suffix/pattern-input-prefix-suffix--preview.html.twig >> ✅ "setAttribute", so doable in UIP2 stories
• nav_footer/pattern-nav-footer--preview.html.twig >> ✅ "No preview", so no stories in UIP2
• nav/pattern-nav--preview.html.twig >> ✅ "No preview", so no stories in UIP2
• process_list_item/pattern-process-list-item--preview.html.twig >> ✅ "No preview", so no stories in UIP2
• radio/pattern-radio--preview.html.twig >> ❌ careful: Some logic
• range_slider/pattern-range-slider--preview.html.twig >> ✅ "setAttribute", so doable in UIP2 stories
• time_picker/pattern-time-picker--preview.html.twig >> ✅ Empty

So, we have:

• 4 "⚠️ HTML wrapper, because sub-component". Once #3351682: [2.2.0] UI Patterns Library: add sub-components is delivered, they will not be needed, because the preview will be done inside the parent component preview.
• 2 "❌ careful: Some logic" but Steven told us "Since I can pass any number of stories no I don’t think I need it "
• 1 "❌ HTML wrapper for 'position-static"
• 4 "❌ Add a button"

So, for only 5 use cases in our most complete themes, do we still really need those story templates?

Proposal to cover both "HTML wrapper" and "Add a button" without the need of such a template, let's introduce a library_wrapper property, with a Twig template as a value.

This property will be ignored by ComponentElementAlter but used by the library pages controller (or formatter, after #3438360: Use Drupal entities & plugins for the Library pages).

It will be resolved as an inline_template render element, with those values in #context:

• all variables already injected in the component
• a special story variable with the renderable of the story

So, if a story miss library_wrapper (which will be the case for 90% of the stories), it will be processed as: library_wrapper: '{{ story }}'

For example, to replace this template: https://git.drupalcode.org/project/ui_suite_bootstrap/-/blob/5.0.x/templ...

stories:
  preview:
    title: Preview
    library_wrapper: '<div class="card">{{ story }}</div>'
    slots:
      title: 'Card title'
      subtitle: 'Card subtitle'
      text: 'Cras justo odio, dapibus ac facilisis in, egestas eget quam. Donec id elit non mi porta gravida at eget metus. Nullam id dolor id nibh ultricies vehicula ut id elit.'
    props:
      heading_level: 5

What will happen if there is already a story slot or prop? Maybe _story would be safer.

Let's do #3455354: [2.0.0-beta4] Add a stories specific discovery first

We can start this task

Grimreaper, what do you think about the current state of work? https://git.drupalcode.org/project/ui_patterns/-/merge_requests/261/diffs

It is not finished, I will need to inject the plugin.manager.component_story dependency for example, but it works and it is advanced enough to talk:

• is TwigExtension the best place to put the logic?
• We trigegr the logic only for single component library page ( ui-patterns-stories-full.html.twig) ?
• _story or story for the variable injected in library_wrapper ?
• ...