@astryxdesign/core 0.7.6-canary.f73623d → 0.7.6-canary.f77aaf2

package/src/Link/Link.tsx

@@ -43,7 +43,7 @@ import type {LinkComponentType} from './types';
 import {mergeProps} from '../utils';
 import {computeTargetAndRel} from './computeTargetAndRel';
 import {useInteractiveRole} from '../hooks/useInteractiveRole';
-import {themeProps} from '../utils/themeProps';
+import {themeDataAttributes, themeProps} from '../utils/themeProps';
 import {focusOutlineProps} from '../utils/focusOutline.stylex';
 import {interactionOverlayStyles} from '../utils/interactionOverlay.stylex';
 import {usePressFeedback} from '../hooks/usePressFeedback';
@@ -335,6 +335,10 @@ export function Link({
   const renderAsButton =
     role === 'button' || (role === 'inert' && href == null);
 
+  // The reflected theme attributes win over a caller's same-named `data-*`, so
+  // theme targeting always sees the real value (public-component-api INV5).
+  const reflectedAttributes = themeDataAttributes({color});
+
   const sharedContent = (
     <>
       <Text
@@ -385,6 +389,7 @@ export function Link({
           style,
         )}
         {...props}
+        {...reflectedAttributes}
         // Focusable while disabled (spec:AST-085 FR1), but inert (FR2).
         {...(isDisabled ? disabledInteractionProps(props.onKeyDown) : null)}>
         {sharedContent}
@@ -419,6 +424,7 @@ export function Link({
           style,
         )}
         {...props}
+        {...reflectedAttributes}
         {...disabledInteractionProps(props.onKeyDown)}>
         {sharedContent}
       </a>
@@ -450,7 +456,8 @@ export function Link({
           className,
           style,
         )}
-        {...props}>
+        {...props}
+        {...reflectedAttributes}>
         {sharedContent}
       </LinkComponent>
     );

package/src/Markdown/Markdown.tsx

@@ -1592,6 +1592,7 @@ function renderBlock(
       }
       try {
         const rendered = renderer.render({node: proposal.node});
+        // eslint-disable-next-line @astryx/no-nullish-jsx-guard -- a plugin renderer's '' is its output; only null, undefined or a boolean asks for the readable fallback
         if (rendered == null || typeof rendered === 'boolean') {
           return fallback;
         }

package/src/MetadataList/MetadataList.tsx

@@ -30,6 +30,7 @@ import {
 } from './MetadataListContext';
 import type {BaseProps} from '../BaseProps';
 import {mergeProps} from '../utils';
+import {isRenderable} from '../utils/isRenderable';
 import {themeProps} from '../utils/themeProps';
 import {useTranslator} from '../i18n';
 
@@ -238,8 +239,9 @@ export function MetadataList({
       ? childrenArray.slice(0, effectiveMax)
       : childrenArray;
 
-  const titleContent =
-    title != null ? <div {...stylex.props(styles.title)}>{title}</div> : null;
+  const titleContent = isRenderable(title) ? (
+    <div {...stylex.props(styles.title)}>{title}</div>
+  ) : null;
 
   // Determine grid style based on columns and label position
   const getGridStyle = () => {

package/src/MetadataList/MetadataListItem.tsx

@@ -27,6 +27,7 @@ import {
 import {MetadataListContext} from './MetadataListContext';
 import type {BaseProps} from '../BaseProps';
 import {mergeProps} from '../utils';
+import {isRenderable} from '../utils/isRenderable';
 import {themeProps} from '../utils/themeProps';
 
 // =============================================================================
@@ -153,7 +154,7 @@ export function MetadataListItem({
 
   const labelContent = (
     <>
-      {icon != null && (
+      {isRenderable(icon) && (
         <span {...stylex.props(styles.iconWrapper)}>{icon}</span>
       )}
       {label}

package/src/MultiSelector/MultiSelector.tsx

@@ -39,7 +39,6 @@ import {
   inputStatusBorderStyles,
   inputStatusHoverShadowStyles,
   inputWrapperStyles,
-  type FieldStatusVariant,
 } from '../Field';
 import {useKeepLayerOpenProps} from '../Layer/useLayer';
 import {InternalInputClearButton} from '../Field/InputClearButton';
@@ -77,10 +76,7 @@ import {useMultiCombobox} from './hooks';
 import {getInputARIA, isImeKeyEvent, mergeProps} from '../utils';
 import {joinAriaIDs} from '../utils/inputAria';
 import {devWarn, warnOnce} from '../utils/devWarning';
-import {
-  getInteractionModality,
-  useInteractionModalityTracking,
-} from '../utils/interactionModality';
+import {useInteractionModalityTracking} from '../utils/interactionModality';
 import {useAnnounce} from '../hooks/useAnnounce';
 import {FOCUSABLE_SELECTOR} from '../hooks/focusableSelector';
 import {useAnnounceRenderedText} from '../hooks/useAnnounceRenderedText';
@@ -110,6 +106,7 @@ import type {AdaptivePresentation} from '../hooks/useAdaptivePresentation';
 import {SelectorBottomSheet} from '../Selector/SelectorBottomSheet';
 import {useSelectorPresentation} from '../Selector/useSelectorPresentation';
 import {selectorPresentationStyles} from '../Selector/selectorPresentation.stylex';
+import type {FieldStatusPlacement} from '../Field/fieldStatusPlacement';
 
 // Sentinel value for the select-all item in keyboard navigation
 const SELECT_ALL_VALUE = '__xds_select_all__';
@@ -807,7 +804,7 @@ export interface MultiSelectorProps<
    * - 'tooltip': message is exposed from the on-field status icon
    * @default 'attached' for input selectors; 'detached' for secondary and ghost selectors
    */
-  statusVariant?: FieldStatusVariant;
+  statusVariant?: FieldStatusPlacement;
 
   /**
    * Width of the field. Numbers are treated as pixels, strings are used as-is
@@ -1192,7 +1189,17 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
   // Read by the live region above so it speaks what this element renders.
   const emptyStateRef = useRef<HTMLDivElement>(null);
   const triggerRef = useRef<HTMLElement>(null);
-  const triggerButtonRef = useMergedRefs<HTMLElement>(triggerRef, ref);
+  // A hover moves the highlight too, but the focus ring follows the shared
+  // interaction modality (architecture:interaction-modality INV1): it is read
+  // whenever a key or the pointer moves the highlight, so an action cell
+  // highlighted after pointer input keeps the hover treatment and no ring.
+  const triggerModality = useInteractionModalityTracking();
+  const readModality = triggerModality.readModality;
+  const triggerButtonRef = useMergedRefs<HTMLElement>(
+    triggerRef,
+    triggerModality.ref,
+    ref,
+  );
   const searchRef = useRef<HTMLInputElement>(null);
   const listboxRef = useRef<HTMLDivElement>(null);
 
@@ -1215,11 +1222,9 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
   // (spec:AST-086 FR8).
   useBusyAnnouncement(isBusy, t('@astryx.spinner.loading'), triggerRef);
 
-  // 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
-  // useMultiCombobox (onTriggerClick / onKeyDown).
+  // Disabled-reason tooltip listeners attach to the existing trigger container.
+  // The trigger stays focusable via aria-disabled. Trigger guards and the value
+  // commit guards below block activation, including from an already-open panel.
   const showsDisabledMessage = isDisabled && !!disabledMessage;
   const disabledMessageTooltip = useTooltip({
     placement: 'above',
@@ -1450,6 +1455,7 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
     onHide: handleLayerHide,
     onShow: handleLayerShow,
     triggerRef,
+    triggerModality,
     isFocusReturnAlways: hasExternalTrigger,
     popoverOptions: {
       hasLightDismiss: true,
@@ -1626,6 +1632,9 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
   // Clear all selected values. Shared by the clear button and the keyboard
   // Delete/Backspace path so clearing is reachable without a mouse.
   const clearValues = useCallback(() => {
+    if (isDisabled) {
+      return;
+    }
     onChange([]);
     announceSelection([]);
     if (changeAction) {
@@ -1635,6 +1644,7 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
       });
     }
   }, [
+    isDisabled,
     onChange,
     changeAction,
     startTransition,
@@ -1663,6 +1673,9 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
 
   const handleToggle = useCallback(
     (itemValue: string) => {
+      if (isDisabled) {
+        return;
+      }
       const newValue = optimisticValue.includes(itemValue)
         ? optimisticValue.filter(v => v !== itemValue)
         : [...optimisticValue, itemValue];
@@ -1677,6 +1690,7 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
       }
     },
     [
+      isDisabled,
       optimisticValue,
       onChange,
       changeAction,
@@ -1711,6 +1725,9 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
       : false;
 
   const handleSelectAll = useCallback(() => {
+    if (isDisabled) {
+      return;
+    }
     let newValue: string[];
     if (allEnabledSelected) {
       // Deselect all enabled items, keep disabled items that are selected
@@ -1736,6 +1753,7 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
       });
     }
   }, [
+    isDisabled,
     allEnabledSelected,
     enabledItems,
     optimisticValue,
@@ -1752,6 +1770,9 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
   // the option the caller adds is visible.
   const commitCreate = useCallback(
     (query: string) => {
+      if (isDisabled) {
+        return;
+      }
       const newValue = optimisticValue.includes(query)
         ? optimisticValue
         : [...optimisticValue, query];
@@ -1766,6 +1787,7 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
       }
     },
     [
+      isDisabled,
       optimisticValue,
       onChange,
       changeAction,
@@ -1836,27 +1858,22 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
     ),
   });
 
-  // A hover moves the highlight too, but the focus ring follows the shared
-  // interaction modality (architecture:interaction-modality INV1): it is read
-  // whenever a key or the pointer moves the highlight, so an action cell
-  // highlighted after pointer input keeps the hover treatment and no ring.
-  useInteractionModalityTracking();
   const [isKeyboardHighlight, setIsKeyboardHighlight] = useState(
-    () => getInteractionModality() === 'keyboard',
+    () => readModality() === 'keyboard',
   );
   const onKeyDown = useCallback(
     (event: React.KeyboardEvent<HTMLElement>) => {
       onComboboxKeyDown(event);
-      setIsKeyboardHighlight(getInteractionModality() === 'keyboard');
+      setIsKeyboardHighlight(readModality() === 'keyboard');
     },
-    [onComboboxKeyDown],
+    [onComboboxKeyDown, readModality],
   );
   const onItemMouseEnter = useCallback(
     (...args: Parameters<typeof onComboboxItemMouseEnter>) => {
       onComboboxItemMouseEnter(...args);
-      setIsKeyboardHighlight(getInteractionModality() === 'keyboard');
+      setIsKeyboardHighlight(readModality() === 'keyboard');
     },
-    [onComboboxItemMouseEnter],
+    [onComboboxItemMouseEnter, readModality],
   );
 
   // The trigger button owns its click so a consumer `onClick`, which lands on
@@ -2514,20 +2531,24 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
       ...(ariaLabelledByProp != null
         ? {'aria-labelledby': ariaLabelledByProp}
         : null),
-      ref: mergeRefs<HTMLElement>(el => {
-        popover.triggerRef(el);
-        triggerRef.current = el;
-        // A control that takes no focus has nowhere for focus to return to
-        // when the panel closes, and focus would land on the body — the
-        // person loses their place in the page. Making it programmatically
-        // focusable repairs the return without putting it in the tab order,
-        // which is the caller's decision to make. It does not make the
-        // control openable from the keyboard: only a real control does
-        // that, which is what the warning below is for.
-        if (el != null && !el.matches(FOCUSABLE_SELECTOR)) {
-          el.tabIndex = -1;
-        }
-      }, ref),
+      ref: mergeRefs<HTMLElement>(
+        el => {
+          popover.triggerRef(el);
+          triggerRef.current = el;
+          // A control that takes no focus has nowhere for focus to return to
+          // when the panel closes, and focus would land on the body — the
+          // person loses their place in the page. Making it programmatically
+          // focusable repairs the return without putting it in the tab order,
+          // which is the caller's decision to make. It does not make the
+          // control openable from the keyboard: only a real control does
+          // that, which is what the warning below is for.
+          if (el != null && !el.matches(FOCUSABLE_SELECTOR)) {
+            el.tabIndex = -1;
+          }
+        },
+        triggerModality.ref,
+        ref,
+      ),
       id: triggerId,
       onClick: isEffectivelyReadOnly
         ? onClick

package/src/MultiSelector/hooks.ts

@@ -18,6 +18,7 @@ import {useCallback, useRef, useState} from 'react';
 import {isRtlElement} from '../hooks/isRtlElement';
 import {useHighlightedOptionScroll} from '../hooks/useHighlightedOptionScroll';
 import type {MultiSelectorOptionData} from './types';
+import {findTypeaheadMatch} from '../utils/typeaheadMatch';
 
 interface UseMultiComboboxOptions {
   selectableItems: MultiSelectorOptionData[];
@@ -335,11 +336,12 @@ export function useMultiCombobox({
         default:
           // Typeahead only when search is not present
           if (!hasSearch && e.key.length === 1 && !e.ctrlKey && !e.metaKey) {
-            const newTypeahead = typeahead + e.key.toLowerCase();
-            const matchIndex = selectableItems.findIndex(
-              item =>
-                !item.disabled &&
-                item.label?.toLowerCase().startsWith(newTypeahead),
+            const newTypeahead = typeahead + e.key;
+            // INV17: the shared type-to-select fold, as Selector uses.
+            const matchIndex = findTypeaheadMatch(
+              selectableItems.flatMap((item, i) => (item.disabled ? [] : [i])),
+              i => selectableItems[i].label,
+              newTypeahead,
             );
             const didOpen = isOpen || matchIndex < 0 || onOpen() !== false;
             if (didOpen) {

package/src/NumberInput/NumberInput.tsx

@@ -24,12 +24,12 @@ import {
   useState,
   useMemo,
   useCallback,
-  useLayoutEffect,
   useRef,
   type FocusEvent,
   type KeyboardEvent,
   type ReactNode,
 } from 'react';
+import {flushSync} from 'react-dom';
 import * as stylex from '@stylexjs/stylex';
 import {
   colorVars,
@@ -47,7 +47,6 @@ import {
   inputStatusBorderStyles,
   inputStatusHoverShadowStyles,
   inputStatusFocusWithinStyles,
-  type FieldStatusVariant,
 } from '../Field';
 import {Icon, renderIconSlot, type IconType} from '../Icon';
 import {VisuallyHidden} from '../VisuallyHidden';
@@ -235,6 +234,7 @@ import {themeProps} from '../utils/themeProps';
 import {useTranslator, useLocale} from '../i18n';
 import {formatEditableNumber} from './numberParser';
 import {parseNumberInput, resolveNumberInputCommit} from './numberInputCommit';
+import type {FieldStatusPlacement} from '../Field/fieldStatusPlacement';
 
 interface NumberInputPropsBase extends Omit<
   FieldInputBaseProps,
@@ -324,7 +324,7 @@ interface NumberInputPropsBase extends Omit<
    * - 'tooltip': no message box; the status icon becomes a focusable info-tip button that reveals the message on hover, keyboard focus, or tap
    * @default 'attached'
    */
-  statusVariant?: FieldStatusVariant;
+  statusVariant?: FieldStatusPlacement;
   /**
    * The size of the input.
    * - 'sm': Compact size (28px height)
@@ -723,39 +723,32 @@ export function NumberInput({
   // `formatValue` the text at rest differs from the editable text, and putting
   // the editable text in the input after focus collapses that selection to the
   // end, so typing would append. When focus arrives with the text selected,
-  // select the swapped-in text too.
-  const reselectOnFocusRef = useRef(false);
-
+  // the focus handler commits the swap and selects the swapped-in text itself:
+  // the work one event causes stays in its handler
+  // (architecture:react-component-runtime/INV2).
   const handleFocus = useCallback(
     (e: FocusEvent<HTMLInputElement>) => {
       const input = e.currentTarget;
-      // Only when focusing swaps the text: otherwise no render follows to
-      // consume the flag, and the first keystroke would.
       const editableText =
         pendingInput ??
         (value == null ? '' : formatEditableNumber(value, locale));
-      reselectOnFocusRef.current =
+      const shouldReselect =
         input.value.length > 0 &&
         input.value !== editableText &&
         input.selectionStart === 0 &&
         input.selectionEnd === input.value.length;
       setIsFocused(true);
       onFocus?.(e);
+      if (shouldReselect) {
+        // Commit the swap now, so the editable text is in the input to select.
+        // eslint-disable-next-line @eslint-react/dom-no-flush-sync -- the editable text must be in the input before the focus event selects it
+        flushSync(() => {});
+        input.setSelectionRange(0, input.value.length);
+      }
     },
     [onFocus, pendingInput, value, locale],
   );
 
-  useLayoutEffect(() => {
-    if (!reselectOnFocusRef.current) {
-      return;
-    }
-    reselectOnFocusRef.current = false;
-    const input = inputRef.current;
-    if (input != null && input === document.activeElement) {
-      input.setSelectionRange(0, input.value.length);
-    }
-  }, [displayValue]);
-
   const commitPendingInput = useCallback(
     (trigger: 'blur' | 'Enter') => {
       if (pendingInput === null) {

package/src/OverflowList/OverflowList.tsx

@@ -27,6 +27,7 @@ import {
   useState,
 } from 'react';
 import type {BaseProps} from '../BaseProps';
+import {isRenderable} from '../utils/isRenderable';
 import type {SpacingStep} from '../utils/types';
 import * as stylex from '@stylexjs/stylex';
 import {mergeProps} from '../utils';
@@ -370,7 +371,7 @@ export function OverflowList({
         inert
         {...stylex.props(styles.measureContainer, gapStyles[gap])}>
         {childArray}
-        {measureIndicator != null && (
+        {isRenderable(measureIndicator) && (
           <div {...stylex.props(styles.measureIndicator)}>
             {measureIndicator}
           </div>

package/src/Pagination/Pagination.tsx

@@ -768,6 +768,7 @@ export function Pagination({
               {inputLabelText}
             </span>
             {inputNode}
+            {/* eslint-disable-next-line @astryx/no-nullish-jsx-guard -- `computedTotalPages` is a page count, not a slot */}
             {computedTotalPages != null && (
               <span
                 {...mergeProps(

package/src/Popover/Popover.tsx

@@ -49,7 +49,7 @@ import {useThemeDefinition} from '../theme/useTheme';
 import * as stylex from '@stylexjs/stylex';
 import {devWarn} from '../utils/devWarning';
 import type {BaseProps} from '../BaseProps';
-import {usePopover} from './usePopover';
+import {FALLBACK_CLOSE_SELECTOR, usePopover} from './usePopover';
 import {FOCUSABLE_SELECTOR} from '../hooks/focusableSelector';
 import type {LayerAlignment, LayerPlacement} from '../Layer/useLayer';
 import {layerAnimations} from '../Layer/layerAnimations.stylex';
@@ -645,7 +645,7 @@ export function Popover({
             // BottomSheet's scroll area is the panel's own child; content
             // sits inside it.
             element.parentElement !== sheetPanel &&
-            element.closest('[data-astryx-popover-fallback-close]') == null,
+            element.closest(FALLBACK_CLOSE_SELECTOR) == null,
         );
       if (target != null) {
         target.focus({preventScroll: true});

package/src/Popover/usePopover.tsx

@@ -5,7 +5,8 @@
 /**
  * @file usePopover.tsx
  * @input Uses useLayer, useFocusTrap, React hooks
- * @output Exports the public usePopover hook with derived focus and guarded opening.
+ * @output Exports the public usePopover hook with derived focus and guarded opening,
+ *   and FALLBACK_CLOSE_SELECTOR for Popover.tsx (internal).
  * @position Higher-level layer utility; used by DatePicker, Combobox, etc.
  *
  * Combines popover layer behavior with focus trap for dialog-like popovers.
@@ -39,7 +40,11 @@ import {paddingStyles} from '../Layout/padding.stylex';
 import type {SpacingStep} from '../utils/types';
 import {stableClassName} from '../naming';
 
-const FALLBACK_CLOSE_SELECTOR = '[data-astryx-popover-fallback-close]';
+/**
+ * The fallback close button's wrapper (anchored layer) or button (sheet,
+ * Popover.tsx); initial focus skips it.
+ */
+export const FALLBACK_CLOSE_SELECTOR = '[data-astryx-popover-fallback-close]';
 
 function attemptFocus(element: HTMLElement): boolean {
   try {

package/src/PowerSearch/PowerSearch.tsx

@@ -38,7 +38,7 @@ import {layerAnimations} from '../Layer/layerAnimations.stylex';
 import {Icon} from '../Icon';
 import type {IconType} from '../Icon';
 import type {IconName} from '../Icon/globalIconRegistry';
-import type {InputStatus, FieldStatusVariant} from '../Field';
+import type {InputStatus} from '../Field';
 import {usePopover} from '../Popover/usePopover';
 import {layerViewportInset} from '../Layer/layerViewportInset.stylex';
 import {useAnnounce} from '../hooks/useAnnounce';
@@ -77,6 +77,7 @@ import type {
 } from './types';
 
 import {useMergedRefs} from '../hooks/useMergedRefs';
+import type {FieldStatusPlacement} from '../Field/fieldStatusPlacement';
 // =============================================================================
 // Icon mapping for typeahead entries
 // =============================================================================
@@ -413,7 +414,7 @@ export interface PowerSearchProps extends Omit<
    * - 'detached': message floats below as a separate element with spacing
    * @default 'attached'
    */
-  statusVariant?: FieldStatusVariant;
+  statusVariant?: FieldStatusPlacement;
   /** Max width for dropdown menu. */
   menuWidth?: number;
   /** Max display length for filter token values. @default 40 */
@@ -1083,6 +1084,7 @@ export function PowerSearch({
   // Build combined endContent from resultCount + endContent props
   const combinedEndContent = useMemo((): React.ReactNode => {
     const resultCountNode =
+      // eslint-disable-next-line @astryx/no-nullish-jsx-guard -- `resultCountText` is a formatted string, not a slot
       resultCountText != null ? (
         <span {...stylex.props(resultCountStyles.text)}>{resultCountText}</span>
       ) : null;

package/src/RadioList/RadioList.tsx

@@ -16,6 +16,7 @@
  * - /packages/cli/assets/templates/blocks/components/RadioList/ (showcase blocks)
  */
 
+import {RadioListReasonContext} from './RadioListReasonContext';
 import {createLayerScopedContext as createContext} from '../Layer/layerScopedContext';
 import React, {
   useCallback,
@@ -246,7 +247,8 @@ export function RadioList({
   // controls swallow pointer events, so the tooltip listeners attach to the
   // radiogroup container and the radios stay perceivable via aria-disabled
   // instead of the disabled attribute. Selection is blocked in the item's
-  // onChange guard.
+  // onChange guard. The reason describes the radiogroup and each radio (see
+  // RadioListReasonContext).
   const showsDisabledMessage = isDisabled && !!disabledMessage;
   const disabledMessageTooltip = useTooltip({
     placement: 'above',
@@ -426,7 +428,16 @@ export function RadioList({
           controlClassName,
           controlStyle,
         )}>
-        <RadioListContext value={contextValue}>{children}</RadioListContext>
+        <RadioListContext value={contextValue}>
+          <RadioListReasonContext
+            value={
+              showsDisabledMessage
+                ? disabledMessageTooltip.describedBy
+                : undefined
+            }>
+            {children}
+          </RadioListReasonContext>
+        </RadioListContext>
       </div>
       {showsDisabledMessage &&
         disabledMessageTooltip.renderTooltip(disabledMessage)}

package/src/RadioList/RadioListItem.tsx

@@ -23,6 +23,8 @@ import * as stylex from '@stylexjs/stylex';
 import type {StyleXStyles} from '@stylexjs/stylex';
 import type {BaseProps} from '../BaseProps';
 import {RadioListContext} from './RadioList';
+import {RadioListReasonContext} from './RadioListReasonContext';
+import {joinAriaIDs} from '../utils/inputAria';
 import {colorVars, radiusVars} from '../theme/tokens.stylex';
 import {mergeProps, isRenderable, rtlStyles} from '../utils';
 import {indicatorScope} from '../Indicator/indicator.markers.stylex';
@@ -265,6 +267,7 @@ export function RadioListItem({
   // the touch press controller (pressableCoverage.test.ts).
   const pressable = usePressFeedback();
   const context = use(RadioListContext);
+  const disabledReasonID = use(RadioListReasonContext);
   if (!context) {
     throw new Error('RadioListItem must be used within an RadioList');
   }
@@ -351,7 +354,12 @@ export function RadioListItem({
         // exclusive — aria-labelledby would otherwise win over it.
         aria-label={ariaLabel}
         aria-labelledby={ariaLabel == null ? labelID : undefined}
-        aria-describedby={hasDescription ? descriptionID : undefined}
+        // The item's own description, then the group's disabled reason
+        // (RadioList's disabledMessage), which describes each radio (FR5).
+        aria-describedby={joinAriaIDs(
+          hasDescription ? descriptionID : undefined,
+          disabledReasonID,
+        )}
         {...stylex.props(
           styles.input,
           rtlStyles.centerInline('-50%'),

package/src/RadioList/RadioListReasonContext.ts

@@ -0,0 +1,25 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file RadioListReasonContext.ts
+ * @input Uses createLayerScopedContext
+ * @output Exports RadioListReasonContext (internal; not re-exported)
+ * @position Internal to RadioList; read by RadioListItem
+ *
+ * The id of a RadioList's disabled-reason tooltip while the group is disabled
+ * with a `disabledMessage`. The reason describes the radiogroup (FR1), and
+ * each radio adds it to its own `aria-describedby` (FR5): a screen reader
+ * announces a radio's description when the radio takes focus, which it does
+ * not reliably do for a description on the radiogroup.
+ */
+
+import {createLayerScopedContext} from '../Layer/layerScopedContext';
+
+// Layer-scoped like RadioListContext: content in a layer opened from inside the
+// group is not a radio of it.
+export const RadioListReasonContext = createLayerScopedContext<
+  string | undefined
+>(undefined);
+RadioListReasonContext.displayName = 'RadioListReasonContext';