fix(core): keep busy Button focusable, recover from failed clickAction

[AKnassa]

Fixes #4871

What happens today

While a clickAction is pending (or isLoading is set), Button sets the native disabled attribute. A natively disabled element cannot hold focus, so the browser drops keyboard focus to <body> the moment the action starts — the next Tab restarts from the top of the document, and nothing is announced when the action completes. This is the deviation already documented in the API Conventions wiki ("Disabled vs Busy" → Known deviation).

What this PR does

Busy no longer uses the native attribute (first commit):

• Only hard-disabled (isDisabled / ButtonGroup disabled) may set native disabled; that behavior is unchanged.
• A busy button stays focusable and announces aria-busy="true" + aria-disabled="true".
• Re-activation is blocked in the handlers instead: the existing handleClick ref guard covers the pointer path, and the existing aria-disabled keydown path (previously tooltip-only) now also suppresses Enter/Space while busy. Fire-once actions still fire exactly once — the same-tick double-click dedupe is untouched.
• With href, a busy button now stays an anchor instead of swapping to a disabled <button> mid-action — the element swap dropped focus the same way the attribute did.
• isInterruptible is unchanged (interactive while pending: aria-busy without aria-disabled).

A rejected clickAction no longer bricks the button (second commit, found while stress-testing the busy state):

• The rejection used to escape the startTransition async scope, so the transition never settled — isPending stuck true, the spinner never left, and the guard blocked every retry until remount. Latent on main too, where it presented as disabled-forever.
• The action now catches the rejection, reports it via devError (the established runtime-failure channel, cf. Table plugins), and settles; the finally still resets the in-flight guard so the user can retry.

Behavior table

State	disabled attr	aria-busy	aria-disabled	Focusable	Activation
idle	–	–	–	yes	fires
busy (pending action / isLoading)	–	✓	✓	yes	guarded in handlers
busy + isInterruptible	–	✓	–	yes	fires (interrupts)
isDisabled (no tooltip)	✓	–	–	no	blocked
isDisabled + tooltip	–	–	✓	yes (to reach tooltip)	blocked
isDisabled + isLoading	✓	✓	–	no	blocked

Testing

• 26 Button tests around this contract, including 11 edge cases: tooltip+busy, isDisabled+isLoading precedence, ButtonGroup disabled (with/without tooltip), interruptible boundaries, form-submit suppression while busy, disabled-link fallback, busy-anchor focusability, and rejected-action recovery. Written red-first against the old code.
• Full suite: 9547 pass; the only 2 failures are the pre-existing packages/cli name-resolution failures, identical on an untouched main baseline.
• Real-browser check (Storybook, Chromium): busy button has no disabled attribute, Tab lands on it, and the :focus-visible ring renders around the spinner.
• Core typecheck, check:repo (incl. changesets), eslint CI=true, prettier: all green. Changeset included (@astryxdesign/core patch).

Notes for review

• aria-disabled="true" on the busy anchor: valid ARIA, but if you'd rather busy links carry only aria-busy, that's a one-line change.
• Busy keeps the existing disabled visual (50% opacity, not-allowed cursor) — conforms to the wiki table ("reduced opacity"); no visual delta intended.
• Every other startTransition(async …) call site in core (Selector, Pagination, ComplexSelector, TimeInput, …) has the same unguarded await and can strand isPending on a rejected action. Deliberately not touched here — happy to follow up separately.
• The wiki's "Known deviation" paragraph under Disabled vs Busy can be deleted when this merges.

[vercel]

@AKnassa is attempting to deploy a commit to the Meta Open Source Team on Vercel.

A member of the Team first needs to authorize it.

[github-actions]

PR Analysis Report

📚 Storybook Preview

View Storybook for this PR
GitHub Pages may take up to a minute to hydrate after deploy.

🧪 Sandbox Preview

View Sandbox for this PR
GitHub Pages may take up to a minute to hydrate after deploy.

Modified Components

Button _{(@astryxdesign/core)} · View in Storybook

Metric	Before	After	Delta
Bundle Size (ESM)	N/A	N/A	N/A
Lines of Code	N/A	566	-
Complexity	N/A	Very High (66)	-

IconButton _{(@astryxdesign/core)} · View in Storybook

Metric	Before	After	Delta
Bundle Size (ESM)	N/A	N/A	N/A
Lines of Code	N/A	17	-
Complexity	N/A	Low (1)	-

Bundle Size Summary

Package	Size (ESM)	Size (CJS)	Gzipped
@astryxdesign/core	N/A	4.7KB	1.2KB

Accessibility Audit

Status: No accessibility violations detected.

---

_{Generated by PR Enrichment workflow | Storybook | Sandbox | View full report}

[astracat-bot]

Thanks for restoring keyboard focus while a Button is busy and for making a failed action retryable — the hard-disabled/busy split, docs, and edge-case tests make that contract clear.

One fix is needed before this is ready: a busy link-rendered Button still forwards Enter/Space to a consumer onKeyDown handler while it exposes aria-disabled="true". In packages/core/src/Button/Button.tsx, the link branch spreads the consumer props and overrides only onClick; the handleKeyDown guard that suppresses activation keys (and forwards other keys) is installed only on the native <button> branch. So <Button href="/docs" isLoading onKeyDown={handler} /> can run consumer keyboard side effects in a state announced as disabled, even though click activation is suppressed.

Please apply the same activation-key guard to the link branch and add a regression test showing Enter/Space do not reach consumer onKeyDown while busy, while a non-activation key still does. The busy-link tests currently cover focus and click suppression only.

[Automated review]

[AKnassa]

Closing this in favour of #4885. @cixzhang picked it as the canonical fix for #4871, and it already carries the busy-href anchor preservation from here. Thanks @HelloOjasMutreja for the credit.

The one open review point on this PR also applies to #4885, so I've left a note there: a busy link-rendered Button still forwards Enter/Space to a consumer onKeyDown while it's aria-disabled.

The only piece #4885 doesn't cover is catching a rejected clickAction. On React 19 a rejected action goes to the error boundary rather than leaving the spinner stuck, so whether Button should swallow it is a contract question rather than a fix. I'm happy to open an issue if that's useful.