Proposal: Well-known symbol for DOM shim

[matthewp]

Issue #17 seeks to make web components runtime agnostic but not relying on globals. However this will be difficult to get the community aligned on in practice as it would require essentially all component authors to start writing components in a different way than today.

This proposal instead seeks to lessen the damage that comes with requiring a DOM shim. Using DOM shims has the disadvantage that adding globals such as window and document can interfere with libraries that still use those globals to detect that they are running in a browser context.

globalThis[Symbol.for('wc.defaultView')]

This proposal is to establish a well-known symbol (bikeshed on the name) that a shim will place browser globals. A shim might look like this:

shim.js

const { window, document, customElements, HTMLElement } = new DOMLibrary();

globalThis[Symbol.for('wc.defaultView')] = {
   window,
   document,
   customElements,
   HTMLElement
};

Then a component library will first look for this symbol to extract the globals it needs:

lip-element.js

const { HTMLElement, customElements, document } = globalThis[Symbol.for('wc.defaultView')] || globalThis;

Falling back means that in browser context where a shim hasn't ran it will extract these globals from the window object.

[matthewp]

@fgirardey talked about this issue in #17 and said:

I've read #18 but I don't see how it will help because the existing custom elements will need to opt-in and use those well-known symbols.

The idea here is for libraries to use the well-known symbol, not for component authors to do so. If libraries were to adopt this symbol that would mean that most components, which generally do not need the browser globals, would also work without global shims.

There will always be some low-level custom elements that do need browser globals, this issue isn't an attempt to provide full compatibility with every element that exists in the wild. Although if this became a community standard which library authors adopted, there's no reason why low-level elements couldn't also do so.