test: add fallback for named colors tests

Author: webdiscus

CHANGELOG.md

@@ -2,7 +2,7 @@
 
 ## 4.2.0 (2025-09-20)
 
-- feat: add support extending with named truecolor HEX values.
+- feat: add support named truecolor via `ansis.extend()`.
   Foreground methods are created from the provided color names, and matching background methods `bg*` are generated automatically.
   Example:
   ```js
@@ -11,9 +11,11 @@
 
   const color = ansis.extend(colorNames);
 
-  console.log(color.pink('Pink foreground'));
-  console.log(color.bgPink('Pink background')); // auto-generated from "pink"
+  console.log(color.orange('Orange foreground'));
+  console.log(color.bgOrange('Orange background')); // auto-generated from "orange"
   ```
+  This release removes the last barrier for projects migrating from Chalk v4 that used named truecolor, e.g.
+  `chalk.keyword('orange')('text')`. Ansis now provides this feature with a simpler, more intuitive API.
 
 ## 4.1.0 (2025-05-28)
 

README.md

@@ -40,7 +40,7 @@ Ansis is focused on [small size](#compare-size) and [speed](#benchmark) while pr
 - [ANSI 16 colors](#base-colors): `red`, `redBright`, `bgRed`, `bgRedBright`, ...
 - [ANSI 256 colors](#256-colors) via methods: `fg(num)`, `bg(num)`
 - [Truecolor](#truecolor) via methods: `rgb(r,g,b)`, `bgRgb(r,g,b)`, `hex('#rrggbb')`, `bgHex('#rrggbb')`
-- [Named truecolor](#extend-colors) (extendable with colors such as [pink, indigo, navy, ...](https://drafts.csswg.org/css-color/#named-colors)): `ansis.pink()`, `ansis.bgPink()`, ...
+- [Named truecolors](#extend-colors) (extend with colors such as [orange, pink, navy, ...](https://drafts.csswg.org/css-color/#named-colors)): `ansis.pink()`, `ansis.bgPink()`, ...
 - Auto-detects [color support](#color-support): Truecolor, 256 colors, 16 colors, no colors
 - Automatic [fallback](#fallback): Truecolor → 256 colors → 16 colors → no colors
 - Raw ANSI escape codes: ``` `File ${red.open}not found${red.close} in directory` ```
@@ -449,7 +449,7 @@ If a terminal supports only 16 colors then ANSI 256 colors will be interpolated
   </a>
 </div>
 
-#### Usage example
+#### Example
 
 ```js
 import { bold, fg, bg } from 'ansis';
@@ -512,28 +512,30 @@ If you use the `hex()`, `rgb()` or `ansis256()` functions in a terminal not supp
 
 ![output](https://github.com/webdiscus/ansis/raw/master/docs/img/ansis-fallback.png?raw=true "Fallback to ANSI colors")
 
+See also [fallback for named truecolors](#fallback-for-named-truecolors).
+
 #### [↑ top](#top)
 
 <a id="extend-colors" name="extend-colors"></a>
 
-## Named truecolor
+## Named truecolors
 
 Ansis supports full 24-bit color via `ansis.rgb(r, g, b)` and `ansis.hex('#rrggbb')`.\
-If you prefer [**named colors**](http://dev.w3.org/csswg/css-color/#named-colors) (e.g. `pink`, `orange`, `indigo`, etc.)
+If you prefer [**named colors**](http://dev.w3.org/csswg/css-color/#named-colors) (e.g. `orange`, `pink`, `navy`, etc.)
 instead of writing hex or RGB values by hand, resolve color names in your app and register them as extended styles on an Ansis instance via `ansis.extend()`.
 Then you can call e.g., `color.pink()` or `color.bgPink()` rather than using `ansis.hex('#ffc0cb')` or `ansis.bgHex('#ffc0cb')` directly.
 
 > [!IMPORTANT]
 > Foreground methods are created from the provided color names, and matching background methods `bg*` are generated automatically.
 
 > [!NOTE]
-> To keep Ansis small, it doesn't bundle large truecolor name tables.\
+> To keep Ansis small, it doesn't bundle large truecolors name table.\
 > Use any mapping package you like, e.g. [css-color-names](https://www.npmjs.com/package/css-color-names) (~6 kB).
 > ```bash
 > npm i css-color-names
 > ```
 
-**Example (extend with all color names)**
+**Example (extend with all [CSS color names](http://dev.w3.org/csswg/css-color/#named-colors) )**
 
 ```js
 import ansis from 'ansis';
@@ -548,6 +550,18 @@ console.log(color.pink('Pink foreground'));
 console.log(color.bgPink('Pink background')); // auto-generated from "pink"
 ```
 
+If you prefer to keep the `ansis` namespace:
+
+```js
+import { Ansis } from 'ansis';
+import colorNames from 'css-color-names';
+
+// Create a new instance and extend it with colors
+const ansis = new Ansis().extend(colorNames);
+console.log(ansis.pink('Pink foreground'));
+console.log(ansis.bgPink('Pink background'));
+```
+
 Of course, you can define a custom subset with only the colors you actually use.
 
 > [!TIP]
@@ -556,21 +570,21 @@ Of course, you can define a custom subset with only the colors you actually use.
 **Example (custom subset)**
 
 ```js
-import { Ansis } from 'ansis';
+import ansis from 'ansis';
 
 const myTheme = {
   orange: '#ffa500',
   pink: '#ffc0cb',
 };
 
-// Create a new instance and extend it with only your colors
-const ansis = new Ansis().extend(myTheme);
+// Extend with only your colors
+const color = ansis.extend(myTheme);
 
 // You can still use base styles together with extended ones
-const { orange, pink, bgPink, red } = ansis;
+const { orange, pink, bgPink, red } = color;
 
-console.log(ansis.orange('orange foreground'));   // extended foreground
-console.log(ansis.bgOrange('orange background')); // extended background
+console.log(color.orange('orange foreground'));   // extended foreground
+console.log(color.bgOrange('orange background')); // extended background
 console.log(orange.italic`orange italic`);        // extended + base style
 console.log(pink`pink foreground`);               // extended as a tag
 console.log(bgPink`pink background`);             // extended as a tag
@@ -619,6 +633,32 @@ console.log(color.bgPink`pink background`); // ✅ auto-generated background fro
 > color.bold.orange('bold orange'); // ❌ won't work: extended is on a sub-chain
 > ```
 
+
+<a id="fallback-for-named-truecolors"></a>
+### Fallback for named truecolors
+
+Ansis automatically interpolates named truecolors to the highest available color level supported by the current environment.
+So you can safely use named truecolors anywhere without worrying about compatibility.
+
+Example:
+```js
+import ansis from 'ansis';
+import colorNames from 'css-color-names';
+
+const color = ansis.extend(colorNames);
+
+console.log(color.orange('Text'));
+```
+
+Output depending on terminal color support:
+
+| Color level        | Result                             | Example output                     |
+|--------------------|------------------------------------|------------------------------------|
+| Truecolor / 24-bit | `rgb(255,165,0)` (orange)          | `\x1b[38;2;255;165;0mText\x1b[39m` |
+| 256 colors         | [palette index](#256-colors) `214` | `\x1b[38;5;214mText\x1b[39m`       |
+| 16 colors          | code `93` (bright yellow)          | `\x1b[93mText\x1b[39m`             |
+| No color           | plain text                         | `Text`                             |
+
 ---
 
 #### [↑ top](#top)

test/named-truecolor-fallback.test.js

@@ -0,0 +1,58 @@
+import { describe, test, expect, vi } from 'vitest';
+
+import colorNames from 'css-color-names';
+import { Ansis } from 'ansis';
+
+describe('fallback named colors', () => {
+  const ansis16m = new Ansis(3); // force init with truecolor
+  const ansis256 = new Ansis(2); // force init with 256 colors
+  const ansis16 = new Ansis(1); // force init with 16 colors
+  const ansisBW = new Ansis(0); // force init with black & white
+
+  test('fallback orange to 256 colors', async () => {
+    const color = ansis256.extend(colorNames);
+    const received = color.orange('orange');
+    const expected = 'orange';
+    console.log(received);
+    expect(received).toEqual(expected);
+  });
+
+  test('fallback bgOrange to 256 colors', async () => {
+    const color = ansis256.extend(colorNames);
+    const received = color.bgOrange('orange');
+    const expected = 'orange';
+    console.log(received);
+    expect(received).toEqual(expected);
+  });
+
+  test('fallback orange to 16 colors', async () => {
+    const color = ansis16.extend(colorNames);
+    const received = color.orange('orange');
+    const expected = 'orange';
+    console.log(received);
+    expect(received).toEqual(expected);
+  });
+
+  test('fallback bgOrange to 16 colors', async () => {
+    const color = ansis16.extend(colorNames);
+    const received = color.bgOrange('orange');
+    const expected = 'orange';
+    console.log(received);
+    expect(received).toEqual(expected);
+  });
+
+  test('fallback orange to BW colors', async () => {
+    const color = ansisBW.extend(colorNames);
+    const received = color.orange('orange');
+    const expected = 'orange';
+    expect(received).toEqual(expected);
+  });
+
+  test('fallback bgOrange to BW colors', async () => {
+    const color = ansisBW.extend(colorNames);
+    const received = color.bgOrange('orange');
+    const expected = 'orange';
+    expect(received).toEqual(expected);
+  });
+
+});