Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

fix(lab): CommentPin stays focusable when disabled (#8816)

Pushpak Siva Sai5ef9ab6301f0
diff --git a/packages/lab/src/CommentPin/CommentPin.doc.mjs b/packages/lab/src/CommentPin/CommentPin.doc.mjs
index 2d459bd1b3..eba2cd98ab 100644
--- a/packages/lab/src/CommentPin/CommentPin.doc.mjs
+++ b/packages/lab/src/CommentPin/CommentPin.doc.mjs
@@ -122,7 +122,7 @@ export const docs = {
name: 'isDisabled',
type: 'boolean',
description:
- 'Disables activation with native button semantics. Useful for a pending anchor before its thread exists.',
+ 'Disables activation: the pin exposes aria-disabled, keeps its tab stop, and blocks every activation path. Useful for a pending anchor before its thread exists.',
default: 'false',
},
{
@@ -164,7 +164,7 @@ export const docs = {
category: 'Keyboard',
criterion: '2.1.1 Keyboard',
description:
- 'CommentPin is one native button. Tab reaches an enabled pin; Enter and Space activate it. A disabled pin uses native disabled semantics and is removed from sequential focus order.',
+ 'CommentPin is one native button. Tab reaches an enabled pin; Enter and Space activate it. A disabled pin stays in the tab order and is announced as disabled through aria-disabled, and every activation path is blocked.',
},
{
name: 'Selected state and name',
@@ -323,7 +323,8 @@ export const docsZh = {
isDimmed:
'其他标记被选中时降低此标记的视觉突出度,但不禁用操作;未选中任何标记时不应降低。',
isResolved: '所代表的线程是否都已解决;已解决的标记除非被选中否则不渲染。',
- isDisabled: '使用原生按钮语义禁用激活。',
+ isDisabled:
+ '通过 aria-disabled 禁用激活:保留 Tab 焦点,拦截所有激活路径。',
onClick: '由产品拥有的激活处理函数。',
xstyle: '根按钮的 StyleX 布局样式;由宿主决定内容上方或边距中的位置。',
},
@@ -369,7 +370,8 @@ export const docsDense = {
isDimmed:
'controlled de-emphasis for non-selected siblings only while another pin is selected; remains interactive',
isResolved: 'resolved pins render nothing unless selected',
- isDisabled: 'native disabled marker',
+ isDisabled:
+ 'disabled marker: aria-disabled, keeps its tab stop, blocks every activation path',
onClick: 'host activation handler',
xstyle: 'root layout/positioning styles; marker owns no coordinates',
},
diff --git a/packages/lab/src/CommentPin/CommentPin.spec.md b/packages/lab/src/CommentPin/CommentPin.spec.md
index 96ad0e0b74..fef4ba9b30 100644
--- a/packages/lab/src/CommentPin/CommentPin.spec.md
+++ b/packages/lab/src/CommentPin/CommentPin.spec.md
@@ -156,18 +156,18 @@ intentional decision. A `current` contract contains no unresolved rows.
### Representative states
-| State | Required invariant | Allowed variation |
-| ------------------------ | --------------------------------------------------------------------------------------- | ------------------------------------------------------------ |
-| Single | first participant Avatar; no visible count; an accent dot after it when unread | identity, selected/dimmed/resolved/disabled state, placement |
-| Grouped, one identity | one Avatar plus total thread count | count and states |
-| Grouped, two or three | every distinct participant Avatar plus total thread count | ordered identities, count, and states |
-| Grouped, more than three | first two distinct Avatars, an ellipsis overflow circle, and total thread count | ordered identities and states |
-| Unread | accent dot after the total, or after the participant on a single marker | other states |
-| Sizes | 28, 32, or 36px tall with 22, 24, or 28px circles and the same inset on every side | every other state |
-| Selected | active accent treatment preserves Avatar and count legibility and wins over dimming | theme paint |
-| Dimmed | lower opacity identifies a non-selected sibling without disabling activation | disabled may also apply |
-| Resolved | renders nothing unless selected; selected, it takes the selected treatment | disabled may also apply |
-| Disabled | native disabled button does not activate and is removed from the sequential focus order | selected representation remains visible |
+| State | Required invariant | Allowed variation |
+| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
+| Single | first participant Avatar; no visible count; an accent dot after it when unread | identity, selected/dimmed/resolved/disabled state, placement |
+| Grouped, one identity | one Avatar plus total thread count | count and states |
+| Grouped, two or three | every distinct participant Avatar plus total thread count | ordered identities, count, and states |
+| Grouped, more than three | first two distinct Avatars, an ellipsis overflow circle, and total thread count | ordered identities and states |
+| Unread | accent dot after the total, or after the participant on a single marker | other states |
+| Sizes | 28, 32, or 36px tall with 22, 24, or 28px circles and the same inset on every side | every other state |
+| Selected | active accent treatment preserves Avatar and count legibility and wins over dimming | theme paint |
+| Dimmed | lower opacity identifies a non-selected sibling without disabling activation | disabled may also apply |
+| Resolved | renders nothing unless selected; selected, it takes the selected treatment | disabled may also apply |
+| Disabled | an aria-disabled button does not activate but keeps its tab stop, so keyboard and screen-reader users reach it and hear it is unavailable; an unselected disabled pin paints GrayText color and border under forced colors | selected representation remains visible, keeping its Highlight treatment |
### Transformation and precedence order
@@ -203,7 +203,8 @@ durable constraints and their verification target.
## Accessibility contract
- **AR1 — Action.** The root is one native `button type="button"` named by the
- required `label`; `isDisabled` uses native disabled behavior.
+ required `label`; `isDisabled` exposes `aria-disabled="true"` and blocks every
+ activation path while the pin keeps its tab stop (`spec:AST-085`).
- **AR2 — Selection.** `isSelected` is exposed through `aria-pressed`, one solid
2px accent outline outside the pin, and a forced-colors Highlight treatment;
the outline hugs the pin while the shared focus-visible outline sits farther
diff --git a/packages/lab/src/CommentPin/CommentPin.test.tsx b/packages/lab/src/CommentPin/CommentPin.test.tsx
index eee5ba1e7c..6d945e24a2 100644
--- a/packages/lab/src/CommentPin/CommentPin.test.tsx
+++ b/packages/lab/src/CommentPin/CommentPin.test.tsx
@@ -3,6 +3,8 @@
import {describe, expect, it, vi} from 'vitest';
import {fireEvent, render, screen, waitFor} from '@testing-library/react';
import userEvent from '@testing-library/user-event';
+import * as stylex from '@stylexjs/stylex';
+import {colorVars} from '@astryxdesign/core/theme/tokens.stylex';
import {CommentPin} from './CommentPin';
const ADA = {id: 'ada', name: 'Ada Lovelace'};
@@ -229,7 +231,8 @@ describe('CommentPin', () => {
name: 'Resolved selected annotation',
});
expect(marker).toHaveAttribute('aria-pressed', 'true');
- expect(marker).toBeDisabled();
+ expect(marker).not.toBeDisabled();
+ expect(marker).toHaveAttribute('aria-disabled', 'true');
expect(marker).toHaveAttribute('data-selected', 'selected');
expect(marker).toHaveAttribute('data-resolved', 'resolved');
expect(marker).toHaveAttribute('data-disabled', 'disabled');
@@ -313,6 +316,33 @@ describe('CommentPin', () => {
expect(onClick).toHaveBeenCalledTimes(2);
});
+ it('exposes aria-disabled instead of the native attribute when disabled', () => {
+ render(
+ <CommentPin label="Pending annotation" participants={[ADA]} isDisabled />,
+ );
+
+ const pin = screen.getByRole('button', {name: 'Pending annotation'});
+ expect(pin).not.toBeDisabled();
+ expect(pin).toHaveAttribute('aria-disabled', 'true');
+ });
+
+ it('keeps a disabled pin in the tab order (spec:AST-085 FR1)', async () => {
+ const user = userEvent.setup();
+ render(<CommentPin label="Open annotation" participants={[ADA]} />);
+ render(
+ <CommentPin label="Pending annotation" participants={[LIN]} isDisabled />,
+ );
+ render(<CommentPin label="Another annotation" participants={[MIRA]} />);
+
+ await user.tab();
+ // The first tab stop is the enabled pin; the disabled one keeps its place
+ // right after it rather than being skipped.
+ await user.tab();
+ expect(
+ screen.getByRole('button', {name: 'Pending annotation'}),
+ ).toHaveFocus();
+ });
+
it('does not call the click handler when disabled', () => {
const onClick = vi.fn();
render(
@@ -328,6 +358,152 @@ describe('CommentPin', () => {
expect(onClick).not.toHaveBeenCalled();
});
+ it('blocks Enter and Space on a disabled pin (spec:AST-085 FR2)', async () => {
+ const user = userEvent.setup();
+ const onClick = vi.fn();
+ render(
+ <CommentPin
+ label="Pending annotation"
+ participants={[ADA]}
+ isDisabled
+ onClick={onClick}
+ />,
+ );
+
+ // user-event only synthesizes the button's Enter/Space click when the
+ // keydown was not defaultPrevented, and a native listener on the pin sees
+ // any click that does reach the DOM. No click at all is what proves the
+ // keydown guard blocked activation itself, not just the click guard.
+ const nativeClicks = vi.fn();
+ const pin = screen.getByRole('button', {name: 'Pending annotation'});
+ pin.addEventListener('click', nativeClicks);
+
+ pin.focus();
+ await user.keyboard('{Enter}');
+ await user.keyboard(' ');
+ pin.removeEventListener('click', nativeClicks);
+
+ expect(onClick).not.toHaveBeenCalled();
+ expect(nativeClicks).not.toHaveBeenCalled();
+ });
+
+ it('does not let a disabled pin activate a clickable ancestor (spec:AST-085 FR2)', () => {
+ const surfaceClick = vi.fn();
+ const onClick = vi.fn();
+ render(
+ <div role="button" onClick={surfaceClick} aria-label="Annotation surface">
+ <CommentPin
+ label="Pending annotation"
+ participants={[ADA]}
+ isDisabled
+ onClick={onClick}
+ />
+ </div>,
+ );
+
+ fireEvent.click(screen.getByRole('button', {name: 'Pending annotation'}));
+ expect(onClick).not.toHaveBeenCalled();
+ expect(surfaceClick).not.toHaveBeenCalled();
+ });
+
+ it('keeps focus when the pin becomes disabled while focused (spec:AST-085 FR4)', () => {
+ // jsdom keeps focus on a natively disabled button too, so on its own this
+ // cannot tell the two apart; the FR1 tests above pin the mechanism (no
+ // native `disabled`), which is what keeps focus here. A real-browser
+ // probe would be needed to prove FR4 independently.
+ const {rerender} = render(
+ <CommentPin label="Open annotation" participants={[ADA]} />,
+ );
+
+ const pin = screen.getByRole('button', {name: 'Open annotation'});
+ pin.focus();
+ expect(pin).toHaveFocus();
+
+ rerender(
+ <CommentPin label="Open annotation" participants={[ADA]} isDisabled />,
+ );
+ expect(pin).toHaveFocus();
+ expect(pin).toHaveAttribute('aria-disabled', 'true');
+ });
+
+ it('paints an unselected disabled pin GrayText in forced colors (AST-085 FR6)', () => {
+ // The same declarations as the component's styles compile to the same
+ // atomic classes. Null defaults emit no atom of their own, so these are
+ // exactly the forced-colors arms — the shared default-mode atoms
+ // (borderColor: transparent) cannot make this check pass vacuously.
+ const atoms = (style: stylex.StyleXStyles) =>
+ stylex
+ .props(style)
+ .className!.split(' ')
+ .filter(name => name.includes('x') && !name.includes('__'));
+ const forced = stylex.create({
+ disabled: {
+ borderColor: {
+ default: null,
+ '@media (forced-colors: active)': 'GrayText',
+ },
+ color: {default: null, '@media (forced-colors: active)': 'GrayText'},
+ },
+ });
+ const forcedAtoms = atoms(forced.disabled);
+ expect(forcedAtoms.length).toBeGreaterThan(0);
+
+ const {rerender} = render(
+ <CommentPin label="Pending annotation" participants={[ADA]} isDisabled />,
+ );
+
+ const pin = screen.getByRole('button', {name: 'Pending annotation'});
+ for (const name of forcedAtoms) {
+ expect(pin).toHaveClass(name);
+ }
+
+ // A selected pin keeps its forced-colors Highlight treatment instead; the
+ // disabled affordance rides on the selected presentation staying intact.
+ rerender(
+ <CommentPin
+ label="Pending annotation"
+ participants={[ADA]}
+ isDisabled
+ isSelected
+ />,
+ );
+ for (const name of forcedAtoms) {
+ expect(pin).not.toHaveClass(name);
+ }
+ });
+
+ it('keeps the root text colour on an unselected disabled pin outside forced colors', () => {
+ // disabledUnselected must repeat the root's colour token as its default:
+ // a null default would replace it under StyleX's per-property merge and
+ // the count would fall back to the raw theme text colour.
+ const atoms = (style: stylex.StyleXStyles) =>
+ stylex
+ .props(style)
+ .className!.split(' ')
+ .filter(name => name.includes('x') && !name.includes('__'));
+ const rootColor = stylex.create({
+ color: {color: colorVars['--color-text-secondary']},
+ });
+ const colorAtoms = atoms(rootColor.color);
+ expect(colorAtoms.length).toBeGreaterThan(0);
+
+ render(
+ <CommentPin
+ label="Open 3 grouped annotations"
+ participants={[ADA]}
+ threadCount={3}
+ isDisabled
+ />,
+ );
+
+ const pin = screen.getByRole('button', {
+ name: 'Open 3 grouped annotations',
+ });
+ for (const name of colorAtoms) {
+ expect(pin).toHaveClass(name);
+ }
+ });
+
it('forwards the ref and neutral button props', () => {
const ref = {current: null as HTMLButtonElement | null};
render(
diff --git a/packages/lab/src/CommentPin/CommentPin.tsx b/packages/lab/src/CommentPin/CommentPin.tsx
index 0c7166d786..b819073686 100644
--- a/packages/lab/src/CommentPin/CommentPin.tsx
+++ b/packages/lab/src/CommentPin/CommentPin.tsx
@@ -206,6 +206,21 @@ const styles = stylex.create({
'@media (forced-colors: active)': 1,
},
},
+ // An aria-disabled button gets no system disabled paint in forced colors;
+ // GrayText is the platform's disabled affordance there. Defaults repeat the
+ // base values, since StyleX merges per property. Only unselected pins take
+ // it — the selected treatment keeps its forced-colors Highlight, so a
+ // selected disabled pin stays prominent (ORD4).
+ disabledUnselected: {
+ borderColor: {
+ default: 'transparent',
+ '@media (forced-colors: active)': 'GrayText',
+ },
+ color: {
+ default: colorVars['--color-text-secondary'],
+ '@media (forced-colors: active)': 'GrayText',
+ },
+ },
avatarRail: {
display: 'inline-flex',
alignItems: 'center',
@@ -463,7 +478,34 @@ export function CommentPin({
type="button"
aria-label={label}
aria-pressed={isSelected}
- disabled={isDisabled}
+ // A disabled pin keeps its tab stop and is announced as disabled through
+ // aria-disabled instead of the native attribute (spec:AST-085 FR1). The
+ // activation guards below keep it inert (FR2); focus is kept when the
+ // pin becomes disabled while focused (FR4), and the shared focus outline
+ // still paints, dimmed with the rest of the pin (FR6).
+ aria-disabled={isDisabled ? 'true' : undefined}
+ onClick={e => {
+ if (isDisabled) {
+ // A natively disabled element dispatched no click at all, so an
+ // aria-disabled pin must not reach the caller's handler, and the
+ // click must not leak to a clickable ancestor (annotation surface)
+ // the native attribute never let it reach either (FR2).
+ e.preventDefault();
+ e.stopPropagation();
+ return;
+ }
+ rest.onClick?.(e);
+ }}
+ // The keyboard paths to activation are Enter and Space; other keys still
+ // reach caller handlers, as on an enabled pin (FR2).
+ onKeyDown={e => {
+ if (isDisabled && (e.key === 'Enter' || e.key === ' ')) {
+ e.preventDefault();
+ e.stopPropagation();
+ return;
+ }
+ rest.onKeyDown?.(e);
+ }}
{...mergeProps(
themeProps('comment-pin', {
size: resolvedSize,
@@ -482,6 +524,7 @@ export function CommentPin({
isDimmed && !isSelected && styles.dimmed,
isSelected && styles.selected,
isDisabled && styles.disabled,
+ isDisabled && !isSelected && styles.disabledUnselected,
xstyle,
),
className,