@shortfuse/materialdesignweb 0.5.0 → 0.7.1-0

package/utils/hct/Cam16.js

@@ -0,0 +1,298 @@
+/**
+ * @license
+ * Copyright 2021 Google LLC
+ *
+ * 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.
+ */
+
+import ViewingConditions from './ViewingConditions.js';
+import * as utils from './colorUtils.js';
+import * as math from './mathUtils.js';
+
+/**
+ * CAM16, a color appearance model. Colors are not just defined by their hex
+ * code, but rather, a hex code and viewing conditions.
+ *
+ * CAM16 instances also have coordinates in the CAM16-UCS space, called J*, a*,
+ * b*, or jstar, astar, bstar in code. CAM16-UCS is included in the CAM16
+ * specification, and should be used when measuring distances between colors.
+ *
+ * In traditional color spaces, a color can be identified solely by the
+ * observer's measurement of the color. Color appearance models such as CAM16
+ * also use information about the environment where the color was
+ * observed, known as the viewing conditions.
+ *
+ * For example, white under the traditional assumption of a midday sun white
+ * point is accurately measured as a slightly chromatic blue by CAM16. (roughly,
+ * hue 203, chroma 3, lightness 100)
+ */
+export default class Cam16 {
+  /**
+   * All of the CAM16 dimensions can be calculated from 3 of the dimensions, in
+   * the following combinations:
+   *      -  {j or q} and {c, m, or s} and hue
+   *      - jstar, astar, bstar
+   * Prefer using a static method that constructs from 3 of those dimensions.
+   * This constructor is intended for those methods to use to return all
+   * possible dimensions.
+   * @param {number} hue
+   * @param {number} chroma informally, colorfulness / color intensity. like saturation
+   *     in HSL, except perceptually accurate.
+   * @param {number} j lightness
+   * @param {number} q brightness; ratio of lightness to white point's lightness
+   * @param {number} m colorfulness
+   * @param {number} s saturation; ratio of chroma to white point's chroma
+   * @param {number} jstar CAM16-UCS J coordinate
+   * @param {number} astar CAM16-UCS a coordinate
+   * @param {number} bstar CAM16-UCS b coordinate
+   */
+  constructor(hue, chroma, j, q, m, s, jstar, astar, bstar) {
+    /** @readonly */
+    this.hue = hue;
+    /** @readonly */
+    this.chroma = chroma;
+    /** @readonly */
+    this.j = j;
+    /** @readonly */
+    this.q = q;
+    /** @readonly */
+    this.m = m;
+    /** @readonly */
+    this.s = s;
+    /** @readonly */
+    this.jstar = jstar;
+    /** @readonly */
+    this.astar = astar;
+    /** @readonly */
+    this.bstar = bstar;
+  }
+
+  /**
+   * CAM16 instances also have coordinates in the CAM16-UCS space, called J*,
+   * a*, b*, or jstar, astar, bstar in code. CAM16-UCS is included in the CAM16
+   * specification, and is used to measure distances between colors.
+   * @param {Cam16} other
+   * @return {number}
+   */
+  distance(other) {
+    const dJ = this.jstar - other.jstar;
+    const dA = this.astar - other.astar;
+    const dB = this.bstar - other.bstar;
+    const dEPrime = Math.sqrt(dJ * dJ + dA * dA + dB * dB);
+    const dE = 1.41 * dEPrime ** 0.63;
+    return dE;
+  }
+
+  /**
+   * @param {number} argb ARGB representation of a color.
+   * @return {Cam16} CAM16 color, assuming the color was viewed in default viewing
+   *     conditions.
+   */
+  static fromInt(argb) {
+    return Cam16.fromIntInViewingConditions(argb, ViewingConditions.DEFAULT);
+  }
+
+  /**
+   * @param {number} argb ARGB representation of a color.
+   * @param {ViewingConditions} viewingConditions Information about the environment where the color
+   *     was observed.
+   * @return {Cam16} CAM16 color.
+   */
+  static fromIntInViewingConditions(argb, viewingConditions) {
+    const red = (argb & 0x00_FF_00_00) >> 16;
+    const green = (argb & 0x00_00_FF_00) >> 8;
+    const blue = (argb & 0x00_00_00_FF);
+    const redL = utils.linearized(red);
+    const greenL = utils.linearized(green);
+    const blueL = utils.linearized(blue);
+    const x = 0.412_338_95 * redL + 0.357_620_64 * greenL + 0.180_510_42 * blueL;
+    const y = 0.2126 * redL + 0.7152 * greenL + 0.0722 * blueL;
+    const z = 0.019_321_41 * redL + 0.119_163_82 * greenL + 0.950_344_78 * blueL;
+
+    const rC = 0.401_288 * x + 0.650_173 * y - 0.051_461 * z;
+    const gC = -0.250_268 * x + 1.204_414 * y + 0.045_854 * z;
+    const bC = -0.002_079 * x + 0.048_952 * y + 0.953_127 * z;
+
+    const rD = viewingConditions.rgbD[0] * rC;
+    const gD = viewingConditions.rgbD[1] * gC;
+    const bD = viewingConditions.rgbD[2] * bC;
+
+    const rAF = ((viewingConditions.fl * Math.abs(rD)) / 100) ** 0.42;
+    const gAF = ((viewingConditions.fl * Math.abs(gD)) / 100) ** 0.42;
+    const bAF = ((viewingConditions.fl * Math.abs(bD)) / 100) ** 0.42;
+
+    const rA = (math.signum(rD) * 400 * rAF) / (rAF + 27.13);
+    const gA = (math.signum(gD) * 400 * gAF) / (gAF + 27.13);
+    const bA = (math.signum(bD) * 400 * bAF) / (bAF + 27.13);
+
+    const a = (11 * rA + -12 * gA + bA) / 11;
+    const b = (rA + gA - 2 * bA) / 9;
+    const u = (20 * rA + 20 * gA + 21 * bA) / 20;
+    const p2 = (40 * rA + 20 * gA + bA) / 20;
+    const atan2 = Math.atan2(b, a);
+    const atanDegrees = (atan2 * 180) / Math.PI;
+    const hue = atanDegrees < 0 ? atanDegrees + 360
+      : (atanDegrees >= 360 ? atanDegrees - 360
+        : atanDegrees);
+    const hueRadians = (hue * Math.PI) / 180;
+
+    const ac = p2 * viewingConditions.nbb;
+    const j = 100
+         * (ac / viewingConditions.aw) ** (viewingConditions.c * viewingConditions.z);
+    const q = (4 / viewingConditions.c) * Math.sqrt(j / 100)
+         * (viewingConditions.aw + 4) * viewingConditions.fLRoot;
+    const huePrime = hue < 20.14 ? hue + 360 : hue;
+    const eHue = 0.25 * (Math.cos((huePrime * Math.PI) / 180 + 2) + 3.8);
+    const p1 = (50_000 / 13) * eHue * viewingConditions.nc * viewingConditions.ncb;
+    const t = (p1 * Math.sqrt(a * a + b * b)) / (u + 0.305);
+    const alpha = t ** 0.9
+         * (1.64 - 0.29 ** viewingConditions.n) ** 0.73;
+    const c = alpha * Math.sqrt(j / 100);
+    const m = c * viewingConditions.fLRoot;
+    const s = 50
+         * Math.sqrt((alpha * viewingConditions.c) / (viewingConditions.aw + 4));
+    const jstar = ((1 + 100 * 0.007) * j) / (1 + 0.007 * j);
+    const mstar = (1 / 0.0228) * Math.log(1 + 0.0228 * m);
+    const astar = mstar * Math.cos(hueRadians);
+    const bstar = mstar * Math.sin(hueRadians);
+
+    return new Cam16(hue, c, j, q, m, s, jstar, astar, bstar);
+  }
+
+  /**
+   * @param {number} j CAM16 lightness
+   * @param {number} c CAM16 chroma
+   * @param {number} h CAM16 hue
+   * @return {Cam16}
+   */
+  static fromJch(j, c, h) {
+    return Cam16.fromJchInViewingConditions(j, c, h, ViewingConditions.DEFAULT);
+  }
+
+  /**
+   * @param {number} j CAM16 lightness
+   * @param {number} c CAM16 chroma
+   * @param {number} h CAM16 hue
+   * @param {ViewingConditions} viewingConditions Information about the environment where the color
+   *     was observed.
+   */
+  static fromJchInViewingConditions(j, c, h, viewingConditions) {
+    const q = (4 / viewingConditions.c) * Math.sqrt(j / 100)
+         * (viewingConditions.aw + 4) * viewingConditions.fLRoot;
+    const m = c * viewingConditions.fLRoot;
+    const alpha = c / Math.sqrt(j / 100);
+    const s = 50
+         * Math.sqrt((alpha * viewingConditions.c) / (viewingConditions.aw + 4));
+    const hueRadians = (h * Math.PI) / 180;
+    const jstar = ((1 + 100 * 0.007) * j) / (1 + 0.007 * j);
+    const mstar = (1 / 0.0228) * Math.log(1 + 0.0228 * m);
+    const astar = mstar * Math.cos(hueRadians);
+    const bstar = mstar * Math.sin(hueRadians);
+    return new Cam16(h, c, j, q, m, s, jstar, astar, bstar);
+  }
+
+  /**
+   * @param {number} jstar CAM16-UCS lightness.
+   * @param {number} astar CAM16-UCS a dimension. Like a* in L*a*b*, it is a Cartesian
+   *     coordinate on the Y axis.
+   * @param {number} bstar CAM16-UCS b dimension. Like a* in L*a*b*, it is a Cartesian
+   *     coordinate on the X axis.
+   * @return {Cam16}
+   */
+  static fromUcs(jstar, astar, bstar) {
+    return Cam16.fromUcsInViewingConditions(jstar, astar, bstar, ViewingConditions.DEFAULT);
+  }
+
+  /**
+   * @param {number} jstar CAM16-UCS lightness.
+   * @param {number} astar CAM16-UCS a dimension. Like a* in L*a*b*, it is a Cartesian
+   *     coordinate on the Y axis.
+   * @param {number} bstar CAM16-UCS b dimension. Like a* in L*a*b*, it is a Cartesian
+   *     coordinate on the X axis.
+   * @param {ViewingConditions} viewingConditions Information about the environment where the color
+   *     was observed.
+   */
+  static fromUcsInViewingConditions(jstar, astar, bstar, viewingConditions) {
+    const a = astar;
+    const b = bstar;
+    const m = Math.sqrt(a * a + b * b);
+    const M = (Math.exp(m * 0.0228) - 1) / 0.0228;
+    const c = M / viewingConditions.fLRoot;
+    let h = Math.atan2(b, a) * (180 / Math.PI);
+    if (h < 0) {
+      h += 360;
+    }
+    const j = jstar / (1 - (jstar - 100) * 0.007);
+    return Cam16.fromJchInViewingConditions(j, c, h, viewingConditions);
+  }
+
+  /**
+   *  @return {number} ARGB representation of color, assuming the color was viewed in
+   *     default viewing conditions, which are near-identical to the default
+   *     viewing conditions for sRGB.
+   */
+  toInt() {
+    return this.viewed(ViewingConditions.DEFAULT);
+  }
+
+  /**
+   * @param {ViewingConditions} viewingConditions Information about the environment where the color
+   *     will be viewed.
+   * @return {number} ARGB representation of color
+   */
+  viewed(viewingConditions) {
+    const alpha = this.chroma === 0 || this.j === 0
+      ? 0
+      : this.chroma / Math.sqrt(this.j / 100);
+
+    const t = (alpha / (1.64 - 0.29 ** viewingConditions.n) ** 0.73) ** (1 / 0.9);
+    const hRad = (this.hue * Math.PI) / 180;
+
+    const eHue = 0.25 * (Math.cos(hRad + 2) + 3.8);
+    const ac = viewingConditions.aw
+         * (this.j / 100) ** (1 / viewingConditions.c / viewingConditions.z);
+    const p1 = eHue * (50_000 / 13) * viewingConditions.nc * viewingConditions.ncb;
+    const p2 = ac / viewingConditions.nbb;
+
+    const hSin = Math.sin(hRad);
+    const hCos = Math.cos(hRad);
+
+    const gamma = (23 * (p2 + 0.305) * t)
+         / (23 * p1 + 11 * t * hCos + 108 * t * hSin);
+    const a = gamma * hCos;
+    const b = gamma * hSin;
+    const rA = (460 * p2 + 451 * a + 288 * b) / 1403;
+    const gA = (460 * p2 - 891 * a - 261 * b) / 1403;
+    const bA = (460 * p2 - 220 * a - 6300 * b) / 1403;
+
+    const rCBase = Math.max(0, (27.13 * Math.abs(rA)) / (400 - Math.abs(rA)));
+    const rC = math.signum(rA) * (100 / viewingConditions.fl)
+         * rCBase ** (1 / 0.42);
+    const gCBase = Math.max(0, (27.13 * Math.abs(gA)) / (400 - Math.abs(gA)));
+    const gC = math.signum(gA) * (100 / viewingConditions.fl)
+         * gCBase ** (1 / 0.42);
+    const bCBase = Math.max(0, (27.13 * Math.abs(bA)) / (400 - Math.abs(bA)));
+    const bC = math.signum(bA) * (100 / viewingConditions.fl)
+         * bCBase ** (1 / 0.42);
+    const rF = rC / viewingConditions.rgbD[0];
+    const gF = gC / viewingConditions.rgbD[1];
+    const bF = bC / viewingConditions.rgbD[2];
+
+    const x = 1.862_067_86 * rF - 1.011_254_63 * gF + 0.149_186_77 * bF;
+    const y = 0.387_526_54 * rF + 0.621_447_44 * gF - 0.008_973_98 * bF;
+    const z = -0.015_841_5 * rF - 0.034_122_94 * gF + 1.049_964_44 * bF;
+
+    const argb = utils.argbFromXyz(x, y, z);
+    return argb;
+  }
+}

package/utils/hct/CorePalette.js

@@ -0,0 +1,84 @@
+/**
+ * @license
+ * Copyright 2021 Google LLC
+ *
+ * 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.
+ */
+
+import Hct from './Hct.js';
+import TonalPalette from './TonalPalette.js';
+
+/**
+ * An intermediate concept between the key color for a UI theme, and a full
+ * color scheme. 5 sets of tones are generated, all except one use the same hue
+ * as the key color, and all vary in chroma.
+ */
+export default class CorePalette {
+  /** @type {TonalPalette} */
+  a1;
+
+  /** @type {TonalPalette} */
+  a2;
+
+  /** @type {TonalPalette} */
+  a3;
+
+  /** @type {TonalPalette} */
+  n1;
+
+  /** @type {TonalPalette} */
+  n2;
+
+  /** @type {TonalPalette} */
+  error;
+
+  /**
+   * @param {number} argb ARGB representation of a color
+   * @return {CorePalette}
+   */
+  static of(argb) {
+    return new CorePalette(argb, false);
+  }
+
+  /**
+   * @param {number} argb ARGB representation of a color
+   * @return {CorePalette}
+   */
+  static contentOf(argb) {
+    return new CorePalette(argb, true);
+  }
+
+  /**
+   * @param {number} argb
+   * @param {boolean} isContent
+   */
+  constructor(argb, isContent) {
+    const hct = Hct.fromInt(argb);
+    const { hue } = hct;
+    const { chroma } = hct;
+    if (isContent) {
+      this.a1 = TonalPalette.fromHueAndChroma(hue, chroma);
+      this.a2 = TonalPalette.fromHueAndChroma(hue, chroma / 3);
+      this.a3 = TonalPalette.fromHueAndChroma(hue + 60, chroma / 2);
+      this.n1 = TonalPalette.fromHueAndChroma(hue, Math.min(chroma / 12, 4));
+      this.n2 = TonalPalette.fromHueAndChroma(hue, Math.min(chroma / 6, 8));
+    } else {
+      this.a1 = TonalPalette.fromHueAndChroma(hue, Math.max(48, chroma));
+      this.a2 = TonalPalette.fromHueAndChroma(hue, 16);
+      this.a3 = TonalPalette.fromHueAndChroma(hue + 60, 24);
+      this.n1 = TonalPalette.fromHueAndChroma(hue, 4);
+      this.n2 = TonalPalette.fromHueAndChroma(hue, 8);
+    }
+    this.error = TonalPalette.fromHueAndChroma(25, 84);
+  }
+}

package/utils/hct/Hct.js

@@ -0,0 +1,172 @@
+/**
+ * @license
+ * Copyright 2021 Google LLC
+ *
+ * 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.
+ */
+
+/**
+ * A color system built using CAM16 hue and chroma, and L* from
+ * L*a*b*.
+ *
+ * Using L* creates a link between the color system, contrast, and thus
+ * accessibility. Contrast ratio depends on relative luminance, or Y in the XYZ
+ * color space. L*, or perceptual luminance can be calculated from Y.
+ *
+ * Unlike Y, L* is linear to human perception, allowing trivial creation of
+ * accurate color tones.
+ *
+ * Unlike contrast ratio, measuring contrast in L* is linear, and simple to
+ * calculate. A difference of 40 in HCT tone guarantees a contrast ratio >= 3.0,
+ * and a difference of 50 guarantees a contrast ratio >= 4.5.
+ */
+
+import Cam16 from './Cam16.js';
+import * as utils from './colorUtils.js';
+import * as hctSolver from './hctSolver.js';
+
+/**
+ * HCT, hue, chroma, and tone. A color system that provides a perceptually
+ * accurate color measurement system that can also accurately render what colors
+ * will appear as in different lighting environments.
+ */
+export default class Hct {
+  /**
+   * @param hue 0 <= hue < 360; invalid values are corrected.
+   * @param chroma 0 <= chroma < ?; Informally, colorfulness. The color
+   *     returned may be lower than the requested chroma. Chroma has a different
+   *     maximum for any given hue and tone.
+   * @param tone 0 <= tone <= 100; invalid values are corrected.
+   * @return HCT representation of a color in default viewing conditions.
+   */
+
+  /** @type {number} */
+  internalHue;
+
+  /** @type {number} */
+  internalChroma;
+
+  /** @type {number} */
+  internalTone;
+
+  /**
+   * @param {number} hue
+   * @param {number} chroma
+   * @param {number} tone
+   * @return {Hct}
+   */
+  static from(hue, chroma, tone) {
+    return new Hct(hctSolver.solveToInt(hue, chroma, tone));
+  }
+
+  /**
+   * @param {number} argb ARGB representation of a color.
+   * @return {Hct} HCT representation of a color in default viewing conditions
+   */
+  static fromInt(argb) {
+    return new Hct(argb);
+  }
+
+  /** @return {number} */
+  toInt() {
+    return this.argb;
+  }
+
+  /**
+   * A number, in degrees, representing ex. red, orange, yellow, etc.
+   * Ranges from 0 <= hue < 360.
+   * @return {number}
+   */
+  get hue() {
+    return this.internalHue;
+  }
+
+  /**
+   * @param {number} newHue 0 <= newHue < 360; invalid values are corrected.
+   * Chroma may decrease because chroma has a different maximum for any given
+   * hue and tone.
+   */
+  set hue(newHue) {
+    this.setInternalState(
+      hctSolver.solveToInt(
+        newHue,
+        this.internalChroma,
+        this.internalTone,
+      ),
+    );
+  }
+
+  /** @return {number} */
+  get chroma() {
+    return this.internalChroma;
+  }
+
+  /**
+   * @param {number} newChroma 0 <= newChroma < ?
+   * Chroma may decrease because chroma has a different maximum for any given
+   * hue and tone.
+   */
+  set chroma(newChroma) {
+    this.setInternalState(
+      hctSolver.solveToInt(
+        this.internalHue,
+        newChroma,
+        this.internalTone,
+      ),
+    );
+  }
+
+  /**
+   * Lightness. Ranges from 0 to 100.
+   * @return {number}
+   */
+  get tone() {
+    return this.internalTone;
+  }
+
+  /**
+   * @param {number} newTone 0 <= newTone <= 100; invalid valids are corrected.
+   * Chroma may decrease because chroma has a different maximum for any given
+   * hue and tone.
+   */
+  set tone(newTone) {
+    this.setInternalState(
+      hctSolver.solveToInt(
+        this.internalHue,
+        this.internalChroma,
+        newTone,
+      ),
+    );
+  }
+
+  /** @param {number} argb */
+  constructor(argb) {
+    const cam = Cam16.fromInt(argb);
+    this.internalHue = cam.hue;
+    this.internalChroma = cam.chroma;
+    this.internalTone = utils.lstarFromArgb(argb);
+    this.argb = argb;
+  }
+
+  /**
+   * @private
+   * @param {number} argb
+   */
+  setInternalState(argb) {
+    const cam = Cam16.fromInt(argb);
+    this.internalHue = cam.hue;
+    this.internalChroma = cam.chroma;
+    this.internalTone = utils.lstarFromArgb(argb);
+    this.argb = argb;
+  }
+}