Add proposal for @sheet to enable multiple stylesheets per file #931

aluhrs13 · 2025-01-09T22:23:51Z

As part of looking at Declarative CSS Modules, TAG has suggested that we should investigate @sheet as a possible direction. This explainer summarizes and builds on the CSSWG discussion about this idea to consolidate it into a single location.

AtSheet/explainer.md

dandclark · 2025-01-09T22:51:05Z

AtSheet/explainer.md

+  [SameObject] readonly attribute StyleSheetList nestedStyleSheets;
+};
+```
+*Open issue: The name `nestedStyleSheets` is up for discussion*


Maybe namedStyleSheets?

dandclark · 2025-01-09T22:53:40Z

AtSheet/explainer.md

+
+## Open Issues
+
+1. Whether rules are applied automatically for `@sheet` definitions, or whether they need to be imported to apply. The CSS Working Group did not have a consensus.


I expect that we'll want them not to apply, to satisfy the scenario where a page wants to define some styles at the top level that will be shared among components used on the page but not used by the base page.

dandclark · 2025-01-09T22:54:17Z

AtSheet/explainer.md

+
+1. Whether rules are applied automatically for `@sheet` definitions, or whether they need to be imported to apply. The CSS Working Group did not have a consensus.
+2. Fragment-only identifiers (without a URL) should allow inline `@sheet` references on the same document to be included globally (even within shadow roots). This wasn't brought up in the CSSWG discussions at all, but is important for DSD without requiring an external file (to avoid FOUC).
+3. Behavior of `@import` - should this be possible within `@sheet` at all, should it be allowed if it's the first/only statement, or should it be blocked? There was discussion of this in the CSSWG, but no conclusion was reached.


Is there any context we can link to for this one?

"This one" being item 3. Behavior of @import.

dandclark · 2025-01-09T22:55:50Z

AtSheet/explainer.md

+Much of this explainer is consolidating and iterating on a CSSWG discussion around [Justin Fagnani](https://github.com/justinfagnani)'s proposal for multiple stylesheets in a single file [here](https://github.com/w3c/csswg-drafts/issues/5629).
+
+## Participate
+- [Issue tracker](https://github.com/w3c/csswg-drafts/issues/5629)


Seems like these links might be reversed.

dandclark · 2025-01-09T23:50:36Z

AtSheet/explainer.md

+
+#### Performance
+
+This will be a performance-neutral feature, and use of it may allow for developers to reduce the number of network requests. We should ensure that multiple imports of different sheets from the same file produce a single network request. 


We can make the argument that eliminating stylesheet duplication is a performance opportunity. Having a bunch of duplicated <style> tags has a cost in terms of both memory and parsing time. This is an old doc, and very large numbers of components are used in order to highlight the effect, but the differences are definitely observable: https://dandclark.github.io/json-css-module-notes/#css-module-performancememory-examples
Or a more recent analysis: https://github.com/nolanlawson/declarative-shadow-dom-style-vs-link-benchmark
Both of those are looking at it from the perspective of CSS modules, but I think the performance argument to be made for @sheet is similar, with the added bonus that it doesn't require JS.

alisonmaher · 2025-01-09T23:18:41Z

AtSheet/explainer.md

+
+## Participate
+- [Issue tracker](https://github.com/w3c/csswg-drafts/issues/5629)
+- [Discussion forum](https://github.com/MicrosoftEdge/MSEdgeExplainers/labels/AtSheet)


I think these two links might be backwards (i.e. the first is linked to the discussion forum, and the second one is actually linked to the Issue tracker)

alisonmaher · 2025-01-09T23:22:30Z

AtSheet/explainer.md

+* Current version: this document
+
+## Introduction
+When developing web components, web authors often encounter challenges with distributing global styles into shadow roots and sharing styles across different shadow roots. Declarative shadow DOM (DSD) enables creation of shadow DOM without JS, but adding styles to DSD requires the developer to either use JS to put a shared stylesheet into `adoptedStyleSheets`, or to duplicate the styles in a `<style>` element for each component instance.


I might split the second sentence up into two. i.e. "Declarative shadow DOM (DSD) enables creation of shadow DOM without JS. However, ..."

alisonmaher · 2025-01-09T23:25:52Z

AtSheet/explainer.md

+
+Additionally, bundling of stylesheets is difficult for developers who are distributing web components. They either need to ship many small stylesheets, or use workarounds like `@import url("data...")` which are suboptimal for performance and don't interact well with other patterns.
+
+We propose an enhancement to allow declaration of new stylesheets via an `@sheet` CSS block, and using existing mechanisims such as `@import` and `<link>` to apply those shared styles to DSDs without the use of Javascript.


"allow declaration" -> "allow the declaration"

"block, and using existing" -> "block and the use of existing"

alisonmaher · 2025-01-09T23:26:50Z

AtSheet/explainer.md

+
+Additionally, bundling of stylesheets is difficult for developers who are distributing web components. They either need to ship many small stylesheets, or use workarounds like `@import url("data...")` which are suboptimal for performance and don't interact well with other patterns.
+
+We propose an enhancement to allow declaration of new stylesheets via an `@sheet` CSS block, and using existing mechanisims such as `@import` and `<link>` to apply those shared styles to DSDs without the use of Javascript.


minor nit, but I see we use simply "JS" elsewhere. Should we do the same here (instead of the full "Javascript")?

alisonmaher · 2025-01-09T23:38:57Z

AtSheet/explainer.md

+  div {
+    color: red;
+  }
+}


nit: inconsistent spacing between the blocks

alisonmaher · 2025-01-10T00:04:12Z

AtSheet/explainer.md

+  readonly attribute DOMString? name;
+};
+```
+*Open issue: Should this overload the existing `title` attribute instead?*


Should we leave all open issues for the open issues section?

alisonmaher · 2025-01-10T00:05:36Z

AtSheet/explainer.md

+```
+*Open issue: The name `nestedStyleSheets` is up for discussion*
+
+## Considered alternatives


Should we include all those mentioned in https://github.com/MicrosoftEdge/MSEdgeExplainers/blob/main/ShadowDOM/explainer.md#alternate-proposals (minus @sheet as well?)

alisonmaher · 2025-01-10T00:06:43Z

AtSheet/explainer.md

+## Open Issues
+
+1. Whether rules are applied automatically for `@sheet` definitions, or whether they need to be imported to apply. The CSS Working Group did not have a consensus.
+2. Fragment-only identifiers (without a URL) should allow inline `@sheet` references on the same document to be included globally (even within shadow roots). This wasn't brought up in the CSSWG discussions at all, but is important for DSD without requiring an external file (to avoid FOUC).


Is this an open issue since this is what we are proposing?

alisonmaher · 2025-01-10T00:07:45Z

AtSheet/explainer.md

+
+1. Whether rules are applied automatically for `@sheet` definitions, or whether they need to be imported to apply. The CSS Working Group did not have a consensus.
+2. Fragment-only identifiers (without a URL) should allow inline `@sheet` references on the same document to be included globally (even within shadow roots). This wasn't brought up in the CSSWG discussions at all, but is important for DSD without requiring an external file (to avoid FOUC).
+3. Behavior of `@import` - should this be possible within `@sheet` at all, should it be allowed if it's the first/only statement, or should it be blocked? There was discussion of this in the CSSWG, but no conclusion was reached.


I might reword this to be clearer what we mean by "this"

alisonmaher · 2025-01-10T00:09:14Z

AtSheet/explainer.md

+1. Whether rules are applied automatically for `@sheet` definitions, or whether they need to be imported to apply. The CSS Working Group did not have a consensus.
+2. Fragment-only identifiers (without a URL) should allow inline `@sheet` references on the same document to be included globally (even within shadow roots). This wasn't brought up in the CSSWG discussions at all, but is important for DSD without requiring an external file (to avoid FOUC).
+3. Behavior of `@import` - should this be possible within `@sheet` at all, should it be allowed if it's the first/only statement, or should it be blocked? There was discussion of this in the CSSWG, but no conclusion was reached.
+4. What happens with multiple `@sheet` definitions with the same identifier? First-definition wins, or do they get merged like `@layer`? Again, this was brought up in the CSSWG but not resolved. Note that it's possible to have a "Flash of other-styled content" if it's last-defintion-wins, as the first definition may apply, then a later definition may override it.


Why would this lead to flash of other styled content? Since we apply the full cascade before painting, could that actually happen?

i.e. I would presume if a DSD uses the same name for the sheet, we would want the last to win instead of the first (unless they combine)

alisonmaher · 2025-01-10T00:12:37Z

AtSheet/explainer.md

+```html
+<template shadowrootmode="open">
+  <style>
+  @sheet foo {


Missing indentation

Co-authored-by: Dan Clark <daniec@microsoft.com>

aluhrs13 and others added 12 commits December 6, 2024 12:29

First start of atSheet explainer

15aee25

First round of additions

6c1e94f

Fixing code blocks

b5e5d00

Adding more open issues and CSSOM interfaces

a311c6e

Remove WIP @sheet notes

13c1fa3

Remove boilerplate

5000e0a

Add shadow -> light open issue.

ffb3ae2

Minor acknowledgements and wording tweaks.

e3f8be4

Make examples consistent

2c691f9

Missed an example

eeec132

Missed one more...

0f7311d

Add to readme

977a53e

dandclark reviewed Jan 9, 2025

View reviewed changes

AtSheet/explainer.md Outdated Show resolved Hide resolved

Fix old example

d65d1b9

dandclark reviewed Jan 9, 2025

View reviewed changes

alisonmaher reviewed Jan 10, 2025

View reviewed changes

AtSheet/explainer.md

```html

<template shadowrootmode="open">

<style>

@sheet foo {

Copy link

alisonmaher Jan 10, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Missing indentation

Update AtSheet/explainer.md

6a3bdf6

Co-authored-by: Dan Clark <daniec@microsoft.com>

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add proposal for @sheet to enable multiple stylesheets per file #931

Add proposal for @sheet to enable multiple stylesheets per file #931

aluhrs13 commented Jan 9, 2025

dandclark Jan 9, 2025

dandclark Jan 9, 2025

dandclark Jan 9, 2025

dandclark Jan 9, 2025

dandclark Jan 9, 2025

dandclark Jan 9, 2025

alisonmaher Jan 9, 2025

alisonmaher Jan 9, 2025

alisonmaher Jan 9, 2025

alisonmaher Jan 9, 2025

alisonmaher Jan 9, 2025

alisonmaher Jan 10, 2025

alisonmaher Jan 10, 2025

alisonmaher Jan 10, 2025

alisonmaher Jan 10, 2025

alisonmaher Jan 10, 2025

alisonmaher Jan 10, 2025

alisonmaher Jan 10, 2025


		## Open Issues

		1. Whether rules are applied automatically for `@sheet` definitions, or whether they need to be imported to apply. The CSS Working Group did not have a consensus.


		#### Performance

		This will be a performance-neutral feature, and use of it may allow for developers to reduce the number of network requests. We should ensure that multiple imports of different sheets from the same file produce a single network request.


		Additionally, bundling of stylesheets is difficult for developers who are distributing web components. They either need to ship many small stylesheets, or use workarounds like `@import url("data...")` which are suboptimal for performance and don't interact well with other patterns.

		We propose an enhancement to allow declaration of new stylesheets via an `@sheet` CSS block, and using existing mechanisims such as `@import` and `<link>` to apply those shared styles to DSDs without the use of Javascript.

Add proposal for @sheet to enable multiple stylesheets per file #931

Are you sure you want to change the base?

Add proposal for @sheet to enable multiple stylesheets per file #931

Conversation

aluhrs13 commented Jan 9, 2025

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment