Scoped Styles

Scoped style rules apply only within a subtree of a document, rather than matching against the entire document. Scoping has two primary effects: * The selector of the scoped style rule is restricted to match only elements within scope. See Scoped Selectors in [[SELECTORS4]]. * The cascade prioritizes scoped rules over unscoped ones, regardless of specificity. See Cascading by Scope in [[CSS3CASCADE]].

Scoping Mechanisms

Style rules can be scoped using constructs defined in the document language or using the ''@scope'' rule in CSS. “Scoping” consists of three somewhat independent concepts, which are in practice generally used together: * A declaration can be scoped to a scoping root, which affects its cascading behavior. [[!CSS3CASCADE]] (Alternately, a style rule can be scoped to a scoping root, which scopes all of the declarations it contains to that scoping root.) * A selector can be either scope-contained or scope-filtered to a scoping root, which limits what elements it is allowed to match. [[!SELECTORS4]] * The '':scope'' pseudo-class matches whatever the context sets as the :scope elements, and is used by several features, such as relative selectors. In the absence of any anything explicitly setting the :scope elements to something, the '':scope'' pseudo-class matches the selector's scoping root.

Document Markup for Scoping

Document languages may define a mechanism for a stylesheet to be scoped to some element in the document. For example, in HTML, a style element with a scoped attribute defines a stylesheet that is scoped to the style element’s parent element. [[HTML]] The element that the stylesheet is scoped to is the scoping root for all the style rules in the stylesheet, and selectors of style rules in the stylesheet are scope-contained to the scoping root.

CSS Syntax for Scoping: the ''@scope'' rule

The @scope at-rule allows authors to create scoped style rules using CSS syntax. The syntax of the ''@scope'' rule is:

	@scope <> {
		<>
	}

where the elements matched by the <> are scoping roots for the style rules in <>, and selectors of style rules scoped by ''@scope'' are scope-contained to their scoping root.

This rule makes it very easy for authors to create scoped style sheets, which could affect the optimization strategies for implementing scoped styles. If multiple elements match the <>, the <> is effectively duplicated and scoped independently to each one. Authors should avoid using overly-generic selectors as it can have confusing interactions with the cascade.

A scoped stylesheet is attached not only to the outermost scoping element, but to all matching elements. For example, given the style sheet below

		@scope div {
			span {
				color: blue;
			}
		}
		@scope section {
			span {
				color: orange;
			}
		}

and the following document fragment

		<div>
			<section>
				<div>
					<span>text</span>
				</div>
			</section>
		</div>

the text will be blue.

''@scope'' rules can be nested. In this case, just as with the nested style rules, the selector of an outer ''@scope'' scope-contains the selector of the inner one. The specificity of selectors inside the ''@scope'' rule is calculated locally: the selector specifying the scoping element is ignored. However, because scoped styles override non-scoped styles, style rules inside the ''@scope'' will override rules outside of it.

In the following example, the text would be green:

			@scope aside {
				p { color: green; }
			}
			aside#sidebar p { color: red; }

Issue: If multiple ''@scope'' rules apply to an element, should they be cascaded by specificity?

Querying the Scoping Context

Selecting the Scoping Root: '':scope'' pseudo-class

In a scoped stylesheet, the '':scope'' pseudo-class, defined in [[SELECTORS4]], matches the scoping root.

Selecting Outside the Scope: '':scope-context()'' pseudo-class

This would be defined similarly to '':host-context()'', but matching the ancestors of the scoping root instead. However, since for scoped stylesheets you may want the ability to match complex selectors against the outside tree, rather than a single compound selector, we may want to instead use a more general mechanism that doesn't syntactically invert the order of tree elements. Possible ideas:

		:scope-context(<>) div {...}
		scope(<>) div {...}
		\scope <>\ div {...}
		<> \scope\ div {...}

This functionality would replace ''@global'', which is a poor excuse for a selector.

Fragmented Styling

Fragmented content can be styled differently based on which line, column, page, region, etc. it appears in. This is done by using an appropriate fragment pseudo-element, which allows targetting individual fragments of an element rather than the entire element.

In our example, the designer wants to make text flowing into #region1 dark blue and bold. This design can be expressed as shown below.

		#region1::region p {
			color: #0C3D5F;
			font-weight: bold;
		}

The ''::region'' pseudo-element is followed by a ''p'' relative selector in this example. The color and font-weight declarations will apply to any fragments of paragraphs that are displayed in ''#region1''. The following figure shows how the rendering changes if we apply this styling specific to ''#region1''. Note how less text fits into this box now that the 'font-weight!!property' is bold instead of normal.

Illustrate how changing region styling affects the flow of content. — Different rendering with a different region styling

Note: This feature is an extension of ''::first-line'' styling.

Region-based Styling: the ''::region'' pseudo-element

Extend this to specify: * ''<region-element-selector>::region'' * ''<paginated-element-selector>::page(<page-selector>)'' * ''<multicol-element>::column(<AnB>)'' * ''<fragmented-element-selector>::nth-fragment(<AnB>)'' * ''::first-line''

A ::region pseudo-element represents a relationship between a selector that matches a CSS Region, and a relative selector that matches some named flow content. This allows style declarations to be applied to fragments of named flow content flowing into particular regions.

	<region selector>::region <content selector>  {
		... CSS styling declarations ...
	}

When the ::region pseudo-element is appended to a selector that matches one or more CSS Regions, this creates a 'flow fragment' selector. The flow fragment selector specifies which range of elements in the flow can be matched by the relative selector. The relative selector can match elements in the range(s) (see [[!DOM]]) of the named flow that are displayed fully or partially in the selected region(s). Elements that are fully or partially in the flow fragment range may match the relative selector. However, the style declarations only apply to the fragment of the element that is displayed in the corresponding region(s). Only a limited list of properties apply to a ::region pseudo-element: Issue: Either this list should be all functionally inheritable properties, or all properties. Why is it a seemingly-arbitrary subset of all properties, including box properties? 1. font properties 2. color property 3. opacity property 4. background property 5. 'word-spacing' 6. 'letter-spacing' 7. 'text-decoration' 8. 'text-transform' 9. 'line-height' 10. alignment and justification properties 11. border properties 12. rounded corner properties 13. border images properties 14. margin properties 15. padding properties 16. 'text-shadow' 17. 'box-shadow' 18. 'box-decoration-break' 19. 'width'

In the following example, the named flow “article-flow” flows into “region-1” and “region-2”.

		<style>
		  #div-1 {
			flow-into: article-flow;
		  }

		  #region-1, #region-2 {
			flow-from: article-flow;
		  }

		  /* region styling */
		  #region-1::region p  {
			margin-right: 5em;
		  }
		</style>

		<body>
		  <div id="div-1">
			  <p id="p-1">...</p>
			  <p id="p-2">...</p>
		  </div>
		  <div id="region-1"></div>
		  <div id="region-2"></div>
		</body>

Example showing how a named flow content fits into regions to illustrate region styling.

The region styling applies to flow content that fits in ''region-1''. The relative selector matches ''p-1'' and ''p-2'' because these paragraphs flow into ''region-1''. Only the fragment of ''p-2'' that flows into ''region-1'' is styled with the pseudo-element.

All of the selectors in a ::region pseudo-element contribute to its specificity. So the specificity of the ::region pseudo-element in the example above would combine the id selector's specificity with the specificity of the type selector, resulting in a specificity of 101. Selectors that match a given element or element fragment (as described above), participate in the CSS Cascading order as defined in [[!CSS21]]. Note: Region styling does not apply to nested regions. For example, if a region ''A'' receives content from a flow that contains region ''B'', the content that flows into ''B'' does not receive the region styling specified for region ''A''. Issue: We'll need some way to query the styles of a fragment in a particular region. getComputedStyle() isn't enough, because an element can exist in multiple regions, for example, with each fragment receiving different styles.