Add `selectionRoot` option to getComposedRanges parameter options

[dizhang168]

To simplify selection for components that only wish to handle selections within a sub-tree, we would like to add the optional selectionRoot parameter. If provided, the returned StaticRange from getComposedRanges() will only contain endpoints that are inclusive descendants of this selectionRoot.

Proposal:

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

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

We would also need to redefine how the rescoping works for selectionRoot:

• If selection range's start node is outside/above the selectionRoot, it is rescoped to be the first position within selectionRoot.
• If selection range's end node is outside/above the selectionRoot, it is rescoped to be the last position within selectionRoot.

Resources

This parameter was first suggested in the explainer and had positive feedback. Please see the example in the explainer as it illustrates this parameter well.

Related issue: https://github.com/w3c/selection-api/issues/176

[dizhang168]

The use case for this parameter was discussed here: https://github.com/w3ctag/design-reviews/issues/694#issuecomment-1082211834

cc: @mfreed7

[mfreed7]

Conversation about the selectionRoot argument is found roughly here:

https://github.com/WICG/webcomponents/issues/79#issuecomment-962013007

Also note that providing selectionRoot automatically adds the containing shadow root to shadowRoots so that only the one argument is required in the common use case that a web component wants to just manage selections within its shadow.

[mfreed7]

@johanneswilm would you mind please Agenda+'ing this issue for TPAC? I don't have permission.

[dizhang168]

Summary of discussion at TPAC: This addition was suggested when the Selection API was first designed, but there has been no recent web developer feedback. Authors can also write library for this, it's not a new primitive. RESOLVED to wait on this until we have more developer feedback.

[dizhang168]

Closing this as this proposal is not in consideration for the current version of getComposedRanges. We can re-open if needed.