From ebafba17af2009e18b584b49832677c4d06b8ffd Mon Sep 17 00:00:00 2001 From: Anders Hartvoll Ruud Date: Mon, 3 Feb 2025 23:02:03 +0000 Subject: [PATCH] [css-mixins-1] Drop 'using', define dynamic scoping Resolves #10954. --- css-mixins-1/Overview.bs | 101 +++++++++++++++++++++++---------------- 1 file changed, 61 insertions(+), 40 deletions(-) diff --git a/css-mixins-1/Overview.bs b/css-mixins-1/Overview.bs index 02a54c791f3..dce74aa5731 100644 --- a/css-mixins-1/Overview.bs +++ b/css-mixins-1/Overview.bs @@ -15,6 +15,7 @@ Default Highlight: css 
 spec:infra; type:dfn; text:list
+spec:infra; type:dfn; for:list; text:append
 spec:css-properties-values-api; type:dfn; text:supported syntax component name
 spec:css-properties-values-api; type:dfn; text:syntax component
 spec:css-syntax-3; type:dfn; text:declaration
@@ -83,7 +84,6 @@ Defining Custom Functions {#defining-custom-functions}
 
 	A custom function consists of a name (<>),
 	a list of [=function parameter|parameters=],
-	a list of [=function dependency|dependencies=],
 	a function body,
 	and optionally a return type described by a [=syntax definition=].
 
@@ -91,12 +91,6 @@ Defining Custom Functions {#defining-custom-functions}
 	optionally a parameter type, described by a [=syntax definition=];
 	and optionally a default value.
 
-	A function dependency,
-	is a special [=function parameter=],
-	that represents
-	a [=local variable=], [=function parameter=], or [=custom property=]
-	being implicitly passed as an argument from the calling context.
-
 The @function Rule {#function-rule}
 ----------------------------------------------
 
@@ -105,14 +99,12 @@ and its syntax is:
 
 
 <@function> = @function <> <>? )
-	[ using ( <> ) ]?
 	[ returns <> ]?
 {
 	<>
 }
 
 <> = <>#
-<> = <>#
 <> = <> <>? [ : <> ]?
 <> = <> | <>
 <type()> = type( <> )
@@ -125,12 +117,10 @@ with the additional restriction that it must start with two dashes
 
 The name of the resulting [=custom function=] is given by the <>,
 the [=function parameters=] are optionally given by <>,
-the [=function dependencies=] are optionally given by <>,
 and the [=return type=] is optionally given by the <> following the "returns" keyword.
 
 

-	If the <> of a [=function parameter=],
-	[=function dependency=],
+	If the <> of a [=function parameter=]
 	or [=custom function=] return value
 	can be described by a single <>,
 	then the ''type()'' function may be omitted:
@@ -150,8 +140,6 @@ and the [=return type=] is optionally given by the <> following the "r
 	

 
 
-Issue: Should duplicates be disallowed across parameters/dependencies
-	as well?
 
 If more than one ''@function'' exists for a given name,
 then the rule in the stronger cascade layer wins,
@@ -161,8 +149,6 @@ The <> of a ''@function'' rule is a [=tree-scoped name=].
 
 If the <>
 contains the same <> more than once,
-or if the <>
-contains the same <> more than once,
 then the ''@function'' rule is invalid.
 
 The body of a ''@function'' rule accepts [=conditional group rules=],
@@ -191,7 +177,7 @@ The '@function/result' descriptor
 determines the result of [=evaluate a custom function|evaluating=]
 the [=custom function=] that is defined by a ''@function'' rule.
 Using [=locally substitute a var()|locally substituted=] ''var()'' functions,
-it can reference [=function parameters=], [=function dependencies=], [=local variables=],
+it can reference [=function parameters=], [=local variables=],
 as well as other [=custom functions=] via <>s.
 
 The '@function/result' descriptor itself does not have a type,
@@ -246,23 +232,24 @@ described in [[!css-variables]].
 		1. Let |function| be the result of dereferencing
 			the |dashed function|'s name as a [=tree-scoped reference=].
 			If no such name exists, return failure.
-		2. Let |dependency values| be an initially empty [=list=].
-		3. For each |dependency| in |function|'s [=function dependency|dependencies=]:
-			* Let |dependency value| be the value that would be substituted
-				if a ''var()'' function had been specified explicitly
-				at the end of |dashed function|'s argument list,
-				with |dependency| as its only argument.
-			* If that substitution would have made a containing declaration
-				[=invalid at computed-value time=],
-				set |dependency value| to the [=guaranteed-invalid value=].
-			* Append the result of [=resolving an argument=] to |dependency values|,
-				using |dependency value| as value,
-				and |dependency| as parameter.
+		2. Let |dependencies| be an initially empty [=list=].
+		3. For every possible argument to ''var()'' (with no fallback)
+			that would lead to a valid [=locally substitute a var()|local substitution=]
+			in place of |dashed function|:
+			[=append=] a [=declaration=] to |dependencies|
+			with that argument as the name,
+			and the substitution value as the value.
+
+			Note: This exposes any [=custom properties=], [=local variables=],
+				and [=function parameters=] that are visible
+				in any given context
+				to [=custom functions=] invoked by that context.
+
 		4. [=substitute arbitrary substitution functions|Substitute=]
 			any [=arbitrary substitution functions=]
 			within |dashed function|'s arguments.
 		5. [=Evaluate a custom function=],
-			using |function|, |dashed function| and |dependency values|.
+			using |function|, |dashed function| and |dependencies|.
 		6. If failure was returned, return failure.
 		7. Otherwise,
 			replace the <> with the [=equivalent token sequence=]
@@ -281,7 +268,7 @@ Evaluating Custom Functions {#evaluating-custom-functions}
 	To evaluate a custom function,
 	with |function| being a [=custom function=],
 	|dashed function| being the <> invoking that |function|,
-	and |dependency values| being a [=list=] of values.
+	and |dependencies| being a [=list=] of [=declarations=].
 
 	1. If the number of values in |dashed function|'s argument list
 		is greater than the number of values in |function|'s [=function parameter|parameters=],
@@ -297,7 +284,7 @@ Evaluating Custom Functions {#evaluating-custom-functions}
 			and |parameter| as parameter.
 	3. Let |result| be the [=resolved local value=]
 		of the '@function/result' descriptor,
-		using |function|, |dashed function|, and |dependency values|.
+		using |function|, |dashed function|, and |dependencies|.
 	4. If |function| has a [=return type=],
 		set |result| to the result of [=resolve a typed value|resolving a typed value=],
 		using |result| as the value,
@@ -367,25 +354,26 @@ Evaluating Custom Functions {#evaluating-custom-functions}
 Parameters and Locals {#parameters}
 -----------------------------------
 
-	The [=function parameters=] and [=function dependencies=] of a [=custom function=]
+	The [=function parameters=] of a [=custom function=]
 	are available for [=locally substitute a var()|local substitution=]
 	as if they were declared as [=local variables=]
 	at the start of the ''@function'' rule body.
 
 	Note: A [=local variable=] with the same name
-		as a [=function parameter=]/[=function dependency=] is allowed,
-		but will make the parameter/dependency unreachable
+		as a [=function parameter=] is allowed,
+		but will make the parameter unreachable
 		for [=locally substitute a var()|substitution=]
 
 	A local variable
 	is a custom property defined with the body of a [=custom function=].
-	It is only visible within the function where it is defined.
+	It is visible within the function where it is defined,
+	and within other [=custom functions=] invoked by that function.
 
 

 	To locally substitute a var() within a value,
 	with |function| being a [=custom function=],
 	|dashed function| being the <> invoking that |function|,
-	and |dependency values| being a [=list=] of values:
+	and |dependencies| being a [=list=] of [=declarations=]:
 
 	1. Let |substitution value| be one of the following options,
 		depending on the [=custom property=] named in the first argument of the ''var()'' function:
@@ -397,9 +385,9 @@ Parameters and Locals {#parameters}
 			:   Otherwise, if the [=custom property=] name matches a [=function parameter|parameter=] within |function|
 			::  The corresponding argument value within the |dashed function|.
 
-			:   Otherwise, if the [=custom property=] name matches a [=function dependency|dependency=] within |function|
-			::  The corresponding value of that [=function dependency|dependency=]
-				within |dependency values|.
+			:   Otherwise, if the [=custom property=] name matches the name
+				of a [=declaration=] within |dependencies|
+			::  The corresponding value of that [=declaration=].
 
 			:   Otherwise
 			::  The [=guaranteed-invalid value=].
@@ -426,6 +414,39 @@ If any substitution algorithm returns failure,
 then the [=resolved local value=] of a [=local variable=]
 is the [=guaranteed-invalid value=].
 
+

+	A [=custom function=] can access [=local variables=]
+	and [=function parameters=]
+	from functions higher up in the call stack:
+
+	
+	@function --foo(--x) {
+	  --y: 2;
+	  result: --bar();
+	}
+	@function --bar() returns <number> {
+	  result: calc(var(--x) + var(--y));
+	}
+	div {
+	  z-index: --foo(1); /* 3 */
+	}
+	

+
+	Similarly, [=custom properties=] are implicitly available:
+
+	
+	@function --double-z() returns <number> {
+	  result: calc(var(--z) * 2);
+	}
+	div {
+	  --z: 3;
+	  z-index: --double-z(); /* 6 */
+	}
+	

+
+

+
+
 Cycles {#cycles}
 ----------------