CSS Conditional Values Module Level 1

1. Introduction

This section is not normative.

Note: This section is a stub and needs to be expanded.

Authors frequently need to set a property to different values based on the relation between certain values.

1.1. High level custom properties

A web component may support several custom properties which do not contain a value fragment verbatim, but set several properties across multiple rules indirectly. For example, a `--size` property with values `small`, `medium`, `large`, or an `--alignment` property with values `horizontal` and `vertical`.

1.2. Relation between units of the same type

Author code often needs to branch based on the relation between different units of the same type.

For example:

• Comparing viewport and absolute units allows compact one-off viewport dimension media queries

• Comparing font-relative units and absolute <length> units allows authors to apply different styling for small and large font sizes, enhancing readability.

1.3. Value Definitions

This specification follows the CSS property definition conventions from [CSS2] using the value definition syntax from [CSS-VALUES-3]. Value types not defined in this specification are defined in CSS Values & Units [CSS-VALUES-3]. Combination with other CSS modules may expand the definitions of these value types.

In addition to the property-specific values listed in their definitions, all properties defined in this specification also accept the CSS-wide keywords as their property value. For readability they have not been repeated explicitly.

2. Boolean data types

2.1. Boolean constants: true and false

<boolean-constant> = 'true' | 'false'

2.2. Logical comparisons: The <condition> type

<condition> = not <condition-in-parens>
                     | <condition-in-parens> [ and <condition-in-parens> ]*
                     | <condition-in-parens> [ or <condition-in-parens> ]*
<condition-in-parens> = ( <condition> ) | <atomic-condition>
<atomic-condition> = <comparison-operand> <comparison-operator> <comparison-operand> | <boolean-constant>
<comparison-operand> = <dimension> | <number> | <percentage> | <ident>
<comparison-operator> = [ '=' | '>=' | '>' | '<' | '<=' ]

Note: A future version of this module may expand <comparison-operand> to complex types, such as colors.

<condition> values are logical expressions that resolve to a <boolean-constant> by performing simple comparisons and following basic boolean operators. When using `and` or `or` operators, precedence must be enforced with parentheses. The `not` operator does not require this, and has higher precedence than `and` and `or`.

Each of these grammar terms is associated with a boolean result, as follows:

<condition>

<condition-in-parens>

The result is the result of the child subexpression.

not <condition-in-parens>

The result is the negation of the <condition-in-parens> term. The negation of unknown is unknown.

<condition-in-parens> [ and <condition-in-parens> ]*

The result is true if all of the <condition-in-parens> child terms are true, false if at least one of the <condition-in-parens> is false, and unknown otherwise.

<condition-in-parens> [ or <condition-in-parens> ]*

The result is false if all of the <condition-in-parens> child terms are false, true if at least one of the <condition-in-parens> is true, and unknown otherwise.

These rules are consistent with the way conditions are resolved in [css-conditional-3].

Together with this, there are currently 3 specs ([css-conditional-3], [mediaqueries-4]) using boolean operators, and two defining how they work ([css-conditional-3] and this). Ideally, this should be defined in one place, and cited everywhere else.

Both <comparison-operand> values in <atomic-condition> need to be of the same type. If they are not, the entire condition becomes an invalid condition and evaluates to unknown.

These operations are only defined on computed values. (As a result, it is not necessary to define, for example, how to compare a <length> value of 15pt with 5em since such values will be resolved to their canonical unit before being passed to any of the above procedures.)

The host syntax defines how relative values (such as percentages or em units) are resolved in <comparison-operand>. When <condition> is used in a declaration, these relative values resolve in the same way as regular values in the declaration property.

Note: Why are we using = for equality and not ':' as is established in [css-conditional-4] already? Because a lot of third party code (syntax highlighters etc) assumes that colons separate declarations and would break. Also, `foo: bar` establishes a key-value pair, whereas in equality comparisons the two operands are of equal weight, and do not establish a key-value pair.

Do we need a "not equals" operator or is 'not(op1 = op2)' sufficient?

The <condition> is resolved at computed value time, though its calculation tree may be simplified earlier.

2.2.1. Computed Value

The computed value of a <condition> value is its calculation tree simplified, using all the information available at computed value time. (Such as the em to px ratio, how to resolve percentages etc.)

Where percentages are not resolved at computed-value time, they are not resolved in <condition>.

The calculation tree is again simplified at used value time; with used value time information, a <condition> always simplifies down to a single <boolean-constant>.

Define these concepts for comparisons (currently they point to calc())

3. Inline conditionals: The if() function

The if() function allows authors to set a property value (or parts thereof) to different values based on certain conditions.

<if()> = if( <condition>, <consequent>, <antecedent>? )
<consequent> = <declaration-value>
<antecedent> = <declaration-value>

How can authors specify consequents or antecedents that include commas? Alternative syntax that addresses this, though may be hard to read when consequent/antecedent are keywords:

<if()>  = if( <condition> then <consequent> [else <antecedent>]?)
<consequent> = <declaration-value>
<antecedent> = <declaration-value>

flex-flow: if(100vw > 500px, row, column);

When <antecedent> is omitted, it defaults to ' ' (empty value).

background: if(var(--raised) = on, linear-gradient(white, transparent)) hsl(200 100% 50%);

font-size: if(var(--size) = small, 2em)
           if(var(--size) = medium, 3em)
           if(var(--size) = large, 5em)

If after substitution of all if() values in a property value, the resulting declaration is invalid, the property containing the if() function is invalid at computed-value time.

When if() is used in shorthands, it has the same behavior as the var() function, for the same reasons.

How to disambiguate when used in a place where arguments are disambiguated by type? Unlike var(), this cannot just be resolved at substitution, because we need to be able to interpret the values to compute the condition and perform the substitution accordingly. One way to address this would be to mandate that both <consequent> and <antecedent> need to be of the same type. How much does that limit use cases?

4. Privacy and Security Considerations

This specification defines a purely author-level mechanism for specifying conditionals on styling information within a page they control. As such, there are no new privacy considerations.