Add Single Directory Components as a new experimental module

Problem/Motivation

We want to add the concept of a component in Drupal core. See #3313520: Single directory components in core for more details.

What do you mean by "component"?

In this context, a component is the combination of:

• A regular Twig template.
• Metadata describing the input data the template accepts (the *.component.yml file).
• Optional JavaScript.
• Optional Styles.

Examples of components

See the test modules and themes in the MR to see some examples of components. You can also take a look at the SDC Examples contrib module.

Proposed resolution

Let's add a new experimental module to Drupal core.

Remaining tasks

• Explicit +1s from front-end framework maintainers, and some other framework maintainers.
• Define requirements for SDC to become a stable module within the expected time window.
• Establish a roadmap for making the module stable.
• Rename module from SDC to something without an acronym.
  Ideally we'd use components, but that name is taken. Right now
  the current thinking is to rename to ui_components - Since we plan on this will going into core itself, there is no need to rename the module (plus there's no viable names)
• Complete code review. - completed by @larowlan
• Have additional themers test out creating a component to validate the architecture.
• Add @todo comments pointing to #3352546: [PP-2] Port SDC to use ExtensionTypeInterface as appropriate. Fixed in commit 27525e27
• Fix CF and Cspell issues
• ???
• Profit!

Validation from themers

We have worked with themers to validate the developer experience by having
them create their own single directory components

• @idiaz.roncero in #3326619: SDC proof of concept: Olivero messages
• @unstatu in #3334326: Claro status-message example
• @mherchel in #3347235: Create new SDC component for Olivero (tabs)
• @markconroy in #3347672: Create new SDC component for Umami (card view mode)
• @mstrelan in #3347736: Create new SDC component for Olivero (header-search)

FAQs

Why a core module instead of a contrib?

As stated in this comment:

Projects that provide a different component solution like Compony, UI Suite, CL Components, and others, will see their different solution on this small part (the component definition) superseded by the new core standard. That is a good thing. UI Suite (for instance) can now leverage the new component solution, and not maintain its own.

Additionally, SDC aims to lower the barrier of entry to front-end developers new to Drupal. This profile of developers is likely to be unaware of the existence of a contributed module that aims to help them be effective.

I am not sure my team needs this. What are the selling points?

Selling points are exclusive for Drupal projects. Some of the biggest benefits we see are:

• Front-end engineers define the visual API (aka slots & props). This means can work reliably in parallel without waiting for that content type, view, etc.
• Hot reloading as they work on CSS & JS of the component in Storybook. Storybook integration is made possible by SDC, but not included in core.
• Improved DX for front-end work. Ex: no more writing and attaching libraries, base components for cross-project reuse with BC safety nets.
• Reliable Storybook integration for Drupal components. This allows automated accessibility audits, automated Lighthouse reports, automated visual regression testing, etc. Storybook integration is made possible by SDC, but not included in core.
• Modules and themes can ship components. Your custom theme can replace components cleanly without having to fight the specificity war and track down the pesky preprocessors.
• Component libraries promote design consistency and code reuse. This has an impact on maintainability.

What parts of the theme system can this replace?

This more an addition to the theme system than a replacement. Perhaps some custom render elements can go, but nothing impactful. When this is stable, we may be able to replace some parts of core themes, when we start to use SDC in them. In the end this is just trying to formalize something that so many agencies build on top of the current theme system, for client projects. Everyone does it their own way, as evidenced in #3313520: Single directory components in core. Our hope is that standarization will allow shared extensions to flourish, starting -perhaps- with projects like the UI Suite.

Why are there no hooks in SDC?

There could be two types of hooks, the ones that alter how the component is discovered and defined, the ones that alter how the component is rendered.

We think it's not a good idea for core to support significant alterations to discovery and definition. This is because it increments the API surface of SDC and the maintenance of it in core. Additionally having disparate discovery and definition in different sites goes against the standarization goal. It will be difficult for a new front-end developer to understand their site when the documentation and examples look so different from what they see in their site. Contributed modules, however, can alter this behavior.

We also believe it's not a good idea to alter how a component is rendered. This is to avoid some of the current confusion that themers experience when several alters change how their template is rendered, or change their variables, etc. When that happens in different modules and base themes, finding your way around is quite hard. When everything can happen everywhere at any time, we can't have good documentation, we can't provide relatable examples, we can't give good support in Slack, newcomers can't state their problems correctly, ... We want to avoid that in components. The principle is that everything that affects a component, is in the component's folder.

How can SDC be extended?

When it comes to extending SDC, there are a couple useful projects that may help see the vision for SDC:

• CL Server: this one is in charge of rendering components in isolation compatible with Storybook and hot reloading. Version 2.x is compatible with SDC.
• CL Generator: this contrib adds a drush command to scaffold a component via command line. Version 2.x is compatible with SDC. See a short video
• CL Devel: debugging aids for components. Adds an audit page that tells you if everything is OK with your component. Version 2.x is compatible with SDC. See a screenshot
• CL Block: let's you turn the components of your choosing into blocks, or CKEditor buttons, with a click. It autogenerates the form for filling the props and slots. Not compatible with SDC yet as I have never written a ckeditor5 plugin before.

User interface changes

No user interface changes.

API changes

No API changes, but new APIs introduced. (TDB: explain the new APIs)

Data model changes

No changes.

Release notes snippet

TBD.