[css-mixins-1] Properly define scoped mixin behavior lifting arguments onto the @apply'd element. w3c#13113

Author: tabatkins

css-mixins-1/Overview.bs

@@ -1017,7 +1017,7 @@ The ''@result'' Rule</h3>
 
 Within a ''@mixin'' rule,
 the ''@result'' rule specifies the <dfn export>mixin result</dfn>,
-a [=nested declarations block=]
+a [=nested declarations rule=]
 similar to the 'result!!descriptor' descriptor in [=custom functions=].
 It's what the ''@apply'' rule will be substituted with.
 
@@ -1500,24 +1500,95 @@ with each property value in the [=mixin result=]
 having its value replaced by an anonymous [=custom function=]
 with the following properties:
 
-* The [=function parameters=] are identical to the [=mixin parameters=],
-	and the [=function invocation=] is passed the same values as the ''@apply''.
+* The [=function parameters=] are identical to the [=mixin parameters=].
+	(The function's invocation has some adjustments; see below.)
 * The [=function body=] is identical to the [=mixin body=],
 	minus any ''@result'' rules,
 	plus a 'result' descriptor
 	containing the original value of the property this anonymous function is replacing.
 
-Note: In practice, this [=custom function=] can usually be completely hypothetical,
+Additionally, the arguments passed to the mixin
+are evaluated and stored on the ''@apply''@apos;d element,
+to ensure they obtain the "expected" value from that element,
+rather than unexpectedly evaluating in a descendant element's context:
+
+* For every [=mixin parameter=],
+	a custom property is added to the top level of the [=mixin result=],
+	with a [=hygienic rename|hygienic name=]
+	and a value of the corresponding ''@apply()'' argument.
+	This custom property is <em>unobservable</em> to the page;
+	it only exists for UA purposes.
+
+	Also, a [=custom property registration=]
+	with that name,
+	a syntax of the [=parameter type=],
+	an inherit flag of "true",
+	and no initial value,
+	is added to the tree of that element.
+* Each anonymous function invocation
+	has its arguments set to ''var()'' functions
+	referring to the corresponding custom property name
+	created in the previous bullet point.
+
+<div class=example>
+	For example, given the following mixin:
+
+	<xmp highlight=css>
+	@mixin --same-size(--size <length>) {
+		@result {
+			&, & > * {
+				width: calc(10 * var(--size));
+			}
+		}
+	}
+	.parent {
+		font-size: 10px;
+		@apply --same-size(1em);
+	}
+	.parent > .child {
+		font-size: 20px;
+	}
+	</xmp>
+
+	This will desugar into approximately:
+
+	<xmp>
+	@property --magic-arg1 {
+		syntax: "<length>";
+		inherits: true;
+		/* initial-value: don't worry about it; */
+	}
+	@function --anonfunc1(--arg1) {
+		result: calc(10 * var(--arg1));
+	}
+	@function --anonfunc2(--arg1) {
+		result: calc(10 * var(--arg1));
+	}
+	.parent {
+		font-size: 10px;
+		--magic-arg1: 1em; /* resolves based on font-size here */
+		width: --anonfunc1(var(--magic-arg1));
+	}
+	.parent > .child {
+		font-size: 20px;
+		width: --anonfunc2(var(--magic-arg1));
+		/* --magic-arg1 is 10px, since it was resolved on the parent */
+	}
+	</xmp>
+</div>
+
+Note: In practice, this anonymous [=custom function=]
+can usually be completely hypothetical,
 and a direct substitution used instead.
-It's required only to make variables resolve correctly.
+It's required only to make variables
+and other element-relative values resolve correctly.
 
 Issue: TODO add a few examples derived from <a href="https://github.com/w3c/csswg-drafts/issues/12927">issue 12927</a>.
 
 
 
 
 
-
 <!-- Big Text: cssom
 
  ███▌   ███▌   ███▌   ███▌  █     █