import { ApiPropertyOptional } from '@nestjs/swagger';
import { IsOptional, IsString, MinLength, MaxLength } from 'class-validator';
import { PaginationDto } from 'src/config/pagination/paginationDto';

/**
 * Search Menu Actions Data Transfer Object (DTO)
 *
 * This DTO is used for searching and filtering menu actions with pagination support.
 * It extends the PaginationDto to include standard pagination parameters while adding
 * a simple text search capability.
 *
 * Menu actions represent individual operations or permissions within the system,
 * and this search DTO provides a minimal interface for finding specific actions.
 *
 * @extends PaginationDto - Inherits page, limit, sort, order properties
 *
 * @example
 * // Basic search with pagination:
 * {
 *   "q": "create",
 *   "page": 1,
 *   "limit": 20,
 *   "sort": "name",
 *   "order": "ASC"
 * }
 *
 * @example
 * // Get all menu actions with default pagination:
 * {
 *   "page": 1,
 *   "limit": 50
 * }
 *
 * @note This DTO is quite minimal compared to other SearchDto classes in the codebase.
 * Consider adding more filter options if needed (e.g., by platform, active status, etc.).
 */
export class SearchMenuActionsDto extends PaginationDto {
  /**
   * Search query text for filtering menu actions by name.
   * Typically performs partial/contains matching on the action name field.
   *
   * @type {string}
   * @optional
   * @example "create" (matches "create_user", "create_product", etc.)
   * @example "delete" (matches "delete_record", "delete_user", etc.)
   * @example "export" (matches "export_reports", "export_data", etc.)
   *
   * @isString - Validation: Must be a string if provided
   *   Error message: "q must be a string"
   *
   * @isOptional - Validation: Field is not required
   *
   * @apiPropertyOptional - Swagger documentation for optional field
   *
   * @note The parameter name 'q' is a common convention for search queries.
   * Consider adding length validation to prevent overly broad or specific searches:
   *   @MinLength(2, { message: 'Search query must be at least 2 characters' })
   *   @MaxLength(50, { message: 'Search query cannot exceed 50 characters' })
   */
  @ApiPropertyOptional({
    description: 'Search query text for filtering menu actions by name',
    example: 'create',
    type: String,
    minLength: 2,
    maxLength: 50,
  })
  @IsOptional()
  @IsString({ message: 'Search query must be a string if provided' })
  @MinLength(2, { message: 'Search query must be at least 2 characters' })
  @MaxLength(50, { message: 'Search query cannot exceed 50 characters' })
  q?: string;
}
