Add OpaqueRange interface

[stephanieyzhang]

OpaqueRange is a specialized, live AbstractRange subtype whose boundary points reference internal nodes within host-defined elements (e.g., <input>/<textarea> today, with a path to custom elements in the future). It enables range-based operations over encapsulated content while avoiding exposure of internal DOM nodes. This PR also updates AbstractRange so startContainer/endContainer are nullable (Node?), which allows OpaqueRange to return null for those getters while Range/StaticRange continue returning nodes.

• Explainer: https://github.com/MicrosoftEdge/MSEdgeExplainers/blob/main/OpaqueRange/explainer.md

• WHATWG Discussion: OpaqueRange Interface html#11478

• Corresponding HTML Spec PR: Integrate OpaqueRange hooks into text controls (input/textarea) html#11741

• Corresponding CSSOM PR: [cssom-view-1] Define OpaqueRange geometry APIs (getClientRects/getBoundingClientRect) w3c/csswg-drafts#12904

• At least two implementers are interested (and none opposed):

  • Microsoft Edge
  • WebKit: OpaqueRange: AbstractRange subtype for encapsulated content (<input>, <textarea>) WebKit/standards-positions#541
  • Mozilla: OpaqueRange: AbstractRange subtype for encapsulated content (<input>, <textarea>) mozilla/standards-positions#1289

• Tests are written and can be reviewed and commented upon at:

  • https://wpt.fyi/results/dom/ranges/tentative?label=master&label=experimental&aligned
  • PR to make tests non-tentative: Coming soon

• Implementation bugs are filed:

  • Chromium: https://issues.chromium.org/issues/421421332
  • Gecko: https://bugzilla.mozilla.org/show_bug.cgi?id=1990256
  • WebKit: https://bugs.webkit.org/show_bug.cgi?id=299375

• MDN issue is filed: …

• The top of this comment includes a clear commit message to use.

(See WHATWG Working Mode: Changes for more details.)

---

Preview | Diff

[dandclark]

Great to see a spec for this coming together!

[rniwa]

FWIW, I'd rather extend Range so that it can work with shadow host in general instead of creating a new interface specifically for form controls.

[stephanieyzhang]

FWIW, I'd rather extend Range so that it can work with shadow host in general instead of creating a new interface specifically for form controls.

We explored extending Range, including shadow host support, but found compatibility and encapsulation issues that made it risky to change existing Range semantics. Based on feedback across discussions, we went with a dedicated FormControlRange instead. The trade-offs and alternatives are covered in the explainer.

[rniwa]

FWIW, I'd rather extend Range so that it can work with shadow host in general instead of creating a new interface specifically for form controls.

We explored extending Range, including shadow host support, but found compatibility and encapsulation issues that made it risky to change existing Range semantics. Based on feedback across discussions, we went with a dedicated FormControlRange instead. The trade-offs and alternatives are covered in the explainer.

Changing the behavior of setStart/setEnd wouldn't be an only way to solve this problem. I'd instead add a new argument or a new function which specifies "offset" within element's shadow tree.

[dandclark]

This is looking good! Next big steps will be defining the right integration points from the HTML spec, and working towards consensus on the API shape.

[dandclark]

(this, too, will likely need to be something that we'll need to put in the HTML spec)

[dandclark]

Changing the behavior of setStart/setEnd wouldn't be an only way to solve this problem. I'd instead add a new argument or a new function which specifies "offset" within element's shadow tree.

@rniwa Thanks for the feedback! Yeah, there are a lot of ways this could be done. This suggestion sounds closer to the 2nd considered approach here. There are enough differences in how a Range inside a builtin element would work vs a "normal" range that we believe it will be overall cleaner and less confusing to split the functionality into a different type. For example the behavior we propose here is that a FormControlRange can't have one boundary point inside a <textarea>/<input> and another boundary point outside, which would be a clumsier invariant to express with the Range API surface. Adding this to Range would also add confusion about what things like Range.selectNodeContents should do; should it move the range to select an <input>'s value string, or not? We could add a parameter to all the setter functions to switch the behavior, but again it seems cleaner to relegate the behavior to a different interface vs adding parameters to a bunch of Range functions.

Anyway, whatwg/html#11478 is a better place to have this discussion -- more folks are following that issue vs this draft PR. @stephanieyzhang it might be helpful if you could update the PR description for this to point to that issue, as well as a direct link to the explainer.

[smaug----]

Is there a reason why OpaqueRange offsets are readonly? Or there isn't any method to update them?

[stephanieyzhang]

The offsets are readonly since they're inherited from AbstractRange. Currently the HTML PR defines createValueRange(start, end) on the element for creation. We haven't yet added an API for updating, so that's an open question. Some options could be an element-side API (e.g. updateValueRange(range, start, end)) to keep OpaqueRange generic, or setters directly on OpaqueRange.

Would appreciate your thoughts @annevk @smaug----