[add] StyleSheet.setCascadeLayer to nest the generated CSS in a cascade layer

[YevheniiKotyrlo]

Problem

The CSS StyleSheet generates is unlayered, and an unlayered declaration takes precedence over every layered one, whatever its specificity. An app that orders its own CSS in cascade layers (Tailwind v4 puts its utilities in @layer utilities) can't override a style a View or Text sets, such as Text's font: '14px System', from a layer. Nor can it put the generated CSS in a layer: declaring the style sheet's element with one, <style id="react-native-stylesheet">@layer rnw{}</style>, makes hydration throw Cannot read properties of undefined (reading 'rules'), because it reads a rule before the first group as a member of a group that was never opened.

Solution

StyleSheet.setCascadeLayer(name) nests the generated CSS in the layer name: the rules already inserted move into it, every later rule goes into it, and getStyleElement() and getSheet() serialize the sheet in it, so a server-rendered sheet hydrates into the same layer. The app positions the layer among its own:

StyleSheet.setCascadeLayer('rnw');

@layer rnw, base, components, utilities;

A page can instead declare the layer in the style sheet's element before the app loads. A copy of the sheet in a shadow root or an iframe is nested in the same layer. Nothing changes for an app that does neither: layering by default would let an app's unlayered CSS, such as a global reset, override every StyleSheet style.

Hydration leaves rules a page declared before the first group alone instead of throwing. An engine without cascade layers rejects the layer block, and the rules stay where they were.

Tests

• dom-test.js: inserting into a declared layer, serializing it, hydrating server-rendered rules from it and copying it into an iframe; setCascadeLayer moving the rules already inserted, keeping a page's own rules, leaving a sheet already in the layer alone, moving rules out of a layer of another name, nesting a sheet created after the call and the copies in other roots, and keeping the rules in place where an engine rejects or misparses the layer.
• dom-test.node.js and AppRegistry's index-test.node.js: the server-rendered sheet and getStyleElement() in the layer.
• dom-cascadeLayer-test.js: finding a declared layer, a nested and an anonymous name, and skipping other rules.
• dom-createOrderedCSSStyleSheet-test.js: hydration with a page's rule before the first group.

With master's dom/index.js, createOrderedCSSStyleSheet.js and StyleSheet/index.js, all 16 new cases fail, the declared-layer ones by throwing in hydration.

Verification

unit:dom 736 passed, 6 skipped · unit:node 8 passed · flow 0 errors · lint · format clean. The React canary job was not run.

The built dist in Chromium 153, Firefox 155 and WebKit 26.6, with @layer app{.box{border-top-width:5px}} and the generated .r-box{border-top-width:1px} on one element:

	top-level rules in the sheet	border-top-width
no layer, as on master	6	1px
setCascadeLayer('rnw') after the first rules	1, @layer rnw	5px
the page declares @layer rnw{}	1	5px
the page declares server-rendered rules in @layer rnw	1, no rule duplicated	5px

In the last three rows a shadow root's copy opens with @layer rnw in all three engines.

No issue tracks this; I searched the issues for "cascade layer", "@layer", "css layer" and "tailwind".

[codesandbox-ci]

This pull request is automatically built and testable in CodeSandbox.

To see build info of the built libraries, click here or the icon next to each commit SHA.

Latest deployment of this branch, based on commit 1d3cef2:

Sandbox	Source
react-native-web-examples	Configuration