colorizr 3.0.2 → 3.0.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "colorizr",
-  "version": "3.0.2",
+  "version": "3.0.4",
   "description": "Manipulate colors like a boss",
   "author": "Gil Barbara <gilbarbara@gmail.com>",
   "keywords": [
@@ -32,13 +32,13 @@
   "types": "dist/index.d.ts",
   "sideEffects": false,
   "devDependencies": {
-    "@arethetypeswrong/cli": "^0.17.0",
+    "@arethetypeswrong/cli": "^0.17.2",
     "@gilbarbara/eslint-config": "^0.8.2",
     "@gilbarbara/prettier-config": "^1.0.0",
     "@gilbarbara/tsconfig": "^0.2.3",
     "@size-limit/preset-small-lib": "^11.1.6",
-    "@types/node": "^22.10.1",
-    "@vitest/coverage-v8": "^2.1.6",
+    "@types/node": "^22.10.2",
+    "@vitest/coverage-v8": "^2.1.8",
     "del-cli": "^6.0.0",
     "husky": "^9.1.7",
     "is-ci-cli": "^2.2.0",
@@ -46,9 +46,9 @@
     "size-limit": "^11.1.6",
     "ts-node": "^10.9.2",
     "tsup": "^8.3.5",
-    "typescript": "^5.7.2",
-    "vite-tsconfig-paths": "^5.1.3",
-    "vitest": "^2.1.6",
+    "typescript": "^5.6.3",
+    "vite-tsconfig-paths": "^5.1.4",
+    "vitest": "^2.1.8",
     "watch-run": "^1.2.5"
   },
   "scripts": {

package/src/colorizr.ts

@@ -20,9 +20,11 @@ import textColor from '~/text-color';
 import transparentize from '~/transparentize';
 import { Alpha, Amount, Analysis, ColorType, Degrees, HEX, HSL, LAB, LCH, RGB } from '~/types';
 
-export interface Options {
+export interface ColorizrOptions {
   /**
-   * The output color type
+   * Output color format.
+   *
+   * If not specified, the output will use the same format as the input color.
    */
   format?: ColorType;
 }
@@ -36,7 +38,7 @@ export default class Colorizr {
   public rgb: RGB;
   public type: ColorType;
 
-  constructor(color: string | HSL | LAB | LCH | RGB, options: Options = {}) {
+  constructor(color: string | HSL | LAB | LCH | RGB, options: ColorizrOptions = {}) {
     invariant(!!color, 'color is required');
 
     const { alpha, hex, hsl, oklab, oklch, rgb, type } = parseColor(color);

package/src/format-css.ts

@@ -7,10 +7,13 @@ import { isHex, isHSL, isLAB, isLCH, isValidColorModel } from '~/modules/validat
 import * as converters from '~/converters';
 import { Alpha, ColorModel, ColorType, HEX, HSL } from '~/types';
 
-export interface FormatOptions {
+export interface FormatCSSOptions {
+  /**
+   * The alpha value of the color.
+   */
   alpha?: Alpha;
   /**
-   * The output color type.
+   * Output color format.
    * @default 'hex'
    */
   format?: ColorType;
@@ -21,6 +24,7 @@ export interface FormatOptions {
   precision?: number;
   /**
    * The separator between the values.
+   *
    * oklab and oklch always use space as a separator.
    * @default ' '
    */
@@ -29,7 +33,7 @@ export interface FormatOptions {
 
 export default function formatCSS<T extends ColorModel | HEX>(
   input: T,
-  options: FormatOptions = {},
+  options: FormatCSSOptions = {},
 ): string {
   invariant(isHex(input) || isValidColorModel(input), MESSAGES.invalid);
 

package/src/index.ts

@@ -33,5 +33,12 @@ export * from '~/types';
 export * from '~/modules/hex-utils';
 export { isHex, isHSL, isLAB, isLCH, isRGB } from '~/modules/validators';
 
+export type { ColorizrOptions } from '~/colorizr';
+export type { FormatCSSOptions } from '~/format-css';
+export type { PaletteOptions } from '~/palette';
+export type { Scheme, SchemeOptions } from '~/scheme';
+export type { Swatch, SwatchOptions, SwatchVariant } from '~/swatch';
+export type { TextColorOptions } from '~/text-color';
+
 // eslint-disable-next-line unicorn/prefer-export-from
 export default Colorizr;

package/src/modules/invariant.ts

@@ -3,7 +3,6 @@ export function invariant(condition: boolean, message: string): asserts conditio
     return;
   }
 
-  /* istanbul ignore else */
   if (process.env.NODE_ENV !== 'production') {
     if (message === undefined) {
       throw new Error('invariant requires an error message argument');

package/src/palette.ts

@@ -11,14 +11,36 @@ import rotate from '~/rotate';
 import { ColorType, HEX } from '~/types';
 
 export interface PaletteOptions {
+  /**
+   * Output color format.
+   *
+   * If not specified, the output will use the same format as the input color.
+   */
   format?: ColorType;
+  /**
+   * Adjusts the lightness of the base color before generating the palette.
+   *
+   * Value should be between 0 and 100.
+   */
   lightness?: number;
+  /**
+   * Adjusts the saturation of the base color before generating the palette.
+   *
+   * Value should be between 0 and 100.
+   */
   saturation?: number;
   /**
-   * The number of colors to generate
+   * The number of colors to generate in the palette.
+   *
+   * Minimum value is 2.
    * @default 6
    */
   size?: number;
+  /**
+   * Generate a monochromatic palette.
+   *
+   * For more options, use the `swatch` function.
+   */
   type?: 'monochromatic';
 }
 
@@ -28,31 +50,25 @@ export default function palette(input: string, options: PaletteOptions = {}): st
 
   const { format, lightness, saturation, size = 6, type } = options;
   const hsl = parseCSS(input, 'hsl');
-  const output: string[] = [];
   const colorFormat = isHex(input) || isNamedColor(input) ? 'hex' : extractColorParts(input).model;
 
-  switch (type) {
-    case 'monochromatic': {
-      const step = 80 / size;
+  const output: string[] = [];
 
-      for (let index = size; index > 0; index--) {
-        output.push(hsl2hex({ ...hsl, l: step * index }));
-      }
+  if (type === 'monochromatic') {
+    const step = 80 / size;
 
-      break;
+    for (let index = size; index > 0; index--) {
+      output.push(hsl2hex({ ...hsl, l: step * index }));
     }
-    default: {
-      const step = 360 / size;
-
-      output.push(hsl2hex({ ...hsl, l: lightness ?? hsl.l, s: saturation ?? hsl.s }));
+  } else {
+    const step = 360 / size;
 
-      for (let index = 1; index < size; index++) {
-        const color = rotate(input, hsl.h + step * index, 'hex') as HEX;
+    output.push(hsl2hex({ ...hsl, l: lightness ?? hsl.l, s: saturation ?? hsl.s }));
 
-        output.push(hsl2hex({ ...hex2hsl(color), l: lightness ?? hsl.l, s: saturation ?? hsl.s }));
-      }
+    for (let index = 1; index < size; index++) {
+      const color = rotate(input, hsl.h + step * index, 'hex') as HEX;
 
-      break;
+      output.push(hsl2hex({ ...hex2hsl(color), l: lightness ?? hsl.l, s: saturation ?? hsl.s }));
     }
   }
 

package/src/scheme.ts

@@ -18,6 +18,11 @@ export type Scheme =
   | 'triadic';
 
 export interface SchemeOptions {
+  /**
+   * Output color format.
+   *
+   * If not specified, the output will use the same format as the input color.
+   */
   format?: ColorType;
   /**
    * The type of scheme to generate.

package/src/swatch.ts

@@ -9,47 +9,81 @@ import oklch2rgb from '~/converters/oklch2rgb';
 import rgb2hex from '~/converters/rgb2hex';
 import extractColorParts from '~/extract-color-parts';
 import parseCSS from '~/parse-css';
-import { ColorType, HEX, LCH } from '~/types';
+import { ColorTokens, ColorType, HEX, LCH } from '~/types';
 
-type ColorTokens = 50 | 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900;
-
-type Swatch = {
+export type Swatch = {
   [key in ColorTokens]: string;
 };
 
+export type SwatchVariant = 'deep' | 'neutral' | 'pastel' | 'subtle' | 'vibrant';
+
 export interface SwatchOptions {
+  /**
+   * Output color format.
+   *
+   * If not specified, the output will use the same format as the input color.
+   */
   format?: ColorType;
   /**
-   * The scale of the swatch.
-   * Linear scale will have equal distance between each shade.
+   * The mode of the swatch.
+   * - 'light': Focuses on lighter tones starting from a higher lightness.
+   * - 'dark': Focuses on darker tones starting from a lower lightness.
+   *
+   * If omitted, a balanced palette is generated.
+   */
+  mode?: 'light' | 'dark';
+  /**
+   * Generate a monochromatic swatch.
+   *
+   * Disable chroma adjustments for all shades.
+   * @default false
+   */
+  monochromatic?: boolean;
+  /**
+   * Determines the scale type for the swatch.
+   * - 'linear': Shades are distributed with equal lightness intervals.
+   * - 'dynamic': Shades are distributed adaptively based on the input color.
    * @default 'dynamic'
    */
   scale?: 'dynamic' | 'linear';
+  /**
+   * The variant of the swatch.
+   * - 'deep': Generates rich and bold tones with significantly reduced lightness.
+   * - 'neutral': Generates muted tones by reducing chroma.
+   * - 'pastel': Produces soft and airy tones with significant chroma reduction.
+   * - 'subtle': Creates extremely desaturated tones, close to grayscale.
+   * - 'vibrant': Enhances chroma for bold and striking tones.
+   */
+  variant?: SwatchVariant;
 }
 
-const MIN_LIGHTNESS = 21;
-const MAX_LIGHTNESS = 97;
+const MIN_LIGHTNESS = 5;
+const MAX_LIGHTNESS = 95;
 
 /**
  * Generate a shade of a color based its lightness tuning factor
  */
-function shadeColorDynamic(input: LCH, lightnessTuningFactor: number, chromaTuningFactor = 0): HEX {
+function shadeColorDynamic(input: LCH, lightnessTuningFactor: number, chromaFactor = 0): HEX {
   if (lightnessTuningFactor === 0) {
-    return rgb2hex(oklch2rgb({ ...input, l: input.l / 100 }));
+    const { l } = input;
+
+    return rgb2hex(oklch2rgb({ ...input, l: l / 100 }));
   }
 
   // Convert back to RGB and make sure it's within the sRGB gamut
-  return shadeColor(input, input.l + lightnessTuningFactor, chromaTuningFactor);
+  return shadeColor(input, input.l + lightnessTuningFactor, chromaFactor);
 }
 
 /**
  * Generate a shade of a color based its lightness tuning factor
  */
-function shadeColor(input: LCH, lightness: number, chromaTuningFactor = 0): HEX {
+function shadeColor(input: LCH, lightness: number, chromaFactor = 0): HEX {
   const { c, h } = input;
 
+  const adjustedChroma = clamp(c + chromaFactor, 0, 0.4);
+
   // Convert back to RGB and make sure it's within the sRGB gamut
-  return oklch2hex({ l: lightness / 100, c: clamp(c + chromaTuningFactor, 0, 0.4), h });
+  return oklch2hex({ l: lightness / 100, c: adjustedChroma, h });
 }
 
 /**
@@ -57,45 +91,68 @@ function shadeColor(input: LCH, lightness: number, chromaTuningFactor = 0): HEX
  */
 export default function swatch(input: string, options: SwatchOptions = {}): Swatch {
   invariant(isString(input), MESSAGES.inputString);
-  const { format, scale = 'dynamic' } = options;
+  const { format, monochromatic = false, scale = 'dynamic', mode, variant = 'base' } = options;
 
   const lch = parseCSS(input, 'oklch');
+  const chromaScale = {
+    base: 1,
+    deep: 0.8,
+    neutral: 0.5,
+    pastel: 0.3,
+    subtle: 0.2,
+    vibrant: 1.25,
+  }[variant];
 
   lch.l = 50;
+  lch.c *= chromaScale;
+
+  if (variant === 'deep') {
+    lch.l *= 0.7;
+  }
 
   const colorFormat = isHex(input) || isNamedColor(input) ? 'hex' : extractColorParts(input).model;
 
   const currentLightness = lch.l;
-  const safeMaxLightness = currentLightness >= 88.5 ? 99.5 : MAX_LIGHTNESS;
-  const safeMinLightness = currentLightness <= 33 ? 0 : MIN_LIGHTNESS;
-  const lightBase = (safeMaxLightness - currentLightness) / 5;
-  const darkBase = (-1 * (currentLightness - safeMinLightness)) / 8;
+  let lightSteps = 5;
+  let darkSteps = 8;
+
+  if (mode) {
+    lightSteps *= mode === 'light' ? 0.75 : 1.25;
+    darkSteps *= mode === 'light' ? 1.25 : 0.75;
+  }
+
+  const lightStepSize = (MAX_LIGHTNESS - currentLightness) / lightSteps;
+  const darkStepSize = (-1 * (currentLightness - MIN_LIGHTNESS)) / darkSteps;
+
+  const getChromaFactor = (value: number): number => {
+    return monochromatic ? 0 : value; // Disable adjustments for monochromatic swatches
+  };
 
   const output: Swatch =
     scale === 'linear'
       ? {
-          50: shadeColor(lch, 95, -0.00375),
-          100: shadeColor(lch, 90, -0.00375),
-          200: shadeColor(lch, 80, -0.00375),
-          300: shadeColor(lch, 70, -0.00375),
-          400: shadeColor(lch, 60, -0.00375),
+          50: shadeColor(lch, 95, getChromaFactor(-0.00375)),
+          100: shadeColor(lch, 90, getChromaFactor(-0.00375)),
+          200: shadeColor(lch, 80, getChromaFactor(-0.00375)),
+          300: shadeColor(lch, 70, getChromaFactor(-0.00375)),
+          400: shadeColor(lch, 60, getChromaFactor(-0.00375)),
           500: shadeColor(lch, 50),
-          600: shadeColor(lch, 40, 0.025),
-          700: shadeColor(lch, 30, 0.05),
-          800: shadeColor(lch, 20, 0.075),
-          900: shadeColor(lch, 10, 0.1),
+          600: shadeColor(lch, 40, getChromaFactor(0.025)),
+          700: shadeColor(lch, 30, getChromaFactor(0.05)),
+          800: shadeColor(lch, 20, getChromaFactor(0.075)),
+          900: shadeColor(lch, 10, getChromaFactor(0.1)),
         }
       : {
-          50: shadeColorDynamic(lch, 5 * lightBase, -0.00375),
-          100: shadeColorDynamic(lch, 4 * lightBase, -0.00375),
-          200: shadeColorDynamic(lch, 3 * lightBase, -0.00375),
-          300: shadeColorDynamic(lch, 2 * lightBase, -0.00375),
-          400: shadeColorDynamic(lch, lightBase, -0.00375),
+          50: shadeColorDynamic(lch, 5 * lightStepSize, getChromaFactor(-0.00375)),
+          100: shadeColorDynamic(lch, 4 * lightStepSize, getChromaFactor(-0.00375)),
+          200: shadeColorDynamic(lch, 3 * lightStepSize, getChromaFactor(-0.00375)),
+          300: shadeColorDynamic(lch, 2 * lightStepSize, getChromaFactor(-0.00375)),
+          400: shadeColorDynamic(lch, lightStepSize, getChromaFactor(-0.00375)),
           500: shadeColorDynamic(lch, 0),
-          600: shadeColorDynamic(lch, 1.6 * darkBase, 0.025),
-          700: shadeColorDynamic(lch, 1.875 * 2 * darkBase, 0.05),
-          800: shadeColorDynamic(lch, 3 * 2 * darkBase, 0.075),
-          900: shadeColorDynamic(lch, 4 * 2 * darkBase, 0.1),
+          600: shadeColorDynamic(lch, 1.6 * darkStepSize, getChromaFactor(0.025)),
+          700: shadeColorDynamic(lch, 3.2 * darkStepSize, getChromaFactor(0.05)),
+          800: shadeColorDynamic(lch, 4.8 * darkStepSize, getChromaFactor(0.075)),
+          900: shadeColorDynamic(lch, 6.4 * darkStepSize, getChromaFactor(0.1)),
         };
 
   return Object.entries(output).reduce((acc, [key, value]) => {

package/src/text-color.ts

@@ -5,7 +5,7 @@ import { isString } from '~/modules/validators';
 import hex2rgb from '~/converters/hex2rgb';
 import parseCSS from '~/parse-css';
 
-interface Options {
+export interface TextColorOptions {
   /**
    * The dark color to return if the input is light.
    * @default '#000000'
@@ -18,6 +18,7 @@ interface Options {
   lightColor?: string;
   /**
    * The threshold to determine if the color is light or dark.
+   *
    * A number between 0 and 255.
    * @default 128
    */
@@ -27,14 +28,23 @@ interface Options {
 /**
  * Get the contrasted color for a given hex.
  */
-export default function textColor(input: string, options: Options = {}): string {
+export default function textColor(input: string, options: TextColorOptions = {}): string {
   const { darkColor = '#000000', lightColor = '#ffffff', threshold = 128 } = options;
 
   invariant(isString(input), MESSAGES.inputString);
   invariant(threshold >= 0 && threshold <= 255, MESSAGES.threshold);
 
-  const { r, g, b } = hex2rgb(parseCSS(input, 'hex'));
-  const yiq = (r * 299 + g * 587 + b * 114) / 1000;
+  try {
+    const { r, g, b } = hex2rgb(parseCSS(input, 'hex'));
+    const yiq = (r * 299 + g * 587 + b * 114) / 1000;
 
-  return yiq >= threshold ? darkColor : lightColor;
+    return yiq >= threshold ? darkColor : lightColor;
+  } catch (error) {
+    /* eslint-disable no-console */
+    console.warn(`Invalid color input: ${input}`);
+    console.warn(error);
+    /* eslint-enable no-console */
+
+    return darkColor; // Default to dark color in case of error
+  }
 }

package/src/types/index.ts

@@ -14,7 +14,8 @@ export type ColorModelKeys<TModel extends ColorModelKey> = TModel extends 'hsl'
 
 export type ColorKeysTuple = [string, string, string];
 export type ColorTuple = [number, number, number];
-export type ConverterParameters<TModel extends ColorModel> = TModel | ColorTuple;
+export type ColorTokens = 50 | 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900;
+
 export interface Colors {
   alpha: Alpha;
   hex: HEX;
@@ -25,6 +26,8 @@ export interface Colors {
   type: ColorType;
 }
 
+export type ConverterParameters<TModel extends ColorModel> = TModel | ColorTuple;
+
 /* A number between 0 and 1 */
 export type Alpha = number;