@astryxdesign/core 0.4.7 → 0.5.0-canary.009bcb3

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

@@ -38,7 +38,7 @@ 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,
@@ -314,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();
     },
@@ -321,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],
   );

package/src/BottomSheet/BottomSheetSwitcher.tsx

@@ -51,7 +51,7 @@ import {
   useFocusTrap,
   useScrollLock,
 } from '../hooks';
-import {composeEventHandlers, mergeProps, mergeRefs} from '../utils';
+import {composeEventHandlers, mergeProps} from '../utils';
 import {BottomSheetEdgeTint} from './BottomSheetEdgeTint';
 import {
   BottomSheetSwitcherContext,
@@ -60,6 +60,7 @@ import {
   type BottomSheetSwitcherTransitionEvent,
 } from './BottomSheetSwitcherContext';
 
+import {useMergedRefs} from '../hooks/useMergedRefs';
 const styles = stylex.create({
   dialog: {
     position: 'fixed',
@@ -621,7 +622,7 @@ export function BottomSheetSwitcher({
       <dialog
         {...props}
         {...dialogPresentationProps}
-        ref={mergeRefs(ref, dialogRef, containerRef)}
+        ref={useMergedRefs(ref, dialogRef, containerRef)}
         aria-label={ariaLabel}
         aria-modal={isModal ? 'true' : undefined}
         onCancel={composeEventHandlers(onCancel, handleCancel)}

package/src/Breadcrumbs/BreadcrumbItem.tsx

@@ -38,11 +38,12 @@ import {
   spacingVars,
   typeScaleVars,
   radiusVars,
+  fontWeightVars,
 } from '../theme/tokens.stylex';
 import {BreadcrumbContext, type BreadcrumbsVariant} from './Breadcrumbs';
 import {useLinkComponent} from '../Link/useLinkComponent';
 import type {LinkComponentType} from '../Link/types';
-import {mergeProps, mergeRefs} from '../utils';
+import {mergeProps} from '../utils';
 import type {BaseProps} from '../BaseProps';
 import {themeProps} from '../utils/themeProps';
 import {focusOutlineProps} from '../utils/focusOutline.stylex';
@@ -64,6 +65,7 @@ import {
 } from '../DropdownMenu/menuItemRoles';
 import type {DropdownMenuOption} from '../DropdownMenu/DropdownMenu';
 
+import {useMergedRefs} from '../hooks/useMergedRefs';
 // =============================================================================
 // Props
 // =============================================================================
@@ -186,7 +188,7 @@ const itemStyles = stylex.create({
     color: colorVars['--color-text-secondary'],
   },
   current: {
-    fontWeight: 'inherit',
+    fontWeight: fontWeightVars['--font-weight-semibold'],
   },
   defaultCurrent: {
     color: colorVars['--color-text-primary'],
@@ -346,6 +348,8 @@ export function BreadcrumbItem({
     }
   });
 
+  const mergedItemRef = useMergedRefs(ref, liRef);
+
   const content = (
     <>
       {startIcon && <span {...stylex.props(itemStyles.icon)}>{startIcon}</span>}
@@ -356,7 +360,7 @@ export function BreadcrumbItem({
   if (isCurrent) {
     return (
       <li
-        ref={mergeRefs(ref, liRef)}
+        ref={mergedItemRef}
         {...mergeProps(
           themeProps('breadcrumb-item', {variant: ctx.variant}),
           stylex.props(
@@ -405,7 +409,7 @@ export function BreadcrumbItem({
   // The effect handles adding aria-current for auto-last detection.
   return (
     <li
-      ref={mergeRefs(ref, liRef)}
+      ref={mergedItemRef}
       {...mergeProps(
         themeProps('breadcrumb-item', {variant: ctx.variant}),
         stylex.props(
@@ -615,7 +619,7 @@ function BreadcrumbMenuTrigger({
   return (
     <>
       <button
-        ref={mergeRefs(
+        ref={useMergedRefs(
           ref as React.Ref<HTMLButtonElement>,
           buttonRef,
           popover.triggerRef,

package/src/Button/Button.doc.mjs

@@ -150,6 +150,28 @@ export const docs = {
       description:
         'Async click handler. Shows loading state while the returned promise is pending.',
     },
+    {
+      name: 'href',
+      type: 'string',
+      description:
+        'When provided, renders the button as a link element (<a> or custom link component).',
+    },
+    {
+      name: 'as',
+      type: 'ComponentType',
+      description:
+        'Custom link component to use when href is provided (e.g. Next.js Link).',
+    },
+    {
+      name: 'target',
+      type: 'string',
+      description: 'HTML target attribute when rendered as a link (e.g. "_blank").',
+    },
+    {
+      name: 'rel',
+      type: 'string',
+      description: 'HTML rel attribute when rendered as a link (e.g. "noopener noreferrer").',
+    },
   ],
   playground: {
     defaults: {
@@ -159,7 +181,7 @@ export const docs = {
   },
   theming: {
     targets: [
-      {className: 'astryx-button', visualProps: ['size', 'variant']},
+      {className: 'astryx-button', visualProps: ['size', 'variant', 'elevation']},
     ],
     vars: [
       {name: '--_button-radius', description: 'Border radius', default: 'var(--radius-element)', private: true},
@@ -240,6 +262,7 @@ export const docsZh = {
         visualProps: [
           'size',
           'variant',
+          'elevation',
         ],
       },
     ],

package/src/Button/Button.test.tsx

@@ -151,6 +151,19 @@ describe('Button', () => {
     expect(ref).toHaveBeenCalledWith(expect.any(HTMLButtonElement));
   });
 
+  it('keeps its merged ref attached across unrelated rerenders', () => {
+    const ref = vi.fn();
+    const {rerender} = render(<Button label="Test" ref={ref} />);
+    const button = screen.getByRole('button');
+    expect(ref).toHaveBeenLastCalledWith(button);
+    ref.mockClear();
+
+    rerender(<Button label="Test" variant="primary" ref={ref} />);
+
+    expect(ref).not.toHaveBeenCalled();
+    expect(screen.getByRole('button')).toBe(button);
+  });
+
   // endContent tests
   it('renders endContent after label', () => {
     render(
@@ -463,6 +476,21 @@ describe('Button', () => {
   });
 
   describe('elevation', () => {
+    it('reflects each elevation level as a theme attribute', () => {
+      const attrFor = (elevation: 'none' | 'low' | 'med' | 'high') => {
+        const {container} = render(
+          <Button label="Save" elevation={elevation} />,
+        );
+        return container
+          .querySelector('button')!
+          .getAttribute('data-elevation');
+      };
+      expect(attrFor('none')).toBe('none');
+      expect(attrFor('low')).toBe('low');
+      expect(attrFor('med')).toBe('med');
+      expect(attrFor('high')).toBe('high');
+    });
+
     it('renders a distinct class for each elevation level', () => {
       const classFor = (elevation: 'none' | 'low' | 'med' | 'high') => {
         const {container} = render(
@@ -480,13 +508,13 @@ describe('Button', () => {
     });
 
     it('defaults to flat (elevation none)', () => {
-      const {container: def} = render(<Button label="Save" />);
+      const {container} = render(<Button label="Save" />);
+      const button = container.querySelector('button')!;
+      expect(button).toHaveAttribute('data-elevation', 'none');
       const {container: none} = render(
         <Button label="Save" elevation="none" />,
       );
-      expect(def.querySelector('button')!.className).toBe(
-        none.querySelector('button')!.className,
-      );
+      expect(button.className).toBe(none.querySelector('button')!.className);
     });
   });
 

package/src/Button/Button.tsx

@@ -42,7 +42,8 @@ import {VisuallyHidden} from '../VisuallyHidden';
 import {EDGE_COMP_ATTR} from '../Layout/edgeCompensation.stylex';
 import {useSize} from '../SizeContext/SizeContext';
 import {useButtonGroup} from '../ButtonGroup/ButtonGroupContext';
-import {mergeProps, mergeRefs} from '../utils';
+import {mergeProps} from '../utils';
+import {useMergedRefs} from '../hooks/useMergedRefs';
 import {useLinkComponent} from '../Link/useLinkComponent';
 import type {LinkComponentType} from '../Link/types';
 import {themeProps} from '../utils/themeProps';
@@ -688,7 +689,13 @@ export function Button({
   );
 
   const sharedMergedProps = mergeProps(
-    themeProps('button', {variant, size}),
+    // Inside a group the group owns the surface's elevation, so the button
+    // reflects the tier it actually paints rather than the prop it was handed.
+    themeProps('button', {
+      variant,
+      size,
+      elevation: buttonGroup ? 'none' : elevation,
+    }),
     sharedStylexProps,
     className,
     style,
@@ -757,9 +764,9 @@ export function Button({
       : null;
 
   // Merge the consumer ref with the tooltip hook's trigger ref so both point at
-  // the same element. mergeRefs tolerates undefined, so this is a no-op for the
-  // tooltip side when no tooltip is set.
-  const mergedButtonRef = mergeRefs(
+  // the same element. useMergedRefs tolerates undefined, so this is a no-op for
+  // the tooltip side when no tooltip is set.
+  const mergedButtonRef = useMergedRefs(
     ref,
     tooltip != null ? tooltipHook.ref : undefined,
   );

package/src/ButtonGroup/ButtonGroup.doc.mjs

@@ -15,7 +15,7 @@ export const docs = {
   },
   theming: {
     targets: [
-      {className: 'astryx-button-group', visualProps: ['size', 'orientation']},
+      {className: 'astryx-button-group', visualProps: ['size', 'orientation', 'elevation']},
     ],
   },
   components: [
@@ -46,6 +46,9 @@ export const docs = {
       {guidance: false, description: "Don't mix wildly different actions. A Save button next to a Delete button in the same group is confusing."},
       {guidance: false, description: "Don't use ButtonGroup for navigation. Use SegmentedControl or TabList for switching between views."},
       {guidance: false, description: "Don't nest ButtonGroups. If you need multiple groups, place them side by side with a gap."},
+      {guidance: true, description: 'Name the group for what its buttons act on. The label is the group\'s accessible name and a screen reader reads it before each member.'},
+      {guidance: true, description: 'Keep the group a single Tab stop. Arrow keys move between members along the orientation, Home/End jump to the ends, and disabled members are skipped. This is the WAI-ARIA APG roving tabindex technique: https://www.w3.org/WAI/ARIA/apg/practices/keyboard-interface/#kbd_roving_tabindex'},
+      {guidance: false, description: "Don't disable the group to show that an action is in flight. A disabled member drops focus, so a keyboard user loses their place; leave the group enabled and show progress on the button that started the work."},
     ],
     anatomy: [
       {name: 'Button', required: true, description: 'One or more Button or IconButton children that form the connected group.'},
@@ -84,6 +87,9 @@ export const docsZh = {
       {guidance: false, description: '不要混合差异很大的操作，将保存按钮和删除按钮放在同一组中会令人困惑。'},
       {guidance: false, description: '不要使用 ButtonGroup 进行导航，使用 SegmentedControl 或 TabList 切换视图。'},
       {guidance: false, description: '不要嵌套 ButtonGroup。如需多个组，请并排放置并留有间隔。'},
+      {guidance: true, description: '按钮组的标签应说明这些按钮作用于什么。该标签是按钮组的无障碍名称，屏幕阅读器会在每个成员之前朗读它。'},
+      {guidance: true, description: '按钮组是单个 Tab 停靠点。方向键沿排列方向在成员间移动焦点，Home/End 跳到首尾，禁用成员会被跳过——即 WAI-ARIA APG 的 roving tabindex 技术。'},
+      {guidance: false, description: '不要用禁用整个按钮组来表示操作进行中。禁用的成员会失去焦点，键盘用户会丢失位置；请保持按钮组可用，并在发起操作的按钮上显示进度。'},
     ],
     anatomy: [
       {name: '按钮', required: true, description: '一个或多个 Button 或 IconButton 子元素，形成连接的组。'},
@@ -105,6 +111,9 @@ export const docsDense = {
       {guidance: false, description: "Don't mix unrelated actions in one group."},
       {guidance: false, description: "Don't use for navigation. Use SegmentedControl or TabList."},
       {guidance: false, description: "Don't nest ButtonGroups."},
+      {guidance: true, description: 'Label the group for what its buttons act on; it is the accessible name.'},
+      {guidance: true, description: 'Single Tab stop; arrows move between members, Home/End to ends, disabled skipped (APG roving tabindex).'},
+      {guidance: false, description: "Don't disable the group for an in-flight action; a disabled member drops focus."},
     ],
   },
   components: [