From 1b0e26b9bdc27bfe1b1d27386a380e0494340aeb Mon Sep 17 00:00:00 2001 From: Florian Rivoal Date: Sat, 14 Dec 2024 14:48:50 +0900 Subject: [PATCH] [css-ui-4] Clarify the applicability of the caret-* properties See #11335 --- css-ui-4/Overview.bs | 121 +++++++++++++++++++++++++------------------ 1 file changed, 70 insertions(+), 51 deletions(-) diff --git a/css-ui-4/Overview.bs b/css-ui-4/Overview.bs index a6e2a358e19..cd6503f032a 100644 --- a/css-ui-4/Overview.bs +++ b/css-ui-4/Overview.bs @@ -1079,6 +1079,35 @@ Cursor of the canvas

Insertion caret

+ The insertion caret (or “caret” for short) + is a visible indicator of the insertion point in an element that [=accepts 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=]. + + Elements are considered to accept input + 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 extend 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). +

Coloring the Insertion Caret: the 'caret-color' property

@@ -1086,7 +1115,7 @@ Coloring the Insertion Caret: the 'caret-color' property Name: caret-color Value: auto | <> Initial: auto - Applies to: all elements + Applies to: elements that [=accept input=] Inherited: yes Percentages: N/A Computed value: The computed value for ''caret-color/auto'' is ''caret-color/auto''. @@ -1094,11 +1123,13 @@ Coloring the Insertion Caret: the 'caret-color' property Animation Type: by computed value + This property controls the color of the [=insertion caret=]. +
auto
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. @@ -1108,21 +1139,9 @@ Coloring the Insertion Caret: the 'caret-color' property
<>
- The insertion caret is colored with the specified color. + The [=caret=] is colored with the specified color.
- 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). -
Example: a textarea with caret-color:#00aacc; @@ -1140,7 +1159,7 @@ Animation of the insertion caret: 'caret-animation' Name: caret-animation Value: auto | manual Initial: auto - Applies to: elements that accept input + Applies to: elements that [=accept input=] Inherited: yes Percentages: N/A Computed value: specified keyword @@ -1148,31 +1167,31 @@ Animation of the insertion caret: 'caret-animation' 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.
auto
- 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.
manual
- 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.
- 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. @@ -1181,7 +1200,7 @@ Animation of the insertion caret: 'caret-animation'
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. @@ -1198,14 +1217,14 @@ Animation of the insertion caret: 'caret-animation' should provide a setting to disable blinking, flashing - and animated carets. + and animated [=carets=]. UAs that do have an editable user stylesheet may want to provide this setting as well. See [[WCAG]] Guideline 2.2 and Guideline 2.3 for details.
- Typically, the caret blinks on and off. + Typically, the [=caret=] blinks on and off. This makes it alternate between 2 colors. 

 		textarea {
@@ -1242,7 +1261,7 @@ Animation of the insertion caret: 'caret-animation'
- 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. @@ -1260,7 +1279,7 @@ Shape of the insertion caret: 'caret-shape' Name: caret-shape Value: auto | bar | block | underscore Initial: auto - Applies to: elements that accept input + Applies to: elements that [=accept input=] Inherited: yes Percentages: N/A Computed value: specified keyword @@ -1268,7 +1287,7 @@ Shape of the insertion caret: 'caret-shape' 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, character is to be understood as extended grapheme cluster, @@ -1278,17 +1297,17 @@ Shape of the insertion caret: 'caret-shape'
auto
- 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 insert 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.
bar
- 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 characters, not over them. It should be perpendicular to the inline progression direction, @@ -1296,7 +1315,7 @@ Shape of the insertion caret: 'caret-shape'
block
- The UA must render the text insertion caret + The UA must render the [=insertion caret=] as a rectangle overlapping the next visible character following the insertion point. If there is no visible character after the insertion point, the UA must render the caret after the last visible character. @@ -1304,45 +1323,45 @@ Shape of the insertion caret: 'caret-shape'
underscore
- The UA must render the text insertion caret + The UA must render the [=insertion caret=] as a thin line under (as defined in [[!CSS-WRITING-MODES-3]] the next visible character following the insertion point. If there is no visible character after the insertion point, the UA must render the caret after the last visible character.
- 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 visible character after the insertion point, or ''1ch'' if there is no next visible character 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 writing mode [[!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]]. - 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:
  • - The caret must not be obscured by the background of the element. + The [=caret=] must not be obscured by the background of the element.
  • - 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=].
- 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. @@ -1366,7 +1385,7 @@ Shape of the insertion caret: 'caret-shape' 'caret-shape' Sample rendering - Your browser
(focus each cell to see the caret) + Your browser
(focus each cell to see the [=caret=]) ''bar'' @@ -1386,7 +1405,7 @@ Shape of the insertion caret: 'caret-shape'
- ''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. 

@@ -1425,7 +1444,7 @@ Shape of the insertion caret: 'caret-shape'
 	Name: caret
 	Value: <<'caret-color'>> || <<'caret-animation'>> || <<'caret-shape'>>
 	Initial: auto
-	Applies to: elements that accept input
+	Applies to: elements that [=accept input=]
 	Inherited: yes
 	Percentages: N/A
@@ -1435,9 +1454,9 @@ Shape of the insertion caret: 'caret-shape' Omitted values are set to their initial values.
- 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.