/**
 * SearchDto
 * ---------
 * DTO used for searching, filtering, and paginating Menu Groups.
 *
 * Inheritance:
 * - Extends PaginationDto to automatically include:
 *   - page
 *   - limit
 *   - sort
 *   - order
 *
 * Purpose:
 * - Supports advanced filtering for list views
 * - Enables CSV export using the same endpoint
 * - Allows date-range-based searching
 *
 * Used in:
 * - MenuGroupsController.findAll()
 */
import { ApiPropertyOptional } from '@nestjs/swagger';
import { Type } from 'class-transformer';
import {
  IsArray,
  IsBoolean,
  IsOptional,
  IsString,
  ValidateNested,
} from 'class-validator';
import { DateRangeDto } from 'src/utils/datetime/dateRangeDto';
import { PaginationDto } from 'src/config/pagination/paginationDto';

export class SearchDto extends PaginationDto {
  /**
   * Global Search Title
   * -------------------
   * Free-text search applied to menu group name or title fields.
   *
   * Validation:
   * - Optional field
   * - Must be a string if provided
   *
   * Example:
   * "admin"
   */
  @ApiPropertyOptional()
  @IsOptional()
  @IsString()
  search_title?: string;

  /**
   * Created By Filter
   * -----------------
   * Filters menu groups created by specific user IDs.
   *
   * Validation:
   * - Optional field
   * - Must be an array
   * - Each value must be a string
   *
   * Example:
   * ["1", "5", "10"]
   */
  @ApiPropertyOptional({ type: [String] })
  @IsOptional()
  @IsArray()
  @IsString({ each: true })
  created_by?: string[];

  /**
   * Updated By Filter
   * -----------------
   * Filters menu groups updated by specific user IDs.
   *
   * Validation:
   * - Optional field
   * - Must be an array
   * - Each value must be a string
   *
   * Example:
   * ["2", "4"]
   */
  @ApiPropertyOptional({ type: [String] })
  @IsOptional()
  @IsArray()
  @IsString({ each: true })
  updated_by?: string[];

  /**
   * Active Status Filter
   * --------------------
   * Filters menu groups based on active/inactive status.
   *
   * Common Values:
   * - ["1"] → Active
   * - ["0"] → Inactive
   *
   * Design Note:
   * - Stored as string array to match query builder IN() clauses
   * - Allows multi-status filtering if needed
   */
  @ApiPropertyOptional({ type: [String] })
  @IsOptional()
  @IsArray()
  @IsString({ each: true })
  active?: string[];

  /**
   * CSV Export Flag
   * ---------------
   * Indicates whether the request is intended for CSV export.
   *
   * Behavior:
   * - true  → return full dataset (ignore pagination)
   * - false → return paginated response
   *
   * Validation:
   * - Optional field
   * - Must be boolean if provided
   *
   * Default:
   * - false
   */
  @ApiPropertyOptional()
  @IsOptional()
  @IsBoolean()
  is_csv?: boolean = false;

  /**
   * Created Date Range Filter
   * -------------------------
   * Filters menu groups based on creation date range.
   *
   * Structure:
   * {
   *   "from": "2024-01-01",
   *   "to": "2024-01-31"
   * }
   *
   * Validation:
   * - Optional nested object
   * - Validated using DateRangeDto rules
   *
   * Notes:
   * - Uses @Type() to enable proper class transformation
   * - Required for ValidateNested() to work correctly
   */
  @ApiPropertyOptional({ type: DateRangeDto })
  @IsOptional()
  @ValidateNested()
  @Type(() => DateRangeDto)
  created_on?: DateRangeDto;

  /**
   * Updated Date Range Filter
   * -------------------------
   * Filters menu groups based on last updated date range.
   *
   * Same behavior and validation rules as `created_on`
   */
  @ApiPropertyOptional({ type: DateRangeDto })
  @IsOptional()
  @ValidateNested()
  @Type(() => DateRangeDto)
  updated_on?: DateRangeDto;
}
