/**
 * A position value for gradient stops, ranging from 0 (start) to 1 (end).
 */
export type GradientPosition = number;
/**
 * A color value that can be a CSS color string, hex value, or rgba/hsla string.
 */
export type ColorValue = string;
/**
 * A gradient stop defining a color at a specific position in the gradient.
 *
 * @example
 * ```ts
 * const stop: GradientStop = {
 *   position: 0.5,
 *   color: '#ffffff'
 * };
 * ```
 */
export interface GradientStop {
    /**
     * Position in the gradient where 0 is the start and 1 is the end.
     * Must be between 0 and 1 inclusive.
     */
    position: GradientPosition;
    /**
     * Color at this position. Can be any valid CSS color value.
     */
    color: ColorValue;
}
/**
 * Linear gradient direction configuration.
 *
 * @example
 * ```ts
 * const direction: LinearGradientDirection = {
 *   x1: 0, y1: 0,  // Start point (top-left)
 *   x2: 0, y2: 1   // End point (bottom-left)
 * };
 * ```
 */
export interface LinearGradientDirection {
    /**
     * X coordinate of the start point (0-1)
     */
    x1: number;
    /**
     * Y coordinate of the start point (0-1)
     */
    y1: number;
    /**
     * X coordinate of the end point (0-1)
     */
    x2: number;
    /**
     * Y coordinate of the end point (0-1)
     */
    y2: number;
}
/**
 * Radial gradient configuration.
 *
 * @example
 * ```ts
 * const radial: RadialGradientConfig = {
 *   centerX: 0.5,
 *   centerY: 0.5,
 *   radius: 0.8
 * };
 * ```
 */
export interface RadialGradientConfig {
    /**
     * X coordinate of the center point (0-1)
     */
    centerX: number;
    /**
     * Y coordinate of the center point (0-1)
     */
    centerY: number;
    /**
     * Radius of the gradient (0-1)
     */
    radius: number;
}
/**
 * Linear gradient color configuration.
 *
 * @example
 * ```ts
 * const linearGradient: LinearGradientColor = {
 *   type: 'linear',
 *   direction: { x1: 0, y1: 0, x2: 0, y2: 1 },
 *   stops: [
 *     { position: 0, color: '#003399' },
 *     { position: 0.5, color: '#ffffff' },
 *     { position: 1, color: '#3366AA' }
 *   ]
 * };
 * ```
 */
export interface LinearGradientColor {
    /**
     * Type discriminator for linear gradients
     */
    type: 'linear';
    /**
     * Direction of the linear gradient
     */
    direction: LinearGradientDirection;
    /**
     * Color stops along the gradient
     */
    stops: readonly GradientStop[];
}
/**
 * Radial gradient color configuration.
 *
 * @example
 * ```ts
 * const radialGradient: RadialGradientColor = {
 *   type: 'radial',
 *   center: { centerX: 0.5, centerY: 0.5, radius: 0.8 },
 *   stops: [
 *     { position: 0, color: '#ff0000' },
 *     { position: 1, color: '#0000ff' }
 *   ]
 * };
 * ```
 */
export interface RadialGradientColor {
    /**
     * Type discriminator for radial gradients
     */
    type: 'radial';
    /**
     * Center and radius configuration
     */
    center: RadialGradientConfig;
    /**
     * Color stops along the gradient
     */
    stops: readonly GradientStop[];
}
/**
 * Enhanced gradient color options that provide better type safety and developer experience.
 *
 * This is a discriminated union that allows for either linear or radial gradients,
 * with comprehensive type checking and better IntelliSense support.
 *
 * @example
 * ```ts
 * // Linear gradient example
 * const linearGradient: GradientColor = {
 *   type: 'linear',
 *   direction: { x1: 0, y1: 0, x2: 0, y2: 1 },
 *   stops: [
 *     { position: 0, color: '#003399' },
 *     { position: 0.5, color: '#ffffff' },
 *     { position: 1, color: '#3366AA' }
 *   ]
 * };
 *
 * // Radial gradient example
 * const radialGradient: GradientColor = {
 *   type: 'radial',
 *   center: { centerX: 0.5, centerY: 0.5, radius: 0.8 },
 *   stops: [
 *     { position: 0, color: '#ff0000' },
 *     { position: 1, color: '#0000ff' }
 *   ]
 * };
 * ```
 */
export type GradientColor = LinearGradientColor | RadialGradientColor;
/**
 * Utility type to check if a value is a linear gradient.
 *
 * @param value - The value to check
 * @returns True if the value is a linear gradient
 */
export declare const isLinearGradient: (value: any) => value is LinearGradientColor;
/**
 * Utility type to check if a value is a radial gradient.
 *
 * @param value - The value to check
 * @returns True if the value is a radial gradient
 */
export declare const isRadialGradient: (value: any) => value is RadialGradientColor;
/**
 * Utility type to check if a value is any gradient.
 *
 * @param value - The value to check
 * @returns True if the value is a gradient
 */
export declare const isGradient: (value: any) => value is GradientColor;
/**
 * Common gradient direction presets for convenience.
 */
export declare const GradientDirections: {
    /**
     * Top to bottom gradient
     */
    readonly topToBottom: {
        readonly x1: 0;
        readonly y1: 0;
        readonly x2: 0;
        readonly y2: 1;
    };
    /**
     * Bottom to top gradient
     */
    readonly bottomToTop: {
        readonly x1: 0;
        readonly y1: 1;
        readonly x2: 0;
        readonly y2: 0;
    };
    /**
     * Left to right gradient
     */
    readonly leftToRight: {
        readonly x1: 0;
        readonly y1: 0;
        readonly x2: 1;
        readonly y2: 0;
    };
    /**
     * Right to left gradient
     */
    readonly rightToLeft: {
        readonly x1: 1;
        readonly y1: 0;
        readonly x2: 0;
        readonly y2: 0;
    };
    /**
     * Diagonal top-left to bottom-right
     */
    readonly diagonalTopLeft: {
        readonly x1: 0;
        readonly y1: 0;
        readonly x2: 1;
        readonly y2: 1;
    };
    /**
     * Diagonal top-right to bottom-left
     */
    readonly diagonalTopRight: {
        readonly x1: 1;
        readonly y1: 0;
        readonly x2: 0;
        readonly y2: 1;
    };
};
/**
 * Common radial gradient presets for convenience.
 */
export declare const RadialGradientPresets: {
    /**
     * Center-focused radial gradient
     */
    readonly center: {
        readonly centerX: 0.5;
        readonly centerY: 0.5;
        readonly radius: 0.8;
    };
    /**
     * Top-left focused radial gradient
     */
    readonly topLeft: {
        readonly centerX: 0;
        readonly centerY: 0;
        readonly radius: 1;
    };
    /**
     * Top-right focused radial gradient
     */
    readonly topRight: {
        readonly centerX: 1;
        readonly centerY: 0;
        readonly radius: 1;
    };
    /**
     * Bottom-left focused radial gradient
     */
    readonly bottomLeft: {
        readonly centerX: 0;
        readonly centerY: 1;
        readonly radius: 1;
    };
    /**
     * Bottom-right focused radial gradient
     */
    readonly bottomRight: {
        readonly centerX: 1;
        readonly centerY: 1;
        readonly radius: 1;
    };
};
/**
 * Helper function to create a linear gradient with common direction presets.
 *
 * @param direction - The gradient direction
 * @param stops - The color stops
 * @returns A linear gradient configuration
 *
 * @example
 * ```ts
 * const gradient = createLinearGradient(
 *   GradientDirections.topToBottom,
 *   [
 *     { position: 0, color: '#003399' },
 *     { position: 1, color: '#3366AA' }
 *   ]
 * );
 * ```
 */
export declare const createLinearGradient: (direction: LinearGradientDirection, stops: readonly GradientStop[]) => LinearGradientColor;
/**
 * Helper function to create a radial gradient with common presets.
 *
 * @param center - The gradient center configuration
 * @param stops - The color stops
 * @returns A radial gradient configuration
 *
 * @example
 * ```ts
 * const gradient = createRadialGradient(
 *   RadialGradientPresets.center,
 *   [
 *     { position: 0, color: '#ff0000' },
 *     { position: 1, color: '#0000ff' }
 *   ]
 * );
 * ```
 */
export declare const createRadialGradient: (center: RadialGradientConfig, stops: readonly GradientStop[]) => RadialGradientColor;
/**
 * Inner compatibility interface that matches the original Highcharts GradientColorObject structure.
 *
 * This interface is provided for backward compatibility with existing Highcharts integrations.
 * For new code, prefer using the enhanced {@link GradientColor} types.
 *
 * @internal
 */
export interface HighchartsGradientColorObject {
    /**
     * Linear gradient configuration (inner format)
     */
    linearGradient?: {
        x1: number;
        y1: number;
        x2: number;
        y2: number;
    };
    /**
     * Radial gradient configuration (inner format)
     */
    radialGradient?: {
        cx: number;
        cy: number;
        r: number;
    };
    /**
     * Color stops in inner format [position, color]
     */
    stops: [number, string][];
}
/**
 * Converts a modern GradientColor to the inner Highcharts format.
 *
 * @param gradient - The modern gradient color
 * @returns The inner format gradient color object
 *
 * @internal
 */
export declare const toGradientHighchartsFormat: (gradient: GradientColor) => HighchartsGradientColorObject;
/**
 * Converts a inner Highcharts gradient to the modern format.
 *
 * @param highchartGradient - The inner gradient color object
 * @returns The modern gradient color format
 *
 * @internal
 */
export declare const fromHighchartsGradientFormat: (highchartGradient: HighchartsGradientColorObject) => GradientColor;
/**
 * Converts a color to the inner Highcharts format if it is a gradient, otherwise returns the color as is.
 *
 * @param color - The color to convert
 * @returns The inner format gradient color object or the color as is
 *
 * @internal
 */
export declare const withGradientConversion: <T>(color: T) => HighchartsGradientColorObject | Exclude<T, GradientColor>;
/**
 * Converts a GradientColor to a valid CSS gradient string.
 *
 * For linear gradients, calculates the angle from the direction coordinates.
 * For radial gradients, uses the center position and radius.
 *
 * @param gradient - The gradient color to convert
 * @returns A valid CSS gradient string (e.g., "linear-gradient(90deg, #fff 0%, #000 100%)")
 *
 * @example
 * ```ts
 * const linearGradient: GradientColor = {
 *   type: 'linear',
 *   direction: { x1: 0, y1: 0, x2: 0, y2: 1 },
 *   stops: [
 *     { position: 0, color: '#003399' },
 *     { position: 1, color: '#3366AA' }
 *   ]
 * };
 * const css = toCSSGradientFormat(linearGradient);
 * // Returns: "linear-gradient(180deg, #003399 0%, #3366AA 100%)"
 *
 * const radialGradient: GradientColor = {
 *   type: 'radial',
 *   center: { centerX: 0.5, centerY: 0.5, radius: 0.8 },
 *   stops: [
 *     { position: 0, color: '#ff0000' },
 *     { position: 1, color: '#0000ff' }
 *   ]
 * };
 * const css = toCSSGradientFormat(radialGradient);
 * // Returns: "radial-gradient(circle 80% at 50% 50%, #ff0000 0%, #0000ff 100%)"
 * ```
 *
 * @internal
 */
export declare const toCSSGradientFormat: (gradient: GradientColor) => string;
