
<!--
 ██████   ██████   ███████  ████████  ████ ██    ██  ██████
██    ██ ██    ██ ██     ██ ██     ██  ██  ███   ██ ██    ██
██       ██       ██     ██ ██     ██  ██  ████  ██ ██
 ██████  ██       ██     ██ ████████   ██  ██ ██ ██ ██   ████
      ██ ██       ██     ██ ██         ██  ██  ████ ██    ██
██    ██ ██    ██ ██     ██ ██         ██  ██   ███ ██    ██
 ██████   ██████   ███████  ██        ████ ██    ██  ██████
-->

<h2 id='scope'>
Scoped Styles</h2>

	<a>Scoped</a> 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 <a>scoped</a> style rule is restricted to match only elements within scope.
		See <a href="https://www.w3.org/TR/selectors4/#scoping">Scoped Selectors</a> in [[SELECTORS4]].
	* The cascade prioritizes scoped rules over unscoped ones, regardless of specificity.
		See <a href="https://www.w3.org/TR/css-cascade/#cascade-scope">Cascading by Scope</a> in [[CSS3CASCADE]].

<h3 id='scoping-mechanisms'>
Scoping Mechanisms</h3>

	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 <a>scoping root</a>,
		which <a href="https://drafts.csswg.org/css-cascade/#cascade-scope">affects its cascading behavior</a>. [[!CSS3CASCADE]]
		(Alternately, a style rule can be scoped to a <a>scoping root</a>,
		which scopes all of the declarations it contains to that <a>scoping root</a>.)

	* A selector can be either <a>scope-contained</a> or <a>scope-filtered</a> to a <a>scoping root</a>,
		which <a href="https://drafts.csswg.org/selectors/#evaluating-selectors">limits what elements it is allowed to match</a>. [[!SELECTORS4]]

	* The '':scope'' pseudo-class matches whatever the context sets as the <a>:scope elements</a>,
		and is used by several features, such as relative selectors.
		In the absence of any anything explicitly setting the <a>:scope elements</a> to something,
		the '':scope'' pseudo-class matches the selector's <a>scoping root</a>.

<h4 id='scoping-markup'>
Document Markup for Scoping</h4>

	Document languages may define a mechanism for a stylesheet to be scoped to some element in the document.
	For example, in HTML,
	a <a element>style</a> element with a <a element-attr for="style">scoped</a> attribute
	defines a stylesheet that is scoped to the <a element>style</a> element’s parent element.
	[[HTML]]

	The element that the stylesheet is scoped to
	is the <a>scoping root</a> for all the style rules in the stylesheet,
	and selectors of style rules in the stylesheet
	are <a>scope-contained</a> to the <a>scoping root</a>.

<!--
 ███████   ██████   ██████   ███████  ████████  ████████
██     ██ ██    ██ ██    ██ ██     ██ ██     ██ ██
██ ███ ██ ██       ██       ██     ██ ██     ██ ██
██ ███ ██  ██████  ██       ██     ██ ████████  ██████
██ █████        ██ ██       ██     ██ ██        ██
██        ██    ██ ██    ██ ██     ██ ██        ██
 ███████   ██████   ██████   ███████  ██        ████████
-->

<h4 id='scope-atrule'>
CSS Syntax for Scoping: the ''@scope'' rule</h4>

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

	<pre class='prod'>
	@scope <<selector-list>> {
		<<stylesheet>>
	}
	</pre>

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

	<p class="issue">
	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 <<selector-list>>,
	the <<stylesheet>> 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.

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

		<pre>
		@scope div {
			span {
				color: blue;
			}
		}
		@scope section {
			span {
				color: orange;
			}
		}
		</pre>

		and the following document fragment

		<pre>
		&lt;div>
			&lt;section>
				&lt;div>
					&lt;span>text&lt;/span>
				&lt;/div>
			&lt;/section>
		&lt;/div>
		</pre>

		the text will be blue.
	</div>

	''@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.

	<div class="example">
		In the following example, the text would be green:

		<pre>
			@scope aside {
				p { color: green; }
			}
			aside#sidebar p { color: red; }
		</pre>
	</div>

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

<!--
 ██   ██████   ██████   ███████  ████████  ████████
████ ██    ██ ██    ██ ██     ██ ██     ██ ██
 ██  ██       ██       ██     ██ ██     ██ ██
      ██████  ██       ██     ██ ████████  ██████
 ██        ██ ██       ██     ██ ██        ██
████ ██    ██ ██    ██ ██     ██ ██        ██
 ██   ██████   ██████   ███████  ██        ████████
-->

<h3 id='scoping-context'>
Querying the Scoping Context</h3>

<h4 id='scope-pseudo'>
Selecting the Scoping Root: '':scope'' pseudo-class</h4>

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

<h4 id='scope-content-pseudo'>
Selecting Outside the Scope: '':scope-context()'' pseudo-class</h4>

	<div class='issue'>
		This would be defined similarly to '':host-context()'',
		but matching the ancestors of the <a>scoping root</a> 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:

		<pre>
		:scope-context(<<selector-list>>) div {...}
		scope(<<selector-list>>) div {...}
		\scope <<selector-list>>\ div {...}
		<<selector-list>> \scope\ div {...}
		</pre>

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



<!--
████████ ████████     ███     ██████   ██     ██ ████████ ██    ██ ████████  ██████
██       ██     ██   ██ ██   ██    ██  ███   ███ ██       ███   ██    ██    ██    ██
██       ██     ██  ██   ██  ██        ████ ████ ██       ████  ██    ██    ██
██████   ████████  ██     ██ ██   ████ ██ ███ ██ ██████   ██ ██ ██    ██     ██████
██       ██   ██   █████████ ██    ██  ██     ██ ██       ██  ████    ██          ██
██       ██    ██  ██     ██ ██    ██  ██     ██ ██       ██   ███    ██    ██    ██
██       ██     ██ ██     ██  ██████   ██     ██ ████████ ██    ██    ██     ██████
-->

<h2 id="fragment-scoping">
Fragmented Styling</h2>

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

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

		<pre>
		#region1::region p {
			color: #0C3D5F;
			font-weight: bold;
		}
		</pre>

		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.

		<figure>
			<img src="images/region-styling.png" width="450" alt= "Illustrate how changing region styling affects the flow of content.">

			<figcaption>Different rendering with a different region styling</figcaption>
		</figure>
	</div>

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

<h3 id="the-region-pseudo-element">
Region-based Styling: the ''::region'' pseudo-element</h3>

	<div class="issue">
		Extend this to specify:

		* ''&lt;region-element-selector>::region''
		* ''&lt;paginated-element-selector>::page(&lt;page-selector>)''
		* ''&lt;multicol-element>::column(&lt;AnB>)''
		* ''&lt;fragmented-element-selector>::nth-fragment(&lt;AnB>)''
		* ''::first-line''
	</div>

	A ::region pseudo-element represents a relationship between
	a selector that matches a <span>CSS Region</span>,
	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.

	<pre>
	&lt;region selector&gt;::region &lt;content selector&gt;  {
		... CSS styling declarations ...
	}
	</pre>

	When the ::region pseudo-element is appended to a
	<a href="https://www.w3.org/TR/css3-selectors/#selector-syntax">selector</a>
	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. <a href="https://www.w3.org/TR/CSS2/fonts.html">font properties</a></li>
	2. <a href="https://www.w3.org/TR/CSS2/colors.html">color property</a></li>
	3. <a href="https://www.w3.org/TR/css3-color/#transparency">opacity property</a></li>
	4. <a href="https://www.w3.org/TR/css3-background/#backgrounds">background property</a></li>
	5. 'word-spacing'</li>
	6. 'letter-spacing'</li>
	7. 'text-decoration'</li>
	8. 'text-transform'</li>
	9. 'line-height'</li>
	10. <a href="https://www.w3.org/TR/css3-text/#justification">alignment and justification properties</a></li>
	11. <a href="https://www.w3.org/TR/css3-background/#borders">border properties</a></li>
	12. <a href="https://www.w3.org/TR/css3-background/#corners">rounded corner properties</a></li>
	13. <a href="https://www.w3.org/TR/css3-background/#border-images">border images properties</a></li>
	14. <a href="https://www.w3.org/TR/CSS2/box.html#margin-properties">margin properties</a></li>
	15. <a href="https://www.w3.org/TR/CSS2/box.html#padding-properties">padding properties</a></li>
	16. 'text-shadow'</li>
	17. 'box-shadow'</li>
	18. 'box-decoration-break'</li>
	19. 'width'</li>

	<div class="example" id="region-style-example">
		In the following example, the <span>named flow</span> “article-flow” flows
		into “region-1” and “region-2”.
		<pre>
		&lt;style&gt;
		  #div-1 {
			<strong>flow-into: article-flow;</strong>
		  }

		  #region-1, #region-2 {
			<strong>flow-from: article-flow;</strong>
		  }

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

		&lt;body&gt;
		  &lt;div id="div-1"&gt;
			  &lt;p id="p-1"&gt;...&lt;/p&gt;
			  &lt;p id="p-2"&gt;...&lt;/p&gt;
		  &lt;/div&gt;
		  &lt;div id="region-1"&gt;&lt;/div&gt;
		  &lt;div id="region-2"&gt;&lt;/div&gt;
		&lt;/body&gt;
		</pre>

		<div id="region_styling_illustration">
			<img id="region_styling_img_2" src="images/region-styling-2.png" alt= "Example showing how a named flow content fits into regions to illustrate region styling.">

			<ul class="swatch-list">
				<li><span class="swatch" style= "background:#1C75BC">&nbsp;</span>div div-1
				<li><span class="swatch" style= "background:crimson">&nbsp;</span>paragraph p-1
				<li><span class="swatch" style= "background:white">&nbsp;</span>paragraph p-2
				<li><span class="swatch" style= "background:#E6E7E8">&nbsp;</span>range of flow that fits into region-1
				<li><span class="swatch" style= "background:#BCBEC0">&nbsp;</span>range of flow that fits into region-2
			</ul>
		</div>

		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.
	</div>

	All of the selectors
	in a ::region pseudo-element
	contribute to its <a href="https://www.w3.org/TR/css3-selectors/#specificity">specificity</a>.
	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 <a href="https://www.w3.org/TR/2011/REC-CSS2-20110607/cascade.html#cascading-order">CSS Cascading
	order</a> 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.
	<code>getComputedStyle()</code> isn't enough,
	because an element can exist in multiple regions, for example,
	with each fragment receiving different styles.
