@breadstone/mosaik-themes 0.0.181 → 0.0.182

package/index.d.mts

@@ -0,0 +1,540 @@
+import { IEventEmitter } from '@breadstone/mosaik-elements';
+
+/**
+ * @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;
+}
+
+/**
+ * Represents a dynamic color scheme.
+ *
+ * @public
+ */
+interface IThemeScheme {
+    [key: string]: CssColor;
+}
+
+/**
+ * Represents a dynamic theme palette.
+ *
+ * @public
+ */
+interface IThemePalette {
+    [key: string]: CssColor;
+}
+/**
+ * @public
+ */
+declare namespace IThemePalette {
+    /**
+     * Checks if the value is a theme palette.
+     *
+     * @param value - The value to check.
+     * @returns The result.
+     */
+    function isThemePalette(value: unknown): value is IThemePalette;
+}
+
+/**
+ * @public
+ */
+type CssLengthUnit = 'em' | 'ex' | 'ch' | 'rem' | 'vh' | 'vw' | 'vmin' | 'vmax' | 'px' | 'mm' | 'cm' | 'in' | 'pt' | 'pc' | 'mozmm';
+/**
+ * @public
+ */
+type CssLength = `${number}${CssLengthUnit | '%'}` | number | '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;
+    /**
+     * @public
+     */
+    function isAuto(value: unknown): value is Extract<CssLength, 'auto'>;
+    /**
+     * @public
+     */
+    function isPercentage(value: unknown): value is `${number}%`;
+    /**
+     * @public
+     */
+    function isLength(value: unknown): value is `${number}${CssLengthUnit}`;
+    function toNumber(value: CssLength): number;
+    /**
+     * 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;
+}
+
+/**
+ * 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 dynamic typography styles.
+ *
+ * @public
+ */
+interface IThemeTypography {
+    [key: string]: IThemeTypographyFontType;
+}
+
+/**
+ * Represents a dynamic theme system.
+ *
+ * @public
+ */
+interface ITheme {
+    name: string;
+    scheme: Record<string, IThemeScheme>;
+    palette: Record<string, Record<string, IThemePalette | CssColor>>;
+    fontFamily: string;
+    typography: IThemeTypography;
+    layout: IThemeLayout;
+    elevation: 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;
+}
+
+/**
+ * @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 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[];
+    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;
+}
+
+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}`;
+/**
+ * @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;
+}
+
+/**
+ * Theme mode.
+ *
+ * @public
+ */
+type ThemeMode = 'system' | 'dark' | 'light';
+/**
+ * Observer for applying themes.
+ *
+ * @public
+ */
+declare class ThemeObserver {
+    private readonly _themeChanged;
+    private readonly _themeModeChanged;
+    private _currentTheme;
+    private _currentThemeMode;
+    /**
+     * Constructs a new instance of the `ThemeObserver` class.
+     *
+     * @public
+     */
+    constructor();
+    /**
+     * Fires when the theme changes.
+     *
+     * @public
+     * @readonly
+     */
+    get themeChanged(): IEventEmitter<string>;
+    /**
+     * Fires when the theme mode changes.
+     *
+     * @public
+     * @readonly
+     */
+    get themeModeChanged(): IEventEmitter<ThemeMode>;
+    applyTheme(theme: string, themeMode: ThemeMode): void;
+    private observe;
+}
+/**
+ * @public
+ */
+declare class ThemeObserverServiceLocator {
+    private static _current;
+    static get current(): ThemeObserver;
+    static isSet(): boolean;
+    static set(current: ThemeObserver): void;
+}
+
+/**
+ * @public
+ */
+declare class ThemeGenerator {
+    private readonly _strategies;
+    constructor();
+    generatePalette(theme: ITheme, baseColor: CssColor, mode: 'dark' | 'light' | 'system'): IThemePalette;
+    generateScheme(theme: ITheme, baseColor: CssColor, mode: 'dark' | 'light' | 'system'): IThemeScheme;
+    private resolveMode;
+    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 {
+    /**
+     * 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
+     */
+    generatePalette(baseColor: CssColor, mode: 'dark' | 'light'): IThemePalette;
+    /**
+     * 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
+     */
+    generateScheme(baseColor: CssColor, mode: 'dark' | 'light'): IThemeScheme;
+}
+
+/**
+ * Factory function type for creating theme generator strategies.
+ *
+ * @public
+ */
+type ThemeGeneratorFactoryFn = () => IThemeGeneratorStrategy;
+
+/**
+ * Material Design theme generator strategy.
+ *
+ * @public
+ */
+declare class MaterialThemeGeneratorStrategy implements IThemeGeneratorStrategy {
+    constructor();
+    generatePalette(baseColor: CssColor, mode: 'dark' | 'light'): IThemePalette;
+    generateScheme(baseColor: CssColor, mode: 'dark' | 'light'): IThemeScheme;
+}
+/**
+ * Generates a Material theme generator strategy.
+ *
+ * @public
+ */
+declare function createMaterialTheme(): ThemeGeneratorFactoryFn;
+
+/**
+ * Joy UI theme generator strategy.
+ * Uses the same generation logic as Material Design.
+ *
+ * @public
+ */
+declare class JoyThemeGeneratorStrategy implements IThemeGeneratorStrategy {
+    private readonly _materialStrategy;
+    constructor();
+    generatePalette(baseColor: CssColor, mode: 'dark' | 'light'): IThemePalette;
+    generateScheme(baseColor: CssColor, mode: 'dark' | 'light'): IThemeScheme;
+}
+/**
+ * Generates a Joy theme generator strategy.
+ *
+ * @public
+ */
+declare function createJoyTheme(): ThemeGeneratorFactoryFn;
+
+/**
+ * Memphis theme generator strategy.
+ * Uses the same generation logic as Material Design.
+ *
+ * @public
+ */
+declare class MemphisThemeGeneratorStrategy implements IThemeGeneratorStrategy {
+    private readonly _materialStrategy;
+    constructor();
+    generatePalette(baseColor: CssColor, mode: 'dark' | 'light'): IThemePalette;
+    generateScheme(baseColor: CssColor, mode: 'dark' | 'light'): IThemeScheme;
+}
+/**
+ * Generates a Memphis theme generator strategy.
+ *
+ * @public
+ */
+declare function createMemphisTheme(): ThemeGeneratorFactoryFn;
+
+/**
+ * Cosmopolitan theme generator strategy.
+ *
+ * @public
+ */
+declare class CosmopolitanThemeGeneratorStrategy implements IThemeGeneratorStrategy {
+    private readonly _materialStrategy;
+    constructor();
+    generatePalette(baseColor: CssColor, mode: 'dark' | 'light'): IThemePalette;
+    generateScheme(baseColor: CssColor, mode: 'dark' | 'light'): IThemeScheme;
+}
+/**
+ * Generates a Cosmopolitan theme generator strategy.
+ *
+ * @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 {
+    /**
+     * Generates a palette of shades based on a base/accent color.
+     *
+     * @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.
+     *
+     * Example (light mode, baseColor = blue-ish):
+     * {
+     *   "50":  "#f5faff",
+     *   "100": "#e1f3ff",
+     *   ...
+     *   "500": "#3498db",
+     *   ...
+     *   "900": "#0a2d4b"
+     * }
+     */
+    generatePalette(baseColor: CssColor, mode: 'light' | 'dark'): IThemePalette;
+    /**
+     * 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.
+     *
+     * Returned keys:
+     * - background  → shade "50"
+     * - foreground  → shade "900"
+     * - primary     → shade "500"
+     * - accent      → shade "700"
+     * - muted       → shade "300"
+     */
+    generateScheme(baseColor: CssColor, mode: 'light' | 'dark'): IThemeScheme;
+}
+/**
+ * Generates a Tailwind theme generator strategy.
+ *
+ * @public
+ */
+declare function createTailwindTheme(): ThemeGeneratorFactoryFn;
+
+export { BootstrapTheme, CosmopolitanTheme, CosmopolitanThemeGeneratorStrategy, CssAspectRatio, CssColor, type CssHEXColor, CssLength, type CssLengthUnit, type CssNameColor, type CssRGBAColor, type CssRGBColor, CssShadow, type CssShadowSingle, CssTime, type CssTimeUnit, ITheme, type IThemeElevation, type IThemeGeneratorStrategy, type IThemeLayout, type IThemeMetadata, IThemePalette, type IThemeScheme, type IThemeTypography, type IThemeTypographyFontType, JoyTheme, JoyThemeGeneratorStrategy, MaterialThemeGeneratorStrategy, MemphisTheme, MemphisThemeGeneratorStrategy, TailwindThemeGeneratorStrategy, ThemeGenerator, ThemeGeneratorServiceLocator, type ThemeMode, ThemeObserver, ThemeObserverServiceLocator, createCosmopolitanTheme, createJoyTheme, createMaterialTheme, createMemphisTheme, createTailwindTheme };