/** * Theming system for colorized help output. * * Provides ANSI color codes, built-in themes (default, mono, ocean, warm), and * utilities for creating custom themes. Each theme defines colors for semantic * elements like flags, commands, descriptions, and section headers. Themes can * be customized by overriding individual color properties. * * @packageDocumentation */ import { stripVTControlCharacters } from 'node:util'; /** * Strip all ANSI escape codes from a string. * * @group Terminal */ export declare const stripAnsi: typeof stripVTControlCharacters; /** * A bargs color theme. All color properties are optional and fall back to the * default theme. * * @group Theming */ export interface Theme { colors?: Partial; } /** * Color codes for each semantic element in help output. Empty string means no * color (passthrough). * * @group Theming */ export interface ThemeColors { /** Command names (e.g., "init", "build") */ command: string; /** Command aliases (e.g., "a", "ls") - shown dimmer than command names */ commandAlias: string; /** The "default: " label text */ defaultText: string; /** Default value annotations (e.g., "false", ""hello"") */ defaultValue: string; /** Description text for options/commands */ description: string; /** Epilog text (homepage, repository) */ epilog: string; /** Example code/commands */ example: string; /** Flag names (e.g., "--verbose", "-v") */ flag: string; /** Positional argument names (e.g., "") */ positional: string; /** CLI name shown in header (e.g., "myapp") */ scriptName: string; /** Section headers (e.g., "USAGE", "OPTIONS") */ sectionHeader: string; /** Type annotations (e.g., "[string]", "[number]") */ type: string; /** URL text (for linkified URLs) */ url: string; /** Usage line text */ usage: string; } /** * Theme input - either a theme name or a custom Theme object. * * @group Theming */ export type ThemeInput = keyof typeof themes | Theme; /** * Internal resolved theme with all colors defined. */ interface ResolvedTheme { colors: ThemeColors; } /** * ANSI escape codes for building custom themes. * * Includes text styles (bold, italic, underline, etc.), foreground colors, * bright foreground colors, background colors, and bright background colors. * * @group Theming */ export declare const ansi: { readonly bgBlack: "\u001B[40m"; readonly bgBlue: "\u001B[44m"; readonly bgBrightBlack: "\u001B[100m"; readonly bgBrightBlue: "\u001B[104m"; readonly bgBrightCyan: "\u001B[106m"; readonly bgBrightGreen: "\u001B[102m"; readonly bgBrightMagenta: "\u001B[105m"; readonly bgBrightRed: "\u001B[101m"; readonly bgBrightWhite: "\u001B[107m"; readonly bgBrightYellow: "\u001B[103m"; readonly bgCyan: "\u001B[46m"; readonly bgGreen: "\u001B[42m"; readonly bgMagenta: "\u001B[45m"; readonly bgRed: "\u001B[41m"; readonly bgWhite: "\u001B[47m"; readonly bgYellow: "\u001B[43m"; readonly black: "\u001B[30m"; readonly blue: "\u001B[34m"; readonly bold: "\u001B[1m"; readonly brightBlack: "\u001B[90m"; readonly brightBlue: "\u001B[94m"; readonly brightCyan: "\u001B[96m"; readonly brightGreen: "\u001B[92m"; readonly brightMagenta: "\u001B[95m"; readonly brightRed: "\u001B[91m"; readonly brightWhite: "\u001B[97m"; readonly brightYellow: "\u001B[93m"; readonly cyan: "\u001B[36m"; readonly dim: "\u001B[2m"; readonly green: "\u001B[32m"; readonly hidden: "\u001B[8m"; readonly inverse: "\u001B[7m"; readonly italic: "\u001B[3m"; readonly magenta: "\u001B[35m"; readonly red: "\u001B[31m"; readonly reset: "\u001B[0m"; readonly strikethrough: "\u001B[9m"; readonly underline: "\u001B[4m"; readonly white: "\u001B[37m"; readonly yellow: "\u001B[33m"; }; /** * Built-in themes. * * @group Theming */ export declare const themes: { /** Default colorful theme */ readonly default: { readonly colors: { readonly command: string; readonly commandAlias: string; readonly defaultText: string; readonly defaultValue: string; readonly description: string; readonly epilog: string; readonly example: string; readonly flag: string; readonly positional: string; readonly scriptName: string; readonly sectionHeader: string; readonly type: string; readonly url: string; readonly usage: string; }; }; /** No colors (monochrome) */ readonly mono: { readonly colors: { readonly command: ""; readonly commandAlias: ""; readonly defaultText: ""; readonly defaultValue: ""; readonly description: ""; readonly epilog: ""; readonly example: ""; readonly flag: ""; readonly positional: ""; readonly scriptName: ""; readonly sectionHeader: ""; readonly type: ""; readonly url: ""; readonly usage: ""; }; }; /** Ocean theme - blues and greens (bright) */ readonly ocean: { readonly colors: { readonly command: string; readonly commandAlias: "\u001B[36m"; readonly defaultText: "\u001B[34m"; readonly defaultValue: "\u001B[32m"; readonly description: "\u001B[37m"; readonly epilog: "\u001B[34m"; readonly example: string; readonly flag: "\u001B[96m"; readonly positional: "\u001B[92m"; readonly scriptName: string; readonly sectionHeader: "\u001B[94m"; readonly type: "\u001B[36m"; readonly url: "\u001B[96m"; readonly usage: "\u001B[37m"; }; }; /** Warm theme - reds and yellows */ readonly warm: { readonly colors: { readonly command: string; readonly commandAlias: string; readonly defaultText: string; readonly defaultValue: "\u001B[93m"; readonly description: "\u001B[37m"; readonly epilog: string; readonly example: string; readonly flag: "\u001B[93m"; readonly positional: "\u001B[91m"; readonly scriptName: string; readonly sectionHeader: "\u001B[31m"; readonly type: "\u001B[33m"; readonly url: "\u001B[93m"; readonly usage: "\u001B[37m"; }; }; }; /** * Default theme export for convenience. * * @group Theming */ export declare const defaultTheme: { readonly colors: { readonly command: string; readonly commandAlias: string; readonly defaultText: string; readonly defaultValue: string; readonly description: string; readonly epilog: string; readonly example: string; readonly flag: string; readonly positional: string; readonly scriptName: string; readonly sectionHeader: string; readonly type: string; readonly url: string; readonly usage: string; }; }; /** * Resolve a theme input to a fully resolved Theme with all colors defined. * Missing colors fall back to the default theme. * * @function */ export declare const getTheme: (input: ThemeInput) => ResolvedTheme; /** * Style function that wraps text with ANSI codes. * * @group Theming */ export type StyleFn = (text: string) => string; /** * Styler object with methods for each semantic element. * * @group Theming */ export interface Styler { command: StyleFn; commandAlias: StyleFn; defaultText: StyleFn; defaultValue: StyleFn; description: StyleFn; epilog: StyleFn; example: StyleFn; flag: StyleFn; positional: StyleFn; scriptName: StyleFn; sectionHeader: StyleFn; type: StyleFn; url: StyleFn; usage: StyleFn; } /** * Create a Styler from a Theme. If the theme has missing colors, they fall back * to the default theme. * * @function * @group Theming */ export declare const createStyler: (theme: Theme) => Styler; export {}; //# sourceMappingURL=theme.d.ts.map