[css-ui-4] Clarify the applicability of the caret-* properties (#11373)

Co-authored-by: Jeremy Roman <[email protected]>
Co-authored-by: Emilio Cobos Álvarez <[email protected]>
Co-authored-by: Oriol Brufau <[email protected]>

Author: 4 people

css-ui-4/Overview.bs

@@ -1082,26 +1082,57 @@ Cursor of the canvas</h5>
 <h3 id="insertion-caret">
 Insertion caret</h3>
 
+	The <dfn lt="insertion caret|caret">insertion caret</dfn> (or “caret” for short)
+	is a visible indicator of the insertion point in an element that [=accepts text input=],
+	where text (and potentially other content) can be inserted by the user.
+	The 'caret-color', 'caret-animation', and 'caret-shape' properties
+	give the author some amount of control over the appearance of the [=caret=].
+
+	Text or elements are considered to <dfn>accept text input</dfn>
+	if they are either an [=editable element=] or a descendent thereof,
+	excluding any such element where the [=used value=] of 'user-select' is ''user-select/none'',
+	as well as subtrees rooted at an HTML element with a {{ElementContentEditable/contentEditable}} attribute set to {{ElementContentEditable/contentEditable/false}}.
+
+	Some user agents have other user interface mechanisms
+	with a similar appearance,
+	also occasionally referred to as “carets”.
+	For example, some UAs can show a “navigation caret”,
+	which acts similarly to an [=insertion caret=]
+	but can be moved around in non-editable text.
+	The 'caret-color', 'caret-animation', and 'caret-shape' properties
+	are not intended to apply to such mechanisms
+	nor outside of [=editable elements=],
+	though user agents may choose to take them into account.
+	Whether to do so and to what extent is up to the user agent.
+
+	Note: The cursor image shown
+	when hovering over text when the 'cursor' property is ''cursor/auto'',
+	or when hovering over an element where the 'cursor' property is ''cursor/text'' or ''cursor/vertical-text'',
+	though it sometimes resembles a caret,
+	is not a caret (it's a cursor).
+
 <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>>
 	Initial: auto
-	Applies to: all elements
+	Applies to: text or elements that [=accept text input=]
 	Inherited: yes
 	Percentages: N/A
 	Computed value: The computed value for ''caret-color/auto'' is ''caret-color/auto''.
 	 For <<color>> values, see [[CSS-COLOR-4#resolving-color-values]].
 	Animation Type: by computed value
 	</pre>
 
+	This property controls the color of the [=insertion caret=].
+
 	<dl>
 		<dt>auto
 		<dd>
 			User agents should use ''currentColor''.
-			User agents may automatically adjust the color of caret
+			User agents may automatically adjust the color of [=caret=]
 			to ensure good visibility and contrast with the surrounding content,
 			possibly based on the currentColor, background, shadows, etc.
 
@@ -1111,21 +1142,9 @@ Coloring the Insertion Caret: the 'caret-color' property</h4>
 
 		<dt><<color>>
 		<dd>
-			The insertion caret is colored with the specified color.
+			The [=caret=] is colored with the specified color.
 	</dl>
 
-	The caret is a visible indicator of the insertion point in an element where text (and potentially other content) is inserted by the user. This property controls the color of that visible indicator.
-
-	Note: UAs might have additional things that count as “carets”.
-	For example, some UAs can show a “navigation caret”,
-	which acts similarly to an insertion caret
-	but can be moved around in non-editable text
-	and is functionally a caret.
-	On the other hand, the cursor image shown
-	when hovering over text when the 'cursor' property is ''cursor/auto'',
-	or when hovering over an element where the 'cursor' property is ''cursor/text'' or ''cursor/vertical-text'',
-	though it sometimes resembles a caret, is not a caret (it's a cursor).
-
 	<div class="example">
 		Example: a textarea with
 		<code class="lang-css">caret-color:#00aacc;</code>
@@ -1143,39 +1162,39 @@ Animation of the insertion caret: 'caret-animation'</h4>
 	Name: caret-animation
 	Value: auto | manual
 	Initial: auto
-	Applies to: elements that accept input
+	Applies to: text or elements that [=accept text input=]
 	Inherited: yes
 	Percentages: N/A
 	Computed value: specified keyword
 	Animation type: discrete
 	</pre>
 
 	On most platforms and in most UAs,
-	the text insertion caret blinks.
+	the [=insertion caret=] blinks.
 	This property allows the author
-	to take control over the way the caret is animated.
+	to take control over the way the [=caret=] is animated.
 
 	<dl dfn-type=value dfn-for=caret-animation>
 		<dt><dfn>auto</dfn>
 		<dd>
-			The UA determines how the caret should be animated, if at all,
+			The UA determines how the [=caret=] should be animated, if at all,
 			as well as the speed of any such animation.
 			It should match platform conventions and settings,
 			and may be adjusted based on context.
 
-			Note: This is typically rendered as a blinking caret.
+			Note: This is typically rendered as a blinking [=caret=].
 			Fading in and out instead of blinking is a variant that appears in some environments.
 
 		<dt><dfn>manual</dfn>
 		<dd>
-			The UA must not animate the caret.
+			The UA must not animate the [=caret=].
 
-			Note: This is only about UA-driven animations of the caret.
-			When CSS animations are used to animate the caret color,
+			Note: This is only about UA-driven animations of the [=caret=].
+			When CSS animations are used to animate the [=caret=] color,
 			they apply normally.
 	</dl>
 
-	Note: It is recommended for authors to stop the caret from blinking or fading
+	Note: It is recommended for authors to stop the [=caret=] from blinking or fading
 	using ''caret-animation: manual''
 	when applying custom animations using [[CSS3-ANIMATIONS]],
 	to prevent the UA's animation and the CSS animation to interfere.
@@ -1184,7 +1203,7 @@ Animation of the insertion caret: 'caret-animation'</h4>
 
 	<div class=example>
 		A user who is disturbed by or has adverse reactions to blinking or flashing visuals
-		may want to make all carets static and non-blinking,
+		may want to make all [=carets=] static and non-blinking,
 		regardless of platform defaults or author settings.
 		This can be accomplished with the following rule in the user stylesheet.
 
@@ -1201,14 +1220,14 @@ Animation of the insertion caret: 'caret-animation'</h4>
 	should provide a setting to disable
 	<a href="https://www.w3.org/TR/WCAG20/#blinksdef">blinking</a>,
 	<a href="https://www.w3.org/TR/WCAG20/#flash-def">flashing</a>,
-	and animated carets.
+	and animated [=carets=].
 	UAs that do have an editable user stylesheet may want to provide this setting as well.
 	See [[WCAG]] <a href="https://www.w3.org/TR/WCAG20/#time-limits-pause">Guideline 2.2</a>
 	and <a href="https://www.w3.org/TR/WCAG20/#seizure">Guideline 2.3</a>
 	for details.
 
 	<div class=example>
-		Typically, the caret blinks on and off.
+		Typically, the [=caret=] blinks on and off.
 		This makes it alternate between 2 colors.
 		<pre><code class="lang-css">
 		textarea {
@@ -1245,7 +1264,7 @@ Animation of the insertion caret: 'caret-animation'</h4>
 	</div>
 
 	<div class=advisement>
-		If a user agent is unwilling to yield control of caret animations
+		If a user agent is unwilling to yield control of [=caret=] animations
 		to page authors and would not honor ''caret-animation: manual'',
 		it must not implement the property at all.
 
@@ -1263,15 +1282,15 @@ Shape of the insertion caret: 'caret-shape'</h4>
 	Name: caret-shape
 	Value: auto | bar | block | underscore
 	Initial: auto
-	Applies to: elements that accept input
+	Applies to: text or elements that [=accept text input=]
 	Inherited: yes
 	Percentages: N/A
 	Computed value: specified keyword
 	Animation type: by computed value
 	</pre>
 
 	This property allows authors to specify
-	the desired shape of the text insertion caret.
+	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>,
@@ -1281,56 +1300,56 @@ Shape of the insertion caret: 'caret-shape'</h4>
 	<dl dfn-type=value dfn-for=caret-shape>
 		<dt><dfn>auto</dfn>
 		<dd>
-			The UA determines the shape of the caret.
+			The UA determines the shape of the [=caret=].
 			It should match platform conventions,
 			and may be adjusted based on context.
 			For example, if a UA switches between insert mode and overtype mode when the
 			user presses the <em>insert</em> key on their keyboard,
-			it may show a ''caret-shape/bar'' caret in insert mode,
-			and a ''caret-shape/block'' caret in overtype mode.
+			it may show a ''caret-shape/bar'' [=caret=] in insert mode,
+			and a ''caret-shape/block'' [=caret=] in overtype mode.
 
 		<dt><dfn>bar</dfn>
 		<dd>
-			The UA must render the text insertion caret
+			The UA must render the [=insertion caret=]
 			as a thin bar placed at the insertion point.
 			This means it is between, before, or after <a>characters</a>, not over them.
 			It should be perpendicular to the inline progression direction,
 			although UAs may render it slanted when inserting italic or oblique text.
 
 		<dt><dfn>block</dfn>
 		<dd>
-			The UA must render the text insertion caret
+			The UA must render the [=insertion caret=]
 			as a rectangle overlapping the next <a>visible character</a> following the insertion point.
 			If there is no <a>visible character</a> after the insertion point,
 			the UA must render the caret after the last <a>visible character</a>.
 			UAs may render it as a slanted rectangle when inserting italic or oblique text.
 
 		<dt><dfn>underscore</dfn>
 		<dd>
-			The UA must render the text insertion caret
+			The UA must render the [=insertion caret=]
 			as a thin line <a>under</a> (as defined in [[!CSS-WRITING-MODES-3]]
 			the next <a>visible character</a> following the insertion point.
 			If there is no <a>visible character</a> after the insertion point,
 			the UA must render the caret after the last <a>visible character</a>.
 	</dl>
 
-	The width of the ''caret-shape/block'' and ''caret-shape/underscore'' carets
+	The width of the ''caret-shape/block'' and ''caret-shape/underscore'' [=carets=]
 	should be the advance measure of the next <a>visible character</a> after the insertion point,
 	or ''1ch'' if there is no next <a>visible character</a>
 	or if this information is impractical to determine.
 
-	When determining the orientation and appearance of the caret,
+	When determining the orientation and appearance of the [=caret=],
 	UAs must take into account the <a>writing mode</a> [[!CSS-WRITING-MODES-3]]
 	and must apply transformations [[!CSS-TRANSFORMS-1]].
 	If the edited text is laid out on a path,
 	for instance by using the SVG <{textPath}> element,
 	UAs should also account for this.
 
-	The thickness of ''caret-shape/bar'' and ''caret-shape/underscore'' carets--
-	as well as that of ''caret-shape/auto'' carets with a similar rendering--
+	The thickness of ''caret-shape/bar'' and ''caret-shape/underscore'' [=carets=]--
+	as well as that of ''caret-shape/auto'' [=carets=] with a similar rendering--
 	is determined by the user agent.
 	When practical, the user agent should choose a thickness that ensures
-	the caret remains visible even if it has been scaled down
+	the [=caret=] remains visible even if it has been scaled down
 	via means such as transformations [[CSS-TRANSFORMS-1]].
 
 	When there is not enough room at the end of a line
@@ -1340,19 +1359,19 @@ Shape of the insertion caret: 'caret-shape'</h4>
 	past the bounds of the [=scrollable overflow area=];
 	user agents may impose limits on this and clip as necessary.
 
-	The stacking position of the caret is left undefined within the following constraints:
+	The stacking position of the [=caret=] is left undefined within the following constraints:
 
 	<ul>
 		<li>
-			The caret must not be obscured by the background of the element.
+			The [=caret=] must not be obscured by the background of the element.
 
 		<li>
-			UAs must render ''caret-shape/block'' carets
-			so that the character it overlaps with is not obscured by the caret.
+			UAs must render ''caret-shape/block'' [=carets=]
+			so that the character it overlaps with is not obscured by the [=caret=].
 	</ul>
 
 	<div class=example>
-		This illustrates the typical appearance of the various caret shapes.
+		This illustrates the typical appearance of the various [=caret=] shapes.
 		In each of the sample renderings below,
 		the insertion point is between the letters u and m.
 
@@ -1376,7 +1395,7 @@ Shape of the insertion caret: 'caret-shape'</h4>
 			<tr>
 				<th>'caret-shape'
 				<th>Sample rendering
-				<th>Your browser<br>(focus each cell to see the caret)
+				<th>Your browser<br>(focus each cell to see the [=caret=])
 
 			<tr>
 				<td>''bar''
@@ -1396,7 +1415,7 @@ Shape of the insertion caret: 'caret-shape'</h4>
 	</div>
 
 	<div class=example>
-		''caret-shape/underscore'' or ''caret-shape/block'' carets are commonly used
+		''caret-shape/underscore'' or ''caret-shape/block'' [=carets=] are commonly used
 		in terminals and command lines,
 		as in this example.
 		<pre><code class="lang-css">
@@ -1435,7 +1454,7 @@ Shape of the insertion caret: 'caret-shape'</h4>
 	Name: caret
 	Value: <<'caret-color'>> || <<'caret-animation'>> || <<'caret-shape'>>
 	Initial: auto
-	Applies to: elements that accept input
+	Applies to: text or elements that [=accept text input=]
 	Inherited: yes
 	Percentages: N/A
 	</pre>
@@ -1445,9 +1464,9 @@ Shape of the insertion caret: 'caret-shape'</h4>
 	Omitted values are set to their initial values.
 
 	<div class=example>
-		This example illustrates using the various caret-related properties
+		This example illustrates using the various [=caret=]-related properties
 		in combination.
-		They are used here to simulate the appearance of the caret
+		They are used here to simulate the appearance of the [=caret=]
 		on an old phosphor computer monitor.
 
 		<pre><code class="lang-css">