@astryxdesign/core 0.4.6 → 0.4.7-canary.20bae6c

package/src/AppShell/AppShell.tsx

@@ -50,7 +50,7 @@ import {AppShellMobileContext} from './AppShellMobileContext';
 import type {AppShellMobileContextValue} from './AppShellMobileContext';
 import type {SpacingStep} from '../utils/types';
 import type {BaseProps} from '../BaseProps';
-import {mergeProps, mergeRefs, isRenderable} from '../utils';
+import {mergeProps, isRenderable} from '../utils';
 import {focusOutlineProps} from '../utils/focusOutline.stylex';
 import {useMediaQuery} from '../hooks/useMediaQuery';
 import {observeResize, unobserveResize} from '../utils/sharedResizeObserver';
@@ -58,6 +58,7 @@ import {themeProps} from '../utils/themeProps';
 import {useTranslator} from '../i18n';
 import type {AppShellVariantMap} from './index';
 
+import {useMergedRefs} from '../hooks/useMergedRefs';
 const HasActivity = typeof React.Activity !== 'undefined';
 const ActivityWrapper = HasActivity
   ? ({
@@ -792,7 +793,7 @@ export function AppShell({
     <AppShellMobileContext value={mobileContextValue}>
       <div
         {...rest}
-        ref={mergeRefs(ref, shellRef)}
+        ref={useMergedRefs(ref, shellRef)}
         data-testid={dataTestId}
         {...mergeProps(
           themeProps('app-shell', {variant}),

package/src/AspectRatio/AspectRatio.doc.mjs

@@ -16,6 +16,7 @@ export const docs = {
       {guidance: true, description: 'Use `fit="cover"` for images and video so the component sizes the child; the child should not repeat `width`/`height`/`objectFit` styles.'},
       {guidance: true, description: 'Pass one child. With `fit` set, every direct child is stretched to fill the box, so put an overlay or caption inside a single wrapper child rather than passing it as a second child.'},
       {guidance: true, description: 'Describe media children with `alt`, or `alt=""` when the image is decorative. AspectRatio adds no role and no accessible name of its own, so the child carries the whole accessible description.'},
+      {guidance: true, description: 'For a breakpoint-dependent ratio, override the ratio responsively: pass an `aspectRatio` rule via `xstyle` (StyleX), or override `aspect-ratio` from your own unlayered CSS under a `@media`/`@container` rule — component styles live in the `astryx-base` cascade layer, so unlayered consumer CSS wins. Give an `xstyle` rule a `default` branch alongside the conditional one (`{default: 3, \'@container ...\': \'3 / 2\'}`) — with only the conditional branch the ratio is unset outside the query and the box collapses.'},
       {guidance: false, description: 'Use for general layout containers; use standard layout components instead.'},
       {guidance: false, description: 'Nest AspectRatio containers; one level is sufficient.'},
       {guidance: false, description: 'Constrain the height on its own. The width comes from the container, so a `height` or `maxHeight` by itself clamps the box off ratio; pair it with `width: "auto"` to size from the height instead.'},
@@ -30,7 +31,7 @@ export const docs = {
     {
       name: 'ratio',
       type: 'number',
-      description: 'Aspect ratio as width/height (e.g. 16/9, 1).',
+      description: 'Aspect ratio as width/height (e.g. 16/9, 1). Emitted as a class-level declaration (never inline), so `xstyle` rules or unlayered consumer CSS can override it responsively.',
       required: true,
     },
     {
@@ -83,6 +84,7 @@ export const docsZh = {
       {guidance: true, description: 'Use `fit="cover"` for images and video so the component sizes the child; the child should not repeat `width`/`height`/`objectFit` styles.'},
       {guidance: true, description: 'Pass one child. With `fit` set, every direct child is stretched to fill the box, so put an overlay or caption inside a single wrapper child rather than passing it as a second child.'},
       {guidance: true, description: 'Describe media children with `alt`, or `alt=""` when the image is decorative. AspectRatio adds no role and no accessible name of its own, so the child carries the whole accessible description.'},
+      {guidance: true, description: 'For a breakpoint-dependent ratio, override the ratio responsively: pass an `aspectRatio` rule via `xstyle` (StyleX), or override `aspect-ratio` from your own unlayered CSS under a `@media`/`@container` rule — component styles live in the `astryx-base` cascade layer, so unlayered consumer CSS wins. Give an `xstyle` rule a `default` branch alongside the conditional one (`{default: 3, \'@container ...\': \'3 / 2\'}`) — with only the conditional branch the ratio is unset outside the query and the box collapses.'},
       {guidance: false, description: 'Use for general layout containers; use standard layout components instead.'},
       {guidance: false, description: 'Nest AspectRatio containers; one level is sufficient.'},
       {guidance: false, description: 'Constrain the height on its own. The width comes from the container, so a `height` or `maxHeight` by itself clamps the box off ratio; pair it with `width: "auto"` to size from the height instead.'},
@@ -94,7 +96,7 @@ export const docsZh = {
     ],
   },
   props: [
-    {name: 'ratio', type: 'number', description: '宽高比，以宽/高表示（例如 16/9、1）。', required: true},
+    {name: 'ratio', type: 'number', description: '宽高比，以宽/高表示（例如 16/9、1）。以类级声明输出（非内联样式），可通过 `xstyle` 规则或未分层的（unlayered）消费者 CSS 做响应式覆盖。', required: true},
     {
       name: 'shape',
       type: "'rectangle' | 'ellipse'",
@@ -133,6 +135,7 @@ export const docsDense = {
       {guidance: true, description: 'Use `fit="cover"` for images and video so the component sizes the child; the child should not repeat `width`/`height`/`objectFit` styles.'},
       {guidance: true, description: 'Pass one child. With `fit` set, every direct child is stretched to fill the box, so put an overlay or caption inside a single wrapper child rather than passing it as a second child.'},
       {guidance: true, description: 'Describe media children with `alt`, or `alt=""` when the image is decorative. AspectRatio adds no role and no accessible name of its own, so the child carries the whole accessible description.'},
+      {guidance: true, description: 'For a breakpoint-dependent ratio, override the ratio responsively: pass an `aspectRatio` rule via `xstyle` (StyleX), or override `aspect-ratio` from your own unlayered CSS under a `@media`/`@container` rule — component styles live in the `astryx-base` cascade layer, so unlayered consumer CSS wins. Give an `xstyle` rule a `default` branch alongside the conditional one (`{default: 3, \'@container ...\': \'3 / 2\'}`) — with only the conditional branch the ratio is unset outside the query and the box collapses.'},
       {guidance: false, description: 'Use for general layout containers; use standard layout components instead.'},
       {guidance: false, description: 'Nest AspectRatio containers; one level is sufficient.'},
       {guidance: false, description: 'Constrain the height on its own. The width comes from the container, so a `height` or `maxHeight` by itself clamps the box off ratio; pair it with `width: "auto"` to size from the height instead.'},
@@ -144,7 +147,7 @@ export const docsDense = {
     ],
   },
   propDescriptions: {
-    ratio: 'width/height ratio (e.g. 16/9, 1)',
+    ratio: 'width/height ratio (e.g. 16/9, 1); class-level declaration (never inline) so xstyle/unlayered-CSS @container overrides win',
     shape: "container shape: 'rectangle' (default) | 'ellipse' (circle at ratio 1)",
     fit: "child layout: 'cover' fill+crop | 'contain' fill+letterbox | 'center' natural size; omitted = child styles itself",
     children: 'content positioned absolutely to fill container',

package/src/AspectRatio/AspectRatio.test.tsx

@@ -13,6 +13,20 @@ import {describe, it, expect, vi, beforeAll} from 'vitest';
 import {render, screen} from '@testing-library/react';
 import {AspectRatio} from './AspectRatio';
 
+/**
+ * The ratio compiles to a class-level `aspect-ratio: var(--x-aspectRatio)`
+ * declaration with the value carried by a CSS variable (so xstyle/@media
+ * and unlayered consumer CSS overrides can win). `--x-aspectRatio` is the
+ * debug-mode variable name emitted for the `aspectRatio` property.
+ */
+function ratioVar(el: HTMLElement): string {
+  return el.style.getPropertyValue('--x-aspectRatio');
+}
+
+function ratioValue(ratio: number): string {
+  return String(ratio);
+}
+
 describe('AspectRatio', () => {
   it('renders with correct aspect ratio', () => {
     render(
@@ -22,7 +36,7 @@ describe('AspectRatio', () => {
     );
     const element = screen.getByTestId('aspect-ratio');
     expect(element).toBeInTheDocument();
-    expect(element.style.aspectRatio).toBe(String(16 / 9));
+    expect(ratioVar(element)).toBe(ratioValue(16 / 9));
   });
 
   it('children fill the container', () => {
@@ -47,7 +61,7 @@ describe('AspectRatio', () => {
       </AspectRatio>,
     );
     const element = screen.getByTestId('aspect-ratio');
-    expect(element.style.aspectRatio).toBe(String(ratio));
+    expect(ratioVar(element)).toBe(ratioValue(ratio));
   });
 
   it('renders with 4:3 ratio', () => {
@@ -58,7 +72,7 @@ describe('AspectRatio', () => {
       </AspectRatio>,
     );
     const element = screen.getByTestId('aspect-ratio');
-    expect(element.style.aspectRatio).toBe(String(ratio));
+    expect(ratioVar(element)).toBe(ratioValue(ratio));
   });
 
   it('renders with 1:1 square ratio', () => {
@@ -68,7 +82,7 @@ describe('AspectRatio', () => {
       </AspectRatio>,
     );
     const element = screen.getByTestId('aspect-ratio');
-    expect(element.style.aspectRatio).toBe('1');
+    expect(ratioVar(element)).toBe(ratioValue(1));
   });
 
   it('renders with 21:9 ultrawide ratio', () => {
@@ -79,7 +93,7 @@ describe('AspectRatio', () => {
       </AspectRatio>,
     );
     const element = screen.getByTestId('aspect-ratio');
-    expect(element.style.aspectRatio).toBe(String(ratio));
+    expect(ratioVar(element)).toBe(ratioValue(ratio));
   });
 
   it('renders an ellipse that respects the ratio (circle at 1:1)', () => {
@@ -89,7 +103,7 @@ describe('AspectRatio', () => {
       </AspectRatio>,
     );
     const element = screen.getByTestId('aspect-ratio');
-    expect(element.style.aspectRatio).toBe('1');
+    expect(ratioVar(element)).toBe(ratioValue(1));
     expect(element.className).toContain('ellipse');
   });
 
@@ -101,7 +115,7 @@ describe('AspectRatio', () => {
     );
     const element = screen.getByTestId('aspect-ratio');
     // Ratio is preserved — the ellipse does not force 1:1.
-    expect(element.style.aspectRatio).toBe(String(16 / 9));
+    expect(ratioVar(element)).toBe(ratioValue(16 / 9));
     expect(element.className).toContain('ellipse');
   });
 
@@ -112,7 +126,7 @@ describe('AspectRatio', () => {
       </AspectRatio>,
     );
     const element = screen.getByTestId('aspect-ratio');
-    expect(element.style.aspectRatio).toBe('1');
+    expect(ratioVar(element)).toBe(ratioValue(1));
     expect(element.className).toContain('rectangle');
     // No ellipse border-radius when shape is the default rectangle
     expect(element.style.borderRadius).toBe('');
@@ -177,6 +191,38 @@ describe('AspectRatio', () => {
     expect(video).toBeInTheDocument();
   });
 
+  describe('responsive ratio', () => {
+    it('emits the ratio as a class-level declaration, not an inline style', () => {
+      render(
+        <AspectRatio ratio={3 / 1} data-testid="aspect-ratio">
+          <div>Hero</div>
+        </AspectRatio>,
+      );
+      const element = screen.getByTestId('aspect-ratio');
+      // No inline aspect-ratio — the declaration lives in a class reading a
+      // CSS variable, so @media/@container rules (via xstyle, or via
+      // unlayered consumer CSS beating the astryx-base layer) can override
+      // it.
+      expect(element.style.aspectRatio).toBe('');
+      expect(ratioVar(element)).toBe(ratioValue(3 / 1));
+    });
+
+    it('lets a consumer inline style win over the class-level ratio', () => {
+      render(
+        <AspectRatio
+          ratio={3 / 1}
+          style={{aspectRatio: '3 / 2'}}
+          data-testid="aspect-ratio">
+          <div>Hero</div>
+        </AspectRatio>,
+      );
+      const element = screen.getByTestId('aspect-ratio');
+      // The consumer's style prop passes through untouched (it is no longer
+      // merged with a component-owned inline aspect-ratio).
+      expect(element.style.aspectRatio).toBe('3 / 2');
+    });
+  });
+
   describe('fit', () => {
     it('marks the child\'s direct parent with data-astryx-aspect-ratio-override for fit="cover"', () => {
       render(
@@ -277,7 +323,7 @@ describe('AspectRatio', () => {
   });
 
   describe('style merging', () => {
-    it('keeps the consumer style and applies the ratio over it', () => {
+    it('keeps the consumer style and lets an inline ratio win', () => {
       render(
         <AspectRatio
           ratio={16 / 9}
@@ -288,7 +334,8 @@ describe('AspectRatio', () => {
       );
       const element = screen.getByTestId('aspect-ratio');
       expect(element.style.opacity).toBe('0.5');
-      expect(element.style.aspectRatio).toBe(String(16 / 9));
+      expect(element.style.aspectRatio).toBe('3 / 1');
+      expect(ratioVar(element)).toBe(ratioValue(16 / 9));
     });
 
     it('keeps a consumer className beside the theme target', () => {

package/src/AspectRatio/AspectRatio.tsx

@@ -43,6 +43,25 @@ export interface AspectRatioProps extends BaseProps<HTMLDivElement> {
   ref?: React.Ref<HTMLDivElement>;
   /**
    * The aspect ratio as width/height (e.g., 16/9 = 1.777..., 4/3 = 1.333..., 1 for square).
+   *
+   * The ratio is emitted as a class-level declaration — never an inline
+   * style — so it can be made responsive:
+   * - StyleX consumers pass an `aspect-ratio` rule via `xstyle`, including
+   *   under `@media`/`@container` conditions.
+   * - Plain-CSS/Tailwind consumers override `aspect-ratio` from their own
+   *   (unlayered) rules: the compiled component styles live in the
+   *   `astryx-base` cascade layer, and unlayered CSS wins over layered
+   *   rules regardless of specificity.
+   *
+   * @example
+   * ```
+   * // 3:1 hero that becomes 3:2 when its container stacks
+   * <AspectRatio ratio={3 / 1} className="gallery-hero">…</AspectRatio>
+   *
+   * // CSS: @container gallery (max-width: 720px) {
+   * //   .gallery-hero { aspect-ratio: 3 / 2; }
+   * // }
+   * ```
    */
   ratio: number;
 
@@ -132,6 +151,20 @@ const styles = stylex.create({
   },
 });
 
+// The ratio compiles to a CSS variable + a class-level declaration
+// (aspect-ratio: var(--x)) instead of a raw inline style, so consumer
+// overrides — `xstyle` rules, including ones inside @media/@container
+// queries — can still win. A raw inline `aspect-ratio` would beat any class
+// (same rationale as Grid's dynamic track values). Non-StyleX consumers
+// don't need a dedicated hook: the compiled declaration sits in the
+// `astryx-base` cascade layer, so any unlayered consumer rule wins
+// regardless of specificity.
+const dynamicStyles = stylex.create({
+  ratio: (ratio: number) => ({
+    aspectRatio: ratio,
+  }),
+});
+
 /**
  * AspectRatio component for maintaining a specific aspect ratio for its children.
  *
@@ -147,6 +180,11 @@ const styles = stylex.create({
  * `ratio={1}` or an oval at other ratios. Both shapes respect the provided
  * `ratio`.
  *
+ * The ratio is a class-level declaration (not an inline style), so it can be
+ * overridden responsively — via `xstyle` for StyleX consumers, or with a
+ * plain unlayered `aspect-ratio` rule for plain-CSS consumers (component
+ * styles live in the `astryx-base` cascade layer, which unlayered CSS beats).
+ *
  * Sizing: the box takes its width from its container and derives its height
  * from the ratio, so it needs an ancestor with a definite width. Two
  * consequences are worth knowing. Constraining only the height (`height` or
@@ -188,11 +226,12 @@ export function AspectRatio({
         themeProps('aspect-ratio', {shape}),
         stylex.props(
           styles.container,
+          dynamicStyles.ratio(ratio),
           shape === 'ellipse' && styles.ellipse,
           xstyle,
         ),
         className,
-        {...style, aspectRatio: ratio},
+        style,
       )}
       {...props}>
       {/* The marker attribute carries the fit value so the reset.css child

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/AvatarGroup/AvatarGroup.tsx

@@ -28,7 +28,7 @@ import {useId, useMemo, useState, type ReactNode} from 'react';
 import type {BaseProps} from '../BaseProps';
 import {resolveSize, type AvatarSize} from '../Avatar';
 import * as stylex from '@stylexjs/stylex';
-import {mergeProps, mergeRefs} from '../utils';
+import {mergeProps} from '../utils';
 import {composeEventHandlers} from '../utils/composeEventHandlers';
 import {AvatarGroupContext} from './AvatarGroupContext';
 import {themeProps} from '../utils/themeProps';
@@ -37,6 +37,7 @@ import {useListFocus} from '../hooks/useListFocus';
 import {useIsomorphicLayoutEffect} from '../hooks/useIsomorphicLayoutEffect';
 import {VisuallyHidden} from '../VisuallyHidden';
 
+import {useMergedRefs} from '../hooks/useMergedRefs';
 const OVERLAP_RATIO = 0.25;
 
 export interface AvatarGroupProps extends BaseProps<HTMLDivElement> {
@@ -143,7 +144,7 @@ export function AvatarGroup({
     <AvatarGroupContext value={contextValue}>
       <div
         {...props}
-        ref={mergeRefs(ref, listRef)}
+        ref={useMergedRefs(ref, listRef)}
         role="group"
         aria-label={ariaLabel}
         aria-describedby={describedBy}

package/src/BottomSheet/BottomSheet.test.tsx

@@ -334,6 +334,106 @@ describe('BottomSheet', () => {
     expect(onOpenChange).toHaveBeenCalledWith(false);
   });
 
+  it('ignores Escape while an IME composition is active', () => {
+    const onOpenChange = vi.fn();
+    render(
+      <BottomSheet isOpen onOpenChange={onOpenChange} label="Filters">
+        <input aria-label="Search" />
+      </BottomSheet>,
+    );
+    const dialog = screen.getByRole('dialog');
+
+    fireEvent.keyDown(dialog, {key: 'Escape', isComposing: true});
+    fireEvent.keyDown(dialog, {key: 'Escape', keyCode: 229});
+
+    expect(onOpenChange).not.toHaveBeenCalled();
+  });
+
+  it('claims the composing Escape so no native close request follows', () => {
+    const onOpenChange = vi.fn();
+    render(
+      <BottomSheet isOpen onOpenChange={onOpenChange} label="Filters">
+        <input aria-label="Search" />
+      </BottomSheet>,
+    );
+    const dialog = screen.getByRole('dialog');
+
+    // An unclaimed Escape lets the browser raise its own close request, which
+    // arrives as `cancel` and dismisses the sheet on the same keypress. The
+    // guard has to swallow the composing Escape, not merely skip dismissal.
+    const wasNotClaimed = fireEvent.keyDown(dialog, {
+      key: 'Escape',
+      isComposing: true,
+    });
+
+    expect(wasNotClaimed).toBe(false);
+    expect(onOpenChange).not.toHaveBeenCalled();
+  });
+
+  it('keeps a form sheet open when Escape cancels a field composition', () => {
+    const onOpenChange = vi.fn();
+    render(
+      <BottomSheet
+        isOpen
+        purpose="form"
+        onOpenChange={onOpenChange}
+        label="Edit profile">
+        <input aria-label="Name" />
+      </BottomSheet>,
+    );
+
+    // The reported path: the keydown starts at the composing field and bubbles
+    // to the sheet's <dialog>, so the guard has to survive the trip.
+    fireEvent.keyDown(screen.getByRole('textbox', {name: 'Name'}), {
+      key: 'Escape',
+      isComposing: true,
+    });
+
+    expect(onOpenChange).not.toHaveBeenCalled();
+  });
+
+  it('still dismisses on the Escape after a composition is cancelled', () => {
+    const onOpenChange = vi.fn();
+    render(
+      <BottomSheet isOpen onOpenChange={onOpenChange} label="Filters">
+        <input aria-label="Search" />
+      </BottomSheet>,
+    );
+    const dialog = screen.getByRole('dialog');
+
+    fireEvent.keyDown(dialog, {key: 'Escape', isComposing: true});
+    expect(onOpenChange).not.toHaveBeenCalled();
+
+    fireEvent.keyDown(dialog, {key: 'Escape'});
+
+    expect(onOpenChange).toHaveBeenCalledWith(false);
+  });
+
+  it('leaves the IME the composition keys that are not Escape', () => {
+    const onOpenChange = vi.fn();
+    render(
+      <BottomSheet isOpen onOpenChange={onOpenChange} label="Filters">
+        <input aria-label="Search" />
+      </BottomSheet>,
+    );
+    const dialog = screen.getByRole('dialog');
+
+    // Enter commits a candidate and the arrows walk the candidate window. The
+    // sheet must claim neither, or the IME loses keys it owns.
+    const enterUnclaimed = fireEvent.keyDown(dialog, {
+      key: 'Enter',
+      isComposing: true,
+    });
+    const arrowUnclaimed = fireEvent.keyDown(dialog, {
+      key: 'ArrowDown',
+      isComposing: true,
+    });
+
+    expect(enterUnclaimed).toBe(true);
+    expect(arrowUnclaimed).toBe(true);
+    expect(onOpenChange).not.toHaveBeenCalled();
+  });
+
   it('requests close when the scrim (dialog element itself) is clicked', () => {
     const onOpenChange = vi.fn();
     render(
@@ -474,6 +574,29 @@ describe('BottomSheet', () => {
       expect(onOpenChange).toHaveBeenCalledWith(false);
     });
 
+    it('ignores Escape while an IME composition is active', () => {
+      const onOpenChange = vi.fn();
+      render(
+        <BottomSheet
+          isOpen
+          hasScrim={false}
+          onOpenChange={onOpenChange}
+          label="Filters">
+          <input aria-label="Search" />
+        </BottomSheet>,
+      );
+
+      // Escape is this sheet's only keyboard route out — there is no native
+      // close request behind it — so the guard is all that stands between a
+      // composing CJK user and a dismissed sheet.
+      fireEvent.keyDown(screen.getByRole('dialog'), {
+        key: 'Escape',
+        isComposing: true,
+      });
+
+      expect(onOpenChange).not.toHaveBeenCalled();
+    });
+
     it('still dismisses on a downward swipe past the threshold', () => {
       const onOpenChange = vi.fn();
       render(

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
@@ -37,12 +38,13 @@ import * as stylex from '@stylexjs/stylex';
 import type {BaseProps} from '../BaseProps';
 import type {DialogPurpose} from '../Dialog';
 import {colorVars, durationVars, easeVars} from '../theme/tokens.stylex';
-import {useDevWarning, useScrollLock} from '../hooks';
+import {isImeKeyEvent, useDevWarning, useScrollLock} from '../hooks';
 import {
   BottomSheetPanel,
   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,
@@ -298,6 +314,9 @@ function StandaloneBottomSheet({
 
   const handleCancel = useCallback(
     (event: React.SyntheticEvent<HTMLDialogElement>) => {
+      // No IME guard here: `cancel` is a plain Event carrying no composition
+      // state, and handleKeyDown claims a composing Escape before the browser
+      // can raise the close request that would arrive here.
       event.preventDefault();
       dismissOnEscape();
     },
@@ -305,10 +324,20 @@ function StandaloneBottomSheet({
   );
   const handleKeyDown = useCallback(
     (event: React.KeyboardEvent<HTMLDialogElement>) => {
-      if (event.key === 'Escape') {
-        event.preventDefault();
-        dismissOnEscape();
+      if (event.key !== 'Escape') {
+        return;
       }
+      // Claim the key before reading it: an unclaimed Escape lets the browser
+      // raise its own close request, which lands on handleCancel and dismisses
+      // on the same keypress.
+      event.preventDefault();
+      // An IME fires this keydown to cancel an in-progress composition, ahead
+      // of compositionend. It is a composition cancel, not a dismissal command
+      // — see utils/ime; Dialog and BottomSheetSwitcher guard the same way.
+      if (isImeKeyEvent(event.nativeEvent)) {
+        return;
+      }
+      dismissOnEscape();
     },
     [dismissOnEscape],
   );
@@ -327,6 +356,7 @@ function StandaloneBottomSheet({
         styles.dialog,
         shouldPresent && styles.dialogOpen,
         hasScrim && styles.scrim,
+        hasScrim && !isOpen && isPresented && styles.scrimClosing,
         !hasScrim && styles.dialogNonModal,
       )}
       ref={dialogRef}
@@ -355,6 +385,8 @@ function StandaloneBottomSheet({
           {children}
         </BottomSheetPanel>
       </div>
+      {/* A modal sheet's ::backdrop already answers Safari's edge sampler. */}
+      {hasScrim ? null : <BottomSheetEdgeTint />}
     </dialog>
   );
 }