@crustjs/style 0.0.2 → 0.0.3

package/README.md

@@ -58,6 +58,63 @@ console.log(applyStyle("critical error", boldRed));
 
 Nested styles are handled safely — no style bleed across boundaries.
 
+## Dynamic Colors (Truecolor)
+
+Use any RGB or hex color via 24-bit truecolor ANSI sequences:
+
+```ts
+import { rgb, bgRgb, hex, bgHex } from "@crustjs/style";
+
+// RGB values (0–255)
+console.log(rgb("ocean", 0, 128, 255));
+console.log(bgRgb("warning", 255, 128, 0));
+
+// Hex colors (#RGB or #RRGGBB)
+console.log(hex("error", "#ff0000"));
+console.log(hex("short", "#f00"));
+console.log(bgHex("highlight", "#ff8800"));
+```
+
+### Pair Factories
+
+Create reusable `AnsiPair` objects for composition:
+
+```ts
+import { rgbCode, bgRgbCode, hexCode, bgHexCode, applyStyle, composeStyles, boldCode } from "@crustjs/style";
+
+const coral = rgbCode(255, 127, 80);
+console.log(applyStyle("coral text", coral));
+
+const boldCoral = composeStyles(boldCode, hexCode("#ff7f50"));
+console.log(applyStyle("bold coral", boldCoral));
+```
+
+### Style Instance
+
+Dynamic colors on `createStyle` instances respect mode and truecolor detection:
+
+```ts
+import { createStyle } from "@crustjs/style";
+
+const s = createStyle({ mode: "always" });
+console.log(s.rgb("text", 255, 0, 0));
+console.log(s.hex("text", "#ff0000"));
+console.log(s.bgRgb("text", 0, 128, 255));
+console.log(s.bgHex("text", "#0080ff"));
+```
+
+In `"auto"` mode, dynamic colors are emitted only when the terminal supports truecolor (detected via `COLORTERM=truecolor|24bit` or `TERM` containing `truecolor`, `24bit`, or `-direct`). When truecolor is not detected, dynamic color methods return plain text while standard 16-color methods continue to work.
+
+In `"never"` mode, all dynamic color methods return plain text. In `"always"` mode, truecolor sequences are always emitted.
+
+### Terminal Compatibility
+
+Dynamic colors use truecolor (24-bit) ANSI sequences. There is no automatic fallback to 256 or 16 colors. On terminals that do not support truecolor:
+
+- Colors may be approximated to the nearest supported color
+- Colors may be silently ignored (text renders in default color)
+- No runtime errors will occur
+
 ## Color Modes
 
 Control when ANSI codes are emitted using `createStyle`:
@@ -92,6 +149,12 @@ const testStyle = createStyle({
   mode: "auto",
   overrides: { isTTY: true, noColor: undefined },
 });
+
+// Include truecolor overrides for dynamic color testing
+const truecolorStyle = createStyle({
+  mode: "auto",
+  overrides: { isTTY: true, noColor: undefined, colorTerm: "truecolor" },
+});
 ```
 
 ## Text Utilities

package/dist/index.d.ts

@@ -312,6 +312,18 @@ interface CapabilityOverrides {
 	readonly noColor?: string | undefined;
 }
 /**
+* Truecolor capability overrides for deterministic testing.
+*
+* These override environment variable checks used by
+* {@link resolveTrueColor} to detect 24-bit color support.
+*/
+interface TrueColorOverrides {
+	/** Override `process.env.COLORTERM`. */
+	readonly colorTerm?: string | undefined;
+	/** Override `process.env.TERM`. */
+	readonly term?: string | undefined;
+}
+/**
 * Configuration options for creating a style instance.
 *
 * @example
@@ -323,7 +335,7 @@ interface StyleOptions {
 	/** Color emission mode. Defaults to `"auto"`. */
 	readonly mode?: ColorMode;
 	/** Capability overrides for deterministic testing. */
-	readonly overrides?: CapabilityOverrides;
+	readonly overrides?: CapabilityOverrides & TrueColorOverrides;
 }
 /**
 * A style function that applies an ANSI style pair to text,
@@ -360,8 +372,18 @@ type StyleMethodName2 = StyleMethodName;
 interface StyleInstance extends StyleMethodMap {
 	/** Whether ANSI codes will be emitted by this instance. */
 	readonly enabled: boolean;
+	/** Whether truecolor (24-bit) sequences will be emitted by this instance. */
+	readonly trueColorEnabled: boolean;
 	/** Apply an arbitrary ANSI pair to text, respecting the color mode. */
 	readonly apply: (text: string, pair: AnsiPair) => string;
+	/** Apply a truecolor foreground RGB color to text. */
+	readonly rgb: (text: string, r: number, g: number, b: number) => string;
+	/** Apply a truecolor background RGB color to text. */
+	readonly bgRgb: (text: string, r: number, g: number, b: number) => string;
+	/** Apply a truecolor foreground hex color to text. */
+	readonly hex: (text: string, hexColor: string) => string;
+	/** Apply a truecolor background hex color to text. */
+	readonly bgHex: (text: string, hexColor: string) => string;
 }
 /**
 * Resolve whether ANSI color codes should be emitted.
@@ -391,6 +413,35 @@ interface StyleInstance extends StyleMethodMap {
 * ```
 */
 declare function resolveCapability(mode: ColorMode, overrides?: CapabilityOverrides): boolean;
+/**
+* Resolve whether the terminal supports truecolor (24-bit) ANSI sequences.
+*
+* Detection heuristics (checked in order):
+* 1. `COLORTERM` environment variable is `"truecolor"` or `"24bit"`.
+* 2. `TERM` environment variable contains `"24bit"`, `"truecolor"`, or `"-direct"`.
+*
+* In `"always"` mode, returns `true` unconditionally.
+* In `"never"` mode, returns `false` unconditionally.
+* In `"auto"` mode, requires base color to be enabled **and** truecolor
+* to be detected.
+*
+* @param mode - The color emission mode.
+* @param overrides - Optional overrides for deterministic testing.
+* @returns `true` if truecolor sequences should be emitted.
+*
+* @example
+* ```ts
+* resolveTrueColor("auto"); // true if TTY + truecolor env detected
+* resolveTrueColor("always"); // true
+* resolveTrueColor("never"); // false
+* resolveTrueColor("auto", {
+*   isTTY: true,
+*   noColor: undefined,
+*   colorTerm: "truecolor",
+* }); // true
+* ```
+*/
+declare function resolveTrueColor(mode: ColorMode, overrides?: CapabilityOverrides & TrueColorOverrides): boolean;
 /** Apply black foreground color. */
 declare function black2(text: string): string;
 /** Apply red foreground color. */
@@ -506,6 +557,150 @@ declare function createStyle(options?: StyleOptions): StyleInstance;
 */
 declare const style: StyleInstance;
 /**
+* Parse a hex color string into RGB channel values.
+*
+* Supports `#RGB` (shorthand) and `#RRGGBB` (full) formats.
+* The `#` prefix is required.
+*
+* @param hex - The hex color string.
+* @returns A tuple of `[r, g, b]` channel values (0–255).
+* @throws {TypeError} If the string is not a valid hex color.
+*
+* @example
+* ```ts
+* parseHex("#ff0000"); // [255, 0, 0]
+* parseHex("#f00");    // [255, 0, 0]
+* ```
+*/
+declare function parseHex(hex: string): [r: number, g: number, b: number];
+/**
+* Create an {@link AnsiPair} for a truecolor foreground RGB color.
+*
+* Uses the ANSI escape sequence `\x1b[38;2;R;G;Bm` with close `\x1b[39m`.
+*
+* @param r - Red channel (0–255).
+* @param g - Green channel (0–255).
+* @param b - Blue channel (0–255).
+* @returns An ANSI pair for the specified foreground color.
+* @throws {RangeError} If any channel value is invalid.
+*
+* @example
+* ```ts
+* const pair = rgbCode(255, 0, 0);
+* applyStyle("error", pair); // red foreground
+* ```
+*/
+declare function rgbCode(r: number, g: number, b: number): AnsiPair;
+/**
+* Create an {@link AnsiPair} for a truecolor background RGB color.
+*
+* Uses the ANSI escape sequence `\x1b[48;2;R;G;Bm` with close `\x1b[49m`.
+*
+* @param r - Red channel (0–255).
+* @param g - Green channel (0–255).
+* @param b - Blue channel (0–255).
+* @returns An ANSI pair for the specified background color.
+* @throws {RangeError} If any channel value is invalid.
+*
+* @example
+* ```ts
+* const pair = bgRgbCode(255, 128, 0);
+* applyStyle("warning", pair); // orange background
+* ```
+*/
+declare function bgRgbCode(r: number, g: number, b: number): AnsiPair;
+/**
+* Create an {@link AnsiPair} for a truecolor foreground hex color.
+*
+* @param hex - Hex color string (`#RGB` or `#RRGGBB`).
+* @returns An ANSI pair for the specified foreground color.
+* @throws {TypeError} If the hex string is invalid.
+*
+* @example
+* ```ts
+* const pair = hexCode("#ff0000");
+* applyStyle("error", pair); // red foreground
+* ```
+*/
+declare function hexCode(hex: string): AnsiPair;
+/**
+* Create an {@link AnsiPair} for a truecolor background hex color.
+*
+* @param hex - Hex color string (`#RGB` or `#RRGGBB`).
+* @returns An ANSI pair for the specified background color.
+* @throws {TypeError} If the hex string is invalid.
+*
+* @example
+* ```ts
+* const pair = bgHexCode("#ff8800");
+* applyStyle("warning", pair); // orange background
+* ```
+*/
+declare function bgHexCode(hex: string): AnsiPair;
+/**
+* Apply a truecolor foreground RGB color to text.
+*
+* @param text - The text to style.
+* @param r - Red channel (0–255).
+* @param g - Green channel (0–255).
+* @param b - Blue channel (0–255).
+* @returns The styled string.
+* @throws {RangeError} If any channel value is invalid.
+*
+* @example
+* ```ts
+* rgb("error", 255, 0, 0);   // red text
+* rgb("ocean", 0, 128, 255); // blue text
+* ```
+*/
+declare function rgb(text: string, r: number, g: number, b: number): string;
+/**
+* Apply a truecolor background RGB color to text.
+*
+* @param text - The text to style.
+* @param r - Red channel (0–255).
+* @param g - Green channel (0–255).
+* @param b - Blue channel (0–255).
+* @returns The styled string.
+* @throws {RangeError} If any channel value is invalid.
+*
+* @example
+* ```ts
+* bgRgb("warning", 255, 128, 0); // orange background
+* ```
+*/
+declare function bgRgb2(text: string, r: number, g: number, b: number): string;
+/**
+* Apply a truecolor foreground hex color to text.
+*
+* @param text - The text to style.
+* @param hexColor - Hex color string (`#RGB` or `#RRGGBB`).
+* @returns The styled string.
+* @throws {TypeError} If the hex string is invalid.
+*
+* @example
+* ```ts
+* hex("error", "#ff0000");   // red text
+* hex("ocean", "#0080ff");   // blue text
+* hex("short", "#f00");      // red text (shorthand)
+* ```
+*/
+declare function hex(text: string, hexColor: string): string;
+/**
+* Apply a truecolor background hex color to text.
+*
+* @param text - The text to style.
+* @param hexColor - Hex color string (`#RGB` or `#RRGGBB`).
+* @returns The styled string.
+* @throws {TypeError} If the hex string is invalid.
+*
+* @example
+* ```ts
+* bgHex("warning", "#ff8800"); // orange background
+* ```
+*/
+declare function bgHex2(text: string, hexColor: string): string;
+/**
 * Apply **bold** (increased intensity) to text.
 *
 * @example
@@ -949,4 +1144,4 @@ declare function createMarkdownTheme(options?: CreateMarkdownThemeOptions): Mark
 * ```
 */
 declare const defaultTheme: MarkdownTheme;
-export { yellow as yellowCode, yellow2 as yellow, wrapText, white as whiteCode, white2 as white, visibleWidth, unorderedList, underline as underlineCode, underline2 as underline, taskList, table, style, stripAnsi, strikethrough as strikethroughCode, strikethrough2 as strikethrough, resolveCapability, reset, red as redCode, red2 as red, padStart, padEnd, orderedList, magenta as magentaCode, magenta2 as magenta, italic as italicCode, italic2 as italic, inverse as inverseCode, inverse2 as inverse, hidden as hiddenCode, hidden2 as hidden, green as greenCode, green2 as green, gray as grayCode, gray2 as gray, dim as dimCode, dim2 as dim, defaultTheme, cyan as cyanCode, cyan2 as cyan, createStyle, createMarkdownTheme, composeStyles, center, buildDefaultMarkdownTheme, brightYellow as brightYellowCode, brightYellow2 as brightYellow, brightWhite as brightWhiteCode, brightWhite2 as brightWhite, brightRed as brightRedCode, brightRed2 as brightRed, brightMagenta as brightMagentaCode, brightMagenta2 as brightMagenta, brightGreen as brightGreenCode, brightGreen2 as brightGreen, brightCyan as brightCyanCode, brightCyan2 as brightCyan, brightBlue as brightBlueCode, brightBlue2 as brightBlue, bold as boldCode, bold2 as bold, blue as blueCode, blue2 as blue, black as blackCode, black2 as black, bgYellow as bgYellowCode, bgYellow2 as bgYellow, bgWhite as bgWhiteCode, bgWhite2 as bgWhite, bgRed as bgRedCode, bgRed2 as bgRed, bgMagenta as bgMagentaCode, bgMagenta2 as bgMagenta, bgGreen as bgGreenCode, bgGreen2 as bgGreen, bgCyan as bgCyanCode, bgCyan2 as bgCyan, bgBrightYellow as bgBrightYellowCode, bgBrightYellow2 as bgBrightYellow, bgBrightWhite as bgBrightWhiteCode, bgBrightWhite2 as bgBrightWhite, bgBrightRed as bgBrightRedCode, bgBrightRed2 as bgBrightRed, bgBrightMagenta as bgBrightMagentaCode, bgBrightMagenta2 as bgBrightMagenta, bgBrightGreen as bgBrightGreenCode, bgBrightGreen2 as bgBrightGreen, bgBrightCyan as bgBrightCyanCode, bgBrightCyan2 as bgBrightCyan, bgBrightBlue as bgBrightBlueCode, bgBrightBlue2 as bgBrightBlue, bgBrightBlack as bgBrightBlackCode, bgBrightBlack2 as bgBrightBlack, bgBlue as bgBlueCode, bgBlue2 as bgBlue, bgBlack as bgBlackCode, bgBlack2 as bgBlack, applyStyle, WrapOptions, UnorderedListOptions, ThemeSlotFn, TaskListOptions, TaskListItem, TableOptions, StyleOptions, StyleInstance, StyleFn, PartialMarkdownTheme, OrderedListOptions, MarkdownTheme, CreateMarkdownThemeOptions, ColumnAlignment, ColorMode, CapabilityOverrides, AnsiPair };
+export { yellow as yellowCode, yellow2 as yellow, wrapText, white as whiteCode, white2 as white, visibleWidth, unorderedList, underline as underlineCode, underline2 as underline, taskList, table, style, stripAnsi, strikethrough as strikethroughCode, strikethrough2 as strikethrough, rgbCode, rgb, resolveTrueColor, resolveCapability, reset, red as redCode, red2 as red, parseHex, padStart, padEnd, orderedList, magenta as magentaCode, magenta2 as magenta, italic as italicCode, italic2 as italic, inverse as inverseCode, inverse2 as inverse, hidden as hiddenCode, hidden2 as hidden, hexCode, hex, green as greenCode, green2 as green, gray as grayCode, gray2 as gray, dim as dimCode, dim2 as dim, defaultTheme, cyan as cyanCode, cyan2 as cyan, createStyle, createMarkdownTheme, composeStyles, center, buildDefaultMarkdownTheme, brightYellow as brightYellowCode, brightYellow2 as brightYellow, brightWhite as brightWhiteCode, brightWhite2 as brightWhite, brightRed as brightRedCode, brightRed2 as brightRed, brightMagenta as brightMagentaCode, brightMagenta2 as brightMagenta, brightGreen as brightGreenCode, brightGreen2 as brightGreen, brightCyan as brightCyanCode, brightCyan2 as brightCyan, brightBlue as brightBlueCode, brightBlue2 as brightBlue, bold as boldCode, bold2 as bold, blue as blueCode, blue2 as blue, black as blackCode, black2 as black, bgYellow as bgYellowCode, bgYellow2 as bgYellow, bgWhite as bgWhiteCode, bgWhite2 as bgWhite, bgRgbCode, bgRgb2 as bgRgb, bgRed as bgRedCode, bgRed2 as bgRed, bgMagenta as bgMagentaCode, bgMagenta2 as bgMagenta, bgHexCode, bgHex2 as bgHex, bgGreen as bgGreenCode, bgGreen2 as bgGreen, bgCyan as bgCyanCode, bgCyan2 as bgCyan, bgBrightYellow as bgBrightYellowCode, bgBrightYellow2 as bgBrightYellow, bgBrightWhite as bgBrightWhiteCode, bgBrightWhite2 as bgBrightWhite, bgBrightRed as bgBrightRedCode, bgBrightRed2 as bgBrightRed, bgBrightMagenta as bgBrightMagentaCode, bgBrightMagenta2 as bgBrightMagenta, bgBrightGreen as bgBrightGreenCode, bgBrightGreen2 as bgBrightGreen, bgBrightCyan as bgBrightCyanCode, bgBrightCyan2 as bgBrightCyan, bgBrightBlue as bgBrightBlueCode, bgBrightBlue2 as bgBrightBlue, bgBrightBlack as bgBrightBlackCode, bgBrightBlack2 as bgBrightBlack, bgBlue as bgBlueCode, bgBlue2 as bgBlue, bgBlack as bgBlackCode, bgBlack2 as bgBlack, applyStyle, WrapOptions, UnorderedListOptions, TrueColorOverrides, ThemeSlotFn, TaskListOptions, TaskListItem, TableOptions, StyleOptions, StyleInstance, StyleFn, PartialMarkdownTheme, OrderedListOptions, MarkdownTheme, CreateMarkdownThemeOptions, ColumnAlignment, ColorMode, CapabilityOverrides, AnsiPair };

package/dist/index.js

@@ -287,6 +287,32 @@ function resolveCapability(mode, overrides) {
   }
   return isTTY;
 }
+function resolveTrueColor(mode, overrides) {
+  if (mode === "always") {
+    return true;
+  }
+  if (mode === "never") {
+    return false;
+  }
+  if (!resolveCapability(mode, overrides)) {
+    return false;
+  }
+  const hasColorTermOverride = overrides !== undefined && "colorTerm" in overrides;
+  const colorTerm = hasColorTermOverride ? overrides.colorTerm : process.env.COLORTERM;
+  const lowerColorTerm = colorTerm?.toLowerCase();
+  if (lowerColorTerm === "truecolor" || lowerColorTerm === "24bit") {
+    return true;
+  }
+  const hasTermOverride = overrides !== undefined && "term" in overrides;
+  const term = hasTermOverride ? overrides.term : process.env.TERM;
+  if (term !== undefined) {
+    const lower = term.toLowerCase();
+    if (lower.includes("24bit") || lower.includes("truecolor") || lower.endsWith("-direct")) {
+      return true;
+    }
+  }
+  return false;
+}
 // src/styleEngine.ts
 function applyStyle(text, style) {
   if (text === "") {
@@ -402,6 +428,72 @@ function bgBrightCyan2(text) {
 function bgBrightWhite2(text) {
   return applyStyle(text, bgBrightWhite);
 }
+// src/dynamicColors.ts
+function validateChannel(value, channel) {
+  if (!Number.isInteger(value) || value < 0 || value > 255) {
+    throw new RangeError(`Invalid ${channel} value: ${String(value)}. Must be an integer between 0 and 255.`);
+  }
+}
+function validateRgb(r, g, b) {
+  validateChannel(r, "red");
+  validateChannel(g, "green");
+  validateChannel(b, "blue");
+}
+var HEX_SHORT = /^#([0-9a-f]{3})$/i;
+var HEX_LONG = /^#([0-9a-f]{6})$/i;
+function parseHex(hex) {
+  const shortMatch = HEX_SHORT.exec(hex);
+  if (shortMatch) {
+    const digits = shortMatch[1];
+    const r = digits.charAt(0);
+    const g = digits.charAt(1);
+    const b = digits.charAt(2);
+    return [
+      Number.parseInt(r + r, 16),
+      Number.parseInt(g + g, 16),
+      Number.parseInt(b + b, 16)
+    ];
+  }
+  const longMatch = HEX_LONG.exec(hex);
+  if (longMatch) {
+    const digits = longMatch[1];
+    return [
+      Number.parseInt(digits.slice(0, 2), 16),
+      Number.parseInt(digits.slice(2, 4), 16),
+      Number.parseInt(digits.slice(4, 6), 16)
+    ];
+  }
+  throw new TypeError(`Invalid hex color: "${hex}". Expected format: "#RGB" or "#RRGGBB".`);
+}
+function rgbCode(r, g, b) {
+  validateRgb(r, g, b);
+  return { open: `\x1B[38;2;${r};${g};${b}m`, close: "\x1B[39m" };
+}
+function bgRgbCode(r, g, b) {
+  validateRgb(r, g, b);
+  return { open: `\x1B[48;2;${r};${g};${b}m`, close: "\x1B[49m" };
+}
+function hexCode(hex) {
+  const [r, g, b] = parseHex(hex);
+  return rgbCode(r, g, b);
+}
+function bgHexCode(hex) {
+  const [r, g, b] = parseHex(hex);
+  return bgRgbCode(r, g, b);
+}
+function rgb(text, r, g, b) {
+  return applyStyle(text, rgbCode(r, g, b));
+}
+function bgRgb(text, r, g, b) {
+  return applyStyle(text, bgRgbCode(r, g, b));
+}
+function hex(text, hexColor) {
+  return applyStyle(text, hexCode(hexColor));
+}
+function bgHex(text, hexColor) {
+  return applyStyle(text, bgHexCode(hexColor));
+}
+
 // src/styleMethodRegistry.ts
 function readStyleMethodPairs() {
   const { reset: _reset, ...pairs } = exports_ansiCodes;
@@ -464,11 +556,17 @@ function buildStyleMethods(createChainableStyle) {
 function createStyle(options) {
   const mode = options?.mode ?? "auto";
   const enabled = resolveCapability(mode, options?.overrides);
+  const trueColorEnabled = resolveTrueColor(mode, options?.overrides);
   const createChainableStyle = buildChainableStyleFactory(enabled);
   const methods = buildStyleMethods(createChainableStyle);
   const instance = {
     enabled,
+    trueColorEnabled,
     apply: enabled ? (text, pair2) => applyStyle(text, pair2) : (text, _pair) => text,
+    rgb: trueColorEnabled ? (text, r, g, b) => rgb(text, r, g, b) : (text, _r, _g, _b) => text,
+    bgRgb: trueColorEnabled ? (text, r, g, b) => bgRgb(text, r, g, b) : (text, _r, _g, _b) => text,
+    hex: trueColorEnabled ? (text, hexColor) => hex(text, hexColor) : (text, _hexColor) => text,
+    bgHex: trueColorEnabled ? (text, hexColor) => bgHex(text, hexColor) : (text, _hexColor) => text,
     ...methods
   };
   return Object.freeze(instance);
@@ -706,10 +804,14 @@ export {
   stripAnsi,
   strikethrough as strikethroughCode,
   strikethrough2 as strikethrough,
+  rgbCode,
+  rgb,
+  resolveTrueColor,
   resolveCapability,
   reset,
   red as redCode,
   red2 as red,
+  parseHex,
   padStart,
   padEnd,
   orderedList,
@@ -721,6 +823,8 @@ export {
   inverse2 as inverse,
   hidden as hiddenCode,
   hidden2 as hidden,
+  hexCode,
+  hex,
   green as greenCode,
   green2 as green,
   gray as grayCode,
@@ -759,10 +863,14 @@ export {
   bgYellow2 as bgYellow,
   bgWhite as bgWhiteCode,
   bgWhite2 as bgWhite,
+  bgRgbCode,
+  bgRgb,
   bgRed as bgRedCode,
   bgRed2 as bgRed,
   bgMagenta as bgMagentaCode,
   bgMagenta2 as bgMagenta,
+  bgHexCode,
+  bgHex,
   bgGreen as bgGreenCode,
   bgGreen2 as bgGreen,
   bgCyan as bgCyanCode,

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@crustjs/style",
-	"version": "0.0.2",
+	"version": "0.0.3",
 	"description": "Terminal styling foundation for the Crust CLI framework",
 	"type": "module",
 	"license": "MIT",