Editcontext API documentation

files/en-us/glossary/input_method_editor/index.md

@@ -6,11 +6,11 @@ page-type: glossary-definition
 
 {{GlossarySidebar}}
 
-An input method editor (IME) is a program that provides a specialized user interface for text input. Input method editors are used in many situations:
+An Input Method Editor (IME) is a program that provides a specialized user interface for text input. Input method editors are used in many situations:
 
-- to enter Chinese, Japanese, or Korean text using a Latin keyboard
-- to enter Latin text using a numeric keypad
-- to enter text on a touch screen using handwriting recognition
+- To enter Chinese, Japanese, or Korean text using a Latin keyboard.
+- To enter Latin text using a numeric keypad.
+- To enter text on a touch screen using handwriting recognition.
 
 ## See also
 

files/en-us/web/api/characterboundsupdateevent/characterboundsupdateevent/index.md

@@ -0,0 +1,38 @@
+---
+title: "CharacterBoundsUpdateEvent: CharacterBoundsUpdateEvent() constructor"
+short-title: CharacterBoundsUpdateEvent()
+slug: Web/API/CharacterBoundsUpdateEvent/CharacterBoundsUpdateEvent
+page-type: web-api-constructor
+browser-compat: api.CharacterBoundsUpdateEvent.CharacterBoundsUpdateEvent
+---
+
+{{APIRef("CharacterBoundsUpdateEvent API")}}
+
+The **`CharacterBoundsUpdateEvent()`** constructor returns a new {{DOMxRef("CharacterBoundsUpdateEvent")}} object.
+
+## Syntax
+
+```js-nolint
+new CharacterBoundsUpdateEvent(options)
+```
+
+### Parameters
+
+- `options` {{optional_inline}}
+  - : An optional object with the following properties:
+    - `rangeStart`
+      - : A number to set the offset of the first character within the editable text region which this event applies to.
+    - `rangeEnd`
+      - : A number to set the offset of the last character within the editable text region which this event applies to.
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- The {{DOMxRef("CharacterBoundsUpdateEvent")}} interface it belongs to.

files/en-us/web/api/characterboundsupdateevent/index.md

@@ -0,0 +1,81 @@
+---
+title: CharacterBoundsUpdateEvent
+slug: Web/API/CharacterBoundsUpdateEvent
+page-type: web-api-interface
+browser-compat: api.CharacterBoundsUpdateEvent
+---
+
+{{APIRef("EditContext API")}}
+
+The **`CharacterBoundsUpdateEvent`** interface is a {{domxref("Event", "DOM event")}} that represents a request from the operating system to know the bounds of certain characters within an editable region that's attached to an {{domxref("EditContext")}} instance.
+
+This interface inherits properties from {{domxref("Event")}}.
+
+{{InheritanceDiagram}}
+
+## Instance properties
+
+- {{domxref('CharacterBoundsUpdateEvent.rangeStart')}} {{readonlyinline}}
+  - : The offset of the first character within the editable region text for which the operating system needs the bounds.
+- {{domxref('CharacterBoundsUpdateEvent.rangeEnd')}} {{readonlyinline}}
+  - : The offset of the last character within the editable region text for which the operating system needs the bounds.
+
+## Examples
+
+### Updating the character bounds when needed
+
+This example shows how to use the `updateCharacterBounds` method to update the character bounds in the `EditContext` of a `canvas` element when the operating system indicates that it requires the information.
+
+```html
+<canvas id="editor-canvas"></canvas>
+```
+
+```js
+const FONT_SIZE = 40;
+const FONT = `${FONT_SIZE}px Arial`;
+
+const canvas = document.getElementById("editor-canvas");
+const ctx = canvas.getContext("2d");
+ctx.font = FONT;
+
+const editContext = new EditContext();
+canvas.editContext = editContext;
+
+function computeCharacterBound(offset) {
+  // Measure the width from the start of the text to the character.
+  const widthBeforeChar = canvasCtx.measureText(
+    editContext.text.substring(0, offset),
+  ).width;
+
+  // Measure the character width.
+  const charWidth = canvasCtx.measureText(editContext.text[offset]).width;
+
+  const charX = canvas.offsetLeft + widthBeforeChar;
+  const charY = canvas.offsetTop;
+
+  // Return a DOMRect representing the character bounds.
+  return DOMRect.fromRect({
+    x: charX,
+    y: charY - FONT_SIZE,
+    width: charWidth,
+    height: FONT_SIZE,
+  });
+}
+
+editContext.addEventListener("characterboundsupdate", (e) => {
+  const charBounds = [];
+  for (let offset = e.rangeStart; offset < e.rangeEnd; offset++) {
+    charBounds.push(computeCharacterBound(offset));
+  }
+
+  editContext.updateCharacterBounds(e.rangeStart, charBounds);
+});
+```
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}

files/en-us/web/api/characterboundsupdateevent/rangeend/index.md

@@ -0,0 +1,40 @@
+---
+title: "CharacterBoundsUpdateEvent: rangeEnd property"
+short-title: rangeEnd
+slug: Web/API/CharacterBoundsUpdateEvent/rangeEnd
+page-type: web-api-instance-property
+browser-compat: api.CharacterBoundsUpdateEvent.rangeEnd
+---
+
+{{APIRef("EditContext API")}}
+
+The **`CharacterBoundsUpdateEvent.rangeEnd`** read-only property represents the offset of the last character within the editable text region for which the operating system needs the bounds.
+
+## Value
+
+A {{jsxref("Number")}}.
+
+## Examples
+
+### Reading the `rangeEnd` value
+
+This example shows how to use the `characterboundsupdate` event and read the value of the `rangeStart` and `rangeEnd` properties.
+
+```js
+const editContext = new EditContext();
+editorElement.editContext = editContext;
+
+editContext.addEventListener("characterboundsupdate", (e) => {
+  console.log(
+    `The OS needs the bounds of the chars at ${e.rangeStart} - ${e.rangeEnd}.`,
+  );
+});
+```
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}

files/en-us/web/api/characterboundsupdateevent/rangestart/index.md

@@ -0,0 +1,40 @@
+---
+title: "CharacterBoundsUpdateEvent: rangeStart property"
+short-title: rangeStart
+slug: Web/API/CharacterBoundsUpdateEvent/rangeStart
+page-type: web-api-instance-property
+browser-compat: api.CharacterBoundsUpdateEvent.rangeStart
+---
+
+{{APIRef("EditContext API")}}
+
+The **`CharacterBoundsUpdateEvent.rangeStart`** read-only property represents the offset of the first character within the editable text region for which the operating system needs the bounds.
+
+## Value
+
+A {{jsxref("Number")}}.
+
+## Examples
+
+### Reading the `rangeStart` value
+
+This example shows how to use the `characterboundsupdate` event and read the value of the `rangeStart` and `rangeEnd` properties.
+
+```js
+const editContext = new EditContext();
+editorElement.editContext = editContext;
+
+editContext.addEventListener("characterboundsupdate", (e) => {
+  console.log(
+    `The OS needs the bounds of the chars at ${e.rangeStart} - ${e.rangeEnd}.`,
+  );
+});
+```
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}

files/en-us/web/api/compositionevent/index.md

@@ -23,7 +23,7 @@ _This interface also inherits properties of its parent, {{domxref("UIEvent")}},
 - {{domxref("CompositionEvent.data")}} {{ReadOnlyInline}}
   - : Returns the characters generated by the input method that raised the event; its varies depending on the type of event that generated the `CompositionEvent` object.
 - {{domxref("CompositionEvent.locale")}} {{ReadOnlyInline}} {{deprecated_inline}} {{Non-standard_Inline}}
-  - : Returns the locale of current input method (for example, the keyboard layout locale if the composition is associated with IME).
+  - : Returns the locale of current input method (for example, the keyboard layout locale if the composition is associated with {{glossary("IME")}}).
 
 ## Instance methods
 

files/en-us/web/api/compositionevent/locale/index.md

@@ -13,7 +13,7 @@ browser-compat: api.CompositionEvent.locale
 
 The **`locale`** read-only property of the
 {{domxref("CompositionEvent")}} interface returns the locale of current input method
-(for example, the keyboard layout locale if the composition is associated with IME).
+(for example, the keyboard layout locale if the composition is associated with {{glossary("IME")}}).
 
 > **Warning:** Even for browsers supporting it, don't trust the value contained in this property.
 > Even if technically it is accessible, the way to set it up when creating a {{domxref("CompositionEvent")}}

files/en-us/web/api/editcontext/attachedelements/index.md

@@ -0,0 +1,54 @@
+---
+title: "EditContext: attachedElements() method"
+short-title: attachedElements()
+slug: Web/API/EditContext/attachedElements
+page-type: web-api-instance-method
+browser-compat: api.EditContext.attachedElements
+---
+
+{{APIRef("EditContext API")}}
+
+The **`attachedElements()`** method of the {{domxref("EditContext")}} interface returns an {{jsxref("Array")}} that contains only one item. This item is the element that's associated with the `EditContext` object.
+
+## Syntax
+
+```js-nolint
+attachedElements()
+```
+
+### Return value
+
+An {{jsxref("Array")}} containing one {{domxref("HTMLElement")}} object.
+
+There can only be one element associated to an `EditContext` instance, so the returned array will always contain one element. If the API is extended in the future to support multiple associated elements, the return value will be an array containing multiple elements.
+
+## Examples
+
+### Getting the element associated with an `EditContext` instance
+
+This example shows how to use the `attachedElements` method to get the element that's associated with an `EditContext` instance.
+
+```html
+<canvas id="editor-canvas"></canvas>
+```
+
+```js
+const canvas = document.getElementById("editor-canvas");
+const editContext = new EditContext();
+canvas.editContext = editContext;
+
+const attachedElements = editContext.attachedElements();
+console.log(attachedElements[0] === canvas); // true
+```
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- The {{DOMxRef("EditContext")}} interface it belongs to.

files/en-us/web/api/editcontext/characterbounds/index.md

@@ -0,0 +1,39 @@
+---
+title: "EditContext: characterBounds() method"
+short-title: characterBounds()
+slug: Web/API/EditContext/characterBounds
+page-type: web-api-instance-method
+browser-compat: api.EditContext.characterBounds
+---
+
+{{APIRef("EditContext API")}}
+
+The **`characterBounds()`** method of the {{domxref("EditContext")}} interface returns an {{jsxref("Array")}} containing the list of bounding rectangles for the characters in the `EditContext` object.
+
+The position and size of the characters in an `EditContext` object is used by the operating system to correctly position platform-specific editing-related UI surfaces such as an {{glossary("Input Method Editor")}} (IME) window when needed. This is especially important in situations where the operating system can't automatically detect the position and size of the characters, such as when rendering text in a `<canvas>` element.
+
+Web developers will most likely be interested in using the {{domxref("EditContext.characterboundsupdate_event", "characterboundsupdate")}} event together with the {{domxref("EditContext.updateCharacterBounds()")}} method to update the character bounds when the operating system indicates that it requires information about the position and size of the characters.
+
+The `characterBounds()` method returns the list of character bounds that were last updated with `updateCharacterBounds()`. The list doesn't contain an item for every character in the `EditContext` object, only for the characters that were updated with `updateCharacterBounds()`. To know where the characters are located in the `EditContext` object, use the {{domxref("EditContext.characterBoundsRangeStart")}} property.
+
+## Syntax
+
+```js-nolint
+characterBounds()
+```
+
+### Return value
+
+An {{jsxref("Array")}} containing {{domxref("DOMRect")}} objects.
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- The {{DOMxRef("EditContext")}} interface it belongs to.

files/en-us/web/api/editcontext/characterboundsrangestart/index.md

@@ -0,0 +1,25 @@
+---
+title: "EditContext: characterBoundsRangeStart property"
+short-title: characterBoundsRangeStart
+slug: Web/API/EditContext/characterBoundsRangeStart
+page-type: web-api-instance-property
+browser-compat: api.EditContext.characterBoundsRangeStart
+---
+
+{{APIRef("EditContext API")}}
+
+The **`characterBoundsRangeStart`** read-only property of the {{domxref("EditContext")}} interface indicates the index of the character, within the editable text content, that corresponds to the first item in the {{domxref("EditContext.characterBounds()", "characterBounds")}} array.
+
+So, if the `EditContent` contains the characters `abc`, and if `characterBoundRangeStart` is `1`, then that means the first item in the `characterBounds` array contains the bounds for the character `b`.
+
+## Value
+
+A {{jsxref("Number")}}.
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}