import { FormControlElement } from "../types.js";

//#region src/TextArea/TextArea.types.d.ts

/**
 * Props for the TextArea component that provides a multi-line text input control.
 */
type TextAreaProps = {
  /**
   * Additional CSS classes to apply to the textarea element.
   * Use this to customize the appearance beyond the default styling.
   */
  extraClassNames?: string;
  /**
   * HTML ID attribute for the textarea element.
   * Should be unique across the page for proper HTML semantics and accessibility.
   */
  id?: string;
  /**
   * Name attribute for the textarea used in form submission.
   * Identifies the textarea's data when the form is submitted to a server.
   */
  name?: string;
  /**
   * Callback function triggered when the textarea value changes.
   * Receives the change event containing the new value. Use this to update
   * your component state in controlled input scenarios.
   */
  onChange?: React.ChangeEventHandler<FormControlElement>;
  /**
   * Callback function triggered when a key is released while the textarea has focus.
   * Useful for implementing search-as-you-type functionality or debounced input handling.
   */
  onKeyUp?: React.KeyboardEventHandler<FormControlElement>;
  /**
   * Callback function triggered when a key is pressed while the textarea has focus.
   * Useful for implementing keyboard shortcuts, form submission shortcuts,
   * or preventing certain characters from being entered.
   */
  onKeyDown?: React.KeyboardEventHandler<FormControlElement>;
  /**
   * Callback function triggered when the textarea receives focus.
   * Use this to handle focus-related logic such as showing hints,
   * clearing placeholder text, or updating UI state.
   */
  onFocus?: React.FocusEventHandler<HTMLTextAreaElement>;
  /**
   * Callback function triggered when the textarea loses focus.
   * Commonly used for form validation, saving draft data, or
   * updating UI state when users finish interacting with the field.
   */
  onBlur?: React.FocusEventHandler<FormControlElement>;
  /**
   * Callback function triggered when the text selection changes in the
   * textarea. Useful for implementing features like mention autocomplete or
   * context-sensitive tools that need to react to cursor position or text
   * selection changes.
   */
  onSelectionChange?: (e: Event) => void;
  /**
   * Placeholder text displayed when the textarea is empty.
   * Provides users with a hint about what type of content is expected.
   * Should be descriptive but not replace proper labels.
   */
  placeholder?: string;
  /**
   * When true, makes the textarea read-only, preventing user input.
   * The field will display its value but users cannot modify it. Unlike disabled fields,
   * read-only fields can still receive focus and their values are included in form submissions.
   */
  readonly?: boolean;
  /**
   * When true, disables the textarea preventing any user interaction.
   * Disabled fields appear visually dimmed, cannot receive focus, and their
   * values are not included in form submissions.
   */
  disabled?: boolean;
  /**
   * Number of visible text lines in the textarea.
   * Controls the initial height of the textarea. Users can typically resize
   * the textarea if the browser allows it.
   * @default 3
   */
  rows?: number;
  /**
   * Number of visible character columns in the textarea.
   * Controls the initial width of the textarea based on average character width.
   * Less commonly used than CSS width styling.
   */
  cols?: number;
  /**
   * When true, automatically focuses this textarea when the component mounts.
   * Useful for modal dialogs or forms where immediate input is expected.
   * Should be used sparingly to avoid accessibility issues.
   */
  autoFocus?: boolean;
  /**
   * Test ID attribute for the textarea element used in automated testing.
   * Applied to the `data-testid` attribute for element selection in test suites.
   */
  testId?: string;
  /**
   * Current value of the textarea for controlled component behavior.
   * Can be a string for text content, an array of strings for multi-value scenarios,
   * or a number that will be converted to string. Use this for controlled input components.
   */
  value?: string | string[] | number;
  /**
   * When true, displays error styling on the textarea.
   * Typically changes border color to red and may add error-related visual cues.
   * Usually used in combination with error messages to provide validation feedback.
   */
  showError?: boolean;
  /**
   * Ref object to access the underlying textarea DOM element.
   */
  ref?: React.Ref<HTMLTextAreaElement>;
};
//#endregion
export { TextAreaProps };