@poupe/tailwindcss

import { StandardDynamicSchemeKey, StandardPaletteKey, ColorMap } from '@poupe/theme-builder'; import { KebabCase } from 'type-fest'; import { Color, Hct } from '@poupe/theme-builder/core'; import { PluginWithOptions } from '../utils.mjs'; import { PluginAPI } from 'tailwindcss/plugin'; /** * This module provides utilities for generating, validating, and managing color shades * in a design system. It converts colors to different shade variants based on the HCT * (Hue, Chroma, Tone) color space, which provides perceptually consistent color gradations. * * Key features: * - Defines standard shade scales (50-950) * - Validates shade values for consistency * - Converts between color formats and shade values * - Supports custom shade definitions with flexible configuration * - Generates color palettes based on a single color reference * * @example * ``` * // Generate standard shades from a color * const blueShades = makeHexShades('#0047AB'); * * // Generate custom shades * const customShades = makeHexShades('#0047AB', [100, 300, 500, 700, 900]); * ``` */ /** Represents the possible types for color shades: an array of numbers or false */ type Shades = number[] | false; /** Default color shades used when no custom shades are specified, representing a standard range of color intensity from lightest (50) to darkest (950) */ declare const defaultShades: number[]; /** @returns true if the given number is a valid shade value */ declare function validShade(n: number): boolean; /** * Generates a set of Hct color objects for each specified shade value. * * This function creates a palette of colors by varying the tone (lightness) while * preserving the hue and chroma of the input color. It maps each shade value to a * corresponding HCT color object. * * @param color - The base color to generate shades from * @param shades - An array of shade values (numbers between 1-999) or `false` to disable shade generation * * @returns A record mapping each shade value to its corresponding Hct color object, * or `undefined` if the provided shades are invalid or disabled * * @example * ``` * // Generate standard shades from a color * const blueHct = hct('#0047AB'); * const blueShades = makeShades(blueHct, [100, 300, 500, 700]); * // Result: { 100: Hct, 300: Hct, 500: Hct, 700: Hct } * * // Disable shades * const noShades = makeShades(blueHct, false); * // Result: undefined * ``` */ declare function makeShades(color: Color, shades: false): undefined; declare function makeShades<K extends number>(color: Color, shades: K[]): Record<K, Hct>; declare function makeShades<K extends number>(color: Color, shades: K[] | false): Record<K, Hct> | undefined; /** * Generates a set of hex color values for each specified shade. * * This is a convenience wrapper around `makeShades()` that converts the Hct color objects * to hexadecimal color strings for easier use in UI components and CSS. * * @param color - The base color to generate shades from * @param shades - An array of shade values, or `false` to disable shade generation. * Defaults to the standard shade scale (50-950) * * @returns A record mapping each shade value to its corresponding hex color string, * or `undefined` if the provided shades are invalid or disabled * * @example * ``` * // Generate standard hex shades * const blueHexShades = makeHexShades('#0047AB'); * // Result: { 50: '#E6F0FF', 100: '#CCE0FF', ... 950: '#00142E' } * * // Generate custom hex shades * const customShades = makeHexShades('#0047AB', [100, 500, 900]); * // Result: { 100: '#CCE0FF', 500: '#0047AB', 900: '#00183D' } * * // Disable shades * const noShades = makeHexShades('#0047AB', false); * // Result: undefined * ``` */ declare function makeHexShades(color: Color, shades?: Shades): { [k: string]: `#${string}`; } | undefined; type Theme = { readonly options: ThemeOptions; readonly paletteKeys: string[]; readonly keys: string[]; readonly dark: ColorMap<string> | undefined; readonly light: ColorMap<string> | undefined; readonly colors: Record<string, ThemeColorConfig>; }; type ThemeColorConfig = { value: string; shades?: Record<number, string>; }; /** * Configuration options for defining a theme with customizable color schemes and styling. * @typeParam K - A generic type parameter representing additional color keys. **/ type ThemeOptions<K extends string = string> = { /** Enable debug mode for theme generation. @defaultValue `false` */ debug?: boolean; /** Prefix for theme-related class names, defaults to 'md-'. @defaultValue `'md-'` */ themePrefix: string; /** Prefix for surface class names, defaults to 'surface-'. * Set to `false` to disable surface generation. * @defaultValue `'surface-'` * */ surfacePrefix: string | false; /** Prefix for shape class names, defaults to 'shape-'. * Set to `false` to disable shape generation. * @defaultValue `'shape-'` * */ shapePrefix: string | false; /** Flag to omit theme generation, @defaultValue `false` */ omitTheme: boolean; /** Flag to extend existing color palette, @defaultValue `false` */ extendColors: boolean; /** Dynamic color scheme type, @defaultValue `'content'` */ scheme: StandardDynamicSchemeKey; /** Theme contrast level, @defaultValue `0` */ contrastLevel: number; /** Suffix for dark theme variants, @defaultValue `''` */ darkSuffix: string; /** Suffix for light theme variants, @defaultValue `''` */ lightSuffix: string; /** Color shade values used in theme generation, * @defaultValue `[50, 100, 200, 300, 400, 500, 600, 700, 800, 900, 950]` **/ shades: Shades; /** Disable print mode, @defaultValue `false` */ disablePrintMode?: boolean; /** Use CSS color-mix() for state colors instead of pre-calculated values * @defaultValue false */ useColorMix?: boolean; /** Color configuration for the theme. */ colors: ThemeColors<K>; }; /** * Defines the color configuration for a theme, including primary and optional additional colors. * @typeParam K - A generic type parameter representing custom color keys. * @remarks * This type allows defining: * - A required primary color configuration * - Optional standard palette colors (excluding primary) * - Custom color keys transformed to kebab-case */ type ThemeColors<K extends string> = { primary: string | ThemeColorOptions; } & { [name in Exclude<StandardPaletteKey, 'primary'>]?: string | ThemeColorOptions; } & { [name in KebabCase<K>]: boolean | string | ThemeColorOptions; }; /** * Defines the options for a color configuration within a theme. * @remarks * This type allows defining: * - The color value, either a string or an object with default and shade values. * - Whether the color should be harmonized. * - The shades associated with the color. */ type ThemeColorOptions = { value?: string; harmonized?: boolean; shades?: Shades | true; /** @defaultValue `[50, 100, 200, 300, 400, 500, 600, 700, 800, 900, 950]` */ }; declare const defaultPrimaryColor = "#74bef5"; declare const defaultThemePrefix = "md-"; declare const defaultThemeDarkSuffix = ""; declare const defaultThemeLightSuffix = ""; declare const defaultThemeContrastLevel = 0; declare const defaultThemeScheme: StandardDynamicSchemeKey; declare const defaultSurfacePrefix = "surface-"; declare const defaultShapePrefix = "shape-"; /** poupe plugin for tailwindcss v4 for config use */ declare const themePlugin: PluginWithOptions<Partial<ThemeOptions>>; /** uses Tailwind CSS's PluginAPI to apply a Theme */ declare function themePluginFunction(api: PluginAPI, theme: Theme): void; /** @returns a Theme built using the provided ThemeOptions. defaults are automatically applied */ declare function makeThemeFromPartialOptions(options?: Partial<ThemeOptions>): Theme; export { type Shades as S, type ThemeOptions as T, type Theme as a, themePluginFunction as b, makeHexShades as c, defaultShades as d, makeShades as e, type ThemeColorConfig as f, type ThemeColors as g, type ThemeColorOptions as h, defaultPrimaryColor as i, defaultThemePrefix as j, defaultThemeDarkSuffix as k, defaultThemeLightSuffix as l, makeThemeFromPartialOptions as m, defaultThemeContrastLevel as n, defaultThemeScheme as o, defaultSurfacePrefix as p, defaultShapePrefix as q, themePlugin as t, validShade as v };