@astryxdesign/core 0.7.5 → 0.7.6-canary.0bd3b37

package/src/Tokenizer/Tokenizer.tsx

@@ -27,6 +27,7 @@
 import React, {
   lazy,
   Suspense,
+  use,
   useCallback,
   useEffect,
   useId,
@@ -51,6 +52,7 @@ import {
   useFieldInputStyling,
 } from '../Field/fieldParts';
 import {useMergedRefs} from '../hooks/useMergedRefs';
+import {TokenizerClearAllMessageContext} from './TokenizerClearAllMessageContext';
 import {useBusyAnnouncement} from '../hooks/useBusyAnnouncement';
 import {useAdaptivePresentation} from '../hooks/useAdaptivePresentation';
 import {useIsHydrating} from '../hooks/useIsHydrating';
@@ -85,9 +87,12 @@ import {
 } from '../theme/tokens.stylex';
 import type {SearchableItem, SearchSource} from '../Typeahead/types';
 import {composeEventHandlers, mergeProps} from '../utils';
+import {joinAriaIDs} from '../utils/inputAria';
+import {isFocusDetached} from '../utils/focusReturn';
 import {themeProps} from '../utils/themeProps';
 import {useTranslator} from '../i18n';
 import type {TokenizerBottomSheetProps} from './TokenizerBottomSheet';
+import {useResolvedRequired} from '../hooks/useResolvedRequired';
 
 // Re-export status types for convenience
 export type {
@@ -754,8 +759,10 @@ export function Tokenizer<T extends SearchableItem>({
   experimental,
   id: idProp,
   'aria-describedby': ariaDescribedByProp,
+  'aria-labelledby': ariaLabelledByProp,
   ...restProps
 }: TokenizerWithPresentationProps<T>): React.JSX.Element {
+  const isEffectivelyRequired = useResolvedRequired({isRequired, isOptional});
   const {rest, container} = useFieldInputStyling('Tokenizer', restProps, {
     containerXstyle,
     containerClassName,
@@ -768,8 +775,15 @@ export function Tokenizer<T extends SearchableItem>({
   const size = useSize(sizeProp, 'md');
   const generatedInputId = useId();
   const inputId = idProp ?? generatedInputId;
+  const fieldLabelId = useId();
   const descriptionId = useId();
   const statusMessageId = useId();
+  // A caller aria-labelledby names the input together with the field's own
+  // label, which it would otherwise replace.
+  const fieldLabelledBy =
+    ariaLabelledByProp != null
+      ? joinAriaIDs(fieldLabelId, ariaLabelledByProp)
+      : undefined;
   const inputRef = useRef<HTMLInputElement>(null);
   const wrapperRef = useRef<HTMLDivElement>(null);
 
@@ -810,14 +824,6 @@ export function Tokenizer<T extends SearchableItem>({
     },
     [onChangeQuery],
   );
-  // Whether the field's control — the inline input or the trigger — holds
-  // focus. Kept in a ref by the focus and blur handlers of both, because a
-  // control unmounted while focused fires no blur: when a presentation swap
-  // removes the focused control (the latch releasing into the popover, or
-  // `adaptive` changing while the sheet is closed), the new presentation's
-  // control takes the focus over once it has mounted, so focus never lands on
-  // the page body (`component:Tokenizer` FR16, `spec:AST-085` FR4).
-  const isControlFocusedRef = useRef(false);
   // Set around a focus move the field makes itself — a presentation swap
   // handing focus from one control to the other — so the receiving control
   // does not report it as focus entering from outside.
@@ -828,38 +834,33 @@ export function Tokenizer<T extends SearchableItem>({
   // entry, and the one focus the trigger then gets — BottomSheet's return
   // focus — is the entry to report.
   const hasReportedFocusRef = useRef(false);
-  // A control can hold focus without the field having seen a focus event:
-  // the inline input server-rendered with `autofocus` (`hasAutoFocus`) is
-  // focused before hydration, and the swap to the trigger in the first
-  // render after it removes that input. React detaches the old control
-  // before any effect of the swapping commit runs, so the live focus is
-  // read during that render, while the control is still in the document —
-  // a read of `document.activeElement` only, with no update made in render.
-  const previousPresentationRef = useRef(isSheetPresentation);
-  if (previousPresentationRef.current !== isSheetPresentation) {
-    previousPresentationRef.current = isSheetPresentation;
-    if (typeof document !== 'undefined') {
-      const active = document.activeElement;
-      if (
-        active != null &&
-        (active === inputRef.current || active === triggerRef.current)
-      ) {
-        isControlFocusedRef.current = true;
-      }
-    }
-  }
-  useEffect(() => {
-    if (!isControlFocusedRef.current) {
+  // When a presentation swap removes the focused control (the latch
+  // releasing into the popover, or `adaptive` changing while the sheet is
+  // closed), the new presentation's control takes the focus over, so focus
+  // never lands on the page body (`component:Tokenizer` FR16, `spec:AST-085`
+  // FR4). Both controls' callback refs own the hand-off
+  // (`architecture:react-component-runtime` INV6): the detaching control
+  // notes that it held focus — it is still in the document then, so this also
+  // covers a control focused before hydration (`hasAutoFocus`), which no focus
+  // event reported — and the attaching control takes it.
+  const isFocusPendingHandOffRef = useRef(false);
+  const handOffFocusRef = useCallback((node: HTMLElement | null) => {
+    if (node == null) {
       return;
     }
-    const active = document.activeElement;
-    if (active != null && active !== document.body) {
-      return;
+    const takesFocus = isFocusPendingHandOffRef.current;
+    isFocusPendingHandOffRef.current = false;
+    if (takesFocus && isFocusDetached(node.ownerDocument)) {
+      isHandingOffFocusRef.current = true;
+      node.focus();
+      isHandingOffFocusRef.current = false;
     }
-    isHandingOffFocusRef.current = true;
-    (isSheetPresentation ? triggerRef.current : inputRef.current)?.focus();
-    isHandingOffFocusRef.current = false;
-  }, [isSheetPresentation]);
+    return () => {
+      if (node.ownerDocument.activeElement === node) {
+        isFocusPendingHandOffRef.current = true;
+      }
+    };
+  }, []);
   // The trigger's accessible description names the selected tokens: the
   // button's children are tokens whose own content assistive technology
   // leaves out of a button's name (`spec:AST-020` FR1).
@@ -934,6 +935,29 @@ export function Tokenizer<T extends SearchableItem>({
     focusTrigger: 'always',
     isEnabled: showsDisabledMessage,
   });
+  // The inline field's wrapper holds every control a swap removes with the
+  // input — a token's Remove button, the inline Clear all — so it notes focus
+  // anywhere inside it for the hand-off above. It also anchors the
+  // disabled-message tooltip, whose handlers are gated internally by
+  // isEnabled, so attaching unconditionally is safe.
+  const tooltipAnchorRef = disabledMessageTooltip.ref;
+  const wrapperCallbackRef = useCallback(
+    (el: HTMLDivElement | null) => {
+      wrapperRef.current = el;
+      tooltipAnchorRef(el);
+      if (el == null) {
+        return;
+      }
+      return () => {
+        if (el.contains(el.ownerDocument.activeElement)) {
+          isFocusPendingHandOffRef.current = true;
+        }
+        wrapperRef.current = null;
+        tooltipAnchorRef(null);
+      };
+    },
+    [tooltipAnchorRef],
+  );
 
   // The sheet presentation has no input; the public ref reaches the trigger,
   // the control it stands for (`family:input-fields` FR10).
@@ -941,6 +965,7 @@ export function Tokenizer<T extends SearchableItem>({
     triggerRef,
     ref as React.Ref<HTMLButtonElement> | undefined,
     disabledMessageTooltip.ref,
+    handOffFocusRef,
   );
 
   useImperativeHandle(handleRef, () => ({
@@ -1021,7 +1046,6 @@ export function Tokenizer<T extends SearchableItem>({
         layer.show();
       }
       if (comingFromOutside) {
-        isControlFocusedRef.current = true;
         if (!isHandingOffFocusRef.current) {
           hasReportedFocusRef.current = true;
           onFocus?.(e);
@@ -1039,8 +1063,9 @@ export function Tokenizer<T extends SearchableItem>({
   const handleBlurCapture = useCallback(
     (e: React.FocusEvent) => {
       if (!isFocusInTokenizer(e.relatedTarget)) {
-        isControlFocusedRef.current = false;
         hasReportedFocusRef.current = false;
+        // Focus left the field: no hand-off is owed any more.
+        isFocusPendingHandOffRef.current = false;
         setIsFocusedWithin(false);
         onBlur?.(e);
         if (isLayerMode) {
@@ -1111,12 +1136,12 @@ export function Tokenizer<T extends SearchableItem>({
       return [
         {
           id: `${CREATABLE_ID_PREFIX}${trimmed}`,
-          label: `Create "${trimmed}"`,
+          label: t('@astryx.tokenizer.create', {value: trimmed}),
           auxiliaryData: {__createdValue: trimmed},
         } as unknown as T,
       ];
     },
-    [hasCreate, selectedIds, selectedLabels],
+    [hasCreate, selectedIds, selectedLabels, t],
   );
 
   const emptySource: SearchSource<T> = useMemo(
@@ -1214,15 +1239,27 @@ export function Tokenizer<T extends SearchableItem>({
   );
 
   // Handle clearing all items
-  const handleClearAll = useCallback(() => {
-    if (isDisabled || value.length === 0) {
-      return;
-    }
-    // Report the last item as removed (convention)
-    const lastItem = value[value.length - 1];
-    onChange([], {item: lastItem, type: 'remove'});
-    inputRef.current?.focus();
-  }, [value, onChange, isDisabled]);
+  // A composing component that words its own Clear all (PowerSearch) provides
+  // its words; otherwise the field's own (component:Tokenizer AR7).
+  const clearAllMessage =
+    use(TokenizerClearAllMessageContext) ?? t('@astryx.tokenizer.allRemoved');
+  const handleClearAll = useCallback(
+    (options?: {silent?: boolean}) => {
+      if (isDisabled || value.length === 0) {
+        return;
+      }
+      // Report the last item as removed (convention)
+      const lastItem = value[value.length - 1];
+      onChange([], {item: lastItem, type: 'remove'});
+      // Focus moves to the input, so the emptied selection is announced, in
+      // the sheet's words (WCAG 4.1.3). The sheet announces its own Clear all.
+      if (!options?.silent) {
+        announce(clearAllMessage);
+      }
+      inputRef.current?.focus();
+    },
+    [value, onChange, isDisabled, announce, clearAllMessage],
+  );
 
   // Handle backspace on empty input — remove last token
   const handleKeyDown = useCallback(
@@ -1302,13 +1339,7 @@ export function Tokenizer<T extends SearchableItem>({
 
   const wrapperContent = (
     <div
-      ref={el => {
-        wrapperRef.current = el;
-        // Anchor + hover/focus listeners for the disabled-message tooltip.
-        // Handlers are gated internally by isEnabled, so attaching
-        // unconditionally is safe.
-        disabledMessageTooltip.ref(el);
-      }}
+      ref={wrapperCallbackRef}
       role="group"
       aria-label={label}
       onClick={handleWrapperClick}
@@ -1374,6 +1405,7 @@ export function Tokenizer<T extends SearchableItem>({
               // With `experimental`, the ref type admits the trigger too; in
               // this presentation it receives the input.
               ref as React.Ref<HTMLInputElement> | undefined,
+              handOffFocusRef,
             )}
             searchSource={isAtMax ? emptySource : filteredSource}
             value={null}
@@ -1391,12 +1423,21 @@ export function Tokenizer<T extends SearchableItem>({
             isFocusableDisabled={showsDisabledMessage}
             hasAutoFocus={hasAutoFocus}
             inputId={inputId}
+            ariaLabelledBy={fieldLabelledBy}
             ariaDescribedBy={
               [ariaDescribedByProp, ariaDescribedBy]
                 .filter(Boolean)
                 .join(' ') || undefined
             }
             onChangeQuery={onChangeQuery}
+            // The resolved required state reaches the combobox, also when a
+            // FormLayout default hides the visible marker (component:FormLayout
+            // FR5, AR2).
+            aria-required={isEffectivelyRequired || rest['aria-required']}
+            // An error status is exposed on the combobox as on every other field
+            // (WCAG 4.1.2; spec:AST-020 FR9). Without one, a caller's own
+            // aria-required / aria-invalid still applies.
+            aria-invalid={status?.type === 'error' || rest['aria-invalid']}
             __queryEntries={createEntries}
             debounceMs={debounceMs}
             onKeyDown={handleKeyDown}
@@ -1457,6 +1498,7 @@ export function Tokenizer<T extends SearchableItem>({
           ref={triggerMergedRef}
           type="button"
           id={inputId}
+          aria-labelledby={fieldLabelledBy}
           aria-haspopup="dialog"
           aria-expanded={isSheetOpen}
           aria-disabled={isDisabled || undefined}
@@ -1498,7 +1540,6 @@ export function Tokenizer<T extends SearchableItem>({
               React.MouseEventHandler<HTMLButtonElement> | undefined,
           )}
           onFocus={event => {
-            isControlFocusedRef.current = true;
             // BottomSheet focuses the trigger only after its exit completes;
             // that focus is the signal that the retained sheet can leave. If
             // the resolution moved to the popover meanwhile, the inline input
@@ -1527,8 +1568,8 @@ export function Tokenizer<T extends SearchableItem>({
             if (isSheetOpen) {
               return;
             }
-            isControlFocusedRef.current = false;
             hasReportedFocusRef.current = false;
+            isFocusPendingHandOffRef.current = false;
             onBlur?.(event);
           }}
           onKeyDown={onKeyDown}
@@ -1625,7 +1666,7 @@ export function Tokenizer<T extends SearchableItem>({
               emptySearchText={emptySearchText}
               onAdd={handleAdd}
               onRemove={handleRemove}
-              onClearAll={handleClearAll}
+              onClearAll={() => handleClearAll({silent: true})}
               onChangeQuery={handleSheetQueryChange}
             />
           )}
@@ -1707,6 +1748,7 @@ export function Tokenizer<T extends SearchableItem>({
       isLabelHidden={isLabelHidden}
       description={description}
       inputID={inputId}
+      labelID={ariaLabelledByProp != null ? fieldLabelId : undefined}
       descriptionID={description ? descriptionId : undefined}
       isOptional={isOptional}
       isRequired={isRequired}

package/src/Tokenizer/TokenizerBottomSheet.tsx

@@ -35,21 +35,22 @@ import {
   type ReactNode,
   type RefObject,
 } from 'react';
+import {flushSync} from 'react-dom';
 import * as stylex from '@stylexjs/stylex';
 import {AlertDialog} from '../AlertDialog/AlertDialog';
 import {BottomSheet} from '../BottomSheet/BottomSheet';
 import {Button} from '../Button/Button';
 import {EmptyState} from '../EmptyState/EmptyState';
 import {PanelSearchInput} from '../Field/PanelSearchInput';
-import {Icon} from '../Icon';
+import {Icon} from '../Icon/Icon';
 import {CheckboxIndicator} from '../Indicator/CheckboxIndicator';
-import {Spinner} from '../Spinner';
+import {Spinner} from '../Spinner/Spinner';
 import {useBusyAnnouncement} from '../hooks/useBusyAnnouncement';
 import {useIsomorphicLayoutEffect} from '../hooks/useIsomorphicLayoutEffect';
 import {useAnnounce} from '../hooks/useAnnounce';
 import {useAnnounceRenderedText} from '../hooks/useAnnounceRenderedText';
 import {Text} from '../Text/Text';
-import {useTranslator} from '../i18n';
+import {useTranslator} from '../i18n/useTranslator';
 import {warnOnce} from '../utils/devWarning';
 import type {SearchableItem, SearchSource} from '../Typeahead/types';
 import {colorVars, radiusVars, spacingVars} from '../theme/tokens.stylex';
@@ -328,8 +329,9 @@ function TokenizerSheetContent<T extends SearchableItem>({
   // trigger's press — so an open sheet with no confirmation pending carries
   // no closed dialog (`architecture:component-style-authoring` INV7). Dialog
   // has an entrance animation and no exit, so a close is its unmount; the
-  // sheet then places focus itself, in the Effect below, once the modal is
-  // gone and the sheet's content can take focus again: on the search field
+  // close handler commits that unmount at once and then places focus itself,
+  // now that the modal is gone and the sheet's content can take focus again
+  // (`architecture:react-component-runtime` INV2): on the search field
   // after a confirmed clear — the clear is spent, and the search field is
   // where the next selection starts (FR24, `spec:AST-085` FR4) — and back on
   // Clear all after a cancel. A confirmed clear is announced there too — a
@@ -341,25 +343,17 @@ function TokenizerSheetContent<T extends SearchableItem>({
   // dialog, so FR14 routes the words into it while the sheet is open.
   const [isClearConfirmationOpen, setIsClearConfirmationOpen] = useState(false);
   const clearAllRef = useRef<HTMLButtonElement>(null);
-  const afterConfirmationRef = useRef<'search' | 'clear-all' | null>(null);
   const announce = useAnnounce();
   const closeClearConfirmation = (confirmed: boolean) => {
-    afterConfirmationRef.current = confirmed ? 'search' : 'clear-all';
-    setIsClearConfirmationOpen(false);
-  };
-  useEffect(() => {
-    if (isClearConfirmationOpen || afterConfirmationRef.current == null) {
-      return;
-    }
-    const destination = afterConfirmationRef.current;
-    afterConfirmationRef.current = null;
-    if (destination === 'search') {
+    // eslint-disable-next-line @eslint-react/dom-no-flush-sync -- the confirmation must be gone before focus moves into the sheet and the words are routed into it
+    flushSync(() => setIsClearConfirmationOpen(false));
+    if (confirmed) {
       searchRef.current?.focus();
       announce(t('@astryx.tokenizer.allRemoved'));
     } else {
       clearAllRef.current?.focus();
     }
-  }, [announce, isClearConfirmationOpen, t]);
+  };
   const selectedIds = useMemo(() => new Set(value.map(v => v.id)), [value]);
 
   // ---- sheet session ----

package/src/Tokenizer/TokenizerClearAllMessageContext.ts

@@ -0,0 +1,21 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file TokenizerClearAllMessageContext.ts
+ * @input None
+ * @output A context carrying the words a composing component announces for
+ *   the field's Clear all
+ * @position Internal to Core: not exported from the Tokenizer barrel. A
+ *   component that composes Tokenizer and words its own Clear all (PowerSearch:
+ *   "All filters removed") provides it; Tokenizer otherwise announces its own
+ *   words (component:Tokenizer AR7).
+ */
+
+import {createContext} from 'react';
+
+export const TokenizerClearAllMessageContext = createContext<string | null>(
+  null,
+);
+TokenizerClearAllMessageContext.displayName = 'TokenizerClearAllMessageContext';

package/src/Toolbar/Toolbar.spec.md

@@ -80,10 +80,9 @@ Consumer migration instructions belong in consumer docs and release notes.
   that does not hold the stop, the stop stays on the earlier control, so
   Shift+Tab from the clicked control lands on that earlier control inside the
   toolbar before leaving it.
-- **Links and some fields keep their own tab stops.** A link (such as a Button
-  with `href`), `textarea`, or `select` in the row is outside the roving stop:
-  it keeps its own tab stop and the arrow keys skip it. The APG toolbar pattern
-  makes the toolbar a single tab stop.
+- **Some fields keep their own tab stops.** A `textarea` or `select` in the
+  row is outside the roving stop: it keeps its own tab stop and the arrow keys
+  skip it. The APG toolbar pattern makes the toolbar a single tab stop.
 
 ## Ownership boundary
 
@@ -115,7 +114,7 @@ owns the shared structural-region boundary.
 | FR1 | The render contains Section-owned Outer chrome around one Toolbar carrying `role="toolbar"`, `aria-label` from `label`, `aria-orientation`, and the `toolbar` target with `size`. Caller `role`, `aria-label`, and `aria-orientation` are dropped; other DOM props reach the toolbar row; `ref`, `className`, `style`, and `xstyle` reach the Section.                                                                                                                                                                                                                                                                                                                                                                                                    | Current source, docs, tests, and family       |
 | FR2 | Without center content the Toolbar is a flex line of the present start and end lanes, a row when horizontal and a column of lanes when vertical; with center content it is a three-lane grid whose lanes sit side by side in either orientation. Each lane lays its controls out in a row. No lane clips its content, and the center lane can shrink below its content width. `gap` spaces controls within and between lanes.                                                                                                                                                                                                                                                                                                                             | Current source and focused structure tests    |
 | FR3 | Variant (default `transparent`), selected divider edges, and block padding by size remain delegated to Section, while Toolbar retains toolbar semantics, keyboard behavior, and internal layout.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | Current source, docs, and family contract     |
-| FR4 | The row MUST be a single tab stop. ArrowRight and ArrowLeft (horizontal) or ArrowDown and ArrowUp (vertical) move focus between its controls, wrapping at the ends and skipping disabled controls; Home and End move to the first and last. Implementation gap: only buttons, inputs, and elements with `tabindex` share the stop, so links, `textarea`, and `select` keep their own tab stops, and a pointer click does not move the stop (Current-state impact). Arrows do not move focus out of a text input whose caret is mid-line, and inside an open composed menu arrow keys belong to the menu. The toolbar keeps its tab stop after a composed menu is dismissed from outside, and keeps its own arrow movement when rendered inside a popover. | APG toolbar pattern; current source and tests |
+| FR4 | The row MUST be a single tab stop. ArrowRight and ArrowLeft (horizontal) or ArrowDown and ArrowUp (vertical) move focus between its controls, wrapping at the ends and skipping disabled controls; Home and End move to the first and last. Implementation gap: only buttons, inputs, links, and elements with `tabindex` share the stop, so `textarea` and `select` carry their own tab stops, and a pointer click does not move the stop (Current-state impact). Arrows do not move focus out of a text input whose caret is mid-line, and inside an open composed menu arrow keys belong to the menu. The toolbar keeps its tab stop after a composed menu is dismissed from outside, and keeps its own arrow movement when rendered inside a popover. | APG toolbar pattern; current source and tests |
 | FR5 | Caller `onKeyDown`, `onFocus`, and `onBlur` run first; when the caller cancels the event, the built-in handling is skipped.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | Current source and tests                      |
 | FR6 | Keyboard focus entering the row can show a brief, self-dismissing hint for its arrow-key axis.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | Current source                                |
 | FR7 | `size` (default `md`) is provided to descendant controls as their default size; Toolbar starts its own size scope and does not inherit an outer size provider (`architecture:component-size-cascade` INV7).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | Current source and tests                      |
@@ -204,7 +203,7 @@ Read from source, with no focused test yet:
 - FR2: the flex and grid layouts themselves, and `gap` spacing.
 - FR3: divider edges.
 - FR5: caller `onFocus` and `onBlur` running first and their cancellation.
-- FR4: links, `textarea`, and `select` keeping their own tab stops, and the stop
+- FR4: `textarea` and `select` keeping their own tab stops, and the stop
   staying put after a pointer click.
 - FR6.
 - FR7: descendant controls taking `size` as their default, and the fresh size

package/src/Toolbar/Toolbar.tsx

@@ -248,7 +248,8 @@ export function Toolbar({
   const gapVar = spacingVars[spacingStepToVar[gap]] as string;
 
   const {listRef, handleKeyDown, handleFocus} = useListFocus<HTMLDivElement>({
-    itemSelector: 'button, input, [tabindex]',
+    // `a[href]` catches a Button rendered with `href`.
+    itemSelector: 'button, input, a[href], [tabindex]',
     boundarySelector: '[role="toolbar"], [popover]',
     orientation,
     hasRovingTabIndex: true,

package/src/TopNav/TopNavMegaMenu.tsx

@@ -378,6 +378,7 @@ export function TopNavMegaMenu({
   if (renderMode === 'drawer') {
     return (
       <DrawerMegaMenu
+        ref={ref}
         label={label}
         items={items}
         featured={featured}
@@ -564,6 +565,7 @@ function DefaultMegaMenu({
 // =============================================================================
 
 function DrawerMegaMenu({
+  ref,
   label,
   items,
   featured,
@@ -572,7 +574,7 @@ function DrawerMegaMenu({
   style,
   onClick: onClickProp,
   ...rest
-}: Pick<TopNavMegaMenuProps, 'label' | 'items' | 'featured'> &
+}: Pick<TopNavMegaMenuProps, 'ref' | 'label' | 'items' | 'featured'> &
   BaseProps<HTMLButtonElement>) {
   const [isExpanded, setIsExpanded] = useState(false);
   const pressable = usePressFeedback();
@@ -582,6 +584,7 @@ function DrawerMegaMenu({
     <div {...stylex.props(styles.drawerSection)}>
       {/* Header toggle — same pattern as TopNavMenu drawer */}
       <button
+        ref={ref}
         type="button"
         {...rest}
         onClick={composeEventHandlers(onClickProp, () =>

package/src/TopNav/TopNavMenu.tsx

@@ -477,6 +477,7 @@ export function TopNavMenu({
     return (
       <div {...stylex.props(drawerStyles.section)}>
         <button
+          ref={ref}
           type="button"
           {...rest}
           onMouseEnter={onMouseEnterProp}

package/src/TreeList/TreeListItem.tsx

@@ -32,7 +32,8 @@ import {
   useClickableContainer,
 } from '../hooks/useClickableContainer';
 import {Icon} from '../Icon';
-import {mergeProps} from '../utils';
+import {mergeProps} from '../utils/mergeProps';
+import {useFocusAcrossSwap} from '../utils/useFocusAcrossSwap';
 import {useLinkComponent} from '../Link/useLinkComponent';
 import {TreeListBranches} from './TreeListBranches';
 import type {TreeListDensity, TreeListVariant} from './TreeListTypes';
@@ -379,6 +380,9 @@ export interface TreeListItemInternalProps {
 // Component
 // =============================================================================
 
+/** A plain anchor, for a disabled item whose link has no destination. */
+const DisabledAnchor = 'a';
+
 export function TreeListItem({
   id,
   label,
@@ -414,6 +418,10 @@ export function TreeListItem({
   const descriptionId = useId();
   const LinkComponent = useLinkComponent();
   const linkRef = useRef<HTMLAnchorElement>(null);
+  // Disabling the item swaps the router link for a plain anchor, so React
+  // replaces it; focus on the inner link (after a pointer click) follows the
+  // swap instead of falling to the page (spec:AST-085 FR4).
+  const anchorRef = useFocusAcrossSwap<HTMLAnchorElement>(linkRef);
   const isInteractive = onClick != null || href != null;
 
   const handleToggle = useMemo(
@@ -596,12 +604,26 @@ export function TreeListItem({
       {startContent != null && (
         <span {...stylex.props(styles.startContent)}>{startContent}</span>
       )}
-      {href != null ? (
+      {href != null && isDisabled ? (
+        // A disabled item's anchor has no destination, so neither the row's
+        // forwarded activation nor a screen reader's click can navigate
+        // (spec:AST-085 FR2). Like a disabled Link, it keeps the link role and
+        // skips the router link component.
+        <DisabledAnchor
+          ref={anchorRef}
+          role="link"
+          aria-disabled={true}
+          aria-labelledby={labelId}
+          aria-describedby={description != null ? descriptionId : undefined}
+          tabIndex={-1}
+          {...stylex.props(styles.invisibleAnchor)}>
+          {labelAndDescription}
+        </DisabledAnchor>
+      ) : href != null ? (
         <LinkComponent
-          ref={linkRef}
+          ref={anchorRef}
           href={href}
           target={target}
-          aria-disabled={isDisabled || undefined}
           aria-labelledby={labelId}
           aria-describedby={description != null ? descriptionId : undefined}
           // Roving tabindex lives on the treeitem row; inner action is not a

package/src/Typeahead/BaseTypeahead.doc.mjs

@@ -175,7 +175,7 @@ export const docs = {
       name: 'isFocusableDisabled',
       type: 'boolean',
       description:
-        'Keep a disabled input focusable with aria-disabled and readOnly so a caller-owned disabled reason remains discoverable. It blocks text entry, but when applied after results are already open, Enter can still select the highlighted option.',
+        'Keep a disabled input focusable with aria-disabled and readOnly so a caller-owned disabled reason remains discoverable. It blocks text entry, opening the results and picking a result, also from results that were open before it applied; Escape or Tab still closes them.',
       default: 'false',
     },
     {
@@ -334,7 +334,7 @@ export const docsZh = {
       name: 'isFocusableDisabled',
       type: 'boolean',
       description:
-        '使用 aria-disabled 和只读状态保持禁用输入框可聚焦，以便访问调用方提供的禁用原因。它会阻止文本输入，但如果结果已打开，按 Enter 仍可选择高亮选项。',
+        '使用 aria-disabled 和只读状态保持禁用输入框可聚焦，以便访问调用方提供的禁用原因。它会阻止文本输入、打开结果列表和选择结果，在它生效前已打开的结果中也是如此；Escape 或 Tab 仍可关闭列表。',
       default: 'false',
     },
     {
@@ -467,7 +467,7 @@ export const docsDense = {
     emptySearchText: 'Content when the query matched nothing. ReactNode.',
     isDisabled: 'Whether input disabled.',
     isFocusableDisabled:
-      'Keeps disabled input focusable and blocks text entry; an already-open highlight can still be selected with Enter.',
+      'Keeps disabled input focusable; blocks text entry, opening and picking, also from an already-open list (Escape/Tab close it).',
     hasAutoFocus: 'Auto-focus on mount.',
     debounceMs: 'Search debounce ms. 0 for sync.',
     size: 'Dropdown option padding size.',