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

package/src/Selector/Selector.tsx

@@ -4,7 +4,7 @@
 
 /**
  * @file Selector.tsx
- * @input Uses React, StyleX, usePopover, Icon
+ * @input Uses React, StyleX, usePopover, useTooltip, Icon
  * @output Exports Selector component
  * @position Core implementation; consumed by index.ts
  *
@@ -27,6 +27,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 {
@@ -369,6 +370,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 +497,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 +548,7 @@ export function Selector<T extends SelectorOptionType>(
     isOptional = false,
     isRequired = false,
     isDisabled = false,
+    disabledMessage,
     options,
     value,
     onChange,
@@ -571,11 +591,26 @@ export function Selector<T extends SelectorOptionType>(
   const [optimisticValue, setOptimisticValue] = useOptimistic(normalizedValue);
   const isBusy = isLoading || optimisticValue !== normalizedValue;
 
+  // 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,
+  });
+
   // Build aria-describedby
   const ariaDescribedBy =
     [
       description ? descriptionId : null,
       status?.message ? statusMessageId : null,
+      showsDisabledMessage ? disabledMessageTooltip.describedBy : null,
     ]
       .filter(Boolean)
       .join(' ') || undefined;
@@ -622,6 +657,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 +691,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 +739,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 +775,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 +817,9 @@ export function Selector<T extends SelectorOptionType>(
     searchQuery,
     searchPlaceholder,
     onKeyDown,
+    popover.isOpen,
+    highlightedIndex,
+    getItemId,
   ]);
 
   // Render an individual item
@@ -812,9 +887,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) {
@@ -868,6 +941,10 @@ export function Selector<T extends SelectorOptionType>(
       <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}
@@ -892,13 +969,16 @@ export function Selector<T extends SelectorOptionType>(
           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
           }
@@ -906,9 +986,13 @@ export function Selector<T extends SelectorOptionType>(
           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 +1002,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 +1059,9 @@ export function Selector<T extends SelectorOptionType>(
           style: popoverOffsetStyle,
         },
       )}
+
+      {showsDisabledMessage &&
+        disabledMessageTooltip.renderTooltip(disabledMessage)}
     </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

@@ -577,6 +577,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/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.doc.mjs

@@ -33,7 +33,17 @@ export const docs = {
         'Index for staggered animation timing. For element at index n, animation starts at DELAY_TIME + (STAGGER_TIME × n).',
       default: '0',
     },
-  ],  theming: {
+  ],
+  playground: {
+    // Skeleton width/height default to '100%', which collapses to a zero-size
+    // (invisible) element in the properties-tab preview. Give the example
+    // explicit pixel dimensions so the shimmer placeholder is visible.
+    defaults: {
+      width: 320,
+      height: 80,
+    },
+  },
+  theming: {
     targets: [
       {className: 'astryx-skeleton'},
     ],

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

package/src/Slider/Slider.doc.mjs

@@ -11,6 +11,10 @@ export const docs = {
     defaults: {
       label: 'Volume',
       value: 50,
+      // Give the properties-tab preview a defined width so the track has room
+      // to render and stays draggable/interactive (the slider track grows to
+      // fill its container, which can collapse without an explicit width).
+      width: 300,
     },
   },
   props: [
@@ -91,6 +95,12 @@ export const docs = {
       description: 'Whether the slider is disabled.',
       default: 'false',
     },
+    {
+      name: 'disabledMessage',
+      type: 'string',
+      description:
+        'Explains why the slider is disabled. With isDisabled, shows a tooltip on hover/keyboard focus and keeps the thumb focusable via aria-disabled (value changes stay blocked). Use this instead of wrapping a disabled Slider in Tooltip — disabled controls swallow the hover events an external Tooltip needs.',
+    },
     {
       name: 'isOptional',
       type: 'boolean',
@@ -147,6 +157,7 @@ export const docs = {
       {guidance: true, description: 'Format values with meaningful units like "$50" or "75%" instead of raw numbers.'},
       {guidance: false, description: 'Use for precise numeric entry; pair with a text input or use NumberInput instead.'},
       {guidance: false, description: 'Set a step size so large that only a few positions are possible; use SegmentedControl or radio buttons instead.'},
+      {guidance: false, description: 'Wrap a disabled slider in Tooltip to explain why it is disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.'},
     ],
   },
 };
@@ -233,6 +244,12 @@ export const docsZh = {
       description: '是否禁用滑块。',
       default: 'false',
     },
+    {
+      name: 'disabledMessage',
+      type: 'string',
+      description:
+        'Explains why the slider is disabled. With isDisabled, shows a tooltip on hover/keyboard focus and keeps the thumb focusable via aria-disabled (value changes stay blocked). Use this instead of wrapping a disabled Slider in Tooltip — disabled controls swallow the hover events an external Tooltip needs.',
+    },
     {
       name: 'isOptional',
       type: 'boolean',
@@ -289,6 +306,7 @@ export const docsZh = {
       {guidance: true, description: 'Format values with meaningful units like "$50" or "75%" instead of raw numbers.'},
       {guidance: false, description: 'Use for precise numeric entry; pair with a text input or use NumberInput instead.'},
       {guidance: false, description: 'Set a step size so large that only a few positions are possible; use SegmentedControl or radio buttons instead.'},
+      {guidance: false, description: 'Wrap a disabled slider in Tooltip to explain why it is disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.'},
     ],
   },
 };
@@ -303,6 +321,7 @@ export const docsDense = {
       {guidance: true, description: 'Format values with meaningful units like "$50" or "75%" instead of raw numbers.'},
       {guidance: false, description: 'Use for precise numeric entry; pair with a text input or use NumberInput instead.'},
       {guidance: false, description: 'Set a step size so large that only a few positions are possible; use SegmentedControl or radio buttons instead.'},
+      {guidance: false, description: 'Wrap a disabled slider in Tooltip to explain why it is disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.'},
     ],
   },
   propDescriptions: {