@astryxdesign/core 0.1.1 → 0.1.2-canary.04e71b2

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

package/src/CheckboxList/CheckboxList.test.tsx

@@ -9,13 +9,46 @@
  * SYNC: When CheckboxList.tsx or CheckboxListItem.tsx changes, update tests to match new behavior
  */
 
-import {describe, it, expect, vi} from 'vitest';
-import {render, screen, fireEvent, within} from '@testing-library/react';
+import {describe, it, expect, vi, beforeEach} from 'vitest';
+import {
+  render,
+  screen,
+  fireEvent,
+  within,
+  waitFor,
+} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import {CheckboxList} from './CheckboxList';
 import {CheckboxListItem} from './CheckboxListItem';
 import {List} from '../List/List';
 
+// 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('CheckboxList', () => {
   it('renders with label', () => {
     render(
@@ -26,6 +59,25 @@ describe('CheckboxList', () => {
     expect(screen.getByText('Preferences')).toBeInTheDocument();
   });
 
+  it('wraps items in a group named by the label (forms audit: group role)', () => {
+    render(
+      <CheckboxList label="Preferences" value={[]} onChange={() => {}}>
+        <CheckboxListItem label="Option A" value="a" />
+      </CheckboxList>,
+    );
+    // The checkboxes are wrapped in a role="group" whose accessible name comes
+    // from the field label (via aria-labelledby). The label is rendered as a
+    // <span> (not a literal <label>, which can't name a group) with no
+    // orphaned htmlFor.
+    const group = screen.getByRole('group', {name: 'Preferences'});
+    expect(group).toBeInTheDocument();
+    const label = screen.getByText('Preferences');
+    expect(label.tagName).toBe('SPAN');
+    expect(label.closest('label')).toBeNull();
+    expect(label).not.toHaveAttribute('for');
+    expect(group.getAttribute('aria-labelledby')).toBe(label.id);
+  });
+
   it('renders checkbox items', () => {
     render(
       <CheckboxList label="Preferences" value={[]} onChange={() => {}}>
@@ -39,10 +91,7 @@ describe('CheckboxList', () => {
 
   it('checks the correct items based on value prop', () => {
     render(
-      <CheckboxList
-        label="Preferences"
-        value={['a', 'c']}
-        onChange={() => {}}>
+      <CheckboxList label="Preferences" value={['a', 'c']} onChange={() => {}}>
         <CheckboxListItem label="Option A" value="a" />
         <CheckboxListItem label="Option B" value="b" />
         <CheckboxListItem label="Option C" value="c" />
@@ -58,10 +107,7 @@ describe('CheckboxList', () => {
     const user = userEvent.setup();
     const handleChange = vi.fn();
     render(
-      <CheckboxList
-        label="Preferences"
-        value={['a']}
-        onChange={handleChange}>
+      <CheckboxList label="Preferences" value={['a']} onChange={handleChange}>
         <CheckboxListItem label="Option A" value="a" />
         <CheckboxListItem label="Option B" value="b" />
       </CheckboxList>,
@@ -272,11 +318,7 @@ describe('CheckboxList', () => {
           isChecked={false}
           onCheck={handleSelectAll}
         />
-        <CheckboxListItem
-          label="Name"
-          isChecked={true}
-          onCheck={handleCheck}
-        />
+        <CheckboxListItem label="Name" isChecked={true} onCheck={handleCheck} />
         <CheckboxListItem
           label="Email"
           isChecked={false}
@@ -347,8 +389,15 @@ describe('CheckboxListItem standalone mode', () => {
         <CheckboxListItem label="Partial" isChecked="indeterminate" />
       </List>,
     );
+    // The inner native checkbox exposes mixed state via the indeterminate DOM
+    // property (not a redundant aria-checked, forms-16); the list row still
+    // carries aria-checked="mixed" for its own listitem semantics.
     const checkbox = screen.getByRole('checkbox');
-    expect(checkbox).toHaveAttribute('aria-checked', 'mixed');
+    expect(checkbox).toBeInstanceOf(HTMLInputElement);
+    if (checkbox instanceof HTMLInputElement) {
+      expect(checkbox.indeterminate).toBe(true);
+    }
+    expect(checkbox).not.toHaveAttribute('aria-checked');
   });
 
   it('calls onCheck with true when clicking indeterminate item', async () => {
@@ -500,4 +549,108 @@ describe('CheckboxListItem ARIA props', () => {
     expect(item).toHaveAttribute('aria-describedby', 'help-text');
     expect(item).toHaveAttribute('aria-label', 'custom label');
   });
+
+  describe('disabledMessage', () => {
+    const h = {hidden: true} as const;
+
+    function renderGroup(props?: {onChange?: (v: string[]) => void}) {
+      return render(
+        <CheckboxList
+          label="Notifications"
+          value={['email']}
+          onChange={props?.onChange ?? (() => {})}
+          isDisabled
+          disabledMessage="Notifications are managed by your administrator">
+          <CheckboxListItem label="Email" value="email" />
+          <CheckboxListItem label="SMS" value="sms" />
+        </CheckboxList>,
+      );
+    }
+
+    it('shows the reason tooltip on hover when the group is disabled with a reason', async () => {
+      renderGroup();
+      const tooltip = screen.getByRole('tooltip', h);
+      expect(tooltip).toHaveTextContent(
+        'Notifications are managed by your administrator',
+      );
+      const group = screen.getByRole('group');
+      fireEvent.mouseEnter(group);
+      await waitFor(() => expect(tooltip).toHaveAttribute('popover-open'));
+      fireEvent.mouseLeave(group);
+      await waitFor(() => expect(tooltip).not.toHaveAttribute('popover-open'));
+    });
+
+    it('shows the reason tooltip on keyboard focus', async () => {
+      const user = userEvent.setup();
+      renderGroup();
+      const tooltip = screen.getByRole('tooltip', h);
+      await user.tab();
+      await waitFor(() => expect(tooltip).toHaveAttribute('popover-open'));
+    });
+
+    it('does not render a tooltip when not disabled', () => {
+      render(
+        <CheckboxList
+          label="Notifications"
+          value={['email']}
+          onChange={() => {}}
+          disabledMessage="Notifications are managed by your administrator">
+          <CheckboxListItem label="Email" value="email" />
+        </CheckboxList>,
+      );
+      expect(screen.queryByRole('tooltip', h)).not.toBeInTheDocument();
+    });
+
+    it('does not render a tooltip when disabled without a reason', () => {
+      render(
+        <CheckboxList
+          label="Notifications"
+          value={['email']}
+          onChange={() => {}}
+          isDisabled>
+          <CheckboxListItem label="Email" value="email" />
+        </CheckboxList>,
+      );
+      expect(screen.queryByRole('tooltip', h)).not.toBeInTheDocument();
+    });
+
+    it('keeps checkboxes focusable via aria-disabled when a reason is provided', () => {
+      renderGroup();
+      for (const checkbox of screen.getAllByRole('checkbox', h)) {
+        expect(checkbox).not.toBeDisabled();
+        expect(checkbox).toHaveAttribute('aria-disabled', 'true');
+      }
+    });
+
+    it('links the reason tooltip from the group via aria-describedby', () => {
+      renderGroup();
+      const group = screen.getByRole('group');
+      const tooltip = screen.getByRole('tooltip', h);
+      expect(group.getAttribute('aria-describedby')).toContain(tooltip.id);
+    });
+
+    it('blocks toggling while focusable-disabled', () => {
+      const onChange = vi.fn();
+      renderGroup({onChange});
+      const sms = screen.getByRole('checkbox', {name: 'SMS', hidden: true});
+      fireEvent.click(sms);
+      expect(onChange).not.toHaveBeenCalled();
+    });
+
+    it('keeps checkboxes natively disabled when disabled without a reason', () => {
+      render(
+        <CheckboxList
+          label="Notifications"
+          value={['email']}
+          onChange={() => {}}
+          isDisabled>
+          <CheckboxListItem label="Email" value="email" />
+          <CheckboxListItem label="SMS" value="sms" />
+        </CheckboxList>,
+      );
+      for (const checkbox of screen.getAllByRole('checkbox', h)) {
+        expect(checkbox).toBeDisabled();
+      }
+    });
+  });
 });

package/src/CheckboxList/CheckboxList.tsx

@@ -30,6 +30,7 @@ import {Field} from '../Field/Field';
 import type {InputStatus} from '../Field/types';
 import {List} from '../List/List';
 import type {ListDensity} from '../List/ListContext';
+import {useTooltip} from '../Tooltip';
 import {mergeProps} from '../utils';
 import {themeProps} from '../utils/themeProps';
 import {
@@ -93,6 +94,18 @@ export interface CheckboxListProps extends Omit<
    * @default false
    */
   isDisabled?: boolean;
+  /**
+   * Explains why the checkbox group is disabled. Applies to the whole-group
+   * disabled state (`isDisabled`), not individual items. When set together with
+   * `isDisabled`, the group shows a tooltip with this text on hover and keyboard
+   * focus, and its checkboxes stay focusable (via `aria-disabled`) so the reason
+   * is discoverable by keyboard and assistive technology. Toggling stays
+   * blocked.
+   *
+   * Use this instead of wrapping a disabled group in `Tooltip` — disabled
+   * controls don't emit the pointer events an external tooltip needs.
+   */
+  disabledMessage?: string;
   /**
    * Whether all checkbox items are read-only.
    * Displays the current state at full opacity but prevents interaction.
@@ -141,6 +154,7 @@ export function CheckboxList({
   density = 'balanced',
   hasDividers = false,
   isDisabled = false,
+  disabledMessage,
   isReadOnly = false,
   children,
   ref,
@@ -151,6 +165,7 @@ export function CheckboxList({
   'data-testid': dataTestId,
 }: CheckboxListProps) {
   const inputID = useId();
+  const labelID = useId();
   const descriptionID = useId();
   const statusMessageID = useId();
 
@@ -162,6 +177,19 @@ export function CheckboxList({
   // the transition settles, so the spinner clears without manual cleanup.
   const [loadingValue, setLoadingValue] = useOptimistic<string | null>(null);
 
+  // Disabled-reason tooltip. Applies to the whole-group disabled state. Disabled
+  // controls swallow pointer events, so the tooltip listeners attach to the
+  // group container and the checkboxes stay perceivable via aria-disabled
+  // instead of the disabled attribute. Toggling is blocked in the item.
+  const showsDisabledMessage = isDisabled && !!disabledMessage;
+  const disabledMessageTooltip = useTooltip({
+    placement: 'above',
+    // The group container is not naturally focusable; focusin bubbles up from
+    // the checkboxes, so always attach focus listeners.
+    focusTrigger: 'always',
+    isEnabled: showsDisabledMessage,
+  });
+
   const handleChange = useCallback(
     (newValues: string[], toggledValue?: string) => {
       onChange?.(newValues);
@@ -189,6 +217,7 @@ export function CheckboxList({
       value: isCollectionMode ? optimisticValue : undefined,
       onChange: isCollectionMode ? handleChange : undefined,
       isDisabled,
+      hasDisabledMessage: showsDisabledMessage,
       isReadOnly,
       loadingValue,
     }),
@@ -197,6 +226,7 @@ export function CheckboxList({
       optimisticValue,
       handleChange,
       isDisabled,
+      showsDisabledMessage,
       isReadOnly,
       loadingValue,
     ],
@@ -210,6 +240,8 @@ export function CheckboxList({
       isLabelHidden={isLabelHidden}
       description={description}
       inputID={inputID}
+      labelID={labelID}
+      isGroupLabel
       descriptionID={description ? descriptionID : undefined}
       isDisabled={isDisabled}
       status={
@@ -226,10 +258,31 @@ export function CheckboxList({
       xstyle={xstyle}
       {...mergeProps(themeProps('checkbox-list'), {className, style})}>
       <CheckboxListContext value={contextValue}>
-        <List density={density} hasDividers={hasDividers}>
-          {children}
-        </List>
+        <div
+          ref={el => {
+            // Anchor + hover/focus listeners for the disabled-message tooltip.
+            // Handlers are gated internally by isEnabled, so attaching
+            // unconditionally is safe.
+            disabledMessageTooltip.ref(el);
+          }}
+          role="group"
+          aria-labelledby={labelID}
+          aria-describedby={
+            [
+              description ? descriptionID : null,
+              status?.message ? statusMessageID : null,
+              showsDisabledMessage ? disabledMessageTooltip.describedBy : null,
+            ]
+              .filter(Boolean)
+              .join(' ') || undefined
+          }>
+          <List density={density} hasDividers={hasDividers}>
+            {children}
+          </List>
+        </div>
       </CheckboxListContext>
+      {showsDisabledMessage &&
+        disabledMessageTooltip.renderTooltip(disabledMessage)}
     </Field>
   );
 }

package/src/CheckboxList/CheckboxListContext.tsx

@@ -21,6 +21,13 @@ export interface CheckboxListContextValue {
    */
   onChange?: (values: string[], toggledValue?: string) => void;
   isDisabled: boolean;
+  /**
+   * True when the whole group is disabled *and* a `disabledMessage` is set. In
+   * that mode items stay focusable via `aria-disabled` (instead of the native
+   * `disabled` attribute) so the group's disabled-reason tooltip is keyboard-
+   * and AT-discoverable; toggling is still blocked.
+   */
+  hasDisabledMessage?: boolean;
   isReadOnly: boolean;
   /**
    * The value of the item with a pending `changeAction`, or null when idle.

package/src/Citation/Citation.doc.mjs

@@ -56,6 +56,16 @@ export const docs = {
     ],
   },
 
+  // `source` is a custom object type the docsite preview cannot generate
+  // automatically; without these defaults the properties tab shows the
+  // missing-required-props placeholder instead of an interactive preview.
+  playground: {
+    defaults: {
+      source: {title: 'Astryx Design', url: 'https://example.com'},
+      number: 1,
+    },
+  },
+
   props: [
     {
       name: 'source',