@astryxdesign/core 0.4.7 → 0.5.0-canary.055e75f

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(

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',
         ],
       },
     ],