@astryxdesign/core 0.7.1 → 0.7.2-canary.374b53a

package/dist/i18n/generated-locales/pseudo.generated.js

@@ -139,6 +139,25 @@ const runtimeCatalog = {
   '@astryx.listInput.announceReturnedToPosition': '⟦{itemName} řéţúřñéð ţó þóšíţíóñ {position, number}.⟧',
   '@astryx.listInput.announceDropped': '⟦{itemName} ðřóþþéð àţ þóšíţíóñ {position, number} óƒ {total, number}.⟧',
   '@astryx.listInput.announceAlreadyAtBoundary': '⟦Ţĥíš {itemName} íš àłřéàðý {boundary, select, first {first} last {last} other {}}.⟧',
+  '@astryx.diffViewer.label': '⟦Ð탃⟧',
+  '@astryx.diffViewer.renamedPath': '⟦{oldPath} → {newPath}⟧',
+  '@astryx.diffViewer.statusAdded': '⟦Àððéð⟧',
+  '@astryx.diffViewer.statusDeleted': '⟦Ðéłéţéð⟧',
+  '@astryx.diffViewer.statusRenamed': '⟦Řéñàɱéð⟧',
+  '@astryx.diffViewer.addedCount': '⟦+{count, number}⟧',
+  '@astryx.diffViewer.removedCount': '⟦−{count, number}⟧',
+  '@astryx.diffViewer.stats': '⟦{added, plural, one {# line added} other {# lines added}}, {removed, plural, one {# line removed} other {# lines removed}}⟧',
+  '@astryx.diffViewer.added': '⟦Àððéð⟧',
+  '@astryx.diffViewer.removed': '⟦Řéɱóṽéð⟧',
+  '@astryx.diffViewer.lineNumberButton': '⟦{side, select, old {Original line {line, number}} other {Changed line {line, number}}}⟧',
+  '@astryx.diffViewer.columnOldLine': '⟦Óříĝíñàł łíñé ñúɱƀéř⟧',
+  '@astryx.diffViewer.columnNewLine': '⟦Çĥàñĝéð łíñé ñúɱƀéř⟧',
+  '@astryx.diffViewer.columnChange': '⟦Çĥàñĝé⟧',
+  '@astryx.diffViewer.columnCode': '⟦Çóðé⟧',
+  '@astryx.diffViewer.columnOldCode': '⟦Óříĝíñàł çóðé⟧',
+  '@astryx.diffViewer.columnNewCode': '⟦Çĥàñĝéð çóðé⟧',
+  '@astryx.diffViewer.binary': '⟦Ɓíñàřý ƒíłé ñóţ šĥóŵñ⟧',
+  '@astryx.diffViewer.noChanges': '⟦Ñó çóñţéñţ çĥàñĝéš⟧',
   '@astryx.markdownHeadingLinks.copied': '⟦Łíñķ çóþíéð⟧',
   '@astryx.markdownHeadingLinks.copy': '⟦Çóþý łíñķ ţó {heading}⟧',
   '@astryx.richTextEditor.tabEscapeHint': '⟦Þřéšš Éšçàþé ţĥéñ Ţàƀ ţó ɱóṽé ƒóçúš óúţ óƒ ţĥé éðíţóř.⟧',

package/dist/utils/sharedMutationObserver.d.ts

@@ -0,0 +1,21 @@
+/**
+ * @file sharedMutationObserver.ts
+ * @input MutationObserver API
+ * @output Exports observeContent for shared content-change observation
+ * @position Internal utility; consumed by useTruncation. The content-change
+ *   counterpart of sharedResizeObserver: one observer for every element, so a
+ *   repeated cell or row path does not create one observer per instance.
+ */
+type ContentCallback = () => void;
+/**
+ * Call `callback` when the element's text or children change (including
+ * descendants). Returns an unsubscribe that removes only this registration.
+ *
+ * MutationObserver has no per-target unobserve, so a released element stays
+ * registered with the shared observer until no element remains; its records
+ * match no callback and are ignored. The observer disconnects and is released
+ * when the last registration goes.
+ */
+export declare function observeContent(element: Element, callback: ContentCallback): () => void;
+export {};
+//# sourceMappingURL=sharedMutationObserver.d.ts.map

package/dist/utils/sharedMutationObserver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sharedMutationObserver.d.ts","sourceRoot":"","sources":["../../src/utils/sharedMutationObserver.ts"],"names":[],"mappings":"AAIA;;;;;;;GAOG;AAEH,KAAK,eAAe,GAAG,MAAM,IAAI,CAAC;AAuBlC;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,OAAO,EAChB,QAAQ,EAAE,eAAe,GACxB,MAAM,IAAI,CA6BZ"}

package/dist/utils/sharedMutationObserver.js

@@ -0,0 +1,69 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file sharedMutationObserver.ts
+ * @input MutationObserver API
+ * @output Exports observeContent for shared content-change observation
+ * @position Internal utility; consumed by useTruncation. The content-change
+ *   counterpart of sharedResizeObserver: one observer for every element, so a
+ *   repeated cell or row path does not create one observer per instance.
+ */
+const OPTIONS = {
+  characterData: true,
+  childList: true,
+  subtree: true
+};
+let observer = null;
+const callbacks = new Map();
+function dispatch(records) {
+  // One call per callback per batch, however many records it received. A
+  // record's target can be any descendant, so walk up to the observed roots.
+  const pending = new Set();
+  for (const record of records) {
+    for (let node = record.target; node; node = node.parentNode) {
+      callbacks.get(node)?.forEach(callback => pending.add(callback));
+    }
+  }
+  pending.forEach(callback => callback());
+}
+
+/**
+ * Call `callback` when the element's text or children change (including
+ * descendants). Returns an unsubscribe that removes only this registration.
+ *
+ * MutationObserver has no per-target unobserve, so a released element stays
+ * registered with the shared observer until no element remains; its records
+ * match no callback and are ignored. The observer disconnects and is released
+ * when the last registration goes.
+ */
+export function observeContent(element, callback) {
+  if (typeof MutationObserver === 'undefined') {
+    return () => {};
+  }
+  observer ??= new MutationObserver(dispatch);
+  const existing = callbacks.get(element);
+  if (existing) {
+    existing.add(callback);
+  } else {
+    callbacks.set(element, new Set([callback]));
+    observer.observe(element, OPTIONS);
+  }
+  let isSubscribed = true;
+  return () => {
+    if (!isSubscribed) {
+      return;
+    }
+    isSubscribed = false;
+    const targetCallbacks = callbacks.get(element);
+    targetCallbacks?.delete(callback);
+    if (targetCallbacks?.size === 0) {
+      callbacks.delete(element);
+    }
+    if (callbacks.size === 0 && observer) {
+      observer.disconnect();
+      observer = null;
+    }
+  };
+}

package/locales/en.json

@@ -527,6 +527,82 @@
     "defaultMessage": "This {itemName} is already {boundary, select, first {first} last {last} other {}}.",
     "description": "Screen-reader-only live announcement when an arrow-key reorder attempt has no effect because the record is already at that end of the list. `{itemName}` is the consumer's singular noun for one record; `{boundary}` is always exactly \"first\" or \"last\"."
   },
+  "@astryx.diffViewer.label": {
+    "defaultMessage": "Diff",
+    "description": "Accessible name of a lab DiffViewer's scrollable code area when the file has no path to name it."
+  },
+  "@astryx.diffViewer.renamedPath": {
+    "defaultMessage": "{oldPath} → {newPath}",
+    "description": "File path shown in a lab DiffViewer header when the file was renamed. `{oldPath}` and `{newPath}` are file paths and must stay untranslated; keep the arrow pointing from the old path to the new one."
+  },
+  "@astryx.diffViewer.statusAdded": {
+    "defaultMessage": "Added",
+    "description": "Badge in a lab DiffViewer file header marking a file that the change creates."
+  },
+  "@astryx.diffViewer.statusDeleted": {
+    "defaultMessage": "Deleted",
+    "description": "Badge in a lab DiffViewer file header marking a file that the change removes."
+  },
+  "@astryx.diffViewer.statusRenamed": {
+    "defaultMessage": "Renamed",
+    "description": "Badge in a lab DiffViewer file header marking a file that the change moves to a new path."
+  },
+  "@astryx.diffViewer.addedCount": {
+    "defaultMessage": "+{count, number}",
+    "description": "Compact count of added lines shown in a lab DiffViewer file header, e.g. \"+12\". Hidden from screen readers, which hear `@astryx.diffViewer.stats` instead."
+  },
+  "@astryx.diffViewer.removedCount": {
+    "defaultMessage": "−{count, number}",
+    "description": "Compact count of removed lines shown in a lab DiffViewer file header, e.g. \"−3\" (a minus sign). Hidden from screen readers, which hear `@astryx.diffViewer.stats` instead."
+  },
+  "@astryx.diffViewer.stats": {
+    "defaultMessage": "{added, plural, one {# line added} other {# lines added}}, {removed, plural, one {# line removed} other {# lines removed}}",
+    "description": "Screen-reader text for the line counts in a lab DiffViewer file header, e.g. \"12 lines added, 3 lines removed\"."
+  },
+  "@astryx.diffViewer.added": {
+    "defaultMessage": "Added",
+    "description": "Screen-reader text marking one line of a lab DiffViewer as added by the change; sighted readers see a + sign and a tinted row."
+  },
+  "@astryx.diffViewer.removed": {
+    "defaultMessage": "Removed",
+    "description": "Screen-reader text marking one line of a lab DiffViewer as removed by the change; sighted readers see a - sign and a tinted row."
+  },
+  "@astryx.diffViewer.lineNumberButton": {
+    "defaultMessage": "{side, select, old {Original line {line, number}} other {Changed line {line, number}}}",
+    "description": "Accessible label of a clickable line number in a lab DiffViewer (callers use it, for example, to start a comment on that line). `side` is `old` for the file before the change and `new` for the file after it; `line` is the line number in that version."
+  },
+  "@astryx.diffViewer.columnOldLine": {
+    "defaultMessage": "Original line number",
+    "description": "Screen-reader-only header of a lab DiffViewer column holding line numbers in the file before the change. Pairs with `@astryx.diffViewer.lineNumberButton` (\"Original line …\")."
+  },
+  "@astryx.diffViewer.columnNewLine": {
+    "defaultMessage": "Changed line number",
+    "description": "Screen-reader-only header of a lab DiffViewer column holding line numbers in the file after the change. Pairs with `@astryx.diffViewer.lineNumberButton` (\"Changed line …\")."
+  },
+  "@astryx.diffViewer.columnChange": {
+    "defaultMessage": "Change",
+    "description": "Screen-reader-only header of a lab DiffViewer column that marks each line as added or removed (noun: the kind of change)."
+  },
+  "@astryx.diffViewer.columnCode": {
+    "defaultMessage": "Code",
+    "description": "Screen-reader-only header of the source-code column in a lab DiffViewer's single-column (unified) view."
+  },
+  "@astryx.diffViewer.columnOldCode": {
+    "defaultMessage": "Original code",
+    "description": "Screen-reader-only header of the source-code column for the file before the change, in a lab DiffViewer's side-by-side (split) view."
+  },
+  "@astryx.diffViewer.columnNewCode": {
+    "defaultMessage": "Changed code",
+    "description": "Screen-reader-only header of the source-code column for the file after the change, in a lab DiffViewer's side-by-side (split) view."
+  },
+  "@astryx.diffViewer.binary": {
+    "defaultMessage": "Binary file not shown",
+    "description": "Message in place of line changes in a lab DiffViewer when the file is binary and has no text diff."
+  },
+  "@astryx.diffViewer.noChanges": {
+    "defaultMessage": "No content changes",
+    "description": "Message in a lab DiffViewer when a file changed only its path or mode, so there are no line changes to show."
+  },
   "@astryx.markdownHeadingLinks.copied": {
     "defaultMessage": "Link copied",
     "description": "Accessible name on the Markdown heading copy button and text announced to a polite live region for ~1.5s after a successful copy. Sentence meaning \"Link copied\"; pairs with `markdownHeadingLinks.copy`."

package/locales/pseudo.json

@@ -395,6 +395,63 @@
   "@astryx.listInput.announceAlreadyAtBoundary": {
     "defaultMessage": "⟦Ţĥíš {itemName} íš àłřéàðý {boundary, select, first {first} last {last} other {}}.⟧"
   },
+  "@astryx.diffViewer.label": {
+    "defaultMessage": "⟦Ð탃⟧"
+  },
+  "@astryx.diffViewer.renamedPath": {
+    "defaultMessage": "⟦{oldPath} → {newPath}⟧"
+  },
+  "@astryx.diffViewer.statusAdded": {
+    "defaultMessage": "⟦Àððéð⟧"
+  },
+  "@astryx.diffViewer.statusDeleted": {
+    "defaultMessage": "⟦Ðéłéţéð⟧"
+  },
+  "@astryx.diffViewer.statusRenamed": {
+    "defaultMessage": "⟦Řéñàɱéð⟧"
+  },
+  "@astryx.diffViewer.addedCount": {
+    "defaultMessage": "⟦+{count, number}⟧"
+  },
+  "@astryx.diffViewer.removedCount": {
+    "defaultMessage": "⟦−{count, number}⟧"
+  },
+  "@astryx.diffViewer.stats": {
+    "defaultMessage": "⟦{added, plural, one {# line added} other {# lines added}}, {removed, plural, one {# line removed} other {# lines removed}}⟧"
+  },
+  "@astryx.diffViewer.added": {
+    "defaultMessage": "⟦Àððéð⟧"
+  },
+  "@astryx.diffViewer.removed": {
+    "defaultMessage": "⟦Řéɱóṽéð⟧"
+  },
+  "@astryx.diffViewer.lineNumberButton": {
+    "defaultMessage": "⟦{side, select, old {Original line {line, number}} other {Changed line {line, number}}}⟧"
+  },
+  "@astryx.diffViewer.columnOldLine": {
+    "defaultMessage": "⟦Óříĝíñàł łíñé ñúɱƀéř⟧"
+  },
+  "@astryx.diffViewer.columnNewLine": {
+    "defaultMessage": "⟦Çĥàñĝéð łíñé ñúɱƀéř⟧"
+  },
+  "@astryx.diffViewer.columnChange": {
+    "defaultMessage": "⟦Çĥàñĝé⟧"
+  },
+  "@astryx.diffViewer.columnCode": {
+    "defaultMessage": "⟦Çóðé⟧"
+  },
+  "@astryx.diffViewer.columnOldCode": {
+    "defaultMessage": "⟦Óříĝíñàł çóðé⟧"
+  },
+  "@astryx.diffViewer.columnNewCode": {
+    "defaultMessage": "⟦Çĥàñĝéð çóðé⟧"
+  },
+  "@astryx.diffViewer.binary": {
+    "defaultMessage": "⟦Ɓíñàřý ƒíłé ñóţ šĥóŵñ⟧"
+  },
+  "@astryx.diffViewer.noChanges": {
+    "defaultMessage": "⟦Ñó çóñţéñţ çĥàñĝéš⟧"
+  },
   "@astryx.markdownHeadingLinks.copied": {
     "defaultMessage": "⟦Łíñķ çóþíéð⟧"
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astryxdesign/core",
-  "version": "0.7.1",
+  "version": "0.7.2-canary.374b53a",
   "displayName": "Astryx Core",
   "description": "The component library. Accessible, themeable React components with built-in spacing, dark mode, and StyleX styling.",
   "author": "Meta Open Source",
@@ -787,6 +787,8 @@
     "react-dom": ">=19.0.0"
   },
   "devDependencies": {
+    "@astryxdesign/a11y-spec": "0.7.2-canary.374b53a",
+    "@astryxdesign/cli": "0.7.2-canary.374b53a",
     "@babel/cli": "^7.29.7",
     "@babel/core": "^7.29.7",
     "@babel/preset-react": "^7.29.7",
@@ -797,9 +799,7 @@
     "@testing-library/jest-dom": "^6.6.0",
     "@testing-library/react": "^16.3.2",
     "@types/babel__core": "^7.20.5",
-    "tailwindcss": "^4.3.2",
-    "@astryxdesign/a11y-spec": "0.0.0",
-    "@astryxdesign/cli": "0.7.1"
+    "tailwindcss": "^4.3.2"
   },
   "dependencies": {
     "intl-messageformat": "^11.2.9"

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)', () => {

package/src/Button/Button.tsx

@@ -594,26 +594,37 @@ export function Button({
   // the consumer is deliberately showing it.
   const delaySpinner = isPending || isInterruptible;
   const groupDisabled = buttonGroup?.isDisabled ?? false;
-  // When interruptible, the loading state drives the spinner and aria-busy but
-  // not disabled, so clicks keep landing and can interrupt the in-flight action.
-  const buttonDisabled =
-    isDisabled || groupDisabled || (isLoadingState && !isInterruptible);
-  // A loading button remains non-interactive, but its spinner communicates an
-  // active state and must retain contrast. Only explicitly disabled controls
-  // receive the visually dimmed treatment.
-  const visuallyDisabled = isDisabled || groupDisabled;
+  const isTrueDisabled = isDisabled || groupDisabled;
+  // Busy-only: the button can't fire again purely because an action is in
+  // flight, not because it's genuinely isDisabled/group-disabled. Per the API
+  // Conventions "Disabled vs Busy" rule, busy is visual-only (aria-busy +
+  // spinner) and must never take focusability away — the click-handler ref
+  // guard (actionInFlightRef) is what actually makes a fire-once action fire
+  // once, so the native disabled attribute adds nothing but a focus loss
+  // here. When interruptible, the loading state drives the spinner and
+  // aria-busy but not disabled at all, so clicks keep landing and can
+  // interrupt the in-flight action.
+  const isBusyOnlyDisabled =
+    !isTrueDisabled && isLoadingState && !isInterruptible;
+  const buttonDisabled = isTrueDisabled || isBusyOnlyDisabled;
   // isIconOnly prop is the source of truth for icon-only rendering.
   // When false (default), label is always rendered as visible text.
 
   const LinkComponent = useLinkComponent(as);
 
-  // Render as link when href is provided and button is not disabled.
-  // Disabled links are an accessibility anti-pattern — fall back to <button>.
-  const renderAsLink = href != null && !buttonDisabled;
+  // Render as link when href is provided and the button is not TRULY
+  // disabled. Disabled links are an accessibility anti-pattern, so a
+  // genuinely isDisabled/group-disabled button falls back to <button>.
+  // Busy-only does NOT fall back: swapping <a> for a disabled <button>
+  // mid-action would drop focus the same way the native attribute does
+  // (credit @AKnassa, #4879), which is exactly the bug this PR fixes.
+  const renderAsLink = href != null && !isTrueDisabled;
 
-  // Use aria-disabled when tooltip is present so the button remains focusable
-  // for keyboard users to reach the tooltip. Otherwise use native disabled.
-  const useAriaDisabled = tooltip != null && buttonDisabled;
+  // Use aria-disabled (button stays focusable) when busy-only, or when a
+  // tooltip is present so keyboard users can still reach it. A genuinely
+  // isDisabled/group-disabled button (not busy) keeps native disabled.
+  const useAriaDisabled =
+    buttonDisabled && (isBusyOnlyDisabled || tooltip != null);
 
   // Attach tooltip behavior via the hook rather than wrapping the button in a
   // <Tooltip> element. The hook adds hover/focus triggers to the button itself,
@@ -630,6 +641,16 @@ export function Button({
     // a re-click while pending starts a fresh action that interrupts the prior.
     if (buttonDisabled || (actionInFlightRef.current && !isInterruptible)) {
       e.preventDefault();
+      // A native `disabled` element never dispatches a click at all, so it
+      // never reaches a wrapping element's own handler either. An
+      // aria-disabled button (busy-only, or with a tooltip) is still a real,
+      // interactive element the DOM keeps dispatching clicks on —
+      // preventDefault alone only cancels the button's OWN default action
+      // (form submit, link navigation), not propagation. Without this, an
+      // unavailable Button inside a clickable row/card/backdrop still
+      // triggers that ancestor's action, which the previously native-disabled
+      // control never did.
+      e.stopPropagation();
       return;
     }
     props.onClick?.(e);
@@ -669,7 +690,7 @@ export function Button({
     isIconOnly && styles.iconOnly,
     interactionOverlayStyles.backgroundImage,
     buttonDisabled && styles.inactive,
-    visuallyDisabled && styles.disabled,
+    isTrueDisabled && styles.disabled,
     useAriaDisabled && styles.ariaDisabled,
     renderAsLink && styles.link,
     !buttonGroup && styles.pressable,
@@ -797,7 +818,9 @@ export function Button({
         {...describedByProp}
         {...edgeCompAttr}
         aria-busy={isLoadingState || undefined}
-        onClick={handleClick}>
+        aria-disabled={useAriaDisabled || undefined}
+        onClick={handleClick}
+        {...(handleKeyDown ? {onKeyDown: handleKeyDown} : null)}>
         {buttonContent}
       </LinkComponent>
     );