Editcontext API documentation

[captainbrosset]

STATUS: This PR has already been technically reviewed by engineers who worked on the API. Editorial review is ongoing.

Description

This PR adds the necessary new pages for documenting the EditContext API.

Motivation

EditContext just shipped in Chromium browsers, and the corresponding data is already in BCD. It's time to document the API on MDN for people to know how to use it.

Additional details

https://w3c.github.io/edit-context/

Related issues and pull requests

mdn/mdn#493

[captainbrosset]

Update: this PR isn't ready for review yet. It only contains the boilerplate code for each interface, method, property, event in the spec. My next step will be to fill in the main API concept, and then slowly fill in the reference pages one by one.

[github-actions]

Preview URLs (53 pages)

• /en-US/docs/Glossary/Input_method_editor
• /en-US/docs/Web/API/CharacterBoundsUpdateEvent/CharacterBoundsUpdateEvent
• /en-US/docs/Web/API/CharacterBoundsUpdateEvent/rangeEnd
• /en-US/docs/Web/API/CharacterBoundsUpdateEvent/rangeStart
• /en-US/docs/Web/API/CharacterBoundsUpdateEvent
• /en-US/docs/Web/API/CompositionEvent/locale
• /en-US/docs/Web/API/CompositionEvent
• /en-US/docs/Web/API/EditContext/EditContext
• /en-US/docs/Web/API/EditContext/attachedElements
• /en-US/docs/Web/API/EditContext/characterBoundsRangeStart
• /en-US/docs/Web/API/EditContext/characterBounds
• /en-US/docs/Web/API/EditContext/characterboundsupdate_event
• /en-US/docs/Web/API/EditContext/compositionend_event
• /en-US/docs/Web/API/EditContext/compositionstart_event
• /en-US/docs/Web/API/EditContext/selectionEnd
• /en-US/docs/Web/API/EditContext/selectionStart
• /en-US/docs/Web/API/EditContext/text
• /en-US/docs/Web/API/EditContext/textformatupdate_event
• /en-US/docs/Web/API/EditContext/textupdate_event
• /en-US/docs/Web/API/EditContext/updateCharacterBounds
• /en-US/docs/Web/API/EditContext/updateControlBounds
• /en-US/docs/Web/API/EditContext/updateSelectionBounds
• /en-US/docs/Web/API/EditContext/updateSelection
• /en-US/docs/Web/API/EditContext/updateText
• /en-US/docs/Web/API/EditContext_API
• /en-US/docs/Web/API/EditContext
• /en-US/docs/Web/API/Element/compositionend_event
• /en-US/docs/Web/API/Element/compositionstart_event
• /en-US/docs/Web/API/Element/compositionupdate_event
• /en-US/docs/Web/API/Element/keydown_event
• /en-US/docs/Web/API/Element/keyup_event
• /en-US/docs/Web/API/HTMLElement/editContext
• /en-US/docs/Web/API/HTMLElement/mscandidatewindowshow_event
• /en-US/docs/Web/API/HTMLElement/mscandidatewindowupdate_event
• /en-US/docs/Web/API/HTMLElement
• /en-US/docs/Web/API/KeyboardEvent/charCode
• /en-US/docs/Web/API/TextFormat/TextFormat
• /en-US/docs/Web/API/TextFormat/rangeEnd
• /en-US/docs/Web/API/TextFormat/rangeStart
• /en-US/docs/Web/API/TextFormat/underlineStyle
• /en-US/docs/Web/API/TextFormat/underlineThickness
• /en-US/docs/Web/API/TextFormatUpdateEvent/TextFormatUpdateEvent
• /en-US/docs/Web/API/TextFormatUpdateEvent/getTextFormats
• /en-US/docs/Web/API/TextFormatUpdateEvent
• /en-US/docs/Web/API/TextFormat
• /en-US/docs/Web/API/TextUpdateEvent/TextUpdateEvent
• /en-US/docs/Web/API/TextUpdateEvent/selectionEnd
• /en-US/docs/Web/API/TextUpdateEvent/selectionStart
• /en-US/docs/Web/API/TextUpdateEvent/text
• /en-US/docs/Web/API/TextUpdateEvent/updateRangeEnd
• /en-US/docs/Web/API/TextUpdateEvent/updateRangeStart
• /en-US/docs/Web/API/TextUpdateEvent
• /en-US/docs/Web/API/UI_Events/Keyboard_event_key_values

Flaws (14)

Note! 42 documents with no flaws that don't need to be listed. 🎉

URL: /en-US/docs/Web/API/CompositionEvent
Title: CompositionEvent
Flaw count: 1

• macros:
  • /en-US/docs/Glossary/IME does not exist

---

URL: /en-US/docs/Web/API/CompositionEvent/locale
Title: CompositionEvent: locale property
Flaw count: 1

• macros:
  • /en-US/docs/Glossary/IME does not exist

---

URL: /en-US/docs/Web/API/Element/keyup_event
Title: Element: keyup event
Flaw count: 1

• macros:
  • /en-US/docs/Glossary/IME does not exist

---

URL: /en-US/docs/Web/API/Element/compositionend_event
Title: Element: compositionend event
Flaw count: 2

• macros:
  • /en-US/docs/Glossary/IME does not exist
  • /en-US/docs/Glossary/IME does not exist

---

URL: /en-US/docs/Web/API/Element/compositionstart_event
Title: Element: compositionstart event
Flaw count: 1

• macros:
  • /en-US/docs/Glossary/IME does not exist

---

URL: /en-US/docs/Web/API/Element/compositionupdate_event
Title: Element: compositionupdate event
Flaw count: 1

• macros:
  • /en-US/docs/Glossary/IME does not exist

---

URL: /en-US/docs/Web/API/Element/keydown_event
Title: Element: keydown event
Flaw count: 1

• macros:
  • /en-US/docs/Glossary/IME does not exist

---

URL: /en-US/docs/Web/API/HTMLElement
Title: HTMLElement
Flaw count: 1

• macros:
  • /en-US/docs/Web/API/HTMLElement/attributeStyleMap does not exist

---

URL: /en-US/docs/Web/API/HTMLElement/mscandidatewindowupdate_event
Title: HTMLElement: mscandidatewindowupdate event
Flaw count: 1

• broken_links:
  • Can't resolve /en-US/docs/Web/API/Microsoft_Extensions

---

URL: /en-US/docs/Web/API/HTMLElement/mscandidatewindowshow_event
Title: HTMLElement: mscandidatewindowshow event
Flaw count: 2

• broken_links:
  • Can't resolve /en-US/docs/Web/API/getCandidateWindowClientRect
  • Can't resolve /en-US/docs/Web/API/Microsoft_Extensions

---

URL: /en-US/docs/Web/API/KeyboardEvent/charCode
Title: KeyboardEvent: charCode property
Flaw count: 2

• macros:
  • /en-US/docs/Glossary/IME does not exist
• broken_links:
  • Can't resolve /en-US/docs/Gecko_Keypress_Event

External URLs (6)

URL: /en-US/docs/Web/API/Element/keyup_event
Title: Element: keyup event

• https://bugzil.la/354358 (1 time) (Note! This may be a new URL 👀)
• https://www.w3.org/TR/ime-api/ (1 time) (Note! This may be a new URL 👀)

---

URL: /en-US/docs/Web/API/Element/compositionend_event
Title: Element: compositionend event

• https://en.wikipedia.org/wiki/Pinyin (1 time) (Note! This may be a new URL 👀)

---

URL: /en-US/docs/Web/API/Element/compositionstart_event
Title: Element: compositionstart event

• https://en.wikipedia.org/wiki/Pinyin (1 time) (Note! This may be a new URL 👀)

---

URL: /en-US/docs/Web/API/Element/compositionupdate_event
Title: Element: compositionupdate event

• https://en.wikipedia.org/wiki/Pinyin (1 time) (Note! This may be a new URL 👀)

---

URL: /en-US/docs/Web/API/Element/keydown_event
Title: Element: keydown event

• https://bugzil.la/354358 (1 time) (Note! This may be a new URL 👀)

(comment last updated: 2024-01-19 08:52:16)

[captainbrosset]

Update: the intro/concept text is now ready in the API landing page. And I've filled in about half of the reference pages. Next step is to finish filling everything in.
Potential extra next steps: create a "Using the EditContext API" tutorial that goes into even more details about how to create a fully functional canvas-based text editor.

[captainbrosset]

Update: almost done with all reference pages. About 3 remaining.

[Elchi3]

I have a demo that uses almost all of the EditContext API's methods, events, properties: https://microsoftedge.github.io/Demos/edit-context/

This is pretty cool! I like how it also makes use of some other interesting APIs like custom selection etc. It would be really cool to have a guide page or a tutorial that shows how to do interesting things by combining these APIs.

What's the best way to provide this to MDN readers? The ref doc is useful, but seeing it work altogether is important when starting out. Should I move this sample somewhere else, like on an MDN demo repo?

Examples on MDN are still a bit of a mess right now. I think the closest thing to what you have done is https://github.com/mdn/dom-examples. These examples there can be embedded into MDN pages.

Is there any guidelines related to linking to external demos from ref articles?

I'm not sure. I think we didn't really like all the glitch demo links some authors provided in the past but we did allow them. So I would say it would be okay to link to the external demo even though it's not ideal.

[Elchi3]

There are 3 pages missing. The constructors for the events:

• docs/Web/API/CharacterBoundsUpdateEvent/CharacterBoundsUpdateEvent
• docs/Web/API/TextFormatUpdateEvent/TextFormatUpdateEvent
• docs/Web/API/TextUpdateEvent/TextUpdateEvent

[Elchi3]

Some code doesn't work. Need to decide if it is e or event. Looks like you used e more.

[Elchi3]

Thanks for adding the event constructors! Some tweaks needed to the syntax box. Need to also have a line for usage without the options parameter. See https://developer.mozilla.org/en-US/docs/MDN/Writing_guidelines/Page_structures/Syntax_sections

[Elchi3]

One more general comment on the code examples (which might not be actionable, but I wanted to mention it):

For some of them I was able to paste the HTML and JS snippets into a codepen and actually saw something happening. Like when I type some text and there is an textupdate event, I see my typing appearing in the canvas and that's great.

For other examples (e.g. those with a textformatupdate event) nothing visible happens at all. Or maybe I'm doing it wrong? How to trigger it? I'm assuming you might have nothing visible here for code brevity and that's fine. What I usually like to do, though, is to have at least some console.log() statements, so that readers can at least grasp that something is in fact going on and be able to fiddle with it.

(I know it can be hard to author short code examples for reference pages, but I think they are almost always better when they can show something, even if it is just logging.)

[captainbrosset]

For other examples (e.g. those with a textformatupdate event) nothing visible happens at all. Or maybe I'm doing it wrong? How to trigger it? I'm assuming you might have nothing visible here for code brevity and that's fine. What I usually like to do, though, is to have at least some console.log() statements, so that readers can at least grasp that something is in fact going on and be able to fiddle with it.

That's a very good point and I 100% agree that standalone code samples that just work, and visibly do something, is far better.
I'll go over all examples and try to add console logs, and other things, as necessary.

It might not always be possible though. For example, for files/en-us/web/api/editcontext\textformatupdate_event/index.md, the only way to get this to run is to click on the canvas, and then trigger IME composition. This means actually having IME configured on your OS to enter Japanese/Chinese/Korean characters from a Latin keyboard. Same for files/en-us/web/api/editcontext/characterboundsupdate_event/index.md, or files/en-us/web/api/editcontext/updatecharacterbounds/index.md, and others.

Also, even if the EditContext API is useful, it does require a lot of code for it to do anything. So, some of these examples, for the sake of being short, don't really achieve much.

But, anyway, I'll go over them all and try my best to make them more visual and as standalone as they can be.

[github-actions]

This PR exceeds the recommended size of 1000 lines. Please make sure you are NOT addressing multiple issues with one PR. Note this PR might be rejected due to its size.

[Elchi3]

Thanks Patrick, great work! I made a final pass through all of the reference pages and have some more comments but after this the reference pages should be good to go.

As you say, it is not always possible to trigger the events. I was testing the code you provided by dispatching the events manually. For example:

const testEvent = new CharacterBoundsUpdateEvent("characterboundsupdate", {rangeStart: 0, rangeEnd: 3});
editContext.dispatchEvent(testEvent);

(I think such code could be example code for the event constructor pages, but of course using event constructors and dispatching events manually isn't something you'd normally do)

[Elchi3]

One more thing: BCD marks this API as experimental (because it is in just one engine). If you don't mark things as experimental in this PR, I think Onkar's bot will update all this PR's files automatically in a follow-up PR (adding the status: experimental front matter, and the {{SeeCompatTable}} and {{Experimental_Inline}} macros).

[captainbrosset]

One more thing: BCD marks this API as experimental (because it is in just one engine). If you don't mark things as experimental in this PR, I think Onkar's bot will update all this PR's files automatically in a follow-up PR (adding the status: experimental front matter, and the {{SeeCompatTable}} and {{Experimental_Inline}} macros).

I added the experimental status and seecompattable macro. I'm not quite sure where the experimental_inline macro should go, so I left that out. It seems like it needs to go in front of each and every method, event, property, and constructor in a reference page. I wasn't sure, so I didn't want to do all this work for nothing, especially if we have a tool to do it.

[Elchi3]

Thanks @captainbrosset! 👍 I'm happy with this! I will merge it, so all of there reference pages can land.
The inline experimental macros can be added by Onkar's automation, you're right to not necessarily worry about them now.
We also haven't talked further about where to put a more extensive example (or a link to it) but I think that could also be a follow-up.

Let's get this in! Great work!

[captainbrosset]

Thank you Florian for the great reviews and help.
I'll make a note to start a new PR that contains a guide to how to use the API. This will be more of a step by step tutorial that guides the person through all of the steps that are required to build a complete editor with the API.
I'm thinking about using the https://microsoftedge.github.io/Demos/edit-context/ demo I made for this. But we'll need to decide where it should go. I'm happy to keep it on our Edge Demos repo, but I understand that it may need to go to a more neutral place too.