printstyle 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Stamat
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,163 @@
+# PrintStyle 🌈
+
+ANSI terminal styling with a built-in micro template language.
+
+Most color libraries make you chain function calls or concatenate escape codes by hand. PrintStyle gives you `paint()` — a template syntax that reads like markup and just works.
+
+```js
+import PrintStyle from "printstyle";
+const ps = new PrintStyle();
+
+ps.paint("{red|Error:} Woops something went wrong!");
+```
+
+## Why PrintStyle?
+
+- **Template syntax** — `paint()` lets you style strings inline without concatenation chains or nested calls. No other terminal color package has this built in.
+- **Tiny** — ~9 KB unpacked, zero dependencies.
+- **Hex colors** — use any color, not just the 16 built-in ANSI names.
+- **NO_COLOR / FORCE_COLOR** — follows the standard out of the box.
+- **No magic** — plain class with string properties. No Proxy, no prototype tricks, no chaining API. Easy to debug, easy to understand.
+
+**Note:** Legacy Windows CMD (before Windows 10) does not support ANSI escape codes. Use Windows Terminal, PowerShell, or WSL instead.
+
+## Install
+
+```bash
+npm install printstyle
+```
+
+## Template Syntax — `paint()`
+
+### Wrap mode (auto-reset)
+
+Style is applied and automatically reset after the content:
+
+```js
+ps.paint("{red|error message}"); // red text, then reset
+ps.paint("{bold.red|ERROR}"); // bold + red, then reset
+ps.paint("{bgRed.white| FAIL }"); // red background, white text
+```
+
+### Spanning mode (manual reset)
+
+Style stays active until you close with `{/}`:
+
+```js
+ps.paint("{red}all of this is red{/}");
+ps.paint("{dim}prefix {bold|inner} still dim{/}");
+```
+
+### Dot-chaining
+
+Combine multiple styles with `.`:
+
+```js
+ps.paint("{bgRed.white.bold|FAIL}"); // background + foreground + style
+ps.paint("{green.bold|✓} {dim|file.jpg}"); // multiple wraps in one string
+```
+
+### Hex colors
+
+Use any hex color for foreground or background:
+
+```js
+ps.paint("{#2e8b57|sea green text}");
+ps.paint("{bg#ff5500.white|orange background}");
+ps.paint("{#f00|shorthand red}"); // 3-char hex supported
+```
+
+## Direct Property Access
+
+Every ANSI code is also available as a string property for manual concatenation:
+
+```js
+console.log(ps.red + "error" + ps.reset);
+console.log(ps.bold + ps.blue + "title" + ps.reset);
+```
+
+### Available properties
+
+**Styles:** `reset` `bold` `dim` `italic` `underline` `blink` `inverse` `hidden` `strikethrough`
+
+**Colors:** `black` `red` `green` `yellow` `blue` `magenta` `cyan` `white` `gray`
+
+**Bright colors:** `redBright` `greenBright` `yellowBright` `blueBright` `magentaBright` `cyanBright` `whiteBright`
+
+**Backgrounds:** `bgBlack` `bgRed` `bgGreen` `bgYellow` `bgBlue` `bgMagenta` `bgCyan` `bgWhite` `bgGray`
+
+**Bright backgrounds:** `bgRedBright` `bgGreenBright` `bgYellowBright` `bgBlueBright` `bgMagentaBright` `bgCyanBright` `bgWhiteBright`
+
+**Other:** `bell`
+
+## Custom Styles — `extend()`
+
+Register your own named styles built from any combination of built-in codes or hex colors:
+
+```js
+const ps = new PrintStyle();
+
+ps.extend({
+  error: ps.bold + ps.red,
+  success: ps.bold + ps.green,
+  warning: ps.yellow,
+  brand: ps.color("#ff6600"),
+  link: ps.blue + ps.underline + ps.italic,
+});
+
+console.log(ps.paint("{error|Something failed}"));
+console.log(ps.paint("{success|All good}"));
+console.log(ps.paint("{brand|Acme Corp}"));
+console.log(ps.paint("{link|https://github.com/stamat/printstyle}"));
+```
+
+Custom styles work everywhere built-in styles do — in `paint()` templates, dot-chaining, direct property access, and they integrate with `disable()` / `enable()`.
+
+## Hex Color Methods
+
+```js
+ps.color("#ff0000"); // foreground escape sequence for hex
+ps.background("#00ff00"); // background escape sequence for hex
+```
+
+Both accept 6-char (`#ff0000`) or 3-char (`#f00`) hex, with or without `#`.
+
+## NO_COLOR / FORCE_COLOR
+
+PrintStyle respects the [NO_COLOR](https://no-color.org/) and [FORCE_COLOR](https://force-color.org/) environment variables automatically:
+
+- `NO_COLOR` (any value) — disables all color output
+- `FORCE_COLOR=1` — forces color output regardless of `NO_COLOR`
+- `FORCE_COLOR=0` — disables color output
+
+You can also control it programmatically:
+
+```js
+ps.disable(); // turn off all codes
+ps.enable(); // restore all codes
+ps.enabled; // check current state
+```
+
+## Comparison
+
+|                     | printstyle | chalk        | ansis     | picocolors | kleur     | ansi-colors | yoctocolors |
+| ------------------- | ---------- | ------------ | --------- | ---------- | --------- | ----------- | ----------- |
+| **Unpacked size**   | ~9 KB      | ~44 KB       | ~6 KB     | ~6 KB      | ~20 KB    | ~26 KB      | ~10 KB      |
+| **Runtime deps**    | 0          | 0            | 0         | 0          | 0         | 0           | 0           |
+| **Template syntax** | Built-in   | Separate pkg | No        | No         | No        | No          | No          |
+| **Hex colors**      | Yes        | Yes          | Yes       | No         | No        | No          | No          |
+| **NO_COLOR**        | Yes        | No           | Yes       | Yes        | Yes       | No          | Yes         |
+| **FORCE_COLOR**     | Yes        | Yes          | Yes       | Yes        | Yes       | Partial     | Yes         |
+| **TypeScript**      | Built-in   | Built-in     | Built-in  | Built-in   | Built-in  | Built-in    | Built-in    |
+| **Module type**     | ESM        | ESM          | CJS + ESM | CJS + ESM  | CJS + ESM | CJS         | ESM         |
+| **Legacy Win CMD**  | No         | Yes          | No        | No         | No        | No          | No          |
+
+## License
+
+[MIT](LICENSE)
+
+## P.S.
+
+> Another one - DJ Khaled
+
+❤️, @stamat

package/index.d.ts

@@ -0,0 +1,124 @@
+/**
+ * Minimal ANSI terminal styling with a built-in micro template language.
+ */
+export default class PrintStyle {
+  /** Whether ANSI codes are currently active. */
+  enabled: boolean
+
+  // Styles
+  reset: string
+  bold: string
+  dim: string
+  italic: string
+  underline: string
+  blink: string
+  inverse: string
+  hidden: string
+  strikethrough: string
+
+  // Foreground colors
+  black: string
+  red: string
+  redBright: string
+  green: string
+  greenBright: string
+  yellow: string
+  yellowBright: string
+  blue: string
+  blueBright: string
+  magenta: string
+  magentaBright: string
+  cyan: string
+  cyanBright: string
+  white: string
+  whiteBright: string
+  gray: string
+
+  // Background colors
+  bgBlack: string
+  bgRed: string
+  bgRedBright: string
+  bgGreen: string
+  bgGreenBright: string
+  bgYellow: string
+  bgYellowBright: string
+  bgBlue: string
+  bgBlueBright: string
+  bgMagenta: string
+  bgMagentaBright: string
+  bgCyan: string
+  bgCyanBright: string
+  bgWhite: string
+  bgWhiteBright: string
+  bgGray: string
+
+  // Other
+  bell: string
+
+  /**
+   * Disable all ANSI codes. Properties become empty strings.
+   * The `bell` property is preserved.
+   */
+  disable(): void
+
+  /**
+   * Re-enable all ANSI codes, restoring their original values.
+   */
+  enable(): void
+
+  /**
+   * Register custom named styles.
+   * Extended styles integrate with `disable()` and `enable()` and are usable in `paint()` templates.
+   * @param styles An object mapping style names to ANSI escape strings.
+   */
+  extend(styles: Record<string, string>): void
+
+  /**
+   * Parse a hex color string into an [R, G, B] array.
+   * @param hex Hex color string (e.g. `'#ff0000'`, `'f00'`).
+   * @returns An array of [red, green, blue] values (0–255).
+   */
+  hexToRgb(hex: string): [number, number, number]
+
+  /**
+   * Convert RGB values to a 256-color terminal index.
+   * @param red Red channel (0–255).
+   * @param green Green channel (0–255).
+   * @param blue Blue channel (0–255).
+   * @returns The terminal color index (16–231).
+   */
+  terminalColorIndex(red: number, green: number, blue: number): number
+
+  /**
+   * Get a 256-color foreground escape sequence for a hex color.
+   * @param hex Hex color string (e.g. `'#ff0000'`, `'f00'`).
+   * @returns The ANSI escape sequence, or `''` if disabled.
+   */
+  color(hex: string): string
+
+  /**
+   * Get a 256-color background escape sequence for a hex color.
+   * @param hex Hex color string (e.g. `'#ff0000'`, `'f00'`).
+   * @returns The ANSI escape sequence, or `''` if disabled.
+   */
+  background(hex: string): string
+
+  /**
+   * Apply styles to a string using a micro template syntax.
+   *
+   * **Wrap mode** (auto-reset): `{style|content}` — e.g. `'{red|error}'`
+   *
+   * **Spanning mode** (manual reset): `{style}...{/}` — e.g. `'{red}error{/}'`
+   *
+   * Styles can be dot-chained: `'{bold.red|ERROR}'`
+   *
+   * Hex colors: `'{#2e8b57|text}'`, `'{bg#ff5500|text}'`
+   *
+   * @param str The template string to process.
+   * @returns The string with ANSI escape sequences applied.
+   */
+  paint(str: string): string
+
+  /** Allow custom styles added via `extend()`. */
+  [key: string]: string | boolean | ((...args: any[]) => any)
+}

package/index.js

@@ -0,0 +1,190 @@
+/**
+ * Minimal ANSI terminal styling with a built-in micro template language.
+ */
+export default class PrintStyle {
+  enabled = true
+  reset = '\x1b[0m'
+  bold = '\x1b[1m'
+  dim = '\x1b[2m'
+  italic = '\x1b[3m'
+  underline = '\x1b[4m'
+  blink = '\x1b[5m'
+  inverse = '\x1b[7m'
+  hidden = '\x1b[8m'
+  strikethrough = '\x1b[9m'
+  black = '\x1b[30m'
+  red = '\x1b[31m'
+  redBright = '\x1b[91m'
+  green = '\x1b[32m'
+  greenBright = '\x1b[92m'
+  yellow = '\x1b[33m'
+  yellowBright = '\x1b[93m'
+  blue = '\x1b[34m'
+  blueBright = '\x1b[94m'
+  magenta = '\x1b[35m'
+  magentaBright = '\x1b[95m'
+  cyan = '\x1b[36m'
+  cyanBright = '\x1b[96m'
+  white = '\x1b[37m'
+  whiteBright = '\x1b[97m'
+  gray = '\x1b[90m'
+  bgBlack = '\x1b[40m'
+  bgRed = '\x1b[41m'
+  bgRedBright = '\x1b[101m'
+  bgGreen = '\x1b[42m'
+  bgGreenBright = '\x1b[102m'
+  bgYellow = '\x1b[43m'
+  bgYellowBright = '\x1b[103m'
+  bgBlue = '\x1b[44m'
+  bgBlueBright = '\x1b[104m'
+  bgMagenta = '\x1b[45m'
+  bgMagentaBright = '\x1b[105m'
+  bgCyan = '\x1b[46m'
+  bgCyanBright = '\x1b[106m'
+  bgWhite = '\x1b[47m'
+  bgWhiteBright = '\x1b[107m'
+  bgGray = '\x1b[100m'
+  bell = '\x07'
+
+  constructor() {
+    this._defaults = {}
+    for (const key of Object.keys(this)) {
+      if (typeof this[key] === 'string') this._defaults[key] = this[key]
+    }
+
+    const env = typeof process !== 'undefined' && process.env ? process.env : {}
+    if ('FORCE_COLOR' in env) {
+      if (env.FORCE_COLOR === '0') this.disable()
+    } else if ('NO_COLOR' in env) {
+      this.disable()
+    }
+  }
+
+  /**
+   * Disable all ANSI codes. Properties become empty strings.
+   * The `bell` property is preserved.
+   */
+  disable() {
+    this.enabled = false
+    for (const key of Object.keys(this._defaults)) {
+      if (key === 'bell') continue
+      this[key] = ''
+    }
+  }
+
+  /**
+   * Re-enable all ANSI codes, restoring their original values.
+   */
+  enable() {
+    this.enabled = true
+    for (const [key, value] of Object.entries(this._defaults)) {
+      this[key] = value
+    }
+  }
+
+  /**
+   * Register custom named styles.
+   * Extended styles integrate with `disable()` and `enable()` and are usable in `paint()` templates.
+   * @param {Record<string, string>} styles - An object mapping style names to ANSI escape strings.
+   * @example
+   * ps.extend({
+   *   error: ps.bold + ps.red,
+   *   brand: ps.color('#ff6600'),
+   * })
+   * ps.paint('{error|Something failed}')
+   */
+  extend(styles) {
+    for (const [key, value] of Object.entries(styles)) {
+      this[key] = value
+      this._defaults[key] = value
+    }
+  }
+
+  /**
+   * Parse a hex color string into an [R, G, B] array.
+   * @param {string} hex - Hex color string (e.g. `'#ff0000'`, `'f00'`).
+   * @returns {number[]} An array of [red, green, blue] values (0–255).
+   */
+  hexToRgb(hex) {
+    let h = hex.replace('#', '')
+    if (h.length === 3) h = h[0] + h[0] + h[1] + h[1] + h[2] + h[2]
+    const red = parseInt(h.substring(0, 2), 16)
+    const green = parseInt(h.substring(2, 4), 16)
+    const blue = parseInt(h.substring(4, 6), 16)
+
+    return [
+      isNaN(red) ? 0 : red,
+      isNaN(green) ? 0 : green,
+      isNaN(blue) ? 0 : blue
+    ]
+  }
+
+  /**
+   * Convert RGB values to a 256-color terminal index.
+   * @param {number} red - Red channel (0–255).
+   * @param {number} green - Green channel (0–255).
+   * @param {number} blue - Blue channel (0–255).
+   * @returns {number} The terminal color index (16–231).
+   */
+  terminalColorIndex(red, green, blue) {
+    return 16 +
+      Math.round(red / 255 * 5) * 36 +
+      Math.round(green / 255 * 5) * 6 +
+      Math.round(blue / 255 * 5)
+  }
+
+  /**
+   * Get a 256-color foreground escape sequence for a hex color.
+   * @param {string} hex - Hex color string (e.g. `'#ff0000'`, `'f00'`).
+   * @returns {string} The ANSI escape sequence, or `''` if disabled.
+   */
+  color(hex) {
+    if (!this.enabled) return ''
+    const [red, green, blue] = this.hexToRgb(hex)
+
+    return `\x1b[38;5;${this.terminalColorIndex(red, green, blue)}m`
+  }
+
+  /**
+   * Get a 256-color background escape sequence for a hex color.
+   * @param {string} hex - Hex color string (e.g. `'#ff0000'`, `'f00'`).
+   * @returns {string} The ANSI escape sequence, or `''` if disabled.
+   */
+  background(hex) {
+    if (!this.enabled) return ''
+    const [red, green, blue] = this.hexToRgb(hex)
+
+    return `\x1b[48;5;${this.terminalColorIndex(red, green, blue)}m`
+  }
+
+  /** @private */
+  _resolveToken(token) {
+    if (token === '/') return this.reset
+    if (token.startsWith('bg#')) return this.background(token.slice(2))
+    if (token.startsWith('#')) return this.color(token)
+    return (typeof this[token] === 'string') ? this[token] : ''
+  }
+
+  /**
+   * Apply styles to a string using a micro template syntax.
+   *
+   * **Wrap mode** (auto-reset): `{style|content}` — e.g. `'{red|error}'`
+   *
+   * **Spanning mode** (manual reset): `{style}...{/}` — e.g. `'{red}error{/}'`
+   *
+   * Styles can be dot-chained: `'{bold.red|ERROR}'`
+   *
+   * Hex colors: `'{#2e8b57|text}'`, `'{bg#ff5500|text}'`
+   *
+   * @param {string} str - The template string to process.
+   * @returns {string} The string with ANSI escape sequences applied.
+   */
+  paint(str) {
+    return str.replace(/\{([^}]+?)(?:\|([^}]*))?\}/g, (_, style, content) => {
+      if (style === '/') return this.reset
+      const codes = style.split('.').map(t => this._resolveToken(t)).join('')
+      if (content !== undefined) return codes + content + this.reset
+      return codes
+    })
+  }
+}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "printstyle",
+  "description": "Minimal, zero-dependency ANSI terminal styling with a micro template language.",
+  "version": "1.0.0",
+  "license": "MIT",
+  "type": "module",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.js"
+    }
+  },
+  "files": [
+    "index.js",
+    "index.d.ts"
+  ],
+  "author": "Stamat <@stamat> (http://stamat.info)",
+  "homepage": "https://github.com/stamat/printstyle",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/stamat/printstyle.git"
+  },
+  "private": false,
+  "keywords": [
+    "ansi",
+    "colors",
+    "style",
+    "template",
+    "cli",
+    "zero-dependency"
+  ],
+  "scripts": {
+    "lint": "eslint ./index.js",
+    "test": "NODE_OPTIONS='--experimental-vm-modules' jest"
+  },
+  "devDependencies": {
+    "@jest/globals": "^30.2.0",
+    "eslint": "^9.39.3",
+    "jest": "^30.2.0",
+    "neostandard": "^0.12.2"
+  }
+}