An open source design system that's fully customizable and agent ready
TypeScript
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
* @file selectionLock.ts
* @input The elements a held touch contact presses, and the touch's target
* @output lockSelection and locksSelectionFor give a held finger's lock.
* lockDragSelection gives a claimed mouse or pen drag's hold, which keeps
* the page's selection. startsOnSelectableText and selectionRangesOf are
* what a mouse or pen press reads.
* @position Recognizers whose hold does something bring lockSelection; the
* gesture host imports the drag hold and the press reads.
*
* SYNC: When modified, update GestureHost.ts and utils/pressFeedback.ts; the
* iOS query matches utils/touchPresentation.ts.
*/
// A hold that does something never starts a selection or the callout under
// the finger (AST-094). A text field keeps its selection, because a held
// finger places its caret. A style change repaints what it covers, so the
// way to refuse differs by engine:
// - iOS WebKit fires no `selectstart` for a long press, so only
// `user-select` refuses it. The lock covers every held element, inline and
// refcounted. A lock on only the element under the finger let a long press
// select a word beside it. WebKit makes every input selectable, so an input
// under the finger is locked too.
// - Elsewhere, cancelling `selectstart` refuses the selection with no style
// write, so nothing repaints.
//
// A mouse never takes the lock, so its released behavior stays (AST-017).
import {
containsAlongFlatTree,
deepActiveElement,
parentAcrossShadow,
shadowHostOf,
shadowRootsOutward,
} from './flatTree';
import {subscribeInput} from './inputStream';
import {isIosWebKit} from './touchQueries';
import {isElement, isNode} from './nodeType';
/** What a held finger must not start on a control or a cell. */
const SELECTION_LOCK = [
'-webkit-touch-callout',
'-webkit-user-select',
'user-select',
] as const;
/** Inputs whose text a held finger edits: it places the caret there. */
const TEXT_ENTRY_TYPES = new Set([
'text',
'search',
'email',
'url',
'tel',
'password',
'number',
]);
/**
* Whether a contact of this pointer kind takes the lock: a finger or a pen,
* under any primary pointer, a laptop's touchscreen and a desktop pen tablet
* included, since a pen's hold acts as a finger's.
*/
export function locksSelectionFor(pointerType: string): boolean {
return pointerType !== 'mouse';
}
/** Locked elements, how many contacts hold each, and what to restore. */
const locks = new WeakMap<
Element,
{
count: number;
saved: ReadonlyArray<{name: string; value: string; priority: string}>;
}
>();
/**
* Refuse a selection and the touch callout on `elements` (and on a non-text
* input target inside one of them) until the returned function runs, while
* any holder holds. Idempotent release.
*/
export function lockSelection(
elements: Iterable<Element>,
target: EventTarget | null,
): () => void {
const set = new Set(elements);
if (
isSelectableControl(target) &&
[...set].some(element => containsAlongFlatTree(element, target))
) {
set.add(target);
}
if (!isIosWebKit()) {
const refuse = (event: Event) => {
if (!isTextEntry(event.target)) {
event.preventDefault();
}
};
for (const element of set) {
element.addEventListener('selectstart', refuse);
}
let isRefusing = true;
return () => {
if (isRefusing) {
isRefusing = false;
for (const element of set) {
element.removeEventListener('selectstart', refuse);
}
}
};
}
return lockStyles(set);
}
/** How a drag's selection hold ends: at a lift, or at a cancel. */
export interface DragSelectionReleaseOptions {
/**
* The press was cancelled (a pointercancel, a blur, a detach), so no
* mouseup or click follows: the hold ends at once. Called again after a
* lift, it ends the hold's last task at once too.
*/
isCancel?: boolean;
}
/** A drag's selection hold: call it to release the hold. */
export interface DragSelectionHold {
(options?: DragSelectionReleaseOptions): void;
/**
* Called after the lift's own handlers ran. A selection they made since
* the release stays: the hold then puts it back, not the press's.
*/
keepLiftSelection(): void;
}
/**
* Refuse a new selection while a mouse or pen drag that a recognizer claimed
* runs, until the returned function runs. `kept` is the page's selection
* when the press began, and it stays. Anything that replaces it while the
* drag runs is put back to it. That includes the press's own collapse and a
* selection the drag started before its claim. So the drag takes no new
* selection and never clears an existing one. `elements` refuse a
* selection with inline styles, on every engine. The document refuses one
* too, because WebKit extends a drag's selection over text outside the
* elements without another `selectstart`. So a `selectstart` anywhere is
* refused, and the selection is put back. A `selectstart` does not leave its
* shadow tree. So the document refuses only one that starts outside every
* shadow tree, and a claiming element inside one refuses its own. The
* press's own `mouseup` and `click` come after its `pointerup` in the same
* task, and WebKit settles the drag's selection there. So the document's
* hold ends a task after a lift. A cancel ends it at once, because nothing
* follows a cancel. `onReleased` runs once the document's hold has ended.
* The page listeners exist only during a press. Idempotent.
*/
export function lockDragSelection(
elements: Iterable<Element>,
view: Window | null | undefined,
kept: ReadonlyArray<AbstractRange>,
onReleased?: () => void,
): DragSelectionHold {
const doc = view?.document ?? null;
let keptRanges = kept;
let roots = shadowRootsOfRanges(keptRanges);
// The selection when the lift released the hold, until the lift's
// handlers ran.
let atLift: ReadonlyArray<AbstractRange> | null = null;
const restore = () => {
const selection = view?.getSelection();
// The focused field keeps its own selection (a drag never starts in one).
if (selection == null || isTextEntry(deepActiveElement(doc))) {
return;
}
const held = heldRanges(selection, roots);
if (keptRanges.length === 0) {
if (held.some(range => !range.collapsed)) {
selection.removeAllRanges();
}
return;
}
// A render can remove what the kept selection held: then there is
// nothing to put back.
if (sameRanges(held, keptRanges) || !keptRanges.every(isValidRange)) {
return;
}
selectRanges(selection, keptRanges);
};
restore();
const set = new Set(elements);
const refuse = (event: Event) => {
if (!isTextEntry(event.target)) {
event.preventDefault();
}
};
for (const element of set) {
element.addEventListener('selectstart', refuse);
}
const stopDocument =
view == null
? []
: [
subscribeInput(view, 'selectstart', refuse, {cancels: true}),
subscribeInput(view, 'selectionchange', restore),
];
const unlockStyles = lockStyles(set);
let stage: 'held' | 'lifted' | 'done' = 'held';
let timer: number | null = null;
const releaseDocument = () => {
if (stage === 'done') {
return;
}
stage = 'done';
if (timer != null) {
view?.clearTimeout(timer);
timer = null;
}
try {
restore();
} finally {
for (const stop of stopDocument) {
stop();
}
onReleased?.();
}
};
const release = (({isCancel = false}: DragSelectionReleaseOptions = {}) => {
if (stage === 'held') {
stage = 'lifted';
atLift = selectionRangesOf(view);
for (const element of set) {
element.removeEventListener('selectstart', refuse);
}
unlockStyles();
// A lift's own mouseup and click follow in its task and must still
// meet the hold; nothing follows a cancel, which ends it at once.
if (view == null || isCancel) {
releaseDocument();
} else {
timer = view.setTimeout(releaseDocument, 0);
}
} else if (stage === 'lifted' && isCancel) {
releaseDocument();
}
}) as DragSelectionHold;
release.keepLiftSelection = () => {
if (stage !== 'lifted' || atLift == null) {
return;
}
const before = atLift;
atLift = null;
const keepIfChanged = () => {
const now = selectionRangesOf(view);
if (stage !== 'done' && !sameRanges(now, before)) {
keptRanges = now;
roots = shadowRootsOfRanges(now);
}
};
keepIfChanged();
// A click's state update renders in a microtask, and its layout effect
// may select then. That still runs before the press's own mouseup.
queueMicrotask(keepIfChanged);
};
return release;
}
/**
* The page's selection now, its ranges copied; none for a collapsed or empty
* one. A drag's hold keeps what this read when the press began.
*/
export function selectionRangesOf(
view: Window | null | undefined,
): ReadonlyArray<AbstractRange> {
const selection = view?.getSelection();
if (selection == null) {
return [];
}
const composed = composedRangesOf(selection, []);
if (composed != null) {
return composed.filter(range => !range.collapsed).map(liveWhereItCan);
}
if (selection.isCollapsed) {
return [];
}
const ranges: Range[] = [];
for (let index = 0; index < selection.rangeCount; index++) {
ranges.push(selection.getRangeAt(index).cloneRange());
}
return ranges;
}
/**
* Whether a press at (`x`, `y`) lands on text a drag would select. That is a
* text field, or a character of non-empty text whose element allows a
* selection. A native button's label, slotted or not, is not selectable text,
* because the engine starts no selection from a drag inside a button. A point
* beside text, which a caret query snaps to the nearest character, lands on
* none. Where the engine has no caret query, nothing is selectable text.
*/
export function startsOnSelectableText(
doc: Document,
x: number,
y: number,
target: EventTarget | null,
): boolean {
if (isTextEntry(target)) {
return true;
}
const caret = caretAt(doc, x, y, [
...ownShadowRoot(target),
...openShadowRootsOf(target),
]);
if (caret == null) {
return false;
}
const {node, offset} = caret;
if (node.nodeType !== 3 || (node.textContent ?? '').trim() === '') {
return false;
}
// Text directly under a shadow root takes its host's style.
const element =
node.parentElement ??
(node.parentNode == null ? null : shadowHostOf(node.parentNode));
if (element == null || !allowsSelection(element) || isInButton(node)) {
return false;
}
const length = (node.textContent ?? '').length;
const range = doc.createRange();
if (typeof range.getClientRects !== 'function') {
return false;
}
for (const start of [offset - 1, offset]) {
if (start < 0 || start >= length) {
continue;
}
range.setStart(node, start);
range.setEnd(node, start + 1);
for (const rect of Array.from(range.getClientRects())) {
if (
x >= rect.left &&
x <= rect.right &&
y >= rect.top &&
y <= rect.bottom
) {
return true;
}
}
}
return false;
}
/** Whether `node` is inside a native button, along the flat tree. */
function isInButton(node: Node): boolean {
for (let at: Node | null = node; at != null; at = parentAcrossShadow(at)) {
if (at.nodeType === 1 && (at as Element).localName === 'button') {
return true;
}
}
return false;
}
/** The caret position the engine puts at a point, by either query. */
export function caretAt(
doc: Document,
x: number,
y: number,
shadowRoots: ReadonlyArray<ShadowRoot>,
): {node: Node; offset: number} | null {
const queries = doc as Document & {
caretPositionFromPoint?: (
x: number,
y: number,
options?: {shadowRoots?: ShadowRoot[]},
) => {offsetNode: Node; offset: number} | null;
caretRangeFromPoint?: (x: number, y: number) => Range | null;
};
if (typeof queries.caretPositionFromPoint === 'function') {
// Without the roots, a point over shadow text answers at its host.
const position =
shadowRoots.length > 0
? queries.caretPositionFromPoint(x, y, {
shadowRoots: [...shadowRoots],
})
: queries.caretPositionFromPoint(x, y);
return position == null
? null
: {node: position.offsetNode, offset: position.offset};
}
if (typeof queries.caretRangeFromPoint === 'function') {
const range = queries.caretRangeFromPoint(x, y);
return range == null
? null
: {node: range.startContainer, offset: range.startOffset};
}
return null;
}
/** Whether an element's text can be selected (`user-select` is not none). */
function allowsSelection(element: Element): boolean {
const style = element.ownerDocument.defaultView?.getComputedStyle(element);
if (style == null) {
return false;
}
return (
style.getPropertyValue('user-select') !== 'none' &&
style.getPropertyValue('-webkit-user-select') !== 'none'
);
}
/**
* The ranges `selection` holds, with boundaries inside `shadowRoots` where the
* engine reads composed ranges.
*/
function heldRanges(
selection: Selection,
shadowRoots: ReadonlyArray<ShadowRoot>,
): ReadonlyArray<AbstractRange> {
const composed = composedRangesOf(selection, shadowRoots);
if (composed != null) {
return composed;
}
const ranges: Range[] = [];
for (let index = 0; index < selection.rangeCount; index++) {
ranges.push(selection.getRangeAt(index));
}
return ranges;
}
/**
* A live copy of `range` when both boundaries share a root, so it follows
* DOM changes. A range across roots stays static: no live range holds it.
*/
function liveWhereItCan(range: StaticRange): AbstractRange {
const live = range.startContainer.ownerDocument?.createRange();
if (
live == null ||
range.startContainer.getRootNode() !== range.endContainer.getRootNode()
) {
return range;
}
live.setStart(range.startContainer, range.startOffset);
live.setEnd(range.endContainer, range.endOffset);
return live;
}
/** Whether both of `range`'s boundaries still exist in the document. */
function isValidRange(range: AbstractRange): boolean {
return (
isValidBoundary(range.startContainer, range.startOffset) &&
isValidBoundary(range.endContainer, range.endOffset)
);
}
function isValidBoundary(node: Node, offset: number): boolean {
const length =
node.nodeType === 3 || node.nodeType === 4 || node.nodeType === 8
? (node as CharacterData).length
: node.childNodes.length;
return node.isConnected && offset >= 0 && offset <= length;
}
/** Whether two range lists have the same boundaries, in order. */
function sameRanges(
held: ReadonlyArray<AbstractRange>,
kept: ReadonlyArray<AbstractRange>,
): boolean {
return (
held.length === kept.length &&
kept.every((range, index) => {
const other = held[index];
return (
other.startContainer === range.startContainer &&
other.startOffset === range.startOffset &&
other.endContainer === range.endContainer &&
other.endOffset === range.endOffset
);
})
);
}
/**
* Put `ranges` back as the selection. One range goes through
* `setBaseAndExtent`, which also reaches inside a shadow root.
*/
function selectRanges(
selection: Selection,
ranges: ReadonlyArray<AbstractRange>,
): void {
const [only] = ranges;
if (ranges.length === 1 && typeof selection.setBaseAndExtent === 'function') {
selection.setBaseAndExtent(
only.startContainer,
only.startOffset,
only.endContainer,
only.endOffset,
);
return;
}
selection.removeAllRanges();
for (const range of ranges) {
const copy = range.startContainer.ownerDocument?.createRange();
if (copy == null) {
continue;
}
copy.setStart(range.startContainer, range.startOffset);
copy.setEnd(range.endContainer, range.endOffset);
selection.addRange(copy);
}
}
/**
* The selection's composed ranges, reaching into each open shadow root a
* boundary lands on; null where the engine has no `getComposedRanges`.
* Without the roots, a selection inside a shadow root reads as one around
* its host.
*/
function composedRangesOf(
selection: Selection,
known: ReadonlyArray<ShadowRoot>,
): StaticRange[] | null {
const query = (
selection as Selection & {
getComposedRanges?: (options?: {
shadowRoots?: ShadowRoot[];
}) => StaticRange[];
}
).getComposedRanges;
if (typeof query !== 'function') {
return null;
}
// Engines take the roots as a dictionary, or, in older releases, as
// arguments.
const read = (roots: ShadowRoot[]): StaticRange[] | null => {
try {
return query.call(selection, {shadowRoots: roots});
} catch {
try {
return (query as (...roots: ShadowRoot[]) => StaticRange[]).call(
selection,
...roots,
);
} catch {
return null;
}
}
};
const roots = [...known];
for (;;) {
const ranges = read([...roots]);
if (ranges == null) {
return null;
}
const found = new Set<ShadowRoot>();
for (const range of ranges) {
for (const [node, offset] of [
[range.startContainer, range.startOffset],
[range.endContainer, range.endOffset],
] as const) {
for (const child of [
node.childNodes[offset],
node.childNodes[offset - 1],
]) {
const root =
child?.nodeType === 1 ? (child as Element).shadowRoot : null;
if (root != null && !roots.includes(root)) {
found.add(root);
}
}
}
}
if (found.size === 0) {
return ranges;
}
roots.push(...found);
}
}
/** The open shadow roots on the root chains of `ranges`' boundaries. */
function shadowRootsOfRanges(
ranges: ReadonlyArray<AbstractRange>,
): ReadonlyArray<ShadowRoot> {
const roots = new Set<ShadowRoot>();
for (const range of ranges) {
for (const root of [
...openShadowRootsOf(range.startContainer),
...openShadowRootsOf(range.endContainer),
]) {
roots.add(root);
}
}
return [...roots];
}
/**
* The open shadow root `target` hosts, if any. A press on text directly under
* a shadow root targets its host.
*/
function ownShadowRoot(target: EventTarget | null): ShadowRoot[] {
const root =
(target as Node | null)?.nodeType === 1
? (target as Element).shadowRoot
: null;
return root == null ? [] : [root];
}
/** The open shadow roots on `target`'s root chain, innermost first. */
function openShadowRootsOf(target: EventTarget | null): ShadowRoot[] {
if (target == null || typeof (target as Node).nodeType !== 'number') {
return [];
}
return shadowRootsOutward((target as Node).getRootNode())
.map(({root}) => root)
.filter(root => root.mode === 'open');
}
/**
* The selection-lock styles on `set`, refcounted per element; idempotent
* release.
*/
function lockStyles(set: ReadonlySet<Element>): () => void {
const locked: Element[] = [];
for (const element of set) {
const style = styleOf(element);
if (style == null) {
continue;
}
locked.push(element);
const lock = locks.get(element);
if (lock != null) {
lock.count += 1;
continue;
}
locks.set(element, {
count: 1,
saved: SELECTION_LOCK.map(name => ({
name,
value: style.getPropertyValue(name),
priority: style.getPropertyPriority(name),
})),
});
for (const name of SELECTION_LOCK) {
style.setProperty(name, 'none');
}
}
let isReleased = false;
return () => {
if (isReleased) {
return;
}
isReleased = true;
for (const element of locked) {
const lock = locks.get(element);
if (lock == null || --lock.count > 0) {
continue;
}
locks.delete(element);
const style = styleOf(element);
for (const {name, value, priority} of lock.saved) {
if (value === '') {
style?.removeProperty(name);
} else {
style?.setProperty(name, value, priority);
}
}
}
};
}
/**
* A form control WebKit's own stylesheet makes selectable, which no
* ancestor's lock reaches: every input that is not a text field.
*/
function isSelectableControl(node: unknown): node is HTMLInputElement {
return (
isElement(node) &&
node.localName === 'input' &&
!TEXT_ENTRY_TYPES.has((node as HTMLInputElement).type)
);
}
/** Text a held finger edits: it places the caret there. */
function isTextEntry(node: EventTarget | null): boolean {
const element = isElement(node)
? node
: isNode(node)
? node.parentElement
: null;
if (element == null) {
return false;
}
if (element.localName === 'textarea') {
return true;
}
if (element.localName === 'input') {
return TEXT_ENTRY_TYPES.has((element as HTMLInputElement).type);
}
return (element as HTMLElement).isContentEditable;
}
/**
* An element's inline style, when it has one (HTML and SVG elements). It is
* checked as an object, so another window's style passes too.
*/
function styleOf(element: Element): CSSStyleDeclaration | null {
const style = (element as Partial<ElementCSSInlineStyle>).style;
return typeof style === 'object' && style !== null ? style : null;
}