Skip to content

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

TypeScript

fix(core): make Timestamp tooltip keyboard-reachable (#4007)

Baraa Hamodieba4f342cab6
diff --git a/.changeset/timestamp-tooltip-keyboard.md b/.changeset/timestamp-tooltip-keyboard.md
new file mode 100644
index 0000000000..1cd846ec83
--- /dev/null
+++ b/.changeset/timestamp-tooltip-keyboard.md
@@ -0,0 +1,6 @@
+---
+'@astryxdesign/core': patch
+---
+
+[fix] Timestamp: the absolute-time tooltip is now reachable by keyboard — the timestamp is focusable while a tooltip is attached, per WCAG content-on-hover requirements.
+@bhamodi
diff --git a/packages/core/src/Timestamp/Timestamp.test.tsx b/packages/core/src/Timestamp/Timestamp.test.tsx
index 8c65dd37e6..d412f881b6 100644
--- a/packages/core/src/Timestamp/Timestamp.test.tsx
+++ b/packages/core/src/Timestamp/Timestamp.test.tsx
@@ -1,7 +1,8 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
import {describe, it, expect, vi, beforeEach, afterEach} from 'vitest';
-import {render, screen, act} from '@testing-library/react';
+import {render, screen, act, waitFor} from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
import {Timestamp} from './Timestamp';
describe('Timestamp', () => {
@@ -41,9 +42,7 @@ describe('Timestamp', () => {
);
expect(screen.getByText('59 minutes ago')).toBeInTheDocument();
- rerender(
- <Timestamp value={Date.now() / 1000 - 86399} format="relative" />,
- );
+ rerender(<Timestamp value={Date.now() / 1000 - 86399} format="relative" />);
expect(screen.getByText('23 hours ago')).toBeInTheDocument();
rerender(
@@ -52,9 +51,7 @@ describe('Timestamp', () => {
expect(screen.getByText('29 days ago')).toBeInTheDocument();
// Same guarantee on the future side.
- rerender(
- <Timestamp value={Date.now() / 1000 + 3599} format="relative" />,
- );
+ rerender(<Timestamp value={Date.now() / 1000 + 3599} format="relative" />);
expect(screen.getByText('in 59 minutes')).toBeInTheDocument();
});
@@ -342,4 +339,120 @@ describe('Timestamp', () => {
warn.mockRestore();
}
});
+
+ // --- Tooltip keyboard reachability (WCAG 1.4.13 / 2.1.1) ---
+
+ describe('tooltip keyboard reachability', () => {
+ const originalMatches = HTMLElement.prototype.matches;
+ const originalShowPopover = HTMLElement.prototype.showPopover;
+ const originalHidePopover = HTMLElement.prototype.hidePopover;
+
+ beforeEach(() => {
+ // The tooltip is lazy-loaded via a dynamic import; real timers let the
+ // import promise and RTL's waitFor resolve naturally (the outer
+ // beforeEach installs fake timers, which would stall them).
+ vi.useRealTimers();
+
+ // Mock the Popover API, which jsdom does not implement.
+ HTMLElement.prototype.showPopover = vi.fn();
+ HTMLElement.prototype.hidePopover = vi.fn();
+
+ // jsdom does not derive :focus-visible from keyboard focus for a <time>
+ // element; treat the focused element as focus-visible so the tooltip's
+ // keyboard-focus path can be exercised.
+ // eslint-disable-next-line @typescript-eslint/no-explicit-any
+ (HTMLElement.prototype as any).matches = function (
+ selector: string,
+ ): boolean {
+ if (selector === ':focus-visible') {
+ return this === document.activeElement;
+ }
+ return originalMatches.call(this, selector);
+ };
+ });
+
+ afterEach(() => {
+ // eslint-disable-next-line @typescript-eslint/no-explicit-any
+ (HTMLElement.prototype as any).matches = originalMatches;
+ HTMLElement.prototype.showPopover = originalShowPopover;
+ HTMLElement.prototype.hidePopover = originalHidePopover;
+ });
+
+ it('makes the <time> element focusable while the tooltip is attached', () => {
+ render(
+ <Timestamp
+ value={Date.now() / 1000 - 3600}
+ format="relative"
+ data-testid="ts"
+ />,
+ );
+ expect(screen.getByTestId('ts')).toHaveAttribute('tabindex', '0');
+ });
+
+ it('shows the tooltip when the timestamp receives keyboard focus', async () => {
+ const user = userEvent.setup();
+ render(
+ <Timestamp
+ value={Date.now() / 1000 - 3600}
+ format="relative"
+ data-testid="ts"
+ />,
+ );
+ const el = screen.getByTestId('ts');
+
+ // Wait for the lazy-loaded tooltip layer to mount and confirm it
+ // carries the full absolute time (same string as the aria-label).
+ // Compare with normalized whitespace: Intl output can contain narrow
+ // no-break spaces that jest-dom's matcher normalization would break on.
+ const layer = await screen.findByRole('tooltip', {hidden: true});
+ const normalize = (s: string) => s.replace(/\s+/g, ' ');
+ expect(normalize(layer.textContent ?? '')).toContain(
+ normalize(el.getAttribute('aria-label') ?? '\0'),
+ );
+
+ // Tab onto the timestamp — the only tab stop in the document.
+ await user.tab();
+ expect(el).toHaveFocus();
+ await waitFor(() => {
+ expect(HTMLElement.prototype.showPopover).toHaveBeenCalled();
+ });
+ });
+
+ it('does not add a tab stop when the tooltip is disabled', () => {
+ render(
+ <Timestamp
+ value={Date.now() / 1000 - 3600}
+ format="relative"
+ hasTooltip={false}
+ data-testid="ts"
+ />,
+ );
+ expect(screen.getByTestId('ts')).not.toHaveAttribute('tabindex');
+ });
+
+ it('does not add a tab stop for absolute formats (no tooltip)', () => {
+ render(
+ <Timestamp
+ value="2026-02-19T17:00:00Z"
+ format="date_time"
+ data-testid="ts"
+ />,
+ );
+ expect(screen.getByTestId('ts')).not.toHaveAttribute('tabindex');
+ });
+
+ it('keeps the full absolute aria-label while the tooltip is attached', () => {
+ render(
+ <Timestamp
+ value={Date.now() / 1000 - 3600}
+ format="relative"
+ data-testid="ts"
+ />,
+ );
+ const label = screen.getByTestId('ts').getAttribute('aria-label');
+ expect(label).toBeTruthy();
+ // The label is the full absolute string, not the relative text.
+ expect(label).not.toContain('ago');
+ });
+ });
});
diff --git a/packages/core/src/Timestamp/Timestamp.tsx b/packages/core/src/Timestamp/Timestamp.tsx
index 66953f9a48..d4bd34fefa 100644
--- a/packages/core/src/Timestamp/Timestamp.tsx
+++ b/packages/core/src/Timestamp/Timestamp.tsx
@@ -23,6 +23,7 @@ import type {TextType, TextSize, TextColor, TextWeight} from '../theme/types';
import {mergeProps, mergeRefs} from '../utils';
import type {BaseProps} from '../BaseProps';
import {themeProps} from '../utils/themeProps';
+import {colorVars} from '../theme/tokens.stylex';
const LazyXDSTooltip = lazy(async () =>
import('../Tooltip/Tooltip').then(mod => ({default: mod.Tooltip})),
@@ -118,6 +119,18 @@ const styles = stylex.create({
color: 'inherit',
fontWeight: 'inherit',
},
+ // Visible focus ring for the tooltip tab stop, matching the repo-wide
+ // focus-visible outline treatment (see Token, Thumbnail).
+ focusable: {
+ outline: {
+ default: null,
+ ':focus-visible': `2px solid ${colorVars['--color-accent']}`,
+ },
+ outlineOffset: {
+ default: '0',
+ ':focus-visible': '2px',
+ },
+ },
});
// =============================================================================
@@ -431,8 +444,15 @@ export function Timestamp({
aria-label={
effectiveFormat === 'relative' ? fullAbsoluteText : undefined
}
+ // The absolute-time tooltip is anchored here with the default 'auto'
+ // focus trigger, which only activates on focusable anchors. A bare
+ // <time> is not focusable, so without a tab stop sighted keyboard
+ // users could never reveal the tooltip (WCAG 1.4.13 / 2.1.1). Only
+ // add the tab stop while a tooltip is actually attached — no
+ // gratuitous tab stops otherwise.
+ tabIndex={showTooltip ? 0 : undefined}
data-testid={testId}
- {...stylex.props(styles.time)}>
+ {...stylex.props(styles.time, showTooltip && styles.focusable)}>
{displayText}
</time>
</Text>