From 21b5ff5f65a38cfdf7113609ec65ad033c16b237 Mon Sep 17 00:00:00 2001
From: Burcu Noyan <burcunoyan@gmail.com>
Date: Fri, 24 Jul 2026 18:20:40 -0400
Subject: [PATCH] Announce Button's disabled links to assistive tech (CS-12305)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Button already styles a hrefless anchor as a disabled link — the CSS has
matched a.boxel-button:not([href]), [href=''] and .disabled-link for a
while (opacity, disabled colour, pointer-events: none). But the @as='anchor'
branch only suppresses the href: no disabled attribute, no aria-disabled.
So the state has been visual-only for every caller, and @disabled={{true}}
on an anchor produced DOM identical to just omitting @href.

role='link' is the part that makes this work. An <a> we've stripped the
href from is not a link — it maps to the generic role, where aria-disabled
is not supported and browsers drop it. Setting aria-disabled alone would
have looked like a fix and changed nothing.

Keyed on @disabled only, deliberately never on a falsy @href: callers pass
href as a plain attribute through ...attributes (base/skill-plus.gts,
base/default-templates/theme-dashboard.gts), where @href is undefined and
the link is real. Inferring from @href would have labelled those
unavailable. There is a test guarding exactly that.

Also adds the first test coverage for Button.

Not verified at runtime: the boxel-ui test-app harness fails at boot
locally with "window.require is not a function", before any test runs. It
does so identically on a clean checkout with an untouched accordion test,
and after mise run build:ui, so it is pre-existing and not caused by this
change. eslint, ember-template-lint and ember-tsc pass in both the addon
and test-app; CI is the real gate for the assertions.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 .../addon/src/components/button/index.gts     | 11 +++
 .../integration/components/button-test.gts    | 95 +++++++++++++++++++
 2 files changed, 106 insertions(+)
 create mode 100644 packages/boxel-ui/test-app/tests/integration/components/button-test.gts

diff --git a/packages/boxel-ui/addon/src/components/button/index.gts b/packages/boxel-ui/addon/src/components/button/index.gts
index db083b4f02..404096929e 100644
--- a/packages/boxel-ui/addon/src/components/button/index.gts
+++ b/packages/boxel-ui/addon/src/components/button/index.gts
@@ -100,9 +100,20 @@ const ButtonComponent: TemplateOnlyComponent<Signature> = <template>
         {{yield}}
       </button>
     {{else if (eq @as 'anchor')}}
+      {{! An <a> we've stripped the href from is not a link — it maps to the
+          generic role, where aria-disabled is not supported and gets dropped.
+          role='link' is what makes the disabled state reach assistive tech;
+          without it the CSS below fades the element and announces nothing.
+
+          Keyed on @disabled only, never on a falsy @href: callers are free to
+          pass href as a plain attribute through ...attributes (see
+          base/skill-plus.gts, base/default-templates/theme-dashboard.gts), and
+          those are real links that must not be labelled unavailable. }}
       <a
         class={{classes}}
         href={{unless @disabled (if @href (sanitizeHtml @href))}}
+        role={{if @disabled 'link'}}
+        aria-disabled={{if @disabled 'true'}}
         data-test-boxel-button
         ...attributes
       >
diff --git a/packages/boxel-ui/test-app/tests/integration/components/button-test.gts b/packages/boxel-ui/test-app/tests/integration/components/button-test.gts
new file mode 100644
index 0000000000..02e13b6d6e
--- /dev/null
+++ b/packages/boxel-ui/test-app/tests/integration/components/button-test.gts
@@ -0,0 +1,95 @@
+import { render } from '@ember/test-helpers';
+import { module, test } from 'qunit';
+import { setupRenderingTest } from 'test-app/tests/helpers';
+import { Button } from '@cardstack/boxel-ui/components';
+
+module('Integration | Component | button', function (hooks) {
+  setupRenderingTest(hooks);
+
+  test('renders a <button> by default and when @as="button"', async function (assert) {
+    await render(
+      <template>
+        <Button>Go</Button>
+      </template>,
+    );
+    assert.dom('[data-test-boxel-button]').hasTagName('button');
+    assert
+      .dom('[data-test-boxel-button]')
+      .doesNotHaveAttribute('aria-disabled');
+
+    await render(
+      <template>
+        <Button @as='button'>Go</Button>
+      </template>,
+    );
+    assert.dom('[data-test-boxel-button]').hasTagName('button');
+  });
+
+  test('@as="anchor" renders a link with the sanitized href', async function (assert) {
+    await render(
+      <template>
+        <Button @as='anchor' @href='https://example.com/x'>Go</Button>
+      </template>,
+    );
+    assert.dom('[data-test-boxel-button]').hasTagName('a');
+    assert
+      .dom('[data-test-boxel-button]')
+      .hasAttribute('href', 'https://example.com/x');
+  });
+
+  // An <a> with no href maps to the generic role, where aria-disabled is not
+  // supported — so role='link' is what makes the state reach assistive tech.
+  test('a disabled anchor is announced as an unavailable link', async function (assert) {
+    await render(
+      <template>
+        <Button @as='anchor' @href='https://example.com/x' @disabled={{true}}>
+          Go
+        </Button>
+      </template>,
+    );
+    assert.dom('[data-test-boxel-button]').doesNotHaveAttribute('href');
+    assert.dom('[data-test-boxel-button]').hasAttribute('role', 'link');
+    assert.dom('[data-test-boxel-button]').hasAria('disabled', 'true');
+  });
+
+  test('an enabled anchor carries neither role nor aria-disabled', async function (assert) {
+    await render(
+      <template>
+        <Button @as='anchor' @href='https://example.com/x' @disabled={{false}}>
+          Go
+        </Button>
+      </template>,
+    );
+    assert.dom('[data-test-boxel-button]').doesNotHaveAttribute('role');
+    assert
+      .dom('[data-test-boxel-button]')
+      .doesNotHaveAttribute('aria-disabled');
+  });
+
+  // Regression guard: the disabled state is keyed on @disabled, never on a
+  // falsy @href. Callers legitimately pass href as a plain attribute through
+  // ...attributes (base/skill-plus.gts, base/default-templates/theme-dashboard.gts),
+  // and those are real links that must not be labelled unavailable.
+  test('an href passed via ...attributes is not treated as disabled', async function (assert) {
+    await render(
+      <template>
+        <Button @as='anchor' href='#top'>Back to top</Button>
+      </template>,
+    );
+    assert.dom('[data-test-boxel-button]').hasAttribute('href', '#top');
+    assert.dom('[data-test-boxel-button]').doesNotHaveAttribute('role');
+    assert
+      .dom('[data-test-boxel-button]')
+      .doesNotHaveAttribute('aria-disabled');
+  });
+
+  test('a disabled <button> keeps the native disabled attribute', async function (assert) {
+    await render(
+      <template>
+        <Button @disabled={{true}}>Go</Button>
+      </template>,
+    );
+    assert.dom('[data-test-boxel-button]').isDisabled();
+    assert.dom('[data-test-boxel-button]').hasAria('disabled', 'true');
+  });
+});