@astryxdesign/core 0.7.1 → 0.7.2-canary.020e1fe

package/src/AspectRatio/AspectRatio.tsx

@@ -9,7 +9,6 @@
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/core/src/AspectRatio/AspectRatio.doc.mjs
  * - /packages/core/src/AspectRatio/AspectRatio.test.tsx
- * - /packages/core/src/reset.css (AspectRatio fit baseline rules)
  * - /apps/storybook/stories/AspectRatio.stories.tsx
  * - /packages/cli/assets/templates/blocks/components/AspectRatio/ (showcase blocks)
  */
@@ -91,13 +90,12 @@ export interface AspectRatioProps extends BaseProps<HTMLDivElement> {
    *   (`object-fit: contain`).
    * - `center`: child keeps its natural size, centered in the box.
    *
-   * `cover`/`contain` child sizing ships as zero-specificity baseline rules
-   * in `reset.css`, keyed on the `data-astryx-aspect-ratio-override`
-   * attribute the component sets on the child's direct parent. Any styles
-   * the child sets itself still win, so children that already size
-   * themselves keep their behavior. When omitted, the child is left
-   * unstyled (the pre-existing contract). `fit` is structural, not visual,
-   * so it is not exposed on the theming surface.
+   * `cover`/`contain` size the child from the component's own styles, in
+   * the `astryx-base` cascade layer. Styles in a later layer (Tailwind
+   * utilities, `astryx-theme`), unlayered CSS, and inline styles on the
+   * child still win. When omitted, the child is left unstyled (the
+   * pre-existing contract). `fit` is structural, not visual, so it is not
+   * exposed on the theming surface.
    *
    * @example
    * ```
@@ -140,15 +138,33 @@ const styles = stylex.create({
     height: '100%',
   },
   // fit="center" centers the child at its natural size from the wrapper —
-  // no styles on the child itself. The `cover`/`contain` child sizing can't
-  // live here (StyleX has no descendant selectors); it ships as baseline
-  // rules in reset.css keyed on the `data-astryx-aspect-ratio-override`
-  // attribute the wrapper carries (see below).
+  // no styles on the child itself.
   childCenter: {
     display: 'flex',
     alignItems: 'center',
     justifyContent: 'center',
   },
+  // `cover`/`contain` must style the child itself (`object-fit` only applies
+  // on the replaced element), and StyleX has no child selector. The
+  // `:not([stylex-hack])` pseudo-class always matches, so StyleX accepts the
+  // key and emits `.x:not([stylex-hack]) > *`, a direct-child rule in the
+  // `astryx-base` layer like every other component style.
+  childFill: {
+    ':not([stylex-hack]) > *': {
+      width: '100%',
+      height: '100%',
+    },
+  },
+  childCover: {
+    ':not([stylex-hack]) > :is(img, video)': {
+      objectFit: 'cover',
+    },
+  },
+  childContain: {
+    ':not([stylex-hack]) > :is(img, video)': {
+      objectFit: 'contain',
+    },
+  },
 });
 
 // The ratio compiles to a CSS variable + a class-level declaration
@@ -234,14 +250,18 @@ export function AspectRatio({
         style,
       )}
       {...props}>
-      {/* The marker attribute carries the fit value so the reset.css child
-          sizing can use direct-child selectors on this wrapper — the child's
-          actual parent — without depending on AspectRatio's internal
-          structure or on the theming surface (fit is structural, not
-          themeable). The name is namespaced to avoid collisions. */}
+      {/* The marker attribute carries the fit value. No Astryx style keys on
+          it any more, but earlier releases documented it, so product CSS may
+          still target it. */}
       <div
         data-astryx-aspect-ratio-override={fit}
-        {...stylex.props(styles.child, fit === 'center' && styles.childCenter)}>
+        {...stylex.props(
+          styles.child,
+          fit === 'center' && styles.childCenter,
+          (fit === 'cover' || fit === 'contain') && styles.childFill,
+          fit === 'cover' && styles.childCover,
+          fit === 'contain' && styles.childContain,
+        )}>
         {children}
       </div>
     </div>

package/src/AspectRatio/__tests__/AspectRatioFitLayers.a11y.browser.spec.ts

@@ -0,0 +1,157 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file AspectRatioFitLayers.a11y.browser.spec.ts
+ * @input The built FitModes story (its rendered markup and compiled CSS) and
+ *   Tailwind's preflight.css
+ * @output Browser evidence that `fit` fills the box on the documented setups
+ * @position AspectRatio integration proof. Which rule sizes the child is a
+ *   cascade-layer question, and only a shipping engine resolves the cascade.
+ */
+
+import * as fs from 'node:fs';
+import {fileURLToPath} from 'node:url';
+import {expect, test, type Page} from '@playwright/test';
+import {
+  DEFAULT_STORYBOOK_DIR,
+  serveStorybook,
+  type StaticServer,
+} from '@astryxdesign/a11y-spec/storybook';
+
+const PREFLIGHT_CSS = fs.readFileSync(
+  fileURLToPath(import.meta.resolve('tailwindcss/preflight.css')),
+  'utf8',
+);
+
+// The layer order each setup guide declares, and the layer preflight goes in.
+const TAILWIND_SETUPS = [
+  {
+    name: 'Tailwind v4',
+    order:
+      '@layer reset, theme, base, astryx-base, astryx-theme, components, utilities;',
+    preflightLayer: 'base',
+  },
+  {
+    name: 'Tailwind v3',
+    order: '@layer reset, tw-preflight, astryx-base, astryx-theme;',
+    preflightLayer: 'tw-preflight',
+  },
+];
+
+// A 100×100 image in a 320px-wide 16:9 box: filling the box makes it 320×180.
+const IMAGE =
+  "data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='100' height='100'/%3E";
+
+type Fit = 'cover' | 'contain';
+
+let storybook: StaticServer;
+test.beforeAll(async () => {
+  storybook = await serveStorybook(
+    process.env.ASTRYX_STORYBOOK_DIR ?? DEFAULT_STORYBOOK_DIR,
+  );
+});
+test.afterAll(async () => {
+  await storybook?.close();
+});
+
+/**
+ * The markup AspectRatio renders for `fit`, and every CSS rule the story
+ * page loaded, taken from the built story so the classes and rules are the
+ * component's real compiled output. The child image gets a fixed id, a
+ * local source and any extra class.
+ */
+async function captureStory(page: Page, fit: Fit, mediaClass: string) {
+  await page.goto(
+    `${storybook.origin}/iframe.html?id=core-aspectratio--fit-modes&viewMode=story`,
+  );
+  const wrapper = page.locator(`[data-astryx-aspect-ratio-override="${fit}"]`);
+  await expect(wrapper).toHaveCount(1);
+  return wrapper.evaluate(
+    (element, {image, extraClass}) => {
+      const root = element.parentElement?.cloneNode(true);
+      const media =
+        root instanceof HTMLElement ? root.querySelector('img') : null;
+      if (!(root instanceof HTMLElement) || media == null) {
+        throw new Error('FitModes no longer renders an img inside AspectRatio');
+      }
+      media.id = 'media';
+      media.src = image;
+      if (extraClass) {
+        media.classList.add(extraClass);
+      }
+      const css = [...document.styleSheets]
+        .flatMap(sheet => [...sheet.cssRules].map(rule => rule.cssText))
+        .join('\n');
+      return {html: root.outerHTML, css};
+    },
+    {image: IMAGE, extraClass: mediaClass},
+  );
+}
+
+/** Re-host the captured story with `before` CSS ahead of it and `after` CSS behind it. */
+async function measureMedia(
+  page: Page,
+  fit: Fit,
+  {
+    before = [],
+    after = [],
+    mediaClass = '',
+  }: {
+    before?: string[];
+    after?: string[];
+    mediaClass?: string;
+  },
+) {
+  const {html, css} = await captureStory(page, fit, mediaClass);
+  await page.setContent(
+    `<!doctype html><div style="width: 320px">${html}</div>`,
+  );
+  for (const content of [...before, css, ...after]) {
+    await page.addStyleTag({content});
+  }
+  await page.waitForFunction(
+    () => (document.getElementById('media') as HTMLImageElement).complete,
+  );
+  return page.evaluate(() => {
+    const media = document.getElementById('media');
+    if (!media) {
+      throw new Error('missing media');
+    }
+    const box = media.getBoundingClientRect();
+    return {
+      width: box.width,
+      height: box.height,
+      objectFit: getComputedStyle(media).objectFit,
+    };
+  });
+}
+
+for (const setup of TAILWIND_SETUPS) {
+  for (const fit of ['cover', 'contain'] as const) {
+    test(`fit="${fit}" fills the box on the ${setup.name} setup`, async ({
+      page,
+    }) => {
+      const media = await measureMedia(page, fit, {
+        before: [
+          setup.order,
+          `@layer ${setup.preflightLayer} { ${PREFLIGHT_CSS} }`,
+        ],
+      });
+      expect(media).toEqual({width: 320, height: 180, objectFit: fit});
+    });
+  }
+}
+
+test('fit fills the box with only Astryx CSS loaded', async ({page}) => {
+  const media = await measureMedia(page, 'cover', {});
+  expect(media).toEqual({width: 320, height: 180, objectFit: 'cover'});
+});
+
+test('a utility class on the child still wins over fit', async ({page}) => {
+  const media = await measureMedia(page, 'cover', {
+    before: [TAILWIND_SETUPS[0].order, `@layer base { ${PREFLIGHT_CSS} }`],
+    after: ['@layer utilities { .h-10 { height: 40px; } }'],
+    mediaClass: 'h-10',
+  });
+  expect(media).toEqual({width: 320, height: 40, objectFit: 'cover'});
+});

package/src/Avatar/Avatar.doc.mjs

@@ -67,8 +67,10 @@ export const docs = {
     },
     {
       name: 'size',
-      type: "'xsm' | 'sm' | 'md' | 'lg' | 'xl' | number",
-      description: "Avatar size. Use a named size ('xsm' 20px, 'sm' 24px, 'md' 36px, 'lg' 48px, 'xl' 128px) or a numeric pixel value. Avatar shares Icon's abbreviated scale, but its tiers are larger because avatars align with media rather than glyphs. Inside an AvatarGroup the group's size wins and this prop is ignored.",
+      type:
+        "'xsm' | 'sm' | 'md' | 'lg' | 'xl' | 16 | 20 | 24 | 32 | 36 | 40 | 48 | 60 | 64 | 72 | 96 | 128 | 144 | 180",
+      description:
+        "Avatar size: named sizes are 'xsm' (20px), 'sm' (24px), 'md' (36px), 'lg' (48px), and 'xl' (128px); numeric sizes must be one of the pixel values listed in the type. Inside an AvatarGroup, the group's size always overrides this prop, including when the group uses its default size.",
       default: "'md'",
     },
     {
@@ -169,7 +171,7 @@ export const docsDense = {
     fallbackSrc: 'fallback image when primary fails',
     name: 'user name for initials and alt text',
     alt: 'alt text; falls back to name',
-    size: "avatar size. Named ('xsm' 20px, 'sm' 24px, 'md' 36px, 'lg' 48px, 'xl' 128px) or numeric px. An AvatarGroup's size overrides it.",
+    size: "named sizes: 'xsm' 20px, 'sm' 24px, 'md' 36px, 'lg' 48px, 'xl' 128px; numeric px restricted to values listed in the type. AvatarGroup's size always wins, default included.",
     status:
       'corner content for status indicators; AvatarStatusDot reports its `label`, composed into the avatar accessible name ("Jane Doe, Online"), at any nesting depth',
     tooltip:

package/src/AvatarGroup/AvatarGroup.doc.mjs

@@ -48,9 +48,10 @@ export const docs = {
     },
     {
       name: 'size',
-      type: 'AvatarSize',
+      type:
+        "'xsm' | 'sm' | 'md' | 'lg' | 'xl' | 16 | 20 | 24 | 32 | 36 | 40 | 48 | 60 | 64 | 72 | 96 | 128 | 144 | 180",
       description:
-        "Size applied to all avatars via context. This wins over each child Avatar's own size prop, including when it is left at the default, so set the size here rather than on the children.",
+        "Size applied to all avatars: named sizes are 'xsm' (20px), 'sm' (24px), 'md' (36px), 'lg' (48px), and 'xl' (128px); numeric sizes must be one of the pixel values listed in the type. The group's size always overrides each child Avatar's size, including when the group uses its default size.",
       default: "'md'",
     },
     {

package/src/Breadcrumbs/BreadcrumbItem.tsx

@@ -56,6 +56,7 @@ import {layerAnimations} from '../Layer/layerAnimations.stylex';
 import {renderDropdownItems} from '../DropdownMenu/renderDropdownItems';
 import {
   DropdownMenuContext,
+  DropdownMenuRootOpenContext,
   type DropdownMenuContextValue,
   type DropdownMenuSize,
 } from '../DropdownMenu/DropdownMenuContext';
@@ -673,7 +674,9 @@ function BreadcrumbMenuTrigger({
             stylex.props(menuStyles.menu),
           )}>
           <DropdownMenuContext value={contextValue}>
-            {menuContent}
+            <DropdownMenuRootOpenContext value={popover.isOpen}>
+              {menuContent}
+            </DropdownMenuRootOpenContext>
           </DropdownMenuContext>
         </div>,
         {

package/src/Breadcrumbs/Breadcrumbs.test.tsx

@@ -7,12 +7,13 @@ import {Breadcrumbs} from './Breadcrumbs';
 import {BreadcrumbItem} from './BreadcrumbItem';
 import {
   BreadcrumbMenuItem,
+  BreadcrumbMenuDivider,
   BreadcrumbMenuGroup,
   BreadcrumbMenuCheckboxItem,
   BreadcrumbMenuRadioGroup,
   BreadcrumbMenuRadioItem,
 } from './index';
-import type {BreadcrumbMenuOption} from './index';
+import type {BreadcrumbMenuDividerProps, BreadcrumbMenuOption} from './index';
 import {LinkProvider} from '../Link/LinkProvider';
 
 function CustomLink({
@@ -771,6 +772,34 @@ describe('BreadcrumbItem menu', () => {
     expect(separators).toHaveLength(3);
   });
 
+  it('renders the separator and props types through the BreadcrumbMenuDivider aliases', async () => {
+    const user = userEvent.setup();
+    const dividerProps: BreadcrumbMenuDividerProps = {
+      'data-testid': 'breadcrumb-menu-divider',
+    };
+    render(
+      <Breadcrumbs>
+        <BreadcrumbItem
+          menu={
+            <>
+              <BreadcrumbMenuItem label="Overview" />
+              <BreadcrumbMenuDivider {...dividerProps} />
+              <BreadcrumbMenuItem label="Settings" />
+            </>
+          }>
+          Project
+        </BreadcrumbItem>
+        <BreadcrumbItem isCurrent>Current</BreadcrumbItem>
+      </Breadcrumbs>,
+    );
+    await user.click(screen.getByRole('button', {name: 'Project'}));
+
+    expect(screen.getByTestId('breadcrumb-menu-divider')).toHaveAttribute(
+      'role',
+      'separator',
+    );
+  });
+
   it('carries the group semantics through the BreadcrumbMenuGroup alias', async () => {
     // The alias must bring the semantics, not just the component: a group
     // that renders but is not named leaves a screen reader with a run of

package/src/Button/Button.doc.mjs

@@ -138,7 +138,7 @@ export const docs = {
     {
       name: 'isLoading',
       type: 'boolean',
-      description: 'Shows a loading spinner and disables interaction. Announces "Loading" via a live region.',
+      description: 'Shows a loading spinner and blocks re-activation while staying focusable (aria-busy + aria-disabled, not native disabled, so keyboard focus is never dropped mid-action). Announces "Loading" via a live region.',
       default: 'false',
     },
     {
@@ -419,7 +419,7 @@ export const docsDense = {
     displayName: 'HTML name for form submission',
     value: 'HTML value for form submission',
     form: 'associates button with form element by ID',
-    isLoading: 'shows spinner+disables interaction; announces via live region',
+    isLoading: 'shows spinner, blocks re-activation but stays focusable (aria-disabled, not native disabled); announces via live region',
     icon: 'icon element rendered before label text; unsized Astryx Icon defaults to sm for sm/md buttons and md for lg',
     isIconOnly: 'when true, renders square icon-only button; label becomes aria-label',
     width: "Width of button. Numbers=pixels, strings=as-is (e.g. '100%' for full-width). Default: content width, capped at the container; label truncates w/ ellipsis in a narrow row; icon-only stays square.",

package/src/Button/Button.test.tsx

@@ -11,7 +11,13 @@
 
 import {readFileSync} from 'node:fs';
 import {describe, it, expect, vi} from 'vitest';
-import {render, screen, fireEvent, act} from '@testing-library/react';
+import {
+  render,
+  screen,
+  fireEvent,
+  createEvent,
+  act,
+} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import {Button} from './Button';
 import * as stylex from '@stylexjs/stylex';
@@ -127,8 +133,9 @@ describe('Button', () => {
   it('shows isLoading state with spinner', () => {
     render(<Button label="Submit" isLoading />);
     const button = screen.getByRole('button');
-    // Button should be disabled when loading
-    expect(button).toBeDisabled();
+    // Busy is aria-disabled (focusable), not native disabled — see #4871.
+    expect(button).not.toBeDisabled();
+    expect(button).toHaveAttribute('aria-disabled', 'true');
     expect(button.className).toContain('styles.inactive');
     expect(button.className).not.toContain('styles.disabled');
   });
@@ -143,7 +150,7 @@ describe('Button', () => {
 
   it('sets aria-busy synchronously while clickAction is pending', async () => {
     // The spinner reveal is visually delayed (CSS animation-delay), but the
-    // loading DOM state — aria-busy and disabled — must not be delayed.
+    // loading DOM state — aria-busy and aria-disabled — must not be delayed.
     const user = userEvent.setup();
     let resolveAction: (() => void) | undefined;
     const clickAction = vi.fn(
@@ -157,7 +164,9 @@ describe('Button', () => {
 
     await user.click(button);
     expect(button).toHaveAttribute('aria-busy', 'true');
-    expect(button).toBeDisabled();
+    // Busy is aria-disabled (focusable), not native disabled — see #4871.
+    expect(button).not.toBeDisabled();
+    expect(button).toHaveAttribute('aria-disabled', 'true');
 
     await act(async () => {
       resolveAction?.();
@@ -165,6 +174,7 @@ describe('Button', () => {
     });
     expect(button).not.toHaveAttribute('aria-busy', 'true');
     expect(button).not.toBeDisabled();
+    expect(button).not.toHaveAttribute('aria-disabled');
   });
 
   it('renders the loading spinner with the inherit shade for every variant (#2717)', () => {
@@ -310,9 +320,10 @@ describe('Button', () => {
     );
     // endContent should still be in the DOM
     expect(screen.getByTestId('end')).toBeInTheDocument();
-    // Button should be disabled and have aria-busy
+    // Busy is aria-disabled (focusable), not native disabled — see #4871.
     const button = screen.getByRole('button');
-    expect(button).toBeDisabled();
+    expect(button).not.toBeDisabled();
+    expect(button).toHaveAttribute('aria-disabled', 'true');
     expect(button).toHaveAttribute('aria-busy', 'true');
   });
 
@@ -516,6 +527,111 @@ describe('Button', () => {
     expect(handleKeyDown).toHaveBeenCalledTimes(1);
   });
 
+  it('uses aria-disabled instead of disabled while isLoading, so the button stays focusable (#4871)', () => {
+    render(<Button label="Save" isLoading />);
+    const button = screen.getByRole('button');
+    // Native disabled would move focus to <body> the moment the action
+    // starts, losing the keyboard user's place — busy must stay
+    // aria-disabled + focusable per the "Disabled vs Busy" convention.
+    expect(button).not.toHaveAttribute('disabled');
+    expect(button).toHaveAttribute('aria-disabled', 'true');
+    expect(button).toHaveAttribute('aria-busy', 'true');
+    button.focus();
+    expect(button).toHaveFocus();
+  });
+
+  it('does not fire onClick while aria-disabled via isLoading', async () => {
+    const user = userEvent.setup();
+    const handleClick = vi.fn();
+    render(<Button label="Save" isLoading onClick={handleClick} />);
+    await user.click(screen.getByRole('button'));
+    expect(handleClick).not.toHaveBeenCalled();
+  });
+
+  it('does not let a click on a busy button reach a wrapping ancestor handler', async () => {
+    // A native `disabled` element never dispatches a click, so it never
+    // reaches an ancestor either. aria-disabled (busy-only) is a real,
+    // interactive element that still dispatches one — preventDefault alone
+    // only cancels the button's own default action, not propagation, so
+    // an unrelated wrapper (a clickable row/card/backdrop) would otherwise
+    // still fire.
+    const user = userEvent.setup();
+    const ancestorClick = vi.fn();
+    render(
+      <div onClick={ancestorClick}>
+        <Button label="Save" isLoading />
+      </div>,
+    );
+    await user.click(screen.getByRole('button'));
+    expect(ancestorClick).not.toHaveBeenCalled();
+  });
+
+  it('does not let a click on a busy-only anchor Button reach a wrapping ancestor handler', async () => {
+    const user = userEvent.setup();
+    const ancestorClick = vi.fn();
+    render(
+      <div onClick={ancestorClick}>
+        <Button label="Docs" href="https://example.com" isLoading />
+      </div>,
+    );
+    await user.click(screen.getByRole('link'));
+    expect(ancestorClick).not.toHaveBeenCalled();
+  });
+
+  it('suppresses activation keys but passes other keys while aria-disabled via isLoading', async () => {
+    const user = userEvent.setup();
+    const handleKeyDown = vi.fn();
+    render(<Button label="Save" isLoading onKeyDown={handleKeyDown} />);
+    const button = screen.getByRole('button');
+    button.focus();
+    await user.keyboard('{Enter}');
+    expect(handleKeyDown).not.toHaveBeenCalled();
+
+    await user.keyboard('{Escape}');
+    expect(handleKeyDown).toHaveBeenCalledTimes(1);
+  });
+
+  it('suppresses activation keys but passes other keys on a busy-only anchor Button', async () => {
+    // The button-rendered path suppresses Enter/Space while aria-disabled;
+    // the anchor-rendered path (href set, busy-only) shares the same
+    // handleKeyDown but only wires onClick, so a consumer onKeyDown still
+    // received Enter/Space on a busy link.
+    const user = userEvent.setup();
+    const handleKeyDown = vi.fn();
+    render(
+      <Button
+        label="Docs"
+        href="https://example.com"
+        isLoading
+        onKeyDown={handleKeyDown}
+      />,
+    );
+    const link = screen.getByRole('link');
+    link.focus();
+    await user.keyboard('{Enter}');
+    expect(handleKeyDown).not.toHaveBeenCalled();
+
+    await user.keyboard('{Escape}');
+    expect(handleKeyDown).toHaveBeenCalledTimes(1);
+  });
+
+  it('keeps native disabled (not aria-disabled) when isDisabled and not busy, even without a tooltip', () => {
+    render(<Button label="Save" isDisabled />);
+    const button = screen.getByRole('button');
+    expect(button).toHaveAttribute('disabled');
+    expect(button).not.toHaveAttribute('aria-disabled');
+  });
+
+  it('keeps native disabled when isDisabled and isLoading are both true (isDisabled wins)', () => {
+    render(<Button label="Save" isDisabled isLoading />);
+    const button = screen.getByRole('button');
+    // "isDisabled behavior unchanged: that stays native disabled" — busy-only
+    // aria-disabled is only for the case where busy is the SOLE reason the
+    // button can't be clicked, not when it's also genuinely isDisabled.
+    expect(button).toHaveAttribute('disabled');
+    expect(button).not.toHaveAttribute('aria-disabled');
+  });
+
   it('has a live region that announces loading state', () => {
     const {rerender} = render(<Button label="Submit" />);
     const button = screen.getByRole('button');
@@ -663,8 +779,6 @@ describe('Button', () => {
   });
 
   it('exposes aria-busy on the link-rendered button while loading', () => {
-    // Non-interruptible loading disables the button, which falls back to
-    // <button> rendering — so an anchor only shows loading when interruptible.
     render(
       <Button
         label="Docs"
@@ -682,6 +796,38 @@ describe('Button', () => {
     const link = screen.getByRole('link');
     expect(link).not.toHaveAttribute('aria-busy');
   });
+
+  it('stays an anchor while busy-only, not a disabled <button> fallback (#4871)', () => {
+    // Non-interruptible busy is exactly the isBusyOnlyDisabled case: not
+    // isDisabled, blocked only because a fire-once action is in flight.
+    // Swapping the element to <button disabled> here would drop focus the
+    // same way the native disabled attribute did (credit @AKnassa, #4879).
+    render(<Button label="Docs" href="https://example.com" isLoading />);
+    const link = screen.getByRole('link', {name: 'Docs'});
+    expect(link.tagName).toBe('A');
+    expect(link).toHaveAttribute('href', 'https://example.com');
+    expect(link).toHaveAttribute('aria-busy', 'true');
+    expect(link).toHaveAttribute('aria-disabled', 'true');
+    expect(link).not.toHaveAttribute('disabled');
+  });
+
+  it('keeps a busy-only anchor focusable and guards its navigation', () => {
+    render(<Button label="Docs" href="https://example.com" isLoading />);
+    const link = screen.getByRole('link', {name: 'Docs'});
+    link.focus();
+    expect(link).toHaveFocus();
+
+    const event = createEvent.click(link);
+    fireEvent(link, event);
+    expect(event.defaultPrevented).toBe(true);
+  });
+
+  it('falls back to <button disabled> for a truly disabled href Button', () => {
+    render(<Button label="Docs" href="https://example.com" isDisabled />);
+    expect(screen.queryByRole('link')).not.toBeInTheDocument();
+    const button = screen.getByRole('button', {name: 'Docs'});
+    expect(button).toBeDisabled();
+  });
 });
 
 describe('Button pressed state (touch)', () => {