Skip to content

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

TypeScript
21.4 KB
Raw Blame
// Copyright (c) Meta Platforms, Inc. and affiliates.

'use client';

/**
 * @file TextInput.tsx
 * @input Uses React, useId, ChangeEvent, Field, Icon, InputGroupContext,
 *   textEntryTraits (the touch-keyboard trait props)
 * @output Exports TextInput component, TextInputProps, TextInputType
 * @position Core implementation; consumed by index.ts, tested by TextInput.test.tsx
 *
 * SYNC: When modified, update these files to stay in sync:
 * - /packages/core/src/TextInput/TextInput.doc.mjs (props table, features, implementation notes)
 * - /packages/core/src/TextInput/TextInput.test.tsx (tests for new/changed behavior)
 * - /packages/core/src/TextInput/index.ts (exports if types change)
 * - /apps/storybook/stories/TextInput.stories.tsx (storybook stories)
 * - /packages/cli/assets/templates/blocks/components/TextInput/ (showcase blocks)
 */

import {
  use,
  useId,
  useOptimistic,
  useTransition,
  useCallback,
  useRef,
  type ChangeEvent,
  type KeyboardEvent,
  type ReactNode,
} from 'react';
import * as stylex from '@stylexjs/stylex';
import {
  colorVars,
  sizeVars,
  typographyVars,
  typeScaleVars,
} from '../theme/tokens.stylex';
import {Field} from '../Field/Field';
import {InputClearButton} from '../Field/InputClearButton';
import {
  inputWrapperStyles,
  inputStatusBorderStyles,
  inputStatusHoverShadowStyles,
  inputStatusFocusWithinStyles,
} from '../Field/inputStyles.stylex';
import type {InputStatus} from '../Field/types';
import {renderIconSlot, type IconType} from '../Icon/Icon';
import {isRenderable} from '../utils/isRenderable';
import {withholdCallerHandlers} from '../utils/disabledInteraction';
import {Spinner} from '../Spinner/Spinner';
import {useTooltip} from '../Tooltip/useTooltip';
import {VisuallyHidden} from '../VisuallyHidden/VisuallyHidden';
import {getInputARIA} from '../utils/inputAria';
import {isImeKeyEvent} from '../utils/ime';
import {
  textEntryTraitAttributes,
  type TextEntryTraitProps,
} from '../Field/textEntryTraits';
import {joinAriaIDs} from '../utils/inputAria';

const styles = stylex.create({
  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',
  },
});

const sizeStyles = stylex.create({
  sm: {
    height: sizeVars['--size-element-sm'],
  },
  md: {
    height: sizeVars['--size-element-md'],
  },
  lg: {
    height: sizeVars['--size-element-lg'],
  },
});

export type TextInputSize = keyof typeof sizeStyles;

import {groupStyles, inputGroupItemProps} from '../InputGroup/groupStyles';

// Re-export shared types for convenience

export type {
  InputStatus as TextInputStatus,
  InputStatusType as TextInputStatusType,
} from '../Field';
import {mergeProps} from '../utils/mergeProps';
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';
import type {BaseProps} from '../BaseProps';
import {
  type FieldInputBaseProps,
  useFieldInputStyling,
} from '../Field/fieldParts';
import {inputDisabledFocusStyles} from '../Field/inputDisabledFocus';
import type {SizeValue} from '../utils/types';
import {themeProps} from '../utils/themeProps';

import {useMergedRefs} from '../hooks/useMergedRefs';
import {useBusyAnnouncement} from '../hooks/useBusyAnnouncement';
import {setInputValue} from '../utils/setInputValue';
import type {FieldStatusPlacement} from '../Field/fieldStatusPlacement';
import {
  registerEnglishFallback,
  useComponentTranslator,
} from '../i18n/useComponentTranslator';
import english from '../i18n/generated-english/TextInput/TextInput.generated';

registerEnglishFallback(english);
/**
 * The HTML input type. Beyond their meaning, `email`, `tel`, `url` and
 * `password` choose a touch keyboard (email, phone pad, URL) and its
 * capitalization; `search` makes the field a search box.
 */
export type TextInputType =
  'text' | 'password' | 'email' | 'search' | 'tel' | 'url';

export interface TextInputProps
  extends
    Omit<FieldInputBaseProps, 'onChange' | 'defaultValue'>,
    TextEntryTraitProps {
  /** Ref forwarded to the root element */
  ref?: React.Ref<HTMLInputElement>;
  /**
   * The HTML input type. `email`, `tel` and `url` also bring up the matching
   * touch keyboard (email, phone pad, URL); `search` makes the field a search
   * box (pair it with `enterKeyHint="search"` for a Search key).
   * @default 'text'
   */
  type?: TextInputType;
  /**
   * 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. A disabled input is dimmed, cannot be
   * edited, and is left out of form submission, but it stays in the tab order
   * (`aria-disabled`, not the native attribute).
   * @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. `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
   * ```
   * <TextInput
   *   label="Owner"
   *   value={owner}
   *   isDisabled
   *   disabledMessage="You need the Editor role to change this"
   * />
   * ```
   */
  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;
  /**
   * 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 (18px height)
   * - 'md': Default size (26px height)
   * @default 'md'
   */
  size?: TextInputSize;
  /**
   * Callback fired when the input value changes.
   */
  onChange?: (value: string, e: ChangeEvent<HTMLInputElement>) => void;
  /** Async action on change. Fires after onChange if not prevented. */
  changeAction?: (
    value: string,
    e: ChangeEvent<HTMLInputElement>,
  ) => void | Promise<void>;
  /** Whether the input is in a loading state. @default false */
  isLoading?: boolean;
  /**
   * The current value of the input.
   */
  value: string;
  /**
   * 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 show a clear button when a value is set.
   * When clicked, resets the value to an empty string and returns focus to the input.
   * @default false
   */
  hasClear?: boolean;
  /**
   * 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;
  /**
   * Callback fired when the user presses the Enter key.
   */
  onEnter?: () => void;
  /**
   * Callback fired on keydown events on the input.
   */
  onKeyDown?: (e: KeyboardEvent<HTMLInputElement>) => void;
  /**
   * The native `autocomplete` attribute, forwarded to the input unchanged.
   * The value stays React-controlled regardless — this only hints the
   * browser/password manager's suggestion behavior (e.g. `'off'` for a
   * session-scoped field that must not reuse a prior value).
   */
  autoComplete?: React.InputHTMLAttributes<HTMLInputElement>['autoComplete'];
  /**
   * Whether misspelled words are underlined (the native `spellcheck`).
   * Unset, the browser decides.
   */
  hasSpellCheck?: boolean;
}

/**
 * A text input component for collecting user input.
 *
 * @example
 * ```
 * <TextInput label="Name" value={name} onChange={setName} />
 * <TextInput label="Search" isLabelHidden value={query} onChange={setQuery} />
 * ```
 */
export function TextInput({
  type = 'text',
  label,
  isLabelHidden = false,
  description,
  isOptional = false,
  isRequired = false,
  isDisabled: isDisabledProp = false,
  isReadOnly = false,
  disabledMessage,
  startIcon,
  status,
  statusVariant = 'attached',
  size: sizeProp,
  onChange,
  changeAction,
  isLoading = false,
  value,
  placeholder,
  labelTooltip,
  hasClear = false,
  hasAutoFocus = false,
  htmlName,
  onEnter,
  onKeyDown,
  enterKeyHint,
  inputMode,
  autoCapitalize,
  hasAutoCorrect,
  hasSpellCheck,
  width,
  containerXstyle,
  containerClassName,
  containerStyle,
  controlXstyle,
  controlClassName,
  controlStyle,
  ref,
  id: idProp,
  'aria-describedby': ariaDescribedByProp,
  'aria-labelledby': ariaLabelledByProp,
  ...restProps
}: TextInputProps) {
  const inputGroup = useInputGroup();
  const inputGroupState = use(InputGroupInternalContext);
  const isDisabled = isDisabledProp || inputGroupState.isDisabled;
  const {rest, container} = useFieldInputStyling('TextInput', restProps, {
    containerXstyle,
    containerClassName,
    containerStyle,
  });
  const t = useComponentTranslator();
  const isEffectivelyRequired = useResolvedRequired({isRequired, isOptional});
  // 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 size = useSize(sizeProp, 'md');

  const generatedID = useId();
  const id = idProp ?? generatedID;
  const fieldLabelID = useId();
  const inputLabelID = useId();
  const descriptionID = useId();
  const statusMessageID = useId();
  const inputRef = useRef<HTMLInputElement | null>(null);
  const containerRef = useRef<HTMLDivElement | null>(null);

  const [, startTransition] = useTransition();
  const [optimisticValue, setOptimisticValue] = useOptimistic(value);
  const isBusy = isLoading || optimisticValue !== value;
  // The busy Spinner is decorative; this control announces its busy start
  // (spec:AST-086 FR8).
  useBusyAnnouncement(isBusy, t('@astryx.spinner.loading'), containerRef);

  // 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 handleChange.
  const showsDisabledMessage = isDisabled && !!disabledMessage;
  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,
      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 handleChange = (e: 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
    // optimistic value and callbacks never fire.
    if (isDisabled || isReadOnly) {
      return;
    }
    const newValue = e.target.value;
    onChange?.(newValue, e);
    if (changeAction && !e.defaultPrevented) {
      startTransition(async () => {
        setOptimisticValue(newValue);
        await changeAction(newValue, e);
      });
    }
  };

  // A native value set and an `input` event run the input's own change handler.
  // So the clear gets a real change event and the same callback order and
  // cancellation as typing.
  const handleClear = useCallback((e?: React.MouseEvent<HTMLButtonElement>) => {
    const input = inputRef.current;
    if (input != null && input.value !== '') {
      setInputValue(input, '');
    }
    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});
    }
  }, []);

  // 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('text-input', {
          size,
          status: status?.type ?? null,
          disabled: isDisabled ? 'disabled' : null,
          readonly: isReadOnly ? 'readonly' : null,
        }),
        stylex.props(
          inputWrapperStyles.base,
          inputWrapperStyles.textField,
          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,
      )}>
      {/* The shared presence check decides the slot
          (`architecture:react-component-runtime` INV16); an icon component
          counts as present, as any non-empty value does. */}
      {isRenderable(startIcon as ReactNode) &&
        renderIconSlot(startIcon, {size: 'sm', color: 'secondary'})}
      {inputGroup && <VisuallyHidden id={inputLabelID}>{label}</VisuallyHidden>}
      <input
        {...fieldProps}
        ref={useMergedRefs(ref, inputRef)}
        id={id}
        name={isDisabled ? undefined : htmlName}
        type={type}
        {...textEntryTraitAttributes({
          enterKeyHint,
          inputMode,
          autoCapitalize,
          hasAutoCorrect,
        })}
        // Only when set, so an untyped `spellCheck` passed through still applies.
        {...(hasSpellCheck != null ? {spellCheck: hasSpellCheck} : {})}
        value={optimisticValue}
        onChange={handleChange}
        onKeyDown={
          isDisabled || onEnter || onKeyDown
            ? e => {
                if (isDisabled) {
                  // A read-only field still submits its form on Enter.
                  if (e.key === 'Enter') {
                    e.preventDefault();
                  }
                  return;
                }
                // The composing keydown fires before compositionend, so without
                // this guard pressing Enter to commit a Japanese/Chinese/Korean
                // IME conversion would trigger onEnter (submit/save actions)
                // before the user intends to submit. onKeyDown still receives
                // the raw event. See utils/ime.ts (#6082).
                if (e.key === 'Enter' && !isImeKeyEvent(e.nativeEvent)) {
                  onEnter?.();
                }
                onKeyDown?.(e);
              }
            : undefined
        }
        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
        // handleChange guard keeping the value from changing.
        aria-disabled={isDisabled ? 'true' : undefined}
        readOnly={isReadOnly || isDisabled || undefined}
        autoFocus={hasAutoFocus}
        data-autofocus={hasAutoFocus || undefined}
        aria-describedby={
          [ariaDescribedByProp, ariaDescribedBy].filter(Boolean).join(' ') ||
          undefined
        }
        aria-required={isEffectivelyRequired ? 'true' : undefined}
        aria-invalid={status?.type === 'error' ? 'true' : undefined}
        aria-busy={isBusy || undefined}
        aria-labelledby={inputLabelledBy}
        {...stylex.props(styles.input, isDisabled && styles.inputDisabled)}
      />
      {/* The Spinner comes first so it appears inward of the clear button
          and the button keeps its place when the field turns busy. */}
      {isBusy && <Spinner size="sm" aria-hidden="true" />}
      {hasClear && value !== '' && !isDisabled && !isReadOnly && (
        <InputClearButton
          label={t('@astryx.textInput.clearLabel', {label})}
          onClick={handleClear}
        />
      )}
      {statusIcon}
    </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}
      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>
  );
}

TextInput.displayName = 'TextInput';