@astryxdesign/core 0.1.2 → 0.1.3

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 is a
+    // plain listitem and must not carry aria-checked (aria-allowed-attr).
     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 () => {
@@ -370,21 +419,26 @@ describe('CheckboxListItem standalone mode', () => {
 });
 
 describe('CheckboxListItem ARIA props', () => {
-  it('sets aria-checked on the list item in collection mode', () => {
+  it('conveys checked state via the inner checkbox, not aria-checked on the listitem', () => {
     render(
       <CheckboxList label="Prefs" value={['a']} onChange={() => {}}>
         <CheckboxListItem label="Option A" value="a" />
         <CheckboxListItem label="Option B" value="b" />
       </CheckboxList>,
     );
+    // The listitem row must not carry aria-checked (not a valid attribute on
+    // role="listitem" — axe: aria-allowed-attr). Checked state is exposed by
+    // the inner native checkbox instead.
     const items = screen.getAllByRole('listitem');
-    // Item A is checked
-    expect(items[0]).toHaveAttribute('aria-checked', 'true');
-    // Item B is not checked
-    expect(items[1]).toHaveAttribute('aria-checked', 'false');
+    expect(items[0]).not.toHaveAttribute('aria-checked');
+    expect(items[1]).not.toHaveAttribute('aria-checked');
+
+    const checkboxes = screen.getAllByRole('checkbox');
+    expect(checkboxes[0]).toBeChecked();
+    expect(checkboxes[1]).not.toBeChecked();
   });
 
-  it('sets aria-checked on the list item in standalone mode', () => {
+  it('does not put aria-checked on the listitem in standalone mode', () => {
     render(
       <List>
         <CheckboxListItem label="Done" isChecked={true} />
@@ -392,18 +446,26 @@ describe('CheckboxListItem ARIA props', () => {
       </List>,
     );
     const items = screen.getAllByRole('listitem');
-    expect(items[0]).toHaveAttribute('aria-checked', 'true');
-    expect(items[1]).toHaveAttribute('aria-checked', 'false');
+    expect(items[0]).not.toHaveAttribute('aria-checked');
+    expect(items[1]).not.toHaveAttribute('aria-checked');
+
+    const checkboxes = screen.getAllByRole('checkbox');
+    expect(checkboxes[0]).toBeChecked();
+    expect(checkboxes[1]).not.toBeChecked();
   });
 
-  it('sets aria-checked="mixed" for indeterminate items', () => {
+  it('exposes indeterminate state via the checkbox, not aria-checked on the listitem', () => {
     render(
       <List>
         <CheckboxListItem label="Partial" isChecked="indeterminate" />
       </List>,
     );
     const item = screen.getByRole('listitem');
-    expect(item).toHaveAttribute('aria-checked', 'mixed');
+    expect(item).not.toHaveAttribute('aria-checked');
+    const checkbox = screen.getByRole('checkbox');
+    if (checkbox instanceof HTMLInputElement) {
+      expect(checkbox.indeterminate).toBe(true);
+    }
   });
 
   it('does not mark items aria-busy when idle', () => {
@@ -500,4 +562,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/CheckboxList/CheckboxListItem.tsx

@@ -201,9 +201,6 @@ export function CheckboxListItem({
       endContent={endContent}
       isDisabled={effectiveDisabled}
       onClick={isInteractive ? handleToggle : undefined}
-      aria-checked={
-        resolvedChecked === 'indeterminate' ? 'mixed' : resolvedChecked
-      }
       aria-busy={isBusy || undefined}
       xstyle={
         [

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',

package/src/Citation/Citation.test.tsx

@@ -0,0 +1,121 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Citation.test.tsx
+ * @input Uses React Testing Library, Citation, theme tokens
+ * @output Tests for Citation component
+ */
+
+import {render, screen} from '@testing-library/react';
+import {describe, it, expect} from 'vitest';
+import * as stylex from '@stylexjs/stylex';
+import {colorVars} from '../theme/tokens.stylex';
+import {Citation} from './Citation';
+
+// StyleX emits one deterministic atomic class per property/value pair, so an
+// element carries a probe's class exactly when it has the same declaration.
+// The dev-mode debug class (contains "__") varies by source location and is
+// excluded from the comparison.
+const probe = stylex.create({
+  secondaryText: {color: colorVars['--color-text-secondary']},
+  accentText: {color: colorVars['--color-text-accent']},
+  badgeBackground: {backgroundColor: colorVars['--color-accent-muted']},
+});
+
+function atomicClasses(style: (typeof probe)[keyof typeof probe]): string[] {
+  const {className = ''} = stylex.props(style);
+  return className.split(' ').filter(c => c !== '' && !c.includes('__'));
+}
+
+describe('Citation', () => {
+  const source = {title: 'Example Source', url: 'https://example.com'};
+
+  it('renders the source title as a link in the label variant', () => {
+    render(<Citation source={source} number={1} data-testid="citation" />);
+    const el = screen.getByTestId('citation');
+    expect(el.tagName).toBe('A');
+    expect(el).toHaveAttribute('href', 'https://example.com');
+    expect(el).toHaveTextContent('Example Source');
+  });
+
+  it('renders the index as a badge in the number variant', () => {
+    render(
+      <Citation
+        source={source}
+        number={3}
+        variant="number"
+        data-testid="citation"
+      />,
+    );
+    const el = screen.getByTestId('citation');
+    expect(el).toHaveTextContent('3');
+    expect(el).toHaveAttribute('role', 'doc-noteref');
+    expect(el).toHaveAttribute('aria-label', 'Citation 3: Example Source');
+  });
+
+  it('renders as a span when the source has no url', () => {
+    render(
+      <Citation
+        source={{title: 'No link'}}
+        number={1}
+        data-testid="citation"
+      />,
+    );
+    const el = screen.getByTestId('citation');
+    expect(el.tagName).toBe('SPAN');
+    // doc-noteref is a reference role that is not permitted on a plain
+    // (unlinked) span (axe: aria-allowed-role), so it must be omitted here.
+    expect(el).not.toHaveAttribute('role');
+  });
+
+  it('renders astryx-* class names for theme targeting', () => {
+    render(<Citation source={source} number={1} data-testid="citation" />);
+    expect(screen.getByTestId('citation').className).toContain(
+      'astryx-citation',
+    );
+  });
+
+  it('uses the secondary text color in the label variant', () => {
+    render(<Citation source={source} number={1} data-testid="citation" />);
+    const el = screen.getByTestId('citation');
+    for (const cls of atomicClasses(probe.secondaryText)) {
+      expect(el.classList.contains(cls)).toBe(true);
+    }
+  });
+
+  it('uses the secondary text color, not accent, in the number variant', () => {
+    render(
+      <Citation
+        source={source}
+        number={1}
+        variant="number"
+        data-testid="citation"
+      />,
+    );
+    const el = screen.getByTestId('citation');
+    for (const cls of atomicClasses(probe.secondaryText)) {
+      expect(el.classList.contains(cls)).toBe(true);
+    }
+    for (const cls of atomicClasses(probe.accentText)) {
+      expect(el.classList.contains(cls)).toBe(false);
+    }
+  });
+
+  it('keeps the accent-muted badge background when the source has a url', () => {
+    // `numberHover` must not clobber the base background: a hover-only
+    // conditional without a default replaces the whole property on merge,
+    // leaving linked badges with a transparent pill.
+    render(
+      <Citation
+        source={source}
+        number={1}
+        variant="number"
+        data-testid="citation"
+      />,
+    );
+    const el = screen.getByTestId('citation');
+    for (const cls of atomicClasses(probe.badgeBackground)) {
+      expect(el.classList.contains(cls)).toBe(true);
+    }
+  });
+});

package/src/Citation/Citation.tsx

@@ -83,6 +83,10 @@ const styles = stylex.create({
       },
     },
     color: {
+      // Explicit default: without it, this hover-only conditional replaces
+      // the base secondary color from `label` (last-wins property merge),
+      // leaving linked citations to inherit the surrounding text color.
+      default: colorVars['--color-text-secondary'],
       ':hover': {
         '@media (hover: hover)': colorVars['--color-text-primary'],
       },
@@ -96,7 +100,7 @@ const styles = stylex.create({
     fontSize: typeScaleVars['--text-supporting-size'],
     fontWeight: fontWeightVars['--font-weight-semibold'],
     lineHeight: typeScaleVars['--text-supporting-leading'],
-    color: colorVars['--color-text-accent'],
+    color: colorVars['--color-text-secondary'],
     backgroundColor: colorVars['--color-accent-muted'],
     borderRadius: radiusVars['--radius-full'],
     minWidth: spacingVars['--spacing-5'],
@@ -110,6 +114,10 @@ const styles = stylex.create({
   },
   numberHover: {
     backgroundColor: {
+      // Explicit default for the same reason as labelHover's color: a
+      // hover-only conditional replaces the base accent-muted pill from
+      // `number` on merge, leaving linked badges transparent.
+      default: colorVars['--color-accent-muted'],
       ':hover': {
         '@media (hover: hover)': colorVars['--color-overlay-hover'],
       },
@@ -150,6 +158,10 @@ export function Citation({
   const href = source.url;
   const icon = source.icon;
   const Tag = href ? 'a' : 'span';
+  // `doc-noteref` is a reference role — only appropriate on the interactive
+  // link form. On a plain (unlinked) span it is not a permitted role
+  // (axe: aria-allowed-role), so omit it there; the aria-label still names it.
+  const noteRole = href ? ('doc-noteref' as const) : undefined;
   const linkProps = href
     ? {
         href,
@@ -168,7 +180,7 @@ export function Citation({
       <Tag
         {...rest}
         ref={elementRef}
-        role="doc-noteref"
+        role={noteRole}
         aria-label={`Citation ${number}: ${title}`}
         data-testid={testId}
         {...linkProps}
@@ -191,7 +203,7 @@ export function Citation({
     <Tag
       {...rest}
       ref={elementRef}
-      role="doc-noteref"
+      role={noteRole}
       aria-label={`Citation ${number}: ${title}`}
       data-testid={testId}
       {...linkProps}