Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open

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

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
669d7a1
[css-ui-4] Clarify the applicability of the caret-* properties
frivoal Dec 14, 2024
ec805f5
Merge branch 'main' into caret-applicability
frivoal Dec 23, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
122 changes: 71 additions & 51 deletions css-ui-4/Overview.bs
View file
Open in desktop
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,10 @@ 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