Is the Web-Components the right technology for a growing platform and community?

[trusz]

Question

Is the Web-Components the right technology for a growing platform and community?

Context

We plan to move away from a monolithic structure to a more modular one.
By separating Core from Plugins we hope for following effects:

• plugin authors can easier pick their technology
• plugin authors can develop independently of each other
• core authors can focus on the platform and provide general solutions
• distributors can easier configure their distributions and pick plugins

Overview Of OpenSCD Next's Planned Architecture

Problem

1. the main problem is that the multiple instances of web-components with the same tag name cannot co-exist
2. this leads to that, that we cannot have multiple versions of a custom element because the first one to register is going to win and everybody will use that
3. currently there is a rail guard¹ so we do not get an error message when we register a component multiple times e.g.: mwc-button. ²
4. if we to split up OpenSCD into different repositories and packages, it will be harder to ensure that everything is going to work
5. this will be a problem until the scoped custom element registry gets implemented³

Options

1. Enforce Same Version (pinning)

Updates need to be synchronised and at the same time to avoid conflicts. This will lead to bottlenecks.

2. Do Not Use Custom Elements (and Lit)

We use custom elements for OpenSCD itself (open-scd element) and for the plugin mechanism.
Custom elements work well for adding plugins and wizards dynamically to OpenSCD. It has great capsulation because styles are captured inside the shadow root and frameworks and libraries do not bother the rest of the DOM.

However, inside of plugins and wizards we need a different technology that does not depend on custom elements like: React, VueJS or Svelte

The main disadvantages:

1. people have to use a different framework and may have to learn a new framework
2. the design won't be consistent anymore, or will be hard to maintain

Both are manageable problems but need extra effort.

3. Wait For Scoped Custom Element Registries

We continue as is and wait for the scoped registries.
As of now there is now target date.

Footnotes

1.   <script>
       const _customElementsDefine = window.customElements.define;
       window.customElements.define = (name, cl, conf) => {
     	if (!customElements.get(name)) {
     	  _customElementsDefine.call(window.customElements, name, cl, conf);
     	}
       };
     </script>
   

   ↩

2. this might be change up so at least we get an error message ↩

3. scoped custom elements are behind a feature flag in chrome canary: https://github.com/WICG/webcomponents/issues/716#issuecomment-1535263394 ↩

[ca-d]

Context

We plan to move away from a monolithic structure to a more modular one.

A modular plugin system was very important for us from the start, we never had a monolithic architecture. @JakobVogelsang and I had intended from the beginning to develop a tiny set of general purpose "internal" plugins ourselves within the open-scd repository, and for all other (more special purpose) plugins to be developed in separate repositories using whatever technology the authors wish. For reasons of convenience, the first external plugin authors were not keen on developing their plugins elsewhere or choosing different technologies for doing so, and despite some reservations Jakob and I included their plugins into the open-scd repository, thinking "we can always factor these out into separate repositories later".

As it turned out, they also wanted to use a weird "wizard" system — for workflows with multiple dialog pages one after the other — that Jakob and I had badly ad-hoc designed for our own internal use only. Thus the whole kerfuffle with widespread use of our weird and bad wizard "API" (never intended to be an external API) in plugins began, making it impossible to separate plugins out to their own repositories.

Web components were originally only meant to be used as a way of loading plugins, and lit-html was chosen as a compatible lightweight way of achieving reactive change propagation. Afterwards, @JakobVogelsang coincidentally decided to use mwc components for UI, mostly because of the pleasing looks, and we decided to use lit-element for implementing our own "internal" plugins.

By separating Core from Plugins we hope for following effects:

When we said "Let's come up with a real purpose and usable API for wizards, pull out the core component into its own repository, and develop all plugins including our own 'internal' ones in separate repositories!" in the beginning of 2022, we intended to make that originally intended way of working more clear by getting rid of our original distinction between "internal" included plugins and "external" plugins.

Options

3. Wait For Scoped Custom Element Registries

We continue as is and wait for the scoped registries. As of now there is now target date.

Actually, there is a polyfill available for using scoped registries across all modern browsers right now. I would suggest this for any plugins that still want to use web components. Please note that some mwc components (like mwc-list) are very likely to be incompatible with this (not tested, just my prediction).

1. Enforce Same Version (pinning)

Updates need to be synchronised and at the same time to avoid conflicts. This will lead to bottlenecks.

We don't have a technical way to force plugin authors to do anything in particular. It is important that plugins may always be developed without any coordination with the open-scd core team, so this is something we really don't want. If plugins want to use custom elements without using the scoped custom element registries polyfill (like our internal plugins currently do), they must be fine with another plugin registering a different version of the same web-component on a "first come, first registered" basis (as our internal plugins currently are).

2. Do Not Use Custom Elements (and Lit)

We use custom elements for OpenSCD itself (open-scd element) and for the plugin mechanism. Custom elements work well for adding plugins and wizards dynamically to OpenSCD. It has great capsulation because styles are captured inside the shadow root and frameworks and libraries do not bother the rest of the DOM.

However, inside of plugins and wizards we need a different technology that does not depend on custom elements like: React, VueJS or Svelte

Plugins may already be developed not just using different javascript frameworks, but also without any framework at all, or using completely different programming languages that compile to javascript like Elm or ClojureScript, or even C# using Blazor compiled to wasm. There are many possibilities here, and I think all of them are fine.

In general I don't see why we need to prescribe a particular approach to plugin authors. If a plugin wants to use web components it can either be fine with different versions (our current approach) or register its own namespaced tag names (or make use of the scoped registries polyfill) in order to have access to fixed versions. If a plugin doesn't want to use web components, it doesn't need to. What do you think of this stance?

[danyill]

3. Wait For Scoped Custom Element Registries
   We continue as is and wait for the scoped registries. As of now there is now target date.

Actually, there is a polyfill available for using scoped registries across all modern browsers right now. I would suggest this for any plugins that still want to use web components. Please note that some mwc components (like mwc-list) are very likely to be incompatible with this (not tested, just my prediction).

I looked at this a couple of months and though I have mostly forgotten the Limitations are important if we are trying to use the same UI components:

Limitation 1: Components should not be self registering. The mwc-components we use are self-registering. Also, see material-components/material-web#2010

Limitation 2: Every component that uses sub components should use scoped-elements. mwc-components do not use scoped elements.

The alternative "find and replace" version which would allow this to be used might be https://github.com/scoped-elements/material-web although I'd be reluctant to use an unreleased, unmaintained thing like this without guarantees and cautious about having to maintain this ourselves.

[trusz]

Maybe there is another UI Library that does not have these problems, or we just have to create our own? 🤷 :D

[trusz]

@ca-d as usual, thank you for the great clarification! :)

In general I don't see why we need to prescribe a particular approach to plugin authors.
That was not my intention, only maybe for those that the core team maintains.

Actually, there is a polyfill available …

If I understood it correctly, the polyfill that you linked is to scope elements that I use in my component. This is something we could maybe ask of plugin authors? Does not seem too much of a hustle. (I don't like that it reminds me of Angular's module structure but that is just my problem :D )

An interesting point I found is that there is a scoped custom element registry polyfill what we could include globally in core so nobody has to do anything:
https://github.com/webcomponents/polyfills/tree/master/packages/scoped-custom-element-registry

What do you think?

I'll try out both and let you know how it went.

[ca-d]

I'm fine with either, I wouldn't ask plugin authors to do anything in particular, some plugins may be fine with a different version of the same component being registered first. We can warn plugin authors of this pitfall and recommend the polyfill as a workaround.

Before adopting a global scoped registry I'd want to check whether components like mwc-list-item are fully compatible using a POC. I'd also be interested how the new material components (prereleases for version 1.0) will handle things like list items and whether it's less of an issue there.

[trusz]

I wouldn't ask plugin authors to do anything in particular

True. Distributors can decide if they want it and can include it in their distribution