import { IsInt, IsNotEmpty, IsOptional, IsString } from 'class-validator';
import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';

/**
 * Data Transfer Object (DTO) for creating or managing menu bookmarks.
 *
 * This DTO is used when users want to add or remove menu items from their
 * bookmarks/favorites list. Bookmarked menus typically appear in a quick-access
 * section of the application UI.
 *
 * @example
 * // Adding a bookmark:
 * {
 *   "menu_link": "/users",
 *   "menu_name": "User Management",
 *   "action": "add"
 * }
 *
 * @example
 * // Removing a bookmark (with ID):
 * {
 *   "id": 123,
 *   "menu_link": "/reports",
 *   "menu_name": "Analytics Reports",
 *   "action": "remove"
 * }
 */
export class CreateMenuBookmarkDto {
  /**
   * Optional ID of an existing bookmark.
   * Used primarily when removing or updating an existing bookmark.
   * Not required when creating a new bookmark.
   *
   * @type {number}
   * @optional
   *
   * @isInt - Validation: Must be an integer if provided
   *   Error message: "id must be an integer"
   *
   * @isOptional - Validation: Field is not required
   */
  @ApiPropertyOptional({
    description: 'ID of existing bookmark (required for removal/updates)',
    example: 123,
    type: Number,
  })
  @IsInt({ message: 'Bookmark ID must be an integer' })
  @IsOptional()
  id?: number;

  /**
   * URL or route path of the menu item to bookmark.
   * This should match the actual navigation path in the application.
   *
   * @type {string}
   * @required
   * @example "/dashboard"
   * @example "/admin/users"
   *
   * @isString - Validation: Must be a string
   *   Error message: "menu_link must be a string"
   *
   * @isNotEmpty - Validation: Cannot be empty string
   *   Error message: "menu_link should not be empty"
   */
  @ApiProperty({
    description: 'URL or route path of the menu item',
    example: '/admin/users',
    type: String,
  })
  @IsString({ message: 'Menu link must be a string' })
  @IsNotEmpty({ message: 'Menu link is required' })
  menu_link: string;

  /**
   * Display name of the menu item.
   * This is what users see in their bookmarks list.
   *
   * @type {string}
   * @required
   * @example "User Management"
   * @example "Analytics Dashboard"
   *
   * @isString - Validation: Must be a string
   *   Error message: "menu_name must be a string"
   *
   * @isNotEmpty - Validation: Cannot be empty string
   *   Error message: "menu_name should not be empty"
   */
  @ApiProperty({
    description: 'Display name of the menu item',
    example: 'User Management',
    type: String,
  })
  @IsString({ message: 'Menu name must be a string' })
  @IsNotEmpty({ message: 'Menu name is required' })
  menu_name: string;

  /**
   * Action to perform on the bookmark.
   * Typically either "add" to create a bookmark or "remove" to delete one.
   *
   * @type {string}
   * @required
   * @example "add"
   * @example "remove"
   *
   * @isString - Validation: Must be a string
   *   Error message: "action must be a string"
   *
   * @isNotEmpty - Validation: Cannot be empty string
   *   Error message: "action should not be empty"
   *
   * @note Consider using an enum for better type safety:
   *   action: 'add' | 'remove' | 'toggle'
   */
  @ApiProperty({
    description:
      'Action to perform: "add" to create bookmark, "remove" to delete',
    example: 'add',
    type: String,
    enum: ['add', 'remove'],
  })
  @IsString({ message: 'Action must be a string' })
  @IsNotEmpty({ message: 'Action is required' })
  action: string;
}
