Skip to content

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

TypeScript

feat(inputs): add statusVariant='tooltip' and dedupe detached status icon (#4492)

Cindy Zhang0921257d5318
diff --git a/.changeset/input-detached-status-icon-dedup.md b/.changeset/input-detached-status-icon-dedup.md
new file mode 100644
index 0000000000..81541c0546
--- /dev/null
+++ b/.changeset/input-detached-status-icon-dedup.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[fix] With `statusVariant="detached"`, bordered inputs no longer render a status icon inside the control (this also covers DateTimeInput, which is fixed to the detached presentation) — the detached message box already carries a leading icon, so the on-field glyph was a duplicate. Also centers the detached message's icon on the first line of text.
+
+@cixzhang
diff --git a/.changeset/input-status-tooltip-variant.md b/.changeset/input-status-tooltip-variant.md
new file mode 100644
index 0000000000..356f7edd11
--- /dev/null
+++ b/.changeset/input-status-tooltip-variant.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[feat] Bordered inputs gain a `statusVariant="tooltip"` option that hides the status message box and surfaces the status as an info-tip on the on-field status icon. The icon is a real focusable button so the status is reachable by everyone: keyboard users tab to it (with a visible focus ring) and see the message on focus, pointer users see it on hover, and touch users tap to toggle it. The message is piped into both the input's and the button's `aria-describedby`, and the tooltip is dismissible with Escape. Added to TextInput, TextArea, NumberInput, DateInput, DateRangeInput, TimeInput, and FileInput.
+
+@cixzhang
diff --git a/apps/storybook/stories/TextInput.stories.tsx b/apps/storybook/stories/TextInput.stories.tsx
index 67b469099d..4040c53950 100644
--- a/apps/storybook/stories/TextInput.stories.tsx
+++ b/apps/storybook/stories/TextInput.stories.tsx
@@ -519,8 +519,10 @@ export const StatusVariantComparison: Story = {
render: () => {
const [a, setA] = useState('invalid@');
const [b, setB] = useState('invalid@');
+ const [c, setC] = useState('invalid@');
return (
- <div style={{display: 'flex', flexDirection: 'column', gap: 24, width: 280}}>
+ <div
+ style={{display: 'flex', flexDirection: 'column', gap: 24, width: 280}}>
<TextInput
label="Attached (default)"
value={a}
@@ -534,6 +536,13 @@ export const StatusVariantComparison: Story = {
status={{type: 'error', message: 'Enter a valid email'}}
statusVariant="detached"
/>
+ <TextInput
+ label="Tooltip (focus, hover, or tap the status icon)"
+ value={c}
+ onChange={setC}
+ status={{type: 'error', message: 'Enter a valid email'}}
+ statusVariant="tooltip"
+ />
</div>
);
},
diff --git a/packages/core/locales/en.json b/packages/core/locales/en.json
index 2cee4d82cc..fa4644c19e 100644
--- a/packages/core/locales/en.json
+++ b/packages/core/locales/en.json
@@ -771,6 +771,18 @@
"defaultMessage": "Clear all {label}",
"description": "Screen-reader-only label on the X that clears every selected value from a MultiSelector. Example: `Clear all Countries`. `{label}` is typically already plural in English."
},
+ "@astryx.input.statusButton.error": {
+ "defaultMessage": "Error details",
+ "description": "Accessible name for the focusable status icon button inside an input when statusVariant is 'tooltip' and the status type is error. Activating or focusing the button reveals the error message in a tooltip. Keep it short — it labels an icon-only button."
+ },
+ "@astryx.input.statusButton.warning": {
+ "defaultMessage": "Warning details",
+ "description": "Accessible name for the focusable status icon button inside an input when statusVariant is 'tooltip' and the status type is warning. Activating or focusing the button reveals the warning message in a tooltip."
+ },
+ "@astryx.input.statusButton.success": {
+ "defaultMessage": "Success details",
+ "description": "Accessible name for the focusable status icon button inside an input when statusVariant is 'tooltip' and the status type is success. Activating or focusing the button reveals the success message in a tooltip."
+ },
"@astryx.numberInput.clearLabel": {
"defaultMessage": "Clear {label}",
"description": "Screen-reader-only label on the X that clears the value from a NumberInput. Example: `Clear Age`, `Clear Quantity`."
diff --git a/packages/core/src/DateInput/DateInput.doc.mjs b/packages/core/src/DateInput/DateInput.doc.mjs
index 3fe71c446c..d43c2d919b 100644
--- a/packages/core/src/DateInput/DateInput.doc.mjs
+++ b/packages/core/src/DateInput/DateInput.doc.mjs
@@ -117,9 +117,9 @@ export const docs = {
},
{
name: 'statusVariant',
- type: "'attached' | 'detached'",
+ type: "'attached' | 'detached' | 'tooltip'",
description:
- 'How the status message is placed relative to the input. attached overlaps directly below the input (bordered treatment); detached floats below as a separate element with spacing.',
+ 'How the status message is placed relative to the input. attached overlaps directly below the input (bordered treatment); detached floats below as a separate element with spacing; tooltip hides the message box and surfaces it in a tooltip on the status icon.',
default: "'attached'",
},
{
@@ -393,9 +393,9 @@ export const docsZh = {
},
{
name: 'statusVariant',
- type: "'attached' | 'detached'",
+ type: "'attached' | 'detached' | 'tooltip'",
description:
- '状态消息相对于输入框的放置方式。attached 直接叠加在输入框下方(带边框处理);detached 作为独立元素浮于下方并留有间距。',
+ '状态消息相对于输入框的放置方式。attached 直接叠加在输入框下方(带边框处理);detached 作为独立元素浮于下方并留有间距;tooltip 隐藏消息框,并在状态图标上以提示气泡形式显示。',
default: "'attached'",
},
{
@@ -506,7 +506,7 @@ export const docsDense = {
placeholder: 'placeholder text in input',
size: 'input control size',
status: 'error/warning/success status w/ message',
- statusVariant: 'How status message is placed: attached overlaps below input; detached floats below w/ spacing.',
+ statusVariant: 'How status message is placed: attached overlaps below input; detached floats below w/ spacing; tooltip hides the box and shows it on the status icon.',
labelTooltip: 'tooltip text via info icon at label end',
hasClear: 'Shows clear button when date is set. Clears value on click.',
numberOfMonths: 'months shown simultaneously in calendar popover',
diff --git a/packages/core/src/DateInput/DateInput.tsx b/packages/core/src/DateInput/DateInput.tsx
index da9dd1d38f..68b4ed13bd 100644
--- a/packages/core/src/DateInput/DateInput.tsx
+++ b/packages/core/src/DateInput/DateInput.tsx
@@ -25,7 +25,6 @@ import {
useTransition,
} from 'react';
import * as stylex from '@stylexjs/stylex';
-import type {IconName} from '../Icon';
import {
colorVars,
sizeVars,
@@ -37,7 +36,6 @@ import {
import {
Field,
type InputStatus,
- type InputStatusType,
inputWrapperStyles,
inputStatusBorderStyles,
inputStatusHoverShadowStyles,
@@ -52,6 +50,7 @@ import {useSize} from '../SizeContext/SizeContext';
import {Spinner} from '../Spinner';
import {Calendar, type ISODateString, type CalendarHandle} from '../Calendar';
import {useCalendarConstraints} from '../Calendar/hooks';
+import {useInputStatusIcon} from '../hooks/useInputStatusIcon';
import {usePopover} from '../Popover';
import {useTooltip} from '../Tooltip';
import {getInputARIA, parseDateInput} from '../utils';
@@ -283,6 +282,7 @@ export interface DateInputProps extends Omit<
* How the status message is placed relative to the input.
* - 'attached': message overlaps directly below the input (bordered treatment)
* - 'detached': message floats below as a separate element with spacing
+ * - 'tooltip': no message box; the status icon becomes a focusable info-tip button that reveals the message on hover, keyboard focus, or tap
* @default 'attached'
*/
statusVariant?: FieldStatusVariant;
@@ -419,30 +419,24 @@ export function DateInput({
isEnabled: showsDisabledMessage,
});
- // Status icon mapping
- const statusIconMap: Record<InputStatusType, IconName> = {
- warning: 'warning',
- error: 'error',
- success: 'success',
- };
-
- const statusIconColorMap: Record<
- InputStatusType,
- 'warning' | 'error' | 'success'
- > = {
- warning: 'warning',
- error: 'error',
- success: 'success',
- };
-
// Constraint checking for text input validation (reuses calendar logic)
const {isDateDisabled} = useCalendarConstraints({min, max, dateConstraints});
+ const {statusIcon, describedBy: statusTooltipDescribedBy} =
+ useInputStatusIcon({
+ status,
+ statusVariant,
+ isInGroup: !!inputGroup,
+ });
+
const {ariaLabelledBy, ariaDescribedBy} = getInputARIA(
inputLabelID,
[
description ? descriptionID : null,
- status?.message ? statusMessageID : null,
+ statusVariant !== 'tooltip' && status?.message ? statusMessageID : null,
+ // The tooltip variant renders no message box; describe the input by the
+ // tooltip's content instead so the status is still announced.
+ statusTooltipDescribedBy,
showsDisabledMessage ? disabledMessageTooltip.describedBy : null,
],
inputGroup,
@@ -727,13 +721,7 @@ export function DateInput({
</button>
)}
{isBusy && <Spinner size="sm" />}
- {status && !inputGroup && (
- <Icon
- icon={statusIconMap[status.type]}
- size="md"
- color={statusIconColorMap[status.type]}
- />
- )}
+ {statusIcon}
{popover.render(
<Calendar
handleRef={calendarRef}
diff --git a/packages/core/src/DateRangeInput/DateRangeInput.doc.mjs b/packages/core/src/DateRangeInput/DateRangeInput.doc.mjs
index cacc4d6c92..60ebefc41f 100644
--- a/packages/core/src/DateRangeInput/DateRangeInput.doc.mjs
+++ b/packages/core/src/DateRangeInput/DateRangeInput.doc.mjs
@@ -129,9 +129,9 @@ export const docs = {
},
{
name: 'statusVariant',
- type: "'attached' | 'detached'",
+ type: "'attached' | 'detached' | 'tooltip'",
description:
- 'How the status message is placed relative to the input. attached overlaps directly below the input (bordered treatment); detached floats below as a separate element with spacing.',
+ 'How the status message is placed relative to the input. attached overlaps directly below the input (bordered treatment); detached floats below as a separate element with spacing; tooltip hides the message box and surfaces it in a tooltip on the status icon.',
default: "'attached'",
},
{
@@ -303,7 +303,7 @@ export const docsDense = {
placeholder: 'placeholder when empty',
size: 'trigger size',
status: 'error/warning/success status',
- statusVariant: 'How status message is placed: attached overlaps below input; detached floats below w/ spacing.',
+ statusVariant: 'How status message is placed: attached overlaps below input; detached floats below w/ spacing; tooltip hides the box and shows it on the status icon.',
labelTooltip: 'tooltip via info icon at label end',
numberOfMonths: 'months in calendar (default 2)',
changeAction:
diff --git a/packages/core/src/DateRangeInput/DateRangeInput.tsx b/packages/core/src/DateRangeInput/DateRangeInput.tsx
index 588d309fc2..d93c71b0a2 100644
--- a/packages/core/src/DateRangeInput/DateRangeInput.tsx
+++ b/packages/core/src/DateRangeInput/DateRangeInput.tsx
@@ -25,7 +25,6 @@ import {
DATE_FORMAT_SHORT,
DATE_FORMAT_SHORT_WITH_YEAR,
} from '../utils/plainDate';
-import type {IconName} from '../Icon';
import {
colorVars,
sizeVars,
@@ -38,7 +37,6 @@ import {
import {
Field,
type InputStatus,
- type InputStatusType,
inputWrapperStyles,
inputStatusBorderStyles,
inputStatusHoverShadowStyles,
@@ -54,6 +52,7 @@ import {mergeProps} from '../utils';
import type {BaseProps} from '../BaseProps';
import type {SizeValue} from '../utils/types';
import {useSize} from '../SizeContext/SizeContext';
+import {useInputStatusIcon} from '../hooks/useInputStatusIcon';
import {themeProps} from '../utils/themeProps';
import {useTranslator} from '../i18n';
@@ -335,6 +334,7 @@ export interface DateRangeInputProps extends Omit<
* How the status message is placed relative to the input.
* - 'attached': message overlaps directly below the input (bordered treatment)
* - 'detached': message floats below as a separate element with spacing
+ * - 'tooltip': no message box; the status icon becomes a focusable info-tip button that reveals the message on hover, keyboard focus, or tap
* @default 'attached'
*/
statusVariant?: FieldStatusVariant;
@@ -431,25 +431,19 @@ export function DateRangeInput({
isEnabled: showsDisabledMessage,
});
- const statusIconMap: Record<InputStatusType, IconName> = {
- warning: 'warning',
- error: 'error',
- success: 'success',
- };
-
- const statusIconColorMap: Record<
- InputStatusType,
- 'warning' | 'error' | 'success'
- > = {
- warning: 'warning',
- error: 'error',
- success: 'success',
- };
+ const {statusIcon, describedBy: statusTooltipDescribedBy} =
+ useInputStatusIcon({
+ status,
+ statusVariant,
+ });
const ariaDescribedBy =
[
description ? descriptionID : null,
- status?.message ? statusMessageID : null,
+ statusVariant !== 'tooltip' && status?.message ? statusMessageID : null,
+ // The tooltip variant renders no message box; describe the input by the
+ // tooltip's content instead so the status is still announced.
+ statusTooltipDescribedBy,
showsDisabledMessage ? disabledMessageTooltip.describedBy : null,
]
.filter(Boolean)
@@ -620,13 +614,7 @@ export function DateRangeInput({
</button>
)}
{isBusy && <Spinner size="sm" />}
- {status && (
- <Icon
- icon={statusIconMap[status.type]}
- size="md"
- color={statusIconColorMap[status.type]}
- />
- )}
+ {statusIcon}
</div>
{popover.render(
<div {...stylex.props(styles.popoverLayout)}>
diff --git a/packages/core/src/DateTimeInput/DateTimeInput.tsx b/packages/core/src/DateTimeInput/DateTimeInput.tsx
index dddf2dc5a2..b3990e1352 100644
--- a/packages/core/src/DateTimeInput/DateTimeInput.tsx
+++ b/packages/core/src/DateTimeInput/DateTimeInput.tsx
@@ -27,7 +27,6 @@ import {
type KeyboardEvent,
} from 'react';
import * as stylex from '@stylexjs/stylex';
-import type {IconName} from '../Icon';
import {
colorVars,
sizeVars,
@@ -40,7 +39,6 @@ import {
import {
Field,
type InputStatus,
- type InputStatusType,
inputWrapperStyles,
inputStatusBorderStyles,
inputStatusHoverShadowStyles,
@@ -54,6 +52,7 @@ import {useCalendarConstraints} from '../Calendar/hooks';
import {usePopover} from '../Popover';
import {useTooltip} from '../Tooltip';
import {useInputContainer} from '../hooks/useInputContainer';
+import {useInputStatusIcon} from '../hooks/useInputStatusIcon';
import {
type ISOTimeString,
parseDateInput,
@@ -470,25 +469,21 @@ export function DateTimeInput({
isEnabled: showsDisabledMessage,
});
- const statusIconMap: Record<InputStatusType, IconName> = {
- warning: 'warning',
- error: 'error',
- success: 'success',
- };
-
- const statusIconColorMap: Record<
- InputStatusType,
- 'warning' | 'error' | 'success'
- > = {
- warning: 'warning',
- error: 'error',
- success: 'success',
- };
+ // DateTimeInput fixes its status presentation to the detached message box,
+ // so the shared helper suppresses the on-field icon (the message box carries
+ // its own leading glyph). Routed through the helper for consistency with the
+ // rest of the bordered input family.
+ const {statusIcon, describedBy: statusTooltipDescribedBy} =
+ useInputStatusIcon({
+ status,
+ statusVariant: 'detached',
+ });
const ariaDescribedBy =
[
description ? descriptionID : null,
status?.message ? statusMessageID : null,
+ statusTooltipDescribedBy,
showsDisabledMessage ? disabledMessageTooltip.describedBy : null,
]
.filter(Boolean)
@@ -976,13 +971,7 @@ export function DateTimeInput({
</button>
)}
{isBusy && <Spinner size="sm" />}
- {status && (
- <Icon
- icon={statusIconMap[status.type]}
- size="md"
- color={statusIconColorMap[status.type]}
- />
- )}
+ {statusIcon}
</div>
{/* Time input */}
diff --git a/packages/core/src/Field/Field.tsx b/packages/core/src/Field/Field.tsx
index aa8f73bb1d..298c363fae 100644
--- a/packages/core/src/Field/Field.tsx
+++ b/packages/core/src/Field/Field.tsx
@@ -22,6 +22,7 @@ import type {BaseProps} from '../BaseProps';
import type {SizeValue} from '../utils/types';
import {FieldLabel} from './FieldLabel';
import {FieldStatus} from '../FieldStatus/FieldStatus';
+import type {FieldStatusVariant} from '../FieldStatus/FieldStatus';
import {spacingVars, borderVars} from '../theme/tokens.stylex';
import type {IconType} from '../Icon';
import {mergeProps} from '../utils';
@@ -156,9 +157,10 @@ export interface FieldProps extends Omit<
* How the status message is rendered relative to the input.
* - 'attached': Status sits directly below the input (default, for bordered inputs)
* - 'detached': Status is a separate element below the field (for checkboxes, switches, sliders)
+ * - 'tooltip': No message box; the input surfaces status through a tooltip on its on-field icon
* @default 'attached'
*/
- statusVariant?: 'attached' | 'detached';
+ statusVariant?: FieldStatusVariant;
/**
* Width of the field. Numbers are treated as pixels, strings are used as-is
* (e.g. `'100%'`). Sizes the whole field — label, control, and status — so
@@ -239,14 +241,17 @@ export function Field({
/>
);
- const statusNode = status?.message ? (
- <FieldStatus
- type={status.type}
- message={status.message}
- id={resolvedMessageID}
- variant={statusVariant}
- />
- ) : null;
+ // The 'tooltip' variant surfaces status through the input's on-field icon
+ // tooltip, so Field renders no message box for it.
+ const statusNode =
+ status?.message && statusVariant !== 'tooltip' ? (
+ <FieldStatus
+ type={status.type}
+ message={status.message}
+ id={resolvedMessageID}
+ variant={statusVariant}
+ />
+ ) : null;
// ─── Horizontal-labels mode ───────────────────────────────────────────
// Use display:contents so the parent grid's `auto 1fr` columns place
diff --git a/packages/core/src/FieldStatus/FieldStatus.tsx b/packages/core/src/FieldStatus/FieldStatus.tsx
index d234333917..5e0a76c92e 100644
--- a/packages/core/src/FieldStatus/FieldStatus.tsx
+++ b/packages/core/src/FieldStatus/FieldStatus.tsx
@@ -71,9 +71,12 @@ const styles = stylex.create({
gap: spacingVars['--spacing-1'],
},
detachedIcon: {
- // Match the height of the first text line so the glyph top-aligns to it
- // (rather than to the flex box) when the message wraps to multiple lines.
- lineHeight: typeScaleVars['--text-supporting-leading'],
+ // Center the glyph within the first text-line box so it aligns to the
+ // first line of the message (rather than the top of the flex row) when the
+ // message wraps to multiple lines.
+ display: 'inline-flex',
+ alignItems: 'center',
+ height: `calc(${typeScaleVars['--text-supporting-size']} * ${typeScaleVars['--text-supporting-leading']})`,
flexShrink: 0,
},
});
@@ -109,6 +112,7 @@ const colorStyles = stylex.create({
export interface FieldStatusVariantMap {
attached: true;
detached: true;
+ tooltip: true;
}
/**
@@ -143,7 +147,9 @@ export interface FieldStatusProps extends BaseProps<HTMLDivElement> {
* decorative for assistive tech (`aria-hidden`): the message text already names
* the status in words and is announced through the live region. The `attached`
* variant keeps its status affordance on the bordered input, so it renders no
- * icon here to avoid a duplicate.
+ * icon here to avoid a duplicate. The `tooltip` variant renders no message box
+ * at all — the input surfaces the status through a tooltip on its on-field
+ * icon — so callers skip rendering FieldStatus for it.
*
* Screen-reader announcements go through the persistent `useAnnounce` live
* regions (assertive for errors, polite otherwise) rather than `role`/
diff --git a/packages/core/src/FileInput/FileInput.doc.mjs b/packages/core/src/FileInput/FileInput.doc.mjs
index 84acc82cd5..041c6d9abf 100644
--- a/packages/core/src/FileInput/FileInput.doc.mjs
+++ b/packages/core/src/FileInput/FileInput.doc.mjs
@@ -121,9 +121,9 @@ export const docs = {
},
{
name: 'statusVariant',
- type: "'attached' | 'detached'",
+ type: "'attached' | 'detached' | 'tooltip'",
description:
- 'How the status message is placed relative to the input. attached overlaps directly below the input (bordered treatment); detached floats below as a separate element with spacing.',
+ 'How the status message is placed relative to the input. attached overlaps directly below the input (bordered treatment); detached floats below as a separate element with spacing; tooltip hides the message box and surfaces it in a tooltip on the status icon.',
default: "'attached'",
},
{
@@ -255,9 +255,9 @@ export const docsZh = {
},
{
name: 'statusVariant',
- type: "'attached' | 'detached'",
+ type: "'attached' | 'detached' | 'tooltip'",
description:
- '状态消息相对于输入框的放置方式。attached 直接叠加在输入框下方(带边框处理);detached 作为独立元素浮于下方并留有间距。',
+ '状态消息相对于输入框的放置方式。attached 直接叠加在输入框下方(带边框处理);detached 作为独立元素浮于下方并留有间距;tooltip 隐藏消息框,并在状态图标上以提示气泡形式显示。',
default: "'attached'",
},
],
@@ -330,7 +330,7 @@ export const docsDense = {
placeholder: 'Placeholder when no files selected.',
mode: "Visual mode: 'input' (compact) or 'dropzone' (drag-and-drop).",
status: 'Validation status; colored border. Message floats below.',
- statusVariant: 'How status message is placed: attached overlaps below input; detached floats below w/ spacing.',
+ statusVariant: 'How status message is placed: attached overlaps below input; detached floats below w/ spacing; tooltip hides the box and shows it on the status icon.',
labelTooltip: 'Tooltip in info icon at label end.',
},
};
diff --git a/packages/core/src/FileInput/FileInput.tsx b/packages/core/src/FileInput/FileInput.tsx
index a5cd9780fc..8467c3372e 100644
--- a/packages/core/src/FileInput/FileInput.tsx
+++ b/packages/core/src/FileInput/FileInput.tsx
@@ -40,13 +40,13 @@ import {
Field,
InputClearButton,
type InputStatus,
- type InputStatusType,
type FieldStatusVariant,
} from '../Field';
-import {Icon, type IconName} from '../Icon';
+import {Icon} from '../Icon';
import {Spinner} from '../Spinner';
import {VisuallyHidden} from '../VisuallyHidden';
import {useAnnounce} from '../hooks/useAnnounce';
+import {useInputStatusIcon} from '../hooks/useInputStatusIcon';
import {useTooltip} from '../Tooltip';
export type {
@@ -353,6 +353,7 @@ export interface FileInputProps extends Omit<
* How the status message is placed relative to the input.
* - 'attached': message overlaps directly below the input (bordered treatment)
* - 'detached': message floats below as a separate element with spacing
+ * - 'tooltip': no message box; the status icon becomes a focusable info-tip button that reveals the message on hover, keyboard focus, or tap
* @default 'attached'
*/
statusVariant?: FieldStatusVariant;
@@ -459,20 +460,11 @@ export function FileInput({
? {type: 'error' as const, message: validationError}
: undefined);
- const statusIconMap: Record<InputStatusType, IconName> = {
- warning: 'warning',
- error: 'error',
- success: 'success',
- };
-
- const statusIconColorMap: Record<
- InputStatusType,
- 'warning' | 'error' | 'success'
- > = {
- warning: 'warning',
- error: 'error',
- success: 'success',
- };
+ const {statusIcon, describedBy: statusTooltipDescribedBy} =
+ useInputStatusIcon({
+ status,
+ statusVariant,
+ });
// Required state. `aria-required` is not a supported property of
// role="button" in WAI-ARIA 1.2 (AT does not announce it there), so the
@@ -484,7 +476,10 @@ export function FileInput({
const ariaDescribedBy =
[
description ? descriptionID : null,
- status?.message ? statusMessageID : null,
+ statusVariant !== 'tooltip' && status?.message ? statusMessageID : null,
+ // The tooltip variant renders no message box; describe the input by the
+ // tooltip's content instead so the status is still announced.
+ statusTooltipDescribedBy,
conveysRequired ? requiredID : null,
showsDisabledMessage ? disabledMessageTooltip.describedBy : null,
]
@@ -696,13 +691,7 @@ export function FileInput({
)}>
{fileNames ?? displayPlaceholder}
</span>
- {status && (
- <Icon
- icon={statusIconMap[status.type]}
- size="md"
- color={statusIconColorMap[status.type]}
- />
- )}
+ {statusIcon}
</>
);
};
diff --git a/packages/core/src/NumberInput/NumberInput.doc.mjs b/packages/core/src/NumberInput/NumberInput.doc.mjs
index ce1b8fdd5c..bd04ade4b4 100644
--- a/packages/core/src/NumberInput/NumberInput.doc.mjs
+++ b/packages/core/src/NumberInput/NumberInput.doc.mjs
@@ -96,9 +96,9 @@ export const docs = {
},
{
name: 'statusVariant',
- type: "'attached' | 'detached'",
+ type: "'attached' | 'detached' | 'tooltip'",
description:
- 'How the status message is placed relative to the input. attached overlaps directly below the input (bordered treatment); detached floats below as a separate element with spacing.',
+ 'How the status message is placed relative to the input. attached overlaps directly below the input (bordered treatment); detached floats below as a separate element with spacing; tooltip hides the message box and surfaces it in a tooltip on the status icon.',
default: "'attached'",
},
{
@@ -284,9 +284,9 @@ export const docsZh = {
},
{
name: 'statusVariant',
- type: "'attached' | 'detached'",
+ type: "'attached' | 'detached' | 'tooltip'",
description:
- '状态消息相对于输入框的放置方式。attached 直接叠加在输入框下方(带边框处理);detached 作为独立元素浮于下方并留有间距。',
+ '状态消息相对于输入框的放置方式。attached 直接叠加在输入框下方(带边框处理);detached 作为独立元素浮于下方并留有间距;tooltip 隐藏消息框,并在状态图标上以提示气泡形式显示。',
default: "'attached'",
},
{
@@ -416,7 +416,7 @@ export const docsDense = {
startIcon: 'Icon at input start.',
labelIcon: 'Icon before label text.',
status: 'Validation status w/ optional message.',
- statusVariant: 'How status message is placed: attached overlaps below input; detached floats below w/ spacing.',
+ statusVariant: 'How status message is placed: attached overlaps below input; detached floats below w/ spacing; tooltip hides the box and shows it on the status icon.',
min: 'Minimum value allowed.',
max: 'Maximum value allowed.',
step: 'Step increment.',
diff --git a/packages/core/src/NumberInput/NumberInput.tsx b/packages/core/src/NumberInput/NumberInput.tsx
index e82581bc19..f51b000927 100644
--- a/packages/core/src/NumberInput/NumberInput.tsx
+++ b/packages/core/src/NumberInput/NumberInput.tsx
@@ -27,7 +27,6 @@ import {
type ReactNode,
} from 'react';
import * as stylex from '@stylexjs/stylex';
-import type {IconName} from '../Icon';
import {
colorVars,
sizeVars,
@@ -39,7 +38,6 @@ import {
import {
Field,
type InputStatus,
- type InputStatusType,
inputWrapperStyles,
inputStatusBorderStyles,
inputStatusHoverShadowStyles,
@@ -52,6 +50,7 @@ import {useTooltip} from '../Tooltip';
import {getInputARIA} from '../utils';
import {useSize} from '../SizeContext/SizeContext';
import {useInputContainer} from '../hooks/useInputContainer';
+import {useInputStatusIcon} from '../hooks/useInputStatusIcon';
import {useInputGroup} from '../InputGroup/InputGroupContext';
const styles = stylex.create({
@@ -212,6 +211,7 @@ interface NumberInputPropsBase extends Omit<
* How the status message is placed relative to the input.
* - 'attached': message overlaps directly below the input (bordered treatment)
* - 'detached': message floats below as a separate element with spacing
+ * - 'tooltip': no message box; the status icon becomes a focusable info-tip button that reveals the message on hover, keyboard focus, or tap
* @default 'attached'
*/
statusVariant?: FieldStatusVariant;
@@ -436,20 +436,12 @@ export function NumberInput({
isEnabled: showsDisabledMessage,
});
- const statusIconMap: Record<InputStatusType, IconName> = {
- warning: 'warning',
- error: 'error',
- success: 'success',
- };
-
- const statusIconColorMap: Record<
- InputStatusType,
- 'warning' | 'error' | 'success'
- > = {
- warning: 'warning',
- error: 'error',
- success: 'success',
- };
+ const {statusIcon, describedBy: statusTooltipDescribedBy} =
+ useInputStatusIcon({
+ status,
+ statusVariant,
+ isInGroup: !!inputGroup,
+ });
const {ariaLabelledBy, ariaDescribedBy} = getInputARIA(
inputLabelID,
@@ -457,7 +449,12 @@ export function NumberInput({
description ? descriptionID : null,
// The status message element is rendered by Field, which is skipped
// inside an InputGroup — only reference it when it actually exists.
- !inputGroup && status?.message ? statusMessageID : null,
+ !inputGroup && statusVariant !== 'tooltip' && status?.message
+ ? statusMessageID
+ : null,
+ // The tooltip variant renders no message box; describe the input by the
+ // tooltip's content instead so the status is still announced.
+ statusTooltipDescribedBy,
units ? unitsID : null,
showsDisabledMessage ? disabledMessageTooltip.describedBy : null,
],
@@ -686,13 +683,7 @@ export function NumberInput({
<Icon icon="close" size="sm" color="secondary" />
</button>
)}
- {status && !inputGroup && (
- <Icon
- icon={statusIconMap[status.type]}
- size="md"
- color={statusIconColorMap[status.type]}
- />
- )}
+ {statusIcon}
</div>
);
diff --git a/packages/core/src/TextArea/TextArea.doc.mjs b/packages/core/src/TextArea/TextArea.doc.mjs
index a2ea1e54ad..af7bbc6637 100644
--- a/packages/core/src/TextArea/TextArea.doc.mjs
+++ b/packages/core/src/TextArea/TextArea.doc.mjs
@@ -108,9 +108,9 @@ export const docs = {
},
{
name: 'statusVariant',
- type: "'attached' | 'detached'",
+ type: "'attached' | 'detached' | 'tooltip'",
description:
- 'How the status message is placed relative to the input. attached overlaps directly below the input (bordered treatment); detached floats below as a separate element with spacing.',
+ 'How the status message is placed relative to the input. attached overlaps directly below the input (bordered treatment); detached floats below as a separate element with spacing; tooltip hides the message box and surfaces it in a tooltip on the status icon.',
default: "'attached'",
},
{
@@ -288,9 +288,9 @@ export const docsZh = {
},
{
name: 'statusVariant',
- type: "'attached' | 'detached'",
+ type: "'attached' | 'detached' | 'tooltip'",
description:
- '状态消息相对于输入框的放置方式。attached 直接叠加在输入框下方(带边框处理);detached 作为独立元素浮于下方并留有间距。',
+ '状态消息相对于输入框的放置方式。attached 直接叠加在输入框下方(带边框处理);detached 作为独立元素浮于下方并留有间距;tooltip 隐藏消息框,并在状态图标上以提示气泡形式显示。',
default: "'attached'",
},
{
@@ -403,7 +403,7 @@ export const docsDense = {
rows: 'Visible text rows.',
maxLength: 'Max chars allowed. Shows counter (current/max) below textarea. No native enforcement.',
status: 'Colored border+icon status. Optional floating message below textarea.',
- statusVariant: 'How status message is placed: attached overlaps below input; detached floats below w/ spacing.',
+ statusVariant: 'How status message is placed: attached overlaps below input; detached floats below w/ spacing; tooltip hides the box and shows it on the status icon.',
labelTooltip: 'Tooltip in info icon at label end.',
startIcon: 'Icon inside leading edge of textarea wrapper.',
hasSpellCheck: 'Enables/disables browser spell checking.',
diff --git a/packages/core/src/TextArea/TextArea.tsx b/packages/core/src/TextArea/TextArea.tsx
index 66ca5c2f91..81ca58a250 100644
--- a/packages/core/src/TextArea/TextArea.tsx
+++ b/packages/core/src/TextArea/TextArea.tsx
@@ -27,7 +27,6 @@ import {
type ReactNode,
} from 'react';
import * as stylex from '@stylexjs/stylex';
-import type {IconName} from '../Icon';
import {
colorVars,
spacingVars,
@@ -42,13 +41,14 @@ import {
inputStatusFocusWithinStyles,
type FieldStatusVariant,
} from '../Field';
-import {Icon, renderIconSlot, type IconType} from '../Icon';
+import {renderIconSlot, type IconType} from '../Icon';
import {Spinner} from '../Spinner';
import {useTooltip} from '../Tooltip';
import {mergeProps, mergeRefs} from '../utils';
import type {BaseProps} from '../BaseProps';
import type {SizeValue} from '../utils/types';
import {useInputContainer} from '../hooks/useInputContainer';
+import {useInputStatusIcon} from '../hooks/useInputStatusIcon';
import {useSize} from '../SizeContext/SizeContext';
import {themeProps} from '../utils/themeProps';
import {VisuallyHidden} from '../VisuallyHidden';
@@ -222,6 +222,7 @@ export interface TextAreaProps extends Omit<
* How the status message is placed relative to the input.
* - 'attached': message overlaps directly below the input (bordered treatment)
* - 'detached': message floats below as a separate element with spacing
+ * - 'tooltip': no message box; the status icon becomes a focusable info-tip button that reveals the message on hover, keyboard focus, or tap
* @default 'attached'
*/
statusVariant?: FieldStatusVariant;
@@ -350,25 +351,19 @@ export function TextArea({
isEnabled: showsDisabledMessage,
});
- const statusIconMap: Record<TextAreaStatusType, IconName> = {
- warning: 'warning',
- error: 'error',
- success: 'success',
- };
-
- const statusIconColorMap: Record<
- TextAreaStatusType,
- 'warning' | 'error' | 'success'
- > = {
- warning: 'warning',
- error: 'error',
- success: 'success',
- };
+ const {statusIcon, describedBy: statusTooltipDescribedBy} =
+ useInputStatusIcon({
+ status,
+ statusVariant,
+ });
const ariaDescribedBy =
[
description ? descriptionID : null,
- status?.message ? statusMessageID : null,
+ statusVariant !== 'tooltip' && status?.message ? statusMessageID : null,
+ // The tooltip variant renders no message box; describe the input by the
+ // tooltip's content instead so the status is still announced.
+ statusTooltipDescribedBy,
maxLength != null ? counterID : null,
showsDisabledMessage ? disabledMessageTooltip.describedBy : null,
]
@@ -490,14 +485,8 @@ export function TextArea({
)}
/>
{isBusy && <Spinner size="sm" />}
- {status && (
- <span {...stylex.props(styles.statusIcon)}>
- <Icon
- icon={statusIconMap[status.type]}
- size="md"
- color={statusIconColorMap[status.type]}
- />
- </span>
+ {statusIcon && (
+ <span {...stylex.props(styles.statusIcon)}>{statusIcon}</span>
)}
</div>
{maxLength != null && (
diff --git a/packages/core/src/TextInput/TextInput.doc.mjs b/packages/core/src/TextInput/TextInput.doc.mjs
index 9f5d277100..837cd2ff8f 100644
--- a/packages/core/src/TextInput/TextInput.doc.mjs
+++ b/packages/core/src/TextInput/TextInput.doc.mjs
@@ -116,9 +116,9 @@ export const docs = {
},
{
name: 'statusVariant',
- type: "'attached' | 'detached'",
+ type: "'attached' | 'detached' | 'tooltip'",
description:
- 'How the status message is placed relative to the input. attached overlaps directly below the input (bordered treatment); detached floats below as a separate element with spacing.',
+ 'How the status message is placed relative to the input. attached overlaps directly below the input (bordered treatment); detached floats below as a separate element with spacing; tooltip hides the message box and surfaces it in a tooltip on the status icon.',
default: "'attached'",
},
{
@@ -283,9 +283,9 @@ export const docsZh = {
},
{
name: 'statusVariant',
- type: "'attached' | 'detached'",
+ type: "'attached' | 'detached' | 'tooltip'",
description:
- '状态消息相对于输入框的放置方式。attached 直接叠加在输入框下方(带边框处理);detached 作为独立元素浮于下方并留有间距。',
+ '状态消息相对于输入框的放置方式。attached 直接叠加在输入框下方(带边框处理);detached 作为独立元素浮于下方并留有间距;tooltip 隐藏消息框,并在状态图标上以提示气泡形式显示。',
default: "'attached'",
},
{
@@ -382,7 +382,7 @@ export const docsDense = {
labelTooltip: 'Tooltip in info icon at label end.',
startIcon: 'SVG icon at input start (e.g. heroicons or lucide).',
status: 'Validation status; colored border+icon. Message floats below. Error sets aria-invalid.',
- statusVariant: 'How status message is placed: attached overlaps below input; detached floats below w/ spacing.',
+ statusVariant: 'How status message is placed: attached overlaps below input; detached floats below w/ spacing; tooltip hides the box and shows it on the status icon.',
hasClear: 'Shows clear button when input has value. Clears value on click.',
hasAutoFocus: 'Auto-focus input on mount.',
htmlName: 'HTML name attr for form submissions.',
diff --git a/packages/core/src/TextInput/TextInput.test.tsx b/packages/core/src/TextInput/TextInput.test.tsx
index 35a5bf2980..74c060db1a 100644
--- a/packages/core/src/TextInput/TextInput.test.tsx
+++ b/packages/core/src/TextInput/TextInput.test.tsx
@@ -681,11 +681,15 @@ describe('TextInput', () => {
});
});
-
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'}} />,
+ <TextInput
+ label="Email"
+ value=""
+ onChange={() => {}}
+ status={{type: 'error', message: 'Invalid email'}}
+ />,
);
expect(container.querySelector('.astryx-field-status')).toHaveAttribute(
'data-variant',
@@ -695,11 +699,113 @@ describe('TextInput statusVariant forwarding', () => {
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" />,
+ <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);
+ });
});
diff --git a/packages/core/src/TextInput/TextInput.tsx b/packages/core/src/TextInput/TextInput.tsx
index e67f898df9..0e1357e7ad 100644
--- a/packages/core/src/TextInput/TextInput.tsx
+++ b/packages/core/src/TextInput/TextInput.tsx
@@ -27,7 +27,6 @@ import {
type ReactNode,
} from 'react';
import * as stylex from '@stylexjs/stylex';
-import type {IconName} from '../Icon';
import {
colorVars,
sizeVars,
@@ -39,7 +38,6 @@ import {
import {
Field,
type InputStatus,
- type InputStatusType,
inputWrapperStyles,
inputStatusBorderStyles,
inputStatusHoverShadowStyles,
@@ -120,6 +118,7 @@ export type {
import {mergeProps, mergeRefs} from '../utils';
import {useSize} from '../SizeContext/SizeContext';
import {useInputContainer} from '../hooks/useInputContainer';
+import {useInputStatusIcon} from '../hooks/useInputStatusIcon';
import {useInputGroup} from '../InputGroup/InputGroupContext';
import type {BaseProps} from '../BaseProps';
import type {SizeValue} from '../utils/types';
@@ -203,6 +202,7 @@ export interface TextInputProps extends Omit<
* How the status message is placed relative to the input.
* - 'attached': message overlaps directly below the input (bordered treatment)
* - 'detached': message floats below as a separate element with spacing
+ * - 'tooltip': no message box; the status icon becomes a focusable info-tip button that reveals the message on hover, keyboard focus, or tap
* @default 'attached'
*/
statusVariant?: FieldStatusVariant;
@@ -337,20 +337,12 @@ export function TextInput({
isEnabled: showsDisabledMessage,
});
- const statusIconMap: Record<InputStatusType, IconName> = {
- warning: 'warning',
- error: 'error',
- success: 'success',
- };
-
- const statusIconColorMap: Record<
- InputStatusType,
- 'warning' | 'error' | 'success'
- > = {
- warning: 'warning',
- error: 'error',
- success: 'success',
- };
+ const {statusIcon, describedBy: statusTooltipDescribedBy} =
+ useInputStatusIcon({
+ status,
+ statusVariant,
+ isInGroup: !!inputGroup,
+ });
const {ariaLabelledBy, ariaDescribedBy} = getInputARIA(
inputLabelID,
@@ -358,7 +350,12 @@ export function TextInput({
description ? descriptionID : null,
// The status message element is rendered by Field, which is skipped
// inside an InputGroup — only reference it when it actually exists.
- !inputGroup && status?.message ? statusMessageID : null,
+ !inputGroup && statusVariant !== 'tooltip' && status?.message
+ ? statusMessageID
+ : null,
+ // The tooltip variant renders no message box; describe the input by the
+ // tooltip's content instead so the status is still announced.
+ statusTooltipDescribedBy,
showsDisabledMessage ? disabledMessageTooltip.describedBy : null,
],
inputGroup,
@@ -467,13 +464,7 @@ export function TextInput({
</button>
)}
{isBusy && <Spinner size="sm" />}
- {status && !inputGroup && (
- <Icon
- icon={statusIconMap[status.type]}
- size="md"
- color={statusIconColorMap[status.type]}
- />
- )}
+ {statusIcon}
</div>
);
diff --git a/packages/core/src/TimeInput/TimeInput.doc.mjs b/packages/core/src/TimeInput/TimeInput.doc.mjs
index 643c26d780..7dcd087e06 100644
--- a/packages/core/src/TimeInput/TimeInput.doc.mjs
+++ b/packages/core/src/TimeInput/TimeInput.doc.mjs
@@ -231,9 +231,9 @@ export const docs = {
},
{
name: 'statusVariant',
- type: "'attached' | 'detached'",
+ type: "'attached' | 'detached' | 'tooltip'",
description:
- 'How the status message is placed relative to the input. attached overlaps directly below the input (bordered treatment); detached floats below as a separate element with spacing.',
+ 'How the status message is placed relative to the input. attached overlaps directly below the input (bordered treatment); detached floats below as a separate element with spacing; tooltip hides the message box and surfaces it in a tooltip on the status icon.',
default: "'attached'",
},
{
@@ -381,9 +381,9 @@ export const docsZh = {
},
{
name: 'statusVariant',
- type: "'attached' | 'detached'",
+ type: "'attached' | 'detached' | 'tooltip'",
description:
- '状态消息相对于输入框的放置方式。attached 直接叠加在输入框下方(带边框处理);detached 作为独立元素浮于下方并留有间距。',
+ '状态消息相对于输入框的放置方式。attached 直接叠加在输入框下方(带边框处理);detached 作为独立元素浮于下方并留有间距;tooltip 隐藏消息框,并在状态图标上以提示气泡形式显示。',
default: "'attached'",
},
{
@@ -559,7 +559,7 @@ export const docsDense = {
placeholder: 'Placeholder when empty. Focused+empty shows format hint.',
size: 'Input element height.',
status: 'Colored border+icon. Message rendered below input.',
- statusVariant: 'How status message is placed: attached overlaps below input; detached floats below w/ spacing.',
+ statusVariant: 'How status message is placed: attached overlaps below input; detached floats below w/ spacing; tooltip hides the box and shows it on the status icon.',
labelTooltip: 'Tooltip as info icon at label row end.',
xstyle:
'StyleX styles for layout customization. Must be stylex.create() value, not inline style.',
diff --git a/packages/core/src/TimeInput/TimeInput.tsx b/packages/core/src/TimeInput/TimeInput.tsx
index 27e2c6c8a8..8371c8c073 100644
--- a/packages/core/src/TimeInput/TimeInput.tsx
+++ b/packages/core/src/TimeInput/TimeInput.tsx
@@ -29,7 +29,6 @@ import {
type FocusEvent,
} from 'react';
import * as stylex from '@stylexjs/stylex';
-import type {IconName} from '../Icon';
import {
colorVars,
sizeVars,
@@ -41,7 +40,6 @@ import {
import {
Field,
type InputStatus,
- type InputStatusType,
inputWrapperStyles,
inputStatusBorderStyles,
inputStatusHoverShadowStyles,
@@ -68,6 +66,7 @@ import type {SizeValue} from '../utils/types';
import {useSize} from '../SizeContext/SizeContext';
import {useAnnounce} from '../hooks/useAnnounce';
import {useInputContainer} from '../hooks/useInputContainer';
+import {useInputStatusIcon} from '../hooks/useInputStatusIcon';
import {useInputGroup} from '../InputGroup/InputGroupContext';
import {groupStyles} from '../InputGroup/groupStyles';
import {useTooltip} from '../Tooltip';
@@ -303,6 +302,7 @@ export interface TimeInputProps extends Omit<
* How the status message is placed relative to the input.
* - 'attached': message overlaps directly below the input (bordered treatment)
* - 'detached': message floats below as a separate element with spacing
+ * - 'tooltip': no message box; the status icon becomes a focusable info-tip button that reveals the message on hover, keyboard focus, or tap
* @default 'attached'
*/
statusVariant?: FieldStatusVariant;
@@ -409,26 +409,21 @@ export function TimeInput({
});
// Status icon mapping
- const statusIconMap: Record<InputStatusType, IconName> = {
- warning: 'warning',
- error: 'error',
- success: 'success',
- };
-
- const statusIconColorMap: Record<
- InputStatusType,
- 'warning' | 'error' | 'success'
- > = {
- warning: 'warning',
- error: 'error',
- success: 'success',
- };
+ const {statusIcon, describedBy: statusTooltipDescribedBy} =
+ useInputStatusIcon({
+ status,
+ statusVariant,
+ isInGroup: !!inputGroup,
+ });
const {ariaLabelledBy, ariaDescribedBy} = getInputARIA(
inputLabelID,
[
description ? descriptionID : null,
- status?.message ? statusMessageID : null,
+ statusVariant !== 'tooltip' && status?.message ? statusMessageID : null,
+ // The tooltip variant renders no message box; describe the input by the
+ // tooltip's content instead so the status is still announced.
+ statusTooltipDescribedBy,
showsDisabledMessage ? disabledMessageTooltip.describedBy : null,
],
inputGroup,
@@ -690,13 +685,7 @@ export function TimeInput({
<Icon icon="close" size="sm" color="secondary" />
</button>
)}
- {status && !inputGroup && (
- <Icon
- icon={statusIconMap[status.type]}
- size="md"
- color={statusIconColorMap[status.type]}
- />
- )}
+ {statusIcon}
</div>
);
diff --git a/packages/core/src/hooks/index.ts b/packages/core/src/hooks/index.ts
index 5303684933..c0665beb4b 100644
--- a/packages/core/src/hooks/index.ts
+++ b/packages/core/src/hooks/index.ts
@@ -76,6 +76,12 @@ export type {
export {useInputContainer} from './useInputContainer';
export type {UseInputContainerOptions} from './useInputContainer';
+export {useInputStatusIcon} from './useInputStatusIcon';
+export type {
+ UseInputStatusIconOptions,
+ UseInputStatusIconReturn,
+} from './useInputStatusIcon';
+
export {useInteractiveRole} from './useInteractiveRole';
export type {
InteractiveRole,
diff --git a/packages/core/src/hooks/useInputStatusIcon.test.tsx b/packages/core/src/hooks/useInputStatusIcon.test.tsx
new file mode 100644
index 0000000000..a2a62de920
--- /dev/null
+++ b/packages/core/src/hooks/useInputStatusIcon.test.tsx
@@ -0,0 +1,162 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {describe, it, expect} from 'vitest';
+import type {ReactElement} from 'react';
+import {render, screen} from '@testing-library/react';
+import {TextInput} from '../TextInput/TextInput';
+import {TextArea} from '../TextArea/TextArea';
+import {NumberInput} from '../NumberInput/NumberInput';
+import {DateInput} from '../DateInput/DateInput';
+import {DateRangeInput} from '../DateRangeInput/DateRangeInput';
+import {TimeInput} from '../TimeInput/TimeInput';
+import {FileInput} from '../FileInput/FileInput';
+import type {FieldStatusVariant} from '../FieldStatus/FieldStatus';
+
+// Every id referenced by an aria-describedby must resolve to an element in the
+// document (WCAG 1.3.1) — a described-by pointing at a non-rendered node is a
+// dangling reference. The tooltip variant is the interesting case: it swaps the
+// message box for a tooltip layer, so the referenced ids change per variant.
+function expectNoDanglingDescribedBy(root: HTMLElement) {
+ for (const el of Array.from(root.querySelectorAll('[aria-describedby]'))) {
+ const value = el.getAttribute('aria-describedby') ?? '';
+ for (const id of value.split(/\s+/).filter(Boolean)) {
+ expect(
+ document.getElementById(id),
+ `dangling aria-describedby id "${id}" on <${el.tagName.toLowerCase()}>`,
+ ).not.toBeNull();
+ }
+ }
+}
+
+const VARIANTS: FieldStatusVariant[] = ['attached', 'detached', 'tooltip'];
+
+const INPUTS: [string, (variant: FieldStatusVariant) => ReactElement][] = [
+ [
+ 'TextInput',
+ v => (
+ <TextInput
+ label="Field"
+ value=""
+ onChange={() => {}}
+ status={{type: 'error', message: 'Message'}}
+ statusVariant={v}
+ />
+ ),
+ ],
+ [
+ 'TextArea',
+ v => (
+ <TextArea
+ label="Field"
+ value=""
+ onChange={() => {}}
+ status={{type: 'error', message: 'Message'}}
+ statusVariant={v}
+ />
+ ),
+ ],
+ [
+ 'NumberInput',
+ v => (
+ <NumberInput
+ label="Field"
+ value={undefined}
+ onChange={() => {}}
+ status={{type: 'error', message: 'Message'}}
+ statusVariant={v}
+ />
+ ),
+ ],
+ [
+ 'DateInput',
+ v => (
+ <DateInput
+ label="Field"
+ value={undefined}
+ onChange={() => {}}
+ status={{type: 'error', message: 'Message'}}
+ statusVariant={v}
+ />
+ ),
+ ],
+ [
+ 'DateRangeInput',
+ v => (
+ <DateRangeInput
+ label="Field"
+ value={null}
+ onChange={() => {}}
+ status={{type: 'error', message: 'Message'}}
+ statusVariant={v}
+ />
+ ),
+ ],
+ [
+ 'TimeInput',
+ v => (
+ <TimeInput
+ label="Field"
+ value={undefined}
+ onChange={() => {}}
+ status={{type: 'error', message: 'Message'}}
+ statusVariant={v}
+ />
+ ),
+ ],
+ [
+ 'FileInput',
+ v => (
+ <FileInput
+ label="Field"
+ value={null}
+ onChange={() => {}}
+ status={{type: 'error', message: 'Message'}}
+ statusVariant={v}
+ />
+ ),
+ ],
+];
+
+describe('useInputStatusIcon — no dangling aria-describedby (WCAG 1.3.1)', () => {
+ for (const [name, make] of INPUTS) {
+ for (const variant of VARIANTS) {
+ it(`${name} / statusVariant="${variant}"`, () => {
+ const {container} = render(make(variant));
+ expectNoDanglingDescribedBy(container);
+ });
+ }
+ }
+
+ it('tooltip variant links the input to the rendered tooltip element', () => {
+ render(
+ <TextInput
+ label="Field"
+ value=""
+ onChange={() => {}}
+ status={{type: 'error', message: 'Message'}}
+ statusVariant="tooltip"
+ />,
+ );
+ const input = screen.getByRole('textbox');
+ const tooltip = screen.getByRole('tooltip', {hidden: true});
+ expect(input.getAttribute('aria-describedby')).toContain(tooltip.id);
+ });
+
+ it('does not render a tooltip (or reference one) when there is no message', () => {
+ // No message → the tooltip variant renders no tooltip layer and no
+ // described-by should point at a non-existent status element.
+ const {container} = render(
+ <TextInput
+ label="Field"
+ value=""
+ onChange={() => {}}
+ status={{type: 'error'}}
+ statusVariant="tooltip"
+ />,
+ );
+ expect(
+ screen.queryByRole('tooltip', {hidden: true}),
+ ).not.toBeInTheDocument();
+ expectNoDanglingDescribedBy(container);
+ });
+});
diff --git a/packages/core/src/hooks/useInputStatusIcon.tsx b/packages/core/src/hooks/useInputStatusIcon.tsx
new file mode 100644
index 0000000000..0b1aa44cec
--- /dev/null
+++ b/packages/core/src/hooks/useInputStatusIcon.tsx
@@ -0,0 +1,224 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file useInputStatusIcon.tsx
+ * @input Input status, statusVariant, and InputGroup awareness
+ * @output The on-field status icon element (with tooltip) and aria-describedby wiring
+ * @position Shared hook for bordered inputs that render a status affordance inside the control
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/hooks/index.ts (exports)
+ *
+ * Centralizes the on-field status icon across the bordered inputs (TextInput,
+ * TextArea, NumberInput, DateInput, DateTimeInput, DateRangeInput, TimeInput,
+ * FileInput) so the three statusVariants behave consistently:
+ *
+ * - `attached` → icon sits inside the control; the message box below carries
+ * the text.
+ * - `detached` → the detached message box renders its OWN leading icon, so the
+ * on-field icon is suppressed here to avoid a duplicate glyph.
+ * - `tooltip` → no message box renders; the status is surfaced through an
+ * info-tip on the on-field icon. The icon is a real focusable `<button>` so
+ * the status is reachable by every user, not just those with hover or a
+ * screen reader:
+ * - Keyboard (no AT): the button is in the tab order (WCAG 2.1.1) with a
+ * visible focus ring (WCAG 2.4.7); focusing it opens the tooltip.
+ * - Pointer: hover opens it (guarded to fine pointers).
+ * - Touch: hover is unavailable, so a tap toggles the tooltip open/closed.
+ * - Assistive tech: the button has an accessible name (its status type,
+ * WCAG 4.1.2) and is described by the message via `aria-describedby`.
+ * - Dismissible with Escape and hoverable (WCAG 1.4.13) via useTooltip.
+ */
+
+import {useCallback, useEffect, useState} from 'react';
+import type {ReactNode} from 'react';
+import * as stylex from '@stylexjs/stylex';
+import {Icon, type IconName, type IconSize} from '../Icon';
+import type {FieldStatusVariant} from '../FieldStatus/FieldStatus';
+import type {InputStatus, InputStatusType} from '../Field/types';
+import {useTooltip} from '../Tooltip';
+import {useTranslator} from '../i18n';
+import {colorVars, radiusVars} from '../theme/tokens.stylex';
+
+/**
+ * Maps each status type to its glyph. Shared so every input shows the same icon
+ * for a given status, matching the detached message box's leading icon.
+ */
+const STATUS_ICON: Record<InputStatusType, IconName> = {
+ warning: 'warning',
+ error: 'error',
+ success: 'success',
+};
+
+/**
+ * Accessible-name i18n keys for the focusable status button, keyed by type.
+ */
+const STATUS_BUTTON_LABEL_KEY: Record<InputStatusType, string> = {
+ warning: '@astryx.input.statusButton.warning',
+ error: '@astryx.input.statusButton.error',
+ success: '@astryx.input.statusButton.success',
+};
+
+const styles = stylex.create({
+ // Contain the anchor so the tooltip positions against the icon, and keep the
+ // glyph vertically centered within the input control.
+ iconAnchor: {
+ display: 'inline-flex',
+ alignItems: 'center',
+ },
+ // The tooltip-variant status affordance is a real button so it is keyboard
+ // focusable and tappable. Strip the native chrome and show only a focus ring.
+ statusButton: {
+ display: 'inline-flex',
+ alignItems: 'center',
+ justifyContent: 'center',
+ padding: 0,
+ margin: 0,
+ border: 'none',
+ background: 'none',
+ color: 'inherit',
+ cursor: 'pointer',
+ borderRadius: radiusVars['--radius-full'],
+ outlineWidth: {default: null, ':focus-visible': '2px'},
+ outlineStyle: {default: null, ':focus-visible': 'solid'},
+ outlineColor: {
+ default: null,
+ ':focus-visible': colorVars['--color-accent'],
+ },
+ outlineOffset: {default: null, ':focus-visible': '2px'},
+ },
+});
+
+export interface UseInputStatusIconOptions {
+ /** The input's status, or undefined when there is none. */
+ status?: InputStatus;
+ /** How the status is presented relative to the input. */
+ statusVariant?: FieldStatusVariant;
+ /** Whether the input is inside an InputGroup (which owns status rendering). */
+ isInGroup?: boolean;
+ /** Size of the on-field icon. @default 'md' */
+ size?: IconSize;
+}
+
+export interface UseInputStatusIconReturn {
+ /**
+ * The on-field status affordance to render inside the input container —
+ * the status icon (plain, for attached) or a focusable info-tip button plus
+ * its tooltip layer (for the `tooltip` variant). `null` when no icon should
+ * render (no status, `detached` variant, or inside a group).
+ */
+ statusIcon: ReactNode;
+ /**
+ * ID to add to the input's `aria-describedby` when — and only when — the
+ * status is surfaced through a rendered tooltip layer (the `tooltip` variant
+ * with a message). It is `undefined` in every other case (no status, no
+ * message, `attached`/`detached`, or inside a group), so call-sites can drop
+ * it straight into their described-by list without a dangling reference: the
+ * id is present exactly when its tooltip element is in the DOM.
+ */
+ describedBy: string | undefined;
+}
+
+/**
+ * Builds the on-field status icon and its accessibility wiring for a bordered
+ * input. See the file header for the per-variant behavior.
+ */
+export function useInputStatusIcon({
+ status,
+ statusVariant = 'attached',
+ isInGroup = false,
+ size = 'md',
+}: UseInputStatusIconOptions): UseInputStatusIconReturn {
+ const t = useTranslator();
+ const isTooltipVariant = statusVariant === 'tooltip';
+ const hasTooltip = isTooltipVariant && !!status?.message;
+
+ // Touch tap-to-toggle. Hover is unavailable on touch, and useTooltip
+ // suppresses simulated hover there, so on touch a tap controls visibility.
+ // `undefined` leaves the tooltip uncontrolled (pointer + keyboard drive it);
+ // a boolean takes control for the current open/close cycle.
+ const [tapOpen, setTapOpen] = useState<boolean | undefined>(undefined);
+
+ const tooltip = useTooltip({
+ placement: 'above',
+ isEnabled: hasTooltip,
+ isOpen: tapOpen,
+ });
+
+ // Re-hand control back to hover/focus once a tap-opened tooltip is dismissed
+ // (Escape/outside interaction), so subsequent pointer/keyboard use behaves
+ // normally.
+ const handleButtonBlur = useCallback(() => {
+ setTapOpen(undefined);
+ }, []);
+
+ const handleButtonClick = useCallback(() => {
+ // Only take control on touch/hover-less devices. On hover-capable devices
+ // pointer hover and keyboard focus already drive the tooltip (uncontrolled),
+ // so a click-toggle would fight them; leave it uncontrolled there.
+ if (
+ typeof window === 'undefined' ||
+ typeof window.matchMedia !== 'function' ||
+ !window.matchMedia('(hover: none)').matches
+ ) {
+ return;
+ }
+ setTapOpen(prev => (prev === true ? false : true));
+ }, []);
+
+ // Dismiss a tap-opened tooltip on Escape and return to the uncontrolled
+ // state (useTooltip owns Escape for the uncontrolled case, but while we hold
+ // control via isOpen it does not, so mirror it here).
+ useEffect(() => {
+ if (tapOpen !== true) {
+ return;
+ }
+ const onKeyDown = (e: KeyboardEvent) => {
+ if (e.key === 'Escape') {
+ setTapOpen(undefined);
+ }
+ };
+ document.addEventListener('keydown', onKeyDown);
+ return () => document.removeEventListener('keydown', onKeyDown);
+ }, [tapOpen]);
+
+ // Inside a group the group owns status rendering; the detached message box
+ // renders its own leading icon, so the on-field icon would duplicate it.
+ const shouldRenderIcon =
+ !!status && !isInGroup && statusVariant !== 'detached';
+
+ if (!shouldRenderIcon) {
+ return {statusIcon: null, describedBy: undefined};
+ }
+
+ const icon = (
+ <Icon icon={STATUS_ICON[status.type]} size={size} color={status.type} />
+ );
+
+ // Attached (and tooltip-without-message) variants: plain, non-interactive
+ // icon. The message box (attached) already carries the text.
+ if (!hasTooltip) {
+ return {statusIcon: icon, describedBy: undefined};
+ }
+
+ return {
+ statusIcon: (
+ <>
+ <button
+ type="button"
+ ref={tooltip.ref}
+ aria-label={t(STATUS_BUTTON_LABEL_KEY[status.type])}
+ aria-describedby={tooltip.describedBy}
+ onClick={handleButtonClick}
+ onBlur={handleButtonBlur}
+ {...stylex.props(styles.statusButton)}>
+ {icon}
+ </button>
+ {tooltip.renderTooltip(status.message)}
+ </>
+ ),
+ describedBy: tooltip.describedBy,
+ };
+}