This patch implements the .direction attribute

Spec: https://www.w3.org/TR/selection-api/#dom-selection-direction

A new type range called CrossBoundaryRange is introduced and attached
to a nsRange when needed. Unlike nsRange::mStart and nsRange::mEnd where
we collapse to one point when the start and the end are in different
DOM trees (ie, crossing shadow boundary), CrossBoundaryRange keeps
the the original start and the end.

Depends on D195301

Spec: https://www.w3.org/TR/selection-api/#ref-for-dom-selection-getcomposedranges-1

Depends on D195302

This is mainly used for nsINode::IsMaybeSelected() to work for nodes
inside shadow tree.

Depends on D195303

Depends on D195304

With the abiliity to disable it as well

Depends on D195305

Depends on D195306

Depends on D195307

Depends on D195308

Depends on D195309

Depends on D195310

Depends on D195311

Depends on D195312

Depends on D195313

Depends on D195314

Depends on D196117

Backed out for causing bustages on AbstractRange.cpp

• Backout link
• Push with failures
• Failure Log

https://hg.mozilla.org/mozilla-central/rev/0b237fd5577a
https://hg.mozilla.org/mozilla-central/rev/713c66e124c7
https://hg.mozilla.org/mozilla-central/rev/0710183c2311
https://hg.mozilla.org/mozilla-central/rev/02d89b880ac5
https://hg.mozilla.org/mozilla-central/rev/b1f1e6ad93f8
https://hg.mozilla.org/mozilla-central/rev/3990acf05c58
https://hg.mozilla.org/mozilla-central/rev/d665bdcc228a
https://hg.mozilla.org/mozilla-central/rev/edcf770a3a1d
https://hg.mozilla.org/mozilla-central/rev/adc0f4aa70db
https://hg.mozilla.org/mozilla-central/rev/7340930e5a53
https://hg.mozilla.org/mozilla-central/rev/6a4069c6ee10
https://hg.mozilla.org/mozilla-central/rev/ca6c1077eb87

FF126 MDN work for this can be tracked in https://github.com/mdn/content/issues/33180

I have some questions:

1. This appears to add support for Selection.direction and Selection.getComposedRange().
   • Is that it? I mean the original explainer had a whole section Changes to existing Selection APIs - did that stuff happen too?
2. Selection.getComposedRange() returns an array of StaticRange. Is it correct that all current implementations in practise return a single range?
3. This is named composed range.
   • Reading around that seems to indicate that the range you get back is different from the old selections. It sounds like those are nodes and offsets, while "composed" might be a kind of flattened version that reflects the components as the UI would render them.
   • SO I'm "guessing" that this means a simplified version. Is this "close" to the right view of things, and what impact does using composed range have on users?
   • What do they have to think about because of this?
4. This returns a StaticRange. Reading the docs it sounds like this is the range at the time you got the selection.
   • So If the underlying DOM changes the StaticRange will be incorrect - presumably selecting something else?
   • What are the implications for someone using this? They have to make sure they fetch a new range every time their is a DOM change?

Bit out of my depth on this.

This appears to add support for Selection.direction and Selection.getComposedRange().
Is that it? I mean the original explainer had a whole section Changes to existing Selection APIs - did that stuff happen too?

Some of those stuff happened but some of them didn't....

• Selection.getRangeAt() should return ... - This didn't happen

• Selection.anchorNode/anchorOffset/focusNode/focusOffset should return ...- This didn't happen

• Selection.setBaseAndExtent() should now accept .... - This happened

• Selection.collapse() should now accept ... - This happened

• Selection.collapseToEnd()/collapseToStart() should .... - This didn't happen

• deleteFromDocument() should .... - This didn't happen

• extend() should .... This happened

• User selection via mouse, keyboard, etc .... This happened

Selection.getComposedRange() returns an array of StaticRange. Is it correct that all current implementations in practise return a single range?

In practice, only Firefox can return multiple ranges, other implementations can only return one range at max.

This is named composed range....
Reading around that seems to indicate that the range you get back is different from the old selections. It sounds like those are nodes and offsets, while "composed" might be a kind of flattened version that reflects the components as the UI would render them.
SO I'm "guessing" that this means a simplified version. Is this "close" to the right view of things, and what impact does using composed range have on users?
What do they have to think about because of this?

So basically it'll return the "true range" if the user provides the correct shadow roots of the corresponding boundaries.
And if the correct shadow roots are not provided, it'll rescope the boundaries to parent element of the root's host element (
if the parent is still in a shadow tree, it'll keep rescoping until the root is not a shadow root)

I think it makes sense to call this "close" to the right view of the boundaries. Speaking of impacts...I am not sure,
it's not going to be very useful if they don't provide the shadow roots. Though it's still better than calling
getRangeAt() because the range returned by getRangeAt() is going to be a collapsed range (at least in Firefox), which is even less useful.

This returns a StaticRange. Reading the docs it sounds like this is the range at the time you got the selection.
So If the underlying DOM changes the StaticRange will be incorrect - presumably selecting something else?
What are the implications for someone using this? They have to make sure they fetch a new range every time their is a DOM change?

Yeah, if the underlying DOM changes, the returned static range will be incorrect. In fact, if DOM mutation
happens, the entire "true range" can be incorrect, because the correct behaviour is undefined at the moment.
See https://github.com/w3c/selection-api/issues/168. So develpers should aware of these issues.

Hamish, hope this shed some lights, let me know if I can help more. Thanks

Thanks very much Sean - that's very helpful.

1. I have captured the "other API" compatibility changes in https://github.com/mdn/browser-compat-data/pull/23013

   • Is it correct these are all behind the same preference and also that they are standard (such as, returning multiple ranges)
   • I have marked that we are the only ones who have implemented all this new stuff so far - is that correct as far as we know.
   • For the the parts above that were not done, is that because they didn't make it into the spec, or they just haven't been implemented by anyone yet?

2. So with respect to a change to the underlying DOM, what should a user DO now? Can they monitor for such changes and re-fetch a range in some way? I mean I can document that this might happen, but it would be even better to be able to say "you can monitor for mutations by doing X, and fix them by doing Y".

   My "guess" is that you might be able to monitor for mutations (?) but if the nodes in the range could just become completely wrong, you might as well just throw away the selection at that point, or perhaps again "rescope to the parent of the shadow dom".

Is it correct these are all behind the same preference and also that they are standard (such as, returning multiple ranges)

Yeah, they all behind the same preference. Returning multiple ranges isn't a standardized behaviour, in fact the spec only asks to return one range.

I have marked that we are the only ones who have implemented all this new stuff so far - is that correct as far as we know.

Safari also have the getComposedRanges and selection.direction implement, I think Chrome doesn't, but some of the APIs might work in Chrome.

For the the parts above that were not done, is that because they didn't make it into the spec, or they just haven't been implemented by anyone yet?

Yeah...it's a mix of both. Really need to look this case-by-case. i.e, getRangeAt should be updated to include that rescope algorithm, but for things like collapseToEnd, it's just I didn't implement it.

So with respect to a change to the underlying DOM, what should a user DO now? Can they monitor for such changes and re-fetch a range in some way? I mean I can document that this might happen, but it would be even better to be able to say "you can monitor for mutations by doing X, and fix them by doing Y".

So if developers want to update the selection, they can use MutationObserver to monitor DOM mutations and then calling setBaseAndExtent to update it. To monitor the selection made by users, I think they should remain to do what they are currently doing? I think the scenario should be pretty much the same as without ShadowDOM selection.

Let me know if I can clarify more things!

Thanks very much Sean! I'll ping you if I need more.

Changes to things such as collapseToEnd aren't always obvious to writers or the browser compat tests, both of which rely on the IDL having a visible change.
So when/if you implement these, please highlight them by marking the bug as dev-docs-needed and adding a specific note.

Sean, mostly just for my interest:

• I understand that getComposedRanges() returns a single range in the spec, but Firefox can return multiple range objects
• Selection.direction returns the direction of a selection. But if a selection covers multiple ranges, to which selection does the value apply?

It's the direction of the most recent selection.