import { IEventEmitter } from '@breadstone/mosaik-elements';

/**
 * @public
 */
declare function darken(hex: string, factor: number): string;
/**
 * @public
 */
declare function lighten(hex: string, factor: number): string;

/**
 * Generate an analogous color palette
 * @param baseHex
 * @param adjustment
 * @returns
 */
declare function generateAnalogousPalette(baseHex: string, adjustment: number): Record<string, string>;
/**
 * Generate a single analogous color
 * @param baseHex
 * @param adjustment
 * @returns
 */
declare function generateAnalogousColor(baseHex: string, adjustment: number): string;

/**
 * Generates a complementary color palette based on the given base color.
 * @param baseHex
 * @returns
 */
declare function generateComplementaryPalette(baseHex: string): Record<string, string>;
/**
 * Generates a single complementary color based on the given base color.
 * @param baseHex
 * @returns
 */
declare function generateComplementaryColor(baseHex: string): string;

/**
 * Generates a material color palette based on the given hex color.
 * @param hexColor
 * @returns
 */
declare function generateMaterialPalette(hexColor: string): Record<string, string>;

/**
 * Generates split-complementary colors based on the given base color.
 * Split-complementary uses two colors adjacent to the complement (150° and 210°).
 *
 * @param baseHex - The base color in hex format.
 * @returns An array of two split-complementary colors.
 * @public
 */
declare function generateSplitComplementaryColors(baseHex: string): [string, string];
/**
 * Generates the first split-complementary color (150° from base).
 *
 * @param baseHex - The base color in hex format.
 * @returns The first split-complementary color.
 * @public
 */
declare function generateSplitComplementaryColor1(baseHex: string): string;
/**
 * Generates the second split-complementary color (210° from base).
 *
 * @param baseHex - The base color in hex format.
 * @returns The second split-complementary color.
 * @public
 */
declare function generateSplitComplementaryColor2(baseHex: string): string;

/**
 * Generates tetradic (square) colors based on the given base color.
 * Tetradic uses four colors evenly spaced around the color wheel (90° apart).
 *
 * @param baseHex - The base color in hex format.
 * @returns An array of three tetradic colors (excluding the base).
 * @public
 */
declare function generateTetradicColors(baseHex: string): [string, string, string];
/**
 * Generates the first tetradic color (90° from base).
 *
 * @param baseHex - The base color in hex format.
 * @returns The first tetradic color.
 * @public
 */
declare function generateTetradicColor1(baseHex: string): string;
/**
 * Generates the third tetradic color (270° from base).
 *
 * @param baseHex - The base color in hex format.
 * @returns The third tetradic color.
 * @public
 */
declare function generateTetradicColor3(baseHex: string): string;

/**
 * Generate a triadic color palette
 * @param baseHex
 * @param adjustment
 * @returns
 */
declare function generateTriadicPalette(baseHex: string, adjustment: number): Record<string, string>;
/**
 * Generate a single triadic color
 * @param baseHex
 * @param adjustment
 * @returns
 */
declare function generateTriadicColor(baseHex: string, adjustment: number): string;

declare namespace Colors {
    const toDarken: typeof darken;
    const toLighten: typeof lighten;
    const toMaterialPalette: typeof generateMaterialPalette;
    const toComplementaryPalette: typeof generateComplementaryPalette;
    const toComplementaryColor: typeof generateComplementaryColor;
    const toAnalogousPalette: typeof generateAnalogousPalette;
    const toAnalogousColor: typeof generateAnalogousColor;
    const toTriadicPalette: typeof generateTriadicPalette;
    const toTriadicColor: typeof generateTriadicColor;
    const toSplitComplementaryColors: typeof generateSplitComplementaryColors;
    const toSplitComplementaryColor1: typeof generateSplitComplementaryColor1;
    const toSplitComplementaryColor2: typeof generateSplitComplementaryColor2;
    const toTetradicColors: typeof generateTetradicColors;
    const toTetradicColor1: typeof generateTetradicColor1;
    const toTetradicColor3: typeof generateTetradicColor3;
}

/**
 * Platform adapter interface for abstracting browser APIs.
 * Allows ThemeObserver and ThemeGenerator to work in both browser and Node.js environments.
 *
 * @public
 */
interface IPlatformAdapter {
    /**
     * Checks if media query matches (e.g., prefers-color-scheme).
     */
    matchMedia(query: string): boolean;
    /**
     * Sets an attribute on the document element.
     */
    setDocumentAttribute(name: string, value: string): void;
    /**
     * Gets an attribute from the document element.
     */
    getDocumentAttribute(name: string): string | null;
    /**
     * Observes changes to document element attributes.
     */
    observeDocumentAttributes(attributes: Array<string>, callback: (attributeName: string, newValue: string | null) => void): () => void;
}

/**
 * Browser implementation of the platform adapter.
 * Uses native DOM APIs (window, document, MutationObserver).
 *
 * @public
 */
declare class BrowserPlatformAdapter implements IPlatformAdapter {
    matchMedia(query: string): boolean;
    setDocumentAttribute(name: string, value: string): void;
    getDocumentAttribute(name: string): string | null;
    observeDocumentAttributes(attributes: Array<string>, callback: (attributeName: string, newValue: string | null) => void): () => void;
}

/**
 * Node.js implementation of the platform adapter.
 * No-op implementation that doesn't crash but does nothing.
 *
 * @public
 */
declare class NodePlatformAdapter implements IPlatformAdapter {
    matchMedia(_query: string): boolean;
    setDocumentAttribute(_name: string, _value: string): void;
    getDocumentAttribute(_name: string): string | null;
    observeDocumentAttributes(_attributes: Array<string>, _callback: (attributeName: string, newValue: string | null) => void): () => void;
}

/**
 * Factory that automatically detects the environment and returns the appropriate adapter.
 *
 * @public
 */
declare class PlatformAdapterFactory {
    /**
     * Creates the appropriate platform adapter based on the current environment.
     * Automatically detects if running in browser or Node.js.
     *
     * @public
     */
    static create(): IPlatformAdapter;
}

/**
 * @public
 */
type CssRGBColor = `rgb(${number}, ${number}, ${number})`;
/**
 * @public
 */
type CssRGBAColor = `rgba(${number}, ${number}, ${number}, ${number})`;
/**
 * @public
 */
type CssHEXColor = `#${string}`;
/**
 * @public
 */
type CssNameColor = 'aliceblue' | 'antiquewhite' | 'aqua' | 'aquamarine' | 'azure' | 'beige' | 'bisque' | 'black' | 'blanchedalmond' | 'blue' | 'blueviolet' | 'brown' | 'burlywood' | 'cadetblue' | 'chartreuse' | 'chocolate' | 'coral' | 'cornflowerblue' | 'cornsilk' | 'crimson' | 'cyan' | 'darkblue' | 'darkcyan' | 'darkgoldenrod' | 'darkgray' | 'darkgreen' | 'darkgrey' | 'darkkhaki' | 'darkmagenta' | 'darkolivegreen' | 'darkorange' | 'darkorchid' | 'darkred' | 'darksalmon' | 'darkseagreen' | 'darkslateblue' | 'darkslategray' | 'darkslategrey' | 'darkturquoise' | 'darkviolet' | 'deeppink' | 'deepskyblue' | 'dimgray' | 'dimgrey' | 'dodgerblue' | 'firebrick' | 'floralwhite' | 'forestgreen' | 'fuchsia' | 'gainsboro' | 'ghostwhite' | 'gold' | 'goldenrod' | 'gray' | 'green' | 'greenyellow' | 'grey' | 'honeydew' | 'hotpink' | 'indianred' | 'indigo' | 'ivory' | 'khaki' | 'lavender' | 'lavenderblush' | 'lawngreen' | 'lemonchiffon' | 'lightblue' | 'lightcoral' | 'lightcyan' | 'lightgoldenrodyellow' | 'lightgray' | 'lightgreen' | 'lightgrey' | 'lightpink' | 'lightsalmon' | 'lightseagreen' | 'lightskyblue' | 'lightslategray' | 'lightslategrey' | 'lightsteelblue' | 'lightyellow' | 'lime' | 'limegreen' | 'linen' | 'magenta' | 'maroon' | 'mediumaquamarine' | 'mediumblue' | 'mediumorchid' | 'mediumpurple' | 'mediumseagreen' | 'mediumslateblue' | 'mediumspringgreen' | 'mediumturquoise' | 'mediumvioletred' | 'midnightblue' | 'mintcream' | 'mistyrose' | 'moccasin' | 'navajowhite' | 'navy' | 'oldlace' | 'olive' | 'olivedrab' | 'orange' | 'orangered' | 'orchid' | 'palegoldenrod' | 'palegreen' | 'paleturquoise' | 'palevioletred' | 'papayawhip' | 'peachpuff' | 'peru' | 'pink' | 'plum' | 'powderblue' | 'purple' | 'rebeccapurple' | 'red' | 'rosybrown' | 'royalblue' | 'saddlebrown' | 'salmon' | 'sandybrown' | 'seagreen' | 'seashell' | 'sienna' | 'silver' | 'skyblue' | 'slateblue' | 'slategray' | 'slategrey' | 'snow' | 'springgreen' | 'steelblue' | 'tan' | 'teal' | 'thistle' | 'tomato' | 'transparent' | 'turquoise' | 'violet' | 'wheat' | 'white' | 'whitesmoke' | 'yellow' | 'yellowgreen';
/**
 * @public
 */
type CssColor = CssRGBColor | CssRGBAColor | CssHEXColor;
/**
 * @public
 */
declare namespace CssColor {
    /**
     * @public
     */
    function isCssColor(value: unknown): value is CssColor;
}

/**
 * @public
 */
type CssLengthUnit = 'em' | 'ex' | 'ch' | 'rem' | 'vh' | 'vw' | 'vmin' | 'vmax' | 'svw' | 'svh' | 'dvw' | 'dvh' | 'lvw' | 'lvh' | 'px' | 'mm' | 'cm' | 'in' | 'pt' | 'pc' | 'mozmm';
/**
 * @public
 */
type CssNumber = `${number}${CssLengthUnit}` | number;
/**
 * @public
 */
type CssLength = `${number}${CssLengthUnit | '%'}` | CssNumber | 'auto';
declare namespace CssLength {
    /**
     * Determines whether the given value is a valid CSS length.
     *
     * @public
     * @param value - The value to check.
     * @returns `true` if the value is a valid CSS length; otherwise, `false`.
     */
    function isCssLength(value: unknown): value is CssLength;
    /**
     * Determines whether the given value is 'auto'.
     *
     * @public
     * @param value - The value to check.
     * @returns `true` if the value is 'auto'; otherwise, `false`.
     */
    function isAuto(value: unknown): value is Extract<CssLength, 'auto'>;
    /**
     * Determines whether the given value is a percentage CSS length.
     *
     * @public
     * @param value - The value to check.
     * @returns `true` if the value is a percentage; otherwise, `false`.
     */
    function isPercentage(value: unknown): value is `${number}%`;
    /**
     * Determines whether the given value is a valid CSS length with units (excluding percentages).
     *
     * @public
     * @param value - The value to check.
     * @returns `true` if the value is a valid CSS length with units; otherwise, `false`.
     */
    function isLength(value: unknown): value is `${number}${CssLengthUnit}`;
    /**
     * Converts a `CssLength` to a number.
     * Only works for numeric values without units.
     *
     * @public
     * @param value - The `CssLength` value to convert.
     * @returns The numeric value.
     * @throws Error if the value is not a number.
     */
    function toNumber(value: CssLength): number;
    /**
     * Converts a `CssLength` to a string representation.
     * Numbers are treated as pixels.
     *
     * @public
     * @param value - The `CssLength` value to convert.
     * @param defaultUnit - The default unit to use if the value is a number.
     * @returns The string representation of the `CssLength`.
     */
    function toString(value?: CssLength, defaultUnit?: CssLengthUnit): string;
    /**
     * Extracts the unit from a CSS length string.
     *
     * @public
     * @param cssLength - The CSS length string to extract the unit from.
     * @returns The unit as a `CssLengthUnit`.
     * @throws Error if the input is not a valid CSS length.
     */
    function extractUnit(cssLength: `${number}${CssLengthUnit | '%'}`): CssLengthUnit;
    /**
     * Extracts the numeric value from a CSS length string.
     *
     * @public
     * @param cssLength - The CSS length string to extract the value from.
     * @returns The numeric value as a number.
     * @throws Error if the input is not a valid CSS length.
     */
    function extractValue(cssLength: `${number}${CssLengthUnit | '%'}`): number;
    /**
     * Converts pixel values to rem units.
     *
     * @public
     * @param pixel - The pixel value to convert.
     * @returns The converted value in rem units.
     */
    function pxToRem(pixel: `${number}${Extract<CssLengthUnit, 'px'>}`): string;
    /**
     * Tries to parse a value into a `CssLength`.
     *
     * @public
     * @param value - The value to parse.
     * @param defaultUnit - The default unit to use if the value is a string without a unit.
     * @returns The parsed `CssLength` or `undefined` if parsing fails.
     */
    function tryParse(value: unknown, defaultUnit?: CssLengthUnit): CssLength | undefined;
}

/**
 * Represents a valid CSS box-shadow value (single or multiple).
 *
 * @public
 */
type CssShadowSingle = 'none' | `${`${number}${Extract<CssLengthUnit, 'px'>}`} ${`${number}${Extract<CssLengthUnit, 'px'>}`} ${`${number}${Extract<CssLengthUnit, 'px'>}`} ${`${number}${Extract<CssLengthUnit, 'px'>}`} ${CssColor}` | `inset ${`${number}${Extract<CssLengthUnit, 'px'>}`} ${`${number}${Extract<CssLengthUnit, 'px'>}`} ${`${number}${Extract<CssLengthUnit, 'px'>}`} ${`${number}${Extract<CssLengthUnit, 'px'>}`} ${CssColor}` | `${`${number}${Extract<CssLengthUnit, 'px'>}`} ${`${number}${Extract<CssLengthUnit, 'px'>}`} ${`${number}${Extract<CssLengthUnit, 'px'>}`} ${CssColor}` | `inset ${`${number}${Extract<CssLengthUnit, 'px'>}`} ${`${number}${Extract<CssLengthUnit, 'px'>}`} ${`${number}${Extract<CssLengthUnit, 'px'>}`} ${CssColor}` | `${`${number}${Extract<CssLengthUnit, 'px'>}`} ${`${number}${Extract<CssLengthUnit, 'px'>}`} ${CssColor}` | `inset ${`${number}${Extract<CssLengthUnit, 'px'>}`} ${`${number}${Extract<CssLengthUnit, 'px'>}`} ${CssColor}`;
/**
 * Represents a valid CSS box-shadow value, including multiple shadows.
 *
 * @public
 */
type CssShadow = CssShadowSingle | `${CssShadowSingle}, ${CssShadowSingle}` | `${CssShadowSingle}, ${CssShadowSingle}, ${CssShadowSingle}`;
/**
 * @public
 */
declare namespace CssShadow {
    /**
     * Checks if the given value is a valid CSS box-shadow (single or multiple).
     *
     * @param value - The value to check.
     * @returns `true` if the value is a valid CSS box-shadow, otherwise `false`.
     */
    function isCssShadow(value: unknown): value is CssShadow;
}

/**
 * Represents dynamic shadow elevation styles.
 *
 * @public
 */
interface IThemeElevation {
    [key: string]: CssShadow;
}

/**
 * Represents dynamic layout properties.
 *
 * @public
 */
interface IThemeLayout {
    thickness?: CssLength;
    radius?: CssLength;
    space?: CssLength;
}

/**
 * Theme mode.
 *
 * @public
 */
type ThemeMode = 'dark' | 'light';
/**
 * Available theme modes.
 *
 * @public
 */
declare const THEME_MODES: ReadonlyArray<ThemeMode>;
/**
 * Theme mode with system option.
 *
 * @public
 */
type ThemeModeWithSystem = ThemeMode | 'system';

/**
 * Represents the shade names available in a theme palette.
 *
 * @public
 */
type ThemeShadeName = '0' | '50' | '100' | '200' | '300' | '400' | '500' | '600' | '700' | '800' | '900';
/**
 * Represents a dynamic theme palette.
 *
 * @public
 */
type ThemePalette = Partial<Record<ThemeShadeName, CssColor>>;
/**
 * @public
 */
declare namespace ThemePalette {
    /**
     * Checks if the value is a theme palette.
     *
     * @public
     * @param value - The value to check.
     * @returns The result.
     */
    function isThemePalette(value: unknown): value is ThemePalette;
}

/**
 * Represents the roles available in a theme scheme.
 *
 * @public
 */
type ThemeSchemeRole = 'surface' | 'background' | 'foreground' | 'highlight' | 'middlelight' | 'lowlight' | 'transparent' | 'semiTransparent' | 'disabled' | 'contrast' | 'selection';
/**
 * Represents a semantic color scheme.
 *
 * ThemeSchemeRole → CssColor
 *
 * @public
 */
type ThemeScheme = Readonly<Partial<Record<ThemeSchemeRole, CssColor>>>;
/**
 * @public
 */
declare namespace ThemeScheme {
    /**
     * Checks whether a value is a ThemeScheme.
     */
    function isThemeScheme(value: unknown): value is ThemeScheme;
}

/**
 * Brand / design-driven semantic colors.
 *
 * @public
 */
type ThemeRoleName = 'primary' | 'secondary' | 'tertiary';
/**
 * State / feedback-driven semantic colors.
 *
 * @public
 */
type ThemeStateName = 'danger' | 'warning' | 'success' | 'info' | 'highlight' | 'neutral';
/**
 * @public
 */
type ThemeSemanticName = ThemeRoleName | ThemeStateName;
/**
 * @public
 */
type ThemeSemantic = Record<ThemeSemanticName, ThemePalette>;

/**
 * Represents dynamic typography styles.
 *
 * @public
 */
interface IThemeTypographyFontType {
    fontFamily?: string;
    fontSize: `${number}${Extract<CssLengthUnit, 'px'>}`;
    lineHeight: `${number}${Extract<CssLengthUnit, 'px'>}` | `${number}`;
    fontWeight: '100' | '200' | '300' | '400' | '500' | '600' | '700' | '800' | '900';
    letterSpacing: `${number}${Extract<CssLengthUnit, 'px'>}` | `${number}` | 'normal';
    textDecoration: 'none' | 'underline' | 'overline' | 'line-through';
    textTransform: 'none' | 'capitalize' | 'uppercase' | 'lowercase';
}

/**
 * Represents the typography type names available in a theme.
 *
 * @public
 */
type ThemeTypographyTypeName = 'headline1' | 'headline2' | 'headline3' | 'headline4' | 'headline5' | 'headline6' | 'subtitle1' | 'subtitle2' | 'body1' | 'body2' | 'supporting' | 'button' | 'caption' | 'overline';
/**
 * Represents dynamic typography styles.
 *
 * ThemeTypographyTypeName → IThemeTypographyFontType
 *
 * @public
 */
type ThemeTypography = Partial<Record<ThemeTypographyTypeName, Partial<IThemeTypographyFontType>>>;

/**
 * Represents a dynamic theme system.
 *
 * @public
 */
interface ITheme {
    /**
     * Human-readable theme name.
     */
    name: string;
    /**
     * Theme color schemes.
     *
     * ThemeMode → ThemeScheme
     */
    scheme: Readonly<Record<ThemeMode, ThemeScheme>>;
    /**
     * Theme color palettes.
     *
     * ThemeMode → Semantic Color → ThemePalette | CssColor
     */
    palette: Readonly<Record<ThemeMode, ThemeSemantic>>;
    /**
     * Base font family.
     */
    fontFamily: string;
    /**
     * Typography definition.
     */
    typography: ThemeTypography;
    /**
     * Layout definition.
     */
    layout: IThemeLayout;
    /**
     * Elevation definitions.
     */
    elevation: Readonly<Record<string, IThemeElevation>>;
}
/**
 * @public
 */
declare namespace ITheme {
    /**
     * Gets the scheme for the specified mode.
     *
     * @param theme The theme to get the scheme from.
     * @param mode The theme mode.
     * @returns The theme scheme for the specified mode.
     */
    function getScheme(theme: ITheme, mode: ThemeMode): ThemeScheme;
    /**
     * Gets the palette for the specified semantic color and mode.
     *
     * @param theme The theme to get the palette from.
     * @param mode The theme mode.
     * @param semanticColor The semantic color name.
     * @returns The theme palette for the specified semantic color and mode.
     */
    function getPalette(theme: ITheme, mode: ThemeMode, semanticColor: ThemeSemanticName): ThemePalette;
    /**
     * Gets a scheme color for the specified role and mode.
     *
     * @param theme The theme to get the color from.
     * @param mode The theme mode.
     * @param role The scheme role.
     * @returns The CSS color for the specified role and mode.
     */
    function getSchemeColor(theme: ITheme, mode: ThemeMode, role: ThemeSchemeRole): CssColor;
    /**
     * Gets a palette color for the specified semantic color, shade, and mode.
     *
     * @param theme The theme to get the color from.
     * @param mode The theme mode.
     * @param semanticColor The semantic color name.
     * @param shade The shade name.
     * @returns The CSS color for the specified semantic color, shade, and mode.
     */
    function getPaletteColor(theme: ITheme, mode: ThemeMode, semanticColor: ThemeSemanticName, shade: ThemeShadeName): CssColor;
    /**
     * Gets an elevation shadow for the specified key and mode.
     *
     * @param theme The theme to get the elevation from.
     * @param mode The theme mode.
     * @param key The elevation key.
     * @returns The CSS shadow for the specified elevation key and mode.
     */
    function getElevationShadow(theme: ITheme, mode: ThemeMode, key: string): CssShadow;
}

/**
 * @public
 */
interface IThemeMetadata {
    theme: ITheme;
    palettes: Array<string>;
    paletteVariants: Array<string>;
    schemes: Array<string>;
    schemeVariants: Array<string>;
    elevation: Array<string>;
    elevationVariants: Array<string>;
    typographies: Array<string>;
}

declare namespace CosmopolitanTheme {
    const COSMOPOLITAN_THEME: ITheme;
    const COSMOPOLITAN_THEME_PALETTES: string[];
    const COSMOPOLITAN_THEME_PALETTE_VARIANTS: string[];
    const COSMOPOLITAN_THEME_SCHEMES: string[];
    const COSMOPOLITAN_THEME_SCHEME_VARIANTS: string[];
    const COSMOPOLITAN_THEME_ELEVATION: string[];
    const COSMOPOLITAN_THEME_ELEVATION_VARIANTS: string[];
    const COSMOPOLITAN_THEME_TYPOGRAPHY: string[];
    const COSMOPOLITAN_THEME_METADATA: IThemeMetadata;
}

declare namespace JoyTheme {
    const JOY_THEME: ITheme;
    const JOY_THEME_PALETTES: string[];
    const JOY_THEME_PALETTE_VARIANTS: string[];
    const JOY_THEME_SCHEMES: string[];
    const JOY_THEME_SCHEME_VARIANTS: string[];
    const JOY_THEME_ELEVATION: string[];
    const JOY_THEME_ELEVATION_VARIANTS: string[];
    const JOY_THEME_TYPOGRAPHY: string[];
    const JOY_THEME_METADATA: IThemeMetadata;
}

declare namespace MemphisTheme {
    const MEMPHIS_THEME: ITheme;
    const MEMPHIS_THEME_PALETTES: string[];
    const MEMPHIS_THEME_PALETTE_VARIANTS: string[];
    const MEMPHIS_THEME_SCHEMES: string[];
    const MEMPHIS_THEME_SCHEME_VARIANTS: string[];
    const MEMPHIS_THEME_ELEVATION: string[];
    const MEMPHIS_THEME_ELEVATION_VARIANTS: string[];
    const MEMPHIS_THEME_TYPOGRAPHY: string[];
    const MEMPHIS_THEME_METADATA: IThemeMetadata;
}

/**
 * Strategy interface for theme-specific palette and scheme generation.
 *
 * @public
 */
interface IThemeGeneratorStrategy {
    /**
     * Determines whether a color is within the expected luminance range for the given mode.
     *
     * @param color - The color to check
     * @param mode - The color mode (dark or light)
     * @returns True if the color is naturally compatible with the given mode
     */
    isColorInModeSpectrum(color: CssColor, mode: Omit<ThemeMode, 'system'>): boolean;
    /**
     * Adapts a color to be compatible with the opposite mode by inverting its
     * perceptual lightness.
     *
     * @remarks
     * The inversion is symmetric (light ↔ dark), so the target mode does not
     * need to be specified — the result always "flips" into the other spectrum.
     *
     * @param color - The color to adapt
     * @returns The adapted color with inverted lightness
     */
    adaptColorToMode(color: CssColor): CssColor;
    /**
     * Generates a color palette for the theme.
     *
     * @param baseColor - The base color to generate the palette from
     * @param mode - The color mode (dark or light)
     * @returns The generated palette with all shades steps
     */
    generatePalette(baseColor: CssColor, mode: Omit<ThemeMode, 'system'>): Required<ThemePalette>;
    /**
     * Generates a color scheme for the theme.
     *
     * @param baseColor - The base color to generate the scheme from
     * @param mode - The color mode (dark or light)
     * @returns The generated scheme with semantic color roles
     */
    generateScheme(baseColor: CssColor, mode: Omit<ThemeMode, 'system'>): Required<ThemeScheme>;
}

/**
 * Abstract theme generator strategy that operates in the **HSL** (Hue, Saturation, Lightness)
 * color space.
 *
 * @remarks
 * HSL is a cylindrical color model widely used in CSS and web design tooling.
 * Unlike LCH it is not perceptually uniform, but it provides a familiar and
 * lightweight alternative for palette generation.
 *
 * Concrete themes that prefer HSL-based generation extend this class.
 *
 * @public
 * @abstract
 */
declare abstract class HslThemeGeneratorStrategy implements IThemeGeneratorStrategy {
    private static readonly _LIGHTNESS_THRESHOLD;
    /**
     * Determines whether a color naturally belongs to the given mode's HSL lightness range.
     *
     * @remarks
     * A color with HSL lightness > 0.5 is considered "light"; ≤ 0.5 is considered "dark".
     *
     * @public
     * @param color - The color to check
     * @param mode - The target color mode ('dark' | 'light')
     * @returns `true` if the color is naturally compatible with the given mode
     */
    isColorInModeSpectrum(color: CssColor, mode: 'dark' | 'light'): boolean;
    /**
     * Adapts a color to the opposite mode by symmetrically inverting its HSL lightness
     * (`L → 1 - L`) while preserving hue and saturation.
     *
     * @remarks
     * The inversion is symmetric: a light color becomes dark and vice-versa, regardless
     * of the direction. Therefore no target mode parameter is required.
     *
     * The inverted lightness is clamped to [0.05, 0.95] to avoid pure black / pure white.
     * Subclasses may override this method for theme-specific post-processing.
     *
     * @public
     * @param color - The color to adapt
     * @returns The adapted color with inverted lightness
     */
    adaptColorToMode(color: CssColor): CssColor;
    /**
     * Generates a palette of shades based on a base/accent color using HSL interpolation.
     *
     * @public
     * @param baseColor - The base/accent color (e.g. "#3498db")
     * @param mode - 'light' or 'dark' mode: determines how light or dark the palette extremes are.
     * @returns The generated theme palette with shade steps 0–900
     */
    generatePalette(baseColor: CssColor, mode: 'light' | 'dark'): Required<ThemePalette>;
    /**
     * Generates a semantic color scheme for UI usage, based on the generated palette.
     *
     * @public
     * @param baseColor - The base/accent color
     * @param mode - 'light' or 'dark'
     * @returns The generated theme scheme with semantic color roles
     */
    generateScheme(baseColor: CssColor, mode: 'light' | 'dark'): Required<ThemeScheme>;
}

/**
 * Abstract theme generator strategy that operates in the **LCH** (Luminance, Chroma, Hue)
 * perceptual color space.
 *
 * @remarks
 * LCH is a perceptually uniform color space where `L*` (lightness 0–100) maps linearly
 * to how humans perceive brightness. This makes it ideal for reliable mode detection
 * and color adaptation.
 *
 * Concrete themes (Joy, Memphis, Cosmopolitan, …) extend this class to inherit
 * the shared color-science logic and only override behavior where their visual
 * language demands it.
 *
 * @public
 * @abstract
 */
declare abstract class LchThemeGeneratorStrategy implements IThemeGeneratorStrategy {
    private static readonly _LUMINANCE_THRESHOLD;
    /**
     * Determines whether a color naturally belongs to the given mode's luminance range.
     *
     * @remarks
     * Uses WCAG relative luminance (0 = black, 1 = white).
     * A color with luminance > 0.5 is considered "light"; ≤ 0.5 is considered "dark".
     *
     * @public
     * @param color - The color to check
     * @param mode - The target color mode ('dark' | 'light')
     * @returns `true` if the color is naturally compatible with the given mode
     */
    isColorInModeSpectrum(color: CssColor, mode: 'dark' | 'light'): boolean;
    /**
     * Adapts a color to the opposite mode by symmetrically inverting its perceptual
     * lightness in the LCH color space (`L* → 100 - L*`) while preserving hue and chroma.
     *
     * @remarks
     * The inversion is symmetric: a light color becomes dark and vice-versa, regardless
     * of the direction. Therefore no target mode parameter is required.
     *
     * The inverted lightness is clamped to [5, 95] to avoid pure black / pure white,
     * which cannot carry chromatic information.
     * Subclasses may override this method to apply theme-specific post-processing
     * (e.g., chroma reduction for muted palettes).
     *
     * @public
     * @param color - The color to adapt
     * @returns The adapted color with inverted lightness
     */
    adaptColorToMode(color: CssColor): CssColor;
    /**
     * Generates a color palette from a base color for the given mode.
     *
     * @public
     * @param baseColor - The base/accent color
     * @param mode - 'light' or 'dark' mode
     * @returns The generated theme palette with shade steps 0–900
     */
    generatePalette(baseColor: CssColor, mode: 'dark' | 'light'): Required<ThemePalette>;
    /**
     * Generates a semantic color scheme based on a base color and mode.
     *
     * @public
     * @param baseColor - The base/accent color
     * @param mode - 'light' or 'dark' mode
     * @returns The generated theme scheme with semantic color roles
     */
    generateScheme(baseColor: CssColor, mode: 'dark' | 'light'): Required<ThemeScheme>;
}

/**
 * Factory function type for creating theme generator strategies.
 *
 * @public
 */
type ThemeGeneratorFactoryFn = () => IThemeGeneratorStrategy;

/**
 * Cosmopolitan theme generator strategy.
 *
 * @remarks
 * Extends {@link LchThemeGeneratorStrategy} with a muted, desaturated aesthetic
 * that defines the Cosmopolitan visual language. Overrides only where the default
 * LCH behavior needs adjustment; all other behavior is inherited.
 *
 * @public
 */
declare class CosmopolitanThemeGeneratorStrategy extends LchThemeGeneratorStrategy {
    private static readonly _CHROMA_REDUCTION_FACTOR;
    /**
     * Adapts a color to the target mode by inverting its perceptual lightness (LCH L*)
     * with a slight chroma reduction for the Cosmopolitan's muted aesthetic.
     *
     * @override
     * @public
     * @param color - The color to adapt
     * @returns The adapted color with inverted lightness and reduced chroma
     */
    adaptColorToMode(color: CssColor): CssColor;
    /**
     * Generates a color palette with Cosmopolitan-specific dark-mode mixing.
     *
     * @remarks
     * Light mode uses the standard LCH base class implementation.
     * Dark mode uses a simplified three-anchor approach (steps 0, 100, 500)
     * to produce the flat, muted dark palette that defines Cosmopolitan.
     *
     * @override
     * @public
     * @param baseColor - The base/accent color
     * @param mode - 'light' or 'dark' mode
     * @returns The generated theme palette with shade steps 0–900
     */
    generatePalette(baseColor: CssColor, mode: 'dark' | 'light'): Required<ThemePalette>;
}
/**
 * Generates a Cosmopolitan theme generator strategy.
 *
 * @public
 */
declare function createCosmopolitanTheme(): ThemeGeneratorFactoryFn;

/**
 * Joy theme generator strategy.
 *
 * @remarks
 * Extends {@link LchThemeGeneratorStrategy} without customization.
 *
 * @public
 */
declare class JoyThemeGeneratorStrategy extends LchThemeGeneratorStrategy {
}
/**
 * Generates a Joy theme generator strategy.
 *
 * @public
 */
declare function createJoyTheme(): ThemeGeneratorFactoryFn;

/**
 * Memphis theme generator strategy.
 *
 * @remarks
 * Extends {@link LchThemeGeneratorStrategy} without customization.
 *
 * @public
 */
declare class MemphisThemeGeneratorStrategy extends LchThemeGeneratorStrategy {
}
/**
 * Generates a Memphis theme generator strategy.
 *
 * @public
 */
declare function createMemphisTheme(): ThemeGeneratorFactoryFn;

/**
 * Central facade for generating theme palettes and color schemes.
 *
 * @remarks
 * Accepts any base color with any mode and autonomously ensures compatibility
 * before delegating to the resolved {@link IThemeGeneratorStrategy}.
 * The `'system'` mode is resolved to `'dark'` or `'light'` via the
 * {@link IPlatformAdapter}.
 *
 * @public
 */
declare class ThemeGenerator {
    private readonly _strategies;
    private readonly _platformAdapter;
    /**
     * @public
     * @param platformAdapter - Optional platform adapter. Auto-detects if not provided.
     */
    constructor(platformAdapter?: IPlatformAdapter);
    /**
     * Generates a complete theme palette (shades 0–900) for the given theme.
     *
     * @remarks
     * 1. If `mode` is `'system'`, it is resolved to `'dark'` or `'light'` via the
     *    platform adapter's `prefers-color-scheme` media query.
     * 2. The base color is forwarded as-is to the theme-specific strategy which
     *    produces 11 shade steps from lightest (0) to darkest (900).
     *
     * No automatic color adaptation is performed. Callers who need mode-compatible
     * colors can use {@link IThemeGeneratorStrategy.isColorInModeSpectrum} and
     * {@link IThemeGeneratorStrategy.adaptColorToMode} explicitly before calling
     * this method.
     *
     * @public
     * @param themeName - The name of the theme (`'joy'`, `'memphis'`, `'cosmopolitan'`).
     * @param baseColor - The base accent color (any valid CSS color value).
     * @param mode - The target mode (`'dark'`, `'light'`, or `'system'`).
     * @returns A fully populated palette with shade keys `0`–`900`.
     * @throws Error if `themeName` is not a registered theme.
     */
    generatePalette(themeName: string, baseColor: CssColor, mode: ThemeMode): Required<ThemePalette>;
    /**
     * Generates a semantic color scheme (surface, foreground, highlight, …) for the given theme.
     *
     * @remarks
     * 1. If `mode` is `'system'`, it is resolved to `'dark'` or `'light'` via the
     *    platform adapter's `prefers-color-scheme` media query.
     * 2. The base color is forwarded as-is to the theme-specific strategy which
     *    maps it to semantic roles such as `surface`, `foreground`, `highlight`,
     *    `contrast`, `disabled`, etc.
     *
     * No automatic color adaptation is performed. Callers who need mode-compatible
     * colors can use {@link IThemeGeneratorStrategy.isColorInModeSpectrum} and
     * {@link IThemeGeneratorStrategy.adaptColorToMode} explicitly before calling
     * this method.
     *
     * @public
     * @param themeName - The name of the theme (`'joy'`, `'memphis'`, `'cosmopolitan'`).
     * @param baseColor - The base background color (any valid CSS color value).
     * @param mode - The target mode (`'dark'`, `'light'`, or `'system'`).
     * @returns A fully populated scheme with all semantic color roles.
     * @throws Error if `themeName` is not a registered theme.
     */
    generateScheme(themeName: string, baseColor: CssColor, mode: ThemeMode): Required<ThemeScheme>;
    /**
     * Resolves the theme mode, converting 'system' to 'dark' or 'light' based on platform settings.
     *
     * @private
     * @param mode The theme mode to resolve.
     * @returns The resolved theme mode.
     */
    private resolveMode;
    /**
     * Gets the theme generator strategy for the specified theme name.
     *
     * @private
     * @param themeName The name of the theme ('joy', 'memphis', 'cosmopolitan').
     * @returns The theme generator strategy.
     */
    private getStrategy;
}
/**
 * Global service locator for the singleton {@link ThemeGenerator} instance.
 *
 * @remarks
 * A default instance is created automatically at module load time.
 * Call {@link ThemeGeneratorServiceLocator.set | set} to replace it (e.g. in tests
 * or SSR environments where a custom {@link IPlatformAdapter} is needed).
 *
 * @public
 */
declare class ThemeGeneratorServiceLocator {
    private static _current;
    static get current(): ThemeGenerator;
    static isSet(): boolean;
    static set(current: ThemeGenerator): void;
}

/**
 * Reactive observer that applies and tracks the active theme on the document.
 *
 * @remarks
 * Manages the `theme` and `theme-mode` document attributes and emits events
 * when either changes. The `'system'` mode is resolved via the
 * {@link IPlatformAdapter}.
 *
 * @public
 */
declare class ThemeObserver {
    private readonly _themeChanged;
    private readonly _themeModeChanged;
    private readonly _platformAdapter;
    private _currentTheme;
    private _currentThemeMode;
    private _unsubscribe?;
    /**
     * Constructs a new instance of the `ThemeObserver` class.
     *
     * @param platformAdapter - Optional platform adapter. Auto-detects if not provided.
     * @public
     */
    constructor(platformAdapter?: IPlatformAdapter);
    /**
     * Fires when the theme changes.
     *
     * @public
     * @readonly
     */
    get themeChanged(): IEventEmitter<string>;
    /**
     * Fires when the theme mode changes.
     *
     * @public
     * @readonly
     */
    get themeModeChanged(): IEventEmitter<ThemeMode>;
    /**
     * Applies the given theme and theme mode to the document.
     *
     * @public
     * @param theme - The theme to apply (joy, cosmopolitan or memphis).
     * @param themeMode - The theme mode to apply.
     */
    applyTheme(theme: string, themeMode: ThemeModeWithSystem): void;
    /**
     * Stops observing document attribute changes and releases the underlying listener.
     *
     * @remarks
     * Safe to call multiple times — subsequent calls are no-ops.
     *
     * @public
     */
    dispose(): void;
    private observe;
}
/**
 * Global service locator for the singleton {@link ThemeObserver} instance.
 *
 * @remarks
 * A default instance is created automatically at module load time.
 * Call {@link ThemeObserverServiceLocator.set | set} to replace it (e.g. in tests
 * or SSR environments where a custom {@link IPlatformAdapter} is needed).
 *
 * @public
 */
declare class ThemeObserverServiceLocator {
    private static _current;
    static get current(): ThemeObserver;
    static isSet(): boolean;
    static set(current: ThemeObserver): void;
}

/**
 * @public
 */
type CssAspectRatio = 'auto' | `${number}` | `${number}/${number}`;
/**
 * @public
 */
declare namespace CssAspectRatio {
    /**
     * @public
     */
    function isCssAspectRatio(value: unknown): value is CssAspectRatio;
}

/**
 * @public
 */
type CssTimeUnit = 's' | 'ms';
/**
 * @public
 */
type CssTime = `${string}${CssTimeUnit}` | number | 0;
/**
 * @public
 */
declare namespace CssTime {
    /**
     * @public
     */
    function isCssTime(value: unknown): value is CssTime;
}

export { BrowserPlatformAdapter, Colors, CosmopolitanTheme, CosmopolitanThemeGeneratorStrategy, CssAspectRatio, CssColor, type CssHEXColor, CssLength, type CssLengthUnit, type CssNameColor, type CssNumber, type CssRGBAColor, type CssRGBColor, CssShadow, type CssShadowSingle, CssTime, type CssTimeUnit, HslThemeGeneratorStrategy, type IPlatformAdapter, ITheme, type IThemeElevation, type IThemeGeneratorStrategy, type IThemeLayout, type IThemeMetadata, type IThemeTypographyFontType, JoyTheme, JoyThemeGeneratorStrategy, LchThemeGeneratorStrategy, MemphisTheme, MemphisThemeGeneratorStrategy, NodePlatformAdapter, PlatformAdapterFactory, THEME_MODES, ThemeGenerator, ThemeGeneratorServiceLocator, type ThemeMode, ThemeObserver, ThemeObserverServiceLocator, ThemePalette, type ThemeRoleName, ThemeScheme, type ThemeSchemeRole, type ThemeSemantic, type ThemeSemanticName, type ThemeShadeName, type ThemeStateName, type ThemeTypography, type ThemeTypographyTypeName, createCosmopolitanTheme, createJoyTheme, createMemphisTheme };