[css-values-4] Add min()/max().

Author: tabatkins

css-values/Overview.bs

@@ -1583,14 +1583,20 @@ Functional Notations</h2>
 -->
 
 <h3 id="calc-notation">
-Mathematical Expressions: ''calc()''</h3>
+Mathematical Expressions: ''calc()'', ''min()'', and ''max()''</h3>
 
-	The <dfn>calc()</dfn> function allows mathematical expressions
+	The <dfn>math functions</dfn>,
+	<dfn>calc()</dfn>, <dfn>min()</dfn>, and <dfn>max()</dfn>,
+	allow mathematical expressions
 	with addition (''+''), subtraction (''-''), multiplication (''*''), and division (''/'')
 	to be used as component values.
-	The ''calc()'' expression represents the result of the mathematical calculation it contains,
-	using standard operator precedence rules.
-	It can be used wherever
+	A ''calc()'' function represents the result of the mathematical calculation it contains,
+	using standard operator precedence rules;
+	a ''min()'' or ''max()'' function represents
+	the smallest (most negative) or largest (most positive), respectively,
+	comma-separated calculation it contains.
+
+	A [=math function=] can be used wherever
 	<<length>>,
 	<<frequency>>,
 	<<angle>>,
@@ -1599,8 +1605,10 @@ Mathematical Expressions: ''calc()''</h3>
 	<<number>>, or
 	<<integer>>
 	values are allowed.
-	Components of a ''calc()'' expression can be literal values or
-	''attr()'' or ''calc()'' expressions.
+	Components of a [=math function=] can be literal values,
+	other [=math functions=],
+	or other expressions, such as ''attr()'',
+	that evaluate to a valid argument type (like <<length>>).
 
 	<div class="example">
 		<pre>
@@ -1664,10 +1672,12 @@ Mathematical Expressions: ''calc()''</h3>
 <h4 id='calc-syntax'>
 Syntax</h4>
 
-	The syntax of a ''calc()'' function is:
+	The syntax of a [=math function=] is:
 
 	<pre class='prod'>
 	<<calc()>> = calc( <<calc-sum>> )
+	<<min()>>  = min( <<calc-sum>># )
+	<<max()>>  = max( <<calc-sum>># )
 	<dfn>&lt;calc-sum></dfn> = <<calc-product>> [ [ '+' | '-' ] <<calc-product>> ]*
 	<dfn>&lt;calc-product></dfn> = <<calc-value>> [ '*' <<calc-value>> | '/' <<calc-number-value>> ]*
 	<dfn>&lt;calc-value></dfn> = <<number>> | <<dimension>> | <<percentage>> | ( <<calc-sum>> )
@@ -1676,38 +1686,53 @@ Syntax</h4>
 	<dfn>&lt;calc-number-value></dfn> = <<number>> | ( <<calc-number-sum>> )
 	</pre>
 
-	In addition, <a href="https://www.w3.org/TR/css-syntax/#whitespace">white space</a>
+	In addition, [=whitespace=]
 	is required on both sides of the ''+'' and ''-'' operators.
 	(The ''*'' and ''/'' operaters can be used without white space around them.)
 
-	UAs must support ''calc()'' expressions of at least 20 terms,
+	UAs must support [=math function=] expressions of at least 20 terms,
 	where each <code>NUMBER</code>, <code>DIMENSION</code>, or <code>PERCENTAGE</code> is a term.
-	If a ''calc()'' expression contains more than the supported number of terms,
+	If a [=math function=] contains more than the supported number of terms,
 	it must be treated as if it were invalid.
 
 
 <h4 id='calc-type-checking'>
 Type Checking</h4>
 
-	A math expression has a <dfn>resolved type</dfn>, which is one of
+	A [=math function=] has a <dfn>resolved type</dfn>, which is one of
 	<<length>>,
 	<<frequency>>,
 	<<angle>>,
 	<<time>>,
 	<<percentage>>,
 	<<number>>, or
 	<<integer>>.
-	The <a>resolved type</a> must be valid for where the expression is placed;
+	The <a>resolved type</a> must be valid for where the [=math function=] is placed;
 	otherwise, the expression is invalid.
-	The <a>resolved type</a> of the expression is determined by the types of the values it contains.
-	<<number-token>>s are of type <<number>> or <<integer>>.
-	A <<dimension-token>>’s type is given by its unit
-	(''cm'' is <<length>>, ''deg'' is <<angle>>, etc.).
-	An ''attr()'' expression's type is given by its <<type-or-unit>> argument.
+
+	The <a>resolved type</a> of a [=math function=] is determined by the values and calculations it contains:
+
+	* <<number-token>>s are of type <<number>> or <<integer>>.
+	* A <<dimension-token>>’s type is given by its unit
+		(''cm'' is <<length>>, ''deg'' is <<angle>>, etc.).
+	* Functions’ types are defined by their specification
+		(nested ''calc()'' has its type determined by its own contents,
+		''attr()''’s type is determined by its <<type-or-unit>> argument,
+		etc).
+	* Larger calculations’ types are determined by the types of their arguments
+		and the rules for their operation,
+		as defined below.
+
+	A ''calc()'' expression's <a>resolved type</a> is the <a>resolved type</a> of the calculation it contains.
+	The <a>resolved type</a> of a ''min()'' or ''max()'' expression
+	is the <a>resolved type</a> of any of the calculations it contains.
+	If a ''min()'' or ''max()'' expression's arguments have different <a>resolved types</a>,
+	the expression is invalid.
 
 	Note: Because <<number-token>>s are always interpreted as <<number>>s or <<integer>>s,
-	"unitless 0" <<length>>s aren't supported in ''calc()''.
+	"unitless 0" <<length>>s aren't supported in [=math functions=].
 	That is, ''width: calc(0 + 5px);'' is invalid,
+	because it's trying to add a <<number>> to a <<length>>,
 	even though both ''width: 0;''
 	and ''width: 5px;''
 	are valid.
@@ -1778,38 +1803,42 @@ Type Checking</h4>
 	(as purely-numeric expressions can be evaluated without any additional
 	information at parse time).
 
-	Note: Algebraic simplifications do not affect the validity of the ''calc()'' expression or its resolved type.
+	Note: Algebraic simplifications do not affect the validity of a [=math function=] or its resolved type.
 	For example, ''calc(5px - 5px + 10s)'' and ''calc(0 * 5px + 10s)'' are both invalid
 	due to the attempt to add a length and a time.
 
 <h4 id='calc-computed-value'>
 Computed Value</h4>
 
-	The computed value of a ''calc()'' expression is the expression
+	The computed value of a ''calc()'' function is the expression
 	with all components computed.
+	The computed value of a ''min()'' or ''max()'' function
+	is the comma-separated list of expressions,
+	with each expression having all its component computed.
 
 	Where percentages are not resolved at computed-value time,
-	they are not resolved in ''calc()'' expressions,
+	they are not resolved in [=math functions=],
 	e.g. ''calc(100% - 100% + 1em)'' resolves to ''calc(1em + 0%)'',
 	not to ''1em''.
 	If there are special rules for computing percentages in a value
 	(e.g. <a href="https://www.w3.org/TR/CSS21/visudet.html#the-height-property">the <css>height</css> property</a>),
-	they apply whenever a ''calc()'' expression contains percentages.
+	they apply whenever a [=math function=] contains percentages.
 
 	<div class=note>
 		Note: The serialization rules do not preserve the structure of the computation,
 		so implementations can simplify the expressions
 		further than what is required here
 		when storing the values internally;
-		in particular, all ''calc()'' expressions can be reduced
+		in particular, all [=math function=] expressions can be reduced
 		to a sum of a <<number>>, a <<percentage>>, and some <<dimension>>s,
 		eliminating all multiplication or division,
 		and combining terms with identical units.
 
 		At this time, all units can be absolutized
 		to a single unit per type at computed-value time,
-		so at that point the ''calc()'' expression can be reduced
-		to just a <<number>>, a <<percentage>>, and a single absolute <<dimension>> of the appropriate type.
+		so at that point the [=math function=] can be reduced
+		to just a <<number>>, a <<percentage>>, and a single absolute <<dimension>> of the appropriate type,
+		per expression.
 	</div>
 
 	<div class='example'>
@@ -1848,7 +1877,7 @@ Computed Value</h4>
 <h4 id='calc-range'>
 Range Checking</h4>
 
-	Parse-time range-checking of values is not performed within ''calc()'',
+	Parse-time range-checking of values is not performed within [=math functions=],
 	and therefore out-of-range values do not cause the declaration to become invalid.
 	However, the used value resulting from an expression
 	must be clamped to the range allowed in the target context.
@@ -1876,33 +1905,76 @@ Serialization</h4>
 
 	Issue: This section is still <a href="https://lists.w3.org/Archives/Member/w3c-css-wg/2016AprJun/0239.html">under discussion</a>.
 
-	To serialize a ''calc()'' value:
+	<div algorithm="serialize a calc() value">
+		To <dfn>serialize a ''calc()'' value</dfn>
+
+		1. [=Simplify the expression=] inside of it.
 
-	1. Simplify the expression by:
+		2. If this simplification process results in only a single value
+			(one <<number>>, one <<dimension>>, or one <<percentage>>),
+			and the value being serialized is a <a>computed value</a> or later,
+			serialize it just as that one value,
+			without the ''calc()'' wrapper.
+			If this value is outside the allowed range for the context,
+			it must be clamped to the nearest allowed value.
+
+		3. Otherwise,
+			[=serialize the summation=],
+			prefix the result with "calc("
+			and suffix it with ")",
+			then return it.
+	</div>
 
-		* Replacing nested ''calc()'' values with parentheses containing their contents
-		* Resolving all multiplications and divisions
-		* Combining identical units
+	<div algorithm="serialize a min()/max() value">
+		To <dfn lt="serialize a min() value|serialize a max() value">serialize a ''min()'' or ''max()'' value</dfn>:
+
+		1. For each comma-separated expression inside of it,
+			[=simplify the expression=].
+
+		2. Let |s| initially be "min(" or "max(", as appropriate.
+
+		3. [=serialize the summation|Serialize each summation=],
+			then join them into a single string,
+			with ", " between each term.
+			Append the result to |s|.
+
+		4. Append ")" to |s|,
+			then return it.
+	</div>
+
+	<div algorithm="simplify an expression">
+		To <dfn lt="simplify an expression | simplify the expression" for="math function">simplify an expression</dfn>:
+
+		1. Replace any ''calc()'' values with parentheses containing their contents.
+		2. Resolve all multiplications and divisions.
+		3. Combine identical units.
+		4. Recurse into ''min()'' or ''max()'' values.
+		5. Return the result.
 
 		Note: The value-computation process can transform disparate units into identical ones.
 		For example, ''em'' and ''px'' are obviously different at specified-value time,
 		but at computed-value time they're both absolutized to ''px''.
 
-		The result must be a summation of unique units.
+		The result must be a summation of unique units and/or [=math functions=].
 		(Terms with a value of zero <strong>must</strong> be preserved in this summation.)
+	</div>
 
-	2. If this simplification process results in only a single value
-		(one <<number>>, one <<dimension>>, or one <<percentage>>),
-		and the value being serialized is a <a>computed value</a> or later,
-		serialize it just as that one value,
-		without the ''calc()'' wrapper.
-		If this value is outside the allowed range for the context,
-		it must be clamped to the nearest allowed value.
-
-	3. Otherwise, serialize as a ''calc()'' containing the summation,
-		with the units ordered <a>ASCII case-insensitive</a> alphabetically,
-		the number (if present) coming before all units,
-		and the percentage (if present) coming after all units.
+	<div algorithm="serialize a summation">
+		To <dfn lt="serialize a summation|serialize the summation" for="math function">serialize a summation</dfn>:
+
+		1. Sort the terms in the following order:
+
+			1. The number, if present
+			2. The dimensions, ordered by their units <a>ASCII case-insensitive</a> alphabetically
+			3. The percentage, if present
+			4. The ''min()'' and ''max()'' functions,
+				in the order they appeared in the original expression.
+
+		2. Serialize all the terms,
+			then join them into a single string,
+			with " + " between each term.
+			Return the result.
+	</div>
 
 	<div class="example">
 		For example, ''calc(20px + 30px)'' would serialize as ''calc(50px)'' as a specified value,