import { TooltipComponentProps } from "../Tooltip/Tooltip.types.js";
import { FormControlElement, InputGroupPlacement } from "../types.js";
import React from "react";

//#region src/TextField/TextField.types.d.ts
type TextFieldProps = {
  /**
   * When true, makes the text field 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 text field preventing any user interaction.
   * Disabled fields appear visually dimmed, cannot receive focus, and their
   * values are not included in form submissions.
   */
  disabled?: boolean;
  /**
   * Callback function triggered when the text field 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 the user pastes content into the text field.
   * Receives the clipboard event with details about the pasted content.
   * Useful for implementing custom paste handling, such as sanitizing input
   * or preventing certain types of content from being pasted.
   */
  onPaste?: React.ClipboardEventHandler<FormControlElement>;
  /**
   * Callback function triggered when a key is released while the field has focus.
   * Useful for implementing search-as-you-type functionality or debounced input handling.
   * Receives the keyboard event with details about the released key.
   */
  onKeyUp?: React.KeyboardEventHandler<FormControlElement>;
  /**
   * Callback function triggered when a key is pressed while the field has focus.
   * Useful for implementing keyboard shortcuts, form submission on Enter,
   * or preventing certain characters from being entered.
   */
  onKeyDown?: React.KeyboardEventHandler<FormControlElement>;
  /**
   * Callback function triggered when the text field receives focus.
   * Use this to handle focus-related logic such as showing hints,
   * clearing placeholder text, or updating UI state.
   */
  onFocus?: React.FocusEventHandler<HTMLInputElement>;
  /**
   * Callback function triggered when the text field 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>;
  /**
   * HTML ID attribute for the text field element.
   * Should be unique across the entire page for proper HTML semantics and accessibility.
   * Used for associating labels and error messages with the input field.
   */
  id?: string;
  /**
   * Name attribute for the text field used in form submission.
   * This identifies the field's data when the form is submitted to a server.
   * Essential for proper form handling and data processing.
   */
  name?: string;
  /**
   * Size variant that controls the text field's height and text size:
   * - `sm`: Small field with compact padding and smaller text
   * - `lg`: Large field with generous padding and larger text
   * If not specified, uses the default/medium size.
   */
  size?: 'sm' | 'lg';
  /**
   * The current value of the text field.
   * Can be a string for text input, an array of strings for multi-value fields,
   * or a number for numeric inputs. Use this for controlled input components.
   */
  value?: string | string[] | number;
  /**
   * Placeholder text displayed when the field is empty.
   * Provides users with a hint about what type of content is expected.
   * Should be descriptive but not replace proper labels.
   */
  placeholder?: string;
  /**
   * Additional CSS classes to apply to the text field element.
   * These classes are combined with the component's built-in styling.
   * Use this to customize appearance beyond the standard size variants.
   */
  extraClassNames?: string;
  /**
   * HTML input type that determines the field's behavior and validation:
   * - `text`: Standard text input (default)
   * - `password`: Obscures entered text for security
   * - `number`: Numeric input with increment/decrement controls
   * - `email`: Email input with built-in email validation
   * @default 'text'
   */
  type?: 'text' | 'password' | 'number' | 'email';
  /**
   * Test ID attribute for the text field element used in automated testing.
   * Applied to the `data-testid` attribute for element selection in test suites.
   */
  testId?: string;
  /**
   * React ref object for direct access to the text field DOM element.
   * Use this when you need to programmatically focus the field,
   * measure its dimensions, or perform other direct DOM operations.
   */
  ref?: React.Ref<HTMLInputElement>;
  /**
   * Configuration for input group styling when the field is part of a group:
   * - `prepend`: Field is preceded by another element (button, icon, text)
   * - `append`: Field is followed by another element
   * Affects border radius and styling to create seamless grouped appearance.
   */
  inputGroup?: InputGroupPlacement;
  /**
   * Step value for numeric input types that defines the increment/decrement amount.
   * When users click the number input's up/down arrows or use arrow keys,
   * the value changes by this step amount. Can be a number or string.
   */
  step?: number | string;
  /**
   * When true, displays error styling on the text field.
   * Typically changes border color to red and may add error-related visual cues.
   * Usually used in combination with `errorText` to provide validation feedback.
   */
  showError?: boolean;
  /**
   * Error message text to display below the field when validation fails.
   * Provides specific feedback about what the user needs to correct.
   * Only shown when there's an actual error to communicate.
   */
  errorText?: string;
  /**
   * When true, marks the field as required for form validation.
   * May add visual indicators (like asterisks) and prevents form submission
   * if the field is empty. Essential for mandatory form fields.
   */
  required?: boolean;
  /**
   * HTML autocomplete attribute that helps browsers provide appropriate suggestions.
   * Values like 'email', 'name', 'new-password', 'current-password', etc.
   * Improves user experience by enabling relevant autocomplete functionality.
   */
  autoComplete?: string;
  /**
   * When true, automatically focuses this field 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;
  /**
   * Fixed width in pixels for the text field input element.
   * Overrides default responsive width behavior when a specific width is needed.
   */
  inputWidth?: number;
  /**
   * Fixed height in pixels for the text field input element.
   * Overrides default height behavior when a specific height is needed.
   */
  inputHeight?: number;
  /**
   * Minimum allowed value for numeric, date, time, and range input types.
   * Prevents users from entering or selecting values below this threshold.
   * Used for validation and UI constraints in number-based inputs.
   */
  min?: number;
  /**
   * Maximum allowed value for numeric, date, time, and range input types.
   * Prevents users from entering or selecting values above this threshold.
   * Used for validation and UI constraints in number-based inputs.
   */
  max?: number;
} & TooltipComponentProps;
/**
 * Interface for defining dimension styles with CSS-compatible values.
 * Used internally for styling components with dynamic width and height.
 */
type DimensionStyle = {
  /** CSS width value (e.g., '100px', '50%', 'auto') */
  width?: string;
  /** CSS height value (e.g., '40px', '2rem', 'auto') */
  height?: string;
};
/**
 * Interface for defining text input length constraints.
 * Used for validation and input limiting in text-based fields.
 */
type InputLengthStyleProps = {
  /**
   * Maximum number of characters allowed in the text field.
   * Prevents users from entering more text beyond this limit.
   * Useful for database field constraints and UI consistency.
   */
  maxLength?: number;
  /**
   * Minimum number of characters required in the text field.
   * Used for validation to ensure adequate input length.
   * Commonly used for passwords, codes, or required descriptions.
   */
  minLength?: number;
};
//#endregion
export { DimensionStyle, InputLengthStyleProps, TextFieldProps };