@poupe/theme-builder/dist/index.d.ts

Design token management and theme generation system for Poupe UI framework

import { CSSRuleObject } from '@poupe/css';
export { formatCSSRules, formatCSSRulesArray, generateCSSRules, generateCSSRulesArray } from '@poupe/css';
import { C as Color, a as CorePalettes, b as CorePaletteKey, c as ColorMap } from './shared/theme-builder.BBfchCYS.js';
export { M as ColorFormat, X as ColorGroup, W as CustomColor, T as HctColor, R as HexColor, U as ObjectColor, S as RgbaColor, l as argb, j as argbFromColord, f as argbFromHct, h as argbFromHctColor, g as argbFromRgbaColor, k as argbFromString, N as colorFormatter, t as colord, m as colordFromArgb, o as colordFromHct, p as colordFromHctColor, q as colordFromString, V as corePaletteKeys, A as hct, u as hctFromArgb, x as hctFromColord, v as hctFromRgbaColor, y as hctFromString, J as hexFromArgb, I as hexFromColord, K as hexFromHct, L as hexFromHctColor, O as hexString, H as hsl, D as hslFromArgb, B as hslFromColord, E as hslFromHct, F as hslFromHctColor, G as hslFromString, P as hslString, i as isObjectColor, n as normalizeAlpha, r as rgbFromRgbaColor, e as rgba, d as rgbaFromHctColor, Q as rgbaString, s as splitArgb, z as splitHct, w as withNormalizedAlpha } from './shared/theme-builder.BBfchCYS.js';
import { S as StandardDynamicSchemeKey, a as StandardDynamicColorKey, C as CustomDynamicColorKey, b as StandardPaletteKey } from './shared/theme-builder.C631FE2Q.js';
export { d as contentAccentToneDelta, c as customDynamicColors, e as standardDynamicColorKeys, s as standardDynamicColors, h as standardDynamicSchemes, g as standardPaletteKeys, f as standardPalettes } from './shared/theme-builder.C631FE2Q.js';
import { TonalPalette, Hct, DynamicScheme, Variant } from '@poupe/material-color-utilities';
export { DynamicScheme, Hct, TonalPalette, Variant } from '@poupe/material-color-utilities';
export { InteractionState, StateColorMixParams, StateLayerOpacity, StateVariants, defaultColors, getStateColorMixParams, hexColorPattern, isHexColor, makeColorMix, makeCustomColor, makeCustomColorFromPalette, makeStateLayerColors, makeStateVariants, makeTonalPalette, stateLayerOpacities, withKnownColor } from './core.js';
import * as type_fest from 'type-fest';
import { KebabCase } from 'type-fest';
export { AnyColor, Colord, HslColor, HslaColor, RgbColor } from 'colord';

/**
 * Configuration options for defining a color in a palette.
 */
interface ColorOptions {
    /** The color value to use */
    value: Color;
    /** Whether to harmonize the color with the primary color. Defaults to true */
    harmonize?: boolean;
}
/**
 * Extended color options that include a custom name for the color.
 */
interface CustomColorOptions extends ColorOptions {
    /** Custom name for the color. Defaults to the key name if not specified */
    name?: string;
}
/** Type representing all possible color option formats for theme colors */
type ThemeColorOptions = Color | ColorOptions;
/**
 * Type representing a complete set of palette colors with custom keys.
 * Includes the required Material Design core palette colors.
 *
 * @typeParam K - Custom color key names
 */
type ThemeColors<K extends string> = Record<K, Color | CustomColorOptions> & {
    /** Primary color (required) - can be a Color or object with value property */
    primary: Color | {
        value: Color;
    };
    /** Secondary color */
    secondary?: ThemeColorOptions;
    /** Tertiary color */
    tertiary?: ThemeColorOptions;
    /** Neutral color */
    neutral?: ThemeColorOptions;
    /** Neutral variant color */
    neutralVariant?: ThemeColorOptions;
    /** Error color */
    error?: ThemeColorOptions;
};
/**
 * Complete set of palettes including core palettes and custom palettes.
 *
 * @typeParam K - Custom palette key names
 */
type Palettes<K extends string> = CorePalettes & Record<K, TonalPalette>;
/**
 * Options for theme generation
 */
interface ThemeGenerationOptions {
    /** Material color scheme to use. Defaults to 'content' */
    scheme?: StandardDynamicSchemeKey;
    /** Contrast level from -1 (minimum) to 1 (maximum). 0 represents standard. Defaults to 0 */
    contrastLevel?: number;
    /** Use CSS color-mix() for state colors instead of generating pre-computed variants. Defaults to false */
    useColorMix?: boolean;
}

type StandardDynamicColors = {
    [K in StandardDynamicColorKey]: Hct;
};
type StandardPaletteColors = {
    [K in KebabCase<StandardPaletteKey>]: Hct;
};
type StandardPalettes = {
    [K in KebabCase<StandardPaletteKey>]: TonalPalette;
};
type CustomDynamicColors<T extends string> = {
    [K in CustomDynamicColorKey<KebabCase<T>>]: Hct;
};
declare function makeStandardColorsFromScheme(scheme: DynamicScheme): StandardDynamicColors;
declare function makeStandardPaletteKeyColorsFromScheme(scheme: DynamicScheme): StandardPaletteColors;
declare function makeStandardPaletteFromScheme(scheme: DynamicScheme): StandardPalettes;
declare function makeCustomColors<K extends string>(source: Color, colors: Record<K, ColorOptions>): {
    source: Color;
    colors: type_fest.DelimiterCase<K, "-", {
        splitOnNumbers: false;
    }>[];
    colorOptions: Record<KebabCase<K>, ColorOptions>;
    palettes: Record<KebabCase<K>, TonalPalette>;
    dark: CustomDynamicColors<K>;
    light: CustomDynamicColors<K>;
};
declare function makeCustomColorsFromPalettes<K extends string>(colors?: Record<K, TonalPalette>): {
    colors: type_fest.DelimiterCase<K, "-", {
        splitOnNumbers: false;
    }>[];
    palettes: Record<KebabCase<K>, TonalPalette>;
    dark: CustomDynamicColors<K>;
    light: CustomDynamicColors<K>;
};
/**
 * Creates a dynamic color scheme based on the provided source color, variant, and other parameters.
 * Uses Material Design 2025 specification with phone platform.
 *
 * @param source - The source color in HCT color space
 * @param variant - The color scheme to apply
 * @param contrastLevel - The desired contrast level
 * @param isDark - Whether the scheme is for a dark or light theme
 * @param palettes - Optional color palettes to customize the scheme
 * @returns A configured DynamicScheme instance
 */
declare function makeDynamicScheme(source: Hct, variant: Variant, contrastLevel: number, isDark: boolean, palettes?: Partial<CorePalettes>): DynamicScheme;

/**
 * Normalizes a value that could be a direct Color or a partial CustomColorOptions
 * to a partial CustomColorOptions object.
 *
 * @param c - A color, custom color options, or partial custom color options to flatten
 * @returns A normalized (partial) CustomColorOptions object
 */
declare function flattenPartialColorOptions(c: Color | CustomColorOptions): CustomColorOptions;
declare function flattenPartialColorOptions(c: Color | CustomColorOptions | Partial<CustomColorOptions> | undefined): CustomColorOptions | Partial<CustomColorOptions>;
/**
 * Normalizes color input to a CustomColorOptions object.
 * Converts raw Color values to CustomColorOptions with HCT color representation.
 *
 * @param c - Color or CustomColorOptions to normalize
 * @returns Normalized CustomColorOptions with HCT color value
 */
declare const flattenColorOptions: (c: Color | CustomColorOptions) => CustomColorOptions;
/**
 * Creates a complete theme palette system from a set of palette colors.
 * Processes primary color as the source for harmonization and generates
 * tonal palettes for all defined colors.
 *
 * @typeParam K - Custom color key names
 * @param colors - Complete set of palette colors including primary and optional colors
 * @returns Object containing source color, core palettes, all palettes, and color configurations
 */
declare const makeThemePalettes: <K extends string>(colors: ThemeColors<K>) => {
    source: Hct;
    corePalettes: CorePalettes;
    extraPalettes: Record<string, TonalPalette>;
    palettes: Palettes<string>;
    colors: Record<CorePaletteKey | string, ColorOptions>;
};

/**
 * Base color keys that support state variants
 */
type StandardInteractiveColorKey = 'primary' | 'secondary' | 'tertiary' | 'error' | 'surface' | 'surface-variant' | 'primary-container' | 'secondary-container' | 'tertiary-container' | 'error-container';
/**
 * State variant types for standard Material Design 3 colors
 */
type StandardStateVariants = {
    [K in StandardInteractiveColorKey as `${K}-hover` | `${K}-focus` | `${K}-pressed` | `${K}-dragged` | `${K}-disabled`]: Hct;
};
/**
 * Generates Material Design 3 state layer variants for standard theme colors
 *
 * @param colors - Standard theme colors generated from scheme
 * @returns Object with state variants for interactive colors
 */
declare function makeStandardStateVariants(colors: StandardDynamicColors): StandardStateVariants;
/**
 * Custom color state variant type
 */
type CustomStateVariantKey<T extends string> = `${T}-hover` | `${T}-focus` | `${T}-pressed` | `${T}-dragged` | `${T}-disabled` | `${T}-container-hover` | `${T}-container-focus` | `${T}-container-pressed` | `${T}-container-dragged` | `${T}-container-disabled`;
type CustomStateVariants<T extends string> = {
    [K in CustomStateVariantKey<KebabCase<T>>]: Hct;
};
/**
 * Generates Material Design 3 state layer variants for custom colors
 *
 * @param customColors - Custom colors with their on-colors
 * @returns Object with state variants for custom colors
 */
declare function makeCustomStateVariants<K extends string>(customColors: CustomDynamicColors<K>): CustomStateVariants<K>;

/**
 * FlatThemeColors defines the colors of the theme
 */
type FlatThemeColors<K extends string> = {
    primary: ColorOptions;
} & Record<K, ColorOptions>;
/**
 * makeThemeKeys returns the keys of makeTheme makes without calculating
 * the values.
 */
declare function makeThemeKeys<K extends string>(colors: Partial<ThemeColors<K>>): {
    keys: ("error" | "surface" | "surface-dim" | "surface-bright" | "surface-variant" | "surface-container-lowest" | "surface-container-low" | "surface-container" | "surface-container-high" | "surface-container-highest" | "inverse-surface" | "on-surface" | "on-surface-dim" | "on-surface-bright" | "on-surface-variant" | "on-surface-container-lowest" | "on-surface-container-low" | "on-surface-container" | "on-surface-container-high" | "on-surface-container-highest" | "on-inverse-surface" | "primary-dim" | "primary-container" | "primary-fixed" | "primary-fixed-dim" | "inverse-primary" | "on-primary" | "on-primary-container" | "on-primary-fixed" | "on-primary-fixed-variant" | "secondary-dim" | "secondary-container" | "secondary-fixed" | "secondary-fixed-dim" | "on-secondary" | "on-secondary-container" | "on-secondary-fixed" | "on-secondary-fixed-variant" | "tertiary-dim" | "tertiary-container" | "tertiary-fixed" | "tertiary-fixed-dim" | "on-tertiary" | "on-tertiary-container" | "on-tertiary-fixed" | "on-tertiary-fixed-variant" | "error-container" | "on-error" | "on-error-container" | "outline" | "outline-variant" | "shadow" | "scrim" | (KebabCase<"primary" | "secondary" | "tertiary" | "neutral" | "neutralVariant"> | KebabCase<K>) | CustomDynamicColorKey<KebabCase<K>>)[];
    paletteKeys: (KebabCase<"primary" | "secondary" | "tertiary" | "neutral" | "neutralVariant"> | KebabCase<K>)[];
    colorOptions: Record<KebabCase<"primary" | "secondary" | "tertiary" | "neutral" | "neutralVariant"> | KebabCase<K>, Partial<ColorOptions>>;
};
/**
 * @param colors - base colors of the theme.
 * @param scheme - Material color scheme to use.
 * @param contrastLevel - contrast level from -1 (minimum) to 1 (maximum). 0 represents standard.
 * @param extraOptions - Additional theme generation options.
 * @returns dark and light themes.
 */
declare function makeTheme<K extends string>(colors: ThemeColors<K>, scheme?: StandardDynamicSchemeKey, contrastLevel?: number, extraOptions?: Partial<ThemeGenerationOptions>): {
    darkKeyColors: {};
    lightKeyColors: {};
    darkPalettes: {};
    lightPalettes: {};
    dark: {
        primary: Hct;
        secondary: Hct;
        tertiary: Hct;
    };
    light: {
        primary: Hct;
        secondary: Hct;
        tertiary: Hct;
    };
    source: Hct;
    colorOptions: Record<string, ColorOptions>;
    darkScheme: DynamicScheme;
    lightScheme: DynamicScheme;
    extraPalettes: Record<string, TonalPalette>;
};
declare function makeThemeFromSchemes<K extends string>(darkScheme: DynamicScheme, lightScheme: DynamicScheme, extraPalettes?: Record<K, TonalPalette>): {
    darkKeyColors: {};
    lightKeyColors: {};
    darkPalettes: {};
    lightPalettes: {};
    dark: { [P in ("primary" | "secondary" | "tertiary") & CustomDynamicColorKey<type_fest.DelimiterCase<K, "-", {
        splitOnNumbers: false;
    }>>]: Hct; };
    light: { [P_1 in ("primary" | "secondary" | "tertiary") & CustomDynamicColorKey<type_fest.DelimiterCase<K, "-", {
        splitOnNumbers: false;
    }>>]: Hct; };
};

interface CSSThemeOptions {
    /** @defaultValue `'.dark'` */
    darkMode: boolean | string | string[];
    /** @defaultValue `'.light'` */
    lightMode: boolean | string | string[];
    /** @defaultValue `'md-'` */
    prefix: string;
    /** @defaultValue `'-dark'` */
    darkSuffix: string;
    /** @defaultValue `'-light'` */
    lightSuffix: string;
    /** @defaultValue `rgb('{r} {g} {b}')` */
    stringify: (c: Hct) => string;
    /** @defaultValue `true` */
    addStarVariantsToDark?: boolean;
    /** @defaultValue `true` */
    addStarVariantsToLight?: boolean;
}
/** apply defaults to {@link CSSThemeOptions} */
declare function defaultCSSThemeOptions(options?: Partial<CSSThemeOptions>): CSSThemeOptions;
/** @returns the dark mode selector or media rule */
declare function defaultDarkSelector(options: Partial<CSSThemeOptions>): string[];
/** @returns the light mode selector, or undefined if disabled */
declare function defaultLightSelector(options: Partial<CSSThemeOptions>): string[] | undefined;
/** generates CSS color tables */
declare function assembleCSSColors<K extends string>(dark: ColorMap<K>, light: ColorMap<K>, options?: Partial<CSSThemeOptions>): {
    vars: Record<K, string>;
    darkValues: CSSRuleObject;
    lightValues: CSSRuleObject;
    darkVars: CSSRuleObject | undefined;
    lightVars: CSSRuleObject | undefined;
    styles: CSSRuleObject[];
    options: CSSThemeOptions;
};
interface MakeCSSThemeOptions extends CSSThemeOptions {
    /** @defaultValue `'content'` */
    scheme?: StandardDynamicSchemeKey;
    /** @defaultValue `0` */
    contrastLevel?: number;
}
/**
 *  makeCSSTheme assembles CSS variables to use in M3 dark/light themes.
 *
 * @param colors - base colors of the theme.
 * @param options - configuration options.
 * @returns  CSSRuleObjects to set up dark/light themes.
 */
declare function makeCSSTheme<K extends string>(colors: ThemeColors<K>, options?: Partial<MakeCSSThemeOptions>): {
    vars: Record<"primary" | "secondary" | "tertiary", string>;
    darkValues: CSSRuleObject;
    lightValues: CSSRuleObject;
    darkVars: CSSRuleObject | undefined;
    lightVars: CSSRuleObject | undefined;
    styles: CSSRuleObject[];
    options: CSSThemeOptions;
};

/** @returns a color suitable to make a theme from the given image element. */
declare function fromImageElement(image: HTMLImageElement): Promise<Hct>;

export { type CSSThemeOptions, Color, ColorMap, type ColorOptions, CorePaletteKey, CorePalettes, type CustomColorOptions, CustomDynamicColorKey, type CustomDynamicColors, type FlatThemeColors, type MakeCSSThemeOptions, type Palettes, StandardDynamicColorKey, type StandardDynamicColors, StandardDynamicSchemeKey, StandardPaletteKey, type ThemeColorOptions, type ThemeColors, type ThemeGenerationOptions, assembleCSSColors, defaultCSSThemeOptions, defaultDarkSelector, defaultLightSelector, flattenColorOptions, flattenPartialColorOptions, fromImageElement, makeCSSTheme, makeCustomColors, makeCustomColorsFromPalettes, makeCustomStateVariants, makeDynamicScheme, makeStandardColorsFromScheme, makeStandardPaletteFromScheme, makeStandardPaletteKeyColorsFromScheme, makeStandardStateVariants, makeTheme, makeThemeFromSchemes, makeThemeKeys, makeThemePalettes };