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}
----------------