Selection API: getComposedRanges

[dizhang168]

Request for Mozilla Position on an Emerging Web Specification

• Specification title: getComposedRanges()
• Specification or proposal URL (if available): https://w3c.github.io/selection-api/#dom-selection-getcomposedranges
• Explainer URL (if available): https://github.com/mfreed7/shadow-dom-selection
• Proposal author(s) (@-mention GitHub accounts): @dizhang168 @mfreed7 @siliu1
• MDN URL (optional): https://developer.mozilla.org/en-US/docs/Web/API/Selection/getComposedRanges
• Caniuse.com URL (optional):
• Bugzilla URL (optional):
• Mozillians who can provide input (optional): @sefeng211 @emilio
• WebKit standards-position: Selection API: getComposedRanges WebKit/standards-positions#376

Other information

Current getComposedRanges API has single shadowRoots parameter which is a rest parameter. We propose changing it to a dictionary that contains an array of shadow roots to be consistent with other shadow DOM API:

• getHTML()
• caretPositionFromPoint()

We would also like to add selectionRoot. This argument "scopes" the selection, so that the returned selection endpoints are always descendants of element.

Proposed change:

sequence<StaticRange> getComposedRanges(optional GetComposedRangesOptions options = {});

dictionary GetComposedRangesOptions {
  sequence<ShadowRoot> shadowRoots = [];
  Node? selectionRoot = null;
};

Further, we need to re-evaluate API changes for the Range and StaticRange interface, to support nodes in different tree. Either we need to update existing definitions or we might need to add new interfaces. Help us resolve these discussions.

See:
Changes to Range, StaticRange: w3c/selection-api#169
Change getComposedRanges’ parameter to a dictionary: w3c/selection-api#176
Change getComposedRanges to have selectionRoot parameter: w3c/selection-api#180
Main: w3c/selection-api#161

[sefeng211]

We are positive with the API. The parameter changes were talked in TPAC 2024 and it was positive from the Working Group. We still have some discussions about whether we should use Composed Tree or Flat Tree for the Selection API, though I don't think they'll necessarily to impact the shape of getComposedRanges. So we are good.