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.mdnew file mode 100644index 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.+@bhamodidiff --git a/packages/core/src/Timestamp/Timestamp.test.tsx b/packages/core/src/Timestamp/Timestamp.test.tsxindex 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.tsxindex 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>