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

Design token management and theme generation system for Poupe UI framework

import { CSSRuleObject, formatCSSRules, formatCSSRulesArray, generateCSSRules, generateCSSRulesArray } from "@poupe/css";
import { DynamicScheme, Hct, Hct as Hct$1, TonalPalette, TonalPalette as TonalPalette$1, Variant } from "@poupe/material-color-utilities";
import { AnyColor, AnyColor as AnyColor$1, Colord, Colord as Colord$1, HslColor, HslaColor, RgbColor, RgbColor as RgbColor$1 } from "colord";
import * as _$type_fest0 from "type-fest";
import { KebabCase } from "type-fest";
type ColorMap<K extends string> = Record<K, Hct$1>;
type HexColor = `#${string}`;
/** {@link RgbColor} variant with optional alpha value */
type RgbaColor = RgbColor$1 & {
  a?: number;
};
/** destructured {@link Hct} color with optional alpha value */
interface HctColor {
  a?: number;
  c: number;
  h: number;
  t: number;
}
/** ObjectColor represents a destructured Color object */
type ObjectColor = Exclude<AnyColor$1, string> | HctColor;
/** Color is any accepted color representation */
type Color = Colord$1 | Hct$1 | number | ObjectColor | string;
/**
 * Core Material Design 3 palettes for DynamicSchemeOptions.
 * Contains tonal palettes for the standard Material Design color roles.
 */
type CorePalettes = {
  error?: TonalPalette$1;
  neutral?: TonalPalette$1;
  neutralVariant?: TonalPalette$1;
  primary: TonalPalette$1;
  secondary?: TonalPalette$1;
  tertiary?: TonalPalette$1;
};
/**
 * Type representing the valid keys for core palettes in the Material Design 3 color system.
 * Derived from the keys of the {@link CorePalettes} type, representing standard color roles.
 */
type CorePaletteKey = keyof CorePalettes;
/**
 * Readonly array of core palette keys used in Material Design 3 color system.
 * Represents the standard color roles that can be defined in a dynamic color scheme.
 */
declare const corePaletteKeys: Readonly<CorePaletteKey[]>;
/**
 * Represents a custom color definition with tones and color groups for light and dark schemes
 * @param name - Optional name for the custom color
 * @param tones - Readonly tonal palette defining color variations
 * @param light - Color group representing the light scheme variant
 * @param dark - Color group representing the dark scheme variant
 */
type CustomColor = {
  dark: Readonly<ColorGroup>;
  light: Readonly<ColorGroup>;
  name?: string;
  tones: TonalPalette$1;
};
/**
 * Represents a color group with specific color roles in a color scheme.
 * Defines the color and its on-color variants for different contexts and containers.
 * @param color - The custom color
 * @param onColor - The color used for content on top of the custom color
 * @param colorContainer - The container variant of the custom color
 * @param onColorContainer - The color used for content on the color container
 */
type ColorGroup = {
  color: Hct$1;
  colorContainer: Hct$1;
  onColor: Hct$1;
  onColorContainer: Hct$1;
};
/**
 * Determines if the given value is an {@link ObjectColor}
 *
 * @param c - The value to check for color object characteristics
 * @returns A boolean indicating whether the input is a color object
 */
declare const isObjectColor: (c: unknown) => boolean;
/**
 * Normalizes an alpha value to a consistent representation between 0 and 1.
 * @param a - Optional alpha value to normalize
 * @returns Normalized alpha value or undefined if input is undefined
 */
declare function normalizeAlpha(a: number): number;
declare function normalizeAlpha(a?: number): number | undefined;
/**
 * Normalizes the alpha value of an object color if present.
 *
 * @param c - The color object to potentially normalize
 * @returns A new color object with a normalized alpha value, or the original object if no alpha is present
 */
declare function withNormalizedAlpha(c: ObjectColor): ObjectColor;
/** @returns the RGB number corresponding to the given {@link RgbaColor} */
declare const rgbFromRgbaColor: (c: RgbaColor) => number;
/** @returns the decomposed {@link RgbaColor} corresponding to the given {@link HctColor} */
declare const rgbaFromHctColor: (c: HctColor) => RgbaColor;
/** @returns the decomposed {@link RgbaColor} corresponding to the given color */
/**
 * Returns the decomposed RGBA components for any color type.
 * @param c - The color to decompose
 * @returns The RGBA color object with r, g, b, and optional a components
 */
declare const rgba: (c: Color) => RgbaColor;
/** @returns the ARGB number corresponding to the given {@link Hct} */
declare const argbFromHct: (c: Hct) => number;
/** @returns the ARGB number corresponding to the given {@link RgbaColor} */
declare const argbFromRgbaColor: (c: RgbaColor) => number;
/** @returns the ARGB number corresponding to the given {@link HctColor} */
declare const argbFromHctColor: (c: HctColor) => number;
/** @returns the ARGB number corresponding to the given {@link Colord} */
declare const argbFromColord: (c: Colord) => number;
/** @returns the ARGB number corresponding to the color string */
declare const argbFromString: (s: string) => number;
/** @returns the the decomposed {@link RgbaColor} corresponding to the given ARGB number */
declare const splitArgb: (argb: number) => RgbaColor;
/** @returns ARGB representation of the given {@link Color}. */
declare const argb: (c: Color) => number;
/** @returns {@link Colord} from an ARGB number */
declare const colordFromArgb: (argb: number) => Colord;
/** @returns {@link Colord} from a {@link Hct} color */
declare const colordFromHct: (c: Hct) => Colord;
/** @returns {@link Colord} from a {@link HctColor} */
declare const colordFromHctColor: (c: HctColor) => Colord;
/** @returns {@link Colord} from a color string, handling known color names */
declare const colordFromString: (c: string) => Colord;
/** @returns {@link Colord} from the given {@link Color}. */
declare const colord: (c: Color) => Colord;
/** @returns {@link Hct} from an ARGB number */
declare const hctFromArgb: (argb: number) => Hct;
/** @returns {@link Hct} from an {@link RgbaColor} object */
declare const hctFromRgbaColor: (c: RgbaColor) => Hct;
/** @returns {@link Hct} from a {@link Colord} object */
declare const hctFromColord: (c: Colord) => Hct;
/** @returns {@link Hct} from a valid CSS color string */
declare const hctFromString: (s: string) => Hct;
/** @returns {@link HctColor} decomposing the given {@link Hct} color. */
declare const splitHct: (c: Hct) => HctColor;
/** @returns {@link Hct} representation of the given {@link Color}. */
declare const hct: (c: Color) => Hct;
/** @returns the {@link HslaColor} for the given {@link Colord} */
declare const hslFromColord: (c: Colord) => HslaColor;
/** @returns the {@link HslaColor} for the given ARGB number */
declare const hslFromArgb: (argb: number) => HslaColor;
/** @returns the {@link HslaColor} for the given {@link Hct} */
declare const hslFromHct: (c: Hct) => HslaColor;
/** @returns the {@link HslaColor} for the given {@link HctColor} */
declare const hslFromHctColor: (c: HctColor) => HslaColor;
/** @returns the {@link HslaColor} for the given CSS color string */
declare const hslFromString: (s: string) => HslaColor;
/** @returns the {@link HslaColor} for the given {@link Color} */
declare const hsl: (c: Color) => HslaColor;
/** @returns the Hex RGB Color string for the given {@link Colord} */
declare const hexFromColord: (c: Colord) => HexColor;
/** @returns the Hex RGB Color string for the given ARGB number */
declare const hexFromArgb: (argb: number) => `#${string}`;
/** @returns the Hex RGB Color string for the given {@link Hct} */
declare const hexFromHct: (c: Hct) => `#${string}`;
/** @returns the Hex RGB Color string for the given {@link HctColor} */
declare const hexFromHctColor: (c: HctColor) => HexColor;
/**
 * Complete collection of CSS named colors as defined in the CSS Color Module specifications.
 *
 * This object contains all standard CSS named colors organized by color family,
 * providing a comprehensive palette for color operations and conversions.
 *
 * @remarks
 * - All values are in hexadecimal format (#rrggbb or #rrggbbaa for transparent)
 * - Colors are grouped by visual similarity for easier navigation
 * - Includes all 147 CSS named colors from the CSS Color Module Level 4 specification
 * - Includes the transparent keyword for complete color support
 * - Some colors appear multiple times (e.g., cyan/aqua, fuchsia/magenta) as they represent the same color
 *
 * @example
 * ```typescript
 * const redColor = defaultColors.red; // '#ff0000'
 * const blueColor = defaultColors.blue; // '#0000ff'
 * ```
 */
declare const defaultColors: {
  indianred: string;
  lightcoral: string;
  salmon: string;
  darksalmon: string;
  crimson: string;
  red: string;
  firebrick: string;
  darkred: string;
  pink: string;
  lightpink: string;
  hotpink: string;
  deeppink: string;
  mediumvioletred: string;
  palevioletred: string;
  lightsalmon: string;
  coral: string;
  tomato: string;
  orangered: string;
  darkorange: string;
  orange: string;
  gold: string;
  yellow: string;
  lightyellow: string;
  lemonchiffon: string;
  lightgoldenrodyellow: string;
  papayawhip: string;
  moccasin: string;
  peachpuff: string;
  palegoldenrod: string;
  khaki: string;
  darkkhaki: string;
  lavender: string;
  thistle: string;
  plum: string;
  violet: string;
  orchid: string;
  fuchsia: string;
  magenta: string;
  mediumorchid: string;
  mediumpurple: string;
  rebeccapurple: string;
  blueviolet: string;
  darkviolet: string;
  darkorchid: string;
  darkmagenta: string;
  purple: string;
  indigo: string;
  slateblue: string;
  darkslateblue: string;
  mediumslateblue: string;
  greenyellow: string;
  chartreuse: string;
  lawngreen: string;
  lime: string;
  limegreen: string;
  palegreen: string;
  lightgreen: string;
  mediumspringgreen: string;
  springgreen: string;
  mediumseagreen: string;
  seagreen: string;
  forestgreen: string;
  green: string;
  darkgreen: string;
  yellowgreen: string;
  olivedrab: string;
  olive: string;
  darkolivegreen: string;
  mediumaquamarine: string;
  darkseagreen: string;
  lightseagreen: string;
  darkcyan: string;
  teal: string;
  aqua: string;
  cyan: string;
  lightcyan: string;
  paleturquoise: string;
  aquamarine: string;
  turquoise: string;
  mediumturquoise: string;
  darkturquoise: string;
  cadetblue: string;
  steelblue: string;
  lightsteelblue: string;
  powderblue: string;
  lightblue: string;
  skyblue: string;
  lightskyblue: string;
  deepskyblue: string;
  dodgerblue: string;
  cornflowerblue: string;
  royalblue: string;
  blue: string;
  mediumblue: string;
  darkblue: string;
  navy: string;
  midnightblue: string;
  cornsilk: string;
  blanchedalmond: string;
  bisque: string;
  navajowhite: string;
  wheat: string;
  burlywood: string;
  tan: string;
  rosybrown: string;
  sandybrown: string;
  goldenrod: string;
  darkgoldenrod: string;
  peru: string;
  chocolate: string;
  saddlebrown: string;
  sienna: string;
  brown: string;
  maroon: string;
  white: string;
  snow: string;
  honeydew: string;
  mintcream: string;
  azure: string;
  aliceblue: string;
  ghostwhite: string;
  whitesmoke: string;
  seashell: string;
  beige: string;
  oldlace: string;
  floralwhite: string;
  ivory: string;
  antiquewhite: string;
  linen: string;
  lavenderblush: string;
  mistyrose: string;
  gainsboro: string;
  lightgray: string;
  lightgrey: string;
  silver: string;
  darkgray: string;
  darkgrey: string;
  gray: string;
  grey: string;
  dimgray: string;
  dimgrey: string;
  lightslategray: string;
  lightslategrey: string;
  slategray: string;
  slategrey: string;
  darkslategray: string;
  darkslategrey: string;
  black: string;
  transparent: string;
};
/**
 * Converts CSS named color strings to their hexadecimal equivalents.
 *
 * @param c - The color value to process. Can be any valid Color type.
 * @returns The hexadecimal color value if the input is a known CSS named color,
 *          otherwise returns the original input unchanged.
 *
 * @example
 * ```typescript
 * withKnownColor('red');    // '#ff0000'
 * withKnownColor('blue');   // '#0000ff'
 * withKnownColor('#abc123'); // '#abc123' (unchanged)
 * withKnownColor('unknown'); // 'unknown' (unchanged)
 * ```
 *
 * @remarks
 * Only processes strings that contain only letters (both uppercase and lowercase).
 * Case-insensitive matching is performed by converting input to lowercase.
 */
declare function withKnownColor(c: string): string;
declare function withKnownColor(c: number): number;
declare function withKnownColor(c: Color): Color;
/**
 * Defines the possible color format types for conversion.
 *
 * @remarks
 * Supports predefined formats like 'numbers', 'rgb', 'hsl', 'hex',
 * or a custom formatting function that takes an Hct color and returns a string.
 */
type ColorFormat = 'hex' | 'hsl' | 'numbers' | 'rgb' | ((c: Hct) => string);
/**
 * Converts an HCT color to a specified format.
 *
 * @param v - The color format to convert to. Can be 'numbers', 'rgb', 'hsl', 'hex', or a custom formatting function.
 * @returns A function that converts an HCT color to the specified string format.
 *
 * @remarks defaults to `'rgb'`
 */
declare function colorFormatter(v?: ColorFormat): ((c: Hct) => string);
/** @returns the Hex RGB Color string for the given {@link Color} */
declare const hexString: (c: Color) => HexColor;
/** @returns the HSL or HSLA color string representation of the given {@link Color}, with optional alpha control */
declare function hslString(c: Color, alpha?: boolean): string;
/**
 * Converts a color to an RGB or RGBA string representation.
 * @param c - The color to convert
 * @param alpha - Whether to include alpha channel (defaults to true)
 * @returns A CSS-compatible RGB or RGBA string
 */
declare const rgbaString: (c: Color, alpha?: boolean) => string;
/** @returns the result of mixing two colors in given ratios */
declare function makeColorMix(base: Color, other: Color, ratios: number): Hct;
declare function makeColorMix(base: Color, other: Color, ratios: Array<number>): Hct[];
declare function makeColorMix<K extends string>(base: Color, other: Color, ratios: Record<K, number>): Record<K, Hct>;
/**
 * Creates a tonal palette from a color with optional harmonization
 *
 * @param color - The base color to create the palette from
 * @param harmonizeTo - Optional target color to harmonize towards.
 *                      Harmonization shifts the hue of the base color
 *                      towards the target color while preserving tone.
 * @param isKeyColor - Whether to preserve the exact tone from the input
 *                     color (true) as key color or derive a tone
 *                     algorithmically (false).
 *                     @defaultValue `true`
 * @returns A TonalPalette instance handling tones from 0-100
 */
declare function makeTonalPalette(color: Color, harmonizeTo?: Hct, isKeyColor?: boolean): TonalPalette;
/**
 * Generates a custom color optionally harmonized to a target color
 *
 * @param color - The base color to transform into a custom color
 * @param harmonizeTo - Optional target color to harmonize towards.
 *                      Harmonization blends the hue of the base color
 *                      with the target while maintaining lightness.
 * @param name - Optional name identifier for the custom color
 * @param isKeyColor - Whether to preserve exact tone from input color
 *                     as key color. @defaultValue `true`.
 * @returns A CustomColor object with light and dark theme variations,
 *          including primary color, on-color, container, and
 *          on-container variants for each theme
 */
declare function makeCustomColor(color: Color, harmonizeTo?: Hct, name?: string, isKeyColor?: boolean): CustomColor;
/**
 * Generates a custom color from a given tonal palette with predefined
 * light and dark color variations.
 *
 * Light theme uses tones: 40 (color), 100 (onColor), 90 (container),
 * 10 (onContainer). Dark theme uses tones: 80 (color), 20 (onColor),
 * 30 (container), 90 (onContainer). These follow Material Design 3
 * color system guidelines for optimal contrast and accessibility.
 *
 * @param tones - The tonal palette (0-100 tone range) used to derive
 *                color variations
 * @param name - Optional name identifier for the custom color
 * @returns A CustomColor object with light and dark color configurations
 *          containing color, onColor, colorContainer, and onColorContainer
 *          properties for each theme mode
 */
declare function makeCustomColorFromPalette(tones: TonalPalette, name?: string): CustomColor;
/**
 * Material Design 3 state layer opacity values
 * @see https://m3.material.io/foundations/interaction/states/state-layers
 */
declare const stateLayerOpacities: {
  readonly hover: 0.08;
  readonly focus: 0.12;
  readonly pressed: 0.12;
  readonly dragged: 0.16;
  readonly disabled: 0.12;
  readonly onDisabled: 0.38;
};
type StateLayerOpacity = typeof stateLayerOpacities;
type InteractionState = keyof Omit<StateLayerOpacity, 'disabled' | 'onDisabled'>;
type StateVariants<T extends string> = { [K in T as `${K}-disabled` | `${K}-dragged` | `${K}-focus` | `${K}-hover` | `${K}-pressed`]: Hct } & { [K in T as `on-${K}-disabled`]: Hct };
/**
 * State color mix parameters for CSS color-mix() function
 */
interface StateColorMixParams {
  /** The base color CSS variable name */
  baseColor: string;
  /** The on-color CSS variable name */
  onColor: string;
  /** The opacity percentage for mixing (0-100) */
  opacityPercent: number;
  /** The state type */
  state: keyof typeof stateLayerOpacities;
}
/**
 * Get CSS color-mix parameters for creating state colors
 * @param colorName - The base color name (e.g., 'primary', 'secondary')
 * @param state - The state type
 * @param prefix - Optional CSS variable prefix (defaults to empty string)
 * @returns Parameters for creating CSS color-mix
 */
declare function getStateColorMixParams(colorName: string, state: keyof Omit<StateLayerOpacity, 'onDisabled'>, prefix?: string): StateColorMixParams;
/**
 * Creates state layer colors by mixing the on-color with the base color at specified opacities
 * Following Material Design 3 state layer principles
 *
 * @param baseColor - The base/background color
 * @param onColor - The on-color (content color that goes on top of the base)
 * @returns Object with state layer colors for each interaction state
 */
declare function makeStateLayerColors(baseColor: Color, onColor: Color): Record<"hover" | "focus" | "pressed" | "dragged" | "disabled" | "onDisabled", Hct>;
/**
 * Generates state variants for a set of color pairs
 * Each color should have a corresponding on-color
 *
 * @param colors - Object with base colors and their on-colors
 * @returns Object with state variants for each color
 */
declare function makeStateVariants<K extends string>(colors: Record<K, Color>, onColors: Record<`on-${K}`, Color>): StateVariants<K>;
declare const hexColorPattern: RegExp;
declare const isHexColor: (s?: string) => boolean;
declare const customDynamicColors: {
  '{}': (cc: ColorGroup) => Hct;
  '{}-container': (cc: ColorGroup) => Hct;
  'on-{}': (cc: ColorGroup) => Hct;
  'on-{}-container': (cc: ColorGroup) => Hct;
};
type CustomDynamicColorKey<T extends string> = `${T}-container` | `${T}` | `on-${T}-container` | `on-${T}`;
/** standardDynamicColors are all dynamic colors defined by Material Design 3 */
declare const standardDynamicColors: {
  surface: (ds: DynamicScheme) => number;
  'surface-dim': (ds: DynamicScheme) => number;
  'surface-bright': (ds: DynamicScheme) => number;
  'surface-variant': (ds: DynamicScheme) => number;
  'surface-container-lowest': (ds: DynamicScheme) => number;
  'surface-container-low': (ds: DynamicScheme) => number;
  'surface-container': (ds: DynamicScheme) => number;
  'surface-container-high': (ds: DynamicScheme) => number;
  'surface-container-highest': (ds: DynamicScheme) => number;
  'inverse-surface': (ds: DynamicScheme) => number;
  'on-surface': (ds: DynamicScheme) => number;
  'on-surface-dim': (ds: DynamicScheme) => number;
  'on-surface-bright': (ds: DynamicScheme) => number;
  'on-surface-variant': (ds: DynamicScheme) => number;
  'on-surface-container-lowest': (ds: DynamicScheme) => number;
  'on-surface-container-low': (ds: DynamicScheme) => number;
  'on-surface-container': (ds: DynamicScheme) => number;
  'on-surface-container-high': (ds: DynamicScheme) => number;
  'on-surface-container-highest': (ds: DynamicScheme) => number;
  'on-inverse-surface': (ds: DynamicScheme) => number;
  primary: (ds: DynamicScheme) => number;
  'primary-dim': (ds: DynamicScheme) => number;
  'primary-container': (ds: DynamicScheme) => number;
  'primary-fixed': (ds: DynamicScheme) => number;
  'primary-fixed-dim': (ds: DynamicScheme) => number;
  'inverse-primary': (ds: DynamicScheme) => number;
  'on-primary': (ds: DynamicScheme) => number;
  'on-primary-container': (ds: DynamicScheme) => number;
  'on-primary-fixed': (ds: DynamicScheme) => number;
  'on-primary-fixed-variant': (ds: DynamicScheme) => number;
  secondary: (ds: DynamicScheme) => number;
  'secondary-dim': (ds: DynamicScheme) => number;
  'secondary-container': (ds: DynamicScheme) => number;
  'secondary-fixed': (ds: DynamicScheme) => number;
  'secondary-fixed-dim': (ds: DynamicScheme) => number;
  'on-secondary': (ds: DynamicScheme) => number;
  'on-secondary-container': (ds: DynamicScheme) => number;
  'on-secondary-fixed': (ds: DynamicScheme) => number;
  'on-secondary-fixed-variant': (ds: DynamicScheme) => number;
  tertiary: (ds: DynamicScheme) => number;
  'tertiary-dim': (ds: DynamicScheme) => number;
  'tertiary-container': (ds: DynamicScheme) => number;
  'tertiary-fixed': (ds: DynamicScheme) => number;
  'tertiary-fixed-dim': (ds: DynamicScheme) => number;
  'on-tertiary': (ds: DynamicScheme) => number;
  'on-tertiary-container': (ds: DynamicScheme) => number;
  'on-tertiary-fixed': (ds: DynamicScheme) => number;
  'on-tertiary-fixed-variant': (ds: DynamicScheme) => number;
  error: (ds: DynamicScheme) => number;
  'error-container': (ds: DynamicScheme) => number;
  'on-error': (ds: DynamicScheme) => number;
  'on-error-container': (ds: DynamicScheme) => number;
  outline: (ds: DynamicScheme) => number;
  'outline-variant': (ds: DynamicScheme) => number;
  shadow: (ds: DynamicScheme) => number;
  scrim: (ds: DynamicScheme) => number;
};
/** contentAccentToneDelta is re-exported from MaterialDynamicColors for completeness */
declare const contentAccentToneDelta: number;
/** StandardDynamicColorKey is a type representing all fields in standardDynamicColors */
type StandardDynamicColorKey = keyof typeof standardDynamicColors;
/** standardDynamicColorKeys is an array of all StandardDynamicColorKey values */
declare const standardDynamicColorKeys: StandardDynamicColorKey[];
/** standardPaletteKeyColors are all palette key colors defined by MaterialDynamicColors */
declare const standardPalettes: {
  primary: (ds: DynamicScheme) => TonalPalette;
  secondary: (ds: DynamicScheme) => TonalPalette;
  tertiary: (ds: DynamicScheme) => TonalPalette;
  neutral: (ds: DynamicScheme) => TonalPalette;
  neutralVariant: (ds: DynamicScheme) => TonalPalette;
};
/** StandardPaletteKey is a type representing all core palettes in standardPalettes */
type StandardPaletteKey = keyof typeof standardPalettes;
/** standardPaletteKeys is an array of all StandardPaletteKey values */
declare const standardPaletteKeys: StandardPaletteKey[];
declare const standardDynamicSchemes: {
  content: Variant.CONTENT;
  expressive: Variant.EXPRESSIVE;
  fidelity: Variant.FIDELITY;
  monochrome: Variant.MONOCHROME;
  neutral: Variant.NEUTRAL;
  tonalSpot: Variant.TONAL_SPOT;
  vibrant: Variant.VIBRANT;
  rainbow: Variant.RAINBOW;
  fruitSalad: Variant.FRUIT_SALAD;
};
type StandardDynamicSchemeKey = keyof typeof standardDynamicSchemes;
/**
 * Configuration options for defining a color in a palette.
 */
interface ColorOptions {
  /** Whether to harmonize the color with the primary color. Defaults to true */
  harmonize?: boolean;
  /** The color value to use */
  value: Color;
}
/**
 * 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> & {
  /** Error color */error?: ThemeColorOptions; /** Neutral color */
  neutral?: ThemeColorOptions; /** Neutral variant color */
  neutralVariant?: ThemeColorOptions; /** Primary color (required) - can be a Color or object with value property */
  primary: Color | {
    value: Color;
  }; /** Secondary color */
  secondary?: ThemeColorOptions; /** Tertiary color */
  tertiary?: 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 {
  /** Contrast level from -1 (minimum) to 1 (maximum). 0 represents standard. Defaults to 0 */
  contrastLevel?: number;
  /** Material color scheme to use. Defaults to 'content' */
  scheme?: StandardDynamicSchemeKey;
  /** 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: KebabCase<K>[];
  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: KebabCase<K>[];
  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 = 'error' | 'error-container' | 'primary' | 'primary-container' | 'secondary' | 'secondary-container' | 'surface' | 'surface-variant' | 'tertiary' | 'tertiary-container';
/**
 * State variant types for standard Material Design 3 colors
 */
type StandardStateVariants = { [K in StandardInteractiveColorKey as `${K}-disabled` | `${K}-dragged` | `${K}-focus` | `${K}-hover` | `${K}-pressed`]: Hct$1 };
/**
 * 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}-container-disabled` | `${T}-container-dragged` | `${T}-container-focus` | `${T}-container-hover` | `${T}-container-pressed` | `${T}-disabled` | `${T}-dragged` | `${T}-focus` | `${T}-hover` | `${T}-pressed`;
type CustomStateVariants<T extends string> = { [K in CustomStateVariantKey<KebabCase<T>>]: Hct$1 };
/**
 * 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> = Record<K, ColorOptions> & {
  primary: ColorOptions;
};
/**
 * makeThemeKeys returns the keys of makeTheme makes without calculating
 * the values.
 */
declare function makeThemeKeys<K extends string>(colors: Partial<ThemeColors<K>>): {
  keys: ("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" | "error-container" | "on-error" | "on-error-container" | "outline" | "outline-variant" | "shadow" | "scrim" | CustomDynamicColorKey<KebabCase<K>> | (KebabCase<"primary" | "secondary" | "tertiary" | "neutral" | "neutralVariant"> | 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 CustomDynamicColorKey<_$type_fest0.DelimiterCase<K, "-", {
    splitOnNumbers: false;
  }>> & ("primary" | "secondary" | "tertiary")]: Hct };
  light: { [P_1 in CustomDynamicColorKey<_$type_fest0.DelimiterCase<K, "-", {
    splitOnNumbers: false;
  }>> & ("primary" | "secondary" | "tertiary")]: Hct };
};
interface CSSThemeOptions {
  /** @defaultValue `true` */
  addStarVariantsToDark?: boolean;
  /** @defaultValue `true` */
  addStarVariantsToLight?: boolean;
  /** @defaultValue `'.dark'` */
  darkMode: boolean | string | string[];
  /** @defaultValue `'-dark'` */
  darkSuffix: string;
  /** @defaultValue `'.light'` */
  lightMode: boolean | string | string[];
  /** @defaultValue `'-light'` */
  lightSuffix: string;
  /** @defaultValue `'md-'` */
  prefix: string;
  /** @defaultValue `rgb('{r} {g} {b}')` */
  stringify: (c: Hct) => string;
}
/** 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 `0` */
  contrastLevel?: number;
  /** @defaultValue `'content'` */
  scheme?: StandardDynamicSchemeKey;
}
/**
 *  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$1>;
export { type AnyColor, type CSSThemeOptions, Color, ColorFormat, ColorGroup, ColorMap, ColorOptions, Colord, CorePaletteKey, CorePalettes, CustomColor, CustomColorOptions, CustomDynamicColorKey, CustomDynamicColors, DynamicScheme, FlatThemeColors, Hct, HctColor, HexColor, type HslColor, type HslaColor, InteractionState, type MakeCSSThemeOptions, ObjectColor, Palettes, type RgbColor, RgbaColor, StandardDynamicColorKey, StandardDynamicColors, StandardDynamicSchemeKey, StandardPaletteKey, StateColorMixParams, StateLayerOpacity, StateVariants, ThemeColorOptions, ThemeColors, ThemeGenerationOptions, TonalPalette, Variant, argb, argbFromColord, argbFromHct, argbFromHctColor, argbFromRgbaColor, argbFromString, assembleCSSColors, colorFormatter, colord, colordFromArgb, colordFromHct, colordFromHctColor, colordFromString, contentAccentToneDelta, corePaletteKeys, customDynamicColors, defaultCSSThemeOptions, defaultColors, defaultDarkSelector, defaultLightSelector, flattenColorOptions, flattenPartialColorOptions, formatCSSRules, formatCSSRulesArray, fromImageElement, generateCSSRules, generateCSSRulesArray, getStateColorMixParams, hct, hctFromArgb, hctFromColord, hctFromRgbaColor, hctFromString, hexColorPattern, hexFromArgb, hexFromColord, hexFromHct, hexFromHctColor, hexString, hsl, hslFromArgb, hslFromColord, hslFromHct, hslFromHctColor, hslFromString, hslString, isHexColor, isObjectColor, makeCSSTheme, makeColorMix, makeCustomColor, makeCustomColorFromPalette, makeCustomColors, makeCustomColorsFromPalettes, makeCustomStateVariants, makeDynamicScheme, makeStandardColorsFromScheme, makeStandardPaletteFromScheme, makeStandardPaletteKeyColorsFromScheme, makeStandardStateVariants, makeStateLayerColors, makeStateVariants, makeTheme, makeThemeFromSchemes, makeThemeKeys, makeThemePalettes, makeTonalPalette, normalizeAlpha, rgbFromRgbaColor, rgba, rgbaFromHctColor, rgbaString, splitArgb, splitHct, standardDynamicColorKeys, standardDynamicColors, standardDynamicSchemes, standardPaletteKeys, standardPalettes, stateLayerOpacities, withKnownColor, withNormalizedAlpha };
//# sourceMappingURL=index.d.mts.map