feat(color): add es-toolkit/color module

.scripts/postbuild.sh

@@ -33,7 +33,7 @@ create_compat_alias() {
 }
 
 # Create root exports
-for module in array error compat function math map object predicate promise set string util; do
+for module in array color error compat function math map object predicate promise set string util; do
     create_root_export $module
 done
 

docs/.vitepress/en.mts

@@ -104,6 +104,11 @@ function sidebar(): DefaultTheme.Sidebar {
           collapsed: true,
           items: getSidebarItems(docsRoot, 'reference', 'util'),
         },
+        {
+          text: 'Color Utilities',
+          collapsed: true,
+          items: getSidebarItems(docsRoot, 'reference', 'color'),
+        },
         {
           text: 'Errors',
           collapsed: true,

docs/.vitepress/ja.mts

@@ -108,6 +108,11 @@ function sidebar(): DefaultTheme.Sidebar {
           collapsed: true,
           items: getSidebarItems(docsRoot, 'ja', 'reference', 'error'),
         },
+        {
+          text: 'カラー',
+          collapsed: true,
+          items: getSidebarItems(docsRoot, 'ja', 'reference', 'color'),
+        },
       ]),
     },
     {

docs/.vitepress/ko.mts

@@ -108,6 +108,11 @@ function sidebar(): DefaultTheme.Sidebar {
           collapsed: true,
           items: getSidebarItems(docsRoot, 'ko', 'reference', 'error'),
         },
+        {
+          text: '컬러',
+          collapsed: true,
+          items: getSidebarItems(docsRoot, 'ko', 'reference', 'color'),
+        },
       ]),
     },
     {

docs/.vitepress/zh_hans.mts

@@ -109,6 +109,11 @@ function sidebar(): DefaultTheme.Sidebar {
           collapsed: true,
           items: getSidebarItems(docsRoot, 'zh_hans', 'reference', 'error'),
         },
+        {
+          text: '颜色',
+          collapsed: true,
+          items: getSidebarItems(docsRoot, 'zh_hans', 'reference', 'color'),
+        },
       ]),
     },
     {

docs/ja/reference/color/color.md

@@ -0,0 +1,97 @@
+# color
+
+ターミナルの色とスタイルを自動検出機能付きで提供します。
+
+すべてのユーティリティは個別の named export として、また default export としてもバンドルされています。各関数は ANSI 色サポートの有無を自動判定し、サポートされない環境（non-TTY、`NO_COLOR=1`、パイプ、`FORCE_COLOR` なしの CI）では入力テキストをそのまま返します。
+
+```typescript
+// 個別の named import（ツリーシェイキング可能）:
+import { bold, hex, red } from 'es-toolkit/color';
+// または default バンドル:
+import color from 'es-toolkit/color';
+
+color.red('エラー');
+```
+
+## 利用可能なユーティリティ
+
+### 修飾子
+
+`reset`, `bold`, `dim`, `italic`, `underline`, `inverse`, `hidden`, `strikethrough`
+
+### 前景色
+
+`black`, `red`, `green`, `yellow`, `blue`, `magenta`, `cyan`, `white`, `gray`
+
+### 明るい前景色
+
+`blackBright`, `redBright`, `greenBright`, `yellowBright`, `blueBright`, `magentaBright`, `cyanBright`, `whiteBright`
+
+### 背景色
+
+`bgBlack`, `bgRed`, `bgGreen`, `bgYellow`, `bgBlue`, `bgMagenta`, `bgCyan`, `bgWhite`
+
+### 明るい背景色
+
+`bgBlackBright`, `bgRedBright`, `bgGreenBright`, `bgYellowBright`, `bgBlueBright`, `bgMagentaBright`, `bgCyanBright`, `bgWhiteBright`
+
+### 拡張色
+
+`ansi256(code)`, `bgAnsi256(code)`, `rgb(r, g, b)`, `bgRgb(r, g, b)`, `hex(color)`, `bgHex(color)`
+
+## 使い方
+
+### 基本的な色とスタイル
+
+```typescript
+import { bgYellow, black, blue, bold, green, red, underline } from 'es-toolkit/color';
+
+red('赤いテキスト');
+green('緑のテキスト');
+blue('青いテキスト');
+
+bold('太字テキスト');
+underline('下線テキスト');
+
+bgYellow(black('黄色い背景に黒いテキスト'));
+```
+
+### 合成
+
+複数のスタイルをネストして使用できます。inner が閉じた後に outer が自動的に再オープンされるため、続くテキストも色が保持されます。
+
+```typescript
+import { bold, red } from 'es-toolkit/color';
+
+bold(red('太字の赤いテキスト'));
+red(`状態: ${bold('重要')} — 確認してください`);
+```
+
+### 拡張色
+
+256色、RGB、Hex 色はカリー化方式です。色の値を先に渡してからテキストを渡します。
+
+```typescript
+import { ansi256, bgAnsi256, bgHex, bgRgb, hex, rgb } from 'es-toolkit/color';
+
+ansi256(196)('明るい赤');
+bgAnsi256(21)('青い背景');
+
+rgb(255, 128, 0)('オレンジ');
+bgRgb(0, 255, 0)('緑の背景');
+
+hex('#ff00ff')('マゼンタ');
+hex('#f0f')('マゼンタ'); // 短い形式
+bgHex('#00ff00')('緑の背景');
+```
+
+### 入力タイプ
+
+すべての色関数は `string` を受け取ります。他の値は渡す前に変換してください。
+
+```typescript
+import { red } from 'es-toolkit/color';
+
+red(String(42)); // '42'
+red(JSON.stringify({ a: 1 }));
+```

docs/ja/reference/color/colorLevel.md

@@ -0,0 +1,55 @@
+# colorLevel
+
+現在のターミナル環境の色サポートレベルを表す値です。
+
+```typescript
+import { colorLevel, isColorSupported } from 'es-toolkit/color';
+```
+
+## 使い方
+
+### `colorLevel`
+
+ターミナルがサポートする色のレベルを数値で返します。
+
+| 値  | 意味         | 色数           |
+| --- | ------------ | -------------- |
+| `0` | 色非サポート | -              |
+| `1` | 基本色       | 16色           |
+| `2` | 256色        | 256色          |
+| `3` | Truecolor    | 1600万色 (RGB) |
+
+```typescript
+import { colorLevel } from 'es-toolkit/color';
+
+if (colorLevel >= 2) {
+  // 256色以上をサポートするターミナル
+}
+```
+
+### `isColorSupported`
+
+色出力が可能かどうかを示すブーリアン値です。`colorLevel > 0` と同じです。
+
+```typescript
+import { isColorSupported } from 'es-toolkit/color';
+
+if (isColorSupported) {
+  console.log('このターミナルは色をサポートしています');
+}
+```
+
+## 検出順序
+
+色のレベルは以下の順序で検出されます。
+
+1. **FORCE_COLOR** — ユーザーが明示的に色のレベルを強制します。`"0"` なら無効化、`"1"`~`"3"` なら該当レベルに設定します。
+2. **NO_COLOR** — ユーザーが明示的に色を無効化します。
+3. **TTY 確認** — stdout がターミナルでない場合（パイプ、リダイレクトなど）、色を無効化します。
+4. **Windows** — Windows Terminal（truecolor）と ConEmu を検出します。その他の Windows ターミナルは基本16色です。
+5. **COLORTERM** — `truecolor` または `24bit` なら Truecolor として検出します。iTerm2、Alacritty などのターミナルが設定します。
+6. **TERM** — `256color` が含まれていれば 256色として検出します。（例: `xterm-256color`）
+7. **hasColors()** — Node.js 内蔵 API（11.13+）でターミナルの色能力を直接確認します。
+8. **デフォルト** — TTY が確認された場合、基本16色です。
+
+`FORCE_COLOR` と `NO_COLOR` は空文字列（`""`）のとき「未設定」として処理されます。これはそれぞれ [force-color.org](https://force-color.org/) と [no-color.org](https://no-color.org/) のスペックに従ったものです。

docs/ja/reference/color/stripColor.md

@@ -0,0 +1,39 @@
+# stripColor
+
+文字列から ANSI 色/スタイルコードを除去します。
+
+```typescript
+import { color, stripColor } from 'es-toolkit/color';
+
+const colored = color.red('hello');
+stripColor(colored);
+// Returns: 'hello'
+```
+
+## 使い方
+
+### `stripColor(text)`
+
+色が適用された文字列から ANSI エスケープコードを除去し、純粋なテキストのみを返します。ログをファイルに保存したり、文字列の長さを正確に測定する際に便利です。
+
+```typescript
+import { color, stripColor } from 'es-toolkit/color';
+
+const message = color.bold(color.red('エラー発生'));
+
+// ファイルに保存する際に ANSI コードを除去
+fs.writeFileSync('log.txt', stripColor(message));
+
+// 文字列の長さを測定
+const visibleLength = stripColor(message).length;
+```
+
+基本色、256色、RGB など、このライブラリが生成する SGR（Select Graphic Rendition）シーケンスのみを除去します。カーソル移動、OSC ハイパーリンクなど、他の ANSI シーケンスは除去しません。
+
+#### パラメータ
+
+- `text` (`string`): ANSI コードが含まれている可能性のある文字列です。
+
+#### 戻り値
+
+(`string`): ANSI コードが除去された文字列を返します。

docs/ko/reference/color/color.md

@@ -0,0 +1,97 @@
+# color
+
+터미널 색상과 스타일을 적용해요. 색상 지원 여부는 자동으로 감지해요.
+
+모든 유틸리티는 개별 named export로도, default export 번들로도 쓸 수 있어요. 각 함수는 ANSI 색상 지원 여부를 자동으로 판단해서, 지원하지 않는 환경(non-TTY, `NO_COLOR=1`, 파이프, `FORCE_COLOR` 없는 CI)에서는 입력 텍스트를 그대로 반환해요.
+
+```typescript
+// 개별 import (트리셰이킹 가능):
+import { bold, hex, red } from 'es-toolkit/color';
+// 또는 default 번들:
+import color from 'es-toolkit/color';
+
+color.red('에러');
+```
+
+## 사용 가능한 유틸리티
+
+### 수정자
+
+`reset`, `bold`, `dim`, `italic`, `underline`, `inverse`, `hidden`, `strikethrough`
+
+### 전경색
+
+`black`, `red`, `green`, `yellow`, `blue`, `magenta`, `cyan`, `white`, `gray`
+
+### 밝은 전경색
+
+`blackBright`, `redBright`, `greenBright`, `yellowBright`, `blueBright`, `magentaBright`, `cyanBright`, `whiteBright`
+
+### 배경색
+
+`bgBlack`, `bgRed`, `bgGreen`, `bgYellow`, `bgBlue`, `bgMagenta`, `bgCyan`, `bgWhite`
+
+### 밝은 배경색
+
+`bgBlackBright`, `bgRedBright`, `bgGreenBright`, `bgYellowBright`, `bgBlueBright`, `bgMagentaBright`, `bgCyanBright`, `bgWhiteBright`
+
+### 확장 색상
+
+`ansi256(code)`, `bgAnsi256(code)`, `rgb(r, g, b)`, `bgRgb(r, g, b)`, `hex(color)`, `bgHex(color)`
+
+## 사용법
+
+### 기본 색상과 스타일
+
+```typescript
+import { bgYellow, black, blue, bold, green, red, underline } from 'es-toolkit/color';
+
+red('빨간 텍스트');
+green('초록 텍스트');
+blue('파란 텍스트');
+
+bold('굵은 텍스트');
+underline('밑줄 텍스트');
+
+bgYellow(black('노란 배경에 검정 텍스트'));
+```
+
+### 합성
+
+여러 스타일을 중첩해서 사용할 수 있어요. inner이 닫히면 outer이 자동으로 재개방돼서 뒤따르는 텍스트도 색이 유지돼요.
+
+```typescript
+import { bold, red } from 'es-toolkit/color';
+
+bold(red('굵은 빨간 텍스트'));
+red(`상태: ${bold('중요')} — 확인 부탁해요`);
+```
+
+### 확장 색상
+
+256색, RGB, Hex 색상은 커링 방식이에요. 색상 값을 먼저 넘기고 텍스트를 이후에 넘겨요.
+
+```typescript
+import { ansi256, bgAnsi256, bgHex, bgRgb, hex, rgb } from 'es-toolkit/color';
+
+ansi256(196)('밝은 빨강');
+bgAnsi256(21)('파란 배경');
+
+rgb(255, 128, 0)('주황색');
+bgRgb(0, 255, 0)('초록 배경');
+
+hex('#ff00ff')('마젠타');
+hex('#f0f')('마젠타'); // 짧은 형식
+bgHex('#00ff00')('초록 배경');
+```
+
+### 입력 타입
+
+모든 색상 함수는 `string`을 받아요. 다른 값은 넘기기 전에 변환해 주세요.
+
+```typescript
+import { red } from 'es-toolkit/color';
+
+red(String(42)); // '42'
+red(JSON.stringify({ a: 1 }));
+```