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

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,11 @@ import {
 } from '../theme/tokens.stylex';
 import type {SearchableItem, SearchSource} from '../Typeahead/types';
 import {composeEventHandlers, mergeProps} from '../utils';
+import {joinAriaIDs} from '../utils/inputAria';
 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 +758,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 +774,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);
 
@@ -1111,12 +1124,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 +1227,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(
@@ -1391,12 +1416,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 +1491,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}
@@ -1625,7 +1660,7 @@ export function Tokenizer<T extends SearchableItem>({
               emptySearchText={emptySearchText}
               onAdd={handleAdd}
               onRemove={handleRemove}
-              onClearAll={handleClearAll}
+              onClearAll={() => handleClearAll({silent: true})}
               onChangeQuery={handleSheetQueryChange}
             />
           )}
@@ -1707,6 +1742,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.test.tsx

@@ -75,6 +75,7 @@ function Harness({
   maxEntries?: number;
   isDisabled?: boolean;
   disabledMessage?: string;
+  'aria-labelledby'?: string;
   debounceMs?: number;
   onFocus?: (event: React.FocusEvent) => void;
   onBlur?: (event: React.FocusEvent) => void;
@@ -238,6 +239,16 @@ describe('Tokenizer experimental.presentation (FR16)', () => {
 });
 
 describe('Tokenizer sheet presentation (single-sheet touch flow)', () => {
+  it('names the sheet trigger by its label, then a caller aria-labelledby', () => {
+    render(
+      <>
+        <span id="billing-heading">Billing</span>
+        <Harness aria-labelledby="billing-heading" />
+      </>,
+    );
+    expect(screen.getByRole('button', {name: 'Tags Billing'})).toBeTruthy();
+  });
+
   it('keeps rows stable while open and applies selected-first order on reopen (FR19)', async () => {
     const spy = vi.fn();
     render(<Harness spy={spy} />);
@@ -797,6 +808,14 @@ describe('Tokenizer sheet presentation (single-sheet touch flow)', () => {
           ),
         ).toHaveTextContent('All items removed'),
       );
+      // Exactly one live region says it: the field's own region stays silent
+      // for a Clear all the sheet already announced.
+      const saying = Array.from(
+        document.querySelectorAll(
+          '[aria-live], [role="status"], [role="alert"]',
+        ),
+      ).filter(region => region.textContent?.includes('All items removed'));
+      expect(saying).toHaveLength(1);
     } finally {
       modalSpy.mockRestore();
     }
@@ -1787,7 +1806,7 @@ describe('Tokenizer sheet presentation (single-sheet touch flow)', () => {
     // changes until the sheet closes.
     compact = false;
     act(() => {
-      for (const cb of listeners) cb();
+      for (const cb of listeners) {cb();}
     });
     expect(screen.getByRole('dialog', {name: 'Tags'})).toBe(dialog);
     expect(trigger).toBeInTheDocument();
@@ -2531,7 +2550,7 @@ describe('Tokenizer sheet presentation (single-sheet touch flow)', () => {
     // the hand-off inside the field reports neither a blur nor a focus.
     compact = false;
     act(() => {
-      for (const cb of listeners) cb();
+      for (const cb of listeners) {cb();}
     });
     expect(screen.getByRole('combobox')).toHaveFocus();
     expect(onFocus).toHaveBeenCalledTimes(1);
@@ -2539,14 +2558,14 @@ describe('Tokenizer sheet presentation (single-sheet touch flow)', () => {
     // And back: the input focused, the screen becomes compact again.
     compact = true;
     act(() => {
-      for (const cb of listeners) cb();
+      for (const cb of listeners) {cb();}
     });
     expect(openTrigger()).toHaveFocus();
     // Unfocused, a change moves nothing.
     openTrigger().blur();
     compact = false;
     act(() => {
-      for (const cb of listeners) cb();
+      for (const cb of listeners) {cb();}
     });
     expect(document.body).toHaveFocus();
   });

package/src/Tokenizer/TokenizerBottomSheet.tsx

@@ -41,15 +41,15 @@ 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';

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.test.tsx

@@ -370,6 +370,36 @@ describe('Toolbar', () => {
     expect(buttons[2]).toHaveAttribute('tabindex', '-1');
   });
 
+  it('keeps a link member in the arrow order and off the tab order', async () => {
+    const user = userEvent.setup();
+    render(
+      <>
+        <Toolbar
+          label="Actions"
+          startContent={
+            <>
+              <button type="button">Cut</button>
+              <a href="https://example.com">Docs</a>
+              <button type="button">Paste</button>
+            </>
+          }
+        />
+        <button type="button">After</button>
+      </>,
+    );
+
+    const cut = screen.getByRole('button', {name: 'Cut'});
+    cut.focus();
+    await user.tab();
+    expect(screen.getByRole('button', {name: 'After'})).toHaveFocus();
+
+    cut.focus();
+    await user.keyboard('{ArrowRight}');
+    expect(screen.getByRole('link', {name: 'Docs'})).toHaveFocus();
+    await user.keyboard('{ArrowRight}');
+    expect(screen.getByRole('button', {name: 'Paste'})).toHaveFocus();
+  });
+
   it('keeps its tab stop after outside dismissal of MoreMenu', async () => {
     const user = userEvent.setup();
     render(

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/Toolbar/__tests__/Toolbar.a11y.chromium.spec.ts

@@ -93,15 +93,27 @@ async function runState(
   });
 }
 
-test('every toolbar expectation is exercised by a Toolbar state', async ({
-  page,
-}) => {
-  const cdp = await page.context().newCDPSession(page);
+// Checking coverage runs every state again, which on a loaded runner nears
+// the per-test timeout as one test. It runs as one serial part per state,
+// sharing their results, then one check over all of them.
+test.describe('every toolbar expectation is exercised by a Toolbar state', () => {
+  test.describe.configure({mode: 'serial'});
   const results: BindingResult[] = [];
+
   for (const state of TOOLBAR_BINDING_STATES) {
-    results.push(await runState(page, cdp, state));
+    test(`runs ${state.id}`, async ({page}) => {
+      const cdp = await page.context().newCDPSession(page);
+      results.push(await runState(page, cdp, state));
+    });
   }
-  expect(neverExercised(results)).toEqual([]);
+
+  test('no expectation is left unexercised', () => {
+    // Every part ran in this worker; this test alone proves nothing.
+    expect(results.map(result => result.state).sort()).toEqual(
+      TOOLBAR_BINDING_STATES.map(state => state.id).sort(),
+    );
+    expect(neverExercised(results)).toEqual([]);
+  });
 });
 
 /**

package/src/Tooltip/__tests__/Tooltip.a11y.chromium.spec.ts

@@ -104,16 +104,27 @@ async function runState(
   });
 }
 
-test('every tooltip expectation is exercised by a Tooltip state', async ({
-  page,
-}) => {
-  test.setTimeout(3 * 60 * 1000);
-  const cdp = await page.context().newCDPSession(page);
+// Checking coverage runs every state again, which on a loaded runner nears
+// the per-test timeout as one test. It runs as one serial part per state,
+// sharing their results, then one check over all of them.
+test.describe('every tooltip expectation is exercised by a Tooltip state', () => {
+  test.describe.configure({mode: 'serial'});
   const results: BindingResult[] = [];
+
   for (const state of TOOLTIP_BINDING_STATES) {
-    results.push(await runState(page, cdp, state));
+    test(`runs ${state.id}`, async ({page}) => {
+      const cdp = await page.context().newCDPSession(page);
+      results.push(await runState(page, cdp, state));
+    });
   }
-  expect(neverExercised(results)).toEqual([]);
+
+  test('no expectation is left unexercised', () => {
+    // Every part ran in this worker; this test alone proves nothing.
+    expect(results.map(result => result.state).sort()).toEqual(
+      TOOLTIP_BINDING_STATES.map(state => state.id).sort(),
+    );
+    expect(neverExercised(results)).toEqual([]);
+  });
 });
 
 for (const state of TOOLTIP_BINDING_STATES) {

package/src/TopNav/TopNav.test.tsx

@@ -377,6 +377,33 @@ describe('TopNavHeading', () => {
       );
     });
 
+    it('moves focus one item per arrow key in a NavHeadingMenu (APG menu)', async () => {
+      __resetMenuPressForTest();
+      const user = userEvent.setup();
+      render(
+        <TopNavHeading
+          heading="My App"
+          menu={
+            <NavHeadingMenu>
+              <NavHeadingMenuItem label="One" onClick={() => {}} />
+              <NavHeadingMenuItem label="Two" onClick={() => {}} />
+              <NavHeadingMenuItem label="Three" onClick={() => {}} />
+            </NavHeadingMenu>
+          }
+        />,
+      );
+      await user.click(screen.getByRole('button', {name: 'Open menu'}));
+      const item = (name: string) =>
+        screen.getByRole('menuitem', {name, hidden: true});
+      item('One').focus();
+      fireEvent.keyDown(item('One'), {key: 'ArrowDown'});
+      expect(item('Two')).toHaveFocus();
+      fireEvent.keyDown(item('Two'), {key: 'ArrowDown'});
+      expect(item('Three')).toHaveFocus();
+      fireEvent.keyDown(item('Three'), {key: 'ArrowUp'});
+      expect(item('Two')).toHaveFocus();
+    });
+
     it('after a pointer pick, returns focus to the trigger without a keyboard ring (interaction-modality INV1)', async () => {
       __resetMenuPressForTest();
       const user = userEvent.setup();

package/src/TopNav/TopNavMegaMenu.test.tsx

@@ -9,6 +9,7 @@
  * SYNC: When TopNavMegaMenu changes, update tests to match new behavior
  */
 
+import {createRef} from 'react';
 import * as stylex from '@stylexjs/stylex';
 import {focusOutlineStyles} from '../utils/focusOutline.stylex';
 import {describe, it, expect, vi, beforeAll, afterAll, afterEach} from 'vitest';
@@ -1130,3 +1131,23 @@ describe('TopNavMegaMenuItem pass-through props', () => {
     );
   });
 });
+
+describe('TopNavMegaMenu ref', () => {
+  const items = <TopNavMegaMenuItem title="Analytics" href="/analytics" />;
+
+  it('forwards its ref to the trigger button', () => {
+    const ref = createRef<HTMLButtonElement>();
+    render(<TopNavMegaMenu ref={ref} label="Products" items={items} />);
+    expect(ref.current).toBe(screen.getByRole('button', {name: 'Products'}));
+  });
+
+  it('forwards its ref to the drawer trigger', () => {
+    const ref = createRef<HTMLButtonElement>();
+    render(
+      <TopNavRenderContext value="drawer">
+        <TopNavMegaMenu ref={ref} label="Products" items={items} />
+      </TopNavRenderContext>,
+    );
+    expect(ref.current).toBe(screen.getByRole('button', {name: /Products/}));
+  });
+});

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.test.tsx

@@ -9,6 +9,7 @@
  * SYNC: When TopNavMenu changes, update tests to match new behavior
  */
 
+import {createRef} from 'react';
 import {beforeEach, describe, it, expect, vi} from 'vitest';
 import {render, screen, fireEvent, act} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
@@ -322,6 +323,22 @@ describe('TopNavMenu pass-through props', () => {
     expect(trigger).toHaveAttribute('data-source', 'nav');
   });
 
+  it('forwards its ref to the trigger button', () => {
+    const ref = createRef<HTMLButtonElement>();
+    render(<TopNavMenu ref={ref} label="Products" items={mockItems} />);
+    expect(ref.current).toBe(screen.getByRole('button', {name: 'Products'}));
+  });
+
+  it('forwards its ref to the drawer trigger', () => {
+    const ref = createRef<HTMLButtonElement>();
+    render(
+      <TopNavRenderContext value="drawer">
+        <TopNavMenu ref={ref} label="Products" items={mockItems} />
+      </TopNavRenderContext>,
+    );
+    expect(ref.current).toBe(screen.getByRole('button', {name: /Products/}));
+  });
+
   it('keeps its own popup wiring when a caller passes the same attributes', () => {
     render(
       <TopNavMenu

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/TreeList.test.tsx

@@ -861,6 +861,26 @@ describe('TreeList', () => {
       });
     });
 
+    it("keeps focus on an item's inner link when the item becomes disabled (spec:AST-085 FR4)", () => {
+      const tree = (isDisabled: boolean) => [
+        {
+          id: 'docs',
+          label: 'Docs',
+          isExpanded: true,
+          children: [
+            {id: 'report', label: 'Report', href: '/report', isDisabled},
+          ],
+        },
+      ];
+      const {rerender} = render(<TreeList items={tree(false)} />);
+      // A pointer click leaves focus on the inner link.
+      screen.getByRole('link', {name: 'Report', hidden: true}).focus();
+      rerender(<TreeList items={tree(true)} />);
+      const disabled = screen.getByRole('link', {name: 'Report', hidden: true});
+      expect(disabled).not.toHaveAttribute('href');
+      expect(disabled).toHaveFocus();
+    });
+
     it('does not follow a disabled link row', () => {
       const items = [
         {
@@ -879,6 +899,12 @@ describe('TreeList', () => {
       const row = link.closest<HTMLElement>('.astryx-tree-list-item')!;
       fireEvent.click(row.firstElementChild!);
       expect(onLinkClick).not.toHaveBeenCalled();
+      // No destination, so a screen reader's click or a link menu cannot
+      // navigate either (spec:AST-085 FR2).
+      expect(link).toHaveAttribute('aria-disabled', 'true');
+      for (const attribute of ['href', 'target']) {
+        expect(link).not.toHaveAttribute(attribute);
+      }
     });
 
     describe('row clicks outside the label (FR7)', () => {