[SPIKE] Comprehensive plan for integrating with SDC

I'm working to gather an overview of all the feature requests and/or mismatches between XB's needs and what SDC offers today. My goal is to make this list complete by the end of the week.

Wim Leers → credited tedbow → .

Marked the "per-slot tag/category-based restrictions" as ✅ since this is needed to implement a design system using the Paragraphs use case.

I believe we can get away without required slots for now because it is possible to compose smaller components into bigger components, which allows defining them as required. This is the purple scenario from 📌 Document supported component modeling approaches Active .

Looks like #11 was already part of the issue summary as "Schema references". Marking it as confirmed.

One more for @lauriii to review 🤓

Another new one, with explicit +1 from @lauriii (and @larowlan!) at #3462074-9: Option to change the icon for components on the page hierarchy display → .

TIL thanks to 📌 Introduce an example set of representative SDC components; transition from "component list" to "component tree" Fixed that default is another thing in addition to examples: https://json-schema.org/draft/2020-12/draft-bhutton-json-schema-validati...

But only a single place in the SDC infrastructure uses it:

    scrollAmount:
      type: number
      title: Scroll Amount
      description: Amount of scrolling at each interval in pixels.
      default: 6
      examples:
        - 6
        - 12

— modules/contrib/sdc_examples/components/my-marquee/my-marquee.component.yml

I think it'd make sense to consider making this required — that'd be better than examples?

Some stuff listed in the issue summary we are already doing in UI Patterns → 2.x and it would be nice to do it the same way in order to stay compatible.

schema references

We use the same mechanism with different stream wrappers:

• ui-patterns:// for UI Patterns 2.x
• json-schema-definitions:// for Experience Builder

In theory, they can coexist in a Drupal instance. Let's check that in a few weeks.

component variants

As described in ✨ Introduce component variants to SDC Active , we have a new root level variant property

name:  Card
variants:
  primary:
    title: Primary
    description: ...
  secondary:
    title: Secondary
    description: ...
  inverted:
    title: Inverted
    description: ...
props: {}
slots: {}

Which is translated as this prop on component loading:

    variant:
      type: string
      enum:
        - primary
        - secondary
        - inverted

component tagging/categorization

We use tags and group:

name: Foo
description: Testing component
group: Testing
tags:
  - tests
status: experimental
slots: {...}
props: {...}

"group" is used in our implementation of CategorizingPluginManagerInterface

enums values do not have (translatable) labels

We use "meta:enum" which is not an official standard but supported by some popular projects:

• https://github.com/adobe/jsonschema2md
• https://github.com/coveooss/json-schema-for-human

props:
  type: object
  properties:
    position:
      type: string
      enum:
        - top
        - bottom
      "meta:enum":
        top: Top
        bottom: Bottom

See: ✨ [2.0.0-alpha3] EnumPropType: Labelled enumerations Fixed

SDC does not respect default — see #19

We use default in when we build the form, as #default_value.

default must not be used in the rendering process (sending default value if prop value is missing or empty) because:

• sometimes we want a default value in forms while allowing the user to set empty or missing value
• the |default() Twig filter is the expected too for such an enforcement

Discussed with @effulgentsia & @lauriii. We consider this spike completed.

About 20 missing features (and bugs) have been identified that we need to land/fix upstream.

#26 by @pdureau is encouraging: UI Patterns 2 ran into many of the same challenges and already has some decisions/proposals for how to deal with those gaps. I see no reason why XB cannot use the exact same solutions.

(Although I defer to @lauriii WRT groups vs tags — IIRC the Acquia UX team was doing user testing around that?)

It's likely that the work on 📌 Implement temporary design system for the DrupalCon Barcelona demo Needs work will surface additional things.

Added to the issue summary: ✨ ComponentPluginManager must implement CategorizingPluginManagerInterface Active .

Sorting the table based on priority.

repeatable/undefined number of slots, e.g. a dynamic columns component where users could place 1–n columns

This must not be a new SDC feature. A dynamic number of "columns" is a single slotswhere we are looping on the slot content.

Example with items slot:

   {% for item in items %}
    <div class="grid__item">
      {{ item }}
    </div>
  {% endfor %}

Also, it can be safer to check if there is a single renderable and wrap it into a sequence before looping:

{% set items = items and items is not sequence ? [items] : items %}

#32: that's not what @lauriii has been stating, so flagging as needing input from him.

Testing out the idea #32 is probably blocked by https://www.drupal.org/project/experience_builder/issues/3491021 ✨ Leverage HTML comment annotations, remove wrapping div elements Active .

I did play around with the latest work in #3491021, but it was too unstable confirm without any doubt that the approach is viable. From the limited experimentation I've performed, I think there's a good chance it'll be workable as #3491021 wraps up though.

Testing out the idea #32 is probably blocked by https://www.drupal.org/project/experience_builder/issues/3491021 ✨ Leverage HTML comment annotations, remove wrapping div elements Active .

When looping on slot values to get the "dynamic columns" result, it is better to not use the Twig block system for the slot. Because, AFAIK, it is not possible to loop on them. You can just use a normal Twig variable.

In general, I would advice against Twig blocks for slots. I know this method is currently highlighted in the SDC documentation, but I have created an issue to change this: 🌱 Clarify SDC documentation by toning down Twig blocks promotion Active