[css-values-4][css-transitions-1][web-animations-1] Define interpolation and animation of basic value types. r=birtles

Author: fantasai

css-values-4/Overview.bs

@@ -339,6 +339,101 @@ Property value examples</h3>
 		</table>
 	</div>
 
+<h2 id="combining-values">
+Combining Values: Interpolation, Addition, and Accumulation</h2>
+
+	Some procedures, for example
+	<a href="https://www.w3.org/TR/css-transitions/">transitions</a>
+	and <a href="https://www.w3.org/TR/css-animations/">animations</a>,
+	combine two CSS property values.
+	The following combining operations--
+	on the two <a>computed values</a> <var>V<sub>a</sub></var> and <var>V<sub>B</sub></var>
+	yielding the <a>computed value</a> <var>V<sub>result</sub></var>--
+	are defined:
+
+	<dl export>
+		<dt><dfn id="interpolation" lt="interpolation | interpolate | value interpolation">interpolation</dfn>
+		<dd>
+			Given two property values
+			<var>V<sub>a</sub></var> and <var>V<sub>B</sub></var>,
+			produces an intermediate value
+			<var>V<sub>result</sub></var>
+			at a distance of <var>p</var>
+			along the interval between
+			<var>V<sub>a</sub></var> and <var>V<sub>a</sub></var>
+			such that <var>p</var> = 0 produces <var>V<sub>a</sub></var>
+			and <var>p</var> = 1 produces <var>V</var><sub>end</sub>.
+
+			The range of <var>p</var> is (&minus;&infin;, &infin;)
+			due to the effect of <a>timing functions</a>.
+			As a result, this procedure must also define
+			extrapolation behavior for <var>p</var> outside [0, 1].
+
+		<dt><dfn id="addition" lt="value addition" local-lt="add | addition">addition</dfn>
+		<dd>
+			Given two property values
+			<var>V<sub>a</sub></var> and <var>V<sub>B</sub></var>,
+			returns the sum of the two properties,
+			<var>V</var><sub>result</sub>.
+			For addition that is not commutative
+			(for example, matrix multiplication)
+			<var>V<sub>a</sub></var> represents
+			the first term of the operation and
+			<var>V<sub>B</sub></var> represents
+			the second.
+
+			Note: While <a>addition</a>
+			can often be expressed
+			in terms of the same weighted sum function
+			used to define <a>interpolation</a>,
+			this is not always the case.
+			For example, interpolation of transform matrices involves
+			decomposing and interpolating the matrix components
+			whilst addition relies on matrix multiplication.
+
+		<dt><dfn id="accumulation" lt="value accumulation" local-lt="accumulate | accumulation">accumulation</dfn>
+		<dd>
+			Given two property values
+			<var>V<sub>a</sub></var> and <var>V<sub>B</sub></var>,
+			returns the result, <var>V<sub>result</sub></var>,
+			of combining the two operands
+			such that <var>V<sub>B</sub></var>
+			is treated as a <em>delta</em> from <var>V<sub>a</sub></var>.
+			For accumulation that is not commutative
+			(for example, accumulation of mismatched transform lists)
+			<var>V<sub>a</sub></var> represents the first term of the operation
+			and <var>V<sub>B</sub></var> represents the second.
+
+			<div class="note">
+				Note: For many types of animation such as numbers or lengths,
+				<a>accumulation</a> is defined to be identical
+				to <a>addition</a>.
+
+				A common case where the definitions differ
+				is for list-based types
+				where <a>addition</a> may be defined as appending to a list
+				whilst <a>accumulation</a> may be defined
+				as component-based addition.
+				For example, the filter list values ''blur(2)'' and ''blur(3)'',
+				when <a>added</a> together would produce ''blur(2) blur(3)'',
+				but when <a>accumulated</a> would produce ''blur(5)''.
+			</div>
+	</dl>
+
+	These operations are only defined on <a>computed values</a>.
+	(As a result, it is not necessary to define, for example,
+	how to add 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.)
+
+	If a value type does not define a specific procedure for <a>addition</a>
+	or is defined as <dfn export>not additive</dfn>,
+	its <a>addition</a> operation is simply
+	<var>V<sub>result</sub></var> = <var>V<sub>a</sub></var>.
+
+	If a value types does not define a specific procedure for <a>accumulation</a>,
+	its <a>accumulation</a> operation is identical to <a>addition</a>.
+
 <h2 id="textual-values">
 Textual Data Types</h2>
 
@@ -687,6 +782,22 @@ Integers: the <<integer>> type</h3>
 	The first digit of an integer may be immediately preceded by <css>-</css> or <css>+</css>
 	to indicate the integer's sign.
 
+<h4 id="combine-integers">
+Combination of <<integer>></h4>
+
+	<a>Interpolation</a> of <<integer>> is defined as
+	<var>V</var><sub>result</sub> =
+		round((1 - <var>p</var>) &times; <var>V<sub>a</sub></var> +
+		<var>p</var> &times; <var>V<sub>b</sub></var>);
+	that is, interpolation happens in the real number space
+	as for <<number>>s, and the result is converted to an <<integer>>
+	by rounding to the nearest integer,
+	with values halfway between adjacent integers rounded towards positive infinity.
+
+	<a>Addition</a> of <<number>> is defined as
+	<var>V<sub>result</sub></var> =
+		<var>V<sub>a</sub></var> + <var>V<sub>b</sub></var>
+
 <!--
 ██    ██ ██     ██ ██     ██ ████████  ████████ ████████
 ███   ██ ██     ██ ███   ███ ██     ██ ██       ██     ██
@@ -719,6 +830,18 @@ Real Numbers: the <<number>> type</h3>
 	do not match <<zero>>;
 	only literal <<number-token>>s do.
 
+<h4 id="combine-numbers">
+Combination of <<number>></h4>
+
+	<a>Interpolation</a> of <<number>> is defined as
+	<var>V</var><sub>result</sub> =
+		(1 - <var>p</var>) &times; <var>V<sub>a</sub></var> +
+		<var>p</var> &times; <var>V<sub>b</sub></var>
+
+	<a>Addition</a> of <<number>> is defined as
+	<var>V<sub>result</sub></var> =
+		<var>V<sub>a</sub></var> + <var>V<sub>b</sub></var>
+
 <h3 id='dimensions'>
 Numbers with Units: <a>dimension</a> values</h3>
 
@@ -762,6 +885,20 @@ Compatible Units</h4>
 	as <a>compatible</a> with the relevant class of <a>dimensions</a>,
 	and canonicalize accordingly.
 
+<h4 id="combine-dimensions">
+Combination of Dimensions</h4>
+
+	<a>Interpolation</a> of <a>compatible</a> <a>dimensions</a>
+	(for example, two <<length>> values)
+	is defined as
+	<var>V</var><sub>result</sub> =
+		(1 - <var>p</var>) &times; <var>V<sub>a</sub></var> +
+		<var>p</var> &times; <var>V<sub>b</sub></var>
+
+	<a>Addition</a> of <a>compatible</a> <a>dimensions</a> is defined as
+	<var>V<sub>result</sub></var> =
+		<var>V<sub>a</sub></var> + <var>V<sub>b</sub></var>
+
 <!--
 █████   ██
 ██ ██  ██
@@ -793,6 +930,18 @@ Percentages: the <<percentage>> type</h3>
 	(e.g., the width of a <a>containing block</a>),
 	or something else.
 
+<h4 id="combine-percentages">
+Combination of <<percentage>></h4>
+
+	<a>Interpolation</a> of <<percentage>> is defined as
+	<var>V</var><sub>result</sub> =
+		(1 - <var>p</var>) &times; <var>V<sub>a</sub></var> +
+		<var>p</var> &times; <var>V<sub>b</sub></var>
+
+	<a>Addition</a> of <<percentage>> is defined as
+	<var>V<sub>result</sub></var> =
+		<var>V<sub>a</sub></var> + <var>V<sub>b</sub></var>
+
 <h3 id="mixed-percentages">
 Mixing Percentages and Dimensions</h3>
 
@@ -837,6 +986,34 @@ Mixing Percentages and Dimensions</h3>
 	A &lt;number-percentage> will never be added,
 	as <<number>> and <<percentage>> can't be combined in ''calc()''.
 
+<h4 id="combine-mixed">
+Combination of Percentage and Dimension Mixes</h4>
+
+	<a>Interpolation</a> of percengage-dimension value combinations
+	(e.g. <<length-percentage>>, <<frequency-percentage>>, <<angle-percentage>>, <<time-percentage>>
+	or equivalent notations)
+	is defined as
+	<ul>
+		<li>
+			equivalent to <a>interpolation</a> of <<length>>
+			if both <var>V<sub>a</sub></var> and <var>V<sub>b</sub></var> are pure <<length>> values
+
+		<li>
+			equivalent to <a>interpolation</a> of <<percentage>>
+			if both <var>V<sub>a</sub></var> and <var>V<sub>b</sub></var> are pure <<percentage>> values
+		<li>
+			equivalent to converting both values into a ''calc()'' expression
+			representing the sum of the dimension type and a percentage
+			(each possibly zero)
+			and <a>interpolating</a> each component individually
+			(as a <<length>>/<<frequency>>/<<angle>>/<<time>>
+			and as a <<percentage>>, respectively)
+	</ul>
+
+	<a>Addition</a> of <<percentage>> is defined
+	the same as <a>interpolation</a>
+	except by <a>adding</a> each component
+	rather than <a>interpolating</a> it.
 
 <!--
 ██       ████████ ██    ██  ██████   ████████ ██     ██
@@ -1493,6 +1670,30 @@ Colors: the <<color>> type</h3>
 	The <<color>> data type is defined in [[!CSS3COLOR]].
 	UAs that support CSS Color Level 3 or its successor must interpret <<color>> as defined therein.
 
+<h4 id="combine-colors">
+Combination of <<color>></h4>
+
+	<a>Interpolation</a> of <<color>> is defined as
+	the independent interpolation of each component
+	(red, green, blue, alpha)
+	as a <<number>>.
+	Interpolation is done between premultiplied colors
+	(that is, colors for which the red, green, and blue components specified
+	have been multiplied by the alpha).
+
+	<a>Addition</a> of <<number>> is likewise defined as
+	the independent <a>addition</a> of each component
+	as a <<number>>
+	in premultiplied space.
+
+	ISSUE: Computed value needs to be able to represent
+	combinations of ''currentColor'' and an actual color.
+	Consider the value of 'text-emphasis-color' in
+	<code>div { text-emphasis: circle; transition: all 2s; }<br>
+	div:hover { text-emphasis-color: lime; }<br>
+	em { color: red; }</code>
+	See <a href="https://github.com/w3c/csswg-drafts/issues/445">Issue 445</a>.
+
 <!--
 ████ ██     ██    ███     ██████   ████████
  ██  ███   ███   ██ ██   ██    ██  ██
@@ -1512,6 +1713,13 @@ Images: the <<image>> type</h3>
 	UAs that do not yet support CSS Images Level 3
 	must interpret <<image>> as <<url>>.
 
+<h4 id="combine-images">
+Combination of <<image>></h4>
+
+	Note: Interpolation of <<image>> is defined in [[css-images-3#interpolation]].
+
+	Images are <a>not additive</a>.
+
 <!--
 ████████   ███████   ██████  ████ ████████ ████  ███████  ██    ██
 ██     ██ ██     ██ ██    ██  ██     ██     ██  ██     ██ ███   ██
@@ -1565,6 +1773,19 @@ Images: the <<image>> type</h3>
 		followed by a <<length>>.
 	</div>
 
+<h4 id="combine-positions">
+Combination of <<position>></h4>
+
+	<a>Interpolation</a> of <<position>> is defined as
+	the independent interpolation of each component (x, y)
+	normalized as an offset from the top left corner
+	as a <<length-percentage>>.
+
+	<a>Addition</a> of <<position>> is likewise defined as
+	the independent <a>addition</a> each component (x, y)
+	normalized as an offset from the top left corner
+	as a <<length-percentage>>.
+
 <h2 id="functional-notations">
 Functional Notations</h2>