@astryxdesign/core 0.4.6 → 0.4.7-canary.4c3982f

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

@@ -1 +1 @@
-{"version":3,"file":"useListFocus.d.ts","sourceRoot":"","sources":["../../src/hooks/useListFocus.ts"],"names":[],"mappings":"AAsBA;;;;;GAKG;AACH,MAAM,MAAM,oBAAoB,GAAG,YAAY,GAAG,UAAU,GAAG,MAAM,CAAC;AAEtE;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB;;;;;;;;;;;;;;;;OAgBG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAE1B;;;OAGG;IACH,IAAI,CAAC,EAAE,OAAO,CAAC;IAEf;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,IAAI,CAAC;IAEtB;;;;OAIG;IACH,WAAW,CAAC,EAAE,oBAAoB,CAAC;IAEnC;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IAErB;;;;;;;;;;;OAWG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;IAEhB;;;;;;;;;;;;OAYG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAE5B;;;;;;;;OAQG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB,CAAC,CAAC,SAAS,WAAW,GAAG,WAAW;IACrE;;OAEG;IACH,OAAO,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IAEnC;;OAEG;IACH,aAAa,EAAE,CAAC,CAAC,EAAE,KAAK,CAAC,aAAa,KAAK,IAAI,CAAC;IAEhD;;;;OAIG;IACH,WAAW,EAAE,CAAC,CAAC,EAAE,KAAK,CAAC,UAAU,KAAK,IAAI,CAAC;IAE3C;;OAEG;IACH,SAAS,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAEnC;;OAEG;IACH,UAAU,EAAE,MAAM,OAAO,CAAC;IAE1B;;OAEG;IACH,SAAS,EAAE,MAAM,OAAO,CAAC;IAEzB;;;;;;OAMG;IACH,SAAS,EAAE,CAAC,CAAC,EAAE,KAAK,CAAC,aAAa,KAAK,OAAO,CAAC;IAE/C;;;;;OAKG;IACH,QAAQ,EAAE,MAAM,WAAW,EAAE,CAAC;CAC/B;AA+FD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,WAAW,GAAG,WAAW,EAC9D,OAAO,GAAE,mBAAwB,GAChC,kBAAkB,CAAC,CAAC,CAAC,CAwVvB"}
+{"version":3,"file":"useListFocus.d.ts","sourceRoot":"","sources":["../../src/hooks/useListFocus.ts"],"names":[],"mappings":"AAwBA;;;;;GAKG;AACH,MAAM,MAAM,oBAAoB,GAAG,YAAY,GAAG,UAAU,GAAG,MAAM,CAAC;AAEtE;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB;;;;;;;;;;;;;;;;OAgBG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAE1B;;;OAGG;IACH,IAAI,CAAC,EAAE,OAAO,CAAC;IAEf;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,IAAI,CAAC;IAEtB;;;;OAIG;IACH,WAAW,CAAC,EAAE,oBAAoB,CAAC;IAEnC;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IAErB;;;;;;;;;;;OAWG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;IAEhB;;;;;;;;;;;;OAYG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAE5B;;;;;;;;OAQG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB,CAAC,CAAC,SAAS,WAAW,GAAG,WAAW;IACrE;;OAEG;IACH,OAAO,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IAEnC;;OAEG;IACH,aAAa,EAAE,CAAC,CAAC,EAAE,KAAK,CAAC,aAAa,KAAK,IAAI,CAAC;IAEhD;;;;OAIG;IACH,WAAW,EAAE,CAAC,CAAC,EAAE,KAAK,CAAC,UAAU,KAAK,IAAI,CAAC;IAE3C;;OAEG;IACH,SAAS,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAEnC;;OAEG;IACH,UAAU,EAAE,MAAM,OAAO,CAAC;IAE1B;;OAEG;IACH,SAAS,EAAE,MAAM,OAAO,CAAC;IAEzB;;;;;;OAMG;IACH,SAAS,EAAE,CAAC,CAAC,EAAE,KAAK,CAAC,aAAa,KAAK,OAAO,CAAC;IAE/C;;;;;OAKG;IACH,QAAQ,EAAE,MAAM,WAAW,EAAE,CAAC;CAC/B;AA+FD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,WAAW,GAAG,WAAW,EAC9D,OAAO,GAAE,mBAAwB,GAChC,kBAAkB,CAAC,CAAC,CAAC,CA2VvB"}

package/dist/hooks/useListFocus.js

@@ -14,6 +14,8 @@
  *
  * SYNC: When modified, update:
  * - /packages/core/src/hooks/index.ts
+ * - /packages/core/src/hooks/useListFocus.doc.mjs
+ * - /packages/core/src/hooks/useListFocus.test.tsx
  */
 import { useCallback, useRef } from 'react';
 import { isRtlElement } from "./isRtlElement.js";
@@ -127,7 +129,8 @@ function shouldDeferToCaret(target, key) {
  * - ArrowUp/ArrowLeft: Move to previous item (wraps to last)
  * - Home: Move to first item
  * - End: Move to last item
- * - Escape: Custom callback (e.g., close menu)
+ * - Escape: runs `onEscape` and consumes the key. With no `onEscape` the key
+ *   is left alone, so a surrounding layer can still dismiss on it.
  *
  * By default the hook only *moves* focus and leaves `tabindex` management to
  * the caller. Opt into {@link UseListFocusOptions.hasRovingTabIndex} for a hook
@@ -380,12 +383,15 @@ export function useListFocus(options = {}) {
       return;
     }
 
-    // Escape is handled regardless of orientation. Preserve the historical
-    // behavior of always consuming Escape here (preventDefault) so consumers
-    // that relied on it are unaffected.
+    // Escape is handled regardless of orientation, but only *consumed* when
+    // a handler asked for it: a list with no dismissal to perform must leave
+    // the key to whatever host layer does have one, and those defer to
+    // `defaultPrevented` (see `useFocusTrap`) or to the native popover.
     if (e.key === 'Escape') {
-      e.preventDefault();
-      onEscape?.();
+      if (onEscape) {
+        e.preventDefault();
+        onEscape();
+      }
       return;
     }
     const horizontal = orientation === 'horizontal' || orientation === 'both';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astryxdesign/core",
-  "version": "0.4.6",
+  "version": "0.4.7-canary.4c3982f",
   "displayName": "Astryx Core",
   "description": "The component library. Accessible, themeable React components with built-in spacing, dark mode, and StyleX styling.",
   "author": "Meta Open Source",
@@ -656,6 +656,7 @@
     "react-dom": ">=19.0.0"
   },
   "devDependencies": {
+    "@astryxdesign/cli": "0.4.7-canary.4c3982f",
     "@babel/cli": "^8.0.4",
     "@babel/core": "^7.29.7",
     "@babel/preset-react": "^8.0.1",
@@ -664,8 +665,7 @@
     "@testing-library/dom": "^10.0.0",
     "@testing-library/jest-dom": "^6.6.0",
     "@testing-library/react": "^16.3.2",
-    "rimraf": "^6.0.1",
-    "@astryxdesign/cli": "0.4.6"
+    "rimraf": "^6.0.1"
   },
   "dependencies": {
     "intl-messageformat": "^11.2.9"

package/src/Avatar/Avatar.doc.mjs

@@ -148,7 +148,8 @@ export const docsDense = {
       {guidance: true, description: 'Match size to context: xsm/sm inline, md/lg in lists, xl for profiles.'},
       {guidance: true, description: 'Add a status dot in chat or team views where availability matters.'},
       {guidance: true, description: 'When wrapping Avatar in your own Tooltip or HoverCard, set tooltip={false} so the built-in name tooltip does not overlap yours.'},
-      {guidance: true, description: 'Interactive avatars (href/onClick) need name or alt; without one they warn in development. A status label is not a name.'},
+      {guidance: true, description: 'Interactive avatars (href/onClick) need name or alt; without one they warn in development.'},
+      {guidance: false, description: 'Rely on a status label to name an interactive avatar. "Online" says nothing about where the link goes.'},
       {guidance: false, description: 'Use for logos or product images. Use an image or icon instead.'},
       {guidance: false, description: 'Force a square or custom shape. Avatars are always circular.'},
     ],

package/src/BottomSheet/BottomSheet.tsx

@@ -16,6 +16,7 @@
  *
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/core/src/BottomSheet/BottomSheetPanel.tsx
+ * - /packages/core/src/BottomSheet/BottomSheetEdgeTint.tsx
  * - /packages/core/src/BottomSheet/BottomSheet.doc.mjs
  * - /packages/core/src/BottomSheet/BottomSheet.test.tsx
  * - /packages/core/src/BottomSheet/BottomSheetSwitcher.tsx
@@ -43,6 +44,7 @@ import {
   type BottomSheetPanelMotion,
   type BottomSheetPanelState,
 } from './BottomSheetPanel';
+import {BottomSheetEdgeTint} from './BottomSheetEdgeTint';
 import {
   BottomSheetSwitcherContext,
   type BottomSheetSwitcherContextValue,
@@ -93,6 +95,20 @@ const styles = stylex.create({
       },
     },
   },
+  /**
+   * The dim leaves with the sheet, on a curve that matches.
+   *
+   * A fade covers no distance, so the decelerate token front-loads its
+   * progress and simply ends it early: `--ease-standard` puts the scrim at 90%
+   * faded in 163ms of a 410ms close, leaving an undimmed page under a sheet
+   * that is still sliding across it. `linear` spends the duration it is given.
+   * Same reasoning the touch date picker's surface swap already carries.
+   */
+  scrimClosing: {
+    '::backdrop': {
+      transitionTimingFunction: 'linear',
+    },
+  },
   positioner: {
     position: 'absolute',
     insetInline: 0,
@@ -327,6 +343,7 @@ function StandaloneBottomSheet({
         styles.dialog,
         shouldPresent && styles.dialogOpen,
         hasScrim && styles.scrim,
+        hasScrim && !isOpen && isPresented && styles.scrimClosing,
         !hasScrim && styles.dialogNonModal,
       )}
       ref={dialogRef}
@@ -355,6 +372,8 @@ function StandaloneBottomSheet({
           {children}
         </BottomSheetPanel>
       </div>
+      {/* A modal sheet's ::backdrop already answers Safari's edge sampler. */}
+      {hasScrim ? null : <BottomSheetEdgeTint />}
     </dialog>
   );
 }

package/src/BottomSheet/BottomSheetEdgeTint.test.tsx

@@ -0,0 +1,225 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file BottomSheetEdgeTint.test.tsx
+ * @input Uses vitest, @testing-library/react, BottomSheet, BottomSheetSwitcher
+ * @output Tests which sheets carry the iOS Safari bottom edge tint, and pins
+ *   the declarations WebKit's edge sampler reads
+ * @position Core testing; validates BottomSheetEdgeTint.tsx and its two hosts
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/BottomSheet/BottomSheetEdgeTint.tsx
+ */
+
+import {describe, it, expect, vi, beforeEach, afterEach} from 'vitest';
+import {render} from '@testing-library/react';
+import {BottomSheet} from './BottomSheet';
+import {BottomSheetSwitcher} from './BottomSheetSwitcher';
+
+// jsdom doesn't implement <dialog> open/close or pointer capture; stub them.
+beforeEach(() => {
+  HTMLDialogElement.prototype.showModal = vi.fn(function (
+    this: HTMLDialogElement,
+  ) {
+    this.setAttribute('open', '');
+  });
+  HTMLDialogElement.prototype.show = vi.fn(function (this: HTMLDialogElement) {
+    this.setAttribute('open', '');
+  });
+  HTMLDialogElement.prototype.close = vi.fn(function (this: HTMLDialogElement) {
+    this.removeAttribute('open');
+  });
+  if (!Element.prototype.setPointerCapture) {
+    Element.prototype.setPointerCapture = vi.fn();
+    Element.prototype.releasePointerCapture = vi.fn();
+  }
+  vi.stubGlobal(
+    'matchMedia',
+    vi.fn().mockReturnValue({
+      matches: false,
+      media: '',
+      onchange: null,
+      addEventListener: vi.fn(),
+      removeEventListener: vi.fn(),
+      addListener: vi.fn(),
+      removeListener: vi.fn(),
+      dispatchEvent: vi.fn(),
+    }),
+  );
+  vi.stubGlobal(
+    'requestAnimationFrame',
+    vi.fn((callback: FrameRequestCallback) => {
+      callback(0);
+      return 1;
+    }),
+  );
+  vi.stubGlobal('cancelAnimationFrame', vi.fn());
+});
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+});
+
+function tints(): ReadonlyArray<Element> {
+  return Array.from(document.querySelectorAll('[data-sheet-edge-tint]'));
+}
+
+async function edgeTintSource(): Promise<string> {
+  const tint = (await fullSource()).match(/\n {2}tint: \{([\s\S]*?)\n {2}\},/);
+  expect(tint).not.toBeNull();
+  return tint![1];
+}
+
+/** The tint's declarations with its explanatory comments stripped out. */
+async function edgeTintDeclarations(): Promise<string> {
+  return (await edgeTintSource())
+    .split('\n')
+    .filter(line => !line.trim().startsWith('//'))
+    .join('\n');
+}
+
+async function fullSource(): Promise<string> {
+  const fs = await import('fs');
+  const path = await import('path');
+  return fs.readFileSync(
+    path.resolve(__dirname, './BottomSheetEdgeTint.tsx'),
+    'utf-8',
+  );
+}
+
+describe('BottomSheetEdgeTint', () => {
+  it('gives a non-modal sheet an edge tint to colour the iOS toolbar strip', () => {
+    render(
+      <BottomSheet
+        isOpen
+        onOpenChange={() => {}}
+        hasScrim={false}
+        label="Place details">
+        Content
+      </BottomSheet>,
+    );
+    expect(tints()).toHaveLength(1);
+  });
+
+  // A modal sheet's ::backdrop is a case WebKit's sampler handles on its own,
+  // so a second sampling target there would only fight it.
+  it('leaves a modal sheet to its ::backdrop', () => {
+    render(
+      <BottomSheet isOpen onOpenChange={() => {}} label="Place details">
+        Content
+      </BottomSheet>,
+    );
+    expect(tints()).toHaveLength(0);
+  });
+
+  it('renders the tint inside the dialog, so it unmounts with the sheet', () => {
+    const {rerender} = render(
+      <BottomSheet
+        isOpen
+        onOpenChange={() => {}}
+        hasScrim={false}
+        label="Place details">
+        Content
+      </BottomSheet>,
+    );
+    const [tint] = tints();
+    expect(tint?.closest('dialog')).not.toBeNull();
+
+    rerender(<div />);
+    expect(tints()).toHaveLength(0);
+  });
+
+  // The switcher owns one shared dialog for the whole flow, so the tint
+  // belongs to that dialog and must not be minted per child sheet.
+  it('gives a non-modal switcher flow exactly one tint', () => {
+    render(
+      <BottomSheetSwitcher
+        activeSheet="comment"
+        hasScrim={false}
+        onActiveSheetChange={() => {}}>
+        <BottomSheet sheetId="comment" label="Add a comment">
+          Comment
+        </BottomSheet>
+        <BottomSheet sheetId="confirmation" label="Confirmation">
+          Confirmation
+        </BottomSheet>
+      </BottomSheetSwitcher>,
+    );
+    expect(tints()).toHaveLength(1);
+  });
+
+  it('leaves a modal switcher flow to its ::backdrop', () => {
+    render(
+      <BottomSheetSwitcher activeSheet="comment" onActiveSheetChange={() => {}}>
+        <BottomSheet sheetId="comment" label="Add a comment">
+          Comment
+        </BottomSheet>
+      </BottomSheetSwitcher>,
+    );
+    expect(tints()).toHaveLength(0);
+  });
+
+  it('keeps the tint out of the accessibility tree and out of hit testing', async () => {
+    render(
+      <BottomSheet
+        isOpen
+        onOpenChange={() => {}}
+        hasScrim={false}
+        label="Place details">
+        Content
+      </BottomSheet>,
+    );
+    const [tint] = tints();
+    expect(tint?.getAttribute('aria-hidden')).toBe('true');
+    expect(tint?.textContent).toBe('');
+    expect(await edgeTintSource()).toContain("pointerEvents: 'none'");
+  });
+
+  // Every declaration below is load-bearing for a heuristic that lives in
+  // WebKit, not in this repo, and none of it is observable in jsdom or in any
+  // engine without retractable browser chrome — so it is asserted on the style
+  // definition, the way BottomSheetPanel pins its handle gradient.
+  describe('the declarations WebKit samples', () => {
+    it('is fixed and flush with the bottom edge of the viewport', async () => {
+      const tint = await edgeTintSource();
+      // Only a fixed or sticky box is a candidate, and only a box flush with
+      // the edge is the one Safari hit tests.
+      expect(tint).toContain("position: 'fixed'");
+      expect(tint).toContain('insetBlockEnd: 0');
+      expect(tint).toContain('insetInline: 0');
+    });
+
+    it('clears the 10px floor below which WebKit ignores the declared colour', async () => {
+      const height = (await fullSource()).match(
+        /const SAMPLE_HEIGHT_PX = (\d+);/,
+      );
+      expect(height).not.toBeNull();
+      expect(Number(height![1])).toBeGreaterThan(10);
+      expect(await edgeTintSource()).toContain(
+        'height: `${SAMPLE_HEIGHT_PX}px`',
+      );
+    });
+
+    it('declares the sheet surface colour, so the strip matches the sheet', async () => {
+      expect(await edgeTintSource()).toContain(
+        "backgroundColor: colorVars['--color-background-surface']",
+      );
+    });
+
+    // visibility: hidden, display: none and a low opacity all disqualify the
+    // element from sampling. A mask does not, which is the only reason the
+    // strip can be both readable by Safari and invisible to the user.
+    it('hides itself with a mask rather than with visibility or opacity', async () => {
+      const tint = await edgeTintDeclarations();
+      expect(tint).toContain(
+        "maskImage: 'linear-gradient(transparent, transparent)'",
+      );
+      expect(tint).toContain(
+        "WebkitMaskImage: 'linear-gradient(transparent, transparent)'",
+      );
+      expect(tint).not.toContain('visibility');
+      expect(tint).not.toContain('opacity');
+      expect(tint).not.toContain("display: 'none'");
+    });
+  });
+});

package/src/BottomSheet/BottomSheetEdgeTint.tsx

@@ -0,0 +1,82 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file BottomSheetEdgeTint.tsx
+ * @input Uses StyleX and core color tokens
+ * @output Exports BottomSheetEdgeTint, an internal decorative element
+ * @position Private helper rendered inside a non-modal BottomSheet dialog
+ *
+ * iOS 26 Safari dropped `<meta name="theme-color">` and instead derives the
+ * colour it paints behind its translucent toolbars by sampling the page: it
+ * hit tests a point just inside each viewport edge, walks up to the nearest
+ * `fixed`/`sticky` ancestor, and extends that element's declared
+ * `background-color` into the browser chrome.
+ *
+ * A modal sheet is served by that heuristic already — WebKit has a dedicated
+ * branch for a dialog's `::backdrop`. A non-modal sheet is not: the nearest
+ * fixed ancestor of the panel is the sheet's own full-viewport `<dialog>`,
+ * which is transparent and viewport-sized, and WebKit answers a viewport-sized
+ * candidate by *keeping the colour it already had* — the host page's. The page
+ * then shows through behind the address bar while the sheet covers the screen
+ * above it.
+ *
+ * This element gives the heuristic something unambiguous to sample: fixed,
+ * full width, flush with the bottom edge, taller than WebKit's 10px minimum
+ * for reading a declared colour, and painted in the sheet's own surface
+ * colour. It is masked out so it never renders for the user; Safari reads the
+ * computed style, not the painted pixels.
+ *
+ * Everywhere else it is inert decoration.
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/BottomSheet/BottomSheet.tsx
+ * - /packages/core/src/BottomSheet/BottomSheetSwitcher.tsx
+ * - /packages/core/src/BottomSheet/BottomSheetEdgeTint.test.tsx
+ */
+
+import * as stylex from '@stylexjs/stylex';
+import {colorVars} from '../theme/tokens.stylex';
+
+/**
+ * WebKit ignores the declared `background-color` of a sampled box thinner than
+ * 10px and falls back to sampling painted pixels, which a masked element has
+ * none of. 12px clears that floor with room to spare and is still far below
+ * the ~40px of chrome it colours.
+ */
+const SAMPLE_HEIGHT_PX = 12;
+
+const styles = stylex.create({
+  tint: {
+    position: 'fixed',
+    insetInline: 0,
+    insetBlockEnd: 0,
+    height: `${SAMPLE_HEIGHT_PX}px`,
+    backgroundColor: colorVars['--color-background-surface'],
+    // Above the panel so the edge hit test lands here, and never in the way of
+    // a touch that was meant for the sheet.
+    zIndex: 2,
+    pointerEvents: 'none',
+    // Invisible to the user. WebKit's sampler checks `visibility` and
+    // `opacity` — either would disqualify the element — but not `mask`, so
+    // this hides the strip while leaving the colour readable. Without it the
+    // strip would show as a hairline under the panel as the sheet slides out.
+    maskImage: 'linear-gradient(transparent, transparent)',
+    WebkitMaskImage: 'linear-gradient(transparent, transparent)',
+  },
+});
+
+/**
+ * Colours the iOS Safari toolbar strip below a non-modal sheet. Renders
+ * nothing visible; see the file header for why it exists.
+ */
+export function BottomSheetEdgeTint() {
+  return (
+    <div
+      {...stylex.props(styles.tint)}
+      data-sheet-edge-tint=""
+      aria-hidden="true"
+    />
+  );
+}

package/src/BottomSheet/BottomSheetPanel.test.tsx

@@ -328,4 +328,70 @@ describe('BottomSheetPanel', () => {
       "backgroundColor: colorVars['--color-background-surface']",
     );
   });
+
+  /**
+   * The exit is not the entrance played backwards.
+   *
+   * `--ease-standard` is a decelerate curve: on it the sheet was half gone in
+   * 59ms of a 410ms transition and 90% gone in 163ms, so the close was over
+   * before it could be seen. The closing state therefore carries its own
+   * accelerating curve, and only the closing state does.
+   */
+  it('closes on an accelerating curve of its own, not the entrance timing', () => {
+    const declarationsFor = (element: HTMLElement) => {
+      const classes = new Set(element.className.split(/\s+/));
+      const out: string[] = [];
+      for (const styleSheet of Array.from(document.styleSheets)) {
+        let rules: CSSRuleList;
+        try {
+          rules = styleSheet.cssRules;
+        } catch {
+          continue;
+        }
+        for (const rule of Array.from(rules)) {
+          const selector = (rule as CSSStyleRule).selectorText;
+          const owner = selector?.match(/^\.([\w-]+)/)?.[1];
+          if (owner != null && classes.has(owner)) {
+            out.push(rule.cssText);
+          }
+        }
+      }
+      return out.join('\n');
+    };
+
+    const {container: closing} = render(
+      <BottomSheetPanel
+        state={{kind: 'exiting'}}
+        height="hug"
+        onDismiss={() => {}}
+        onScrimOpacity={() => {}}>
+        Panel content
+      </BottomSheetPanel>,
+    );
+    const closingRules = declarationsFor(
+      closing.querySelector('.astryx-bottom-sheet') as HTMLElement,
+    );
+    // An accelerating curve: no vertical rise at the start (y1 = 0), so the
+    // travel lands inside the duration instead of ahead of it.
+    expect(closingRules).toContain(
+      'transition-timing-function: cubic-bezier(.3,0,.6,.6)',
+    );
+
+    const {container: resting} = render(
+      <BottomSheetPanel
+        state={{kind: 'open', entering: false}}
+        height="hug"
+        onDismiss={() => {}}
+        onScrimOpacity={() => {}}>
+        Panel content
+      </BottomSheetPanel>,
+    );
+    const restingRules = declarationsFor(
+      resting.querySelector('.astryx-bottom-sheet') as HTMLElement,
+    );
+    expect(restingRules).toContain(
+      'transition-timing-function: var(--ease-standard)',
+    );
+    expect(restingRules).not.toContain('cubic-bezier(.3,0,.6,.6)');
+  });
 });

package/src/BottomSheet/BottomSheetPanel.tsx

@@ -149,8 +149,27 @@ const styles = stylex.create({
       transitionDuration: '0.01s',
     },
   },
+  /**
+   * The exit is its own motion, not the entrance played backwards.
+   *
+   * `--ease-standard` is `cubic-bezier(0.24, 1, 0.4, 1)`, a decelerate curve:
+   * it spends its speed immediately and coasts. That is right for an entrance,
+   * where the sheet arrives fast and settles, and wrong for an exit. Measured
+   * on device, it put the sheet half off-screen in 59ms of a 410ms close and
+   * 90% off in 163ms -- the travel is over before the eye has followed it, and
+   * the rest of the duration moves pixels already below the fold.
+   *
+   * An exit accelerates instead: away from rest, gathering speed, quickest as
+   * it leaves the screen. The curve is deliberately gentle rather than a hard
+   * `ease-in` -- it is moving within ~50ms, so the close reads as one
+   * departure rather than a hesitation and a snap. The duration is the
+   * entrance's own band, so only the curve differs between the two
+   * directions; a shorter band leaves too little visible travel once a theme
+   * scales the motion scale down (neutral's medium is 300ms against 410ms).
+   */
   sheetClosing: {
     transform: 'translateY(100%)',
+    transitionTimingFunction: 'cubic-bezier(0.3, 0, 0.6, 0.6)',
   },
   sheetFading: {
     opacity: 0,

package/src/BottomSheet/BottomSheetSwitcher.tsx

@@ -22,6 +22,7 @@
  *
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/core/src/BottomSheet/BottomSheet.tsx
+ * - /packages/core/src/BottomSheet/BottomSheetEdgeTint.tsx
  * - /packages/core/src/BottomSheet/BottomSheetSwitcher.doc.mjs
  * - /packages/core/src/BottomSheet/BottomSheetSwitcher.test.tsx
  * - /packages/core/src/BottomSheet/index.ts
@@ -51,6 +52,7 @@ import {
   useScrollLock,
 } from '../hooks';
 import {composeEventHandlers, mergeProps, mergeRefs} from '../utils';
+import {BottomSheetEdgeTint} from './BottomSheetEdgeTint';
 import {
   BottomSheetSwitcherContext,
   type BottomSheetSwitcherContextValue,
@@ -103,6 +105,14 @@ const styles = stylex.create({
       },
     },
   },
+  // The flow's dim leaves with its last panel. Same rule, same reasoning, as
+  // a standalone sheet's -- see `scrimClosing` in BottomSheet.tsx. A handoff
+  // between two sheets is not a close, and keeps the entrance curve.
+  scrimClosing: {
+    '::backdrop': {
+      transitionTimingFunction: 'linear',
+    },
+  },
 });
 
 type RetainedSheetPhase = 'covered' | 'aligning' | 'fading' | 'exiting';
@@ -593,6 +603,7 @@ export function BottomSheetSwitcher({
     styles.dialog,
     isFlowVisible && styles.dialogOpen,
     hasScrim && styles.scrim,
+    hasScrim && isFlowVisible && activeSheet == null && styles.scrimClosing,
     !hasScrim && styles.dialogNonModal,
     xstyle,
   );
@@ -620,6 +631,8 @@ export function BottomSheetSwitcher({
           ? {role: 'alertdialog'}
           : undefined)}>
         {children}
+        {/* A modal flow's ::backdrop already answers Safari's edge sampler. */}
+        {hasScrim ? null : <BottomSheetEdgeTint />}
       </dialog>
     </BottomSheetSwitcherContext>
   );

package/src/BottomSheet/useSheetGestures.test.ts

@@ -530,6 +530,33 @@ describe('useSheetGestures', () => {
       expect(hook.result.current.dragOffset).toBe(40);
     });
 
+    /**
+     * A finger is never still. Tapping a control inside the sheet drifts a
+     * pixel or two, and with no slop that drift promoted to a sheet drag —
+     * which wrote `transition: none` onto the panel across the release, so the
+     * close the tap triggered cut instead of animating. That is the "the sheet
+     * closes with no animation" report: only on a tap, and only on a tap
+     * inside the sheet (the scrim never arms a drag).
+     */
+    it('treats a few pixels of finger drift as a tap, not a drag', () => {
+      const {hook} = setup({snapHeights: () => [200]});
+      const body = makeBody(0); // at the top, where a pull-down would promote
+      bodyDown(hook, 0, 0, body);
+      bodyMove(hook, 3, 40, body); // the drift of a finger tapping a button
+      expect(hook.result.current.isDragging).toBe(false);
+      // and nothing suppressed the panel's transition, so a close that lands
+      // now still animates
+      expect(hook.result.current.contentProps.style.transition).toBeUndefined();
+    });
+
+    it('still promotes once the pull passes the tap slop', () => {
+      const {hook} = setup({snapHeights: () => [200]});
+      const body = makeBody(0);
+      bodyDown(hook, 0, 0, body);
+      bodyMove(hook, 9, 40, body); // just past the 8px slop
+      expect(hook.result.current.isDragging).toBe(true);
+    });
+
     it('does not hijack scrolling when the body is scrolled down', () => {
       const {hook} = setup({snapHeights: () => [200]});
       const body = makeBody(120); // scrolled, not at the top