Skip to content

Commit

Permalink
[css-ui-4] Clarify the applicability of the caret-* properties
Browse files Browse the repository at this point in the history 
See #11335
  • Loading branch information
@frivoal
frivoal committed Dec 14, 2024
1 parent ca9c45d commit 1b0e26b
Showing 1 changed file with 70 additions and 51 deletions.
121 changes: 70 additions & 51 deletions css-ui-4/Overview.bs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1079,26 +1079,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 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 <dfn>accept 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 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).

<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: elements that [=accept 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.

Expand All @@ -1108,21 +1139,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>
Expand All @@ -1140,39 +1159,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: elements that [=accept 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.
Expand All @@ -1181,7 +1200,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.

Expand All @@ -1198,14 +1217,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 {
Expand Down Expand Up @@ -1242,7 +1261,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.

Expand All @@ -1260,15 +1279,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: elements that [=accept 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>,
Expand All @@ -1278,71 +1297,71 @@ 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]].

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.

Expand All @@ -1366,7 +1385,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''
Expand All @@ -1386,7 +1405,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">
Expand Down Expand Up @@ -1425,7 +1444,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: elements that [=accept input=]
Inherited: yes
Percentages: N/A
</pre>
Expand All @@ -1435,9 +1454,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">
Expand Down

0 comments on commit 1b0e26b

Please sign in to comment.