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

package/dist/hooks/menuPressGesture.js

@@ -4,7 +4,7 @@
  * @file menuPressGesture.ts
  * @input A menu press gesture and one pointer event, both as plain data
  * @output The pure `menuPressStep` state machine, its state, event and effect
- *   types, and the settle constant
+ *   types, the settle constant, and the finger's handoff distance
  * @position Pure module under `useMenuPress`. It has no DOM and no React, so
  *   a unit test can check each transition without a browser.
  *
@@ -13,8 +13,28 @@
  * - /packages/core/src/hooks/useMenuPress.ts
  */
 
-/** How long the opening press must last before its release may act. */
+import { MENU_PRESS_HANDOFF_PX as UIKIT_MENU_PRESS_HANDOFF_PX } from "./menuPressValues.js";
+
+/**
+ * How long the opening press must last before its release may act, unless a
+ * finger's handoff applies.
+ */
 export const MENU_PRESS_SETTLE_MS = 300;
+
+/**
+ * How far a finger that opened the menu travels, from the first sample the
+ * menu sees, before it starts picking (UIMenu's scrub handoff).
+ */
+export const MENU_PRESS_HANDOFF_PX = UIKIT_MENU_PRESS_HANDOFF_PX;
+
+/** @internal The machine's own shape, with the finger's handoff; not public contract. */
+
+/** @internal The machine's own shape, with the finger's handoff; not public contract. */
+
+/** @internal The machine's own shape, with the finger's handoff; not public contract. */
+
+/** @internal The machine's own shape, with the finger's handoff; not public contract. */
+
 export const IDLE_MENU_PRESS = {
   phase: 'idle'
 };
@@ -38,6 +58,23 @@ function highlightEffect(row) {
   };
 }
 
+/** A finger or a pen: UIKit's touch rules apply. */
+function isFinger(pointerType) {
+  return pointerType !== 'mouse';
+}
+function hasPosition(event) {
+  return event.x != null && event.y != null;
+}
+
+/**
+ * Whether a finger has travelled the handoff distance from `from`. The
+ * distance is a straight line, as UIMenu measures it: a diagonal 7 pt each
+ * way does not hand off, 9 pt each way does.
+ */
+function hasPassedHandoff(from, to) {
+  return Math.hypot(to.x - from.x, to.y - from.y) >= MENU_PRESS_HANDOFF_PX;
+}
+
 /**
  * Resolve a release while the highlight is tracking the pointer: over an
  * enabled row it acts, over the menu's chrome it acts on nothing, outside the
@@ -73,10 +110,15 @@ function release(pointerType, event) {
  * - `idle`: no gesture is live.
  * - `triggerPress`: a finger rests on the trigger, and the menu is not open
  *   yet. A mouse press on the trigger skips this state and opens at once.
- * - `open`: the menu opened under a held pointer, and the pointer has not
- *   entered it yet.
+ * - `open`: the menu opened under a held pointer, and the pointer does not
+ *   pick yet.
  * - `tracking`: the pointer is held, and the highlight follows it.
  *
+ * A finger or a pen that opened the menu picks only after it travels
+ * `MENU_PRESS_HANDOFF_PX` from the first position the menu sees. UIMenu
+ * hands off the same way. Until then nothing lights, and its lift acts on
+ * nothing. A host that reports no positions keeps the settle rule.
+ *
  * The settle rule: the release of the opening gesture acts only after the
  * pointer entered the menu or the press lasted `MENU_PRESS_SETTLE_MS`. Else a
  * menu that opens under the pointer would pick a row that nobody chose.
@@ -84,8 +126,11 @@ function release(pointerType, event) {
  * Rows are opaque (`T`). The hook feeds in the enabled row under the
  * pointer, or `null` over a divider, a heading, a disabled row, or outside
  * the menu.
+ *
+ * @internal The machine's own shape, with the finger's handoff; not public
+ * contract.
  */
-export function menuPressStep(gesture, event) {
+export function menuPressTransition(gesture, event) {
   switch (gesture.phase) {
     case 'idle':
       return stepIdle(gesture, event);
@@ -176,23 +221,67 @@ function stepTriggerPress(gesture, event) {
 function stepOpen(gesture, event) {
   switch (event.type) {
     case 'move':
-      if (!event.isInMenu) {
+      {
+        if (isFinger(gesture.pointerType) && hasPosition(event)) {
+          // UIMenu counts from the first sample after the open, not from the
+          // open point.
+          const from = gesture.handoffFrom;
+          if (from == null) {
+            return {
+              gesture: {
+                ...gesture,
+                handoffFrom: {
+                  x: event.x,
+                  y: event.y
+                }
+              },
+              effect: NONE
+            };
+          }
+          if (!hasPassedHandoff(from, event)) {
+            return {
+              gesture,
+              effect: NONE
+            };
+          }
+          return {
+            gesture: {
+              phase: 'tracking',
+              pointerType: gesture.pointerType,
+              origin: 'trigger',
+              row: event.row
+            },
+            effect: highlightEffect(event.row)
+          };
+        }
+        if (!event.isInMenu) {
+          return {
+            gesture,
+            effect: NONE
+          };
+        }
         return {
-          gesture,
-          effect: NONE
+          gesture: {
+            phase: 'tracking',
+            pointerType: gesture.pointerType,
+            origin: 'trigger',
+            row: event.row
+          },
+          effect: highlightEffect(event.row)
         };
       }
-      return {
-        gesture: {
-          phase: 'tracking',
-          pointerType: gesture.pointerType,
-          origin: 'trigger',
-          row: event.row
-        },
-        effect: highlightEffect(event.row)
-      };
     case 'up':
       {
+        if (isFinger(gesture.pointerType) && hasPosition(event)) {
+          // The finger never travelled the handoff distance, so the row under it
+          // appeared under a press nobody moved. Nothing acts, the menu stays,
+          // and the trigger's click for this press is spent.
+          return idle({
+            type: 'settle',
+            stray: true,
+            dismiss: false
+          });
+        }
         const hasSettled = event.time - gesture.openedAt >= MENU_PRESS_SETTLE_MS;
         if (!hasSettled) {
           // The pointer never entered the menu and the press was short: the
@@ -208,7 +297,7 @@ function stepOpen(gesture, event) {
       }
     case 'cancel':
       // As above: the gesture ends, so its document listeners come off. The
-      // menu stays open — a cancelled pointer did not ask to close it.
+      // menu stays open: a cancelled pointer did not ask to close it.
       return idle({
         type: 'settle',
         stray: false,
@@ -225,21 +314,19 @@ function stepOpen(gesture, event) {
 function stepTracking(gesture, event) {
   switch (event.type) {
     case 'move':
-      {
-        if (event.row === gesture.row) {
-          return {
-            gesture,
-            effect: NONE
-          };
-        }
+      if (event.row === gesture.row) {
         return {
-          gesture: {
-            ...gesture,
-            row: event.row
-          },
-          effect: highlightEffect(event.row)
+          gesture,
+          effect: NONE
         };
       }
+      return {
+        gesture: {
+          ...gesture,
+          row: event.row
+        },
+        effect: highlightEffect(event.row)
+      };
     case 'up':
       return release(gesture.pointerType, event);
     case 'cancel':
@@ -257,4 +344,42 @@ function stepTracking(gesture, event) {
         effect: NONE
       };
   }
+}
+
+// ---------------------------------------------------------------------------
+// The released public shape (`@astryxdesign/core/hooks`). The handoff
+// positions and `handoffFrom` stay internal: a caller of
+// `menuPressStep` keeps the settle rule, as released.
+// ---------------------------------------------------------------------------
+
+/**
+ * The menu press machine, as released: one step from a gesture and an event
+ * to the next gesture and the effect to apply. Pure.
+ */
+export function menuPressStep(gesture, event) {
+  // The released machine keeps the settle rule. Positions start the handoff,
+  // so a caller's event reaches the transition without them.
+  const {
+    x: _x,
+    y: _y,
+    ...released
+  } = event;
+  const {
+    gesture: next,
+    effect
+  } = menuPressTransition(gesture, released);
+  return {
+    gesture: publicGesture(next),
+    effect
+  };
+}
+function publicGesture(gesture) {
+  if (gesture.phase !== 'open') {
+    return gesture;
+  }
+  return {
+    phase: 'open',
+    pointerType: gesture.pointerType,
+    openedAt: gesture.openedAt
+  };
 }

package/dist/hooks/menuPressValues.d.ts

@@ -0,0 +1,16 @@
+/**
+ * @file menuPressValues.ts
+ * @input None
+ * @output The UIKit value the menu press model reads
+ * @position A copy of one UIKit table entry, motion/uikit gestures.ts
+ *   `UIKIT_MENU_PRESS.handoff`. A menu then bundles this number, not the
+ *   table with its measurement records. The table stays the source and
+ *   documents the measurement. menuPressValues.test.ts fails when the copy
+ *   drifts.
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/motion/uikit/gestures.ts
+ */
+/** How far the opening finger travels after the menu opens before it picks. */
+export declare const MENU_PRESS_HANDOFF_PX = 10;
+//# sourceMappingURL=menuPressValues.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"menuPressValues.d.ts","sourceRoot":"","sources":["../../src/hooks/menuPressValues.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;GAYG;AAEH,+EAA+E;AAC/E,eAAO,MAAM,qBAAqB,KAAK,CAAC"}

package/dist/hooks/menuPressValues.js

@@ -0,0 +1,18 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file menuPressValues.ts
+ * @input None
+ * @output The UIKit value the menu press model reads
+ * @position A copy of one UIKit table entry, motion/uikit gestures.ts
+ *   `UIKIT_MENU_PRESS.handoff`. A menu then bundles this number, not the
+ *   table with its measurement records. The table stays the source and
+ *   documents the measurement. menuPressValues.test.ts fails when the copy
+ *   drifts.
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/motion/uikit/gestures.ts
+ */
+
+/** How far the opening finger travels after the menu opens before it picks. */
+export const MENU_PRESS_HANDOFF_PX = 10;

package/dist/hooks/useClickableContainer.d.ts

@@ -1,16 +1,19 @@
 /**
  * @file useClickableContainer.ts
  * @input Container ref, interactive element ref, click/href handlers
- * @output onClick and onMouseUp handlers for the container; INTERACTIVE_SELECTORS list;
- *   hasInteractiveAncestor and the shared innermostInteractive walk
+ * @output onClick, onMouseUp and onPointerDown handlers for the container;
+ *   INTERACTIVE_SELECTORS list; hasInteractiveAncestor and the shared
+ *   innermostInteractive walk; the internal useClickableContainerProxy, the
+ *   handlers without the marker
  * @position Core hook for clickable containers with nested interactive
  *   elements. A click on a nested button or link does not run the card's
- *   action. Each navigation passes the rule in utils/safeUrl.ts first.
+ *   action, and a finger press there shows no press on the card. Each navigation
+ *   passes the rule in utils/safeUrl.ts first.
  *
  * SYNC: When modified, update:
  * - /packages/core/src/hooks/index.ts (export)
  */
-import { type RefObject, type MouseEvent } from 'react';
+import { type RefObject, type MouseEvent, type PointerEvent } from 'react';
 /**
  * The attribute this hook sets on the container it makes clickable. A click
  * inside a nested marked container belongs to that container (see
@@ -57,6 +60,14 @@ export declare function innermostInteractive(el: Element, rootEl: Element | null
  * belongs to that surface, not the container around its trigger.
  */
 export declare function hasInteractiveAncestor(el: Element, rootEl: Element): boolean;
+/**
+ * The touch half of a container's press rule: a finger press that starts on a nested interactive element
+ * other than the container's own action does not activate the container, so
+ * it ends the press controller's paint on `container`. A mouse or pen press,
+ * and a press on the container's surface or on `ownAction`, are left alone.
+ * Not part of the package's public API.
+ */
+export declare function cancelNestedTouchPress(event: PointerEvent<HTMLElement>, container: HTMLElement | null, ownAction: Element | null): void;
 /**
  * Check if there's a text selection inside the node (don't navigate on text select)
  *
@@ -87,6 +98,14 @@ export interface UseClickableContainerOptions {
 export interface ClickableContainerResult {
     onClick: (event: MouseEvent<HTMLElement>) => void;
     onMouseUp: (event: MouseEvent<HTMLElement>) => void;
+    /**
+     * Spread on the container with `onClick`. A press that starts on a nested
+     * interactive element does not activate the container. On a container that
+     * paints its press with `usePressFeedback`, this drops that touch press.
+     * A mouse `:active` press paint is unchanged. A container without it keeps
+     * its activation rule and shows its pressed state for every press.
+     */
+    onPointerDown: (event: PointerEvent<HTMLElement>) => void;
 }
 /**
  * Hook that makes a container element clickable while preserving
@@ -103,17 +122,27 @@ export interface ClickableContainerResult {
  * @example
  * ```
  * const containerRef = useRef<HTMLDivElement>(null);
- * const { onClick, onMouseUp } = useClickableContainer({
+ * const { onClick, onMouseUp, onPointerDown } = useClickableContainer({
  *   containerRef,
  *   onClick: () => console.log('card clicked'),
  * });
  * return (
- *   <div ref={containerRef} onClick={onClick} onMouseUp={onMouseUp}>
+ *   <div
+ *     ref={containerRef}
+ *     onClick={onClick}
+ *     onMouseUp={onMouseUp}
+ *     onPointerDown={onPointerDown}>
  *     <p>Click anywhere on this card</p>
  *     <button onClick={() => alert('button')}>Nested button</button>
  *   </div>
  * );
  * ```
  */
-export declare function useClickableContainer({ containerRef, interactiveRef, onClick: onClickProp, href, target, disabled, }: UseClickableContainerOptions): ClickableContainerResult;
+export declare function useClickableContainer(options: UseClickableContainerOptions): ClickableContainerResult;
+/**
+ * `useClickableContainer`'s click handlers, without its marker. Internal: Item
+ * serves its delegate and List link rows from one call, and renders the marker
+ * on a delegate row itself.
+ */
+export declare function useClickableContainerProxy({ containerRef, interactiveRef, onClick: onClickProp, href, target, disabled, }: UseClickableContainerOptions): ClickableContainerResult;
 //# sourceMappingURL=useClickableContainer.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"useClickableContainer.d.ts","sourceRoot":"","sources":["../../src/hooks/useClickableContainer.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAyB,KAAK,SAAS,EAAE,KAAK,UAAU,EAAC,MAAM,OAAO,CAAC;AAI9E;;;;GAIG;AACH,eAAO,MAAM,6BAA6B,6BAA6B,CAAC;AAExE;;;;;;;;;;GAUG;AACH,eAAO,MAAM,qBAAqB,QAmBvB,CAAC;AAIZ;;;GAGG;AACH,wBAAgB,2BAA2B,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAKrE;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAClC,EAAE,EAAE,OAAO,EACX,MAAM,EAAE,OAAO,GAAG,IAAI,EACtB,aAAa,GAAE,CAAC,OAAO,EAAE,OAAO,KAAK,OAAqC,GACzE,OAAO,GAAG,IAAI,CAShB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,sBAAsB,CAAC,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,GAAG,OAAO,CAE5E;AASD;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CASvD;AAED,MAAM,WAAW,4BAA4B;IAC3C,yCAAyC;IACzC,YAAY,EAAE,SAAS,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;IAC5C,mEAAmE;IACnE,cAAc,CAAC,EAAE,SAAS,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;IAC/C,oBAAoB;IACpB,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,UAAU,CAAC,WAAW,CAAC,KAAK,IAAI,CAAC;IACnD;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,kBAAkB;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,wCAAwC;IACxC,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,wBAAwB;IACvC,OAAO,EAAE,CAAC,KAAK,EAAE,UAAU,CAAC,WAAW,CAAC,KAAK,IAAI,CAAC;IAClD,SAAS,EAAE,CAAC,KAAK,EAAE,UAAU,CAAC,WAAW,CAAC,KAAK,IAAI,CAAC;CACrD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,qBAAqB,CAAC,EACpC,YAAY,EACZ,cAAc,EACd,OAAO,EAAE,WAAW,EACpB,IAAI,EACJ,MAAM,EACN,QAAgB,GACjB,EAAE,4BAA4B,GAAG,wBAAwB,CA+GzD"}
+{"version":3,"file":"useClickableContainer.d.ts","sourceRoot":"","sources":["../../src/hooks/useClickableContainer.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAGL,KAAK,SAAS,EACd,KAAK,UAAU,EACf,KAAK,YAAY,EAClB,MAAM,OAAO,CAAC;AAKf;;;;GAIG;AACH,eAAO,MAAM,6BAA6B,6BAA6B,CAAC;AAExE;;;;;;;;;;GAUG;AACH,eAAO,MAAM,qBAAqB,QAmBvB,CAAC;AAIZ;;;GAGG;AACH,wBAAgB,2BAA2B,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAKrE;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAClC,EAAE,EAAE,OAAO,EACX,MAAM,EAAE,OAAO,GAAG,IAAI,EACtB,aAAa,GAAE,CAAC,OAAO,EAAE,OAAO,KAAK,OAAqC,GACzE,OAAO,GAAG,IAAI,CAShB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,sBAAsB,CAAC,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,GAAG,OAAO,CAE5E;AASD;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,YAAY,CAAC,WAAW,CAAC,EAChC,SAAS,EAAE,WAAW,GAAG,IAAI,EAC7B,SAAS,EAAE,OAAO,GAAG,IAAI,GACxB,IAAI,CAeN;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CASvD;AAED,MAAM,WAAW,4BAA4B;IAC3C,yCAAyC;IACzC,YAAY,EAAE,SAAS,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;IAC5C,mEAAmE;IACnE,cAAc,CAAC,EAAE,SAAS,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;IAC/C,oBAAoB;IACpB,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,UAAU,CAAC,WAAW,CAAC,KAAK,IAAI,CAAC;IACnD;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,kBAAkB;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,wCAAwC;IACxC,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,wBAAwB;IACvC,OAAO,EAAE,CAAC,KAAK,EAAE,UAAU,CAAC,WAAW,CAAC,KAAK,IAAI,CAAC;IAClD,SAAS,EAAE,CAAC,KAAK,EAAE,UAAU,CAAC,WAAW,CAAC,KAAK,IAAI,CAAC;IACpD;;;;;;OAMG;IACH,aAAa,EAAE,CAAC,KAAK,EAAE,YAAY,CAAC,WAAW,CAAC,KAAK,IAAI,CAAC;CAC3D;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,4BAA4B,GACpC,wBAAwB,CAU1B;AAED;;;;GAIG;AACH,wBAAgB,0BAA0B,CAAC,EACzC,YAAY,EACZ,cAAc,EACd,OAAO,EAAE,WAAW,EACpB,IAAI,EACJ,MAAM,EACN,QAAgB,GACjB,EAAE,4BAA4B,GAAG,wBAAwB,CAwHzD"}

package/dist/hooks/useClickableContainer.js

@@ -5,11 +5,14 @@
 /**
  * @file useClickableContainer.ts
  * @input Container ref, interactive element ref, click/href handlers
- * @output onClick and onMouseUp handlers for the container; INTERACTIVE_SELECTORS list;
- *   hasInteractiveAncestor and the shared innermostInteractive walk
+ * @output onClick, onMouseUp and onPointerDown handlers for the container;
+ *   INTERACTIVE_SELECTORS list; hasInteractiveAncestor and the shared
+ *   innermostInteractive walk; the internal useClickableContainerProxy, the
+ *   handlers without the marker
  * @position Core hook for clickable containers with nested interactive
  *   elements. A click on a nested button or link does not run the card's
- *   action. Each navigation passes the rule in utils/safeUrl.ts first.
+ *   action, and a finger press there shows no press on the card. Each navigation
+ *   passes the rule in utils/safeUrl.ts first.
  *
  * SYNC: When modified, update:
  * - /packages/core/src/hooks/index.ts (export)
@@ -17,6 +20,7 @@
 import { useCallback, useEffect } from 'react';
 import { isLayerSurface } from "../Layer/layerSurfacePress.js";
 import { isSafeUrl } from "../utils/safeUrl.js";
+import { cancelPress } from "../utils/pressFeedback.js";
 
 /**
  * The attribute this hook sets on the container it makes clickable. A click
@@ -90,6 +94,24 @@ function belongsToSomethingElse(element) {
   return matchesInteractiveSelectors(element) || isLayerSurface(element);
 }
 
+/**
+ * The touch half of a container's press rule: a finger press that starts on a nested interactive element
+ * other than the container's own action does not activate the container, so
+ * it ends the press controller's paint on `container`. A mouse or pen press,
+ * and a press on the container's surface or on `ownAction`, are left alone.
+ * Not part of the package's public API.
+ */
+export function cancelNestedTouchPress(event, container, ownAction) {
+  const target = event.target;
+  if (event.pointerType !== 'touch' || container == null || !(target instanceof Element) || target === event.currentTarget || !hasInteractiveAncestor(target, container) ||
+  // The container's own action, such as the control it delegates to: a
+  // press on it activates the container.
+  ownAction?.contains(target) === true) {
+    return;
+  }
+  cancelPress(container);
+}
+
 /**
  * Check if there's a text selection inside the node (don't navigate on text select)
  *
@@ -123,26 +145,26 @@ export function hasTextSelection(node) {
  * @example
  * ```
  * const containerRef = useRef<HTMLDivElement>(null);
- * const { onClick, onMouseUp } = useClickableContainer({
+ * const { onClick, onMouseUp, onPointerDown } = useClickableContainer({
  *   containerRef,
  *   onClick: () => console.log('card clicked'),
  * });
  * return (
- *   <div ref={containerRef} onClick={onClick} onMouseUp={onMouseUp}>
+ *   <div
+ *     ref={containerRef}
+ *     onClick={onClick}
+ *     onMouseUp={onMouseUp}
+ *     onPointerDown={onPointerDown}>
  *     <p>Click anywhere on this card</p>
  *     <button onClick={() => alert('button')}>Nested button</button>
  *   </div>
  * );
  * ```
  */
-export function useClickableContainer({
-  containerRef,
-  interactiveRef,
-  onClick: onClickProp,
-  href,
-  target,
-  disabled = false
-}) {
+export function useClickableContainer(options) {
+  const {
+    containerRef
+  } = options;
   // Mark container as pressable for the interactive selector check
   useEffect(() => {
     const el = containerRef.current;
@@ -150,6 +172,22 @@ export function useClickableContainer({
       el.setAttribute(PRESSABLE_CONTAINER_ATTRIBUTE, 'true');
     }
   }, [containerRef]);
+  return useClickableContainerProxy(options);
+}
+
+/**
+ * `useClickableContainer`'s click handlers, without its marker. Internal: Item
+ * serves its delegate and List link rows from one call, and renders the marker
+ * on a delegate row itself.
+ */
+export function useClickableContainerProxy({
+  containerRef,
+  interactiveRef,
+  onClick: onClickProp,
+  href,
+  target,
+  disabled = false
+}) {
   const onClick = useCallback(event => {
     if (disabled) {
       return;
@@ -226,8 +264,19 @@ export function useClickableContainer({
       window.open(href, '_blank', 'noopener');
     }
   }, [containerRef, href, disabled]);
+
+  // The press-state counterpart of onClick's rule, for touch: a finger press
+  // that would not activate the container shows no press on it. A mouse or
+  // pen press keeps its `:active` paint.
+  const onPointerDown = useCallback(event => {
+    if (disabled) {
+      return;
+    }
+    cancelNestedTouchPress(event, containerRef.current, interactiveRef?.current ?? null);
+  }, [containerRef, interactiveRef, disabled]);
   return {
     onClick,
-    onMouseUp
+    onMouseUp,
+    onPointerDown
   };
 }

package/dist/hooks/useFocusTrap.d.ts

@@ -24,6 +24,16 @@ export declare function useFocusTrapEscapeCompatibilitySignal(isActive: boolean)
  * the trap does. Not re-exported from the package's `hooks` entry.
  */
 export declare function getFocusableElements(container: HTMLElement): HTMLElement[];
+/**
+ * Tab containment for a focus region: Tab and Shift+Tab pressed inside wrap at
+ * either end, and a Tab that starts outside is left to the page. When regions
+ * nest, the innermost one holding focus answers.
+ *
+ * `useFocusTrap` composes this. Dialog, BottomSheet and Lightbox call it
+ * directly, because their native lifecycle already owns focus entry and
+ * return. Internal: not re-exported from `hooks`.
+ */
+export declare function useFocusRegionContainment(containerRef: React.RefObject<HTMLElement | null>, isActive: boolean): void;
 /**
  * Configuration for focus trap behavior
  */

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

@@ -1 +1 @@
-{"version":3,"file":"useFocusTrap.d.ts","sourceRoot":"","sources":["../../src/hooks/useFocusTrap.ts"],"names":[],"mappings":"AA+BA;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,IAAI,OAAO,CAElD;AAED;;;;;;GAMG;AACH,wBAAgB,qCAAqC,CAAC,QAAQ,EAAE,OAAO,GAAG,IAAI,CAY7E;AA+BD;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,WAAW,GAAG,WAAW,EAAE,CAI1E;AA8DD;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC;;OAEG;IACH,QAAQ,EAAE,OAAO,CAAC;IAElB;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,IAAI,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB,CAAC,CAAC,SAAS,WAAW,GAAG,WAAW;IACrE;;OAEG;IACH,YAAY,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IAExC;;OAEG;IACH,UAAU,EAAE,MAAM,IAAI,CAAC;CACxB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,WAAW,GAAG,WAAW,EAC9D,OAAO,EAAE,mBAAmB,GAC3B,kBAAkB,CAAC,CAAC,CAAC,CAEvB;AAED;;GAEG;AACH,UAAU,wBAAyB,SAAQ,mBAAmB;IAC5D;;;;;;OAMG;IACH,gBAAgB,CAAC,EAAE,MAAM,WAAW,GAAG,IAAI,CAAC;CAC7C;AAED,wBAAgB,oBAAoB,CAAC,CAAC,SAAS,WAAW,GAAG,WAAW,EACtE,OAAO,EAAE,wBAAwB,GAChC,kBAAkB,CAAC,CAAC,CAAC,CA2QvB"}
+{"version":3,"file":"useFocusTrap.d.ts","sourceRoot":"","sources":["../../src/hooks/useFocusTrap.ts"],"names":[],"mappings":"AAgCA;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,IAAI,OAAO,CAElD;AAED;;;;;;GAMG;AACH,wBAAgB,qCAAqC,CAAC,QAAQ,EAAE,OAAO,GAAG,IAAI,CAY7E;AAwDD;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,WAAW,GAAG,WAAW,EAAE,CAI1E;AA8GD;;;;;;;;GAQG;AACH,wBAAgB,yBAAyB,CACvC,YAAY,EAAE,KAAK,CAAC,SAAS,CAAC,WAAW,GAAG,IAAI,CAAC,EACjD,QAAQ,EAAE,OAAO,GAChB,IAAI,CAgLN;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC;;OAEG;IACH,QAAQ,EAAE,OAAO,CAAC;IAElB;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,IAAI,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB,CAAC,CAAC,SAAS,WAAW,GAAG,WAAW;IACrE;;OAEG;IACH,YAAY,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IAExC;;OAEG;IACH,UAAU,EAAE,MAAM,IAAI,CAAC;CACxB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,WAAW,GAAG,WAAW,EAC9D,OAAO,EAAE,mBAAmB,GAC3B,kBAAkB,CAAC,CAAC,CAAC,CAEvB;AAED;;GAEG;AACH,UAAU,wBAAyB,SAAQ,mBAAmB;IAC5D;;;;;;OAMG;IACH,gBAAgB,CAAC,EAAE,MAAM,WAAW,GAAG,IAAI,CAAC;CAC7C;AAED,wBAAgB,oBAAoB,CAAC,CAAC,SAAS,WAAW,GAAG,WAAW,EACtE,OAAO,EAAE,wBAAwB,GAChC,kBAAkB,CAAC,CAAC,CAAC,CAwHvB"}