toolbox-x 1.0.0

package/dist/stylog.cjs

@@ -0,0 +1,621 @@
+/**
+ * Copyright 2026 - present Nazmul Hassan
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+const require_primitives = require('./primitives-B26uZolQ.cjs');
+const require_css_colors = require('./css-colors-CXCDqQbG.cjs');
+const require_guards = require('./guards-C8gkvIHb.cjs');
+const require_convert = require('./convert-BrzlG-m_.cjs');
+const require_specials = require('./specials-DzLr1ZgU.cjs');
+
+//#region src/stylog/console.log.ts
+/**
+* {@link Console.log} wrapper to avoid linting issues.
+* @param data Data to log in the console.
+*/
+function _logToConsole(...data) {
+	console.log(data);
+}
+
+//#endregion
+//#region src/stylog/constants.ts
+/** ANSI styles for non-color text effects */
+const ANSI_TEXT_STYLES = /* @__PURE__ */ Object.freeze({
+	bold: ["\x1B[1m", "\x1B[22m"],
+	bolder: ["\x1B[1m", "\x1B[22m"],
+	dim: ["\x1B[2m", "\x1B[22m"],
+	italic: ["\x1B[3m", "\x1B[23m"],
+	underline: ["\x1B[4m", "\x1B[24m"],
+	strikethrough: ["\x1B[9m", "\x1B[29m"],
+	inverse: ["\x1B[7m", "\x1B[27m"]
+});
+/** Browser CSS equivalents */
+const CSS_TEXT_STYLES = /* @__PURE__ */ Object.freeze({
+	bold: "font-weight: bold",
+	bolder: "font-weight: bolder",
+	dim: "opacity: 0.7",
+	italic: "font-style: italic",
+	underline: "text-decoration: underline",
+	strikethrough: "text-decoration: line-through",
+	inverse: "filter: invert(1)"
+});
+/** Records of ANSI-16 colors with values */
+const ANSI_16_COLORS = /* @__PURE__ */ Object.freeze({
+	black: [30, 39],
+	red: [31, 39],
+	green: [32, 39],
+	yellow: [33, 39],
+	blue: [34, 39],
+	purple: [35, 39],
+	cyan: [36, 39],
+	white: [37, 39],
+	blackBright: [90, 39],
+	redBright: [91, 39],
+	greenBright: [92, 39],
+	yellowBright: [93, 39],
+	blueBright: [94, 39],
+	purpleBright: [95, 39],
+	cyanBright: [96, 39],
+	whiteBright: [97, 39],
+	bgBlack: [40, 49],
+	bgRed: [41, 49],
+	bgGreen: [42, 49],
+	bgYellow: [43, 49],
+	bgBlue: [44, 49],
+	bgPurple: [45, 49],
+	bgCyan: [46, 49],
+	bgWhite: [47, 49],
+	bgBlackBright: [100, 49],
+	bgRedBright: [101, 49],
+	bgGreenBright: [102, 49],
+	bgYellowBright: [103, 49],
+	bgBlueBright: [104, 49],
+	bgPurpleBright: [105, 49],
+	bgCyanBright: [106, 49],
+	bgWhiteBright: [107, 49]
+});
+/** Browser CSS equivalents for ANSI 16 colors */
+const CSS_16_COLORS = /* @__PURE__ */ Object.freeze({
+	black: "#000000",
+	red: "#800000",
+	green: "#008000",
+	yellow: "#808000",
+	blue: "#000080",
+	purple: "#800080",
+	cyan: "#008080",
+	white: "#c0c0c0",
+	blackBright: "#808080",
+	redBright: "#ff0000",
+	greenBright: "#00ff00",
+	yellowBright: "#ffff00",
+	blueBright: "#0000ff",
+	purpleBright: "#ff00ff",
+	cyanBright: "#00ffff",
+	whiteBright: "#ffffff",
+	bgBlack: "#000000",
+	bgRed: "#800000",
+	bgGreen: "#008000",
+	bgYellow: "#808000",
+	bgBlue: "#000080",
+	bgPurple: "#800080",
+	bgCyan: "#008080",
+	bgWhite: "#c0c0c0",
+	bgBlackBright: "#808080",
+	bgRedBright: "#ff0000",
+	bgGreenBright: "#00ff00",
+	bgYellowBright: "#ffff00",
+	bgBlueBright: "#0000ff",
+	bgPurpleBright: "#ff00ff",
+	bgCyanBright: "#00ffff",
+	bgWhiteBright: "#ffffff"
+});
+
+//#endregion
+//#region src/stylog/helpers.ts
+/**
+* * Extract the CSS color name from a background-prefixed style key.
+*
+* @param bgColor Style key starting with `bg` (e.g. `"bgRed"`).
+* @returns Extracted CSS color name.
+*/
+function _extractColorName(bgColor) {
+	return bgColor.slice(2).toLowerCase();
+}
+/** * Check if a string represents a valid `AnsiSequence`. */
+function _isAnsiSequence(seq) {
+	return require_specials.isArrayOfType(seq, require_primitives.isString) && seq?.length === 2 && (seq[0].startsWith("\x1B[48") || seq[0].startsWith("\x1B[38")) && (seq[1].startsWith("\x1B[49") || seq[1].startsWith("\x1B[39"));
+}
+/** * Check if a value represents a valid `Ansi16Value`. */
+function _isAnsi16ColorValue(value) {
+	return require_specials.isArrayOfType(value, require_primitives.isNumber) && value?.length === 2 && value[0] >= 30 && value[0] <= 107 && (value[1] === 39 || value[1] === 49);
+}
+/** * Check if a value represents a valid `CSS16Color` against `Ansi16Value`. */
+function _isCSS16Color(value) {
+	return value?.startsWith("css-") && value?.replace("css-", "") in CSS_16_COLORS;
+}
+/**
+* * Convert a `CSS16Color` value in `Hex6` format
+*
+* @param value `CSS16Color` value to convert
+* @returns Converted `CSS16Color` value in `Hex6` format
+*/
+function _css16ToHex(value) {
+	return CSS_16_COLORS?.[value?.replace("css-", "")];
+}
+
+//#endregion
+//#region src/stylog/utils.ts
+/**
+* * Detects color support level of the current terminal/shell.
+* @returns `0 = none`, `1 = basic (16 colors)`, `2 = 256 colors`, `3 = truecolor`
+*/
+function detectColorSupport() {
+	if ("NO_COLOR" in process.env) return 0;
+	if ("FORCE_COLOR" in process.env) return 3;
+	if (!process.stdout.isTTY) return 0;
+	const term = process.env.TERM ?? process.env.COLORTERM ?? "";
+	if (term === "dumb") return 0;
+	if (/\b256(color)?\b/i.test(term)) return 2;
+	if (/\btruecolor\b|\b24bit\b/i.test(term)) return 3;
+	return 1;
+}
+/**
+* * Convert `RGB` color components into an `ANSI` escape code sequence.
+*
+* @param r Red component (`0-255`).
+* @param g Green component (`0-255`).
+* @param b Blue component (`0-255`).
+* @param isBg Whether the color should be applied as background (`true`) or foreground (`false`). Defaults to `false`.
+* @returns Tuple containing the opening and closing `ANSI` escape sequences.
+*/
+function rgbToAnsi(r, g, b, isBg = false) {
+	return [`\x1b[${isBg ? 48 : 38};2;${r};${g};${b}m`, `\x1b[${isBg ? 49 : 39}m`];
+}
+/**
+* * Convert a HEX color into an `ANSI` escape code sequence.
+*
+* @param hex HEX color string. e.g. `#000000`
+* @param isBg Whether the color should be applied as background (`true`) or foreground (`false`). Defaults to `false`.
+* @returns Tuple containing the opening and closing `ANSI` escape sequences.
+*/
+function hexToAnsi(hex, isBg = false) {
+	return rgbToAnsi(...(require_convert.convertHexToRgb(hex).match(/\d+/g) || []).map(parseFloat), isBg);
+}
+/** * Check if a string represents `bgColor` with valid CSS color name. */
+function isBGColor(value) {
+	return value?.startsWith("bg") && require_guards.isCSSColor(value.slice(2).toLowerCase());
+}
+/** * Check if a string represent `TextStyle` used in `LogStyler`. */
+function isTextStyle(value) {
+	return value in CSS_TEXT_STYLES || value in ANSI_TEXT_STYLES;
+}
+
+//#endregion
+//#region src/stylog/Stylog.ts
+/**
+* @class Utility class for styling console log output with `ANSI` (`Node.js`) or `CSS` (Browser).
+*
+* @remarks
+* - Allows chaining of style methods or initializing with predefined styles.
+* - For fluent, chainable styling with zero configuration use {@link https://toolbox.nazmul-nhb.dev/docs/utilities/misc/stylog Stylog} (`LogStyler` chainable wrapper).
+*
+* @example
+* const styled = new LogStyler(['red', 'bold']);
+* styled.log('Hello World');
+*
+* const logger = new LogStyler();
+* logger.style('blue', 'dim', 'bold').log('Hello Blue');
+* logger.style('blue', 'dim', 'bold').toANSI('Hello Blue');
+* logger.style('blue', 'dim', 'bold').toCSS('Hello Blue');
+*/
+var LogStyler = class LogStyler {
+	#styles;
+	/**
+	* * Creates a new `LogStyler` instance.
+	*
+	* @param styles - Optional array of initial styles to apply (e.g., ['red', 'bold']). Defaults to an empty array.
+	*
+	* @example
+	* const styled = new LogStyler(['red', 'bold']);
+	* styled.log('Hello World');
+	*
+	* const logger = new LogStyler();
+	* logger.style('blue', 'dim', 'bold').log('Hello Blue');
+	* logger.style('blue', 'dim', 'bold').toANSI('Hello Blue');
+	* logger.style('blue', 'dim', 'bold').toCSS('Hello Blue');
+	*/
+	constructor(styles = []) {
+		this.#styles = styles;
+	}
+	#applyStyles(...style) {
+		return createStylogProxy(new LogStyler([...this.#styles, ...style]));
+	}
+	/**
+	* * Chain multiple styles to the input.
+	*
+	* @param style - One or more styles to apply (color, background, or text style).
+	* @returns A new StylogChain instance with the additional styles applied.
+	*
+	* @remarks
+	*  - When chaining similar styles, only the last one(s) takes effect.
+	*  - All colors applied through `style()` method are `truecolor` in form, to apply `ANSI-16` colors, use `ansi16()` method.
+	*
+	* @example
+	* // Single style
+	* Stylog.style('red').log('Red text');
+	* Stylog.style('red').toANSI('Red text');
+	* Stylog.style('red').toCSS('Red text');
+	*
+	* @example
+	* // Multiple styles at once
+	* Stylog.style('red', 'bold', 'underline').log('Red bold underlined text');
+	* Stylog.style('red', 'bold', 'underline').toANSI('Red bold underlined text');
+	* Stylog.style('red', 'bold', 'underline').toCSS('Red bold underlined text');
+	*
+	* @example
+	* // Mixed foreground and background
+	* Stylog.style('white', 'bgBlue').log('White text on blue background');
+	* Stylog.style('white', 'bgBlue').toANSI('White text on blue background');
+	* Stylog.style('white', 'bgBlue').toCSS('White text on blue background');
+	*
+	* @example
+	* // Building on existing styles
+	* const errorStyle = Stylog.style('red', 'bold');
+	* errorStyle.style('underline').log('Red bold underlined error');
+	* errorStyle.style('underline').toANSI('Red bold underlined error');
+	* errorStyle.style('underline').toCSS('Red bold underlined error');
+	*/
+	style(...style) {
+		return this.#applyStyles(...style);
+	}
+	/**
+	* * Apply ANSI 16-color styling to the text.
+	*
+	* @param color - ANSI 16-color name (e.g., 'red', 'cyanBright', 'bgRed').
+	* @returns A new `StylogChain` instance with the `ANSI 16-color` style applied.
+	*
+	* @remarks
+	*  - Only one argument (color) can be passed on a single call.
+	*  - Color applied through `ansi16()` method is `truecolor` in form, to apply `truecolor` colors, use `style()` method.
+	*
+	* @example
+	* // Basic usage
+	* Stylog.ansi16('red').log('Error message');
+	*
+	* @example
+	* // Chaining with other styles
+	* Stylog.ansi16('redBright').bold.italic.log('Bright red bold italic');
+	* Stylog.ansi16('redBright').bold.italic.toANSI('Bright red bold italic');
+	* Stylog.ansi16('redBright').bold.italic.toCSS('Bright red bold italic');
+	*
+	* @example
+	* // Background colors
+	* Stylog.ansi16('bgRed').log('Red background');
+	* Stylog.ansi16('bgRed').toANSI('Red background');
+	* Stylog.ansi16('bgRed').toCSS('Red background');
+	*/
+	ansi16(color) {
+		return this.#applyStyles(ANSI_16_COLORS[color], `css-${color}`);
+	}
+	/**
+	* * Returns styled tuple `[format, cssList]` for Browser.
+	*
+	* @remarks
+	* - This method is specifically designed for browser environments and returns a tuple containing the formatted string with `%c` placeholder and an array of CSS styles (`string[]`).
+	* - Use this when you need direct access to the CSS styling for custom browser output.
+	* - If you want to format with ANSI escape codes, consider using {@link https://toolbox.nazmul-nhb.dev/docs/classes/LogStyler#toansiinput-stringify toANSI} method.
+	*
+	* @param input - Input to style before printing in the shell.
+	* @param stringify - Whether to apply `JSON.stringify()` before styling. Defaults to `false`.
+	* @returns Tuple `[format, cssList]` where:
+	*   - `format`: String with `%c` placeholder for CSS styling
+	*   - `cssList`: Array of CSS style strings
+	*
+	* @example
+	* // Basic usage in browser
+	* const styler = new LogStyler(['red', 'bold']);
+	* const [format, cssList] = styler.toCSS('Error message');
+	* // format: "%cError message"
+	* // cssList: ["color: #FF0000", "font-weight: bold"]
+	*
+	* @example
+	* // Custom browser output handling
+	* const styled = new LogStyler(['blue', 'bgYellow', 'italic']);
+	* const [format, styles] = styled.toCSS('Warning', true);
+	*
+	* // Use with custom logging function
+	* function customLog(formatted: string, styles: string[]) {
+	*   const styleString = styles.join('; ');
+	*   console.log(formatted, styleString);
+	* }
+	* customLog(format, styles);
+	*
+	* @example
+	* // With object stringification
+	* const dataOutput = new LogStyler(['green']).toCSS({ id: 123 }, true);
+	* // format: "%c{\"id\":123}"
+	* // cssList: ["color: #008000"]
+	*/
+	toCSS(input, stringify = false) {
+		const stringified = stringify === true ? JSON.stringify(input) : `${input}`;
+		const cssList = [];
+		for (const style of this.#styles) if (require_primitives.isString(style)) {
+			if (isTextStyle(style)) cssList.push(CSS_TEXT_STYLES[style]);
+			else if (isBGColor(style)) {
+				const color = require_css_colors.CSS_COLORS[_extractColorName(style)];
+				cssList.push(`background: ${color}`);
+			} else if (require_guards.isCSSColor(style)) {
+				const color = require_css_colors.CSS_COLORS[style];
+				cssList.push(`color: ${color}`);
+			} else if (this.#isValidHexOrRGB(style)) if (style.startsWith("bg-")) cssList.push(`background: ${style?.replace("bg-", "")}`);
+			else cssList.push(`color: ${style}`);
+			else if (_isCSS16Color(style)) {
+				const color = _css16ToHex(style);
+				const colorValue = style.startsWith("css-bg") ? `background: ${color}` : `color: ${color}`;
+				cssList.push(colorValue);
+			}
+		}
+		return [`%c${stringified}`, cssList];
+	}
+	/**
+	* * Returns the input as a styled string with ANSI escape codes.
+	*
+	* @remarks
+	* - This method returns ANSI-formatted strings suitable for environments that support ANSI escape codes (terminals, modern browser consoles, etc.).
+	* - For unsupported browsers, consider using the {@link https://toolbox.nazmul-nhb.dev/docs/classes/LogStyler#loginput-stringify log} method to print directly or {@link https://toolbox.nazmul-nhb.dev/docs/classes/LogStyler#tocssinput-stringify toCSS} to get styled tuple `[format, cssList]` for Browser.
+	*
+	* @param input - Input to style before printing in the shell.
+	* @param stringify - Whether to apply `JSON.stringify()` before styling. Defaults to `false`.
+	* @returns The styled string with ANSI escape codes.
+	*
+	* @example
+	* const styled = new LogStyler(['red', 'bold']);
+	* const errorMessage = styled.toANSI('Error occurred, using LogStyler');
+	* // Or with Stylog
+	* const errorMessage = Stylog.red.bold.toANSI('Error occurred, using Stylog');
+	* // Returns: "\x1b[31m\x1b[1mError occurred, using Stylog\xx1b[22m\x1b[39m"
+	*
+	* @example
+	* // Use in console (terminal or modern browser consoles)
+	* console.error(errorMessage);
+	* console.info(Stylog.red.bold.toANSI('I support ANSI!'));
+	*/
+	toANSI(input, stringify = false) {
+		const stringified = stringify === true ? JSON.stringify(input) : `${input}`;
+		let openSeq = "", closeSeq = "";
+		let fgOpenSeq = "", bgOpenSeq = "";
+		const reopenSequences = /* @__PURE__ */ new Map();
+		for (const style of this.#styles) if (require_primitives.isString(style)) {
+			if (isTextStyle(style)) {
+				const [open, close] = ANSI_TEXT_STYLES[style];
+				openSeq += open;
+				closeSeq = close + closeSeq;
+				reopenSequences.set(close, (reopenSequences.get(close) ?? "") + open);
+			} else if (isBGColor(style)) {
+				const hex = require_css_colors.CSS_COLORS[_extractColorName(style)];
+				const [open, close] = hexToAnsi(hex, true);
+				openSeq += open;
+				closeSeq = close + closeSeq;
+				bgOpenSeq = open;
+			} else if (require_guards.isCSSColor(style)) {
+				const hex = require_css_colors.CSS_COLORS[style];
+				const [open, close] = hexToAnsi(hex, false);
+				openSeq += open;
+				closeSeq = close + closeSeq;
+				fgOpenSeq = open;
+			}
+		} else if (_isAnsiSequence(style)) {
+			openSeq += style[0];
+			closeSeq = style[1] + closeSeq;
+			if (style[1] === "\x1B[49m") bgOpenSeq = style[0];
+			else if (style[1] === "\x1B[39m") fgOpenSeq = style[0];
+		} else if (_isAnsi16ColorValue(style)) {
+			const [open, close] = style.map((s) => `\x1b[${s}m`);
+			openSeq += open;
+			closeSeq = close + closeSeq;
+			if (close === "\x1B[49m") bgOpenSeq = open;
+			else if (close === "\x1B[39m") fgOpenSeq = open;
+		}
+		if (!detectColorSupport()) return stringified;
+		else {
+			let nestedStr = stringified;
+			if (nestedStr.includes("\x1B[")) {
+				if (fgOpenSeq) nestedStr = nestedStr.replaceAll("\x1B[39m", `\x1b[39m${fgOpenSeq}`);
+				if (bgOpenSeq) nestedStr = nestedStr.replaceAll("\x1B[49m", `\x1b[49m${bgOpenSeq}`);
+				for (const [close, reopen] of reopenSequences) nestedStr = nestedStr.replaceAll(close, `${close}${reopen}`);
+				if (openSeq) nestedStr = nestedStr.replaceAll("\x1B[0m", `\x1b[0m${openSeq}`);
+			}
+			return openSeq.concat(nestedStr, closeSeq);
+		}
+	}
+	/**
+	* * Print styled input to the console.
+	*
+	* @param input Input to print to the shell/console.
+	* @param stringify Whether to apply `JSON.stringify()` before printing. Defaults to `false`.
+	*/
+	log(input, stringify = false) {
+		if (require_specials.isBrowser()) {
+			const [fmt, cssList] = this.toCSS(input, stringify);
+			_logToConsole(fmt, cssList.join(";"));
+		} else _logToConsole(this.toANSI(input, stringify));
+	}
+	#isValidHexOrRGB(color) {
+		const pure = color?.replace("bg-", "");
+		return require_guards.isHex6(pure) || require_guards.isRGB(pure);
+	}
+	#sanitizeHex(code) {
+		return code?.trim()?.startsWith("#") ? code?.trim() : `#${code?.trim()}`;
+	}
+	#handleHex(code, isBg = false) {
+		const sanitized = this.#sanitizeHex(code);
+		if (!require_guards.isHex6(sanitized)) return this.#applyStyles();
+		const ansi = hexToAnsi(sanitized, isBg);
+		return this.#applyStyles(isBg ? `bg-${sanitized}` : sanitized, ansi);
+	}
+	/**
+	* * Apply a HEX color to the text foreground.
+	*
+	* @param code - HEX color string (e.g., `'#4682B4'` or `'4682B4'`).
+	* @returns A new `StylogChain` instance with the HEX color applied.
+	*
+	* @example
+	* // With hash prefix
+	* Stylog.hex('#4682B4').log('Steel blue text');
+	* Stylog.hex('#4682B4').toANSI('Steel blue text');
+	* Stylog.hex('#4682B4').toCSS('Steel blue text');
+	*
+	* @example
+	* // Without hash prefix
+	* Stylog.hex('4682B4').log('Steel blue text');
+	* Stylog.hex('4682B4').toANSI('Steel blue text');
+	* Stylog.hex('4682B4').toCSS('Steel blue text');
+	*
+	* @example
+	* // Chaining with other styles
+	* Stylog.hex('#FF0000').bold.log('Red bold text');
+	* Stylog.hex('#FF0000').bold.toANSI('Red bold text');
+	* Stylog.hex('#FF0000').bold.toCSS('Red bold text');
+	*/
+	hex(code) {
+		return this.#handleHex(code, false);
+	}
+	/**
+	* * Apply a HEX color to the text background.
+	*
+	* @param code - HEX color string (e.g., `'#4682B4'` or `'4682B4'`).
+	* @returns A new StylogChain instance with the HEX background color applied.
+	*
+	* @example
+	* // With hash prefix
+	* Stylog.bgHex('#4682B4').log('Steel blue background');
+	* Stylog.bgHex('#4682B4').toANSI('Steel blue background');
+	* Stylog.bgHex('#4682B4').toCSS('Steel blue background');
+	*
+	* @example
+	* // Without hash prefix
+	* Stylog.bgHex('4682B4').log('Steel blue background');
+	* Stylog.bgHex('4682B4').toANSI('Steel blue background');
+	* Stylog.bgHex('4682B4').toCSS('Steel blue background');
+	*
+	* @example
+	* // Chaining with foreground color
+	* Stylog.white.bgHex('#000000').log('White text on black background');
+	* Stylog.white.bgHex('#000000').toANSI('White text on black background');
+	* Stylog.white.bgHex('#000000').toCSS('White text on black background');
+	*/
+	bgHex(code) {
+		return this.#handleHex(code, true);
+	}
+	#extractColorValues(code) {
+		return ((code?.trim())?.match(/[\d.]+%?/g) || []).map(parseFloat);
+	}
+	#isValidRGB(...value) {
+		return value.every(require_guards._isValidRGBComponent);
+	}
+	#handleRGB(code, green, blue, isBg = false) {
+		if (require_primitives.isString(code)) {
+			const rgb = this.#extractColorValues(code);
+			if (this.#isValidRGB(...rgb)) return this.#applyStyles(rgbToAnsi(...rgb, isBg), isBg ? `bg-rgb(${rgb[0]}, ${rgb[1]}, ${rgb[2]})` : `rgb(${rgb[0]}, ${rgb[1]}, ${rgb[2]})`);
+			else return this.#applyStyles();
+		} else if (require_primitives.isNumber(code) && require_primitives.isNumber(green) && require_primitives.isNumber(blue)) if (this.#isValidRGB(code, green, blue)) return this.#applyStyles(rgbToAnsi(code, green, blue, isBg), isBg ? `bg-rgb(${code}, ${green}, ${blue})` : `rgb(${code}, ${green}, ${blue})`);
+		else return this.#applyStyles();
+		else return this.#applyStyles();
+	}
+	/** * Apply an RGB color to the text foreground using string or individual components. */
+	rgb(code, green, blue) {
+		return this.#handleRGB(code, green, blue, false);
+	}
+	/** * Apply an RGB color to the text background using string or individual components. */
+	bgRGB(code, green, blue) {
+		return this.#handleRGB(code, green, blue, true);
+	}
+	#isValidHSL(h, s, l) {
+		return require_guards._isValidHue(h) && require_guards._isValidPercentage(s) && require_guards._isValidPercentage(l);
+	}
+	#handleHSL(code, saturation, lightness, isBg = false) {
+		if (require_primitives.isString(code)) {
+			const hsl = this.#extractColorValues(code);
+			if (this.#isValidHSL(...hsl)) return this.#handleRGB(require_convert.convertHslToRgb(...hsl), void 0, void 0, isBg);
+			else return this.#applyStyles();
+		} else if (require_primitives.isNumber(code) && require_primitives.isNumber(saturation) && require_primitives.isNumber(lightness)) if (this.#isValidHSL(code, saturation, lightness)) return this.#handleRGB(require_convert.convertHslToRgb(code, saturation, lightness), void 0, void 0, isBg);
+		else return this.#applyStyles();
+		else return this.#applyStyles();
+	}
+	/** * Apply an HSL color to the text foreground using string or individual components. */
+	hsl(code, saturation, lightness) {
+		return this.#handleHSL(code, saturation, lightness, false);
+	}
+	/** * Apply an HSL color to the text background using string or individual components. */
+	bgHSL(code, saturation, lightness) {
+		return this.#handleHSL(code, saturation, lightness, true);
+	}
+};
+/**
+* * Create a proxied instance of `LogStyler` that supports dynamic style chaining.
+*
+* @param styler Base `LogStyler` instance.
+* @returns Proxied `LogStyler` instance with dynamic chaining support (`StylogChain`).
+*/
+function createStylogProxy(styler) {
+	return new Proxy(styler, { get(target, prop) {
+		if (prop in target) {
+			const value = target[prop];
+			if (typeof value === "function") return value.bind(target);
+			else return value;
+		}
+		if (require_guards.isCSSColor(prop) || isBGColor(prop) || isTextStyle(prop)) return createStylogProxy(target.style(prop));
+	} });
+}
+/**
+* * Styled console logger with chainable, type-safe color and text effects for both `Node.js` (`ANSI true-color`) and browsers (`CSS` via `%c`).
+*
+* @remarks
+* - Chain any mix of foreground colors (e.g. `green`), background colors (e.g. `bgBlue`), and text styles (e.g. `bold`, `italic`, `underline`).
+* - In browsers, styles are applied using `CSS`; in `Node.js`, `ANSI` escape codes are used.
+* - When multiple styles of the same category are chained, the last one wins.
+* - Use `.log(value, stringify?)` to print; set `stringify` to `true` to serialize with `JSON.stringify`.
+* - If you need custom reusable style configurations, use {@link https://toolbox.nazmul-nhb.dev/docs/classes/LogStyler Stylog} class.
+*
+* @example
+* // Simple color
+* Stylog.green.log('Ready');
+*
+* @example
+* // Foreground + background + effect, with JSON stringification
+* Stylog.green.bgBlue.bold.log({ a: 121 }, true);
+*
+* @example
+* // Reusable base chain
+* const base = Stylog.underline;
+* base.red.log('Error');
+* base.error.log('Error');
+* base.bgYellow.bold.log('Caution');
+*
+* @example
+* // Works in the browser console too
+* Stylog.cornflowerblue.italic.log('Hello from the browser');
+*/
+const Stylog = createStylogProxy(new LogStyler());
+
+//#endregion
+exports.LogStyler = LogStyler;
+exports.Stylog = Stylog;
+exports.detectColorSupport = detectColorSupport;
+exports.hexToAnsi = hexToAnsi;
+exports.isBGColor = isBGColor;
+exports.isTextStyle = isTextStyle;
+exports.rgbToAnsi = rgbToAnsi;

package/dist/stylog.d.cts

@@ -0,0 +1,49 @@
+/**
+ * Copyright 2026 - present Nazmul Hassan
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { _ as Hex } from "./Color-B3mgF9Dh.cjs";
+import { a as AnsiSequence, n as Stylog, o as BGColor, t as LogStyler, u as TextStyle } from "./Stylog-Df7eq3-j.cjs";
+
+//#region src/stylog/utils.d.ts
+/**
+ * * Detects color support level of the current terminal/shell.
+ * @returns `0 = none`, `1 = basic (16 colors)`, `2 = 256 colors`, `3 = truecolor`
+ */
+declare function detectColorSupport(): 0 | 1 | 2 | 3;
+/**
+ * * Convert `RGB` color components into an `ANSI` escape code sequence.
+ *
+ * @param r Red component (`0-255`).
+ * @param g Green component (`0-255`).
+ * @param b Blue component (`0-255`).
+ * @param isBg Whether the color should be applied as background (`true`) or foreground (`false`). Defaults to `false`.
+ * @returns Tuple containing the opening and closing `ANSI` escape sequences.
+ */
+declare function rgbToAnsi(r: number, g: number, b: number, isBg?: boolean): AnsiSequence;
+/**
+ * * Convert a HEX color into an `ANSI` escape code sequence.
+ *
+ * @param hex HEX color string. e.g. `#000000`
+ * @param isBg Whether the color should be applied as background (`true`) or foreground (`false`). Defaults to `false`.
+ * @returns Tuple containing the opening and closing `ANSI` escape sequences.
+ */
+declare function hexToAnsi(hex: Hex, isBg?: boolean): AnsiSequence;
+/** * Check if a string represents `bgColor` with valid CSS color name. */
+declare function isBGColor(value: string): value is BGColor;
+/** * Check if a string represent `TextStyle` used in `LogStyler`. */
+declare function isTextStyle(value: string): value is TextStyle;
+//#endregion
+export { LogStyler, Stylog, detectColorSupport, hexToAnsi, isBGColor, isTextStyle, rgbToAnsi };