[META] Missing features in SDC needed for XB

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.

One more for @lauriii to review 🤓

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

TIL thanks to #3446722: Introduce an example set of representative SDC components; transition from "component list" to "component tree" 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?

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

schema references

Both projects 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 #3390712: Add component variants to SDC, UI Patterns 2 has 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

variant & attributes are the 2 magical props: they have defined machine name and a defined type, so they don't need to be defined in among the other props.

component tagging/categorization

UI Patterns 2 uses tags and group:

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

"tags" and "group" are used only for documentation and organization purpose. There is no processing or rendering logic applied to them.

"group" is used in UI Patterns 2 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: #3456335: [2.0.0-alpha3] EnumPropType: Labelled enumerations

SDC does not respect default — see #19

UI Patterns 2 uses default when building 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 #3454125: Implement temporary design system for the DrupalCon Barcelona demo will surface additional things.

Added to the issue summary: #3474533: ComponentPluginManager must implement CategorizingPluginManagerInterface.

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 slot where 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.

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.

When looping on slot values to get the "dynamic columns" effect, 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 use a normal Twig variable instead.

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: #3484727: Complete and clarify SDC documentation

#3507641: Allow components containing non-required images and no examples to be placed straddles the line here. If core would do this, then XB wouldn't have to.

FYI: met with @pdureau at DrupalCon Atlanta just now and we went over everything in this issue, to identify things to collaborate on 😄

Results:

1. #3471454-22: [Meta] List of related core issues
2. Closed #3493078: per-slot tag/category-based restrictions in favor of #3514072: SDC slots can set expectations and cardinality . (And updated in issue summary.)

Some of the things in this list, @pdureau strongly disagrees with, like #3493079: repeatable/undefined number of slots, but then again it's not yet well-defined on the XB side yet. So let's start with the things where there's clearly convergence! 🤝

Articulated a detailed plan for the top-priority issue here (see #3493070-11: SDC `enum` props should have translatable labels: use `meta:enum`), plus XB sibling issue (#3493070: SDC `enum` props should have translatable labels: use `meta:enum`)

@lauriii: thoughts on #3516359: ComponentValidator ignores the set validator and creates a new one, which would allow us to switch from our use of $ref to format, because it allows us to define custom formats? 😄

Added #3518105: Support other format for string and integer: color and range.

Not sure it's a strict requirement, but we might want to track #3519917: Disable additionalProperties in slots in SDC json schema

I don't think this being assigned to @lauriii for #34 is highly relevant anymore.

@penyaskito has been leading the effort on the XB team to get as many SDC improvements into core as possible. I see he's got #3519917: Disable additionalProperties in slots in SDC json schema to RTBC too 🤩🥳

@penyaskito Could you take on #46 + #47 on the XB side too? 😇🙏

Created #3532397: Add support for SDC variants and added to the table.