Extend Canvas TextMetrics for editing and text styling #11000

AndresRPerez12 · 2025-02-05T15:09:52Z

This change adds the following functionalities to TextMetrics objects:

Get the set of rectangles that the user agent would render as the selection background when a particular character range of the measured text is selected.
Get the rectangle corresponding to the actual bounding box for a character range of the measured text. This is the equivalent to TextMetrics.actualBoundingBox restricted to the given range.
Get the string index for the character at a given offset distance from the start position of the measured text.
Split a character range of the measured text into grapheme clusters. That is, for the given range, it returns the minimal logical units of text, each of which can be rendered, along with their corresponding positional data.

Additionally, a new method is added to the Canvas 2D rendering context to render these clusters. When rendering, all relevant CanvasTextDrawingStyles are used as they were when the text was measured.

See the discussion in the issue: #10677

At least two implementers are interested (and none opposed):
- Chromium: The new methods have been implemented (https://issues.chromium.org/u/1/issues/341213359)
- Gecko: Position has been requested ([HTML Canvas] TextMetrics Additions mozilla/standards-positions#1144)
- WebKit: Position has been requested, and some portions have already started landing ([HTML Canvas] TextMetrics Additions for Editing and Graphic Design WebKit/standards-positions#436)
Tests are written and can be reviewed and commented upon at:
- https://github.com/web-platform-tests/wpt/tree/master/html/canvas/element/text
- https://github.com/web-platform-tests/wpt/tree/master/html/canvas/offscreen/text
- Relevant tests: 2d.text.measure.selection-rects*, 2d.text.measure.getActualBoundingBox*, 2d.text.measure.index-from-offset*, and 2d.text.measure.text-clusters*.
Implementation bugs are filed:
- Chromium: https://crbug.com/341213359
- Gecko: …
- WebKit: https://bugs.webkit.org/show_bug.cgi?id=284464
Corresponding HTML AAM & ARIA in HTML issues & PRs:
MDN issue is filed: …
The top of this comment includes a clear commit message to use.

(See WHATWG Working Mode: Changes for more details.)

/acknowledgements.html ( diff )
/canvas.html ( diff )
/infrastructure.html ( diff )

schenney-chromium · 2025-02-05T16:14:45Z

source

+   <dt><code data-x=""><var>metrics</var>.<span subdfn data-x="dom-textmetrics-getIndexFromOffset">getIndexFromOffset</span>(<var>offset</var>)</code></dt>
+   <dt><code data-x=""><var>metrics</var>.<span subdfn data-x="dom-textmetrics-getTextClusters">getTextClusters</span>(<var>start</var>, <var>end</var> [, <var>options</var> ])</code></dt>
+
+   <dt><code data-x=""><var>context</var>.<span subdfn data-x="dom-context-2d-fillTextCluster">fillTextCluster</span>(<var>textCluster</var>, <var>x</var>, <var>y</var> [, <var>options</var> ])</code></dt>


The fill method belongs up with the other drawing methods.

schenney-chromium · 2025-02-05T16:22:17Z

source

@@ -65506,6 +65515,7 @@ interface mixin <dfn interface>CanvasText</dfn> {
  undefined <span data-x="dom-context-2d-fillText">fillText</span>(DOMString text, unrestricted double x, unrestricted double y, optional unrestricted double maxWidth);
  undefined <span data-x="dom-context-2d-strokeText">strokeText</span>(DOMString text, unrestricted double x, unrestricted double y, optional unrestricted double maxWidth);
  <span>TextMetrics</span> <span data-x="dom-context-2d-measureText">measureText</span>(DOMString text);
+  undefined <span data-x="dom-context-2d-fillTextCluster">fillTextCluster</span>(<span>TextCluster</span> textCluster, double x, double y, optional <span>TextClusterOptions</span> options);


I would expect this to be up with drawing methods.

schenney-chromium · 2025-02-05T16:25:21Z

source

+    readonly attribute <span>CanvasTextBaseline</span> <span data-x="dom-TextCluster-baseline">baseline</span>;
+};
+
+dictionary <dfn dictionary>TextClusterOptions</dfn> {


Looks like dictionaries go before their first use.

AndresRPerez12 · 2025-02-05T16:26:15Z

Tagging: @whatwg/canvas

schenney-chromium

Sorry for leaving some comments out of the review.

schenney-chromium · 2025-02-05T16:27:14Z

source

+        data-x="dom-context-2d-measureText">measureText()</code> was called) in relation to the text
+        as a whole.</p>
+
+        <p>The x position specified for each cluster corresponds to the aligment point given by the


Typo aligment

schenney-chromium · 2025-02-05T16:30:17Z

source

+
+      <dt><dfn attribute for="TextCluster"><code data-x="dom-TextCluster-end">end</code></dfn> attribute</dt>
+
+      <dd><p>The ending index for the range of <span data-x="code point">code points</span> that are


Is this the index one past the end? Range APIs seem to behave that way but I'm not sure how conventional it is.

schenney-chromium · 2025-02-05T16:34:21Z

source

+    <p class="note">The user agent might internally store in the <code>TextCluster</code> object the
+    complete text, as well as all the <code>CanvasTextDrawingStyles</code> at the time that <code
+    data-x="dom-context-2d-measureText">measureText()</code> was called, as they will be needed to
+    correctly render the clusters as they were measured.</p>


Is it a requirement that the drawing command uses the same parameters as the measurement? If so I would say that directly here, because right now it seems suggestive but not prescribed.

Kaiido

Thanks for doing this!

A couple of questions that came to mind:

Should there be a strokeTextCluster() method akin to strokeText()?
Should the TextCluster be serializable? (so that we can send it to/from a Worker).

Also, I didn't receive the @whatwg/canvas notification from your previous comment. Hopefully this one will work better.

Kaiido · 2025-02-06T05:20:43Z

source

+  The cluster is rendered where it would be if the whole text that was passed to <code
+  data-x="dom-context-2d-measureText">measureText()</code> to obtain the cluster was rendered at


Disclaimer: I'm not an editor, so take this with a grain of salt.

I feel this would be a lot clearer if the TextMetrics interface had an internal value to store the original text for each instance and reuse it where needed, instead of this tedious "the text that was passed to measureText() to obtain the cluster".

See for instance how CanvasPattern objects have a transformation matrix that isn't exposed:

Patterns have a transformation matrix, which controls how the pattern is used when it is painted. Initially, a pattern's transformation matrix must be the identity matrix.

It might even be needed to have a clear relationship established between the TextCluster and the TextMetrics from where it's been created, so that you can do something like the cluster's textmetrics's text, or, given that when the TextCluster is created text is available, and TextMetrics may not need it otherwise, you could maybe store it directly along the TextCluster (still in an internal value).

Kaiido · 2025-02-06T05:35:21Z

source

+    <li><p>Run the <span>text preparation algorithm</span>, passing it the <var>text</var>
+    originally passed to <code data-x="dom-context-2d-measureText">measureText()</code> to obtain
+    the cluster, and an object with the <code>CanvasTextDrawingStyles</code> values as they were
+    when the cluster was measured, with the exception of <code


This object should probably be created explicitly sooner, in the getTextClusters() method. However I'm not sure how this should be done since we want the computed values at that time.

Kaiido · 2025-02-06T05:36:15Z

source

+  The cluster is rendered where it would be if the whole text that was passed to <code
+  data-x="dom-context-2d-measureText">measureText()</code> to obtain the cluster was rendered at
+  position (<var>x</var>,<var>y</var>), unless the positioning is modified with the options
+  argument. Specifically, when the methods are invoked, the user agent must run these steps:</p>


The plural in "the methods are" sounds weird. What methods does this refer to?

Kaiido · 2025-02-06T05:42:26Z

source

+    data-x="dom-TextCluster-baseline">baseline</code> attributes of <var>cluster</var>. Let
+    <var>glyphs</var> be the result.</p></li>
+
+    <li><p>Filter <var>glyphs</var> to include only glyphs that contain <span


typo: "to include only [the] glyphs that"

Kaiido · 2025-02-06T06:03:56Z

source

+      <p>If a <code>TextClusterOptions</code> options dictionary is passed and it has an <code
+      data-x="">options.x</code> value, move all the shapes in <var>glyphs</var> to the right by
+      <code data-x="">options.x-cluster.x</code>.</p>
+
+      <p>If a <code>TextClusterOptions</code> options dictionary is passed and it has an <code
+      data-x="">options.y</code> value, move all the shapes in <var>glyphs</var> down by <code
+      data-x="">options.y-cluster.y</code>.</p>


I think at this point options and cluster are infra maps, and thus this should be <var>options["x"]</var> instead of options.x. Also I think the - should be − in free text. So e.g. for the last one, that'd give <var>options["y"]</var> − <var>cluster["y"]</var>, but here again take this with a grain of salt.

Initial commit: TextMetrics additions

20e36f8

AndresRPerez12 marked this pull request as draft February 5, 2025 15:10

schenney-chromium reviewed Feb 5, 2025

View reviewed changes

Kaiido reviewed Feb 6, 2025

View reviewed changes

Kaiido added the topic: canvas label Feb 6, 2025

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Extend Canvas TextMetrics for editing and text styling #11000

Extend Canvas TextMetrics for editing and text styling #11000

AndresRPerez12 commented Feb 5, 2025 •

edited by pr-preview bot

Loading

schenney-chromium Feb 5, 2025

schenney-chromium Feb 5, 2025

schenney-chromium Feb 5, 2025

AndresRPerez12 commented Feb 5, 2025

schenney-chromium left a comment

schenney-chromium Feb 5, 2025

schenney-chromium Feb 5, 2025

schenney-chromium Feb 5, 2025

Kaiido left a comment

Kaiido Feb 6, 2025 •

edited

Loading

Kaiido Feb 6, 2025

Kaiido Feb 6, 2025

Kaiido Feb 6, 2025

Kaiido Feb 6, 2025


		<dt><dfn attribute for="TextCluster"><code data-x="dom-TextCluster-end">end</code></dfn> attribute</dt>

		<dd><p>The ending index for the range of <span data-x="code point">code points</span> that are

		The cluster is rendered where it would be if the whole text that was passed to <code
		data-x="dom-context-2d-measureText">measureText()</code> to obtain the cluster was rendered at

Extend Canvas TextMetrics for editing and text styling #11000

Are you sure you want to change the base?

Extend Canvas TextMetrics for editing and text styling #11000

Conversation

AndresRPerez12 commented Feb 5, 2025 • edited by pr-preview bot Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

AndresRPerez12 commented Feb 5, 2025

schenney-chromium left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Kaiido left a comment

Choose a reason for hiding this comment

Kaiido Feb 6, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

AndresRPerez12 commented Feb 5, 2025 •

edited by pr-preview bot

Loading

Kaiido Feb 6, 2025 •

edited

Loading