Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

fix(core): announce date/time stepping and localize invalid-value messages (#4363)

Baraa Hamodiaba744cfdc08
diff --git a/.changeset/a11y-time-stepping-announce.md b/.changeset/a11y-time-stepping-announce.md
new file mode 100644
index 0000000000..a6048172cf
--- /dev/null
+++ b/.changeset/a11y-time-stepping-announce.md
@@ -0,0 +1,6 @@
+---
+'@astryxdesign/core': patch
+---
+
+[fix] TimeInput: announce arrow-key time stepping via the polite live region (also in DateTimeInput), localize the "Invalid date"/"Invalid time" live-region messages through the i18n catalog, and use long timezone names in Timestamp's AT-facing aria-label while keeping the short form visible
+@bhamodi
diff --git a/packages/core/locales/en.json b/packages/core/locales/en.json
index 7679fed823..36ad464aaf 100644
--- a/packages/core/locales/en.json
+++ b/packages/core/locales/en.json
@@ -639,6 +639,10 @@
"defaultMessage": "Clear {label}",
"description": "Aria label for the clear-value button in DateInput / DateRangeInput / DateTimeInput. `{label}` is the field's own label so screen readers announce e.g. 'Clear Start date'."
},
+ "@astryx.dateInput.invalidDate": {
+ "defaultMessage": "Invalid date",
+ "description": "Screen-reader-only live-region alert in DateInput / DateTimeInput when the typed date cannot be parsed. The field silently reverts on blur, so this is the only rejection feedback a screen-reader user gets."
+ },
"@astryx.dateTimeInput.timeSuffix": {
"defaultMessage": "{label} time",
"description": "Screen-reader-only accessible name for the time-of-day slot in a DateTimeInput. Example: `Start date time`; reorder freely (e.g. \"time of {label}\")."
@@ -711,6 +715,10 @@
"defaultMessage": "Select a time",
"description": "\"Time\" = clock time (HH:MM), not duration or era. Grey placeholder inside an empty TimeInput field; imperative verb."
},
+ "@astryx.timeInput.invalidTime": {
+ "defaultMessage": "Invalid time",
+ "description": "Screen-reader-only live-region alert in TimeInput / DateTimeInput when the typed time cannot be parsed. \"Time\" = clock time (HH:MM). The field silently reverts on blur, so this is the only rejection feedback a screen-reader user gets."
+ },
"@astryx.topNav.heading.dialogLabel": {
"defaultMessage": "Navigation menu",
"description": "Screen-reader-only accessible name for the dropdown dialog opened from a TopNavHeading's overflow menu. Kept separate from the SideNav sibling."
diff --git a/packages/core/src/DateInput/DateInput.test.tsx b/packages/core/src/DateInput/DateInput.test.tsx
index 916bc55190..060cb1cbc4 100644
--- a/packages/core/src/DateInput/DateInput.test.tsx
+++ b/packages/core/src/DateInput/DateInput.test.tsx
@@ -25,6 +25,7 @@ import {InputGroup} from '../InputGroup';
import {InputGroupText} from '../InputGroup/InputGroupText';
import {defineTheme} from '../theme/defineTheme';
import {generateThemeCSS} from '../theme/generateThemeRules';
+import {InternationalizationProvider} from '../i18n';
function generateThemeTestCSS(theme: Parameters<typeof generateThemeCSS>[0]) {
const {prose, component} = generateThemeCSS(theme);
@@ -170,6 +171,24 @@ describe('DateInput', () => {
expect(screen.queryByText('Invalid date')).not.toBeInTheDocument();
});
+ it('resolves the invalid-date announcement from the i18n catalog', () => {
+ const {container} = render(
+ <InternationalizationProvider
+ locale="en"
+ overrides={{en: {'@astryx.dateInput.invalidDate': 'Ungültiges Datum'}}}>
+ <DateInput label="Date" onChange={() => {}} />
+ </InternationalizationProvider>,
+ );
+
+ fireEvent.change(screen.getByRole('combobox'), {
+ target: {value: '13/45/2024'},
+ });
+
+ expect(within(container).getByRole('alert')).toHaveTextContent(
+ 'Ungültiges Datum',
+ );
+ });
+
it('reverts to previous value on blur when input is invalid', async () => {
const onChange = vi.fn();
render(<DateInput label="Date" value="2026-01-25" onChange={onChange} />);
diff --git a/packages/core/src/DateInput/DateInput.tsx b/packages/core/src/DateInput/DateInput.tsx
index d4ec8f41c5..d1b0ca4e2d 100644
--- a/packages/core/src/DateInput/DateInput.tsx
+++ b/packages/core/src/DateInput/DateInput.tsx
@@ -751,7 +751,7 @@ export function DateInput({
user would get no feedback that their entry was rejected (WCAG 3.3.1).
*/}
<VisuallyHidden as="div" role="alert" aria-live="assertive">
- {!isInputValid ? 'Invalid date' : ''}
+ {!isInputValid ? t('@astryx.dateInput.invalidDate') : ''}
</VisuallyHidden>
{hasClear && value !== undefined && !isEffectivelyDisabled && (
<InputClearButton
diff --git a/packages/core/src/DateTimeInput/DateTimeInput.test.tsx b/packages/core/src/DateTimeInput/DateTimeInput.test.tsx
index 13ef45ba73..e157a76158 100644
--- a/packages/core/src/DateTimeInput/DateTimeInput.test.tsx
+++ b/packages/core/src/DateTimeInput/DateTimeInput.test.tsx
@@ -9,7 +9,7 @@
* SYNC: When DateTimeInput.tsx changes, update tests to match new behavior
*/
-import {describe, it, expect, vi, beforeEach} from 'vitest';
+import {describe, it, expect, vi, beforeEach, afterEach} from 'vitest';
import {render, screen, fireEvent, waitFor} from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import {getButton, queryButton} from '../__tests__/fastRoleQueries';
@@ -17,6 +17,16 @@ import {DateTimeInput} from './DateTimeInput';
import type {ISODateTimeString} from './DateTimeInput';
import {defineTheme} from '../theme/defineTheme';
import {generateThemeCSS} from '../theme/generateThemeRules';
+import {InternationalizationProvider} from '../i18n';
+import {__resetLiveRegionsForTest} from '../hooks/useAnnounce';
+
+function politeRegion(): HTMLElement | null {
+ return document.querySelector('[data-astryx-live-region="polite"]');
+}
+
+afterEach(() => {
+ __resetLiveRegionsForTest();
+});
function generateThemeTestCSS(theme: Parameters<typeof generateThemeCSS>[0]) {
const {prose, component} = generateThemeCSS(theme);
@@ -626,6 +636,35 @@ describe('DateTimeInput', () => {
expect(screen.getByText('Invalid time')).toBeInTheDocument();
});
+
+ it('resolves the invalid date and time announcements from the i18n catalog', () => {
+ render(
+ <InternationalizationProvider
+ locale="en"
+ overrides={{
+ en: {
+ '@astryx.dateInput.invalidDate': 'Ungültiges Datum',
+ '@astryx.timeInput.invalidTime': 'Ungültige Zeit',
+ },
+ }}>
+ <DateTimeInput
+ label="Meeting"
+ value={'2026-03-15T10:00' as ISODateTimeString}
+ onChange={() => {}}
+ />
+ </InternationalizationProvider>,
+ );
+
+ fireEvent.change(screen.getByRole('combobox'), {
+ target: {value: '13/45/2024'},
+ });
+ expect(screen.getByText('Ungültiges Datum')).toBeInTheDocument();
+
+ fireEvent.change(screen.getByLabelText('Meeting time'), {
+ target: {value: '99:99 zz'},
+ });
+ expect(screen.getByText('Ungültige Zeit')).toBeInTheDocument();
+ });
});
describe('disabledMessage', () => {
// jsdom does not implement the Popover API used by the tooltip, so mock
@@ -819,6 +858,45 @@ describe('DateTimeInput', () => {
expect(onChange).toHaveBeenCalledTimes(1);
expect(onChange.mock.calls[0][0]).toContain('14:31');
});
+
+ // 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 () => {
+ render(
+ <DateTimeInput
+ label="Meeting"
+ value={'2026-03-15T14:30' as ISODateTimeString}
+ onChange={() => {}}
+ />,
+ );
+
+ fireEvent.keyDown(screen.getByLabelText('Meeting time'), {
+ key: 'ArrowUp',
+ });
+
+ await waitFor(() => {
+ expect(politeRegion()).toHaveTextContent('2:31 PM');
+ });
+ });
+
+ it('politely announces the new time after ArrowDown stepping', async () => {
+ render(
+ <DateTimeInput
+ label="Meeting"
+ value={'2026-03-15T14:30' as ISODateTimeString}
+ onChange={() => {}}
+ />,
+ );
+
+ fireEvent.keyDown(screen.getByLabelText('Meeting time'), {
+ key: 'ArrowDown',
+ });
+
+ await waitFor(() => {
+ expect(politeRegion()).toHaveTextContent('2:29 PM');
+ });
+ });
});
describe('weekStartsOn', () => {
diff --git a/packages/core/src/DateTimeInput/DateTimeInput.tsx b/packages/core/src/DateTimeInput/DateTimeInput.tsx
index 0722d31c40..b20cfc17b5 100644
--- a/packages/core/src/DateTimeInput/DateTimeInput.tsx
+++ b/packages/core/src/DateTimeInput/DateTimeInput.tsx
@@ -4,7 +4,7 @@
/**
* @file DateTimeInput.tsx
- * @input Uses React, Field, Calendar, usePopover, time parsing utilities
+ * @input Uses React, Field, Calendar, usePopover, useAnnounce, time parsing utilities
* @output Exports DateTimeInput component, DateTimeInputProps
* @position Core implementation; consumed by index.ts, tested by DateTimeInput.test.tsx
*
@@ -82,6 +82,7 @@ import {
import type {BaseProps} from '../BaseProps';
import type {SizeValue} from '../utils/types';
+import {useAnnounce} from '../hooks/useAnnounce';
import {useSize} from '../SizeContext/SizeContext';
import {themeProps} from '../utils/themeProps';
import {focusOutlineStyles} from '../utils/focusOutline.stylex';
@@ -446,6 +447,10 @@ export function DateTimeInput({
...rest
}: DateTimeInputProps) {
const t = useTranslator();
+ // Speaks arrow-key stepping results through the persistent live regions:
+ // stepping programmatically rewrites a plain textbox's value, which screen
+ // readers do not announce on their own (WCAG 4.1.2).
+ const announce = useAnnounce();
const placeholder =
placeholderFromProps ?? t('@astryx.dateTimeInput.placeholder');
const timePlaceholder =
@@ -851,11 +856,23 @@ export function DateTimeInput({
const combined = combineDateTime(valueParts.date, newTime);
if (combined) {
fireChange(combined);
+ // Screen readers do not announce the programmatic value rewrite,
+ // so speak the new time explicitly (WCAG 4.1.2).
+ announce(formatDisplayTime(newTime, hasSeconds));
}
}
}
},
- [valueParts, hasSeconds, timeIncrement, timeMin, timeMax, fireChange],
+ [
+ valueParts,
+ hasSeconds,
+ timeIncrement,
+ timeMin,
+ timeMax,
+ fireChange,
+ announce,
+ formatDisplayTime,
+ ],
);
// --- Clear ---
@@ -985,7 +1002,7 @@ export function DateTimeInput({
rejected (WCAG 3.3.1).
*/}
<VisuallyHidden as="div" role="alert" aria-live="assertive">
- {!isDateInputValid ? 'Invalid date' : ''}
+ {!isDateInputValid ? t('@astryx.dateInput.invalidDate') : ''}
</VisuallyHidden>
{hasClear && value !== undefined && !isEffectivelyDisabled && (
<InputClearButton
@@ -1058,7 +1075,7 @@ export function DateTimeInput({
technology (WCAG 3.3.1).
*/}
<VisuallyHidden as="div" role="alert" aria-live="assertive">
- {!isTimeInputValid ? 'Invalid time' : ''}
+ {!isTimeInputValid ? t('@astryx.timeInput.invalidTime') : ''}
</VisuallyHidden>
</div>
</div>
diff --git a/packages/core/src/TimeInput/TimeInput.test.tsx b/packages/core/src/TimeInput/TimeInput.test.tsx
index d89c03ef00..06e44000e6 100644
--- a/packages/core/src/TimeInput/TimeInput.test.tsx
+++ b/packages/core/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();
diff --git a/packages/core/src/TimeInput/TimeInput.tsx b/packages/core/src/TimeInput/TimeInput.tsx
index 9890705213..bc9cbe4e98 100644
--- a/packages/core/src/TimeInput/TimeInput.tsx
+++ b/packages/core/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 && (
diff --git a/packages/core/src/Timestamp/Timestamp.test.tsx b/packages/core/src/Timestamp/Timestamp.test.tsx
index b35e76a9b7..3a29034010 100644
--- a/packages/core/src/Timestamp/Timestamp.test.tsx
+++ b/packages/core/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')),
);
});
});
diff --git a/packages/core/src/Timestamp/Timestamp.tsx b/packages/core/src/Timestamp/Timestamp.tsx
index 92cdc5c2b8..cec0f4ef75 100644
--- a/packages/core/src/Timestamp/Timestamp.tsx
+++ b/packages/core/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
diff --git a/packages/core/src/Timestamp/formatInstant.ts b/packages/core/src/Timestamp/formatInstant.ts
index 6938dd5114..906f443b06 100644
--- a/packages/core/src/Timestamp/formatInstant.ts
+++ b/packages/core/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);