colorizr 5.0.1 → 5.1.0

package/dist/index.d.mts

@@ -921,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.
  *
@@ -931,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.
      *
@@ -947,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.
      *
@@ -965,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;
     /**
@@ -1022,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.
  *
@@ -1078,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, 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 ScaleOptions, 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 };
+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

@@ -921,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.
  *
@@ -931,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.
      *
@@ -947,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.
      *
@@ -965,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;
     /**
@@ -1022,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.
  *
@@ -1078,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, 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 ScaleOptions, 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 };
+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.js

@@ -2177,11 +2177,53 @@ var chromaScale = {
   subtle: 0.2,
   vibrant: 1.25
 };
+function assertScaleObject(value, label) {
+  invariant(isPlainObject(value), `${label} must be a number or an object.`);
+}
+function computeLightnessMapWithLock(lock, inputLightness, keys, lightnessCurve, maxLightness, minLightness, mode) {
+  const lightnessMap = {};
+  const lockIndex = keys.indexOf(lock);
+  lightnessMap[lock] = inputLightness;
+  if (lockIndex > 0) {
+    const target = mode === "light" ? maxLightness : minLightness;
+    for (let index = 0; index < lockIndex; index++) {
+      const t = index / lockIndex;
+      lightnessMap[keys[index]] = target + (inputLightness - target) * t ** lightnessCurve.low;
+    }
+  }
+  const remaining = keys.length - 1 - lockIndex;
+  if (remaining > 0) {
+    const target = mode === "light" ? minLightness : maxLightness;
+    for (let index = lockIndex + 1; index < keys.length; index++) {
+      const t = (index - lockIndex) / remaining;
+      lightnessMap[keys[index]] = inputLightness + (target - inputLightness) * t ** lightnessCurve.high;
+    }
+  }
+  return lightnessMap;
+}
+function computeLightnessMapWithoutLock(keys, lightnessCurve, maxLightness, minLightness, mode) {
+  const lightnessMap = {};
+  for (let index = 0; index < keys.length; index++) {
+    const tBase = index / (keys.length - 1);
+    const exponent = lightnessCurve.low + (lightnessCurve.high - lightnessCurve.low) * tBase;
+    const t = tBase ** exponent;
+    lightnessMap[keys[index]] = mode === "light" ? maxLightness - (maxLightness - minLightness) * t : minLightness + (maxLightness - minLightness) * t;
+  }
+  return lightnessMap;
+}
+function computeStepHue(hue, hueShift, index, anchorIndex, keysLength) {
+  if (hueShift.low === 0 && hueShift.high === 0 || index === anchorIndex) {
+    return hue;
+  }
+  const shift = index < anchorIndex ? hueShift.low * (1 - index / anchorIndex) : hueShift.high * ((index - anchorIndex) / (keysLength - 1 - anchorIndex));
+  return (hue + shift + 360) % 360;
+}
 function generatePalette(options) {
   const {
     baseChroma,
     chromaCurve,
     hue,
+    hueShift,
     inputLightness,
     keys,
     lightnessCurve,
@@ -2191,52 +2233,113 @@ function generatePalette(options) {
     mode
   } = options;
   const palette2 = {};
-  const lightnessMap = {};
-  if (lock !== void 0 && inputLightness !== void 0) {
-    const lockIndex = keys.indexOf(lock);
-    lightnessMap[lock] = inputLightness;
-    if (lockIndex > 0) {
-      const target = mode === "light" ? maxLightness : minLightness;
-      for (let index = 0; index < lockIndex; index++) {
-        const t = index / lockIndex;
-        lightnessMap[keys[index]] = target + (inputLightness - target) * t ** lightnessCurve;
-      }
-    }
-    const remaining = keys.length - 1 - lockIndex;
-    if (remaining > 0) {
-      const target = mode === "light" ? minLightness : maxLightness;
-      for (let index = lockIndex + 1; index < keys.length; index++) {
-        const t = (index - lockIndex) / remaining;
-        lightnessMap[keys[index]] = inputLightness + (target - inputLightness) * t ** lightnessCurve;
-      }
-    }
-  } else {
-    for (let index = 0; index < keys.length; index++) {
-      const t = (index / (keys.length - 1)) ** lightnessCurve;
-      lightnessMap[keys[index]] = mode === "light" ? maxLightness - (maxLightness - minLightness) * t : minLightness + (maxLightness - minLightness) * t;
-    }
-  }
-  for (const key of keys) {
+  const lightnessMap = lock !== void 0 && inputLightness !== void 0 ? computeLightnessMapWithLock(
+    lock,
+    inputLightness,
+    keys,
+    lightnessCurve,
+    maxLightness,
+    minLightness,
+    mode
+  ) : computeLightnessMapWithoutLock(keys, lightnessCurve, maxLightness, minLightness, mode);
+  const anchorIndex = lock !== void 0 ? keys.indexOf(lock) : Math.floor((keys.length - 1) / 2);
+  for (let index = 0; index < keys.length; index++) {
+    const key = keys[index];
     const lightness = lightnessMap[key];
-    const chroma2 = getStepChroma(lightness, baseChroma, chromaCurve);
-    const maxChroma = getP3MaxChroma({ l: lightness, c: 0, h: hue });
-    palette2[key] = { l: lightness, c: Math.min(chroma2, maxChroma), h: hue };
+    const stepHue = computeStepHue(hue, hueShift, index, anchorIndex, keys.length);
+    const maxChroma = getP3MaxChroma({ l: lightness, c: 0, h: stepHue });
+    const chroma2 = chromaCurve.type === "endpoints" ? getStepRelativeChroma(chromaCurve, index, anchorIndex, keys.length) * maxChroma : getStepChroma(lightness, baseChroma, chromaCurve.amount, chromaCurve.peak);
+    palette2[key] = { l: lightness, c: Math.min(chroma2, maxChroma), h: stepHue };
   }
   return palette2;
 }
-function getStepChroma(lightness, baseChroma, chromaCurve) {
-  if (chromaCurve === 0) {
+function getStepChroma(lightness, baseChroma, amount, peak) {
+  if (amount === 0) {
     return baseChroma;
   }
-  const parabolic = 4 * lightness * (1 - lightness);
-  const curveScale = 1 - chromaCurve * (1 - parabolic);
+  const parabolic = peak === 0.5 ? 4 * lightness * (1 - lightness) : Math.max(0, 1 - ((lightness - peak) / Math.max(peak, 1 - peak)) ** 2);
+  const curveScale = 1 - amount * (1 - parabolic);
   return Math.max(0, baseChroma * curveScale);
 }
+function getStepRelativeChroma(curve, index, anchorIndex, total) {
+  const { high, low, mid } = curve;
+  if (index === anchorIndex) {
+    return mid;
+  }
+  if (index < anchorIndex) {
+    return low + (mid - low) * (index / anchorIndex);
+  }
+  return mid + (high - mid) * ((index - anchorIndex) / (total - 1 - anchorIndex));
+}
+function normalizeChromaCurve(chromaCurve, lch, baseChroma) {
+  if (isNumber(chromaCurve)) {
+    invariant(isNumberInRange(chromaCurve, 0, 1), "chromaCurve must be within the range [0, 1].");
+    return { amount: chromaCurve, peak: 0.5, type: "parabola" };
+  }
+  assertScaleObject(chromaCurve, "chromaCurve");
+  if ("amount" in chromaCurve) {
+    const { amount, peak = 0.5 } = chromaCurve;
+    invariant(isNumberInRange(amount, 0, 1), "chromaCurve amount must be within the range [0, 1].");
+    invariant(
+      isNumber(peak) && peak > 0 && peak < 1,
+      "chromaCurve peak must be within the range (0, 1)."
+    );
+    return { amount, peak, type: "parabola" };
+  }
+  const { high, low } = chromaCurve;
+  invariant(
+    isNumberInRange(low, 0, 1) && isNumberInRange(high, 0, 1),
+    "chromaCurve low/high must be within the range [0, 1]."
+  );
+  const maxChromaAtInput = getP3MaxChroma(lch);
+  return {
+    high,
+    low,
+    mid: maxChromaAtInput > 0 ? clamp(baseChroma / maxChromaAtInput, 0, 1) : 0,
+    type: "endpoints"
+  };
+}
+function resolveBaseChroma(saturation, variant, lch) {
+  if (saturation !== void 0) {
+    return clamp(saturation, 0, 100) / 100 * getP3MaxChroma(lch);
+  }
+  if (variant && chromaScale[variant]) {
+    return lch.c * chromaScale[variant];
+  }
+  if (variant) {
+    warn(`variant: ${variant} is not valid, ignoring`);
+  }
+  return lch.c;
+}
+function warnIgnoredLockEndpoints(lock, keys, options) {
+  if (lock === void 0) {
+    return;
+  }
+  const lockIndex = keys.indexOf(lock);
+  if (lockIndex !== 0 && lockIndex !== keys.length - 1) {
+    return;
+  }
+  const { chromaCurve, hueShift, lightnessCurve } = options;
+  const ignored = lockIndex === 0 ? "low" : "high";
+  const ranges = [
+    ["hueShift", hueShift],
+    ["lightnessCurve", lightnessCurve]
+  ];
+  if (chromaCurve.type === "endpoints") {
+    ranges.push(["chromaCurve", { high: chromaCurve.high, low: chromaCurve.low }]);
+  }
+  for (const [name2, range] of ranges) {
+    if (range.low !== range.high) {
+      warn(`lock at ${lock} ignores ${name2}.${ignored} (${range[ignored]})`);
+    }
+  }
+}
 function scale(input, options = {}) {
   invariant(isString(input), MESSAGES.inputString);
   const {
     chromaCurve = 0,
     format,
+    hueShift = 0,
     lightnessCurve = 1.5,
     lock: lockOption,
     maxLightness = 0.97,
@@ -2250,6 +2353,22 @@ function scale(input, options = {}) {
     maxLightness > minLightness && maxLightness <= 1 && minLightness >= 0,
     "maxLightness must be greater than minLightness and within the range [0, 1]."
   );
+  if (!isNumber(hueShift)) {
+    assertScaleObject(hueShift, "hueShift");
+  }
+  const hueShiftRange = isNumber(hueShift) ? { low: -hueShift, high: hueShift } : hueShift;
+  invariant(
+    isNumberInRange(hueShiftRange.low, -180, 180) && isNumberInRange(hueShiftRange.high, -180, 180),
+    "hueShift values must be within the range [-180, 180]."
+  );
+  if (!isNumber(lightnessCurve)) {
+    assertScaleObject(lightnessCurve, "lightnessCurve");
+  }
+  const lightnessCurveRange = isNumber(lightnessCurve) ? { low: lightnessCurve, high: lightnessCurve } : lightnessCurve;
+  invariant(
+    isNumber(lightnessCurveRange.low) && lightnessCurveRange.low > 0 && isNumber(lightnessCurveRange.high) && lightnessCurveRange.high > 0,
+    "lightnessCurve values must be greater than 0."
+  );
   const steps = stepsOption !== void 0 ? Math.round(stepsOption) : 11;
   const keys = getScaleStepKeys(steps);
   let lock = lockOption;
@@ -2259,23 +2378,22 @@ function scale(input, options = {}) {
   }
   const parsed = resolveColor(input);
   const lch = parsed.oklch;
-  let baseChroma;
-  if (saturation !== void 0) {
-    const maxChroma = getP3MaxChroma(lch);
-    baseChroma = clamp(saturation, 0, 100) / 100 * maxChroma;
-  } else if (variant && chromaScale[variant]) {
-    baseChroma = lch.c * chromaScale[variant];
-  } else {
-    baseChroma = lch.c;
-  }
+  const baseChroma = resolveBaseChroma(saturation, variant, lch);
   const colorFormat = format ?? parsed.type;
+  const chromaCurveConfig = normalizeChromaCurve(chromaCurve, lch, baseChroma);
+  warnIgnoredLockEndpoints(lock, keys, {
+    chromaCurve: chromaCurveConfig,
+    hueShift: hueShiftRange,
+    lightnessCurve: lightnessCurveRange
+  });
   const palette2 = generatePalette({
     baseChroma,
-    chromaCurve,
+    chromaCurve: chromaCurveConfig,
     hue: lch.h,
+    hueShift: hueShiftRange,
     inputLightness: lock !== void 0 ? lch.l : void 0,
     keys,
-    lightnessCurve,
+    lightnessCurve: lightnessCurveRange,
     lock,
     maxLightness,
     minLightness,