[2.0.0-beta2] Allow library wrappers around stories

Can we "merge" with https://www.drupal.org/project/storybook → ?

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 theme using this format in drupal.org first

Let's also have a look on https://www.drupal.org/project/sdc_styleguide →

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)

the legacy SDC 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/

the legacy SDC 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/...

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, so we may still need a template
• 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, so we may still need a template
• 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, so we may still need a template
• 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, 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 >> ⚠️ Some logic, so we may still need a template
• 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 >> ⚠️ Some logic, so we may still need a template
• range_slider/pattern-range-slider--preview.html.twig >> ✅ "setAttribute", so doable in UIP2 stories
• time_picker/pattern-time-picker--preview.html.twig >> ✅ Empty

So, 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 📌 [2.0.0-alpha3] Use Drupal entities & plugins for the Library pages Active ).

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.

By the way, once ✨ [2.1.x] UI Patterns Library: add sub-components Postponed is done, most of the "HTML wrapper" will not be needed, because the preview will be done inside the parent component preview.

Participating in the discussion in off with @pdureau ;)