Add "Accessibility" section to the explainer by ltenmoz · Pull Request #146 · w3c/edit-context

ltenmoz · 2026-08-06T16:32:18Z

Fixes #136

ltenmoz · 2026-08-06T16:33:51Z

 # EditContext API Explainer
 ## Introduction
-The EditContext is a new API that simplifies the process of integrating a web app with [advanced text input methods](#example-text-input-methods), improves accessibility and performance, and unlocks new capabilities for web-based editors.
+The EditContext is a new API that simplifies the process of integrating a web app with [advanced text input methods](#example-text-input-methods), improves performance, and unlocks new capabilities for web-based editors.


I don't know if we want to lead with "improves accessibility" given that

for canvas EditContext, the situation is not really any better than hidden contenteditable

for non-canvas EditContext, it's not as if accessibility is "solved" by just switching to EditContext - the DOM contents still have to be made accessible

Yeah I think this is a reasonable change.

smaug---- · 2026-08-10T18:56:48Z

@dandclark

dandclark

Thank for working on this, it's an important missing piece. What do you think about adding it as a non-normative section to the actual spec?

dandclark · 2026-08-12T16:25:22Z

 # EditContext API Explainer
 ## Introduction
-The EditContext is a new API that simplifies the process of integrating a web app with [advanced text input methods](#example-text-input-methods), improves accessibility and performance, and unlocks new capabilities for web-based editors.
+The EditContext is a new API that simplifies the process of integrating a web app with [advanced text input methods](#example-text-input-methods), improves performance, and unlocks new capabilities for web-based editors.


Yeah I think this is a reasonable change.

dandclark · 2026-08-12T16:27:34Z

+For this reason, it is **not** exposed to assistive technologies such as screen readers.
+So in order for an EditContext editor to be fully accessible, it must also render its contents in an accessible format to the DOM.
+
+For all EditContext editors, the `aria-label` attribute should be set to a value which describes the purpose


The aria-label suggestion is probably correct, but is it specific to EditContext editors? I'm not sure it's more necessary here than for a general <div contenteditable> or <input>/<textarea>, so it might be misleading to call it out as something needed for EditContext in particular (although we could still show it in the example).

Yes, that's true, although it's particularly important for <canvas> EditContext, since without the label, it gets announced as "image" to screen readers which is especially confusing. So I think it's worth saying it explicitly, although I'll make it clearer that it's not specific to EditContext.

dandclark · 2026-08-12T16:30:11Z

+be set to `true` if the editor allows for more than one line of text.
+The DOM contents of the editor should use the appropriate elements
+and the appropriate ARIA attributes to communicate the semantics of the editor contents.
+For example, `<p>` tags should be used for paragraphs,


Or another element given the paragraph role

dandclark · 2026-08-12T16:46:03Z


 This [example](native_selection_demo.html) shows how an author can leverage native selection when using EditContext.

+## Accessibility


I think we should consider adding this as a non-normative section to the spec instead of (or in addition to) the explainer. The spec has several examples already but unfortunately doesn't say much about accessibility.

Sounds good! Maybe we can link to the spec from the explainer, so that we don't have the same information in multiple places, but people who only read the explainer will still see it?

That sounds good to me!

dandclark · 2026-08-12T16:51:07Z

+rendered to the canvas, to ensure that accessibility features which require the position of the text
+work correctly (such as Windows Narrator highlighting the announced text).
+
+### Example: Accessibility for canvas EditContext


It would be nice to have an a11y expert review this, but I'm not sure who to recommend. I was also looking for something at https://www.w3.org/WAI/ARIA/apg/patterns/, but seems they chose not to include a rich text editor example: w3c/aria-practices#3310, w3c/aria-practices#88.

I'm still fine to move ahead with this for now though given the focus is more on "you'll have work to do to make this accessible" rather than "this the exact list of things you need to do to make this accessible."

Yes, I'll try to see if we can get someone at Mozilla to take a look.

jcsteh

Thanks for working on this. I think this makes the accessibility situation much clearer.

jcsteh · 2026-08-27T05:13:32Z

+            <p>
+                An EditContext's [=text=] useful for text input methods,
+                but since it is just a string, it cannot have any structure, such as paragraph divisions,
+                or interactive elements, such as hyperlinks and buttons.


I assume it also can't have formatting information; e.g. bold, emphasis, superscript, etc.? This is implied by text being a string, but it might be worth mentioning to further illustrate the point. (I see you do mention it later.)

Yes, good point

jcsteh · 2026-08-27T05:46:19Z

+            <p>
+                Just like with <code>contenteditable</code>, EditContext editors
+                should be given the attribute
+                <a href="https://w3c.github.io/aria/#textbox"><code>role="textbox"</code></a>,


role="textbox" isn't sufficient alone to expose the editable state which signals that something is an editor to some accessibility clients. This isn't an authoring concern, but somewhere, we'll need to specify what should signal to browsers to expose the editable state to accessibility clients. For example, here's where that is specified for contenteditable.

I'll file a separate issue about it: #150

jcsteh · 2026-08-27T05:55:01Z

+                When an EditContext is attached to a canvas, further care must be taken to ensure that the editor is accessible.
+                Alternative content must be provided for assistive technologies, using child elements of the canvas.
+                The selection in the EditContext must be kept in sync with the selection in the alternative content to ensure that assistive technologies work correctly.
+                Furthermore, the text in the alternative content should be in the same position on screen as the text


This is absolutely true. However, I'm fairly sure this isn't possible with any browser currently. Hit testing needs to be supported as well. I'm not sure whether either of these are feasible without changes to canvas; I suspect they aren't. I think this needs further investigation to determine whether this is even possible. If it isn't, that's a significant accessibility problem.

I was thinking originally that the alternative content could be in a sibling element to prevent that kind of issue, but having the selection in a different place from the focus seems to cause even bigger problems. For what it's worth, descendants of canvas are still laid out (e.g. they have reasonable values for getBoundingClientRect) so I think it would just be a matter of making sure that information is exposed to accessibility, at least for a canvas with an attached EditContext. Not sure how feasible that is though. Maybe we can add a note about it in the spec for now.

Hmm actually this does work properly in Firefox. Using Windows Narrator, the blue boxes are in the right place when narrating the EditContext text in the canvas EditContext demo I made. But it seems that Chromium and WebKit don't lay out canvas fallback content at all, unfortunately, although I'm not sure if this is specified anywhere.

Interesting; I wasn't sure about that, though I did see some coordinates differing between paragraphs, so I did wonder. Note that even in Firefox, I'm fairly sure hit testing doesn't work (because that requires that the frames are included in display lists), even if bounding boxes do work. So this is definitely something that needs to be addressed in some way or another across all browsers.

jcsteh · 2026-08-27T06:04:58Z

+            <p>
+                When an EditContext is attached to a canvas, further care must be taken to ensure that the editor is accessible.
+                Alternative content must be provided for assistive technologies, using child elements of the canvas.
+                The selection in the EditContext must be kept in sync with the selection in the alternative content to ensure that assistive technologies work correctly.


I think this is also true for DOM based EditContext editors. That is, it is not sufficient to "render its contents in an accessible format to the DOM"; the DOM selection needs to be kept in sync with EditContext. If that's already true by definition, please disregard, but I don't think it is.

Yes, that's true. I think the original idea behind DOM-based EditContext was that the browser would manage the DOM selection (e.g. moving it with the arrow keys), and the web app would be responsible for updating the EditContext selection whenever the DOM selection changes (that's what the examples do). However in practice some EditContext users (namely Google Docs and the Monaco Editor) are just using it to receive text input, and render everything in a separate element. That's really not great for accessibility, so we should probably explicitly discourage it here.

jcsteh · 2026-08-27T06:09:30Z

There's also a section entitled "Accessibility Issues in the Monaco Editor". Everything therein is true. However, I wanted to clarify: does EditContext definitely solve this? I guess with EditContext, the actual "rich view created from HTML" would be the focusable element with EditContext, so accessibility clients would be interacting directly with the rich HTML view instead of the textarea? Presumably, Monaco would need to keep the DOM selection in sync, etc.

Yes, in theory it could improve the situation, if Monaco did let the browser manage the selection. Although it's a bit awkward to use that example when in fact Monaco isn't doing that, and so its EditContext implementation is not particularly accessible, as far as I can tell. So maybe it's best to remove that example.

Given that this is an explainer, it seems reasonable that this could be used as a motivating example use case. However, given that it doesn't actually implement the fix, it might be appropriate to explain that EditContext could fix this (vs does fix it). For example, you could add something like the following paragraph to the bottom of that section:

With EditContext, use cases like this could be fixed by having the actual rich HTML view inside the EditContext element. This element would receive focus, so accessibility clients would be interacting directly with the real rich HTML view, rather than a separate, incomplete representation. The editor would need to ensure the DOM selection and caret were synchronized with the internal state and visual rendering of the editor.

Or we could drop this example altogether, as you suggest. The above was just an alternative if there were any desire to keep mention of this example, not something I feel strongly about.

ltenmoz commented Aug 6, 2026

View reviewed changes

ltenmoz added the Agenda+ Queue this item for discussion at the next WG meeting label Aug 6, 2026

dandclark reviewed Aug 12, 2026

View reviewed changes

ltenmoz force-pushed the explainer-a11y branch from 4eaf55e to 7479c4b Compare August 12, 2026 20:11

smaug---- mentioned this pull request Aug 13, 2026

How should canvas EditContext be made accessible? #139

Open

smaug---- removed the Agenda+ Queue this item for discussion at the next WG meeting label Aug 13, 2026

jcsteh suggested changes Aug 27, 2026

View reviewed changes

Add "Accessibility" section to explainer and spec

d132db3

ltenmoz force-pushed the explainer-a11y branch from 7479c4b to d132db3 Compare August 27, 2026 18:46


		This [example](native_selection_demo.html) shows how an author can leverage native selection when using EditContext.

		## Accessibility

Uh oh!

Conversation

ltenmoz commented Aug 6, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

smaug---- commented Aug 10, 2026

Uh oh!

dandclark left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jcsteh left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants