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

(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 https://github.com/11ty/webc/issues/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

• https://github.com/11ty/webc/issues/5 - subcomponent style leakage
• https://github.com/11ty/webc/issues/206 - which elements are tagged?
• https://github.com/11ty/webc/issues/213 - per-class vs per-instance
• https://github.com/11ty/webc/issues/198 - :host must start the selector
• https://github.com/11ty/webc/issues/166 - descendant chain prefixing breaks nested CSS
• https://github.com/11ty/eleventy-plugin-webc/issues/98 - same
• https://github.com/11ty/webc/issues/154 - same?
• https://github.com/11ty/webc/issues/124 - more complex selector issues

Start with the webc:scoped documentation and the linked issues about tagging, selector handling, scoping, and nested CSS. Clarify the intended behavior for :host, :host(...), :host-context(...), default scoping, and subcomponents with maintainers before editing. Done means the behavior is decided and the documentation accurately describes the supported selectors and their differences from Web Components.