[css-values] Define how to serialize calc() values.

Author: tabatkins

css-values/Overview.bs

@@ -1301,6 +1301,52 @@ Range Checking</h4>
 		</pre>
 	</div>
 
+<h4 id='calc-serialize'>
+Serialization</h4>
+
+	To serialize a ''calc()'' value:
+
+	1. Simplify the expression by
+		resolving all multiplications and divisions,
+		and combining compatible units.
+		(Which units are compatible can vary based on what stage of the value computation pipeline it's in.
+		For example, as a specified value, ''px'' and ''em'' are incompatible;
+		as a computed value, they're compatible.)
+
+		The result must be a summation of unique incompatible units.
+		(Terms with a value of zero <strong>must</strong> be preserved in this summation.)
+
+	2. If the result is a single value,
+		serialize as that value,
+		discarding the ''calc()'' wrapper.
+
+	3. Otherwise, serialize as a ''calc()'' containing the summation,
+		with the units ordered <a>ASCII case-insensitive</a> alphabetically,
+		numbers coming before all units,
+		and percentages coming after all units.
+
+	<div class="example">
+		For example, ''calc(20px + 30px)'' would first simplify to a single ''px'' value,
+		then serialize as just ''50px''.
+
+		A value like ''calc(20px + 0%)'' would serialize as ''calc(20px + 0%)'',
+		maintaining both terms in the serialized value.
+		(It's important to maintain zero-valued terms,
+		so the ''calc()'' doesn't suddenly "change shape" in the middle of a transition
+		when one of the values happens to have a zero value temporarily.
+		This also removes the need to "pick a unit" when all the terms are zero.)
+
+		A value like ''calc(20px + 2em)'' would serialize as ''calc(2em + 20px)'' as a specified value
+		(maintaining both units as they're incompatible at specified-value time,
+		but sorting them alphabetically),
+		or as something like ''52px'' as a computed value
+		(''em'' values are converted to absolute lengths at computed-value time,
+		so assuming ''1em'' = ''16px'',
+		they combine into ''52px'',
+		which then drops the ''calc()'' wrapper.)
+	</div>
+
+
 <h3 id="toggle-notation">
 Toggling Between Values: ''toggle()''</h3>
 

css-values/Overview.html

@@ -92,7 +92,7 @@
    <h1 class="p-name no-ref" id="title">CSS Values and Units Module Level 3</h1>
 
    <h2 class="no-num no-toc no-ref heading settled" id="subtitle"><span class="content">Editor’s Draft,
-    <time class="dt-updated" datetime="2015-06-08">8 June 2015</time></span></h2>
+    <time class="dt-updated" datetime="2015-06-25">25 June 2015</time></span></h2>
 
    <div data-fill-with="spec-metadata">
     <dl>
@@ -454,6 +454,8 @@ <h2 class="no-num no-toc no-ref heading settled" id="contents"><span class="cont
 Computed Value</span></a>
         <li><a href="#calc-range"><span class="secno">8.1.4</span> <span class="content">
 Range Checking</span></a>
+        <li><a href="#calc-serialize"><span class="secno">8.1.5</span> <span class="content">
+Serialization</span></a>
        </ul>
       <li><a href="#toggle-notation"><span class="secno">8.2</span> <span class="content">
 Toggling Between Values: <span class="css">toggle()</span></span></a>
@@ -2687,6 +2689,72 @@ <h4 class="heading settled" data-level="8.1.4" id="calc-range"><span class="secn
    </div>
 
 
+   <h4 class="heading settled" data-level="8.1.5" id="calc-serialize"><span class="secno">8.1.5. </span><span class="content">
+Serialization</span><a class="self-link" href="#calc-serialize"></a></h4>
+
+
+   <p>To serialize a <a class="css" data-link-type="maybe" href="#funcdef-calc">calc()</a> value:</p>
+
+
+   <ol>
+    <li data-md="">
+     <p>Simplify the expression by
+resolving all multiplications and divisions,
+and combining compatible units.
+(Which units are compatible can vary based on what stage of the value computation pipeline it’s in.
+For example, as a specified value, <span class="css">px</span> and <span class="css">em</span> are incompatible;
+as a computed value, they’re compatible.)</p>
+     
+
+
+     <p>The result must be a summation of unique incompatible units.
+(Terms with a value of zero <strong>must</strong> be preserved in this summation.)</p>
+     
+
+
+    <li data-md="">
+     <p>If the result is a single value,
+serialize as that value,
+discarding the <a class="css" data-link-type="maybe" href="#funcdef-calc">calc()</a> wrapper.</p>
+     
+
+
+    <li data-md="">
+     <p>Otherwise, serialize as a <a class="css" data-link-type="maybe" href="#funcdef-calc">calc()</a> containing the summation,
+with the units ordered <a data-link-type="dfn" href="http://dom.spec.whatwg.org/#ascii-case_insensitive">ASCII case-insensitive</a> alphabetically,
+numbers coming before all units,
+and percentages coming after all units.</p>
+     
+</ol>
+	
+   <div class="example" id="example-65075dff"><a class="self-link" href="#example-65075dff"></a>
+		For example, <span class="css">calc(20px + 30px)</span> would first simplify to a single <span class="css">px</span> value,
+		then serialize as just <span class="css">50px</span>.
+
+
+    <p>A value like <span class="css">calc(20px + 0%)</span> would serialize as <span class="css">calc(20px + 0%)</span>,
+		maintaining both terms in the serialized value.
+		(It’s important to maintain zero-valued terms,
+		so the <a class="css" data-link-type="maybe" href="#funcdef-calc">calc()</a> doesn’t suddenly "change shape" in the middle of a transition
+		when one of the values happens to have a zero value temporarily.
+		This also removes the need to "pick a unit" when all the terms are zero.)</p>
+    
+
+
+    <p>A value like <span class="css">calc(20px + 2em)</span> would serialize as <span class="css">calc(2em + 20px)</span> as a specified value
+		(maintaining both units as they’re incompatible at specified-value time,
+		but sorting them alphabetically),
+		or as something like <span class="css">52px</span> as a computed value
+		(<span class="css">em</span> values are converted to absolute lengths at computed-value time,
+		so assuming <span class="css">1em</span> = <span class="css">16px</span>,
+		they combine into <span class="css">52px</span>,
+		which then drops the <a class="css" data-link-type="maybe" href="#funcdef-calc">calc()</a> wrapper.)</p>
+    
+	
+   </div>
+
+
+
    <h3 class="heading settled" data-level="8.2" id="toggle-notation"><span class="secno">8.2. </span><span class="content">
 Toggling Between Values: <a class="css" data-link-type="maybe" href="#funcdef-toggle">toggle()</a></span><a class="self-link" href="#toggle-notation"></a></h3>