import { SemanticColorVariable } from './theme-types.js';

/**
 * Theme Schema Versioning System
 *
 * This module tracks changes to the theme variable system over time.
 * When new CSS variables are added to Pika's theme system, a new schema version
 * is created so users can be notified and optionally update their theme configs.
 *
 * Usage:
 * - `pika theme check` - Shows what's new since your schema version
 * - `pika theme update` - Adds new variables with suggested defaults
 *
 * @since 0.16.0
 */

/**
 * The current theme schema version.
 * Increment this when adding new theme variables.
 */
declare const CURRENT_THEME_SCHEMA_VERSION = 1;
/**
 * Represents a change in a theme schema version
 */
interface ThemeSchemaChange {
    /** Version number (must be sequential) */
    version: number;
    /** Release date in ISO format */
    date: string;
    /** Brief description of changes */
    description: string;
    /** New CSS variables added in this version */
    addedVariables: {
        /** Variable name without -- prefix */
        name: string;
        /** Category for organization */
        category: ThemeVariableCategory;
        /** Description of what this variable controls */
        description: string;
        /** Suggested default value (oklch format preferred) */
        defaultLight: string;
        /** Suggested dark mode value */
        defaultDark?: string;
        /** What UI elements are affected */
        affectedElements: string[];
    }[];
    /** Variables that were deprecated */
    deprecatedVariables?: {
        name: string;
        replacement?: string;
        reason: string;
    }[];
}
/**
 * Categories for organizing theme variables
 */
type ThemeVariableCategory = 'core' | 'surface' | 'text' | 'border' | 'status' | 'sidebar' | 'chart' | 'brand';
/**
 * Complete documentation of a theme variable
 */
interface ThemeVariableDoc {
    name: SemanticColorVariable | string;
    category: ThemeVariableCategory;
    description: string;
    defaultLight: string;
    defaultDark: string;
    affectedElements: string[];
    introduced: number;
}
/**
 * Schema changelog - documents all changes to the theme system
 */
declare const THEME_SCHEMA_CHANGELOG: ThemeSchemaChange[];
/**
 * Get all theme variables introduced up to a specific version
 */
declare function getVariablesForVersion(version: number): ThemeVariableDoc[];
/**
 * Get variables added between two schema versions
 */
declare function getNewVariablesSince(fromVersion: number): ThemeSchemaChange[];
/**
 * Check if a theme config is up to date
 */
declare function isThemeSchemaUpToDate(schemaVersion: number | undefined): boolean;
/**
 * Get all variables organized by category
 */
declare function getVariablesByCategory(): Record<ThemeVariableCategory, ThemeVariableDoc[]>;
/**
 * Generate a theme config snippet with defaults for new variables
 */
declare function generateThemeSnippetForNewVariables(fromVersion: number, mode?: 'light' | 'dark'): string;

export { CURRENT_THEME_SCHEMA_VERSION, THEME_SCHEMA_CHANGELOG, type ThemeSchemaChange, type ThemeVariableCategory, type ThemeVariableDoc, generateThemeSnippetForNewVariables, getNewVariablesSince, getVariablesByCategory, getVariablesForVersion, isThemeSchemaUpToDate };