Custom Elements will be used as the components for Ashlar
Context
We have been long discussing ways to make parts of Ashlar available to web applications outside of Drupal. Some of the technologies that have been floated are Web Components and frameworks like React.js
Warning that some of the language used in this ADR can be confusing due to different meanings in different contexts. For this particular ADR:
- Web Components (both words together, capitalized) refer to the specifications set forth by W3C as described at webcomponents.org. Web components are composed of four pieces: 1) Custom Elements, 2) Shadow Dom, 3) ES Modules, and 4) HTML Template. These can also be thought of as Vanilla web components, since they don't require external frameworks (like react.js)
- components refer to the more casual use of the phrase "web components," which can refer to any number of technologies that allow for use of custom elements, including frameworks like React.js, Angular.js, etc
- Custom Elements are essentially Web Components that don't use a Shadow Dom. They are created with Vanilla JS, but they lack scoped styles.
Decision
While scoped styles in the Shadow DOM are a key selling point of Web Components, they conflict with the way that styles in Ashlar are specifically set up to cascade and inherit. Using Shadow DOM would require introducing repetition and redundancy. For this reason, we will use Custom Elements to create portable components in the theme, rather that Web Components.
Using Custom Elements introduces new dependencies on JavaScript, which can present usability problems for a small subset of users. For this reason, we will only create custom elements when there is a clear use case (such as using the Western Header on non-Drupal applications) and we will use <noscript> within Ashlar as a fallback.
Component frameworks, such as React.js, can introduce complexity into the development and deployment of the theme and individual components. For this reason, we will write our own Custom Elements using Vanilla JavaScript
Status
Consequences
We are able to create slim, packaged components both for use within Ashlar and in non-Drupal applications
We do not require special installation for using these components, only a few lines of HTML
We miss out on some of the benefits of ShadowDOM, which means that we still require linking to external stylesheets for our components to be styled properly