@astryxdesign/core 0.1.2-canary.b753238 → 0.1.2-canary.bfcbf64

package/src/Button/Button.tsx

@@ -34,7 +34,6 @@ import {
 } from '../theme/tokens.stylex';
 import {Tooltip} from '../Tooltip/Tooltip';
 import {Spinner} from '../Spinner';
-import {VisuallyHidden} from '../VisuallyHidden';
 
 import {EDGE_COMP_ATTR} from '../Layout/edgeCompensation.stylex';
 import {useSize} from '../SizeContext/SizeContext';
@@ -125,6 +124,17 @@ const styles = stylex.create({
     textOverflow: 'ellipsis',
     minWidth: 0,
   },
+  visuallyHidden: {
+    position: 'absolute',
+    width: '1px',
+    height: '1px',
+    padding: 0,
+    margin: '-1px',
+    overflow: 'hidden',
+    clip: 'rect(0, 0, 0, 0)',
+    whiteSpace: 'nowrap',
+    borderWidth: 0,
+  },
   link: {
     textDecoration: 'none',
   },
@@ -680,9 +690,12 @@ export function Button({
         )}
       </span>
       {/* Live region for loading state announcements */}
-      <VisuallyHidden role="status" aria-live="polite">
+      <span
+        {...stylex.props(styles.visuallyHidden)}
+        role="status"
+        aria-live="polite">
         {isLoadingState ? 'Loading' : ''}
-      </VisuallyHidden>
+      </span>
     </>
   );
 

package/src/Calendar/Calendar.tsx

@@ -32,6 +32,7 @@ import {useGridFocus} from '../hooks';
 import {
   useCalendarDays,
   useCalendarConstraints,
+  useCalendarRovingTabindex,
   type CalendarDay,
 } from './hooks';
 import {
@@ -553,34 +554,14 @@ function MonthGrid({
     return null;
   }, [mode, value]);
 
-  // Seed the initial roving tab stop for this month. useGridFocus owns the
-  // live tab stop (see `hasRovingTabIndex` below) — it honors an existing
-  // `tabindex="0"` and repairs/moves it thereafter — so this only decides
-  // which day button starts tabbable. Priority: selected date (if visible and
-  // enabled) > today (if visible and enabled) > first enabled in-month day.
-  const seedTabbableIso = useMemo((): ISODateString | null => {
-    if (selectedDateForTabindex) {
-      const isSelectedInMonth =
-        selectedDateForTabindex.year === year &&
-        selectedDateForTabindex.month === month.month;
-      if (isSelectedInMonth && !isDateDisabled(selectedDateForTabindex)) {
-        return plainDateToISO(selectedDateForTabindex);
-      }
-    }
-
-    const isTodayInMonth = today.year === year && today.month === month.month;
-    if (isTodayInMonth && !isDateDisabled(today)) {
-      return plainDateToISO(today);
-    }
-
-    for (const day of days) {
-      if (!day.isOutside && !isDateDisabled(day.date)) {
-        return day.iso;
-      }
-    }
-
-    return null;
-  }, [days, today, year, month.month, isDateDisabled, selectedDateForTabindex]);
+  const {isTabbable} = useCalendarRovingTabindex({
+    days,
+    today,
+    year,
+    month: month.month,
+    isDateDisabled,
+    selectedDate: selectedDateForTabindex,
+  });
 
   // Helper to get the focused date from the currently focused element.
   // Reads the machine-readable `data-date` (ISO) attribute rather than parsing
@@ -647,22 +628,18 @@ function MonthGrid({
   // focus (the day button inside the cell). Arrow keys move to the target
   // row/column and, if that cell is disabled, continue in the same direction to
   // the next enabled cell.
-  const {
-    gridRef,
-    handleKeyDown: handleGridKeyDown,
-    handleFocus: handleGridFocus,
-  } = useGridFocus<HTMLDivElement>({
-    columns: 7,
-    cellSelector: '[role="gridcell"]',
-    isCellFocusable: cell =>
-      cell.querySelector('button:not([disabled])') !== null,
-    getFocusTarget: cell => cell.querySelector<HTMLElement>('button'),
-    hasRovingTabIndex: true,
-    onNavigateBefore: handleNavigatePrevious,
-    onNavigateAfter: handleNavigateNext,
-    onPageUp: handlePageUp,
-    onPageDown: handlePageDown,
-  });
+  const {gridRef, handleKeyDown: handleGridKeyDown} =
+    useGridFocus<HTMLDivElement>({
+      columns: 7,
+      cellSelector: '[role="gridcell"]',
+      isCellFocusable: cell =>
+        cell.querySelector('button:not([disabled])') !== null,
+      getFocusTarget: cell => cell.querySelector<HTMLElement>('button'),
+      onNavigateBefore: handleNavigatePrevious,
+      onNavigateAfter: handleNavigateNext,
+      onPageUp: handlePageUp,
+      onPageDown: handlePageDown,
+    });
 
   // Handle pending focus after month navigation
   useEffect(() => {
@@ -742,7 +719,6 @@ function MonthGrid({
         role="grid"
         aria-label={monthLabel}
         onKeyDown={handleGridKeyDown}
-        onFocus={handleGridFocus}
         {...stylex.props(
           monthGridStyles.daysGrid,
           hasWeekNumbers && monthGridStyles.daysGridWithNumbers,
@@ -798,7 +774,7 @@ function MonthGrid({
                   today={today}
                   hasOutsideDays={hasOutsideDays}
                   isDisabled={isDateDisabled(day.date)}
-                  isTabbable={day.iso === seedTabbableIso}
+                  isTabbable={isTabbable(day.iso)}
                   onDayClick={onDayClick}
                   onDayHover={onDayHover}
                 />
@@ -827,11 +803,6 @@ interface DayCellProps {
   today: PlainDate;
   hasOutsideDays: boolean;
   isDisabled: boolean;
-  /**
-   * Whether this day seeds the initial roving tab stop. useGridFocus
-   * (`hasRovingTabIndex`) owns the live tab stop thereafter — it honors an
-   * existing `tabindex="0"` and repairs/moves it on navigation and focus.
-   */
   isTabbable: boolean;
   onDayClick: (date: PlainDate) => void;
   onDayHover: (date: PlainDate | null) => void;
@@ -923,7 +894,6 @@ function DayCell({
         aria-selected={state.isSelected || state.isInRange || undefined}
         aria-disabled={state.effectivelyDisabled || undefined}
         disabled={isDisabled}
-        // Initial roving tab-stop seed; useGridFocus owns it after mount.
         tabIndex={isTabbableDay ? 0 : -1}
         onClick={() => !state.effectivelyDisabled && onDayClick(date)}
         onMouseEnter={() => !state.effectivelyDisabled && onDayHover(date)}

package/src/Calendar/hooks/index.ts

@@ -27,3 +27,9 @@ export type {
   UseCalendarNavigationOptions,
   UseCalendarNavigationReturn,
 } from './useCalendarNavigation';
+
+export {useCalendarRovingTabindex} from './useCalendarRovingTabindex';
+export type {
+  UseCalendarRovingTabindexOptions,
+  UseCalendarRovingTabindexReturn,
+} from './useCalendarRovingTabindex';

package/src/Calendar/hooks/useCalendarRovingTabindex.ts

@@ -0,0 +1,118 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file useCalendarRovingTabindex.ts
+ * @input Uses React useMemo, PlainDate utilities
+ * @output Exports useCalendarRovingTabindex hook for accessible grid navigation
+ * @position Calendar-specific hook; used by Calendar
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/Calendar/hooks/index.ts
+ */
+
+import {useMemo} from 'react';
+import type {ISODateString} from '../../utils/dateTypes';
+import {type PlainDate, plainDateToISO} from '../../utils/plainDate';
+import type {CalendarDay} from './useCalendarDays';
+
+/**
+ * Configuration for calendar roving tabindex
+ */
+export interface UseCalendarRovingTabindexOptions {
+  /** All days in the grid */
+  days: CalendarDay[];
+  /** Today's date as a PlainDate */
+  today: PlainDate;
+  /** The year being displayed */
+  year: number;
+  /** The month being displayed (1-based: 1 = January, 12 = December) */
+  month: number;
+  /** Function to check if a date is disabled */
+  isDateDisabled: (date: PlainDate) => boolean;
+  /** Currently selected date (if any) */
+  selectedDate?: PlainDate | null;
+}
+
+/**
+ * Return type for useCalendarRovingTabindex hook
+ */
+export interface UseCalendarRovingTabindexReturn {
+  /** The ISO date string of the tabbable element, or null */
+  tabbableDate: ISODateString | null;
+  /** Check if a specific date is the tabbable one */
+  isTabbable: (iso: ISODateString) => boolean;
+}
+
+/**
+ * Hook for managing roving tabindex in calendar grids.
+ *
+ * Implements the WAI-ARIA roving tabindex pattern where only one element
+ * in a group has tabindex="0" while others have tabindex="-1".
+ *
+ * Priority for tabbable element:
+ * 1. Today if visible in the current month and enabled
+ * 2. First enabled day in the month
+ *
+ * @example
+ * ```
+ * const {tabbableDate, isTabbable} = useCalendarRovingTabindex({
+ *   days,
+ *   today: {year: 2026, month: 1, day: 20},
+ *   year: 2026,
+ *   month: 1, // January (1-based)
+ *   isDateDisabled,
+ * });
+ *
+ * // In day rendering:
+ * <button tabIndex={isTabbable(day.iso) ? 0 : -1}>
+ *   {day.dayNumber}
+ * </button>
+ * ```
+ */
+export function useCalendarRovingTabindex(
+  options: UseCalendarRovingTabindexOptions,
+): UseCalendarRovingTabindexReturn {
+  const {days, today, year, month, isDateDisabled, selectedDate} = options;
+
+  // Determine which day should be tabbable
+  const tabbableDate = useMemo(() => {
+    // Priority 1: Selected date if visible in this month and enabled
+    if (selectedDate) {
+      const isSelectedInMonth =
+        selectedDate.year === year && selectedDate.month === month;
+      if (isSelectedInMonth && !isDateDisabled(selectedDate)) {
+        return plainDateToISO(selectedDate);
+      }
+    }
+
+    // Priority 2: Today if visible in this month and enabled
+    const isTodayInMonth = today.year === year && today.month === month;
+
+    if (isTodayInMonth && !isDateDisabled(today)) {
+      return plainDateToISO(today);
+    }
+
+    // Priority 3: First enabled day in this month
+    for (const day of days) {
+      if (!day.isOutside && !isDateDisabled(day.date)) {
+        return day.iso;
+      }
+    }
+
+    return null;
+  }, [days, today, year, month, isDateDisabled, selectedDate]);
+
+  // Check if a specific date is tabbable
+  const isTabbable = useMemo(() => {
+    return (iso: ISODateString): boolean => {
+      return tabbableDate !== null && iso === tabbableDate;
+    };
+  }, [tabbableDate]);
+
+  return {
+    tabbableDate,
+    isTabbable,
+  };
+}

package/src/Calendar/index.ts

@@ -26,6 +26,7 @@ export {
   useCalendarDays,
   useCalendarConstraints,
   useCalendarNavigation,
+  useCalendarRovingTabindex,
 } from './hooks';
 export type {
   CalendarDay,
@@ -35,6 +36,8 @@ export type {
   UseCalendarConstraintsReturn,
   UseCalendarNavigationOptions,
   UseCalendarNavigationReturn,
+  UseCalendarRovingTabindexOptions,
+  UseCalendarRovingTabindexReturn,
 } from './hooks';
 
 // Re-export calendar-specific utilities for advanced usage

package/src/CheckboxList/CheckboxList.tsx

@@ -151,7 +151,7 @@ export function CheckboxList({
   'data-testid': dataTestId,
 }: CheckboxListProps) {
   const inputID = useId();
-  const labelID = useId();
+  const labelElementID = useId();
   const descriptionID = useId();
   const statusMessageID = useId();
 
@@ -211,7 +211,7 @@ export function CheckboxList({
       isLabelHidden={isLabelHidden}
       description={description}
       inputID={inputID}
-      labelID={labelID}
+      labelElementID={labelElementID}
       isGroupLabel
       descriptionID={description ? descriptionID : undefined}
       isDisabled={isDisabled}
@@ -231,7 +231,7 @@ export function CheckboxList({
       <CheckboxListContext value={contextValue}>
         <div
           role="group"
-          aria-labelledby={labelID}
+          aria-labelledby={labelElementID}
           aria-describedby={
             [
               description ? descriptionID : null,

package/src/ContextMenu/ContextMenu.doc.mjs

@@ -58,6 +58,12 @@ export const docs = {
       description: 'Accessible name for the menu surface, announced when it opens.',
       default: "'Context menu'",
     },
+    {
+      name: 'hasAutoFocus',
+      type: 'boolean',
+      description: 'Whether to auto-focus the first menu item when the menu opens. Set to false for inline showcases.',
+      default: 'true',
+    },
     {
       name: 'isDisabled',
       type: 'boolean',

package/src/ContextMenu/ContextMenu.test.tsx

@@ -62,7 +62,9 @@ describe('ContextMenu', () => {
 
   it('typeahead focuses the matching menu item (menus-11)', () => {
     render(
-      <ContextMenu items={[{label: 'Cut'}, {label: 'Copy'}, {label: 'Paste'}]}>
+      <ContextMenu
+        items={[{label: 'Cut'}, {label: 'Copy'}, {label: 'Paste'}]}
+        hasAutoFocus={false}>
         <div>Right-click me</div>
       </ContextMenu>,
     );
@@ -119,7 +121,7 @@ describe('ContextMenu', () => {
 
   it('closes on Escape even when opened without auto-focus', () => {
     render(
-      <ContextMenu items={[{label: 'Item 1'}]}>
+      <ContextMenu items={[{label: 'Item 1'}]} hasAutoFocus={false}>
         <div>Right-click me</div>
       </ContextMenu>,
     );
@@ -133,7 +135,7 @@ describe('ContextMenu', () => {
 
   it('ignores Escape during IME composition', () => {
     render(
-      <ContextMenu items={[{label: 'Item 1'}]}>
+      <ContextMenu items={[{label: 'Item 1'}]} hasAutoFocus={false}>
         <div>Right-click me</div>
       </ContextMenu>,
     );
@@ -145,7 +147,7 @@ describe('ContextMenu', () => {
 
   it('restores focus to the trigger on close', () => {
     render(
-      <ContextMenu items={[{label: 'Item 1'}]}>
+      <ContextMenu items={[{label: 'Item 1'}]} hasAutoFocus={false}>
         <button type="button">Right-click me</button>
       </ContextMenu>,
     );

package/src/ContextMenu/ContextMenu.tsx

@@ -125,6 +125,12 @@ interface ContextMenuBaseProps extends BaseProps {
    * @default 'Context menu'
    */
   label?: string;
+  /**
+   * Whether to auto-focus the first menu item when the menu opens.
+   * Set to `false` for inline showcases or documentation previews.
+   * @default true
+   */
+  hasAutoFocus?: boolean;
   /** When true, right-click shows the native browser context menu instead. */
   isDisabled?: boolean;
   /** Called when the menu opens or closes. */
@@ -178,6 +184,7 @@ export function ContextMenu({
   menuWidth,
   size = 'md',
   label = 'Context menu',
+  hasAutoFocus = true,
   isDisabled = false,
   onOpenChange,
   ref,
@@ -275,9 +282,10 @@ export function ContextMenu({
   }, [isOpen, closeMenu, listRef]);
 
   // Dismiss on Escape from anywhere while open. The menu div's own onKeyDown
-  // only fires when focus is inside the menu; a document-level listener is
-  // kept as a reliable fallback Escape path (e.g. if focus has moved out of
-  // the menu). Guards against IME composition-cancel.
+  // only fires when focus is inside the menu, which never happens when the
+  // menu is opened with hasAutoFocus={false} (e.g. table context menus), so a
+  // document-level listener is required for a reliable Escape path. Guards
+  // against IME composition-cancel.
   useEffect(() => {
     if (!isOpen) {
       return;
@@ -342,9 +350,11 @@ export function ContextMenu({
           ? document.activeElement
           : (e.currentTarget as HTMLElement);
       layer.show();
-      requestAnimationFrame(() => focusFirst());
+      if (hasAutoFocus) {
+        requestAnimationFrame(() => focusFirst());
+      }
     },
-    [isDisabled, layer, focusFirst],
+    [isDisabled, layer, hasAutoFocus, focusFirst],
   );
 
   // Touch long-press invocation (menus-8). iOS Safari never synthesizes a
@@ -357,9 +367,11 @@ export function ContextMenu({
       (point: {x: number; y: number}) => {
         positionRef.current = {x: point.x, y: point.y};
         layer.show();
-        requestAnimationFrame(() => focusFirst());
+        if (hasAutoFocus) {
+          requestAnimationFrame(() => focusFirst());
+        }
       },
-      [layer, focusFirst],
+      [layer, hasAutoFocus, focusFirst],
     ),
   });
 

package/src/DropdownMenu/DropdownMenu.doc.mjs

@@ -61,7 +61,14 @@ export const docs = {
       type: 'boolean',
       description: 'Whether to show a chevron icon on the trigger button. Set to false for icon-only triggers.',
       default: 'true',
-    },    {
+    },
+    {
+      name: 'hasAutoFocus',
+      type: 'boolean',
+      description: 'Whether to auto-focus the first menu item when the menu opens. Set to false for inline showcases or documentation previews.',
+      default: 'true',
+    },
+    {
       name: 'children',
       type: '(item: DropdownMenuItemData) => ReactNode',
       description: 'Custom render function for each item in the list.',

package/src/DropdownMenu/DropdownMenu.test.tsx

@@ -249,6 +249,29 @@ describe('DropdownMenu controlled mode', () => {
   });
 });
 
+describe('DropdownMenu hasAutoFocus', () => {
+  it('does not focus menu items when hasAutoFocus is false and isMenuOpen is true', () => {
+    const focusSpy = vi.spyOn(HTMLElement.prototype, 'focus');
+    render(
+      <DropdownMenu
+        button={{label: 'Actions'}}
+        items={[{label: 'Edit'}, {label: 'Delete'}]}
+        isMenuOpen={true}
+        hasAutoFocus={false}
+        onOpenChange={() => {}}
+      />,
+    );
+
+    const menuItems = screen.getAllByRole('menuitem', {hidden: true});
+    const menuItemFocusCalls = focusSpy.mock.calls.filter((_, i) => {
+      const ctx = focusSpy.mock.contexts[i];
+      return menuItems.includes(ctx as HTMLElement);
+    });
+    expect(menuItemFocusCalls).toHaveLength(0);
+    focusSpy.mockRestore();
+  });
+});
+
 describe('DropdownMenu items', () => {
   it('renders items with labels', () => {
     render(

package/src/DropdownMenu/DropdownMenu.tsx

@@ -135,6 +135,13 @@ interface DropdownMenuBaseProps extends BaseProps {
    */
   placement?: LayerPlacement;
 
+  /**
+   * Whether to auto-focus the first menu item when the menu opens.
+   * Set to `false` for inline showcases or documentation previews
+   * where stealing focus is undesirable.
+   * @default true
+   */
+  hasAutoFocus?: boolean;
   'data-testid'?: string;
 }
 
@@ -186,6 +193,7 @@ export function DropdownMenu({
   onClick,
   hasChevron = true,
   placement = 'below',
+  hasAutoFocus = true,
   className,
   style,
   xstyle,
@@ -291,12 +299,14 @@ export function DropdownMenu({
     if (isControlled) {
       if (controlledIsOpen && !popover.isOpen) {
         popover.show();
-        requestAnimationFrame(() => focusFirst());
+        if (hasAutoFocus) {
+          requestAnimationFrame(() => focusFirst());
+        }
       } else if (!controlledIsOpen && popover.isOpen) {
         popover.hide();
       }
     }
-  }, [controlledIsOpen, isControlled, popover, focusFirst]);
+  }, [controlledIsOpen, isControlled, popover, hasAutoFocus, focusFirst]);
 
   // Extend useListFocus with Enter/Space activation + typeahead
   const listKeyDown = useCallback(
@@ -330,8 +340,10 @@ export function DropdownMenu({
 
   const openAndFocus = useCallback(() => {
     popover.show();
-    requestAnimationFrame(() => focusFirst());
-  }, [popover, focusFirst]);
+    if (hasAutoFocus) {
+      requestAnimationFrame(() => focusFirst());
+    }
+  }, [popover, hasAutoFocus, focusFirst]);
 
   const handleButtonClick = useCallback(() => {
     // If the menu was just closed by light dismiss (e.g. iOS Safari fires

package/src/Field/Field.test.tsx

@@ -109,7 +109,7 @@ describe('Field', () => {
       <Field
         label="Plan"
         inputID="plan-group"
-        labelID="plan-label"
+        labelElementID="plan-label"
         isGroupLabel>
         <div role="radiogroup" aria-labelledby="plan-label" />
       </Field>,
@@ -119,7 +119,7 @@ describe('Field', () => {
     expect(labelEl.tagName).toBe('SPAN');
     expect(labelEl.closest('label')).toBeNull();
     expect(labelEl).not.toHaveAttribute('for');
-    // labelID is applied to the label element and referenced by the group.
+    // labelElementID is applied to the label element and referenced by the group.
     expect(labelEl).toHaveAttribute('id', 'plan-label');
     const group = screen.getByRole('radiogroup', {name: 'Plan'});
     expect(group.getAttribute('aria-labelledby')).toBe(labelEl.id);

package/src/Field/Field.tsx

@@ -101,7 +101,7 @@ export interface FieldProps extends Omit<
   /**
    * ID of the input element this label points AT (used as the label's
    * `htmlFor`). This is the id of the *control*, not of the label element —
-   * see `labelID` for the latter.
+   * see `labelElementID` for the latter.
    */
   inputID: string;
   /**
@@ -110,12 +110,12 @@ export interface FieldProps extends Omit<
    * (radiogroup, checkbox group) references this via `aria-labelledby` to take
    * the label as its accessible name. Pair with `isGroupLabel`.
    */
-  labelID?: string;
+  labelElementID?: string;
   /**
    * When the field wraps a group of controls rather than a single input, set
    * this so the label renders as a non-`<label>` element (a `<span>`): a
    * `<label>` semantically names one control and can't be associated with a
-   * group. Pair with `labelID` + `aria-labelledby` on the group.
+   * group. Pair with `labelElementID` + `aria-labelledby` on the group.
    * @default false
    */
   isGroupLabel?: boolean;
@@ -189,7 +189,7 @@ export function Field({
   isLabelHidden = false,
   description,
   inputID,
-  labelID,
+  labelElementID,
   isGroupLabel = false,
   descriptionID,
   isOptional = false,
@@ -225,7 +225,7 @@ export function Field({
     <FieldLabel
       label={label}
       inputID={inputID}
-      labelID={labelID}
+      labelElementID={labelElementID}
       isGroupLabel={isGroupLabel}
       isLabelHidden={isLabelHidden}
       isDisabled={isDisabled}

package/src/Field/FieldLabel.tsx

@@ -84,7 +84,7 @@ export interface FieldLabelProps extends BaseProps<HTMLLabelElement> {
   /**
    * ID of the input element this label points AT (rendered as `htmlFor` on the
    * label). This is *not* the id of the label element itself — see
-   * `labelID` for that.
+   * `labelElementID` for that.
    */
   inputID: string;
   /**
@@ -93,14 +93,14 @@ export interface FieldLabelProps extends BaseProps<HTMLLabelElement> {
    * reference this via `aria-labelledby` to take the label as its accessible
    * name.
    */
-  labelID?: string;
+  labelElementID?: string;
   /**
    * When true, the field wraps a *group* of controls (e.g. a radiogroup)
    * rather than a single input. In that case the label is rendered as a
    * `<span>` instead of a `<label>` — a `<label>` semantically names one form
    * control and can't be associated with a group, so it must not be a literal
    * label element. The group takes the label as its name via
-   * `labelID` + `aria-labelledby`.
+   * `labelElementID` + `aria-labelledby`.
    * @default false
    */
   isGroupLabel?: boolean;
@@ -161,7 +161,7 @@ export interface FieldLabelProps extends BaseProps<HTMLLabelElement> {
 export function FieldLabel({
   label,
   inputID,
-  labelID,
+  labelElementID,
   isGroupLabel = false,
   isLabelHidden = false,
   isDisabled = false,
@@ -203,7 +203,7 @@ export function FieldLabel({
     <>
       <LabelElement
         ref={ref}
-        id={labelID}
+        id={labelElementID}
         // `htmlFor` only applies to a real `<label>` associating with a single
         // control; a group label (span) has no `htmlFor`.
         htmlFor={isGroupLabel ? undefined : inputID}