[Carousel] Change custom Carousel strategies to be restricted visibility in order to refactor custom strategies

PiperOrigin-RevId: 707143621

Author: imhappi

docs/components/Carousel.md

@@ -259,99 +259,3 @@ 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

@@ -21,13 +21,16 @@
 
 import androidx.annotation.NonNull;
 import androidx.annotation.Nullable;
+import androidx.annotation.RestrictTo;
+import androidx.annotation.RestrictTo.Scope;
 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.
  */
+@RestrictTo(Scope.LIBRARY_GROUP)
 public final class Arrangement {
 
   // Specifies a percentage of a medium item's size by which it can be increased or decreased to

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

@@ -16,9 +16,12 @@
 
 package com.google.android.material.carousel;
 
+import androidx.annotation.RestrictTo;
+import androidx.annotation.RestrictTo.Scope;
 import com.google.android.material.carousel.CarouselLayoutManager.Alignment;
 
 /** An interface that defines a widget that can be configured as a Carousel. */
+@RestrictTo(Scope.LIBRARY_GROUP)
 public interface Carousel {
 
   /** Gets the width of the carousel container. */

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

@@ -20,6 +20,8 @@
 import android.view.View;
 import androidx.annotation.FloatRange;
 import androidx.annotation.NonNull;
+import androidx.annotation.RestrictTo;
+import androidx.annotation.RestrictTo.Scope;
 
 /**
  * A class responsible for creating a model used by a carousel to mask and offset views as they move
@@ -104,6 +106,7 @@ void initialize(Context context) {
    *     along the scrolling axis.
    */
   @NonNull
+  @RestrictTo(Scope.LIBRARY_GROUP)
   public abstract KeylineState onFirstChildMeasuredWithMargins(
       @NonNull Carousel carousel, @NonNull View child);
 
@@ -161,6 +164,7 @@ StrategyType getStrategyType() {
    *
    * @return true if the keylines should be refreshed.
    */
+  @RestrictTo(Scope.LIBRARY_GROUP)
   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.

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

@@ -22,6 +22,8 @@
 import androidx.annotation.FloatRange;
 import androidx.annotation.NonNull;
 import androidx.annotation.Nullable;
+import androidx.annotation.RestrictTo;
+import androidx.annotation.RestrictTo.Scope;
 import com.google.android.material.animation.AnimationUtils;
 import com.google.errorprone.annotations.CanIgnoreReturnValue;
 import java.util.ArrayList;
@@ -49,6 +51,7 @@
  * focal keylines at the beginning of the scroll container, center-aligned strategies at the center
  * of the scroll container, etc.
  */
+@RestrictTo(Scope.LIBRARY_GROUP)
 public final class KeylineState {
 
   private final float itemSize;

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

@@ -20,6 +20,8 @@
 import static java.lang.Math.min;
 
 import androidx.annotation.NonNull;
+import androidx.annotation.RestrictTo;
+import androidx.annotation.RestrictTo.Scope;
 import androidx.core.math.MathUtils;
 import com.google.android.material.animation.AnimationUtils;
 import com.google.android.material.carousel.KeylineState.Keyline;
@@ -43,6 +45,7 @@
  * handle reversing a KeylineState when being laid out right-to-left before constructing a
  * KeylineStateList.
  */
+@RestrictTo(Scope.LIBRARY_GROUP)
 public class KeylineStateList {
 
   private static final int NO_INDEX = -1;