SDC and code component props should be able to receive HTML, editable in formatted text fields+widgets

We need to allow SDCs to specify they accept HTML markup in a particular prop

From the perspective of an SDC author, what's the difference between an HTML prop and a slot? What are example use-cases for an HTML prop and why shouldn't that be a slot instead?

Introduce a new type: string, format: markup

If we decide to go with this option, I suggest format: html rather than format: markup.

this string must start and end with an angular bracket

Not all HTML fragments start and end with brackets. E.g.:

• hello world
• <em>hello</em> world
• hello <em>world</em>

are all valid HTML fragments.

I was imagining this would be a prop because a) it's not any HTML that the prop allows, it's HTML generated by a rich text editor that's allowed b) slots are considered separate from props which would make generating a form pretty complex.

What comes to configuring the prop, it seems that type: string, pattern: ^\<.*\>$ is also pretty bad for developer ergonomics, and that type: string, format: markup or type: string, format: html would be much better from that perspective.

it's not any HTML that the prop allows, it's HTML generated by a rich text editor that's allowed

Does it make sense for the SDC creator to decide that? A rich text editor can generate almost any HTML (e.g., if you use Drupal's "Full HTML" format), so what exactly is the decision that the SDC creator is making when saying something is an HTML prop vs. a slot? I.e., imagine someone creating a component library in Storybook and not thinking about Drupal concepts: for this person, what does it mean for something to be a slot? what does it mean for something to be an HTML prop?

#7: The SDC schema is not generic in the sense that other systems would be able to read it without a specific Drupal integration. In the process where you have pre-existing components that may exist in a component library utilizing storybook, you would still have an integrator specifying the SDC schemas for the Drupal integration, which is when these types of decisions would be made. In Twig there are some interesting aspects to this, such as that slots have their own syntax, meaning that some of these decisions may be made upfront. I believe it is possible to expose a slot as a prop within a component without modifying the original code but not vice versa.

I think using either props or slots could be right depending on the use case. Here's two examples that demonstrate this.

Example 1:

Let's imagine a frontend developer received this as a design for them to implement as a component. Because the text is using bold and italic, would they think automatically that they should be using a slot that could allow variety of inputs? I personally don't think so because this would always be a short text that could have some formatting. Because HTML is somewhat arbitrary and generally wouldn't be used for defining logic, they could potentially define this as a slot that only allows a paragraph component but that would mean that the content is authored via a separate component.

Example 2:

Let's imagine we now have this as a design for them to implement as a component. The text has formatting but based on this design, we can expect this layout to also allow content creators using elements other than the text. We can se an example of button being shown in the design. I think in this case it would most likely make sense to use slots that provide content creators with more flexibility to use the space.

Hi all,

I was imagining this would be a prop because a) it's not any HTML that the prop allows, it's HTML generated by a rich text editor that's allowed b) slots are considered separate from props which would make generating a form pretty complex.

As effulgentsia asked: "Does it make sense for the SDC creator to decide that?"

In my opinion, no, it doesn't. The component author doesn't have to care about rich text editors and other CMS stuff.

The component author is building a pure UI data model, without any applicative or business considerations, where he needs to pick the right type for each data he is expecting in the template.

If there is markup, it is a slot. I would advice to keep string prop for plain text.

@pdureau I think we might be talking past each other because I think you could still define component libraries and design systems that are free of business considerations. I could imagine with the example that I provided in #10 that organizations with more experience in design systems could own two components; one that's free from business considerations and one that includes business considerations. Only the one that includes business considerations would be exposed to content creators within XB. An organization could decide to share either one or both between sites depending on your particular needs. What I'm arguing is that frontend developers should be able to define these constraints in a way that is natural to them, which would be in *.component.yml.

Hi Laurii,

I think we might be talking past each other

Indeed, our comments have crossed in the thread.

Thanks for those interesting examples.

Example 1: Because the text is using bold and italic, would they think automatically that they should be using a slot that could allow variety of inputs?

The prop type described in the issue will also allow users to inject any markup, like an other component markup.

Of course, you can prevent this in the Experience Builder UI, by allowing only a simple WYSIWYG for this prop type, but it doesn't change the reality of the component, and the other usages (custom PHP code, twig includes, other display builders...) it will get. And the component author may not even know what Experience Builder is. It is like using a Field Widget instead of a Field Type to define and check the field's stored data.

If a component author really want to enforce this specific design (with one line of italic, and one line of italic + bold), it becomes a part of the component itself. So, 2 string props, one for each line, seems to be a good solution.

that organizations with more experience in design systems could own two components; one that's free from business considerations and one that includes business considerations. Only the one that includes business considerations would be exposed to content creators within XB.

I am not sure I am understanding this idea. The business-related UI component will call/embed the business-agnostic UI component ?

I am not sure I am understanding this idea. The business-related UI component will call/embed the business-agnostic UI component ?

Yes 👍 It could look like something like this:

The business agnostic card in the design system which would work in XB, but would not result in optimal editorial experience for a content creators:

<div class="card">
  <div class="card__image">
    {% block image %}
    {% endblock %}
  </div>
  <div class="card__title">
    {% block title %}
    {% endblock %}
  </div>
  <div class="card__body">
    {% block body %}
    {% endblock %}
  </div>
</div>

A site specific card component with business requirements accounted for resulting in better experience for a content creator:

{% embed "design_system:card" %}
  {% block image %}
    {{ include "experience_builder:image" with { ...image } only }}
  {% endblock %}
  {% block title %}
    <h3>{{ title }}</h3>
  {% endblock %}
  {% block body %}
    {{ body }}
  {% endblock %}
{% endembed %}

they could potentially define this as a slot that only allows a paragraph component but that would mean that the content is authored via a separate component.

I don't think this is a limitation. I think we can support in XB the concept of slots whose values are populated by the value of a rendered field type (such as text_long) or field (such as field_body), so that the content author doesn't see it as a separate component but rather as indistinguishable from a prop. The question then becomes where should the information live that a particular slot should be treated this way within XB.

What I'm arguing is that frontend developers should be able to define these constraints in a way that is natural to them, which would be in *.component.yml.

But what is the constraint that the component.yml should specify? That the slot should be constrained to "rich text" only and leave it to the system to decide what that means in terms of allowed HTML tags? Should this basically be the same as "all inline HTML tags" or would it need to vary by site or by component or be tied to Drupal's text formats?

#18 was a cross-post with #16/#17. If we go with the enum approach in Proposed resolution #3, then that addresses all of my concerns with it being a prop. Perhaps it would even make sense to name it format: rich_text or format:restricted_html instead of format: markup for even more guidance as to what would typically be appropriate for the enum? Also, presumably we could create some default JSON schema definitions for common enum sets that a component can reference via $ref?

This is counter to the vision @lauriii has expressed, and would violate many of the 64 product requirements (...) As a SDC component author, I'd expect to be able to express that in a particular markup prop, only and are allowed, but in another prop only is allowed. (...) The prop's schema should be able to optionally convey exactly which tags are allowed.

Thanks for making this explicit. However, I don't recognize here the design system philosophy and the separation of concerns I am promoting. So, I have nothing more to add than the warnings I have already shared.

I am out of this thread, but I am always happy to discuss about other SDC & XB subjects ;)

enum:
        - <p>
        - <br>
        - <a hreflang href>
        - <ul type>
        - <ol start type>
        - <strong>
        - <em>

Is there a reason for the SDC to constrain the attributes? I'm not clear why that would be relevant to the component's design.

If XB then uses a text_long field for authoring, then that field's filter format will be what restricts the attributes, but that's a separate concern from what the component cares about.

This, however, raises the question of what if there's a mismatch between the component prop's allowed tags and the filter format's allowed tags?

• If the component prop allows tags that the filter format doesn't, that's fine, it doesn't break any validation: just because the component's design allows something, doesn't mean the content author has to use it.
• But if the filter format allows tags that the component prop doesn't, then it gets trickier. We'd need to get the processed text out of the text field and then strip the tags not allowed by the component prop. Which is fine from a technical standpoint, but probably not great UX (what you see in the CKEditor wouldn't match what you'd get in the rendered output). Better would be to set CKEditor's ACF to the intersection of what's allowed by the filter format and what's allowed by the component's prop.

I don't recognize here the design system philosophy and the separation of concerns I am promoting.

I care about design system philosophy and separation of concerns. Do you think proposed resolution #3 achieves that? As I understand it:

• If the SDC wants to specify "more or less any HTML can go here", then that's a slot.
• If the SDC wants to specify "more or less only formatted text can go here", then that's a prop, with a way to specify which formatting tags are allowed.

Or does the above not match how components for design systems are actually designed?

Is there a reason for the SDC to constrain the attributes? I'm not clear why that would be relevant to the component's design.

I didn't mean this level of configurability by my comment in #13. At most, I could see there there to be a use case for two different levels of RTE for components; inline vs block (inline wouldn't wrap text in <p>).

I personally have a slight preference to the prop solution because I believe that's closer to what other platforms are doing. Pretty much all of the ones I looked at provide RTE as a unique prop type. For example:

1. Paragraphs uses RTE as a field but has the concept of slots through entity references
2. Wordpress Gutenberg uses type: 'rich-text'
3. Shopify uses type: 'richtext' and type: 'inline_richtext'
4. Builder.io uses type: 'richText'
5. Plasmic uses type: 'string', control: 'large'
6. Framer uses type: ControlType.RichText

That said, if we find a way to provide a decent DX by using slots, I'd be totally fine with that. I'm not sure I fully understand what's the benefit of that so maybe it would be better understand what are the differences that allow it to provide a better experience.

I'm wondering if we should ship with two pre-configured text formats that are optimized to XB by us, and are always used for the XB components. The text formats can be modified but not deleted.

Block text format would come with the following buttons and would wrap text in <p>:

1. Bold
2. Italic
3. Underline
4. Link
5. Unordered list
6. Ordered list

And the inline text format would come with following buttons but would not wrap any text in <p>:

• Bold
• Italic
• Underline
• Link

This would allow us to optimize the experience so that the block text allows input from regular RTE fields using a token. However, the inline text would only allow input from string types.

Big discussions :)

Is this targeted for Barcelona?

Is the best way to see what's for Barcelona here?

https://www.drupal.org/project/experience_builder/issues/3454094

Should there be tags like "Barcelona Blocker" or similar for must haves for Barcelona?

I thought more about the prop vs slot conundrum, and unfortunately I've come back around to favoring slots for this. I say unfortunately, because it will mean that this issue will take longer to get done, but I think it's worth it.

To be fair, I think there are two quite reasonable approaches for how to model the props vs slots distinction, one that leads to modeling rich text as a prop and one that leads to modeling rich text as a slot. Although both are reasonable, I think the slot approach is better.

Approach 1:
HTML web components are about the closest actual standard that exists that's closely related to the props vs slots concept. Within web components, you have attributes (which are a lot like props) and slots, and you can pass HTML content only through slots. I think this is a strong point in favor of us modeling SDC props and slots the same way. For example, it would make it easier to in the future (e.g., in #3454519: [META] Support component types other than SDC, block, and code components) support implementing SDC-like components as web components. Also, because web components are a standard, all major JS component frameworks (React, Vue, Svelte, etc.) support this way of distinguishing props and slots (even in React, where it all ends up as just props, there's docs and libraries for how to map to React props if you're coming from a web components props vs slots mindset).

Approach 2:
We can define SDC slots as things that you put other SDCs (or other kinds of components once #3454519: [META] Support component types other than SDC, block, and code components is done) into, and since content coming from a rich text editor isn't itself a component, then it should be modeled as a prop. This is the approach / mental model implied in #10, and which according to #23 is adopted by various other content management tools.

However, we don't need to adopt approach #2 in order to have the UX we want. In #3462705: [META] Missing features in SDC needed for XB we're already surfacing the need for various ways we need to express slot restrictions. Whatever approach we come up with for that, I think we can extend to also include being able to express slot restrictions as HTML tag restrictions. And if a slot restriction is expressed as HTML tag restrictions rather than as component restrictions, then we can infer that we want to give content authors a rich text editor for that instead of letting them drag other components into that slot.

Following approach 1, this would avoid the need for us to figure out how to express the concept of rich text and tag restrictions within JSON schema. Instead we can invent how to do this within the concept of slot restrictions which is something we're making up all of the syntax for anyway.

However, a downside of approach 1 is that we'll need to evolve our data model. Currently our data model consists of a clean separation between the tree (which deals with slots) and prop values (which deals with props). That would need to evolve to where the "prop values" can also include the rich text values that populate slots, at which point we might need to rename that from "prop values" to just "values".

While I don't think that extending our future implementation of slot restrictions and our current data model will add an unreasonable amount of work, I think it will likely add enough to not make it in by the 0.1.0 release that we're targeting for Barcelona. I'm not sure what that means if we want the 0.1.0 release to have the ability to populate components with rich text. Maybe there's something we can hack in as a temporary way to achieve that?

@lauriii and I discussed this and he gave me some compelling arguments for props (approach 2 in #25). I'm thinking that over and also thinking whether we can do that while still accommodating future use cases of web components and JS (React/Vue/Svelte/etc.) components.

1. Paragraphs uses RTE as a field but has the concept of slots through entity references
2. Wordpress Gutenberg uses type: 'rich-text'
3. Shopify uses type: 'richtext' and type: 'inline_richtext'
4. Builder.io uses type: 'richText'
5. Plasmic uses type: 'string', control: 'large'
6. Framer uses type: ControlType.RichText

If my understanding is correct, those are examples of WYSIWYG / display builders configurations, not UI components definitions. And none of them are using JSON Schema notation anyway.

he gave me some compelling arguments for props

If we go this way anyway, can we stay compatible with JSON schema specification by not introducing drupalisms or anything related to XB in the prop definitions?

For example, this is wrong because the enum keyword will limit available strings to "<em>" and "<stong>" instead of acting as #allowed_tags property of #markup renderable:

    heading:
      title: Heading
      type: string
      format: markup
      enum:
        - <em>
        - <strong>
 

For JSON schema, I think we can represent it (in YAML) as:

type: string
contentMediaType: text/html
x-allowedTags:
  - em
  - strong

See contentMediaType and custom annotations.

Within web components ... you can pass HTML content only through slots.

In practice I think there's some decent options available to us for passing HTML content from a rich text editor through as props/attributes to JS framework components or web components. For JS framework components, the JS framework component can internally delegate the responsibility to a component dedicated to rendering HTML content from a CMS. For example, for React there's react-html-map and probably various other options. Or, people can roll their own using whatever the framework's approach to rendering HTML strings is (for example, in Svelte, using {@html ...}) combined with an XSS filtering library like DOMPurify.

For vanilla web components (does anyone actually write vanilla web components these days now that https://lit.dev/ exists?), someone could either use .innerHTML combined with an XSS filtering library like DOMPurify, or we could add an optional PHP-side rich-text prop to slot converter when rendering the web component's custom element.

So from a technical standpoint, I don't have objections to rich text as a prop anymore.

@lauriii and I discussed this and he gave me some compelling arguments for props (approach 2 in #25)

The main one is being able to express order. For example, say you have an SDC with "props":

• title
• description
• link

And you want description to be able to contain HTML formatting like <strong>, <em>, etc. If we modeled description as a slot, we'd need some way within the SDC's YAML to specify that within editing UIs (like XB), we want the input entry for description to be after title and before link. Any syntax for doing that would already necessitate the SDC developer's mental model being "it's a slot but in a way it's kind of a prop", so actually making it a prop cleans that up.

See contentMediaType and custom annotations.

Cool finding! I am happy to know about contentMediaType.

we want the input entry for description to be after title and before link.

For this specific example, if we consider title a slot (which it is IMHO), we don't need to have such elaborated solution to get description after title (first the slots in the declared order, then the props in the declared order) 😉

This looks like I am nitpicking, and I like the contentMediaType proposal, but my concerns are broader.

We are talking here about adapting the component definition because of the display order in the XB contribution form. This is what I had in mind when I said:

I know Experience Builder is trying to build both a display builder (a better Layout Builder) and an UI components loader/manager (like UI Patterns 2), and I understand it is not an easy task. But I am also afraid the components management may be bent in some ways we may regret later, in order to comply with the current state and needs of the display builder.

I left this thread when I read about "business-related UI components", but I am an hopeless optimist.

SDC freed us by giving us the opportunity of doing front-end without caring about Drupal as a CMS, business rules and application state. Now, we can build the best UI components possible, without thinking about Views, Field API, Layout Builder or Experience builder... and then use them with all their glory in a Drupal context. Let's embrace this.

It will be a key success indicator if XB is shipped without any SDC components AND is able to leverage correctly any SDC component from the Drupal community.

I haven't read through the comments, but @lauriii wanted me to post my use case here for a question that I was asking:

Is it possible to allow rich text, and then limit the HTML within that within props?

Use case: I have a card component. I want the entire card to be clickable, so I can either wrap everything in an <a> tag or do another method to make it clickable. However, I want the description text to be rich (so editors can bold and italicize). But it cannot allow links since these will not work.

The point of all this: thinking through what it'd mean to go much further in allowing SDC developers to specify the authoring experience for Content Creators.

Hi Wim, it has been a long time you haven't heard of my warnings so here I am again 😉

The mission of SDC developers (as component authors) is to provide the best implementation for UI components, they don't have to think about the business/applicative/CMS side, so they don't have to specify the content editor experience. Once a component author starts to think about the CMS, he is in risk of lowering the quality of its UI Component.

It is not only a theoretical stance, we are doing this with UI Patterns since 2017 and it works well. UI Patterns 2.x is the proof it still work (and work even better IMHO) with SDC: we are able to inject data to slots & props from many sources.

Content editors are not the only users of a component. An UI component has to be as usable in other contexts (non editorial, unexpected constraints, data retrieval from API...).

So I am afraid this x-format: inline/block will cause harm to XB in the future.

The approach proposed in the issue summary looks great to me, except for 3 minor points:

Follow-up: later still: detailed customization

I agree with #39 that we shouldn't do this for the same reasons as explained in that comment. But since it's listed as a follow-up that's even later than all the other follow-ups, we don't need to come to a consensus on it here.

x-format

May I suggest changing it to x-formatting-context? Although that's more verbose, it grounds it in a specification with a precise meaning. And if it's not specified, we should default to block. @pdureau: Would that resolve your concern with it? If not, why not? Why do you see it as violating separation of concerns for the component author to specify that the component is designed for HTML prop foo to be contained in an inline formatting context?

xb_inline text format (restricted to <strong> <em> <u> <a href>)

I think we should allow <br> as well, since that's an inline-level element and example 1 in comment #10 seems to have one between "Developers" and "Download", unless those are intended to be two different props.

I don't think we need to allow <br> for inline content to build #10. If the design is supposed to have text on two lines regardless of the width, it should not be managed with a RTE.

Usually the use of <br> results in more problems that it solves so I'd say we should probably avoid getting to those. If we don't allow <br>, explaining inline text and regular rich text remains simple since one allows multiple lines and one doesn't.

Proposed solution makes sense 👍

@Wim IIRC you asked for my view on this:

⚠️Big caveat: IIRC there are problems/limitations around CKEditor 5's ability to be configured to use only inline elements — IIRC <p> and <br> are fundamentally assumed to be allowed.

Yes, by default everything must be wrapped with <p> (or <hX> or maybe some other element).
That is an implication of CKEditor 5 internal model's schema:

As per CKEditor 5 documentation:

You cannot put anything you want inside the document model. At least not until you update the schema. The schema defines what is allowed and where, what attributes are allowed for certain nodes, what is not allowed, and so on.

Schema determines things like whether the given element can be enclosed in a block quote, or whether the bold button is enabled on selected content.

https://ckeditor.com/docs/ckeditor5/latest/framework/tutorials/crash-cou...

As metioned schema can be updated. I tried this in a custom CKEditor 5 plugin:

    editor.model.schema.extend( '$text', {
      allowIn: '$root'
    } );

$text is a any text input $root is an root of the document
By default $text is allowed among others in paragraph and that one is allowed in $root

After the schema update I think I got the result you want to implement (source editing enabled here):

Additionally I was unable to insert a new paragraph with enter key also use some plugins (lists mostly) as they most probably aren't allowed in $root:

<br> is allowed in $root and apparently there is no way to remove allowIn entry in element definition. I'll consult that with core team.

Thanks, reading through

Just fixed 1 link in the summary

x-formatting-context: inline won't be possible to support without allowing <br>s

Wouldn't it be possible to hack around this though? For example, implement a plugin that responds to events (keyUp?, maybe others?) by checking if any <br>s made their way in, and if so, remove them?

@Wim Leers this looks good to me. I updated test expectations to get tests to pass. The expectations look correct to me but you probably should review.