@astryxdesign/core 0.4.0 → 0.4.1-canary.f4868b2

package/src/Timestamp/Timestamp.test.tsx

@@ -408,6 +408,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,15 +646,26 @@ 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 layer mounts inline and 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.
       // 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);
+      expect(normalize(card.textContent ?? '')).toContain(normalize(expected));
 
       // Tab onto the timestamp — the only tab stop in the document.
       await user.tab();
@@ -705,15 +760,28 @@ describe('Timestamp', () => {
       // 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 () => {
@@ -1171,10 +1239,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 +1255,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/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/useInputStatusIcon.tsx

@@ -40,8 +40,9 @@ import type {FieldStatusVariant} from '../FieldStatus/FieldStatus';
 import type {InputStatus, InputStatusType} from '../Field/types';
 import {useTooltip} from '../Tooltip';
 import {useTranslator} from '../i18n';
-import {colorVars, radiusVars} from '../theme/tokens.stylex';
+import {radiusVars} from '../theme/tokens.stylex';
 import {themeProps} from '../utils/themeProps';
+import {focusOutlineStyles} from '../utils/focusOutline.stylex';
 
 /**
  * Maps each status type to its glyph. Shared so every input shows the same icon
@@ -82,12 +83,8 @@ const styles = stylex.create({
     color: 'inherit',
     cursor: 'pointer',
     borderRadius: radiusVars['--radius-full'],
-    outlineWidth: {default: null, ':focus-visible': '2px'},
-    outlineStyle: {default: null, ':focus-visible': 'solid'},
-    outlineColor: {
-      default: null,
-      ':focus-visible': colorVars['--color-accent'],
-    },
+    // Not the shared offset: this button sits inside the field, and measured at
+    // the standard 3px its ring crosses the field border.
     outlineOffset: {default: null, ':focus-visible': '2px'},
   },
 });
@@ -224,7 +221,10 @@ export function useInputStatusIcon({
           aria-describedby={tooltip.describedBy}
           onClick={handleButtonClick}
           onBlur={handleButtonBlur}
-          {...stylex.props(styles.statusButton)}>
+          {...stylex.props(
+            focusOutlineStyles.focusVisible,
+            styles.statusButton,
+          )}>
           {icon}
         </button>
         {tooltip.renderTooltip(status.message)}