CSS Conditional Values Module Level 1

Unofficial Proposal Draft,

More details about this document
This version:
https://drafts.csswg.org/css-conditional-values-1/
Issue Tracking:
CSSWG Issues Repository
Inline In Spec
Editor:
Lea Verou (Invited Expert)
Suggest an Edit for this Spec:
GitHub Editor
Not Ready For Implementation

This spec is not yet ready for implementation. It exists in this repository to record the ideas and promote discussion.

Before attempting to implement this spec, please contact the CSSWG at www-style@w3.org.


Abstract

This module explores additions to CSS to enable conditional values.

CSS is a language for describing the rendering of structured documents (such as HTML and XML) on screen, on paper, etc.

Status of this document

This section describes the status of this document at the time of its publication. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at https://www.w3.org/TR/.

Please send feedback by filing issues in GitHub (preferred), including the spec code “css-conditional-values” in the title, like this: “[css-conditional-values] …summary of comment…”. All issues and comments are archived. Alternately, feedback can be sent to the (archived) public mailing list www-style@w3.org.

This document is governed by the 03 November 2023 W3C Process Document.

This document was produced by a group operating under the W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

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:

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:

This is an example of an informative example.

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

Note, this is an informative note.

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

Conformance to this specification is defined for three conformance classes:

style sheet
A CSS style sheet.
renderer
A UA that interprets the semantics of a style sheet and renders documents that use them.
authoring tool
A UA that writes a style sheet.

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

To avoid clashes with future stable CSS features, the CSSWG recommends following best practices for the implementation of unstable features and proprietary extensions to CSS.

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.

Index

Terms defined by this specification

Terms defined by reference

References

Normative References

[CSS-CASCADE-5]
Elika Etemad; Miriam Suzanne; Tab Atkins Jr.. CSS Cascading and Inheritance Level 5. URL: https://drafts.csswg.org/css-cascade-5/
[CSS-SYNTAX-3]
Tab Atkins Jr.; Simon Sapin. CSS Syntax Module Level 3. URL: https://drafts.csswg.org/css-syntax/
[CSS-VALUES-3]
Tab Atkins Jr.; Elika Etemad. CSS Values and Units Module Level 3. URL: https://drafts.csswg.org/css-values-3/
[CSS-VALUES-4]
Tab Atkins Jr.; Elika Etemad. CSS Values and Units Module Level 4. URL: https://drafts.csswg.org/css-values-4/
[CSS-VARIABLES-2]
CSS Custom Properties for Cascading Variables Module Level 2. Editor's Draft. URL: https://drafts.csswg.org/css-variables-2/
[CSS2]
Bert Bos; et al. Cascading Style Sheets Level 2 Revision 1 (CSS 2.1) Specification. URL: https://drafts.csswg.org/css2/
[MEDIAQUERIES-5]
Dean Jackson; et al. Media Queries Level 5. URL: https://drafts.csswg.org/mediaqueries-5/
[RFC2119]
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: https://datatracker.ietf.org/doc/html/rfc2119

Informative References

[CSS-CONDITIONAL-3]
David Baron; Elika Etemad; Chris Lilley. CSS Conditional Rules Module Level 3. URL: https://drafts.csswg.org/css-conditional-3/
[CSS-CONDITIONAL-4]
David Baron; Elika Etemad; Chris Lilley. CSS Conditional Rules Module Level 4. URL: https://drafts.csswg.org/css-conditional-4/
[MEDIAQUERIES-4]
Florian Rivoal; Tab Atkins Jr.. Media Queries Level 4. URL: https://drafts.csswg.org/mediaqueries-4/

Issues Index

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.
Do we need a "not equals" operator or is 'not(op1 = op2)' sufficient?
Define these concepts for comparisons (currently they point to calc())
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:
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?