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

package/dist/hooks/useKeyboardHint.js

@@ -0,0 +1,220 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file useKeyboardHint.tsx
+ * @input Uses React, StyleX, Kbd, useLayer
+ * @output Exports useKeyboardHint hook — ephemeral arrow-key navigation hint
+ * @position Core hook; shows sighted keyboard users how to navigate composite
+ *   widgets that use roving tabindex (single Tab stop, arrows inside)
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/hooks/index.ts
+ * - /packages/core/src/hooks/useKeyboardHint.doc.mjs
+ * - /apps/storybook/stories/useKeyboardHint.stories.tsx
+ * - /packages/cli/templates/blocks/components/Hooks/useKeyboardHintHookUsage.tsx
+ */
+import React, { useCallback, useEffect, useRef } from 'react';
+import * as stylex from '@stylexjs/stylex';
+import "../theme/tokens.stylex.js";
+import { colorVars, radiusVars, shadowVars, spacingVars, typeScaleVars } from "../theme/tokens.stylex.js";
+import { Kbd } from "../Kbd/index.js";
+import { useLayer } from "../Layer/useLayer.js";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// ---------------------------------------------------------------------------
+// Styles
+// ---------------------------------------------------------------------------
+
+const ARROW_KEYS = new Set(['ArrowLeft', 'ArrowRight', 'ArrowUp', 'ArrowDown']);
+const ARROW_HINT_KEYS = {
+  horizontal: ['left', 'right'],
+  vertical: ['up', 'down'],
+  both: ['left', 'right', 'up', 'down']
+};
+const styles = {
+  hint: {
+    kVAEAm: "xixxii4",
+    kpwlN0: "x1anvkwx",
+    kogj98: "x1ghz6dp",
+    kWkggS: "x1prclbq",
+    kaIpWk: "xh6dtrn",
+    kGVxlE: "x1i5ehqx",
+    kLKAdn: "xfsso4q",
+    kGO01o: "xy143xn",
+    kZCmMZ: "x12gdq22",
+    kwRFfy: "x1djylfy",
+    kGuDYH: "x141an7d",
+    kLWn49: "x1ltkj2j",
+    kMwMTN: "xv1l7n4",
+    khDVqt: "xuxw1ft",
+    kSiTet: "xg01cxk xofkqq2",
+    k1ekBW: "xsm4mo9",
+    kIyJzY: "xx6bhzk",
+    kzIqYQ: "xd00j3c",
+    kfzvcC: "x47corl",
+    $$css: true
+  }
+};
+
+// ---------------------------------------------------------------------------
+// Hook
+// ---------------------------------------------------------------------------
+
+/**
+ * Shows an ephemeral visual hint ("← → to navigate") anchored to the focused
+ * item when a composite widget first receives keyboard focus. Teaches sighted
+ * keyboard users that arrows navigate within the group.
+ *
+ * The hint renders in the top layer (popover="manual") and is CSS-anchor-
+ * positioned to the currently focused element, so it is never clipped by
+ * overflow containers. It auto-dismisses on first arrow press, timeout, or
+ * blur, and does not re-show for that instance.
+ *
+ * @example
+ * ```
+ * const hint = useKeyboardHint({orientation: 'horizontal'});
+ * <div role="toolbar" onFocus={hint.onFocus} onBlur={hint.onBlur} onKeyDown={hint.onKeyDown}>
+ *   {children}
+ *   {hint.hintElement}
+ * </div>
+ * ```
+ */
+export function useKeyboardHint(options = {}) {
+  const {
+    orientation = 'horizontal',
+    dismissAfterMs = 3000,
+    isEnabled = true
+  } = options;
+  const timeoutRef = useRef(null);
+  const dismissedRef = useRef(false);
+  const isVisibleRef = useRef(false);
+  const layerAnchorRef = useRef(() => {});
+  const clearDismissTimeout = useCallback(() => {
+    if (timeoutRef.current) {
+      clearTimeout(timeoutRef.current);
+      timeoutRef.current = null;
+    }
+  }, []);
+  const handleLayerShow = useCallback(() => {
+    isVisibleRef.current = true;
+  }, []);
+  const handleLayerHide = useCallback(() => {
+    isVisibleRef.current = false;
+    clearDismissTimeout();
+    layerAnchorRef.current(null);
+  }, [clearDismissTimeout]);
+  const layer = useLayer({
+    mode: 'context',
+    onShow: handleLayerShow,
+    onHide: handleLayerHide
+  });
+  layerAnchorRef.current = layer.ref;
+
+  // Hide + mark dismissed (won't re-show for this instance)
+  const dismiss = useCallback(() => {
+    dismissedRef.current = true;
+    clearDismissTimeout();
+    layer.hide();
+    isVisibleRef.current = false;
+    layerAnchorRef.current(null);
+  }, [clearDismissTimeout, layer]);
+
+  // Show the layer anchored to the focused element
+  const show = useCallback(anchor => {
+    if (dismissedRef.current || !isEnabled) {
+      return;
+    }
+    layerAnchorRef.current(anchor);
+    layer.show();
+    clearDismissTimeout();
+    timeoutRef.current = setTimeout(() => {
+      dismiss();
+    }, dismissAfterMs);
+  }, [clearDismissTimeout, dismiss, dismissAfterMs, isEnabled, layer]);
+
+  // Cleanup on unmount
+  useEffect(() => () => {
+    clearDismissTimeout();
+    layerAnchorRef.current(null);
+  }, [clearDismissTimeout]);
+
+  // --- Handlers ---
+
+  const onFocus = useCallback(e => {
+    if (dismissedRef.current || !isEnabled) {
+      return;
+    }
+    // Only show on keyboard focus (focus-visible)
+    const target = e.target;
+    if (!target.matches(':focus-visible')) {
+      return;
+    }
+    // Only show when focus enters from outside the container
+    const container = e.currentTarget;
+    if (e.relatedTarget instanceof Node && container.contains(e.relatedTarget)) {
+      return;
+    }
+    show(target);
+  }, [show, isEnabled]);
+  const onBlur = useCallback(e => {
+    if (!isVisibleRef.current) {
+      return;
+    }
+    const container = e.currentTarget;
+    // Only dismiss when focus leaves the container entirely
+    if (e.relatedTarget instanceof Node && container.contains(e.relatedTarget)) {
+      // Focus moved within — re-anchor to the new target
+      if (!dismissedRef.current && e.relatedTarget instanceof HTMLElement) {
+        layerAnchorRef.current(e.relatedTarget);
+      }
+      return;
+    }
+    dismiss();
+  }, [dismiss]);
+  const onKeyDown = useCallback(e => {
+    if (!isVisibleRef.current) {
+      return;
+    }
+    if (ARROW_KEYS.has(e.key)) {
+      dismiss();
+    }
+  }, [dismiss]);
+
+  // --- Render the hint element ---
+
+  const arrowContent = /*#__PURE__*/_jsx("span", {
+    ...{
+      className: "x3nfvp2 x6s0dn4 xzye2dw"
+    },
+    children: ARROW_HINT_KEYS[orientation].map(key => /*#__PURE__*/_jsx(Kbd, {
+      keys: key
+    }, key))
+  });
+  const hintElement = layer.render(/*#__PURE__*/_jsxs("span", {
+    "aria-hidden": "true",
+    children: [arrowContent, /*#__PURE__*/_jsx("span", {
+      ...{
+        className: "x11g1kdw"
+      },
+      children: "to navigate"
+    })]
+  }), {
+    placement: 'below',
+    alignment: 'start',
+    xstyle: styles.hint,
+    style: {
+      marginBlockStart: spacingVars['--spacing-2']
+    }
+  });
+  return {
+    hintElement,
+    onFocus,
+    onBlur,
+    onKeyDown
+  };
+}

package/dist/hooks/useTreeFocus.d.ts

@@ -83,6 +83,24 @@ export interface UseTreeFocusOptions {
      * TreeList uses this to move its single roving tab stop.
      */
     onActiveChange?: (id: string | undefined) => void;
+    /**
+     * Roving-tabindex ownership. When true, the hook manages a single tab stop
+     * across the visible treeitems: exactly one enabled treeitem carries
+     * `tabindex="0"` and the rest `tabindex="-1"`. The tab stop is repaired on
+     * mount and whenever items mount/unmount or toggle disabled, and moves with
+     * keyboard navigation. Attach the returned {@link UseTreeFocusReturn.handleFocus}
+     * to the container's `onFocus` to keep the stop in sync after clicks or
+     * programmatic focus.
+     *
+     * On mount the hook preserves an existing `tabindex="0"` treeitem (so a
+     * consumer can seed the active item in its render); if none exists it
+     * promotes the first enabled treeitem.
+     *
+     * When false (the default), the hook only *moves* focus (`.focus()`) and
+     * never touches `tabindex` — the caller owns tab-stop management.
+     * @default false
+     */
+    hasRovingTabIndex?: boolean;
 }
 /**
  * Return type for useTreeFocus hook.
@@ -92,6 +110,12 @@ export interface UseTreeFocusReturn<T extends HTMLElement = HTMLElement> {
     treeRef: React.RefObject<T | null>;
     /** Key down handler to attach to the tree container. */
     handleKeyDown: (e: React.KeyboardEvent) => void;
+    /**
+     * Focus handler to attach to the container's `onFocus`. Keeps the roving tab
+     * stop in sync when `hasRovingTabIndex` is enabled; a no-op otherwise, so it
+     * is always safe to attach.
+     */
+    handleFocus: (e: React.FocusEvent) => void;
     /** Focus the first enabled visible treeitem. */
     focusFirst: () => void;
     /** Focus the last enabled visible treeitem. */
@@ -119,12 +143,12 @@ export interface UseTreeFocusReturn<T extends HTMLElement = HTMLElement> {
  *
  * @example
  * ```
- * const {treeRef, handleKeyDown} = useTreeFocus<HTMLUListElement>({
+ * const {treeRef, handleKeyDown, handleFocus} = useTreeFocus<HTMLUListElement>({
  *   onToggleExpand: id => toggle(id),
- *   onActiveChange: id => setActiveId(id),
+ *   hasRovingTabIndex: true,
  * });
  *
- * <ul ref={treeRef} role="tree" onKeyDown={handleKeyDown}>
+ * <ul ref={treeRef} role="tree" onKeyDown={handleKeyDown} onFocus={handleFocus}>
  *   {items.map(item => <li role="treeitem" tabIndex={-1}>{item.label}</li>)}
  * </ul>
  * ```

package/dist/hooks/useTreeFocus.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useTreeFocus.d.ts","sourceRoot":"","sources":["../../src/hooks/useTreeFocus.ts"],"names":[],"mappings":"AAiCA;;;;;;;;;GASG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB;;;;;;OAMG;IACH,cAAc,CAAC,EAAE,CAAC,IAAI,EAAE,WAAW,KAAK,OAAO,CAAC;IAEhD;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,WAAW,KAAK,MAAM,CAAC;IAEzC;;;;;OAKG;IACH,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,WAAW,KAAK,OAAO,CAAC;IAE5C;;;;OAIG;IACH,WAAW,CAAC,EAAE,CAAC,IAAI,EAAE,WAAW,KAAK,OAAO,CAAC;IAE7C;;;;;OAKG;IACH,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,WAAW,KAAK,MAAM,GAAG,SAAS,CAAC;IAEtD;;;;OAIG;IACH,cAAc,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAC;IAEtC;;;;;;;;;OASG;IACH,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,WAAW,EAAE,EAAE,EAAE,MAAM,GAAG,SAAS,KAAK,OAAO,GAAG,SAAS,CAAC;IAEhF;;;;OAIG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IAEpB,gEAAgE;IAChE,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAE1B;;;OAGG;IACH,cAAc,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,GAAG,SAAS,KAAK,IAAI,CAAC;CACnD;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB,CAAC,CAAC,SAAS,WAAW,GAAG,WAAW;IACrE,iEAAiE;IACjE,OAAO,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IAEnC,wDAAwD;IACxD,aAAa,EAAE,CAAC,CAAC,EAAE,KAAK,CAAC,aAAa,KAAK,IAAI,CAAC;IAEhD,gDAAgD;IAChD,UAAU,EAAE,MAAM,IAAI,CAAC;IAEvB,+CAA+C;IAC/C,SAAS,EAAE,MAAM,IAAI,CAAC;CACvB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,WAAW,GAAG,WAAW,EAC9D,OAAO,GAAE,mBAAwB,GAChC,kBAAkB,CAAC,CAAC,CAAC,CA0RvB"}
+{"version":3,"file":"useTreeFocus.d.ts","sourceRoot":"","sources":["../../src/hooks/useTreeFocus.ts"],"names":[],"mappings":"AAkCA;;;;;;;;;GASG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB;;;;;;OAMG;IACH,cAAc,CAAC,EAAE,CAAC,IAAI,EAAE,WAAW,KAAK,OAAO,CAAC;IAEhD;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,WAAW,KAAK,MAAM,CAAC;IAEzC;;;;;OAKG;IACH,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,WAAW,KAAK,OAAO,CAAC;IAE5C;;;;OAIG;IACH,WAAW,CAAC,EAAE,CAAC,IAAI,EAAE,WAAW,KAAK,OAAO,CAAC;IAE7C;;;;;OAKG;IACH,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,WAAW,KAAK,MAAM,GAAG,SAAS,CAAC;IAEtD;;;;OAIG;IACH,cAAc,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAC;IAEtC;;;;;;;;;OASG;IACH,UAAU,CAAC,EAAE,CACX,IAAI,EAAE,WAAW,EACjB,EAAE,EAAE,MAAM,GAAG,SAAS,KACnB,OAAO,GAAG,SAAS,CAAC;IAEzB;;;;OAIG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IAEpB,gEAAgE;IAChE,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAE1B;;;OAGG;IACH,cAAc,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,GAAG,SAAS,KAAK,IAAI,CAAC;IAElD;;;;;;;;;;;;;;;;OAgBG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB,CAAC,CAAC,SAAS,WAAW,GAAG,WAAW;IACrE,iEAAiE;IACjE,OAAO,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IAEnC,wDAAwD;IACxD,aAAa,EAAE,CAAC,CAAC,EAAE,KAAK,CAAC,aAAa,KAAK,IAAI,CAAC;IAEhD;;;;OAIG;IACH,WAAW,EAAE,CAAC,CAAC,EAAE,KAAK,CAAC,UAAU,KAAK,IAAI,CAAC;IAE3C,gDAAgD;IAChD,UAAU,EAAE,MAAM,IAAI,CAAC;IAEvB,+CAA+C;IAC/C,SAAS,EAAE,MAAM,IAAI,CAAC;CACvB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,WAAW,GAAG,WAAW,EAC9D,OAAO,GAAE,mBAAwB,GAChC,kBAAkB,CAAC,CAAC,CAAC,CA2VvB"}

package/dist/hooks/useTreeFocus.js

@@ -4,7 +4,7 @@
 
 /**
  * @file useTreeFocus.ts
- * @input Uses React useCallback, useRef
+ * @input Uses React useCallback, useRef, useIsomorphicLayoutEffect
  * @output Exports useTreeFocus hook for WAI-ARIA tree keyboard navigation
  * @position Core hook; used by TreeList for roving tabindex + APG tree keyboard model
  *
@@ -14,6 +14,7 @@
  * - /packages/core/src/hooks/useTreeFocus.test.tsx
  */
 import { useCallback, useRef } from 'react';
+import { useIsomorphicLayoutEffect } from "./useIsomorphicLayoutEffect.js";
 
 /** Keys handled by the tree keyboard model (used to gate typeahead). */
 const NAVIGATION_KEYS = new Set(['ArrowDown', 'ArrowUp', 'ArrowRight', 'ArrowLeft', 'Home', 'End', 'Enter', ' ']);
@@ -58,12 +59,12 @@ const DEFAULT_TYPEAHEAD_RESET_MS = 500;
  *
  * @example
  * ```
- * const {treeRef, handleKeyDown} = useTreeFocus<HTMLUListElement>({
+ * const {treeRef, handleKeyDown, handleFocus} = useTreeFocus<HTMLUListElement>({
  *   onToggleExpand: id => toggle(id),
- *   onActiveChange: id => setActiveId(id),
+ *   hasRovingTabIndex: true,
  * });
  *
- * <ul ref={treeRef} role="tree" onKeyDown={handleKeyDown}>
+ * <ul ref={treeRef} role="tree" onKeyDown={handleKeyDown} onFocus={handleFocus}>
  *   {items.map(item => <li role="treeitem" tabIndex={-1}>{item.label}</li>)}
  * </ul>
  * ```
@@ -80,7 +81,8 @@ export function useTreeFocus(options = {}) {
     onActivate,
     typeahead = true,
     typeaheadResetMs = DEFAULT_TYPEAHEAD_RESET_MS,
-    onActiveChange
+    onActiveChange,
+    hasRovingTabIndex = false
   } = options;
   const treeRef = useRef(null);
   const typeaheadRef = useRef({
@@ -102,14 +104,63 @@ export function useTreeFocus(options = {}) {
   const collapsedOf = useCallback(el => isCollapsed ? isCollapsed(el) : el.getAttribute('aria-expanded') === 'false', [isCollapsed]);
   const idOf = useCallback(el => getItemId ? getItemId(el) : el.dataset.treeId, [getItemId]);
 
+  // --- Roving tabindex ownership (opt-in via `hasRovingTabIndex`) -------------
+
+  /**
+   * Set `tabindex` on a treeitem, but only when it differs (avoids redundant
+   * DOM writes).
+   */
+  const setTabIndex = useCallback((el, value) => {
+    if (el.getAttribute('tabindex') !== String(value)) {
+      el.setAttribute('tabindex', String(value));
+    }
+  }, []);
+
+  /**
+   * Make `target` the sole tabbable treeitem: 0 on it, -1 on every other
+   * visible treeitem.
+   */
+  const moveTabStop = useCallback((items, target) => {
+    for (const el of items) {
+      setTabIndex(el, el === target ? 0 : -1);
+    }
+  }, [setTabIndex]);
+
+  /**
+   * Repair the roving tab stop: exactly one enabled treeitem is tabbable (0),
+   * the rest are -1. Prefer an existing `tabindex="0"` treeitem (so a consumer
+   * can seed the active item in its render); otherwise promote the first
+   * enabled treeitem.
+   */
+  const syncTabStops = useCallback(() => {
+    const items = getItems();
+    const enabled = items.filter(el => !itemDisabled(el));
+    if (enabled.length === 0) {
+      return;
+    }
+    const current = enabled.find(el => el.getAttribute('tabindex') === '0');
+    moveTabStop(items, current ?? enabled[0]);
+  }, [getItems, itemDisabled, moveTabStop]);
+
+  // Keep the tab stop valid across renders (items added/removed, disabled
+  // toggled). Runs after every commit but only when roving tabindex is on.
+  useIsomorphicLayoutEffect(() => {
+    if (hasRovingTabIndex) {
+      syncTabStops();
+    }
+  });
+
   /** Move focus to a treeitem and notify the active-change listener. */
   const focusItem = useCallback(el => {
     if (el == null) {
       return;
     }
+    if (hasRovingTabIndex) {
+      moveTabStop(getItems(), el);
+    }
     onActiveChange?.(idOf(el));
     el.focus();
-  }, [idOf, onActiveChange]);
+  }, [idOf, onActiveChange, hasRovingTabIndex, moveTabStop, getItems]);
 
   /**
    * Focus the first enabled treeitem from `start`, moving by `dir`. No wrap —
@@ -265,9 +316,21 @@ export function useTreeFocus(options = {}) {
         break;
     }
   }, [getItems, typeahead, runTypeahead, focusEnabledFrom, focusItem, collapsedOf, expandedOf, idOf, levelOf, itemDisabled, onToggleExpand, onActivate]);
+
+  /**
+   * Keep the roving stop pointing at whatever ended up focused (e.g. a click
+   * or programmatic focus) so the next Tab behaves correctly. No-op unless
+   * roving tabindex is enabled.
+   */
+  const handleFocus = useCallback(() => {
+    if (hasRovingTabIndex) {
+      syncTabStops();
+    }
+  }, [hasRovingTabIndex, syncTabStops]);
   return {
     treeRef,
     handleKeyDown,
+    handleFocus,
     focusFirst,
     focusLast
   };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astryxdesign/core",
-  "version": "0.1.2-canary.bfcbf64",
+  "version": "0.1.2-canary.c395fca",
   "displayName": "XDS Core",
   "description": "The component library. Accessible, themeable React components with built-in spacing, dark mode, and StyleX styling.",
   "author": "Meta Open Source",

package/src/Breadcrumbs/BreadcrumbItem.tsx

@@ -179,6 +179,7 @@ export function BreadcrumbItem({
   className,
   style,
   'data-testid': testId,
+  ...rest
 }: BreadcrumbItemProps) {
   const ctx = use(BreadcrumbContext);
   const LinkComponent = useLinkComponent(as);
@@ -252,7 +253,8 @@ export function BreadcrumbItem({
           className,
           style,
         )}
-        data-testid={testId}>
+        data-testid={testId}
+        {...rest}>
         <span aria-hidden="true" {...stylex.props(itemStyles.separator)}>
           {ctx.separator}
         </span>
@@ -286,7 +288,8 @@ export function BreadcrumbItem({
         className,
         style,
       )}
-      data-testid={testId}>
+      data-testid={testId}
+      {...rest}>
       <span aria-hidden="true" {...stylex.props(itemStyles.separator)}>
         {ctx.separator}
       </span>

package/src/Button/Button.tsx

@@ -34,6 +34,7 @@ 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';
@@ -124,17 +125,6 @@ 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',
   },
@@ -690,12 +680,9 @@ export function Button({
         )}
       </span>
       {/* Live region for loading state announcements */}
-      <span
-        {...stylex.props(styles.visuallyHidden)}
-        role="status"
-        aria-live="polite">
+      <VisuallyHidden role="status" aria-live="polite">
         {isLoadingState ? 'Loading' : ''}
-      </span>
+      </VisuallyHidden>
     </>
   );
 

package/src/Calendar/Calendar.tsx

@@ -32,7 +32,6 @@ import {useGridFocus} from '../hooks';
 import {
   useCalendarDays,
   useCalendarConstraints,
-  useCalendarRovingTabindex,
   type CalendarDay,
 } from './hooks';
 import {
@@ -554,14 +553,34 @@ function MonthGrid({
     return null;
   }, [mode, value]);
 
-  const {isTabbable} = useCalendarRovingTabindex({
-    days,
-    today,
-    year,
-    month: month.month,
-    isDateDisabled,
-    selectedDate: selectedDateForTabindex,
-  });
+  // 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]);
 
   // Helper to get the focused date from the currently focused element.
   // Reads the machine-readable `data-date` (ISO) attribute rather than parsing
@@ -628,18 +647,22 @@ 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} =
-    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,
-    });
+  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,
+  });
 
   // Handle pending focus after month navigation
   useEffect(() => {
@@ -719,6 +742,7 @@ function MonthGrid({
         role="grid"
         aria-label={monthLabel}
         onKeyDown={handleGridKeyDown}
+        onFocus={handleGridFocus}
         {...stylex.props(
           monthGridStyles.daysGrid,
           hasWeekNumbers && monthGridStyles.daysGridWithNumbers,
@@ -774,7 +798,7 @@ function MonthGrid({
                   today={today}
                   hasOutsideDays={hasOutsideDays}
                   isDisabled={isDateDisabled(day.date)}
-                  isTabbable={isTabbable(day.iso)}
+                  isTabbable={day.iso === seedTabbableIso}
                   onDayClick={onDayClick}
                   onDayHover={onDayHover}
                 />
@@ -803,6 +827,11 @@ 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;
@@ -894,6 +923,7 @@ 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,9 +27,3 @@ export type {
   UseCalendarNavigationOptions,
   UseCalendarNavigationReturn,
 } from './useCalendarNavigation';
-
-export {useCalendarRovingTabindex} from './useCalendarRovingTabindex';
-export type {
-  UseCalendarRovingTabindexOptions,
-  UseCalendarRovingTabindexReturn,
-} from './useCalendarRovingTabindex';

package/src/Calendar/index.ts

@@ -26,7 +26,6 @@ export {
   useCalendarDays,
   useCalendarConstraints,
   useCalendarNavigation,
-  useCalendarRovingTabindex,
 } from './hooks';
 export type {
   CalendarDay,
@@ -36,8 +35,6 @@ 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 labelElementID = useId();
+  const labelID = useId();
   const descriptionID = useId();
   const statusMessageID = useId();
 
@@ -211,7 +211,7 @@ export function CheckboxList({
       isLabelHidden={isLabelHidden}
       description={description}
       inputID={inputID}
-      labelElementID={labelElementID}
+      labelID={labelID}
       isGroupLabel
       descriptionID={description ? descriptionID : undefined}
       isDisabled={isDisabled}
@@ -231,7 +231,7 @@ export function CheckboxList({
       <CheckboxListContext value={contextValue}>
         <div
           role="group"
-          aria-labelledby={labelElementID}
+          aria-labelledby={labelID}
           aria-describedby={
             [
               description ? descriptionID : null,

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