@astryxdesign/core 0.7.7 → 0.7.8-canary.0588a13

package/dist/hooks/rootScrollStyles.js

@@ -0,0 +1,207 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file rootScrollStyles.ts
+ * @input The inline styles of the root and `<body>`
+ * @output claimRootScrollStyle, which owns the page's `overflow`,
+ *   `overscroll-behavior-y` and `scrollbar-gutter`; isScrollLockActive and
+ *   subscribeScrollLock, which report whether a scroll lock holds the page
+ * @position Internal hook utility. Each caller that changes how the page
+ *   scrolls claims these styles here, so no caller overwrites a value that
+ *   another caller still needs.
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/hooks/useScrollLock.ts
+ */
+
+/** The root scroll styles a caller can hold. */
+const PROPERTIES = ['overflow', 'overscrollBehaviorY', 'scrollbarGutter'];
+const claims = {
+  overflow: [],
+  overscrollBehaviorY: [],
+  scrollbarGutter: []
+};
+/**
+ * The inline styles saved for each property, so a page's own value comes back
+ * exactly, including a one-axis `overflow-x` or `overflow-y`.
+ */
+const SAVED = {
+  overflow: ['overflow', 'overflowX', 'overflowY'],
+  overscrollBehaviorY: ['overscrollBehaviorY'],
+  scrollbarGutter: ['scrollbarGutter']
+};
+
+/**
+ * An element that holds a property's claims. It keeps the page's own inline
+ * values, saved at the first claim, and the value that the claims last wrote.
+ */
+
+const held = new Map();
+let nextClaimId = 0;
+
+/**
+ * The element whose `overflow` the viewport uses. That is the root, unless the
+ * root's own is `visible` and `<body>` sets one, which then propagates to the
+ * viewport. A write to the root in that case stops the propagation. Then
+ * `<body>` becomes its own scroller at offset 0, and the page jumps to its top.
+ */
+function overflowTarget(doc) {
+  const root = doc.documentElement;
+  const {
+    body
+  } = doc;
+  const view = doc.defaultView;
+  if (body == null || view == null) {
+    return root;
+  }
+  const isVisible = element => {
+    const style = view.getComputedStyle(element);
+    return (style.overflowX || 'visible') === 'visible' && (style.overflowY || 'visible') === 'visible';
+  };
+  return isVisible(root) && !isVisible(body) ? body : root;
+}
+
+/**
+ * Where a property's claims go. `overflow` goes to the element that the
+ * viewport takes it from. `overscroll-behavior-y` goes to the root and to
+ * `<body>`, because Chrome on Android reads `<body>`'s value for its
+ * pull-to-refresh. `scrollbar-gutter` goes to the root.
+ */
+function claimTargets(property, doc) {
+  if (property === 'overflow') {
+    return [overflowTarget(doc)];
+  }
+  if (property === 'scrollbarGutter') {
+    return [doc.documentElement];
+  }
+  return doc.body == null ? [doc.documentElement] : [doc.documentElement, doc.body];
+}
+function applyTopClaim(property) {
+  const targets = held.get(property);
+  if (targets == null) {
+    return;
+  }
+  const stack = claims[property];
+  const top = stack[stack.length - 1];
+  for (const target of targets) {
+    const {
+      style
+    } = target.element;
+    if (top != null) {
+      style[property] = top.value;
+      target.written = top.value;
+      continue;
+    }
+    // The last claim is gone, so the page gets its own values back. A value
+    // that an outside writer set meanwhile stays.
+    if (style[property] === target.written) {
+      style[property] = '';
+      for (const name of SAVED[property]) {
+        const value = target.pageValues[name];
+        if (value) {
+          style[name] = value;
+        }
+      }
+    }
+  }
+  if (top == null) {
+    held.delete(property);
+  }
+}
+
+/**
+ * Sets the page's `overflow`, `overscroll-behavior-y` or `scrollbar-gutter`
+ * until the returned release runs. Claims stack per property: the latest claim
+ * wins, and a release in any order restores the claim beneath it. The page's
+ * own inline value comes back after the last release, unless an outside writer
+ * changed that style meanwhile. A second release does nothing.
+ *
+ * @example
+ * ```
+ * const release = claimRootScrollStyle({overflow: 'hidden'});
+ * // later
+ * release();
+ * ```
+ */
+export function claimRootScrollStyle(claim) {
+  if (typeof document === 'undefined') {
+    return () => {};
+  }
+  nextClaimId += 1;
+  const id = nextClaimId;
+  const claimed = [];
+  for (const property of PROPERTIES) {
+    const value = claim[property];
+    if (value == null) {
+      continue;
+    }
+    if (claims[property].length === 0) {
+      held.set(property, claimTargets(property, document).map(element => {
+        const pageValues = {};
+        for (const name of SAVED[property]) {
+          pageValues[name] = element.style[name];
+        }
+        return {
+          element,
+          pageValues,
+          written: ''
+        };
+      }));
+    }
+    claims[property].push({
+      id,
+      value
+    });
+    claimed.push(property);
+    applyTopClaim(property);
+  }
+  let released = false;
+  return () => {
+    if (released) {
+      return;
+    }
+    released = true;
+    for (const property of claimed) {
+      const stack = claims[property];
+      const index = stack.findIndex(entry => entry.id === id);
+      if (index !== -1) {
+        stack.splice(index, 1);
+      }
+      applyTopClaim(property);
+    }
+  };
+}
+let lockCount = 0;
+const lockListeners = new Set();
+
+/** Whether a scroll lock (useScrollLock) currently holds the page. */
+export function isScrollLockActive() {
+  return lockCount > 0;
+}
+
+/**
+ * Calls `listener` with the new state each time the page becomes locked or
+ * free. A second lock while one holds is no change. Returns the unsubscribe
+ * function.
+ */
+export function subscribeScrollLock(listener) {
+  lockListeners.add(listener);
+  return () => {
+    lockListeners.delete(listener);
+  };
+}
+
+/** For scroll locks: one lock taken (`1`) or released (`-1`). */
+export function reportScrollLock(delta) {
+  const wasActive = lockCount > 0;
+  lockCount = Math.max(0, lockCount + delta);
+  const isActive = lockCount > 0;
+  if (isActive === wasActive) {
+    return;
+  }
+  for (const listener of [...lockListeners]) {
+    listener(isActive);
+  }
+}

package/dist/hooks/scrollLockTouchGuard.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Whether the page is pinch-zoomed in (`visualViewport.scale > 1`). A
+ * one-finger drag then pans the zoomed view, which a zoomed-in reader needs
+ * around an open overlay. The value is read per touch, so a pinch during the
+ * lock counts from the next drag.
+ */
+export declare function isPageZoomedIn(doc: Document): boolean;
+/**
+ * Whether a scroller in the scroll chain of `target` takes a pan of (`dx`,
+ * `dy`) before the page does.
+ */
+export declare function isPanAbsorbedBeforePage(target: EventTarget | null, dx: number, dy: number): boolean;
+//# sourceMappingURL=scrollLockTouchGuard.d.ts.map

package/dist/hooks/scrollLockTouchGuard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scrollLockTouchGuard.d.ts","sourceRoot":"","sources":["../../src/hooks/scrollLockTouchGuard.ts"],"names":[],"mappings":"AAoFA;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,QAAQ,GAAG,OAAO,CAErD;AAWD;;;GAGG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,WAAW,GAAG,IAAI,EAC1B,EAAE,EAAE,MAAM,EACV,EAAE,EAAE,MAAM,GACT,OAAO,CAqCT"}

package/dist/hooks/scrollLockTouchGuard.js

@@ -0,0 +1,117 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file scrollLockTouchGuard.ts
+ * @input The node under a finger and the pan's direction, while a scroll lock
+ *   holds the page; the native-scroll probe's edge test (gestures/nativeScroll)
+ * @output isPanAbsorbedBeforePage and isPageZoomedIn, for the page hold
+ * @position Internal hook utility; gestures/pageHold calls it for
+ *   useScrollLock.
+ */
+
+// iOS Safari scrolls an `overflow: hidden` page under a finger.
+// The page hold cancels each pan that would reach the page. This walk decides
+// which pans those are. A scroller that can move in the pan's direction takes
+// the pan. A scroller at its edge that contains its overscroll also takes it.
+// The walk follows flat-tree parents. It ends at a top-layer or fixed-position
+// element, whose containing block is the viewport, so its untaken pans go to
+// the page.
+import { canElementScroll } from "../gestures/nativeScroll.js";
+import { parentAcrossShadow } from "../utils/flatTree.js";
+
+/**
+ * Whether `element` itself takes a pan. It does when it can still scroll that
+ * way, or when its `overscroll-behavior` contains the overscroll at its edge.
+ */
+function takesPan(element, style, isVertical, dx, dy) {
+  const x = isVertical ? 0 : dx;
+  const y = isVertical ? dy : 0;
+  if (canElementScroll(element, x, y)) {
+    return true;
+  }
+  // A scroller at its edge can still move the other way. A box that does not
+  // scroll, or whose content fits, cannot. Its pan goes on along the chain.
+  if (!canElementScroll(element, -x, -y)) {
+    return false;
+  }
+  const behavior = isVertical ? style.overscrollBehaviorY : style.overscrollBehaviorX;
+  return behavior === 'contain' || behavior === 'none';
+}
+
+/**
+ * Whether `element` is in the state that a pseudo-class names (`:modal`,
+ * `:popover-open`). An engine without the pseudo-class has no element in that
+ * state. Its `matches` throws on the selector, so the engine is not asked.
+ * Other errors surface.
+ */
+function isInState(element, pseudoClass) {
+  const css = element.ownerDocument.defaultView?.CSS;
+  return typeof css?.supports === 'function' && css.supports(`selector(${pseudoClass})`) && element.matches(pseudoClass);
+}
+
+/**
+ * Whether a pan that `element` does not take goes to the viewport, not to its
+ * DOM parent. The browser chains scrolling along containing blocks. A
+ * top-layer element (an open modal dialog or popover) or a fixed-position one
+ * has the viewport as its containing block. So a Dialog inside a scrolling
+ * container gives an untaken pan to the page.
+ */
+function chainsToViewport(element, style) {
+  return style.position === 'fixed' || isInState(element, ':modal') || isInState(element, ':popover-open');
+}
+
+/**
+ * Whether the page is pinch-zoomed in (`visualViewport.scale > 1`). A
+ * one-finger drag then pans the zoomed view, which a zoomed-in reader needs
+ * around an open overlay. The value is read per touch, so a pinch during the
+ * lock counts from the next drag.
+ */
+export function isPageZoomedIn(doc) {
+  return (doc.defaultView?.visualViewport?.scale ?? 1) > 1;
+}
+
+/**
+ * Whether `element` is a native control that takes a finger's drag itself. A
+ * range input moves its thumb, so the drag never reaches the page.
+ */
+function takesDragItself(element) {
+  // `:disabled` also covers a slider inside a disabled fieldset.
+  return element.matches('input[type="range"]:not(:disabled)');
+}
+
+/**
+ * Whether a scroller in the scroll chain of `target` takes a pan of (`dx`,
+ * `dy`) before the page does.
+ */
+export function isPanAbsorbedBeforePage(target, dx, dy) {
+  if (!(target instanceof Node)) {
+    return false;
+  }
+  const doc = target.ownerDocument ?? document;
+  const view = doc.defaultView;
+  if (view == null) {
+    return false;
+  }
+  const isVertical = Math.abs(dy) >= Math.abs(dx);
+  for (let node = target; node != null; node = parentAcrossShadow(node)) {
+    if (!(node instanceof Element)) {
+      continue;
+    }
+    if (takesDragItself(node)) {
+      return true;
+    }
+    if (node === doc.documentElement || node === doc.body || node === doc.scrollingElement) {
+      break;
+    }
+    const style = view.getComputedStyle(node);
+    if (takesPan(node, style, isVertical, dx, dy)) {
+      return true;
+    }
+    if (chainsToViewport(node, style)) {
+      break;
+    }
+  }
+  return false;
+}

package/dist/hooks/scrollbarGutter.d.ts

@@ -1,7 +1,7 @@
 export interface ScrollbarGutterHold {
     /**
-     * Call once the lock's own styles are applied: measures whether the element
-     * grew anyway and, only then, pads the difference away.
+     * Call once the lock's own styles apply. It holds the gutter open, or,
+     * without `scrollbar-gutter`, pads away only the width the element gained.
      */
     settle(): void;
     /** Call on unlock: restores everything this hold changed. */
@@ -16,8 +16,8 @@ export interface ScrollbarGutterHold {
  * ScrollbarGutterHold.release} on unlock:
  *
  * ```
- * const hold = holdScrollbarGutter(document.body);
- * body.style.position = 'fixed';
+ * const hold = holdScrollbarGutter(document.documentElement);
+ * document.documentElement.style.overflow = 'hidden';
  * hold.settle();
  * ```
  *

package/dist/hooks/scrollbarGutter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scrollbarGutter.d.ts","sourceRoot":"","sources":["../../src/hooks/scrollbarGutter.ts"],"names":[],"mappings":"AAuBA,MAAM,WAAW,mBAAmB;IAClC;;;OAGG;IACH,MAAM,IAAI,IAAI,CAAC;IACf,6DAA6D;IAC7D,OAAO,IAAI,IAAI,CAAC;CACjB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,WAAW,GAAG,mBAAmB,CA+D7E"}
+{"version":3,"file":"scrollbarGutter.d.ts","sourceRoot":"","sources":["../../src/hooks/scrollbarGutter.ts"],"names":[],"mappings":"AA0BA,MAAM,WAAW,mBAAmB;IAClC;;;OAGG;IACH,MAAM,IAAI,IAAI,CAAC;IACf,6DAA6D;IAC7D,OAAO,IAAI,IAAI,CAAC;CACjB;AAWD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,WAAW,GAAG,mBAAmB,CAkE7E"}

package/dist/hooks/scrollbarGutter.js

@@ -2,7 +2,8 @@
 
 /**
  * @file scrollbarGutter.ts
- * @input The element a scroll lock pins, plus live layout measurements
+ * @input The element whose width a scroll lock holds, plus live layout
+ *   measurements
  * @output holdScrollbarGutter and the ScrollbarGutterHold it returns
  * @position Internal hook utility; used by useScrollLock and MobileNav so that
  *   locking background scroll does not resize the layout viewport.
@@ -16,10 +17,16 @@
 // engines without `scrollbar-gutter`, and it applies only when a measurement
 // shows that the element moved.
 
+import { claimRootScrollStyle } from "./rootScrollStyles.js";
 const NOOP = {
   settle() {},
   release() {}
 };
+/** Whether the engine reserves a gutter for `scrollbar-gutter: stable`. */
+function supportsScrollbarGutter() {
+  return typeof CSS !== 'undefined' && typeof CSS.supports === 'function' && CSS.supports('scrollbar-gutter', 'stable');
+}
+
 /**
  * Keeps `element`'s content box the width it is right now, across a scroll
  * lock that is about to hide the document's scrollbar.
@@ -29,8 +36,8 @@ const NOOP = {
  * ScrollbarGutterHold.release} on unlock:
  *
  * ```
- * const hold = holdScrollbarGutter(document.body);
- * body.style.position = 'fixed';
+ * const hold = holdScrollbarGutter(document.documentElement);
+ * document.documentElement.style.overflow = 'hidden';
  * hold.settle();
  * ```
  *
@@ -44,25 +51,37 @@ export function holdScrollbarGutter(element) {
   const root = document.documentElement;
   const viewportWidth = root.clientWidth;
 
-  // 0 means "no layout to measure" (jsdom, and any non-visual environment),
-  // not "the scrollbar is as wide as the window".
-  if (viewportWidth === 0) {
+  // 0 means that there is no layout to measure, as in jsdom. An overlay
+  // scrollbar takes no space, so there is nothing to hold. A gutter held open
+  // on such a page would add space that was never there.
+  if (viewportWidth === 0 || window.innerWidth <= viewportWidth) {
     return NOOP;
   }
-  const previousGutter = root.style.scrollbarGutter;
+  if (supportsScrollbarGutter()) {
+    // The gutter holds the width by construction, so the lock forces no second
+    // layout. Each hold is a stacked claim, so one release keeps the gutter
+    // that another hold still needs.
+    let releaseGutter = null;
+    return {
+      settle() {
+        releaseGutter ??= claimRootScrollStyle({
+          scrollbarGutter: 'stable'
+        });
+      },
+      release() {
+        releaseGutter?.();
+        releaseGutter = null;
+      }
+    };
+  }
+
+  // An engine without `scrollbar-gutter`: measure the element now, again
+  // once the lock's styles apply, and pad away what it grew. This is the one
+  // path that reads layout after a write.
   const previousPadding = element.style.paddingRight;
   const widthBefore = element.getBoundingClientRect().width;
-  let heldGutter = false;
   let padded = false;
   let settled = false;
-
-  // Only when a space-taking scrollbar is actually there. Holding the gutter
-  // open on a page that never had one would carve out 15px that was never
-  // reserved — the same shift, in the other direction.
-  if (window.innerWidth > viewportWidth) {
-    root.style.scrollbarGutter = 'stable';
-    heldGutter = true;
-  }
   return {
     settle() {
       if (settled) {
@@ -71,9 +90,7 @@ export function holdScrollbarGutter(element) {
       settled = true;
 
       // What the lock actually did to this element, rather than what we
-      // assumed it would do. 0 on any engine where the gutter held — and on a
-      // page that already sets `scrollbar-gutter: stable` itself, where the
-      // scrollbar was never taking the space back.
+      // assumed it would do.
       const grew = element.getBoundingClientRect().width - widthBefore;
       if (grew <= 0) {
         return;
@@ -87,10 +104,6 @@ export function holdScrollbarGutter(element) {
         element.style.paddingRight = previousPadding;
         padded = false;
       }
-      if (heldGutter) {
-        root.style.scrollbarGutter = previousGutter;
-        heldGutter = false;
-      }
     }
   };
 }

package/dist/hooks/useActionGroupTracking.d.ts

@@ -0,0 +1,53 @@
+/**
+ * @file useActionGroupTracking.ts
+ * @input A ref to a group of sibling actions, the actions' selector, and the
+ *   component's tracking constants
+ * @output Exports useActionGroupTracking and ActionGroupTrackingOptions
+ * @position Internal hook, not exported from the hooks entry. A long press
+ *   drives the shared action-group tracker (hooks/actionGroupTracker.ts) for
+ *   a group that a held pointer slides across. AlertDialog consumes it.
+ *
+ * SYNC: When modified, update useActionGroupTracking.test.tsx
+ */
+import { type RefObject } from 'react';
+import { LongPressGestureRecognizer } from '../gestures/LongPressGestureRecognizer.js';
+import type { GestureTouch, PointerKind } from '../gestures/types.js';
+export interface ActionGroupTrackingOptions {
+    /** Selects the actions inside the tracked element. */
+    itemSelector: string;
+    /** How long after touch-down the touched action highlights, ms. */
+    highlightOnsetMs: number;
+    /**
+     * How far outside an action a finger keeps it highlighted, px. A mouse or a
+     * pen hit-tests the actions' exact rects.
+     */
+    highlightExpansion: number;
+    /** Pointers that are tracked; others keep the browser's click. @default every pointer */
+    pointerTypes?: ReadonlyArray<PointerKind>;
+    /** A press whose target this rejects is not tracked. */
+    shouldTrack?: (target: unknown) => boolean;
+    /** Off, nothing is attached and nothing is tracked. @default true */
+    isEnabled?: boolean;
+    /**
+     * Let the gesture host write the group's `touch-action` and refuse a text
+     * selection while a finger or a pen holds it.
+     * @default true
+     */
+    manageStyle?: boolean;
+    /** Runs the action under the finger at the lift. @default its own click */
+    onActivate?: (item: HTMLElement) => void;
+}
+/**
+ * The group's press: a long press that a second finger on the group ends with
+ * nothing acting. A plain long press ignores a second finger.
+ */
+declare class ActionGroupPress extends LongPressGestureRecognizer {
+    protected acceptsTouch(touch: GestureTouch): boolean;
+}
+/**
+ * Track a held pointer on the group behind `ref` across the actions inside
+ * it, through the shared action-group tracker.
+ */
+export declare function useActionGroupTracking(ref: RefObject<HTMLElement | null>, options: ActionGroupTrackingOptions): ActionGroupPress;
+export {};
+//# sourceMappingURL=useActionGroupTracking.d.ts.map

package/dist/hooks/useActionGroupTracking.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useActionGroupTracking.d.ts","sourceRoot":"","sources":["../../src/hooks/useActionGroupTracking.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;GAUG;AAEH,OAAO,EAA8B,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AAElE,OAAO,EAAC,0BAA0B,EAAC,MAAM,wCAAwC,CAAC;AAElF,OAAO,KAAK,EAAC,YAAY,EAAE,WAAW,EAAC,MAAM,mBAAmB,CAAC;AAOjE,MAAM,WAAW,0BAA0B;IACzC,sDAAsD;IACtD,YAAY,EAAE,MAAM,CAAC;IACrB,mEAAmE;IACnE,gBAAgB,EAAE,MAAM,CAAC;IACzB;;;OAGG;IACH,kBAAkB,EAAE,MAAM,CAAC;IAC3B,yFAAyF;IACzF,YAAY,CAAC,EAAE,aAAa,CAAC,WAAW,CAAC,CAAC;IAC1C,wDAAwD;IACxD,WAAW,CAAC,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,OAAO,CAAC;IAC3C,qEAAqE;IACrE,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB;;;;OAIG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,2EAA2E;IAC3E,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,WAAW,KAAK,IAAI,CAAC;CAC1C;AASD;;;GAGG;AACH,cAAM,gBAAiB,SAAQ,0BAA0B;cACpC,YAAY,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO;CAO9D;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CACpC,GAAG,EAAE,SAAS,CAAC,WAAW,GAAG,IAAI,CAAC,EAClC,OAAO,EAAE,0BAA0B,GAClC,gBAAgB,CAoHlB"}