@astryxdesign/core 0.4.0 → 0.4.1-canary.0ad35c3

package/src/Timestamp/Timestamp.test.tsx

@@ -16,6 +16,24 @@ import {formatTooltipLines} from './tooltipEntries';
 import {__resetLiveRegionsForTest} from '../hooks/useAnnounce';
 import {InternationalizationProvider} from '../i18n';
 
+async function openTimestampHoverCard(): Promise<HTMLElement> {
+  const timestamp = document.querySelector('time');
+  if (timestamp == null) {
+    throw new Error('Expected Timestamp to render a <time> element');
+  }
+  const trigger = timestamp.parentElement;
+  if (trigger == null) {
+    throw new Error('Expected Timestamp to render a hover-card trigger');
+  }
+
+  fireEvent.mouseEnter(trigger);
+  await waitFor(() => {
+    expect(HTMLElement.prototype.showPopover).toHaveBeenCalled();
+  });
+
+  return screen.getByRole('dialog', {hidden: true});
+}
+
 describe('Timestamp', () => {
   // The hover card is loaded lazily (React.lazy + Suspense), so its chunk
   // resolves asynchronously the first time a card renders. Warm the module
@@ -408,6 +426,50 @@ describe('Timestamp', () => {
     expect(el.getAttribute('aria-label')).toBeNull();
   });
 
+  // Timezone abbreviations like "PST" or "GMT+2" are unexpanded abbreviations
+  // to a screen-reader user (WCAG 3.1.4) — the AT-facing aria-label must spell
+  // the timezone out in full, while visible text keeps the compact short form.
+  it('uses the long timezone name in the aria-label (WCAG 3.1.4)', () => {
+    const oneHourAgo = new Date(Date.now() - 3600 * 1000);
+    render(
+      <Timestamp
+        value={oneHourAgo.getTime() / 1000}
+        format="relative"
+        hasTooltip={false}
+        data-testid="ts"
+      />,
+    );
+
+    const longTz =
+      new Intl.DateTimeFormat(undefined, {timeZoneName: 'long'})
+        .formatToParts(oneHourAgo)
+        .find(p => p.type === 'timeZoneName')?.value ?? '';
+    expect(longTz).not.toBe('');
+    expect(screen.getByTestId('ts').getAttribute('aria-label')).toContain(
+      longTz,
+    );
+  });
+
+  it('keeps the short timezone form in visible text when isTimezoneShown', () => {
+    const date = new Date('2026-03-25T10:00:00Z');
+    render(
+      <Timestamp
+        value="2026-03-25T10:00:00Z"
+        format="time"
+        isTimezoneShown
+        data-testid="ts"
+      />,
+    );
+
+    const tzPart = (form: 'short' | 'long') =>
+      new Intl.DateTimeFormat(undefined, {timeZoneName: form})
+        .formatToParts(date)
+        .find(p => p.type === 'timeZoneName')?.value ?? '';
+    const text = screen.getByTestId('ts').textContent ?? '';
+    expect(text).toContain(tzPart('short'));
+    expect(text).not.toContain(tzPart('long'));
+  });
+
   // --- Input handling ---
 
   it('accepts Unix timestamp in seconds', () => {
@@ -602,22 +664,32 @@ describe('Timestamp', () => {
       );
       const el = screen.getByTestId('ts');
 
-      // The card layer mounts inline and carries the full absolute time (the
-      // same string as the aria-label) as its single default copyable row.
+      // The card carries the full absolute time in its visible form (short
+      // timezone abbreviation) as its single default copyable row. The
+      // aria-label spells the timezone out in full (WCAG 3.1.4), so the two
+      // strings intentionally differ — compare the card against an
+      // independently formatted short-form string after opening it.
       // Compare with normalized whitespace: Intl output can contain narrow
       // no-break spaces that jest-dom's matcher normalization would break on.
-      const card = await screen.findByRole('dialog', {hidden: true});
       const normalize = (s: string) => s.replace(/\s+/g, ' ');
-      expect(normalize(card.textContent ?? '')).toContain(
-        normalize(el.getAttribute('aria-label') ?? '\0'),
-      );
-
+      const datetime = new Date(el.getAttribute('datetime') ?? '');
+      const expected = new Intl.DateTimeFormat(undefined, {
+        year: 'numeric',
+        month: 'long',
+        day: 'numeric',
+        hour: 'numeric',
+        minute: '2-digit',
+        second: '2-digit',
+        timeZoneName: 'short',
+      }).format(datetime);
       // Tab onto the timestamp — the only tab stop in the document.
       await user.tab();
       expect(el).toHaveFocus();
       await waitFor(() => {
         expect(HTMLElement.prototype.showPopover).toHaveBeenCalled();
       });
+      const card = screen.getByRole('dialog', {hidden: true});
+      expect(normalize(card.textContent ?? '')).toContain(normalize(expected));
     });
 
     it('does not add a tab stop when the hover card is disabled', () => {
@@ -701,24 +773,37 @@ describe('Timestamp', () => {
           .queryAllByRole('tooltip', {hidden: true})
           .filter(el => !/^(Copy|Copied)$/.test(el.textContent?.trim() ?? '')),
       ).toHaveLength(0);
-      const card = await screen.findByRole('dialog', {hidden: true});
+      const card = await openTimestampHoverCard();
       // The default card is the named details card, exactly as the configured
       // one is.
       expect(card).toHaveAttribute('aria-label', 'Timestamp details');
-      // Exactly one row, carrying the full absolute time (the same string as
-      // the aria-label) with its own copy button.
+      // Exactly one row, carrying the full absolute time in its visible form
+      // (short timezone abbreviation) with its own copy button. The
+      // aria-label spells the timezone out in full (WCAG 3.1.4), so the two
+      // strings intentionally differ — compare the row against an
+      // independently formatted short-form string.
       expect(card.querySelectorAll('dd')).toHaveLength(1);
       expect(card.querySelectorAll('button')).toHaveLength(1);
 
       const normalize = (s: string) => s.replace(/\s+/g, ' ');
-      expect(normalize(card.textContent ?? '')).toContain(
-        normalize(screen.getByTestId('ts').getAttribute('aria-label') ?? '\0'),
+      const datetime = new Date(
+        screen.getByTestId('ts').getAttribute('datetime') ?? '',
       );
+      const expected = new Intl.DateTimeFormat(undefined, {
+        year: 'numeric',
+        month: 'long',
+        day: 'numeric',
+        hour: 'numeric',
+        minute: '2-digit',
+        second: '2-digit',
+        timeZoneName: 'short',
+      }).format(datetime);
+      expect(normalize(card.textContent ?? '')).toContain(normalize(expected));
     });
 
     it("copies the default absolute row's value", async () => {
       render(<Timestamp value={Date.now() / 1000 - 3600} format="relative" />);
-      const card = await screen.findByRole('dialog', {hidden: true});
+      const card = await openTimestampHoverCard();
       const rowValue = card.querySelector('dd')?.textContent ?? '';
       expect(rowValue).toBeTruthy();
       fireEvent.click(card.querySelector('button')!);
@@ -734,10 +819,11 @@ describe('Timestamp', () => {
 
     it("shows a 'Copy' tooltip on the copy button, flipping to 'Copied' after a copy", async () => {
       render(<Timestamp value={Date.now() / 1000 - 3600} format="relative" />);
-      const card = await screen.findByRole('dialog', {hidden: true});
+      const card = await openTimestampHoverCard();
       const button = card.querySelector('button')!;
       // The visible tooltip content defaults to the short imperative 'Copy'
       // (the full "Copy <value>" string stays the button's aria-label).
+      fireEvent.mouseEnter(button);
       await waitFor(() =>
         expect(
           screen.getByText('Copy', {
@@ -804,7 +890,7 @@ describe('Timestamp', () => {
           .queryAllByRole('tooltip', {hidden: true})
           .filter(el => !/^(Copy|Copied)$/.test(el.textContent?.trim() ?? '')),
       ).toHaveLength(0);
-      const card = await screen.findByRole('dialog', {hidden: true});
+      const card = await openTimestampHoverCard();
       expect(card).toHaveAttribute('aria-label', 'Timestamp details');
     });
 
@@ -820,7 +906,7 @@ describe('Timestamp', () => {
           ]}
         />,
       );
-      const card = await screen.findByRole('dialog', {hidden: true});
+      const card = await openTimestampHoverCard();
       expect(card.querySelectorAll('dd')).toHaveLength(3);
       // Entries are read-only unless they opt in, so no copy buttons and no
       // trailing action column are rendered.
@@ -847,7 +933,7 @@ describe('Timestamp', () => {
           ]}
         />,
       );
-      const card = await screen.findByRole('dialog', {hidden: true});
+      const card = await openTimestampHoverCard();
       // Three rows, but only the opted-in row carries a copy button.
       expect(card.querySelectorAll('dd')).toHaveLength(3);
       expect(card.querySelectorAll('button')).toHaveLength(1);
@@ -868,7 +954,7 @@ describe('Timestamp', () => {
           ]}
         />,
       );
-      const card = await screen.findByRole('dialog', {hidden: true});
+      const card = await openTimestampHoverCard();
       const values = Array.from(card.querySelectorAll('dd')).map(
         el => el.textContent,
       );
@@ -892,7 +978,7 @@ describe('Timestamp', () => {
           ]}
         />,
       );
-      const card = await screen.findByRole('dialog', {hidden: true});
+      const card = await openTimestampHoverCard();
       const [rowValue] = Array.from(card.querySelectorAll('dd')).map(
         el => el.textContent ?? '',
       );
@@ -923,7 +1009,7 @@ describe('Timestamp', () => {
           />
         </InternationalizationProvider>,
       );
-      const card = await screen.findByRole('dialog', {hidden: true});
+      const card = await openTimestampHoverCard();
       fireEvent.click(card.querySelector('button')!);
       await waitFor(() => {
         expect(
@@ -943,7 +1029,7 @@ describe('Timestamp', () => {
       );
       // Without entries an absolute format has no hover surface at all;
       // configuring entries must not be silently ignored.
-      const card = await screen.findByRole('dialog', {hidden: true});
+      const card = await openTimestampHoverCard();
       expect(card.textContent).toContain('UTC');
       // ...and the anchor becomes keyboard-reachable, as it is for relative.
       expect(screen.getByTestId('ts')).toHaveAttribute('tabindex', '0');
@@ -1052,7 +1138,7 @@ describe('Timestamp', () => {
         />,
       );
       // autoThreshold={0} forces the absolute branch regardless of the clock.
-      const card = await screen.findByRole('dialog', {hidden: true});
+      const card = await openTimestampHoverCard();
       expect(card.textContent).toContain('2026-02-19 17:00:00');
       expect(screen.getByTestId('ts')).toHaveAttribute('tabindex', '0');
     });
@@ -1067,7 +1153,7 @@ describe('Timestamp', () => {
           ]}
         />,
       );
-      const card = await screen.findByRole('dialog', {hidden: true});
+      const card = await openTimestampHoverCard();
       expect(card.textContent).toContain('2026-02-19 17:00:00');
     });
 
@@ -1083,7 +1169,7 @@ describe('Timestamp', () => {
           ]}
         />,
       );
-      const card = await screen.findByRole('dialog', {hidden: true});
+      const card = await openTimestampHoverCard();
       // An unlabeled entry still emits its label cell, so the grid stays
       // aligned and the <dl> stays valid markup.
       expect(card.querySelectorAll('dt')).toHaveLength(3);
@@ -1121,7 +1207,7 @@ describe('Timestamp', () => {
             ]}
           />,
         );
-        const card = await screen.findByRole('dialog', {hidden: true});
+        const card = await openTimestampHoverCard();
         const values = Array.from(card.querySelectorAll('dd')).map(
           el => el.textContent,
         );
@@ -1171,10 +1257,14 @@ describe('Timestamp', () => {
       },
     );
 
-    it('renders the full style identically as the aria-label and as a line', () => {
+    it('renders the full style as the aria-label and as a line, differing only in zone-name spelling', () => {
       // 'full' is the one member with no visible-text counterpart — it backs
       // the accessible name of a relative timestamp and the tooltip's default
-      // line. Those two must not drift apart either.
+      // line. The two must not drift apart on anything but the zone name: the
+      // aria-label spells the zone out in full for assistive tech (WCAG 3.1.4),
+      // the visible line keeps the abbreviation. Comparing them after swapping
+      // the abbreviation for the spelled-out form keeps this a direct
+      // surface-to-surface check, so re-forking either path still fails here.
       render(
         <Timestamp
           value={VALUE}
@@ -1183,9 +1273,14 @@ describe('Timestamp', () => {
           data-testid="ts"
         />,
       );
-      const [line] = formatTooltipLines(new Date(VALUE), [{format: 'full'}]);
-      expect(line.value).toBe(
-        screen.getByTestId('ts').getAttribute('aria-label'),
+      const date = new Date(VALUE);
+      const tzPart = (form: 'short' | 'long') =>
+        new Intl.DateTimeFormat(undefined, {timeZoneName: form})
+          .formatToParts(date)
+          .find(p => p.type === 'timeZoneName')?.value ?? '';
+      const [line] = formatTooltipLines(date, [{format: 'full'}]);
+      expect(screen.getByTestId('ts').getAttribute('aria-label')).toBe(
+        line.value.replace(tzPart('short'), tzPart('long')),
       );
     });
   });

package/src/Timestamp/Timestamp.tsx

@@ -451,8 +451,14 @@ export function Timestamp({
           ? formatInstant(date, effectiveFormat, {isTimezoneShown})
           : '';
 
-  // Full absolute text for tooltip and aria-label
+  // Full absolute text for the tooltip (visible — keeps the compact timezone
+  // abbreviation) and for the AT-facing aria-label, which spells the timezone
+  // out in full: abbreviations like "PST" or "GMT+2" are unexpanded
+  // abbreviations to a screen-reader user (WCAG 3.1.4).
   const fullAbsoluteText = isValidDate ? formatInstant(date, 'full') : '';
+  const ariaLabelText = isValidDate
+    ? formatInstant(date, 'full', {timeZoneNameStyle: 'long'})
+    : '';
 
   // Live updates
   useEffect(() => {
@@ -518,8 +524,14 @@ export function Timestamp({
       <time
         ref={mergeRefs(ref, timeRef)}
         dateTime={isoString}
+        // `ariaLabelText` is '' only for an invalid date, which bails out
+        // before rendering — but keep the guard local: an empty aria-label
+        // must be omitted entirely (not rendered as aria-label="") so AT
+        // falls back to reading the visible <time> content.
         aria-label={
-          isRelativeFormat(effectiveFormat) ? fullAbsoluteText : undefined
+          isRelativeFormat(effectiveFormat) && ariaLabelText !== ''
+            ? ariaLabelText
+            : undefined
         }
         // The hover card is anchored here with focusTrigger="always", which
         // attaches focus listeners but does not itself make the anchor

package/src/Timestamp/formatInstant.ts

@@ -69,6 +69,16 @@ export interface FormatInstantOptions {
    * @default false
    */
   isTimezoneShown?: boolean;
+  /**
+   * How the zone name is spelled when a format carries one. `'short'` is the
+   * abbreviation ("PST"); `'long'` spells it out ("Pacific Standard Time").
+   * Only `'full'` honours it — it is the one format that always names its zone.
+   * The spelled-out form backs a relative timestamp's accessible name, where an
+   * abbreviation reads as an unexpanded initialism to a screen reader
+   * (WCAG 3.1.4); every visible surface keeps the abbreviation.
+   * @default 'short'
+   */
+  timeZoneNameStyle?: 'short' | 'long';
 }
 
 // =============================================================================
@@ -155,7 +165,11 @@ function getWallClock(date: Date, timeZone: string | undefined): WallClock {
 export function formatInstant(
   date: Date,
   format: InstantFormat,
-  {timeZone, isTimezoneShown = false}: FormatInstantOptions = {},
+  {
+    timeZone,
+    isTimezoneShown = false,
+    timeZoneNameStyle = 'short',
+  }: FormatInstantOptions = {},
 ): string {
   const zone = timeZone === undefined ? {} : {timeZone};
   const zoneName = isTimezoneShown ? {timeZoneName: 'short' as const} : {};
@@ -164,6 +178,7 @@ export function formatInstant(
     case 'full':
       return new Intl.DateTimeFormat(undefined, {
         ...FULL_OPTIONS,
+        timeZoneName: timeZoneNameStyle,
         ...zone,
       }).format(date);
 

package/src/Toolbar/Toolbar.test.tsx

@@ -72,11 +72,11 @@ describe('Toolbar', () => {
     expect(screen.getByTestId('end')).toBeInTheDocument();
 
     // Three-slot layout produces 3 child divs (plus the aria-hidden
-    // keyboard-hint popover, which is excluded here as an implementation detail)
+    // keyboard-hint layer infrastructure, excluded as an implementation detail)
     const toolbar = screen.getByRole('toolbar');
-    expect(toolbar.querySelectorAll(':scope > :not([popover])')).toHaveLength(
-      3,
-    );
+    expect(
+      toolbar.querySelectorAll(':scope > :not([popover]):not(template)'),
+    ).toHaveLength(3);
   });
 
   it('renders two-slot layout without centerContent', () => {
@@ -91,11 +91,11 @@ describe('Toolbar', () => {
     expect(screen.getByTestId('end')).toBeInTheDocument();
 
     // Two-slot layout produces 2 child divs (plus the aria-hidden
-    // keyboard-hint popover, excluded here)
+    // keyboard-hint layer infrastructure, excluded here)
     const toolbar = screen.getByRole('toolbar');
-    expect(toolbar.querySelectorAll(':scope > :not([popover])')).toHaveLength(
-      2,
-    );
+    expect(
+      toolbar.querySelectorAll(':scope > :not([popover]):not(template)'),
+    ).toHaveLength(2);
   });
 
   it('renders start-only layout', () => {
@@ -107,9 +107,9 @@ describe('Toolbar', () => {
     );
     expect(screen.getByTestId('start')).toBeInTheDocument();
     const toolbar = screen.getByRole('toolbar');
-    expect(toolbar.querySelectorAll(':scope > :not([popover])')).toHaveLength(
-      1,
-    );
+    expect(
+      toolbar.querySelectorAll(':scope > :not([popover]):not(template)'),
+    ).toHaveLength(1);
   });
 
   it('renders end-only layout', () => {
@@ -121,9 +121,9 @@ describe('Toolbar', () => {
     );
     expect(screen.getByTestId('end')).toBeInTheDocument();
     const toolbar = screen.getByRole('toolbar');
-    expect(toolbar.querySelectorAll(':scope > :not([popover])')).toHaveLength(
-      1,
-    );
+    expect(
+      toolbar.querySelectorAll(':scope > :not([popover]):not(template)'),
+    ).toHaveLength(1);
   });
 
   it('sets aria-orientation to horizontal by default', () => {

package/src/TopNav/TopNavMegaMenu.doc.mjs

@@ -7,6 +7,11 @@ export const docs = {
   subComponentOf: 'TopNav',
   displayName: 'Top Nav Mega Menu',
   description: 'Navigation item that displays a full-width mega menu panel on hover. Uses a slots API with items and featured props. TopNavMegaMenuItem renders itself in both desktop and mobile drawer modes. Supports inline collapsible drawer via render mode context.',
+  // The panel anchors to the nearest <nav>; wrap the preview in a TopNav so
+  // it opens below the bar instead of pinning to the viewport corner (#4905).
+  playground: {
+    wrapper: {component: 'TopNav'},
+  },
   props: [
     {
       name: 'label',

package/src/TopNav/TopNavMegaMenu.test.tsx

@@ -9,6 +9,8 @@
  * SYNC: When TopNavMegaMenu changes, update tests to match new behavior
  */
 
+import * as stylex from '@stylexjs/stylex';
+import {focusOutlineStyles} from '../utils/focusOutline.stylex';
 import {describe, it, expect, vi, beforeAll, afterAll, afterEach} from 'vitest';
 import {render, screen, act, fireEvent} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
@@ -817,3 +819,44 @@ describe('TopNavMegaMenuItem', () => {
     expect(screen.getByRole('link', {name: /Analytics/})).toBeInTheDocument();
   });
 });
+
+// =============================================================================
+// The shared focus ring (#4654) — see the note in SideNav.test.tsx: jsdom will
+// not derive `:focus-visible` here, so what is pinned is that the focusable
+// element composes the shared utility's classes rather than falling back to
+// the browser's own outline.
+// =============================================================================
+
+const sharedFocusRingClasses = stylex
+  .props(focusOutlineStyles.focusVisible)
+  .className!.split(' ');
+
+function expectSharedFocusRing(el: Element) {
+  const classes = el.className.split(' ');
+  for (const c of sharedFocusRingClasses) {
+    expect(classes).toContain(c);
+  }
+}
+
+describe('TopNavMegaMenu — drawer focus ring', () => {
+  it('draws the shared ring on the drawer section header', () => {
+    render(
+      <TopNavRenderContext value="drawer">
+        <TopNavMegaMenu
+          label="Products"
+          items={<TopNavMegaMenuItem title="Analytics" href="/analytics" />}
+        />
+      </TopNavRenderContext>,
+    );
+    expectSharedFocusRing(screen.getByRole('button', {name: 'Products'}));
+  });
+
+  it('draws the shared ring on a drawer item', () => {
+    render(
+      <TopNavRenderContext value="drawer">
+        <TopNavMegaMenuItem title="Analytics" href="/analytics" />
+      </TopNavRenderContext>,
+    );
+    expectSharedFocusRing(screen.getByRole('link', {name: /Analytics/}));
+  });
+});

package/src/TopNav/TopNavMegaMenu.tsx

@@ -602,7 +602,10 @@ function DrawerMegaMenu({
         aria-controls={`${menuId}-items`}
         {...mergeProps(
           themeProps('top-nav-mega-menu', {mode: 'drawer'}),
-          stylex.props(navItemStyles.item, styles.drawerHeader),
+          focusOutlineProps.focusVisible(
+            navItemStyles.item,
+            styles.drawerHeader,
+          ),
         )}>
         {label}
         <Icon

package/src/TopNav/TopNavMegaMenuItem.tsx

@@ -215,7 +215,7 @@ export function TopNavMegaMenuItem({
         {...elementProps}
         {...mergeProps(
           themeProps('top-nav-mega-menu-item', {mode: 'drawer'}),
-          stylex.props(navItemStyles.item, styles.drawerItem),
+          focusOutlineProps.focusVisible(navItemStyles.item, styles.drawerItem),
         )}>
         {icon && <div {...stylex.props(styles.drawerItemIcon)}>{icon}</div>}
         <div {...stylex.props(styles.drawerItemContent)}>

package/src/TopNav/TopNavMenu.test.tsx

@@ -12,6 +12,9 @@
 import {describe, it, expect, vi} from 'vitest';
 import {render, screen, fireEvent} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
+import * as stylex from '@stylexjs/stylex';
+import {focusOutlineStyles} from '../utils/focusOutline.stylex';
+import {TopNavRenderContext} from './TopNavRenderContext';
 import {TopNavMenu} from './TopNavMenu';
 
 const mockItems = [
@@ -171,3 +174,41 @@ describe('keyboard navigation (APG menu pattern)', () => {
     expect(trigger).toHaveAttribute('aria-expanded', 'false');
   });
 });
+
+// =============================================================================
+// The shared focus ring (#4654) — see the note in SideNav.test.tsx: jsdom will
+// not derive `:focus-visible` here, so what is pinned is that the focusable
+// element composes the shared utility's classes rather than falling back to
+// the browser's own outline.
+// =============================================================================
+
+const sharedFocusRingClasses = stylex
+  .props(focusOutlineStyles.focusVisible)
+  .className!.split(' ');
+
+function expectSharedFocusRing(el: Element) {
+  const classes = el.className.split(' ');
+  for (const c of sharedFocusRingClasses) {
+    expect(classes).toContain(c);
+  }
+}
+
+describe('TopNavMenu — drawer focus ring', () => {
+  it('draws the shared ring on the drawer section header', () => {
+    render(
+      <TopNavRenderContext value="drawer">
+        <TopNavMenu label="Products" items={mockItems} />
+      </TopNavRenderContext>,
+    );
+    expectSharedFocusRing(screen.getByRole('button', {name: /Products/}));
+  });
+
+  it('draws the shared ring on a drawer item', () => {
+    render(
+      <TopNavRenderContext value="drawer">
+        <TopNavMenu label="Products" items={mockItems} />
+      </TopNavRenderContext>,
+    );
+    expectSharedFocusRing(screen.getByRole('link', {name: /Analytics/}));
+  });
+});

package/src/TopNav/TopNavMenu.tsx

@@ -432,7 +432,10 @@ export function TopNavMenu({
           onClick={() => setDrawerExpanded(v => !v)}
           aria-expanded={drawerExpanded}
           aria-controls={`${menuId}-items`}
-          {...stylex.props(navItemStyles.item, drawerStyles.header)}>
+          {...focusOutlineProps.focusVisible(
+            navItemStyles.item,
+            drawerStyles.header,
+          )}>
           {label}
           <Icon
             icon="chevronDown"
@@ -459,7 +462,10 @@ export function TopNavMenu({
                   item.onClick?.();
                   closeMobileNav();
                 }}
-                {...stylex.props(navItemStyles.item, drawerStyles.item)}>
+                {...focusOutlineProps.focusVisible(
+                  navItemStyles.item,
+                  drawerStyles.item,
+                )}>
                 {item.icon && (
                   <span {...stylex.props(drawerStyles.itemIcon)}>
                     {item.icon}

package/src/TreeList/TreeList.test.tsx

@@ -16,6 +16,7 @@ import {TreeList} from './TreeList';
 import type {TreeListItemData} from './TreeListTypes';
 import {defineTheme} from '../theme/defineTheme';
 import {generateThemeCSS} from '../theme/generateThemeRules';
+import {FOCUS_OUTLINE} from '../utils/focusOutline.stylex';
 
 function generateThemeTestCSS(theme: Parameters<typeof generateThemeCSS>[0]) {
   const {prose, component} = generateThemeCSS(theme);
@@ -299,8 +300,8 @@ describe('TreeList', () => {
     expect(root).toHaveFocus();
 
     expect(
-      getComputedStyle(root).getPropertyValue('--_focus-outline'),
-    ).toContain('solid');
+      getComputedStyle(root).getPropertyValue('--_focus-outline').trim(),
+    ).toBe(FOCUS_OUTLINE);
     // Mid and Leaf are DOM descendants of Root's <li> (nested <ul role="group">
     // subtrees) — their own outline var must stay unset, not inherit Root's.
     expect(getComputedStyle(mid).getPropertyValue('--_focus-outline')).toBe(

package/src/VisuallyHidden/VisuallyHidden.tsx

@@ -1,7 +1,5 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-'use client';
-
 /**
  * @file VisuallyHidden.tsx
  * @input Uses React createElement/ElementType, stylex

package/src/VisuallyHidden/index.ts

@@ -1,7 +1,5 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-'use client';
-
 /**
  * @file index.ts
  * @input Imports from VisuallyHidden.tsx

package/src/hooks/index.ts

@@ -11,7 +11,11 @@
  * SYNC: When modified, update this header
  */
 
-export {useFocusTrap} from './useFocusTrap';
+export {
+  hasActiveFocusTrapEscape,
+  isImeKeyEvent,
+  useFocusTrap,
+} from './useFocusTrap';
 export type {UseFocusTrapOptions, UseFocusTrapReturn} from './useFocusTrap';
 
 export {useAnnounce} from './useAnnounce';