@astryxdesign/core 0.7.8 → 0.7.9-canary.3b44b43

package/dist/Layer/inputHold.js

@@ -0,0 +1,636 @@
+// 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.js";
+import { getLastPointerType, subscribeInput } from "../utils/inputStream.js";
+
+/**
+ * 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.
+ */
+
+/** What ends a hold: a promise, or an animator handle (its `finished`). */
+
+/** A document while any of its layers is held. */
+
+/** A document's press hold, while its window listeners are on. */
+
+const held = new WeakMap();
+const heldDocuments = new WeakMap();
+const pressHolds = new WeakMap();
+const liveShields = new WeakSet();
+
+/** Whether the shared input stream last delivered a mouse's pointer event. */
+function isMouseLast(doc) {
+  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) {
+  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) {
+  for (let node = 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) {
+  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 = 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) {
+  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) {
+  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) {
+  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'];
+const swallow = 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, isFull) {
+  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, {
+  until,
+  scope
+}) {
+  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 = 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'];
+const TOUCH_EVENTS = ['touchstart', 'touchmove', 'touchend', 'touchcancel'];
+const PRESS_EVENTS = ['mousedown', 'mouseup', 'click', 'auxclick', 'dblclick', 'contextmenu'];
+
+/** The document's press hold, turned on if it is off. */
+function pressHoldFor(doc) {
+  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) {
+  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();
+  const touches = new Set();
+  /** Whose press the next click is: a held one's, or any other's. */
+  let lastPress = null;
+  /** Until when a click with no pointer type is a held press's. */
+  let clickUntil = -Infinity;
+  let timer;
+  const now = () => view.performance.now();
+  const isPressDown = () => pointers.size > 0 || touches.size > 0;
+  const swallow = 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 => {
+    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 => {
+    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 => {
+    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)) {
+      return;
+    }
+    shield.setPointerCapture(event.pointerId);
+  };
+  const onPointer = event => {
+    const {
+      pointerId,
+      pointerType,
+      type
+    } = event;
+    // 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.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);
+    } 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 => {
+    const {
+      changedTouches,
+      touches: down,
+      type
+    } = event;
+    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 => {
+    // A click a key or assistive technology sends counts no press.
+    if (event.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;
+    const isHeldPress = lastPress === 'held' && (pointerType == null || pointerType === '' || HELD_POINTERS.has(pointerType));
+    if (isHeldPress && (isPressDown() || now() <= clickUntil)) {
+      swallow(event);
+      return true;
+    }
+    return false;
+  };
+  function stop() {
+    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 = {
+    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, shield) {
+  const content = new Map();
+  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) {
+  for (const [element, wasInert] of content) {
+    if (!wasInert) {
+      element.removeAttribute('inert');
+    }
+  }
+}

package/dist/Layer/preserveAnimations.d.ts

@@ -1,11 +1,7 @@
 /**
  * Run `reset`, which takes `root` out of rendering and back, and put every
  * CSS animation and transition of `root` and its subtree back in the state it
- * was in before. Recreated animations are matched to the ones they replace by
- * element, pseudo-element and name, in order, and then by name alone (an
- * effect script moved to another element or pseudo-element); a recreated
- * animation with no predecessor (an entry animation that had already played
- * and been dropped) is finished.
+ * was in before.
  */
 export declare function preserveAnimations(root: Element, reset: () => void): void;
 //# sourceMappingURL=preserveAnimations.d.ts.map

package/dist/Layer/preserveAnimations.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"preserveAnimations.d.ts","sourceRoot":"","sources":["../../src/Layer/preserveAnimations.ts"],"names":[],"mappings":"AAoPA;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,IAAI,GAAG,IAAI,CAkDzE"}
+{"version":3,"file":"preserveAnimations.d.ts","sourceRoot":"","sources":["../../src/Layer/preserveAnimations.ts"],"names":[],"mappings":"AA0BA;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,IAAI,GAAG,IAAI,CASzE"}