// Copyright (c) Meta Platforms, Inc. and affiliates.

'use client';

/**
 * @file TextArea.tsx
 * @input Uses React, useId, ChangeEvent, ClipboardEvent, FocusEvent, Field, Icon, Spinner
 * @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 "../style-runtime.js";
import "../theme/tokens.stylex.js";
import { colorVars, spacingVars, typographyVars, typeScaleVars } from "../theme/tokens.stylex.js";
import { Field, inputWrapperStyles, inputStatusBorderStyles, inputStatusHoverShadowStyles, inputStatusFocusWithinStyles, type FieldStatusVariant } from "../Field/index.js";
import { Icon, renderIconSlot, type IconType } from "../Icon/index.js";
import { Spinner } from "../Spinner/index.js";
import { useTooltip } from "../Tooltip/index.js";
import { mergeProps } from "../utils/index.js";
import type { BaseProps } from "../BaseProps.js";
import type { SizeValue } from "../utils/types.js";
import { useInputContainer } from "../hooks/useInputContainer.js";
import { useInputStatusIcon } from "../hooks/useInputStatusIcon.js";
import { useAnnounce } from "../hooks/useAnnounce.js";
import { useResolvedRequired } from "../hooks/useResolvedRequired.js";
import { useSize } from "../SizeContext/SizeContext.js";
import { themeProps } from "../utils/themeProps.js";
import { characterCount } from "../utils/characters.js";
import { useTranslator } from "../i18n/index.js";
import { useMergedRefs } from "../hooks/useMergedRefs.js";
const COUNTER_WARNING_THRESHOLD = 0.8;
const styles = {
  wrapper: {
    kY2c9j: "x1vjfegm",
    k1xSpc: "x1lliihq",
    k8WAf4: "xt970qd",
    kg3NbH: "xnjsko4",
    "--_textarea-inline-padding": "x1kdpo6e",
    $$css: true as const
  },
  textarea: {
    k1xSpc: "x1lliihq",
    kzqmXN: "xh8yej3",
    kB7OPa: "x9f619",
    k7Eaqz: "xeuugli",
    kMzoRj: "xc342km",
    ksu8eU: "xng3xce",
    k8WAf4: "xu0wf1k",
    kg3NbH: "x1w6f3ag",
    kMv6JI: "x9ynric",
    kGuDYH: "xjm74w1 xf9zqsd",
    kLWn49: "xw6l6zx",
    kMwMTN: "x1tgivj0",
    kWkggS: "xjbqb8w",
    kI3sdo: "x1a2a7pz",
    k8Qsv1: "xeyghm5",
    kHenm0: "x288g5",
    $$css: true as const
  },
  textareaDisabled: {
    kkrTdU: "xt0e3qv",
    $$css: true as const
  },
  textareaWithStartIcon: {
    kZCmMZ: "x1b6te9z",
    $$css: true as const
  },
  textareaWithStatus: {
    kwRFfy: "xp2dy4z",
    $$css: true as const
  },
  textareaWithBusyStatus: {
    kwRFfy: "x1g2apga",
    $$css: true as const
  },
  textareaWithCounter: {
    kGO01o: "xekm6fs",
    $$css: true as const
  }
};
const textareaSizeStyles = {
  sm: {
    $$css: true as const
  },
  md: {
    $$css: true as const
  },
  lg: {
    k8WAf4: "xce4md1",
    $$css: true as const
  }
};
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<BaseProps, 'onChange' | 'defaultValue'> {
  /** 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.
   * @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 stays in the tab order — 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` — disabled
   * controls don't emit the pointer events an external tooltip needs.
   *
   * @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?: 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 they
   * stay aligned, unlike setting width via `xstyle`/`className`/`style`.
   */
  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,
  onPaste,
  maxLength,
  hasAutoFocus = false,
  size: sizeProp,
  htmlName,
  onFocus,
  onBlur,
  width,
  xstyle,
  className,
  style,
  ref,
  ...rest
}: TextAreaProps) {
  const size = useSize(sizeProp, 'md');
  const t = useTranslator();
  const isEffectivelyRequired = useResolvedRequired({
    isRequired,
    isOptional
  });
  const announce = useAnnounce();
  const id = 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;

  // Disabled-reason tooltip. Disabled controls swallow pointer events, so 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;
  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 label={label} isLabelHidden={isLabelHidden} description={description} inputID={id} 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
    },
    // `textarea` ran the compound name together; keep it emitted so
    // existing themes continue to work.
    {
      legacyNames: ['textarea']
    }), stylex.props(inputWrapperStyles.base, styles.wrapper, isDisabled && inputWrapperStyles.disabled, status && inputStatusBorderStyles[status.type], status && !isDisabled && inputStatusHoverShadowStyles[status.type], status && inputStatusFocusWithinStyles[status.type], xstyle), className, style)}>
        {startIcon && <span className="x10l6tqk xctzyg x1kiyvbf x47corl x78zum5">
            {renderIconSlot(startIcon, {
          size: 'sm',
          color: 'secondary'
        })}
          </span>}
        <textarea {...rest} ref={useMergedRefs(ref, textareaRef)} id={id} name={isDisabled ? undefined : htmlName} value={optimisticValue} onChange={handleChange} onPaste={onPaste} onFocus={onFocus} onBlur={onBlur} placeholder={placeholder} rows={rows}
      // With a disabledMessage the textarea keeps focusability via
      // aria-disabled so the reason is focus-discoverable; readOnly + the
      // handleChange guard keep the value from changing.
      disabled={isDisabled && !showsDisabledMessage} aria-disabled={showsDisabledMessage ? 'true' : undefined} readOnly={isReadOnly || showsDisabledMessage || undefined} spellCheck={hasSpellCheck} autoFocus={hasAutoFocus} data-autofocus={hasAutoFocus || undefined} aria-describedby={ariaDescribedBy} 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, Boolean(startIcon) && 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 className="x10l6tqk xctzyg x13oyzgk x47corl x78zum5 x6s0dn4 x1txdalj">
            {isBusy && <Spinner size="sm" />}
            {statusIcon}
          </span>}
        {maxLength != null && <div id={counterID} {...mergeProps(themeProps('text-area-counter'), {
        0: {
          className: "x10l6tqk x112dmjn x13oyzgk x47corl x78zum5 x6s0dn4 xzye2dw x9ynric x141an7d x1ltkj2j xv1l7n4"
        },
        1: {
          className: "x10l6tqk x112dmjn x13oyzgk x47corl x78zum5 x6s0dn4 xzye2dw x9ynric x141an7d x1ltkj2j xjt36v0"
        }
      }[Number(!!(valueLength > maxLength)) << 0])}>
            {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" />}
            {valueLength}/{maxLength}
          </div>}
      </div>
      {showsDisabledMessage && disabledMessageTooltip.renderTooltip(disabledMessage)}
    </Field>;
}
TextArea.displayName = 'TextArea';