From 3b10e5ed46ccbfa10584cd60f7c307e5b261ca35 Mon Sep 17 00:00:00 2001
From: Tab Atkins-Bittner <jackalmage@gmail.com>
Date: Wed, 9 May 2018 17:23:08 -0700
Subject: [PATCH] [css-values-4] Add clamp(), per WG resolution. Fixes #2519.

---
 css-values-4/Overview.bs | 44 +++++++++++++++++++++++++++++++++-------
 1 file changed, 37 insertions(+), 7 deletions(-)

diff --git a/css-values-4/Overview.bs b/css-values-4/Overview.bs
index e34d6f7cdce..6bccf5f5869 100644
--- a/css-values-4/Overview.bs
+++ b/css-values-4/Overview.bs
@@ -1585,10 +1585,10 @@ Functional Notations</h2>
 -->
 
 <h3 id="calc-notation">
-Mathematical Expressions: ''calc()'', ''min()'', and ''max()''</h3>
+Mathematical Expressions: ''calc()'', ''min()'', ''max()'', and ''clamp()''</h3>
 
 	The <dfn export lt="math function">math functions</dfn>,
-	<dfn>calc()</dfn>, <dfn>min()</dfn>, and <dfn>max()</dfn>,
+	<dfn>calc()</dfn>, <dfn>min()</dfn>, <dfn>max()</dfn>, and <dfn>clamp()</dfn>
 	allow mathematical expressions
 	with addition (''+''), subtraction (''-''), multiplication (''*''), and division (''/'')
 	to be used as component values.
@@ -1596,7 +1596,11 @@ Mathematical Expressions: ''calc()'', ''min()'', and ''max()''</h3>
 	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.
+	comma-separated calculation it contains;
+	a ''clamp()'' function represents its central calculation,
+	clamped according to its min and max calculations
+	(given ''clamp(MIN, VAL, MAX)'',
+	it is resolved exactly identically to ''max(MIN, min(VAL, MAX))'').
 
 	A [=math function=] can be used wherever
 	<<length>>,
@@ -1672,6 +1676,31 @@ Mathematical Expressions: ''calc()'', ''min()'', and ''max()''</h3>
 		</pre>
 	</div>
 
+	<div class=note>
+		Note that ''clamp()'',
+		matching CSS conventions elsewhere,
+		has its minimum value "win" over its maximum value
+		if the two are in the "wrong order".
+		That is, ''clamp(100px, ..., 50px)''
+		will resolve to ''100px'',
+		exceeding its stated "max" value.
+
+		If alternate resolution mechanics are desired
+		they can be achieved by combining ''clamp()'' with ''min()'' or ''max()'':
+
+		: To have MAX win over MIN:
+		::
+			''clamp(min(MIN, MAX), VAL, MAX)''.
+			If you want to avoid repeating the MAX calculation,
+			you can just reverse the nesting of functions that ''clamp()'' is defined against--
+			''min(MAX, max(MIN, VAL))''.
+
+		: To have MAX and MIN "swap" when they're in the wrong order:
+		::
+			''clamp(min(MIN, MAX), VAL, max(MIN, MAX))''.
+			Unfortunately, there's no easy way to do this without repeating the MIN and MAX terms.
+	</div>
+
 
 <h4 id='calc-syntax'>
 Syntax</h4>
@@ -1679,9 +1708,10 @@ Syntax</h4>
 	The syntax of a [=math function=] is:
 
 	<pre class='prod'>
-	<<calc()>> = calc( <<calc-sum>> )
-	<<min()>>  = min( <<calc-sum>># )
-	<<max()>>  = max( <<calc-sum>># )
+	<<calc()>>  = calc( <<calc-sum>> )
+	<<min()>>   = min( <<calc-sum>># )
+	<<max()>>   = max( <<calc-sum>># )
+	<<clamp()>> = clamp( <<calc-sum>>#{3} )
 	<dfn>&lt;calc-sum></dfn> = <<calc-product>> [ [ '+' | '-' ] <<calc-product>> ]*
 	<dfn>&lt;calc-product></dfn> = <<calc-value>> [ [ '*' | '/' ] <<calc-value>> ]*
 	<dfn>&lt;calc-value></dfn> = <<number>> | <<dimension>> | <<percentage>> | ( <<calc-sum>> )
@@ -1788,7 +1818,7 @@ Type Checking</h4>
 
 	* The [=CSSNumericValue/type=] of a ''calc()'' expression
 		is the [=CSSNumericValue/type=] of its contained expression.
-		The [=CSSNumericValue/type=] of a ''min()'' or ''max()'' expression
+		The [=CSSNumericValue/type=] of a ''min()'', ''max()'', or ''clamp()'' expression
 		is the result of [=add two types|adding the types=]
 		of its comma-separated expressions.
 		If the result is failure,