import { ApiProperty } from '@nestjs/swagger';

/**
 * Generic response DTO for select/dropdown options.
 * This DTO provides a standardized structure for returning option data
 * used in UI dropdowns, select inputs, autocomplete fields, and filters.
 *
 * The `value` property represents the underlying data value (for processing),
 * while the `label` property represents the display text (for user interface).
 *
 * @template T - Type of the value (typically number or string)
 *
 * @example
 * // For a country dropdown:
 * {
 *   value: 1,
 *   label: "United States"
 * }
 *
 * @example
 * // For a status dropdown:
 * {
 *   value: "active",
 *   label: "Active"
 * }
 *
 * @example
 * // Array of options for a select input:
 * [
 *   { value: 1, label: "Option 1" },
 *   { value: 2, label: "Option 2" },
 *   { value: 3, label: "Option 3" }
 * ]
 */
export class OptionsResponseDto<T = number | string> {
  /**
   * The underlying value of the option.
   * This is the value that gets submitted/stored/processed.
   *
   * @type {number | string}
   * @example 1 (for ID-based options)
   * @example "usa" (for code-based options)
   * @example "ACTIVE" (for status codes)
   */
  @ApiProperty({
    description: 'The underlying value for the option (submitted/stored value)',
    oneOf: [
      { type: 'number', example: 1 },
      { type: 'string', example: 'active' },
    ],
  })
  value: T;

  /**
   * The display label for the option.
   * This is the text shown to users in the UI.
   *
   * @type {number | string}
   * @example "United States" (for country name)
   * @example "Active" (for status display)
   * @example 2024 (for year display - though string might be better)
   */
  @ApiProperty({
    description: 'The display text shown to users in the UI',
    oneOf: [
      { type: 'number', example: 'United States' },
      { type: 'string', example: 'Active' },
    ],
  })
  label: T;
}
