Skip to content

Declarative CSS Modules #11687

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 20 commits into
base: main
Choose a base branch
from
+186 −5
Open

Declarative CSS Modules #11687

Changes from 14 commits
Commits
Show all changes
20 commits
Select commit Hold shift + click to select a range
7f91f78
Initial commit
KurtCattiSchmidt Sep 23, 2025
b8c96ae
Adding missing shadowrootadoptedstylesheets and other small fixes
KurtCattiSchmidt Sep 24, 2025
4487b30
Addressing Hoch's feedback
KurtCattiSchmidt Sep 24, 2025
fde2e28
Fixing order and removing duplicate shadowrootadoptedstylesheets
KurtCattiSchmidt Sep 24, 2025
141c474
Fixing shadowrootadoptedstylesheets to definition to not include clon…
KurtCattiSchmidt Sep 25, 2025
c174820
Wrapping algorithm per new requirements
KurtCattiSchmidt Sep 26, 2025
477caa7
Fixing formatting
KurtCattiSchmidt Sep 26, 2025
582566e
Merge branch 'main' into css-modules-firstpr
KurtCattiSchmidt Sep 26, 2025
ccac8fe
Fixing <li> conformance error
KurtCattiSchmidt Sep 26, 2025
746cdad
Simplifying stylesheet adopting steps
KurtCattiSchmidt Sep 29, 2025
ca450c7
Making stylesheet adopting steps append instead of set
KurtCattiSchmidt Sep 29, 2025
d8cae13
Fixing typo
KurtCattiSchmidt Sep 29, 2025
11fcb56
Addressing Dan's feedback
KurtCattiSchmidt Oct 6, 2025
9e2f7ee
Minor style fixes
KurtCattiSchmidt Oct 6, 2025
b2c6025
Addressing Dan's second round of feedback
KurtCattiSchmidt Oct 8, 2025
adf1484
Updating external URL references to draft URL's
KurtCattiSchmidt Oct 9, 2025
05edbed
Adding component percent-encode set per Anne's feedback
KurtCattiSchmidt Oct 9, 2025
6cee43f
Separating JSON string step into a JSON object + stringify
KurtCattiSchmidt Oct 9, 2025
6a95872
Updating wording on the 'type' attribute being obselete
KurtCattiSchmidt Oct 10, 2025
188162a
Converting Import Map to Blob
KurtCattiSchmidt Oct 20, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
174 changes: 172 additions & 2 deletions source
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4131,6 +4131,13 @@ a.setAttribute('href', 'https://example.com/'); // change the content attribute
<li>The <dfn data-x="event-scrollend" data-x-href="https://drafts.csswg.org/cssom-view/#eventdef-document-scrollend"><code>scrollend</code></dfn> event</li>
<li><dfn data-x-href="https://drafts.csswg.org/cssom-view/#set-up-browsing-context-features">set up browsing context features</dfn></li>
<li>The <dfn data-x="mouseevent-clientx" data-x-href="https://drafts.csswg.org/cssom-view/#dom-mouseevent-clientx">clientX</dfn> and <dfn data-x="mouseevent-clienty" data-x-href="https://drafts.csswg.org/cssom-view/#dom-mouseevent-clienty">clientY</dfn> extension attributes of the <span>MouseEvent</span> interface</li>
<li>
<dfn data-x="concept-documentorshadowroot-extensions-mixin"
data-x-href="https://www.w3.org/TR/cssom-1/#extensions-to-the-document-or-shadow-root-interface">Extensions to the <code>DocumentOrShadowRoot</code> Interface Mixin</dfn>:
<ul class="brief">
<li><dfn data-x="adoptedstylesheets" data-x-href="https://www.w3.org/TR/cssom-1/#dom-documentorshadowroot-adoptedstylesheets">adoptedStyleSheets</dfn></li>
</ul>
</li>
</ul>

<p>The following features and terms are defined in <cite>CSS Syntax</cite>:
Expand Down Expand Up @@ -18513,6 +18520,7 @@ people expect to have work and what is necessary.
<dd><span>Global attributes</span></dd>
<dd><code data-x="attr-style-media">media</code></dd>
<dd><code data-x="attr-style-blocking">blocking</code></dd>
<dd><code data-x="attr-style-specifier">specifier</code></dd>
<dd>Also, the <code data-x="attr-style-title">title</code> attribute <span data-x="attr-style-title">has special semantics</span> on this element.</dd>
<dt><span
data-x="concept-element-accessibility-considerations">Accessibility considerations</span>:</dt>
Expand All @@ -18527,6 +18535,7 @@ interface <dfn interface>HTMLStyleElement</dfn> : <span>HTMLElement</span> {
attribute boolean <span data-x="dom-style-disabled">disabled</span>;
[<span>CEReactions</span>, <span data-x="xattr-Reflect">Reflect</span>] attribute DOMString <dfn attribute for="HTMLStyleElement" data-x="dom-style-media">media</dfn>;
[SameObject, PutForwards=<span data-x="dom-DOMTokenList-value">value</span>, <span data-x="xattr-Reflect">Reflect</span>] readonly attribute <span>DOMTokenList</span> <dfn attribute for="HTMLStyleElement" data-x="dom-style-blocking">blocking</dfn>;
[SameObject, PutForwards=value, Reflect] readonly attribute DOMString specifier;

// <a href="#HTMLStyleElement-partial">also has obsolete members</a>
};
Expand Down Expand Up @@ -18602,6 +18611,10 @@ console.log(style.disabled); // false</code></pre>
<p>The <dfn element-attr for="style"><code data-x="attr-style-blocking">blocking</code></dfn>
attribute is a <span>blocking attribute</span>.</p>

<p>The <dfn element-attr for="style"><code data-x="attr-style-specifier">specifier</code></dfn>
attribute defines an exportable <span
data-x="specifier-resolution-record-specifier">specifier</span>.</p>

<p id="title-on-style">The <dfn element-attr for="style"><code
data-x="attr-style-title">title</code></dfn> attribute on <code>style</code> elements defines
<span data-x="CSS style sheet set">CSS style sheet sets</span>. If the <code>style</code> element
Expand Down Expand Up @@ -18831,7 +18844,76 @@ console.log(style.disabled); // false</code></pre>

</div>

<p>The user agent must run the <span>create a declarative CSS module script</span> algorithm when
all of the following conditions are true:</p>

<ul>
<li><p>The element is popped off the <span>stack of open elements</span> of an <span>HTML
parser</span> or <span>XML parser</span>.</p></li>

<li><p>The element is not on the <span>stack of open elements</span> of an <span>HTML
parser</span> or <span>XML parser</span>, and it <span>becomes connected</span>.</p></li>
</ul>

<div algorithm>
<p>The <dfn export>create a declarative CSS module script</dfn> algorithm is as follows:</p>

<ol>
<li><p>Let <var>element</var> be the <code>style</code> element.</p></li>

<li><p>If <var>element</var> is not <span>connected</span>, then return.</p></li>
Copy link
Contributor

Choose a reason for hiding this comment

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

I guess this is also the point where we'd also check a new equivalent of the already started flag to ensure a given <style type=module> only ever gets processed once?

Copy link
Author

Choose a reason for hiding this comment

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

Yeah I'll have to think about this a little more. I will likely bring this up soon with the WHATWG.

<!-- See:
https://software.hixie.ch/utilities/js/live-dom-viewer/?saved=2740
https://github.com/w3c/csswg-drafts/issues/3096 -->

<li><p>If <var>element</var>'s <code data-x="attr-style-type">type</code> attribute is not present
or its value is not an <span>ASCII case-insensitive</span> match for
"<code data-x="">module</code>", then return.</p></li>

<li><p>If <var>element</var>'s <code data-x="attr-style-specifier">specifier</code> attribute
is not present or its value is an empty string, then return.</p></li>

<li><p>If the <span>Should element's inline behavior be blocked by Content Security
Policy?</span> algorithm returns "<code data-x="">Blocked</code>" when executed upon the
<code>style</code> element, "<code data-x="">style</code>", and the <code>style</code>
element's <span>child text content</span>, then return. <ref>CSP</ref></p></li>

<li><p>Let <var>styleDataURI</var> be the string "<code data-x="">data:text/css,</code>"
appended with the result of running <span data-x="UTF-8 percent-encode">UTF-8 percent-encode</span>
on the <span>child text content</span> of the <code>style</code> element.</p></li>

<li><p>Create a JSON string <var>jsonString</var> with a single key of "<code data-x="">imports</code>"
whose value is a single JSON string containing a <span>module specifier map</span> with a key consisting
of the value of the <span data-x="attr-style-specifier">specifier attribute</span> and a value of
<var>styleDataURI</var>.</p></li>

<li><p><span>Create an import map parse result</span> with <var>input</var> as <var>jsonString</var>
Copy link
Contributor

Choose a reason for hiding this comment

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

Create an import map parse result can throw -- do we need to handle any of those cases? The one I particularly had in mind to watch for is does it throw when a given specifier is invalid? If not, do we need to handle an invalid specifier some other way?

Copy link
Author

Choose a reason for hiding this comment

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

Good question. For now I added a step to look at the importMapParseResult's error to rethrow and to continue if that happens. In practice, we probably want to log something in the console, but this might be enough for the spec.

and <var>baseURL</var> as the <span>document base URL</span>.</p></li>

<li><p><span>Register an import map</span> using <var>element</var>'s <span>relevant global
object</span> and the resulting <span>import map parse result</span> from the prior step.</p></li>
</ol>
</div>

<div class="example">

<p>For example, a <code>style</code> element defined as follows:</p>

<pre><code class="html">
&lt;style type="module" specifier="foo">body { background: navy; color: yellow; }&lt;/style>
</code></pre>

<p>Is equivalent to the following <span>import map</span> definition:</p>

<pre><code class="html" data-x="">
&lt;script type="importmap">
{
"imports": {
"foo": "data:text/css,body%20%7B%20background%3A%20navy%3B%20color%3A%20yellow%3B%20%7D"
}
}
&lt;/script></code></pre>
</div>

<div w-nodev>

Expand Down Expand Up @@ -67818,6 +67900,7 @@ not-slash = %x0000-002E / %x0030-10FFFF
<dd><code data-x="attr-template-shadowrootclonable">shadowrootclonable</code></dd>
<dd><code data-x="attr-template-shadowrootserializable">shadowrootserializable</code></dd>
<dd><code data-x="attr-template-shadowrootcustomelementregistry">shadowrootcustomelementregistry</code></dd>
<dd><code data-x="attr-template-shadowrootadoptedstylesheets">shadowrootadoptedstylesheets</code></dd>
<dt><span
data-x="concept-element-accessibility-considerations">Accessibility considerations</span>:</dt>
<dd><a href="https://w3c.github.io/html-aria/#el-template">For authors</a>.</dd>
Expand All @@ -67834,6 +67917,7 @@ interface <dfn interface>HTMLTemplateElement</dfn> : <span>HTMLElement</span> {
[<span>CEReactions</span>, <span data-x="xattr-Reflect">Reflect</span>] attribute boolean <dfn attribute for="HTMLTemplateElement" data-x="dom-template-shadowrootclonable">shadowRootClonable</dfn>;
[<span>CEReactions</span>, <span data-x="xattr-Reflect">Reflect</span>] attribute boolean <dfn attribute for="HTMLTemplateElement" data-x="dom-template-shadowRootSerializable">shadowRootSerializable</dfn>;
[<span>CEReactions</span>, <span data-x="xattr-Reflect">Reflect</span>] attribute DOMString <dfn attribute for="HTMLTemplateElement" data-x="dom-template-shadowRootCustomElementRegistry">shadowRootCustomElementRegistry</dfn>;
[<span>CEReactions</span>, <span data-x="xattr-Reflect">Reflect</span>] attribute DOMString <dfn attribute for="HTMLTemplateElement" data-x="dom-template-shadowrootadoptedstylesheets">shadowRootAdoptedStyleSheets</dfn>;
};</code></pre>
</dd>
<dd w-dev>Uses <code>HTMLTemplateElement</code>.</dd>
Expand Down Expand Up @@ -67886,6 +67970,11 @@ interface <dfn interface>HTMLTemplateElement</dfn> : <span>HTMLElement</span> {
data-x="attr-template-shadowrootcustomelementregistry">shadowrootcustomelementregistry</code></dfn>
content attribute is a <span>boolean attribute</span>.</p>

<p>The <dfn element-attr for="template"><code
data-x="attr-template-shadowrootadoptedstylesheets">shadowrootadoptedstylesheets</code></dfn> content
contributes to the <span data-x="concept-DocumentFragment-host">host's</span>
<span>adoptedStyleSheets</span>.</p>

<p>The <span>template contents</span> of a <code>template</code> element <a
href="#template-syntax">are not children of the element itself</a>.</p>

Expand Down Expand Up @@ -68108,7 +68197,71 @@ interface <dfn interface>HTMLTemplateElement</dfn> : <span>HTMLElement</span> {

</div>

<hr>

<div algorithm>
<p>The <dfn>stylesheet adopting steps</dfn> for <code>template</code> elements are:</p>

<ol>
<li><p>If the value of
<span data-x="attr-template-shadowrootadoptedstylesheets">shadowrootadoptedstylesheets</span> is
empty, then return.</p></li>
<li><p>Let <var>adoptedStyleSheets</var> be an empty array.</p></li>

<li><p>For each <span>unordered set of unique space-separated tokens</span> <var>specifier</var> in
<span data-x="attr-template-shadowrootadoptedstylesheets">shadowrootadoptedstylesheets</span>:</p>
<ol>
<li><p>Let <var>url</var> be the result of <span data-x="resolve a module specifier">resolving
a module specifier</span> given <var>moduleScript</var> and <var>specifier</var>.</p> If
any errors occur, then <span>continue</span>.</li>
<li><p>Let <var>settingsObject</var> be the <span>current settings object</span>.</li>
<li><p>Let <var>moduleType</var> be "<code data-x="">css</code>".</p></li>
<li><p>Let <var>moduleMap</var> be <var>settingsObject</var>'s <span
data-x="concept-settings-object-module-map">module map</span>.</p></li>
<li><p>Let <var>moduleScript</var> be
<var>moduleMap</var>[(<var>url</var>, <var>moduleType</var>)].</p></li>
<li><p>If <var>moduleScript</var> is null, then <span>continue</span>.</p></li>
<li><p>Extract the <code>CSSStyleSheet</code> from <var>moduleScript</var>'s
<span data-x="concept-script-record">record</span> and append it to
<var>adoptedStyleSheets</var>. If any error occurs, then <span>continue</span>.</p></li>
</ol>
</li>
<li><p><span data-x="list extend">Extend</span> <span>adoptedStyleSheets</span> to the
<span data-x="concept-DocumentFragment-host">host</span>'s <var>adoptedStyleSheets</var>.</p></li>
</ol>
</div>

<div class="example">

<p>This example demonstrates two equivalent methods to import CSS module scripts, the
first using the JavaScript <code data-x="">import</code> method and the second using the
<span data-x="attr-template-shadowrootadoptedstylesheets">shadowrootadoptedstylesheets</span>
attribute.</p>

<pre><code class="html">
&lt;script type="importmap">
{
"imports": {
"foo": "data:text/css,div {color:blue}"
}
}
&lt;/script>
&lt;div id="host">
&lt;template shadowrootmode="open">
&lt;script type="module">
import styles from "foo" with { type: "css"};
document.getElementById("host").shadowRoot.adoptedStyleSheets = [styles];
&lt;/script>
&lt;div>test&lt;/div>
&lt;/template>
&lt;/div>
&lt;div id="host_shadowrootadoptedstylesheets_attribute">
&lt;template shadowrootmode="open" shadowrootadoptedstylesheets="foo">
&lt;div>test&lt;/div>
&lt;/template>
&lt;/div></code></pre>

</div>

<div w-nodev>

Expand Down Expand Up @@ -140229,6 +140382,10 @@ document.body.appendChild(text);
data-x="attr-template-shadowrootcustomelementregistry">shadowrootcustomelementregistry</code>
attribute, then set <var>shadow</var>'s <span>keep custom element registry null</span> to
true.</p></li>

<li><p>If <var>templateStartTag</var> has a <code
data-x="attr-template-shadowrootadoptedstylesheets">shadowrootadoptedstylesheets</code>
attribute, then perform <span>stylesheet adopting steps</span> on <var>template</var>.</p></li>
</ol>
</li>
</ol>
Expand Down Expand Up @@ -151699,7 +151856,8 @@ interface <dfn interface>External</dfn> {
<td>text*</td>
<td><span data-x="global attributes">globals</span>;
<code data-x="attr-style-media">media</code>;
<code data-x="attr-style-blocking">blocking</code></td>
<code data-x="attr-style-blocking">blocking</code>;
<code data-x="attr-style-specifier">specifier</code></td>
<td><code>HTMLStyleElement</code></td>
</tr>

Expand Down Expand Up @@ -151809,7 +151967,8 @@ interface <dfn interface>External</dfn> {
<code data-x="attr-template-shadowrootdelegatesfocus">shadowrootdelegatesfocus</code>;
<code data-x="attr-template-shadowrootclonable">shadowrootclonable</code>;
<code data-x="attr-template-shadowrootserializable">shadowrootserializable</code>;
<code data-x="attr-template-shadowrootcustomelementregistry">shadowrootcustomelementregistry</code></td>
<code data-x="attr-template-shadowrootcustomelementregistry">shadowrootcustomelementregistry</code>;
<code data-x="attr-template-shadowrootadoptedstylesheets">shadowrootadoptedstylesheets</code></td>
<td><code>HTMLTemplateElement</code></td>
</tr>

Expand Down Expand Up @@ -153322,6 +153481,11 @@ interface <dfn interface>External</dfn> {
<td> <code data-x="attr-option-selected">option</code>
<td> Whether the option is selected by default
<td> <span>Boolean attribute</span>
<tr>
<th> <code data-x="">shadowrootadoptedstylesheets</code>
<td> <code data-x="attr-template-shadowrootadoptedstylesheets">template</code>
<td> Sets <span>adoptedStyleSheets</span> on a declarative shadow root
<td> <a href="#attribute-text">Text</a>
<tr>
<th> <code data-x="">shadowrootclonable</code>
<td> <code data-x="attr-template-shadowrootclonable">template</code>
Expand Down Expand Up @@ -153391,6 +153555,11 @@ interface <dfn interface>External</dfn> {
<td> "<code data-x="attr-spellcheck-true">true</code>";
"<code data-x="attr-spellcheck-false">false</code>";
the empty string
<tr>
<th> <code data-x="">specifier</code>
<td> <code data-x="attr-style-specifier">style</code>
<td> A <span data-x="specifier-resolution-record-specifier">specifier</span> value used in a <span>module specifier map</span>
<td> <a href="#attribute-text">Text</a>
<tr>
<th> <code data-x="">src</code>
<td> <code data-x="attr-media-src">audio</code>;
Expand Down Expand Up @@ -156406,6 +156575,7 @@ INSERT INTERFACES HERE
Kristof Zelechovski,
Krzysztof Maczy&#x0144;ski,
&#x9ed2;&#x6fa4;&#x525b;&#x5fd7; (Kurosawa Takeshi),
Kurt Catti-Schmidt,
Kyle Barnhart,
Kyle Hofmann<!-- Ozob -->,
Kyle Huey,
Expand Down