@jhbrown94/selectionrange
v0.1.1
Published
Determine selection range inside of ShadowRoots with uniform API across browsers
Downloads
35
Maintainers
Readme
selectionrange
The problem
Browsers are inconsistent when a Selection
includes content that is inside a
ShadowRoot
Chrome implements
getSelection
onShadowRoot
which returns the real selection range inside the ShadowRoot.Firefox doesn't implement
getSelection
onShadowRoot
, butDocument.getSelection
sees into aShadowRoot
as if it wasn't hiding anything.Safari's
Document.getSelection
gives a boundary point which is just before theShadowRoot
.
This package aspires to paper over these differences with three functions.
The API
getSelectionRange
getSelectionRange(root)
gets the current selection if it is under the
root
. For root
, it takes either a ShadowRoot
or a Document
. If there
is no selection in the given root
, it returns null
. Otherwise, it returns
an object with this shape:
{
anchorNode: Node,
anchorOffset: Int,
focusNode: Node,
focusOffset: Int
}
The fields of this object follow the fields of the same name in a Selection
.
Note that this is not a formal Range
and will not update dynamically.
On Chrome and Firefox this should be about as fast as regular getSelection
. On Safari it could be considerably slower -- to determine position in text nodes, it often has to compute the entire string represented by the selection region, and also sometimes has to split text nodes one letter at a time (idea again from shadow-selection-polyfill
). The cost is at least O(N)
and could be O(N^2)
in text node length -- I don't actually know how (in)efficient text node splitting is under the hood in Safari.
setSelectionRange
setSelectionRange(root, range)
sets the current selection under the root
. It takes either a Document
or a ShadowRoot
as root
. For range
it takes either null
to indicate no selection range, or an object of the same shape as shown above.
isSquelchingEvents()
On Safari, getSelectionRange
generates a shower of selectionchange
events and triggers mutation observers, even though by the time their handlers are run the selection and DOM are restored to original state. isSquelchingEvents
returns true during a period that is intended to cover all of these byproduct events. Clients that don't want to respond to all of these can check isSquelchingEvents
in their event handlers and exit early when it is true. There is a theoretical possibility that some non-byproduct events could get hidden behind this squelch, please let me know if you run into this.
Automated testing
There is no automated testing of the package yet, so there are likely many quirky cases as yet undiscovered.
Request for feedback
This package is still in alpha. I'd love any and all reports of field experiences with it. Finding out that there are actual users will be the best motivation for me to improve it :)
Credits
This package is very, very heavily informed by
shadow-selection-polyfill
.
Where that package seeks principally to determine selected text, this one
attempts to more precisely identify selected DOM elements so that it can be
safely used with contenteditable
elements.