@astryxdesign/lab 0.7.6-canary.df8928a → 0.7.6-canary.eaae8e3

package/dist/CommentPin/CommentPin.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"CommentPin.d.ts","sourceRoot":"","sources":["../../src/CommentPin/CommentPin.tsx"],"names":[],"mappings":"AAyBA,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,oBAAoB,CAAC;AA4BlD,qEAAqE;AACrE,MAAM,MAAM,cAAc,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;AAEhD,sEAAsE;AACtE,MAAM,WAAW,qBAAqB;IACpC,gEAAgE;IAChE,EAAE,EAAE,MAAM,CAAC;IACX,+DAA+D;IAC/D,IAAI,EAAE,MAAM,CAAC;IACb,8CAA8C;IAC9C,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,eAAgB,SAAQ,IAAI,CAC3C,SAAS,CAAC,iBAAiB,CAAC,EAC5B,UAAU,CACX;IACC,0CAA0C;IAC1C,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,iBAAiB,CAAC,CAAC;IACnC;;;;OAIG;IACH,KAAK,EAAE,MAAM,CAAC;IACd;;;;;;;OAOG;IACH,YAAY,EAAE,SAAS,CAAC,qBAAqB,EAAE,GAAG,qBAAqB,EAAE,CAAC,CAAC;IAC3E;;;;OAIG;IACH,IAAI,CAAC,EAAE,cAAc,CAAC;IACtB;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;;OAMG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,oEAAoE;IACpE,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;OAGG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;;OAIG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,yCAAyC;IACzC,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AA8ND;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,UAAU,CAAC,EACzB,KAAK,EACL,YAAY,EACZ,IAAW,EACX,WAAe,EACf,WAAe,EACf,UAAkB,EAClB,QAAgB,EAChB,UAAkB,EAClB,UAAkB,EAClB,GAAG,EACH,MAAM,EACN,SAAS,EACT,KAAK,EACL,GAAG,IAAI,EACR,EAAE,eAAe,GAAG,KAAK,CAAC,SAAS,CA4JnC;yBA3Ke,UAAU"}
+{"version":3,"file":"CommentPin.d.ts","sourceRoot":"","sources":["../../src/CommentPin/CommentPin.tsx"],"names":[],"mappings":"AAyBA,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,oBAAoB,CAAC;AA4BlD,qEAAqE;AACrE,MAAM,MAAM,cAAc,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;AAEhD,sEAAsE;AACtE,MAAM,WAAW,qBAAqB;IACpC,gEAAgE;IAChE,EAAE,EAAE,MAAM,CAAC;IACX,+DAA+D;IAC/D,IAAI,EAAE,MAAM,CAAC;IACb,8CAA8C;IAC9C,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,eAAgB,SAAQ,IAAI,CAC3C,SAAS,CAAC,iBAAiB,CAAC,EAC5B,UAAU,CACX;IACC,0CAA0C;IAC1C,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,iBAAiB,CAAC,CAAC;IACnC;;;;OAIG;IACH,KAAK,EAAE,MAAM,CAAC;IACd;;;;;;;OAOG;IACH,YAAY,EAAE,SAAS,CAAC,qBAAqB,EAAE,GAAG,qBAAqB,EAAE,CAAC,CAAC;IAC3E;;;;OAIG;IACH,IAAI,CAAC,EAAE,cAAc,CAAC;IACtB;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;;OAMG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,oEAAoE;IACpE,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;OAGG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;;OAIG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,yCAAyC;IACzC,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AA6OD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,UAAU,CAAC,EACzB,KAAK,EACL,YAAY,EACZ,IAAW,EACX,WAAe,EACf,WAAe,EACf,UAAkB,EAClB,QAAgB,EAChB,UAAkB,EAClB,UAAkB,EAClB,GAAG,EACH,MAAM,EACN,SAAS,EACT,KAAK,EACL,GAAG,IAAI,EACR,EAAE,eAAe,GAAG,KAAK,CAAC,SAAS,CAwLnC;yBAvMe,UAAU"}

package/dist/CommentPin/CommentPin.js

@@ -88,6 +88,11 @@ const styles = {
     kSiTet: "xyd83as x1tbh5bv",
     $$css: true
   },
+  disabledUnselected: {
+    kVAM5u: "x9r1u3d xmnqt3w",
+    kMwMTN: "xv1l7n4 x1bhcspo",
+    $$css: true
+  },
   overflowCircle: {
     kg3NbH: "xnjsko4",
     $$css: true
@@ -269,8 +274,37 @@ export function CommentPin({
     ref: mergedRef,
     type: "button",
     "aria-label": label,
-    "aria-pressed": isSelected,
-    disabled: isDisabled,
+    "aria-pressed": isSelected
+    // 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,
       grouped: isGrouped ? 'grouped' : null,
@@ -279,7 +313,7 @@ export function CommentPin({
       dimmed: isDimmed ? 'dimmed' : null,
       resolved: isResolved ? 'resolved' : null,
       disabled: isDisabled ? 'disabled' : null
-    }), focusOutlineProps.focusVisible(styles.root, sizeStyles[resolvedSize], interactionOverlayStyles.backgroundImage, (isGrouped || hasUnread) && styles.withCount, isDimmed && !isSelected && styles.dimmed, isSelected && styles.selected, isDisabled && styles.disabled, xstyle), className, style),
+    }), focusOutlineProps.focusVisible(styles.root, sizeStyles[resolvedSize], interactionOverlayStyles.backgroundImage, (isGrouped || hasUnread) && styles.withCount, isDimmed && !isSelected && styles.dimmed, isSelected && styles.selected, isDisabled && styles.disabled, isDisabled && !isSelected && styles.disabledUnselected, xstyle), className, style),
     children: [/*#__PURE__*/_jsx("span", {
       "aria-hidden": "true",
       ...{

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astryxdesign/lab",
-  "version": "0.7.6-canary.df8928a",
+  "version": "0.7.6-canary.eaae8e3",
   "description": "Experimental Astryx components — published to npm only under the @canary dist-tag for early testing; never released as a stable (latest) version.",
   "author": "Meta Open Source",
   "license": "MIT",
@@ -49,7 +49,7 @@
   },
   "peerDependencies": {
     "@stylexjs/stylex": ">=0.10.0",
-    "@astryxdesign/core": "0.7.6-canary.df8928a",
+    "@astryxdesign/core": "0.7.6-canary.eaae8e3",
     "react": ">=19.0.0",
     "react-dom": ">=19.0.0"
   },
@@ -59,8 +59,8 @@
     "d3-shape": "^3.2.0"
   },
   "devDependencies": {
-    "@astryxdesign/a11y-spec": "0.7.6-canary.df8928a",
-    "@astryxdesign/cli": "0.7.6-canary.df8928a",
+    "@astryxdesign/a11y-spec": "0.7.6-canary.eaae8e3",
+    "@astryxdesign/cli": "0.7.6-canary.eaae8e3",
     "@babel/cli": "^7.29.7",
     "@babel/core": "^7.29.7",
     "@babel/preset-react": "^7.29.7",

package/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',
   },

package/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

package/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(

package/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,