An open source design system that's fully customizable and agent ready
TypeScript
// Copyright (c) Meta Platforms, Inc. and affiliates.
'use client';
/**
* @file NumberInput.tsx
* @input Uses React, useId, useState, useMemo, useCallback, useEffect, Field, Icon, InputGroupContext
* @output Exports NumberInput component, NumberInputProps; optional steppers are hidden on coarse pointers, and a held one repeats into the draft
* @position Core implementation; consumed by index.ts, tested by NumberInput.test.tsx
*
* SYNC: When modified, update these files to stay in sync:
* - /packages/core/src/NumberInput/numberParser.ts (locale-aware parsing)
* - /packages/core/src/NumberInput/numberInputCommit.ts (draft commit policy)
* - /packages/core/src/NumberInput/NumberInput.doc.mjs (props table, features, implementation notes)
* - /packages/core/src/NumberInput/NumberInput.test.tsx (tests for new/changed behavior)
* - /packages/core/src/NumberInput/index.ts (exports if types change)
* - /apps/storybook/stories/NumberInput.stories.tsx (storybook stories)
* - /packages/cli/assets/templates/blocks/components/NumberInput/ (showcase blocks)
*/
import {
use,
useId,
useState,
useMemo,
useCallback,
useEffect,
useRef,
type FocusEvent,
type KeyboardEvent,
type MouseEvent,
type PointerEvent,
type ReactNode,
} from 'react';
import {flushSync} from 'react-dom';
import * as stylex from '@stylexjs/stylex';
import {
colorVars,
sizeVars,
spacingVars,
typographyVars,
typeScaleVars,
borderVars,
} from '../theme/tokens.stylex';
import {
Field,
InputClearButton,
type InputStatus,
inputWrapperStyles,
inputStatusBorderStyles,
inputStatusHoverShadowStyles,
inputStatusFocusWithinStyles,
} from '../Field';
import {Icon, renderIconSlot, type IconType} from '../Icon';
import {VisuallyHidden} from '../VisuallyHidden';
import {useTooltip} from '../Tooltip';
import {getInputARIA} from '../utils';
import {joinAriaIDs} from '../utils/inputAria';
import {withholdCallerHandlers} from '../utils/disabledInteraction';
import {interactionOverlayStyles} from '../utils/interactionOverlay.stylex';
import {usePressFeedback} from '../hooks/usePressFeedback';
import {lockSelection, locksSelectionFor} from '../utils/selectionLock';
import {inputDisabledFocusStyles} from '../Field/inputDisabledFocus';
import {useSize} from '../SizeContext/SizeContext';
import {useInputContainer} from '../hooks/useInputContainer';
import {useInputStatusIcon} from '../hooks/useInputStatusIcon';
import {useResolvedRequired} from '../hooks/useResolvedRequired';
import {useInputGroup} from '../InputGroup/InputGroupContext';
import {InputGroupInternalContext} from '../InputGroup/InputGroupInternalContext';
// Public padding tokens for the `number-input` theme target. A theme writes an
// ordinary `padding` (in ANY spelling — the shorthand, `paddingBlock`, or a
// single `paddingBlockStart`) and the pipeline's `container` expansion parses
// it and emits these normalized per-side tokens; the wrapper and the stepper
// column both read them, so the column tracks whatever the theme sets instead
// of assuming the default. Routing through the shared expansion rather than a
// hand-rolled property→var mapping is what makes every spelling work: a
// mapping only fires for the exact property name it names.
//
// Read order per level: `var(--astryx-…, <next level>)`, terminating at the
// shared field defaults (NOT the container default --spacing-4, which is a
// layout metric and would resize every themed field). Built as chained const
// strings — no function calls — so StyleX can statically analyze them; same
// shape as the card/section/dialog chains in Layout/container.stylex.ts.
const FIELD_PAD_BLOCK = spacingVars['--spacing-1'];
const FIELD_PAD_INLINE = spacingVars['--spacing-2'];
const padBlockAll = `var(--astryx-number-input-padding, ${FIELD_PAD_BLOCK})`;
const padInlineAll = `var(--astryx-number-input-padding, ${FIELD_PAD_INLINE})`;
const padInline = `var(--astryx-number-input-padding-inline, ${padInlineAll})`;
const padInlineStart = `var(--astryx-number-input-padding-inline-start, ${padInline})`;
const padInlineEnd = `var(--astryx-number-input-padding-inline-end, ${padInline})`;
const padBlockStart = `var(--astryx-number-input-padding-block-start, ${padBlockAll})`;
const padBlockEnd = `var(--astryx-number-input-padding-block-end, ${padBlockAll})`;
const styles = stylex.create({
wrapper: {
zIndex: 1,
// Applied per side rather than through the shared field base's
// `paddingBlock`/`paddingInline` shorthands, because the stepper column
// has to cancel the block padding edge by edge — an asymmetric
// `paddingBlock: 4px 12px` needs two different negative margins.
paddingBlockStart: padBlockStart,
paddingBlockEnd: padBlockEnd,
paddingInlineStart: padInlineStart,
paddingInlineEnd: padInlineEnd,
},
wrapperWithNumberSteppers: {
paddingInlineEnd: {
default: 0,
'@media (pointer: coarse)': padInlineEnd,
},
},
input: {
display: 'block',
flex: 1,
minWidth: 0,
borderWidth: 0,
borderStyle: 'none',
padding: 0,
fontFamily: typographyVars['--font-family-body'],
// The 16px floor is iOS-only: iOS Safari zooms the page when a focused
// control sits under 16px, and only iOS WebKit implements
// -webkit-touch-callout to key the coarse-pointer floor to it.
fontSize: {
default: typeScaleVars['--text-body-size'],
'@media (pointer: coarse)': {
'@supports (-webkit-touch-callout: none)': `max(1rem, ${typeScaleVars['--text-body-size']})`,
},
},
lineHeight: typeScaleVars['--text-body-leading'],
color: colorVars['--color-text-primary'],
backgroundColor: 'transparent',
outline: 'none',
'::placeholder': {
color: colorVars['--color-text-secondary'],
},
},
inputDisabled: {
cursor: 'default',
},
inputInvalid: {
color: colorVars['--color-text-secondary'],
},
units: {
fontFamily: typographyVars['--font-family-body'],
fontSize: typeScaleVars['--text-body-size'],
lineHeight: typeScaleVars['--text-body-leading'],
color: colorVars['--color-text-secondary'],
flexShrink: 0,
},
numberSteppers: {
alignSelf: 'stretch',
// These compact buttons are a fine-pointer affordance. Touch users can
// enter a value directly; keyboard stepping remains available.
display: {
default: 'flex',
'@media (pointer: coarse)': 'none',
},
flexDirection: 'column',
flexShrink: 0,
width: spacingVars['--spacing-4'],
// Cancel the wrapper's block padding edge by edge so the column spans the
// field's full height. Reading the same tokens the wrapper applies is what
// keeps it flush under a themed padding — including an asymmetric one,
// where a single `marginBlock` would be wrong at one end.
marginBlockStart: `calc(-1 * ${padBlockStart})`,
marginBlockEnd: `calc(-1 * ${padBlockEnd})`,
borderInlineStartWidth: borderVars['--border-width'],
borderInlineStartStyle: 'solid',
borderInlineStartColor: colorVars['--color-border-emphasized'],
overflow: 'hidden',
borderStartEndRadius: 'var(--_field-radius)',
borderEndEndRadius: 'var(--_field-radius)',
},
numberStepperButton: {
boxSizing: 'border-box',
display: 'flex',
alignItems: 'center',
justifyContent: 'center',
flex: 1,
minHeight: 0,
padding: 0,
margin: 0,
borderWidth: 0,
borderStyle: 'none',
color: colorVars['--color-icon-secondary'],
backgroundColor: colorVars['--color-background-surface'],
cursor: {
default: 'pointer',
':is(:disabled,[aria-disabled="true"])': 'default',
},
outline: 'none',
},
numberStepperButtonDisabled: {
color: colorVars['--color-icon-disabled'],
cursor: 'default',
backgroundImage: 'none',
},
decrementButton: {
borderBlockStartWidth: borderVars['--border-width'],
borderBlockStartStyle: 'solid',
borderBlockStartColor: colorVars['--color-border-emphasized'],
},
incrementIcon: {
transform: 'rotate(180deg)',
},
});
const sizeStyles = stylex.create({
sm: {
height: sizeVars['--size-element-sm'],
},
md: {
height: sizeVars['--size-element-md'],
},
lg: {
height: sizeVars['--size-element-lg'],
},
});
export type NumberInputSize = keyof typeof sizeStyles;
import {groupStyles, inputGroupItemProps} from '../InputGroup/groupStyles';
// Re-export shared types for convenience
export type {
InputStatus as NumberInputStatus,
InputStatusType as NumberInputStatusType,
} from '../Field';
import {isImeKeyEvent, mergeProps, mergeRefs} from '../utils';
import type {BaseProps} from '../BaseProps';
import {
type FieldInputBaseProps,
useFieldInputStyling,
} from '../Field/fieldParts';
import type {SizeValue} from '../utils/types';
import {themeProps} from '../utils/themeProps';
import {useLocale} from '../i18n';
import {formatEditableNumber} from './numberParser';
import {parseNumberInput, resolveNumberInputCommit} from './numberInputCommit';
import type {FieldStatusPlacement} from '../Field/fieldStatusPlacement';
import {
registerEnglishFallback,
useComponentTranslator,
} from '../i18n/useComponentTranslator';
import english from '../i18n/generated-english/NumberInput/NumberInput.generated';
registerEnglishFallback(english);
interface NumberInputPropsBase extends Omit<
FieldInputBaseProps,
'onChange' | 'defaultValue'
> {
/** Ref forwarded to the root element */
ref?: React.Ref<HTMLInputElement>;
/**
* Label text for the input (always rendered for accessibility).
*/
label: string;
/**
* Whether to visually hide the label (still accessible to screen readers).
* @default false
*/
isLabelHidden?: boolean;
/**
* Description text displayed between the label and input.
*/
description?: string;
/**
* Whether the field is optional. Mutually exclusive with isRequired.
* @default false
*/
isOptional?: boolean;
/**
* Whether the field is required. Mutually exclusive with isOptional.
* @default false
*/
isRequired?: boolean;
/**
* Whether the input is disabled.
* @default false
*/
isDisabled?: boolean;
/**
* Whether the input is read-only.
* The value is shown at full opacity and still submits with the form, but
* cannot be edited. Unlike `isDisabled`, a read-only input is not dimmed and
* keeps its form value — use it for a value the user should see and send
* but not change. Stepping is off in every form while read-only: arrow keys,
* the wheel, and the number steppers. `isDisabled` takes precedence when both
* are set.
* @default false
*/
isReadOnly?: boolean;
/**
* Explains why the input is disabled. When set together with `isDisabled`,
* the input shows a tooltip with this text on hover and keyboard focus, and
* stays focusable (via `aria-disabled`) so the reason is discoverable by
* keyboard and assistive technology. The field cannot be edited (it becomes
* read-only) while disabled.
*
* Use this instead of wrapping a disabled input in `Tooltip`, so the reason
* is attached to the field itself.
*
* @example
* ```
* <NumberInput
* label="Quantity"
* value={quantity}
* isDisabled
* disabledMessage="Editing is locked while the order is processing"
* />
* ```
*/
disabledMessage?: string;
/**
* Icon to display at the start of the input.
* Accepts a ReactNode (e.g. `<Icon icon={SearchIcon} />`) or an SVG icon component directly.
*/
startIcon?: ReactNode | IconType;
/**
* Icon to display before the label text.
*/
labelIcon?: ReactNode | IconType;
/**
* Status indicator for the input.
* When set, displays a colored border and status icon.
* If message is provided, displays a floating message box below the input.
*/
status?: InputStatus;
/**
* 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?: FieldStatusPlacement;
/**
* The size of the input.
* - 'sm': Compact size (28px height)
* - 'md': Default size (32px height)
* - 'lg': Large size (36px height)
* @default 'md'
*/
size?: NumberInputSize;
// onChange and hasClear defined in discriminated union below
/**
* The current value of the input.
* Use null or undefined to represent an empty/unset value.
*/
value: number | null | undefined;
/**
* Placeholder text shown when the input is empty.
*/
placeholder?: string;
/**
* 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 they
* stay aligned, unlike setting width via `controlXstyle`/`controlClassName`/`controlStyle`.
*/
width?: SizeValue;
/**
* Tooltip text to display in an info icon at the end of the label.
*/
labelTooltip?: string;
/**
* Whether to automatically focus the input on mount.
* @default false
*/
hasAutoFocus?: boolean;
/**
* The HTML name attribute for the input.
* Useful for form submissions.
*/
htmlName?: string;
/**
* The HTML autocomplete attribute for the input.
*/
autoComplete?: string;
/**
* The minimum value allowed.
* A smaller entry commits at this value on blur or Enter.
*/
min?: number | null;
/**
* The maximum value allowed.
* A larger entry commits at this value on blur or Enter.
*/
max?: number | null;
/**
* The step increment for the input.
* @default 1
*/
step?: number | null;
/**
* Formats the committed value while the input is not being edited.
* The raw numeric value is shown on focus so it remains editable.
*/
formatValue?: (value: number) => string;
/**
* Whether scrolling the wheel over a focused input steps the value.
* @default true
*/
isWheelEnabled?: boolean;
/**
* Whether to show increment and decrement buttons at the end of the input.
* The buttons are hidden on coarse pointers (such as touch screens).
* Holding a button with a mouse or a pen repeats the step and commits once,
* when the hold ends.
* Direct text entry and keyboard stepping remain available.
* @default false
*/
hasNumberSteppers?: boolean;
/**
* Units text to display at the end of the input (e.g., "%" or "GB").
*/
units?: string | null;
/**
* Whether to only allow integer values (no floating point).
* @default false
*/
isIntegerOnly?: boolean;
/**
* Callback fired when the input receives focus.
*/
onFocus?: (e: FocusEvent<HTMLInputElement>) => void;
/**
* Callback fired when the input loses focus.
*/
onBlur?: (e: FocusEvent<HTMLInputElement>) => void;
/**
* Callback fired when the user presses the Enter key.
*/
onEnter?: () => void;
/**
* Callback fired on keydown events on the input.
*/
onKeyDown?: (e: KeyboardEvent<HTMLInputElement>) => void;
}
/**
* Without `hasClear`, onChange only receives valid numbers.
* With `hasClear`, onChange also receives `null` when the user clears the input.
*/
type NumberInputPropsNonClearable = NumberInputPropsBase & {
hasClear?: false;
onChange: (value: number) => void;
};
type NumberInputPropsClearable = NumberInputPropsBase & {
/**
* Whether to show a clear button when a value is set.
* When clicked, resets the value to null and returns focus to the input.
*
* When enabled, the `onChange` callback type widens to also accept `null`,
* signaling that the user cleared the input.
*/
hasClear: true;
onChange: (value: number | null) => void;
};
export type NumberInputProps =
NumberInputPropsNonClearable | NumberInputPropsClearable;
type StepDirection = -1 | 1;
/**
* A held stepper's timing: the first repeat comes `delayMs` after the press.
* Each later interval is `acceleration` times the one before, from
* `firstIntervalMs` down to `minIntervalMs`.
*/
const STEPPER_HOLD = {
delayMs: 500,
firstIntervalMs: 250,
acceleration: 0.9,
minIntervalMs: 50,
} as const;
/**
* A held stepper press: its pointer, its next repeat, the value its repeats
* reached, whether the field stopped taking them, and the release of its
* selection lock.
*/
type StepperHold = {
pointerId: number;
timer: ReturnType<typeof setTimeout> | null;
held: number | null;
intervalMs: number;
isFrozen: boolean;
unlockSelection: (() => void) | null;
};
function getDecimalPlaces(value: number): number {
const [coefficient, exponentText] = String(value).toLowerCase().split('e');
const fractionLength = coefficient.split('.')[1]?.length ?? 0;
const exponent = exponentText == null ? 0 : Number(exponentText);
return Math.max(0, fractionLength - exponent);
}
function getEffectiveStep(
step: number | null | undefined,
isIntegerOnly: boolean,
): number {
if (
step == null ||
!Number.isFinite(step) ||
step <= 0 ||
(isIntegerOnly && !Number.isInteger(step))
) {
return 1;
}
return step;
}
function getSteppedValue({
currentValue,
direction,
min,
max,
step,
isIntegerOnly,
}: {
currentValue: number | null;
direction: StepDirection;
min?: number | null;
max?: number | null;
step?: number | null;
isIntegerOnly: boolean;
}): number | null {
const effectiveStep = getEffectiveStep(step, isIntegerOnly);
const stepBase =
min != null && (!isIntegerOnly || Number.isInteger(min)) ? min : 0;
let nextValue: number;
if (currentValue == null) {
nextValue = direction === 1 ? (min ?? 0) : (max ?? 0);
if (isIntegerOnly) {
nextValue =
direction === 1 ? Math.ceil(nextValue) : Math.floor(nextValue);
}
} else {
const stepPosition = (currentValue - stepBase) / effectiveStep;
const tolerance = Number.EPSILON * Math.max(1, Math.abs(stepPosition)) * 4;
const nextStepPosition =
direction === 1
? Math.floor(stepPosition + tolerance) + 1
: Math.ceil(stepPosition - tolerance) - 1;
nextValue = stepBase + nextStepPosition * effectiveStep;
}
const precision = Math.min(
12,
Math.max(getDecimalPlaces(effectiveStep), getDecimalPlaces(stepBase)),
);
nextValue = Number(nextValue.toFixed(precision));
// Clamp after rounding so a bound with finer precision than the step cannot
// be rounded back out of its own range.
if (min != null) {
nextValue = Math.max(min, nextValue);
}
if (max != null) {
nextValue = Math.min(max, nextValue);
}
if (!Number.isFinite(nextValue)) {
return currentValue;
}
if (isIntegerOnly && !Number.isInteger(nextValue)) {
return currentValue;
}
return Object.is(nextValue, -0) ? 0 : nextValue;
}
/**
* A number input component for collecting numeric user input.
* Commits text edits on blur or Enter and only calls onChange when the whole
* draft passes validation.
*
* @example
* ```
* <NumberInput label="Quantity" value={quantity} onChange={setQuantity} />
* <NumberInput label="Price" value={price} onChange={setPrice} min={0} step={0.01} />
* ```
*/
export function NumberInput({
label,
isLabelHidden = false,
description,
isOptional = false,
isRequired = false,
isDisabled: isDisabledProp = false,
isReadOnly = false,
disabledMessage,
startIcon,
labelIcon,
status,
statusVariant = 'attached',
size: sizeProp,
onChange,
value,
placeholder,
labelTooltip,
hasAutoFocus = false,
htmlName,
autoComplete,
min,
max,
step,
formatValue,
isWheelEnabled = true,
hasNumberSteppers = false,
units,
isIntegerOnly = false,
onFocus,
onBlur,
hasClear,
onEnter,
onKeyDown,
width,
containerXstyle,
containerClassName,
containerStyle,
controlXstyle,
controlClassName,
controlStyle,
ref,
id: idProp,
'aria-describedby': ariaDescribedByProp,
'aria-labelledby': ariaLabelledByProp,
...restProps
}: NumberInputProps) {
const {rest, container} = useFieldInputStyling('NumberInput', restProps, {
containerXstyle,
containerClassName,
containerStyle,
});
const pressable = usePressFeedback();
const t = useComponentTranslator();
const locale = useLocale();
const isEffectivelyRequired = useResolvedRequired({isRequired, isOptional});
const size = useSize(sizeProp, 'md');
const generatedID = useId();
const id = idProp ?? generatedID;
const fieldLabelID = useId();
const inputLabelID = useId();
const descriptionID = useId();
const statusMessageID = useId();
const unitsID = useId();
const inputRef = useRef<HTMLInputElement | null>(null);
const containerRef = useRef<HTMLDivElement | null>(null);
const inputGroup = useInputGroup();
const inputGroupState = use(InputGroupInternalContext);
const isDisabled = isDisabledProp || inputGroupState.isDisabled;
// Pending input while user is typing (null = show formatted value)
const [pendingInput, setPendingInput] = useState<string | null>(null);
// The value a held stepper's repeats reached, shown until the hold ends.
const [holdDraft, setHoldDraft] = useState<number | null>(null);
// A field that turns disabled or read-only drops the held value during
// render, so no commit shows a value that the release does not commit.
if (holdDraft !== null && (isDisabled || isReadOnly)) {
setHoldDraft(null);
}
const [isFocused, setIsFocused] = useState(false);
// Disabled-reason tooltip. The tooltip listeners attach to the input container (which already exists) and
// the input stays perceivable via aria-disabled instead of the native
// disabled attribute. The field is made read-only so it can't be typed into,
// and value mutation is blocked by the isDisabled guard in the handlers.
const showsDisabledMessage = isDisabled && !!disabledMessage;
// A disabled field keeps its tab stop but, like a natively disabled one,
// runs no caller event handler other than focus and blur (`spec:AST-085` FR2).
const fieldProps = withholdCallerHandlers(rest, isDisabled);
const disabledMessageTooltip = useTooltip({
placement: 'above',
// The container div is not naturally focusable; focusin bubbles up from
// the input, so always attach focus listeners.
focusTrigger: 'always',
isEnabled: showsDisabledMessage,
});
const {statusIcon, describedBy: statusTooltipDescribedBy} =
useInputStatusIcon({
status,
statusVariant,
isInGroup: !!inputGroup,
});
const {ariaLabelledBy, ariaDescribedBy} = getInputARIA(
inputLabelID,
[
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 && 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,
],
inputGroup,
);
// A caller aria-labelledby names the input together with the field's own
// label (the Field label standalone, the group and input labels in a group).
const inputLabelledBy =
ariaLabelledByProp != null
? joinAriaIDs(ariaLabelledBy ?? fieldLabelID, ariaLabelledByProp)
: ariaLabelledBy;
const parseInput = useCallback(
(text: string) => parseNumberInput(text, {min, max, isIntegerOnly, locale}),
[isIntegerOnly, locale, max, min],
);
const formattedValue = useMemo(() => {
if (value == null) {
return '';
}
return formatValue?.(value) ?? String(value);
}, [formatValue, value]);
// Preserve pending text while editing. Otherwise show the formatted value
// at rest and the raw numeric value while focused so it remains editable.
const displayValue = useMemo(() => {
if (holdDraft !== null) {
return formatEditableNumber(holdDraft, locale);
}
if (pendingInput !== null) {
return pendingInput;
}
if (value == null) {
return '';
}
return isFocused ? formatEditableNumber(value, locale) : formattedValue;
}, [formattedValue, holdDraft, isFocused, locale, pendingInput, value]);
// Check if current pending input is valid (for styling purposes)
const isInputValid = useMemo(() => {
// A held value is a step on the grid, so it is always valid.
if (holdDraft !== null) {
return true;
}
if (pendingInput === null || !pendingInput.trim()) {
return true;
}
return parseInput(pendingInput) !== null;
}, [holdDraft, pendingInput, parseInput]);
// Keep the whole text edit as a draft until an explicit commit boundary.
const handleInputChange = useCallback(
(e: React.ChangeEvent<HTMLInputElement>) => {
// Value can't change while showing a disabled message (the field is
// read-only and non-native-disabled), but guard the handler too so the
// pending value never changes.
if (isDisabled || isReadOnly) {
return;
}
setPendingInput(e.target.value);
},
[isDisabled, isReadOnly],
);
// Handle focus
// Tab into the field selects its text so typing replaces it. With
// `formatValue` the text at rest differs from the editable text, and putting
// the editable text in the input after focus collapses that selection to the
// end, so typing would append. When focus arrives with the text selected,
// the focus handler commits the swap and selects the swapped-in text itself:
// the work one event causes stays in its handler
// (architecture:react-component-runtime/INV2).
const handleFocus = useCallback(
(e: FocusEvent<HTMLInputElement>) => {
const input = e.currentTarget;
const editableText =
pendingInput ??
(value == null ? '' : formatEditableNumber(value, locale));
const shouldReselect =
input.value.length > 0 &&
input.value !== editableText &&
input.selectionStart === 0 &&
input.selectionEnd === input.value.length;
setIsFocused(true);
onFocus?.(e);
if (shouldReselect) {
// Commit the swap now, so the editable text is in the input to select.
// eslint-disable-next-line @eslint-react/dom-no-flush-sync -- the editable text must be in the input before the focus event selects it
flushSync(() => {});
input.setSelectionRange(0, input.value.length);
}
},
[onFocus, pendingInput, value, locale],
);
const commitPendingInput = useCallback(
(trigger: 'blur' | 'Enter') => {
if (pendingInput === null) {
return;
}
if (isDisabled) {
// A field disabled mid-entry commits nothing; its draft is dropped, as
// a natively disabled field's was (spec:AST-085 FR2).
setPendingInput(null);
return;
}
const decision = resolveNumberInputCommit(pendingInput, {
min,
max,
isIntegerOnly,
locale,
hasClear: !!hasClear,
});
if (
trigger === 'blur' ||
(decision.type === 'commit' && decision.didClamp)
) {
setPendingInput(null);
}
if (decision.type === 'clear') {
if (hasClear && value != null) {
onChange(null);
}
} else if (decision.type === 'commit' && decision.value !== value) {
onChange(decision.value);
}
},
[
hasClear,
isDisabled,
isIntegerOnly,
locale,
max,
min,
onChange,
pendingInput,
value,
],
);
// Blur ends the edit and displays the resulting committed value.
const handleBlur = useCallback(
(e: FocusEvent<HTMLInputElement>) => {
commitPendingInput('blur');
setIsFocused(false);
onBlur?.(e);
},
[commitPendingInput, onBlur],
);
const valueForStepping = useMemo(() => {
if (pendingInput === null) {
return value ?? null;
}
if (pendingInput.trim() === '') {
return null;
}
return parseInput(pendingInput) ?? value ?? null;
}, [parseInput, pendingInput, value]);
const getNextValue = useCallback(
(direction: StepDirection) =>
getSteppedValue({
currentValue: valueForStepping,
direction,
min,
max,
step,
isIntegerOnly,
}),
[isIntegerOnly, max, min, step, valueForStepping],
);
const stepValue = useCallback(
(direction: StepDirection) => {
// A read-only field is not steppable by any route: keyboard, wheel, or
// the stepper buttons all land here.
if (isDisabled || isReadOnly) {
return;
}
const nextValue = getNextValue(direction);
if (nextValue == null) {
return;
}
setPendingInput(null);
if (nextValue !== value) {
onChange(nextValue);
}
},
[getNextValue, isDisabled, isReadOnly, onChange, value],
);
// A held stepper repeats into its own draft and commits once, when the hold
// ends.
const stepperHoldRef = useRef<StepperHold | null>(null);
const isClickAfterHoldRef = useRef(false);
// The pointer of a repeated hold that another press cancelled. Its own
// release still swallows the click that follows.
const cancelledHoldPointerRef = useRef<number | null>(null);
// Ends a hold with no commit, and drops the draft its repeats wrote.
const cancelStepperHold = useCallback(() => {
const hold = stepperHoldRef.current;
if (hold == null) {
return;
}
stepperHoldRef.current = null;
cancelledHoldPointerRef.current = hold.held != null ? hold.pointerId : null;
if (hold.timer != null) {
clearTimeout(hold.timer);
}
hold.unlockSelection?.();
setHoldDraft(null);
}, []);
// Syncs the held stepper's repeat timer with the field's editability: a
// field that turns disabled or read-only stops the repeats, and the release
// commits nothing.
useEffect(() => {
const hold = stepperHoldRef.current;
if (hold == null || !(isDisabled || isReadOnly)) {
return;
}
hold.isFrozen = true;
if (hold.timer != null) {
clearTimeout(hold.timer);
hold.timer = null;
}
}, [isDisabled, isReadOnly]);
// The stepper column's removal or unmount ends the hold with no commit, as
// its buttons can no longer hear the release.
const stepperColumnRef = useCallback(
() => () => {
cancelStepperHold();
},
[cancelStepperHold],
);
const startStepperHold = (
direction: StepDirection,
canStep: boolean,
event: PointerEvent<HTMLButtonElement>,
) => {
isClickAfterHoldRef.current = false;
if (cancelledHoldPointerRef.current === event.pointerId) {
cancelledHoldPointerRef.current = null;
}
// Any new press ends a running hold, whichever pointer made it.
cancelStepperHold();
// Steppers render only under a non-coarse primary pointer, so a hold is a
// mouse or pen press. A finger keeps the single step of its click.
if (
event.button !== 0 ||
event.pointerType === 'touch' ||
!canStep ||
isDisabled ||
isReadOnly
) {
return;
}
const first = getNextValue(direction);
if (first == null) {
return;
}
// The release ends the hold wherever the pointer is by then.
event.currentTarget.setPointerCapture?.(event.pointerId);
const grid = {direction, min, max, step, isIntegerOnly};
const hold: StepperHold = {
pointerId: event.pointerId,
timer: null,
held: null,
intervalMs: STEPPER_HOLD.firstIntervalMs,
isFrozen: false,
// A pen's hold starts no text selection or callout.
unlockSelection: locksSelectionFor(event.pointerType)
? lockSelection([event.currentTarget], event.target)
: null,
};
const repeat = () => {
const next =
hold.held == null
? first
: getSteppedValue({currentValue: hold.held, ...grid});
// At a bound the repeats stop, and the release still commits.
if (next == null || next === hold.held) {
hold.timer = null;
return;
}
hold.held = next;
setHoldDraft(next);
hold.timer = setTimeout(repeat, hold.intervalMs);
hold.intervalMs = Math.max(
STEPPER_HOLD.minIntervalMs,
hold.intervalMs * STEPPER_HOLD.acceleration,
);
};
hold.timer = setTimeout(repeat, STEPPER_HOLD.delayMs);
stepperHoldRef.current = hold;
};
const handleStepperContextMenu = (event: MouseEvent<HTMLButtonElement>) => {
const hold = stepperHoldRef.current;
if (hold == null) {
return;
}
// A pen's hold opens no callout menu. A mouse's context request, such as
// a Control-click, ends its hold with no commit and opens the menu.
if (hold.unlockSelection != null) {
event.preventDefault();
return;
}
cancelStepperHold();
// A click that follows the menu steps nothing, as after any ended hold.
cancelledHoldPointerRef.current = hold.pointerId;
isClickAfterHoldRef.current = true;
};
const endStepperHold = (end: 'release' | 'cancel', pointerId: number) => {
const hold = stepperHoldRef.current;
// Only the pointer that holds can end the hold.
if (hold == null || hold.pointerId !== pointerId) {
if (cancelledHoldPointerRef.current === pointerId) {
cancelledHoldPointerRef.current = null;
// Only arm the swallow here: a lost capture must not clear it.
if (end === 'release') {
isClickAfterHoldRef.current = true;
}
}
return;
}
stepperHoldRef.current = null;
if (hold.timer != null) {
clearTimeout(hold.timer);
}
hold.unlockSelection?.();
// A press released before its first repeat is a click, and its click
// steps.
if (hold.held == null) {
return;
}
isClickAfterHoldRef.current = end === 'release';
setHoldDraft(null);
// A frozen hold commits nothing, so a typed draft under it stays.
if (hold.isFrozen || isDisabled || isReadOnly) {
return;
}
setPendingInput(null);
if (hold.held !== value) {
onChange(hold.held);
}
};
// Handle keyboard events
const handleKeyDown = useCallback(
(e: KeyboardEvent<HTMLInputElement>) => {
if (isDisabled) {
// A read-only field still submits its form on Enter.
if (e.key === 'Enter') {
e.preventDefault();
}
return;
}
// The field is type="text" for formatted display, so an IME can compose
// into it: Enter commits the candidate and the arrows walk the candidate
// window. The composing keydown fires before compositionend, so without
// this guard those keystrokes would commit or step the value instead.
// See utils/ime.ts.
if (isImeKeyEvent(e.nativeEvent)) {
return;
}
const hasModifier = e.altKey || e.ctrlKey || e.metaKey || e.shiftKey;
if (!hasModifier && (e.key === 'ArrowUp' || e.key === 'ArrowDown')) {
onKeyDown?.(e);
if (e.defaultPrevented) {
return;
}
e.preventDefault();
stepValue(e.key === 'ArrowUp' ? 1 : -1);
return;
}
if (e.key === 'Enter') {
commitPendingInput('Enter');
onEnter?.();
}
onKeyDown?.(e);
},
[commitPendingInput, isDisabled, onEnter, onKeyDown, stepValue],
);
// React's delegated wheel listener can be passive, so use a native,
// explicitly non-passive listener to prevent page scrolling only when this
// focused input is intentionally consuming the gesture to step its value.
const wheelListenerRef = useCallback(
(input: HTMLInputElement | null) => {
if (input == null || !isWheelEnabled) {
return;
}
const handleWheel = (event: WheelEvent) => {
// Bail before preventDefault so a read-only input never swallows the
// page scroll it cannot act on.
if (
document.activeElement !== input ||
isDisabled ||
isReadOnly ||
event.deltaY === 0 ||
event.altKey ||
event.ctrlKey ||
event.metaKey ||
event.shiftKey
) {
return;
}
event.preventDefault();
event.stopPropagation();
stepValue(event.deltaY < 0 ? 1 : -1);
};
input.addEventListener('wheel', handleWheel, {passive: false});
return () => input.removeEventListener('wheel', handleWheel);
},
[isDisabled, isReadOnly, isWheelEnabled, stepValue],
);
const mergedInputRef = useMemo(
() => mergeRefs(ref, inputRef, wheelListenerRef),
[ref, wheelListenerRef],
);
// While a hold runs, the steppers follow the value that it shows.
const {canIncrement, canDecrement} = useMemo(() => {
const base = holdDraft ?? valueForStepping;
const grid = {currentValue: base, min, max, step, isIntegerOnly};
return {
canIncrement: getSteppedValue({...grid, direction: 1}) !== base,
canDecrement: getSteppedValue({...grid, direction: -1}) !== base,
};
}, [holdDraft, isIntegerOnly, max, min, step, valueForStepping]);
// Handle clear button click
const handleClear = useCallback(
(e?: React.MouseEvent<HTMLButtonElement>) => {
if (hasClear) {
onChange(null);
}
setPendingInput(null);
if (!e || e.detail === 0) {
inputRef.current?.focus();
} else {
// Focus inside the tap: iOS Safari brings up its keyboard only for a
// focus made while handling the touch, so a field the tap reaches
// unfocused gets its keyboard, as UIKit's clear button makes the
// field first responder. `preventScroll` keeps a scrolled page where
// it is.
inputRef.current?.focus({preventScroll: true});
}
},
[hasClear, onChange],
);
// Focus input when clicking anywhere on the wrapper (icons, padding, etc.)
const {onClick: handleWrapperClick, onMouseUp: handleWrapperMouseUp} =
useInputContainer({
containerRef,
inputRef,
disabled: isDisabled,
});
const inputWrapper = (
<div
ref={el => {
containerRef.current = el;
// Anchor + hover/focus listeners for the disabled-message tooltip.
// Handlers are gated internally by isEnabled, and anchor names
// compose, so attaching unconditionally is safe.
disabledMessageTooltip.ref(el);
}}
onClick={handleWrapperClick}
onMouseUp={handleWrapperMouseUp}
{...(inputGroup ? inputGroupItemProps : undefined)}
{...mergeProps(
themeProps('number-input', {
size,
status: status?.type ?? null,
disabled: isDisabled ? 'disabled' : null,
readonly: isReadOnly ? 'readonly' : null,
}),
stylex.props(
inputWrapperStyles.base,
inputWrapperStyles.textField,
styles.wrapper,
hasNumberSteppers && styles.wrapperWithNumberSteppers,
sizeStyles[size],
isDisabled && inputWrapperStyles.disabled,
isDisabled && inputDisabledFocusStyles.ring,
status && inputStatusBorderStyles[status.type],
status && !isDisabled && inputStatusHoverShadowStyles[status.type],
status && inputStatusFocusWithinStyles[status.type],
inputGroup && groupStyles.inGroup,
controlXstyle,
),
controlClassName,
controlStyle,
)}>
{startIcon && renderIconSlot(startIcon, {size: 'sm', color: 'secondary'})}
{inputGroup && <VisuallyHidden id={inputLabelID}>{label}</VisuallyHidden>}
<input
{...fieldProps}
ref={mergedInputRef}
id={id}
name={isDisabled || formatValue ? undefined : htmlName}
type="text"
inputMode={isIntegerOnly ? 'numeric' : 'decimal'}
role="spinbutton"
autoComplete={autoComplete}
value={displayValue}
onChange={handleInputChange}
onFocus={handleFocus}
onBlur={handleBlur}
onKeyDown={handleKeyDown}
placeholder={placeholder}
// A disabled input keeps its place in the tab order (spec:AST-085):
// aria-disabled instead of the native attribute, with readOnly + the
// handler guards keeping the value from changing.
aria-disabled={isDisabled ? 'true' : undefined}
readOnly={isReadOnly || isDisabled || undefined}
autoFocus={hasAutoFocus}
data-autofocus={hasAutoFocus || undefined}
aria-valuemin={min ?? undefined}
aria-valuemax={max ?? undefined}
// The ARIA value and hidden form input expose the committed value;
// pendingInput is still an uncommitted edit and may be invalid.
aria-valuenow={value ?? undefined}
aria-valuetext={
value == null || !formatValue ? undefined : formattedValue
}
aria-describedby={
[ariaDescribedByProp, ariaDescribedBy].filter(Boolean).join(' ') ||
undefined
}
aria-required={isEffectivelyRequired ? 'true' : undefined}
aria-invalid={
status?.type === 'error' || !isInputValid ? 'true' : undefined
}
aria-labelledby={inputLabelledBy}
{...stylex.props(
styles.input,
isDisabled && styles.inputDisabled,
!isInputValid && styles.inputInvalid,
)}
/>
{formatValue && htmlName && !isDisabled && (
<input
type="hidden"
name={htmlName}
value={value == null ? '' : String(value)}
/>
)}
{units && (
<span id={unitsID} {...stylex.props(styles.units)}>
{units}
</span>
)}
{/*
Live region announcing invalid typed input to assistive technology.
The value silently reverts on blur, so without this a screen-reader
user would get no feedback that their entry was rejected (WCAG 3.3.1).
*/}
<VisuallyHidden as="div" role="alert" aria-live="assertive">
{!isInputValid ? t('@astryx.numberInput.invalidNumber') : ''}
</VisuallyHidden>
{hasClear && value != null && !isDisabled && !isReadOnly && (
<InputClearButton
label={t('@astryx.numberInput.clearLabel', {label})}
onClick={handleClear}
/>
)}
{statusIcon}
{hasNumberSteppers && (
<div ref={stepperColumnRef} {...stylex.props(styles.numberSteppers)}>
<button
type="button"
tabIndex={-1}
{...pressable}
aria-disabled={
isDisabled || isReadOnly || !canIncrement || undefined
}
aria-label={t('@astryx.numberInput.incrementLabel', {label})}
onPointerDown={event => {
event.preventDefault();
startStepperHold(1, canIncrement, event);
}}
onContextMenu={handleStepperContextMenu}
onPointerUp={event => endStepperHold('release', event.pointerId)}
onPointerCancel={event => endStepperHold('cancel', event.pointerId)}
onLostPointerCapture={event =>
endStepperHold('cancel', event.pointerId)
}
onClick={event => {
const isAfterHold = isClickAfterHoldRef.current;
isClickAfterHoldRef.current = false;
// A pointer's click after a held press's release steps nothing.
// A click with no pointer, such as a screen reader's, steps.
if (isAfterHold && event.detail > 0) {
inputRef.current?.focus();
return;
}
// An aria-disabled stepper does nothing, as a natively disabled
// one did (spec:AST-085 FR2).
if (isDisabled || isReadOnly || !canIncrement) {
return;
}
inputRef.current?.focus();
stepValue(1);
}}
{...stylex.props(
styles.numberStepperButton,
interactionOverlayStyles.backgroundImage,
(isDisabled || isReadOnly || !canIncrement) &&
styles.numberStepperButtonDisabled,
)}>
<Icon
icon="numberInput:stepperDown"
size="xsm"
color="inherit"
xstyle={styles.incrementIcon}
/>
</button>
<button
type="button"
tabIndex={-1}
{...pressable}
aria-disabled={
isDisabled || isReadOnly || !canDecrement || undefined
}
aria-label={t('@astryx.numberInput.decrementLabel', {label})}
onPointerDown={event => {
event.preventDefault();
startStepperHold(-1, canDecrement, event);
}}
onContextMenu={handleStepperContextMenu}
onPointerUp={event => endStepperHold('release', event.pointerId)}
onPointerCancel={event => endStepperHold('cancel', event.pointerId)}
onLostPointerCapture={event =>
endStepperHold('cancel', event.pointerId)
}
onClick={event => {
const isAfterHold = isClickAfterHoldRef.current;
isClickAfterHoldRef.current = false;
// A pointer's click after a held press's release steps nothing.
// A click with no pointer, such as a screen reader's, steps.
if (isAfterHold && event.detail > 0) {
inputRef.current?.focus();
return;
}
// An aria-disabled stepper does nothing, as a natively disabled
// one did (spec:AST-085 FR2).
if (isDisabled || isReadOnly || !canDecrement) {
return;
}
inputRef.current?.focus();
stepValue(-1);
}}
{...stylex.props(
styles.numberStepperButton,
interactionOverlayStyles.backgroundImage,
styles.decrementButton,
(isDisabled || isReadOnly || !canDecrement) &&
styles.numberStepperButtonDisabled,
)}>
<Icon icon="numberInput:stepperDown" size="xsm" color="inherit" />
</button>
</div>
)}
</div>
);
if (inputGroup) {
return (
<>
{inputWrapper}
{showsDisabledMessage &&
disabledMessageTooltip.renderTooltip(disabledMessage)}
</>
);
}
return (
<Field
{...container}
label={label}
isLabelHidden={isLabelHidden}
description={description}
inputID={id}
labelID={ariaLabelledByProp != null ? fieldLabelID : undefined}
descriptionID={description ? descriptionID : undefined}
isOptional={isOptional}
isRequired={isRequired}
isDisabled={isDisabled}
labelIcon={labelIcon}
status={
status
? {
type: status.type,
message: status.message,
messageID: status.message ? statusMessageID : undefined,
}
: undefined
}
statusVariant={statusVariant}
labelTooltip={labelTooltip}
width={width}>
{inputWrapper}
{showsDisabledMessage &&
disabledMessageTooltip.renderTooltip(disabledMessage)}
</Field>
);
}
NumberInput.displayName = 'NumberInput';