CSS Functions and Mixins Module

1. Introduction

This section is not normative.

TODO

2. Defining Custom Functions

A custom function can be thought of as an advanced custom property, which instead of being substituted by a single fixed value provides its substitution value based on function parameters and local variables.

Whenever a declaration’s value contains a reference to a custom function (a <dashed-function>), the value behaves as if it contained a var(), with the actual check against the property’s grammar delayed until computed-value time.

@function --negative (--value) {
  result: calc(-1 * var(--value));
}

html { padding: --negative(var(--gap)); }

A custom function consists of a name (<function-name>), a list of parameters, a list of dependencies, a function body, and optionally a return type described by a syntax definition.

A function parameter consists of a name (<custom-property-name>); 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.

2.1. The @function Rule

The @function rule defines a custom function, and its syntax is:

<@function> = @function <function-name> [ ( <function-parameter-list> ) ]?
  [ using ( <function-dependency-list> ) ]?
  [ returns <css-type> ]?
{
  <declaration-rule-list>
}

<function-name> = <dashed-ident>
<function-parameter-list> = <function-parameter>#
<function-dependency-list> = <function-parameter>#
<function-parameter> = <custom-property-name> <css-type>? [ : <declaration-value> ]?
<css-type> = <syntax-component> | <type()>
<type()> = type( <syntax> )

The name of the resulting custom function is given by the <function-name>, the function parameters are optionally given by <function-parameter-list>, the function dependencies are optionally given by <function-dependency-list>, and the return type is optionally given by the <css-type> following the "returns" keyword.

@function --foo(--a <length>) { /* ... */ }
@function --foo(--a <color>) { /* ... */ }
@function --foo(--a <length>+) { /* ... */ }

@function --foo(--a type(<number> | <percentage>)) { /* ... */ }

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, and rules defined later win within the same layer.

The <function-name> of a @function rule is a tree-scoped name.

If the <function-parameter-list> contains the same <custom-property-name> more than once, or if the <function-dependency-list> contains the same <custom-property-name> more than once, then the @function rule is invalid.

The body of a @function rule accepts conditional group rules, such as @media. Additionally, it accepts the following descriptors:

• The result descriptor, which determines the result of evaluating the function.

• Custom properties, acting like local variable descriptors.

Unknown descriptors are invalid and ignored, but do not make the @function rule itself invalid.

2.2. The result Descriptor

The result descriptor determines the result of evaluating the custom function that is defined by a @function rule. Using locally substituted var() functions, it can reference function parameters, function dependencies, local variables, as well as other custom functions via <dashed-function>s.

The result descriptor itself does not have a type, but its resolved value is type checked during the substitution of a <dashed-function>.

3. Using Custom Functions

Similar to how the value of a custom property can be substituted into the value of another property with var(), the result of a custom function evaluation can be substituted with a <dashed-function>.

A <dashed-function> is a functional notation whose function name starts with two dashes (U+002D HYPHEN-MINUS). Its syntax is:

--*( <declaration-value># )

Mention semicolon upgrades.

A <dashed-function> can only be used where var() is allowed.

If a property contains one or more <dashed-function>s, the entire property’s grammar must be assumed to be valid at parse time. At computed-value time, every <dashed-function> must be substituted before finally being checked against the property’s grammar.

When a value is being computed, substitution of var(), env() and attr() must take place before <dashed-function> substitution.

Note: This means arguments passed to a custom function never contain var(), or similar functions.

A var() function within a local variable, or within the result descriptor, invokes local substitution, rather than the computed-value based substitution described in [css-variables].

If substitute a dashed function fails, and the substitution is taking place on a property’s value, then the declaration containing the <dashed-function> becomes invalid at computed-value time.

3.1. Evaluating Custom Functions

3.2. Parameters and Locals

The function parameters and function dependencies of a custom function are available for 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 for 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.

A resolved local value is the value of a local variable or descriptor, except:

• Any var() functions are replaced by local substitution.

• Any env() or attr() functions are substituted normally.

• Any <dashed-function>s are replaced by dashed function substitution.

If any substitution algorithm returns failure, then the resolved local value of a local variable is the guaranteed-invalid value.

3.3. Cycles

TODO

4. Execution Model of Custom Functions

Like the rest of CSS, custom functions adhere to a declarative model.

The local variable descriptors and result descriptor can appear in any order, and may be provided multiple times. If this happens, then declarations appearing later win over earlier ones.

@function --mypi() {
  result: 3;
  result: 3.14;
}

@function --circle-area(--r) {
  result: calc(pi * var(--r2));
  --r2: var(--r) * var(--r);
}

4.1. Conditional Rules

A conditional group rule that appears within a @function becomes a nested group rule, with the additional restriction that only descriptors allowed within @function are allowed within the nested group rule.

Conditional group rules within @function are processed as normal, acting as if the contents of the rule were present at the conditional group rule's location when the condition is true, or acting as if nothing exists at that location otherwise.

@function --suitable-font-size() {
  result: 16px;
  @media (width > 1000px) {
    result: 20px;
  }
}

@function --suitable-font-size() {
  @media (width > 1000px) {
    result: 20px;
  }
  result: 16px;
}

@function --suitable-font-size() {
  --size: 16px;
  @media (width > 1000px) {
    --size: 20px;
  }
  result: var(--size);
}

5. CSSOM

The CSSFunctionRule interface represents a @function rule.

[Exposed=Window]
interface CSSFunctionRule : CSSGroupingRule { };

While declarations may be specified directly within a @function rule, they are not represented as such in the CSSOM. Instead, consecutive segments of declarations appear as if wrapped in CSSNestedDeclarations rules.

Note: This also applies to the "leading" declarations in the @function rule, i.e those that do not follow another nested rule.

@function --bar() {
  --x: 42;
  result: var(--y);
  @media (width > 1000px) {
    /* ... */
  }
  --y: var(--x);
}

@function --bar() {
  /* CSSNestedDeclarations { */
    --x: 42;
    result: var(--y);
  /* } */
  @media (width > 1000px) {
    /* ... */
  }
  /* CSSNestedDeclarations { */
    --y: var(--x);
  /* } */
}

Should we indeed use CSSNestedDeclarations for this purpose? The style attribute of the CSSNestedDeclarations rule should probably not be a regular CSSStyleDeclaration, since only custom properties and the result descriptor are relevant.

6. Appendix: The <syntax> Production

The <syntax> production represents a syntax definition, which may be used to impose a type on function parameters, function dependencies, or custom function return values.

<syntax-type> = angle | color | custom-ident | image | integer |
  length | length-percentage | number |
  percentage | resolution | string | time |
  url | transform-function
<syntax-combinator> = '|'
<syntax-multiplier> = [ '#' | '+' ]
<syntax-component-name> = '<' <syntax-type> '>' | <custom-ident>
<syntax-component> = <syntax-component-name> <syntax-multiplier>? |
  '<' transform-list '>'
<syntax> = '*' | <syntax-component> [ <syntax-combinator> <syntax-component> ]+

A <syntax-component> consists of either a <syntax-type>, which maps to one of the supported syntax component names; or a <custom-ident>, which represents any keyword. Additionally, a <syntax-component> may contain a multiplier, which indicates a list of values.

Note: This means that <length> and length are two different types: the former describes a <length>, whereas the latter describes a keyword length.

Multiple <syntax-component>s may be combined with a | <delim-token>, causing the syntax components to be matched against a value in the specified order.

<percentage> | <number> | auto

red | <color>

The * <delim-token> represents the universal syntax definition.

The <transform-list> production is a convenience form equivalent to <transform-function>+. Note that <transform-list> may not be followed by a <syntax-multiplier>.

Whitespace is not allowed between the angle bracket <delim-token>s (< >) and the <syntax-type> they enclose, nor is whitespace allowed to precede a <syntax-multiplier>.

Note: The whitespace restrictions also apply to <transform-list>.