/**
 * Type definitions for the App Asset Generator.
 *
 * This module defines the core types used throughout the asset generation
 * pipeline. These types ensure type safety across CLI parsing, configuration,
 * and asset generation.
 *
 * Key concepts:
 * - Platforms: Target platforms (iOS, Android, Web).
 * - Asset types: Categories of generated assets (icons, splash screens, etc.).
 * - Background/Foreground: The two layers composited to create each asset.
 */

// ─── Platform and Asset Type Enums ─────────────────────────────────────────

/** Target platform for asset generation. */
export type Platform =
	| 'ios'
	| 'android'
	| 'web'
	| 'watchos'
	| 'tvos'
	| 'visionos'

/** Category of asset to generate. */
export type AssetType = 'icon' | 'splash' | 'adaptive' | 'favicon' | 'store'

/** Type of background layer. */
export type BackgroundType = 'color' | 'gradient' | 'image'

/** Type of foreground layer (the logo/icon content). */
export type ForegroundType = 'svg' | 'text' | 'image'

/**
 * Color mode for theming support.
 * - 'light': Standard light appearance.
 * - 'dark': Dark appearance (iOS 18+ dark icons, Android night drawables).
 * - 'any': Works in both modes (Android monochrome icons for Material You).
 * - 'tinted': iOS 18 tinted (monochrome, system applies wallpaper color).
 * - 'clear-light': iOS 18 clear on light background (translucent).
 * - 'clear-dark': iOS 18 clear on dark background (translucent).
 */
export type ColorMode =
	| 'light'
	| 'dark'
	| 'any'
	| 'tinted'
	| 'clear-light'
	| 'clear-dark'

// ─── Background Configuration ──────────────────────────────────────────────

/** Solid color configuration with hex value. */
export interface ColorConfig {
	type: 'solid'
	/** Hex color code (e.g., '#FF5500'). */
	color: string
}

/** Gradient configuration for linear or radial gradients. */
export interface GradientConfig {
	type: 'linear' | 'radial'
	/** Array of hex color stops (minimum 2). */
	colors: string[]
	/** Angle in degrees for linear gradients (0-360, where 0 is top-to-bottom). */
	angle?: number
}

/**
 * Background layer configuration.
 *
 * The background is the base layer of each asset, filling the entire canvas.
 * Only one of color, gradient, or imagePath should be set based on type.
 */
export interface BackgroundConfig {
	type: BackgroundType
	/** Solid color configuration (when type is 'color'). */
	color?: ColorConfig
	/** Gradient configuration (when type is 'gradient'). */
	gradient?: GradientConfig
	/** Path to background image file (when type is 'image'). */
	imagePath?: string
}

// ─── Foreground Configuration ──────────────────────────────────────────────

/**
 * Text-based foreground configuration.
 *
 * Renders text characters using a specified font. Ideal for icons that use
 * a single letter or symbol (e.g., "G" for Google, "f" for Facebook).
 */
export interface TextForegroundConfig {
	type: 'text'
	/** Character(s) to display (typically 1-2 characters). */
	text: string
	/** Font family name (e.g., 'Playfair Display', 'Inter'). */
	fontFamily: string
	/** Optional font size override (auto-calculated if omitted). */
	fontSize?: number
	/** Text color as hex code. */
	color: string
	/** Where to load the font from. */
	fontSource: 'google' | 'system' | 'custom'
	/** Path to custom font file (required when fontSource is 'custom'). */
	fontPath?: string
}

/**
 * SVG-based foreground configuration.
 *
 * Renders an SVG file as the icon content. Ideal for vector logos that
 * need to scale cleanly to any resolution.
 */
export interface SVGForegroundConfig {
	type: 'svg'
	/** Path to SVG file. */
	svgPath: string
	/** Optional color override (replaces all fill colors in the SVG). */
	color?: string
}

/**
 * Image-based foreground configuration.
 *
 * Uses a raster image (PNG, JPEG) as the icon content. The image is
 * scaled to fit within the foreground area while preserving aspect ratio.
 */
export interface ImageForegroundConfig {
	type: 'image'
	/** Path to image file (PNG, JPEG, WebP, etc.). */
	imagePath: string
}

/** Union type for all foreground configuration variants. */
export type ForegroundConfig =
	| TextForegroundConfig
	| SVGForegroundConfig
	| ImageForegroundConfig

// ─── Main Configuration ────────────────────────────────────────────────────

/**
 * Complete configuration for the asset generation pipeline.
 *
 * This interface represents all options needed to generate a complete set
 * of app assets across all requested platforms and asset types.
 */
export interface AssetGeneratorConfig {
	/** Application name (used for documentation). */
	appName: string

	/** Target platforms to generate assets for. */
	platforms: Platform[]

	/** Types of assets to generate. */
	assetTypes: AssetType[]

	/** Background layer configuration. */
	background: BackgroundConfig

	/** Foreground layer configuration (logo/icon content). */
	foreground: ForegroundConfig

	/** Output directory for generated assets. */
	outputDir: string

	/**
	 * Foreground scale for app icons (0.1 to 1.5).
	 *
	 * Controls how much of the icon canvas the logo fills.
	 * Default: 0.7 (70% of icon size).
	 *
	 * Best practices:
	 * - 0.6-0.7: Standard, good for text/logos with padding.
	 * - 0.8-0.9: Bold, fills most of the icon.
	 * - 0.5-0.6: Conservative, more background visible.
	 * - 1.0-1.5: Edge-to-edge, logo may extend beyond canvas.
	 */
	iconScale?: number

	/**
	 * Foreground scale for splash screens (0.05 to 1.0).
	 *
	 * Controls how much of the screen height the logo fills.
	 * Default: 0.25 (25% of screen height).
	 *
	 * Best practices:
	 * - 0.2-0.3: Standard, centered branding.
	 * - 0.15-0.2: Minimal, subtle presence.
	 * - 0.3-0.5: Prominent, bold statement.
	 * - 0.5-1.0: Large, fills most of screen.
	 */
	splashScale?: number

	/**
	 * Foreground scale for web favicons (0.5 to 1.0).
	 *
	 * Controls how much of the favicon canvas the logo fills.
	 * Default: 0.85 (85% of icon size) for visibility at small sizes.
	 *
	 * Best practices:
	 * - 0.85-0.95: Recommended, maximizes visibility at 16px/32px.
	 * - 0.7-0.85: Standard, matches icon scale with more padding.
	 * - 0.5-0.7: Conservative, more background visible.
	 *
	 * Note: Favicons are typically very small (16-48px), so higher
	 * scales improve legibility. This scale applies to all favicon
	 * sizes including favicon.ico and PNG favicons.
	 */
	faviconScale?: number

	/**
	 * Foreground scale for store listing graphics (0.3 to 0.8).
	 *
	 * Controls how much of the store graphic canvas the logo fills.
	 * Default: 0.5 (50% of graphic size).
	 *
	 * Best practices:
	 * - 0.5: Standard, centered branding with comfortable padding.
	 * - 0.3-0.4: Conservative, more background visible for feature graphics.
	 * - 0.6-0.8: Prominent, fills more of the graphic.
	 *
	 * Note: Store graphics (feature graphic, TV banner) are typically
	 * wide-format and benefit from lower scales to avoid crowding.
	 */
	storeScale?: number
}

// ─── Asset Specification and Results ───────────────────────────────────────

/**
 * Specification for a single asset to generate.
 *
 * Each AssetSpec describes one output file with its dimensions, platform,
 * type, and optional variants (scale, color mode).
 */
export interface AssetSpec {
	/** Output filename (may include subdirectory, e.g., 'mipmap-hdpi/icon.png'). */
	name: string

	/** Width in pixels. */
	width: number

	/** Height in pixels. */
	height: number

	/** Target platform. */
	platform: Platform

	/** Asset type category. */
	type: AssetType

	/** Display scale factor for @2x, @3x variants (iOS). */
	scale?: number

	/** Color mode for light/dark theme variants. */
	colorMode?: ColorMode
}

/**
 * A generated asset with its image data and output path.
 */
export interface GeneratedAsset {
	/** The specification this asset was generated from. */
	spec: AssetSpec

	/** PNG image data as a Buffer. */
	buffer: Buffer

	/** Full output path for the asset file. */
	path: string
}

/**
 * Result of the asset generation pipeline.
 *
 * Contains all generated assets, output location, and any errors that
 * occurred during generation.
 */
export interface GenerationResult {
	/** True if all assets generated successfully. */
	success: boolean

	/** Array of generated asset objects. */
	assets: GeneratedAsset[]

	/** Root output directory. */
	outputDir: string

	/** Path to the generated README.md file. */
	instructionsPath?: string

	/** Array of error messages for failed assets. */
	errors?: string[]
}

// ─── History Types ─────────────────────────────────────────────────────────

/**
 * A single history entry representing a past generation.
 *
 * Stored in ~/.appicons/history.json for persistence across sessions.
 * Allows users to reload and reuse previous configurations.
 */
export interface HistoryEntry {
	/** Unique identifier (timestamp-based). */
	id: string

	/** ISO 8601 datetime when the entry was created. */
	createdAt: string

	/** Optional user-provided name for easy identification. */
	name?: string

	/** Full generation configuration that was used. */
	config: AssetGeneratorConfig

	/** Directory where assets were generated. */
	outputDir: string
}

/**
 * History file structure stored at ~/.appicons/history.json.
 *
 * Version field allows for future schema migrations.
 * Entries are stored newest first, with a maximum of 50 entries.
 */
export interface HistoryFile {
	/** Schema version for future migrations. */
	version: 1

	/** Array of history entries, newest first. Max 50 entries. */
	entries: HistoryEntry[]
}