Compatibility and Interop Specification (Versioning WCs)

[thescientist13]

Overview

As "Web Components" itself is an umbrella label for a subset of web standards, yet also benefits from and is enhanced by many other adjacent web standards, coalescing around a shared understanding of what it means to be a "Web Component" can be a bit challenging from a user (of WCs) perspective. This extends to characteristics of a Web Component like the spec web platform features used, bundling, polyfills, or server rendering support to name a few. Additionally, it is often up to each maintainer / platform / project to try and best explain the journey of developing and distributing Web Components so as to best facilitate that user (developer) journey for their respective use case.

Motivation

For example, for a new major version release of most large and popular open source project, I can go to a changelog or blog post and typically get a run down of:

• Features and capabilities
• Environment and runtime expectations
• Potential known issues and limitations

By taking a sample of what's standard in the platform through a representative majority of critical browsers (Chrome / Edge, Firefox, Safari) at a given time, the goal of this proposal would be in the (ongoing) drafting of a living specification document that can identify a reasonable "SLA" that community projects can align on, either directly documented in a project's README / website, or through something like Custom Elements Manifest.

Use Cases

There are a couple principal use cases that come to mind as for who might best be able to take advantage of such a protocol for Web Components.

Library Authors

Library authors wanting to know what features are "safe" to use or adopt, and that can reference via a link for evaluators or potential consumers to communicate what sort of features they take advantage of from the web platform or to what degree of polyfills or shims may be expected from the userland implementor. Being able to express this through a link that could provide supporting references and materials to help users achieve the necessary parity to instrument said library would be very useful.

It can also be used to hint or indicate to any sort of SSR compatibility.

(Full Stack) Framework Implementors

For those delivering frameworks solutions where SSG or SSR comes into play, this would really benefit by aligning on a shared understanding of the WC related APIs, on top of the runtime at play. I know from observing a handful of various repos on GitHub that using WCs in non-tuned for WCs SSR frameworks can often come with unexpected results, so adding a little more standardization on the server side could be really valuable.

In a way, this feels like a natural extension from the ElementRender proposal presented in the SSR issue.

Specification

Similar to how TC39 drafts a new version of the ECMAScript specification each year to set a level of expectation, the Web Components community could similarly draft as well, and help capture what features or standards have broad enough platform support that they can be "versioned" against.

Documentation

So at pre-defined intervals the governing body would "snap a line" of what is supported by browser vendors at that given time and "tag" that new level of cross-platform support as a new version, and then publish those details. Each new entry published would be a canonical link that could be reference in Custom Elements Manifest, thus clearly communicating a level of support and / or compatibility.

Version	Year	Standards Adopted	Notes
2	TBD	TBD	Evaluating import assertions and constructible stylesheets
1	2021	Custom Elements, HTML Templates, Shadow DOM, ESM	Baseline

Custom Elements Manifest

Totally bike-shedding on the name here with specificationVersion but an example snippet from a custom-elements-manifest.json would be defined as such, e.g.

{
  "schemaVersion": "1.0.0",
  "specificationVersion": "v2",
  "readme": "README.md",
  "modules": [
    "..."
  ]
}

Canonical link would be evaluated to something like http://webcomponents.org/community-specification/v2.html.

Server Side Rendering (SSR)

I see something like this being especially valuable for SSR frameworks, so as to allow each of them to set and support the level of compatibility with any of these versions that they can support. For user's of these frameworks, it would be a very helpful reference of what sort of baseline support to expect as they're picking their frontend libraries / design systems / etc.

For example, thinking of these kinds of APIs (and to what degree of support if applicable) that might be assumed already given a browser context and so would want special attention for SSR:

• window / document
• customElements.[define|get]
• HTMLElement
• addEventListener (no-op?)
• HTMLTemplateElement
• attachShadow
• .[get|set|has]Attribute
• <template> / DocumentFragment

On the topic of SSR, not sure if there would be a different version needed for SSR support, or maybe just a "companion" list to supplement the spec? There is also WinterCG, which is curating a "web standard" first runtime for JavaScript in the context of Serverless and Edge functions, so factoring that in could also be useful?

Governance

It would be great to have some governance around this in particular to make sure participation is socialized and to conduct a "roll call" from key contributors when preparing the next version of the specification. This could also maybe even align with other objectives and interest like our reports for TPAC?

Not so much sure on the process just yet, mostly just interested in getting the idea out there for now.

---

Thoughts / Prompts / Bike Shedding

1. How often to snap a line (yearly?)
2. Versioning strategy (semver, yearly, other)
3. Different specification for Browser vs SSR?
4. Specification name (for CEM)

[justinfagnani]

The way I see this is that the web components APIs are just a subset of the DOM APIs, and libraries with web components in them are just libraries. In other words, what is special about web components compared to other uses of the DOM?

If we want some kind of year label on the DOM, shouldn't it apply to all the APIs?

[thescientist13]

Yeah, it might not apply as much to the browser runtime where caniuse.com or the Web Interop report can provide that sort of "compatibility matrix", or probably the libraries own documentation.

I mostly had SSR in mind, where it is more than likely each (meta) framework's dom-shim.js implementation would be DIY, and so establishing some sort of continuity at that layer could be beneficial to the community.

[thescientist13]

@justinfagnani
I noticed in the Lit SSR DOM Shim README it says

(This package is planned to eventually move to @webcomponents/ssr-dom-shim to better reflect this use case)

This is actually a nice evolution of what I was thinking of in the SSR section of my issue here, so would definitely be down to help champion an effort towards a shared SSR shim at the community protocol level like that. 💯

[thescientist13]

Moved the SSR part specifically to its own issue, focusing on just the topic of a community DOM shim - #55