colorizr 5.0.0 → 5.1.0

package/dist/index.d.mts

@@ -658,6 +658,26 @@ declare function extractAlphaFromHex(input: string): number;
  */
 declare function removeAlphaFromHex(input: string): HEX;
 
+declare const CLMS_TO_OKLAB: number[][];
+declare const DEG2RAD: number;
+declare const LMS_TO_LRGB: number[][];
+declare const LRGB_TO_LMS: number[][];
+declare const OKLAB_TO_CLMS: number[][];
+declare const P3_TO_SRGB: number[][];
+declare const P3_TO_XYZ: number[][];
+declare const SRGB_TO_P3: number[][];
+declare const XYZ_TO_SRGB: number[][];
+declare const GAMUT_EPSILON = 0.000001;
+declare const PRECISION = 5;
+declare const RAD2DEG: number;
+
+declare function srgbGammaDecode(input: number): number;
+declare function srgbGammaEncode(input: number): number;
+
+declare function isInGamut(color: ColorTuple): boolean;
+declare function oklabToLinearP3(L: number, a: number, b: number): ColorTuple;
+declare function oklabToLinearSRGB(L: number, a: number, b: number): ColorTuple;
+
 /**
  * Get the step keys for a given step count.
  *
@@ -901,6 +921,18 @@ declare function saturate(input: string, amount: number, format?: ColorType): st
 
 type ScaleMode = 'light' | 'dark';
 type ScaleVariant = 'deep' | 'neutral' | 'pastel' | 'subtle' | 'vibrant';
+/**
+ * Parabolic chroma curve with a movable center.
+ */
+interface ScaleChromaPeak {
+    /** Blend between constant chroma (0) and the full parabola (1). */
+    amount: number;
+    /**
+     * Lightness (exclusive 0-1) where chroma stays at full base.
+     * @default 0.5
+     */
+    peak?: number;
+}
 /**
  * Options for generating a color scale.
  *
@@ -911,14 +943,29 @@ type ScaleVariant = 'deep' | 'neutral' | 'pastel' | 'subtle' | 'vibrant';
  */
 interface ScaleOptions {
     /**
-     * Controls chroma distribution across lightness levels (0-1).
+     * Controls how chroma flows across the scale. Three forms:
+     *
+     * Scalar (0-1) — parabolic blend centered at mid-lightness:
      * - 0: Constant chroma across all steps (default).
-     * - 1: Parabolic curve — full chroma at mid-lightness, reduced toward extremes.
-     * - Values between interpolate between constant and parabolic.
+     * - 1: Full parabola — peak chroma at mid-lightness, reduced toward extremes.
+     * Shorthand for `{ amount: x }`.
+     *
+     * `{ amount, peak }` — the same parabola with a movable center.
+     * `peak` is the lightness (exclusive 0-1) that keeps full base chroma;
+     * sides away from it are reduced. Defaults to 0.5.
+     *
+     * `{ low, high }` — fractions (0-1) of the maximum P3 chroma at each step,
+     * blended from `low` (50-end) through the input color's own fraction at the
+     * lock/middle step to `high` (950-end). NOT equivalent to the scalar form —
+     * it is a different model: values set chroma relative to the gamut ceiling
+     * instead of bending the input's chroma. Being gamut-relative, the input's
+     * chroma matters only at the anchor step; an achromatic input collapses the
+     * anchor fraction to 0, yielding a V-shaped, colored scale (full at the ends,
+     * gray at the anchor).
      *
      * @default 0
      */
-    chromaCurve?: number;
+    chromaCurve?: number | ScaleChromaPeak | ScaleRange;
     /**
      * Output color format.
      *
@@ -927,14 +974,36 @@ interface ScaleOptions {
      * If not specified, the output will match the format of the input color.
      */
     format?: ColorType;
+    /**
+     * Hue rotation across the scale, in degrees.
+     *
+     * A scalar `x` is shorthand for `{ low: -x, high: x }`.
+     * `low` shifts the low-key end (50), `high` the high-key end (950); shifts
+     * blend to 0° at the lock step (or the middle step when not locked), so the
+     * input hue is preserved there. The per-step gamut clamp follows the
+     * shifted hue.
+     *
+     * Values must be within [-180, 180].
+     *
+     * @default 0
+     */
+    hueShift?: number | ScaleRange;
     /**
      * The lightness tuning factor for the scale.
      * - 1: Linear lightness distribution.
      * - >1: Lighter tones are emphasized.
      * - <1: Darker tones are emphasized.
+     *
+     * A scalar `x` is shorthand for `{ low: x, high: x }`. With `{ low, high }`
+     * each half of the scale gets its own exponent: `low` shapes the low-key
+     * half (toward 50), `high` the high-key half (toward 950), split at the
+     * lock step when locked or blended continuously when not.
+     * Reference palettes typically fit `{ low: 1.5, high: 1 }`.
+     *
+     * Values must be greater than 0.
      * @default 1.5
      */
-    lightnessCurve?: number;
+    lightnessCurve?: number | ScaleRange;
     /**
      * Lock input color's lightness at specific step position.
      *
@@ -945,6 +1014,11 @@ interface ScaleOptions {
      * Must be a valid step key for the current step count.
      * Default step keys (11 steps): 50, 100, 200, 300, 400, 500, 600, 700, 800, 900, 950.
      * Step keys vary based on the `steps` option (3-20 steps supported).
+     *
+     * When locked at the first or last step, only one side of the scale remains,
+     * so the unused-side value (`low`/`high`) of asymmetric options
+     * (`hueShift`, `lightnessCurve`, endpoint `chromaCurve`) has no effect and
+     * emits a warning.
      */
     lock?: number;
     /**
@@ -1002,6 +1076,16 @@ interface ScaleOptions {
      */
     variant?: ScaleVariant;
 }
+/**
+ * Endpoint values for an asymmetric scale option.
+ *
+ * `low` applies at the low-key end (50), `high` at the high-key end (950),
+ * regardless of `mode` — keys, not lightness, define the ends.
+ */
+interface ScaleRange {
+    high: number;
+    low: number;
+}
 /**
  * Generate a scale of colors based on the input color.
  *
@@ -1058,4 +1142,4 @@ declare function toGamut(input: string, format?: ColorType): string;
  */
 declare function transparentize(input: string, alpha: number, format?: ColorType): string;
 
-export { APCA_VERSION, type Analysis, type ColorKeysTuple, type ColorModel, type ColorModelKey, type ColorModelKeys, type ColorReturn, type ColorTuple, type ColorType, type ColorTypeInput, type ColorValue, type ColorizrOptions, type ConverterParameters, DELTA_E_JND, type FormatCSSOptions, type HEX, type HSL, type HueMode, type LAB, type LCH, type MixOptions, type PaletteOptions, type PlainObject, type RGB, type ReadableColorMethod, type ReadableColorOptions, type ScaleOptions, type ScaleVariant, type Scheme, type SchemeOptions, addAlphaToHex, apcaContrast, brightnessDifference, chroma, colorDifference, compare, contrast, convertAlphaToHex, convertCSS, darken, Colorizr as default, deltaE, desaturate, extractAlphaFromHex, extractColorParts, formatCSS, formatHex, getColorType, getP3MaxChroma, getP3MaxColor, getScaleStepKeys, grayscale, hex2hsl, hex2oklab, hex2oklch, hex2rgb, hsl2hex, hsl2oklab, hsl2oklch, hsl2rgb, invert, isHSL, isHex, isLAB, isLCH, isRGB, isValidColor, lighten, luminance, mix, name, oklab2hex, oklab2hsl, oklab2oklch, oklab2rgb, oklch2hex, oklch2hsl, oklch2oklab, oklch2rgb, opacify, opacity, palette, parseCSS, random, readableColor, removeAlphaFromHex, rgb2hex, rgb2hsl, rgb2oklab, rgb2oklch, rotate, saturate, scale, scheme, toGamut, transparentize };
+export { APCA_VERSION, type Analysis, CLMS_TO_OKLAB, type ColorKeysTuple, type ColorModel, type ColorModelKey, type ColorModelKeys, type ColorReturn, type ColorTuple, type ColorType, type ColorTypeInput, type ColorValue, type ColorizrOptions, type ConverterParameters, DEG2RAD, DELTA_E_JND, type FormatCSSOptions, GAMUT_EPSILON, type HEX, type HSL, type HueMode, type LAB, type LCH, LMS_TO_LRGB, LRGB_TO_LMS, type MixOptions, OKLAB_TO_CLMS, P3_TO_SRGB, P3_TO_XYZ, PRECISION, type PaletteOptions, type PlainObject, RAD2DEG, type RGB, type ReadableColorMethod, type ReadableColorOptions, SRGB_TO_P3, type ScaleChromaPeak, type ScaleOptions, type ScaleRange, type ScaleVariant, type Scheme, type SchemeOptions, XYZ_TO_SRGB, addAlphaToHex, apcaContrast, brightnessDifference, chroma, colorDifference, compare, contrast, convertAlphaToHex, convertCSS, darken, Colorizr as default, deltaE, desaturate, extractAlphaFromHex, extractColorParts, formatCSS, formatHex, getColorType, getP3MaxChroma, getP3MaxColor, getScaleStepKeys, grayscale, hex2hsl, hex2oklab, hex2oklch, hex2rgb, hsl2hex, hsl2oklab, hsl2oklch, hsl2rgb, invert, isHSL, isHex, isInGamut, isLAB, isLCH, isRGB, isValidColor, lighten, luminance, mix, name, oklab2hex, oklab2hsl, oklab2oklch, oklab2rgb, oklabToLinearP3, oklabToLinearSRGB, oklch2hex, oklch2hsl, oklch2oklab, oklch2rgb, opacify, opacity, palette, parseCSS, random, readableColor, removeAlphaFromHex, rgb2hex, rgb2hsl, rgb2oklab, rgb2oklch, rotate, saturate, scale, scheme, srgbGammaDecode, srgbGammaEncode, toGamut, transparentize };

package/dist/index.d.ts

@@ -658,6 +658,26 @@ declare function extractAlphaFromHex(input: string): number;
  */
 declare function removeAlphaFromHex(input: string): HEX;
 
+declare const CLMS_TO_OKLAB: number[][];
+declare const DEG2RAD: number;
+declare const LMS_TO_LRGB: number[][];
+declare const LRGB_TO_LMS: number[][];
+declare const OKLAB_TO_CLMS: number[][];
+declare const P3_TO_SRGB: number[][];
+declare const P3_TO_XYZ: number[][];
+declare const SRGB_TO_P3: number[][];
+declare const XYZ_TO_SRGB: number[][];
+declare const GAMUT_EPSILON = 0.000001;
+declare const PRECISION = 5;
+declare const RAD2DEG: number;
+
+declare function srgbGammaDecode(input: number): number;
+declare function srgbGammaEncode(input: number): number;
+
+declare function isInGamut(color: ColorTuple): boolean;
+declare function oklabToLinearP3(L: number, a: number, b: number): ColorTuple;
+declare function oklabToLinearSRGB(L: number, a: number, b: number): ColorTuple;
+
 /**
  * Get the step keys for a given step count.
  *
@@ -901,6 +921,18 @@ declare function saturate(input: string, amount: number, format?: ColorType): st
 
 type ScaleMode = 'light' | 'dark';
 type ScaleVariant = 'deep' | 'neutral' | 'pastel' | 'subtle' | 'vibrant';
+/**
+ * Parabolic chroma curve with a movable center.
+ */
+interface ScaleChromaPeak {
+    /** Blend between constant chroma (0) and the full parabola (1). */
+    amount: number;
+    /**
+     * Lightness (exclusive 0-1) where chroma stays at full base.
+     * @default 0.5
+     */
+    peak?: number;
+}
 /**
  * Options for generating a color scale.
  *
@@ -911,14 +943,29 @@ type ScaleVariant = 'deep' | 'neutral' | 'pastel' | 'subtle' | 'vibrant';
  */
 interface ScaleOptions {
     /**
-     * Controls chroma distribution across lightness levels (0-1).
+     * Controls how chroma flows across the scale. Three forms:
+     *
+     * Scalar (0-1) — parabolic blend centered at mid-lightness:
      * - 0: Constant chroma across all steps (default).
-     * - 1: Parabolic curve — full chroma at mid-lightness, reduced toward extremes.
-     * - Values between interpolate between constant and parabolic.
+     * - 1: Full parabola — peak chroma at mid-lightness, reduced toward extremes.
+     * Shorthand for `{ amount: x }`.
+     *
+     * `{ amount, peak }` — the same parabola with a movable center.
+     * `peak` is the lightness (exclusive 0-1) that keeps full base chroma;
+     * sides away from it are reduced. Defaults to 0.5.
+     *
+     * `{ low, high }` — fractions (0-1) of the maximum P3 chroma at each step,
+     * blended from `low` (50-end) through the input color's own fraction at the
+     * lock/middle step to `high` (950-end). NOT equivalent to the scalar form —
+     * it is a different model: values set chroma relative to the gamut ceiling
+     * instead of bending the input's chroma. Being gamut-relative, the input's
+     * chroma matters only at the anchor step; an achromatic input collapses the
+     * anchor fraction to 0, yielding a V-shaped, colored scale (full at the ends,
+     * gray at the anchor).
      *
      * @default 0
      */
-    chromaCurve?: number;
+    chromaCurve?: number | ScaleChromaPeak | ScaleRange;
     /**
      * Output color format.
      *
@@ -927,14 +974,36 @@ interface ScaleOptions {
      * If not specified, the output will match the format of the input color.
      */
     format?: ColorType;
+    /**
+     * Hue rotation across the scale, in degrees.
+     *
+     * A scalar `x` is shorthand for `{ low: -x, high: x }`.
+     * `low` shifts the low-key end (50), `high` the high-key end (950); shifts
+     * blend to 0° at the lock step (or the middle step when not locked), so the
+     * input hue is preserved there. The per-step gamut clamp follows the
+     * shifted hue.
+     *
+     * Values must be within [-180, 180].
+     *
+     * @default 0
+     */
+    hueShift?: number | ScaleRange;
     /**
      * The lightness tuning factor for the scale.
      * - 1: Linear lightness distribution.
      * - >1: Lighter tones are emphasized.
      * - <1: Darker tones are emphasized.
+     *
+     * A scalar `x` is shorthand for `{ low: x, high: x }`. With `{ low, high }`
+     * each half of the scale gets its own exponent: `low` shapes the low-key
+     * half (toward 50), `high` the high-key half (toward 950), split at the
+     * lock step when locked or blended continuously when not.
+     * Reference palettes typically fit `{ low: 1.5, high: 1 }`.
+     *
+     * Values must be greater than 0.
      * @default 1.5
      */
-    lightnessCurve?: number;
+    lightnessCurve?: number | ScaleRange;
     /**
      * Lock input color's lightness at specific step position.
      *
@@ -945,6 +1014,11 @@ interface ScaleOptions {
      * Must be a valid step key for the current step count.
      * Default step keys (11 steps): 50, 100, 200, 300, 400, 500, 600, 700, 800, 900, 950.
      * Step keys vary based on the `steps` option (3-20 steps supported).
+     *
+     * When locked at the first or last step, only one side of the scale remains,
+     * so the unused-side value (`low`/`high`) of asymmetric options
+     * (`hueShift`, `lightnessCurve`, endpoint `chromaCurve`) has no effect and
+     * emits a warning.
      */
     lock?: number;
     /**
@@ -1002,6 +1076,16 @@ interface ScaleOptions {
      */
     variant?: ScaleVariant;
 }
+/**
+ * Endpoint values for an asymmetric scale option.
+ *
+ * `low` applies at the low-key end (50), `high` at the high-key end (950),
+ * regardless of `mode` — keys, not lightness, define the ends.
+ */
+interface ScaleRange {
+    high: number;
+    low: number;
+}
 /**
  * Generate a scale of colors based on the input color.
  *
@@ -1058,4 +1142,4 @@ declare function toGamut(input: string, format?: ColorType): string;
  */
 declare function transparentize(input: string, alpha: number, format?: ColorType): string;
 
-export { APCA_VERSION, type Analysis, type ColorKeysTuple, type ColorModel, type ColorModelKey, type ColorModelKeys, type ColorReturn, type ColorTuple, type ColorType, type ColorTypeInput, type ColorValue, type ColorizrOptions, type ConverterParameters, DELTA_E_JND, type FormatCSSOptions, type HEX, type HSL, type HueMode, type LAB, type LCH, type MixOptions, type PaletteOptions, type PlainObject, type RGB, type ReadableColorMethod, type ReadableColorOptions, type ScaleOptions, type ScaleVariant, type Scheme, type SchemeOptions, addAlphaToHex, apcaContrast, brightnessDifference, chroma, colorDifference, compare, contrast, convertAlphaToHex, convertCSS, darken, Colorizr as default, deltaE, desaturate, extractAlphaFromHex, extractColorParts, formatCSS, formatHex, getColorType, getP3MaxChroma, getP3MaxColor, getScaleStepKeys, grayscale, hex2hsl, hex2oklab, hex2oklch, hex2rgb, hsl2hex, hsl2oklab, hsl2oklch, hsl2rgb, invert, isHSL, isHex, isLAB, isLCH, isRGB, isValidColor, lighten, luminance, mix, name, oklab2hex, oklab2hsl, oklab2oklch, oklab2rgb, oklch2hex, oklch2hsl, oklch2oklab, oklch2rgb, opacify, opacity, palette, parseCSS, random, readableColor, removeAlphaFromHex, rgb2hex, rgb2hsl, rgb2oklab, rgb2oklch, rotate, saturate, scale, scheme, toGamut, transparentize };
+export { APCA_VERSION, type Analysis, CLMS_TO_OKLAB, type ColorKeysTuple, type ColorModel, type ColorModelKey, type ColorModelKeys, type ColorReturn, type ColorTuple, type ColorType, type ColorTypeInput, type ColorValue, type ColorizrOptions, type ConverterParameters, DEG2RAD, DELTA_E_JND, type FormatCSSOptions, GAMUT_EPSILON, type HEX, type HSL, type HueMode, type LAB, type LCH, LMS_TO_LRGB, LRGB_TO_LMS, type MixOptions, OKLAB_TO_CLMS, P3_TO_SRGB, P3_TO_XYZ, PRECISION, type PaletteOptions, type PlainObject, RAD2DEG, type RGB, type ReadableColorMethod, type ReadableColorOptions, SRGB_TO_P3, type ScaleChromaPeak, type ScaleOptions, type ScaleRange, type ScaleVariant, type Scheme, type SchemeOptions, XYZ_TO_SRGB, addAlphaToHex, apcaContrast, brightnessDifference, chroma, colorDifference, compare, contrast, convertAlphaToHex, convertCSS, darken, Colorizr as default, deltaE, desaturate, extractAlphaFromHex, extractColorParts, formatCSS, formatHex, getColorType, getP3MaxChroma, getP3MaxColor, getScaleStepKeys, grayscale, hex2hsl, hex2oklab, hex2oklch, hex2rgb, hsl2hex, hsl2oklab, hsl2oklch, hsl2rgb, invert, isHSL, isHex, isInGamut, isLAB, isLCH, isRGB, isValidColor, lighten, luminance, mix, name, oklab2hex, oklab2hsl, oklab2oklch, oklab2rgb, oklabToLinearP3, oklabToLinearSRGB, oklch2hex, oklch2hsl, oklch2oklab, oklch2rgb, opacify, opacity, palette, parseCSS, random, readableColor, removeAlphaFromHex, rgb2hex, rgb2hsl, rgb2oklab, rgb2oklch, rotate, saturate, scale, scheme, srgbGammaDecode, srgbGammaEncode, toGamut, transparentize };