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,119 @@
+# color
+
+ターミナル出力に色やスタイルを適用するオブジェクトです。環境に応じて色のサポート可否を自動的に検出します。
+
+```typescript
+import { color } from 'es-toolkit/color';
+
+color.red('エラーが発生しました');
+```
+
+## なぜ es-toolkit/color なのか？
+
+既存の色ライブラリ（picocolors など）の既知の問題を解決しています。
+
+- **`FORCE_COLOR=0` バグ修正**: picocolors は `"0"` を truthy として扱い、色が有効になります。es-toolkit はスペック（force-color.org）に従い正しく無効化します。
+- **安全な `process` アクセス**: Cloudflare Workers のように `process` が存在しない環境でもクラッシュせずに動作します。
+- **CI パイプ出力処理**: stdout が TTY でない場合（パイプ、リダイレクト）、色を無効化します。picocolors は CI 環境でこれを無視します。
+- **FORCE_COLOR/NO_COLOR スペック準拠**: 空文字列を「未設定」として正しく処理します。
+- **拡張色サポート**: 256色、RGB、Hex 色をサポートします。picocolors は基本16色のみ対応しています。
+- **`stripAnsi` 内蔵**: ANSI コードを除去するユーティリティを別パッケージなしで提供します。
+- **背景色マルチライン処理**: 改行で背景色が崩れません。
+- **TypeScript サポート**: 完全な型定義を提供します。
+- **ESM/CJS デュアル**: Named export と CommonJS の両方をサポートします。
+
+## 使い方
+
+### 基本的な色とスタイル
+
+```typescript
+import { color } from 'es-toolkit/color';
+
+// 前景色
+color.red('赤いテキスト');
+color.green('緑のテキスト');
+color.blue('青いテキスト');
+color.yellow('黄色いテキスト');
+
+// スタイル
+color.bold('太字テキスト');
+color.dim('薄いテキスト');
+color.italic('斜体テキスト');
+color.underline('下線テキスト');
+color.strikethrough('取り消し線テキスト');
+
+// 背景色
+color.bgRed('赤い背景');
+color.bgGreen('緑の背景');
+```
+
+### 合成
+
+複数のスタイルをネストして使用できます。
+
+```typescript
+import { color } from 'es-toolkit/color';
+
+color.bold(color.red('太字の赤いテキスト'));
+color.bgYellow(color.black('黄色い背景に黒いテキスト'));
+```
+
+### 拡張色
+
+256色、RGB、Hex 色を使用できます。カリー化方式で、色の値を先に渡してからテキストを渡します。
+
+```typescript
+import { color } from 'es-toolkit/color';
+
+// 256色パレット
+color.ansi256(196)('明るい赤');
+color.bgAnsi256(21)('青い背景');
+
+// RGB
+color.rgb(255, 128, 0)('オレンジ');
+color.bgRgb(0, 255, 0)('緑の背景');
+
+// Hex
+color.hex('#ff00ff')('マゼンタ');
+color.bgHex('#00ff00')('緑の背景');
+
+// 短い Hex (#RGB)
+color.hex('#f0f')('マゼンタ');
+```
+
+### 入力タイプ
+
+すべての色関数はどのタイプでも受け取り、`String()` で変換します。chalk からマイグレーションする際に型エラーなく使用できます。
+
+```typescript
+color.red(123); // '123' (数値)
+color.red(true); // 'true' (ブーリアン)
+color.red(null); // 'null'
+color.red(undefined); // 'undefined'
+```
+
+## 利用可能なスタイル
+
+### 修飾子
+
+`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)`

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/createColors.md

@@ -0,0 +1,55 @@
+# createColors
+
+色の有効化を直接制御できるファクトリ関数です。
+
+```typescript
+import { createColors } from 'es-toolkit/color';
+
+const c = createColors(true); // 常に色を有効化
+const noColor = createColors(false); // 常に無効化
+```
+
+## 使い方
+
+### `createColors(enabled?)`
+
+引数なしで呼び出すと環境を自動検出します。`true`/`false` を渡すと強制的に有効化/無効化します。
+
+```typescript
+import { createColors } from 'es-toolkit/color';
+
+// テスト環境で色を強制無効化
+const c = createColors(false);
+c.red('hello'); // 'hello' (ANSIコードなしで返される)
+
+// ロギングライブラリで色を強制有効化
+const log = createColors(true);
+log.green('成功'); // '\x1b[32m成功\x1b[39m'
+```
+
+### いつ使うのか？
+
+- **テスト**: 色を無効化して ANSI コードなしの純粋な文字列を比較したい場合
+- **ライブラリ開発**: ユーザーが色オプションを制御できるようにする場合
+- **条件付き色**: 特定の条件でのみ色を適用したい場合
+
+```typescript
+import { createColors } from 'es-toolkit/color';
+
+function createLogger(useColor: boolean) {
+  const c = createColors(useColor);
+
+  return {
+    info: (msg: string) => console.log(c.blue(msg)),
+    error: (msg: string) => console.error(c.red(msg)),
+  };
+}
+```
+
+#### パラメータ
+
+- `enabled` (`boolean`, 省略可): 色の有効化の可否です。省略すると環境を自動検出します。
+
+#### 戻り値
+
+(`Colors`): すべての色、スタイル、拡張色関数を含むオブジェクトを返します。

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 コードが除去された文字列を返します。