[Carousel] Make carousel internal classes public to enable custom strategies

PiperOrigin-RevId: 679710469

Author: imhappi

docs/components/Carousel.md

@@ -260,4 +260,98 @@ carouselLayoutManager.setCarouselAlignment(CarouselLayoutManager.CENTER)
 
 By default, the focal alignment is start-aligned.
 
+### Creating a custom strategy
+
+You can create a custom Carousel strategy by extending the `CarouselStrategy`
+class, and overriding the `onFirstChildMeasuredWithMargins` method. This method
+is called when the RecyclerView measures the first item to be added to its
+scroll container. This method must return a `KeylineState` which tells the
+Carousel how to fill the scroll container with items - how many are visible at
+once, what their sizes are, and where they're placed.
+
+This is done by using the `KeylineState.Builder` to add "keylines", which
+represent items that will be shown. For example, if there are 3 non-anchor
+keylines, 3 items will be shown in the carousel. As the items move through the
+carousel, each item will be the exact size specified by each keyline when they
+are directly at the center of the keyline.
+
+Note that anchor keylines are used to control how small items become as they
+reach the edge of the carousel, and must always be added to denote the start and
+ends of the keyline strategy. Smaller anchor keyline sizes will result in items
+looking 'squeezed' to the edges of the carousel, whereas bigger anchor sizes
+will make it look like there's no size change as it goes off-screen.
+
+Keylines must always follow rule patterns:
+
+-   Anchor keylines must always be smaller than any other keyline (it wouldn't
+    make sense for an item to get bigger as it goes off-screen)
+-   Anchor keylines must always be off-screen; typically, the left anchor's
+    center is located at `-(anchorSize)/2` and the right anchor's center is
+    located at `availableSpace + anchorSize/2`
+-   The biggest keyline must be focal keylines; these are items that are fully
+    unmasked
+-   Focal keylines must be grouped together, and there must be at least one
+    focal keyline
+-   Non-anchor keylines must be in ascending size order up to the focal
+    keyline(s), and in descending order after the focal keyline(s)
+-   All non-anchor keyline sizes must add up to the available space in the
+    carousel
+
+For example, if you want the following strategy structure:
+
+![A custom Carousel](assets/carousel/custom.png)
+
+Then you can define it with a `KeylineState` like below in your custom Strategy.
+The `KeylineState` returned by `onFirstChildMeasuredWithMargins` should always
+be the 'default' `KeylineState`, meaning the `KeylineState` with no altered
+behavior. The `CarouselLayoutManager` will take care of special behavior at the
+front and ends of the RecyclerView by taking the default `KeylineState` given
+and altering them.
 
+```kt
+override fun onFirstChildMeasuredWithMargins(
+  carousel: Carousel,
+  child: View,
+): KeylineState? {
+  val availableSpace = if (carousel.isHorizontal()) carousel.containerWidth else carousel.containerHeight
+  val focalItemSize = 200f
+  val mediumItemSize = 160f
+  val smallItemSize = 80f
+  val anchorSize = 50f // the anchor size determines how small items become as they reach the edge of the carousel
+  val childLayoutParams = child.layoutParams as LayoutParams
+  val childMargins = (childLayoutParams.leftMargin + childLayoutParams.rightMargin).toFloat() // this will be top and bottom margins for vertical strategies
+  val anchorMaskSize = CarouselStrategy.getChildMaskPercentage(
+    anchorSize,
+    focalItemSize,
+    childMargins
+  )
+  val mediumMaskSize = CarouselStrategy.getChildMaskPercentage(
+    mediumItemSize,
+    focalItemSize,
+    childMargins
+  )
+  val smallMaskSize = CarouselStrategy.getChildMaskPercentage(
+    smallItemSize,
+    focalItemSize,
+    childMargins
+  )
+  val leftAnchorCenterX = -anchorSize / 2f // the anchor keyline
+  val rightAnchorCenterX = availableSpace + anchorSize / 2f
+  return
+    KeylineState.Builder(/* itemSize= */ focalItemSize, /* availableSpace= */ availableSpace)
+      .addAnchorKeyline(/* offsetLoc= */ leftAnchorCenterX, /* mask= */ anchorMaskSize, /* maskedItemSize= */ anchorSize)
+      .addKeyline(/* offsetLoc= */ focalItemSize / 2f, /* mask= */ 0, /* maskedItemSize= */ focalItemSize, /* isFocal= */ true)
+      .addKeyline(/* offsetLoc= */ focalItemSize + mediumItemSize / 2f, /* mask= */ mediumMaskSize, /* maskedItemSize= */ mediumItemSize)
+      .addKeyline(/* offsetLoc= */ focalItemSize + mediumItemSize + smallItemSize / 2f, /* mask= */ smallMaskSize, /* maskedItemSize= * smallItemSize)
+      .addAnchorKeyline(/* offsetLoc= */ rightAnchorCenterX, /* mask= */ anchorMaskSize, /* maskedItemSize= */ anchorSize)
+      .build()
+}
+```
+
+You may also use the helper class `Arrangement` and the helper method
+`Arrangement.findLowestCostArrangement` to calculate the best suited arrangement
+for the given available space, and the given desired number of items along with
+their desired sizes. `Arrangement.findLowestCostArrangement` will give you an
+arrangement of items and sizes that will fit within the available space. This is
+encouraged unless you're doing some custom calculations with the available
+carousel size to determine an exact size for all of the keylines.

docs/components/assets/carousel/custom.png

@@ -20,14 +20,15 @@
 import static java.lang.Math.min;
 
 import androidx.annotation.NonNull;
+import androidx.annotation.Nullable;
 import androidx.core.math.MathUtils;
 
 /**
  * A class that holds data about a combination of large, medium, and small items, knows how to alter
  * an arrangement to fit within an available space, and can assess the arrangement's
  * desirability according to a priority heuristic.
  */
-final class Arrangement {
+public final class Arrangement {
 
   // Specifies a percentage of a medium item's size by which it can be increased or decreased to
   // help fit an arrangement into the carousel's available space.
@@ -64,7 +65,7 @@ final class Arrangement {
    * @param largeCount the number of large items in this arrangement
    * @param availableSpace the space this arrangement needs to fit within
    */
-  Arrangement(
+  public Arrangement(
       int priority,
       float targetSmallSize,
       float minSmallSize,
@@ -237,16 +238,17 @@ private float cost(float targetLargeSize) {
    * @return the arrangement that is considered the most desirable and has been adjusted to fit
    *     within the available space
    */
-  static Arrangement findLowestCostArrangement(
+  @Nullable
+  public static Arrangement findLowestCostArrangement(
       float availableSpace,
       float targetSmallSize,
       float minSmallSize,
       float maxSmallSize,
-      int[] smallCounts,
+      @NonNull int[] smallCounts,
       float targetMediumSize,
-      int[] mediumCounts,
+      @NonNull int[] mediumCounts,
       float targetLargeSize,
-      int[] largeCounts) {
+      @NonNull int[] largeCounts) {
     Arrangement lowestCostArrangement = null;
     int priority = 1;
     for (int largeCount : largeCounts) {

lib/java/com/google/android/material/carousel/Arrangement.java

@@ -19,7 +19,7 @@
 import com.google.android.material.carousel.CarouselLayoutManager.Alignment;
 
 /** An interface that defines a widget that can be configured as a Carousel. */
-interface Carousel {
+public interface Carousel {
 
   /** Gets the width of the carousel container. */
   int getContainerWidth();

lib/java/com/google/android/material/carousel/Carousel.java

@@ -103,7 +103,8 @@ void initialize(Context context) {
    * @return A {@link KeylineState} to be used by the layout manager to offset and mask children
    *     along the scrolling axis.
    */
-  abstract KeylineState onFirstChildMeasuredWithMargins(
+  @NonNull
+  public abstract KeylineState onFirstChildMeasuredWithMargins(
       @NonNull Carousel carousel, @NonNull View child);
 
   /**
@@ -120,7 +121,8 @@ abstract KeylineState onFirstChildMeasuredWithMargins(
    *     maskedSize}. 0F is fully unmasked and 1F is fully masked.
    */
   @FloatRange(from = 0F, to = 1F)
-  static float getChildMaskPercentage(float maskedSize, float unmaskedSize, float childMargins) {
+  public static float getChildMaskPercentage(
+      float maskedSize, float unmaskedSize, float childMargins) {
     return 1F - ((maskedSize - childMargins) / (unmaskedSize - childMargins));
   }
 
@@ -153,11 +155,13 @@ StrategyType getStrategyType() {
 
   /**
    * Whether or not the strategy keylines should be refreshed based on the old item count and the
-   * carousel's current parameters.
+   * carousel's current parameters. This method is called when the item count is updated, and is
+   * used to update the keyline strategy when the item count is less than the number of keylines in
+   * the normal keyline strategy.
    *
    * @return true if the keylines should be refreshed.
    */
-  boolean shouldRefreshKeylineState(Carousel carousel, int oldItemCount) {
+  public boolean shouldRefreshKeylineState(@NonNull Carousel carousel, int oldItemCount) {
     // TODO: b/301332183 - Update existing strategies with logic on when to refresh keyline
     // state based on item count.
     return false;

lib/java/com/google/android/material/carousel/CarouselStrategy.java

@@ -43,7 +43,8 @@ public class FullScreenCarouselStrategy extends CarouselStrategy {
 
   @Override
   @NonNull
-  KeylineState onFirstChildMeasuredWithMargins(@NonNull Carousel carousel, @NonNull View child) {
+  public KeylineState onFirstChildMeasuredWithMargins(
+      @NonNull Carousel carousel, @NonNull View child) {
     float availableSpace;
     LayoutParams childLayoutParams = (LayoutParams) child.getLayoutParams();
     float childMargins;

lib/java/com/google/android/material/carousel/FullScreenCarouselStrategy.java

@@ -54,7 +54,8 @@ public class HeroCarouselStrategy extends CarouselStrategy {
 
   @Override
   @NonNull
-  KeylineState onFirstChildMeasuredWithMargins(@NonNull Carousel carousel, @NonNull View child) {
+  public KeylineState onFirstChildMeasuredWithMargins(
+      @NonNull Carousel carousel, @NonNull View child) {
     int availableSpace = carousel.getContainerHeight();
     if (carousel.isHorizontal()) {
       availableSpace = carousel.getContainerWidth();
@@ -147,7 +148,7 @@ KeylineState onFirstChildMeasuredWithMargins(@NonNull Carousel carousel, @NonNul
     }
 
   @Override
-  boolean shouldRefreshKeylineState(@NonNull Carousel carousel, int oldItemCount) {
+  public boolean shouldRefreshKeylineState(@NonNull Carousel carousel, int oldItemCount) {
     return carousel.getCarouselAlignment() == CarouselLayoutManager.ALIGNMENT_CENTER
         && ((oldItemCount < keylineCount && carousel.getItemCount() >= keylineCount)
             || (oldItemCount >= keylineCount && carousel.getItemCount() < keylineCount));

lib/java/com/google/android/material/carousel/HeroCarouselStrategy.java

@@ -49,7 +49,7 @@
  * focal keylines at the beginning of the scroll container, center-aligned strategies at the center
  * of the scroll container, etc.
  */
-final class KeylineState {
+public final class KeylineState {
 
   private final float itemSize;
   private int totalVisibleFocalItems;
@@ -252,7 +252,7 @@ static KeylineState reverse(KeylineState keylineState, float availableSpace) {
    *
    * Typically there should be a keyline for every visible item in the scrolling container.
    */
-  static final class Builder {
+  public static final class Builder {
 
     private static final int NO_INDEX = -1;
     private static final float UNKNOWN_LOC = Float.MIN_VALUE;
@@ -276,7 +276,7 @@ static final class Builder {
     /**
      * Creates a new {@link KeylineState.Builder}.
      *
-     * @param itemSize The size of a fully unmaksed item. This is the size that will be used by the
+     * @param itemSize The size of a fully unmasked item. This is the size that will be used by the
      *     carousel to measure and lay out all children, overriding each child's desired size.
      * @param availableSpace The available space of the carousel the keylines calculate cutoffs by.
      */
@@ -305,7 +305,7 @@ static final class Builder {
      */
     @NonNull
     @CanIgnoreReturnValue
-    Builder addKeyline(
+    public Builder addKeyline(
         float offsetLoc,
         @FloatRange(from = 0.0F, to = 1.0F) float mask,
         float maskedItemSize,
@@ -321,7 +321,7 @@ Builder addKeyline(
      */
     @NonNull
     @CanIgnoreReturnValue
-    Builder addKeyline(
+    public Builder addKeyline(
         float offsetLoc, @FloatRange(from = 0.0F, to = 1.0F) float mask, float maskedItemSize) {
       return addKeyline(offsetLoc, mask, maskedItemSize, false);
     }
@@ -353,7 +353,7 @@ Builder addKeyline(
      */
     @NonNull
     @CanIgnoreReturnValue
-    Builder addKeyline(
+    public Builder addKeyline(
         float offsetLoc,
         @FloatRange(from = 0.0F, to = 1.0F) float mask,
         float maskedItemSize,
@@ -440,7 +440,7 @@ Builder addKeyline(
      */
     @NonNull
     @CanIgnoreReturnValue
-    Builder addKeyline(
+    public Builder addKeyline(
         float offsetLoc,
         @FloatRange(from = 0.0F, to = 1.0F) float mask,
         float maskedItemSize,
@@ -478,7 +478,7 @@ Builder addKeyline(
      */
     @NonNull
     @CanIgnoreReturnValue
-    Builder addKeyline(
+    public Builder addKeyline(
         float offsetLoc,
         @FloatRange(from = 0.0F, to = 1.0F) float mask,
         float maskedItemSize,
@@ -520,7 +520,7 @@ Builder addKeyline(
      */
     @NonNull
     @CanIgnoreReturnValue
-    Builder addAnchorKeyline(
+    public Builder addAnchorKeyline(
         float offsetLoc, @FloatRange(from = 0.0F, to = 1.0F) float mask, float maskedItemSize) {
       return addKeyline(
           offsetLoc, mask, maskedItemSize, /* isFocal= */ false, /* isAnchor= */ true);
@@ -535,7 +535,7 @@ Builder addAnchorKeyline(
      */
     @NonNull
     @CanIgnoreReturnValue
-    Builder addKeylineRange(
+    public Builder addKeylineRange(
         float offsetLoc,
         @FloatRange(from = 0.0F, to = 1.0F) float mask,
         float maskedItemSize,
@@ -564,7 +564,7 @@ Builder addKeylineRange(
      */
     @NonNull
     @CanIgnoreReturnValue
-    Builder addKeylineRange(
+    public Builder addKeylineRange(
         float offsetLoc,
         @FloatRange(from = 0.0F, to = 1.0F) float mask,
         float maskedItemSize,
@@ -584,7 +584,7 @@ Builder addKeylineRange(
 
     /** Builds and returns a {@link KeylineState}. */
     @NonNull
-    KeylineState build() {
+    public KeylineState build() {
       if (tmpFirstFocalKeyline == null) {
         throw new IllegalStateException("There must be a keyline marked as focal.");
       }

lib/java/com/google/android/material/carousel/KeylineState.java

@@ -43,7 +43,7 @@
  * handle reversing a KeylineState when being laid out right-to-left before constructing a
  * KeylineStateList.
  */
-class KeylineStateList {
+public class KeylineStateList {
 
   private static final int NO_INDEX = -1;
 
@@ -133,6 +133,7 @@ KeylineState getEndState() {
    *     container as possible.
    * @return a {@link KeylineState} that has been shifted according on the scroll offset.
    */
+  @NonNull
   public KeylineState getShiftedState(
       float scrollOffset, float minScrollOffset, float maxScrollOffset) {
     return getShiftedState(scrollOffset, minScrollOffset, maxScrollOffset, false);

lib/java/com/google/android/material/carousel/KeylineStateList.java

@@ -57,7 +57,8 @@ public final class MultiBrowseCarouselStrategy extends CarouselStrategy {
 
   @Override
   @NonNull
-  KeylineState onFirstChildMeasuredWithMargins(@NonNull Carousel carousel, @NonNull View child) {
+  public KeylineState onFirstChildMeasuredWithMargins(
+      @NonNull Carousel carousel, @NonNull View child) {
     float availableSpace = carousel.getContainerHeight();
     if (carousel.isHorizontal()) {
       availableSpace = carousel.getContainerWidth();
@@ -178,7 +179,7 @@ boolean ensureArrangementFitsItemCount(Arrangement arrangement, int carouselItem
   }
 
   @Override
-  boolean shouldRefreshKeylineState(Carousel carousel, int oldItemCount) {
+  public boolean shouldRefreshKeylineState(@NonNull Carousel carousel, int oldItemCount) {
     return (oldItemCount < keylineCount && carousel.getItemCount() >= keylineCount)
         || (oldItemCount >= keylineCount && carousel.getItemCount() < keylineCount);
   }