@artiq/stylize
Version:
Lightweight terminal text stylizer with ANSI, RGB, HEX colors, multiple styling modes, and chainable proxy API.
202 lines (142 loc) • 4.78 kB
Markdown
# @artiq/stylize
A minimalist ANSI styling tool for text formatting — made for simplicity, flexibility, and extensibility.
## ✨ Key Features
- 🎨 **Rich Styling Support** – ANSI modifiers, foreground/background colors, 8-bit RGB, HEX
- 🔗 **Chainable Proxy API** – Use `.bold.red.bgBlue(...)` with full IntelliSense
- ⚙️ **Flexible Application** – Apply styles per character, word, line, or sentence
- 🧪 **Runtime Safe** – Auto-validates styles and mode usage
## 📦 Installation
```bash
npm install @artiq/stylize
```
> This package is **ESM only**, make sure you have `"type": "module"` in your `package.json`.
## 🎨 Supported Styles
### Modifiers
```
bold, dim, italic, underline, inverse, hidden, strikethrough
```
### Foreground Colors
```
black, red, green, yellow, blue, magenta, cyan, white,
gray, brightRed, brightGreen, brightYellow, brightBlue, brightMagenta, brightCyan, brightWhite
```
### Background Colors
Prefix with `bg` + capitalized color, e.g.:
```
bgRed, bgBlue, bgGreen, bgBrightCyan, bgWhite, etc.
```
> Each word will receive a random style from the `styleSets`.
## 📘 API Reference
### `stylize(text, styleSets, options?)`
| Param | Type | Description |
|-------------|--------------|-----------------------------------------------------|
| `text` | `string` | The raw text to stylize |
| `styleSets` | `string[][]` | Array of style groups |
| `options` | `object` | Optional: `style` (mode), `randomize` (boolean) |
### `resolveAnsiStyles(styles: string[])`
Resolve an array of styles to a single ANSI escape sequence.
## 🚀 Getting Started
### Import package
```js
import stylize from '@artiq/stylize';
```
### Basic Style
```js
console.log(stylize(
'HELLO ARTIQ',
[['bold', 'red']],
{ style: 'word' }
));
console.log(stylize('HELLO STYLIZE', [['italic', 'green']]));
```
**Result:**
### Using Multiple Styles (`styleSets`)
```js
const styleSets = [
['green', 'bold'],
['blue', 'italic'],
['yellow', 'dim'],
['magenta'],
['cyan', 'underline']
];
console.log(stylize(
'Stylize is fun and colorful!',
styleSets,
{ style: 'word' }
));
```
**Result:**
### Available Modes
| Mode | Description |
|------------|---------------------------|
| `char` | Apply style per character |
| `word` | Apply style per word |
| `line` | Apply style per line |
| `sentence` | Apply style per sentence |
### 🧩 Proxy API (Chaining Style)
```js
console.log(
stylize.yellow.bold.underline('HELLO ARTIQ STYLIZE')
);
```
**Result:**
### Custom RGB & HEX
```js
const stylesRGB = [
['bold', 'rgb(255,0,0)'],
['underline', 'rgb(0,255,0)'],
['italic', 'rgb(0,0,255)'],
['bgRgb(255,255,0)', 'black']
];
console.log(
stylize('Hello colorful style rgb', stylesRGB, { style: 'word', randomize: false })
);
const stylesHEX = [
['#00FFFF', 'underline'],
['#ff0000', 'strikethrough'],
['bg#00FF00'],
['bg#333333'],
['dim']
];
console.log(stylize('Hello colorful style hex', stylesHEX, { style: 'word' }));
```
**Result:**
### 🔀 Advanced: Random & Gradient Application
#### Randomize Style per Segment
```js
console.log(stylize(
'Random style fun',
[['red'], ['blue', 'italic'], ['green', 'underline']],
{ style: 'word', randomize: true }
));
```
**Result:**
## 👤 Author
**[Dimas Fajar](https://github.com/fajardison)**
## ⚖️ License
This project is licensed under the **MIT License** – see the [LICENSE](https://raw.githubusercontent.com/fajardison/artiq-stylize/refs/heads/main/LICENSE) file for details.