@breadstone/mosaik-themes 0.0.230 → 0.0.232

package/index.d.ts

@@ -1,5 +1,200 @@
 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
  */
@@ -287,7 +482,7 @@ interface IThemeTypographyFontType {
  *
  * @public
  */
-type ThemeTypographyTypeName = 'headline1' | 'headline2' | 'headline3' | 'headline4' | 'headline5' | 'headline6' | 'subtitle1' | 'subtitle2' | 'body1' | 'body2' | 'button' | 'caption' | 'overline';
+type ThemeTypographyTypeName = 'headline1' | 'headline2' | 'headline3' | 'headline4' | 'headline5' | 'headline6' | 'subtitle1' | 'subtitle2' | 'body1' | 'body2' | 'supporting' | 'button' | 'caption' | 'overline';
 /**
  * Represents dynamic typography styles.
  *
@@ -401,6 +596,18 @@ interface IThemeMetadata {
     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[];
@@ -425,209 +632,181 @@ declare namespace MemphisTheme {
     const MEMPHIS_THEME_METADATA: IThemeMetadata;
 }
 
-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;
-}
-
-/**
- * @public
- */
-type CssAspectRatio = 'auto' | `${number}` | `${number}/${number}`;
 /**
+ * Strategy interface for theme-specific palette and scheme generation.
+ *
  * @public
  */
-declare namespace CssAspectRatio {
+interface IThemeGeneratorStrategy {
     /**
-     * @public
+     * 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
      */
-    function isCssAspectRatio(value: unknown): value is CssAspectRatio;
+    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
  */
-type CssTimeUnit = 's' | 'ms';
-/**
- * @public
- */
-type CssTime = `${string}${CssTimeUnit}` | number | 0;
-/**
- * @public
- */
-declare namespace CssTime {
+declare abstract class HslThemeGeneratorStrategy implements IThemeGeneratorStrategy {
+    private static readonly _LIGHTNESS_THRESHOLD;
     /**
-     * @public
-     */
-    function isCssTime(value: unknown): value is CssTime;
-}
-
-/**
- * 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;
-}
-
-/**
- * Observer for applying themes.
- *
- * @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.
+     * 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".
      *
-     * @param platformAdapter - Optional platform adapter. Auto-detects if not provided.
      * @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
      */
-    constructor(platformAdapter?: IPlatformAdapter);
+    isColorInModeSpectrum(color: CssColor, mode: 'dark' | 'light'): boolean;
     /**
-     * Fires when the theme changes.
+     * 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
-     * @readonly
+     * @param color - The color to adapt
+     * @returns The adapted color with inverted lightness
      */
-    get themeChanged(): IEventEmitter<string>;
+    adaptColorToMode(color: CssColor): CssColor;
     /**
-     * Fires when the theme mode changes.
+     * Generates a palette of shades based on a base/accent color using HSL interpolation.
      *
      * @public
-     * @readonly
+     * @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
      */
-    get themeModeChanged(): IEventEmitter<ThemeMode>;
+    generatePalette(baseColor: CssColor, mode: 'light' | 'dark'): Required<ThemePalette>;
     /**
-     * Applies the given theme and theme mode to the document.
+     * Generates a semantic color scheme for UI usage, based on the generated palette.
      *
      * @public
-     * @param theme - The theme to apply (joy, cosmopolitan or memphis).
-     * @param themeMode - The theme mode to apply.
+     * @param baseColor - The base/accent color
+     * @param mode - 'light' or 'dark'
+     * @returns The generated theme scheme with semantic color roles
      */
-    applyTheme(theme: string, themeMode: ThemeModeWithSystem): void;
-    dispose(): void;
-    private observe;
-}
-/**
- * @public
- */
-declare class ThemeObserverServiceLocator {
-    private static _current;
-    static get current(): ThemeObserver;
-    static isSet(): boolean;
-    static set(current: ThemeObserver): void;
+    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 class ThemeGenerator {
-    private readonly _strategies;
-    private readonly _platformAdapter;
-    /**
-     * @public
-     * @param platformAdapter - Optional platform adapter. Auto-detects if not provided.
-     */
-    constructor(platformAdapter?: IPlatformAdapter);
+declare abstract class LchThemeGeneratorStrategy implements IThemeGeneratorStrategy {
+    private static readonly _LUMINANCE_THRESHOLD;
     /**
-     * Generates a theme palette.
+     * Determines whether a color naturally belongs to the given mode's luminance range.
      *
-     * @public
-     * @param themeName The name of the theme.
-     * @param baseColor The base color (typically a 500 level shade).
-     * @param mode The theme mode ('dark', 'light', or 'system').
-     * @returns The generated theme palette.
-     */
-    generatePalette(themeName: string, baseColor: CssColor, mode: ThemeMode): ThemePalette;
-    /**
-     * Generates a theme scheme.
+     * @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 themeName The name of the theme.
-     * @param baseColor The base color (typically a background level shade).
-     * @param mode The theme mode ('dark', 'light', or 'system').
-     * @returns The generated theme scheme.
+     * @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
      */
-    generateScheme(themeName: string, baseColor: CssColor, mode: ThemeMode): ThemeScheme;
+    isColorInModeSpectrum(color: CssColor, mode: 'dark' | 'light'): boolean;
     /**
-     * Resolves the theme mode, converting 'system' to 'dark' or 'light' based on platform settings.
+     * 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.
      *
-     * @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.
+     * @remarks
+     * The inversion is symmetric: a light color becomes dark and vice-versa, regardless
+     * of the direction. Therefore no target mode parameter is required.
      *
-     * @private
-     * @param themeName The name of the theme.
-     * @returns The theme generator strategy.
+     * 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
      */
-    private getStrategy;
-}
-/**
- * @public
- */
-declare class ThemeGeneratorServiceLocator {
-    private static _current;
-    static get current(): ThemeGenerator;
-    static isSet(): boolean;
-    static set(current: ThemeGenerator): void;
-}
-
-/**
- * Strategy interface for theme-specific palette and scheme generation.
- *
- * @public
- */
-interface IThemeGeneratorStrategy {
+    adaptColorToMode(color: CssColor): CssColor;
     /**
-     * Generates a color palette for the theme.
+     * Generates a color palette from a base color for the given mode.
      *
-     * @param baseColor - The base color to generate the palette from
-     * @param mode - The color mode (dark or light)
-     * @returns The generated palette
+     * @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: Omit<ThemeMode, 'system'>): ThemePalette;
+    generatePalette(baseColor: CssColor, mode: 'dark' | 'light'): Required<ThemePalette>;
     /**
-     * Generates a color scheme for the theme.
+     * Generates a semantic color scheme based on a base color and mode.
      *
-     * @param baseColor - The base color to generate the scheme from
-     * @param mode - The color mode (dark or light)
-     * @returns The generated scheme
+     * @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: Omit<ThemeMode, 'system'>): ThemeScheme;
+    generateScheme(baseColor: CssColor, mode: 'dark' | 'light'): Required<ThemeScheme>;
 }
 
 /**
@@ -638,49 +817,59 @@ interface IThemeGeneratorStrategy {
 type ThemeGeneratorFactoryFn = () => IThemeGeneratorStrategy;
 
 /**
- * Material Design theme generator strategy.
+ * 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 MaterialThemeGeneratorStrategy implements IThemeGeneratorStrategy {
-    constructor();
+declare class CosmopolitanThemeGeneratorStrategy extends LchThemeGeneratorStrategy {
+    private static readonly _CHROMA_REDUCTION_FACTOR;
     /**
-     * Generates a color palette for the Material theme.
+     * 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 baseColor The base/accent color.
-     * @param mode 'light' or 'dark' mode.
-     * @returns The generated theme palette.
+     * @param color - The color to adapt
+     * @returns The adapted color with inverted lightness and reduced chroma
      */
-    generatePalette(baseColor: CssColor, mode: 'dark' | 'light'): ThemePalette;
+    adaptColorToMode(color: CssColor): CssColor;
     /**
-     * Generates a semantic color scheme for Material theme usage, based on the generated palette.
+     * 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 scheme.
+     * @param baseColor - The base/accent color
+     * @param mode - 'light' or 'dark' mode
+     * @returns The generated theme palette with shade steps 0–900
      */
-    generateScheme(baseColor: CssColor, mode: 'dark' | 'light'): ThemeScheme;
+    generatePalette(baseColor: CssColor, mode: 'dark' | 'light'): Required<ThemePalette>;
 }
 /**
- * Generates a Material theme generator strategy.
+ * Generates a Cosmopolitan theme generator strategy.
  *
  * @public
  */
-declare function createMaterialTheme(): ThemeGeneratorFactoryFn;
+declare function createCosmopolitanTheme(): ThemeGeneratorFactoryFn;
 
 /**
- * Joy UI theme generator strategy.
- * Uses the same generation logic as Material Design.
+ * Joy theme generator strategy.
+ *
+ * @remarks
+ * Extends {@link LchThemeGeneratorStrategy} without customization.
  *
  * @public
  */
-declare class JoyThemeGeneratorStrategy implements IThemeGeneratorStrategy {
-    private readonly _materialStrategy;
-    constructor();
-    generatePalette(baseColor: CssColor, mode: 'dark' | 'light'): ThemePalette;
-    generateScheme(baseColor: CssColor, mode: 'dark' | 'light'): ThemeScheme;
+declare class JoyThemeGeneratorStrategy extends LchThemeGeneratorStrategy {
 }
 /**
  * Generates a Joy theme generator strategy.
@@ -691,15 +880,13 @@ declare function createJoyTheme(): ThemeGeneratorFactoryFn;
 
 /**
  * Memphis theme generator strategy.
- * Uses the same generation logic as Material Design.
+ *
+ * @remarks
+ * Extends {@link LchThemeGeneratorStrategy} without customization.
  *
  * @public
  */
-declare class MemphisThemeGeneratorStrategy implements IThemeGeneratorStrategy {
-    private readonly _materialStrategy;
-    constructor();
-    generatePalette(baseColor: CssColor, mode: 'dark' | 'light'): ThemePalette;
-    generateScheme(baseColor: CssColor, mode: 'dark' | 'light'): ThemeScheme;
+declare class MemphisThemeGeneratorStrategy extends LchThemeGeneratorStrategy {
 }
 /**
  * Generates a Memphis theme generator strategy.
@@ -709,241 +896,207 @@ declare class MemphisThemeGeneratorStrategy implements IThemeGeneratorStrategy {
 declare function createMemphisTheme(): ThemeGeneratorFactoryFn;
 
 /**
- * Cosmopolitan theme generator strategy.
+ * Central facade for generating theme palettes and color schemes.
  *
- * @public
- */
-declare class CosmopolitanThemeGeneratorStrategy implements IThemeGeneratorStrategy {
-    private readonly _materialStrategy;
-    constructor();
-    generatePalette(baseColor: CssColor, mode: 'dark' | 'light'): ThemePalette;
-    generateScheme(baseColor: CssColor, mode: 'dark' | 'light'): ThemeScheme;
-}
-/**
- * Generates a Cosmopolitan theme generator strategy.
+ * @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 function createCosmopolitanTheme(): ThemeGeneratorFactoryFn;
-
-/**
- * Tailwind-like strategy.
- *
- * Generates a color palette with the following shade steps:
- * 50, 100, 200, 300, 400, 500, 600, 700, 800, 900.
- *
- * Each returned color is a hex string (CssColor).
- */
-declare class TailwindThemeGeneratorStrategy implements IThemeGeneratorStrategy {
+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 palette of shades based on a base/accent color.
+     * Generates a complete theme palette (shades 0–900) for the given theme.
      *
-     * @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 An IThemePalette mapping each shade step to a hex color.
+     * @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.
      *
-     * Example (light mode, baseColor = blue-ish):
-     * {
-     *   "50":  "#f5faff",
-     *   "100": "#e1f3ff",
-     *   ...
-     *   "500": "#3498db",
-     *   ...
-     *   "900": "#0a2d4b"
-     * }
+     * @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(baseColor: CssColor, mode: 'light' | 'dark'): ThemePalette;
+    generatePalette(themeName: string, baseColor: CssColor, mode: ThemeMode): Required<ThemePalette>;
     /**
-     * Generates a semantic color scheme for UI usage, based on the generated palette.
+     * Generates a semantic color scheme (surface, foreground, highlight, …) for the given theme.
      *
-     * @param baseColor - The base/accent color
-     * @param mode - 'light' or 'dark'
-     * @returns An scheme with semantic color roles.
+     * @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.
      *
-     * Returned keys:
-     * - background  → shade "50"
-     * - foreground  → shade "900"
-     * - primary     → shade "500"
-     * - accent      → shade "700"
-     * - muted       → shade "300"
+     * @private
+     * @param themeName The name of the theme ('joy', 'memphis', 'cosmopolitan').
+     * @returns The theme generator strategy.
      */
-    generateScheme(baseColor: CssColor, mode: 'light' | 'dark'): ThemeScheme;
+    private getStrategy;
 }
 /**
- * Generates a Tailwind theme generator strategy.
+ * Global service locator for the singleton {@link ThemeGenerator} instance.
  *
- * @public
- */
-declare function createTailwindTheme(): ThemeGeneratorFactoryFn;
-
-/**
- * Browser implementation of the platform adapter.
- * Uses native DOM APIs (window, document, MutationObserver).
+ * @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 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;
+declare class ThemeGeneratorServiceLocator {
+    private static _current;
+    static get current(): ThemeGenerator;
+    static isSet(): boolean;
+    static set(current: ThemeGenerator): void;
 }
 
 /**
- * Node.js implementation of the platform adapter.
- * No-op implementation that doesn't crash but does nothing.
+ * Reactive observer that applies and tracks the active theme on the document.
  *
- * @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.
+ * @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 PlatformAdapterFactory {
+declare class ThemeObserver {
+    private readonly _themeChanged;
+    private readonly _themeModeChanged;
+    private readonly _platformAdapter;
+    private _currentTheme;
+    private _currentThemeMode;
+    private _unsubscribe?;
     /**
-     * Creates the appropriate platform adapter based on the current environment.
-     * Automatically detects if running in browser or Node.js.
+     * Constructs a new instance of the `ThemeObserver` class.
      *
+     * @param platformAdapter - Optional platform adapter. Auto-detects if not provided.
      * @public
      */
-    static create(): IPlatformAdapter;
+    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;
 }
-
-/**
- * @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°).
+ * 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).
  *
- * @param baseHex - The base color in hex format.
- * @returns An array of two split-complementary colors.
  * @public
  */
-declare function generateSplitComplementaryColors(baseHex: string): [string, string];
+declare class ThemeObserverServiceLocator {
+    private static _current;
+    static get current(): ThemeObserver;
+    static isSet(): boolean;
+    static set(current: ThemeObserver): void;
+}
+
 /**
- * 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;
+type CssAspectRatio = 'auto' | `${number}` | `${number}/${number}`;
 /**
- * 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;
+declare namespace CssAspectRatio {
+    /**
+     * @public
+     */
+    function isCssAspectRatio(value: unknown): value is CssAspectRatio;
+}
 
 /**
- * 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];
+type CssTimeUnit = 's' | 'ms';
 /**
- * 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;
+type CssTime = `${string}${CssTimeUnit}` | number | 0;
 /**
- * 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;
+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, type IPlatformAdapter, ITheme, type IThemeElevation, type IThemeGeneratorStrategy, type IThemeLayout, type IThemeMetadata, type IThemeTypographyFontType, JoyTheme, JoyThemeGeneratorStrategy, MaterialThemeGeneratorStrategy, MemphisTheme, MemphisThemeGeneratorStrategy, NodePlatformAdapter, PlatformAdapterFactory, THEME_MODES, TailwindThemeGeneratorStrategy, 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, createMaterialTheme, createMemphisTheme, createTailwindTheme };
+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 };