@astryxdesign/core 0.1.2 → 0.1.3

package/src/Selector/Selector.tsx

@@ -4,13 +4,15 @@
 
 /**
  * @file Selector.tsx
- * @input Uses React, StyleX, usePopover, Icon
+ * @input Uses React, StyleX, usePopover, useTooltip, Icon, InputGroupContext
  * @output Exports Selector component
  * @position Core implementation; consumed by index.ts
  *
  * SYNC: When modified, update:
  * - /packages/core/src/Selector/Selector.doc.mjs
+ * - /packages/core/src/Selector/Selector.test.tsx
  * - /packages/core/src/Selector/index.ts
+ * - /apps/storybook/stories/InputGroup.stories.tsx
  * - /packages/cli/templates/blocks/components/Selector/ (showcase blocks)
  */
 
@@ -27,6 +29,7 @@ import React, {
 } from 'react';
 import * as stylex from '@stylexjs/stylex';
 import {usePopover} from '../Popover/usePopover';
+import {useTooltip} from '../Tooltip';
 import {Icon, renderIconSlot, type IconType} from '../Icon';
 import type {IconName} from '../Icon';
 import {
@@ -61,11 +64,14 @@ import {
 } from './utils';
 import {useCombobox, useSelectedItemOffset} from './hooks';
 import {SelectorOption} from './SelectorOption';
-import {mergeProps} from '../utils';
+import {getInputARIA, mergeProps} from '../utils';
 import {useSize} from '../SizeContext/SizeContext';
 import type {BaseProps} from '../BaseProps';
 import type {SizeValue} from '../utils/types';
 import {themeProps} from '../utils/themeProps';
+import {groupStyles} from '../InputGroup/groupStyles';
+import {useInputGroup} from '../InputGroup/InputGroupContext';
+import {VisuallyHidden} from '../VisuallyHidden';
 
 const styles = stylex.create({
   // Trigger container — the enhanced click target wrapping the combobox button and clear button as siblings
@@ -369,6 +375,28 @@ interface SelectorPropsBase<
    */
   isDisabled?: boolean;
 
+  /**
+   * Explains why the selector is disabled. When set together with
+   * `isDisabled`, the selector shows a tooltip with this text on hover and
+   * keyboard focus, and the trigger 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 selector in `Tooltip` — disabled
+   * controls don't emit the pointer events an external tooltip needs.
+   *
+   * @example
+   * ```
+   * <Selector
+   *   label="Owner"
+   *   options={owners}
+   *   isDisabled
+   *   disabledMessage="You need the Editor role to change this"
+   * />
+   * ```
+   */
+  disabledMessage?: string;
+
   /**
    * The options to display in the selector.
    * Can be strings, objects, dividers, or sections.
@@ -474,34 +502,30 @@ type SelectorPropsNonClearable<
   changeAction?: (value: string) => void | Promise<void>;
 };
 
-type SelectorPropsClearable<
-  T extends SelectorOptionType = SelectorOptionType,
-> = SelectorPropsBase<T> & {
-  /**
-   * Whether to show a clear button when a value is selected.
-   * When clicked, resets the value to `null` and returns focus to the trigger.
-   *
-   * When enabled, `value` and `onChange` widen to include `null`.
-   */
-  hasClear: true;
-  value: string | null;
-  onChange?: (value: string | null) => void;
-  changeAction?: (value: string | null) => void | Promise<void>;
-};
-
-export type SelectorProps<
-  T extends SelectorOptionType = SelectorOptionType,
-> = SelectorPropsNonClearable<T> | SelectorPropsClearable<T>;
+type SelectorPropsClearable<T extends SelectorOptionType = SelectorOptionType> =
+  SelectorPropsBase<T> & {
+    /**
+     * Whether to show a clear button when a value is selected.
+     * When clicked, resets the value to `null` and returns focus to the trigger.
+     *
+     * When enabled, `value` and `onChange` widen to include `null`.
+     */
+    hasClear: true;
+    value: string | null;
+    onChange?: (value: string | null) => void;
+    changeAction?: (value: string | null) => void | Promise<void>;
+  };
+
+export type SelectorProps<T extends SelectorOptionType = SelectorOptionType> =
+  | SelectorPropsNonClearable<T>
+  | SelectorPropsClearable<T>;
 
 /**
  * Default option renderer
  */
 function DefaultOption({option}: {option: SelectorOptionData}) {
   return (
-    <SelectorOption
-      icon={option.icon}
-      label={option.label ?? option.value}
-    />
+    <SelectorOption icon={option.icon} label={option.label ?? option.value} />
   );
 }
 
@@ -529,6 +553,7 @@ export function Selector<T extends SelectorOptionType>(
     isOptional = false,
     isRequired = false,
     isDisabled = false,
+    disabledMessage,
     options,
     value,
     onChange,
@@ -561,9 +586,11 @@ export function Selector<T extends SelectorOptionType>(
   const listboxId = useId();
   const descriptionId = useId();
   const statusMessageId = useId();
+  const inputLabelId = useId();
   const searchId = useId();
   const triggerRef = useRef<HTMLButtonElement>(null);
   const searchRef = useRef<HTMLInputElement>(null);
+  const inputGroup = useInputGroup();
 
   const [searchQuery, setSearchQuery] = useState('');
 
@@ -571,14 +598,29 @@ export function Selector<T extends SelectorOptionType>(
   const [optimisticValue, setOptimisticValue] = useOptimistic(normalizedValue);
   const isBusy = isLoading || optimisticValue !== normalizedValue;
 
-  // Build aria-describedby
-  const ariaDescribedBy =
+  // Disabled-reason tooltip. Disabled controls swallow pointer events, so the
+  // tooltip listeners attach to the trigger container (which already exists)
+  // and the trigger button stays perceivable via aria-disabled instead of the
+  // disabled attribute. Activation is blocked by the isDisabled guards in
+  // useCombobox (onTriggerClick / onKeyDown).
+  const showsDisabledMessage = isDisabled && !!disabledMessage;
+  const disabledMessageTooltip = useTooltip({
+    placement: 'above',
+    // The container div is not naturally focusable; focusin bubbles up from
+    // the trigger button, so always attach focus listeners.
+    focusTrigger: 'always',
+    isEnabled: showsDisabledMessage,
+  });
+
+  const {ariaLabelledBy, ariaDescribedBy} = getInputARIA(
+    inputLabelId,
     [
       description ? descriptionId : null,
       status?.message ? statusMessageId : null,
-    ]
-      .filter(Boolean)
-      .join(' ') || undefined;
+      showsDisabledMessage ? disabledMessageTooltip.describedBy : null,
+    ],
+    inputGroup,
+  );
 
   // Flatten options for keyboard navigation
   const selectableItems = useMemo(
@@ -622,6 +664,9 @@ export function Selector<T extends SelectorOptionType>(
     hasLightDismiss: true,
     hasCloseButton: false,
     hasAutoFocus: false,
+    // The popup's own role="listbox" is the exposed semantics; the trigger
+    // keeps DOM focus, so wrapping it in a modal dialog would misrepresent it.
+    role: 'none',
   });
 
   // Open dropdown on mount when isDefaultOpen is true
@@ -653,6 +698,18 @@ export function Selector<T extends SelectorOptionType>(
       ? {marginBlockStart: `-${selectedItemOffset}px`}
       : undefined;
 
+  // Clear the current value. Shared by the clear button and the keyboard
+  // Delete/Backspace path so clearing is reachable without a mouse.
+  const clearValue = useCallback(() => {
+    onChange?.(null);
+    if (changeAction) {
+      startTransition(async () => {
+        setOptimisticValue(undefined);
+        await changeAction(null);
+      });
+    }
+  }, [onChange, changeAction, startTransition, setOptimisticValue]);
+
   // Selector behavior (keyboard nav, typeahead, selection)
   const {
     highlightedIndex,
@@ -689,22 +746,30 @@ export function Selector<T extends SelectorOptionType>(
       },
       [onChange, changeAction, startTransition, setOptimisticValue],
     ),
+    onClear: hasClear ? clearValue : undefined,
     listboxId,
   });
 
+  // Keep the highlighted option visible during keyboard navigation. The
+  // listbox is a fixed-height scroll container, so without this the virtual
+  // cursor walks off-screen once navigation passes the visible window. Mirrors
+  // CommandPaletteItem's scrollIntoView({block: 'nearest'}) behavior.
+  useEffect(() => {
+    if (!popover.isOpen || highlightedIndex < 0) {
+      return;
+    }
+    document
+      .getElementById(getItemId(highlightedIndex))
+      ?.scrollIntoView?.({block: 'nearest'});
+  }, [popover.isOpen, highlightedIndex, getItemId]);
+
   // Handle clear button click
   const handleClear = useCallback(
     (e: React.MouseEvent) => {
       e.stopPropagation(); // Don't open dropdown
-      onChange?.(null);
-      if (changeAction) {
-        startTransition(async () => {
-          setOptimisticValue(undefined);
-          await changeAction(null);
-        });
-      }
+      clearValue();
     },
-    [onChange, changeAction, startTransition, setOptimisticValue],
+    [clearValue],
   );
 
   // Render search input
@@ -717,16 +782,30 @@ export function Selector<T extends SelectorOptionType>(
         <input
           ref={searchRef}
           id={searchId}
-          role="searchbox"
+          // When hasSearch is set, focus moves into this input on open, so it —
+          // not the trigger — must be the combobox that reports the highlighted
+          // option via aria-activedescendant (comboboxes-4). A bare searchbox
+          // left the highlight silent to screen readers.
+          role="combobox"
+          aria-expanded={popover.isOpen}
           aria-controls={listboxId}
+          aria-autocomplete="list"
+          aria-activedescendant={
+            popover.isOpen && highlightedIndex >= 0
+              ? getItemId(highlightedIndex)
+              : undefined
+          }
           aria-label="Search options"
           type="text"
           value={searchQuery}
           onChange={e => setSearchQuery(e.target.value)}
           onKeyDown={e => {
+            // Arrow keys navigate options; Enter selects; Escape/Tab close.
+            // Home/End are left to the input for caret movement.
             if (
               e.key === 'ArrowDown' ||
               e.key === 'ArrowUp' ||
+              e.key === 'Enter' ||
               e.key === 'Escape' ||
               e.key === 'Tab'
             ) {
@@ -745,6 +824,9 @@ export function Selector<T extends SelectorOptionType>(
     searchQuery,
     searchPlaceholder,
     onKeyDown,
+    popover.isOpen,
+    highlightedIndex,
+    getItemId,
   ]);
 
   // Render an individual item
@@ -812,9 +894,7 @@ export function Selector<T extends SelectorOptionType>(
       const option = options[i];
 
       if (isDivider(option)) {
-        elements.push(
-          <Divider key={`divider-${i}`} xstyle={styles.divider} />,
-        );
+        elements.push(<Divider key={`divider-${i}`} xstyle={styles.divider} />);
       } else if (isSection(option)) {
         const sectionItems: ReactNode[] = [];
         for (const opt of option.options) {
@@ -844,30 +924,15 @@ export function Selector<T extends SelectorOptionType>(
     return elements;
   }, [options, renderItem, hasSearch, searchQuery, filteredItems]);
 
-  return (
-    <Field
-      label={label}
-      isLabelHidden={isLabelHidden}
-      description={description}
-      inputID={triggerId}
-      descriptionID={description ? descriptionId : undefined}
-      isOptional={isOptional}
-      isRequired={isRequired}
-      isDisabled={isDisabled}
-      status={
-        status
-          ? {
-              type: status.type,
-              message: status.message,
-              messageID: status.message ? statusMessageId : undefined,
-            }
-          : undefined
-      }
-      labelTooltip={labelTooltip}
-      width={width}>
+  const selectorContent = (
+    <>
       <div
         ref={el => {
           popover.triggerRef(el);
+          // Anchor + hover/focus listeners for the disabled-message tooltip.
+          // Handlers are gated internally by isEnabled, and anchor names
+          // compose, so attaching unconditionally is safe.
+          disabledMessageTooltip.ref(el);
         }}
         onClick={onTriggerClick}
         data-testid={testId}
@@ -881,6 +946,7 @@ export function Selector<T extends SelectorOptionType>(
             !selectedItem && styles.triggerPlaceholder,
             status && inputStatusBorderStyles[status.type],
             status && inputStatusHoverShadowStyles[status.type],
+            inputGroup && groupStyles.inGroup,
             xstyle,
           ),
           className,
@@ -888,27 +954,38 @@ export function Selector<T extends SelectorOptionType>(
         )}>
         {startIcon &&
           renderIconSlot(startIcon, {size: 'sm', color: 'secondary'})}
+        {inputGroup && (
+          <VisuallyHidden id={inputLabelId}>{label}</VisuallyHidden>
+        )}
         <button
           ref={triggerRef}
           id={triggerId}
           type="button"
-          role="combobox"
+          // In hasSearch mode the popup's search input is the combobox (it owns
+          // focus + aria-activedescendant, comboboxes-4), so the trigger is a
+          // plain button that opens the listbox — not a second combobox.
+          role={hasSearch ? undefined : 'combobox'}
           {...rest}
           aria-haspopup="listbox"
           aria-expanded={popover.isOpen}
           aria-controls={listboxId}
           aria-activedescendant={
-            popover.isOpen && highlightedIndex >= 0
+            !hasSearch && popover.isOpen && highlightedIndex >= 0
               ? getItemId(highlightedIndex)
               : undefined
           }
           aria-describedby={ariaDescribedBy}
+          aria-labelledby={ariaLabelledBy}
           aria-required={isRequired ? 'true' : undefined}
           aria-invalid={status?.type === 'error' ? 'true' : undefined}
           aria-busy={isBusy || undefined}
-          disabled={isDisabled}
+          // With a disabledMessage the trigger keeps focusability via
+          // aria-disabled so the reason is focus-discoverable; activation is
+          // still blocked by the isDisabled guards in useCombobox.
+          disabled={isDisabled && !showsDisabledMessage}
+          aria-disabled={showsDisabledMessage ? 'true' : undefined}
           onKeyDown={onKeyDown}
-          tabIndex={-1}
+          tabIndex={isDisabled && !showsDisabledMessage ? -1 : 0}
           {...stylex.props(styles.trigger)}>
           <span {...stylex.props(styles.triggerLabel)}>
             {selectedItem?.label ?? placeholder}
@@ -918,7 +995,6 @@ export function Selector<T extends SelectorOptionType>(
         {hasClear && value != null && !isDisabled && (
           <button
             type="button"
-            tabIndex={-1}
             onClick={handleClear}
             aria-label={`Clear ${label}`}
             {...stylex.props(styles.clearButton)}>
@@ -976,6 +1052,38 @@ export function Selector<T extends SelectorOptionType>(
           style: popoverOffsetStyle,
         },
       )}
+
+      {showsDisabledMessage &&
+        disabledMessageTooltip.renderTooltip(disabledMessage)}
+    </>
+  );
+
+  if (inputGroup) {
+    return selectorContent;
+  }
+
+  return (
+    <Field
+      label={label}
+      isLabelHidden={isLabelHidden}
+      description={description}
+      inputID={triggerId}
+      descriptionID={description ? descriptionId : undefined}
+      isOptional={isOptional}
+      isRequired={isRequired}
+      isDisabled={isDisabled}
+      status={
+        status
+          ? {
+              type: status.type,
+              message: status.message,
+              messageID: status.message ? statusMessageId : undefined,
+            }
+          : undefined
+      }
+      labelTooltip={labelTooltip}
+      width={width}>
+      {selectorContent}
     </Field>
   );
 }

package/src/Selector/hooks.ts

@@ -138,6 +138,13 @@ interface UseComboboxOptions {
   onOpen: () => void;
   onClose: () => void;
   onSelect?: (value: string) => void;
+  /**
+   * Clear the current value. When provided, pressing Delete or Backspace on the
+   * closed trigger clears the selection — a keyboard equivalent of the clear
+   * button, so clearing is not mouse-only. No-op when the popup is open (arrow
+   * navigation owns those keys there) or when there is no value.
+   */
+  onClear?: () => void;
   listboxId: string;
 }
 
@@ -163,6 +170,7 @@ export function useCombobox({
   onOpen,
   onClose,
   onSelect,
+  onClear,
   listboxId,
 }: UseComboboxOptions): UseComboboxResult {
   const [highlightedIndex, setHighlightedIndex] = useState<number>(-1);
@@ -310,6 +318,19 @@ export function useCombobox({
           }
           break;
 
+        case 'Delete':
+        case 'Backspace':
+          // Keyboard equivalent of the clear button (comboboxes-2): clear the
+          // value from the closed trigger so clearing is not mouse-only. When
+          // hasSearch is active these keys must edit the search text instead,
+          // and when the popup is open arrow navigation owns interaction, so
+          // only handle the closed non-search case with a clearable value.
+          if (!hasSearch && !isOpen && onClear != null && value != null) {
+            e.preventDefault();
+            onClear();
+          }
+          break;
+
         default:
           if (!hasSearch && e.key.length === 1 && !e.ctrlKey && !e.metaKey) {
             const newTypeahead = typeahead + e.key.toLowerCase();
@@ -349,6 +370,8 @@ export function useCombobox({
       getEnabledIndices,
       typeahead,
       hasSearch,
+      onClear,
+      value,
     ],
   );
 

package/src/SideNav/SideNav.test.tsx

@@ -234,6 +234,38 @@ describe('SideNavHeading', () => {
     expect(links[1]).toHaveAttribute('href', '/product');
   });
 
+  it('gives every link an accessible name with superheadingHref, headingHref, and menu', () => {
+    render(
+      <SideNavHeading
+        icon={<span>Icon</span>}
+        superheading="Suite Name"
+        superheadingHref="/suite"
+        heading="Product Name"
+        headingHref="/product"
+        menu={<div>Analytics</div>}
+      />,
+    );
+    // The icon link to /product previously rendered with no text and no
+    // aria-label, producing an empty accessible name (axe rule: link-name).
+    // Every link pointing at /product must now expose "Product Name".
+    const productLinks = screen
+      .getAllByRole('link', {name: 'Product Name'})
+      .filter(link => link.getAttribute('href') === '/product');
+    expect(productLinks.length).toBeGreaterThan(0);
+    for (const link of productLinks) {
+      expect(link).toHaveAccessibleName('Product Name');
+    }
+    // The independent superheading link is unaffected.
+    expect(screen.getByRole('link', {name: 'Suite Name'})).toHaveAttribute(
+      'href',
+      '/suite',
+    );
+    // No link should be missing an accessible name.
+    for (const link of screen.getAllByRole('link')) {
+      expect(link).toHaveAccessibleName();
+    }
+  });
+
   it('shows chevron when menu is provided', () => {
     render(<SideNavHeading heading="My App" menu={<div>Menu content</div>} />);
     // The chevron SVG should be rendered
@@ -577,6 +609,22 @@ describe('SideNavItem', () => {
     expect(link).toHaveAttribute('aria-current', 'page');
   });
 
+  it('places aria-current on the link, not the wrapper, for split-action items', () => {
+    // A collapsible item (has children) WITH a primary href renders the
+    // split-action path: the link and the expand toggle are siblings inside a
+    // wrapper div. aria-current="page" must sit on the focusable link so it is
+    // announced as the current page (navigation-8).
+    render(
+      <SideNavItem label="Reports" href="/reports" isSelected>
+        <SideNavItem label="Weekly" href="/reports/weekly" />
+      </SideNavItem>,
+    );
+    const link = screen.getByRole('link', {name: /Reports/});
+    expect(link).toHaveAttribute('aria-current', 'page');
+    // The wrapper div must NOT carry aria-current.
+    expect(link.closest('[aria-current="page"]')).toBe(link);
+  });
+
   it('renders custom component when as and href are provided', () => {
     render(<SideNavItem label="Dashboard" href="/dashboard" as={CustomLink} />);
     const link = screen.getByRole('link');

package/src/SideNav/SideNavHeading.tsx

@@ -652,7 +652,10 @@ export function SideNavHeading({
           )}>
           {icon &&
             (headingHref ? (
-              <LinkComponent href={headingHref} {...stylex.props(styles.icon)}>
+              <LinkComponent
+                href={headingHref}
+                aria-label={heading}
+                {...stylex.props(styles.icon)}>
                 {icon}
               </LinkComponent>
             ) : (
@@ -709,7 +712,10 @@ export function SideNavHeading({
         {...props}>
         {icon &&
           (headingHref ? (
-            <LinkComponent href={headingHref} {...stylex.props(styles.icon)}>
+            <LinkComponent
+              href={headingHref}
+              aria-label={heading}
+              {...stylex.props(styles.icon)}>
               {icon}
             </LinkComponent>
           ) : (

package/src/SideNav/SideNavItem.tsx

@@ -612,16 +612,14 @@ export function SideNavItem({
 
   if (hasIndependentToggle) {
     itemElement = (
-      <div
-        aria-current={isSelected ? ('page' as const) : undefined}
-        data-testid={testId}
-        {...navItemStyleProps}>
+      <div data-testid={testId} {...navItemStyleProps}>
         <NavItemElement
           ref={ref}
           href={href}
           as={as}
           isDisabled={isDisabled}
           onClick={handleClick}
+          aria-current={isSelected ? ('page' as const) : undefined}
           {...stylex.props(styles.splitAction)}>
           {itemContent}
         </NavItemElement>

package/src/Skeleton/Skeleton.test.tsx

@@ -0,0 +1,25 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {describe, it, expect} from 'vitest';
+import {render, screen} from '@testing-library/react';
+import {Skeleton} from './Skeleton';
+
+describe('Skeleton', () => {
+  it('renders a placeholder element', () => {
+    render(<Skeleton width={200} height={20} data-testid="sk" />);
+    expect(screen.getByTestId('sk')).toBeInTheDocument();
+  });
+
+  it('is hidden from assistive tech by default (complex-20)', () => {
+    render(<Skeleton width={200} height={20} data-testid="sk" />);
+    expect(screen.getByTestId('sk')).toHaveAttribute('aria-hidden', 'true');
+  });
+
+  it('allows the aria-hidden default to be overridden', () => {
+    render(
+      <Skeleton width={200} height={20} data-testid="sk" aria-hidden={false} />,
+    );
+    // Consumer opt-out: not hidden when explicitly set false.
+    expect(screen.getByTestId('sk')).toHaveAttribute('aria-hidden', 'false');
+  });
+});

package/src/Skeleton/Skeleton.tsx

@@ -62,7 +62,12 @@ const styles = stylex.create({
     animationDirection: 'alternate',
     animationDuration: durationVars['--duration-medium-max'],
     animationIterationCount: 'infinite',
-    animationName: skeletonFade,
+    // Disable the pulse under reduced-motion; the static placeholder still
+    // reads as loading (complex-20).
+    animationName: {
+      default: skeletonFade,
+      '@media (prefers-reduced-motion: reduce)': 'none',
+    },
     animationTimingFunction: 'steps(10, end)',
   },
 });
@@ -180,6 +185,11 @@ export function Skeleton({
   return (
     <div
       ref={ref}
+      // Purely decorative loading placeholder — hide from assistive tech so it
+      // isn't announced as empty content. The surrounding region should convey
+      // the loading/busy state (e.g. aria-busy) (complex-20). Consumers can
+      // override via props if a specific skeleton must be exposed.
+      aria-hidden="true"
       data-testid={testId}
       {...mergeProps(
         themeProps('skeleton'),