@breadstone/mosaik-themes 0.0.205 → 0.0.209

package/index.d.ts

@@ -31,33 +31,53 @@ declare namespace CssColor {
 }
 
 /**
- * Represents a dynamic color scheme.
+ * Represents the roles available in a theme scheme.
  *
  * @public
  */
-interface IThemeScheme {
-    [key: string]: CssColor;
+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;
 }
 
+/**
+ * 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
  */
-interface IThemePalette {
-    [key: string]: CssColor;
-}
+type ThemePalette = Partial<Record<ThemeShadeName, CssColor>>;
 /**
  * @public
  */
-declare namespace IThemePalette {
+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 IThemePalette;
+    function isThemePalette(value: unknown): value is ThemePalette;
 }
 
 /**
@@ -67,7 +87,11 @@ type CssLengthUnit = 'em' | 'ex' | 'ch' | 'rem' | 'vh' | 'vw' | 'vmin' | 'vmax'
 /**
  * @public
  */
-type CssLength = `${number}${CssLengthUnit | '%'}` | number | 'auto';
+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.
@@ -187,14 +211,54 @@ interface IThemeTypographyFontType {
     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' | 'button' | 'caption' | 'overline';
 /**
  * Represents dynamic typography styles.
  *
+ * ThemeTypographyTypeName → IThemeTypographyFontType
+ *
  * @public
  */
-interface IThemeTypography {
-    [key: string]: IThemeTypographyFontType;
-}
+type ThemeTypography = Partial<Record<ThemeTypographyTypeName, Partial<IThemeTypographyFontType>>>;
+
+/**
+ * Theme mode.
+ *
+ * @public
+ */
+type ThemeMode = 'dark' | 'light';
+/**
+ * Theme mode with system option.
+ *
+ * @public
+ */
+type ThemeModeWithSystem = ThemeMode | 'system';
+
+/**
+ * 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 a dynamic theme system.
@@ -202,22 +266,47 @@ interface IThemeTypography {
  * @public
  */
 interface ITheme {
+    /**
+     * Human-readable theme name.
+     */
     name: string;
-    scheme: Record<string, IThemeScheme>;
-    palette: Record<string, Record<string, IThemePalette | CssColor>>;
+    /**
+     * 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: IThemeTypography;
+    /**
+     * Typography definition.
+     */
+    typography: ThemeTypography;
+    /**
+     * Layout definition.
+     */
     layout: IThemeLayout;
-    elevation: Record<string, IThemeElevation>;
+    /**
+     * Elevation definitions.
+     */
+    elevation: Readonly<Record<string, IThemeElevation>>;
 }
 /**
  * @public
  */
 declare namespace ITheme {
-    function getScheme(theme: ITheme, mode: string): IThemeScheme;
-    function getSchemeColor(theme: ITheme, mode: string, key: string): CssColor;
-    function getPalette(theme: ITheme, mode: string, palette: string): IThemePalette;
-    function getPaletteColor(theme: ITheme, mode: string, palette: string, key: string): CssColor;
+    function getScheme(theme: ITheme, mode: ThemeMode): ThemeScheme;
+    function getSchemeColor(theme: ITheme, mode: ThemeMode, role: ThemeSchemeRole): CssColor;
+    function getPalette(theme: ITheme, mode: ThemeMode, semanticColor: ThemeSemanticName): ThemePalette;
+    function getPaletteColor(theme: ITheme, mode: ThemeMode, semanticColor: ThemeSemanticName, shade: ThemeShadeName): CssColor;
 }
 
 /**
@@ -234,17 +323,6 @@ interface IThemeMetadata {
     typographies: Array<string>;
 }
 
-declare namespace BootstrapTheme {
-    const BOOTSTRAP_THEME: ITheme;
-    const BOOTSTRAP_THEME_PALETTES: string[];
-    const BOOTSTRAP_THEME_PALETTE_VARIANTS: string[];
-    const BOOTSTRAP_THEME_SCHEMES: string[];
-    const BOOTSTRAP_THEME_SCHEME_VARIANTS: string[];
-    const BOOTSTRAP_THEME_ELEVATION: string[];
-    const BOOTSTRAP_THEME_ELEVATION_VARIANTS: string[];
-    const BOOTSTRAP_THEME_METADATA: IThemeMetadata;
-}
-
 declare namespace JoyTheme {
     const JOY_THEME: ITheme;
     const JOY_THEME_PALETTES: string[];
@@ -335,15 +413,9 @@ interface IPlatformAdapter {
     /**
      * Observes changes to document element attributes.
      */
-    observeDocumentAttributes(attributes: string[], callback: (attributeName: string, newValue: string | null) => void): () => void;
+    observeDocumentAttributes(attributes: Array<string>, callback: (attributeName: string, newValue: string | null) => void): () => void;
 }
 
-/**
- * Theme mode.
- *
- * @public
- */
-type ThemeMode = 'system' | 'dark' | 'light';
 /**
  * Observer for applying themes.
  *
@@ -377,7 +449,14 @@ declare class ThemeObserver {
      * @readonly
      */
     get themeModeChanged(): IEventEmitter<ThemeMode>;
-    applyTheme(theme: string, themeMode: ThemeMode): void;
+    /**
+     * 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;
     dispose(): void;
     private observe;
 }
@@ -398,13 +477,45 @@ declare class ThemeGenerator {
     private readonly _strategies;
     private readonly _platformAdapter;
     /**
-     * @param platformAdapter - Optional platform adapter. Auto-detects if not provided.
      * @public
+     * @param platformAdapter - Optional platform adapter. Auto-detects if not provided.
      */
     constructor(platformAdapter?: IPlatformAdapter);
-    generatePalette(theme: ITheme, baseColor: CssColor, mode: 'dark' | 'light' | 'system'): IThemePalette;
-    generateScheme(theme: ITheme, baseColor: CssColor, mode: 'dark' | 'light' | 'system'): IThemeScheme;
+    /**
+     * Generates a theme palette.
+     *
+     * @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.
+     *
+     * @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.
+     */
+    generateScheme(themeName: string, baseColor: CssColor, mode: ThemeMode): 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.
+     * @returns The theme generator strategy.
+     */
     private getStrategy;
 }
 /**
@@ -430,7 +541,7 @@ interface IThemeGeneratorStrategy {
      * @param mode - The color mode (dark or light)
      * @returns The generated palette
      */
-    generatePalette(baseColor: CssColor, mode: 'dark' | 'light'): IThemePalette;
+    generatePalette(baseColor: CssColor, mode: Omit<ThemeMode, 'system'>): ThemePalette;
     /**
      * Generates a color scheme for the theme.
      *
@@ -438,7 +549,7 @@ interface IThemeGeneratorStrategy {
      * @param mode - The color mode (dark or light)
      * @returns The generated scheme
      */
-    generateScheme(baseColor: CssColor, mode: 'dark' | 'light'): IThemeScheme;
+    generateScheme(baseColor: CssColor, mode: Omit<ThemeMode, 'system'>): ThemeScheme;
 }
 
 /**
@@ -455,8 +566,24 @@ type ThemeGeneratorFactoryFn = () => IThemeGeneratorStrategy;
  */
 declare class MaterialThemeGeneratorStrategy implements IThemeGeneratorStrategy {
     constructor();
-    generatePalette(baseColor: CssColor, mode: 'dark' | 'light'): IThemePalette;
-    generateScheme(baseColor: CssColor, mode: 'dark' | 'light'): IThemeScheme;
+    /**
+     * Generates a color palette for the Material theme.
+     *
+     * @public
+     * @param baseColor The base/accent color.
+     * @param mode 'light' or 'dark' mode.
+     * @returns The generated theme palette.
+     */
+    generatePalette(baseColor: CssColor, mode: 'dark' | 'light'): ThemePalette;
+    /**
+     * Generates a semantic color scheme for Material theme usage, based on the generated palette.
+     *
+     * @public
+     * @param baseColor The base/accent color.
+     * @param mode 'light' or 'dark' mode.
+     * @returns The generated theme scheme.
+     */
+    generateScheme(baseColor: CssColor, mode: 'dark' | 'light'): ThemeScheme;
 }
 /**
  * Generates a Material theme generator strategy.
@@ -474,8 +601,8 @@ declare function createMaterialTheme(): ThemeGeneratorFactoryFn;
 declare class JoyThemeGeneratorStrategy implements IThemeGeneratorStrategy {
     private readonly _materialStrategy;
     constructor();
-    generatePalette(baseColor: CssColor, mode: 'dark' | 'light'): IThemePalette;
-    generateScheme(baseColor: CssColor, mode: 'dark' | 'light'): IThemeScheme;
+    generatePalette(baseColor: CssColor, mode: 'dark' | 'light'): ThemePalette;
+    generateScheme(baseColor: CssColor, mode: 'dark' | 'light'): ThemeScheme;
 }
 /**
  * Generates a Joy theme generator strategy.
@@ -493,8 +620,8 @@ declare function createJoyTheme(): ThemeGeneratorFactoryFn;
 declare class MemphisThemeGeneratorStrategy implements IThemeGeneratorStrategy {
     private readonly _materialStrategy;
     constructor();
-    generatePalette(baseColor: CssColor, mode: 'dark' | 'light'): IThemePalette;
-    generateScheme(baseColor: CssColor, mode: 'dark' | 'light'): IThemeScheme;
+    generatePalette(baseColor: CssColor, mode: 'dark' | 'light'): ThemePalette;
+    generateScheme(baseColor: CssColor, mode: 'dark' | 'light'): ThemeScheme;
 }
 /**
  * Generates a Memphis theme generator strategy.
@@ -511,8 +638,8 @@ declare function createMemphisTheme(): ThemeGeneratorFactoryFn;
 declare class CosmopolitanThemeGeneratorStrategy implements IThemeGeneratorStrategy {
     private readonly _materialStrategy;
     constructor();
-    generatePalette(baseColor: CssColor, mode: 'dark' | 'light'): IThemePalette;
-    generateScheme(baseColor: CssColor, mode: 'dark' | 'light'): IThemeScheme;
+    generatePalette(baseColor: CssColor, mode: 'dark' | 'light'): ThemePalette;
+    generateScheme(baseColor: CssColor, mode: 'dark' | 'light'): ThemeScheme;
 }
 /**
  * Generates a Cosmopolitan theme generator strategy.
@@ -547,13 +674,13 @@ declare class TailwindThemeGeneratorStrategy implements IThemeGeneratorStrategy
      *   "900": "#0a2d4b"
      * }
      */
-    generatePalette(baseColor: CssColor, mode: 'light' | 'dark'): IThemePalette;
+    generatePalette(baseColor: CssColor, mode: 'light' | 'dark'): ThemePalette;
     /**
      * Generates a semantic color scheme for UI usage, based on the generated palette.
      *
      * @param baseColor - The base/accent color
      * @param mode - 'light' or 'dark'
-     * @returns An IThemeScheme with semantic color roles.
+     * @returns An scheme with semantic color roles.
      *
      * Returned keys:
      * - background  → shade "50"
@@ -562,7 +689,7 @@ declare class TailwindThemeGeneratorStrategy implements IThemeGeneratorStrategy
      * - accent      → shade "700"
      * - muted       → shade "300"
      */
-    generateScheme(baseColor: CssColor, mode: 'light' | 'dark'): IThemeScheme;
+    generateScheme(baseColor: CssColor, mode: 'light' | 'dark'): ThemeScheme;
 }
 /**
  * Generates a Tailwind theme generator strategy.
@@ -581,7 +708,7 @@ declare class BrowserPlatformAdapter implements IPlatformAdapter {
     matchMedia(query: string): boolean;
     setDocumentAttribute(name: string, value: string): void;
     getDocumentAttribute(name: string): string | null;
-    observeDocumentAttributes(attributes: string[], callback: (attributeName: string, newValue: string | null) => void): () => void;
+    observeDocumentAttributes(attributes: Array<string>, callback: (attributeName: string, newValue: string | null) => void): () => void;
 }
 
 /**
@@ -594,7 +721,7 @@ declare class NodePlatformAdapter implements IPlatformAdapter {
     matchMedia(_query: string): boolean;
     setDocumentAttribute(_name: string, _value: string): void;
     getDocumentAttribute(_name: string): string | null;
-    observeDocumentAttributes(_attributes: string[], _callback: (attributeName: string, newValue: string | null) => void): () => void;
+    observeDocumentAttributes(_attributes: Array<string>, _callback: (attributeName: string, newValue: string | null) => void): () => void;
 }
 
 /**
@@ -612,4 +739,75 @@ declare class PlatformAdapterFactory {
     static create(): IPlatformAdapter;
 }
 
-export { BootstrapTheme, BrowserPlatformAdapter, CosmopolitanTheme, CosmopolitanThemeGeneratorStrategy, CssAspectRatio, CssColor, type CssHEXColor, CssLength, type CssLengthUnit, type CssNameColor, type CssRGBAColor, type CssRGBColor, CssShadow, type CssShadowSingle, CssTime, type CssTimeUnit, type IPlatformAdapter, ITheme, type IThemeElevation, type IThemeGeneratorStrategy, type IThemeLayout, type IThemeMetadata, IThemePalette, type IThemeScheme, type IThemeTypography, type IThemeTypographyFontType, JoyTheme, JoyThemeGeneratorStrategy, MaterialThemeGeneratorStrategy, MemphisTheme, MemphisThemeGeneratorStrategy, NodePlatformAdapter, PlatformAdapterFactory, TailwindThemeGeneratorStrategy, ThemeGenerator, ThemeGeneratorServiceLocator, type ThemeMode, ThemeObserver, ThemeObserverServiceLocator, createCosmopolitanTheme, createJoyTheme, createMaterialTheme, createMemphisTheme, createTailwindTheme };
+/**
+ * @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>;
+
+/**
+ * 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;
+}
+
+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, 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 };