colorutils.ts

// @ts-nocheck
'use strict';

/**
 * This code is mostly from the old Etherpad. Please help us to comment this code.
 * This helps other people to understand this code better and helps them to improve it.
 * TL;DR COMMENTS ON THIS FILE ARE HIGHLY APPRECIATED
 */

// DO NOT EDIT THIS FILE, edit infrastructure/ace/www/colorutils.js
// THIS FILE IS ALSO SERVED AS CLIENT-SIDE JS
/**
 * Copyright 2009 Google Inc.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS-IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

const colorutils = {};

// Check that a given value is a css hex color value, e.g.
// "#ffffff" or "#fff"
colorutils.isCssHex = (cssColor) => /^#([0-9a-f]{3}|[0-9a-f]{6})$/i.test(cssColor);

// "#ffffff" or "#fff" or "ffffff" or "fff" to [1.0, 1.0, 1.0]
colorutils.css2triple = (cssColor) => {
  const sixHex = colorutils.css2sixhex(cssColor);

  const hexToFloat = (hh) => Number(`0x${hh}`) / 255;
  return [
    hexToFloat(sixHex.substr(0, 2)),
    hexToFloat(sixHex.substr(2, 2)),
    hexToFloat(sixHex.substr(4, 2)),
  ];
};

// "#ffffff" or "#fff" or "ffffff" or "fff" to "ffffff"
colorutils.css2sixhex = (cssColor) => {
  let h = /[0-9a-fA-F]+/.exec(cssColor)[0];
  if (h.length !== 6) {
    const a = h.charAt(0);
    const b = h.charAt(1);
    const c = h.charAt(2);
    h = a + a + b + b + c + c;
  }
  return h;
};

// [1.0, 1.0, 1.0] -> "#ffffff"
colorutils.triple2css = (triple) => {
  const floatToHex = (n) => {
    const n2 = colorutils.clamp(Math.round(n * 255), 0, 255);
    return (`0${n2.toString(16)}`).slice(-2);
  };
  return `#${floatToHex(triple[0])}${floatToHex(triple[1])}${floatToHex(triple[2])}`;
};


colorutils.clamp = (v, bot, top) => v < bot ? bot : (v > top ? top : v);
colorutils.min3 = (a, b, c) => (a < b) ? (a < c ? a : c) : (b < c ? b : c);
colorutils.max3 = (a, b, c) => (a > b) ? (a > c ? a : c) : (b > c ? b : c);
colorutils.colorMin = (c) => colorutils.min3(c[0], c[1], c[2]);
colorutils.colorMax = (c) => colorutils.max3(c[0], c[1], c[2]);
colorutils.scale = (v, bot, top) => colorutils.clamp(bot + v * (top - bot), 0, 1);
colorutils.unscale = (v, bot, top) => colorutils.clamp((v - bot) / (top - bot), 0, 1);

colorutils.scaleColor = (c, bot, top) => [
  colorutils.scale(c[0], bot, top),
  colorutils.scale(c[1], bot, top),
  colorutils.scale(c[2], bot, top),
];

colorutils.unscaleColor = (c, bot, top) => [
  colorutils.unscale(c[0], bot, top),
  colorutils.unscale(c[1], bot, top),
  colorutils.unscale(c[2], bot, top),
];

// rule of thumb for RGB brightness; 1.0 is white
colorutils.luminosity = (c) => c[0] * 0.30 + c[1] * 0.59 + c[2] * 0.11;

colorutils.saturate = (c) => {
  const min = colorutils.colorMin(c);
  const max = colorutils.colorMax(c);
  if (max - min <= 0) return [1.0, 1.0, 1.0];
  return colorutils.unscaleColor(c, min, max);
};

colorutils.blend = (c1, c2, t) => [
  colorutils.scale(t, c1[0], c2[0]),
  colorutils.scale(t, c1[1], c2[1]),
  colorutils.scale(t, c1[2], c2[2]),
];

colorutils.invert = (c) => [1 - c[0], 1 - c[1], 1 - c[2]];

colorutils.complementary = (c) => {
  const inv = colorutils.invert(c);
  return [
    (inv[0] >= c[0]) ? Math.min(inv[0] * 1.30, 1) : (c[0] * 0.30),
    (inv[1] >= c[1]) ? Math.min(inv[1] * 1.59, 1) : (c[1] * 0.59),
    (inv[2] >= c[2]) ? Math.min(inv[2] * 1.11, 1) : (c[2] * 0.11),
  ];
};

colorutils.textColorFromBackgroundColor = (bgcolor, skinName) => {
  const white = skinName === 'colibris' ? 'var(--super-light-color)' : '#fff';
  const black = skinName === 'colibris' ? 'var(--super-dark-color)' : '#222';

  return colorutils.luminosity(colorutils.css2triple(bgcolor)) < 0.5 ? white : black;
};

// --- WCAG 2.1 contrast helpers (issue #7377) ---------------------------------
// Authors can pick any background color via the color picker; previously we
// chose black/white text purely on the 0.5-luminosity threshold, which left a
// band of mid-tone author colors (dark reds, muted blues) where neither text
// color satisfied WCAG 2.1 AA (4.5:1 contrast) and the pad was genuinely hard
// to read. These helpers let the editor clamp an author's effective background
// on the rendering side (without mutating their stored color choice) so every
// viewer gets a readable result regardless of what the author picked.

// WCAG 2.1 relative luminance
//   https://www.w3.org/TR/WCAG21/#dfn-relative-luminance
// Takes an sRGB triple in [0, 1] and returns the linear luminance in [0, 1].
colorutils.relativeLuminance = (c) => {
  const toLinear = (v) => v <= 0.03928 ? v / 12.92 : Math.pow((v + 0.055) / 1.055, 2.4);
  return 0.2126 * toLinear(c[0]) + 0.7152 * toLinear(c[1]) + 0.0722 * toLinear(c[2]);
};

// WCAG 2.1 contrast ratio between two sRGB triples, in [1, 21].
// 4.5 = AA for body text; 7.0 = AAA.
colorutils.contrastRatio = (c1, c2) => {
  const l1 = colorutils.relativeLuminance(c1);
  const l2 = colorutils.relativeLuminance(c2);
  return (Math.max(l1, l2) + 0.05) / (Math.min(l1, l2) + 0.05);
};

// Lighten the given background until black text on top of it meets the target
// WCAG contrast ratio (default 4.5:1 — AA for body text). Returns a css hex
// string. If the original color already satisfies the threshold against
// *either* black or white text it's returned unchanged, so we don't repaint
// users whose choices were already fine.
//
// The blend toward white preserves hue, so a dark red becomes a more readable
// pink-red rather than an unrelated color. Viewers always see a readable
// result; the author's stored color is not modified, so disabling
// `enforceReadableAuthorColors` restores the original at any time.
colorutils.ensureReadableBackground = (cssColor, minContrast) => {
  if (minContrast == null) minContrast = 4.5;
  const triple = colorutils.css2triple(cssColor);
  const black = [0, 0, 0];
  const white = [1, 1, 1];
  if (colorutils.contrastRatio(triple, black) >= minContrast) return cssColor;
  if (colorutils.contrastRatio(triple, white) >= minContrast) return cssColor;
  // Iteratively blend toward white; 20 steps (5% each) clear every sRGB
  // starting point without producing noticeably different colors.
  for (let i = 1; i <= 20; i++) {
    const blended = colorutils.blend(triple, white, i * 0.05);
    if (colorutils.contrastRatio(blended, black) >= minContrast) {
      return colorutils.triple2css(blended);
    }
  }
  return '#ffffff';
};

exports.colorutils = colorutils;