fix(citation): only use doc-noteref role on the linked form (#3546)

Author: cixzhang

.changeset/citation-doc-noteref-role.md

@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[fix] Citation: only apply `role="doc-noteref"` on the linked (anchor) form. On a plain unlinked span the role is not permitted (axe: aria-allowed-role), so it is omitted there while the `aria-label` still names the citation. (#3343)
+
+@cixzhang

packages/core/src/Citation/Citation.test.tsx

@@ -61,7 +61,11 @@ describe('Citation', () => {
         data-testid="citation"
       />,
     );
-    expect(screen.getByTestId('citation').tagName).toBe('SPAN');
+    const el = screen.getByTestId('citation');
+    expect(el.tagName).toBe('SPAN');
+    // doc-noteref is a reference role that is not permitted on a plain
+    // (unlinked) span (axe: aria-allowed-role), so it must be omitted here.
+    expect(el).not.toHaveAttribute('role');
   });
 
   it('renders astryx-* class names for theme targeting', () => {

packages/core/src/Citation/Citation.tsx

@@ -158,6 +158,10 @@ export function Citation({
   const href = source.url;
   const icon = source.icon;
   const Tag = href ? 'a' : 'span';
+  // `doc-noteref` is a reference role — only appropriate on the interactive
+  // link form. On a plain (unlinked) span it is not a permitted role
+  // (axe: aria-allowed-role), so omit it there; the aria-label still names it.
+  const noteRole = href ? ('doc-noteref' as const) : undefined;
   const linkProps = href
     ? {
         href,
@@ -176,7 +180,7 @@ export function Citation({
       <Tag
         {...rest}
         ref={elementRef}
-        role="doc-noteref"
+        role={noteRole}
         aria-label={`Citation ${number}: ${title}`}
         data-testid={testId}
         {...linkProps}
@@ -199,7 +203,7 @@ export function Citation({
     <Tag
       {...rest}
       ref={elementRef}
-      role="doc-noteref"
+      role={noteRole}
       aria-label={`Citation ${number}: ${title}`}
       data-testid={testId}
       {...linkProps}