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.mjsindex 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.mdindex 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 solid2px accent outline outside the pin, and a forced-colors Highlight treatment;the outline hugs the pin while the shared focus-visible outline sits fartherdiff --git a/packages/lab/src/CommentPin/CommentPin.test.tsx b/packages/lab/src/CommentPin/CommentPin.test.tsxindex 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.tsxindex 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,