webc:scoped :host selector is very unlike actual Web Components :host selector (and badly documented!)

[egnor]

(I'm happy to submit PRs if the intended behavior and/or documentation can be clarified! Also please correct any misconceptions I have here!)

The documentation for webc:scoped is scant and only describes the :host selector with the phrase "if you use :host it will be replaced with that [scope hash] class selector". Even ignoring the standard Web Components meaning of :host, this is misleading and/or confusing in several ways...

• it never says which elements this new class is added to (see Scope hash is added to all nodes in page mode. #206)
• the term "prefix" is confusing, it's not a string prefix (.myclass -> .scopehash_myclass) but a descendant chain prefix?
• :host must be the FIRST part of any selector expression; p:host or .myclass:host are NOT handled
• :host(p) becomes .scopehash p, but :host(.myclass) becomes .scopehash.myclass, for some reason?
• and in fact the functional forms :host(...) and :host-context(...) are never described
• finally if no :host is found in a selector, the .scopehash selector is added by default, which is never explained

Worse, the use of :host implies a parallel with the Web Components :host pseudoclass, perhaps allowing migration between the approaches. However :host with webc:scoped and :host in Web Components are wildly different. If nothing else these differences should be clarified!

• Web Components :host is NOT a scope-limiting mechanism, it is an ANTI scoping mechanism. In Web Components, selectors in a component are limited to component elements by default; :host (and friends :host() and :host-content()) allow outer document elements to be "brought into the light" for selection purposes
• Similarly, in Web Components, subcomponent structure is invisible to selection from the outer level. However, with webc:scoped, the use of :host as a descendant prefix means that subcomponent structure is always included in selection, which is typically undesired
• Web Component scoping is per component instance, webc:scoped scoping is per component type (ish)

All considered, the documentation implies that webc:scoped and :host can be used as an easy-breezy "only select things in my component, just like Web Components" mechanism, and it sort of works that way but not consistently, especially if you care about isolation from subcomponents (e.g. using webc for a page-level container template) or want to use more complex selectors.

If I can get clarification on what's intended, then I can at least make a PR to clarify the documentation so people like me don't have to struggle quite as hard to figure out what's going on??

See also

• CSS: Support scoping inner elements of a webc file  #5 - subcomponent style leakage
• Scope hash is added to all nodes in page mode. #206 - which elements are tagged?
• Scoped CSS properties overridden when multiple instances of same component #213 - per-class vs per-instance
• Scoped CSS: Next sibling selector not working with :host #198 - :host must start the selector
• Style scoping prefixes nested CSS #166 - descendant chain prefixing breaks nested CSS
• Webc Scoped CSS Breaks CSS Nesting eleventy-plugin-webc#98 - same
• Style scoping bug when moving to v0.11.x #154 - same?
• Bug with webc:scoped and complex-ish CSS selector with :host #124 - more complex selector issues