[Color] Internal color library update.

PiperOrigin-RevId: 655678296

Author: pekingme

lib/java/com/google/android/material/color/utilities/Cam16.java

@@ -19,6 +19,7 @@
 import static androidx.annotation.RestrictTo.Scope.LIBRARY_GROUP;
 import static java.lang.Math.max;
 
+import androidx.annotation.NonNull;
 import androidx.annotation.RestrictTo;
 
 /**
@@ -75,7 +76,7 @@ public final class Cam16 {
    * astar, bstar in code. CAM16-UCS is included in the CAM16 specification, and is used to measure
    * distances between colors.
    */
-  double distance(Cam16 other) {
+  public double distance(@NonNull Cam16 other) {
     double dJ = getJstar() - other.getJstar();
     double dA = getAstar() - other.getAstar();
     double dB = getBstar() - other.getBstar();

lib/java/com/google/android/material/color/utilities/Contrast.java

@@ -59,7 +59,7 @@ public final class Contrast {
   private static final double CONTRAST_RATIO_EPSILON = 0.04;
 
   // Color spaces that measure luminance, such as Y in XYZ, L* in L*a*b*, or T in HCT, are known as
-  // perceptual accurate color spaces.
+  // perceptually accurate color spaces.
   //
   // To be displayed, they must gamut map to a "display space", one that has a defined limit on the
   // number of colors. Display spaces include sRGB, more commonly understood  as RGB/HSL/HSV/HSB.
@@ -79,7 +79,7 @@ public final class Contrast {
   // result such that the desired contrast ratio will be reached even if inaccuracy is introduced.
   //
   // 0.4 is generous, ex. HCT requires much less delta. It was chosen because it provides a rough
-  // guarantee that as long as a percetual color space gamut maps lightness such that the resulting
+  // guarantee that as long as a perceptual color space gamut maps lightness such that the resulting
   // lightness rounds to the same as the requested, the desired contrast ratio will be reached.
   private static final double LUMINANCE_GAMUT_MAP_TOLERANCE = 0.4;
 

lib/java/com/google/android/material/color/utilities/ContrastCurve.java

@@ -21,34 +21,34 @@
 import androidx.annotation.RestrictTo;
 
 /**
- * A class containing the contrast curve for a dynamic color on its background.
+ * A class containing a value that changes with the contrast level.
  *
- * <p>The four values correspond to contrast requirements for contrast levels -1.0, 0.0, 0.5, and
- * 1.0, respectively.
+ * <p>Usually represents the contrast requirements for a dynamic color on its background. The four
+ * values correspond to values for contrast levels -1.0, 0.0, 0.5, and 1.0, respectively.
  *
  * @hide
  */
 @RestrictTo(LIBRARY_GROUP)
 public final class ContrastCurve {
-  /** Contrast requirement for contrast level -1.0 */
+  /** Value for contrast level -1.0 */
   private final double low;
 
-  /** Contrast requirement for contrast level 0.0 */
+  /** Value for contrast level 0.0 */
   private final double normal;
 
-  /** Contrast requirement for contrast level 0.5 */
+  /** Value for contrast level 0.5 */
   private final double medium;
 
-  /** Contrast requirement for contrast level 1.0 */
+  /** Value for contrast level 1.0 */
   private final double high;
 
   /**
    * Creates a `ContrastCurve` object.
    *
-   * @param low Contrast requirement for contrast level -1.0
-   * @param normal Contrast requirement for contrast level 0.0
-   * @param medium Contrast requirement for contrast level 0.5
-   * @param high Contrast requirement for contrast level 1.0
+   * @param low Value for contrast level -1.0
+   * @param normal Value for contrast level 0.0
+   * @param medium Value for contrast level 0.5
+   * @param high Value for contrast level 1.0
    */
   public ContrastCurve(double low, double normal, double medium, double high) {
     this.low = low;
@@ -58,13 +58,13 @@ public ContrastCurve(double low, double normal, double medium, double high) {
   }
 
   /**
-   * Returns the contrast ratio at a given contrast level.
+   * Returns the value at a given contrast level.
    *
    * @param contrastLevel The contrast level. 0.0 is the default (normal); -1.0 is the lowest; 1.0
    *     is the highest.
-   * @return The contrast ratio, a number between 1.0 and 21.0.
+   * @return The value. For contrast ratios, a number between 1.0 and 21.0.
    */
-  public double getContrast(double contrastLevel) {
+  public double get(double contrastLevel) {
     if (contrastLevel <= -1.0) {
       return this.low;
     } else if (contrastLevel < 0.0) {

lib/java/com/google/android/material/color/utilities/DislikeAnalyzer.java

@@ -24,7 +24,7 @@
  * Check and/or fix universally disliked colors.
  *
  * <p>Color science studies of color preference indicate universal distaste for dark yellow-greens,
- * and also show this is correlated to distate for biological waste and rotting food.
+ * and also show this is correlated to distaste for biological waste and rotting food.
  *
  * <p>See Palmer and Schloss, 2010 or Schloss and Palmer's Chapter 21 in Handbook of Color
  * Psychology (2015).

lib/java/com/google/android/material/color/utilities/DynamicColor.java

@@ -120,6 +120,36 @@ public DynamicColor(
     this.opacity = null;
   }
 
+  /**
+   * A constructor for DynamicColor.
+   *
+   * <p>_Strongly_ prefer using one of the convenience constructors. This class is arguably too
+   * flexible to ensure it can support any scenario. Functional arguments allow overriding without
+   * risks that come with subclasses.
+   *
+   * <p>For example, the default behavior of adjust tone at max contrast to be at a 7.0 ratio with
+   * its background is principled and matches accessibility guidance. That does not mean it's the
+   * desired approach for _every_ design system, and every color pairing, always, in every case.
+   *
+   * <p>For opaque colors (colors with alpha = 100%).
+   *
+   * @param name The name of the dynamic color.
+   * @param palette Function that provides a TonalPalette given DynamicScheme. A TonalPalette is
+   *     defined by a hue and chroma, so this replaces the need to specify hue/chroma. By providing
+   *     a tonal palette, when contrast adjustments are made, intended chroma can be preserved.
+   * @param tone Function that provides a tone, given a DynamicScheme.
+   * @param isBackground Whether this dynamic color is a background, with some other color as the
+   *     foreground.
+   * @param background The background of the dynamic color (as a function of a `DynamicScheme`), if
+   *     it exists.
+   * @param secondBackground A second background of the dynamic color (as a function of a
+   *     `DynamicScheme`), if it exists.
+   * @param contrastCurve A `ContrastCurve` object specifying how its contrast against its
+   *     background should behave in various contrast levels options.
+   * @param toneDeltaPair A `ToneDeltaPair` object specifying a tone delta constraint between two
+   *     colors. One of them must be the color being constructed.
+   * @param opacity A function returning the opacity of a color, as a number between 0 and 1.
+   */
   public DynamicColor(
       @NonNull String name,
       @NonNull Function<DynamicScheme, TonalPalette> palette,
@@ -304,8 +334,8 @@ public double getTone(@NonNull DynamicScheme scheme) {
       double expansionDir = scheme.isDark ? 1 : -1;
 
       // 1st round: solve to min, each
-      double nContrast = nearer.contrastCurve.getContrast(scheme.contrastLevel);
-      double fContrast = farther.contrastCurve.getContrast(scheme.contrastLevel);
+      double nContrast = nearer.contrastCurve.get(scheme.contrastLevel);
+      double fContrast = farther.contrastCurve.get(scheme.contrastLevel);
 
       // If a color is good enough, it is not adjusted.
       // Initial and adjusted tones for `nearer`
@@ -385,7 +415,7 @@ public double getTone(@NonNull DynamicScheme scheme) {
 
       double bgTone = background.apply(scheme).getTone(scheme);
 
-      double desiredRatio = contrastCurve.getContrast(scheme.contrastLevel);
+      double desiredRatio = contrastCurve.get(scheme.contrastLevel);
 
       if (Contrast.ratioOfTones(bgTone, answer) >= desiredRatio) {
         // Don't "improve" what's good enough.