An open source design system that's fully customizable and agent ready
TypeScript
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
* @file TextInput.test.tsx
* @input Uses vitest, @testing-library/react, TextInput component, and the
* shared declaredValue StyleX read-back helper
* @output Unit tests for TextInput component behavior
* @position Testing; validates TextInput.tsx implementation
*
* SYNC: When TextInput.tsx changes, update tests to match new behavior
*/
import {describe, it, expect, vi, beforeEach} from 'vitest';
import {render, screen, fireEvent, waitFor, act} from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import * as stylex from '@stylexjs/stylex';
import {colorVars} from '../theme/tokens.stylex';
import {TestIcon} from '../__tests__/TestIcon';
import {declaredValue} from '../__tests__/stylexDeclarations';
import {InputGroup} from '../InputGroup';
import {TextInput} from './TextInput';
// jsdom cannot match `:focus-visible`: compare the ring's StyleX class hash.
const RING = stylex
.props(
stylex.create({
ring: {
boxShadow: {
default: null,
':has(> [aria-disabled="true"]:focus-visible)': `inset 0px 0px 0px 2px ${colorVars['--color-accent-muted']}`,
},
},
}).ring,
)
.className!.split(' ')
.pop()!;
// Mock showPopover/hidePopover since jsdom does not implement them. Used by the
// disabledMessage tooltip.
beforeEach(() => {
HTMLElement.prototype.showPopover = vi.fn(function (this: HTMLElement) {
this.setAttribute('popover-open', '');
const event = new Event('toggle', {bubbles: false});
Object.defineProperty(event, 'newState', {value: 'open'});
this.dispatchEvent(event);
});
HTMLElement.prototype.hidePopover = vi.fn(function (this: HTMLElement) {
this.removeAttribute('popover-open');
const event = new Event('toggle', {bubbles: false});
Object.defineProperty(event, 'newState', {value: 'closed'});
this.dispatchEvent(event);
});
const originalMatches = HTMLElement.prototype.matches;
// eslint-disable-next-line @typescript-eslint/no-explicit-any
(HTMLElement.prototype as any).matches = function (
selector: string,
): boolean {
if (selector === ':popover-open') {
return this.hasAttribute('popover-open');
}
return originalMatches.call(this, selector);
};
});
// jsdom popover content is in the DOM but may not be "visible" in the
// accessibility tree. Use hidden: true to find it.
const h = {hidden: true} as const;
describe('TextInput', () => {
it('renders with label', () => {
render(<TextInput label="Name" value="" onChange={() => {}} />);
expect(screen.getByLabelText('Name')).toBeInTheDocument();
});
it('renders with placeholder', () => {
render(
<TextInput
label="Name"
value=""
onChange={() => {}}
placeholder="Enter text"
/>,
);
expect(screen.getByPlaceholderText('Enter text')).toBeInTheDocument();
});
it('calls onChange with value and event when typing', async () => {
const user = userEvent.setup();
const handleChange = vi.fn();
render(<TextInput label="Name" value="" onChange={handleChange} />);
const input = screen.getByRole('textbox');
await user.type(input, 'Hi');
expect(handleChange).toHaveBeenCalledTimes(2);
expect(handleChange).toHaveBeenLastCalledWith('i', expect.any(Object));
});
it('works with state setter function directly', async () => {
const user = userEvent.setup();
const setValue = vi.fn();
render(<TextInput label="Name" value="" onChange={setValue} />);
const input = screen.getByRole('textbox');
await user.type(input, 'A');
expect(setValue).toHaveBeenCalledWith('A', expect.any(Object));
});
it('renders empty string when value is undefined', () => {
// @ts-expect-error — testing runtime safety when value is omitted
render(<TextInput label="Name" onChange={() => {}} />);
expect(screen.getByRole('textbox')).toHaveValue('');
});
it('displays controlled value', () => {
render(
<TextInput label="Name" value="Controlled value" onChange={() => {}} />,
);
expect(screen.getByRole('textbox')).toHaveValue('Controlled value');
});
it('forwards ref correctly', () => {
const ref = vi.fn();
render(<TextInput ref={ref} label="Name" value="" onChange={() => {}} />);
expect(ref).toHaveBeenCalledWith(expect.any(HTMLInputElement));
});
it('visually hides label when isLabelHidden is true', () => {
render(
<TextInput label="Search" isLabelHidden value="" onChange={() => {}} />,
);
const label = screen.getByText('Search');
expect(label).toBeInTheDocument();
// Label should still be accessible
expect(screen.getByLabelText('Search')).toBeInTheDocument();
});
it('shows label visually by default', () => {
render(<TextInput label="Email" value="" onChange={() => {}} />);
const label = screen.getByText('Email');
expect(label).toBeVisible();
});
it('sets aria-required when isRequired is true', () => {
render(
<TextInput label="Username" isRequired value="" onChange={() => {}} />,
);
expect(screen.getByRole('textbox')).toHaveAttribute(
'aria-required',
'true',
);
});
it('does not set aria-required when isRequired is false', () => {
render(<TextInput label="Username" value="" onChange={() => {}} />);
expect(screen.getByRole('textbox')).not.toHaveAttribute('aria-required');
});
it('exposes aria-disabled and read-only, not native disabled, when isDisabled is true', () => {
render(<TextInput label="Name" isDisabled value="" onChange={() => {}} />);
const input = screen.getByRole('textbox');
expect(input).not.toBeDisabled();
expect(input).toHaveAttribute('aria-disabled', 'true');
expect(input).toHaveAttribute('readonly');
});
it('keeps a disabled input in the tab order (spec:AST-085)', async () => {
const user = userEvent.setup();
render(
<>
<TextInput label="First" value="" onChange={() => {}} />
<TextInput label="Second" isDisabled value="" onChange={() => {}} />
<TextInput label="Third" value="" onChange={() => {}} />
</>,
);
await user.tab();
await user.tab();
expect(screen.getByRole('textbox', {name: 'Second'})).toHaveFocus();
});
it('runs no caller handler and submits no form from a disabled input (spec:AST-085 FR2)', async () => {
const user = userEvent.setup();
const handlers = {onEnter: vi.fn(), onKeyDown: vi.fn(), onPaste: vi.fn()};
const onSubmit = vi.fn((e: React.FormEvent) => e.preventDefault());
render(
<form onSubmit={onSubmit}>
<TextInput
label="Name"
isDisabled
value=""
onChange={() => {}}
{...handlers}
/>
</form>,
);
await user.click(screen.getByRole('textbox'));
await user.keyboard('{Enter}');
await user.paste('x');
for (const handler of [...Object.values(handlers), onSubmit]) {
expect(handler).not.toHaveBeenCalled();
}
});
it('rings a disabled input under keyboard focus (spec:AST-085 FR6)', () => {
render(<TextInput label="Name" isDisabled value="" onChange={() => {}} />);
const wrapper = screen.getByRole('textbox').parentElement!;
expect(wrapper).toHaveClass(RING);
});
it('does not fire onChange when disabled', async () => {
const user = userEvent.setup();
const handleChange = vi.fn();
render(
<TextInput label="Name" isDisabled value="" onChange={handleChange} />,
);
const input = screen.getByRole('textbox');
await user.type(input, 'test');
expect(handleChange).not.toHaveBeenCalled();
});
it('is not disabled by default', () => {
render(<TextInput label="Name" value="" onChange={() => {}} />);
expect(screen.getByRole('textbox')).not.toBeDisabled();
});
it('renders with startIcon', () => {
render(
<TextInput
label="Search"
value=""
onChange={() => {}}
startIcon={TestIcon}
/>,
);
expect(screen.getByRole('textbox')).toBeInTheDocument();
// Icon should be rendered (as an SVG element)
const svg = document.querySelector('svg');
expect(svg).toBeInTheDocument();
});
it('renders without icon wrapper when startIcon is not provided', () => {
const {container} = render(
<TextInput label="Name" value="" onChange={() => {}} />,
);
// No SVG should be present
expect(container.querySelector('svg')).not.toBeInTheDocument();
});
// The shared presence check decides the start icon's slot
// (architecture:react-component-runtime INV16).
it.each([
['null', null],
['false', false],
['an empty string', ''],
])('renders no start icon for %s', (_label, value) => {
const {container} = render(
<TextInput label="Name" value="" onChange={() => {}} startIcon={value} />,
);
const wrapper = screen.getByRole('textbox').parentElement as HTMLElement;
expect(wrapper.firstChild).toBe(screen.getByRole('textbox'));
expect(container.querySelector('svg')).toBeNull();
});
describe('status prop', () => {
it('renders with error status icon', () => {
const {container} = render(
<TextInput
label="Email"
value=""
onChange={() => {}}
status={{type: 'error'}}
/>,
);
expect(container.querySelector('svg')).toBeInTheDocument();
});
it('renders with warning status icon', () => {
const {container} = render(
<TextInput
label="Email"
value=""
onChange={() => {}}
status={{type: 'warning'}}
/>,
);
expect(container.querySelector('svg')).toBeInTheDocument();
});
it('renders with success status icon', () => {
const {container} = render(
<TextInput
label="Email"
value=""
onChange={() => {}}
status={{type: 'success'}}
/>,
);
expect(container.querySelector('svg')).toBeInTheDocument();
});
it('renders status message when provided', () => {
render(
<TextInput
label="Email"
value=""
onChange={() => {}}
status={{type: 'error', message: 'Invalid email address'}}
/>,
);
expect(screen.getByText('Invalid email address')).toBeInTheDocument();
});
it('has no dangling aria-describedby ids inside InputGroup (WCAG 1.3.1)', () => {
// Inside an InputGroup no Field renders, so the status message element
// does not exist; aria-describedby must not reference its id.
render(
<InputGroup label="Contact">
<TextInput
label="Email"
value=""
onChange={() => {}}
status={{type: 'error', message: 'Invalid email address'}}
/>
</InputGroup>,
);
const input = screen.getByRole('textbox');
const describedBy = input.getAttribute('aria-describedby') ?? '';
for (const idToken of describedBy.split(/\s+/).filter(Boolean)) {
expect(document.getElementById(idToken)).not.toBeNull();
}
});
it('names the input by its label and a caller aria-labelledby', () => {
render(
<>
<span id="billing-heading">Billing</span>
<TextInput
label="Email"
value=""
onChange={() => {}}
aria-labelledby="billing-heading"
/>
</>,
);
const input = screen.getByRole('textbox', {name: 'Email Billing'});
expect(input.getAttribute('aria-labelledby')?.split(' ')).toContain(
'billing-heading',
);
});
it('names a grouped input by the group, its label, and a caller aria-labelledby', () => {
render(
<>
<span id="billing-heading">Billing</span>
<InputGroup label="Contact">
<TextInput
label="Email"
value=""
onChange={() => {}}
aria-labelledby="billing-heading"
/>
</InputGroup>
</>,
);
expect(
screen.getByRole('textbox', {name: 'Contact Email Billing'}),
).toBeInTheDocument();
});
it('leaves a standalone input named by its label element without a caller aria-labelledby', () => {
render(<TextInput label="Email" value="" onChange={() => {}} />);
const input = screen.getByRole('textbox', {name: 'Email'});
expect(input).not.toHaveAttribute('aria-labelledby');
});
it('does not render status message when not provided', () => {
render(
<TextInput
label="Email"
value=""
onChange={() => {}}
status={{type: 'error'}}
/>,
);
expect(screen.queryByText(/invalid/i)).not.toBeInTheDocument();
});
it('sets aria-invalid when status type is error', () => {
render(
<TextInput
label="Email"
value=""
onChange={() => {}}
status={{type: 'error'}}
/>,
);
expect(screen.getByRole('textbox')).toHaveAttribute(
'aria-invalid',
'true',
);
});
it('does not set aria-invalid for warning status', () => {
render(
<TextInput
label="Email"
value=""
onChange={() => {}}
status={{type: 'warning'}}
/>,
);
expect(screen.getByRole('textbox')).not.toHaveAttribute('aria-invalid');
});
it('does not set aria-invalid for success status', () => {
render(
<TextInput
label="Email"
value=""
onChange={() => {}}
status={{type: 'success'}}
/>,
);
expect(screen.getByRole('textbox')).not.toHaveAttribute('aria-invalid');
});
it('includes status message in aria-describedby', () => {
render(
<TextInput
label="Email"
value=""
onChange={() => {}}
status={{type: 'error', message: 'Invalid email'}}
/>,
);
const input = screen.getByRole('textbox');
const describedBy = input.getAttribute('aria-describedby');
expect(describedBy).toBeTruthy();
// The status message should be reachable via the described-by ID
const messageElement = screen.getByText('Invalid email');
expect(messageElement).toHaveAttribute('id');
expect(describedBy).toContain(messageElement.id);
});
});
it('renders tooltip info icon when labelTooltip is provided', () => {
render(
<TextInput
label="Help"
value=""
onChange={() => {}}
labelTooltip="Helpful info"
/>,
);
// Info icon should be present
expect(document.querySelector('svg')).toBeInTheDocument();
});
it('does not render tooltip icon when labelTooltip is not provided', () => {
render(<TextInput label="Name" value="" onChange={() => {}} />);
expect(document.querySelector('svg')).not.toBeInTheDocument();
});
describe('hasAutoFocus prop', () => {
it('focuses the input when hasAutoFocus is true', () => {
render(
<TextInput label="Name" value="" onChange={() => {}} hasAutoFocus />,
);
expect(screen.getByRole('textbox')).toHaveFocus();
});
it('does not focus when hasAutoFocus is false', () => {
render(<TextInput label="Name" value="" onChange={() => {}} />);
expect(screen.getByRole('textbox')).not.toHaveFocus();
});
});
describe('htmlName prop', () => {
it('sets name attribute when htmlName is provided', () => {
render(
<TextInput
label="Name"
value=""
onChange={() => {}}
htmlName="username"
/>,
);
expect(screen.getByRole('textbox')).toHaveAttribute('name', 'username');
});
it('does not set name attribute when htmlName is not provided', () => {
render(<TextInput label="Name" value="" onChange={() => {}} />);
expect(screen.getByRole('textbox')).not.toHaveAttribute('name');
});
});
describe('form participation', () => {
it('submits the value under htmlName', () => {
const {container} = render(
<form>
<TextInput
label="Owner"
htmlName="owner"
value="alice"
onChange={() => {}}
/>
</form>,
);
const data = new FormData(container.querySelector('form')!);
expect(data.get('owner')).toBe('alice');
});
it('is excluded from form data when disabled', () => {
const {container} = render(
<form>
<TextInput
label="Owner"
htmlName="owner"
value="alice"
onChange={() => {}}
isDisabled
/>
</form>,
);
expect([
...new FormData(container.querySelector('form')!).keys(),
]).toEqual([]);
});
// Regression: a disabledMessage swaps the native `disabled` attribute for
// aria-disabled + readOnly so the reason stays focus-discoverable, but
// read-only fields still submit — the name has to be withheld too.
it('is excluded from form data when disabled, even with a disabledMessage', () => {
const {container} = render(
<form>
<TextInput
label="Owner"
htmlName="owner"
value="alice"
onChange={() => {}}
isDisabled
disabledMessage="You need the Editor role to change this"
/>
</form>,
);
expect([
...new FormData(container.querySelector('form')!).keys(),
]).toEqual([]);
});
});
describe('isReadOnly', () => {
it('marks the input read-only', () => {
render(
<TextInput
label="Owner"
value="alice"
onChange={() => {}}
isReadOnly
/>,
);
expect(screen.getByRole('textbox')).toHaveAttribute('readonly');
});
it('still submits its value with the form', () => {
const {container} = render(
<form>
<TextInput
label="Owner"
htmlName="owner"
value="alice"
onChange={() => {}}
isReadOnly
/>
</form>,
);
expect(new FormData(container.querySelector('form')!).get('owner')).toBe(
'alice',
);
});
it('does not call onChange when the user types', async () => {
const user = userEvent.setup();
const handleChange = vi.fn();
render(
<TextInput
label="Owner"
value="alice"
onChange={handleChange}
isReadOnly
/>,
);
await user.type(screen.getByRole('textbox'), 'xyz');
expect(handleChange).not.toHaveBeenCalled();
});
it('stays focusable and is not disabled', async () => {
const user = userEvent.setup();
render(
<TextInput
label="Owner"
value="alice"
onChange={() => {}}
isReadOnly
/>,
);
const input = screen.getByRole('textbox');
expect(input).not.toBeDisabled();
await user.tab();
expect(input).toHaveFocus();
});
it('hides the clear button', () => {
render(
<TextInput
label="Owner"
value="alice"
onChange={() => {}}
hasClear
isReadOnly
/>,
);
expect(screen.queryByRole('button')).not.toBeInTheDocument();
});
it('lets isDisabled win when both are set', () => {
const {container} = render(
<form>
<TextInput
label="Owner"
htmlName="owner"
value="alice"
onChange={() => {}}
isReadOnly
isDisabled
/>
</form>,
);
expect(screen.getByRole('textbox')).toHaveAttribute(
'aria-disabled',
'true',
);
expect([
...new FormData(container.querySelector('form')!).keys(),
]).toEqual([]);
});
});
describe('autoComplete prop (#5638)', () => {
it('forwards autoComplete to the native input unchanged', () => {
render(
<TextInput
label="Reason"
value=""
onChange={() => {}}
autoComplete="off"
/>,
);
expect(screen.getByRole('textbox')).toHaveAttribute(
'autocomplete',
'off',
);
});
it('does not set autocomplete when not provided', () => {
render(<TextInput label="Name" value="" onChange={() => {}} />);
expect(screen.getByRole('textbox')).not.toHaveAttribute('autocomplete');
});
});
describe('touch keyboard traits', () => {
it('renders no trait attribute when none is set, leaving the browser default', () => {
render(<TextInput label="Name" value="" onChange={() => {}} />);
const input = screen.getByRole('textbox');
for (const attribute of [
'enterkeyhint',
'inputmode',
'autocapitalize',
'autocorrect',
'spellcheck',
]) {
expect(input).not.toHaveAttribute(attribute);
}
});
it('labels the Return key with enterKeyHint', () => {
render(
<TextInput
label="Search"
value=""
onChange={() => {}}
enterKeyHint="search"
/>,
);
expect(screen.getByRole('textbox')).toHaveAttribute(
'enterkeyhint',
'search',
);
});
it.each([
'enter',
'done',
'go',
'next',
'previous',
'search',
'send',
] as const)(
'calls onEnter on Enter whatever the Return key says (%s)',
async enterKeyHint => {
const user = userEvent.setup();
const onEnter = vi.fn();
render(
<TextInput
label="Field"
value=""
onChange={() => {}}
enterKeyHint={enterKeyHint}
onEnter={onEnter}
/>,
);
await user.type(screen.getByRole('textbox'), '{Enter}');
expect(onEnter).toHaveBeenCalledTimes(1);
},
);
it('asks for a keyboard with inputMode without changing the type', () => {
render(
<TextInput
label="Amount"
value=""
onChange={() => {}}
inputMode="decimal"
/>,
);
const input = screen.getByRole('textbox');
expect(input).toHaveAttribute('inputmode', 'decimal');
expect(input).toHaveAttribute('type', 'text');
});
it('sets capitalization, correction and spell checking', () => {
render(
<TextInput
label="Username"
value=""
onChange={() => {}}
autoCapitalize="none"
hasAutoCorrect={false}
hasSpellCheck={false}
/>,
);
const input = screen.getByRole('textbox');
expect(input).toHaveAttribute('autocapitalize', 'none');
expect(input).toHaveAttribute('autocorrect', 'off');
expect(input).toHaveAttribute('spellcheck', 'false');
});
it('keeps an untyped spellCheck passed through while hasSpellCheck is unset', () => {
const passthrough = {spellCheck: false} as Record<string, unknown>;
render(
<TextInput
label="Code"
value=""
onChange={() => {}}
{...passthrough}
/>,
);
expect(screen.getByRole('textbox')).toHaveAttribute(
'spellcheck',
'false',
);
});
it('turns correction and spell checking on explicitly', () => {
render(
<TextInput
label="Title"
value=""
onChange={() => {}}
autoCapitalize="words"
hasAutoCorrect
hasSpellCheck
/>,
);
const input = screen.getByRole('textbox');
expect(input).toHaveAttribute('autocapitalize', 'words');
expect(input).toHaveAttribute('autocorrect', 'on');
expect(input).toHaveAttribute('spellcheck', 'true');
});
it('keeps the traits on the input inside an InputGroup', () => {
render(
<InputGroup label="Website">
<TextInput
label="Website"
value=""
onChange={() => {}}
type="url"
enterKeyHint="go"
autoCapitalize="none"
/>
</InputGroup>,
);
const input = screen.getByRole('textbox');
expect(input).toHaveAttribute('type', 'url');
expect(input).toHaveAttribute('enterkeyhint', 'go');
expect(input).toHaveAttribute('autocapitalize', 'none');
});
it('lets the trait props win over the same attributes passed untyped', () => {
const untyped = {enterKeyHint: 'done', autoCorrect: 'on'} as object;
render(
<TextInput
label="Code"
value=""
onChange={() => {}}
{...untyped}
enterKeyHint="next"
hasAutoCorrect={false}
/>,
);
const input = screen.getByRole('textbox');
expect(input).toHaveAttribute('enterkeyhint', 'next');
expect(input).toHaveAttribute('autocorrect', 'off');
});
});
describe('type', () => {
it.each([
['search', 'searchbox'],
['tel', 'textbox'],
['url', 'textbox'],
['email', 'textbox'],
] as const)('renders type="%s" as a %s', (type, role) => {
render(
<TextInput label="Field" value="" onChange={() => {}} type={type} />,
);
expect(screen.getByRole(role, {name: 'Field'})).toHaveAttribute(
'type',
type,
);
});
it('keeps onEnter on a search field', async () => {
const user = userEvent.setup();
const onEnter = vi.fn();
render(
<TextInput
label="Search"
value=""
onChange={() => {}}
type="search"
enterKeyHint="search"
onEnter={onEnter}
/>,
);
await user.type(screen.getByRole('searchbox'), '{Enter}');
expect(onEnter).toHaveBeenCalledTimes(1);
});
});
describe('onEnter', () => {
it('calls onEnter when Enter key is pressed', async () => {
const user = userEvent.setup();
const handleEnter = vi.fn();
render(
<TextInput
label="Name"
value="hello"
onChange={() => {}}
onEnter={handleEnter}
/>,
);
const input = screen.getByRole('textbox');
await user.click(input);
await user.keyboard('{Enter}');
expect(handleEnter).toHaveBeenCalledTimes(1);
});
it('does not call onEnter when Enter commits an IME conversion', () => {
// The browser fires this composing keydown for the Enter that commits an
// IME candidate (isComposing: true, or the legacy keyCode 229) before
// compositionend writes the conversion. It must NOT trigger onEnter —
// submit/save actions would fire before the user intends to submit.
// See utils/ime.ts and #6082.
const handleEnter = vi.fn();
const {container} = render(
<TextInput
label="Name"
value="にほんご"
onChange={() => {}}
onEnter={handleEnter}
/>,
);
const input = container.querySelector('input')!;
fireEvent.keyDown(input, {key: 'Enter', isComposing: true});
expect(handleEnter).not.toHaveBeenCalled();
fireEvent.keyDown(input, {key: 'Enter', keyCode: 229});
expect(handleEnter).not.toHaveBeenCalled();
// A real, non-composing Enter after composition ends still submits.
fireEvent.keyDown(input, {key: 'Enter'});
expect(handleEnter).toHaveBeenCalledTimes(1);
});
it('still calls onKeyDown for composing keydowns', () => {
// onKeyDown is the raw escape hatch: it keeps receiving IME keydowns so
// consumers with custom composition handling are unaffected by the
// onEnter guard.
const handleKeyDown = vi.fn();
const {container} = render(
<TextInput
label="Name"
value="にほんご"
onChange={() => {}}
onKeyDown={handleKeyDown}
onEnter={() => {}}
/>,
);
const input = container.querySelector('input')!;
fireEvent.keyDown(input, {key: 'Enter', isComposing: true});
expect(handleKeyDown).toHaveBeenCalledTimes(1);
});
it('does not call onEnter for other keys', async () => {
const user = userEvent.setup();
const handleEnter = vi.fn();
render(
<TextInput
label="Name"
value=""
onChange={() => {}}
onEnter={handleEnter}
/>,
);
const input = screen.getByRole('textbox');
await user.click(input);
await user.keyboard('abc');
expect(handleEnter).not.toHaveBeenCalled();
});
});
describe('onKeyDown', () => {
it('passes through onKeyDown events', async () => {
const user = userEvent.setup();
const handleKeyDown = vi.fn();
render(
<TextInput
label="Name"
value=""
onChange={() => {}}
onKeyDown={handleKeyDown}
/>,
);
const input = screen.getByRole('textbox');
await user.click(input);
await user.keyboard('a');
expect(handleKeyDown).toHaveBeenCalledTimes(1);
});
it('calls both onKeyDown and onEnter on Enter', async () => {
const user = userEvent.setup();
const handleKeyDown = vi.fn();
const handleEnter = vi.fn();
render(
<TextInput
label="Name"
value=""
onChange={() => {}}
onKeyDown={handleKeyDown}
onEnter={handleEnter}
/>,
);
const input = screen.getByRole('textbox');
await user.click(input);
await user.keyboard('{Enter}');
expect(handleEnter).toHaveBeenCalledTimes(1);
expect(handleKeyDown).toHaveBeenCalledTimes(1);
});
});
describe('hasClear', () => {
it('shows clear button when hasClear is true and value is non-empty', () => {
render(
<TextInput label="Name" value="hello" onChange={() => {}} hasClear />,
);
expect(
screen.getByRole('button', {name: 'Clear Name'}),
).toBeInTheDocument();
});
it('does not show clear button when value is empty', () => {
render(<TextInput label="Name" value="" onChange={() => {}} hasClear />);
expect(
screen.queryByRole('button', {name: 'Clear Name'}),
).not.toBeInTheDocument();
});
it('does not show clear button when hasClear is false', () => {
render(<TextInput label="Name" value="hello" onChange={() => {}} />);
expect(
screen.queryByRole('button', {name: 'Clear Name'}),
).not.toBeInTheDocument();
});
it('does not show clear button when disabled', () => {
render(
<TextInput
label="Name"
value="hello"
onChange={() => {}}
hasClear
isDisabled
/>,
);
expect(
screen.queryByRole('button', {name: 'Clear Name'}),
).not.toBeInTheDocument();
});
it('calls onChange with empty string when clear is clicked', async () => {
const user = userEvent.setup();
const onChange = vi.fn();
render(
<TextInput label="Name" value="hello" onChange={onChange} hasClear />,
);
await user.click(screen.getByRole('button', {name: 'Clear Name'}));
expect(onChange).toHaveBeenCalledWith(
'',
expect.objectContaining({target: screen.getByRole('textbox')}),
);
});
it('calls onChange, then changeAction, with an empty string and the change event when clear is clicked', async () => {
const user = userEvent.setup();
const onChange = vi.fn();
const changeAction = vi.fn();
render(
<TextInput
label="Name"
value="hello"
onChange={onChange}
changeAction={changeAction}
hasClear
/>,
);
await user.click(screen.getByRole('button', {name: 'Clear Name'}));
const input = screen.getByRole('textbox');
// A real change event, so an Action that reads e.target works on clear.
expect(onChange).toHaveBeenCalledWith(
'',
expect.objectContaining({target: input}),
);
expect(changeAction).toHaveBeenCalledWith(
'',
expect.objectContaining({target: input}),
);
expect(onChange.mock.invocationCallOrder[0]).toBeLessThan(
changeAction.mock.invocationCallOrder[0],
);
});
it('runs no changeAction on clear when onChange prevents the change event', async () => {
const user = userEvent.setup();
const changeAction = vi.fn();
render(
<TextInput
label="Name"
value="hello"
onChange={(_value, e) => e.preventDefault()}
changeAction={changeAction}
hasClear
/>,
);
await user.click(screen.getByRole('button', {name: 'Clear Name'}));
expect(changeAction).not.toHaveBeenCalled();
});
it('presents optimistic empty value and busy state while clear changeAction is pending', async () => {
const user = userEvent.setup();
let resolveAction: () => void = () => {};
const changeAction = vi.fn(
async () =>
new Promise<void>(resolve => {
resolveAction = resolve;
}),
);
render(
<TextInput
label="Name"
value="hello"
onChange={() => {}}
changeAction={changeAction}
hasClear
/>,
);
const input = screen.getByRole('textbox');
expect(input).toHaveValue('hello');
await user.click(screen.getByRole('button', {name: 'Clear Name'}));
expect(input).toHaveValue('');
expect(input).toHaveAttribute('aria-busy', 'true');
await act(async () => {
resolveAction();
});
});
});
it('keeps the clear button where it is when the field turns busy', () => {
// What follows the button in the lane (a `<template>` is not rendered).
const after = (button: HTMLElement) =>
Array.from(button.parentElement?.children ?? [])
.slice(Array.from(button.parentElement?.children ?? []).indexOf(button))
.filter(el => el !== button && el.tagName !== 'TEMPLATE');
const props = {label: 'Name', value: 'hello', onChange: () => {}};
const {rerender} = render(<TextInput {...props} hasClear />);
const idle = screen.getByRole('button', {name: 'Clear Name'});
const idleAfter = after(idle).length;
rerender(<TextInput {...props} hasClear isLoading />);
const busy = screen.getByRole('button', {name: 'Clear Name'});
// The Spinner joins on the inward side, before the button, so nothing new
// follows it and its distance from the end does not change.
expect(after(busy)).toHaveLength(idleAfter);
expect(busy.previousElementSibling?.getAttribute('aria-hidden')).toBe(
'true',
);
});
describe('click-to-focus', () => {
it('focuses input when clicking the start icon', () => {
render(
<TextInput
label="Search"
value=""
onChange={() => {}}
startIcon={<TestIcon />}
/>,
);
const input = screen.getByRole('textbox');
const wrapper = input.parentElement!;
// The icon is rendered before the input; grab the first non-input child
const iconElement = wrapper.querySelector('svg')!;
fireEvent.click(iconElement);
expect(input).toHaveFocus();
});
it('focuses input when clicking the wrapper padding', () => {
render(<TextInput label="Name" value="" onChange={() => {}} />);
const input = screen.getByRole('textbox');
const wrapper = input.parentElement!;
fireEvent.click(wrapper);
expect(input).toHaveFocus();
});
});
describe('width prop (#2755)', () => {
it('sizes the outer field, not just the input wrapper', () => {
render(
<TextInput label="Name" value="" onChange={() => {}} width="100%" />,
);
const input = screen.getByRole('textbox');
const inputWrapper = input.parentElement!;
// Field root is the labelled ancestor that owns the width.
const fieldRoot = input.closest('.astryx-field') as HTMLElement;
expect(fieldRoot).toBeTruthy();
expect(fieldRoot.getAttribute('style')).toContain('100%');
// The inner control wrapper is not the element carrying the width.
expect(fieldRoot).not.toBe(inputWrapper);
expect(inputWrapper.getAttribute('style') ?? '').not.toContain('100%');
});
it('does not set width when the prop is omitted', () => {
render(<TextInput label="Name" value="" onChange={() => {}} />);
const fieldRoot = screen
.getByRole('textbox')
.closest('.astryx-field') as HTMLElement;
expect(fieldRoot.getAttribute('style') ?? '').not.toContain('100%');
});
});
describe('disabledMessage', () => {
it('shows the reason tooltip on hover when disabled with a reason', async () => {
render(
<TextInput
label="Owner"
value=""
onChange={() => {}}
isDisabled
disabledMessage="You need the Editor role"
/>,
);
const input = screen.getByRole('textbox');
const container = input.parentElement as HTMLElement;
const tooltip = screen.getByRole('tooltip', h);
expect(tooltip).toHaveTextContent('You need the Editor role');
fireEvent.mouseEnter(container);
await waitFor(() => {
expect(tooltip).toHaveAttribute('popover-open');
});
fireEvent.mouseLeave(container);
await waitFor(() => {
expect(tooltip).not.toHaveAttribute('popover-open');
});
});
it('shows the reason tooltip on keyboard focus', async () => {
const user = userEvent.setup();
render(
<TextInput
label="Owner"
value=""
onChange={() => {}}
isDisabled
disabledMessage="You need the Editor role"
/>,
);
const tooltip = screen.getByRole('tooltip', h);
await user.tab();
expect(screen.getByRole('textbox')).toHaveFocus();
await waitFor(() => {
expect(tooltip).toHaveAttribute('popover-open');
});
});
it('does not render a tooltip when not disabled', () => {
render(
<TextInput
label="Owner"
value=""
onChange={() => {}}
disabledMessage="You need the Editor role"
/>,
);
expect(screen.queryByRole('tooltip', h)).not.toBeInTheDocument();
});
it('does not render a tooltip when disabled without a reason', () => {
render(
<TextInput label="Owner" value="" onChange={() => {}} isDisabled />,
);
expect(screen.queryByRole('tooltip', h)).not.toBeInTheDocument();
});
it('keeps the input focusable via aria-disabled when a reason is provided', () => {
render(
<TextInput
label="Owner"
value=""
onChange={() => {}}
isDisabled
disabledMessage="You need the Editor role"
/>,
);
const input = screen.getByRole('textbox');
expect(input).not.toBeDisabled();
expect(input).toHaveAttribute('aria-disabled', 'true');
expect(input).toHaveAttribute('readonly');
});
it('links the reason tooltip from the input via aria-describedby', () => {
render(
<TextInput
label="Owner"
value=""
onChange={() => {}}
isDisabled
disabledMessage="You need the Editor role"
/>,
);
const input = screen.getByRole('textbox');
const tooltip = screen.getByRole('tooltip', h);
expect(input.getAttribute('aria-describedby')).toContain(tooltip.id);
});
it('blocks value changes while focusable-disabled', async () => {
const user = userEvent.setup();
const onChange = vi.fn();
render(
<TextInput
label="Owner"
value=""
onChange={onChange}
isDisabled
disabledMessage="You need the Editor role"
/>,
);
const input = screen.getByRole('textbox');
await user.click(input);
await user.keyboard('hello');
expect(onChange).not.toHaveBeenCalled();
expect(input).toHaveValue('');
});
it('stays focusable when disabled without a reason', () => {
render(
<TextInput label="Owner" value="" onChange={() => {}} isDisabled />,
);
const input = screen.getByRole('textbox');
expect(input).not.toBeDisabled();
expect(input).toHaveAttribute('aria-disabled', 'true');
});
});
});
describe('TextInput statusVariant forwarding', () => {
it('defaults to attached (status renders with data-variant="attached")', () => {
const {container} = render(
<TextInput
label="Email"
value=""
onChange={() => {}}
status={{type: 'error', message: 'Invalid email'}}
/>,
);
expect(container.querySelector('.astryx-field-status')).toHaveAttribute(
'data-variant',
'attached',
);
});
it('forwards statusVariant="detached" to the underlying Field status', () => {
const {container} = render(
<TextInput
label="Email"
value=""
onChange={() => {}}
status={{type: 'error', message: 'Invalid email'}}
statusVariant="detached"
/>,
);
expect(container.querySelector('.astryx-field-status')).toHaveAttribute(
'data-variant',
'detached',
);
});
it('renders no message box for statusVariant="tooltip"', () => {
const {container} = render(
<TextInput
label="Email"
value=""
onChange={() => {}}
status={{type: 'error', message: 'Invalid email'}}
statusVariant="tooltip"
/>,
);
expect(
container.querySelector('.astryx-field-status'),
).not.toBeInTheDocument();
});
it('surfaces the status message in a tooltip for statusVariant="tooltip"', () => {
render(
<TextInput
label="Email"
value=""
onChange={() => {}}
status={{type: 'error', message: 'Invalid email'}}
statusVariant="tooltip"
/>,
);
const tooltip = screen.getByRole('tooltip', h);
expect(tooltip).toHaveTextContent('Invalid email');
});
it('describes the input by the status tooltip for statusVariant="tooltip"', () => {
render(
<TextInput
label="Email"
value=""
onChange={() => {}}
status={{type: 'error', message: 'Invalid email'}}
statusVariant="tooltip"
/>,
);
const input = screen.getByRole('textbox');
const tooltip = screen.getByRole('tooltip', h);
expect(input.getAttribute('aria-describedby')).toContain(tooltip.id);
});
it('renders the tooltip status affordance as a focusable button (WCAG 2.1.1)', () => {
render(
<TextInput
label="Email"
value=""
onChange={() => {}}
status={{type: 'error', message: 'Invalid email'}}
statusVariant="tooltip"
/>,
);
// The status affordance is a real button with an accessible name naming
// the status type (WCAG 4.1.2), so keyboard-only users (no AT) can reach it.
const statusButton = screen.getByRole('button', {name: /error details/i});
expect(statusButton).toBeInTheDocument();
expect(statusButton).toHaveAttribute('type', 'button');
});
it('opens the status tooltip on keyboard focus for statusVariant="tooltip"', async () => {
const user = userEvent.setup();
render(
<TextInput
label="Email"
value=""
onChange={() => {}}
status={{type: 'error', message: 'Invalid email'}}
statusVariant="tooltip"
/>,
);
const tooltip = screen.getByRole('tooltip', h);
// Tab from the input to the status button; keyboard focus reveals the tip.
await user.tab();
await user.tab();
await waitFor(() => {
expect(tooltip).toHaveAttribute('popover-open');
});
});
it('describes the status button by the tooltip content for statusVariant="tooltip"', () => {
render(
<TextInput
label="Email"
value=""
onChange={() => {}}
status={{type: 'error', message: 'Invalid email'}}
statusVariant="tooltip"
/>,
);
const statusButton = screen.getByRole('button', {name: /error details/i});
const tooltip = screen.getByRole('tooltip', h);
expect(statusButton.getAttribute('aria-describedby')).toContain(tooltip.id);
});
});
describe('TextInput disabled theme state', () => {
// Reflecting isDisabled on the root theming target lets a theme gate its own
// hover/border treatment on disabled (data-disabled + a .disabled variant),
// mirroring how status is reflected — without structural :has() CSS.
it('reflects disabled on the root target so themes can gate paint on it', () => {
const {container} = render(
<TextInput label="Name" value="" onChange={() => {}} isDisabled />,
);
const root = container.querySelector('.astryx-text-input');
expect(root).toHaveAttribute('data-disabled', 'disabled');
});
it('omits data-disabled when enabled, like status does', () => {
const {container} = render(
<TextInput label="Name" value="" onChange={() => {}} />,
);
const root = container.querySelector('.astryx-text-input');
expect(root).not.toHaveAttribute('data-disabled');
});
});
describe('TextInput readonly theme state', () => {
it('reflects readonly on the root target so themes can gate paint on it', () => {
const {container} = render(
<TextInput label="Name" value="" onChange={() => {}} isReadOnly />,
);
const root = container.querySelector('.astryx-text-input');
expect(root).toHaveAttribute('data-readonly', 'readonly');
});
it('omits data-readonly when editable', () => {
const {container} = render(
<TextInput label="Name" value="" onChange={() => {}} />,
);
const root = container.querySelector('.astryx-text-input');
expect(root).not.toHaveAttribute('data-readonly');
});
});
describe('TextInput clear button focus behavior', () => {
it('synchronously restores focus to the input on keyboard activation (detail === 0)', () => {
const handleChange = vi.fn();
render(
<TextInput
label="Search"
value="test"
hasClear
onChange={handleChange}
/>,
);
const input = screen.getByRole('textbox');
const clearButton = screen.getByRole('button', {name: /clear/i});
clearButton.focus();
expect(document.activeElement).toBe(clearButton);
// Keyboard activation (e.g. Enter / Space on focused button yields detail 0)
fireEvent.click(clearButton, {detail: 0});
expect(handleChange).toHaveBeenCalledWith('', expect.any(Object));
// Must be synchronously focused without waiting for animation frames
expect(document.activeElement).toBe(input);
});
it('focuses the input inside the tap on pointer activation, without scrolling', () => {
// iOS Safari brings up its keyboard only for a focus made while handling
// the touch: a deferred focus would leave an unfocused field focused but
// keyboardless.
const handleChange = vi.fn();
const focusSpy = vi.spyOn(HTMLElement.prototype, 'focus');
const rafSpy = vi.spyOn(window, 'requestAnimationFrame');
render(
<TextInput
label="Search"
value="test"
hasClear
onChange={handleChange}
/>,
);
const input = screen.getByRole('textbox');
const clearButton = screen.getByRole('button', {name: /clear/i});
expect(document.activeElement).not.toBe(input);
fireEvent.click(clearButton, {detail: 1});
expect(handleChange).toHaveBeenCalledWith('', expect.any(Object));
expect(document.activeElement).toBe(input);
expect(focusSpy).toHaveBeenLastCalledWith({preventScroll: true});
expect(rafSpy).not.toHaveBeenCalled();
focusSpy.mockRestore();
rafSpy.mockRestore();
});
});
describe('TextInput text size', () => {
it('renders the theme body size outside the iOS zoom gate', () => {
// The 16px floor rides `@supports (-webkit-touch-callout: none)` inside
// `@media (pointer: coarse)` — iOS Safari is the browser that zooms on
// focus under 16px, so the floor targets it alone instead of every
// coarse pointer. jsdom's CSSOM drops at-rule-wrapped declarations it
// cannot parse, so the gate itself is pinned against the sources in
// inputFontFloor.test.ts; what this asserts is the visible result off
// the gate: the plain token size, not a floor.
render(<TextInput label="Name" value="" onChange={() => {}} />);
expect(declaredValue(screen.getByLabelText('Name'), 'font-size')).toBe(
'var(--text-body-size)',
);
});
});
describe('TextInput in a narrow row', () => {
it('lets a filter bar shrink the whole field instead of overflowing', () => {
const {container} = render(
<TextInput label="Search" value="" onChange={() => {}} />,
);
const root = container.querySelector('.astryx-field')!;
expect(getComputedStyle(root).minWidth).toBe('0');
});
});