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.)

For example, 5px > 4deg is an invalid condition because the first operand is a <length> and the second is an <angle>.

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.

For example, ''(5px > 4px) and (1em = 2em)'' can be simplified to (true) and (false) and then to false at parse time and serialized as such.

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>

Authors can write inline media queries by comparing viewport and absolute units:

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

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

This allows authors to use conditionals to toggle certain parts of a value and even "compose" a property value from a series of conditionals:

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

This also allows authors to write multiple branches for the same value side by side instead of deeply nesting them:

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.

Conformance

Document conventions

Conformance requirements are expressed with a combination of descriptive assertions and RFC 2119 terminology. The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in the normative parts of this document are to be interpreted as described in RFC 2119. However, for readability, these words do not appear in all uppercase letters in this specification.

All of the text of this specification is normative except sections explicitly marked as non-normative, examples, and notes. [RFC2119]

Examples in this specification are introduced with the words “for example” or are set apart from the normative text with class="example", like this:

Informative notes begin with the word “Note” and are set apart from the normative text with class="note", like this:

Advisements are normative sections styled to evoke special attention and are set apart from other normative text with <strong class="advisement">, like this: UAs MUST provide an accessible alternative.

Conformance classes

A style sheet is conformant to this specification if all of its statements that use syntax defined in this module are valid according to the generic CSS grammar and the individual grammars of each feature defined in this module.

A renderer is conformant to this specification if, in addition to interpreting the style sheet as defined by the appropriate specifications, it supports all the features defined by this specification by parsing them correctly and rendering the document accordingly. However, the inability of a UA to correctly render a document due to limitations of the device does not make the UA non-conformant. (For example, a UA is not required to render color on a monochrome monitor.)

An authoring tool is conformant to this specification if it writes style sheets that are syntactically correct according to the generic CSS grammar and the individual grammars of each feature in this module, and meet all other conformance requirements of style sheets as described in this module.

Partial implementations

So that authors can exploit the forward-compatible parsing rules to assign fallback values, CSS renderers must treat as invalid (and ignore as appropriate) any at-rules, properties, property values, keywords, and other syntactic constructs for which they have no usable level of support. In particular, user agents must not selectively ignore unsupported component values and honor supported values in a single multi-value property declaration: if any value is considered invalid (as unsupported values must be), CSS requires that the entire declaration be ignored.

Implementations of Unstable and Proprietary Features

Non-experimental implementations

Once a specification reaches the Candidate Recommendation stage, non-experimental implementations are possible, and implementors should release an unprefixed implementation of any CR-level feature they can demonstrate to be correctly implemented according to spec.

To establish and maintain the interoperability of CSS across implementations, the CSS Working Group requests that non-experimental CSS renderers submit an implementation report (and, if necessary, the testcases used for that implementation report) to the W3C before releasing an unprefixed implementation of any CSS features. Testcases submitted to W3C are subject to review and correction by the CSS Working Group.

Further information on submitting testcases and implementation reports can be found from on the CSS Working Group’s website at http://www.w3.org/Style/CSS/Test/. Questions should be directed to the public-css-testsuite@w3.org mailing list.

CSS Conditional Values Module Level 1

Abstract

Status of this document