@astryxdesign/core 0.1.2 → 0.1.3

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.' },
     ],
   },
 };