@astryxdesign/core 0.7.6-canary.e736b92 → 0.7.6-canary.e7530db

package/dist/Chat/useTriggerMenu.d.ts

@@ -1,6 +1,6 @@
 /**
  * @file useTriggerMenu.tsx
- * @input Uses React, usePopover, SearchSource
+ * @input Uses React, usePopover, SearchSource, useBusyAnnouncement
  * @output Exports useTriggerMenu hook for trigger-based menus in contentEditable
  * @position Internal hook; consumed by ChatComposerInput
  *

package/dist/Chat/useTriggerMenu.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useTriggerMenu.d.ts","sourceRoot":"","sources":["../../src/Chat/useTriggerMenu.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAML,KAAK,SAAS,EACf,MAAM,OAAO,CAAC;AAaf,OAAO,KAAK,EAAC,cAAc,EAAC,MAAM,oBAAoB,CAAC;AAGvD,OAAO,KAAK,EAAC,mBAAmB,EAAE,iBAAiB,EAAC,MAAM,qBAAqB,CAAC;AAMhF,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,OAAO,CAAC;IAClB,aAAa,EAAE,mBAAmB,GAAG,IAAI,CAAC;IAC1C,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,cAAc,EAAE,CAAC;IACxB,gBAAgB,EAAE,MAAM,CAAC;IACzB,SAAS,EAAE,OAAO,CAAC;IACnB;;;OAGG;IACH,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,EAAE,mBAAmB,EAAE,CAAC;IACjC,WAAW,EAAE,KAAK,CAAC,SAAS,CAAC,cAAc,GAAG,IAAI,CAAC,CAAC;IACpD,aAAa,EAAE,CAAC,KAAK,EAAE,iBAAiB,KAAK,IAAI,CAAC;IAClD,YAAY,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACrC,YAAY,EAAE,MAAM,IAAI,CAAC;IACzB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,gBAAgB,CAAC;IACxB,gEAAgE;IAChE,WAAW,EAAE,MAAM,IAAI,CAAC;IACxB,+DAA+D;IAC/D,aAAa,EAAE,CAAC,CAAC,EAAE,KAAK,CAAC,aAAa,KAAK,OAAO,CAAC;IACnD,sCAAsC;IACtC,UAAU,EAAE,MAAM,SAAS,CAAC;IAC5B,mCAAmC;IACnC,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB;;;;;OAKG;IACH,SAAS,EAAE;QACT,IAAI,EAAE,UAAU,GAAG,SAAS,CAAC;QAC7B,gBAAgB,CAAC,EAAE,MAAM,CAAC;QAC1B,eAAe,CAAC,EAAE,OAAO,CAAC;QAC1B,eAAe,CAAC,EAAE,MAAM,CAAC;QACzB,uBAAuB,CAAC,EAAE,MAAM,CAAC;QACjC,eAAe,CAAC,EAAE,SAAS,CAAC;KAC7B,CAAC;CACH;AAoOD,wBAAgB,cAAc,CAC5B,OAAO,EAAE,qBAAqB,GAC7B,oBAAoB,CAsqBtB"}
+{"version":3,"file":"useTriggerMenu.d.ts","sourceRoot":"","sources":["../../src/Chat/useTriggerMenu.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAML,KAAK,SAAS,EACf,MAAM,OAAO,CAAC;AAaf,OAAO,KAAK,EAAC,cAAc,EAAC,MAAM,oBAAoB,CAAC;AAGvD,OAAO,KAAK,EAAC,mBAAmB,EAAE,iBAAiB,EAAC,MAAM,qBAAqB,CAAC;AAMhF,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,OAAO,CAAC;IAClB,aAAa,EAAE,mBAAmB,GAAG,IAAI,CAAC;IAC1C,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,cAAc,EAAE,CAAC;IACxB,gBAAgB,EAAE,MAAM,CAAC;IACzB,SAAS,EAAE,OAAO,CAAC;IACnB;;;OAGG;IACH,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,EAAE,mBAAmB,EAAE,CAAC;IACjC,WAAW,EAAE,KAAK,CAAC,SAAS,CAAC,cAAc,GAAG,IAAI,CAAC,CAAC;IACpD,aAAa,EAAE,CAAC,KAAK,EAAE,iBAAiB,KAAK,IAAI,CAAC;IAClD,YAAY,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACrC,YAAY,EAAE,MAAM,IAAI,CAAC;IACzB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,gBAAgB,CAAC;IACxB,gEAAgE;IAChE,WAAW,EAAE,MAAM,IAAI,CAAC;IACxB,+DAA+D;IAC/D,aAAa,EAAE,CAAC,CAAC,EAAE,KAAK,CAAC,aAAa,KAAK,OAAO,CAAC;IACnD,sCAAsC;IACtC,UAAU,EAAE,MAAM,SAAS,CAAC;IAC5B,mCAAmC;IACnC,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB;;;;;OAKG;IACH,SAAS,EAAE;QACT,IAAI,EAAE,UAAU,GAAG,SAAS,CAAC;QAC7B,gBAAgB,CAAC,EAAE,MAAM,CAAC;QAC1B,eAAe,CAAC,EAAE,OAAO,CAAC;QAC1B,eAAe,CAAC,EAAE,MAAM,CAAC;QACzB,uBAAuB,CAAC,EAAE,MAAM,CAAC;QACjC,eAAe,CAAC,EAAE,SAAS,CAAC;KAC7B,CAAC;CACH;AAoOD,wBAAgB,cAAc,CAC5B,OAAO,EAAE,qBAAqB,GAC7B,oBAAoB,CA4pBtB"}

package/dist/Chat/useTriggerMenu.js

@@ -4,7 +4,7 @@
 
 /**
  * @file useTriggerMenu.tsx
- * @input Uses React, usePopover, SearchSource
+ * @input Uses React, usePopover, SearchSource, useBusyAnnouncement
  * @output Exports useTriggerMenu hook for trigger-based menus in contentEditable
  * @position Internal hook; consumed by ChatComposerInput
  *
@@ -24,7 +24,7 @@
 import { useState, useCallback, useRef, useEffect, useId } from 'react';
 import * as stylex from '@stylexjs/stylex';
 import { usePopover } from "../Popover/usePopover.js";
-import { useAnnounce } from "../hooks/useAnnounce.js";
+import { useBusyAnnouncement } from "../hooks/useBusyAnnouncement.js";
 import { useHighlightedOptionScroll } from "../hooks/useHighlightedOptionScroll.js";
 import "../theme/tokens.stylex.js";
 import { colorVars, spacingVars, radiusVars, typeScaleVars, typographyVars } from "../theme/tokens.stylex.js";
@@ -194,34 +194,16 @@ export function useTriggerMenu(options) {
   });
 
   // The loading row carries no live role: it mounts already holding its text
-  // and is removed when results arrive, so it would be skipped. The shared
-  // channel announces each loading episode once instead (spec:AST-086 FR2,
-  // FR6), once the row has been painted: the second animation frame runs
-  // after the first paint, and a search that settles before then never shows
-  // the row, so it announces nothing (FR7). The flag clears when the loading
-  // row goes away, so the next search is a new occasion.
-  const announce = useAnnounce();
-  const hasAnnouncedLoadingRef = useRef(false);
+  // and is removed when results arrive, so it would be skipped. "Searching…"
+  // is the menu's busy state, so the shared busy path announces each loading
+  // episode once (spec:AST-086 FR6, FR8): rerenders and further keystrokes
+  // while loading do not repeat it, results arriving re-arm it, and a search
+  // that settles before the announcement goes out announces nothing.
   // Mirrors renderMenu: no row exists without an active trigger or while hidden.
   const isLoadingRowShown = state.isLoading && !state.isHidden && state.activeTrigger !== null;
   // One catalog string serves the row and the announcement (FR7).
   const loadingText = state.activeTrigger?.loadingText ?? t('@astryx.chatTriggerMenu.searching');
-  useEffect(() => {
-    if (!isLoadingRowShown) {
-      hasAnnouncedLoadingRef.current = false;
-      return;
-    }
-    if (hasAnnouncedLoadingRef.current) {
-      return;
-    }
-    let frame = requestAnimationFrame(() => {
-      frame = requestAnimationFrame(() => {
-        hasAnnouncedLoadingRef.current = true;
-        announce(loadingText, 'polite');
-      });
-    });
-    return () => cancelAnimationFrame(frame);
-  }, [announce, isLoadingRowShown, loadingText]);
+  const settleBusyAnnouncement = useBusyAnnouncement(isLoadingRowShown, loadingText, editableRef);
   const triggerStartRef = useRef(-1);
   const searchTimeoutRef = useRef(null);
   const searchRequestIdRef = useRef(0);
@@ -374,6 +356,9 @@ export function useTriggerMenu(options) {
       return true;
     };
     const applyResults = items => {
+      // Results that arrive before the busy start is heard withdraw it, so a
+      // search that settles on its first frame announces nothing (FR8).
+      settleBusyAnnouncement();
       const isHidden = isUnmatchedMultiWordQuery(trigger, items, false);
       setState(prev => ({
         ...prev,
@@ -399,7 +384,7 @@ export function useTriggerMenu(options) {
         trigger.searchSource.cancel?.();
         const result = trigger.searchSource.search(query);
         // A synchronous source already has its results, so it never shows
-        // or announces the loading row (spec:AST-086 FR7).
+        // or announces the loading row.
         if (!Array.isArray(result)) {
           setState(prev => ({
             ...prev,
@@ -435,7 +420,7 @@ export function useTriggerMenu(options) {
         doSearch();
       }
     }
-  }, [debounceMs, editableRef, triggers, reset, setAnchor, hidePopover, showPopover]);
+  }, [debounceMs, editableRef, triggers, reset, setAnchor, hidePopover, showPopover, settleBusyAnnouncement]);
   const selectItem = useCallback(item => {
     const trigger = state.activeTrigger;
     if (!trigger) {

package/dist/TopNav/TopNavMegaMenuFeaturedCard.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"TopNavMegaMenuFeaturedCard.d.ts","sourceRoot":"","sources":["../../src/TopNav/TopNavMegaMenuFeaturedCard.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,EAAC,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AAS5C,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAiD5C,MAAM,WAAW,+BAAgC,SAAQ,SAAS,CAAC,cAAc,CAAC;IAChF,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IAChC,kBAAkB;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,wCAAwC;IACxC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,mDAAmD;IACnD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;;;;;OAQG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,qBAAqB;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,oBAAoB;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,uDAAuD;IACvD,QAAQ,CAAC,EAAE,SAAS,CAAC;CACtB;AAMD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,0BAA0B,CAAC,EACzC,GAAG,EACH,KAAK,EACL,WAAW,EACX,KAAK,EACL,QAAQ,EACR,SAAS,EACT,QAAQ,EACR,QAAQ,EACR,MAAM,EACN,SAAS,EACT,KAAK,EACL,GAAG,IAAI,EACR,EAAE,+BAA+B,qBAsCjC;yBAnDe,0BAA0B"}
+{"version":3,"file":"TopNavMegaMenuFeaturedCard.d.ts","sourceRoot":"","sources":["../../src/TopNav/TopNavMegaMenuFeaturedCard.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,EAAC,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AAS5C,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAqD5C,MAAM,WAAW,+BAAgC,SAAQ,SAAS,CAAC,cAAc,CAAC;IAChF,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IAChC,kBAAkB;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,wCAAwC;IACxC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,mDAAmD;IACnD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;;;;;OAQG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,qBAAqB;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,oBAAoB;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,uDAAuD;IACvD,QAAQ,CAAC,EAAE,SAAS,CAAC;CACtB;AAMD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,0BAA0B,CAAC,EACzC,GAAG,EACH,KAAK,EACL,WAAW,EACX,KAAK,EACL,QAAQ,EACR,SAAS,EACT,QAAQ,EACR,QAAQ,EACR,MAAM,EACN,SAAS,EACT,KAAK,EACL,GAAG,IAAI,EACR,EAAE,+BAA+B,qBAyCjC;yBAtDe,0BAA0B"}

package/dist/TopNav/TopNavMegaMenuFeaturedCard.js

@@ -21,7 +21,7 @@ import React from 'react';
 import * as stylex from '@stylexjs/stylex';
 import "../theme/tokens.stylex.js";
 import { colorVars, spacingVars, typeScaleVars, fontWeightVars } from "../theme/tokens.stylex.js";
-import { mergeProps } from "../utils/index.js";
+import { mergeProps, rtlStyles } from "../utils/index.js";
 import { useLinkComponent } from "../Link/useLinkComponent.js";
 import { themeProps } from "../utils/themeProps.js";
 
@@ -34,6 +34,10 @@ const styles = {
     k1xSpc: "x78zum5",
     kXwgrk: "xdt5ytf",
     $$css: true
+  },
+  linkArrow: {
+    k1xSpc: "x1rg5ohu",
+    $$css: true
   }
 };
 
@@ -121,7 +125,10 @@ export function TopNavMegaMenuFeaturedCard({
         ...{
           className: "x141an7d x2mo6ok x1ltkj2j xjse4m1 x1hl2dhg"
         },
-        children: [linkLabel, " \u2192"]
+        children: [linkLabel, ' ', /*#__PURE__*/_jsx("span", {
+          ...stylex.props(styles.linkArrow, rtlStyles.mirror),
+          children: "\u2192"
+        })]
       }), children]
     })]
   });

package/dist/TreeList/TreeList.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"TreeList.d.ts","sourceRoot":"","sources":["../../src/TreeList/TreeList.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;GAWG;AAEH,OAAO,EAOL,KAAK,SAAS,EACf,MAAM,OAAO,CAAC;AAKf,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAE5C,OAAO,KAAK,EACV,gBAAgB,EAChB,eAAe,EACf,eAAe,EAChB,MAAM,iBAAiB,CAAC;AAIzB,OAAO,EAML,KAAK,cAAc,EAEpB,MAAM,0BAA0B,CAAC;AAMlC,OAAO,EAAC,KAAK,eAAe,EAAE,KAAK,eAAe,EAAC,MAAM,iBAAiB,CAAC;AAE3E,MAAM,WAAW,aAAc,SAAQ,SAAS,CAAC,cAAc,CAAC;IAC9D,wCAAwC;IACxC,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IAEhC;;;;OAIG;IACH,cAAc,CAAC,EAAE,cAAc,CAAC;IAEhC;;;OAGG;IACH,KAAK,EAAE,gBAAgB,EAAE,CAAC;IAE1B;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,eAAe,CAAC;IAE1B;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE,eAAe,CAAC;IAE1B;;;OAGG;IACH,MAAM,CAAC,EAAE,SAAS,CAAC;IAEnB;;OAEG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AA6HD,wBAAgB,QAAQ,CAAC,EACvB,KAAK,EACL,OAAoB,EACpB,OAAsB,EACtB,MAAM,EACN,MAAM,EACN,SAAS,EACT,KAAK,EACL,aAAa,EAAE,MAAM,EACrB,YAAY,EAAE,SAAS,EACvB,iBAAiB,EAAE,cAAc,EACjC,GAAG,EACH,SAAS,EAAE,aAAa,EACxB,cAAc,EACd,GAAG,SAAS,EACb,EAAE,aAAa,+BA8Xf;yBA7Ye,QAAQ"}
+{"version":3,"file":"TreeList.d.ts","sourceRoot":"","sources":["../../src/TreeList/TreeList.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;GAWG;AAEH,OAAO,EAOL,KAAK,SAAS,EACf,MAAM,OAAO,CAAC;AAKf,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAE5C,OAAO,KAAK,EACV,gBAAgB,EAChB,eAAe,EACf,eAAe,EAChB,MAAM,iBAAiB,CAAC;AAYzB,OAAO,EAML,KAAK,cAAc,EAEpB,MAAM,0BAA0B,CAAC;AAMlC,OAAO,EAAC,KAAK,eAAe,EAAE,KAAK,eAAe,EAAC,MAAM,iBAAiB,CAAC;AAE3E,MAAM,WAAW,aAAc,SAAQ,SAAS,CAAC,cAAc,CAAC;IAC9D,wCAAwC;IACxC,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IAEhC;;;;OAIG;IACH,cAAc,CAAC,EAAE,cAAc,CAAC;IAEhC;;;OAGG;IACH,KAAK,EAAE,gBAAgB,EAAE,CAAC;IAE1B;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,eAAe,CAAC;IAE1B;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE,eAAe,CAAC;IAE1B;;;OAGG;IACH,MAAM,CAAC,EAAE,SAAS,CAAC;IAEnB;;OAEG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AA6HD,wBAAgB,QAAQ,CAAC,EACvB,KAAK,EACL,OAAoB,EACpB,OAAsB,EACtB,MAAM,EACN,MAAM,EACN,SAAS,EACT,KAAK,EACL,aAAa,EAAE,MAAM,EACrB,YAAY,EAAE,SAAS,EACvB,iBAAiB,EAAE,cAAc,EACjC,GAAG,EACH,SAAS,EAAE,aAAa,EACxB,cAAc,EACd,GAAG,SAAS,EACb,EAAE,aAAa,+BAmcf;yBAlde,QAAQ"}

package/dist/TreeList/TreeList.js

@@ -24,6 +24,10 @@ import { TreeListItem } from "./TreeListItem.js";
 import { themeProps } from "../utils/themeProps.js";
 import { useTreeFocusInternal } from "../hooks/useTreeFocus.js";
 import { LayoutChangeSnapshot } from "../motion/LayoutChangeSnapshot.js";
+import { moveFocusLeftBehind, noteFocusWithin } from "../utils/focusReturn.js";
+import { useInteractionModalityTracking } from "../utils/interactionModality.js";
+import { useFocusLeavingChange } from "../utils/useFocusLeavingChange.js";
+import { useMergedRefs } from "../hooks/useMergedRefs.js";
 import { applyLayoutChangeTransition, holdLayoutExit, playLayoutChange, releaseLayoutExit, reportLayoutChange } from "../motion/animatedLayout.js";
 
 // =============================================================================
@@ -259,6 +263,58 @@ export function TreeList({
       });
     }
   }, [animatedLayout, expandedIds]);
+  // Focus inside a branch's child group when it collapses would be lost once
+  // the group goes (or turns inert for its exit). It moves to the collapsing
+  // row itself (AR2); focus anywhere else is not moved. The shared sequence
+  // notes it in the commit before the DOM changes and moves it once the
+  // collapse has committed.
+  // The tree's own document's last input decides the moved focus's ring.
+  const {
+    ref: modalityRef
+  } = useInteractionModalityTracking();
+  const noteCollapsingFocus = useFocusLeavingChange(expandedIds,
+  // Every expanded row whose group holds focus, outermost first, found by
+  // walking up from the focused element: which of them collapsed is known
+  // only after the commit.
+  previous => {
+    const tree = treeElementRef.current;
+    const active = tree?.ownerDocument.activeElement;
+    if (tree == null || active == null || !tree.contains(active)) {
+      return null;
+    }
+    let focus = null;
+    const ids = [];
+    for (let element = active.parentElement; element != null && element !== tree; element = element.parentElement) {
+      const id = element.parentElement?.dataset.treeId;
+      if (element.getAttribute('role') === 'group' && id != null && previous.has(id)) {
+        focus = noteFocusWithin(element);
+        ids.unshift(id);
+      }
+    }
+    return focus == null ? null : {
+      focus,
+      ids
+    };
+  }, (noted, expanded) => {
+    // The outermost row that collapsed: a row inside it goes with it.
+    const id = noted.ids.find(candidate => !expanded.has(candidate));
+    if (id == null) {
+      return;
+    }
+    const row = treeElementRef.current?.querySelector(`[data-tree-id="${CSS.escape(id)}"]`);
+    const moved = moveFocusLeftBehind(noted.focus, row, row?.querySelector(':scope > [role="group"]') ?? null);
+    // The row focus moved to holds the tree's one Tab stop, unless it is
+    // disabled (AR1, AR2).
+    if (moved && row != null) {
+      takeTabStop(row);
+    }
+  });
+  const beforeExpansionChange = useCallback(previous => {
+    noteCollapsingFocus(previous);
+    if (animatedLayout != null) {
+      measureChanges(previous);
+    }
+  }, [animatedLayout, measureChanges, noteCollapsingFocus]);
   // Without a handle the chevrons keep the theme's own turn: a spring a
   // handle set stays only while it is passed (`spec:AST-105` FR2).
   useLayoutEffect(() => {
@@ -341,7 +397,8 @@ export function TreeList({
   const {
     treeRef,
     handleKeyDown,
-    handleFocus
+    handleFocus,
+    takeTabStop
   } = useTreeFocusInternal({
     onToggleExpand: handleToggle,
     onActivate: activateItem,
@@ -355,6 +412,7 @@ export function TreeList({
   useLayoutEffect(() => {
     treeElementRef.current = treeRef.current;
   });
+  const mergedTreeRef = useMergedRefs(treeRef, modalityRef);
   const handleRootKeyDown = useCallback(e => {
     onKeyDownProp?.(e);
     if (e.defaultPrevented) {
@@ -429,11 +487,11 @@ export function TreeList({
         className: "x1p37lm5"
       },
       children: header
-    }), animatedLayout != null && /*#__PURE__*/_jsx(LayoutChangeSnapshot, {
+    }), /*#__PURE__*/_jsx(LayoutChangeSnapshot, {
       value: expandedIds,
-      onBeforeChange: measureChanges
+      onBeforeChange: beforeExpansionChange
     }), /*#__PURE__*/_jsx("ul", {
-      ref: treeRef,
+      ref: mergedTreeRef,
       role: "tree",
       "aria-label": hasHeader ? undefined : ariaLabel,
       "aria-labelledby": hasHeader ? headerId : ariaLabelledby,

package/dist/hooks/useTreeFocus.d.ts

@@ -170,9 +170,19 @@ export type UseTreeFocusInternalOptions = UseTreeFocusOptions & {
      */
     matchLabelledBy?: boolean;
 };
+/** What the package's own components get beyond the public hook. */
+export type UseTreeFocusInternalReturn<T extends HTMLElement = HTMLElement> = UseTreeFocusReturn<T> & {
+    /**
+     * With `hasRovingTabIndex`, makes `item` the tree's one Tab stop, by the
+     * same rule the hook's own moves follow: a disabled or hidden row never
+     * takes it, and the stop stays where it is. TreeList calls it when it
+     * moves focus to a collapsing row (`component:TreeList` AR2).
+     */
+    takeTabStop: (item: HTMLElement) => void;
+};
 /**
  * The implementation behind {@link useTreeFocus}. Not exported from the
  * package; the public hook calls it without the internal options.
  */
-export declare function useTreeFocusInternal<T extends HTMLElement = HTMLElement>(options?: UseTreeFocusInternalOptions): UseTreeFocusReturn<T>;
+export declare function useTreeFocusInternal<T extends HTMLElement = HTMLElement>(options?: UseTreeFocusInternalOptions): UseTreeFocusInternalReturn<T>;
 //# sourceMappingURL=useTreeFocus.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"useTreeFocus.d.ts","sourceRoot":"","sources":["../../src/hooks/useTreeFocus.ts"],"names":[],"mappings":"AAoCA;;;;;;;;;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;AAwBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,wBAAgB,YAAY,CAAC,CAAC,SAAS,WAAW,GAAG,WAAW,EAC9D,OAAO,GAAE,mBAAwB,GAChC,kBAAkB,CAAC,CAAC,CAAC,CAIvB;AAED;;;;;GAKG;AACH,MAAM,MAAM,2BAA2B,GAAG,mBAAmB,GAAG;IAC9D;;;;;;OAMG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B,CAAC;AAEF;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,SAAS,WAAW,GAAG,WAAW,EACtE,OAAO,GAAE,2BAAgC,GACxC,kBAAkB,CAAC,CAAC,CAAC,CAsXvB"}
+{"version":3,"file":"useTreeFocus.d.ts","sourceRoot":"","sources":["../../src/hooks/useTreeFocus.ts"],"names":[],"mappings":"AAoCA;;;;;;;;;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;AAwBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,wBAAgB,YAAY,CAAC,CAAC,SAAS,WAAW,GAAG,WAAW,EAC9D,OAAO,GAAE,mBAAwB,GAChC,kBAAkB,CAAC,CAAC,CAAC,CAQvB;AAED;;;;;GAKG;AACH,MAAM,MAAM,2BAA2B,GAAG,mBAAmB,GAAG;IAC9D;;;;;;OAMG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B,CAAC;AAEF,oEAAoE;AACpE,MAAM,MAAM,0BAA0B,CAAC,CAAC,SAAS,WAAW,GAAG,WAAW,IACxE,kBAAkB,CAAC,CAAC,CAAC,GAAG;IACtB;;;;;OAKG;IACH,WAAW,EAAE,CAAC,IAAI,EAAE,WAAW,KAAK,IAAI,CAAC;CAC1C,CAAC;AAEJ;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,SAAS,WAAW,GAAG,WAAW,EACtE,OAAO,GAAE,2BAAgC,GACxC,0BAA0B,CAAC,CAAC,CAAC,CAoY/B"}

package/dist/hooks/useTreeFocus.js

@@ -90,11 +90,15 @@ function itemLabelText(item, matchLabelledBy) {
 
 export function useTreeFocus(options = {}) {
   // The flag is pinned off here so an untyped options object cannot smuggle
-  // it through the public hook.
-  return useTreeFocusInternal({
+  // it through the public hook, and the internal stop move stays internal.
+  const {
+    takeTabStop: _takeTabStop,
+    ...result
+  } = useTreeFocusInternal({
     ...options,
     matchLabelledBy: false
   });
+  return result;
 }
 
 /**
@@ -104,6 +108,8 @@ export function useTreeFocus(options = {}) {
  * `UseTreeFocusOptions` stays exactly as released.
  */
 
+/** What the package's own components get beyond the public hook. */
+
 /**
  * The implementation behind {@link useTreeFocus}. Not exported from the
  * package; the public hook calls it without the internal options.
@@ -390,11 +396,21 @@ export function useTreeFocusInternal(options = {}) {
       syncTabStops();
     }
   }, [hasRovingTabIndex, syncTabStops]);
+  const takeTabStop = useCallback(item => {
+    if (!hasRovingTabIndex || itemDisabled(item)) {
+      return;
+    }
+    const items = getItems();
+    if (items.includes(item)) {
+      moveTabStop(items, item);
+    }
+  }, [getItems, hasRovingTabIndex, itemDisabled, moveTabStop]);
   return {
     treeRef,
     handleKeyDown,
     handleFocus,
     focusFirst,
-    focusLast
+    focusLast,
+    takeTabStop
   };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astryxdesign/core",
-  "version": "0.7.6-canary.e736b92",
+  "version": "0.7.6-canary.e7530db",
   "displayName": "Astryx Core",
   "description": "The component library. Accessible, themeable React components with built-in spacing, dark mode, and StyleX styling.",
   "author": "Meta Open Source",
@@ -860,9 +860,9 @@
     "react-dom": ">=19.0.0"
   },
   "devDependencies": {
-    "@astryxdesign/a11y-spec": "0.7.6-canary.e736b92",
-    "@astryxdesign/cli": "0.7.6-canary.e736b92",
-    "@astryxdesign/interaction-harness": "0.7.6-canary.e736b92",
+    "@astryxdesign/a11y-spec": "0.7.6-canary.e7530db",
+    "@astryxdesign/cli": "0.7.6-canary.e7530db",
+    "@astryxdesign/interaction-harness": "0.7.6-canary.e7530db",
     "@babel/cli": "^7.29.7",
     "@babel/core": "^7.29.7",
     "@babel/preset-react": "^7.29.7",

package/src/Chat/useTriggerMenu.tsx

@@ -4,7 +4,7 @@
 
 /**
  * @file useTriggerMenu.tsx
- * @input Uses React, usePopover, SearchSource
+ * @input Uses React, usePopover, SearchSource, useBusyAnnouncement
  * @output Exports useTriggerMenu hook for trigger-based menus in contentEditable
  * @position Internal hook; consumed by ChatComposerInput
  *
@@ -32,7 +32,7 @@ import {
 } from 'react';
 import * as stylex from '@stylexjs/stylex';
 import {usePopover} from '../Popover/usePopover';
-import {useAnnounce} from '../hooks/useAnnounce';
+import {useBusyAnnouncement} from '../hooks/useBusyAnnouncement';
 import {useHighlightedOptionScroll} from '../hooks/useHighlightedOptionScroll';
 import {
   colorVars,
@@ -355,36 +355,22 @@ export function useTriggerMenu(
   });
 
   // The loading row carries no live role: it mounts already holding its text
-  // and is removed when results arrive, so it would be skipped. The shared
-  // channel announces each loading episode once instead (spec:AST-086 FR2,
-  // FR6), once the row has been painted: the second animation frame runs
-  // after the first paint, and a search that settles before then never shows
-  // the row, so it announces nothing (FR7). The flag clears when the loading
-  // row goes away, so the next search is a new occasion.
-  const announce = useAnnounce();
-  const hasAnnouncedLoadingRef = useRef(false);
+  // and is removed when results arrive, so it would be skipped. "Searching…"
+  // is the menu's busy state, so the shared busy path announces each loading
+  // episode once (spec:AST-086 FR6, FR8): rerenders and further keystrokes
+  // while loading do not repeat it, results arriving re-arm it, and a search
+  // that settles before the announcement goes out announces nothing.
   // Mirrors renderMenu: no row exists without an active trigger or while hidden.
   const isLoadingRowShown =
     state.isLoading && !state.isHidden && state.activeTrigger !== null;
   // One catalog string serves the row and the announcement (FR7).
   const loadingText =
     state.activeTrigger?.loadingText ?? t('@astryx.chatTriggerMenu.searching');
-  useEffect(() => {
-    if (!isLoadingRowShown) {
-      hasAnnouncedLoadingRef.current = false;
-      return;
-    }
-    if (hasAnnouncedLoadingRef.current) {
-      return;
-    }
-    let frame = requestAnimationFrame(() => {
-      frame = requestAnimationFrame(() => {
-        hasAnnouncedLoadingRef.current = true;
-        announce(loadingText, 'polite');
-      });
-    });
-    return () => cancelAnimationFrame(frame);
-  }, [announce, isLoadingRowShown, loadingText]);
+  const settleBusyAnnouncement = useBusyAnnouncement(
+    isLoadingRowShown,
+    loadingText,
+    editableRef,
+  );
 
   const triggerStartRef = useRef<number>(-1);
   const searchTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
@@ -570,6 +556,9 @@ export function useTriggerMenu(
       };
 
       const applyResults = (items: SearchableItem[]) => {
+        // Results that arrive before the busy start is heard withdraw it, so a
+        // search that settles on its first frame announces nothing (FR8).
+        settleBusyAnnouncement();
         const isHidden = isUnmatchedMultiWordQuery(trigger, items, false);
         setState(prev => ({
           ...prev,
@@ -596,7 +585,7 @@ export function useTriggerMenu(
           trigger.searchSource.cancel?.();
           const result = trigger.searchSource.search(query);
           // A synchronous source already has its results, so it never shows
-          // or announces the loading row (spec:AST-086 FR7).
+          // or announces the loading row.
           if (!Array.isArray(result)) {
             setState(prev => ({...prev, isLoading: true}));
           }
@@ -638,6 +627,7 @@ export function useTriggerMenu(
       setAnchor,
       hidePopover,
       showPopover,
+      settleBusyAnnouncement,
     ],
   );
 

package/src/TopNav/TopNavMegaMenuFeaturedCard.tsx

@@ -26,7 +26,7 @@ import {
   typeScaleVars,
   fontWeightVars,
 } from '../theme/tokens.stylex';
-import {mergeProps} from '../utils';
+import {mergeProps, rtlStyles} from '../utils';
 import type {BaseProps} from '../BaseProps';
 import {useLinkComponent} from '../Link/useLinkComponent';
 import {themeProps} from '../utils/themeProps';
@@ -70,6 +70,10 @@ const styles = stylex.create({
     color: colorVars['--color-text-accent'],
     textDecoration: 'none',
   },
+  // A transform needs a box: an inline span would not mirror.
+  linkArrow: {
+    display: 'inline-block',
+  },
 });
 
 // =============================================================================
@@ -175,7 +179,10 @@ export function TopNavMegaMenuFeaturedCard({
         )}
         {linkLabel && linkHref && (
           <LinkComponent href={linkHref} {...stylex.props(styles.link)}>
-            {linkLabel} →
+            {linkLabel}{' '}
+            {/* The arrow points toward the inline end, so it mirrors in RTL
+                (design:bidirectionality DR4); U+2192 is not bidi-mirrored. */}
+            <span {...stylex.props(styles.linkArrow, rtlStyles.mirror)}>→</span>
           </LinkComponent>
         )}
         {children}

package/src/TreeList/TreeList.tsx

@@ -38,6 +38,14 @@ import type {
 import {themeProps} from '../utils/themeProps';
 import {useTreeFocusInternal} from '../hooks/useTreeFocus';
 import {LayoutChangeSnapshot} from '../motion/LayoutChangeSnapshot';
+import {
+  moveFocusLeftBehind,
+  noteFocusWithin,
+  type FocusWithin,
+} from '../utils/focusReturn';
+import {useInteractionModalityTracking} from '../utils/interactionModality';
+import {useFocusLeavingChange} from '../utils/useFocusLeavingChange';
+import {useMergedRefs} from '../hooks/useMergedRefs';
 import {
   applyLayoutChangeTransition,
   holdLayoutExit,
@@ -383,6 +391,76 @@ export function TreeList({
     },
     [animatedLayout, expandedIds],
   );
+  // Focus inside a branch's child group when it collapses would be lost once
+  // the group goes (or turns inert for its exit). It moves to the collapsing
+  // row itself (AR2); focus anywhere else is not moved. The shared sequence
+  // notes it in the commit before the DOM changes and moves it once the
+  // collapse has committed.
+  // The tree's own document's last input decides the moved focus's ring.
+  const {ref: modalityRef} = useInteractionModalityTracking();
+  const noteCollapsingFocus = useFocusLeavingChange<
+    ReadonlySet<string>,
+    {focus: FocusWithin; ids: string[]}
+  >(
+    expandedIds,
+    // Every expanded row whose group holds focus, outermost first, found by
+    // walking up from the focused element: which of them collapsed is known
+    // only after the commit.
+    (previous: ReadonlySet<string>) => {
+      const tree = treeElementRef.current;
+      const active = tree?.ownerDocument.activeElement;
+      if (tree == null || active == null || !tree.contains(active)) {
+        return null;
+      }
+      let focus: FocusWithin | null = null;
+      const ids: string[] = [];
+      for (
+        let element = active.parentElement;
+        element != null && element !== tree;
+        element = element.parentElement
+      ) {
+        const id = element.parentElement?.dataset.treeId;
+        if (
+          element.getAttribute('role') === 'group' &&
+          id != null &&
+          previous.has(id)
+        ) {
+          focus = noteFocusWithin(element);
+          ids.unshift(id);
+        }
+      }
+      return focus == null ? null : {focus, ids};
+    },
+    (noted, expanded) => {
+      // The outermost row that collapsed: a row inside it goes with it.
+      const id = noted.ids.find(candidate => !expanded.has(candidate));
+      if (id == null) {
+        return;
+      }
+      const row = treeElementRef.current?.querySelector<HTMLElement>(
+        `[data-tree-id="${CSS.escape(id)}"]`,
+      );
+      const moved = moveFocusLeftBehind(
+        noted.focus,
+        row,
+        row?.querySelector(':scope > [role="group"]') ?? null,
+      );
+      // The row focus moved to holds the tree's one Tab stop, unless it is
+      // disabled (AR1, AR2).
+      if (moved && row != null) {
+        takeTabStop(row);
+      }
+    },
+  );
+  const beforeExpansionChange = useCallback(
+    (previous: ReadonlySet<string>) => {
+      noteCollapsingFocus(previous);
+      if (animatedLayout != null) {
+        measureChanges(previous);
+      }
+    },
+    [animatedLayout, measureChanges, noteCollapsingFocus],
+  );
   // Without a handle the chevrons keep the theme's own turn: a spring a
   // handle set stays only while it is passed (`spec:AST-105` FR2).
   useLayoutEffect(() => {
@@ -481,7 +559,7 @@ export function TreeList({
     }
   }, [expandedIds, animatedLayout, endExit]);
 
-  const {treeRef, handleKeyDown, handleFocus} =
+  const {treeRef, handleKeyDown, handleFocus, takeTabStop} =
     useTreeFocusInternal<HTMLUListElement>({
       onToggleExpand: handleToggle,
       onActivate: activateItem,
@@ -495,6 +573,7 @@ export function TreeList({
   useLayoutEffect(() => {
     treeElementRef.current = treeRef.current;
   });
+  const mergedTreeRef = useMergedRefs(treeRef, modalityRef);
 
   const handleRootKeyDown = useCallback(
     (e: React.KeyboardEvent<HTMLDivElement>) => {
@@ -605,14 +684,12 @@ export function TreeList({
           {header}
         </div>
       )}
-      {animatedLayout != null && (
-        <LayoutChangeSnapshot
-          value={expandedIds}
-          onBeforeChange={measureChanges}
-        />
-      )}
+      <LayoutChangeSnapshot
+        value={expandedIds}
+        onBeforeChange={beforeExpansionChange}
+      />
       <ul
-        ref={treeRef}
+        ref={mergedTreeRef}
         role="tree"
         aria-label={hasHeader ? undefined : ariaLabel}
         aria-labelledby={hasHeader ? headerId : ariaLabelledby}

package/src/hooks/useTreeFocus.ts

@@ -236,8 +236,12 @@ export function useTreeFocus<T extends HTMLElement = HTMLElement>(
   options: UseTreeFocusOptions = {},
 ): UseTreeFocusReturn<T> {
   // The flag is pinned off here so an untyped options object cannot smuggle
-  // it through the public hook.
-  return useTreeFocusInternal<T>({...options, matchLabelledBy: false});
+  // it through the public hook, and the internal stop move stays internal.
+  const {takeTabStop: _takeTabStop, ...result} = useTreeFocusInternal<T>({
+    ...options,
+    matchLabelledBy: false,
+  });
+  return result;
 }
 
 /**
@@ -257,13 +261,25 @@ export type UseTreeFocusInternalOptions = UseTreeFocusOptions & {
   matchLabelledBy?: boolean;
 };
 
+/** What the package's own components get beyond the public hook. */
+export type UseTreeFocusInternalReturn<T extends HTMLElement = HTMLElement> =
+  UseTreeFocusReturn<T> & {
+    /**
+     * With `hasRovingTabIndex`, makes `item` the tree's one Tab stop, by the
+     * same rule the hook's own moves follow: a disabled or hidden row never
+     * takes it, and the stop stays where it is. TreeList calls it when it
+     * moves focus to a collapsing row (`component:TreeList` AR2).
+     */
+    takeTabStop: (item: HTMLElement) => void;
+  };
+
 /**
  * The implementation behind {@link useTreeFocus}. Not exported from the
  * package; the public hook calls it without the internal options.
  */
 export function useTreeFocusInternal<T extends HTMLElement = HTMLElement>(
   options: UseTreeFocusInternalOptions = {},
-): UseTreeFocusReturn<T> {
+): UseTreeFocusInternalReturn<T> {
   const {
     itemSelector = '[role="treeitem"]',
     isItemDisabled,
@@ -630,11 +646,25 @@ export function useTreeFocusInternal<T extends HTMLElement = HTMLElement>(
     }
   }, [hasRovingTabIndex, syncTabStops]);
 
+  const takeTabStop = useCallback(
+    (item: HTMLElement) => {
+      if (!hasRovingTabIndex || itemDisabled(item)) {
+        return;
+      }
+      const items = getItems();
+      if (items.includes(item)) {
+        moveTabStop(items, item);
+      }
+    },
+    [getItems, hasRovingTabIndex, itemDisabled, moveTabStop],
+  );
+
   return {
     treeRef,
     handleKeyDown,
     handleFocus,
     focusFirst,
     focusLast,
+    takeTabStop,
   };
 }