@astryxdesign/core 0.7.8 → 0.7.9-canary.0200dfe

package/src/Layer/inputHold.ts

@@ -0,0 +1,734 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file inputHold.ts
+ * @input A layer root, what ends its hold (a promise or an animator handle),
+ *   and the hold's scope
+ * @output holdInput, holdsTouch, isInHeldLayer and isInputShield: input held
+ *   away from a layer while it presents or dismisses
+ * @position The Layer module's one input hold, for components whose layer
+ *   presents under a finger
+ *
+ * SYNC: When modified, update inputHold.test.tsx,
+ * __tests__/inputHold.interaction.browser.spec.ts and the holdInput callers.
+ */
+
+import {
+  containsAlongFlatTree,
+  deepActiveElement,
+  parentAcrossShadow,
+} from '../utils/flatTree';
+import {getLastPointerType, subscribeInput} from '../utils/inputStream';
+
+/**
+ * What a hold does. `'viewport'` and `'layer'` add one shield over the whole
+ * viewport. `'layer'` also makes the layer's content inert and moves focus
+ * out of it. `'surface'` shields only the layer's own box, and the page
+ * around it stays live.
+ */
+export type InputHoldScope = 'viewport' | 'layer' | 'surface';
+
+/** What ends a hold: a promise, or an animator handle (its `finished`). */
+export type InputHoldEnd =
+  PromiseLike<unknown> | {readonly finished: PromiseLike<unknown>};
+
+export interface InputHoldOptions {
+  /** The hold ends when this settles. */
+  until: InputHoldEnd;
+  /**
+   * `'viewport'` while presenting, `'layer'` while dismissing, `'surface'`
+   * while a non-modal layer presents.
+   */
+  scope: InputHoldScope;
+}
+
+interface HeldLayer {
+  viewport: number;
+  layer: number;
+  surface: number;
+  shield: HTMLElement | null;
+  /** Whether the shield covers the viewport, or only the layer's box. */
+  isShieldFull: boolean;
+  /** The content a dismissal made inert, and whether each was already. */
+  inertContent: Map<Element, boolean> | null;
+}
+
+/** A document while any of its layers is held. */
+interface HeldDocument {
+  /** Its held layers, oldest first. */
+  readonly layers: Set<Element>;
+}
+
+/** A document's press hold, while its window listeners are on. */
+interface PressHold {
+  /** New presses are held again (a layer is held). */
+  hold: () => void;
+  /** No new press is held; held ones are followed to their end. */
+  release: () => void;
+}
+
+const held = new WeakMap<Element, HeldLayer>();
+const heldDocuments = new WeakMap<Document, HeldDocument>();
+const pressHolds = new WeakMap<Document, PressHold>();
+const liveShields = new WeakSet<Node>();
+
+/** Whether the shared input stream last delivered a mouse's pointer event. */
+function isMouseLast(doc: Document | null): boolean {
+  const view = doc?.defaultView;
+  return view != null && getLastPointerType(view) === 'mouse';
+}
+
+/**
+ * Whether `node` is the shield of a live hold. A hit test that must see past
+ * held input takes the first element of `elementsFromPoint` that is not one.
+ */
+export function isInputShield(node: Node | null): boolean {
+  return node != null && liveShields.has(node);
+}
+
+/**
+ * Whether `target` is inside a held layer. It walks the flat tree as the
+ * gesture host does: a slotted node goes to its slot, and a shadow root to
+ * its host.
+ */
+export function isInHeldLayer(target: Node | null): boolean {
+  for (
+    let node: Node | null = target;
+    node != null;
+    node = parentAcrossShadow(node)
+  ) {
+    if (node instanceof Element && held.has(node)) {
+      return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * Whether the gesture host holds `target` away for the current pointer. A
+ * dismissing layer holds every pointer. A presenting layer holds every
+ * pointer but a mouse, which keeps today's behavior. The host asks this for
+ * every touch. So this module imports nothing from gestures/, and a
+ * root-entry component can hold its layer without gesture code. With nothing
+ * held, this answers false.
+ */
+export function holdsTouch(target: Node): boolean {
+  const doc = target instanceof Document ? target : target.ownerDocument;
+  // The gesture host asks for every touch: with nothing held, answer at once.
+  if (doc == null || !heldDocuments.has(doc)) {
+    return false;
+  }
+  // What lands on a shield is held, a mouse's press included.
+  if (isInputShield(target)) {
+    return true;
+  }
+  let isHeld = false;
+  for (
+    let node: Node | null = target;
+    node != null;
+    node = parentAcrossShadow(node)
+  ) {
+    const state = node instanceof Element ? held.get(node) : undefined;
+    if (state != null) {
+      if (state.layer > 0) {
+        return true;
+      }
+      isHeld = true;
+    }
+  }
+  return isHeld && !isMouseLast(doc);
+}
+
+/**
+ * Starts holding `layer`. A document's first held layer turns its press hold
+ * on, with one stream subscription per event type, however many layers are
+ * held. The hold subscribes to nothing while nothing is held.
+ */
+function startHolding(layer: Element): void {
+  const doc = layer.ownerDocument;
+  let state = heldDocuments.get(doc);
+  if (state == null) {
+    state = {layers: new Set()};
+    heldDocuments.set(doc, state);
+  }
+  state.layers.add(layer);
+  pressHoldFor(doc)?.hold();
+}
+
+/** Stops holding `layer`; after the document's last one, ends its holding. */
+function stopHolding(layer: Element): void {
+  heldDocuments.get(layer.ownerDocument)?.layers.delete(layer);
+  liveLayers(layer.ownerDocument);
+}
+
+/**
+ * The document's held layers still in it, oldest first. A layer that has
+ * left the document holds nothing more. When none is left, `holdsTouch`
+ * answers false and the press hold takes no new press. Its subscriptions end
+ * once the presses it holds have ended.
+ */
+function liveLayers(doc: Document): Element[] {
+  const state = heldDocuments.get(doc);
+  if (state == null) {
+    return [];
+  }
+  for (const layer of state.layers) {
+    if (!layer.isConnected) {
+      state.layers.delete(layer);
+    }
+  }
+  if (state.layers.size > 0) {
+    return [...state.layers];
+  }
+  heldDocuments.delete(doc);
+  pressHolds.get(doc)?.release();
+  return [];
+}
+
+const SWALLOWED = [
+  'pointerdown',
+  'pointerup',
+  'touchstart',
+  'touchend',
+  'mousedown',
+  'mouseup',
+  'click',
+  'contextmenu',
+] as const;
+
+const swallow = (event: Event) => {
+  // A touch's start stays uncancelled: cancelling it would cancel the page's
+  // pinch-zoom too. The shield's `touch-action: pinch-zoom` keeps a finger
+  // from panning. A tap's mouse events and click land on the shield, which
+  // swallows them.
+  if (event.cancelable && event.type !== 'touchstart') {
+    event.preventDefault();
+  }
+  event.stopPropagation();
+};
+
+/**
+ * A transparent cover inside `layer`: of the viewport from the top layer
+ * (`isFull`), or of the layer's own box alone. Because the cover is inside
+ * the layer, a tap on it lands in the layer, and a light-dismissing layer
+ * stays open.
+ */
+function addShield(layer: Element, isFull: boolean): HTMLElement {
+  const shield = layer.ownerDocument.createElement('div');
+  if (isFull) {
+    shield.setAttribute('popover', 'manual');
+  }
+  shield.setAttribute('aria-hidden', 'true');
+  Object.assign(shield.style, {
+    position: isFull ? 'fixed' : 'absolute',
+    inset: '0',
+    width: isFull ? '100vw' : '100%',
+    height: isFull ? '100vh' : '100%',
+    // Above the layer's own content.
+    zIndex: isFull ? 'auto' : '2147483647',
+    maxWidth: 'none',
+    maxHeight: 'none',
+    margin: '0',
+    padding: '0',
+    border: '0',
+    background: 'transparent',
+    overflow: 'hidden',
+    touchAction: 'pinch-zoom',
+    // These two inherited properties decide hit-testing. A layer root can opt
+    // out of hits, as a full-viewport layer does when a backdrop child takes
+    // them. Inherited from such a root, they would let a held tap fall through
+    // to the page.
+    pointerEvents: 'auto',
+    visibility: 'visible',
+  });
+  for (const type of SWALLOWED) {
+    shield.addEventListener(type, swallow, {capture: true, passive: false});
+  }
+  layer.append(shield);
+  liveShields.add(shield);
+  if (isFull && typeof shield.showPopover === 'function') {
+    try {
+      shield.showPopover();
+    } catch {
+      // Not connected, or popovers unsupported: the shield still covers
+      // what it can as a fixed element.
+    }
+  }
+  return shield;
+}
+
+/**
+ * Holds input away from `layer` until `until` settles. Returns the release
+ * (idempotent), for a hold that ends early. Holds on one layer stack, and
+ * the layer comes back when the last one ends. Each event is judged by its
+ * own pointer, never by the primary pointer. So a mouse on a touch screen
+ * keeps its clicks during a presentation.
+ */
+export function holdInput(
+  layer: Element,
+  {until, scope}: InputHoldOptions,
+): () => void {
+  let state = held.get(layer);
+  if (state == null) {
+    state = {
+      viewport: 0,
+      layer: 0,
+      surface: 0,
+      shield: null,
+      isShieldFull: false,
+      inertContent: null,
+    };
+    held.set(layer, state);
+  }
+  startHolding(layer);
+  const isFull = scope !== 'surface';
+  if (state.shield != null && isFull && !state.isShieldFull) {
+    // A surface hold's shield gives way to one over the viewport.
+    liveShields.delete(state.shield);
+    state.shield.remove();
+    state.shield = null;
+  }
+  if (state.shield == null) {
+    state.isShieldFull = isFull || state.viewport + state.layer > 0;
+    state.shield = addShield(layer, state.isShieldFull);
+    // A presentation lets a mouse through from the start when the stream's
+    // last pointer was a mouse. A press where the mouse rests then acts.
+    if (scope !== 'layer' && isMouseLast(layer.ownerDocument)) {
+      state.shield.style.pointerEvents = 'none';
+    }
+  }
+  if (scope === 'viewport') {
+    state.viewport += 1;
+  } else if (scope === 'surface') {
+    state.surface += 1;
+  } else {
+    state.layer += 1;
+    // A dismissal's shield takes every hit, a mouse's included.
+    state.shield.style.pointerEvents = 'auto';
+    if (state.layer === 1) {
+      state.inertContent = makeContentInert(layer, state.shield);
+    }
+  }
+  let isReleased = false;
+  const release = () => {
+    if (isReleased) {
+      return;
+    }
+    isReleased = true;
+    const current = held.get(layer);
+    if (current == null) {
+      return;
+    }
+    if (scope === 'viewport') {
+      current.viewport -= 1;
+    } else if (scope === 'surface') {
+      current.surface -= 1;
+    } else {
+      current.layer -= 1;
+      if (current.layer === 0 && current.inertContent != null) {
+        restoreInert(current.inertContent);
+        current.inertContent = null;
+      }
+    }
+    if (
+      current.viewport === 0 &&
+      current.layer === 0 &&
+      current.surface === 0
+    ) {
+      if (current.shield != null) {
+        liveShields.delete(current.shield);
+        current.shield.remove();
+      }
+      held.delete(layer);
+      stopHolding(layer);
+    }
+  };
+  const end = 'finished' in until ? until.finished : until;
+  void Promise.resolve(end).then(release, release);
+  return release;
+}
+
+const HELD_POINTERS: ReadonlySet<string> = new Set(['touch', 'pen']);
+
+/**
+ * How long after a held press ends its click and compatibility mouse events
+ * still count as its own (WebKit sends them after `touchend`).
+ */
+const CLICK_WINDOW_MS = 800;
+
+/** How long a held press is followed past the hold's end, at most. */
+const STRAY_PRESS_MS = 10_000;
+
+const POINTER_EVENTS = [
+  'pointerdown',
+  'pointermove',
+  'pointerup',
+  'pointercancel',
+] as const;
+const TOUCH_EVENTS = [
+  'touchstart',
+  'touchmove',
+  'touchend',
+  'touchcancel',
+] as const;
+const PRESS_EVENTS = [
+  'mousedown',
+  'mouseup',
+  'click',
+  'auxclick',
+  'dblclick',
+  'contextmenu',
+] as const;
+
+/** The document's press hold, turned on if it is off. */
+function pressHoldFor(doc: Document): PressHold | null {
+  let hold = pressHolds.get(doc) ?? null;
+  if (hold == null) {
+    hold = createPressHold(doc);
+    if (hold != null) {
+      pressHolds.set(doc, hold);
+    }
+  }
+  return hold;
+}
+
+/**
+ * Holds each finger or pen press that lands in `doc`'s window while any of
+ * its layers is held. Each press is held to its own end, even past the
+ * hold's end. A moving mouse passes through a presentation's shield. The
+ * hold hears input through the shared input stream, before its other
+ * subscribers, and stops each held event there. So no document or element
+ * listener hears it, and neither does press feedback or the gesture host.
+ * There is one per document. Its subscriptions end once nothing is held and
+ * the held presses and their clicks have ended.
+ */
+function createPressHold(doc: Document): PressHold | null {
+  const view = doc.defaultView;
+  if (view == null) {
+    return null;
+  }
+  /** Whether a new press is held: until the release. */
+  let isHolding = true;
+  let isListening = true;
+  /** The held presses still down, by pointer id and by touch identifier. */
+  const pointers = new Set<number>();
+  const touches = new Set<number>();
+  /** Whose press the next click is: a held one's, or any other's. */
+  let lastPress: 'held' | 'free' | null = null;
+  /** Until when a click with no pointer type is a held press's. */
+  let clickUntil = -Infinity;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+
+  const now = () => view.performance.now();
+  const isPressDown = () => pointers.size > 0 || touches.size > 0;
+
+  const swallow = (event: Event) => {
+    if (event.cancelable) {
+      event.preventDefault();
+    }
+    event.stopImmediatePropagation();
+  };
+
+  /** After the release: stops once the last held press and its click end. */
+  const settle = () => {
+    if (isHolding || !isListening) {
+      return;
+    }
+    if (timer !== undefined) {
+      clearTimeout(timer);
+    }
+    if (isPressDown()) {
+      timer = setTimeout(stop, STRAY_PRESS_MS);
+      return;
+    }
+    const wait = clickUntil - now();
+    if (wait > 0) {
+      timer = setTimeout(stop, wait);
+    } else {
+      stop();
+    }
+  };
+
+  /** Whether a layer is still held (one that left the document is not). */
+  const holdsNewPress = () => {
+    if (isHolding) {
+      liveLayers(doc);
+    }
+    return isHolding;
+  };
+
+  /**
+   * Whether a new press that lands on `target` is held. While a layer is held
+   * over the viewport, a press anywhere is held. While a layer is held only
+   * to its box (a `'surface'` hold), only a press on the layer is held. The
+   * page around it stays live.
+   */
+  const holdsPressAt = (target: EventTarget | null) => {
+    if (!holdsNewPress()) {
+      return false;
+    }
+    for (const layer of liveLayers(doc)) {
+      const state = held.get(layer);
+      if (state == null) {
+        continue;
+      }
+      if (state.viewport > 0 || state.layer > 0) {
+        return true;
+      }
+      if (
+        state.surface > 0 &&
+        target instanceof Node &&
+        containsAlongFlatTree(layer, target)
+      ) {
+        return true;
+      }
+    }
+    return false;
+  };
+
+  const pressEnded = () => {
+    clickUntil = now() + CLICK_WINDOW_MS;
+    settle();
+  };
+
+  /** A shield takes hits for a finger or a pen, not for a moving mouse. */
+  const followPointer = (pointerType: string) => {
+    for (const layer of liveLayers(doc)) {
+      const state = held.get(layer);
+      if (state?.shield == null) {
+        continue;
+      }
+      const value =
+        pointerType === 'mouse' && state.layer === 0 ? 'none' : 'auto';
+      if (state.shield.style.pointerEvents !== value) {
+        state.shield.style.pointerEvents = value;
+      }
+    }
+  };
+
+  /**
+   * A held press that landed past the shield, which had let a mouse through,
+   * is captured to the shield. Its release then stays the hold's, and a
+   * light-dismissing layer stays open. A synthetic press has no active
+   * pointer to capture, so `setPointerCapture` throws NotFoundError. Its
+   * events are swallowed all the same.
+   */
+  const captureToShield = (event: PointerEvent) => {
+    if (!event.isTrusted) {
+      return;
+    }
+    const top = liveLayers(doc).at(-1);
+    const shield = top == null ? null : held.get(top)?.shield;
+    if (shield == null || isInputShield(event.target as Node | null)) {
+      return;
+    }
+    shield.setPointerCapture(event.pointerId);
+  };
+
+  const onPointer = (event: Event): boolean => {
+    const {pointerId, pointerType, type} = event as PointerEvent;
+    // A finger or a pen raises the shields. Only a mouse that moves with no
+    // button down lowers them. So a mouse press that began on a shield stays
+    // the shield's to its end. Otherwise its click would go to the two
+    // targets' common ancestor, a dialog that reads it as a backdrop click.
+    const isFollowed = HELD_POINTERS.has(pointerType)
+      ? type === 'pointerdown' || type === 'pointermove'
+      : pointerType === 'mouse' &&
+        type === 'pointermove' &&
+        (event as PointerEvent).buttons === 0;
+    if (isFollowed && holdsNewPress()) {
+      followPointer(pointerType);
+    }
+    if (type === 'pointerdown') {
+      if (!HELD_POINTERS.has(pointerType) || !holdsPressAt(event.target)) {
+        // A mouse's press, or one after the hold: its click is its own, and a
+        // held press with its id ended unheard.
+        pointers.delete(pointerId);
+        lastPress = 'free';
+        clickUntil = -Infinity;
+        settle();
+        return false;
+      }
+      pointers.add(pointerId);
+      lastPress = 'held';
+      captureToShield(event as PointerEvent);
+    } else if (!pointers.has(pointerId)) {
+      return false;
+    }
+    // Canceling the press keeps the browser from sending its compatibility
+    // mouse events, and with them a focus move.
+    swallow(event);
+    if (type === 'pointerup' || type === 'pointercancel') {
+      pointers.delete(pointerId);
+      pressEnded();
+    }
+    return true;
+  };
+
+  const onTouch = (event: Event): boolean => {
+    const {changedTouches, touches: down, type} = event as TouchEvent;
+    const changed = Array.from(changedTouches);
+    if (type === 'touchstart') {
+      // A held touch that the screen no longer has ended unheard. Its target,
+      // the shield, left the document at the release, so its end reached no
+      // listener here.
+      const live = new Set(Array.from(down, touch => touch.identifier));
+      for (const identifier of touches) {
+        if (!live.has(identifier)) {
+          touches.delete(identifier);
+        }
+      }
+      const heldTouches = changed.filter(touch => holdsPressAt(touch.target));
+      if (heldTouches.length === 0) {
+        // A touch after the hold, or one beside a layer held only to its
+        // box, is a new one, whatever its identifier.
+        for (const touch of changed) {
+          touches.delete(touch.identifier);
+        }
+        lastPress = 'free';
+        clickUntil = -Infinity;
+        settle();
+        return false;
+      }
+      for (const touch of heldTouches) {
+        touches.add(touch.identifier);
+      }
+      lastPress = 'held';
+      // Never canceled: canceling a touch's start would cancel the page's
+      // pinch-zoom with it.
+      event.stopImmediatePropagation();
+      return true;
+    }
+    if (!changed.some(touch => touches.has(touch.identifier))) {
+      return false;
+    }
+    if (type === 'touchmove') {
+      event.stopImmediatePropagation();
+      // One finger pans nothing; two still zoom the page.
+      if (down.length === 1 && event.cancelable) {
+        event.preventDefault();
+      }
+      return true;
+    }
+    // A canceled end sends no click and no compatibility mouse events.
+    swallow(event);
+    for (const touch of changed) {
+      touches.delete(touch.identifier);
+    }
+    pressEnded();
+    return true;
+  };
+
+  const onPress = (event: Event): boolean => {
+    // A click a key or assistive technology sends counts no press.
+    if ((event as MouseEvent).detail === 0) {
+      return false;
+    }
+    // A click that names its pointer is judged by that pointer. A
+    // compatibility mouse event, or a click sent as a plain mouse event,
+    // belongs to the last press.
+    const {pointerType} = event as Partial<PointerEvent>;
+    const isHeldPress =
+      lastPress === 'held' &&
+      (pointerType == null ||
+        pointerType === '' ||
+        HELD_POINTERS.has(pointerType));
+    if (isHeldPress && (isPressDown() || now() <= clickUntil)) {
+      swallow(event);
+      return true;
+    }
+    return false;
+  };
+
+  function stop(): void {
+    if (!isListening) {
+      return;
+    }
+    isListening = false;
+    if (pressHolds.get(doc) === pressHold) {
+      pressHolds.delete(doc);
+    }
+    if (timer !== undefined) {
+      clearTimeout(timer);
+    }
+    for (const unsubscribe of unsubscribers.splice(0)) {
+      unsubscribe();
+    }
+  }
+
+  // A touch's start and cancel are never canceled, so their subscriptions
+  // keep the stream passive for them. The hold hears each event first, so a
+  // held one reaches no other subscriber: press feedback and the gesture host
+  // never hear it.
+  const unsubscribers = [
+    ...POINTER_EVENTS.map(type =>
+      subscribeInput(view, type, onPointer, {cancels: true, first: true}),
+    ),
+    ...TOUCH_EVENTS.map(type =>
+      subscribeInput(view, type, onTouch, {
+        cancels: type === 'touchmove' || type === 'touchend',
+        first: true,
+      }),
+    ),
+    ...PRESS_EVENTS.map(type =>
+      subscribeInput(view, type, onPress, {cancels: true, first: true}),
+    ),
+  ];
+
+  const pressHold: PressHold = {
+    hold() {
+      isHolding = true;
+      if (timer !== undefined) {
+        clearTimeout(timer);
+        timer = undefined;
+      }
+    },
+    release() {
+      if (!isHolding) {
+        return;
+      }
+      isHolding = false;
+      settle();
+    },
+  };
+  return pressHold;
+}
+
+/**
+ * Makes the layer's content inert, except the shield, and moves focus out of
+ * it. An element that turns inert while focused keeps its focus and its key
+ * activation. Enter and Space still click such a button until the engine's
+ * focus fixup runs, if it runs. Blurring it leaves focus on the document, as
+ * that fixup does. The layer element itself stays live. An inert subtree is
+ * no hit target, so the shield inside the layer still catches every hit.
+ */
+function makeContentInert(
+  layer: Element,
+  shield: Element,
+): Map<Element, boolean> {
+  const content = new Map<Element, boolean>();
+  for (const child of layer.children) {
+    if (child !== shield) {
+      content.set(child, child.hasAttribute('inert'));
+      child.setAttribute('inert', '');
+    }
+  }
+  const focused = deepActiveElement(layer.ownerDocument);
+  if (
+    focused instanceof HTMLElement &&
+    [...content.keys()].some(child => containsAlongFlatTree(child, focused))
+  ) {
+    focused.blur();
+  }
+  return content;
+}
+
+function restoreInert(content: Map<Element, boolean>): void {
+  for (const [element, wasInert] of content) {
+    if (!wasInert) {
+      element.removeAttribute('inert');
+    }
+  }
+}