Skip to content

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

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

'use client';

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

import {
  useId,
  useOptimistic,
  useTransition,
  useRef,
  useCallback,
  useMemo,
  type ChangeEvent,
  type ClipboardEvent,
  type FocusEvent,
  type ReactNode,
} from 'react';
import * as stylex from '@stylexjs/stylex';
import {
  colorVars,
  spacingVars,
  typographyVars,
  typeScaleVars,
} from '../theme/tokens.stylex';
import {
  Field,
  inputWrapperStyles,
  inputStatusBorderStyles,
  inputStatusHoverShadowStyles,
  inputStatusFocusWithinStyles,
} from '../Field';
import {Icon, renderIconSlot, type IconType} from '../Icon';
import {isRenderable} from '../utils/isRenderable';
import {withholdCallerHandlers} from '../utils/disabledInteraction';
import {Spinner} from '../Spinner';
import {useTooltip} from '../Tooltip';
import {mergeProps} from '../utils';
import {joinAriaIDs} from '../utils/inputAria';
import type {BaseProps} from '../BaseProps';
import {
  type FieldInputBaseProps,
  useFieldInputStyling,
} from '../Field/fieldParts';
import {inputDisabledFocusStyles} from '../Field/inputDisabledFocus';
import type {SizeValue} from '../utils/types';
import {useInputContainer} from '../hooks/useInputContainer';
import {useInputStatusIcon} from '../hooks/useInputStatusIcon';
import {useAnnounce} from '../hooks/useAnnounce';
import {useResolvedRequired} from '../hooks/useResolvedRequired';
import {useSize} from '../SizeContext/SizeContext';
import {themeProps} from '../utils/themeProps';
import {characterCount} from '../utils/characters';
import {
  textEntryTraitAttributes,
  type TextEntryTraitProps,
} from '../Field/textEntryTraits';

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

registerEnglishFallback(english);
const COUNTER_WARNING_THRESHOLD = 0.8;

const styles = stylex.create({
  // The wrapper is a bare positioning context. The <textarea> spans the full
  // container and carries its own internal padding; icons, status/spinner, and
  // the character counter are absolutely-positioned overlays anchored to the
  // container corners. This keeps the native resize grip in the true
  // bottom-right corner and lets the scrollbar represent the full input area.
  wrapper: {
    zIndex: 1,
    display: 'block',
    // Zero the shared wrapper inset with matching longhands, not the `padding`
    // shorthand: StyleX ranks longhands above shorthands regardless of merge
    // order, so a `padding: 0` shorthand loses to the base's
    // paddingBlock/paddingInline. The wrapper would keep a duplicate inset that
    // the <textarea>'s own padding then doubles — insetting the text and
    // pushing the native resize grip in from the corner.
    paddingBlock: 0,
    paddingInline: 0,
    // Internal inline padding for the textarea's text. Defined on the wrapper
    // so the counter (a sibling overlay) inherits the same value and stays
    // aligned with the text edge. Kept as an internal var so it can later be
    // driven by a theme "padding" translation without touching either child.
    '--_textarea-inline-padding': spacingVars['--spacing-2'],
  },
  textarea: {
    display: 'block',
    width: '100%',
    boxSizing: 'border-box',
    minWidth: 0,
    borderWidth: 0,
    borderStyle: 'none',
    // Base internal padding; overlays get their own reserved space below.
    paddingBlock: spacingVars['--spacing-1'],
    paddingInline: 'var(--_textarea-inline-padding)',
    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'],
    },
    resize: 'vertical',
  },
  textareaDisabled: {
    cursor: 'default',
  },
  // Reserve start padding so text clears the start icon.
  // inline inset + 16px icon (sm) + 8px gap
  textareaWithStartIcon: {
    paddingInlineStart: `calc(var(--_textarea-inline-padding) + ${spacingVars['--spacing-6']})`,
  },
  // Reserve end padding so text clears the status icon / spinner overlay.
  // inline inset + 20px icon (md) + 4px gap
  textareaWithStatus: {
    paddingInlineEnd: `calc(var(--_textarea-inline-padding) + ${spacingVars['--spacing-6']})`,
  },
  // Reserve wider end padding when the spinner AND status icon both show.
  // inline inset + 16px spinner + 8px gap + 20px icon + 4px gap
  textareaWithBusyStatus: {
    paddingInlineEnd: `calc(var(--_textarea-inline-padding) + ${spacingVars['--spacing-12']})`,
  },
  // Reserve bottom padding so text clears the character counter overlay.
  textareaWithCounter: {
    paddingBottom: spacingVars['--spacing-7'],
  },
  startIcon: {
    position: 'absolute',
    top: spacingVars['--spacing-2'],
    insetInlineStart: 'var(--_textarea-inline-padding)',
    pointerEvents: 'none',
    display: 'flex',
  },
  endSlot: {
    position: 'absolute',
    top: spacingVars['--spacing-2'],
    insetInlineEnd: 'var(--_textarea-inline-padding)',
    pointerEvents: 'none',
    display: 'flex',
    alignItems: 'center',
    gap: spacingVars['--spacing-2'],
  },
  // Character counter lives inside the input container, anchored bottom-right
  // underneath the textarea, aligned to the same inline inset as the text.
  counter: {
    position: 'absolute',
    bottom: spacingVars['--spacing-1'],
    insetInlineEnd: 'var(--_textarea-inline-padding)',
    pointerEvents: 'none',
    display: 'flex',
    alignItems: 'center',
    gap: spacingVars['--spacing-1'],
    fontFamily: typographyVars['--font-family-body'],
    fontSize: typeScaleVars['--text-supporting-size'],
    lineHeight: typeScaleVars['--text-supporting-leading'],
    color: colorVars['--color-text-secondary'],
  },
  counterError: {
    color: colorVars['--color-text-error'],
  },
});

const textareaSizeStyles = stylex.create({
  sm: {},
  md: {},
  lg: {
    paddingBlock: spacingVars['--spacing-2'],
  },
});

export type TextAreaStatusType = 'warning' | 'error' | 'success';

export type TextAreaSize = 'sm' | 'md' | 'lg';

export interface TextAreaStatus {
  /**
   * The type of status to display.
   */
  type: TextAreaStatusType;
  /**
   * Optional message to display below the textarea.
   */
  message?: string;
}

export interface TextAreaProps
  extends
    Omit<FieldInputBaseProps, 'onChange' | 'defaultValue'>,
    TextEntryTraitProps {
  /** Ref forwarded to the root element */
  ref?: React.Ref<HTMLTextAreaElement>;
  /**
   * Label text for the textarea (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 textarea.
   */
  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;
  /**
   * Callback fired when the textarea value changes.
   */
  onChange?: (value: string, e: ChangeEvent<HTMLTextAreaElement>) => void;
  /** Async action on change. Fires after onChange if not prevented. */
  changeAction?: (
    value: string,
    e: ChangeEvent<HTMLTextAreaElement>,
  ) => void | Promise<void>;
  /** Whether the input is in a loading state. @default false */
  isLoading?: boolean;
  /**
   * The current value of the textarea.
   */
  value: string;
  /**
   * Placeholder text shown when the textarea is empty.
   */
  placeholder?: string;
  /**
   * The number of visible text rows.
   * @default 3
   */
  rows?: number;
  /**
   * Whether the textarea is disabled. A disabled textarea 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 textarea 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 textarea 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 textarea is disabled. When set together with
   * `isDisabled`, the textarea 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 textarea in `Tooltip`, so the
   * reason is attached to the field itself.
   *
   * @example
   * ```
   * <TextArea
   *   label="Notes"
   *   value={notes}
   *   isDisabled
   *   disabledMessage="Notes are locked after submission"
   * />
   * ```
   */
  disabledMessage?: string;
  /**
   * Status indicator for the textarea.
   * When set, displays a colored border and status icon.
   * If message is provided, displays a floating message box below the textarea.
   */
  status?: TextAreaStatus;
  /**
   * 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;
  /**
   * 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;
  /**
   * Icon to display at the start of the textarea.
   * Accepts a ReactNode (e.g. `<Icon icon={SearchIcon} />`) or an SVG icon component directly.
   */
  startIcon?: ReactNode | IconType;
  /**
   * Whether to enable browser spell checking.
   * @default true
   */
  hasSpellCheck?: boolean;
  /**
   * Callback fired when content is pasted into the textarea.
   */
  onPaste?: (e: ClipboardEvent<HTMLTextAreaElement>) => void;
  /**
   * Maximum number of characters allowed, counted as user-perceived
   * characters — an emoji or flag sequence counts as one. When set,
   * displays a character counter below the textarea.
   * Does not enforce the limit natively — the counter shows error styling
   * when exceeded, and the consumer can validate via onChange. Validate with
   * `characterCount` (exported from this package) rather than `value.length`
   * so enforcement matches the displayed count.
   */
  maxLength?: number;
  /**
   * Whether to automatically focus the textarea on mount.
   * @default false
   */
  hasAutoFocus?: boolean;
  /**
   * The size of the textarea, affecting internal padding.
   * Height is controlled by `rows`, not size.
   * @default 'md'
   */
  size?: TextAreaSize;
  /**
   * The HTML name attribute for the textarea.
   * Useful for form submissions.
   */
  htmlName?: string;
  /**
   * Callback fired when the textarea receives focus.
   */
  onFocus?: (e: FocusEvent<HTMLTextAreaElement>) => void;
  /**
   * Callback fired when the textarea loses focus.
   */
  onBlur?: (e: FocusEvent<HTMLTextAreaElement>) => void;
  /**
   * The native `autocomplete` attribute, forwarded to the textarea 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.TextareaHTMLAttributes<HTMLTextAreaElement>['autoComplete'];
}

/**
 * A multi-line text input component for collecting longer user input.
 *
 * @example
 * ```
 * <TextArea label="Description" value={description} onChange={setDescription} />
 * <TextArea label="Notes" rows={5} value={notes} onChange={setNotes} />
 * ```
 */
export function TextArea({
  label,
  isLabelHidden = false,
  description,
  isOptional = false,
  isRequired = false,
  onChange,
  changeAction,
  isLoading = false,
  value,
  placeholder,
  rows = 3,
  isDisabled = false,
  isReadOnly = false,
  disabledMessage,
  status,
  statusVariant = 'attached',
  labelTooltip,
  startIcon,
  hasSpellCheck = true,
  enterKeyHint,
  inputMode,
  autoCapitalize,
  hasAutoCorrect,
  onPaste,
  maxLength,
  hasAutoFocus = false,
  size: sizeProp,
  htmlName,
  onFocus,
  onBlur,
  width,
  containerXstyle,
  containerClassName,
  containerStyle,
  controlXstyle,
  controlClassName,
  controlStyle,
  ref,
  id: idProp,
  'aria-describedby': ariaDescribedByProp,
  'aria-labelledby': ariaLabelledByProp,
  ...restProps
}: TextAreaProps) {
  const {rest, container} = useFieldInputStyling('TextArea', restProps, {
    containerXstyle,
    containerClassName,
    containerStyle,
  });
  const size = useSize(sizeProp, 'md');
  // One presence check for the start icon's slot and its padding
  // (`architecture:react-component-runtime` INV16), on the value the caller
  // passed: an icon component counts as present, as any non-empty value does.
  const hasStartIcon = isRenderable(startIcon as ReactNode);
  const t = useComponentTranslator();
  const isEffectivelyRequired = useResolvedRequired({isRequired, isOptional});
  const announce = useAnnounce();
  const generatedID = useId();
  const id = idProp ?? generatedID;
  const fieldLabelID = useId();
  const descriptionID = useId();
  const statusMessageID = useId();
  const counterID = useId();
  const textareaRef = useRef<HTMLTextAreaElement | null>(null);
  const containerRef = useRef<HTMLDivElement | null>(null);
  // Tracks the counter "zone" last announced (under / near / over) so we only
  // announce on a zone change, not on every keystroke.
  const counterZoneRef = useRef<'under' | 'near' | 'over' | 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 textarea container (which already exists)
  // and the textarea 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;
  // 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 textarea, so always attach focus listeners.
    focusTrigger: 'always',
    isEnabled: showsDisabledMessage,
  });

  const {statusIcon, describedBy: statusTooltipDescribedBy} =
    useInputStatusIcon({
      status,
      statusVariant,
    });

  const ariaDescribedBy =
    [
      description ? descriptionID : 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,
    ]
      .filter(Boolean)
      .join(' ') || undefined;

  // Announce the character-count status through the shared live region, but
  // only when the value crosses into a new zone (near the limit / over the
  // limit) so we don't speak on every keystroke. Over-limit is assertive (an
  // error the user should hear immediately); nearing the limit is polite.
  const announceCounter = useCallback(
    (length: number) => {
      if (maxLength == null) {
        return;
      }
      const zone: 'under' | 'near' | 'over' =
        length > maxLength
          ? 'over'
          : length >= maxLength * COUNTER_WARNING_THRESHOLD
            ? 'near'
            : 'under';
      if (zone === counterZoneRef.current) {
        return;
      }
      counterZoneRef.current = zone;
      if (zone === 'over') {
        announce(
          t('@astryx.textArea.charactersOverLimit', {
            count: length - maxLength,
          }),
          'assertive',
        );
      } else if (zone === 'near') {
        announce(
          t('@astryx.textArea.charactersRemaining', {
            count: maxLength - length,
          }),
        );
      }
    },
    [announce, t, maxLength],
  );

  const handleChange = (e: ChangeEvent<HTMLTextAreaElement>) => {
    // 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;
    // Guarded here, not just inside announceCounter, so textareas without a
    // maxLength never pay for segmenting the whole value on each keystroke.
    if (maxLength != null) {
      announceCounter(characterCount(newValue));
    }
    onChange?.(newValue, e);
    if (changeAction && !e.defaultPrevented) {
      startTransition(async () => {
        setOptimisticValue(newValue);
        await changeAction(newValue, e);
      });
    }
  };

  // Counter semantics count user-perceived characters, so an emoji or flag
  // sequence counts as one character, not its code units.
  // Only measured when a counter exists — segmentation is O(value length),
  // and memoized so re-renders that keep the same value skip it entirely.
  const valueLength = useMemo(
    () => (maxLength != null ? characterCount(optimisticValue) : 0),
    [maxLength, optimisticValue],
  );

  const effectivelyDisabled = isDisabled || isBusy;

  // Focus textarea when clicking anywhere on the wrapper (icons, padding, etc.)
  const {onClick: handleWrapperClick, onMouseUp: handleWrapperMouseUp} =
    useInputContainer({
      containerRef,
      inputRef: textareaRef,
      disabled: effectivelyDisabled,
    });

  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}>
      <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}
        {...mergeProps(
          themeProps('text-area', {
            size,
            status: status?.type ?? null,
            disabled: isDisabled ? 'disabled' : null,
            readonly: isReadOnly ? 'readonly' : null,
          }),
          stylex.props(
            inputWrapperStyles.base,
            inputWrapperStyles.textField,
            styles.wrapper,
            isDisabled && inputWrapperStyles.disabled,
            isDisabled && inputDisabledFocusStyles.ring,
            status && inputStatusBorderStyles[status.type],
            status && !isDisabled && inputStatusHoverShadowStyles[status.type],
            status && inputStatusFocusWithinStyles[status.type],
            controlXstyle,
          ),
          controlClassName,
          controlStyle,
        )}>
        {hasStartIcon && (
          <span {...stylex.props(styles.startIcon)}>
            {renderIconSlot(startIcon, {size: 'sm', color: 'secondary'})}
          </span>
        )}
        <textarea
          {...fieldProps}
          ref={useMergedRefs(ref, textareaRef)}
          id={id}
          name={isDisabled ? undefined : htmlName}
          value={optimisticValue}
          onChange={handleChange}
          onPaste={isDisabled ? undefined : onPaste}
          onFocus={onFocus}
          onBlur={onBlur}
          placeholder={placeholder}
          rows={rows}
          {...textEntryTraitAttributes({
            enterKeyHint,
            inputMode,
            autoCapitalize,
            hasAutoCorrect,
          })}
          // A disabled textarea 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}
          spellCheck={hasSpellCheck}
          autoFocus={hasAutoFocus}
          data-autofocus={hasAutoFocus || undefined}
          // A caller aria-labelledby names the textarea together with the
          // field's own label, which it would otherwise replace.
          aria-labelledby={
            ariaLabelledByProp != null
              ? joinAriaIDs(fieldLabelID, ariaLabelledByProp)
              : undefined
          }
          aria-describedby={
            [ariaDescribedByProp, ariaDescribedBy].filter(Boolean).join(' ') ||
            undefined
          }
          aria-required={isEffectivelyRequired ? 'true' : undefined}
          aria-invalid={
            status?.type === 'error' ||
            (maxLength != null && valueLength > maxLength)
              ? 'true'
              : undefined
          }
          aria-busy={isBusy || undefined}
          {...mergeProps(
            themeProps('text-area-control'),
            stylex.props(
              styles.textarea,
              textareaSizeStyles[size],
              isDisabled && styles.textareaDisabled,
              hasStartIcon && styles.textareaWithStartIcon,
              // Reserve trailing space only when the end slot actually renders
              // something (spinner or on-field status icon). The `detached`
              // status variant suppresses the on-field icon — its glyph lives
              // in the message box below — so reserving here would inset the
              // text for an icon that never appears.
              (isBusy || statusIcon != null) && styles.textareaWithStatus,
              isBusy && statusIcon != null && styles.textareaWithBusyStatus,
              maxLength != null && styles.textareaWithCounter,
            ),
          )}
        />
        {(isBusy || statusIcon) && (
          <span {...stylex.props(styles.endSlot)}>
            {isBusy && <Spinner size="sm" aria-hidden="true" />}
            {statusIcon}
          </span>
        )}
        {/* eslint-disable-next-line @astryx/no-nullish-jsx-guard -- `maxLength` is a number; 0 still shows its counter */}
        {maxLength != null && (
          <div
            id={counterID}
            {...mergeProps(
              themeProps('text-area-counter'),
              stylex.props(
                styles.counter,
                valueLength > maxLength && styles.counterError,
              ),
            )}>
            {valueLength > maxLength && (
              // Non-color cue so the over-limit state isn't conveyed by the red
              // color alone (WCAG 1.4.1). Decorative — the count text and the
              // live-region announcement carry the meaning.
              <Icon icon="warning" size="sm" />
            )}
            {t('@astryx.textArea.counter', {
              count: valueLength,
              limit: maxLength,
            })}
          </div>
        )}
      </div>
      {showsDisabledMessage &&
        disabledMessageTooltip.renderTooltip(disabledMessage)}
    </Field>
  );
}

TextArea.displayName = 'TextArea';