diff --git a/OpaqueRange/explainer.md b/OpaqueRange/explainer.md index 1def46b03..b91a388e8 100644 --- a/OpaqueRange/explainer.md +++ b/OpaqueRange/explainer.md @@ -18,9 +18,7 @@ The current `Range` interface methods do not support retrieving or creating ranges that represent the `value` (rather than the element itself) of ` - -const textarea = document.querySelector("#messageArea"); -const popup = document.querySelector("#popup"); +When an element is removed from the document or an `` element's type changes from a selectable type to a non-selectable type, all associated OpaqueRanges have their `startOffset` and `endOffset` set to 0 and the element's set of associated OpaqueRanges is cleared. -// Create a live, collapsed range at the caret. -const range = textarea.getValueRange(textarea.selectionStart, textarea.selectionStart); +When the underlying content changes, the browser automatically adjusts the offsets of all associated OpaqueRanges. For incremental edits (such as user typing or `setRangeText()`), offsets shift to reflect inserted or deleted characters. For wholesale value changes (such as setting the `value` property or changing the `type` attribute), offsets are reset. -textarea.addEventListener("input", () => { - // Position popup under caret. - const rect = range.getBoundingClientRect(); - popup.style.left = `${rect.left}px`; - popup.style.top = `${rect.bottom}px`; -}); -``` -As the user types, the popup stays positioned under the caret without manually recalculating offsets. +## Live Range Example + +The example below demonstrates how `OpaqueRange` updates in real time as the text content of the control changes, without requiring manual offset adjustments. -### Example 2: Highlight Follows Word Through Edits +### Highlight Follows Word Through Edits ```js const textarea = document.querySelector("#messageArea"); @@ -525,7 +524,7 @@ However, this design had two limitations: 2. **Limited extensibility** Because the design encoded form-control-specific concepts into the API surface, extending it to additional environments would have required redefining or duplicating similar ideas elsewhere. -`OpaqueRange` resolves these issues by providing a host-extensible abstraction. Host specifications (such as HTML) define their own opaque strings and create or update `OpaqueRange` instances accordingly, without the interface being tied to form controls or their internal mechanisms. +`OpaqueRange` resolves these issues by providing an extensible abstraction. The HTML standard defines which elements [support opaque ranges](#supports-opaque-ranges), creates or updates `OpaqueRange` instances accordingly, and specifies the internal container nodes used — without the interface being tied to form controls or their internal mechanisms. ## Other Considerations @@ -537,15 +536,13 @@ However, this design had two limitations: - There are no anticipated security concerns. -### Consistency - -`OpaqueRange` is always returned by the platform from `getValueRange()` on `