From 603f0d6d59031e24ca4b5ce2a226a627811c43d1 Mon Sep 17 00:00:00 2001
From: Patrick Brosset <patrick.brosset@microsoft.com>
Date: Wed, 31 Jan 2024 11:03:08 +0100
Subject: [PATCH 1/9] Start of an EditContext tutorial

---
 .../web/api/editcontext_api/guide/index.md    | 187 ++++++++++++++++++
 files/jsondata/GroupData.json                 |   1 +
 2 files changed, 188 insertions(+)
 create mode 100644 files/en-us/web/api/editcontext_api/guide/index.md

diff --git a/files/en-us/web/api/editcontext_api/guide/index.md b/files/en-us/web/api/editcontext_api/guide/index.md
new file mode 100644
index 000000000000000..d6410efeabeca66
--- /dev/null
+++ b/files/en-us/web/api/editcontext_api/guide/index.md
@@ -0,0 +1,187 @@
+---
+title: Using the EditContext API
+slug: Web/API/EditContext_API/Guide
+page-type: guide
+---
+
+{{DefaultAPISidebar("EditContext API")}}
+
+The **[EditContext API](/en-US/docs/Web/API/EditContext_API)** can be used to build rich text editors on the web that support advanced text input experiences, such as {{glossary("Input Method Editor")}} (IME) composition, emoji picker, or any other platform-specific editing-related UI surfaces.
+
+This article goes through all the steps that are necessary to build a text editor using the EditContext API. In this guide, you will build a simple HTML code editor that highlights the syntax of the code as you type, and that supports IME composition.
+
+## Final code and live demo
+
+If you want to see the final code, you can check out the [live demo](https://mdn.github.io/dom-examples/editcontext-api/html-editor/) and [source code](https://github.com/mdn/dom-examples/tree/master/editcontext-api/html-editor) on GitHub.
+
+## Create the editor UI
+
+The first step is to create the UI for the editor. The editor will be a simple [`<div>`](/en-US/docs/Web/HTML/Element/div) element with he [`spellcheck`](/en-US/docs/Web/HTML/Global_attributes/spellcheck) attribute set to `false` to disable spell checking:
+
+```html
+<div id="html-editor" spellcheck="false"></div>
+```
+
+The following CSS code is used to make the editor fill the entire viewport and scroll when there's too much content to fit. The [`white-space`](/en-US/docs/Web/CSS/white-space) property is also used to preserve whitespace, and the [`tab-size`](/en-US/docs/Web/CSS/tab-size) property is used to make tab characters render as two spaces. Finally, some default background and text colors are set.
+
+```css
+#html-editor {
+  width: 100%;
+  height: 100%;
+  box-sizing: border-box;
+  padding: 1rem;
+  overflow: auto;
+  white-space: pre;
+  tab-size: 2;
+  background: #000;
+  color: red;
+}
+```
+
+## Make the editor editable
+
+To make an element editable on the web, most of the time, you use an [`<input>`](/en-US/docs/Web/HTML/Element/input) element, a [`<textarea>`](/en-US/docs/Web/HTML/Element/textarea) element, or the [`contenteditable`](/en-US/docs/Web/HTML/Global_attributes/contenteditable) attribute.
+
+However, with the EditContext API, you can make other types of elements editable without using an attribute. To see the list of elements that can be used with the EditContext API, see [Possible elements](/en-US/docs/Web/API/HTMLElement/editContext#possible_elements) on the HTMLElement editContext property page.
+
+To make the editor editable, you create an {{domxref("EditContext")}} instance, and then you set the [`editContext`](/en-US/docs/Web/API/HTMLElement/editContext) property of the editor element to the `EditContext` instance:
+
+```js
+if ("EditContext" in window) {
+  // Create the EditContext instance.
+  const editContext = new EditContext();
+
+  // Retrieve the editor element from the DOM.
+  const editorEl = document.getElementById("html-editor");
+
+  // Set the editor's editContext property value.
+  editorEl.editContext = editContext;
+} else {
+  console.log("The EditContext API is not supported.");
+}
+```
+
+You can now focus the editor element. Entering text in the element will fire the {{domxref("EditContext.textupdate_event", "textupdate")}} event on the `EditContext` instance.
+
+## Render the text
+
+The next step is to write a function that renders the syntax-highlighted HTML code in the editor when the user enters text. This function will be called when new text is entered, when characters are deleted, or when the selection is changed.
+
+### Tokenizing the HTML code
+
+In order to render the syntax-highlighted HTML, you'll first need to tokenize the HTML code. This means reading the HTML code string, and determining where each opening tag, closing tag, attribute, comment node, and text node start and end. This can be done by iterating over the string character by character while maintaining a state machine.
+
+Since this is a guide about the EditContext API, the tokenizer code is not shown here. You can find the tokenizer code used in this tutorial in the [source code](https://github.com/mdn/dom-examples/blob/main/editcontext-api/html-editor/tokenizer.js).
+
+For the purpose of this tutorial, let's assume that the tokenizer is a function that's imported from a separate file:
+
+```js
+import { tokenizeHTML } from "./tokenizer.js";
+```
+
+### The render function
+
+For the `render` function, let's start the following simple code snippet:
+
+```js
+function render() {
+  // First, empty the editor. We're re-rendering everything.
+  editorEl.innerHTML = "";
+
+  // Tokenize the text.
+  const currentTokens = tokenizeHTML(editContext.text);
+
+  for (const token of currentTokens) {
+    // Render each token as a span element.
+    const span = document.createElement("span");
+    span.classList.add(`token-${token.type}`);
+    span.textContent = token.value;
+
+    // Attach the span to the editor element.
+    editorEl.appendChild(span);
+  }
+}
+```
+
+With the above code, it's easy to see that the EditContext API makes you responsible for rendering the user interface of your editor. You can render the HTML text any other way you want, including rendering it into a `<canvas>` element.
+
+Make sure to call the render function when needed. This includes calling it once at the beginning, when initializing the editor, and then calling it again when the user enters text, by listening to the {{domxref("EditContext.textupdate_event", "textupdate")}} event:
+
+```js
+// Listen to the EditContext's textupdate event.
+// This tells us when text input happens. We use it to re-render the view.
+editContext.addEventListener("textupdate", (e) => {
+  render();
+});
+
+// Do the initial render.
+render();
+```
+
+## Handle tab, enter, and other text edit keys
+
+The `textupdate` event used in the previous section isn't fired when the user presses the <kbd>Tab</kbd> or <kbd>Enter</kbd> keys, so you need to handle these keys separately.
+
+To handle them, you can listen to the {{domxref("keydown_event", "keydown")}} event on the editor element, and use it to update the `EditContext` instance's text content and selection, as shown below:
+
+```js
+// Handle key presses that are not already handled by the EditContext.
+editorEl.addEventListener("keydown", (e) => {
+  // Handling the Tab key.
+  if (e.key === "Tab") {
+    // Prevent the default behavior of the Tab key.
+    e.preventDefault();
+
+    // Use the EditContext.updateText method to insert a tab character
+    // at the current selection position.
+    editContext.updateText(
+      editContext.selectionStart,
+      editContext.selectionEnd,
+      "\t",
+    );
+
+    // Update the selection to be after the inserted tab character.
+    editContext.updateSelection(
+      editContext.selectionStart + 1,
+      editContext.selectionStart + 1,
+    );
+
+    // Re-render the editor.
+    render();
+  }
+
+  // Handling the Enter key.
+  if (e.key === "Enter") {
+    // Use the EditContext.updateText method to insert a newline character
+    // at the current selection position.
+    editContext.updateText(
+      editContext.selectionStart,
+      editContext.selectionEnd,
+      "\n",
+    );
+
+    // Update the selection to be after the inserted newline character.
+    editContext.updateSelection(
+      editContext.selectionStart + 1,
+      editContext.selectionStart + 1,
+    );
+
+    // Re-render the editor.
+    render();
+  }
+});
+```
+
+## Updating the control bounds
+
+## Updating the selection
+
+## Calculating character bounds for IME composition
+
+## Applying IME composition text formats
+
+## Summary
+
+## See also
+
+- [EditContext API](/en-US/docs/Web/API/EditContext_API)
diff --git a/files/jsondata/GroupData.json b/files/jsondata/GroupData.json
index 79d28627d5513ec..5a6ecb9decadbf2 100644
--- a/files/jsondata/GroupData.json
+++ b/files/jsondata/GroupData.json
@@ -414,6 +414,7 @@
     },
     "EditContext API": {
       "overview": ["EditContext API"],
+      "guides": ["/docs/Web/API/EditContext_API/Guide"],
       "interfaces": [
         "EditContext",
         "TextFormat",

From ddfbeaa8dba41ca472d8b7193571ca9aa42c3977 Mon Sep 17 00:00:00 2001
From: Patrick Brosset <patrick.brosset@microsoft.com>
Date: Wed, 31 Jan 2024 15:17:48 +0100
Subject: [PATCH 2/9] Finalized the tutorial content

---
 .../web/api/editcontext_api/guide/index.md    | 335 +++++++++++++++++-
 1 file changed, 324 insertions(+), 11 deletions(-)

diff --git a/files/en-us/web/api/editcontext_api/guide/index.md b/files/en-us/web/api/editcontext_api/guide/index.md
index d6410efeabeca66..0e8757cf2f05960 100644
--- a/files/en-us/web/api/editcontext_api/guide/index.md
+++ b/files/en-us/web/api/editcontext_api/guide/index.md
@@ -63,13 +63,13 @@ if ("EditContext" in window) {
 
 You can now focus the editor element. Entering text in the element will fire the {{domxref("EditContext.textupdate_event", "textupdate")}} event on the `EditContext` instance.
 
-## Render the text
+## Render the text and user selection
 
 The next step is to write a function that renders the syntax-highlighted HTML code in the editor when the user enters text. This function will be called when new text is entered, when characters are deleted, or when the selection is changed.
 
-### Tokenizing the HTML code
+### Tokenize the HTML code
 
-In order to render the syntax-highlighted HTML, you'll first need to tokenize the HTML code. This means reading the HTML code string, and determining where each opening tag, closing tag, attribute, comment node, and text node start and end. This can be done by iterating over the string character by character while maintaining a state machine.
+In order to render the syntax-highlighted HTML, you'll first need to tokenize the HTML code. This means reading the HTML code string, and determining where each opening tag, closing tag, attribute, comment node, and text node starts and ends. This can be done by iterating over the string character by character while maintaining a state machine.
 
 Since this is a guide about the EditContext API, the tokenizer code is not shown here. You can find the tokenizer code used in this tutorial in the [source code](https://github.com/mdn/dom-examples/blob/main/editcontext-api/html-editor/tokenizer.js).
 
@@ -79,9 +79,9 @@ For the purpose of this tutorial, let's assume that the tokenizer is a function
 import { tokenizeHTML } from "./tokenizer.js";
 ```
 
-### The render function
+### Render the text
 
-For the `render` function, let's start the following simple code snippet:
+To render the text, let's create a `render` function that will be called whenever the user enters text, or when the selection changes. This function will first empty the editor element, and then it will render each token as a separate HTML element:
 
 ```js
 function render() {
@@ -99,11 +99,14 @@ function render() {
 
     // Attach the span to the editor element.
     editorEl.appendChild(span);
+
+    // Save the span element in the token object for later.
+    token.node = span;
   }
 }
 ```
 
-With the above code, it's easy to see that the EditContext API makes you responsible for rendering the user interface of your editor. You can render the HTML text any other way you want, including rendering it into a `<canvas>` element.
+As seen above, with the EditContext API, you are responsible for rendering the user interface of your editor. You can render the HTML text any way you want, including rendering it into a `<canvas>` element.
 
 Make sure to call the render function when needed. This includes calling it once at the beginning, when initializing the editor, and then calling it again when the user enters text, by listening to the {{domxref("EditContext.textupdate_event", "textupdate")}} event:
 
@@ -118,7 +121,95 @@ editContext.addEventListener("textupdate", (e) => {
 render();
 ```
 
-## Handle tab, enter, and other text edit keys
+### Render the selection
+
+Even though you used a `<div>` element for the editor, which already supports displaying a blinking text cursor and highlighting the selected text, you still need to render the selection yourself. This is because the EditContext API can be used with other types of elements that don't support this behavior. Rendering the selection yourself also gives you more control over how the selection is displayed. Finally, because your `render` function clears the HTML content of the editor element everytime it runs, any selection that the user might have made will be lost if you don't render it yourself.
+
+To render the selection, because the EditContext API gives you the selection as a pair of start and end character offsets, you'll need to convert these offsets into a DOM selection. The following code snippet shows how you can do this:
+
+```js
+function convertFromOffsetsToSelection(start, end) {
+  // Create a TreeWalker that walks over all the
+  // text nodes in the editor element.
+  const treeWalker = document.createTreeWalker(editorEl, NodeFilter.SHOW_TEXT);
+
+  let offset = 0;
+  let anchorNode = null;
+  let anchorOffset = 0;
+  let extentNode = null;
+  let extentOffset = 0;
+
+  // Iterate over the text nodes.
+  while (treeWalker.nextNode()) {
+    const node = treeWalker.currentNode;
+
+    if (!anchorNode && offset + node.textContent.length >= start) {
+      // The anchor node is the first node that contains the start offset.
+      anchorNode = node;
+      anchorOffset = start - offset;
+    }
+
+    if (offset + node.textContent.length >= end) {
+      // The extent node is the first node that contains the end offset.
+      extentNode = node;
+      extentOffset = end - offset;
+      break;
+    }
+
+    offset += node.textContent.length;
+  }
+
+  // Return an object that can be used to create a DOM selection.
+  return { anchorNode, anchorOffset, extentNode, extentOffset };
+}
+```
+
+With the above function, you can now update the `render` function created earlier to render the current selection by using the {{DOMxRef("Selection.setBaseAndExtent()")}} method:
+
+```js
+function render() {
+  // ...
+  // The beginning of the render function is omitted for brevity.
+
+  // Render the selection at the correct location by
+  // converting the start/end offsets to a DOM selection.
+  const selectionStart = editContext.selectionStart;
+  const selectionEnd = editContext.selectionEnd;
+
+  const { anchorNode, anchorOffset, extentNode, extentOffset } =
+    convertFromOffsetsToSelection(selectionStart, selectionEnd);
+
+  document
+    .getSelection()
+    .setBaseAndExtent(anchorNode, anchorOffset, extentNode, extentOffset);
+}
+```
+
+## Update the control bounds
+
+The EditContext API gives you a lot of flexibility to define your own text editor UI. However, this also means that you need to handle some things that are usually handled by the browser or operating system (OS).
+
+For example, you must tell the OS where the editable text region is located on the page. This way, the OS can correctly position any text-editing UI that the user might be composing text with, such as an IME composition window.
+
+This is done by calling the {{domxref("EditContext.updateControlBounds()")}} method, and passing it a {{domxref("DOMRect")}} object that represents the bounds of the editable text region:
+
+```js
+function updateControlBounds() {
+  // Get the DOMRect object for the editor element.
+  const editorBounds = editorEl.getBoundingClientRect();
+
+  // Update the control bounds of the EditContext instance.
+  editContext.updateControlBounds(editorBounds);
+}
+
+// Call the updateControlBounds function when the editor is initialized,
+updateControlBounds();
+
+// And call it again when the window is resized.
+window.addEventListener("resize", updateControlBounds);
+```
+
+## Handle Tab, Enter, and other text edit keys
 
 The `textupdate` event used in the previous section isn't fired when the user presses the <kbd>Tab</kbd> or <kbd>Enter</kbd> keys, so you need to handle these keys separately.
 
@@ -172,16 +263,238 @@ editorEl.addEventListener("keydown", (e) => {
 });
 ```
 
-## Updating the control bounds
+You might also want to handle other key combinations like <kbd>Ctrl</kbd>+<kbd>C</kbd> and <kbd>Ctrl</kbd>+<kbd>V</kbd> to copy and paste text, or <kbd>Ctrl</kbd>+<kbd>Z</kbd> and <kbd>Ctrl</kbd>+<kbd>Y</kbd> to undo and redo text changes.
+
+## Update the selection state and selection bounds
+
+Earlier, you wrote code to _render_ the selection in the editor element. But you also need to _update_ the selection state and bounds when the user changes the selection. The EditContext API doesn't do this for you, again because you might choose to implement your editor UI in a different way, such as by using a `<canvas>` element.
+
+To know when the user changes the selection, use the {{domxref("Document/selectionchange_event", "selectionchange")}} event and the {{domxref("Document.getSelection()")}} method. This will give you a {{DOMxRef("Selection")}} object. Because the EditContext API uses character offsets to represent the selection, you'll need to convert the DOM selection to character offsets. This can be done by using the following function:
+
+```js
+function convertFromSelectionToOffsets(selection) {
+  // Create a TreeWalker that walks over all the
+  // text nodes in the editor element.
+  const treeWalker = document.createTreeWalker(editorEl, NodeFilter.SHOW_TEXT);
+
+  let anchorNodeFound = false;
+  let extentNodeFound = false;
+  let anchorOffset = 0;
+  let extentOffset = 0;
+
+  // Iterate over the text nodes until we find
+  // the anchor and extent nodes given by the selection.
+  while (treeWalker.nextNode()) {
+    const node = treeWalker.currentNode;
+    if (node === selection.anchorNode) {
+      anchorNodeFound = true;
+      anchorOffset += selection.anchorOffset;
+    }
+
+    if (node === selection.extentNode) {
+      extentNodeFound = true;
+      extentOffset += selection.extentOffset;
+    }
+
+    if (!anchorNodeFound) {
+      anchorOffset += node.textContent.length;
+    }
+    if (!extentNodeFound) {
+      extentOffset += node.textContent.length;
+    }
+  }
+
+  // Return null if the nodes couldn't be found.
+  // The selection is outside the editor element.
+  if (!anchorNodeFound || !extentNodeFound) {
+    return null;
+  }
+
+  if (anchorOffset > extentOffset) {
+    [anchorOffset, extentOffset] = [extentOffset, anchorOffset];
+  }
+
+  return { start: anchorOffset, end: extentOffset };
+}
+```
+
+With the above function, listen to the `selectionchange` event and update the EditContext selection state. Also update the bounds of the selection using the {{domxref("EditContext.updateSelectionBounds()")}} method. This is used by the OS to position the IME composition window correctly:
+
+```js
+// Listen to selectionchange events to let the
+// EditContext know where it is.
+document.addEventListener("selectionchange", () => {
+  const selection = document.getSelection();
+  const offsets = convertFromSelectionToOffsets(selection);
+  if (!offsets) {
+    return;
+  }
+
+  // Update the selection.
+  editContext.updateSelection(offsets.start, offsets.end);
+
+  // Get the bounds of the selection.
+  editContext.updateSelectionBounds(
+    document.getSelection().getRangeAt(0).getBoundingClientRect(),
+  );
+});
+```
+
+## Calculate character bounds
+
+Earlier, you used the {{domxref("EditContext.updateControlBounds()")}} and {{domxref("EditContext.updateSelectionBounds()")}} methods to help the OS position any text editing UI that the user might be composing text with, such as an IME composition window. There's one more bit of information that the OS requires to do this correctly: the position and size of certain characters within the editor element.
+
+To do this, you'll need to listen to the {{domxref("EditContext.characterboundsupdate_event", "characterboundsupdate")}} event, use it to calculate the bounds of some of the characters in the editor element, and then use the {{domxref("EditContext.updateCharacterBounds()")}} method to update the character bounds.
+
+The EditContext API only uses character offsets, which means that the `characterboundsupdate` event will only tell you the start and end offsets for the characters it needs bounds for. It's up to you to find the DOM elements that these characters have been rendered in, and to calculate the bounds for these characters. To help with this, you'll first create a function that converts from character offsets to DOM elements:
+
+```js
+function convertFromOffsetsToListOfRenderedTokenNodes(start, end) {
+  const tokenNodes = [];
+
+  // Go over all character offsets in the range.
+  for (let offset = start; offset < end; offset++) {
+    // Find the DOM node that contains this character.
+    // This assumes that the `currentTokens` array is accessible,
+    // and that each item of the `currentTokens` array has a
+    // `node` and `pos` property.
+    const token = currentTokens.find(
+      (token) => token.pos <= offset && token.pos + token.value.length > offset,
+    );
+    if (token) {
+      tokenNodes.push({
+        node: token.node,
+        nodeOffset: token.pos,
+        charOffset: offset,
+      });
+    }
+  }
+
+  return tokenNodes;
+}
+```
+
+With the above function, you can now listen to the `characterboundsupdate` event, and use it to calculate the bounds of the characters in the editor element:
+
+```js
+editContext.addEventListener("characterboundsupdate", (e) => {
+  // Retrieve information about the token nodes in the range.
+  const tokenNodes = convertFromOffsetsToListOfRenderedTokenNodes(
+    e.rangeStart,
+    e.rangeEnd,
+  );
+
+  // Convert this information into a list of DOMRect objects.
+  const charBounds = tokenNodes.map(({ node, nodeOffset, charOffset }) => {
+    const range = document.createRange();
+    range.setStart(node.firstChild, charOffset - nodeOffset);
+    range.setEnd(node.firstChild, charOffset - nodeOffset + 1);
+    return range.getBoundingClientRect();
+  });
+
+  // Let the EditContext instance know about the character bounds.
+  editContext.updateCharacterBounds(e.rangeStart, charBounds);
+});
+```
+
+## Apply IME composition text formats
 
-## Updating the selection
+For the final step, there is one more thing you need to do to fully support IME composition. When the user is composing text with an IME, the IME might decide that certain parts of the text being composed should be formatted differently to indicate the composition state. For example, the IME might decide to render the text in a different color, or to underline it.
 
-## Calculating character bounds for IME composition
+Because you're responsible for rendering the content in the editable text region, the EditContext API doesn't do this for you. Instead, the API fires the {{domxref("EditContext.textformatupdate_event", "textformatupdate")}} event, and it's up to you to listen to this event and apply the formatting to the text.
 
-## Applying IME composition text formats
+As shown in the following code snippet, you will use the `convertFromOffsetsToSelection` function again to find the DOM nodes that are in the range of the IME composition. Let's also use the [CSS Custom Highlight API](/en-US/docs/Web/API/CSS_Custom_Highlight_API) to render the text formats. The CSS Custom Highlight API provides a mechanism for styling arbitrary text ranges by using JavaScript to create the ranges, and CSS to style them.
+
+First, use the {{cssxref("::highlight", "::highlight()")}} pseudo-element to define the highlight styles. The text formats define the style and thickness of an underline. So, create as many highlights as there are possible combinations of underline styles and thicknesses:
+
+```css
+::highlight(ime-solid-thin) {
+  text-decoration: underline 1px;
+}
+
+::highlight(ime-solid-thick) {
+  text-decoration: underline 2px;
+}
+
+::highlight(ime-double-thin) {
+  text-decoration: underline double 1px;
+}
+
+::highlight(ime-double-thick) {
+  text-decoration: underline double 2px;
+}
+
+/* The rest of the highlights are omitted for brevity. */
+```
+
+Next, create instances of the highlights using the {{domxref("Highlight")}} constructor, store them in an object, and register them in the {{domxref("HighlightRegistry")}} by using the {{domxref("CSS/highlights_static", "CSS.highlights")}} property:
+
+```js
+// Instances of CSS custom Highlight objects, used to render
+// the IME composition text formats.
+const imeHighlights = {
+  "solid-thin": null,
+  "solid-thick": null,
+  "double-thin": null,
+  "double-thick": null,
+  "dotted-thin": null,
+  "dotted-thick": null,
+  "dashed-thin": null,
+  "dashed-thick": null,
+  "wavy-thin": null,
+  "wavy-thick": null,
+  "squiggle-thin": null,
+  "squiggle-thick": null,
+};
+for (const [key, value] of Object.entries(imeHighlights)) {
+  imeHighlights[key] = new Highlight();
+  CSS.highlights.set(`ime-${key}`, imeHighlights[key]);
+}
+```
+
+Now, you can listen to the `textformatupdate` event, and use it to apply the IME composition text formats:
+
+```js
+editContext.addEventListener("textformatupdate", (e) => {
+  // Get the list of formats that the IME wants to apply.
+  const formats = e.getTextFormats();
+
+  // Iterate over the text formats.
+  for (const format of formats) {
+    // For each format, we know the underline style and thickness,
+    // as well as the start and end offsets of the range that needs
+    // to be styled.
+    const { rangeStart, rangeEnd, underlineStyle, underlineThickness } = format;
+
+    // Find the nodes that are in the range of the current format.
+    const { anchorNode, anchorOffset, extentNode, extentOffset } =
+      convertFromOffsetsToSelection(rangeStart, rangeEnd);
+
+    // Get the right Highlight instance.
+    const highlight =
+      imeHighlights[
+        `${format.underlineStyle.toLowerCase()}-${format.underlineThickness.toLowerCase()}`
+      ];
+
+    // Create a range object for the range that needs to be styled
+    // And add it to the Highlight object.
+    const range = document.createRange();
+    range.setStart(anchorNode, anchorOffset);
+    range.setEnd(extentNode, extentOffset);
+    highlight.add(range);
+  }
+});
+```
 
 ## Summary
 
+This article showed you how to use the EditContext API to build a simple HTML code editor that supports IME composition and syntax highlighting.
+
+The final code and live demo can be found on GitHub: [live demo](https://mdn.github.io/dom-examples/editcontext-api/html-editor/) and [source code](https://github.com/mdn/dom-examples/tree/master/editcontext-api/html-editor).
+
+More importantly, this article showed you that the EditContext API provides a lot of flexibility when it comes to the user interface of your editor. Based on this demo, you could build a similar text editor that uses a `<canvas>` element to render the syntax-highlighted HTML code instead of the `<div>` that the demo uses. You could also change how each token is rendered, or how the selection is rendered.
+
 ## See also
 
 - [EditContext API](/en-US/docs/Web/API/EditContext_API)
+- [CSS Custom Highlight API](/en-US/docs/Web/API/CSS_Custom_Highlight_API)

From 4028aa5b266b85cb194343a1fb29639c2473c1f2 Mon Sep 17 00:00:00 2001
From: Patrick Brosset <patrickbrosset@gmail.com>
Date: Thu, 1 Feb 2024 10:49:45 +0100
Subject: [PATCH 3/9] Apply suggestions from code review

Co-authored-by: skyclouds2001 <95597335+skyclouds2001@users.noreply.github.com>
---
 files/en-us/web/api/editcontext_api/guide/index.md | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/files/en-us/web/api/editcontext_api/guide/index.md b/files/en-us/web/api/editcontext_api/guide/index.md
index 0e8757cf2f05960..1e179ee2ab53579 100644
--- a/files/en-us/web/api/editcontext_api/guide/index.md
+++ b/files/en-us/web/api/editcontext_api/guide/index.md
@@ -16,13 +16,13 @@ If you want to see the final code, you can check out the [live demo](https://mdn
 
 ## Create the editor UI
 
-The first step is to create the UI for the editor. The editor will be a simple [`<div>`](/en-US/docs/Web/HTML/Element/div) element with he [`spellcheck`](/en-US/docs/Web/HTML/Global_attributes/spellcheck) attribute set to `false` to disable spell checking:
+The first step is to create the UI for the editor. The editor will be a simple {{HTMLElement("div")}} element with the [`spellcheck`](/en-US/docs/Web/HTML/Global_attributes/spellcheck) attribute set to `false` to disable spell checking:
 
 ```html
 <div id="html-editor" spellcheck="false"></div>
 ```
 
-The following CSS code is used to make the editor fill the entire viewport and scroll when there's too much content to fit. The [`white-space`](/en-US/docs/Web/CSS/white-space) property is also used to preserve whitespace, and the [`tab-size`](/en-US/docs/Web/CSS/tab-size) property is used to make tab characters render as two spaces. Finally, some default background and text colors are set.
+The following CSS code is used to make the editor fill the entire viewport and scroll when there's too much content to fit. The {{CSSXref("white-space")}} property is also used to preserve whitespace, and the {{CSSXref("tab-size")}} property is used to make tab characters render as two spaces. Finally, some default background and text colors are set.
 
 ```css
 #html-editor {
@@ -40,11 +40,11 @@ The following CSS code is used to make the editor fill the entire viewport and s
 
 ## Make the editor editable
 
-To make an element editable on the web, most of the time, you use an [`<input>`](/en-US/docs/Web/HTML/Element/input) element, a [`<textarea>`](/en-US/docs/Web/HTML/Element/textarea) element, or the [`contenteditable`](/en-US/docs/Web/HTML/Global_attributes/contenteditable) attribute.
+To make an element editable on the web, most of the time, you use an {{HTMLElement("input")}} element, a {{HTMLElement("textarea")}} element, or the [`contenteditable`](/en-US/docs/Web/HTML/Global_attributes/contenteditable) attribute.
 
 However, with the EditContext API, you can make other types of elements editable without using an attribute. To see the list of elements that can be used with the EditContext API, see [Possible elements](/en-US/docs/Web/API/HTMLElement/editContext#possible_elements) on the HTMLElement editContext property page.
 
-To make the editor editable, you create an {{domxref("EditContext")}} instance, and then you set the [`editContext`](/en-US/docs/Web/API/HTMLElement/editContext) property of the editor element to the `EditContext` instance:
+To make the editor editable, you create an {{domxref("EditContext")}} instance, and then you set the {{DOMxRef("HTMLElement.editContext", "editContext")}} property of the editor element to the `EditContext` instance:
 
 ```js
 if ("EditContext" in window) {

From 69f710473324e76edd7da430b46ab6a7d0e0f3ac Mon Sep 17 00:00:00 2001
From: Patrick Brosset <patrick.brosset@microsoft.com>
Date: Thu, 1 Feb 2024 10:52:08 +0100
Subject: [PATCH 4/9] Fixed the demo links

---
 files/en-us/web/api/editcontext_api/guide/index.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/files/en-us/web/api/editcontext_api/guide/index.md b/files/en-us/web/api/editcontext_api/guide/index.md
index 1e179ee2ab53579..b4167cacead1a47 100644
--- a/files/en-us/web/api/editcontext_api/guide/index.md
+++ b/files/en-us/web/api/editcontext_api/guide/index.md
@@ -12,7 +12,7 @@ This article goes through all the steps that are necessary to build a text edito
 
 ## Final code and live demo
 
-If you want to see the final code, you can check out the [live demo](https://mdn.github.io/dom-examples/editcontext-api/html-editor/) and [source code](https://github.com/mdn/dom-examples/tree/master/editcontext-api/html-editor) on GitHub.
+If you want to see the final code, you can check out the [live demo](https://mdn.github.io/dom-examples/edit-context/html-editor/) and [source code](https://github.com/mdn/dom-examples/tree/main/edit-context/html-editor) on GitHub.
 
 ## Create the editor UI
 
@@ -490,7 +490,7 @@ editContext.addEventListener("textformatupdate", (e) => {
 
 This article showed you how to use the EditContext API to build a simple HTML code editor that supports IME composition and syntax highlighting.
 
-The final code and live demo can be found on GitHub: [live demo](https://mdn.github.io/dom-examples/editcontext-api/html-editor/) and [source code](https://github.com/mdn/dom-examples/tree/master/editcontext-api/html-editor).
+The final code and live demo can be found on GitHub: [live demo](https://mdn.github.io/dom-examples/edit-context/html-editor/) and [source code](https://github.com/mdn/dom-examples/tree/main/edit-context/html-editor).
 
 More importantly, this article showed you that the EditContext API provides a lot of flexibility when it comes to the user interface of your editor. Based on this demo, you could build a similar text editor that uses a `<canvas>` element to render the syntax-highlighted HTML code instead of the `<div>` that the demo uses. You could also change how each token is rendered, or how the selection is rendered.
 

From d81e0faa9fc169d8fe25ca331ee686d6204e20e8 Mon Sep 17 00:00:00 2001
From: Patrick Brosset <patrick.brosset@microsoft.com>
Date: Thu, 1 Feb 2024 11:56:32 +0100
Subject: [PATCH 5/9] Addressed review comments from Dan

---
 .../web/api/editcontext_api/guide/index.md    | 64 +++++++++----------
 1 file changed, 30 insertions(+), 34 deletions(-)

diff --git a/files/en-us/web/api/editcontext_api/guide/index.md b/files/en-us/web/api/editcontext_api/guide/index.md
index b4167cacead1a47..9659600df1bb5fe 100644
--- a/files/en-us/web/api/editcontext_api/guide/index.md
+++ b/files/en-us/web/api/editcontext_api/guide/index.md
@@ -129,6 +129,11 @@ To render the selection, because the EditContext API gives you the selection as
 
 ```js
 function convertFromOffsetsToSelection(start, end) {
+  // Deal with backwards selections.
+  const isBackwards = start > end;
+  const orderedStart = isBackwards ? end : start;
+  const orderedEnd = isBackwards ? start : end;
+
   // Create a TreeWalker that walks over all the
   // text nodes in the editor element.
   const treeWalker = document.createTreeWalker(editorEl, NodeFilter.SHOW_TEXT);
@@ -143,16 +148,16 @@ function convertFromOffsetsToSelection(start, end) {
   while (treeWalker.nextNode()) {
     const node = treeWalker.currentNode;
 
-    if (!anchorNode && offset + node.textContent.length >= start) {
+    if (!anchorNode && offset + node.textContent.length >= orderedStart) {
       // The anchor node is the first node that contains the start offset.
       anchorNode = node;
-      anchorOffset = start - offset;
+      anchorOffset = orderedStart - offset;
     }
 
-    if (offset + node.textContent.length >= end) {
+    if (offset + node.textContent.length >= orderedEnd) {
       // The extent node is the first node that contains the end offset.
       extentNode = node;
-      extentOffset = end - offset;
+      extentOffset = orderedEnd - offset;
       break;
     }
 
@@ -160,7 +165,12 @@ function convertFromOffsetsToSelection(start, end) {
   }
 
   // Return an object that can be used to create a DOM selection.
-  return { anchorNode, anchorOffset, extentNode, extentOffset };
+  return {
+    anchorNode: isBackwards ? extentNode : anchorNode,
+    anchorOffset: isBackwards ? extentOffset : anchorOffset,
+    extentNode: isBackwards ? anchorNode : extentNode,
+    extentOffset: isBackwards ? anchorOffset : extentOffset,
+  };
 }
 ```
 
@@ -218,6 +228,12 @@ To handle them, you can listen to the {{domxref("keydown_event", "keydown")}} ev
 ```js
 // Handle key presses that are not already handled by the EditContext.
 editorEl.addEventListener("keydown", (e) => {
+  // EditContext.updateText() expects the start and end offsets
+  // to be in the correct order, but the current selection state
+  // might be backwards.
+  const start = Math.min(editContext.selectionStart, editContext.selectionEnd);
+  const end = Math.max(editContext.selectionStart, editContext.selectionEnd);
+
   // Handling the Tab key.
   if (e.key === "Tab") {
     // Prevent the default behavior of the Tab key.
@@ -225,17 +241,10 @@ editorEl.addEventListener("keydown", (e) => {
 
     // Use the EditContext.updateText method to insert a tab character
     // at the current selection position.
-    editContext.updateText(
-      editContext.selectionStart,
-      editContext.selectionEnd,
-      "\t",
-    );
+    editContext.updateText(start, end, "\t");
 
     // Update the selection to be after the inserted tab character.
-    editContext.updateSelection(
-      editContext.selectionStart + 1,
-      editContext.selectionStart + 1,
-    );
+    editContext.updateSelection(start + 1, start + 1);
 
     // Re-render the editor.
     render();
@@ -245,17 +254,10 @@ editorEl.addEventListener("keydown", (e) => {
   if (e.key === "Enter") {
     // Use the EditContext.updateText method to insert a newline character
     // at the current selection position.
-    editContext.updateText(
-      editContext.selectionStart,
-      editContext.selectionEnd,
-      "\n",
-    );
+    editContext.updateText(start, end, "\n");
 
     // Update the selection to be after the inserted newline character.
-    editContext.updateSelection(
-      editContext.selectionStart + 1,
-      editContext.selectionStart + 1,
-    );
+    editContext.updateSelection(start + 1, start + 1);
 
     // Re-render the editor.
     render();
@@ -310,10 +312,6 @@ function convertFromSelectionToOffsets(selection) {
     return null;
   }
 
-  if (anchorOffset > extentOffset) {
-    [anchorOffset, extentOffset] = [extentOffset, anchorOffset];
-  }
-
   return { start: anchorOffset, end: extentOffset };
 }
 ```
@@ -399,7 +397,7 @@ editContext.addEventListener("characterboundsupdate", (e) => {
 
 ## Apply IME composition text formats
 
-For the final step, there is one more thing you need to do to fully support IME composition. When the user is composing text with an IME, the IME might decide that certain parts of the text being composed should be formatted differently to indicate the composition state. For example, the IME might decide to render the text in a different color, or to underline it.
+For the final step, there is one more thing you need to do to fully support IME composition. When the user is composing text with an IME, the IME might decide that certain parts of the text being composed should be formatted differently to indicate the composition state. For example, the IME might decide to underline the text.
 
 Because you're responsible for rendering the content in the editable text region, the EditContext API doesn't do this for you. Instead, the API fires the {{domxref("EditContext.textformatupdate_event", "textformatupdate")}} event, and it's up to you to listen to this event and apply the formatting to the text.
 
@@ -416,12 +414,12 @@ First, use the {{cssxref("::highlight", "::highlight()")}} pseudo-element to def
   text-decoration: underline 2px;
 }
 
-::highlight(ime-double-thin) {
-  text-decoration: underline double 1px;
+::highlight(ime-dotted-thin) {
+  text-decoration: underline dotted 1px;
 }
 
-::highlight(ime-double-thick) {
-  text-decoration: underline double 2px;
+::highlight(ime-dotted-thick) {
+  text-decoration: underline dotted 2px;
 }
 
 /* The rest of the highlights are omitted for brevity. */
@@ -435,8 +433,6 @@ Next, create instances of the highlights using the {{domxref("Highlight")}} cons
 const imeHighlights = {
   "solid-thin": null,
   "solid-thick": null,
-  "double-thin": null,
-  "double-thick": null,
   "dotted-thin": null,
   "dotted-thick": null,
   "dashed-thin": null,

From e0a974ceb5e64f3ebb5897b31577b7c4f02f24e7 Mon Sep 17 00:00:00 2001
From: Patrick Brosset <patrick.brosset@microsoft.com>
Date: Fri, 2 Feb 2024 11:13:19 +0100
Subject: [PATCH 6/9] Simplified the backwards selection code

---
 .../web/api/editcontext_api/guide/index.md    | 23 +++++++------------
 1 file changed, 8 insertions(+), 15 deletions(-)

diff --git a/files/en-us/web/api/editcontext_api/guide/index.md b/files/en-us/web/api/editcontext_api/guide/index.md
index 9659600df1bb5fe..3149030f6faf2a3 100644
--- a/files/en-us/web/api/editcontext_api/guide/index.md
+++ b/files/en-us/web/api/editcontext_api/guide/index.md
@@ -129,11 +129,6 @@ To render the selection, because the EditContext API gives you the selection as
 
 ```js
 function convertFromOffsetsToSelection(start, end) {
-  // Deal with backwards selections.
-  const isBackwards = start > end;
-  const orderedStart = isBackwards ? end : start;
-  const orderedEnd = isBackwards ? start : end;
-
   // Create a TreeWalker that walks over all the
   // text nodes in the editor element.
   const treeWalker = document.createTreeWalker(editorEl, NodeFilter.SHOW_TEXT);
@@ -148,16 +143,19 @@ function convertFromOffsetsToSelection(start, end) {
   while (treeWalker.nextNode()) {
     const node = treeWalker.currentNode;
 
-    if (!anchorNode && offset + node.textContent.length >= orderedStart) {
+    if (!anchorNode && offset + node.textContent.length >= start) {
       // The anchor node is the first node that contains the start offset.
       anchorNode = node;
-      anchorOffset = orderedStart - offset;
+      anchorOffset = start - offset;
     }
 
-    if (offset + node.textContent.length >= orderedEnd) {
+    if (!extentNode && offset + node.textContent.length >= end) {
       // The extent node is the first node that contains the end offset.
       extentNode = node;
-      extentOffset = orderedEnd - offset;
+      extentOffset = end - offset;
+    }
+
+    if (anchorNode && extentNode) {
       break;
     }
 
@@ -165,12 +163,7 @@ function convertFromOffsetsToSelection(start, end) {
   }
 
   // Return an object that can be used to create a DOM selection.
-  return {
-    anchorNode: isBackwards ? extentNode : anchorNode,
-    anchorOffset: isBackwards ? extentOffset : anchorOffset,
-    extentNode: isBackwards ? anchorNode : extentNode,
-    extentOffset: isBackwards ? anchorOffset : extentOffset,
-  };
+  return { anchorNode, anchorOffset, extentNode, extentOffset };
 }
 ```
 

From d10558cf731823f6ecdda83d6e763076636560d0 Mon Sep 17 00:00:00 2001
From: Patrick Brosset <patrick.brosset@microsoft.com>
Date: Tue, 5 Mar 2024 16:20:05 +0100
Subject: [PATCH 7/9] Addressed Will's comment

---
 .../web/api/editcontext_api/guide/index.md    | 261 ++++++++++--------
 1 file changed, 145 insertions(+), 116 deletions(-)

diff --git a/files/en-us/web/api/editcontext_api/guide/index.md b/files/en-us/web/api/editcontext_api/guide/index.md
index 3149030f6faf2a3..302e07a6ee54e67 100644
--- a/files/en-us/web/api/editcontext_api/guide/index.md
+++ b/files/en-us/web/api/editcontext_api/guide/index.md
@@ -8,15 +8,17 @@ page-type: guide
 
 The **[EditContext API](/en-US/docs/Web/API/EditContext_API)** can be used to build rich text editors on the web that support advanced text input experiences, such as {{glossary("Input Method Editor")}} (IME) composition, emoji picker, or any other platform-specific editing-related UI surfaces.
 
-This article goes through all the steps that are necessary to build a text editor using the EditContext API. In this guide, you will build a simple HTML code editor that highlights the syntax of the code as you type, and that supports IME composition.
+This article goes over the necessary steps to build a text editor using the EditContext API. In this guide, you will review the main steps involved in building a simple HTML code editor that highlights the syntax of the code as you type, and that supports IME composition.
 
 ## Final code and live demo
 
-If you want to see the final code, you can check out the [live demo](https://mdn.github.io/dom-examples/edit-context/html-editor/) and [source code](https://github.com/mdn/dom-examples/tree/main/edit-context/html-editor) on GitHub.
+To see the final code, check out the [source code](https://github.com/mdn/dom-examples/tree/main/edit-context/html-editor) on GitHub. It's a good idea to keep the source code open while reading, as the tutorial only shows the most important parts of the code.
 
-## Create the editor UI
+To use the live demo, open [Edit Context API: HTML editor demo](https://mdn.github.io/dom-examples/edit-context/html-editor/).
 
-The first step is to create the UI for the editor. The editor will be a simple {{HTMLElement("div")}} element with the [`spellcheck`](/en-US/docs/Web/HTML/Global_attributes/spellcheck) attribute set to `false` to disable spell checking:
+## Creating the editor UI
+
+The first step is to create the UI for the editor. The editor is a simple {{HTMLElement("div")}} element with the [`spellcheck`](/en-US/docs/Web/HTML/Global_attributes/spellcheck) attribute set to `false` to disable spell checking:
 
 ```html
 <div id="html-editor" spellcheck="false"></div>
@@ -38,50 +40,48 @@ The following CSS code is used to make the editor fill the entire viewport and s
 }
 ```
 
-## Make the editor editable
+## Making the editor editable
 
 To make an element editable on the web, most of the time, you use an {{HTMLElement("input")}} element, a {{HTMLElement("textarea")}} element, or the [`contenteditable`](/en-US/docs/Web/HTML/Global_attributes/contenteditable) attribute.
 
 However, with the EditContext API, you can make other types of elements editable without using an attribute. To see the list of elements that can be used with the EditContext API, see [Possible elements](/en-US/docs/Web/API/HTMLElement/editContext#possible_elements) on the HTMLElement editContext property page.
 
-To make the editor editable, you create an {{domxref("EditContext")}} instance, and then you set the {{DOMxRef("HTMLElement.editContext", "editContext")}} property of the editor element to the `EditContext` instance:
+To make the editor editable, the demo app creates an {{domxref("EditContext")}} instance, and then sets the {{DOMxRef("HTMLElement.editContext", "editContext")}} property of the editor element to the `EditContext` instance:
 
 ```js
-if ("EditContext" in window) {
-  // Create the EditContext instance.
-  const editContext = new EditContext();
+// Retrieve the editor element from the DOM.
+const editorEl = document.getElementById("html-editor");
 
-  // Retrieve the editor element from the DOM.
-  const editorEl = document.getElementById("html-editor");
+// Create the EditContext instance.
+const editContext = new EditContext();
 
-  // Set the editor's editContext property value.
-  editorEl.editContext = editContext;
-} else {
-  console.log("The EditContext API is not supported.");
-}
+// Set the editor's editContext property value.
+editorEl.editContext = editContext;
 ```
 
-You can now focus the editor element. Entering text in the element will fire the {{domxref("EditContext.textupdate_event", "textupdate")}} event on the `EditContext` instance.
+These lines of code make the editor element focusable. Entering text in the element fires the {{domxref("EditContext.textupdate_event", "textupdate")}} event on the `EditContext` instance.
+
+## Rendering the text and user selection
 
-## Render the text and user selection
+To render the syntax-highlighted HTML code in the editor when the user enters text, the demo app uses a function, `render()`, that's called when new text is entered, when characters are deleted, or when the selection is changed.
 
-The next step is to write a function that renders the syntax-highlighted HTML code in the editor when the user enters text. This function will be called when new text is entered, when characters are deleted, or when the selection is changed.
+### Tokenizing the HTML code
 
-### Tokenize the HTML code
+One of the first things the `render()` function does is tokenize the HTML text content. Tokenizing the HTML text content is needed to highlight the HTML syntax, and involves reading the HTML code string, and determining where each opening tag, closing tag, attribute, comment node, and text node starts and ends.
 
-In order to render the syntax-highlighted HTML, you'll first need to tokenize the HTML code. This means reading the HTML code string, and determining where each opening tag, closing tag, attribute, comment node, and text node starts and ends. This can be done by iterating over the string character by character while maintaining a state machine.
+The demo app uses the `tokenizeHTML` function to achieve this, which iterates over the string character by character while maintaining a state machine.
 
-Since this is a guide about the EditContext API, the tokenizer code is not shown here. You can find the tokenizer code used in this tutorial in the [source code](https://github.com/mdn/dom-examples/blob/main/editcontext-api/html-editor/tokenizer.js).
+You can see the source code for the `tokenizeHTML` function in [tokenizer.js](https://github.com/mdn/dom-examples/blob/main/editcontext-api/html-editor/tokenizer.js), on GitHub.
 
-For the purpose of this tutorial, let's assume that the tokenizer is a function that's imported from a separate file:
+The function is imported into the demo app HTML file like this:
 
 ```js
 import { tokenizeHTML } from "./tokenizer.js";
 ```
 
-### Render the text
+### Rendering the text
 
-To render the text, let's create a `render` function that will be called whenever the user enters text, or when the selection changes. This function will first empty the editor element, and then it will render each token as a separate HTML element:
+Whenever the `render()` function is called, which is when the user enters text, or when the selection changes, the function removes the content in the editor element, and then renders each token as a separate HTML element:
 
 ```js
 function render() {
@@ -99,16 +99,13 @@ function render() {
 
     // Attach the span to the editor element.
     editorEl.appendChild(span);
-
-    // Save the span element in the token object for later.
-    token.node = span;
   }
 }
 ```
 
-As seen above, with the EditContext API, you are responsible for rendering the user interface of your editor. You can render the HTML text any way you want, including rendering it into a `<canvas>` element.
+The EditContext API gives us the ability to control the way the edited text is rendered. The above function renders it by using HTML elements, but it could render it in any other way, including by rendering it into a `<canvas>` element.
 
-Make sure to call the render function when needed. This includes calling it once at the beginning, when initializing the editor, and then calling it again when the user enters text, by listening to the {{domxref("EditContext.textupdate_event", "textupdate")}} event:
+The demo app runs the `render()` function when necessary. This includes once when the app starts, and then again when the user enters text, by listening to the {{domxref("EditContext.textupdate_event", "textupdate")}} event:
 
 ```js
 // Listen to the EditContext's textupdate event.
@@ -121,13 +118,47 @@ editContext.addEventListener("textupdate", (e) => {
 render();
 ```
 
-### Render the selection
+### Styling the tokens
+
+As seen in the previous `render()` function code example, each token is given a class name that corresponds to the type of token it is. The demo app uses this class name to style the tokens, using CSS, as shown below:
+
+```css
+.token-attributeName {
+  color: rgb(207, 81, 198);
+}
+
+.token-attributeValue {
+  font-style: italic;
+  color: rgb(127 230 127);
+  border: 1px dashed #8c8c8c;
+  border-width: 1px 0 1px 0;
+}
+```
+
+### Rendering the selection
 
-Even though you used a `<div>` element for the editor, which already supports displaying a blinking text cursor and highlighting the selected text, you still need to render the selection yourself. This is because the EditContext API can be used with other types of elements that don't support this behavior. Rendering the selection yourself also gives you more control over how the selection is displayed. Finally, because your `render` function clears the HTML content of the editor element everytime it runs, any selection that the user might have made will be lost if you don't render it yourself.
+Even though the demo app uses a `<div>` element for the editor, which already supports displaying a blinking text cursor and highlighting user selections, the EditContext API still requires us to render the selection. This is because the EditContext API can be used with other types of elements that don't support these behaviors. Rendering the selection ourselves also gives us more control over how the selection is displayed. Finally, because the `render()` function clears the HTML content of the editor element everytime it runs, any selection that the user might have made is lost the next time the `render()` function runs.
 
-To render the selection, because the EditContext API gives you the selection as a pair of start and end character offsets, you'll need to convert these offsets into a DOM selection. The following code snippet shows how you can do this:
+To render the selection, the demo app uses the {{DOMxRef("Selection.setBaseAndExtent()")}} method at the end of the `render()` function. To use the `setBaseAndExtent()` method, we need a pair of DOM nodes and character offsets that represent the start and end of the selection. However, the EditContext API maintains the state for the current selection as a pair of start and end character offsets only. The demo app code uses another function, called `convertFromOffsetsToSelection()` that's used to convert these character offsets into a DOM selection.
 
 ```js
+function render() {
+  // ...
+  // The beginning of the render function is omitted for brevity.
+
+  // Render the selection at the correct location by
+  // converting the start/end offsets to a DOM selection.
+  const selectionStart = editContext.selectionStart;
+  const selectionEnd = editContext.selectionEnd;
+
+  const { anchorNode, anchorOffset, extentNode, extentOffset } =
+    convertFromOffsetsToSelection(selectionStart, selectionEnd);
+
+  document
+    .getSelection()
+    .setBaseAndExtent(anchorNode, anchorOffset, extentNode, extentOffset);
+}
+
 function convertFromOffsetsToSelection(start, end) {
   // Create a TreeWalker that walks over all the
   // text nodes in the editor element.
@@ -167,34 +198,13 @@ function convertFromOffsetsToSelection(start, end) {
 }
 ```
 
-With the above function, you can now update the `render` function created earlier to render the current selection by using the {{DOMxRef("Selection.setBaseAndExtent()")}} method:
+## Updating the control bounds
 
-```js
-function render() {
-  // ...
-  // The beginning of the render function is omitted for brevity.
+The EditContext API gives us a lot of flexibility to define our own text editor UI. However, this also means that we need to handle some things that are usually handled by the browser or operating system (OS).
 
-  // Render the selection at the correct location by
-  // converting the start/end offsets to a DOM selection.
-  const selectionStart = editContext.selectionStart;
-  const selectionEnd = editContext.selectionEnd;
+For example, we must tell the OS where the editable text region is located on the page. This way, the OS can correctly position any text-editing UI that the user might be composing text with, such as an IME composition window.
 
-  const { anchorNode, anchorOffset, extentNode, extentOffset } =
-    convertFromOffsetsToSelection(selectionStart, selectionEnd);
-
-  document
-    .getSelection()
-    .setBaseAndExtent(anchorNode, anchorOffset, extentNode, extentOffset);
-}
-```
-
-## Update the control bounds
-
-The EditContext API gives you a lot of flexibility to define your own text editor UI. However, this also means that you need to handle some things that are usually handled by the browser or operating system (OS).
-
-For example, you must tell the OS where the editable text region is located on the page. This way, the OS can correctly position any text-editing UI that the user might be composing text with, such as an IME composition window.
-
-This is done by calling the {{domxref("EditContext.updateControlBounds()")}} method, and passing it a {{domxref("DOMRect")}} object that represents the bounds of the editable text region:
+The demo app uses the {{domxref("EditContext.updateControlBounds()")}} method, providing it with a {{domxref("DOMRect")}} object that represents the bounds of the editable text region. The demo app calls this method when the editor is initialized, and again when the window is resized:
 
 ```js
 function updateControlBounds() {
@@ -212,11 +222,11 @@ updateControlBounds();
 window.addEventListener("resize", updateControlBounds);
 ```
 
-## Handle Tab, Enter, and other text edit keys
+## Handling Tab, Enter, and other text edit keys
 
-The `textupdate` event used in the previous section isn't fired when the user presses the <kbd>Tab</kbd> or <kbd>Enter</kbd> keys, so you need to handle these keys separately.
+The `textupdate` event used in the previous section isn't fired when the user presses the <kbd>Tab</kbd> or <kbd>Enter</kbd> keys, so we need to handle these keys separately.
 
-To handle them, you can listen to the {{domxref("keydown_event", "keydown")}} event on the editor element, and use it to update the `EditContext` instance's text content and selection, as shown below:
+To handle them, the demo app uses an event listener for the {{domxref("keydown_event", "keydown")}} event on the editor element, and uses this listener to update the `EditContext` instance's text content and selection, as shown below:
 
 ```js
 // Handle key presses that are not already handled by the EditContext.
@@ -258,15 +268,37 @@ editorEl.addEventListener("keydown", (e) => {
 });
 ```
 
-You might also want to handle other key combinations like <kbd>Ctrl</kbd>+<kbd>C</kbd> and <kbd>Ctrl</kbd>+<kbd>V</kbd> to copy and paste text, or <kbd>Ctrl</kbd>+<kbd>Z</kbd> and <kbd>Ctrl</kbd>+<kbd>Y</kbd> to undo and redo text changes.
+We could improve the demo app by handling other key combinations, such as <kbd>Ctrl</kbd>+<kbd>C</kbd> and <kbd>Ctrl</kbd>+<kbd>V</kbd> to copy and paste text, or <kbd>Ctrl</kbd>+<kbd>Z</kbd> and <kbd>Ctrl</kbd>+<kbd>Y</kbd> to undo and redo text changes.
+
+## Updating the selection state and selection bounds
 
-## Update the selection state and selection bounds
+As we saw earlier, the `render()` function handled rendering the current user selection in the editor element. But the demo app also needs to _update_ the selection state and bounds when the user changes the selection. The EditContext API doesn't do this for automatically, again because the editor UI might be implemented in a different way, such as by using a `<canvas>` element.
 
-Earlier, you wrote code to _render_ the selection in the editor element. But you also need to _update_ the selection state and bounds when the user changes the selection. The EditContext API doesn't do this for you, again because you might choose to implement your editor UI in a different way, such as by using a `<canvas>` element.
+To know when the user changes the selection, the demo app uses the {{domxref("Document/selectionchange_event", "selectionchange")}} event and the {{domxref("Document.getSelection()")}} method, which provide a {{DOMxRef("Selection")}} object, telling us where the user's selection is. Using this information the demo app updates the EditContext selection state and selection bounds by using the {{domxref("EditContext.updateSelection()")}} and {{domxref("EditContext.updateSelectionBounds()")}} methods. This is used by the OS to position the IME composition window correctly.
 
-To know when the user changes the selection, use the {{domxref("Document/selectionchange_event", "selectionchange")}} event and the {{domxref("Document.getSelection()")}} method. This will give you a {{DOMxRef("Selection")}} object. Because the EditContext API uses character offsets to represent the selection, you'll need to convert the DOM selection to character offsets. This can be done by using the following function:
+However, because the EditContext API uses character offsets to represent the selection, the demo app also uses a function, `convertFromSelectionToOffsets()` that converts DOM selection objects to character offsets.
 
 ```js
+// Listen to selectionchange events to let the
+// EditContext know where it is.
+document.addEventListener("selectionchange", () => {
+  const selection = document.getSelection();
+
+  // Convert the DOM selection into character offsets.
+  const offsets = convertFromSelectionToOffsets(selection);
+  if (!offsets) {
+    return;
+  }
+
+  // Update the selection.
+  editContext.updateSelection(offsets.start, offsets.end);
+
+  // Get the bounds of the selection.
+  editContext.updateSelectionBounds(
+    selection.getRangeAt(0).getBoundingClientRect(),
+  );
+});
+
 function convertFromSelectionToOffsets(selection) {
   // Create a TreeWalker that walks over all the
   // text nodes in the editor element.
@@ -309,37 +341,36 @@ function convertFromSelectionToOffsets(selection) {
 }
 ```
 
-With the above function, listen to the `selectionchange` event and update the EditContext selection state. Also update the bounds of the selection using the {{domxref("EditContext.updateSelectionBounds()")}} method. This is used by the OS to position the IME composition window correctly:
+## Calculating character bounds
 
-```js
-// Listen to selectionchange events to let the
-// EditContext know where it is.
-document.addEventListener("selectionchange", () => {
-  const selection = document.getSelection();
-  const offsets = convertFromSelectionToOffsets(selection);
-  if (!offsets) {
-    return;
-  }
+On top of using the {{domxref("EditContext.updateControlBounds()")}} and {{domxref("EditContext.updateSelectionBounds()")}} methods to help the OS position a text editing UI that the user might be using, there's one more bit of information that the OS requires: the position and size of certain characters within the editor element.
 
-  // Update the selection.
-  editContext.updateSelection(offsets.start, offsets.end);
-
-  // Get the bounds of the selection.
-  editContext.updateSelectionBounds(
-    document.getSelection().getRangeAt(0).getBoundingClientRect(),
-  );
-});
-```
+To do this, the demo app listens to the {{domxref("EditContext.characterboundsupdate_event", "characterboundsupdate")}} event, uses it to calculate the bounds of some of the characters in the editor element, and then uses the {{domxref("EditContext.updateCharacterBounds()")}} method to update the character bounds.
 
-## Calculate character bounds
+As seen before, the EditContext API only knows about character offsets, which means that the `characterboundsupdate` event provides the start and end offsets for the characters it needs bounds for. The demo app uses another function, `convertFromOffsetsToListOfRenderedTokenNodes()`, to find the DOM elements that these characters have been rendered in, and uses this information to calculate the required bounds.
 
-Earlier, you used the {{domxref("EditContext.updateControlBounds()")}} and {{domxref("EditContext.updateSelectionBounds()")}} methods to help the OS position any text editing UI that the user might be composing text with, such as an IME composition window. There's one more bit of information that the OS requires to do this correctly: the position and size of certain characters within the editor element.
+```js
+// Listen to the characterboundsupdate event to know when character bounds
+// information is needed, and which characters need bounds.
+editContext.addEventListener("characterboundsupdate", (e) => {
+  // Retrieve information about the token nodes in the range.
+  const tokenNodes = convertFromOffsetsToListOfRenderedTokenNodes(
+    e.rangeStart,
+    e.rangeEnd,
+  );
 
-To do this, you'll need to listen to the {{domxref("EditContext.characterboundsupdate_event", "characterboundsupdate")}} event, use it to calculate the bounds of some of the characters in the editor element, and then use the {{domxref("EditContext.updateCharacterBounds()")}} method to update the character bounds.
+  // Convert this information into a list of DOMRect objects.
+  const charBounds = tokenNodes.map(({ node, nodeOffset, charOffset }) => {
+    const range = document.createRange();
+    range.setStart(node.firstChild, charOffset - nodeOffset);
+    range.setEnd(node.firstChild, charOffset - nodeOffset + 1);
+    return range.getBoundingClientRect();
+  });
 
-The EditContext API only uses character offsets, which means that the `characterboundsupdate` event will only tell you the start and end offsets for the characters it needs bounds for. It's up to you to find the DOM elements that these characters have been rendered in, and to calculate the bounds for these characters. To help with this, you'll first create a function that converts from character offsets to DOM elements:
+  // Let the EditContext instance know about the character bounds.
+  editContext.updateCharacterBounds(e.rangeStart, charBounds);
+});
 
-```js
 function convertFromOffsetsToListOfRenderedTokenNodes(start, end) {
   const tokenNodes = [];
 
@@ -365,38 +396,36 @@ function convertFromOffsetsToListOfRenderedTokenNodes(start, end) {
 }
 ```
 
-With the above function, you can now listen to the `characterboundsupdate` event, and use it to calculate the bounds of the characters in the editor element:
+## Applying IME composition text formats
 
-```js
-editContext.addEventListener("characterboundsupdate", (e) => {
-  // Retrieve information about the token nodes in the range.
-  const tokenNodes = convertFromOffsetsToListOfRenderedTokenNodes(
-    e.rangeStart,
-    e.rangeEnd,
-  );
+The demo app goes through a final step to fully support IME composition. When the user is composing text with an IME, the IME might decide that certain parts of the text being composed should be formatted differently to indicate the composition state. For example, the IME might decide to underline the text.
 
-  // Convert this information into a list of DOMRect objects.
-  const charBounds = tokenNodes.map(({ node, nodeOffset, charOffset }) => {
-    const range = document.createRange();
-    range.setStart(node.firstChild, charOffset - nodeOffset);
-    range.setEnd(node.firstChild, charOffset - nodeOffset + 1);
-    return range.getBoundingClientRect();
-  });
+Because it's the demo app's responsibility to render the content in the editable text region, it's also its responsibility to apply the necessary IME formatting. The demo app achieves this by listening to the {{domxref("EditContext.textformatupdate_event", "textformatupdate")}} event to know when the IME wants to apply text formats, where, and what formats to apply.
 
-  // Let the EditContext instance know about the character bounds.
-  editContext.updateCharacterBounds(e.rangeStart, charBounds);
-});
-```
+As shown in the following code snippet, the demo app uses the `textformatupdate` event and the `convertFromOffsetsToSelection()` function again to find the text range that the IME composition wants to format.
 
-## Apply IME composition text formats
+```js
+editContext.addEventListener("textformatupdate", (e) => {
+  // Get the list of formats that the IME wants to apply.
+  const formats = e.getTextFormats();
 
-For the final step, there is one more thing you need to do to fully support IME composition. When the user is composing text with an IME, the IME might decide that certain parts of the text being composed should be formatted differently to indicate the composition state. For example, the IME might decide to underline the text.
+  // Iterate over the text formats.
+  for (const format of formats) {
+    // For each format, we know the underline style and thickness,
+    // as well as the start and end offsets of the range that needs
+    // to be styled.
+    const { rangeStart, rangeEnd, underlineStyle, underlineThickness } = format;
 
-Because you're responsible for rendering the content in the editable text region, the EditContext API doesn't do this for you. Instead, the API fires the {{domxref("EditContext.textformatupdate_event", "textformatupdate")}} event, and it's up to you to listen to this event and apply the formatting to the text.
+    // Find the nodes that are in the range of the current format.
+    const { anchorNode, anchorOffset, extentNode, extentOffset } =
+      convertFromOffsetsToSelection(rangeStart, rangeEnd);
 
-As shown in the following code snippet, you will use the `convertFromOffsetsToSelection` function again to find the DOM nodes that are in the range of the IME composition. Let's also use the [CSS Custom Highlight API](/en-US/docs/Web/API/CSS_Custom_Highlight_API) to render the text formats. The CSS Custom Highlight API provides a mechanism for styling arbitrary text ranges by using JavaScript to create the ranges, and CSS to style them.
+    // Style the above range...
+  }
+});
+```
 
-First, use the {{cssxref("::highlight", "::highlight()")}} pseudo-element to define the highlight styles. The text formats define the style and thickness of an underline. So, create as many highlights as there are possible combinations of underline styles and thicknesses:
+The demo app then uses the [CSS Custom Highlight API](/en-US/docs/Web/API/CSS_Custom_Highlight_API) to render the text formats. The CSS Custom Highlight API provides a mechanism for styling arbitrary text ranges by using JavaScript to create the ranges, and CSS to style them. To use this API, the {{cssxref("::highlight", "::highlight()")}} pseudo-element is used to define the highlight styles:
 
 ```css
 ::highlight(ime-solid-thin) {
@@ -415,10 +444,10 @@ First, use the {{cssxref("::highlight", "::highlight()")}} pseudo-element to def
   text-decoration: underline dotted 2px;
 }
 
-/* The rest of the highlights are omitted for brevity. */
+/* Other highlights are omitted for brevity. */
 ```
 
-Next, create instances of the highlights using the {{domxref("Highlight")}} constructor, store them in an object, and register them in the {{domxref("HighlightRegistry")}} by using the {{domxref("CSS/highlights_static", "CSS.highlights")}} property:
+{{domxref("Highlight")}} instances are also created, stored in an object, and registered in the {{domxref("HighlightRegistry")}} by using the {{domxref("CSS/highlights_static", "CSS.highlights")}} property:
 
 ```js
 // Instances of CSS custom Highlight objects, used to render
@@ -441,7 +470,7 @@ for (const [key, value] of Object.entries(imeHighlights)) {
 }
 ```
 
-Now, you can listen to the `textformatupdate` event, and use it to apply the IME composition text formats:
+With this in place, the demo app creates {{domxref("Range")}} objects for the ranges that need to be styled, and adds them to the `Highlight` object:
 
 ```js
 editContext.addEventListener("textformatupdate", (e) => {

From 78e1a46a06f65e9081f3acdb9391cf88daf55ac1 Mon Sep 17 00:00:00 2001
From: Patrick Brosset <patrick.brosset@microsoft.com>
Date: Mon, 18 Mar 2024 14:57:47 +0100
Subject: [PATCH 8/9] Addressed review comments

---
 .../web/api/editcontext_api/guide/index.md    | 337 ++++++++----------
 1 file changed, 151 insertions(+), 186 deletions(-)

diff --git a/files/en-us/web/api/editcontext_api/guide/index.md b/files/en-us/web/api/editcontext_api/guide/index.md
index 302e07a6ee54e67..6647e52963f2186 100644
--- a/files/en-us/web/api/editcontext_api/guide/index.md
+++ b/files/en-us/web/api/editcontext_api/guide/index.md
@@ -14,28 +14,39 @@ This article goes over the necessary steps to build a text editor using the Edit
 
 To see the final code, check out the [source code](https://github.com/mdn/dom-examples/tree/main/edit-context/html-editor) on GitHub. It's a good idea to keep the source code open while reading, as the tutorial only shows the most important parts of the code.
 
-To use the live demo, open [Edit Context API: HTML editor demo](https://mdn.github.io/dom-examples/edit-context/html-editor/).
+The source code is organized into the following files:
+
+- [index.html](https://github.com/mdn/dom-examples/tree/main/edit-context/html-editor/index.html) contains the editor UI element, and loads the necessary CSS and JavaScript code for the demo.
+- [styles.css](https://github.com/mdn/dom-examples/tree/main/edit-context/html-editor/styles.css) contains the styles for the editor UI.
+- [editor.js](https://github.com/mdn/dom-examples/tree/main/edit-context/html-editor/editor.js) contains the JavaScript code that sets up the editor UI, renders the HTML code, and handles user input.
+- [tokenizer.js](https://github.com/mdn/dom-examples/tree/main/edit-context/html-editor/tokenizer.js) contains the JavaScript code that splits the HTML code into separate tokens, such as opening tags, closing tags, and text nodes.
+- [converter.js](https://github.com/mdn/dom-examples/tree/main/edit-context/html-editor/converter.js) contains the JavaScript code that converts between the character offsets that the EditContext API uses, and the DOM nodes that the browser uses for text selections.
+
+To use the live demo, open [Edit Context API: HTML editor demo](https://mdn.github.io/dom-examples/edit-context/html-editor/) in a browser that supports the EditContext API.
 
 ## Creating the editor UI
 
-The first step is to create the UI for the editor. The editor is a simple {{HTMLElement("div")}} element with the [`spellcheck`](/en-US/docs/Web/HTML/Global_attributes/spellcheck) attribute set to `false` to disable spell checking:
+The first step is to create the UI for the editor. The editor is a {{HTMLElement("div")}} element with the [`spellcheck`](/en-US/docs/Web/HTML/Global_attributes/spellcheck) attribute set to `false` to disable spell checking:
 
 ```html
 <div id="html-editor" spellcheck="false"></div>
 ```
 
-The following CSS code is used to make the editor fill the entire viewport and scroll when there's too much content to fit. The {{CSSXref("white-space")}} property is also used to preserve whitespace, and the {{CSSXref("tab-size")}} property is used to make tab characters render as two spaces. Finally, some default background and text colors are set.
+To style the editor element, the following CSS code is used. The code makes the editor fill the entire viewport and scroll when there's too much content to fit. The {{cssxref("white-space")}} property is also used to preserve whitespace characters found in the HTML input text, and the {{cssxref("tab-size")}} property is used to make tab characters render as two spaces. Finally, some default background, text, and caret colors are set:
 
 ```css
 #html-editor {
+  box-sizing: border-box;
   width: 100%;
   height: 100%;
-  box-sizing: border-box;
+  border-radius: 0.5rem;
   padding: 1rem;
   overflow: auto;
   white-space: pre;
   tab-size: 2;
+  caret-color: red;
   background: #000;
+  line-height: 1.6;
   color: red;
 }
 ```
@@ -44,16 +55,18 @@ The following CSS code is used to make the editor fill the entire viewport and s
 
 To make an element editable on the web, most of the time, you use an {{HTMLElement("input")}} element, a {{HTMLElement("textarea")}} element, or the [`contenteditable`](/en-US/docs/Web/HTML/Global_attributes/contenteditable) attribute.
 
-However, with the EditContext API, you can make other types of elements editable without using an attribute. To see the list of elements that can be used with the EditContext API, see [Possible elements](/en-US/docs/Web/API/HTMLElement/editContext#possible_elements) on the HTMLElement editContext property page.
+However, with the EditContext API, you can make other types of elements editable without using an attribute. To see the list of elements that can be used with the EditContext API, see [Possible elements](/en-US/docs/Web/API/HTMLElement/editContext#possible_elements) on the HTMLElement `editContext` property page.
 
-To make the editor editable, the demo app creates an {{domxref("EditContext")}} instance, and then sets the {{DOMxRef("HTMLElement.editContext", "editContext")}} property of the editor element to the `EditContext` instance:
+To make the editor editable, the demo app creates an {{domxref("EditContext")}} instance, passing some initial HTML text to the constructor, and then sets the {{domxref("HTMLElement.editContext", "editContext")}} property of the editor element to the `EditContext` instance:
 
 ```js
 // Retrieve the editor element from the DOM.
 const editorEl = document.getElementById("html-editor");
 
 // Create the EditContext instance.
-const editContext = new EditContext();
+const editContext = new EditContext({
+  text: "<html>\n  <body id=foo>\n    <h1 id='header'>Cool Title</h1>\n    <p class=\"wow\">hello<br/>How are you? test</p>\n  </body>\n</html>",
+});
 
 // Set the editor's editContext property value.
 editorEl.editContext = editContext;
@@ -63,15 +76,13 @@ These lines of code make the editor element focusable. Entering text in the elem
 
 ## Rendering the text and user selection
 
-To render the syntax-highlighted HTML code in the editor when the user enters text, the demo app uses a function, `render()`, that's called when new text is entered, when characters are deleted, or when the selection is changed.
+To render the syntax-highlighted HTML code in the editor when the user enters text, the demo app uses a function named `render()` that's called when new text is entered, when characters are deleted, or when the selection is changed.
 
 ### Tokenizing the HTML code
 
 One of the first things the `render()` function does is tokenize the HTML text content. Tokenizing the HTML text content is needed to highlight the HTML syntax, and involves reading the HTML code string, and determining where each opening tag, closing tag, attribute, comment node, and text node starts and ends.
 
-The demo app uses the `tokenizeHTML` function to achieve this, which iterates over the string character by character while maintaining a state machine.
-
-You can see the source code for the `tokenizeHTML` function in [tokenizer.js](https://github.com/mdn/dom-examples/blob/main/editcontext-api/html-editor/tokenizer.js), on GitHub.
+The demo app uses the `tokenizeHTML()` function to achieve this, which iterates over the string character by character while maintaining a state machine. You can see the source code for the `tokenizeHTML()` function in [tokenizer.js](https://github.com/mdn/dom-examples/blob/main/editcontext-api/html-editor/tokenizer.js), on GitHub.
 
 The function is imported into the demo app HTML file like this:
 
@@ -84,12 +95,15 @@ import { tokenizeHTML } from "./tokenizer.js";
 Whenever the `render()` function is called, which is when the user enters text, or when the selection changes, the function removes the content in the editor element, and then renders each token as a separate HTML element:
 
 ```js
-function render() {
-  // First, empty the editor. We're re-rendering everything.
+// Stores the list of HTML tokens.
+let currentTokens = [];
+
+function render(text, selectionStart, selectionEnd) {
+  // Empty the editor. We're re-rendering everything.
   editorEl.innerHTML = "";
 
   // Tokenize the text.
-  const currentTokens = tokenizeHTML(editContext.text);
+  currentTokens = tokenizeHTML(text);
 
   for (const token of currentTokens) {
     // Render each token as a span element.
@@ -99,11 +113,20 @@ function render() {
 
     // Attach the span to the editor element.
     editorEl.appendChild(span);
+
+    // Store the new DOM node as a property of the token
+    // in the currentTokens array. We will need it again
+    // later in fromOffsetsToRenderedTokenNodes.
+    token.node = span;
   }
+
+  // Code to render the text selection is omitted for brevity.
+  // See "Rendering the selection", below.
+  // ...
 }
 ```
 
-The EditContext API gives us the ability to control the way the edited text is rendered. The above function renders it by using HTML elements, but it could render it in any other way, including by rendering it into a `<canvas>` element.
+The EditContext API gives the ability to control the way the edited text is rendered. The above function renders it by using HTML elements, but it could render it in any other way, including by rendering it into a `<canvas>` element.
 
 The demo app runs the `render()` function when necessary. This includes once when the app starts, and then again when the user enters text, by listening to the {{domxref("EditContext.textupdate_event", "textupdate")}} event:
 
@@ -111,11 +134,11 @@ The demo app runs the `render()` function when necessary. This includes once whe
 // Listen to the EditContext's textupdate event.
 // This tells us when text input happens. We use it to re-render the view.
 editContext.addEventListener("textupdate", (e) => {
-  render();
+  render(editContext.text, e.selectionStart, e.selectionEnd);
 });
 
 // Do the initial render.
-render();
+render(editContext.text, editContext.selectionStart, editContext.selectionEnd);
 ```
 
 ### Styling the tokens
@@ -123,6 +146,26 @@ render();
 As seen in the previous `render()` function code example, each token is given a class name that corresponds to the type of token it is. The demo app uses this class name to style the tokens, using CSS, as shown below:
 
 ```css
+.token-openTagStart,
+.token-openTagEnd,
+.token-closeTagStart,
+.token-closeTagEnd,
+.token-selfClose {
+  background: rgb(7 53 92);
+  margin: 0 2px;
+  color: white;
+  border-radius: 0.25rem;
+}
+
+.token-equal {
+  color: white;
+}
+
+.token-tagName {
+  font-weight: bold;
+  color: rgb(117, 186, 242);
+}
+
 .token-attributeName {
   color: rgb(207, 81, 198);
 }
@@ -133,71 +176,56 @@ As seen in the previous `render()` function code example, each token is given a
   border: 1px dashed #8c8c8c;
   border-width: 1px 0 1px 0;
 }
+
+.token-quoteStart,
+.token-quoteEnd {
+  font-weight: bold;
+  color: rgb(127 230 127);
+  border: 1px solid #8c8c8c;
+  border-width: 1px 0 1px 1px;
+  border-radius: 0.25rem 0 0 0.25rem;
+}
+
+.token-quoteEnd {
+  border-width: 1px 1px 1px 0;
+  border-radius: 0 0.25rem 0.25rem 0;
+}
+
+.token-text {
+  color: #6a6a6a;
+  padding: 0 0.25rem;
+}
 ```
 
 ### Rendering the selection
 
-Even though the demo app uses a `<div>` element for the editor, which already supports displaying a blinking text cursor and highlighting user selections, the EditContext API still requires us to render the selection. This is because the EditContext API can be used with other types of elements that don't support these behaviors. Rendering the selection ourselves also gives us more control over how the selection is displayed. Finally, because the `render()` function clears the HTML content of the editor element everytime it runs, any selection that the user might have made is lost the next time the `render()` function runs.
+Even though the demo app uses a `<div>` element for the editor, which already supports displaying a blinking text cursor and highlighting user selections, the EditContext API still requires to render the selection. This is because the EditContext API can be used with other types of elements that don't support these behaviors. Rendering the selection ourselves also gives us more control over how the selection is displayed. Finally, because the `render()` function clears the HTML content of the editor element everytime it runs, any selection that the user might have made is lost the next time the `render()` function runs.
+
+To render the selection, the demo app uses the {{domxref("Selection.setBaseAndExtent()")}} method at the end of the `render()` function. To use the `setBaseAndExtent()` method, we need a pair of DOM nodes and character offsets that represent the start and end of the selection. However, the EditContext API maintains the state for the current selection only as a pair of start and end character offsets into the entire edit buffer. The demo app code uses another function, called `fromOffsetsToSelection()` that's used to convert these character offsets into four values:
 
-To render the selection, the demo app uses the {{DOMxRef("Selection.setBaseAndExtent()")}} method at the end of the `render()` function. To use the `setBaseAndExtent()` method, we need a pair of DOM nodes and character offsets that represent the start and end of the selection. However, the EditContext API maintains the state for the current selection as a pair of start and end character offsets only. The demo app code uses another function, called `convertFromOffsetsToSelection()` that's used to convert these character offsets into a DOM selection.
+- The DOM node that contains the start of the selection.
+- A number representing the character position of the selection start, within the start node.
+- The DOM node that contains the end of the selection.
+- A number representing the character position of the selection end, within the end node.
 
 ```js
-function render() {
+function render(text, selectionStart, selectionEnd) {
   // ...
   // The beginning of the render function is omitted for brevity.
 
-  // Render the selection at the correct location by
-  // converting the start/end offsets to a DOM selection.
-  const selectionStart = editContext.selectionStart;
-  const selectionEnd = editContext.selectionEnd;
-
+  // Convert the start/end offsets to a DOM selection.
   const { anchorNode, anchorOffset, extentNode, extentOffset } =
-    convertFromOffsetsToSelection(selectionStart, selectionEnd);
+    fromOffsetsToSelection(selectionStart, selectionEnd);
 
+  // Render the selection in the editor element.
   document
     .getSelection()
     .setBaseAndExtent(anchorNode, anchorOffset, extentNode, extentOffset);
 }
-
-function convertFromOffsetsToSelection(start, end) {
-  // Create a TreeWalker that walks over all the
-  // text nodes in the editor element.
-  const treeWalker = document.createTreeWalker(editorEl, NodeFilter.SHOW_TEXT);
-
-  let offset = 0;
-  let anchorNode = null;
-  let anchorOffset = 0;
-  let extentNode = null;
-  let extentOffset = 0;
-
-  // Iterate over the text nodes.
-  while (treeWalker.nextNode()) {
-    const node = treeWalker.currentNode;
-
-    if (!anchorNode && offset + node.textContent.length >= start) {
-      // The anchor node is the first node that contains the start offset.
-      anchorNode = node;
-      anchorOffset = start - offset;
-    }
-
-    if (!extentNode && offset + node.textContent.length >= end) {
-      // The extent node is the first node that contains the end offset.
-      extentNode = node;
-      extentOffset = end - offset;
-    }
-
-    if (anchorNode && extentNode) {
-      break;
-    }
-
-    offset += node.textContent.length;
-  }
-
-  // Return an object that can be used to create a DOM selection.
-  return { anchorNode, anchorOffset, extentNode, extentOffset };
-}
 ```
 
+You can see the code for the `fromOffsetsToSelection()` function in the [converter.js](<(https://github.com/mdn/dom-examples/tree/main/edit-context/html-editor/converter.js)>) file.
+
 ## Updating the control bounds
 
 The EditContext API gives us a lot of flexibility to define our own text editor UI. However, this also means that we need to handle some things that are usually handled by the browser or operating system (OS).
@@ -226,7 +254,7 @@ window.addEventListener("resize", updateControlBounds);
 
 The `textupdate` event used in the previous section isn't fired when the user presses the <kbd>Tab</kbd> or <kbd>Enter</kbd> keys, so we need to handle these keys separately.
 
-To handle them, the demo app uses an event listener for the {{domxref("keydown_event", "keydown")}} event on the editor element, and uses this listener to update the `EditContext` instance's text content and selection, as shown below:
+To handle them, the demo app uses an event listener for the {{domxref("Element.keydown_event", "keydown")}} event on the editor element, and uses this listener to update the `EditContext` instance's text content and selection, as shown below:
 
 ```js
 // Handle key presses that are not already handled by the EditContext.
@@ -247,10 +275,14 @@ editorEl.addEventListener("keydown", (e) => {
     editContext.updateText(start, end, "\t");
 
     // Update the selection to be after the inserted tab character.
-    editContext.updateSelection(start + 1, start + 1);
+    updateSelection(start + 1, start + 1);
 
     // Re-render the editor.
-    render();
+    render(
+      editContext.text,
+      editContext.selectionStart,
+      editContext.selectionEnd,
+    );
   }
 
   // Handling the Enter key.
@@ -260,23 +292,29 @@ editorEl.addEventListener("keydown", (e) => {
     editContext.updateText(start, end, "\n");
 
     // Update the selection to be after the inserted newline character.
-    editContext.updateSelection(start + 1, start + 1);
+    updateSelection(start + 1, start + 1);
 
     // Re-render the editor.
-    render();
+    render(
+      editContext.text,
+      editContext.selectionStart,
+      editContext.selectionEnd,
+    );
   }
 });
 ```
 
-We could improve the demo app by handling other key combinations, such as <kbd>Ctrl</kbd>+<kbd>C</kbd> and <kbd>Ctrl</kbd>+<kbd>V</kbd> to copy and paste text, or <kbd>Ctrl</kbd>+<kbd>Z</kbd> and <kbd>Ctrl</kbd>+<kbd>Y</kbd> to undo and redo text changes.
+The above code also calls the `updateSelection()` function to update the selection after the text content has been updated. See [Updating the selection state and selection bounds](#updating-the-selection-state-and-selection-bounds), below, for more information.
+
+We could improve the code by handling other key combinations, such as <kbd>Ctrl</kbd>+<kbd>C</kbd> and <kbd>Ctrl</kbd>+<kbd>V</kbd> to copy and paste text, or <kbd>Ctrl</kbd>+<kbd>Z</kbd> and <kbd>Ctrl</kbd>+<kbd>Y</kbd> to undo and redo text changes.
 
 ## Updating the selection state and selection bounds
 
-As we saw earlier, the `render()` function handled rendering the current user selection in the editor element. But the demo app also needs to _update_ the selection state and bounds when the user changes the selection. The EditContext API doesn't do this for automatically, again because the editor UI might be implemented in a different way, such as by using a `<canvas>` element.
+As we saw earlier, the `render()` function handles rendering the current user selection in the editor element. But the demo app also needs to _update_ the selection state and bounds when the user changes the selection. The EditContext API doesn't do this automatically, again because the editor UI might be implemented in a different way, such as by using a `<canvas>` element.
 
-To know when the user changes the selection, the demo app uses the {{domxref("Document/selectionchange_event", "selectionchange")}} event and the {{domxref("Document.getSelection()")}} method, which provide a {{DOMxRef("Selection")}} object, telling us where the user's selection is. Using this information the demo app updates the EditContext selection state and selection bounds by using the {{domxref("EditContext.updateSelection()")}} and {{domxref("EditContext.updateSelectionBounds()")}} methods. This is used by the OS to position the IME composition window correctly.
+To know when the user changes the selection, the demo app uses the {{domxref("Document/selectionchange_event", "selectionchange")}} event and the {{domxref("Document.getSelection()")}} method, which provide a {{domxref("Selection")}} object, telling us where the user's selection is. Using this information the demo app updates the EditContext selection state and selection bounds by using the {{domxref("EditContext.updateSelection()")}} and {{domxref("EditContext.updateSelectionBounds()")}} methods. This is used by the OS to position the IME composition window correctly.
 
-However, because the EditContext API uses character offsets to represent the selection, the demo app also uses a function, `convertFromSelectionToOffsets()` that converts DOM selection objects to character offsets.
+However, because the EditContext API uses character offsets to represent the selection, the demo app also uses a function, `fromSelectionToOffsets()` that converts DOM selection objects to character offsets.
 
 ```js
 // Listen to selectionchange events to let the
@@ -285,76 +323,40 @@ document.addEventListener("selectionchange", () => {
   const selection = document.getSelection();
 
   // Convert the DOM selection into character offsets.
-  const offsets = convertFromSelectionToOffsets(selection);
-  if (!offsets) {
-    return;
+  const offsets = fromSelectionToOffsets(selection, editorEl);
+  if (offsets) {
+    updateSelection(offsets.start, offsets.end);
   }
+});
 
-  // Update the selection.
-  editContext.updateSelection(offsets.start, offsets.end);
-
+// Update the selection and selection bounds in the EditContext object.
+// This helps the OS position the IME composition window correctly.
+function updateSelection(start, end) {
+  editContext.updateSelection(start, end);
   // Get the bounds of the selection.
   editContext.updateSelectionBounds(
-    selection.getRangeAt(0).getBoundingClientRect(),
+    document.getSelection().getRangeAt(0).getBoundingClientRect(),
   );
-});
-
-function convertFromSelectionToOffsets(selection) {
-  // Create a TreeWalker that walks over all the
-  // text nodes in the editor element.
-  const treeWalker = document.createTreeWalker(editorEl, NodeFilter.SHOW_TEXT);
-
-  let anchorNodeFound = false;
-  let extentNodeFound = false;
-  let anchorOffset = 0;
-  let extentOffset = 0;
-
-  // Iterate over the text nodes until we find
-  // the anchor and extent nodes given by the selection.
-  while (treeWalker.nextNode()) {
-    const node = treeWalker.currentNode;
-    if (node === selection.anchorNode) {
-      anchorNodeFound = true;
-      anchorOffset += selection.anchorOffset;
-    }
-
-    if (node === selection.extentNode) {
-      extentNodeFound = true;
-      extentOffset += selection.extentOffset;
-    }
-
-    if (!anchorNodeFound) {
-      anchorOffset += node.textContent.length;
-    }
-    if (!extentNodeFound) {
-      extentOffset += node.textContent.length;
-    }
-  }
-
-  // Return null if the nodes couldn't be found.
-  // The selection is outside the editor element.
-  if (!anchorNodeFound || !extentNodeFound) {
-    return null;
-  }
-
-  return { start: anchorOffset, end: extentOffset };
 }
 ```
 
+You can see the code for the `fromSelectionToOffsets()` function in the [converter.js](<(https://github.com/mdn/dom-examples/tree/main/edit-context/html-editor/converter.js)>) file.
+
 ## Calculating character bounds
 
 On top of using the {{domxref("EditContext.updateControlBounds()")}} and {{domxref("EditContext.updateSelectionBounds()")}} methods to help the OS position a text editing UI that the user might be using, there's one more bit of information that the OS requires: the position and size of certain characters within the editor element.
 
 To do this, the demo app listens to the {{domxref("EditContext.characterboundsupdate_event", "characterboundsupdate")}} event, uses it to calculate the bounds of some of the characters in the editor element, and then uses the {{domxref("EditContext.updateCharacterBounds()")}} method to update the character bounds.
 
-As seen before, the EditContext API only knows about character offsets, which means that the `characterboundsupdate` event provides the start and end offsets for the characters it needs bounds for. The demo app uses another function, `convertFromOffsetsToListOfRenderedTokenNodes()`, to find the DOM elements that these characters have been rendered in, and uses this information to calculate the required bounds.
+As seen before, the EditContext API only knows about character offsets, which means that the `characterboundsupdate` event provides the start and end offsets for the characters it needs bounds for. The demo app uses another function, `fromOffsetsToRenderedTokenNodes()`, to find the DOM elements that these characters have been rendered in, and uses this information to calculate the required bounds.
 
 ```js
 // Listen to the characterboundsupdate event to know when character bounds
 // information is needed, and which characters need bounds.
 editContext.addEventListener("characterboundsupdate", (e) => {
   // Retrieve information about the token nodes in the range.
-  const tokenNodes = convertFromOffsetsToListOfRenderedTokenNodes(
+  const tokenNodes = fromOffsetsToRenderedTokenNodes(
+    currentTokens,
     e.rangeStart,
     e.rangeEnd,
   );
@@ -370,62 +372,38 @@ editContext.addEventListener("characterboundsupdate", (e) => {
   // Let the EditContext instance know about the character bounds.
   editContext.updateCharacterBounds(e.rangeStart, charBounds);
 });
-
-function convertFromOffsetsToListOfRenderedTokenNodes(start, end) {
-  const tokenNodes = [];
-
-  // Go over all character offsets in the range.
-  for (let offset = start; offset < end; offset++) {
-    // Find the DOM node that contains this character.
-    // This assumes that the `currentTokens` array is accessible,
-    // and that each item of the `currentTokens` array has a
-    // `node` and `pos` property.
-    const token = currentTokens.find(
-      (token) => token.pos <= offset && token.pos + token.value.length > offset,
-    );
-    if (token) {
-      tokenNodes.push({
-        node: token.node,
-        nodeOffset: token.pos,
-        charOffset: offset,
-      });
-    }
-  }
-
-  return tokenNodes;
-}
 ```
 
+You can see the code for the `fromOffsetsToRenderedTokenNodes()` function in the [converter.js](<(https://github.com/mdn/dom-examples/tree/main/edit-context/html-editor/converter.js)>) file.
+
 ## Applying IME composition text formats
 
 The demo app goes through a final step to fully support IME composition. When the user is composing text with an IME, the IME might decide that certain parts of the text being composed should be formatted differently to indicate the composition state. For example, the IME might decide to underline the text.
 
 Because it's the demo app's responsibility to render the content in the editable text region, it's also its responsibility to apply the necessary IME formatting. The demo app achieves this by listening to the {{domxref("EditContext.textformatupdate_event", "textformatupdate")}} event to know when the IME wants to apply text formats, where, and what formats to apply.
 
-As shown in the following code snippet, the demo app uses the `textformatupdate` event and the `convertFromOffsetsToSelection()` function again to find the text range that the IME composition wants to format.
+As shown in the following code snippet, the demo app uses the `textformatupdate` event and the `fromOffsetsToSelection()` function again to find the text range that the IME composition wants to format:
 
 ```js
 editContext.addEventListener("textformatupdate", (e) => {
   // Get the list of formats that the IME wants to apply.
   const formats = e.getTextFormats();
 
-  // Iterate over the text formats.
   for (const format of formats) {
-    // For each format, we know the underline style and thickness,
-    // as well as the start and end offsets of the range that needs
-    // to be styled.
-    const { rangeStart, rangeEnd, underlineStyle, underlineThickness } = format;
-
-    // Find the nodes that are in the range of the current format.
-    const { anchorNode, anchorOffset, extentNode, extentOffset } =
-      convertFromOffsetsToSelection(rangeStart, rangeEnd);
+    // Find the DOM selection that corresponds to the format's range.
+    const selection = fromOffsetsToSelection(
+      format.rangeStart,
+      format.rangeEnd,
+      editorEl,
+    );
 
-    // Style the above range...
+    // Highlight the selection with the right style and thickness.
+    addHighlight(selection, format.underlineStyle, format.underlineThickness);
   }
 });
 ```
 
-The demo app then uses the [CSS Custom Highlight API](/en-US/docs/Web/API/CSS_Custom_Highlight_API) to render the text formats. The CSS Custom Highlight API provides a mechanism for styling arbitrary text ranges by using JavaScript to create the ranges, and CSS to style them. To use this API, the {{cssxref("::highlight", "::highlight()")}} pseudo-element is used to define the highlight styles:
+The above event handler calls the function named `addHighlight()` to format text. This function uses the [CSS Custom Highlight API](/en-US/docs/Web/API/CSS_Custom_Highlight_API) to render the text formats. The CSS Custom Highlight API provides a mechanism for styling arbitrary text ranges by using JavaScript to create the ranges, and CSS to style them. To use this API, the {{cssxref("::highlight", "::highlight()")}} pseudo-element is used to define the highlight styles:
 
 ```css
 ::highlight(ime-solid-thin) {
@@ -470,38 +448,25 @@ for (const [key, value] of Object.entries(imeHighlights)) {
 }
 ```
 
-With this in place, the demo app creates {{domxref("Range")}} objects for the ranges that need to be styled, and adds them to the `Highlight` object:
+With this in place, the `addHighlight()` function uses {{domxref("Range")}} objects for the ranges that need to be styled, and adds them to the `Highlight` object:
 
 ```js
-editContext.addEventListener("textformatupdate", (e) => {
-  // Get the list of formats that the IME wants to apply.
-  const formats = e.getTextFormats();
-
-  // Iterate over the text formats.
-  for (const format of formats) {
-    // For each format, we know the underline style and thickness,
-    // as well as the start and end offsets of the range that needs
-    // to be styled.
-    const { rangeStart, rangeEnd, underlineStyle, underlineThickness } = format;
-
-    // Find the nodes that are in the range of the current format.
-    const { anchorNode, anchorOffset, extentNode, extentOffset } =
-      convertFromOffsetsToSelection(rangeStart, rangeEnd);
-
-    // Get the right Highlight instance.
-    const highlight =
-      imeHighlights[
-        `${format.underlineStyle.toLowerCase()}-${format.underlineThickness.toLowerCase()}`
-      ];
-
-    // Create a range object for the range that needs to be styled
-    // And add it to the Highlight object.
+function addHighlight(selection, underlineStyle, underlineThickness) {
+  // Get the right CSS custom Highlight object depending on the
+  // underline style and thickness.
+  const highlight =
+    imeHighlights[
+      `${underlineStyle.toLowerCase()}-${underlineThickness.toLowerCase()}`
+    ];
+
+  if (highlight) {
+    // Add a range to the Highlight object.
     const range = document.createRange();
-    range.setStart(anchorNode, anchorOffset);
-    range.setEnd(extentNode, extentOffset);
+    range.setStart(selection.anchorNode, selection.anchorOffset);
+    range.setEnd(selection.extentNode, selection.extentOffset);
     highlight.add(range);
   }
-});
+}
 ```
 
 ## Summary

From 0ea8d7bd8645d62db514cef718ef7eec90038da7 Mon Sep 17 00:00:00 2001
From: wbamberg <will@bootbonnet.ca>
Date: Mon, 18 Mar 2024 14:34:31 -0700
Subject: [PATCH 9/9] Fix link, hopefully

---
 files/en-us/web/api/editcontext_api/guide/index.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/files/en-us/web/api/editcontext_api/guide/index.md b/files/en-us/web/api/editcontext_api/guide/index.md
index 6647e52963f2186..3b6dfe92a943b53 100644
--- a/files/en-us/web/api/editcontext_api/guide/index.md
+++ b/files/en-us/web/api/editcontext_api/guide/index.md
@@ -224,7 +224,7 @@ function render(text, selectionStart, selectionEnd) {
 }
 ```
 
-You can see the code for the `fromOffsetsToSelection()` function in the [converter.js](<(https://github.com/mdn/dom-examples/tree/main/edit-context/html-editor/converter.js)>) file.
+You can see the code for the `fromOffsetsToSelection()` function in the [converter.js](https://github.com/mdn/dom-examples/tree/main/edit-context/html-editor/converter.js) file.
 
 ## Updating the control bounds