[M3][ColorUtilities] Internal Color Utilities Library update

PiperOrigin-RevId: 543777709

Author: Material Design Team

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

@@ -66,6 +66,16 @@ public DynamicScheme(
     this.errorPalette = TonalPalette.fromHueAndChroma(25.0, 84.0);
   }
 
+  /**
+   * Given a set of hues and set of hue rotations, locate which hues the source color's hue is
+   * between, apply the rotation at the same index as the first hue in the range, and return the
+   * rotated hue.
+   *
+   * @param sourceColorHct The color whose hue should be rotated.
+   * @param hues A set of hues.
+   * @param rotations A set of hue rotations.
+   * @return Color's hue with a rotation applied.
+   */
   public static double getRotatedHue(Hct sourceColorHct, double[] hues, double[] rotations) {
     final double sourceHue = sourceColorHct.getHue();
     if (rotations.length == 1) {

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

@@ -44,6 +44,37 @@ public DynamicColor highestSurface(@NonNull DynamicScheme s) {
     return s.isDark ? surfaceBright() : surfaceDim();
   }
 
+  // Compatibility Keys Colors for Android
+  @NonNull
+  public DynamicColor primaryPaletteKeyColor() {
+    return DynamicColor.fromPalette(
+        (s) -> s.primaryPalette, (s) -> s.primaryPalette.getKeyColor().getTone());
+  }
+
+  @NonNull
+  public DynamicColor secondaryPaletteKeyColor() {
+    return DynamicColor.fromPalette(
+        (s) -> s.secondaryPalette, (s) -> s.secondaryPalette.getKeyColor().getTone());
+  }
+
+  @NonNull
+  public DynamicColor tertiaryPaletteKeyColor() {
+    return DynamicColor.fromPalette(
+        (s) -> s.tertiaryPalette, (s) -> s.tertiaryPalette.getKeyColor().getTone());
+  }
+
+  @NonNull
+  public DynamicColor neutralPaletteKeyColor() {
+    return DynamicColor.fromPalette(
+        (s) -> s.neutralPalette, (s) -> s.neutralPalette.getKeyColor().getTone());
+  }
+
+  @NonNull
+  public DynamicColor neutralVariantPaletteKeyColor() {
+    return DynamicColor.fromPalette(
+        (s) -> s.neutralVariantPalette, (s) -> s.neutralVariantPalette.getKeyColor().getTone());
+  }
+
   @NonNull
   public DynamicColor background() {
     return DynamicColor.fromPalette((s) -> s.neutralPalette, (s) -> s.isDark ? 6.0 : 98.0);

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

@@ -39,12 +39,14 @@ public SchemeExpressive(Hct sourceColorHct, boolean isDark, double contrastLevel
         isDark,
         contrastLevel,
         TonalPalette.fromHueAndChroma(
-            MathUtils.sanitizeDegreesDouble(sourceColorHct.getHue() + 120.0), 40.0),
+            MathUtils.sanitizeDegreesDouble(sourceColorHct.getHue() + 240.0), 40.0),
         TonalPalette.fromHueAndChroma(
             DynamicScheme.getRotatedHue(sourceColorHct, HUES, SECONDARY_ROTATIONS), 24.0),
         TonalPalette.fromHueAndChroma(
             DynamicScheme.getRotatedHue(sourceColorHct, HUES, TERTIARY_ROTATIONS), 32.0),
-        TonalPalette.fromHueAndChroma(sourceColorHct.getHue(), 8.0),
-        TonalPalette.fromHueAndChroma(sourceColorHct.getHue(), 12.0));
+        TonalPalette.fromHueAndChroma(
+            MathUtils.sanitizeDegreesDouble(sourceColorHct.getHue() + 15.0), 8.0),
+        TonalPalette.fromHueAndChroma(
+            MathUtils.sanitizeDegreesDouble(sourceColorHct.getHue() + 15.0), 12.0));
   }
 }

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

@@ -33,7 +33,7 @@ public SchemeTonalSpot(Hct sourceColorHct, boolean isDark, double contrastLevel)
         Variant.TONAL_SPOT,
         isDark,
         contrastLevel,
-        TonalPalette.fromHueAndChroma(sourceColorHct.getHue(), 40.0),
+        TonalPalette.fromHueAndChroma(sourceColorHct.getHue(), 36.0),
         TonalPalette.fromHueAndChroma(sourceColorHct.getHue(), 16.0),
         TonalPalette.fromHueAndChroma(
             MathUtils.sanitizeDegreesDouble(sourceColorHct.getHue() + 60.0), 24.0),

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

@@ -42,7 +42,7 @@ public SchemeVibrant(Hct sourceColorHct, boolean isDark, double contrastLevel) {
             DynamicScheme.getRotatedHue(sourceColorHct, HUES, SECONDARY_ROTATIONS), 24.0),
         TonalPalette.fromHueAndChroma(
             DynamicScheme.getRotatedHue(sourceColorHct, HUES, TERTIARY_ROTATIONS), 32.0),
-        TonalPalette.fromHueAndChroma(sourceColorHct.getHue(), 8.0),
+        TonalPalette.fromHueAndChroma(sourceColorHct.getHue(), 10.0),
         TonalPalette.fromHueAndChroma(sourceColorHct.getHue(), 12.0));
   }
 }

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

@@ -31,6 +31,7 @@
 @RestrictTo(LIBRARY_GROUP)
 public final class TonalPalette {
   Map<Integer, Integer> cache;
+  Hct keyColor;
   double hue;
   double chroma;
 
@@ -40,7 +41,7 @@ public final class TonalPalette {
    * @param argb ARGB representation of a color
    * @return Tones matching that color's hue and chroma.
    */
-  public static final TonalPalette fromInt(int argb) {
+  public static TonalPalette fromInt(int argb) {
     return fromHct(Hct.fromInt(argb));
   }
 
@@ -50,8 +51,8 @@ public static final TonalPalette fromInt(int argb) {
    * @param hct HCT representation of a color.
    * @return Tones matching that color's hue and chroma.
    */
-  public static final TonalPalette fromHct(Hct hct) {
-    return TonalPalette.fromHueAndChroma(hct.getHue(), hct.getChroma());
+  public static TonalPalette fromHct(Hct hct) {
+    return new TonalPalette(hct.getHue(), hct.getChroma(), hct);
   }
 
   /**
@@ -61,14 +62,53 @@ public static final TonalPalette fromHct(Hct hct) {
    * @param chroma HCT chroma
    * @return Tones matching hue and chroma.
    */
-  public static final TonalPalette fromHueAndChroma(double hue, double chroma) {
-    return new TonalPalette(hue, chroma);
+  public static TonalPalette fromHueAndChroma(double hue, double chroma) {
+    return new TonalPalette(hue, chroma, createKeyColor(hue, chroma));
   }
 
-  private TonalPalette(double hue, double chroma) {
+  private TonalPalette(double hue, double chroma, Hct keyColor) {
     cache = new HashMap<>();
     this.hue = hue;
     this.chroma = chroma;
+    this.keyColor = keyColor;
+  }
+
+  /** The key color is the first tone, starting from T50, matching the given hue and chroma. */
+  private static Hct createKeyColor(double hue, double chroma) {
+    double startTone = 50.0;
+    Hct smallestDeltaHct = Hct.from(hue, chroma, startTone);
+    double smallestDelta = Math.abs(smallestDeltaHct.getChroma() - chroma);
+    // Starting from T50, check T+/-delta to see if they match the requested
+    // chroma.
+    //
+    // Starts from T50 because T50 has the most chroma available, on
+    // average. Thus it is most likely to have a direct answer and minimize
+    // iteration.
+    for (double delta = 1.0; delta < 50.0; delta += 1.0) {
+      // Termination condition rounding instead of minimizing delta to avoid
+      // case where requested chroma is 16.51, and the closest chroma is 16.49.
+      // Error is minimized, but when rounded and displayed, requested chroma
+      // is 17, key color's chroma is 16.
+      if (Math.round(chroma) == Math.round(smallestDeltaHct.getChroma())) {
+        return smallestDeltaHct;
+      }
+
+      final Hct hctAdd = Hct.from(hue, chroma, startTone + delta);
+      final double hctAddDelta = Math.abs(hctAdd.getChroma() - chroma);
+      if (hctAddDelta < smallestDelta) {
+        smallestDelta = hctAddDelta;
+        smallestDeltaHct = hctAdd;
+      }
+
+      final Hct hctSubtract = Hct.from(hue, chroma, startTone - delta);
+      final double hctSubtractDelta = Math.abs(hctSubtract.getChroma() - chroma);
+      if (hctSubtractDelta < smallestDelta) {
+        smallestDelta = hctSubtractDelta;
+        smallestDeltaHct = hctSubtract;
+      }
+    }
+
+    return smallestDeltaHct;
   }
 
   /**
@@ -88,15 +128,23 @@ public int tone(int tone) {
     return color;
   }
 
+  /** Given a tone, use hue and chroma of palette to create a color, and return it as HCT. */
   public Hct getHct(double tone) {
     return Hct.from(this.hue, this.chroma, tone);
   }
 
+  /** The chroma of the Tonal Palette, in HCT. Ranges from 0 to ~130 (for sRGB gamut). */
   public double getChroma() {
     return this.chroma;
   }
 
+  /** The hue of the Tonal Palette, in HCT. Ranges from 0 to 360. */
   public double getHue() {
     return this.hue;
   }
+
+  /** The key color is the first tone, starting from T50, that matches the palette's chroma. */
+  public Hct getKeyColor() {
+    return this.keyColor;
+  }
 }

lib/javatests/com/google/android/material/color/utilities/SchemeContentTest.java

@@ -27,6 +27,18 @@ public final class SchemeContentTest {
 
   private final MaterialDynamicColors dynamicColors = new MaterialDynamicColors();
 
+  @Test
+  public void testKeyColors() {
+    SchemeContent scheme = new SchemeContent(Hct.fromInt(0xff0000ff), false, 0.0);
+
+    assertThat(dynamicColors.primaryPaletteKeyColor().getArgb(scheme)).isSameColorAs(0xff080CFF);
+    assertThat(dynamicColors.secondaryPaletteKeyColor().getArgb(scheme)).isSameColorAs(0xff656DD3);
+    assertThat(dynamicColors.tertiaryPaletteKeyColor().getArgb(scheme)).isSameColorAs(0xff81009F);
+    assertThat(dynamicColors.neutralPaletteKeyColor().getArgb(scheme)).isSameColorAs(0xff767684);
+    assertThat(dynamicColors.neutralVariantPaletteKeyColor().getArgb(scheme))
+        .isSameColorAs(0xff757589);
+  }
+
   @Test
   public void lightTheme_minContrast_primary() {
     SchemeContent scheme = new SchemeContent(Hct.fromInt(0xFF0000ff), false, -1.0);