@reliverse/relico 1.1.0 → 1.1.2

package/bin/mod.d.ts

@@ -0,0 +1,364 @@
+/** A color definition: [primary, secondary]. */
+export type ColorDefinition = [string, string];
+/** A list of default color keys. */
+export declare const defaultColorKeys: readonly ["reset", "bold", "dim", "italic", "underline", "inverse", "hidden", "strikethrough", "black", "red", "green", "yellow", "blue", "magenta", "cyan", "white", "gray", "bgBlack", "bgRed", "bgGreen", "bgYellow", "bgBlue", "bgMagenta", "bgCyan", "bgWhite", "blackBright", "redBright", "greenBright", "yellowBright", "blueBright", "magentaBright", "cyanBright", "whiteBright", "bgBlackBright", "bgRedBright", "bgGreenBright", "bgYellowBright", "bgBlueBright", "bgMagentaBright", "bgCyanBright", "bgWhiteBright", "redPastel", "greenPastel", "yellowPastel", "bluePastel", "magentaPastel", "cyanPastel", "bgRedPastel", "bgGreenPastel", "bgYellowPastel", "bgBluePastel", "bgMagentaPastel", "bgCyanPastel", "orange", "pink", "purple", "teal", "lime", "brown", "navy", "maroon", "olive", "silver", "bgOrange", "bgPink", "bgPurple", "bgTeal", "bgLime", "bgBrown", "bgNavy", "bgMaroon", "bgOlive", "bgSilver", "gray10", "gray20", "gray30", "gray40", "gray50", "gray60", "gray70", "gray80", "gray90"];
+/** Union of all default color keys */
+export type DefaultColorKeys = (typeof defaultColorKeys)[number];
+/**
+ * Format keys that must NOT be overridden by the user.
+ * We'll exclude them from IntelliSense and also skip them at runtime.
+ */
+type RestrictedKeys = "reset" | "bold" | "dim" | "italic" | "underline" | "inverse" | "hidden" | "strikethrough";
+/** All the keys user is allowed to override */
+type OverridableColorKeys = Exclude<DefaultColorKeys, RestrictedKeys>;
+/** A map of user-overridable color definitions (no format keys) */
+export type OverridableColorMap = Partial<Record<OverridableColorKeys, ColorDefinition>>;
+/**
+ * `relico.config.ts` configuration options.
+ * Note: `customColors` is restricted to OverridableColorMap.
+ */
+export type RelicoConfig = {
+    /**
+     * Determines which ANSI mode is used:
+     * - 0: no color
+     * - 1: basic ANSI (8 colors)
+     * - 2: 256 color palette
+     * - 3: 24-bit truecolor (default)
+     */
+    colorLevel?: 0 | 1 | 2 | 3;
+    /**
+     * Theme to use for color definitions.
+     * - "primary": primary theme (default)
+     * - "secondary": secondary theme
+     */
+    theme?: "primary" | "secondary";
+    /**
+     * Custom color definitions.
+     * - Theming: ["primary", "secondary"]
+     */
+    customColors?: OverridableColorMap;
+    /**
+     * Enable auto-detection of terminal color support
+     * Default: true
+     */
+    autoDetect?: boolean;
+};
+export type IRelicoColors = {
+    reset(text: string | number): string;
+    bold(text: string | number): string;
+    dim(text: string | number): string;
+    italic(text: string | number): string;
+    underline(text: string | number): string;
+    inverse(text: string | number): string;
+    hidden(text: string | number): string;
+    strikethrough(text: string | number): string;
+    black(text: string | number): string;
+    red(text: string | number): string;
+    green(text: string | number): string;
+    yellow(text: string | number): string;
+    blue(text: string | number): string;
+    magenta(text: string | number): string;
+    cyan(text: string | number): string;
+    white(text: string | number): string;
+    gray(text: string | number): string;
+    bgBlack(text: string | number): string;
+    bgRed(text: string | number): string;
+    bgGreen(text: string | number): string;
+    bgYellow(text: string | number): string;
+    bgBlue(text: string | number): string;
+    bgMagenta(text: string | number): string;
+    bgCyan(text: string | number): string;
+    bgWhite(text: string | number): string;
+    blackBright(text: string | number): string;
+    redBright(text: string | number): string;
+    greenBright(text: string | number): string;
+    yellowBright(text: string | number): string;
+    blueBright(text: string | number): string;
+    magentaBright(text: string | number): string;
+    cyanBright(text: string | number): string;
+    whiteBright(text: string | number): string;
+    bgBlackBright(text: string | number): string;
+    bgRedBright(text: string | number): string;
+    bgGreenBright(text: string | number): string;
+    bgYellowBright(text: string | number): string;
+    bgBlueBright(text: string | number): string;
+    bgMagentaBright(text: string | number): string;
+    bgCyanBright(text: string | number): string;
+    bgWhiteBright(text: string | number): string;
+    redPastel(text: string | number): string;
+    greenPastel(text: string | number): string;
+    yellowPastel(text: string | number): string;
+    bluePastel(text: string | number): string;
+    magentaPastel(text: string | number): string;
+    cyanPastel(text: string | number): string;
+    bgRedPastel(text: string | number): string;
+    bgGreenPastel(text: string | number): string;
+    bgYellowPastel(text: string | number): string;
+    bgBluePastel(text: string | number): string;
+    bgMagentaPastel(text: string | number): string;
+    bgCyanPastel(text: string | number): string;
+    orange(text: string | number): string;
+    pink(text: string | number): string;
+    purple(text: string | number): string;
+    teal(text: string | number): string;
+    lime(text: string | number): string;
+    brown(text: string | number): string;
+    navy(text: string | number): string;
+    maroon(text: string | number): string;
+    olive(text: string | number): string;
+    silver(text: string | number): string;
+    bgOrange(text: string | number): string;
+    bgPink(text: string | number): string;
+    bgPurple(text: string | number): string;
+    bgTeal(text: string | number): string;
+    bgLime(text: string | number): string;
+    bgBrown(text: string | number): string;
+    bgNavy(text: string | number): string;
+    bgMaroon(text: string | number): string;
+    bgOlive(text: string | number): string;
+    bgSilver(text: string | number): string;
+    gray10(text: string | number): string;
+    gray20(text: string | number): string;
+    gray30(text: string | number): string;
+    gray40(text: string | number): string;
+    gray50(text: string | number): string;
+    gray60(text: string | number): string;
+    gray70(text: string | number): string;
+    gray80(text: string | number): string;
+    gray90(text: string | number): string;
+};
+export declare const re: IRelicoColors;
+/**
+ * Configures the library with a partial or complete
+ * `RelicoConfig`. Invalid fields are ignored.
+ */
+export declare function configure(userInput: unknown): void;
+/**
+ * Returns a color function by name (or `reset` or identity if not found).
+ * Uses cached functions for better performance.
+ */
+export declare function getColor(name: string): (text: string | number) => string;
+/**
+ * Colorizes text with a color function.
+ */
+export declare function colorize(name: string, text: string | number): string;
+/**
+ * Sets the color level (0=none, 1=basic, 2=256, 3=truecolor).
+ */
+export declare function setColorLevel(level: 0 | 1 | 2 | 3): void;
+/**
+ * Returns a custom "rgb" color function if level is truecolor, otherwise identity.
+ * Uses caching for better performance.
+ * @param r Red component (0-255)
+ * @param g Green component (0-255)
+ * @param b Blue component (0-255)
+ */
+export declare function rgb(r: number, g: number, b: number): (text: string | number) => string;
+/**
+ * Returns a custom background "bgRgb" color function.
+ * Uses caching for better performance.
+ * @param r Red component (0-255)
+ * @param g Green component (0-255)
+ * @param b Blue component (0-255)
+ */
+export declare function bgRgb(r: number, g: number, b: number): (text: string | number) => string;
+/**
+ * Creates a color function from a hex string or color name
+ * @param color Hex string (e.g., "#ff0000") or color name (e.g., "red")
+ */
+export declare function hex(color: string): (text: string | number) => string;
+/**
+ * Creates a background color function from a hex string or color name
+ * @param color Hex string (e.g., "#ff0000") or color name (e.g., "red")
+ */
+export declare function bgHex(color: string): (text: string | number) => string;
+/**
+ * Creates an HSL color from hue, saturation, and lightness values
+ * @param h Hue (0-360)
+ * @param s Saturation (0-100)
+ * @param l Lightness (0-100)
+ */
+export declare function hsl(h: number, s: number, l: number): (text: string | number) => string;
+/**
+ * Creates a background HSL color
+ * @param h Hue (0-360)
+ * @param s Saturation (0-100)
+ * @param l Lightness (0-100)
+ */
+export declare function bgHsl(h: number, s: number, l: number): (text: string | number) => string;
+/**
+ * Chain multiple color formatters together
+ * @param formatters Array of color formatters to apply in sequence
+ */
+export declare function chain(...formatters: ((text: string | number) => string)[]): (text: string | number) => string;
+/**
+ * Creates a rainbow text effect
+ * @param text The text to colorize
+ * @param saturation Saturation (0-100)
+ * @param lightness Lightness (0-100)
+ * @param options Additional options
+ * @returns The rainbow-colorized text
+ */
+export declare function rainbow(text: string, saturation?: number, lightness?: number, options?: {
+    startHue?: number;
+    endHue?: number;
+}): string;
+/**
+ * Creates a gradient text effect between multiple colors
+ * @param text The text to colorize
+ * @param colors Array of colors (hex, rgb, hsl, or named colors)
+ * @param options Additional options (smoothing, distribution)
+ * @returns The gradient-colorized text
+ */
+export declare function multiGradient(text: string, colors: string[], options?: {
+    smoothing?: number;
+    distribution?: "even" | "weighted";
+}): string;
+/**
+ * Creates a gradient text effect between two colors
+ * @param text The text to colorize
+ * @param startColor Starting color (hex, rgb, hsl, or named color)
+ * @param endColor Ending color (hex, rgb, hsl, or named color)
+ * @param options Additional options (smoothing)
+ * @returns The gradient-colorized text
+ */
+export declare function gradient(text: string, startColor: string, endColor: string, options?: {
+    smoothing?: number;
+}): string;
+/**
+ * Blend two colors together with a given ratio
+ * @param color1 First color
+ * @param color2 Second color
+ * @param ratio Blend ratio (0-1, 0 = color1, 1 = color2)
+ * @returns A formatter function with the blended color
+ */
+export declare function blend(color1: string, color2: string, ratio?: number): (text: string | number) => string;
+/**
+ * Checks if a color meets WCAG contrast guidelines against another color
+ * @param foreground Foreground color
+ * @param background Background color (defaults to white)
+ * @returns Object with contrast ratio and pass/fail for AA and AAA levels
+ */
+export declare function checkContrast(foreground: string, background?: string): {
+    ratio: number;
+    passesAA: boolean;
+    passesAAA: boolean;
+    passesAALarge: boolean;
+    passesAAALarge: boolean;
+};
+/**
+ * Find an accessible color by adjusting lightness until it meets contrast requirements
+ * @param color Base color to adjust
+ * @param background Background color to check contrast against
+ * @param targetRatio Minimum contrast ratio to achieve (4.5 = AA, 7 = AAA)
+ * @returns A color with sufficient contrast
+ */
+export declare function getAccessibleColor(color: string, background?: string, targetRatio?: number): string;
+export type ColorSupport = {
+    isColorSupported: boolean;
+    isForced: boolean;
+    isDisabled: boolean;
+    terminalName: string;
+    colorLevel: 0 | 1 | 2 | 3;
+};
+export declare const colorSupport: ColorSupport;
+/**
+ * Creates a safe background color wrapping that prevents spillover to new lines
+ * @param text The text to colorize
+ * @param bgColorFn Background color formatter function
+ * @param textColorFn Optional text color formatter function
+ * @returns Safely wrapped colored text
+ */
+export declare function colorWrap(text: string, bgColorFn: (text: string | number) => string, textColorFn?: (text: string | number) => string): string;
+/**
+ * Smart background color function that prevents background color overflow
+ * Apply background color to text while ensuring it doesn't spill over to new lines
+ * @param color Background color (hex, named, etc.)
+ * @param text Optional text to colorize immediately
+ */
+export declare function safeBg(color: string, text?: string | number): ((text: string | number) => string) | string;
+/**
+ * Apply background and foreground colors while preventing spillover
+ * @param bgColor Background color
+ * @param fgColor Foreground color
+ * @param text Optional text to colorize immediately
+ */
+export declare function safeColor(bgColor: string, fgColor: string, text?: string | number): ((text: string | number) => string) | string;
+/**
+ * Creates a color function that automatically ensures good contrast
+ * @param color Base color to use
+ * @param background Background color to check contrast against
+ * @param targetRatio Minimum contrast ratio to achieve (4.5 = AA, 7 = AAA)
+ */
+export declare function autoContrast(color: string, background?: string, targetRatio?: number): (text: string | number) => string;
+/**
+ * Creates a color scheme from a base color
+ * @param baseColor The main color to generate a scheme from
+ * @returns Object with various related colors
+ */
+export declare function createColorScheme(baseColor: string): {
+    base: (text: string | number) => string;
+    light: (text: string | number) => string;
+    dark: (text: string | number) => string;
+    bright: (text: string | number) => string;
+    pastel: (text: string | number) => string;
+    bg: (text: string | number) => string;
+    bgLight: (text: string | number) => string;
+    accent: (text: string | number) => string;
+};
+/**
+ * Creates a highlighted text with colored background and contrasting text
+ * @param text Text to highlight
+ * @param bgColor Background color
+ * @param options Additional options
+ */
+export declare function highlight(text: string, bgColor: string, options?: {
+    padding?: number;
+    border?: boolean;
+    borderColor?: string;
+}): string;
+/**
+ * Creates an ANSI link (works in supported terminals)
+ * @param text Link text to display
+ * @param url The URL to link to
+ * @param color Optional color for the link text
+ */
+export declare function link(text: string, url: string, color?: string): string;
+/**
+ * Colorize a JSON object with syntax highlighting
+ * @param obj Object to stringify and colorize
+ * @param options Options for JSON stringification
+ */
+export declare function colorizeJson(obj: unknown, options?: {
+    indent?: number;
+    compact?: boolean;
+}): string;
+/**
+ * Initialize user configuration with optional programmatic overrides
+ * @param programmaticConfig Optional configuration to override default settings
+ * @param userSettingsPrecedence If true, user file settings take precedence over programmatic
+ */
+/**
+ * Initialize user configuration with optional programmatic overrides
+ * @param programmaticConfig Optional configuration to override settings
+ * @param userSettingsPrecedence If true, user file settings take precedence over programmatic
+ */
+export declare function initUserConfig(programmaticConfig?: Partial<RelicoConfig>, userSettingsPrecedence?: boolean): Promise<void>;
+/**
+ * Provides type safety and IntelliSense for user configuration.
+ * Example usage in `relico.config.ts`:
+ * ```ts
+ * import { defineConfig } from "@reliverse/relico-cfg";
+ * export default defineConfig({
+ *   colorLevel: 3,
+ *   theme: "secondary",
+ *   customColors: {
+ *     red: ["#f00", "#c00"],
+ *     blue: ["#0af", "#08f"],
+ *     green: ["#00ff00", "#00cc00"],
+ *   },
+ * });
+ * ```
+ */
+export declare function defineConfig(cfg: RelicoConfig): RelicoConfig;
+export {};