@astryxdesign/core 0.1.2 → 0.1.3-canary.1e94ba0

package/src/Chat/ChatMessageList.doc.mjs

@@ -45,6 +45,12 @@ export const docs = {
       type: 'SpacingStep',
       description: 'Gap between top-level message rows. Defaults to the selected density; override for LLM event streams or independent rows that need different spacing from density.',
     },
+    {
+      name: 'isStreaming',
+      type: 'boolean',
+      description: 'Whether an assistant message is actively streaming. Marks the log aria-busy so screen readers wait and announce the completed message once instead of re-announcing partial text on every token.',
+      default: 'false',
+    },
   ],
 };
 
@@ -59,6 +65,7 @@ export const docsZh = {
     scrollToTopAction: '用户滚动到顶部时触发的异步操作。用于加载更早的消息。',
     density: '视觉密度，通过上下文传递给子消息。',
     gap: '顶层消息行之间的间距。默认跟随密度；当 LLM 事件流等独立行需要不同间距时可覆盖。',
+    isStreaming: '是否有助手消息正在流式输出。标记日志为 aria-busy，让屏幕阅读器等待并在完成后一次性播报，而不是每个 token 都重复播报。',
   },
 };
 
@@ -73,5 +80,6 @@ export const docsDense = {
     scrollToTopAction: 'async action at scroll top; load older msgs',
     density: 'visual density; flows to children via context',
     gap: 'top-level row gap; defaults to density spacing; override for independent LLM/tool rows',
+    isStreaming: 'assistant streaming? marks log aria-busy so SR announces the completed msg once',
   },
 };

package/src/Chat/ChatMessageList.test.tsx

@@ -28,6 +28,24 @@ describe('ChatMessageList', () => {
     expect(el.getAttribute('role')).toBe('log');
   });
 
+  it('is not aria-busy by default', () => {
+    render(
+      <ChatMessageList data-testid="list">
+        <div>msg</div>
+      </ChatMessageList>,
+    );
+    expect(screen.getByTestId('list')).not.toHaveAttribute('aria-busy');
+  });
+
+  it('marks the log aria-busy while streaming', () => {
+    render(
+      <ChatMessageList data-testid="list" isStreaming>
+        <div>msg</div>
+      </ChatMessageList>,
+    );
+    expect(screen.getByTestId('list')).toHaveAttribute('aria-busy', 'true');
+  });
+
   it('renders empty state when no children', () => {
     render(
       <ChatMessageList emptyState={<div>No messages yet</div>}>

package/src/Chat/ChatMessageList.tsx

@@ -72,6 +72,20 @@ export interface ChatMessageListProps extends BaseProps<HTMLDivElement> {
    * be grouped) and row spacing should be tuned separately from density.
    */
   gap?: SpacingStep;
+
+  /**
+   * Whether an assistant message is actively streaming into the list.
+   *
+   * The list is a `role="log"` / `aria-live="polite"` region, so while a
+   * message streams in token-by-token, screen readers would otherwise
+   * re-announce the accumulating partial text on every mutation. Set
+   * `isStreaming` to `true` for the duration of a stream: it marks the log
+   * `aria-busy="true"` so assistive tech waits and announces the completed
+   * message once, when `isStreaming` returns to `false`.
+   *
+   * @default false
+   */
+  isStreaming?: boolean;
 }
 
 // =============================================================================
@@ -190,6 +204,7 @@ export function ChatMessageList({
   scrollToTopAction,
   density = 'balanced',
   gap,
+  isStreaming = false,
   xstyle,
   className,
   style,
@@ -252,6 +267,7 @@ export function ChatMessageList({
         ref={ref}
         role="log"
         aria-live="polite"
+        aria-busy={isStreaming || undefined}
         tabIndex={0}
         data-testid={testId}
         {...mergeProps(

package/src/Chat/useTriggerMenu.tsx

@@ -81,8 +81,15 @@ export interface UseTriggerMenuReturn {
   renderMenu: () => ReactNode;
   /** Reset/close the trigger menu */
   reset: () => void;
-  /** ARIA props to spread onto the textbox element */
+  /**
+   * ARIA props to spread onto the editable element. When triggers are
+   * configured the element becomes a `combobox` (which is the only role that
+   * permits `aria-expanded`/`aria-haspopup`/`aria-controls`/
+   * `aria-activedescendant`); otherwise it stays a plain `textbox` and no
+   * combobox attributes are emitted.
+   */
   ariaProps: {
+    role: 'combobox' | 'textbox';
     'aria-expanded'?: boolean;
     'aria-controls'?: string;
     'aria-activedescendant'?: string;
@@ -296,6 +303,9 @@ export function useTriggerMenu(
     hasLightDismiss: true,
     hasCloseButton: false,
     hasAutoFocus: false,
+    // The popup's own role="listbox" is the exposed semantics; focus stays in
+    // the contenteditable composer, so a modal dialog wrapper is incorrect.
+    role: 'none',
   });
 
   // Cleanup on unmount
@@ -598,10 +608,17 @@ export function useTriggerMenu(
     el?.scrollIntoView({block: 'nearest'});
   }, [state.highlightedIndex, popover.isOpen, getItemId]);
 
-  // ARIA props for the textbox element
-  const ariaProps =
-    state.isActive && popover.isOpen
+  // ARIA props for the editable element. Combobox attributes
+  // (aria-expanded/haspopup/controls/activedescendant) are only valid on
+  // role="combobox", so we only switch to that role — and only emit those
+  // attributes — when triggers are actually configured. With no triggers the
+  // element stays a plain role="textbox".
+  const hasTriggers = (triggers?.length ?? 0) > 0;
+  const ariaProps: UseTriggerMenuReturn['ariaProps'] = !hasTriggers
+    ? {role: 'textbox'}
+    : state.isActive && popover.isOpen
       ? {
+          role: 'combobox',
           'aria-expanded': true as const,
           'aria-controls': listboxId,
           'aria-activedescendant':
@@ -611,6 +628,7 @@ export function useTriggerMenu(
           'aria-haspopup': 'listbox' as const,
         }
       : {
+          role: 'combobox',
           'aria-expanded': false as const,
           'aria-haspopup': 'listbox' as const,
         };

package/src/CheckboxInput/CheckboxInput.doc.mjs

@@ -63,6 +63,12 @@ export const docs = {
       description: 'Whether the checkbox is disabled.',
       default: 'false',
     },
+    {
+      name: 'disabledMessage',
+      type: 'string',
+      description:
+        'Explains why the checkbox is disabled. With isDisabled, shows a tooltip on hover/keyboard focus and keeps the checkbox focusable via aria-disabled (toggling stays blocked). Use this instead of wrapping a disabled CheckboxInput in Tooltip. Disabled controls swallow the hover events an external Tooltip needs.',
+    },
     {
       name: 'isReadOnly',
       type: 'boolean',
@@ -124,6 +130,7 @@ export const docs = {
       { guidance: true, description: 'Use the indeterminate state for "select all" checkboxes when only some items in a group are selected.' },
       { guidance: false, description: 'Use a checkbox for mutually exclusive choices; use RadioList when only one option can be selected.' },
       { guidance: false, description: 'Use a checkbox for actions that take effect immediately; use a toggle switch or button instead.' },
+      { guidance: false, description: 'Wrap a disabled checkbox in Tooltip to explain why it is disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.' },
     ],
     anatomy: [
       { name: 'Checkbox', required: true, description: 'The check box itself: unchecked, checked, or indeterminate.' },
@@ -146,6 +153,7 @@ export const docsZh = {
       { guidance: true, description: 'Use the indeterminate state for "select all" checkboxes when only some items in a group are selected.' },
       { guidance: false, description: 'Use a checkbox for mutually exclusive choices; use RadioList when only one option can be selected.' },
       { guidance: false, description: 'Use a checkbox for actions that take effect immediately; use a toggle switch or button instead.' },
+      { guidance: false, description: 'Wrap a disabled checkbox in Tooltip to explain why it is disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.' },
     ],
   },
   props: [
@@ -163,6 +171,7 @@ export const docsZh = {
     },
     {name: 'isLoading', type: 'boolean', description: '复选框是否处于加载状态。显示旋转器并阻止交互。', default: 'false'},
     {name: 'isDisabled', type: 'boolean', description: '复选框是否禁用。', default: 'false'},
+    {name: 'disabledMessage', type: 'string', description: 'Explains why the checkbox is disabled. With isDisabled, shows a tooltip on hover/keyboard focus and keeps the checkbox focusable via aria-disabled (toggling stays blocked). Use this instead of wrapping a disabled CheckboxInput in Tooltip. Disabled controls swallow the hover events an external Tooltip needs.'},
     {name: 'isReadOnly', type: 'boolean', description: '复选框是否为只读。以完整不透明度显示当前状态但阻止交互。与 isDisabled 不同，只读复选框不会变暗。', default: 'false'},
     {name: 'isOptional', type: 'boolean', description: '字段是否可选。与 isRequired 互斥。', default: 'false'},
     {name: 'isRequired', type: 'boolean', description: '复选框是否必填。与 isOptional 互斥。', default: 'false'},
@@ -200,6 +209,7 @@ export const docsDense = {
       { guidance: true, description: 'Use the indeterminate state for "select all" checkboxes when only some items in a group are selected.' },
       { guidance: false, description: 'Use a checkbox for mutually exclusive choices; use RadioList when only one option can be selected.' },
       { guidance: false, description: 'Use a checkbox for actions that take effect immediately; use a toggle switch or button instead.' },
+      { guidance: false, description: 'Wrap a disabled checkbox in Tooltip to explain why it is disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.' },
     ],
   },
   propDescriptions: {

package/src/CheckboxInput/CheckboxInput.test.tsx

@@ -9,41 +9,56 @@
  * SYNC: When CheckboxInput.tsx changes, update tests to match new behavior
  */
 
-import {describe, it, expect, vi} from 'vitest';
-import {render, screen} from '@testing-library/react';
+import {describe, it, expect, vi, beforeEach} from 'vitest';
+import {render, screen, fireEvent, waitFor} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import {CheckboxInput} from './CheckboxInput';
 
+// Mock showPopover/hidePopover (not implemented in jsdom) so the tooltip layer
+// reflects its open state via a `popover-open` attribute the tests can assert.
+beforeEach(() => {
+  HTMLElement.prototype.showPopover = vi.fn(function (this: HTMLElement) {
+    this.setAttribute('popover-open', '');
+    const event = new Event('toggle', {bubbles: false});
+    Object.defineProperty(event, 'newState', {value: 'open'});
+    this.dispatchEvent(event);
+  });
+  HTMLElement.prototype.hidePopover = vi.fn(function (this: HTMLElement) {
+    this.removeAttribute('popover-open');
+    const event = new Event('toggle', {bubbles: false});
+    Object.defineProperty(event, 'newState', {value: 'closed'});
+    this.dispatchEvent(event);
+  });
+  const originalMatches = HTMLElement.prototype.matches;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  (HTMLElement.prototype as any).matches = function (
+    selector: string,
+  ): boolean {
+    if (selector === ':popover-open') {
+      return this.hasAttribute('popover-open');
+    }
+    return originalMatches.call(this, selector);
+  };
+});
+
 describe('CheckboxInput', () => {
   it('renders with label', () => {
     render(
-      <CheckboxInput
-        label="Accept terms"
-        value={false}
-        onChange={() => {}}
-      />,
+      <CheckboxInput label="Accept terms" value={false} onChange={() => {}} />,
     );
     expect(screen.getByLabelText('Accept terms')).toBeInTheDocument();
   });
 
   it('renders as unchecked by default', () => {
     render(
-      <CheckboxInput
-        label="Accept terms"
-        value={false}
-        onChange={() => {}}
-      />,
+      <CheckboxInput label="Accept terms" value={false} onChange={() => {}} />,
     );
     expect(screen.getByRole('checkbox')).not.toBeChecked();
   });
 
   it('renders as checked when value prop is true', () => {
     render(
-      <CheckboxInput
-        label="Accept terms"
-        value={true}
-        onChange={() => {}}
-      />,
+      <CheckboxInput label="Accept terms" value={true} onChange={() => {}} />,
     );
     expect(screen.getByRole('checkbox')).toBeChecked();
   });
@@ -182,11 +197,7 @@ describe('CheckboxInput', () => {
 
   it('shows label visually by default', () => {
     render(
-      <CheckboxInput
-        label="Accept terms"
-        value={false}
-        onChange={() => {}}
-      />,
+      <CheckboxInput label="Accept terms" value={false} onChange={() => {}} />,
     );
     const label = screen.getByText('Accept terms');
     expect(label).toBeVisible();
@@ -204,7 +215,7 @@ describe('CheckboxInput', () => {
     expect(screen.getByRole('checkbox')).toHaveAttribute('aria-busy', 'true');
   });
 
-  it('sets aria-checked="mixed" for indeterminate state', () => {
+  it('exposes indeterminate state via the native indeterminate property', () => {
     render(
       <CheckboxInput
         label="Select all"
@@ -212,10 +223,15 @@ describe('CheckboxInput', () => {
         onChange={() => {}}
       />,
     );
-    expect(screen.getByRole('checkbox')).toHaveAttribute(
-      'aria-checked',
-      'mixed',
-    );
+    const checkbox = screen.getByRole('checkbox');
+    // Native checkboxes expose mixed state through the DOM indeterminate
+    // property, which browsers map to aria-checked="mixed". A redundant
+    // aria-checked attribute is intentionally NOT set (forms-16).
+    expect(checkbox).toBeInstanceOf(HTMLInputElement);
+    if (checkbox instanceof HTMLInputElement) {
+      expect(checkbox.indeterminate).toBe(true);
+    }
+    expect(checkbox).not.toHaveAttribute('aria-checked');
   });
 
   it('renders semantic labelIcon names as icons', () => {
@@ -247,4 +263,133 @@ describe('CheckboxInput', () => {
       'true',
     );
   });
+
+  describe('disabledMessage', () => {
+    const h = {hidden: true} as const;
+
+    function getRow(): HTMLElement {
+      return screen.getByRole('checkbox', h).closest('div')!.parentElement!;
+    }
+
+    it('shows the reason tooltip on hover when disabled with a reason', async () => {
+      render(
+        <CheckboxInput
+          label="Accept terms"
+          value={false}
+          onChange={() => {}}
+          isDisabled
+          disabledMessage="Terms are managed by your administrator"
+        />,
+      );
+      const tooltip = screen.getByRole('tooltip', h);
+      expect(tooltip).toHaveTextContent(
+        'Terms are managed by your administrator',
+      );
+      fireEvent.mouseEnter(getRow());
+      await waitFor(() => expect(tooltip).toHaveAttribute('popover-open'));
+      fireEvent.mouseLeave(getRow());
+      await waitFor(() => expect(tooltip).not.toHaveAttribute('popover-open'));
+    });
+
+    it('shows the reason tooltip on keyboard focus', async () => {
+      const user = userEvent.setup();
+      render(
+        <CheckboxInput
+          label="Accept terms"
+          value={false}
+          onChange={() => {}}
+          isDisabled
+          disabledMessage="Terms are managed by your administrator"
+        />,
+      );
+      const tooltip = screen.getByRole('tooltip', h);
+      await user.tab();
+      expect(screen.getByRole('checkbox', h)).toHaveFocus();
+      await waitFor(() => expect(tooltip).toHaveAttribute('popover-open'));
+    });
+
+    it('does not render a tooltip when not disabled', () => {
+      render(
+        <CheckboxInput
+          label="Accept terms"
+          value={false}
+          onChange={() => {}}
+          disabledMessage="Terms are managed by your administrator"
+        />,
+      );
+      expect(screen.queryByRole('tooltip', h)).not.toBeInTheDocument();
+    });
+
+    it('does not render a tooltip when disabled without a reason', () => {
+      render(
+        <CheckboxInput
+          label="Accept terms"
+          value={false}
+          onChange={() => {}}
+          isDisabled
+        />,
+      );
+      expect(screen.queryByRole('tooltip', h)).not.toBeInTheDocument();
+    });
+
+    it('keeps the checkbox focusable via aria-disabled when a reason is provided', () => {
+      render(
+        <CheckboxInput
+          label="Accept terms"
+          value={false}
+          onChange={() => {}}
+          isDisabled
+          disabledMessage="Terms are managed by your administrator"
+        />,
+      );
+      const checkbox = screen.getByRole('checkbox', h);
+      expect(checkbox).not.toBeDisabled();
+      expect(checkbox).toHaveAttribute('aria-disabled', 'true');
+    });
+
+    it('links the reason tooltip via aria-describedby', () => {
+      render(
+        <CheckboxInput
+          label="Accept terms"
+          value={false}
+          onChange={() => {}}
+          isDisabled
+          disabledMessage="Terms are managed by your administrator"
+        />,
+      );
+      const checkbox = screen.getByRole('checkbox', h);
+      const tooltip = screen.getByRole('tooltip', h);
+      expect(checkbox.getAttribute('aria-describedby')).toContain(tooltip.id);
+    });
+
+    it('blocks toggling while focusable-disabled', async () => {
+      const user = userEvent.setup();
+      const onChange = vi.fn();
+      render(
+        <CheckboxInput
+          label="Accept terms"
+          value={false}
+          onChange={onChange}
+          isDisabled
+          disabledMessage="Terms are managed by your administrator"
+        />,
+      );
+      const checkbox = screen.getByRole('checkbox', h);
+      await user.click(checkbox);
+      expect(onChange).not.toHaveBeenCalled();
+      expect(checkbox).not.toBeChecked();
+    });
+
+    it('remains natively disabled when disabled without a reason', () => {
+      render(
+        <CheckboxInput
+          label="Accept terms"
+          value={false}
+          onChange={() => {}}
+          isDisabled
+        />,
+      );
+      expect(screen.getByRole('checkbox')).toBeDisabled();
+    });
+  });
 });

package/src/CheckboxInput/CheckboxInput.tsx

@@ -4,7 +4,7 @@
 
 /**
  * @file CheckboxInput.tsx
- * @input Uses React, useId, ChangeEvent, FieldLabel, FieldStatus, IconType, InputStatus
+ * @input Uses React, useId, ChangeEvent, FieldLabel, FieldStatus, IconType, InputStatus, useTooltip
  * @output Exports CheckboxInput component, CheckboxInputProps
  * @position Core implementation; consumed by index.ts, tested by CheckboxInput.test.tsx
  *
@@ -19,6 +19,7 @@
 import {
   useId,
   useCallback,
+  use,
   useOptimistic,
   useTransition,
   type ChangeEvent,
@@ -44,9 +45,11 @@ import {FieldStatus} from '../FieldStatus/FieldStatus';
 import type {IconType} from '../Icon';
 import type {InputStatus} from '../Field/types';
 import {Spinner} from '../Spinner';
+import {useTooltip} from '../Tooltip';
 import {mergeProps, mergeRefs} from '../utils';
 import {checkboxScope} from './checkbox.markers.stylex';
 import {themeProps} from '../utils/themeProps';
+import {CheckboxListContext} from '../CheckboxList/CheckboxListContext';
 
 const styles = stylex.create({
   container: {
@@ -269,6 +272,27 @@ export interface CheckboxInputProps extends Omit<BaseProps, 'onChange'> {
    * @default false
    */
   isDisabled?: boolean;
+  /**
+   * Explains why the checkbox is disabled. When set together with
+   * `isDisabled`, the checkbox shows a tooltip with this text on hover and
+   * keyboard focus, and the control stays focusable (via `aria-disabled`) so
+   * the reason is discoverable by keyboard and assistive technology.
+   * Activation stays blocked.
+   *
+   * Use this instead of wrapping a disabled checkbox in `Tooltip` — disabled
+   * controls don't emit the pointer events an external tooltip needs.
+   *
+   * @example
+   * ```
+   * <CheckboxInput
+   *   label="Accept terms"
+   *   value={accepted}
+   *   isDisabled
+   *   disabledMessage="Terms are managed by your administrator"
+   * />
+   * ```
+   */
+  disabledMessage?: string;
   /**
    * Whether the checkbox is read-only.
    * Displays the current state at full opacity but prevents interaction.
@@ -350,6 +374,7 @@ export function CheckboxInput({
   isLoading = false,
   value,
   isDisabled = false,
+  disabledMessage,
   isReadOnly = false,
   isOptional = false,
   isRequired = false,
@@ -372,11 +397,37 @@ export function CheckboxInput({
   const [optimisticValue, setOptimisticValue] = useOptimistic(value);
   const isBusy = isLoading || optimisticValue !== value;
 
+  // Disabled-reason tooltip. Disabled controls swallow pointer events, so the
+  // tooltip listeners attach to the checkbox row (which already exists) and the
+  // native checkbox stays perceivable via aria-disabled instead of the disabled
+  // attribute. Value mutation is blocked by the isDisabled guard in onChange.
+  const showsDisabledMessage = isDisabled && !!disabledMessage;
+  // Keep the native checkbox focusable via aria-disabled either when it renders
+  // its own reason tooltip, or when it sits in a CheckboxList whose whole-group
+  // `disabledMessage` (shown on the group container) needs each checkbox to
+  // stay keyboard-perceivable. The group signals this through context rather
+  // than a public prop.
+  const checkboxListContext = use(CheckboxListContext);
+  const isFocusableDisabled =
+    isDisabled &&
+    (showsDisabledMessage ||
+      (checkboxListContext?.hasDisabledMessage ?? false));
+  const disabledMessageTooltip = useTooltip({
+    placement: 'above',
+    // The container row is not naturally focusable; focusin bubbles up from the
+    // native checkbox, so always attach focus listeners.
+    focusTrigger: 'always',
+    isEnabled: showsDisabledMessage,
+  });
+
   const isIndeterminate = optimisticValue === 'indeterminate';
   const isChecked = optimisticValue === true;
   const isCheckedOrIndeterminate = isChecked || isIndeterminate;
 
-  // Sync the native indeterminate DOM property (can't be set via JSX attribute)
+  // Sync the native indeterminate DOM property (can't be set via JSX
+  // attribute). On a native checkbox this is the authoritative way to expose
+  // the mixed state — a separate aria-checked="mixed" would be redundant and
+  // can desync from / override the native state (forms-16), so it is omitted.
   const indeterminateRef = useCallback(
     (el: HTMLInputElement | null) => {
       if (el) {
@@ -395,6 +446,9 @@ export function CheckboxInput({
   if (status?.message) {
     describedByParts.push(statusMessageID);
   }
+  if (showsDisabledMessage) {
+    describedByParts.push(disabledMessageTooltip.describedBy);
+  }
   const ariaDescribedBy =
     describedByParts.length > 0 ? describedByParts.join(' ') : undefined;
 
@@ -407,6 +461,15 @@ export function CheckboxInput({
         style,
       )}>
       <div
+        ref={el => {
+          // Interaction (hover/focus) listeners for the disabled-message
+          // tooltip attach to the whole row for a larger trigger target;
+          // positioning anchors on the checkbox itself (below) so the tooltip
+          // appears next to the control, not the far edge of the row.
+          // Handlers are gated internally by isEnabled, so attaching
+          // unconditionally is safe.
+          disabledMessageTooltip.interactionRef(el);
+        }}
         {...stylex.props(
           styles.container,
           isLabelHidden && styles.containerLabelHidden,
@@ -414,15 +477,23 @@ export function CheckboxInput({
         )}>
         <div {...stylex.props(styles.checkboxWrapper, wrapperSizeStyles[size])}>
           <input
-            ref={mergeRefs(ref, indeterminateRef)}
+            ref={mergeRefs(
+              ref,
+              indeterminateRef,
+              disabledMessageTooltip.positionRef,
+            )}
             id={id}
             type="checkbox"
             checked={isChecked}
-            disabled={isDisabled}
+            // With a disabledMessage the checkbox keeps focusability via
+            // aria-disabled so the reason is focus-discoverable; toggling is
+            // still blocked by the isDisabled guard in onChange below.
+            disabled={isDisabled && !isFocusableDisabled}
+            aria-disabled={isFocusableDisabled ? 'true' : undefined}
             readOnly={isReadOnly}
             required={isRequired}
             onChange={e => {
-              if (isBusy || isReadOnly) {
+              if (isDisabled || isBusy || isReadOnly) {
                 return;
               }
               const checked = e.target.checked;
@@ -436,7 +507,6 @@ export function CheckboxInput({
             }}
             onFocus={onFocus}
             onBlur={onBlur}
-            aria-checked={isIndeterminate ? 'mixed' : undefined}
             aria-readonly={isReadOnly || undefined}
             aria-describedby={ariaDescribedBy}
             aria-invalid={status?.type === 'error' ? true : undefined}
@@ -525,6 +595,8 @@ export function CheckboxInput({
           variant="detached"
         />
       )}
+      {showsDisabledMessage &&
+        disabledMessageTooltip.renderTooltip(disabledMessage)}
     </div>
   );
 }

package/src/CheckboxList/CheckboxList.doc.mjs

@@ -77,6 +77,12 @@ export const docs = {
       description: 'Whether all checkbox items are disabled.',
       default: 'false',
     },
+    {
+      name: 'disabledMessage',
+      type: 'string',
+      description:
+        'Explains why the group is disabled. Applies to the whole-group disabled state (isDisabled), not per item. With isDisabled, shows a tooltip on hover/keyboard focus and keeps the checkboxes focusable via aria-disabled (toggling stays blocked). Use this instead of wrapping a disabled CheckboxList in Tooltip. Disabled controls swallow the hover events an external Tooltip needs.',
+    },
     {
       name: 'status',
       type: 'InputStatus',
@@ -99,6 +105,7 @@ export const docs = {
       { guidance: true, description: 'Write a group label that says what the choices represent: "Export formats" tells users more than "Options".' },
       { guidance: false, description: 'Show a CheckboxList when the user can only pick one thing; that is what RadioList is for.' },
       { guidance: false, description: 'Put buttons or links inside the trailing slot (endContent); the whole row is already tappable, so a nested button creates two competing click targets.' },
+      { guidance: false, description: 'Wrap a disabled CheckboxList in Tooltip to explain why it is disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.' },
     ],
   },
 };
@@ -113,6 +120,7 @@ export const docsZh = {
       { guidance: true, description: 'Write a group label that says what the choices represent: "Export formats" tells users more than "Options".' },
       { guidance: false, description: 'Show a CheckboxList when the user can only pick one thing; that is what RadioList is for.' },
       { guidance: false, description: 'Put buttons or links inside the trailing slot (endContent); the whole row is already tappable, so a nested button creates two competing click targets.' },
+      { guidance: false, description: 'Wrap a disabled CheckboxList in Tooltip to explain why it is disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.' },
     ],
   },
 };
@@ -129,6 +137,7 @@ export const docsDense = {
       { guidance: true, description: 'Write a group label that says what the choices represent: "Export formats" tells users more than "Options".' },
       { guidance: false, description: 'Show a CheckboxList when the user can only pick one thing; that is what RadioList is for.' },
       { guidance: false, description: 'Put buttons or links inside the trailing slot (endContent); the whole row is already tappable, so a nested button creates two competing click targets.' },
+      { guidance: false, description: 'Wrap a disabled CheckboxList in Tooltip to explain why it is disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.' },
     ],
   },
 };