@kljj04/cli-kit 1.1.0 → 1.2.1

package/README.long.md

@@ -0,0 +1,245 @@
+# @kljj04/cli-kit — Full Documentation
+
+All-in-one terminal styling library for Node.js.  
+RGB truecolor, boxes, tables, spinners, and progress bars — all in one package, zero dependencies.
+
+---
+
+## Install
+
+```bash
+npm install @kljj04/cli-kit
+```
+
+---
+
+## Core Concept
+
+All styling follows a consistent 3-step chain:
+
+```js
+kit.color(R, G, B).style(...args).context(value)
+```
+
+| Step | Method | Description |
+|---|---|---|
+| 1 | `color(r, g, b)` | Set RGB truecolor (0–255 each) |
+| 2 | `style(...args)` | Set text styles + output type |
+| 3 | `context(value)` | Render the output |
+
+You can also write it across multiple lines:
+
+```js
+kit
+  .color(255, 100, 50)
+  .style('bold', 'box')
+  .context('Hello!')
+```
+
+---
+
+## color(r, g, b)
+
+Sets the foreground color using RGB truecolor.  
+Requires a terminal with truecolor support (Windows Terminal, iTerm2, most modern terminals).
+
+```js
+kit.color(255, 0, 0)    // red
+kit.color(0, 255, 0)    // green
+kit.color(0, 0, 255)    // blue
+kit.color(255, 255, 255) // white
+```
+
+---
+
+## style(...args)
+
+Accepts any combination of text styles and one output type.
+
+### Text Styles
+
+| Value | Description |
+|---|---|
+| `bold` | Bold text |
+| `dim` | Dimmed text |
+| `italic` | Italic text |
+| `underline` | Underlined text |
+| `inverse` | Inverted fg/bg colors |
+| `strikethrough` | Strikethrough text |
+
+### Output Types
+
+| Value | Description |
+|---|---|
+| `print` | Plain text (default) |
+| `box` | Unicode box border |
+| `spinner` | Animated spinner |
+| `progress` | Progress bar |
+| `table` | Formatted table |
+
+Multiple text styles can be combined. Only one output type should be passed.
+
+```js
+kit.color(255, 100, 50).style('bold', 'italic', 'box').context('Hello!')
+```
+
+---
+
+## Output Types
+
+### print (default)
+
+Prints styled text to stdout. Output type can be omitted.
+
+```js
+kit.color(255, 100, 50).style('bold').context('Hello!')
+kit.color(255, 100, 50).style('bold', 'print').context('Hello!')
+```
+
+---
+
+### box
+
+Wraps text in a Unicode box border. Supports multiline strings (`\n`).
+
+```js
+kit.color(100, 200, 255).style('box').context('Hello!')
+```
+
+```
+┌────────┐
+│ Hello! │
+└────────┘
+```
+
+Multiline:
+
+```js
+kit.color(150, 255, 100).style('box').context('Line one\nLine two\nLine three')
+```
+
+```
+┌────────────┐
+│ Line one   │
+│ Line two   │
+│ Line three │
+└────────────┘
+```
+
+---
+
+### spinner
+
+Returns a spinner object with a `.stop(text)` method.
+
+```js
+const s = kit.color(0, 255, 200).style('spinner').context('Loading...')
+
+setTimeout(() => {
+    s.stop('Done!')  // clears spinner, prints final message
+}, 2000)
+```
+
+| Method | Description |
+|---|---|
+| `s.stop(text?)` | Stop spinner. Optionally print a final message. |
+
+---
+
+### progress
+
+Pass a number from 0 to 100.
+
+```js
+kit.color(255, 200, 0).style('progress').context(72)
+// [██████████████████████░░░░░░░░] 72%
+```
+
+**Live mode** — pass `{ value, override: true }` to overwrite the same line.  
+Useful inside loops or intervals.
+
+```js
+// style에 override 추가
+kit.color(0, 255, 150).style('progress', 'override').context(i)
+```
+
+Example with interval:
+
+```js
+let i = 0
+const interval = setInterval(() => {
+    i++
+    kit.color(0, 255, 150).style('progress', 'override').context(i)
+    if (i >= 100) clearInterval(interval)
+}, 30)
+```
+
+---
+
+### table
+
+Pass an array of objects. Keys are used as column headers automatically.
+
+```js
+kit.color(200, 150, 255).style('table').context([
+    { name: 'Alice', age: 20, role: 'dev' },
+    { name: 'Bob',   age: 25, role: 'designer' },
+    { name: 'Carol', age: 30, role: 'PM' },
+])
+```
+
+```
+┌───────┬─────┬──────────┐
+│ name  │ age │ role     │
+┼───────┼─────┼──────────┼
+│ Alice │ 20  │ dev      │
+│ Bob   │ 25  │ designer │
+│ Carol │ 30  │ PM       │
+└───────┴─────┴──────────┘
+```
+
+---
+
+## Full Example
+
+```js
+const kit = require('@kljj04/cli-kit')
+
+// box
+kit.color(0, 255, 100).style('bold', 'box').context('Welcome!')
+
+// spinner
+const s = kit.color(100, 200, 255).style('spinner').context('Loading...')
+setTimeout(() => s.stop('Done!'), 1500)
+
+// table
+kit.color(200, 150, 255).style('table').context([
+    { task: 'Build',  status: 'OK' },
+    { task: 'Deploy', status: 'OK' },
+])
+
+// progress (live)
+let i = 0
+const iv = setInterval(() => {
+    i++
+    kit.color(255, 200, 0).style('progress', 'override').context(i)
+    if (i >= 100) {
+        clearInterval(iv)
+        kit.color(0, 255, 100).style('bold').context('Complete!')
+    }
+}, 20)
+```
+
+---
+
+## Planned Features
+
+- `gradient([r,g,b], [r,g,b])` — per-character color interpolation for progress bars
+- `style('round', 'box')` — rounded box corners
+- `bgColor(r, g, b)` — background color support
+
+---
+
+## License
+
+MIT

package/README.md

@@ -1,3 +1,7 @@
+> [!WARNING]
+> This README is old and outdated. It will be updated as soon as possible.
+> AI.md, README.long.md too.
+
 # @kljj04/cli-kit
 
 All-in-one terminal styling library for Node.js.  

package/index.js

@@ -6,6 +6,9 @@ const kit = {
     },
     style(...args) {
         return new KitBuilder().style(...args);
+    },
+    gradient(from, to) {
+        return new KitBuilder().gradient(from, to);
     }
 };
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kljj04/cli-kit",
-  "version": "1.1.0",
+  "version": "1.2.1",
   "description": "All-in-one terminal styling library. Colors, boxes, tables, spinners, and progress bars.",
   "main": "index.js",
   "scripts": {

package/src/color.js

@@ -24,6 +24,9 @@ class KitBuilder {
         this._b = 255;
         this._styles = [];
         this._outputType = 'print';
+        this._override = false;
+        this._gradientColors = null;
+        this._fixedGradient = false;
     }
 
     color(r, g, b) {
@@ -33,10 +36,19 @@ class KitBuilder {
         return this;
     }
 
+    gradient(from, to) {
+        this._gradientColors = [from, to];
+        return this;
+    }
+
     style(...args) {
         const outputTypes = ['print', 'box', 'spinner', 'progress', 'table'];
         args.forEach(arg => {
-            if (outputTypes.includes(arg)) {
+            if (arg === 'override') {
+                this._override = true;
+            } else if (arg === 'fixedgradient') {
+                this._fixedGradient = true;
+            } else if (outputTypes.includes(arg)) {
                 this._outputType = arg;
             } else if (STYLES[arg]) {
                 this._styles.push(arg);
@@ -46,7 +58,7 @@ class KitBuilder {
     }
 
     _buildPrefix() {
-        const colorCode = rgb(this._r, this._g, this._b);
+        const colorCode = this._gradientColors ? '' : rgb(this._r, this._g, this._b);
         const styleCodes = this._styles.map(s => STYLES[s]).join('');
         return `${colorCode}${styleCodes}`;
     }
@@ -63,15 +75,17 @@ class KitBuilder {
             case 'spinner':
                 return require('./spinner').spinner(prefix, value);
             case 'progress':
-                require('./progress').progress(prefix, value);
+                require('./progress').progress(prefix, value, this._override, this._gradientColors, this._fixedGradient);
                 break;
             case 'table':
                 require('./table').table(prefix, value);
                 break;
         }
-        // reset for next use
         this._styles = [];
         this._outputType = 'print';
+        this._override = false;
+        this._gradientColors = null;
+        this._fixedGradient = false;
     }
 }
 

package/src/progress.js

@@ -1,21 +1,89 @@
 const { RESET } = require('./color');
 
-function renderBar(prefix, pct) {
+function linearize(c) {
+    c /= 255;
+    return c <= 0.04045 ? c / 12.92 : Math.pow((c + 0.055) / 1.055, 2.4);
+}
+
+function delinearize(c) {
+    c = c <= 0.0031308 ? 12.92 * c : 1.055 * Math.pow(c, 1 / 2.4) - 0.055;
+    return Math.round(Math.min(1, Math.max(0, c)) * 255);
+}
+
+function rgbToOklch(r, g, b) {
+    const lr = linearize(r), lg = linearize(g), lb = linearize(b);
+    const l = 0.4122214708*lr + 0.5363325363*lg + 0.0514459929*lb;
+    const m = 0.2119034982*lr + 0.6806995451*lg + 0.1073969566*lb;
+    const s = 0.0883024619*lr + 0.2817188376*lg + 0.6299787005*lb;
+    const l_ = Math.cbrt(l), m_ = Math.cbrt(m), s_ = Math.cbrt(s);
+    const L = 0.2104542553*l_ + 0.7936177850*m_ - 0.0040720468*s_;
+    const a = 1.9779984951*l_ - 2.4285922050*m_ + 0.4505937099*s_;
+    const bVal = 0.0259040371*l_ + 0.7827717662*m_ - 0.8086757660*s_;
+    const C = Math.sqrt(a*a + bVal*bVal);
+    const H = Math.atan2(bVal, a) * (180/Math.PI);
+    return [L, C, H < 0 ? H+360 : H];
+}
+
+function oklchToRgb(L, C, H) {
+    const hRad = H * (Math.PI/180);
+    const a = C*Math.cos(hRad);
+    const b = C*Math.sin(hRad);
+    const l_ = L+0.3963377774*a+0.2158037573*b;
+    const m_ = L-0.1055613458*a-0.0638541728*b;
+    const s_ = L-0.0894841775*a-1.2914855480*b;
+    const lc=l_*l_*l_, mc=m_*m_*m_, sc=s_*s_*s_;
+    const lr =  4.0767416621*lc - 3.3077115913*mc + 0.2309699292*sc;
+    const lg = -1.2684380046*lc + 2.6097574011*mc - 0.3413193965*sc;
+    const lb = -0.0041960863*lc - 0.7034186147*mc + 1.7076147010*sc;
+    return [delinearize(lr), delinearize(lg), delinearize(lb)];
+}
+
+function lerpOklch(from, to, t) {
+    const a = rgbToOklch(...from);
+    const b = rgbToOklch(...to);
+    let dH = b[2]-a[2];
+    if (dH > 180) dH -= 360;
+    if (dH < -180) dH += 360;
+    return oklchToRgb(a[0]+(b[0]-a[0])*t, a[1]+(b[1]-a[1])*t, a[2]+dH*t);
+}
+
+function renderBar(prefix, pct, gradientColors, fixedGradient) {
     const width = 30;
     const filled = Math.round((pct / 100) * width);
     const empty = width - filled;
-    const bar = '█'.repeat(filled) + '░'.repeat(empty);
+
+    let bar = '';
+    if (gradientColors && fixedGradient) {
+        // 전체 30칸 기준으로 색 미리 계산, 채워진 만큼만 표시
+        for (let i = 0; i < filled; i++) {
+            const t = (width > 1) ? i / (width - 1) : 0;
+            const [r, g, b] = lerpOklch(gradientColors[0], gradientColors[1], t);
+            bar += `\x1b[38;2;${r};${g};${b}m█`;
+        }
+        bar += `${RESET}${'░'.repeat(empty)}`;
+    } else if (gradientColors) {
+        // 채워진 칸 기준 보간 (기존 gradient)
+        for (let i = 0; i < filled; i++) {
+            const t = filled > 1 ? i / (filled - 1) : 0;
+            const [r, g, b] = lerpOklch(gradientColors[0], gradientColors[1], t);
+            bar += `\x1b[38;2;${r};${g};${b}m█`;
+        }
+        bar += `${RESET}${'░'.repeat(empty)}`;
+    } else {
+        bar = '█'.repeat(filled) + '░'.repeat(empty);
+    }
+
     return `${prefix}[${bar}] ${pct}%${RESET}`;
 }
 
-function progress(prefix, value) {
-    if (typeof value === 'object' && value !== null && value.live) {
-        const pct = Math.min(100, Math.max(0, Number(value.value)));
-        process.stdout.write(`\r${renderBar(prefix, pct)}`);
+function progress(prefix, value, override, gradientColors, fixedGradient) {
+    const pct = Math.min(100, Math.max(0, Number(value)));
+    const bar = renderBar(prefix, pct, gradientColors, fixedGradient);
+    if (override) {
+        process.stdout.write(`\r${bar}`);
         if (pct >= 100) process.stdout.write('\n');
     } else {
-        const pct = Math.min(100, Math.max(0, Number(value)));
-        console.log(renderBar(prefix, pct));
+        console.log(bar);
     }
 }