[open-stylable] Collection of user stories

[michaelwarren1106]

Let’s let this issue serve as the single place to collect user stories around the “open-stylable shadow roots” proposal.

#909

Submit user stories as comments and I will do my best to collate theme here in this top comment for easy viewing/referral.

User Stories

• As a component author, I want to build unstyled components that only manage behavior. I want to give my consumers full control and achieve maximum compatibility with their existing styling solutions. I am ok with the tradeoff that DOM changes can break consumer's styles
• "As a website author, I want to use shadow DOM for my own components (that I author and consume myself). I want to use my existing CSS system, including any global resets, utility classes, and hand-rolled scoped classes. Crucially, I want these styles to be usable in DSD without causing FOUC."
• As a page author/WC user, I would like to have a way to say, as @chriscoyier put it, "I know what I'm doing" and go wild overwriting anything I want (and not be at the mercy of the WC author).
• As a performance minded web app developer, I would like a way to benefit from the styles encapsulation of the shadow DOM to avoid style recalculation's performance hit as described by @captainbrosset's at CSS Day 2023 (slides).
• As an application developer developing apps for company-internal use, I want to re-use web components that represent common logic across various projects regardless of what tech stack they individually use. When frameworks are used that require extra classes, I want to extend the components to use templates and have the framework classes available automatically inside the component.
• As a web app I’ve already written the styles for various user interface elements (e.g. buttons, form controls). Now I have a larger composition that I need to repeat throughout the app which includes a number of these elements (e.g. a modal dialog that includes a few buttons) and I would like to use the shadow DOM for this. The component doesn’t need the composition slots provide. Parts require me to rewrite my CSS. I would love to write the styles for these elements once, then allow the web components in my app use them, ideally without requiring my entire stylesheet also be applied to the shadow root.

[mayank99]

Pasting my comment:

• "As a component author, I want to build unstyled components that only manage behavior. I want to give my consumers full control and achieve maximum compatibility with their existing styling solutions. I am ok with the tradeoff that DOM changes can break consumer's styles."
• "As a website author, I want to use shadow DOM for my own components (that I author and consume myself). I want to use my existing CSS system, including any global resets, utility classes, and hand-rolled scoped classes. Crucially, I want these styles to be usable in DSD without causing FOUC."

[robglidden]

From shadow layers proposal (noting they may be a bit over-broad particularly as to coordination scenarios):

Use Cases Addressed

• Include all document CSS as a low priority layer inside a shadow tree. This is the heart of a solution to the original issue as opened.
• Support both declarative and imperative use. Declarative shadow trees are fully supported from the onset, as well as imperative use cases.
• Include selected document CSS as a layer inside a shadow tree. Selected named outer layers can be brought into a shadow tree by either a shadow tree designer or shadow tree user.
• Enable layer reprioritization. Inner and outer context layers can be intermixed and reprioritized.
• Enable shadow tree designers to bring in document CSS without intervention by a shadow tree user. If desired, a shadow tree designer can bring in all of or just selected layers of the document outer context CSS, without intervention of the shadow tree user.
• Enable coordination between shadow tree designers and shadow tree users. Either can bring in and repriortize outer layers.
• Enable shadow tree user to add and repriortize layers originally provided by shadow tree designer. A user can bring in any chosen outer layer, not just those pre-defined by a designer.
• Enable a shadow tree designer to "advertise" to shadow tree users the CSS priorities of a shadow tree's inner context. A designer can expose, publish, or document the original layer order of a shadow tree, so that a user can knowingly adjust it or add to it.
• Polyfillable. As hopefully implied by this proof of concept implementations.

[michaelwarren1106]

From shadow layers proposal (noting they may be a bit over-broad particularly as to coordination scenarios):

Use Cases Addressed

• Include all document CSS as a low priority layer inside a shadow tree. This is the heart of a solution to the original issue as opened.
• Support both declarative and imperative use. Declarative shadow trees are fully supported from the onset, as well as imperative use cases.
• Include selected document CSS as a layer inside a shadow tree. Selected named outer layers can be brought into a shadow tree by either a shadow tree designer or shadow tree user.
• Enable layer reprioritization. Inner and outer context layers can be intermixed and reprioritized.
• Enable shadow tree designers to bring in document CSS without intervention by a shadow tree user. If desired, a shadow tree designer can bring in all of or just selected layers of the document outer context CSS, without intervention of the shadow tree user.
• Enable coordination between shadow tree designers and shadow tree users. Either can bring in and repriortize outer layers.
• Enable shadow tree user to add and repriortize layers originally provided by shadow tree designer. A user can bring in any chosen outer layer, not just those pre-defined by a designer.
• Enable a shadow tree designer to "advertise" to shadow tree users the CSS priorities of a shadow tree's inner context. A designer can expose, publish, or document the original layer order of a shadow tree, so that a user can knowingly adjust it or add to it.
• Polyfillable. As hopefully implied by this proof of concept implementations.

these are great! would you mind taking a swing at framing these use cases in terms of user stories? i definitely agree that any solution must have some/or all of these baked in, but the current phrasing makes them sound more like features of a solution and less like stories that describe particular, specific user needs/wants.

[robglidden]

Filtering as a potentially key requirement:

To me, the key open question that needs to be answered is whether selective adoption of document-level stylesheets is necessary or not. That is, should a component or users of the component need to be able to filter (i.e. selectively apply) which stylesheet or style rules apply to its shadow tree.

answering yes, filtering needed, with related essential requirements:

Use cases are intertwined.

Whether simple (I just want my page resets to work in my shadow tree) or most painful (component and context are controlled by different entities) or in between, use cases trace to the same shadow encapsulation, and loosening encapsulation will likely impact many if not all in some way.

Declarative shadow DOM is required.

To me, declarative shadow DOM is required from the onset not just because it is a new thing so logically it must be supported too, but because shadow trees are just HTML and they are what are doing the encapsulating to loosen. And they are a part of the solution.

So Javascript-only solutions are basically out. And polyfillability though not a strict requirement is in this case something of an acid test for completeness.

But also declarative shadow trees already by design address opt-in for imperatively-created web components.

Context-aware opt-in protection is needed.

I don't think an opt-in flag or mode that just brings in all page styles would work as expected in all cases. Some shadow styles could unexpectedly lose. Or get pulled back into a specificity race that could feel like shadow trees just gave up.

Prioritization is required.

Or maybe just unavoidable, since unlayered styles are of necessity assigned a layer priority. And a limited form of priority for shadow trees already exists in the context step, so any brought-in styles would pass through that step too.

[rniwa]

Declarative shadow DOM is required.

To me, declarative shadow DOM is required from the onset not just because it is a new thing so logically it must be supported too, but because shadow trees are just HTML and they are what are doing the encapsulating to loosen. And they are a part of the solution.

So Javascript-only solutions are basically out. And polyfillability though not a strict requirement is in this case something of an acid test for completeness.

What are concrete user scenarios that necessitates declarative shadow DOM support? i.e. what exactly is one building to encounter this need?

Context-aware opt-in protection is needed.

I don't think an opt-in flag or mode that just brings in all page styles would work as expected in all cases. Some shadow styles could unexpectedly lose. Or get pulled back into a specificity race that could feel like shadow trees just gave up.

Again, what are concrete user scenarios that necessitates context-aware opt-in?

Prioritization is required.

Or maybe just unavoidable, since unlayered styles are of necessity assigned a layer priority. And a limited form of priority for shadow trees already exists in the context step, so any brought-in styles would pass through that step too.

Again, what are concrete user scenarios that necessitates prioritization of CSS rules?

[michaelwarren1106]

Filtering as a potentially key requirement:

To me, the key open question that needs to be answered is whether selective adoption of document-level stylesheets is necessary or not. That is, should a component or users of the component need to be able to filter (i.e. selectively apply) which stylesheet or style rules apply to its shadow tree.

answering yes, filtering needed, with related essential requirements:

Use cases are intertwined.

Whether simple (I just want my page resets to work in my shadow tree) or most painful (component and context are controlled by different entities) or in between, use cases trace to the same shadow encapsulation, and loosening encapsulation will likely impact many if not all in some way.

Declarative shadow DOM is required.

To me, declarative shadow DOM is required from the onset not just because it is a new thing so logically it must be supported too, but because shadow trees are just HTML and they are what are doing the encapsulating to loosen. And they are a part of the solution.

So Javascript-only solutions are basically out. And polyfillability though not a strict requirement is in this case something of an acid test for completeness.

But also declarative shadow trees already by design address opt-in for imperatively-created web components.

Context-aware opt-in protection is needed.

I don't think an opt-in flag or mode that just brings in all page styles would work as expected in all cases. Some shadow styles could unexpectedly lose. Or get pulled back into a specificity race that could feel like shadow trees just gave up.

Prioritization is required.

Or maybe just unavoidable, since unlayered styles are of necessity assigned a layer priority. And a limited form of priority for shadow trees already exists in the context step, so any brought-in styles would pass through that step too.

i understand all of these as possible solution requirements. in order to frame them, i would still love to see each of these connected to a direct user need in terms of the typical user story framing.

how do these items get put into a sentence like:

“As a {person} i would like {feature/requirement} so that I can {do a specific thing}.

i think this exercise and framing will help tie stuff like “prioritization is required” to a direct reason WHY prioritization is required in terms of a person and their ability/non-ability to build things.

[ziadkh0]

Two non-mutually exclusive use cases concerning styling shadow DOM elements from outside the component that I wish can be supported (but not sure if they can be part of this initiative/proposal):

• As a page author/WC user, I would like to have a way to say, as @chriscoyier put it, "I know what I'm doing" and go wild overwriting anything I want (and not be at the mercy of the WC author).
• As a performance minded web app developer, I would like a way to benefit from the styles encapsulation of the shadow DOM to avoid style recalculation's performance hit as described by @captainbrosset's at CSS Day 2023 (slides).

EDIT: On second thought, they might be mutually exclusive, not sure 🤔

[DarkWiiPlayer]

Here's an attempt at counting how many of these user stories imply a need for:

• A pull-based system whereby CEs autonomously adopt styles from the outside
• A push-based system whereby websites can force style rules into shadow trees
• Granularity in what is adopted that can be satisfied via layers (but doesn't have to be layers; see this comment)
• The ability for combinators in css selectors to reach across shadow-boundaries

User	pull	push	layers	combinators
@mayank99	2	0	1	0?
@zaygraveyard	0	1	0	0
@DarkWiiPlayer	2	0	2	1
@knowler	1	0	1	0
@robglidden	1	2	1	0
Total	6	3	5	1

I will attempt to update this list as more user-stories come in (as time allows). Feel free to suggest additional considerations to track.

[DarkWiiPlayer]

When developing web applications for company-internal use, I want to re-use web components that represent common logic across various projects regardless of what tech stack they individually use. When frameworks are used that require extra classes, I want to extend the components to use templates and have the framework classes available automatically inside the component.

[robglidden]

@michaelwarren1106, @rniwa:

It seems to be getting missed that modern browsers support "Declarative Shadow DOM".

The "user" in the above use cases and requirements is just the user of a shadow tree, particularly a declarative shadow tree.

To elaborate:

• Shadow trees are "just HTML" (a document fragment attached to a particular element, for which certain css rules apply).
• Shadow trees are not "Custom Elements" i.e elements upgraded by customElements.define() to have a Javascript class instance associated with them. This kind of "Custom Element" is often informally called a "web component" or a "Web Component".
• "Custom Elements" don't encapsulate anything. Shadow trees do the encapsulating.

Declarative shadow DOM already gives web component users a way to present a shadow tree (with user-written CSS styles in it) to the web component. And a way for the web component to accept, reject, or use those styles as it sees fit.

So user stories that boil down to something like "as a web component user I want the web component to consider using some styles I present to it in a shadow tree" is not a missing platform feature, it is a choice for web component authors to make.

What is missing is a way to bring page styles into shadow trees.

Without this common context, there seems to be a conflation loop.

Classifying as "push" vs "pull" vs "other" seem to suffer similarly.

[michaelwarren1106]

user stories that boil down to “as a user i need X so that Y” is precisely for the purpose of making sure we don’t conflate things and are crystal clear about what to ask implementers for and why.

if the user stories you are thinking of are more specific than “as a web component user” then that’s great! let’s capture those under a different persona. like “as a developer using shadow trees with declarative shadow dom, i need X so that Y”.

what i think implementers are asking for, and the purpose of my creating this issue is about finding all the Xs and the Ys.

we all have different opinions on the “what do people want” it’s the “so that Y”s that really matter. specifying what devs are unable to do today, or what things are difficult/cumbersome today is the entire reason to change things. calling some feature being “a missing platform feature” isn’t as powerful as describing specifically what that new feature will accomplish that matters.

in the other thread, and now starting in this one, there’s been a lot of “i think it should be this way” and not enough “if it is {this way} then {persona} can do {thing} way easier/simpler/faster/better etc etc“.

we need to get at the specifics of what folks are trying to do. enumerate those first. THEN work on solutions that solve those cases. as of yet we’ve been working backwards from opinions about things we think are needed and not working forward from actual outlined spelled out problems.

[DarkWiiPlayer]

@robglidden

It seems to be getting missed that modern browsers support "Declarative Shadow DOM".

Declarative Shadow DOM is an optimisation to avoid FOUC by pre-rendering the contents of a shadow DOM on the server or during deployment. It's not an entirely new way of doing shadow DOM, just an additional API to attach and initialise it. The problems with styling remain the exact same ones: Outside style-sheets don't affect the insides of the shadow DOM.

• Shadow trees are not "Custom Elements"

I think you're missing the forest for the trees here, no pun intended. Shadow DOM is primarily useful in combination with custom elements and <template>s to build web components. They can be attached to other elements, yes, but that is a very rare way of using them, so it makes sense for most of these user stories to focus on this main use-case.

If you have any user stories that showcase the use of shadow-dom with normal HTML elements, I'd be curious to see those to get another perspective on the spec, but if you don't actually post them here, then we can't read your mind.

So user stories that boil down to something like "as a web component user I want the web component to consider using some styles I present to it in a shadow tree" is not a missing platform feature, it is a choice for web component authors to make.

It is not per se a missing feature, as it can be done imperatively using Javascript, but it is a common enough case for a specific platform feature to be added to make it more ergonomic and resilient. Synchronising stylesheets between light- and shadow-dom is far from trivial with the APIs we currently have.

Classifying as "push" vs "pull" vs "other" seem to suffer similarly

I disagree. Classifying as "push" vs "pull" is very important because it is the distinction between whether the component author or the component user is the one who initiates the style adoption. The open-stylable proposal specifically addresses the former case, where a component author wants to opt in to some or all styles defined by the component user. It preserves encapsulation except where the author specifically chooses to expose APIs to let the user influence the process.

Separating user stories into which of the two they need is important to know whether a push-based mechanism is worth exploring further, either as a separate feature, or as a part of open-stylable, or a purely pull-based mechanism can cover most of the users' needs.

Again, if you think there's another, more important axis to consider, it'd be much easier if you could explain it with some actual user stories or at least specific use cases. I think this issue was created precisely because just listing requirements seems a bit arbitrary to us strangers on the internet, and user stories are a convenient way of bundling a requirement with the context to show why that requirement is useful.

[robglidden]

@michaelwarren1106:

No objection from me, user stories are valuable.

I am saying something different.

The primary use case #909 was opened for in 2020 is component library maintainers who want to move to web components while supporting stylesheets that they don't control. And there are important related use cases.

But now, years later, declarative shadow DOM directly addresses many of these related use cases.

In particular, declarative shadow DOM already provides a way for web component users to present user written styles to web components. In a way that answers the often-expressed need on behalf of web component authors to have opt-in say before accepting those styles into web components.

So I am saying it doesn't make sense to collect user stories for something that was already considered and implemented in web browsers. To me, the problem to solve is bringing page styles into shadow trees, not some other already solved problem.

So no, I am not saying or implying at all that I am thinking of (or being cagey about) user stories that are more specific than "as a web component user". That's backwards.

[robglidden]

@DarkWiiPlayer:

Declarative Shadow DOM is most powerful when used with "Custom Elements".

Declarative shadow trees were designed exactly to support the case of web component users presenting shadow trees to web component authors to consider using in a more declarative, ergonomic, resilient, and component-author-acceptable way than imperative Javascript.

To me that's the other, more important axis to consider.

[rniwa]

That's not really use cases / user stories. Use cases are specific scenarios in which specific piece of software may be used in a specific way, not some general statement about what kind of problem ought to be solved.