@astryxdesign/core 0.7.7 → 0.7.8-canary.0b39b51

package/locales/en.json

@@ -255,6 +255,126 @@
     "defaultMessage": "{count, number} {count, plural, one {result} other {results}}",
     "description": "Live result-count text next to the PowerSearch input, announced to screen readers on change. Example: `12 results`, `1 result`; keep compact."
   },
+  "@astryx.powersearch.sheet.filtersTitle": {
+    "defaultMessage": "Filters",
+    "description": "Heading and accessible name of the PowerSearch touch sheet that lists the active filters (experimental bottom-sheet presentation). Plural noun."
+  },
+  "@astryx.powersearch.sheet.addFilter": {
+    "defaultMessage": "Add filter",
+    "description": "Button label in the PowerSearch touch flow: in the Filters sheet header it opens the field list; in the value step it confirms a new filter. Imperative verb; no leading plus sign."
+  },
+  "@astryx.powersearch.sheet.noFilters": {
+    "defaultMessage": "No filters applied",
+    "description": "Heading of the PowerSearch Filters sheet empty state when no filter is active (experimental bottom-sheet presentation). Neutral tone."
+  },
+  "@astryx.powersearch.sheet.noFiltersDescription": {
+    "defaultMessage": "Add a filter to narrow your results and find what you need faster.",
+    "description": "Guidance line under the PowerSearch Filters sheet empty state, above its Add filter action. One short sentence."
+  },
+  "@astryx.powersearch.sheet.clearAll": {
+    "defaultMessage": "Clear all",
+    "description": "Button label in the PowerSearch Filters sheet footer that asks to remove every editable filter. Imperative verb + determiner."
+  },
+  "@astryx.powersearch.sheet.clearAllTitle": {
+    "defaultMessage": "Clear all filters?",
+    "description": "Title and accessible name of the confirmation dialog that Clear all opens in the PowerSearch touch flow. A short question."
+  },
+  "@astryx.powersearch.sheet.clearAllDescription": {
+    "defaultMessage": "This removes all editable filters from this search.",
+    "description": "Body text of the PowerSearch Clear all confirmation dialog. Read-only filters stay, so it names editable filters."
+  },
+  "@astryx.powersearch.sheet.clearAllConfirm": {
+    "defaultMessage": "Clear filters",
+    "description": "Destructive action of the PowerSearch Clear all confirmation dialog: removes the editable filters. Imperative verb + plural noun."
+  },
+  "@astryx.powersearch.sheet.clearAllCancel": {
+    "defaultMessage": "Keep filters",
+    "description": "Safe action of the PowerSearch Clear all confirmation dialog: closes it and changes nothing. Imperative verb + plural noun."
+  },
+  "@astryx.powersearch.sheet.done": {
+    "defaultMessage": "Done",
+    "description": "Primary button label in the PowerSearch Filters sheet footer that closes the sheet. Short; marks the end of the filtering task."
+  },
+  "@astryx.powersearch.sheet.search": {
+    "defaultMessage": "Search",
+    "description": "Screen-reader-only label of the content-search box at the top of the PowerSearch Add filter sheet; its suggestions list inline below it. Noun or verb as reads best."
+  },
+  "@astryx.powersearch.sheet.searchResults": {
+    "defaultMessage": "Search results",
+    "description": "Screen-reader-only name of the inline suggestion list under the PowerSearch Add filter sheet's content search. Plural noun."
+  },
+  "@astryx.powersearch.sheet.searchFields": {
+    "defaultMessage": "Search filters",
+    "description": "Screen-reader-only label of the field-list filter box in the PowerSearch Add filter sheet, shown once the config has eight or more fields. Imperative verb + plural noun."
+  },
+  "@astryx.powersearch.sheet.searchFieldsPlaceholder": {
+    "defaultMessage": "Search filters…",
+    "description": "Placeholder inside the field-list filter box in the PowerSearch Add filter sheet. Imperative verb; trailing `…` is one character."
+  },
+  "@astryx.powersearch.sheet.ungroupedFields": {
+    "defaultMessage": "General",
+    "description": "Heading of the PowerSearch Add filter sheet's list of fields that belong to no group, shown before the named groups. A short noun."
+  },
+  "@astryx.powersearch.sheet.noMatchingFields": {
+    "defaultMessage": "No filters match your search",
+    "description": "Empty-state text in the PowerSearch Add filter sheet when the field-list filter matches no field. Neutral tone."
+  },
+  "@astryx.powersearch.sheet.tryDifferentSearch": {
+    "defaultMessage": "Try a different search.",
+    "description": "Guidance line under the PowerSearch Add filter sheet's empty search result (\"No results found\", \"No filters match your search\"). One short sentence."
+  },
+  "@astryx.powersearch.sheet.noResults": {
+    "defaultMessage": "No results found",
+    "description": "Empty-state text in the PowerSearch Add filter sheet when the content search has no suggestion for the typed query. Neutral tone (not error-y)."
+  },
+  "@astryx.powersearch.sheet.filterUnavailable": {
+    "defaultMessage": "This filter is no longer available",
+    "description": "Message in the PowerSearch value step when a config update removed the field or operator being edited; Cancel remains as the way out, and the Filters row keeps its remove action."
+  },
+  "@astryx.powersearch.sheet.removeFilter": {
+    "defaultMessage": "Remove {field} filter",
+    "description": "Accessible name and tooltip of the trailing remove button on a PowerSearch Filters sheet row; field is the filter's field label (for example \"Remove Status filter\")."
+  },
+  "@astryx.powersearch.sheet.relativeDaysAgo": {
+    "defaultMessage": "{count, number} {count, plural, one {day} other {days}} ago",
+    "description": "A relative-date choice row in the PowerSearch touch sheet, in the past (for example \"3 days ago\"). The popover editor lists the same choices."
+  },
+  "@astryx.powersearch.sheet.relativeDaysFromNow": {
+    "defaultMessage": "{count, number} {count, plural, one {day} other {days}} from now",
+    "description": "A relative-date choice row in the PowerSearch touch sheet, in the future (for example \"3 days from now\"). The popover editor lists the same choices."
+  },
+  "@astryx.powersearch.sheet.relativeWeeksAgo": {
+    "defaultMessage": "{count, number} {count, plural, one {week} other {weeks}} ago",
+    "description": "A relative-date choice row in the PowerSearch touch sheet, in the past (for example \"3 weeks ago\"). The popover editor lists the same choices."
+  },
+  "@astryx.powersearch.sheet.relativeWeeksFromNow": {
+    "defaultMessage": "{count, number} {count, plural, one {week} other {weeks}} from now",
+    "description": "A relative-date choice row in the PowerSearch touch sheet, in the future (for example \"3 weeks from now\"). The popover editor lists the same choices."
+  },
+  "@astryx.powersearch.sheet.relativeMonthsAgo": {
+    "defaultMessage": "{count, number} {count, plural, one {month} other {months}} ago",
+    "description": "A relative-date choice row in the PowerSearch touch sheet, in the past (for example \"3 months ago\"). The popover editor lists the same choices."
+  },
+  "@astryx.powersearch.sheet.relativeMonthsFromNow": {
+    "defaultMessage": "{count, number} {count, plural, one {month} other {months}} from now",
+    "description": "A relative-date choice row in the PowerSearch touch sheet, in the future (for example \"3 months from now\"). The popover editor lists the same choices."
+  },
+  "@astryx.powersearch.sheet.fieldOperator": {
+    "defaultMessage": "{field} {operator}",
+    "description": "A field label joined with an operator label in the PowerSearch touch sheet: the value step's title, an operator radio's name, and the first part of a Filters row (for example \"Status is\"). Translators may reorder the two parts."
+  },
+  "@astryx.powersearch.sheet.labelValue": {
+    "defaultMessage": "{label} {value}",
+    "description": "A Filters row's \"field operator\" text joined with its value, as the removal announcement reads it (for example \"Status is Open\"). Translators may reorder the two parts."
+  },
+  "@astryx.powersearch.sheet.filtersClearedWithCount": {
+    "defaultMessage": "All filters removed. {resultCount}",
+    "description": "Polite screen-reader announcement after Clear all in the PowerSearch touch sheet when the result count changed with it; resultCount is the field's already formatted result count (for example \"240 results\"). Live-region text, never shown on screen."
+  },
+  "@astryx.powersearch.sheet.editableFiltersClearedWithCount": {
+    "defaultMessage": "Editable filters removed. {resultCount}",
+    "description": "Polite screen-reader announcement after Clear all in the PowerSearch touch sheet removes the editable filters, keeps read-only ones, and the result count changed with it; resultCount is the field's already formatted result count (for example \"240 results\"). Live-region text, never shown on screen."
+  },
   "@astryx.alertDialog.cancel": {
     "defaultMessage": "Cancel",
     "description": "Button label on the secondary/dismiss button of an AlertDialog (modal confirmation). Imperative verb; consumers usually override with task-specific text."

package/locales/pseudo.json

@@ -191,6 +191,96 @@
   "@astryx.powersearch.resultCount": {
     "defaultMessage": "⟦{count, number} {count, plural, one {result} other {results}}⟧"
   },
+  "@astryx.powersearch.sheet.filtersTitle": {
+    "defaultMessage": "⟦Ƒíłţéřš⟧"
+  },
+  "@astryx.powersearch.sheet.addFilter": {
+    "defaultMessage": "⟦Àðð ƒíłţéř⟧"
+  },
+  "@astryx.powersearch.sheet.noFilters": {
+    "defaultMessage": "⟦Ñó ƒíłţéřš àþþłíéð⟧"
+  },
+  "@astryx.powersearch.sheet.noFiltersDescription": {
+    "defaultMessage": "⟦Àðð à ƒíłţéř ţó ñàřřóŵ ýóúř řéšúłţš àñð ƒíñð ŵĥàţ ýóú ñééð ƒàšţéř.⟧"
+  },
+  "@astryx.powersearch.sheet.clearAll": {
+    "defaultMessage": "⟦Çłéàř àłł⟧"
+  },
+  "@astryx.powersearch.sheet.clearAllTitle": {
+    "defaultMessage": "⟦Çłéàř àłł ƒíłţéřš?⟧"
+  },
+  "@astryx.powersearch.sheet.clearAllDescription": {
+    "defaultMessage": "⟦Ţĥíš řéɱóṽéš àłł éðíţàƀłé ƒíłţéřš ƒřóɱ ţĥíš šéàřçĥ.⟧"
+  },
+  "@astryx.powersearch.sheet.clearAllConfirm": {
+    "defaultMessage": "⟦Çłéàř ƒíłţéřš⟧"
+  },
+  "@astryx.powersearch.sheet.clearAllCancel": {
+    "defaultMessage": "⟦Ķééþ ƒíłţéřš⟧"
+  },
+  "@astryx.powersearch.sheet.done": {
+    "defaultMessage": "⟦Ðóñé⟧"
+  },
+  "@astryx.powersearch.sheet.search": {
+    "defaultMessage": "⟦Šéàřçĥ⟧"
+  },
+  "@astryx.powersearch.sheet.searchResults": {
+    "defaultMessage": "⟦Šéàřçĥ řéšúłţš⟧"
+  },
+  "@astryx.powersearch.sheet.searchFields": {
+    "defaultMessage": "⟦Šéàřçĥ ƒíłţéřš⟧"
+  },
+  "@astryx.powersearch.sheet.searchFieldsPlaceholder": {
+    "defaultMessage": "⟦Šéàřçĥ ƒíłţéřš…⟧"
+  },
+  "@astryx.powersearch.sheet.ungroupedFields": {
+    "defaultMessage": "⟦Ĝéñéřàł⟧"
+  },
+  "@astryx.powersearch.sheet.noMatchingFields": {
+    "defaultMessage": "⟦Ñó ƒíłţéřš ɱàţçĥ ýóúř šéàřçĥ⟧"
+  },
+  "@astryx.powersearch.sheet.tryDifferentSearch": {
+    "defaultMessage": "⟦Ţřý à ð탃éřéñţ šéàřçĥ.⟧"
+  },
+  "@astryx.powersearch.sheet.noResults": {
+    "defaultMessage": "⟦Ñó řéšúłţš ƒóúñð⟧"
+  },
+  "@astryx.powersearch.sheet.filterUnavailable": {
+    "defaultMessage": "⟦Ţĥíš ƒíłţéř íš ñó łóñĝéř àṽàíłàƀłé⟧"
+  },
+  "@astryx.powersearch.sheet.removeFilter": {
+    "defaultMessage": "⟦Řéɱóṽé {field} ƒíłţéř⟧"
+  },
+  "@astryx.powersearch.sheet.relativeDaysAgo": {
+    "defaultMessage": "⟦{count, number} {count, plural, one {day} other {days}} àĝó⟧"
+  },
+  "@astryx.powersearch.sheet.relativeDaysFromNow": {
+    "defaultMessage": "⟦{count, number} {count, plural, one {day} other {days}} ƒřóɱ ñóŵ⟧"
+  },
+  "@astryx.powersearch.sheet.relativeWeeksAgo": {
+    "defaultMessage": "⟦{count, number} {count, plural, one {week} other {weeks}} àĝó⟧"
+  },
+  "@astryx.powersearch.sheet.relativeWeeksFromNow": {
+    "defaultMessage": "⟦{count, number} {count, plural, one {week} other {weeks}} ƒřóɱ ñóŵ⟧"
+  },
+  "@astryx.powersearch.sheet.relativeMonthsAgo": {
+    "defaultMessage": "⟦{count, number} {count, plural, one {month} other {months}} àĝó⟧"
+  },
+  "@astryx.powersearch.sheet.relativeMonthsFromNow": {
+    "defaultMessage": "⟦{count, number} {count, plural, one {month} other {months}} ƒřóɱ ñóŵ⟧"
+  },
+  "@astryx.powersearch.sheet.fieldOperator": {
+    "defaultMessage": "⟦{field} {operator}⟧"
+  },
+  "@astryx.powersearch.sheet.labelValue": {
+    "defaultMessage": "⟦{label} {value}⟧"
+  },
+  "@astryx.powersearch.sheet.filtersClearedWithCount": {
+    "defaultMessage": "⟦Àłł ƒíłţéřš řéɱóṽéð. {resultCount}⟧"
+  },
+  "@astryx.powersearch.sheet.editableFiltersClearedWithCount": {
+    "defaultMessage": "⟦Éðíţàƀłé ƒíłţéřš řéɱóṽéð. {resultCount}⟧"
+  },
   "@astryx.alertDialog.cancel": {
     "defaultMessage": "⟦Çàñçéł⟧"
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astryxdesign/core",
-  "version": "0.7.7",
+  "version": "0.7.8-canary.0b39b51",
   "displayName": "Astryx Core",
   "description": "The component library. Accessible, themeable React components with built-in spacing, dark mode, and StyleX styling.",
   "author": "Meta Open Source",
@@ -824,15 +824,20 @@
       "types": "./dist/Markdown/remark.d.ts",
       "default": "./dist/Markdown/remark.js"
     },
+    "./internal/indicatorPress.stylex": {
+      "source": "./src/internal/indicatorPress.stylex.ts",
+      "types": "./dist/internal/indicatorPress.stylex.d.ts",
+      "default": "./dist/internal/indicatorPress.stylex.js"
+    },
     "./internal/touch": {
       "source": "./src/internal/touch.ts",
       "types": "./dist/internal/touch.d.ts",
       "default": "./dist/internal/touch.js"
     },
-    "./internal/touch-sheet": {
-      "source": "./src/internal/touch-sheet.ts",
-      "types": "./dist/internal/touch-sheet.d.ts",
-      "default": "./dist/internal/touch-sheet.js"
+    "./internal/selectable-card": {
+      "source": "./src/internal/selectable-card.ts",
+      "types": "./dist/internal/selectable-card.d.ts",
+      "default": "./dist/internal/selectable-card.js"
     }
   },
   "files": [
@@ -865,6 +870,9 @@
     "react-dom": ">=19.0.0"
   },
   "devDependencies": {
+    "@astryxdesign/a11y-spec": "0.7.8-canary.0b39b51",
+    "@astryxdesign/cli": "0.7.8-canary.0b39b51",
+    "@astryxdesign/interaction-harness": "0.7.8-canary.0b39b51",
     "@babel/cli": "^7.29.7",
     "@babel/core": "^7.29.7",
     "@babel/preset-react": "^7.29.7",
@@ -875,10 +883,7 @@
     "@testing-library/jest-dom": "^6.6.0",
     "@testing-library/react": "^16.3.2",
     "@types/babel__core": "^7.20.5",
-    "tailwindcss": "^4.3.2",
-    "@astryxdesign/a11y-spec": "0.0.0",
-    "@astryxdesign/interaction-harness": "0.0.0",
-    "@astryxdesign/cli": "0.7.7"
+    "tailwindcss": "^4.3.2"
   },
   "dependencies": {
     "intl-messageformat": "^11.2.9"

package/src/AlertDialog/AlertDialog.doc.mjs

@@ -21,7 +21,7 @@ export const docs = {
   ],
   usage: {
     description:
-      'AlertDialog asks the user to confirm a destructive or irreversible action before it happens. Use it for things like deleting content, revoking access, or discarding unsaved changes.\n\nIt implements the WAI-ARIA APG [Alert Dialog pattern](https://www.w3.org/WAI/ARIA/apg/patterns/alertdialog/): `role="alertdialog"`, a title linked by `aria-labelledby`, a consequence description linked by `aria-describedby`, focus moved into the dialog on open and returned to the trigger on close, and no dismissal by clicking outside. Escape cancels.\n\nAlertDialog passes its requested width through to Dialog, which clamps the surface to the container and dynamic viewport with token gutters. Generic Dialog footers should wrap, but Dialog does not own action semantics or order; consumer composition controls that. AlertDialog owns its confirmation semantics: above 640px, actions render horizontally and may move onto another row; at 640px and below, the destructive action appears above Cancel and both buttons fill the footer width. Button labels retain their standard single-line behavior. The breakpoint follows available width, not pointer or hover capability. The body scrolls when block space is constrained.\n\nFor cases where you want to show an alert without managing open state, use the `useImperativeAlertDialog` hook: call `alert.show(options)` and render `alert.element` in your tree.',
+      'AlertDialog asks the user to confirm a destructive or irreversible action before it happens. Use it for things like deleting content, revoking access, or discarding unsaved changes.\n\nIt implements the WAI-ARIA APG [Alert Dialog pattern](https://www.w3.org/WAI/ARIA/apg/patterns/alertdialog/): `role="alertdialog"`, a title linked by `aria-labelledby`, a consequence description linked by `aria-describedby`, focus moved into the dialog on open and returned to the trigger on close, and no dismissal by clicking outside. Escape cancels.\n\nAlertDialog passes its requested width through to Dialog, which clamps the surface to the container and dynamic viewport with token gutters. Generic Dialog footers should wrap, but Dialog does not own action semantics or order; consumer composition controls that. AlertDialog owns its confirmation semantics: above 640px, actions render horizontally and may move onto another row; at 640px and below, the destructive action appears above Cancel and both buttons fill the footer width. Button labels retain their standard single-line behavior. The breakpoint follows available width, not pointer or hover capability. The body scrolls when block space is constrained.\n\nThe two actions are tracked as one group under every pointer, the way iOS tracks the actions of an alert: the action under the pointer highlights as soon as it is pressed, the highlight follows the pointer from one action to the other, and the release runs the action under it. Releasing off both actions runs nothing. The keyboard and assistive technology keep the click of each button.\n\nFor cases where you want to show an alert without managing open state, use the `useImperativeAlertDialog` hook: call `alert.show(options)` and render `alert.element` in your tree.',
     bestPractices: [
       {
         guidance: true,
@@ -196,7 +196,7 @@ export const docsDense = {
     'Confirms destructive/irreversible action before it happens (delete, revoke access, discard unsaved changes).',
   usage: {
     description:
-      'AlertDialog confirms destructive/irreversible action (delete, revoke access, discard changes). Implements WAI-ARIA APG Alert Dialog pattern (https://www.w3.org/WAI/ARIA/apg/patterns/alertdialog/): role="alertdialog", aria-labelledby title, aria-describedby description, focus into dialog on open + back to trigger on close, no outside-click dismissal, Escape cancels. Dialog preserves requested width + clamps it to container/dynamic viewport gutters. Generic Dialog footers wrap while consumers own action order. AlertDialog owns confirmation action layout: >640px horizontal buttons may move to another row; <=640px puts the destructive action above Cancel and makes both buttons full width regardless of pointer/hover capability. Button labels remain single-line. Body scrolls when height constrained. To show w/o managing open state, use useImperativeAlertDialog hook: call alert.show(options) + render alert.element in tree.',
+      'AlertDialog confirms destructive/irreversible action (delete, revoke access, discard changes). Implements WAI-ARIA APG Alert Dialog pattern (https://www.w3.org/WAI/ARIA/apg/patterns/alertdialog/): role="alertdialog", aria-labelledby title, aria-describedby description, focus into dialog on open + back to trigger on close, no outside-click dismissal, Escape cancels. Dialog preserves requested width + clamps it to container/dynamic viewport gutters. Generic Dialog footers wrap while consumers own action order. AlertDialog owns confirmation action layout: >640px horizontal buttons may move to another row; <=640px puts the destructive action above Cancel and makes both buttons full width regardless of pointer/hover capability. Button labels remain single-line. Body scrolls when height constrained. Every pointer: both actions tracked as one group like iOS alerts (action under pointer highlights at once, highlight follows pointer between actions, release runs action under pointer, release off both runs nothing); keyboard/AT keep each button click. To show w/o managing open state, use useImperativeAlertDialog hook: call alert.show(options) + render alert.element in tree.',
     bestPractices: [
       {
         guidance: true,

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

@@ -647,6 +647,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 +816,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;

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

@@ -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: {
@@ -418,6 +422,7 @@ function waitForTransition(
 
   let done = false;
   let timer: ReturnType<typeof setTimeout> | null = null;
+  let backstopMs = 0;
   const finish = () => {
     if (done) {
       return;
@@ -431,9 +436,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 +504,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 +515,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)) {
@@ -676,6 +710,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;

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/useMobileKeyboard.ts

@@ -148,6 +148,8 @@ export function useMobileKeyboard({
     }
   }, [isEnabled, isSheetTraveling, sheetRef]);
 
+  // Syncs the on-screen keyboard with the sheet. When a presented sheet closes,
+  // the focused field blurs, so the keyboard closes.
   useEffect(() => {
     if (!isEnabled || !isPresented || isOpen) {
       return;
@@ -165,6 +167,8 @@ export function useMobileKeyboard({
     }
   }, [isEnabled, isOpen, isPresented, sheetRef]);
 
+  // Syncs the body's end inset with the visual viewport, so the on-screen
+  // keyboard does not cover the body.
   useEffect(() => {
     const body = bodyRef.current;
     const sheet = sheetRef.current;

package/src/BottomSheet/useSheetGestures.ts

@@ -699,6 +699,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 +740,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 +760,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 +912,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 +1031,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) {