[css-values-4] Write examples for min/max/clamp, and improve existing examples for calc().

Author: tabatkins

css-values-4/Overview.bs

@@ -20,6 +20,9 @@ spec: css-backgrounds-3; type: type; text: <position>
 spec: css2; type: property; text: border-collapse
 spec: css-color-4; type: value; text: currentcolor
 spec: css-cascade-4; type: at-rule; text: @import
+spec: css-sizing-3; type: property;
+	text: min-width
+	text: box-sizing
 </pre>
 <style>
 code, small { white-space: nowrap }
@@ -1633,59 +1636,90 @@ Mathematical Expressions: ''calc()'', ''min()'', ''max()'', and ''clamp()''</h3>
 	that evaluate to a valid argument type (like <<length>>).
 
 	<div class="example">
-		<pre>
+
+		[=Math functions=] can be used to combine value that use different units.
+		In this example the author wants the <em>margin box</em> of each section
+		to take up 1/3 of the space,
+		so they start with ''100%/3'',
+		then subtract the element's borders and margins.
+		('box-sizing' can automatically achieve this effect for borders and padding,
+		but a [=math function=] is needed if you want to include margins.)
+
+		<pre class=lang-css>
 		section {
 		  float: left;
 		  margin: 1em; border: solid 1px;
 		  width: calc(100%/3 - 2*1em - 2*1px);
 		}
 		</pre>
-	</div>
 
-	<div class="example">
-		<pre>
-		p {
-		  margin: calc(1rem - 2px) calc(1rem - 1px);
+		Similar, in this example the gradient will show a color transition
+		only in the first and last ''20px'' of the element:
+
+		<pre class=lang-css>
+		.fade {
+			background-image: linear-gradient(silver 0%, white 20px,
+			                                  white calc(100% - 20px), silver 100%);
 		}
 		</pre>
 	</div>
 
 	<div class="example">
-		The following sets the 'font-size' so that exactly 40em fits within the viewport,
+
+		[=Math functions=] can also be useful just to express values
+		in a more natural, readable fashion,
+		rather than as an obscure decimal.
+		For example, the following sets the 'font-size' so that exactly 35em fits within the viewport,
 		ensuring that roughly the same amount of text always fills the screen no matter the screen size.
 
-		<pre>
+		<pre class=lang-css>
 		:root {
-			font-size: calc(100vw / 40);
+			font-size: calc(100vw / 35);
 		}
 		</pre>
 
-		If the rest of the design is specified using the ''rem'' unit,
-		the entire layout will scale to match the viewport width.
+		Functionality-wise, this is identical to just writing ''font-size: 2.857vw'',
+		but then the intent
+		(that ''35em'' fills the viewport)
+		is much less clear to someone reading the code;
+		the later reader will have to reverse the math themselves
+		to figure out that 2.857 is meant to approximate 100/35.
 	</div>
 
-	<div class='example'>
-		The following example stacks two centered background images,
-		with one offset slightly from the other.
+	<div class="example">
 
-		<pre>
-		.foo {
-			background: url(top.png), url(bottom.png);
-			background-repeat: no-repeat;
-			background-position: calc(50% + 20px) calc(50% + 20px), 50% 50%;
+		''min()'', ''max()'', and ''clamp()'' can be used to make sure a value doesn't exceed a "safe" limit:
+		For example, "responsive type" that sets 'font-size' with viewport units
+		might still want a minimum size to ensure readability:
+
+		<pre class=lang-css>
+		.type {
+			/* Set font-size to 10x the average of vw and vh,
+			   but don't let it go below 12px. */
+			font-size: max(10 * (1vw + 1vh) / 2, 12px);
 		}
 		</pre>
-	</div>
 
-	<div class='example'>
-		This example shows how to place color-stops on a gradient an equal distance from either end.
+		Note: Full math expressions are allowed in each of the arguments;
+		there's no need to nest a ''calc()'' inside!
+		You can also provide more than two arguments,
+		if you have multiple constraints to apply.
+	</div>
 
-		<pre>
-		.foo {
-			background-image: linear-gradient(to right, silver,
-			                                            white 50px,
-			                                            white calc(100% - 50px),
-			                                            silver);
+	<div class="example">
+		An occasional point of confusion when using ''min()''/''max()''
+		is that you use ''max()'' to impose a minimum value on something
+		(that is, properties like 'min-width' effectively use ''max()''),
+		and ''min()'' to impose a maximum value on something;
+		it's easy to accidentally reach for the opposite function
+		and try to use ''min()'' to add a minimum size.
+		Using ''clamp()'' can make the code read more naturally,
+		as the value is nestled between its minimum and maximum:
+
+		<pre class=lang-css>
+		.type {
+			/* Force the font-size to stay between 12px and 100px */
+			font-size: clamp(12px, 10 * (1vw + 1vh) / 2, 100px);
 		}
 		</pre>
 	</div>