@kljj04/cli-kit 1.2.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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kljj04/cli-kit",
-  "version": "1.2.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

@@ -26,6 +26,7 @@ class KitBuilder {
         this._outputType = 'print';
         this._override = false;
         this._gradientColors = null;
+        this._fixedGradient = false;
     }
 
     color(r, g, b) {
@@ -45,6 +46,8 @@ class KitBuilder {
         args.forEach(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]) {
@@ -72,7 +75,7 @@ class KitBuilder {
             case 'spinner':
                 return require('./spinner').spinner(prefix, value);
             case 'progress':
-                require('./progress').progress(prefix, value, this._override, this._gradientColors);
+                require('./progress').progress(prefix, value, this._override, this._gradientColors, this._fixedGradient);
                 break;
             case 'table':
                 require('./table').table(prefix, value);
@@ -82,6 +85,7 @@ class KitBuilder {
         this._outputType = 'print';
         this._override = false;
         this._gradientColors = null;
+        this._fixedGradient = false;
     }
 }
 

package/src/progress.js

@@ -12,48 +12,57 @@ function delinearize(c) {
 
 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 = 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];
+    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;
+    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];
+    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);
+    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) {
+function renderBar(prefix, pct, gradientColors, fixedGradient) {
     const width = 30;
     const filled = Math.round((pct / 100) * width);
     const empty = width - filled;
 
     let bar = '';
-    if (gradientColors) {
+    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);
@@ -67,9 +76,9 @@ function renderBar(prefix, pct, gradientColors) {
     return `${prefix}[${bar}] ${pct}%${RESET}`;
 }
 
-function progress(prefix, value, override, gradientColors) {
+function progress(prefix, value, override, gradientColors, fixedGradient) {
     const pct = Math.min(100, Math.max(0, Number(value)));
-    const bar = renderBar(prefix, pct, gradientColors);
+    const bar = renderBar(prefix, pct, gradientColors, fixedGradient);
     if (override) {
         process.stdout.write(`\r${bar}`);
         if (pct >= 100) process.stdout.write('\n');