[css-scoping-1] First draft of the shadow-scoped constructs text.

Author: tabatkins

css-scoping-1/Overview.bs

@@ -541,6 +541,151 @@ Slots and Slotted Elements in a Shadow Tree</h4>
 	and any deeper <a>slots</a> that their <a>slot</a> gets assigned to,
 	don't affect inheritance.
 
+
+<h3 id='shadow-names'>
+Name-Defining Constructs and Inheritance</h3>
+
+	[=Shadow trees=] are meant to be an encapsulation boundary,
+	allowing independent authors to share code
+	without accidentally polluting each other's namespaces.
+	For example, element IDs,
+	which are generally meant to be unique within a document,
+	can be validly used multiple times 
+	as long as each use is in a different [=shadow tree=].
+
+	Similarly, several [=at-rules=] in CSS,
+	such as ''@keyframes'' or ''@font-face'',
+	define a name that later at-rules or properties can refer to them by.
+	Like IDs, these names are globally exposed and unique within a document;
+	also like IDs,
+	this restriction is now loosened to being unique within a given [=shadow tree=].
+
+	However, property inheritance can carry values from one tree to another,
+	which complicates referencing the correct definition of a given name.
+	Done naively, this can produce surprising and confusing results for authors.
+	This section defines a set of concepts to use in defining and referencing "global" names
+	in a way that respects encapsulation
+	and doesn't give surprising results.
+
+	If an at-rule or property defines a name that other CSS constructs can refer to it by,
+	such as a 'font-family!!descriptor' name
+	or an ''@keyframes'' name,
+	it must be defined as a <dfn export for=CSS>tree-scoped name</dfn>.
+	[=Tree-scoped names=] are "global" within a particular [=node tree=];
+	unless otherwise specified,
+	they're associated with the [=root=] of the [=element=] hosting the stylesheet that the at-rule or property is defined in.
+
+	Properties or descriptors that reference a "global" name,
+	such as the 'font-family!!property'
+	or 'animation-name' properties,
+	must define their value as a <dfn export for=CSS>tree-scoped reference</dfn>.
+	[=Tree-scoped references=] implicitly capture
+	a [=node tree=] [=root=]
+	along with their specified value:
+	unless otherwise specified,
+	the [=root=] of the [=element=] hosting the stylesheet that the property or descriptor is defined in.
+	This [=root=] reference stays with the [=tree-scoped reference=]
+	as it is inherited.
+
+	Whenever a [=tree-scoped reference=] is dereferenced
+	to find the CSS construct it is referencing,
+	only the [=tree-scoped names=] associated with the same [=root=]
+	as the [=tree-scoped reference=] must be searched.
+
+	<div class=issue>
+		TODO: Fix all the at-rules that define global names,
+		and the properties that reference them,
+		to use these concepts.
+
+		* ''@font-face'', referenced by 'font-family!!property'
+		* ''@font-feature-values'', referenced by 'font-family!!property'
+		* ''@keyframes'', referenced by 'animation-name'
+		* ''@counter-style'', referenced by 'list-style-type'
+		* ''@color-profile'', referenced by the ''color()'' function
+		* ''@font-palette-values'', referenced by 'font-palette'
+		* others?
+	</div>
+
+<h4 id='shadow-names-serialization'>
+Serialized Tree-Scoped References</h4>
+
+	If a [=tree-scoped reference=] is [=serialized=],
+	it serializes only its value;
+	the associated [=root=] is lost.
+
+	<div class=example>
+
+		This implies that `el.style.foo = getComputedStyle(el).foo;`
+		is not necessarily a no-op,
+		like it typically was before [=shadow trees=] existed.
+
+		For example,
+		given the following document
+		(using the imaginary <::shadow></::shadow> markup
+		to indicate an element's [=shadow tree=]):
+
+		<xmp highlight=markup>
+			<p class=outer>Here's some text in the outer document's "foo" font.
+			<style>
+				@font-face {
+					font-family: foo;
+					src: url(foo.woff);
+				}
+				.outer { font-family: foo; }
+			</style>
+
+			<my-component>
+				<::shadow>
+					<p class=inner-default>I'm inheriting the outer document's font-family.
+					<p class=inner-styled>And I'm explicitly styled to be in the component's "foo" font.
+					<style>
+						@font-face {
+							font-family: foo;
+							src: url(https://example.com/foo.woff);
+						}
+						.inner-styled { font-family: foo; }
+					</style>
+					<script>
+						const innerDefault = document.querySelector('.inner-default');
+						const innerStyled = document.querySelector('.inner-styled');
+						const defaultFont = getComputedStyle(innerDefault).fontFamily;
+						const styledFont = getComputedStyle(innerStyled).fontFamily;
+
+						console.log(defaultFont == styledFont); // true!
+					</script>
+				</::shadow>
+			</my-component>
+		</xmp>
+
+		The <code>.outer</code> element is styled with the outer document's "foo" ''@font-face''.
+		The <code>.inner-default</code> element inherits 'font-family' from the outer document,
+		meaning it inherits a [=tree-scoped reference=]
+		referencing that outer document,
+		and so it's in the same font as <code>.outer</code>.
+
+		Meanwhile, <code>.inner-styled</code> is explicitly styled from inside the shadow root,
+		so it receives a fresh [=tree-scoped reference=]
+		referencing its shadow tree,
+		and it is instead styled the shadow's own "foo" ''@font-face''.
+
+		Despite that, the script running inside the component
+		sees the two elements as having the same value for 'font-family',
+		because the [=root=]-reference part of a [=tree-scoped reference=]
+		is not preserved by serialization.
+		If it were to set <code highlight=js>innerDefault.style.fontFamily = defaultFont;</code>
+		(thus setting the 'font-family' property of the element's attribute stylesheet,
+		which lives in the shadow tree),
+		the <code>.inner-default</code> element would suddenly switch
+		to the same font as <code>.inner-styled</code>!
+	</div>
+
+	Note: The [[css-typed-om-1]] is expected to reflect the [=root=] reference of a [=tree-scoped reference=]
+	in its [=reification=] rules for values,
+	allowing authors to tell what [=node tree=] the reference is taking its values from,
+	and allowing values to be transported across [=node trees=]
+	without changing their meaning.
+
+
 <h2 id="changes">
 Changes</h2>