Allow SDCs to specify what components are allowed in its respective slots

Thanks a lot Mike for this issue which will make a lot of people happy.

Instead of " are allowed" i would say "are suggested" because it would be a mistake for display building tools to strictly enforce this:

• sometimes business needs are surprising from a design system point of view and business always win. So, if a card component suggests
• sometimes a display builder doesn't know which component is a renderable. For example, placing a view inside a component slot. The view is build with another component, but the component is not know yet.

So, it is up to the display building too to decide how strict it will be considering this suggestion, but from a SDC point of view it is only a suggestion.

So, an early proposal with an example similar to yours, Bootstrap's accordion:

name: Accordion
description: "Render content in a box that expands and collapses vertically."
group: Accordion
slots:
  content:
    title: Content
    description: "Accordion items."
    suggested: [accordion_item]

Example with DaisyUI's Card:

name: Card
description: "Cards are used to group and display content in a way that is easily readable."
group: "Data display"
slots:
  image:
    title: Image
  title:
    title: Title
  text:
    title: Text
  actions:
    title: Actions
   suggested: [badge, buttons]

What do you think?

What do you think?

It really depends on how XB and equivalents implement the UI.

I want XB to 100% limit accordion_group to only accept accordion_item SDCs. The key suggested seems somewhat weak for this action.

It also might be worth exploring whether we can limit an SDC to only appear in a specific slot of a specific SDC. A use case of this is that I don't want my end user to be able to place an accordion_item in the main content area. It only works when placed inside of accordion_group

It really depends on how XB and equivalents implement the UI.

Just a side-note: Let's not implement this fetaure only to please some specific display builders. Let's do it the better way in a SDC point of view, and the display building tools will be able to add features upon it.

The key suggested seems somewhat weak for this action.

Maybe we need different keys:

• suggested: for the DaisyUI card example.
• enforced: for the Carousel example

So, let's see how a display building tool can handle those:

It also might be worth exploring whether we can limit an SDC to only appear in a specific slot of a specific SDC. A use case of this is that I don't want my end user to be able to place an accordion_item in the main content area. It only works when placed inside of accordion_group

Interesting path to explore indeed:

• Is it always the reverse of enforced? So no need to add a new keyword?
• If we need a new keyword, will it be also in the parent's slot definition ? Or in the child definition?

Let's be careful with any restriction we would add. For example, if the design system is expanded by a distinct team with new components, and one of the also want to use accordion_item in of those slots, we need to allow that.

I agree with pdureau that at the SDC level there shouldn't be any restriction on what can go in a slot. The HTML spec does not have any restrictions apart from the content of the slot being valid HTML. If we're starting to Drupalify the term "slot" by adding some implicit features, we might have a bad time later on.

The restrictions should be declared/implemented at a higher level. I like the idea of "suggested", because there is no code beside a new optional key in the yaml to support that. It's up to display builders to treat that as they want. XB could even take "suggested" key from yaml and make that "required" in the UI and adding the validation code there, nothing holding that up.

If we're starting to Drupalify the term "slot" by adding some implicit features

I don't think that specifying rules for which components can go into which slots is about Drupalifying, I think it's about encoding the rules of a design system. If you're building a design system for broad consumption, like Bootstrap, DaisyUI, etc., then you probably don't want to be overly prescriptive, and instead leave as much creative freedom to put almost any component into almost any slot as possible to the users of the design system. However, what if you're building a design system for a single customer, such as a university (or any other type of organization with different units within it), and that university wants every department's website to have some creative freedom, but also stay on brand. So even though functionally you could put any component into any slot, because after all, it's all just HTML, the creator of this type of design system wants to impose some rules. Where should those rules be encoded? It could be in Drupal config entities, but I don't think these are Drupal-related rules, they are an aspect of the design system. Should they be in the SDC's YAML files? Or at some other level, but if some other level, what is that level?

Yes that was not clear on my part, let me try to be clearer :)

SDC is not the right level because we would still want the design system rules to be applied when the component is overridden (I assume). And overriding a component just to change the rules for a slot in a yaml file is going to be a nightmare, now you own the whole component just to change a couple of YAML lines, how do you make sure it's updated? now the design system allows something else in that slot, how does it work with your overridden component? do you have one component by website if the rules are different? All these problems can go away if we work at a higher level, the declaration and enforcement of the restrictions should be at a higher level.

Declaring the restrictions at the theme level could work. IF at the theme level there is nothing that require changing a file on the filesystem to change the rules. We could have a file that declare the "default" restrictions but it's imported once or in an update hook and the file is not used at runtime. We want themes to be reusable so the rules should be easy to change by site builders without the need to deploy anything (designers will be happy about that too).

The way I see it at the moment is that restrictions should be tied to the website itself (maybe having a companion module for design system themes would be a good idea?) with the basic restrictions for reuse. If it's in a config entity we could even implement some of the rules though ECA, or let people alter them "easily" with ECA when necessary. Also we need to keep in mind all of this should be theme dependent, if you switch theme the restrictions should not apply anymore.

Not sure where the actual enforcement of the rules should happen (or if it should happen at all). I'm of the opinion that we need to let people do whatever if they access this from the code/render arrays directly, so enforcing would be only at the UI level in the various display builders interfaces. I don't think we should have code that check if this component is allowed in that slot at render time. That would mean only showing/hiding things in the display builder interface where/when necessary.

I'm just seeing a lot of complexity for a feature that will get in the way of the ambitious site builder (which is our focus, or marketers in the case of Drupal CMS) or, as Pierre said in #2, developers that need to implement a business requirement that doesn't follow design system rules but that was greenlit despite the Design team's opinion.

I'm of the opinion that we need to let people do whatever if they access this from the code/render arrays directly, so enforcing would be only at the UI level in the various display builders interfaces.

I agree with this.

I'm just seeing a lot of complexity for a feature that will get in the way of the ambitious site builder (which is our focus, or marketers in the case of Drupal CMS)

This functionality would radically simplify the page building experience for site builders / content editors / marketers by removing a significant amount of cognitive load, and removing the need for custom documentation.

I'm personally indifferent if the suggestions/restrictions are created at the SDC or in config, just as long as it's possible for the theme to ship the suggestions/restrictions.

Sounds good, the complexity I'm worried about is if we try to enforce this at render time. Having a way to filter the elements in the UI is good I agree.

wim leers → credited griffynh → .

Closed ✨ per-slot tag/category-based restrictions Active in favor of this one 😊 Crediting @gryffinh

I would second the notion of not enforcing this at the SDC layer due to inherent limitations. I can think up a couple of scenarios where having access to the entire working render tree may be beneficial to effectively enforcing design expectations.

• As a designer, when I design a component that should only be displayed within full-width contexts, a content editor shouldn't be able to add it in a way such that it would display otherwise.
• As an accessibility auditor, a component known to have dark text shouldn't be able to be placed if the closest parent component that ships with a background color is known to have a dark background

Layout builder restrictions offers an API that does offer quite a bit of additional context in ways that make non-trivial business logic able to be enforced. The "in the weeds" bits here are quite niche in nature, and will likely vary from design system to design system. Is providing an API for restriction management / XB tree validation on the table?

Following #03 ✨ Allow SDCs to specify what components are allowed in its respective slots Active @mherchel I have a counter-example for accordion.

In DaisyUI accordion component expects collapse components. But the collapse component could be use individually :)

BTW +1 in favor of an enforced: AND/OR suggested: mechanism as it is often requested by end-users.

Based on the issue summary and #2, this is really about the tight coupling between 2 or more specific components. IOW: it's about compatibility, not semantics/purpose?

@nod_ in #7:

The HTML spec does not have any restrictions apart from the content of the slot being valid HTML.

But a <ul> can only contain a <li>, a <dl> can contain only <dt>s and <dd>s, etc.

This discussion so far makes me think we're reinventing DTDs?! 😅 The HTML DTD defines exactly this: the

@nod_ in #9:

I don't think we should have code that check if this component is allowed in that slot at render time. That would mean only showing/hiding things in the display builder interface where/when necessary.

+1

As alluded to in #16, I think this issue is conflating two fairly different needs.

1. compatibility (this is what the issue title seems to be focused on), which (in the discussion so far) is focused on the relationship between (a limited set of) specific SDCs
2. semantics/purpose (+ design choices + accessibility considerations as @luke.leber raised in #14)

XB Product Lead @lauriii has always indicated that for XB, it should be tag/group/category-based (hence ✨ per-slot tag/category-based restrictions Active 's title), not about specific SDCs. AFAIK he's been mostly thinking about design choices. So … I don't think the proposals so far scale to that? 🫣

Can we learn from DTDs? The HTML DTD kind of has two "tags/categories": inline elements and block elements. What if SDCs would be able to define slot restrictions using those 2, but would be able to define additional ones, relevant for the theme's design system?

Here's a concrete example use-case - https://www.previousnext.com.au/blog/creating-cards-section-layout-builder

A 'cards' component that has a slot for cards and props for title, intro text and read more link.

You want to prevent adding anything other than card-like components into the slot.

Trying to synthesize all the comments here, here's a proposal. I hope the terminology is clear enough to convey the concepts, but we can refine the terminology as needed.

Within the SDC's YML, we introduce two new top-level keys (i.e., information about the component):

• is
• traits

And for each slot, we also introduce two keys:

• slotted
• traits

And we define a set of traits. This can grow over time, but to give some examples:

• width
• luminance

An example of what an accordion_group component might look like:

name: Accordion

props:
  ...

slots:
  items:
    title: ...
    description: ...
    slotted:
      - accordion_item
    traits:
      width: full
      luminance: 80

An example of what an accordion_item component might look like:

name: Accordion Item

is:
  - accordion_item

traits:
  width: full
  luminance: 20

props:
  ...

slots:
  ...

Traits, at the component level, or at the slot level, can also be conditional on the values of enum and boolean props. For example:

name: Heading

is:
  - text

traits:
  luminance:
    -
      condition:
        prop: color
        value: light
      value: 80
    -
      condition:
        prop: color
        value: dark
      value: 20

props:
  color:
    type: string
    enum:
      - light
      - dark

slots:
  ...

Trait values descend. Meaning, if a slot doesn't specify a trait, it inherits the value from its component. If a component doesn't specify a trait, it inherits the value from the slot that it's in.

All of the above is info that's in the SDC's YAML. In addition, we define a Drupal config entity type that can store policies. Themes (or modules, recipes, etc.) can include these policies within their config/install directory, just like any other default config. Exact syntax for these policies TBD, but for example, there could be:

• A policy that says: a component can only be placed in a slot if there's an intersection between the component's is and the slot's slotted.
• Another policy that says: a component can only be placed in a slot if its luminance has a contrast of at least 4.5 with the slot's luminance.

Policies can be enabled/disabled, and they're only applied by builder tools (e.g., Experience Builder), not when rendering.

What do you all think? Is this a reasonable partitioning of concerns?

I'm missing some infos somewhere because I do not know how we went from "restrict what's in a slot", to "let's add simple suggestions for the UI" to a whole new YAML condition API. I think I missed some IRL discussions somewhere. The terminology is confusing me too, at first I was wondering if the comment was on the right issue :p

I like the "policies" config idea.

I do not understand why the slot restrictions/conditions are in the SDC definition. @Wim talked about DTDs, huge fan, it's in a separate file that's specially made for that. Anything beyond "suggested" (and even that is arguably not at the right place) doesn't belong on the SDC layer for me, especially now that we agree this is a UI concern, not a technical (as in render-time validation) concern.

Additionally I'm thinking that adding all this at the slot level in SDC will make it very hard share SDCs across themes/modules. We'd need to have dependencies on other components to make it work. Not having this inter-components dependency mechanism is a feature, not a bug ✨ [PP-1] Allow schema references in Single Directory Component prop schemas Postponed .

I think the proposal in #19 is a rational start, but am slightly concerned that not all business rules can be represented in YML fashion.

I'm still of the mind that power users will require some degree of programmatic interface to check all the boxes that are presently fulfilled by things like LB Restrictions.

Whether these traits exist on the SDC or in a parallel XB-only configuration is the question.

Additionally I'm thinking that adding all this at the slot level in SDC will make it very hard share SDCs across themes/modules.

This is a great point. I do rather struggle to see how SDC's would be able to be mixed and matched across different themes in ways that wouldn't end up "looking weird" from a branding perspective though. My mind immediately went to an example like "I'd like a header from Princeton's design system, a footer from Harvard's, and accordions from Yale's -- which would result in a very odd looking thing from a branding perspective.

Are there any concrete use cases for wanting to mix and match SDC's across different themes? Typically I'd think that there wouldn't be the desire for design systems to be arbitrarily mixed and matched in that fashion.

WordPress core defines about 90+ components that are reused and customized though classes and some custom API. They have more than a 100 fully "block themes" that are build on those (few themes define their own components, they mostly reuse the core ones to build pages) and since they consider their "hybrid themes" as block theme they're announcing more than a thousand block themes available, all built on those core components. It works for them and we don't have a radically different needs (XB has a lot in commun with gutenberg: problem space, technologies) so it'd work for us.

Closer to home, we have the navigation module that provides a "badge" SDC, no reason it couldn't be a global SDC that core and contrib can use. The goal is for core to move to SDC as a step to simplify the render API, see #2702061-106: Unify & simplify render & theme system: component-based rendering (enables pattern library, style guides, interface previews, client-side re-rendering) → .

It's not about a header from this and a footer from that, it's lower level. Like a card component, buttons it's always mostly the same. So yes, reusable SDC is definitely something that is necessary.

Changing title and component because it's about the UI, not about the capabilities of SDC themselves

I think I missed some IRL discussions somewhere.

Maybe, but not in relation to comment #19. My proposal in that comment came directly from reading this issue's comments.

The issue summary gives the example of an accordion_group component containing a slot into which only accordion_item components make sense to be slotted. The IS also points out that the concept of an accordion_item isn't unique to just one SDC: you can have multiple SDCs (e.g., one from a module, one from a theme) that are all accordion items. #18 provides a similar use case of 'cards', but is even more explicit about the concept that multiple SDCs can be "card-like". I think #19's suggestion of is and slotted addresses those use cases: a components can identify what it is, and a slot can identify what kind of slotted content it's designed for.

That addresses the direct slot/slotted relationship, but comment #14 mentions additional use cases of context that should affect more distant descendants. #19 proposes traits as the way to represent that.

#9 argues for the restriction rules to live in a different level than the SDCs, so #19 incorporates that via the separation between SDCs just declaring information about themselves, while the policies that act on that information being defined in Drupal config.

Additionally I'm thinking that adding all this at the slot level in SDC will make it very hard share SDCs across themes/modules.

The is, slotted, and traits keys I'm proposing in #19 would all be optional. SDCs that are designed to be super generic and flexible don't need to populate those keys. But what other than the SDC itself should be declaring that it's an accordion item, or card-like, or that it's full-width, or has a certain luminance, for the cases where the SDC author knows that information and wants to make that information available, so that policies can be created around that information?

doesn't belong on the SDC layer for me, especially now that we agree this is a UI concern, not a technical (as in render-time validation) concern

The SDC YAML already provides information about itself that isn't a render-time concern. For example, examples and description. A big selling point of SDCs is that everything about the SDC is colocated: the YAML, the Twig, the JS, the CSS. What's proposed in #19 is additional optional metadata about the SDC: why break the colocation advantage of SDCs by forcing that additional metadata to be somewhere else?

Overall I think #19 is headed in the right direction but also don't find the terms used obvious. When reading through the comment is lacked any hints or context to the purpose/intent of the value and slotted to me implied components that had been placed in the slot. Can't think of any good alternatives to is but for slotted something like wants,accepts,intendedFor,canContain are more clear to me.

+1 to

• putting the info in the SDC definition
• making enforcement the responsibility of SDC consumers
• not enforcing this at the render level, though a warning when twig debug is enabled could be interesting
• is being multi value

Policies are a really interesting abstraction to handle enforcing restrictions and I think with an extensible implementation would address #21's concern about needing to apply advanced logic. Traits with conditions I'm not so sure about. Even in the short example the inclusion of conditions adds a lot of complexity to the definition. A simpler structure that's just a place to put arbitrary information for policies to interpret would be more approachable. One downside to such a flexible system is we are bordering on violating the concept that everything you need to know about a component is in the directory which has been part of the reasoning behind not allowing preprocessing in ✨ Have a way to implement the a preprocess function per each SDC component (ideally in the same folder) Active

Could policies also be used to add slot limits similar to https://www.drupal.org/project/layout_builder_limit → ?

We're talking about adding something optional for which the only existing/current need is accordion/accordion_item. From there we assume things will get more complicated and try to come up with a solution, that doesn't sound like a plan that will address our users needs. In that situation where the needs are not clearly defined, contrib will implement it, battle test/refine the requirements and we get it in core once we know more about how it's used.

On the technical side of things It's totally possible for XB to add an extra yml file to SDCs that it will use (and maybe other modules can end up using the file too), core is not blocking anything except for this annoying restriction with finding SDC yaml files: 📌 Make DirectoryWithMetadataDiscovery generic and reusable Active . As wim said in that very same issue: "In Drupal core, we generally only introduce an abstraction once there's >=3 uses for it." From what we talked about here, we're not there yet.

To me this issue should be postponed on XB implementing this, finding what works and what doesn't and we get the parts that are actually needed and helpful then.

The complexity of #19 proposal (6 new keywords! a full rule system! 1 config entity!) show how risky the subject and how careful we need to be.

Let's go back to the start of this issue, when we were still proposing straightforward solutions. Maybe using component IDs in our new keyword is too limiting:

name: Accordion
description: "Render content in a box that expands and collapses vertically."
group: Accordion
slots:
  content:
    title: Content
    description: "Accordion items."
    suggested: ["my_theme:accordion_item"]

The suggestion of "tags/categories" system, or a DTD like system, as proposed by Wim in #16 & #17 is interesting.

Just brainstorming with you here...

Considering:

• A component has a single HTML element as a root in the template. Yes, always, never seen a counter example in 8 years of component-based development. But this HTML element can be dynamically printed.
• A slot has always a parent/wrapper element in the template. Yes, always, at least it is the component root.
• In HTML5 specification, each element have a "Content model" which describe which children they accept, with 2 kinds of values:
  • explicit HTML elements tag names. Example: UL element expects LI elements https://html.spec.whatwg.org/multipage/grouping-content.html#the-ul-element
  • keywords from the content categories list (metadata, flow, sectioning, heading, phrasing, embeddedand interactive). Example: P element expects phrasing content. https://html.spec.whatwg.org/multipage/grouping-content.html#the-p-element

Let's leverage this information, and only this information, coming from an industry standard source, without the temptation of adding drupalisms.

Proposal

By adding only 3 simple things:

1. A single keyword: model (or something else, let's discuss) which can be optionally used both in a component definition and a slot definition:

• At the component definition level, we put the HTML element(s) of the component root in the template
• At the slot definition level, we put the HTML element(s) of the slot wrapper in the template

Front devs own both the definition and the templates, and they all know what an HTML is. It will be easy for them.

2. A simple service with a registry of the content model all HTML elements (no need to put much data inside thanks to the HTML content model information) and:

• a method to check if a HTML element can be the parent of the others ::checkElementModel(string $parent_element_tag, string $child_element_tag): bool;
• a method to check if a component can be the included in the slot of an others ::checkComponentModel(string $parent_component_id, string $parent_component_slot, string $child_component_id): bool;

A display building tool will be able to use this service for altering its UI and mechanisms.

With this simple system:

• we will propose the user to put LI outside UL, or TR outside TABLE, or P inside another P
• this is not covering specifically the initial Accordion Items example from Mike, but it will filter the component available in an Accordion slots to a manageable list, with a low risk of doing something wrong

Example

I took the most radical example i can find in the wild 😉

https://git.drupalcode.org/project/ui_suite_bootstrap/-/tree/5.1.x/compo...

name: Table
model: [table]
slots:
  rows:
    model: [tbody]
  header:
    model: [thead]
  footer:
    model: [tfoot]
  caption:
  model: [caption]

https://git.drupalcode.org/project/ui_suite_bootstrap/-/tree/5.1.x/compo...

name: "(Table Row)"
model: [tr]
slots:
  cells:
    title: "Row cells"
    description: "A sequence of cell components."
    model: [tr]

https://git.drupalcode.org/project/ui_suite_bootstrap/-/tree/5.1.x/compo...

name: "(Table Cell)"
slots:
  content:
    model: [td, th]

⚠️ To be clear, we are not putting here what we expect in slots or as parent, but what we have as component or slot wrapper. So no unexpected behaviours.

Discussed with Laurii which is agreeing with keeping this simple, with ideally a single keyword, but not using such logic based on HTML elements.

So, other proposal...

1. A single keyword: model (or something else, let's discuss) which can be optionally used both in a component definition and a slot definition:

• At the component definition level, we put any keyword (ex: "section", "flow", "content"...)
• At the slot definition level, we put a component id (ex: my_theme:accordion_item) OR any keyword (ex: "section", "flow", "content"... anything)

Example with component ID

my_theme:accordion parent component:

name: Accordion
slots:
  content:
    title: Content
    description: "Accordion items."
    model: ["my_theme:accordion_item"]

Matching my_theme:accordion_item child component:

name: Accordion item
slots: {...}
props: {}

Example with a keyword

my_theme:accordion parent component:

name: Accordion
slots:
  content:
    title: Content
    description: "Accordion items."
    model: ["accordion_item"]

Matching my_theme:accordion_item child component:

name: Accordion item
model: ["accordion_item"]
slots: {...}
props: {}

Pierre's personal note

I like the keyword-based proposal as much as my previous HTML-based proposal, but I am afraid using component ID will be considered as bad practices (because too constraining) after a while.

Responding to earlier comments, not #29...

It's totally possible for XB to add an extra yml file to SDCs

+1. I moved my proposal, with this suggestion incorporated, into #3513563-12: [later phase] Component slot restrictions ("which?") + limits ("how many?") → .

intendedFor

Love it! I incorporated it into that issue comment.

Traits with conditions I'm not so sure about.

I think we need it to support use cases like #14, because whether a component is wide or narrow, light or dark, often depends on prop values. From an Experience Builder perspective, what this would mean is as long as the component has some prop values that are compatible with the policies, we'd let you put the component into the slot and then restrict the props form to only the policy-compatible values.

A simpler structure

I agree with simplifying how to express the conditions. I incorporated that into #3513563-12: [later phase] Component slot restrictions ("which?") + limits ("how many?") → .

One downside to such a flexible system is we are bordering on violating the concept that everything you need to know about a component is in the directory

The key to #19 / #3513563-12: [later phase] Component slot restrictions ("which?") + limits ("how many?") → is that everything that's about the component is still in the SDC's directory. Whereas the policies aren't about individual components, they're about component traits. For example, a policy about contrast ratios or width compatibilities is based purely on comparing the slot's computed traits (its own traits plus ones inherited by ancestors in the layout tree) with the component's computed traits. Even a policy that says "there must be an intersection between a component's is trait and a slot's intendedFor trait" isn't about a specific component, just about that general rule.

I like #29, but I think it's confusing for the same word, model, to mean something different for a component (what the component is) than for a slot (what the slot is intended to contain).

Personally, I'd suggest renaming it to something like is at the component level and intendedFor at the slot level.

I think the keywords within each can also include HTML tags where appropriate. For example:

name: "(Table Row)"
is: [table_row, tr]
slots:
  cells:
    title: "Row cells"
    description: "A sequence of cell components."
    intendedFor: [table_cell, td]

The above example might seem redundant, but something like [card, div] might not be.

Other terminology brainstorming...

We could shorten intendedFor to just for:

name: "(Table Row)"
is: [tr]
slots:
  cells:
    for: [td]

Or, if we like the idea of using model in both places, we could qualify the one for the slot with slotted:

name: "(Table Row)"
model: [tr]
slots:
  cells:
    slotted:
      model: [td]

#32.2 would leave room for also being able to identify the model of the slot distinctly from either the containing component or the slotted component. For example:

name: Table
model: [table]
slots:
  rows:
    model: [tbody]
    slotted:
      model: [tr]

Don't know if there's practical use cases for that though.

@effulgentsia

I don't have strong opinion about the naming of the properties we may add. Let's focus on mechanisms first.

I still believe the logic based on HTML elements in #28 is the best for now. Not because it is dealing with HTML elements, but because we are not adding information about what we expect in slots or as parent, but information about what we are as component or slot wrapper. It delegates the logic to an external, alterable, service and keep component definitions "clean" and furire proof while doing the expected job.

In #31, you propose to use both tags and HTML elements, but your example is dealing with the expectations (cell slot is expecting td components):

slots:
  cells:
    intendedFor: [table_cell, td]
 

How can we achieve that with your new proposals?

Anyway, all those proposals from everybody are useful. Step by step, we are approaching a solution.