@astryxdesign/core 0.2.0 → 0.3.0-canary.1b8b3f2

package/src/Chat/ChatComposerTokenElement.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
   name: 'ChatComposerTokenElement',

package/src/Chat/ChatDictationButton.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
   name: 'ChatDictationButton',
@@ -65,7 +65,7 @@ export const docs = {
 
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsZh = {
   usage: {
     description:
@@ -87,7 +87,7 @@ export const docsZh = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   description: 'mic toggle btn for voice input in chat composer; idle=mic icon, listening=freq bars; pairs w/ useChatDictation',
   usage: {

package/src/Chat/ChatDictationButton.tsx

@@ -15,7 +15,7 @@
  *
  * SYNC: When modified, update:
  * - /packages/core/src/Chat/index.ts (exports)
- * - /packages/cli/templates/blocks/components/ChatDictationButton/ (block examples)
+ * - /packages/cli/assets/templates/blocks/components/ChatDictationButton/ (block examples)
  */
 
 import React from 'react';

package/src/Chat/ChatLayout.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
   name: 'ChatLayout',

package/src/Chat/ChatLayout.test.tsx

@@ -103,6 +103,63 @@ describe('ChatLayout', () => {
   });
 });
 
+// ---------------------------------------------------------------------------
+// Self-scroll layout contract (#2573)
+//
+// jsdom has no layout, so these assert the class-level CSS intent: the root
+// must be a flex column whose message area flexes (grow, no shrink) instead
+// of forcing minHeight: 100%. With minHeight: 100% the in-flow sticky dock
+// added its full height on top of the message area, so the root always
+// overflowed by exactly the dock height (phantom scrollbar). Real-layout
+// geometry was verified in a browser; see the PR for measurements.
+// ---------------------------------------------------------------------------
+
+describe('ChatLayout — self-scroll layout contract (#2573)', () => {
+  it('root is a flex column so the dock height is part of the 100%', () => {
+    render(
+      <ChatLayout composer={<div>composer</div>} data-testid="layout">
+        <div>msg</div>
+      </ChatLayout>,
+    );
+    const root = screen.getByTestId('layout');
+    expect(root).toHaveStyle({display: 'flex', flexDirection: 'column'});
+  });
+
+  it('message area flexes to fill leftover space instead of minHeight: 100%', () => {
+    render(
+      <ChatLayout composer={<div>composer</div>} data-testid="layout">
+        <div>msg</div>
+      </ChatLayout>,
+    );
+    const messageArea = screen.getByTestId('layout')
+      .firstElementChild as HTMLElement;
+    expect(messageArea).toHaveStyle({flexGrow: '1', flexShrink: '0'});
+    // minHeight: 100% is the phantom-scrollbar bug — it must not come back.
+    expect(getComputedStyle(messageArea).minHeight).not.toBe('100%');
+  });
+
+  it('dock is sticky in self-scroll mode and fixed with an external scrollRef', () => {
+    const {rerender} = render(
+      <ChatLayout composer={<div>composer</div>} data-testid="layout">
+        <div>msg</div>
+      </ChatLayout>,
+    );
+    const dock = screen.getByTestId('layout').lastElementChild as HTMLElement;
+    expect(dock).toHaveStyle({position: 'sticky'});
+
+    const scrollRef = {current: document.documentElement};
+    rerender(
+      <ChatLayout
+        composer={<div>composer</div>}
+        data-testid="layout"
+        scrollRef={scrollRef}>
+        <div>msg</div>
+      </ChatLayout>,
+    );
+    expect(dock).toHaveStyle({position: 'fixed'});
+  });
+});
+
 // ---------------------------------------------------------------------------
 // First-fill scroll positioning
 //

package/src/Chat/ChatLayout.tsx

@@ -12,6 +12,13 @@
  * Provides the scroll container ref and content ref, renders the
  * scroll-to-bottom button, frosted glass dock, and message area.
  *
+ * Layout contract: the root is a flex column. The message area flexes
+ * (grow 1, shrink 0) to fill the space the dock doesn't need; the sticky
+ * dock keeps its natural height in flow. Short content therefore fills
+ * exactly 100% with no overflow, and long content grows past the root so
+ * self-scroll mode scrolls (#2573). In external-scrollRef mode the dock
+ * is position: fixed (out of flow) and the message area fills the root.
+ *
  * Density (compact/balanced/spacious) is controlled via a prop with
  * 'balanced' as the default. No JS measurement or ResizeObserver needed.
  * The container-type on root enables container queries in child components.
@@ -19,7 +26,7 @@
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/core/src/Chat/index.ts (exports)
  * - /apps/storybook/stories/ChatLayout.stories.tsx
- * - /packages/cli/templates/blocks/components/ChatLayout/ (block examples)
+ * - /packages/cli/assets/templates/blocks/components/ChatLayout/ (block examples)
  */
 
 import {type ReactNode, useMemo, useRef} from 'react';
@@ -100,6 +107,13 @@ const styles = stylex.create({
     containerType: 'inline-size',
     minHeight: 0,
     flex: 1,
+    // Flex column so the sticky dock's natural height is part of the 100%:
+    // messageArea flexes to fill the leftover space instead of forcing
+    // minHeight: 100% on its own. Without this, the in-flow sticky dock
+    // adds its full height on top of the 100% message area and the root
+    // always overflows by exactly the dock height (#2573).
+    display: 'flex',
+    flexDirection: 'column',
   },
   rootScrollable: {
     overflowY: 'auto',
@@ -116,7 +130,11 @@ const styles = stylex.create({
     display: 'flex',
     flexDirection: 'column',
     marginInline: 'auto',
-    minHeight: '100%',
+    // Fill the space the dock doesn't need (grow), but never shrink below
+    // content height — long content must overflow the root so it scrolls.
+    flexGrow: 1,
+    flexShrink: 0,
+    flexBasis: 'auto',
     paddingBlockEnd: spacingVars['--spacing-6'],
     width: '100%',
     maxWidth: '100%',
@@ -139,6 +157,9 @@ const styles = stylex.create({
     zIndex: 0,
     isolation: 'isolate',
     pointerEvents: 'none',
+    // Keep the sticky dock at its natural height as a flex item.
+    // (Inert in fixed mode — position: fixed takes it out of flex layout.)
+    flexShrink: 0,
   },
   dockContainerFixed: {
     position: 'fixed',

package/src/Chat/ChatLayoutScrollButton.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
   name: 'ChatLayoutScrollButton',

package/src/Chat/ChatLayoutScrollButton.tsx

@@ -13,7 +13,7 @@
  *
  * SYNC: When modified, update:
  * - /packages/core/src/Chat/index.ts (exports)
- * - /packages/cli/templates/blocks/components/ChatLayoutScrollButton/ (block examples)
+ * - /packages/cli/assets/templates/blocks/components/ChatLayoutScrollButton/ (block examples)
  */
 
 import React from 'react';

package/src/Chat/ChatMessage.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
   name: 'ChatMessage',

package/src/Chat/ChatMessage.tsx

@@ -16,7 +16,7 @@
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/core/src/Chat/index.ts (exports)
  * - /apps/storybook/stories/Chat.stories.tsx
- * - /packages/cli/templates/blocks/components/ChatMessage/ (block examples)
+ * - /packages/cli/assets/templates/blocks/components/ChatMessage/ (block examples)
  */
 
 import {type ReactNode, useMemo, useId} from 'react';

package/src/Chat/ChatMessageBubble.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
   name: 'ChatMessageBubble',

package/src/Chat/ChatMessageBubble.tsx

@@ -22,7 +22,7 @@
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/core/src/Chat/index.ts (exports)
  * - /apps/storybook/stories/Chat.stories.tsx
- * - /packages/cli/templates/blocks/components/ChatMessageBubble/ (block examples)
+ * - /packages/cli/assets/templates/blocks/components/ChatMessageBubble/ (block examples)
  */
 
 import type {ReactNode} from 'react';

package/src/Chat/ChatMessageList.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
   name: 'ChatMessageList',

package/src/Chat/ChatMessageList.tsx

@@ -19,7 +19,7 @@
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/core/src/Chat/index.ts (exports)
  * - /apps/storybook/stories/Chat.stories.tsx
- * - /packages/cli/templates/blocks/components/ChatMessageList/ (block examples)
+ * - /packages/cli/assets/templates/blocks/components/ChatMessageList/ (block examples)
  */
 
 import {type ReactNode, useEffect, useMemo, useRef, useTransition} from 'react';

package/src/Chat/ChatMessageMetadata.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
   name: 'ChatMessageMetadata',

package/src/Chat/ChatSendButton.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
   name: 'ChatSendButton',

package/src/Chat/ChatSendButton.tsx

@@ -20,7 +20,7 @@
 import React, {type ReactNode} from 'react';
 import * as stylex from '@stylexjs/stylex';
 import {Button} from '../Button';
-import {getIcon} from '../Icon/globalIconRegistry';
+import {useIcon} from '../Icon';
 import {useChatComposerContext} from './ChatContext';
 
 import type {BaseProps} from '../BaseProps';
@@ -95,6 +95,8 @@ export function ChatSendButton(props: ChatSendButtonProps): ReactNode {
   } = props;
 
   const handleSend = onSend ?? (() => context?.onSubmit(''));
+  const defaultStopIcon = useIcon('stop');
+  const defaultSendIcon = useIcon('arrowUp');
 
   return (
     <Button
@@ -108,8 +110,8 @@ export function ChatSendButton(props: ChatSendButtonProps): ReactNode {
       size={size}
       icon={
         isStopShown
-          ? (stopIcon ?? getIcon('stop'))
-          : (sendIcon ?? getIcon('arrowUp'))
+          ? (stopIcon ?? defaultStopIcon)
+          : (sendIcon ?? defaultSendIcon)
       }
       isIconOnly
       isDisabled={!isStopShown && isDisabled}

package/src/Chat/ChatSystemMessage.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
   name: 'ChatSystemMessage',

package/src/Chat/ChatSystemMessage.tsx

@@ -16,7 +16,7 @@
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/core/src/Chat/index.ts (exports)
  * - /apps/storybook/stories/Chat.stories.tsx
- * - /packages/cli/templates/blocks/components/ChatSystemMessage/ (block examples)
+ * - /packages/cli/assets/templates/blocks/components/ChatSystemMessage/ (block examples)
  */
 
 import type {ReactNode} from 'react';

package/src/Chat/ChatTokenizedText.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
   name: 'ChatTokenizedText',

package/src/Chat/ChatTokenizedText.tsx

@@ -14,7 +14,7 @@
  *
  * SYNC: When modified, update:
  * - /packages/core/src/Chat/index.ts
- * - /packages/cli/templates/blocks/components/ChatTokenizedText/ (block examples)
+ * - /packages/cli/assets/templates/blocks/components/ChatTokenizedText/ (block examples)
  */
 
 import React, {type ReactNode} from 'react';

package/src/Chat/ChatToolCalls.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
   name: 'ChatToolCalls',
@@ -73,7 +73,7 @@ export const docs = {
   ],
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsZh = {
   usage: {
     description:
@@ -97,7 +97,7 @@ export const docsZh = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   description: 'tool/function call display from LLM response; single=inline, multiple=collapsible summary w/ latest at surface',
   usage: {

package/src/CheckboxInput/CheckboxInput.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
   name: 'CheckboxInput',
@@ -153,7 +153,7 @@ export const docs = {
   },
 };
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 export const docsZh = {
   name: 'CheckboxInput',
   displayName: 'Checkbox Input',
@@ -211,7 +211,7 @@ export const docsZh = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   description: 'single on/off toggle for settings, terms, and opt-in choices',
   usage: {

package/src/CheckboxInput/CheckboxInput.test.tsx

@@ -13,6 +13,7 @@ import {describe, it, expect, vi, beforeEach, afterEach} from 'vitest';
 import {render, screen, fireEvent, waitFor} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import {CheckboxInput} from './CheckboxInput';
+import {getForcedColorsRules} from '../__tests__/forcedColors';
 import {__resetLiveRegionsForTest} from '../hooks/useAnnounce';
 
 afterEach(() => {
@@ -143,6 +144,39 @@ describe('CheckboxInput', () => {
     expect(checkbox).toHaveAttribute('aria-describedby', description.id);
   });
 
+  it('toggles when clicking on the description', async () => {
+    const user = userEvent.setup();
+    const handleChange = vi.fn();
+    render(
+      <CheckboxInput
+        label="Subscribe"
+        description="Receive weekly updates"
+        value={false}
+        onChange={handleChange}
+      />,
+    );
+    await user.click(screen.getByText('Receive weekly updates'));
+    expect(handleChange).toHaveBeenCalledWith(true, expect.any(Object));
+  });
+
+  it('does not fold the description into the checkbox accessible name', () => {
+    // The description stays a sibling of the <label>, so it must NOT become
+    // part of the checkbox's accessible name (which is computed from the
+    // associated label). It belongs in the accessible DESCRIPTION only
+    // (via aria-describedby) — otherwise screen readers announce it twice.
+    render(
+      <CheckboxInput
+        label="Email notifications"
+        description="We'll send weekly digests"
+        value={false}
+        onChange={() => {}}
+      />,
+    );
+    const checkbox = screen.getByRole('checkbox');
+    expect(checkbox).toHaveAccessibleName('Email notifications');
+    expect(checkbox).toHaveAccessibleDescription("We'll send weekly digests");
+  });
+
   it('is disabled when isDisabled prop is true', () => {
     render(
       <CheckboxInput
@@ -543,3 +577,25 @@ describe('CheckboxInput', () => {
     });
   });
 });
+
+// jsdom cannot emulate forced-colors rendering, so this asserts that the
+// compiled output includes the forced-colors rule; visual behavior needs
+// manual verification under Windows High Contrast.
+describe('forced colors (WCAG 1.4.11)', () => {
+  it('compiles a forced-colors fill so the indeterminate mark survives Windows High Contrast', () => {
+    render(
+      <CheckboxInput label="All" value="indeterminate" onChange={() => {}} />,
+    );
+    // The painted indeterminate bar would be stripped to Canvas (invisible);
+    // CanvasText keeps it perceivable.
+    expect(getForcedColorsRules()).toContain('background-color: canvastext;');
+  });
+
+  it('compiles a forced-colors color so the checkmark survives Windows High Contrast', () => {
+    render(<CheckboxInput label="Accept" value={true} onChange={() => {}} />);
+    // The check strokes with currentColor; forced colors leaves it the same
+    // white as the flattened box, so it needs its own CanvasText color to stay
+    // perceivable on the Canvas box.
+    expect(getForcedColorsRules()).toContain('color: canvastext;');
+  });
+});

package/src/CheckboxInput/CheckboxInput.tsx

@@ -13,7 +13,7 @@
  * - /packages/core/src/CheckboxInput/CheckboxInput.test.tsx (tests for new/changed behavior)
  * - /packages/core/src/CheckboxInput/index.ts (exports if types change)
  * - /apps/storybook/stories/CheckboxInput.stories.tsx (storybook stories)
- * - /packages/cli/templates/blocks/components/CheckboxInput/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/CheckboxInput/ (showcase blocks)
  */
 
 import {
@@ -158,14 +158,29 @@ const styles = stylex.create({
   },
   checkmark: {
     display: 'none',
-    color: colorVars['--color-on-accent'],
+    color: {
+      default: colorVars['--color-on-accent'],
+      // Forced colors (Windows High Contrast) does not reliably force an SVG
+      // stroke painted with currentColor, so the check stays the same white as
+      // the flattened (Canvas) box fill — a white check on a white box.
+      // CanvasText keeps it perceivable on the Canvas box, matching the
+      // indeterminate mark (WCAG 1.4.11).
+      '@media (forced-colors: active)': 'CanvasText',
+    },
   },
   checkmarkVisible: {
     display: 'block',
   },
   indeterminateMark: {
     display: 'none',
-    backgroundColor: colorVars['--color-on-accent'],
+    backgroundColor: {
+      default: colorVars['--color-on-accent'],
+      // Forced colors (Windows High Contrast) strips painted backgrounds,
+      // which would make the indeterminate bar invisible; CanvasText keeps it
+      // perceivable on the Canvas box fill (WCAG 1.4.11). The checkmark carries
+      // the matching CanvasText treatment on its own style.
+      '@media (forced-colors: active)': 'CanvasText',
+    },
     borderRadius: radiusVars['--radius-full'],
   },
   indeterminateMarkVisible: {

package/src/CheckboxList/CheckboxList.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
   name: 'CheckboxList',
@@ -121,7 +121,7 @@ export const docs = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsZh = {
   usage: {
     description: 'CheckboxList shows a small group of checkboxes so users can turn several options on or off at once. Place it in settings pages, filter panels, or forms where every choice should be visible without scrolling. For a single standalone checkbox (like "I agree to the terms"), use CheckboxInput instead. If only one option can be picked, use RadioList. If the list is long enough to need searching or scrolling, use MultiSelector instead.',
@@ -136,7 +136,7 @@ export const docsZh = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   description:
     'Checkbox group component for multi-value selection. Collection mode (parent state) + standalone mode (per-item state).',

package/src/CheckboxList/CheckboxList.test.tsx

@@ -154,14 +154,105 @@ describe('CheckboxList', () => {
       </CheckboxList>,
     );
 
-    // Click the interactive row (invisible-button pattern), which is where the
-    // composed onClick lives — not the inner checkbox.
-    await user.click(screen.getByRole('button', {name: 'Option B'}));
+    // The row is a pointer-only click surface (no invisible row button — the
+    // checkbox is the option's only tab stop). Click the row's label area,
+    // where the composed onClick fires — not the inner checkbox.
+    expect(
+      screen.queryByRole('button', {name: 'Option B'}),
+    ).not.toBeInTheDocument();
+    // The text also exists in the checkbox's visually hidden <label>; target
+    // the row's label <span> to click the row surface.
+    await user.click(screen.getByText('Option B', {selector: 'span'}));
 
     expect(handleClick).toHaveBeenCalledTimes(1);
     expect(handleChange).toHaveBeenCalledWith(['a', 'b']);
   });
 
+  describe('single tab stop per option (WCAG 4.1.2 / APG checkbox pattern)', () => {
+    it('renders exactly one focusable control per option — the checkbox, no row button', () => {
+      render(
+        <CheckboxList label="Preferences" value={['a']} onChange={() => {}}>
+          <CheckboxListItem label="Option A" value="a" />
+          <CheckboxListItem label="Option B" value="b" />
+        </CheckboxList>,
+      );
+      // No invisible whole-row button duplicating the checkbox's action.
+      expect(screen.queryByRole('button')).not.toBeInTheDocument();
+      for (const item of screen.getAllByRole('listitem')) {
+        const focusables = item.querySelectorAll(
+          'button, a[href], input, select, textarea, [tabindex]:not([tabindex="-1"])',
+        );
+        expect(focusables).toHaveLength(1);
+        expect(focusables[0]).toBe(within(item).getByRole('checkbox'));
+      }
+    });
+
+    it('Tab moves directly from one option checkbox to the next', async () => {
+      const user = userEvent.setup();
+      render(
+        <CheckboxList label="Preferences" value={[]} onChange={() => {}}>
+          <CheckboxListItem label="Option A" value="a" />
+          <CheckboxListItem label="Option B" value="b" />
+        </CheckboxList>,
+      );
+      await user.tab();
+      expect(screen.getByRole('checkbox', {name: 'Option A'})).toHaveFocus();
+      await user.tab();
+      expect(screen.getByRole('checkbox', {name: 'Option B'})).toHaveFocus();
+      // No further tab stop inside the list (the row itself is not focusable).
+      await user.tab();
+      expect(document.body).toHaveFocus();
+    });
+
+    it('clicking the row surface (outside the checkbox) still toggles', async () => {
+      const user = userEvent.setup();
+      const handleChange = vi.fn();
+      render(
+        <CheckboxList label="Preferences" value={['a']} onChange={handleChange}>
+          <CheckboxListItem label="Option A" value="a" />
+          <CheckboxListItem label="Option B" value="b" />
+        </CheckboxList>,
+      );
+      // The text also exists in the checkbox's visually hidden <label>;
+      // target the row's label <span> to click the row surface.
+      await user.click(screen.getByText('Option B', {selector: 'span'}));
+      expect(handleChange).toHaveBeenCalledTimes(1);
+      expect(handleChange).toHaveBeenCalledWith(['a', 'b']);
+    });
+
+    it('toggles with Space on the focused checkbox, which reports checked state', async () => {
+      const user = userEvent.setup();
+      const handleChange = vi.fn();
+      render(
+        <CheckboxList label="Preferences" value={['a']} onChange={handleChange}>
+          <CheckboxListItem label="Option A" value="a" />
+          <CheckboxListItem label="Option B" value="b" />
+        </CheckboxList>,
+      );
+      await user.tab();
+      // The focused control is the checkbox itself, so its accessible name
+      // and checked state are what assistive tech announces on focus.
+      const checkboxA = screen.getByRole('checkbox', {name: 'Option A'});
+      expect(checkboxA).toHaveFocus();
+      expect(checkboxA).toBeChecked();
+      await user.keyboard(' ');
+      expect(handleChange).toHaveBeenCalledTimes(1);
+      expect(handleChange).toHaveBeenCalledWith([]);
+    });
+
+    it('the row itself is not focusable', () => {
+      render(
+        <CheckboxList label="Preferences" value={[]} onChange={() => {}}>
+          <CheckboxListItem label="Option A" value="a" />
+        </CheckboxList>,
+      );
+      const item = screen.getByRole('listitem');
+      expect(item).not.toHaveAttribute('tabindex');
+      item.focus();
+      expect(item).not.toHaveFocus();
+    });
+  });
+
   it('disables all checkboxes when group isDisabled is true', () => {
     render(
       <CheckboxList