@astryxdesign/core 0.4.0 → 0.4.1

package/src/TimeInput/TimeInput.test.tsx

@@ -14,6 +14,7 @@ import {render, screen, fireEvent, waitFor} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import {TimeInput} from './TimeInput';
 import {InputGroup, InputGroupText} from '../InputGroup';
+import {InternationalizationProvider} from '../i18n';
 import type {ISOTimeString} from '../utils';
 import {__resetLiveRegionsForTest} from '../hooks/useAnnounce';
 
@@ -209,6 +210,59 @@ describe('TimeInput', () => {
     expect(screen.queryByText('Invalid time')).not.toBeInTheDocument();
   });
 
+  it('resolves the invalid-time announcement from the i18n catalog', () => {
+    render(
+      <InternationalizationProvider
+        locale="en"
+        overrides={{en: {'@astryx.timeInput.invalidTime': 'Ungültige Zeit'}}}>
+        <TimeInput label="Time" onChange={() => {}} />
+      </InternationalizationProvider>,
+    );
+
+    fireEvent.change(screen.getByRole('textbox'), {target: {value: '25:99'}});
+
+    expect(screen.getByRole('alert')).toHaveTextContent('Ungültige Zeit');
+  });
+
+  // Arrow-key stepping mutates a plain textbox programmatically, and screen
+  // readers do not announce programmatic textbox changes — the new value must
+  // be announced through the polite live region (WCAG 4.1.2).
+  it('politely announces the new time after ArrowUp stepping', async () => {
+    const onChange = vi.fn();
+    render(
+      <TimeInput
+        label="Time"
+        value={'14:30' as ISOTimeString}
+        onChange={onChange}
+      />,
+    );
+
+    fireEvent.keyDown(screen.getByRole('textbox'), {key: 'ArrowUp'});
+
+    expect(onChange).toHaveBeenCalledWith('14:31');
+    await waitFor(() => {
+      expect(politeRegion()).toHaveTextContent('2:31 PM');
+    });
+  });
+
+  it('politely announces the new time after ArrowDown stepping', async () => {
+    const onChange = vi.fn();
+    render(
+      <TimeInput
+        label="Time"
+        value={'14:30' as ISOTimeString}
+        onChange={onChange}
+      />,
+    );
+
+    fireEvent.keyDown(screen.getByRole('textbox'), {key: 'ArrowDown'});
+
+    expect(onChange).toHaveBeenCalledWith('14:29');
+    await waitFor(() => {
+      expect(politeRegion()).toHaveTextContent('2:29 PM');
+    });
+  });
+
   it('calls onChange on blur when input is valid', async () => {
     const user = userEvent.setup();
     const onChange = vi.fn();

package/src/TimeInput/TimeInput.tsx

@@ -558,10 +558,25 @@ export function TimeInput({
         // Check if within range
         if (isTimeInRange(newTime, min, max)) {
           fireChange(newTime);
+          // Stepping programmatically rewrites a plain textbox's value, and
+          // screen readers do not announce programmatic textbox changes — the
+          // new value must be spoken explicitly or stepping is silent
+          // (WCAG 4.1.2).
+          announce(formatDisplayTime(newTime, hasSeconds));
         }
       }
     },
-    [value, hasSeconds, increment, min, max, fireChange, isDisabled],
+    [
+      value,
+      hasSeconds,
+      increment,
+      min,
+      max,
+      fireChange,
+      isDisabled,
+      announce,
+      formatDisplayTime,
+    ],
   );
 
   // Handle clear button click
@@ -659,7 +674,7 @@ export function TimeInput({
           user would get no feedback that their entry was rejected (WCAG 3.3.1).
         */}
       <VisuallyHidden as="div" role="alert" aria-live="assertive">
-        {!isInputValid ? 'Invalid time' : ''}
+        {!isInputValid ? t('@astryx.timeInput.invalidTime') : ''}
       </VisuallyHidden>
       {isBusy && <Spinner size="sm" />}
       {hasClear && value && !isDisabled && (

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/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)}