/**
 * Model of google fonts api response
 */
export interface GoogleFontsApiModel {
    /**
     * Array of font items returned by the Google Fonts API
     * Contains all font families matching the requested query parameters
     */
    items: FontItem[];
}

export interface FontItem {
    /**
     * Font family name (e.g., "Roboto", "Open Sans", "Lato")
     * This is the name used in CSS font-family declarations
     */
    family: string;

    /**
     * Font category classification (e.g., "sans-serif", "serif", "display", "handwriting", "monospace")
     * Useful for grouping and filtering fonts by style
     */
    category: string;

    /**
     * Available font variants for this font family
     * Array of strings representing available weights and styles
     * Examples: ["regular", "italic", "100", "200", "300", "400", "500", "600", "700", "800", "900", "100italic", "900italic"]
     * The keys in the `files` object correspond to these variant values
     */
    variants: FontVariant[];

    /**
     * Supported character subsets for this font
     * Examples: ["latin", "latin-ext", "cyrillic", "greek", "arabic", "devanagari", "vietnamese", "hebrew", "thai", etc.]
     * Determines which character sets are included in the font files
     */
    subsets: string[];

    /**
     * Font version identifier
     * Format: "v" followed by version number (e.g., "v31", "v20", "v1")
     * Used to track font updates and cache busting
     */
    version: string;

    /**
     * Last modification date of the font
     * Format: ISO 8601 date string (e.g., "2024-01-15", "2023-12-01")
     * Indicates when the font was last updated by the font foundry
     */
    lastModified: string;

    /**
     * Mapping of font variants to their downloadable URLs
     * Keys correspond to values in the `variants` array
     * Examples:
     * - "regular" → "https://fonts.gstatic.com/s/roboto/v30/KFOmCnqEu92Fr1Me4W..."
     * - "700" → "https://fonts.gstatic.com/s/roboto/v30/KFOlCnqEu92Fr1MmWUlf..."
     * - "700italic" → "https://fonts.gstatic.com/s/roboto/v30/KFOjCnqEu92Fr1Mu51TzA..."
     */
    files: FontFiles;

    /**
     * URL to the font menu preview image
     * Typically a PNG showing the font family name in the font
     * Example: "https://fonts.gstatic.com/l/font?kit=KFOmCnqEu92Fr1Me4W...&s=i2"
     */
    menu: string;
}

/**
 * Standard font weights that can appear in Google Fonts API
 */
export type FontWeight = '100' | '200' | '300' | '400' | '500' | '600' | '700' | '800' | '900';

/**
 * Italic variant format: e.g., "100italic", "400italic", "700italic"
 */
export type FontWeightItalic = `${FontWeight}italic`;

/**
 * All possible font variants in Google Fonts API
 * - Numeric weights: "400", "700", etc.
 * - Italic variants: "400italic", "700italic", etc.
 * - Legacy names: "regular", "italic", "bold", "bolditalic"
 */
export type FontVariant =
    | FontWeight
    | FontWeightItalic
    | 'regular'
    | 'italic'
    | 'bold'
    | 'bolditalic';

/**
 * Google Fonts API file mapping
 * Dynamic keys that match the variants array
 *
 * Examples:
 * - { "regular": "...", "italic": "...", "700": "...", "700italic": "..." }
 * - { "400": "...", "400italic": "...", "900": "..." }
 */
export type FontFiles = Partial<Record<FontVariant, string>>;