Overview.bs

<pre class='metadata'>
Title: CSS Conditional Values Module Level 1
Shortname: css-conditional-values
Level: 1
Status: UD
ED: https://drafts.csswg.org/css-conditional-values-1/
Group: csswg
Work Status: exploring
Editor: Lea Verou, Invited Expert, http://lea.verou.me/about, w3cid 52258
Abstract: This module explores additions to CSS to enable conditional values.
Repository: w3c/csswg-drafts
Default Highlight: css
Inline Github Issues: title
Warning: Not Ready
</pre>

Introduction {#intro}
=====================

	<em>This section is not normative.</em>

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.


High level custom properties {#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`.


Relation between units of the same type {#relation-between-units}
---------------------------------------

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.

Value Definitions {#values}
---------------------------

	This specification follows the <a href="https://www.w3.org/TR/CSS2/about.html#property-defs">CSS property definition conventions</a> from [[!CSS2]]
	using the <a href="https://www.w3.org/TR/css-values-3/#value-defs">value definition syntax</a> from [[!CSS-VALUES-3]].
	Value types not defined in this specification are defined in CSS Values &amp; 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 <a>CSS-wide keywords</a> as their property value.
	For readability they have not been repeated explicitly.

Boolean data types {#boolean}
==============================

Boolean constants: ''true'' and ''false''  {#bool-constants}
--------------------------------------------------------------

<pre class="prod def">
	<dfn export>&lt;boolean-constant></dfn> = <dfn export>'true'</dfn> | <dfn export>'false'</dfn>
</pre>

Logical comparisons: The <<condition>> type {#condition}
---------------------------------------------

<pre class="prod def" nohighlight>
	<dfn>&lt;condition></dfn> = not <<condition-in-parens>>
	                     | <<condition-in-parens>> [ and <<condition-in-parens>> ]*
	                     | <<condition-in-parens>> [ or <<condition-in-parens>> ]*
	<dfn>&lt;condition-in-parens></dfn> = ( <<condition>> ) | <<atomic-condition>>
	<dfn>&lt;atomic-condition></dfn> = <<comparison-operand>> <<comparison-operator>> <<comparison-operand>> | <<boolean-constant>>
	<dfn>&lt;comparison-operand></dfn> = <<dimension>> | <<number>> | <<percentage>> | <<ident>>
	<dfn>&lt;comparison-operator></dfn> = [ '=' | '>=' | '>' | '<' | '<=' ]
</pre>

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

Issue: 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
<dfn export>invalid condition</dfn> and evaluates to unknown.

These operations are only defined on <a>computed values</a>.
(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 <a>canonical unit</a>
before being passed to any of the above procedures.)

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

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.

Issue: 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.

<div class=example>
	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.
</div>

<h4 id='condition-computed-value'>
Computed Value</h4>

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

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

Inline conditionals: The ''if()'' function {#if}
===========================================

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

<pre class="prod def">

<<if()>> = if( <<condition>>, <<consequent>>, <<antecedent>>? )
<dfn>&lt;consequent></dfn> = <<declaration-value>>
<dfn>&lt;antecedent></dfn> = <<declaration-value>>
</pre>

Issue: 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:

<pre class="prod def">
<<if()>>  = if( <<condition>> then <<consequent>> [else <<antecedent>>]?)
<<consequent>> = <<declaration-value>>
<<antecedent>> = <<declaration-value>>
</pre>

<div class=example>
	Authors can write inline media queries by comparing viewport and absolute units:

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

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

<div class=example>
	This allows authors to use conditionals to toggle certain parts
	of a value and even "compose" a property value from a series of conditionals:

	<pre>background: if(var(--raised) = on, linear-gradient(white, transparent)) hsl(200 100% 50%);</pre>
</div>
<div class=example>
	This also allows authors to write multiple branches for the same value
	side by side instead of deeply nesting them:

	<pre>
		font-size: if(var(--size) = small, 2em)
		           if(var(--size) = medium, 3em)
		           if(var(--size) = large, 5em)
	</pre>
</div>

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

When ''if()'' is used in shorthands, it has the same
<a href="../css-variables/#variables-in-shorthands">behavior</a>
as the ''var()'' function, for the same reasons.

Issue: 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?

Privacy and Security Considerations {#priv-sec}
===============================================

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.