@astryxdesign/core 0.4.6 → 0.4.7-canary.019ae5a

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/Banner/Banner.doc.mjs

@@ -17,6 +17,7 @@ export const docs = {
       {guidance: true, description: 'Keep titles short and scannable: "Payment failed" not "There was a problem processing your most recent payment."'},
       {guidance: false, description: 'Use Banner for short-lived messages that disappear on their own; use Toast instead.'},
       {guidance: false, description: 'Stack multiple banners with the same status; combine related messages into one banner.'},
+      {guidance: true, description: 'Set collapsible={false} when the user needs the content to act on the message, like the list of fields that failed validation. Keep the default toggle when the detail is long enough to bury the banner\u2019s own message.'},
       {guidance: true, description: 'Error and warning banners render as role="alert"; info and success render as role="status". Mount an alert banner in response to an event rather than on first paint, so assistive tech has a change to report.'},
       {guidance: false, description: 'Rely on the status color or icon alone to carry meaning; say which status it is in the title text, because the icon is decorative to a screen reader.'},
     ],
@@ -26,7 +27,7 @@ export const docs = {
       {name: 'Description', required: false, description: 'Additional detail below the title.'},
       {name: 'Action button', required: false, description: 'A button for the user to act on the message, like "Review" or "Retry".'},
       {name: 'Dismiss button', required: false, description: 'Lets the user close the banner. Enabled by setting isDismissable.'},
-      {name: 'Collapsible content', required: false, description: 'Extra detail that expands below the banner header, like a list of errors.'},
+      {name: 'Content', required: false, description: 'Extra detail below the banner header, like a list of errors. Sits behind an expand/collapse toggle by default; set collapsible={false} to keep it visible.'},
     ],
   },
 
@@ -94,14 +95,14 @@ export const docs = {
       name: 'children',
       type: 'ReactNode',
       description:
-        'Content rendered in the card-background area below the colored header.',
+        'Content rendered in the card-background area below the colored header. Sits behind an expand/collapse toggle unless `collapsible={false}`.',
     },
     {
-      name: 'defaultIsExpanded',
-      type: 'boolean',
+      name: 'collapsible',
+      type: 'boolean | {defaultIsOpen?: boolean; isOpen?: boolean; onOpenChange?: (isOpen: boolean) => void}',
       description:
-        'Whether the content area (children) starts expanded. Only relevant when children are provided.',
-      default: 'false',
+        'Whether the content area (children) sits behind an expand/collapse toggle in the header. On by default, starting collapsed. `false` opts out: children are always visible with no toggle. `{defaultIsOpen: true}` starts open; `{isOpen, onOpenChange}` is controlled. Takes the same CollapsibleConfig as Collapsible.',
+      default: 'true',
     },
     {
       name: 'xstyle',
@@ -154,7 +155,7 @@ export const docsZh = {
       {name: 'Description', required: false, description: 'Additional detail below the title.'},
       {name: 'Action button', required: false, description: 'A button for the user to act on the message, like "Review" or "Retry".'},
       {name: 'Dismiss button', required: false, description: 'Lets the user close the banner. Enabled by setting isDismissable.'},
-      {name: 'Collapsible content', required: false, description: 'Extra detail that expands below the banner header, like a list of errors.'},
+      {name: 'Content', required: false, description: 'Extra detail below the banner header, like a list of errors. Sits behind an expand/collapse toggle by default; set collapsible={false} to keep it visible.'},
     ],
   },
   props: [
@@ -167,8 +168,8 @@ export const docsZh = {
     {name: 'endContent', type: 'ReactNode', description: '渲染在头部区域末端对齐的操作内容，通常是按钮或链接。头部过窄时会整体换行到文本下方，自成一行。'},
     {name: 'container', type: "'card' | 'section'", description: '视觉变体：card 带圆角；section 无圆角全宽，适用于页面级场景。', default: "'card'"},
     {name: 'elevation', type: "'none' | 'low' | 'med' | 'high'", description: '静止阴影深度。用于悬浮于内容之上的浮动横幅；none 为默认内联横幅。', default: "'none'"},
-    {name: 'children', type: 'ReactNode', description: '渲染在彩色头部下方卡片背景区域的内容。'},
-    {name: 'defaultIsExpanded', type: 'boolean', description: '内容区域（children）是否初始展开。仅在提供 children 时相关。', default: 'false'},
+    {name: 'children', type: 'ReactNode', description: '渲染在彩色头部下方卡片背景区域的内容。默认位于展开/折叠开关之后，除非设置 collapsible={false}。'},
+    {name: 'collapsible', type: 'boolean | {defaultIsOpen?: boolean; isOpen?: boolean; onOpenChange?: (isOpen: boolean) => void}', description: '内容区域（children）是否位于头部的展开/折叠开关之后。默认开启，且初始为折叠状态。false 表示关闭：内容始终可见且没有开关。{defaultIsOpen: true} 表示初始展开；{isOpen, onOpenChange} 为受控模式。与 Collapsible 使用同一套 CollapsibleConfig。', default: 'true'},
     {
       name: 'xstyle',
       type: 'StyleXStyles',
@@ -230,7 +231,7 @@ export const docsDense = {
       {name: 'Description', required: false, description: 'Detail below title.'},
       {name: 'Action button', required: false, description: 'CTA like Review or Retry.'},
       {name: 'Dismiss button', required: false, description: 'Close button via isDismissable.'},
-      {name: 'Collapsible content', required: false, description: 'Expandable detail area.'},
+      {name: 'Content', required: false, description: 'Detail area; behind a toggle unless collapsible={false}.'},
     ],
   },
   propDescriptions: {
@@ -243,7 +244,8 @@ export const docsDense = {
     endContent: 'end-aligned action in header, typically button/link; wraps to its own row when the header is too narrow',
     container: 'card=border-radius; section=full-width no radius for page-level',
     elevation: 'resting shadow depth: none|low|med|high; raise for a floating banner',
-    children: 'content in card-bg area below colored header',
+    children: 'content in card-bg area below colored header; behind a toggle unless collapsible={false}',
+    collapsible: 'children behind a header toggle; default true=collapsed. false=always visible, no toggle. {defaultIsOpen:true}=starts open, {isOpen,onOpenChange}=controlled',
     xstyle: 'StyleX layout customization via stylex.create()',
   },
 };

package/src/Banner/Banner.test.tsx

@@ -184,33 +184,84 @@ describe('Banner', () => {
   });
 
   // =========================================================================
-  // Collapsible content area
+  // Content area — collapsible by default, `collapsible={false}` opts out
   // =========================================================================
 
-  it('hides children by default (collapsed)', () => {
+  it('hides children behind a toggle by default', () => {
     render(
       <Banner status="info" title="Collapsible">
         <div data-testid="child-content">Extra content</div>
       </Banner>,
     );
+    // The historical default, unchanged: chevron present, content collapsed.
     expect(screen.queryByTestId('child-content')).not.toBeInTheDocument();
+    expect(screen.getByRole('button', {name: 'Expand'})).toBeInTheDocument();
+  });
+
+  it('treats an explicit collapsible={true} as the default', () => {
+    render(
+      <Banner status="info" title="Explicit" collapsible>
+        <div data-testid="child-content">Extra content</div>
+      </Banner>,
+    );
+    expect(screen.queryByTestId('child-content')).not.toBeInTheDocument();
+    expect(screen.getByRole('button', {name: 'Expand'})).toBeInTheDocument();
   });
 
-  it('shows children when defaultIsExpanded is true', () => {
+  it('shows children with no toggle for collapsible={false}', () => {
     render(
-      <Banner status="info" title="Expanded" defaultIsExpanded>
+      <Banner status="info" title="Opted out" collapsible={false}>
         <div data-testid="child-content">Extra content</div>
       </Banner>,
     );
     expect(screen.getByTestId('child-content')).toBeInTheDocument();
+    expect(
+      screen.queryByRole('button', {name: 'Expand'}),
+    ).not.toBeInTheDocument();
+    expect(
+      screen.queryByRole('button', {name: 'Collapse'}),
+    ).not.toBeInTheDocument();
   });
 
-  it('shows expand button when children are provided', () => {
+  it('leaves non-collapsible content out of the disclosure wiring', () => {
     render(
-      <Banner status="info" title="With Toggle">
-        <div>Content</div>
+      <Banner
+        status="info"
+        title="Plain content"
+        isDismissable
+        collapsible={false}>
+        <div data-testid="child-content">Extra content</div>
+      </Banner>,
+    );
+    // No toggle exists, so nothing should carry disclosure state, and the
+    // region needs no id for a button to point at.
+    const dismiss = screen.getByRole('button', {name: 'Dismiss'});
+    expect(dismiss).not.toHaveAttribute('aria-expanded');
+    expect(dismiss).not.toHaveAttribute('aria-controls');
+    expect(
+      screen.getByTestId('child-content').parentElement,
+    ).not.toHaveAttribute('id');
+  });
+
+  it('starts open for collapsible={{defaultIsOpen: true}}', () => {
+    render(
+      <Banner status="info" title="Open" collapsible={{defaultIsOpen: true}}>
+        <div data-testid="child-content">Content</div>
+      </Banner>,
+    );
+    expect(screen.getByTestId('child-content')).toBeInTheDocument();
+    expect(screen.getByRole('button', {name: 'Collapse'})).toBeInTheDocument();
+  });
+
+  it('treats a null collapsible as the default', () => {
+    render(
+      // @ts-expect-error null is outside the prop's type, but JS callers and a
+      // value widened to `| null` still reach this.
+      <Banner status="info" title="Nullish" collapsible={null}>
+        <div data-testid="child-content">Content</div>
       </Banner>,
     );
+    expect(screen.queryByTestId('child-content')).not.toBeInTheDocument();
     expect(screen.getByRole('button', {name: 'Expand'})).toBeInTheDocument();
   });
 
@@ -247,13 +298,38 @@ describe('Banner', () => {
     expect(screen.getByRole('button', {name: 'Expand'})).toBeInTheDocument();
   });
 
-  it('shows collapse button when defaultIsExpanded', () => {
+  it('reports open-state changes through onOpenChange', async () => {
+    const user = userEvent.setup();
+    const onOpenChange = vi.fn();
     render(
-      <Banner status="info" title="Expanded" defaultIsExpanded>
-        <div>Content</div>
+      <Banner status="info" title="Notify" collapsible={{onOpenChange}}>
+        <div data-testid="child-content">Extra content</div>
       </Banner>,
     );
-    expect(screen.getByRole('button', {name: 'Collapse'})).toBeInTheDocument();
+
+    await user.click(screen.getByRole('button', {name: 'Expand'}));
+    expect(onOpenChange).toHaveBeenCalledWith(true);
+    await user.click(screen.getByRole('button', {name: 'Collapse'}));
+    expect(onOpenChange).toHaveBeenLastCalledWith(false);
+  });
+
+  it('defers to the consumer when collapsible is controlled', async () => {
+    const user = userEvent.setup();
+    const onOpenChange = vi.fn();
+    render(
+      <Banner
+        status="info"
+        title="Controlled"
+        collapsible={{isOpen: false, onOpenChange}}>
+        <div data-testid="child-content">Extra content</div>
+      </Banner>,
+    );
+
+    // A controlled banner must not move on its own: the click reports, the
+    // content stays hidden until the consumer re-renders with isOpen.
+    await user.click(screen.getByRole('button', {name: 'Expand'}));
+    expect(onOpenChange).toHaveBeenCalledWith(true);
+    expect(screen.queryByTestId('child-content')).not.toBeInTheDocument();
   });
 
   it('renders expand button to the left of dismiss button', () => {
@@ -273,7 +349,10 @@ describe('Banner', () => {
 
   it('links the expand toggle to its content region via aria-controls', () => {
     render(
-      <Banner status="info" title="Controls Test" defaultIsExpanded>
+      <Banner
+        status="info"
+        title="Controls Test"
+        collapsible={{defaultIsOpen: true}}>
         <div data-testid="region-content">Region content</div>
       </Banner>,
     );
@@ -509,9 +588,17 @@ describe('Banner', () => {
           <p>Detail</p>
         </Banner>,
       );
-      expect(
-        screen.getByRole('button', {name: 'Expand'}),
-      ).toBeInTheDocument();
+      expect(screen.getByRole('button', {name: 'Expand'})).toBeInTheDocument();
+    });
+
+    it('renders no content area for children that render nothing', () => {
+      const {container} = render(
+        <Banner status="info" title="Heads up" collapsible={false}>
+          {false}
+        </Banner>,
+      );
+      // Header only — an empty slot must not draw the card-background area.
+      expect(container.firstElementChild?.children).toHaveLength(1);
     });
 
     it('renders no description node for a description that renders nothing', () => {

package/src/Banner/Banner.tsx

@@ -4,20 +4,24 @@
 
 /**
  * @file Banner.tsx
- * @input Uses React useState/useRef/useId, Button, Icon (with registry string names), StyleX
+ * @input Uses React useState/useRef/useId, useCollapsible, Button, Icon (with registry string names), StyleX
  * @output Exports Banner component, BannerProps, BannerStatus, BannerContainer types
  * @position Core implementation; consumed by index.ts, tested by Banner.test.tsx
  *
  * Visual structure:
  * - Root container: layout-only wrapper (flex column), no visual styling, no theme target
  * - Header area (themeProps 'banner'): colored status background with icon, title, description, actions, dismiss
- * - Content area (themeProps 'banner-content'): collapsible card background for additional content (children)
+ * - Content area (themeProps 'banner-content'): card background for additional content (children)
  * - Status icon (themeProps 'banner-icon'): the target rides on the default
  *   <Icon> itself — the element that paints — so 'status:X' overrides reach
  *   the glyph (#4166); for a custom `icon` node it stays on the layout wrapper
  * - No left border accent — color is expressed through the full header background
  * - Each visual area owns its own border-radius (no overflow:clip on the container)
- * - When children are provided, a collapse/expand toggle button appears in the end area
+ * - Children are collapsible by default: a toggle appears in the header end
+ *   area and the content starts closed. `collapsible={false}` opts out and
+ *   pins the content open with no toggle. The whole collapse axis (enabled /
+ *   default / controlled) lives on that one prop and is driven by the shared
+ *   `useCollapsible` hook rather than local state.
  *
  * A status added through `BannerStatusMap` augmentation has no entry in the
  * status lookups, so it renders with no status fill, no default glyph and the
@@ -55,6 +59,8 @@ import {
   easeVars,
   shadowVars,
 } from '../theme/tokens.stylex';
+import {useCollapsible} from '../Collapsible/useCollapsible';
+import type {CollapsibleConfig} from '../Collapsible/useCollapsible';
 import {composeEventHandlers, isRenderable, mergeProps} from '../utils';
 import type {Elevation} from '../utils/types';
 import {edgeCompSlot} from '../Layout/edgeCompensation.stylex';
@@ -140,15 +146,29 @@ export interface BannerProps extends BaseProps<HTMLDivElement> {
    */
   elevation?: Elevation;
   /**
-   * Whether the content area (children) starts expanded.
-   * Only relevant when children are provided.
-   * @default false
+   * Whether the content area (children) sits behind an expand/collapse toggle
+   * in the header. On by default, so a banner with children behaves as it
+   * always has.
+   *
+   * - omitted / `true` — collapsible, starts collapsed
+   * - `{defaultIsOpen: true}` — collapsible, starts open
+   * - `{isOpen, onOpenChange}` — controlled by the consumer
+   * - `false` — not collapsible: children are always visible, with no toggle,
+   *   no `aria-expanded`, and a content region that stays mounted
+   *
+   * Takes the shared `CollapsibleConfig` so a banner's disclosure is
+   * configured exactly like `Collapsible`'s, rather than through a
+   * Banner-only vocabulary. Banner's default differs from the hook's on one
+   * point — it starts closed, not open — because a banner's message lives in
+   * its header and the content is supplementary.
+   *
+   * @default true
    */
-  defaultIsExpanded?: boolean;
+  collapsible?: boolean | CollapsibleConfig;
   /**
-   * Extra content rendered below the header in a collapsible card-background area.
+   * Extra content rendered below the header in a card-background area.
    * Use for rich content like lists, links, or detailed information.
-   * When provided, a collapse/expand toggle button appears in the header.
+   * Collapsed behind a toggle unless `collapsible={false}`.
    */
   children?: ReactNode;
 }
@@ -367,11 +387,12 @@ const elevationStyles = stylex.create({
  *
  * Two-part visual structure:
  * - Header: colored status background with icon, title, description, and actions
- * - Content (optional): collapsible card background area for additional rich content
+ * - Content (optional): card background area for additional rich content
  *
- * When children are provided, a collapse/expand chevron button appears in the
- * header end area (to the left of the dismiss button if present). Clicking it
- * toggles the visibility of the content area.
+ * When children are provided, a chevron toggle appears in the header end area
+ * (to the left of the dismiss button if present) and the content starts
+ * collapsed. Pass `collapsible={false}` for content that is always visible,
+ * or a config object to change the initial state or control it.
  *
  * Manages its own dismissed state internally — the banner hides on dismiss
  * even if `onDismiss` is not provided, so product teams don't need to wire
@@ -402,9 +423,14 @@ const elevationStyles = stylex.create({
  * <Banner
  *   status="warning"
  *   title="Configuration changes"
- *   defaultIsExpanded>
+ *   collapsible={{defaultIsOpen: true}}>
  *   <p>Details here...</p>
  * </Banner>
+ * <Banner status="error" title="3 fields need attention" collapsible={false}>
+ *   <ul>
+ *     <li>Email address is invalid</li>
+ *   </ul>
+ * </Banner>
  * ```
  */
 export function Banner({
@@ -417,7 +443,7 @@ export function Banner({
   endContent,
   container = 'card',
   elevation = 'none',
-  defaultIsExpanded = false,
+  collapsible = true,
   children,
   xstyle,
   className,
@@ -429,7 +455,26 @@ export function Banner({
 }: BannerProps) {
   const t = useTranslator();
   const [isDismissed, setIsDismissed] = useState(false);
-  const [isExpanded, setIsExpanded] = useState(defaultIsExpanded);
+  // The disclosure state machine is the shared one — Banner owns no collapse
+  // state of its own. `collapsible={false}` disables it, and that is what
+  // makes the content permanently visible.
+  //
+  // The one place Banner departs from the hook's defaults: `useCollapsible`
+  // opens by default, a banner starts closed. Its header already carries the
+  // message, so the content is supplementary — and this is the behaviour
+  // Banner has always had.
+  const collapsibleConfig =
+    collapsible != null && typeof collapsible === 'object' ? collapsible : {};
+  const {
+    isEnabled: isCollapsible,
+    isOpen: isExpanded,
+    toggle: handleToggleExpand,
+  } = useCollapsible({
+    isCollapsible: collapsible !== false && {
+      ...collapsibleConfig,
+      defaultIsOpen: collapsibleConfig.defaultIsOpen ?? false,
+    },
+  });
   // The element focus came from before it entered the banner. Dismissing
   // unmounts the whole banner, dismiss button included, so without a handoff
   // the browser drops focus to <body> and a keyboard user loses their place.
@@ -438,7 +483,8 @@ export function Banner({
   // Links the expand/collapse toggle to the content region it shows/hides so
   // assistive tech can move from the button to its controlled content
   // (disclosure pattern). The region is conditionally rendered, so aria-controls
-  // below is set only while it's mounted to avoid a dangling reference.
+  // below is set only while it's mounted to avoid a dangling reference. A
+  // non-collapsible banner has no toggle, so neither end of the link is used.
   const contentId = useId();
   const defaultIconName = defaultIconNames[status];
   const role = statusRole[status] ?? FALLBACK_ROLE;
@@ -482,18 +528,19 @@ export function Banner({
     }
   };
 
-  const handleToggleExpand = () => {
-    setIsExpanded(prev => !prev);
-  };
-
+  // The toggle exists only for a collapsible banner that actually has content
+  // to disclose.
+  const hasToggle = isCollapsible && hasChildren;
   // Show the end area if there are actions, dismiss, or a collapsible toggle
-  const showEndArea = isRenderable(endContent) || isDismissable || hasChildren;
+  const showEndArea = isRenderable(endContent) || isDismissable || hasToggle;
   // Center items vertically when there's only a title (no description)
   // and the banner has action buttons
   const hasActions = isRenderable(endContent) || isDismissable;
   const isSingleLine = !isRenderable(description) && hasActions;
 
-  const showContent = hasChildren && isExpanded;
+  // Non-collapsible children are always shown; collapsible ones follow the
+  // hook's open state.
+  const showContent = hasChildren && (!isCollapsible || isExpanded);
   const isCard = container === 'card';
 
   return (
@@ -575,7 +622,7 @@ export function Banner({
               edgeCompSlot.inset(spacingVars['--spacing-2']),
             )}>
             {endContent}
-            {hasChildren && (
+            {hasToggle && (
               <Button
                 variant="ghost"
                 size="sm"
@@ -623,7 +670,7 @@ export function Banner({
       {/* Content area: collapsible card background — theme target ('banner-content') */}
       {showContent && (
         <div
-          id={contentId}
+          id={hasToggle ? contentId : undefined}
           {...mergeProps(
             themeProps('banner-content', {container, status}),
             stylex.props(styles.contentArea, isCard && styles.contentAreaCard),

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(