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

package/src/AlertDialog/AlertDialog.tsx

@@ -4,7 +4,9 @@
 
 /**
  * @file AlertDialog.tsx
- * @input Uses React, StyleX, Dialog, Layout, Heading, Text, Button
+ * @input Uses React, StyleX, Dialog, Layout, Heading, Text, Button, the
+ *   action-group tracking (hooks/useActionGroupTracking) and the press-group
+ *   marker (privateAttributes/pressGroupItem.stylex)
  * @output Exports AlertDialog component, AlertDialogProps type
  * @position Core implementation; consumed by index.ts, tested by AlertDialog.test.tsx
  *
@@ -12,11 +14,12 @@
  * - /packages/core/src/AlertDialog/AlertDialog.doc.mjs (props table, features, examples)
  * - /packages/core/src/AlertDialog/AlertDialog.test.tsx (tests for new/changed behavior)
  * - /packages/core/src/AlertDialog/index.ts (exports if types change)
+ * - /packages/core/src/AlertDialog/__tests__/AlertDialog.interaction.browser.spec.ts (touch tracking)
  * - /apps/storybook/stories/AlertDialog.stories.tsx (storybook stories)
  * - /packages/cli/assets/templates/blocks/components/AlertDialog/ (showcase blocks)
  */
 
-import React, {useId, useCallback} from 'react';
+import React, {useId, useCallback, useRef} from 'react';
 import * as stylex from '@stylexjs/stylex';
 import {Dialog} from '../Dialog/Dialog';
 import {Layout} from '../Layout/Layout';
@@ -31,17 +34,31 @@ import type {BaseProps} from '../BaseProps';
 import {mergeProps} from '../utils/mergeProps';
 import {themeProps} from '../utils/themeProps';
 import {useMediaQuery} from '../hooks/useMediaQuery';
+import {useTouchPresentation} from '../utils/touchPresentation';
 import {
   registerEnglishFallback,
   useComponentTranslator,
 } from '../i18n/useComponentTranslator';
 import english from '../i18n/generated-english/AlertDialog/AlertDialog.generated';
+import {useActionGroupTracking} from '../hooks/useActionGroupTracking';
+import {PressGroupContext} from '../hooks/pressGroupContext';
+import {alertController} from '../motion/uikit/alert';
+import {pressGroupItemProps} from '../privateAttributes/pressGroupItem.stylex';
 
 registerEnglishFallback(english);
 
+const SLIDING_POINTERS = ['touch', 'pen'] as const;
+const ACTION_TRACKING_PROPS = pressGroupItemProps(SLIDING_POINTERS);
+
 const SMALL_SCREEN_QUERY = '(max-width: 640px)';
 
 const styles = stylex.create({
+  // The browser may pinch-zoom on the actions but never pans there. Chrome on
+  // Android cancels a pointer it pans, which would cancel the group's press.
+  // The gesture host keeps an author's narrower touch-action.
+  trackingRow: {
+    touchAction: 'pinch-zoom',
+  },
   action: {
     maxWidth: '100%',
     minWidth: 0,
@@ -177,6 +194,24 @@ export function AlertDialog({
     onOpenChange(false);
   }, [onOpenChange]);
 
+  // Each action carries the press-group marker from its first render, so the
+  // tracker is its only painter.
+  const actionsRef = useRef<HTMLElement>(null);
+  // Only under the touch presentation does a press slide across the
+  // actions. A desktop press stays the native button's.
+  const {isTouch} = useTouchPresentation();
+  const isTracking = isOpen && isInline !== true && isTouch;
+  useActionGroupTracking(actionsRef, {
+    // The actions row holds only the two buttons.
+    itemSelector: 'button',
+    highlightOnsetMs: alertController.actions.highlightOnsetMs,
+    highlightExpansion: alertController.actions.highlightExpansion,
+    // A mouse press acts as a native button's under any presentation.
+    pointerTypes: SLIDING_POINTERS,
+    isEnabled: isTracking,
+  });
+  const actionTrackingProps = isTracking ? ACTION_TRACKING_PROPS : undefined;
+
   const buttonActionStyle = [
     styles.action,
     isSmallScreen && styles.stackedAction,
@@ -188,6 +223,7 @@ export function AlertDialog({
       label={cancelLabel}
       onClick={handleCancel}
       xstyle={buttonActionStyle}
+      {...actionTrackingProps}
       // Dialog focuses [data-autofocus] itself after showModal(), because
       // React's autoFocus runs during commit while the dialog is invisible.
       // Cancel is least destructive, so it remains the autofocus target even
@@ -203,6 +239,7 @@ export function AlertDialog({
       onClick={onAction}
       isLoading={isActionLoading}
       xstyle={buttonActionStyle}
+      {...actionTrackingProps}
     />
   );
 
@@ -244,13 +281,17 @@ export function AlertDialog({
                 destructive-above-Cancel narrow order because confirmation
                 actions have component-specific meaning here. */}
             <Stack
+              ref={actionsRef}
+              xstyle={isTracking && styles.trackingRow}
               direction={isSmallScreen ? 'vertical' : 'horizontal'}
               gap={2}
               hAlign={isSmallScreen ? 'stretch' : 'end'}
               wrap={isSmallScreen ? 'nowrap' : 'wrap'}>
-              {isSmallScreen
-                ? [actionButton, cancelButton]
-                : [cancelButton, actionButton]}
+              <PressGroupContext value={isTracking}>
+                {isSmallScreen
+                  ? [actionButton, cancelButton]
+                  : [cancelButton, actionButton]}
+              </PressGroupContext>
             </Stack>
           </LayoutFooter>
         }

package/src/AppShell/AppShell.tsx

@@ -59,6 +59,7 @@ import {
   holdLayoutSwap,
   landLayoutGlide,
   layoutMotionFor,
+  layoutStartFor,
   playLayoutFrames,
   playLayoutSwap,
   reportLayoutChange,
@@ -647,6 +648,8 @@ export function AppShell({
   if (isMobileNavOpen && !isMobileNavCloseHeld) {
     setIsMobileNavCloseHeld(true);
   }
+  // Syncs the mobile-nav close hold with a timer. The hold ends after the
+  // slide-out delay.
   useEffect(() => {
     if (!HasActivity || isMobileNavOpen) {
       return;
@@ -814,6 +817,8 @@ export function AppShell({
   const headerRef = useRef<HTMLDivElement>(null);
   const shellRef = useRef<HTMLDivElement>(null);
 
+  // Syncs the header-height CSS variable with a ResizeObserver while the height
+  // is automatic.
   useEffect(() => {
     if (!isAuto || !headerRef.current || !shellRef.current) {
       return;
@@ -996,9 +1001,13 @@ export function AppShell({
         let entering = 0;
         const last = lastSwapRef.current;
         if (last != null && motion.kind === 'spring') {
-          const elapsed =
-            Number(main.ownerDocument.timeline?.currentTime ?? 0) -
-            last.startedAt;
+          // Read at the change's own start, where the glide it retargets
+          // carries on. After a block, that is later than the frame the
+          // timeline still reads.
+          const elapsed = Math.max(
+            0,
+            layoutStartFor(main.ownerDocument) - last.startedAt,
+          );
           if (elapsed < motion.progress.durationMs) {
             const p = 1 - motion.progress.remaining(elapsed);
             held = last.entering + (1 - last.entering) * p;
@@ -1058,7 +1067,7 @@ export function AppShell({
         }
         const {held, entering} = pending;
         lastSwapRef.current = {
-          startedAt: Number(main.ownerDocument.timeline?.currentTime ?? 0),
+          startedAt: layoutStartFor(main.ownerDocument),
           held,
           entering,
         };

package/src/BottomSheet/BottomSheet.doc.mjs

@@ -152,7 +152,7 @@ export const docs = {
       name: 'height',
       type: "'hug' | 'capped' | 'tall' | number | string",
       description:
-        "How tall the sheet is. Named budgets: 'hug' fits its content up to 92% of the viewport, 'capped' is a scrolling mid-height panel (~62%), and 'tall' is a pinned near-full panel (~92%) for content that streams in. Or pass a number (px) / CSS length for a custom budget. Give snapPoints to let the user drag between heights. On shorter viewports the sheet fills the available height. Only a fully expanded 'tall' sheet provides mobile-keyboard accommodation: it stays put and scrolls each focused control above the keyboard. Hug, Capped, numeric and CSS-length heights never do, and a Tall sheet stops doing it the moment the user drags it to a shorter detent, resuming when they drag it back. Outside that state the sheet neither moves nor adds keyboard scroll space, and the browser's own focus reveal is left in place; on iOS that reveal can shift the whole page.",
+        "How tall the sheet is. Named budgets: 'hug' fits its content up to 92% of the viewport, 'capped' is a scrolling mid-height panel (~62%), and 'tall' is a pinned near-full panel (~92%) for content that streams in. Or pass a number (px) / CSS length for a custom budget. Give snapPoints to let the user drag between heights. On shorter viewports the sheet fills the available height. Only a fully expanded 'tall' sheet provides mobile-keyboard accommodation: it stays put and scrolls each focused control above the keyboard. Hug, Capped, numeric and CSS-length heights never do, and a Tall sheet stops doing it the moment the user drags it to a shorter detent, resuming when they drag it back. Outside that state the sheet neither moves nor adds keyboard scroll space, and the browser's own focus reveal is left in place; on iOS that reveal can shift the whole page. This accommodation applies where the visual viewport shrinks for the keyboard, as in Safari on iOS, Firefox for Android and Chrome on Android, where the sheet places the focused control just above the keyboard as it comes up, and the control rides the rest of Gboard\u2019s slide up, and the slide down after it loses focus; a hide Chrome reports late, such as Back, rides down from Chrome\u2019s report (`astryx docs browser-support`).",
       default: "'capped'",
     },
     {

package/src/BottomSheet/BottomSheet.tsx

@@ -517,6 +517,7 @@ function StandaloneBottomSheet({
   const stackViewRef = useRef(stackView);
   stackViewRef.current = stackView;
   const scrimWriteRef = useRef<BottomSheetScrimWrite>({frame: null});
+  // Releases the pending scrim write frame on unmount.
   useEffect(() => () => cancelScrimWrite(scrimWriteRef.current), []);
   const writeScrim = useCallback(
     (opacity: '0' | '1') =>

package/src/BottomSheet/BottomSheetPanel.tsx

@@ -14,7 +14,7 @@
  * - /packages/core/src/BottomSheet/BottomSheet.tsx
  * - /packages/core/src/BottomSheet/BottomSheetPanel.test.tsx
  * - /packages/core/src/BottomSheet/snapOffsets.ts
- * - /packages/core/src/BottomSheet/useMobileKeyboard.ts
+ * - /packages/core/src/keyboard/useMobileKeyboard.ts
  * - /packages/core/src/BottomSheet/useSheetGestures.ts
  * - /packages/core/src/Layout/container.stylex.ts (bottom-sheet padding chain)
  */
@@ -66,7 +66,7 @@ import {
   resolveSnapPoints,
   type BottomSheetSnapPoint,
 } from './snapOffsets';
-import {useMobileKeyboard} from './useMobileKeyboard';
+import {useMobileKeyboard} from '../keyboard/useMobileKeyboard';
 import {
   scrollPreservationPadding,
   sheetLayoutHeight,
@@ -255,6 +255,10 @@ const styles = stylex.create({
     // surface behind the pill itself, fading out across the lower half so the
     // content emerging below has no visible cut line.
     backgroundImage: `linear-gradient(to bottom, ${colorVars['--color-background-surface']} 60%, transparent)`,
+    // WebKit can draw this bar under the scrolling body's own layer while the
+    // sheet's transform animates, so the pill vanishes until the sheet rests.
+    // A layer of its own keeps it above the body.
+    willChange: 'transform',
     // Drags are the handle's; a pinch still zooms the page (WCAG 1.4.4).
     touchAction: 'pinch-zoom',
     cursor: {
@@ -312,13 +316,29 @@ const styles = stylex.create({
   },
   tallKeyboardBody: {
     scrollPaddingBlockEnd: MOBILE_KEYBOARD_BOTTOM_CLEARANCE,
+  },
+  // The inset the keyboard takes at the end of a Tall sheet's content
+  // (useMobileKeyboard), so its last control can scroll above the keyboard.
+  // It is the content box's last in-flow box, after the content's own
+  // children, not a box after the content. Firefox resolves the content's
+  // `min-height: min-content` as `auto` in the block axis. The content box
+  // then keeps the body's height while its children overflow it. An inset
+  // after that box sat inside the overflow and added no scroll range. In
+  // Firefox for Android, the body's scrollHeight was 1491 with and without a
+  // 357 px inset.
+  tallKeyboardContent: {
     '::after': {
       content: '""',
       display: 'block',
-      blockSize: 'var(--_sheet-keyboard-inset, 0px)',
+      blockSize: 0,
       pointerEvents: 'none',
     },
   },
+  keyboardInset: (inset: number) => ({
+    '::after': {
+      blockSize: inset,
+    },
+  }),
   budget: {
     height: `calc(var(--_sheet-budget) + ${OVERSCROLL_PADDING}px)`,
   },
@@ -418,6 +438,7 @@ function waitForTransition(
 
   let done = false;
   let timer: ReturnType<typeof setTimeout> | null = null;
+  let backstopMs = 0;
   const finish = () => {
     if (done) {
       return;
@@ -431,9 +452,24 @@ function waitForTransition(
     complete();
   };
   const handleTransitionEnd = (event: TransitionEvent) => {
-    if (event.target === element && event.propertyName === propertyName) {
-      finish();
+    if (event.target !== element || event.propertyName !== propertyName) {
+      return;
+    }
+    // The engine cancels a transition whose end value changes mid-flight. A
+    // percentage transform does when the closing frame moves the height by a
+    // fraction of a pixel. A replacement runs on from where it was. That one
+    // ends the motion, not the cancel.
+    if (
+      event.type === 'transitioncancel' &&
+      hasRunningTransition(element, propertyName)
+    ) {
+      if (timer != null) {
+        clearTimeout(timer);
+        timer = setTimeout(finish, backstopMs);
+      }
+      return;
     }
+    finish();
   };
   element.addEventListener('transitionend', handleTransitionEnd);
   element.addEventListener('transitioncancel', handleTransitionEnd);
@@ -484,7 +520,8 @@ function waitForTransition(
     return () => {};
   }
 
-  timer = setTimeout(finish, transitionMs + TRANSITION_BACKSTOP_BUFFER_MS);
+  backstopMs = transitionMs + TRANSITION_BACKSTOP_BUFFER_MS;
+  timer = setTimeout(finish, backstopMs);
   return () => {
     if (timer != null) {
       clearTimeout(timer);
@@ -494,6 +531,19 @@ function waitForTransition(
   };
 }
 
+// Whether a CSS transition of `propertyName` still runs on `element`.
+function hasRunningTransition(
+  element: HTMLElement,
+  propertyName: string,
+): boolean {
+  return (element.getAnimations?.() ?? []).some(
+    animation =>
+      (animation as Animation & {transitionProperty?: string})
+        .transitionProperty === propertyName &&
+      (animation.playState === 'running' || animation.playState === 'paused'),
+  );
+}
+
 function parseTransitionTime(value: string): number | null {
   const normalizedValue = value.trim();
   if (!/^-?(?:\d+|\d*\.\d+)(?:ms|s)$/.test(normalizedValue)) {
@@ -530,6 +580,9 @@ export function BottomSheetPanel({
   ...props
 }: BottomSheetPanelProps) {
   const elementRef = useRef<HTMLDivElement | null>(null);
+  const dismissKeyboardRef = useRef<
+    ((focusTarget?: HTMLElement) => void) | null
+  >(null);
   const previousStateRef = useRef(state);
   const reactivatedEntranceRef = useRef(false);
   const onMotionStartRef = useRef(onMotionStart);
@@ -605,7 +658,6 @@ export function BottomSheetPanel({
     dragOffset,
     settledOffset,
     isDragging,
-    isTraveling,
     isDismissedByTouchDrag,
     sheetHeight,
     scrollPreservationInset,
@@ -619,6 +671,10 @@ export function BottomSheetPanel({
     offscreenBlockEndInset: OVERSCROLL_PADDING,
     onDismiss,
     snapHeights,
+    onTravelStart: () => {
+      // Focusing the sheet dismisses the keyboard as the sheet starts to move.
+      dismissKeyboardRef.current?.(elementRef.current ?? undefined);
+    },
     onScrimOpacity,
     hasFixedHeight: consumerHeight != null,
   });
@@ -652,17 +708,19 @@ export function BottomSheetPanel({
     isPresentedRef.current = isPresented;
     sheetRef(isPresented ? elementRef.current : null);
   }, [isPresented, sheetRef]);
-  useMobileKeyboard({
-    bodyRef: bodyElementRef,
-    bottomClearance: MOBILE_KEYBOARD_BOTTOM_CLEARANCE,
-    isEnabled: height === 'tall',
-    isFullyExpanded: settledOffset === 0,
-    isPageScrollLocked,
-    isSheetTraveling: isTraveling,
+  const keyboard = useMobileKeyboard(elementRef, {
+    move: 'ride',
+    inset: true,
+    offset: MOBILE_KEYBOARD_BOTTOM_CLEARANCE,
+    isEnabled: height === 'tall' && isPresented,
+    isExpanded: settledOffset === 0,
     isOpen: isInteractive,
-    isPresented,
-    sheetRef: elementRef,
+    isPageScrollLocked,
   });
+  const keyboardInset = keyboard.inset;
+  // The drag's own callback dismisses the keyboard as the sheet starts to
+  // move. It runs in the gesture, so it reads the newest dismiss.
+  dismissKeyboardRef.current = keyboard.dismiss;
   // Keep controller registration attached to one stable host ref. React
   // detaches an old callback ref when a consumer supplies a new identity; if
   // that public ref were merged with setElement, an ordinary parent rerender
@@ -676,6 +734,8 @@ export function BottomSheetPanel({
   const isCoarseCrossFade = useMediaQuery(REDUCED_MOTION_COARSE_QUERY);
   const isCrossFade =
     isCoarseCrossFade || (isReducedMotion && isDismissedByTouchDrag);
+  // Syncs the motion with the panel's CSS transition. The motion completes when
+  // that transition ends.
   useLayoutEffect(() => {
     if (motion == null) {
       return;
@@ -907,6 +967,10 @@ export function BottomSheetPanel({
             getContentProps<HTMLDivElement>(
               stylex.props(
                 styles.content,
+                height === 'tall' && styles.tallKeyboardContent,
+                height === 'tall' &&
+                  keyboardInset > 0 &&
+                  styles.keyboardInset(keyboardInset),
                 ...container(
                   usesThemePadding
                     ? {useThemeDefault: 'bottom-sheet'}

package/src/BottomSheet/BottomSheetSwitcher.doc.mjs

@@ -29,6 +29,11 @@ export const docs = {
   group: 'BottomSheet',
   category: 'Overlay',
   keywords: ['bottom sheet', 'switcher', 'multi-step', 'flow', 'wizard'],
+  deprecated: {
+    replacement: 'BottomSheet',
+    description:
+      'Write each step as its own BottomSheet with isOpen, controlled by one state value that names the open step; moving on from inside the open step replaces it in place (see BottomSheet, Replacing a sheet). BottomSheetSwitcher keeps working until a future minor release removes it.',
+  },
   playground: {
     overlay: true,
     overlayControl: {

package/src/BottomSheet/BottomSheetSwitcher.tsx

@@ -358,6 +358,7 @@ export function BottomSheetSwitcher({
   const stackViewRef = useRef(stackView);
   stackViewRef.current = stackView;
   const scrimWriteRef = useRef<BottomSheetScrimWrite>({frame: null});
+  // Releases the pending scrim write frame on unmount.
   useEffect(() => () => cancelScrimWrite(scrimWriteRef.current), []);
   // What the flow's place in the stack was when it left the registry: its
   // depth and the open sheet beneath it. React runs the registration
@@ -564,6 +565,9 @@ export function BottomSheetSwitcher({
     presentationCounterRef.current += 1;
     presentationOrderRef.current.set(sheetId, presentationCounterRef.current);
   }, []);
+  // Syncs document focus with the flow's visibility. When the flow hides, focus
+  // goes to the opener, to the sheet now on top, or to the target of the
+  // registry.
   useLayoutEffect(() => {
     if (isFlowVisible) {
       if (!hasScrim) {
@@ -694,6 +698,7 @@ export function BottomSheetSwitcher({
       unregister();
     };
   }, [hasScrim, isFlowVisible, onBeforeSheetPresent]);
+  // Syncs the open state of this flow in the sheet stack registry.
   useLayoutEffect(() => {
     if (isFlowVisible && hasScrim) {
       setBottomSheetOpen(stackKeyRef.current, isFlowOpen);

package/src/BottomSheet/bottomSheetStack.ts

@@ -1881,7 +1881,7 @@ export function getBottomSheetBeneath(
 
 // preventScroll on both: presenting a sheet must not scroll the page to reveal
 // what it just focused. For an autofocused field that reveal is the mobile
-// keyboard's, and it moves the document under a fixed sheet; useMobileKeyboard
+// keyboard's, and it moves the document under a fixed sheet. useMobileKeyboard
 // brings the field into view within the sheet instead.
 /**
  * Move focus into a sheet panel. Focus already inside the sheet stays put:

package/src/BottomSheet/useSheetGestures.ts

@@ -354,6 +354,8 @@ export interface UseSheetGesturesOptions {
   snapHeights?: () => number[];
   /** Notified when the settled visible detent height (px) changes. */
   onSnap?: (heightPx: number) => void;
+  /** Called once a drag first moves the sheet off its detent. */
+  onTravelStart?: () => void;
   /**
    * Called with the scrim opacity the sheet should show (1 = fully visible,
    * 0 = hidden) as the drag moves and on settle. Full while the sheet is at
@@ -508,6 +510,7 @@ export function useSheetGestures({
   onDismiss,
   snapHeights,
   onSnap,
+  onTravelStart,
   onScrimOpacity,
   hasFixedHeight = false,
 }: UseSheetGesturesOptions): UseSheetGesturesResult {
@@ -654,6 +657,8 @@ export function useSheetGestures({
   // stops by the time the re-anchor read it.
   const snapHeightsRef = useRef(snapHeights);
   snapHeightsRef.current = snapHeights;
+  const onTravelStartRef = useRef(onTravelStart);
+  onTravelStartRef.current = onTravelStart;
 
   const onDismissRef = useRef(onDismiss);
   const canDismissRef = useRef(canDismiss);
@@ -699,6 +704,8 @@ export function useSheetGestures({
   const sheetElRef = useRef<HTMLElement | null>(null);
   const bodyNodeRef = useRef<HTMLElement | null>(null);
   const observerRef = useRef<ResizeObserver | null>(null);
+  // Syncs the browser layout with the transform reset, then ends the
+  // scroll-area reconcile one frame later.
   useLayoutEffect(() => {
     if (!isScrollAreaReconciling) {
       return;
@@ -738,7 +745,9 @@ export function useSheetGestures({
         }
         return;
       }
-      recordSheetHeight(node.getBoundingClientRect().height);
+      // No measure here: reading the height while the sheet mounts forces a
+      // layout in the middle of the open. The observer's first report comes
+      // after the browser's own layout, before the first paint.
       const ro = new ResizeObserver(entries => {
         const entry = entries[0];
         if (entry) {
@@ -756,6 +765,7 @@ export function useSheetGestures({
     },
     [recordSheetHeight],
   );
+  // Releases the height observer on unmount.
   useEffect(() => () => observerRef.current?.disconnect(), []);
 
   // Reset to the tallest detent each time the sheet re-opens.
@@ -907,6 +917,8 @@ export function useSheetGestures({
     resolveDetents,
   ]);
 
+  // Syncs window resize and orientation listeners with `isOpen`. Each event
+  // anchors the sheet to its settled detent again.
   useEffect(() => {
     if (!isOpen || typeof window === 'undefined') {
       return;
@@ -1024,6 +1036,8 @@ export function useSheetGestures({
     [prepareScrollAreaSettle, resolveDetents],
   );
 
+  // Syncs window blur and document visibilitychange listeners with `isOpen`. A
+  // blur or a hidden page cancels a drag.
   useEffect(() => {
     // Only an open sheet can be dragged; a closed one listens to nothing.
     if (!isOpen) {
@@ -1303,6 +1317,7 @@ export function useSheetGestures({
       if (!state.hasTraveled && next !== state.baseOffset) {
         state.hasTraveled = true;
         setIsTraveling(true);
+        onTravelStartRef.current?.();
       }
 
       // Mirror the scrim to the live drag: full at/above the mid detent,

package/src/Button/Button.tsx

@@ -53,6 +53,7 @@ import {iconBoxSizeStyles, type IconSize} from '../Icon/IconSize.stylex';
 import {EDGE_COMP_ATTR} from '../Layout/edgeCompensation.stylex';
 import {useSize} from '../SizeContext/SizeContext';
 import {useButtonGroup} from '../ButtonGroup/ButtonGroupContext';
+import {PressGroupContext} from '../hooks/pressGroupContext';
 import {useInputGroup} from '../InputGroup/InputGroupContext';
 import {InputGroupInternalContext} from '../InputGroup/InputGroupInternalContext';
 import {
@@ -77,6 +78,12 @@ import {isRenderable} from '../utils/isRenderable';
 
 registerEnglishFallback(english);
 
+/**
+ * Written by the press controller or a group's tracker while a press is
+ * believed. Typed `string`, so StyleX reads it as a computed key.
+ */
+const PRESSED_ON: string = '[data-astryx-press="on"]';
+
 /**
  * Base button styles
  * Pseudo-classes are nested within properties per StyleX recommendation:
@@ -138,7 +145,19 @@ const styles = stylex.create({
         default: 'scale(0.98)',
         '@media (pointer: coarse)': 'scale(1)',
       },
-      '[data-astryx-press="on"]': 'scale(0.98)',
+      [PRESSED_ON]: 'scale(0.98)',
+    },
+  },
+  // A tracked action's own `:active` image paints nothing: the tracker paints
+  // the action under the pointer, which need not be the one pressed first.
+  trackedOverlay: {
+    backgroundSize: {default: null, [`:active:not(${PRESSED_ON})`]: '0 0'},
+  },
+  // A tracked action's press is painted by its group's tracker alone.
+  pressableTracked: {
+    transform: {
+      default: 'scale(1)',
+      [PRESSED_ON]: 'scale(0.98)',
     },
   },
   inactive: {
@@ -147,7 +166,7 @@ const styles = stylex.create({
     transform: {
       default: 'none',
       ':active': 'none',
-      '[data-astryx-press="on"]': 'none',
+      [PRESSED_ON]: 'none',
     },
   },
   disabled: {
@@ -160,7 +179,7 @@ const styles = stylex.create({
     backgroundImage: {
       default: 'none',
       ':active': 'none',
-      '[data-astryx-press="on"]': 'none',
+      [PRESSED_ON]: 'none',
     },
   },
   iconOnly: {
@@ -632,6 +651,7 @@ export function Button({
   const t = useComponentTranslator();
   const size = useSize(sizeProp, 'md');
   const buttonGroup = useButtonGroup();
+  const isGroupTracked = use(PressGroupContext);
   const inputGroup = useInputGroup();
 
   const [isPending, startTransition] = useTransition();
@@ -760,11 +780,13 @@ export function Button({
     sizeStyles[size],
     isIconOnly && styles.iconOnly,
     interactionOverlayStyles.backgroundImage,
+    isGroupTracked && styles.trackedOverlay,
     buttonDisabled && styles.inactive,
     isTrueDisabled && styles.disabled,
     useAriaDisabled && styles.ariaDisabled,
     renderAsLink && styles.link,
-    !buttonGroup && styles.pressable,
+    !buttonGroup &&
+      (isGroupTracked ? styles.pressableTracked : styles.pressable),
     buttonGroup &&
       (buttonGroup.orientation === 'horizontal'
         ? groupStyles.horizontal