[css-ui] Add second value for caret-color

This controls the color of the text when it overlaps block carets.

Closes #13723

Author: frivoal

css-ui-4/Overview.bs

@@ -1371,12 +1371,18 @@ Insertion caret</h3>
 	though it sometimes resembles a caret,
 	is not a caret (it's a cursor).
 
+	Within the context of this section, <dfn>character</dfn> is
+	to be understood as <em>extended grapheme cluster</em>,
+	as defined in [[!UAX29]], and <dfn>visible character</dfn>
+	means a character with a non-zero advance measure.
+
+
 <h4 id="caret-color" caniuse="css-caret-color">
 Coloring the Insertion Caret: the 'caret-color' property</h4>
 
 	<pre class="propdef">
 	Name: caret-color
-	Value: auto | <<color>>
+	Value: auto | <<color>> [auto | <<color>>]?
 	Initial: auto
 	Applies to: text or elements that [=accept text input=]
 	Inherited: yes
@@ -1416,6 +1422,8 @@ Coloring the Insertion Caret: the 'caret-color' property</h4>
 	</wpt>
 
 	This property controls the color of the [=insertion caret=].
+	It takes one or two values.
+	The first value has the following effects:
 
 	<dl>
 		<dt>auto
@@ -1443,6 +1451,83 @@ Coloring the Insertion Caret: the 'caret-color' property</h4>
 		</textarea>
 	</div>
 
+	The second value has no effect when 'caret-shape' is ''caret-shape/bar'', ''caret-shape/underscore'',
+	or ''caret-shape/auto'' behaving as either of these values.
+	If 'caret-shape' is ''caret-shape/block''--
+	or ''caret-shape/auto'' behaving as ''caret-shape/block''--
+	then it determines the color of the text [=overlapping the caret=].
+	If the second value is omitted,
+	the behavior is the same as if <code>auto</code> had been specified.
+
+	<dl>
+		<dt>auto
+		<dd>
+			User agents must automatically adjust the color of the text [=overlapping the caret=]
+			to ensure good visibility and contrast between the text
+			and the underlying ''caret-shape/block'' caret,
+			if using ''currentColor'' would result in poor readability.
+			The specifics of how to assess contrast
+			and how to pick a sufficiently contrasty color are up to the user agent.
+
+		<dt><<color>>
+		<dd>
+			The color of text [=overlapping the caret=] is the specified color.
+
+			Note: Authors wishing to ensure that the color of the text remains constant
+			regardless of the position of a ''caret-shape/block'' caret
+			can specify ''currentColor'' as the second value of 'caret-color'.
+	</dl>
+
+	Text considered to <dfn>overlap the caret</dfn>
+	is the next [=visible character=] after the insertion point, if any.
+
+	<div class=example id=caret-color-2-values>
+		This illustrates the effect of the second value of 'caret-color' on ''caret-shape/block'' carets.
+		In each of the sample renderings below,
+		the insertion point is between the letters u and m.
+
+		<style>
+		@keyframes caret-color-2-ref { 50% { background: transparent; color: inherit; } }
+		#caret-color-2 {
+			min-width: 25em;
+		}
+		#caret-color-2,
+		#caret-color-2 td,
+		#caret-color-2 th {
+			border: solid 1px;
+		}
+		#caret-color-2 td+td {
+			background:white;
+			color: black;
+		}
+		</style>
+		<table id="caret-color-2">
+			<tr>
+				<th>'caret-color:'
+				<th>Sample rendering
+				<th>Your browser<br>(focus each cell to see the [=caret=])
+
+			<tr>
+				<td>''black'' (or ''black auto'')
+				<td>Lorem ipsu<span style="background: #000; color: #fff; animation: caret-color-2-ref 1s step-end infinite;">m</span>
+				<td contentEditable=true style="caret-shape: block; caret-color: black;">Lorem Ipsum
+
+			<tr>
+				<td>''black yellow''
+				<td>Lorem ipsu<span style="background: #000; color: yellow; animation: caret-color-2-ref 1s step-end infinite;">m</span>
+				<td contentEditable=true style="caret-shape: block; caret-color: black yellow;">Lorem Ipsum
+
+			<tr>
+				<td>''black black''
+				<td>Lorem ipsu<span style="background: #000; animation: caret-color-2-ref 1s step-end infinite;">m</span>
+				<td contentEditable=true style="caret-shape: block; caret-color: black black;">Lorem Ipsum
+		</table>
+	</div>
+
+	Optionally, user agents may treat as overlapping only those parts of next [=visible character=]
+	which visually intersect with the ''caret-shape/block'',
+	and adjust the color of those parts only.
+
 
 <h4 id="caret-animation">
 Animation of the insertion caret: 'caret-animation'</h4>
@@ -1608,11 +1693,6 @@ Shape of the insertion caret: 'caret-shape'</h4>
 	This property allows authors to specify
 	the desired shape of the [=insertion caret=].
 
-	Within the context of this definition, <dfn>character</dfn> is
-	to be understood as <em>extended grapheme cluster</em>,
-	as defined in [[!UAX29]], and <dfn>visible character</dfn>
-	means a character with a non-zero advance measure.
-
 	<dl dfn-type=value dfn-for=caret-shape>
 		<dt><dfn>auto</dfn>
 		<dd>