@markgorzynski/color-utils/src/chromaControl.js

The only color science library with adaptive visual perception modeling and accessibility-driven optimization.

/**
 * @file src/chromaControl.js
 * @module color-utils/chromaControl
 * @description Provides advanced functions for controlling Oklch chroma and AOkLab Lightness
 * to achieve specific target CIE Luminance (derived from CIELAB L*) values,
 * while leveraging the AOkLab model for its surround adaptation and hue uniformity.
 * This enables the creation of color palettes that are both perceptually harmonious
 * under various viewing conditions and compliant with WCAG contrast requirements.
 *
 * **Key Features & Novel Approach:**
 *
 * This module offers a unique combination of capabilities not commonly found together:
 *
 * 1.  **Leverages Oklab's Excellent Hue Uniformity:**
 * By working with AOkLab Hue (H_aok) and Chroma (C_aok), which are based on Oklab's
 * structure, this module benefits from Oklab's superior hue linearity compared to
 * spaces like CIELAB (especially in blue regions, avoiding violet shifts).
 *
 * 2.  **Leverages Oklab's Simplicity and Speed (as a base for AOkLab):**
 * AOkLab, built upon Oklab, is computationally more efficient than full
 * Color Appearance Models (CAMs) like CIECAM16, making these advanced
 * adjustments practical for dynamic applications.
 *
 * 3.  **Integrates AOkLab's Surround Correction (New for an Oklab-based framework):**
 * The core AOkLab model (`AdaptiveOklab` class from `aoklab.js`) adjusts its
 * internal lightness mapping based on 'white', 'gray', or 'dark' surround
 * conditions. This module uses a configured AOkLab instance, meaning all
 * color transformations inherently account for the specified surround adaptation.
 * This is achieved by AOkLab using a derived adaptive exponent `p` and a
 * hue correction factor `x0^((1/3)-p)`.
 *
 * 4.  **Enables Constant WCAG Contrast & CIE Luminance Compatibility (Novel Combination):**
 * - Standard Oklab/AOkLab Lightness (L_ok / L_aok) does not directly correlate
 * with CIE Luminance (Y) or provide straightforward WCAG contrast control.
 * - This module solves this by allowing users to specify a **target CIELAB L*** value.
 * This target L\* is converted to a target CIE Relative Luminance (Y_cie).
 * - An iterative search then finds the **AOkLab Lightness (L_aok)** that, for a
 * given AOkLab Hue, AOkLab Chroma, and AOkLab surround setting, produces an
 * sRGB color matching the `Y_target_cie`.
 * - This provides precise control over physical luminance for accessibility,
 * while retaining the perceptual benefits (hue uniformity, surround adaptation)
 * of the AOkLab color model for defining the color's chromatic characteristics.
 *
 * **In essence, designers gain two powerful, previously incompatible control mechanisms:**
 * - Define color appearance (hue, colorfulness, adaptation to surround) using AOkLab.
 * - Simultaneously enforce precise luminance levels (for WCAG contrast) by targeting
 * a CIELAB L* value.
 */

// --- Type Imports for JSDoc ---
/**
 * @typedef {object} AokChromaControlOptions
 * @property {AdaptiveOklabOptions} [adaptiveOklabOptions]
 * @property {number} [tolerance=1e-4]
 * @property {number} [maxIterations=50]
 * @property {number} [chromaStep=0.005]
 * @property {number} [maxChromaSearchLimit=0.4]
 */
/** @typedef {AokChromaControlOptions & { globalTargetAokChroma?: number }} AdjustAokColorOptions */
/**
 * @typedef {object} AokChromaControlResult
 * @property {OklchColor} aokLCH
 * @property {SrgbColor} srgbColor
 * @property {number} relativeLuminanceY
 * @property {boolean} outOfGamut
 * @property {number} iterations
 */

// --- Utility and Color Module Imports ---
import { D65_WHITE_POINT_XYZ, normalizeHue } from './utils.js';
import { AdaptiveOklab } from './aoklab.js';
import { getSrgbRelativeLuminance } from './color-metrics.js';

// --- Constants for CIELAB L* to Y conversion ---
const EPSILON_CIELAB = Math.pow(6 / 29, 3);
const KAPPA_CIELAB = Math.pow(29 / 3, 3);

/**
 * Converts a CIELAB L* value to CIE relative luminance Y (0-1 scale).
 * @private
 * @param {number} L_star - CIELAB Lightness L* [0, 100].
 * @param {number} [referenceWhiteYn=100.0] - Y tristimulus of reference white.
 * @returns {number} CIE Relative Luminance Y (0-1).
 */
function _labLToRelativeY(L_star, referenceWhiteYn = 100.0) {
  if (typeof L_star !== 'number' || Number.isNaN(L_star) || L_star < 0 || L_star > 100) {
    throw new TypeError('L_star must be a number between 0 and 100.');
  }
  if (typeof referenceWhiteYn !== 'number' || Number.isNaN(referenceWhiteYn) || referenceWhiteYn <= 0) {
    throw new TypeError('referenceWhiteYn must be a positive number.');
  }
  const fy = (L_star + 16) / 116;
  const yr = (fy > Math.cbrt(EPSILON_CIELAB)) ? Math.pow(fy, 3) : (116 * fy - 16) / KAPPA_CIELAB;
  return Math.max(0, Math.min(1, yr * (referenceWhiteYn / 100.0)));
}

/**
 * Core search: Finds AOkLab L for a target CIE Y.
 * @private
 * @param {number} targetCieY
 * @param {number} targetAokChroma
 * @param {number} targetAokHue
 * @param {AdaptiveOklabOptions} aokOptions
 * @param {Required<Pick<AokChromaControlOptions, 'tolerance' | 'maxIterations'>>} searchCtrlOptions
 * @returns {{foundAokL: number, finalSrgb: SrgbColor, finalCieY: number, finalOutOfGamut: boolean, iterations: number}}
 */
function _findAokLForTargetCIELuminance(
  targetCieY,
  targetAokChroma,
  targetAokHue,
  aokOptions,
  searchCtrlOptions
) {
  const aokConverter = new AdaptiveOklab(aokOptions);
  let lowAokL = 0.0;
  let highAokL = 1.0;
  let midAokL = Math.max(0, Math.min(1, targetCieY));
  let iterations = 0;

  let bestMatch = {
    foundAokL: midAokL,
    finalSrgb: { r: 0.5, g: 0.5, b: 0.5 },
    finalCieY: 0.5,
    finalOutOfGamut: true,
    diffY: Infinity,
  };

  for (iterations = 0; iterations < searchCtrlOptions.maxIterations; iterations++) {
    midAokL = (lowAokL + highAokL) / 2;
    if (Math.abs(highAokL - lowAokL) < 1e-7) break;

    // Convert LCH to Lab for AdaptiveOklab
    const hueRad = (targetAokHue * Math.PI) / 180;
    const candidateAokLab = { 
      L: midAokL, 
      a: targetAokChroma * Math.cos(hueRad), 
      b: targetAokChroma * Math.sin(hueRad) 
    };
    const currentSrgb = aokConverter.toSrgb(candidateAokLab);
    const currentCieY = getSrgbRelativeLuminance(currentSrgb);
    const epsilonGamut = 1e-7;
    const currentOutOfGamut =
      currentSrgb.r < -epsilonGamut || currentSrgb.r > 1 + epsilonGamut ||
      currentSrgb.g < -epsilonGamut || currentSrgb.g > 1 + epsilonGamut ||
      currentSrgb.b < -epsilonGamut || currentSrgb.b > 1 + epsilonGamut;
    const diffY = currentCieY - targetCieY;

    if (!currentOutOfGamut) {
      if (bestMatch.finalOutOfGamut || Math.abs(diffY) < Math.abs(bestMatch.diffY)) {
        bestMatch = { foundAokL: midAokL, finalSrgb: currentSrgb, finalCieY: currentCieY, finalOutOfGamut: false, diffY };
      }
      if (Math.abs(diffY) < searchCtrlOptions.tolerance) break;
    } else if (bestMatch.finalOutOfGamut && Math.abs(diffY) < Math.abs(bestMatch.diffY)) {
      bestMatch = { foundAokL: midAokL, finalSrgb: currentSrgb, finalCieY: currentCieY, finalOutOfGamut: true, diffY };
    }

    if (diffY < 0) { lowAokL = midAokL; }
    else { highAokL = midAokL; }
  }

  // Convert LCH to Lab for AdaptiveOklab
  const finalHueRad = (targetAokHue * Math.PI) / 180;
  const finalEvalAokLab = { 
    L: bestMatch.foundAokL, 
    a: targetAokChroma * Math.cos(finalHueRad), 
    b: targetAokChroma * Math.sin(finalHueRad) 
  };
  bestMatch.finalSrgb = aokConverter.toSrgb(finalEvalAokLab);
  bestMatch.finalCieY = getSrgbRelativeLuminance(bestMatch.finalSrgb);
  const epsilonGamutFinal = 1e-7;
  bestMatch.finalOutOfGamut =
    bestMatch.finalSrgb.r < -epsilonGamutFinal || bestMatch.finalSrgb.r > 1 + epsilonGamutFinal ||
    bestMatch.finalSrgb.g < -epsilonGamutFinal || bestMatch.finalSrgb.g > 1 + epsilonGamutFinal ||
    bestMatch.finalSrgb.b < -epsilonGamutFinal || bestMatch.finalSrgb.b > 1 + epsilonGamutFinal;

  return { ...bestMatch, iterations };
}

/**
 * Default options for AOkLab chroma control functions.
 * @type {Readonly<Required<AokChromaControlOptions>>}
 */
const DEFAULT_AOK_CHROMA_CONTROL_OPTIONS = Object.freeze({
  adaptiveOklabOptions: { surround: 'gray', x0: 0.5 },
  tolerance: 1e-4,
  maxIterations: 50,
  chromaStep: 0.005,
  maxChromaSearchLimit: 0.4,
});

/**
 * Finds the maximum AOkLab Chroma for a given AOkLab Hue that results in an sRGB color
 * matching a target CIELAB L* (and thus a target CIE Y), within the sRGB gamut.
 * AOkLab Lightness is internally adjusted by the search.
 *
 * @param {number} targetAokHueInput - Target AOkLab Hue in degrees [0, 360).
 * @param {number} targetLabL_forY - Target CIELAB L* [0, 100], used to derive target CIE Y.
 * @param {Partial<AokChromaControlOptions>} [userOptions={}] - Optional parameters.
 * @returns {number} Maximum achievable AOkLab Chroma (C_aok), or 0 if no in-gamut solution.
 * @throws {TypeError}
 * @example
 * const maxC = findMaxAokChromaForLabL(265, 50, {
 * adaptiveOklabOptions: { surround: 'white' }
 * });
 * console.log(`Max C_aok for H_aok=265, L*_lab=50 (white surround): ${maxC}`);
 */
export function findMaxAokChromaForLabL(targetAokHueInput, targetLabL_forY, userOptions = {}) {
  const targetAokHue = normalizeHue(targetAokHueInput);
  if (typeof targetAokHue !== 'number' || Number.isNaN(targetAokHue)) {
    throw new TypeError('targetAokHue must be a valid number.');
  }
  if (typeof targetLabL_forY !== 'number' || Number.isNaN(targetLabL_forY) || targetLabL_forY < 0 || targetLabL_forY > 100) {
    throw new TypeError('targetLabL_forY must be a number between 0 and 100.');
  }

  const options = {
    ...DEFAULT_AOK_CHROMA_CONTROL_OPTIONS,
    ...userOptions,
    adaptiveOklabOptions: {
        ...DEFAULT_AOK_CHROMA_CONTROL_OPTIONS.adaptiveOklabOptions,
        ...(userOptions.adaptiveOklabOptions || {})
    }
  };

  const targetCieY = _labLToRelativeY(targetLabL_forY, D65_WHITE_POINT_XYZ.Y);
  let currentAokChroma = options.maxChromaSearchLimit;
  let maxInGamutAokChroma = 0;

  while (currentAokChroma >= -options.chromaStep/2) {
    const searchResult = _findAokLForTargetCIELuminance(
      targetCieY,
      Math.max(0, currentAokChroma),
      targetAokHue,
      options.adaptiveOklabOptions,
      options
    );
    if (!searchResult.finalOutOfGamut && Math.abs(searchResult.finalCieY - targetCieY) < options.tolerance * 5) {
      maxInGamutAokChroma = Math.max(0, currentAokChroma);
      break;
    }
    currentAokChroma -= options.chromaStep;
  }
  // Final check for C=0 if nothing found, as achromatic should always be possible if Y is valid.
  if (maxInGamutAokChroma === 0 && currentAokChroma < 0) {
      const achromaticSearch = _findAokLForTargetCIELuminance(targetCieY, 0, targetAokHue, options.adaptiveOklabOptions, options);
      if (!achromaticSearch.finalOutOfGamut && Math.abs(achromaticSearch.finalCieY - targetCieY) < options.tolerance * 5) {
          return 0; // Achromatic is possible
      }
      // else truly nothing found, return 0, or could throw error if Y target is impossible (e.g. Y=0 or Y=1 with C>0)
  }
  return maxInGamutAokChroma;
}

/**
 * Adjusts an AOkLab color (defined by Hue and target Chroma) to match a target CIELAB L*
 * (by matching its corresponding CIE Luminance Y), respecting sRGB gamut.
 * The output AOkLab Lightness is found by iterative search.
 *
 * @param {{L?: number, C: number, h: number}} inputAokLCHHint - Provides target AOkLab Hue (h),
 * and target/initial AOkLab Chroma (C). The L component is ignored.
 * @param {number} targetLabL_forY - Target CIELAB L* [0, 100] for the output's luminance.
 * @param {'clip' | 'target'} mode - How chroma is handled:
 * - 'clip': `inputAokLCHHint.C` is target, clipped to max achievable at `targetLabL_forY`.
 * - 'target': `userOptions.globalTargetAokChroma` is target, clipped to max achievable.
 * @param {Partial<AdjustAokColorOptions>} [userOptions={}] - Optional parameters.
 * If `mode` is 'target', `userOptions.globalTargetAokChroma` is required.
 * @returns {AokChromaControlResult} Result object.
 * @throws {TypeError|Error}
 * @example
 * const blueHint = { C: 0.1, h: 265 };
 * const result = adjustAokColorToLabL(blueHint, 50, 'clip', {
 * adaptiveOklabOptions: { surround: 'white' }
 * });
 * if (!result.outOfGamut) {
 * console.log('White adapted L*50 Blue:', result.aokLCH, 'sRGB:', result.srgbColor);
 * }
 */
export function adjustAokColorToLabL(inputAokLCHHint, targetLabL_forY, mode, userOptions = {}) {
  if (
    typeof inputAokLCHHint !== 'object' || inputAokLCHHint === null ||
    typeof inputAokLCHHint.C !== 'number' || Number.isNaN(inputAokLCHHint.C) ||
    typeof inputAokLCHHint.h !== 'number' || Number.isNaN(inputAokLCHHint.h)
  ) {
    throw new TypeError('inputAokLCHHint must be an object with C and h valid number properties.');
  }
  const targetAokHue = normalizeHue(inputAokLCHHint.h);

  if (typeof targetLabL_forY !== 'number' || Number.isNaN(targetLabL_forY) || targetLabL_forY < 0 || targetLabL_forY > 100) {
    throw new TypeError('targetLabL_forY must be a number between 0 and 100.');
  }
  if (mode !== 'clip' && mode !== 'target') {
    throw new TypeError("Mode must be either 'clip' or 'target'.");
  }

  const options = {
    ...DEFAULT_AOK_CHROMA_CONTROL_OPTIONS,
    ...userOptions,
    adaptiveOklabOptions: {
      ...DEFAULT_AOK_CHROMA_CONTROL_OPTIONS.adaptiveOklabOptions,
      ...(userOptions.adaptiveOklabOptions || {})
    }
  };

  if (mode === 'target' && (typeof options.globalTargetAokChroma !== 'number' || Number.isNaN(options.globalTargetAokChroma))) {
    throw new Error("The 'globalTargetAokChroma' option must be provided and be a valid number for 'target' mode.");
  }

  const maxAchievableAokChroma = findMaxAokChromaForLabL(targetAokHue, targetLabL_forY, options);

  let finalTargetAokChroma;
  if (mode === 'target') {
    finalTargetAokChroma = Math.min(options.globalTargetAokChroma, maxAchievableAokChroma);
  } else { // mode === 'clip'
    finalTargetAokChroma = Math.min(inputAokLCHHint.C, maxAchievableAokChroma);
  }
  finalTargetAokChroma = Math.max(0, finalTargetAokChroma);

  const targetCieY = _labLToRelativeY(targetLabL_forY, D65_WHITE_POINT_XYZ.Y);

  const searchResult = _findAokLForTargetCIELuminance(
    targetCieY,
    finalTargetAokChroma,
    targetAokHue,
    options.adaptiveOklabOptions,
    options
  );

  return {
    aokLCH: { L: searchResult.foundAokL, C: finalTargetAokChroma, h: targetAokHue },
    srgbColor: searchResult.finalSrgb,
    relativeLuminanceY: searchResult.finalCieY,
    outOfGamut: searchResult.finalOutOfGamut,
    iterations: searchResult.iterations,
  };
}