An open source design system that's fully customizable and agent ready
TypeScript
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
* @file Text.test.tsx
* Tests for Text component
*/
import {act, fireEvent, render, screen, waitFor} from '@testing-library/react';
import {describe, it, expect, vi} from 'vitest';
import userEvent from '@testing-library/user-event';
import {Text} from './Text';
// Loaded up front, so the truncation tooltip's lazy import resolves at once.
import '../Tooltip/Tooltip';
import type {TextType} from './Text';
import type {TextColor} from '../theme/types';
// jsdom does not resolve var(); the browser spec checks the resolved value.
// Untruncated text reads the private container override, else break-word.
const DEFAULT_WRAP = 'var(--_astryx-text-overflow-wrap,break-word)';
const wrapOf = (element: Element) =>
getComputedStyle(element).overflowWrap.replace(/\s/g, '');
describe('Text', () => {
describe('rendering', () => {
it('renders without type prop (defaults to body)', () => {
render(<Text>Default body text</Text>);
expect(screen.getByText('Default body text')).toBeInTheDocument();
});
it('renders children correctly', () => {
render(<Text type="body">Hello World</Text>);
expect(screen.getByText('Hello World')).toBeInTheDocument();
});
it('keeps a forwarded ref attached across rerenders', () => {
const ref = vi.fn();
const {rerender} = render(
<Text ref={ref} type="body">
Before
</Text>,
);
const element = screen.getByText('Before');
expect(ref).toHaveBeenLastCalledWith(element);
ref.mockClear();
rerender(
<Text ref={ref} type="body">
After
</Text>,
);
expect(ref).not.toHaveBeenCalled();
expect(screen.getByText('After')).toBe(element);
});
it('renders as span by default', () => {
render(<Text type="body">Text</Text>);
const element = screen.getByText('Text');
expect(element.tagName).toBe('SPAN');
});
it('renders as paragraph when as="p"', () => {
render(
<Text type="body" as="p">
Paragraph
</Text>,
);
const element = screen.getByText('Paragraph');
expect(element.tagName).toBe('P');
});
it('renders as div when as="div"', () => {
render(
<Text type="body" as="div">
Div
</Text>,
);
const element = screen.getByText('Div');
expect(element.tagName).toBe('DIV');
});
it('renders as label when as="label"', () => {
render(
<Text type="body" as="label">
Label
</Text>,
);
const element = screen.getByText('Label');
expect(element.tagName).toBe('LABEL');
});
});
describe('types', () => {
it('renders body type', () => {
render(<Text type="body">Body text</Text>);
expect(screen.getByText('Body text')).toBeInTheDocument();
});
it('renders large type', () => {
render(<Text type="large">Large text</Text>);
expect(screen.getByText('Large text')).toBeInTheDocument();
});
it('renders supporting type', () => {
render(<Text type="supporting">Supporting text</Text>);
expect(screen.getByText('Supporting text')).toBeInTheDocument();
});
it('renders code type', () => {
render(<Text type="code">const x = 1;</Text>);
expect(screen.getByText('const x = 1;')).toBeInTheDocument();
});
it('renders label type', () => {
render(<Text type="label">Label text</Text>);
expect(screen.getByText('Label text')).toBeInTheDocument();
});
});
describe('props', () => {
it('forwards additional props', () => {
render(
<Text type="body" data-testid="custom-text">
Text
</Text>,
);
expect(screen.getByTestId('custom-text')).toBeInTheDocument();
});
it('accepts color prop', () => {
render(
<Text type="body" color="secondary">
Secondary text
</Text>,
);
expect(screen.getByText('Secondary text')).toBeInTheDocument();
});
it('accepts weight prop', () => {
render(
<Text type="body" weight="bold">
Bold text
</Text>,
);
expect(screen.getByText('Bold text')).toBeInTheDocument();
});
it('reflects explicit size overrides for styling and theming', () => {
render(
<Text type="code" size="2xs">
Tiny code
</Text>,
);
const element = screen.getByText('Tiny code');
expect(element).toHaveAttribute('data-size', '2xs');
});
it('accepts display prop', () => {
render(
<Text type="body" display="block">
Block text
</Text>,
);
expect(screen.getByText('Block text')).toBeInTheDocument();
});
it('accepts hasStrikethrough prop', () => {
render(
<Text type="body" hasStrikethrough>
Strikethrough text
</Text>,
);
expect(screen.getByText('Strikethrough text')).toBeInTheDocument();
});
it('accepts hasTabularNumbers prop', () => {
render(
<Text type="body" hasTabularNumbers>
12345
</Text>,
);
expect(screen.getByText('12345')).toBeInTheDocument();
});
it('accepts hasCapsize prop', () => {
render(
<Text type="body" hasCapsize>
Capsize text
</Text>,
);
expect(screen.getByText('Capsize text')).toBeInTheDocument();
});
it('accepts textWrap prop', () => {
render(
<Text type="body" textWrap="balance">
Balanced text wrap
</Text>,
);
expect(screen.getByText('Balanced text wrap')).toBeInTheDocument();
});
it('accepts maxLines prop', () => {
render(
<Text type="body" maxLines={2}>
This is a long text that should be truncated to two lines
</Text>,
);
expect(
screen.getByText(
'This is a long text that should be truncated to two lines',
),
).toBeInTheDocument();
});
it('accepts wordBreak prop', () => {
render(
<Text type="body" maxLines={1} wordBreak="break-word">
Text with word break
</Text>,
);
expect(screen.getByText('Text with word break')).toBeInTheDocument();
});
it('accepts hasTruncateTooltip=false to disable tooltip', () => {
render(
<Text type="body" maxLines={1} hasTruncateTooltip={false}>
No tooltip
</Text>,
);
expect(screen.getByText('No tooltip')).toBeInTheDocument();
});
});
// Text FR3 (spec:AST-020 FR1, WCAG 2.2 1.4.10): a token longer than its line
// wraps in text that is not truncated; truncation keeps its own treatment.
describe('long unbroken tokens', () => {
const token =
'https://example.com/aVeryLongUnbrokenTokenThatIsWiderThan320px';
it('wraps them in inline and block text that is not truncated', () => {
render(
<>
<Text>{token}</Text>
<Text display="block">{`${token}/block`}</Text>
</>,
);
expect(wrapOf(screen.getByText(token))).toBe(DEFAULT_WRAP);
expect(wrapOf(screen.getByText(`${token}/block`))).toBe(DEFAULT_WRAP);
});
it('leaves single-line truncation clipping on one line', () => {
render(<Text maxLines={1}>{token}</Text>);
const style = getComputedStyle(screen.getByText(token));
expect(style.whiteSpace).toBe('nowrap');
expect(style.textOverflow).toBe('ellipsis');
expect(style.wordBreak).toBe('break-all');
expect(style.overflowWrap).not.toBe('break-word');
});
});
it('renders the stable target and type data attribute for theme targeting', () => {
render(<Text type="body">Themed Text</Text>);
const element = screen.getByText('Themed Text');
expect(element.className).toContain('astryx-text');
expect(element).toHaveAttribute('data-type', 'body');
});
});
describe('Text custom types', () => {
it('renders custom text types with body fallback styles', () => {
render(<Text type={'hero' as TextType}>Custom</Text>);
const el = screen.getByText('Custom');
expect(el).toBeInTheDocument();
expect(el.className).toContain('astryx-text');
expect(el).toHaveAttribute('data-type', 'hero');
});
it('applies primary color to custom types by default', () => {
render(<Text type={'caption' as TextType}>Caption</Text>);
expect(screen.getByText('Caption')).toHaveAttribute(
'data-color',
'primary',
);
});
it('allows color override on custom types', () => {
render(
<Text type={'hero' as TextType} color="secondary">
Muted
</Text>,
);
expect(screen.getByText('Muted')).toHaveAttribute(
'data-color',
'secondary',
);
});
});
describe('Text custom colors', () => {
it('reflects a custom color for theme CSS to target', () => {
// A theme adds a custom color through TextColorMap augmentation and
// defineTheme. The rendered element keeps the stable Text target and
// reflects the custom value as data-color so the generated theme selector
// can reach it without a collision-prone bare class.
render(<Text color={'brand' as TextColor}>Branded</Text>);
const el = screen.getByText('Branded');
expect(el.className).toContain('astryx-text');
expect(el).toHaveAttribute('data-color', 'brand');
});
it('does not crash on a custom color (falls back to the primary StyleX baseline)', () => {
// colorStyles has no entry for a custom color; the component must resolve a
// built-in baseline instead of indexing undefined. Built-in `primary` is
// the baseline, so both share its StyleX color class.
render(
<>
<Text color={'brand' as TextColor}>Custom</Text>
<Text color="primary">Builtin</Text>
</>,
);
const custom = screen.getByText('Custom');
const builtin = screen.getByText('Builtin');
// Neither throws, and the custom color reuses primary's baseline StyleX
// class (the real color comes from theme CSS via `data-color="brand"`).
const primaryAtomic = builtin.className
.split(/\s+/)
.filter(c => c.startsWith('x'));
expect(primaryAtomic.length).toBeGreaterThan(0);
for (const cls of primaryAtomic) {
expect(custom.className).toContain(cls);
}
});
it('still applies built-in colors directly', () => {
render(<Text color="accent">Accent</Text>);
expect(screen.getByText('Accent')).toHaveAttribute('data-color', 'accent');
});
});
// A truncated Text rendered its own Tooltip AND set `title` with the same
// string, so the browser drew a second, unstyled tooltip on top of ours.
describe('truncated text shows one tooltip, not two', () => {
function withOverflow() {
const proto = window.HTMLElement.prototype;
const original = {
scrollWidth: Object.getOwnPropertyDescriptor(proto, 'scrollWidth'),
offsetWidth: Object.getOwnPropertyDescriptor(proto, 'offsetWidth'),
};
Object.defineProperty(proto, 'scrollWidth', {
configurable: true,
get: () => 400,
});
Object.defineProperty(proto, 'offsetWidth', {
configurable: true,
get: () => 100,
});
return () => {
if (original.scrollWidth) {
Object.defineProperty(proto, 'scrollWidth', original.scrollWidth);
}
if (original.offsetWidth) {
Object.defineProperty(proto, 'offsetWidth', original.offsetWidth);
}
};
}
it('leaves the native title to the tooltip it already renders', () => {
const restore = withOverflow();
try {
render(
<Text type="body" maxLines={1}>
A label far wider than the space it has been given
</Text>,
);
expect(
screen.getByText('A label far wider than the space it has been given'),
).not.toHaveAttribute('title');
} finally {
restore();
}
});
});
// With hasTruncateTooltip={false} nothing reads the measured overflow, so a
// long table of truncated cells must not pay a layout read per cell.
function countScrollWidthReads(run: () => void): number {
const proto = window.HTMLElement.prototype;
const original = Object.getOwnPropertyDescriptor(proto, 'scrollWidth');
let reads = 0;
Object.defineProperty(proto, 'scrollWidth', {
configurable: true,
get() {
reads += 1;
return 0;
},
});
try {
run();
} finally {
if (original) {
Object.defineProperty(proto, 'scrollWidth', original);
} else {
delete (proto as {scrollWidth?: number}).scrollWidth;
}
}
return reads;
}
describe('Text maxLines without a truncation tooltip', () => {
it('takes no truncation measurement when hasTruncateTooltip is false', () => {
const reads = countScrollWidthReads(() => {
render(
<>
{Array.from({length: 20}, (_, index) => (
<Text
type="body"
maxLines={1}
hasTruncateTooltip={false}
key={index}>
Cell {index} with text far wider than its column
</Text>
))}
</>,
);
});
expect(reads).toBe(0);
});
it('still measures when the tooltip is enabled', () => {
const reads = countScrollWidthReads(() => {
render(
<Text type="body" maxLines={1}>
Text far wider than its column
</Text>,
);
});
expect(reads).toBeGreaterThan(0);
});
});
describe('Text keeps its children mounted when maxLines changes', () => {
it('keeps the same child elements, focus, and input values across a clamp toggle', () => {
const {rerender} = render(
<Text maxLines={2} hasTruncateTooltip={false}>
Lead text <input aria-label="Note" defaultValue="" />
</Text>,
);
const input = screen.getByRole<HTMLInputElement>('textbox', {
name: 'Note',
});
input.value = 'typed';
input.focus();
rerender(
<Text maxLines={0} hasTruncateTooltip={false}>
Lead text <input aria-label="Note" defaultValue="" />
</Text>,
);
const after = screen.getByRole<HTMLInputElement>('textbox', {
name: 'Note',
});
expect(after).toBe(input);
expect(after.value).toBe('typed');
expect(document.activeElement).toBe(after);
rerender(
<Text maxLines={2} hasTruncateTooltip={false}>
Lead text <input aria-label="Note" defaultValue="" />
</Text>,
);
expect(screen.getByRole('textbox', {name: 'Note'})).toBe(input);
});
});
// A page of truncated text mounted one closed tooltip layer per element at
// load. The tooltip now mounts on the first hover, tap or focus, and that
// interaction opens it as it would once mounted.
describe('the truncation tooltip mounts on the first interaction', () => {
const LABEL = 'A label far wider than the space it has been given';
function withOverflowAndPopover() {
const proto = window.HTMLElement.prototype;
const original = {
scrollWidth: Object.getOwnPropertyDescriptor(proto, 'scrollWidth'),
offsetWidth: Object.getOwnPropertyDescriptor(proto, 'offsetWidth'),
showPopover: proto.showPopover,
hidePopover: proto.hidePopover,
};
Object.defineProperty(proto, 'scrollWidth', {
configurable: true,
get: () => 400,
});
Object.defineProperty(proto, 'offsetWidth', {
configurable: true,
get: () => 100,
});
const showPopover = vi.fn();
const hidePopover = vi.fn();
proto.showPopover = showPopover;
proto.hidePopover = hidePopover;
return {
showPopover,
hidePopover,
restore: () => {
if (original.scrollWidth) {
Object.defineProperty(proto, 'scrollWidth', original.scrollWidth);
}
if (original.offsetWidth) {
Object.defineProperty(proto, 'offsetWidth', original.offsetWidth);
}
proto.showPopover = original.showPopover;
proto.hidePopover = original.hidePopover;
},
};
}
it('mounts no tooltip layer and no description before any interaction', async () => {
const {restore} = withOverflowAndPopover();
try {
render(
<Text type="body" maxLines={1}>
{LABEL}
</Text>,
);
// Let a lazily loaded tooltip settle, if one were mounting.
await act(async () => {
await new Promise(resolve => setTimeout(resolve, 300));
});
expect(screen.queryByRole('tooltip', {hidden: true})).toBeNull();
expect(screen.getByText(LABEL)).not.toHaveAttribute('aria-describedby');
} finally {
restore();
}
});
it('mounts the tooltip on the first hover and opens it after the hover delay', async () => {
const {showPopover, restore} = withOverflowAndPopover();
try {
render(
<Text type="body" maxLines={1}>
{LABEL}
</Text>,
);
const text = screen.getByText(LABEL);
fireEvent.pointerEnter(text, {pointerType: 'mouse'});
await waitFor(
() => {
expect(screen.queryByRole('tooltip', {hidden: true})).not.toBeNull();
},
{timeout: 3000},
);
await waitFor(
() => {
expect(showPopover).toHaveBeenCalled();
},
{timeout: 3000},
);
expect(text.getAttribute('aria-describedby')).toBe(
screen.getByRole('tooltip', {hidden: true}).id,
);
} finally {
restore();
}
});
it('opens on the first hover after the hover delay, not later', async () => {
const {showPopover, restore} = withOverflowAndPopover();
try {
render(
<Text type="body" maxLines={1}>
{LABEL}
</Text>,
);
// Truncation is measured and the Tooltip module loads.
await act(async () => {
await new Promise(resolve => setTimeout(resolve, 50));
});
vi.useFakeTimers();
const text = screen.getByText(LABEL);
act(() => {
fireEvent.pointerEnter(text, {pointerType: 'mouse'});
fireEvent.mouseEnter(text);
});
act(() => {
vi.advanceTimersByTime(199);
});
expect(showPopover).not.toHaveBeenCalled();
act(() => {
vi.advanceTimersByTime(1);
});
expect(showPopover).toHaveBeenCalled();
} finally {
vi.useRealTimers();
restore();
}
});
it('opens no tooltip when the pointer leaves before the hover delay ends', async () => {
const {showPopover, restore} = withOverflowAndPopover();
try {
render(
<Text type="body" maxLines={1}>
{LABEL}
</Text>,
);
const text = screen.getByText(LABEL);
fireEvent.pointerEnter(text, {pointerType: 'mouse'});
// A browser follows a mouse's pointerleave with mouseleave.
fireEvent.pointerLeave(text, {pointerType: 'mouse'});
fireEvent.mouseLeave(text);
await waitFor(
() => {
expect(screen.queryByRole('tooltip', {hidden: true})).not.toBeNull();
},
{timeout: 3000},
);
await act(async () => {
await new Promise(resolve => setTimeout(resolve, 300));
});
expect(showPopover).not.toHaveBeenCalled();
} finally {
restore();
}
});
// A finger's arrival is not yet a tap: only the tap's click mounts the
// tooltip, and the touch trigger answers it, arming the outside dismissal.
function tap(element: Element) {
fireEvent.pointerDown(element, {pointerType: 'touch'});
fireEvent.pointerUp(element, {pointerType: 'touch'});
fireEvent.click(element);
}
it('opens on the tap that mounts it, and a tap outside closes it', async () => {
const {showPopover, hidePopover, restore} = withOverflowAndPopover();
try {
render(
<>
<Text type="body" maxLines={1}>
{LABEL}
</Text>
<button type="button">Elsewhere</button>
</>,
);
const text = screen.getByText(LABEL);
fireEvent.pointerEnter(text, {pointerType: 'touch'});
tap(text);
await waitFor(
() => {
expect(showPopover).toHaveBeenCalled();
},
{timeout: 3000},
);
tap(screen.getByRole('button', {name: 'Elsewhere'}));
await waitFor(
() => {
expect(hidePopover).toHaveBeenCalled();
},
{timeout: 3000},
);
} finally {
restore();
}
});
// Focus inside the clamped text mounts the tooltip. Whether it then opens
// is Tooltip's own focus rule: focus on a descendant of a trigger that is
// not itself focusable does not open it.
it('mounts on keyboard focus inside the clamped text', async () => {
const {restore} = withOverflowAndPopover();
try {
const user = userEvent.setup();
render(
<Text type="body" maxLines={1}>
<a href="#details">{LABEL}</a>
</Text>,
);
expect(screen.queryByRole('tooltip', {hidden: true})).toBeNull();
await user.tab();
expect(screen.getByRole('link', {name: LABEL})).toHaveFocus();
await waitFor(
() => {
expect(screen.queryByRole('tooltip', {hidden: true})).not.toBeNull();
},
{timeout: 3000},
);
} finally {
restore();
}
});
it('opens nothing for a click that follows a scroll with no press of its own', async () => {
const {showPopover, restore} = withOverflowAndPopover();
try {
render(
<Text type="body" maxLines={1}>
{LABEL}
</Text>,
);
const text = screen.getByText(LABEL);
fireEvent.pointerDown(text, {pointerType: 'touch'});
fireEvent.pointerCancel(text, {pointerType: 'touch'});
fireEvent.click(text);
await act(async () => {
await new Promise(resolve => setTimeout(resolve, 300));
});
expect(showPopover).not.toHaveBeenCalled();
} finally {
restore();
}
});
it("still mounts on a tap when the caller's handlers prevent the default", async () => {
const {showPopover, restore} = withOverflowAndPopover();
try {
render(
<Text
type="body"
maxLines={1}
onPointerDown={event => event.preventDefault()}
onClick={event => event.preventDefault()}>
{LABEL}
</Text>,
);
tap(screen.getByText(LABEL));
await waitFor(
() => {
expect(showPopover).toHaveBeenCalled();
},
{timeout: 3000},
);
} finally {
restore();
}
});
it('opens for a mouse that leaves and comes back before the tooltip mounts', async () => {
const {showPopover, restore} = withOverflowAndPopover();
try {
render(
<Text type="body" maxLines={1}>
{LABEL}
</Text>,
);
const text = screen.getByText(LABEL);
// A browser follows each pointer event of a mouse with its mouse event.
fireEvent.pointerEnter(text, {pointerType: 'mouse'});
fireEvent.mouseEnter(text);
fireEvent.pointerLeave(text, {pointerType: 'mouse'});
fireEvent.mouseLeave(text);
fireEvent.pointerEnter(text, {pointerType: 'mouse'});
fireEvent.mouseEnter(text);
await waitFor(
() => {
expect(showPopover).toHaveBeenCalled();
},
{timeout: 3000},
);
} finally {
restore();
}
});
it('opens nothing after a mouse press made while the tooltip loads', async () => {
const {showPopover, restore} = withOverflowAndPopover();
try {
render(
<Text type="body" maxLines={1}>
{LABEL}
</Text>,
);
const text = screen.getByText(LABEL);
fireEvent.pointerEnter(text, {pointerType: 'mouse'});
fireEvent.pointerDown(text, {pointerType: 'mouse'});
await waitFor(
() => {
expect(screen.queryByRole('tooltip', {hidden: true})).not.toBeNull();
},
{timeout: 3000},
);
await act(async () => {
await new Promise(resolve => setTimeout(resolve, 300));
});
expect(showPopover).not.toHaveBeenCalled();
} finally {
restore();
}
});
it('mounts nothing for a touch that becomes a scroll', async () => {
const {restore} = withOverflowAndPopover();
try {
render(
<Text type="body" maxLines={1}>
{LABEL}
</Text>,
);
const text = screen.getByText(LABEL);
fireEvent.pointerEnter(text, {pointerType: 'touch'});
fireEvent.pointerDown(text, {pointerType: 'touch'});
fireEvent.pointerCancel(text, {pointerType: 'touch'});
await act(async () => {
await new Promise(resolve => setTimeout(resolve, 300));
});
expect(screen.queryByRole('tooltip', {hidden: true})).toBeNull();
} finally {
restore();
}
});
});