[Carousel] Add left-aligned uncontained strategy

PiperOrigin-RevId: 559197283

Author: imhappi

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

@@ -294,7 +294,8 @@ private void recalculateKeylineStateList(Recycler recycler) {
     KeylineState keylineState = carouselStrategy.onFirstChildMeasuredWithMargins(this, firstChild);
     keylineStateList =
         KeylineStateList.from(
-            this, isLayoutRtl() ? KeylineState.reverse(keylineState) : keylineState);
+            this,
+            isLayoutRtl() ? KeylineState.reverse(keylineState, getContainerSize()) : keylineState);
   }
 
   /**

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

@@ -101,8 +101,8 @@ static KeylineState createLeftAlignedKeylineState(
     float largeMask = 0F;
 
     KeylineState.Builder builder =
-        new KeylineState.Builder(arrangement.largeSize)
-            .addKeyline(extraSmallHeadCenterX, extraSmallMask, extraSmallChildWidth)
+        new KeylineState.Builder(arrangement.largeSize, availableSpace)
+            .addAnchorKeyline(extraSmallHeadCenterX, extraSmallMask, extraSmallChildWidth)
             .addKeylineRange(
                 largeStartCenterX, largeMask, arrangement.largeSize, arrangement.largeCount, true);
     if (arrangement.mediumCount > 0) {
@@ -112,7 +112,7 @@ static KeylineState createLeftAlignedKeylineState(
       builder.addKeylineRange(
           smallStartCenterX, smallMask, arrangement.smallSize, arrangement.smallCount);
     }
-    builder.addKeyline(extraSmallTailCenterX, extraSmallMask, extraSmallChildWidth);
+    builder.addAnchorKeyline(extraSmallTailCenterX, extraSmallMask, extraSmallChildWidth);
     return builder.build();
   }
 
@@ -193,8 +193,8 @@ static KeylineState createCenterAlignedKeylineState(
     float largeMask = 0F;
 
     KeylineState.Builder builder =
-        new KeylineState.Builder(arrangement.largeSize)
-            .addKeyline(extraSmallHeadCenterX, extraSmallMask, extraSmallChildWidth);
+        new KeylineState.Builder(arrangement.largeSize, availableSpace)
+            .addAnchorKeyline(extraSmallHeadCenterX, extraSmallMask, extraSmallChildWidth);
     if (arrangement.smallCount > 0) {
       builder.addKeylineRange(
           halfSmallStartCenterX,
@@ -229,7 +229,7 @@ static KeylineState createCenterAlignedKeylineState(
           (int) Math.ceil(arrangement.smallCount / 2F));
     }
 
-    builder.addKeyline(extraSmallTailCenterX, extraSmallMask, extraSmallChildWidth);
+    builder.addAnchorKeyline(extraSmallTailCenterX, extraSmallMask, extraSmallChildWidth);
     return builder.build();
   }
 

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

@@ -16,8 +16,12 @@
 
 package com.google.android.material.carousel;
 
+import static java.lang.Math.max;
+import static java.lang.Math.min;
+
 import androidx.annotation.FloatRange;
 import androidx.annotation.NonNull;
+import androidx.annotation.Nullable;
 import com.google.android.material.animation.AnimationUtils;
 import com.google.errorprone.annotations.CanIgnoreReturnValue;
 import java.util.ArrayList;
@@ -107,6 +111,30 @@ Keyline getLastKeyline() {
     return keylines.get(keylines.size() - 1);
   }
 
+  /** Returns the first non-anchor keyline. */
+  @Nullable
+  Keyline getFirstNonAnchorKeyline() {
+    for (int i = 0; i < keylines.size(); i++) {
+      Keyline keyline = keylines.get(i);
+      if (!keyline.isAnchor) {
+        return keyline;
+      }
+    }
+    return null;
+  }
+
+  /** Returns the last non-anchor keyline. */
+  @Nullable
+  Keyline getLastNonAnchorKeyline() {
+    for (int i = keylines.size()-1; i >= 0; i--) {
+      Keyline keyline = keylines.get(i);
+      if (!keyline.isAnchor) {
+        return keyline;
+      }
+    }
+    return null;
+  }
+
   /**
    * Linearly interpolate between two {@link KeylineState}s.
    *
@@ -149,11 +177,14 @@ static KeylineState lerp(KeylineState from, KeylineState to, float progress) {
    * <p>This is used to reverse a keyline state for RTL layouts.
    *
    * @param keylineState the {@link KeylineState} to reverse
+   * @param availableSpace the space in which the keylines calculate whether or not they are cut
+   *     off.
    * @return a new {@link KeylineState} that has all keylines reversed.
    */
-  static KeylineState reverse(KeylineState keylineState) {
+  static KeylineState reverse(KeylineState keylineState, float availableSpace) {
 
-    KeylineState.Builder builder = new KeylineState.Builder(keylineState.getItemSize());
+    KeylineState.Builder builder =
+        new KeylineState.Builder(keylineState.getItemSize(), availableSpace);
 
     float start =
         keylineState.getFirstKeyline().locOffset
@@ -198,6 +229,8 @@ static final class Builder {
 
     private final float itemSize;
 
+    private final float availableSpace;
+
     // A list of keylines that hold all values except the Keyline#loc which needs to be calculated
     // in the build method.
     private final List<Keyline> tmpKeylines = new ArrayList<>();
@@ -208,21 +241,54 @@ static final class Builder {
 
     private float lastKeylineMaskedSize = 0F;
 
+    private int latestAnchorKeylineIndex = NO_INDEX;
+
+
     /**
      * 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
      *     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.
      */
-    Builder(float itemSize) {
+    Builder(float itemSize, float availableSpace) {
       this.itemSize = itemSize;
+      this.availableSpace = availableSpace;
     }
 
     /**
-     * Adds a keyline along the scrolling axis where an object should be masked by the given {@code
-     * mask} and positioned at {@code offsetLoc}.
+     * Adds a non-anchor keyline along the scrolling axis where an object should be masked by the
+     * given {@code mask} and positioned at {@code offsetLoc}. Non-anchor keylines shift when
+     * keylines shift due to scrolling.
+     *
+     * <p>Note that calls to {@link #addKeyline(float, float, float, boolean)} and {@link
+     * #addKeylineRange(float, float, float, int)} are added in order. Typically, this means
+     * keylines should be added in order of ascending {@code offsetLoc}.
+     *
+     * @param offsetLoc The location of this keyline along the scrolling axis. An offsetLoc of 0
+     *     will be at the start of the scroll container.
+     * @param mask The percentage of a child's full size that it should be masked by when its center
+     *     is at {@code offsetLoc}. 0 is fully unmasked and 1 is fully masked.
+     * @param maskedItemSize The total size of this item when masked. This might differ from {@code
+     *     itemSize - (itemSize * mask)} depending on how margins are included in the {@code mask}.
+     * @param isFocal Whether this keyline is considered part of the focal range. Typically, this is
+     *     when {@code mask} is equal to 0.
+     */
+    @NonNull
+    @CanIgnoreReturnValue
+    Builder addKeyline(
+        float offsetLoc,
+        @FloatRange(from = 0.0F, to = 1.0F) float mask,
+        float maskedItemSize,
+        boolean isFocal) {
+      return addKeyline(offsetLoc, mask, maskedItemSize, isFocal, /* isAnchor= */ false);
+    }
+
+    /**
+     * Adds a non-anchor keyline along the scrolling axis where an object should be masked by the
+     * given {@code mask} and positioned at {@code offsetLoc}.
      *
-     * @see #addKeyline(float, float, float, boolean)
+     * @see #addKeyline(float, float, float, boolean, boolean)
      */
     @NonNull
     @CanIgnoreReturnValue
@@ -235,9 +301,14 @@ Builder addKeyline(
      * Adds a keyline along the scrolling axis where an object should be masked by the given {@code
      * mask} and positioned at {@code offsetLoc}.
      *
-     * <p>Note that calls to {@link #addKeyline(float, float, float, boolean)} and {@link
+     * <p>Note that calls to {@link #addKeyline(float, float, float, boolean, boolean)} and {@link
      * #addKeylineRange(float, float, float, int)} are added in order. Typically, this means
-     * keylines should be added in order of ascending {@code offsetLoc}.
+     * keylines should be added in order of ascending {@code offsetLoc}. The first and last keylines
+     * added are 'anchor' keylines that mark the start and ends of the keylines. These keylines do
+     * not shift when scrolled.
+     *
+     * <p>Note also that {@code isFocal} and {@code isAnchor} cannot be true at the same time as
+     * anchor keylines refer to keylines offscreen that dictate the ends of the keylines.
      *
      * @param offsetLoc The location of this keyline along the scrolling axis. An offsetLoc of 0
      *     will be at the start of the scroll container.
@@ -247,19 +318,36 @@ Builder addKeyline(
      *     itemSize - (itemSize * mask)} depending on how margins are included in the {@code mask}.
      * @param isFocal Whether this keyline is considered part of the focal range. Typically, this is
      *     when {@code mask} is equal to 0.
+     * @param isAnchor Whether this keyline is an anchor keyline. Anchor keylines do not shift when
+     *     keylines are shifted.
+     * @param cutoff How much the keyline item is out the bounds of the available space.
      */
     @NonNull
     @CanIgnoreReturnValue
     Builder addKeyline(
         float offsetLoc,
         @FloatRange(from = 0.0F, to = 1.0F) float mask,
         float maskedItemSize,
-        boolean isFocal) {
+        boolean isFocal,
+        boolean isAnchor,
+        float cutoff) {
       if (maskedItemSize <= 0F) {
         return this;
       }
+      if (isAnchor) {
+        if (isFocal) {
+          throw new IllegalArgumentException(
+              "Anchor keylines cannot be focal.");
+        }
+        if (latestAnchorKeylineIndex != NO_INDEX && latestAnchorKeylineIndex != 0) {
+          throw new IllegalArgumentException(
+              "Anchor keylines must be either the first or last keyline.");
+        }
+        latestAnchorKeylineIndex = tmpKeylines.size();
+      }
 
-      Keyline tmpKeyline = new Keyline(UNKNOWN_LOC, offsetLoc, mask, maskedItemSize);
+      Keyline tmpKeyline =
+          new Keyline(UNKNOWN_LOC, offsetLoc, mask, maskedItemSize, isAnchor, cutoff);
       if (isFocal) {
         if (tmpFirstFocalKeyline == null) {
           tmpFirstFocalKeyline = tmpKeyline;
@@ -294,6 +382,81 @@ Builder addKeyline(
       return this;
     }
 
+    /**
+     * Adds a keyline along the scrolling axis where an object should be masked by the given {@code
+     * mask} and positioned at {@code offsetLoc}. This method also calculates the amount that a
+     * keyline may be cut off by the bounds of the available space given.
+     *
+     * <p>Note that calls to {@link #addKeyline(float, float, float, boolean, boolean)} and {@link
+     * #addKeylineRange(float, float, float, int)} are added in order. Typically, this means
+     * keylines should be added in order of ascending {@code offsetLoc}. The first and last keylines
+     * added are 'anchor' keylines that mark the start and ends of the keylines. These keylines do
+     * not shift when scrolled.
+     *
+     * <p>Note also that {@code isFocal} and {@code isAnchor} cannot be true at the same time as
+     * anchor keylines refer to keylines offscreen that dictate the ends of the keylines.
+     *
+     * @param offsetLoc The location of this keyline along the scrolling axis. An offsetLoc of 0
+     *     will be at the start of the scroll container.
+     * @param mask The percentage of a child's full size that it should be masked by when its center
+     *     is at {@code offsetLoc}. 0 is fully unmasked and 1 is fully masked.
+     * @param maskedItemSize The total size of this item when masked. This might differ from {@code
+     *     itemSize - (itemSize * mask)} depending on how margins are included in the {@code mask}.
+     * @param isFocal Whether this keyline is considered part of the focal range. Typically, this is
+     *     when {@code mask} is equal to 0.
+     * @param isAnchor Whether this keyline is an anchor keyline. Anchor keylines do not shift when
+     *     keylines are shifted.
+     */
+    @NonNull
+    @CanIgnoreReturnValue
+    Builder addKeyline(
+        float offsetLoc,
+        @FloatRange(from = 0.0F, to = 1.0F) float mask,
+        float maskedItemSize,
+        boolean isFocal,
+        boolean isAnchor) {
+      float cutoff = 0;
+      // Calculate if the item will be cut off on either side. Currently we do not support an item
+      // cut off on both sides as we do not not support that use case. If an item is cut off on both
+      // sides, only the end cutoff will be included in the cutoff.
+      float keylineStart = offsetLoc - maskedItemSize/2F;
+      float keylineEnd = offsetLoc + maskedItemSize/2F;
+      if (keylineEnd > availableSpace) {
+        cutoff = Math.abs(keylineEnd - max(keylineEnd - maskedItemSize, availableSpace));
+      } else if (keylineStart < 0) {
+        cutoff = Math.abs(keylineStart - min(keylineStart + maskedItemSize, 0));
+      }
+
+      return addKeyline(offsetLoc, mask, maskedItemSize, isFocal, isAnchor, cutoff);
+    }
+
+    /**
+     * Adds an anchor keyline along the scrolling axis where an object should be masked by the given
+     * {@code mask} and positioned at {@code offsetLoc}.
+     *
+     * <p>Anchor keylines are keylines that are added to increase motion of carousel items going
+     * out of bounds of the carousel, and are 'anchored' (ie. does not shift). These keylines must
+     * be at the start or end of all keylines.
+     *
+     * <p>Note that calls to {@link #addKeyline(float, float, float, boolean)} and {@link
+     * #addKeylineRange(float, float, float, int)} are added in order. This method should be called
+     * first, or last of all the `addKeyline` calls.
+     *
+     * @param offsetLoc The location of this keyline along the scrolling axis. An offsetLoc of 0
+     *     will be at the start of the scroll container.
+     * @param mask The percentage of a child's full size that it should be masked by when its center
+     *     is at {@code offsetLoc}. 0 is fully unmasked and 1 is fully masked.
+     * @param maskedItemSize The total size of this item when masked. This might differ from {@code
+     *     itemSize - (itemSize * mask)} depending on how margins are included in the {@code mask}.
+     */
+    @NonNull
+    @CanIgnoreReturnValue
+    Builder addAnchorKeyline(
+        float offsetLoc, @FloatRange(from = 0.0F, to = 1.0F) float mask, float maskedItemSize) {
+      return addKeyline(
+          offsetLoc, mask, maskedItemSize, /* isFocal= */ false, /* isAnchor= */ true);
+    }
+
     /**
      * Adds a range of keylines along the scrolling axis where an item should be masked by {@code
      * mask} when its center is between {@code offsetLoc} and {@code offsetLoc + (maskedItemSize *
@@ -366,7 +529,9 @@ KeylineState build() {
                     tmpFirstFocalKeyline.locOffset, itemSize, firstFocalKeylineIndex, i),
                 tmpKeyline.locOffset,
                 tmpKeyline.mask,
-                tmpKeyline.maskedItemSize);
+                tmpKeyline.maskedItemSize,
+                tmpKeyline.isAnchor,
+                tmpKeyline.cutoff);
         keylines.add(keyline);
       }
 
@@ -401,9 +566,11 @@ static final class Keyline {
     final float locOffset;
     final float mask;
     final float maskedItemSize;
+    final boolean isAnchor;
+    final float cutoff;
 
     /**
-     * Creates a keyline along a scroll axis.
+     * Creates a non-anchor keyline along a scroll axis.
      *
      * @param loc Where this item will be along the scroll axis if it were laid out end-to-end when
      *     it should be in the state defined by {@code locOffset} and {@code mask}.
@@ -414,10 +581,36 @@ static final class Keyline {
      * @param maskedItemSize The size of this item when masked.
      */
     Keyline(float loc, float locOffset, float mask, float maskedItemSize) {
+      this(loc, locOffset, mask, maskedItemSize, /* isAnchor= */ false, 0);
+    }
+
+    /**
+     * Creates a keyline along a scroll axis.
+     *
+     * @param loc Where this item will be along the scroll axis if it were laid out end-to-end when
+     *     it should be in the state defined by {@code locOffset} and {@code mask}.
+     * @param locOffset The location within the carousel where an item should be when its center is
+     *     at {@code loc}.
+     * @param mask The percentage of this items full size that it should be masked by when its
+     *     center is at {@code loc}.
+     * @param maskedItemSize The size of this item when masked.
+     * @param isAnchor Whether or not the keyline is an anchor keyline (keylines at the end that do
+     *     not shift).
+     * @param cutoff The amount by which the keyline item is cut off by the bounds of the carousel.
+     */
+    Keyline(
+        float loc,
+        float locOffset,
+        float mask,
+        float maskedItemSize,
+        boolean isAnchor,
+        float cutoff) {
       this.loc = loc;
       this.locOffset = locOffset;
       this.mask = mask;
       this.maskedItemSize = maskedItemSize;
+      this.isAnchor = isAnchor;
+      this.cutoff = cutoff;
     }
 
     /** Linearly interpolates between two keylines and returns the interpolated object. */

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

@@ -83,7 +83,7 @@ private KeylineStateList(
   /** Creates a new {@link KeylineStateList} from a {@link KeylineState}. */
   static KeylineStateList from(Carousel carousel, KeylineState state) {
     return new KeylineStateList(
-        state, getStateStepsStart(state), getStateStepsEnd(carousel, state));
+        state, getStateStepsStart(carousel, state), getStateStepsEnd(carousel, state));
   }
 
   /** Returns the default state for this state list. */
@@ -334,21 +334,23 @@ private static boolean isFirstFocalItemAtLeftOfContainer(KeylineState state) {
    * last state will be the start state or the state that has the focal range at the beginning of
    * the carousel.
    */
-  private static List<KeylineState> getStateStepsStart(KeylineState defaultState) {
+  private static List<KeylineState> getStateStepsStart(
+      Carousel carousel, KeylineState defaultState) {
     List<KeylineState> steps = new ArrayList<>();
     steps.add(defaultState);
-    int firstInBoundsKeylineIndex = findFirstInBoundsKeylineIndex(defaultState);
+    int firstNonAnchorKeylineIndex = findFirstNonAnchorKeylineIndex(defaultState);
     // If the first focal item is already at the left of the container or there are no in bounds
     // keylines, return a list of steps that only includes the default state (there is nowhere to
     // shift).
     if (isFirstFocalItemAtLeftOfContainer(defaultState)
-        || firstInBoundsKeylineIndex == NO_INDEX) {
+        || firstNonAnchorKeylineIndex == NO_INDEX) {
       return steps;
     }
 
-    int start = firstInBoundsKeylineIndex;
+    int start = firstNonAnchorKeylineIndex;
     int end = defaultState.getFirstFocalKeylineIndex() - 1;
     int numberOfSteps = end - start;
+    float cutoffs = 0;
 
     float originalStart =
         defaultState.getFirstKeyline().locOffset
@@ -361,6 +363,7 @@ private static List<KeylineState> getStateStepsStart(KeylineState defaultState)
       // Otherwise, use it's adjacent item's mask to find suitable index on the other side of the
       // focal range where it can be placed.
       int dstIndex = defaultState.getKeylines().size() - 1;
+      cutoffs += defaultState.getKeylines().get(itemOrigIndex).cutoff;
       if (itemOrigIndex - 1 >= 0) {
         float originalAdjacentMaskLeft = defaultState.getKeylines().get(itemOrigIndex - 1).mask;
         dstIndex =
@@ -374,11 +377,14 @@ private static List<KeylineState> getStateStepsStart(KeylineState defaultState)
       KeylineState shifted =
           moveKeylineAndCreateKeylineState(
               prevStepState,
-              /* keylineSrcIndex= */ firstInBoundsKeylineIndex,
+              /* keylineSrcIndex= */ firstNonAnchorKeylineIndex,
               /* keylineDstIndex= */ dstIndex,
-              originalStart,
+              originalStart + cutoffs,
               newFirstFocalIndex,
-              newLastFocalIndex);
+              newLastFocalIndex,
+              carousel.isHorizontal()
+                  ? carousel.getContainerWidth()
+                  : carousel.getContainerHeight());
       steps.add(shifted);
     }
     return steps;
@@ -391,17 +397,18 @@ private static List<KeylineState> getStateStepsStart(KeylineState defaultState)
    * @param carousel the {@link Carousel} associated with this {@link KeylineStateList}.
    * @param state the state to check for right item position
    * @return true if the {@code state}'s first focal item has its right aligned with the right of
-   *     the {@code carousel} container
+   *     the {@code carousel} container and is fully visible.
    */
-  private static boolean isLastFocalItemAtRightOfContainer(Carousel carousel, KeylineState state) {
+  private static boolean isLastFocalItemVisibleAtRightOfContainer(
+      Carousel carousel, KeylineState state) {
     int containerSize = carousel.getContainerHeight();
     if (carousel.isHorizontal()) {
       containerSize = carousel.getContainerWidth();
     }
-    float firstFocalItemRight =
+    float lastFocalItemRight =
         state.getLastFocalKeyline().locOffset + (state.getLastFocalKeyline().maskedItemSize / 2F);
-    return firstFocalItemRight >= containerSize
-        || state.getLastFocalKeyline() == state.getLastKeyline();
+    return lastFocalItemRight <= containerSize
+        && state.getLastFocalKeyline() == state.getLastNonAnchorKeyline();
   }
 
   /**
@@ -424,26 +431,49 @@ private static List<KeylineState> getStateStepsEnd(
       Carousel carousel, KeylineState defaultState) {
     List<KeylineState> steps = new ArrayList<>();
     steps.add(defaultState);
-    int lastInBoundsKeylineIndex = findLastInBoundsKeylineIndex(carousel, defaultState);
-    // If the focal end item is already at the end of the container or there are no in bounds
-    // keylines, return a list of steps that only includes the default state (there is nowhere to
-    // shift).
-    if (isLastFocalItemAtRightOfContainer(carousel, defaultState)
-        || lastInBoundsKeylineIndex == NO_INDEX) {
+    int lastNonAnchorKeylineIndex = findLastNonAnchorKeylineIndex(defaultState);
+
+    // If the focal end item is already at the end of the container and is fully visible or there
+    // are no in bounds keylines, return a list of steps that only includes the default state
+    // (there is nowhere to shift).
+    if (isLastFocalItemVisibleAtRightOfContainer(carousel, defaultState)
+        || lastNonAnchorKeylineIndex == NO_INDEX) {
       return steps;
     }
 
-    int start = defaultState.getLastFocalKeylineIndex();
-    int end = lastInBoundsKeylineIndex;
-    int numberOfSteps = end - start;
+    float carouselSize =
+        carousel.isHorizontal() ? carousel.getContainerWidth() : carousel.getContainerHeight();
 
     float originalStart =
         defaultState.getFirstKeyline().locOffset
             - (defaultState.getFirstKeyline().maskedItemSize / 2F);
 
+    // If we are here, it means that the last keyline is focal, but is cut off
+    // since it is not visible. If this is the case, we want to add one step where
+    // the keylines are shifted so that the last keyline is visible.
+    if (defaultState.getLastFocalKeyline() == defaultState.getLastNonAnchorKeyline()) {
+      KeylineState shifted =
+          moveKeylineAndCreateKeylineState(
+              defaultState,
+              /* keylineSrcIndex= */ defaultState.getLastFocalKeylineIndex(),
+              /* keylineDstIndex= */ defaultState.getFirstFocalKeylineIndex(),
+              originalStart - defaultState.getLastFocalKeyline().cutoff,
+              defaultState.getFirstFocalKeylineIndex(),
+              defaultState.getLastFocalKeylineIndex(),
+              carouselSize);
+      steps.add(shifted);
+      return steps;
+    }
+
+    int start = defaultState.getLastFocalKeylineIndex();
+    int end = lastNonAnchorKeylineIndex;
+    int numberOfSteps = end - start;
+    float cutoffs = 0;
+
     for (int i = 0; i < numberOfSteps; i++) {
       KeylineState prevStepState = steps.get(steps.size() - 1);
       int itemOrigIndex = end - i;
+      cutoffs += defaultState.getKeylines().get(itemOrigIndex).cutoff;
       // If this is the last item from the original state, place it at the start of the dest state.
       // Otherwise, use it's adjacent item's mask to find suitable index on the other side of the
       // focal range where it can be placed.
@@ -458,15 +488,15 @@ private static List<KeylineState> getStateStepsEnd(
       // The index of the start and end focal keylines in this step's keyline state.
       int newFirstFocalIndex = defaultState.getFirstFocalKeylineIndex() + i + 1;
       int newLastFocalIndex = defaultState.getLastFocalKeylineIndex() + i + 1;
-
       KeylineState shifted =
           moveKeylineAndCreateKeylineState(
               prevStepState,
-              /* keylineSrcIndex= */ lastInBoundsKeylineIndex,
+              /* keylineSrcIndex= */ lastNonAnchorKeylineIndex,
               /* keylineDstIndex= */ dstIndex,
-              originalStart,
+              originalStart - cutoffs,
               newFirstFocalIndex,
-              newLastFocalIndex);
+              newLastFocalIndex,
+              carouselSize);
       steps.add(shifted);
     }
 
@@ -492,20 +522,23 @@ private static KeylineState moveKeylineAndCreateKeylineState(
       int keylineDstIndex,
       float startOffset,
       int newFirstFocalIndex,
-      int newLastFocalIndex) {
+      int newLastFocalIndex,
+      float carouselSize) {
 
     List<Keyline> tmpKeylines = new ArrayList<>(state.getKeylines());
     Keyline item = tmpKeylines.remove(keylineSrcIndex);
     tmpKeylines.add(keylineDstIndex, item);
 
-    KeylineState.Builder builder = new KeylineState.Builder(state.getItemSize());
+    KeylineState.Builder builder = new KeylineState.Builder(state.getItemSize(), carouselSize);
 
     for (int j = 0; j < tmpKeylines.size(); j++) {
       Keyline k = tmpKeylines.get(j);
       float offset = startOffset + (k.maskedItemSize / 2F);
 
       boolean isFocal = j >= newFirstFocalIndex && j <= newLastFocalIndex;
-      builder.addKeyline(offset, k.mask, k.maskedItemSize, isFocal);
+      // We must keep the same cutoff value from the default keylines instead of re-calculating
+      // them based on the new offset.
+      builder.addKeyline(offset, k.mask, k.maskedItemSize, isFocal, k.isAnchor, k.cutoff);
       startOffset += k.maskedItemSize;
     }
 
@@ -534,23 +567,19 @@ private static int findLastIndexBeforeFirstFocalKeylineWithMask(KeylineState sta
     return 0;
   }
 
-  private static int findFirstInBoundsKeylineIndex(KeylineState state) {
+  private static int findFirstNonAnchorKeylineIndex(KeylineState state) {
     for (int i = 0; i < state.getKeylines().size(); i++) {
-      if (state.getKeylines().get(i).locOffset >= 0) {
+      if (!state.getKeylines().get(i).isAnchor) {
         return i;
       }
     }
 
     return NO_INDEX;
   }
 
-  private static int findLastInBoundsKeylineIndex(Carousel carousel, KeylineState state) {
-    int containerSize = carousel.getContainerHeight();
-    if (carousel.isHorizontal()) {
-      containerSize = carousel.getContainerWidth();
-    }
+  private static int findLastNonAnchorKeylineIndex(KeylineState state) {
     for (int i = state.getKeylines().size() - 1; i >= 0; i--) {
-      if (state.getKeylines().get(i).locOffset <= containerSize) {
+      if (!state.getKeylines().get(i).isAnchor) {
         return i;
       }
     }

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

@@ -0,0 +1,168 @@
+/*
+ * Copyright 2023 The Android Open Source Project
+ *
+ * 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
+ *
+ *     https://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.
+ */
+
+package com.google.android.material.carousel;
+
+import static com.google.android.material.carousel.CarouselStrategyHelper.getExtraSmallSize;
+import static java.lang.Math.max;
+
+import android.content.Context;
+import androidx.recyclerview.widget.RecyclerView.LayoutParams;
+import android.view.View;
+import androidx.annotation.NonNull;
+import androidx.annotation.RestrictTo;
+import androidx.annotation.RestrictTo.Scope;
+
+/**
+ * A {@link CarouselStrategy} that does not resize the original item width and fits as many as it
+ * can into the container, cutting off the rest. Cut off items may be resized in order to show an
+ * effect of items getting smaller at the ends.
+ *
+ * Note that this strategy does not adjust the size of large items. Item widths are taken
+ * from the {@link androidx.recyclerview.widget.RecyclerView} item width.
+ *
+ * <p>This class will automatically be reversed by {@link CarouselLayoutManager} if being laid out
+ * right-to-left and does not need to make any account for layout direction itself.
+ *
+ * <p>For more information, see the <a
+ * href="https://github.com/material-components/material-components-android/blob/master/docs/components/Carousel.md">component
+ * developer guidance</a> and <a href="https://material.io/components/carousel/overview">design
+ * guidelines</a>.
+ */
+public final class UncontainedCarouselStrategy extends CarouselStrategy {
+
+  @RestrictTo(Scope.LIBRARY_GROUP)
+  public UncontainedCarouselStrategy() {
+  }
+
+  @Override
+  @NonNull
+  KeylineState onFirstChildMeasuredWithMargins(@NonNull Carousel carousel, @NonNull View child) {
+    float availableSpace =
+        carousel.isHorizontal() ? carousel.getContainerWidth() : carousel.getContainerHeight();
+
+    LayoutParams childLayoutParams = (LayoutParams) child.getLayoutParams();
+    float childMargins = childLayoutParams.topMargin + childLayoutParams.bottomMargin;
+    float measuredChildSize = child.getMeasuredHeight();
+
+    if (carousel.isHorizontal()) {
+      childMargins = childLayoutParams.leftMargin + childLayoutParams.rightMargin;
+      measuredChildSize = child.getMeasuredWidth();
+    }
+
+    float largeChildSize = measuredChildSize + childMargins;
+    float mediumChildSize = getExtraSmallSize(child.getContext()) + childMargins;
+    float xSmallChildSize = getExtraSmallSize(child.getContext()) + childMargins;
+
+    // Calculate how much space there is remaining after squeezing in as many large items as we can.
+    int largeCount = (int) Math.floor(availableSpace/largeChildSize);
+    float remainingSpace = availableSpace - largeCount*largeChildSize;
+    int mediumCount = 0;
+    // If the keyline location for the next large size would be within the remaining space,
+    // then we can place a large child there as the last non-anchor keyline because visually
+    // keylines will become smaller as it goes past the large keyline location.
+    // Otherwise, we want to add a medium item instead so that visually there will still
+    // be the effect of the item getting smaller closer to the end.
+    if (remainingSpace > largeChildSize/2F) {
+      largeCount += 1;
+    } else {
+      mediumCount = 1;
+      // We want the medium size to be large enough to be at least 1/3 of the way cut
+      // off.
+      mediumChildSize = max(remainingSpace + remainingSpace/2F, mediumChildSize);
+    }
+
+    return createKeylineState(
+        child.getContext(),
+        childMargins,
+        availableSpace,
+        largeChildSize,
+        largeCount,
+        mediumChildSize,
+        mediumCount,
+        xSmallChildSize);
+  }
+
+  private KeylineState createKeylineState(
+      Context context,
+      float childMargins,
+      float availableSpace,
+      float largeSize,
+      int largeCount,
+      float mediumSize,
+      int mediumCount,
+      float xSmallSize) {
+
+    float extraSmallMask =
+        getChildMaskPercentage(xSmallSize, largeSize, childMargins);
+    float mediumMask =
+        getChildMaskPercentage(mediumSize, largeSize, childMargins);
+    float largeMask = 0F;
+
+    float start = 0F;
+    float extraSmallHeadCenterX = start - (xSmallSize / 2F);
+
+    float largeStartCenterX = largeSize/2F;
+    // We exclude one large item from the large count so we can calculate the correct
+    // cutoff value for the last large item if it is getting cut off.
+    int excludedLargeCount = max(largeCount - 1, 1);
+    start += excludedLargeCount * largeSize;
+    // Where to start laying the last possibly-cutoff large item.
+    float lastEndStart = start + largeSize / 2F;
+
+    // Add xsmall keyline, and then if there is more than 1 large keyline, add
+    // however many large keylines there are except for the last one that may be cut off.
+    KeylineState.Builder builder =
+        new KeylineState.Builder(largeSize, availableSpace)
+            .addAnchorKeyline(extraSmallHeadCenterX, extraSmallMask, xSmallSize)
+            .addKeylineRange(
+                largeStartCenterX,
+                largeMask,
+                largeSize,
+                excludedLargeCount,
+                /* isFocal= */ true);
+
+    // If we have more than 1 large item, then here we include the last large item that is
+    // possibly getting cut off.
+    if (largeCount > 1) {
+      start += largeSize;
+      builder.addKeyline(
+          lastEndStart,
+          largeMask,
+          largeSize,
+          /* isFocal= */ true);
+    }
+
+    if (mediumCount > 0) {
+      float mediumCenterX = start + mediumSize / 2F;
+      start += mediumSize;
+      builder.addKeyline(
+          mediumCenterX,
+          mediumMask,
+          mediumSize,
+          /* isFocal= */ false);
+    }
+
+    float xSmallCenterX = start + getExtraSmallSize(context) / 2F;
+    builder.addAnchorKeyline(xSmallCenterX, extraSmallMask, xSmallSize);
+    return builder.build();
+  }
+
+  @Override
+  boolean isContained() {
+    return false;
+  }
+}

lib/javatests/com/google/android/material/carousel/CarouselHelper.java

@@ -382,7 +382,7 @@ static KeylineState getTestCenteredKeylineState() {
     float smallMask = getKeylineMaskPercentage(smallSize, largeSize);
     float mediumMask = getKeylineMaskPercentage(mediumSize, largeSize);
 
-    return new KeylineState.Builder(450F)
+    return new KeylineState.Builder(450F, 1320F)
         .addKeyline(5F, extraSmallMask, extraSmallSize)
         .addKeylineRange(38F, smallMask, smallSize, 2)
         .addKeyline(166F, mediumMask, mediumSize)
@@ -403,7 +403,7 @@ static KeylineState getTestCenteredVerticalKeylineState() {
     float smallMask = getKeylineMaskPercentage(smallSize, largeSize);
     float mediumMask = getKeylineMaskPercentage(mediumSize, largeSize);
 
-    return new KeylineState.Builder(100F)
+    return new KeylineState.Builder(100F, 200F)
         .addKeyline(9F, smallMask, smallSize)
         .addKeyline(25F, mediumMask, mediumSize)
         .addKeyline(66F, 0F, largeSize, true)

lib/javatests/com/google/android/material/carousel/CarouselLayoutManagerRtlTest.java

@@ -97,7 +97,9 @@ public void testScrollBeyondMaxHorizontalScroll_shouldLimitToMaxScrollOffset() t
     scrollToPosition(recyclerView, layoutManager, 200);
 
     KeylineState leftState =
-        KeylineStateList.from(layoutManager, KeylineState.reverse(keylineState)).getStartState();
+        KeylineStateList.from(
+                layoutManager, KeylineState.reverse(keylineState, DEFAULT_RECYCLER_VIEW_WIDTH))
+            .getStartState();
 
     MaskableFrameLayout child =
         (MaskableFrameLayout) recyclerView.getChildAt(recyclerView.getChildCount() - 1);
@@ -182,7 +184,7 @@ private static KeylineState getTestCenteredKeylineState() {
     float smallMask = 1F - (smallSize / largeSize);
     float mediumMask = 1F - (mediumSize / largeSize);
 
-    return new KeylineState.Builder(450F)
+    return new KeylineState.Builder(450F, DEFAULT_RECYCLER_VIEW_WIDTH)
         .addKeyline(5F, extraSmallMask, extraSmallSize)
         .addKeylineRange(38F, smallMask, smallSize, 2)
         .addKeyline(166F, mediumMask, mediumSize)

lib/javatests/com/google/android/material/carousel/CarouselLayoutManagerTest.java

@@ -93,7 +93,7 @@ public void testMaskedChild_isStillGivenFullWidthBounds() throws Throwable {
           @Override
           KeylineState onFirstChildMeasuredWithMargins(
               @NonNull Carousel carousel, @NonNull View child) {
-            return new KeylineState.Builder(DEFAULT_ITEM_WIDTH)
+            return new KeylineState.Builder(DEFAULT_ITEM_WIDTH, DEFAULT_RECYCLER_VIEW_WIDTH)
                 .addKeyline(225F, .5F, 225F, true)
                 .build();
           }
@@ -112,7 +112,7 @@ public void testMaskedChild_isMaskedToCorrectSize() throws Throwable {
           @Override
           KeylineState onFirstChildMeasuredWithMargins(
               @NonNull Carousel carousel, @NonNull View child) {
-            return new KeylineState.Builder(DEFAULT_ITEM_WIDTH)
+            return new KeylineState.Builder(DEFAULT_ITEM_WIDTH, DEFAULT_RECYCLER_VIEW_WIDTH)
                 .addKeyline(225F, .8F, 90F, true)
                 .build();
           }
@@ -675,11 +675,11 @@ KeylineState onFirstChildMeasuredWithMargins(@NonNull Carousel carousel, @NonNul
       float focal = largeSize / 2F;
       float smallTail = focal + (largeSize / 2F) + (smallSize / 2F);
       float xSmallTail = availableSpace + (xSmallSize / 2F);
-      return new KeylineState.Builder(largeSize)
-          .addKeyline(xSmallHead, getKeylineMaskPercentage(xSmallSize, largeSize), xSmallSize)
+      return new KeylineState.Builder(largeSize, availableSpace)
+          .addAnchorKeyline(xSmallHead, getKeylineMaskPercentage(xSmallSize, largeSize), xSmallSize)
           .addKeyline(focal, 0F, largeSize, true)
           .addKeyline(smallTail, getKeylineMaskPercentage(smallSize, largeSize), smallSize)
-          .addKeyline(xSmallTail, getKeylineMaskPercentage(xSmallSize, largeSize), xSmallSize)
+          .addAnchorKeyline(xSmallTail, getKeylineMaskPercentage(xSmallSize, largeSize), xSmallSize)
           .build();
     }
 

lib/javatests/com/google/android/material/carousel/KeylineStateListTest.java

@@ -43,7 +43,7 @@ public void testCenterArrangement_shouldShiftStart() {
           new float[] {20F, 60F, 90F, 110F, 125F, 135F}
         };
     KeylineState state =
-        new KeylineState.Builder(40F)
+        new KeylineState.Builder(40F, 140)
             .addKeyline(5F, getKeylineMaskPercentage(10F, 40F), 10F)
             .addKeyline(20F, getKeylineMaskPercentage(20F, 40F), 20F)
             .addKeylineRange(50F, 0F, 40F, 2, true)
@@ -72,7 +72,7 @@ public void testCenterArrangement_shouldCreateIntermediaryStates() {
           new float[] {20F, 60F, 90F, 110F, 125F, 135F}
         };
     KeylineState state =
-        new KeylineState.Builder(40F)
+        new KeylineState.Builder(40F, 140)
             .addKeyline(5F, getKeylineMaskPercentage(10F, 40F), 10F)
             .addKeyline(20F, getKeylineMaskPercentage(20F, 40F), 20F)
             .addKeylineRange(50F, 0F, 40F, 2, true)
@@ -103,7 +103,7 @@ public void testCenterArrangement_shouldShiftEnd() {
         };
 
     KeylineState state =
-        new KeylineState.Builder(40F)
+        new KeylineState.Builder(40F, 140)
             .addKeyline(5F, getKeylineMaskPercentage(10F, 40F), 10F)
             .addKeyline(20F, getKeylineMaskPercentage(20F, 40F), 20F)
             .addKeylineRange(50F, 0F, 40F, 2, true)
@@ -126,7 +126,7 @@ public void testCenterArrangement_shouldShiftEnd() {
   @Test
   public void testCenterArrangement_shouldNotShift() {
     KeylineState state =
-        new KeylineState.Builder(40F)
+        new KeylineState.Builder(40F, 140)
             .addKeyline(5F, getKeylineMaskPercentage(10F, 40F), 10F)
             .addKeyline(20F, getKeylineMaskPercentage(20F, 40F), 20F)
             .addKeylineRange(50F, 0F, 40F, 2, true)
@@ -144,7 +144,7 @@ public void testCenterArrangement_shouldNotShift() {
   @Test
   public void testStartArrangement_shouldShiftStart() {
     KeylineState state =
-        new KeylineState.Builder(40F)
+        new KeylineState.Builder(40F, 70)
             .addKeyline(20F, 0F, 40F, true)
             .addKeyline(50F, getKeylineMaskPercentage(20F, 40F), 20F)
             .addKeyline(65F, getKeylineMaskPercentage(10F, 40F), 10F)
@@ -169,7 +169,7 @@ public void testStartArrangement_shouldShiftEnd() {
         };
 
     KeylineState state =
-        new KeylineState.Builder(40F)
+        new KeylineState.Builder(40F, 70)
             .addKeyline(20F, 0F, 40F, true)
             .addKeyline(50F, getKeylineMaskPercentage(20F, 40F), 20F)
             .addKeyline(65F, getKeylineMaskPercentage(10F, 40F), 10F)
@@ -191,16 +191,17 @@ public void testStartArrangement_shouldShiftEnd() {
   public void testStartArrangementWithOutOfBoundsKeylines_shouldShiftStart() {
     float[][] startStepsLocOffsets =
         new float[][] {
-          new float[] {-10F, 10F, 40F, 70F, 85F},
-          new float[] {-10F, 20F, 50F, 70F, 85F}
+          new float[] {-10F, 10F, 40F, 70F, 90F},
+          new float[] {-10F, 20F, 50F, 70F, 90F}
         };
 
     KeylineState state =
-        new KeylineState.Builder(40F)
-            .addKeylineRange(-10F, getKeylineMaskPercentage(20F, 40F), 20F, 2)
+        new KeylineState.Builder(40F, 90)
+            .addAnchorKeyline(-10F, getKeylineMaskPercentage(20F, 40F), 20F)
+            .addKeyline(10F, getKeylineMaskPercentage(20F, 40F), 20F, false)
             .addKeyline(40F, 0F, 40F, true)
             .addKeyline(70F, getKeylineMaskPercentage(20F, 40F), 20F)
-            .addKeyline(85F, getKeylineMaskPercentage(10F, 40F), 10F)
+            .addKeyline(90F, getKeylineMaskPercentage(20F, 40F), 20F)
             .build();
     KeylineStateList stateList = KeylineStateList.from(createCarouselWithWidth(90), state);
 
@@ -220,17 +221,21 @@ public void testStartArrangementWithOutOfBoundsKeylines_shouldShiftStart() {
   public void testStartArrangementWithOutOfBoundsKeyline_shouldShiftEnd() {
     float[][] endStepsLocOffsets =
         new float[][] {
-          new float[] {-10F, 10F, 40F, 70F, 90F, 110F, 125F},
-          new float[] {-10F, 10F, 30F, 60F, 90F, 110F, 125F},
-          new float[] {-10F, 10F, 30F, 50F, 80F, 110F, 125F},
+            // keyline sizes are as follows: {20, 20, 20, 20, 40, 20, 20}
+            new float[] {-50F, -30F, -10F, 10F, 40F, 70F, 90F},
+            // keyline sizes are as follows: {20, 20, 20, 20, 20, 40, 20}
+            new float[] {-50F, -30F, -10F, 10F, 30F, 60F, 90F},
+            // keyline sizes are as follows: {20, 20, 20, 20, 20, 20, 40}
+            new float[] {-50F, -30F, -10F, 10F, 30F, 50F, 80F},
         };
 
     KeylineState state =
-        new KeylineState.Builder(40F)
-            .addKeylineRange(-10F, getKeylineMaskPercentage(20F, 40F), 20F, 2)
+        new KeylineState.Builder(40F, 100F)
+            .addAnchorKeyline(-10F, getKeylineMaskPercentage(20F, 40F), 20F)
+            .addKeyline(10F, getKeylineMaskPercentage(20F, 40F), 20F, false)
             .addKeyline(40F, 0F, 40F, true)
             .addKeylineRange(70F, getKeylineMaskPercentage(20F, 40F), 20F, 3)
-            .addKeyline(125F, getKeylineMaskPercentage(10F, 40F), 10F)
+            .addKeyline(130F, getKeylineMaskPercentage(20F, 40F), 20F)
             .build();
     KeylineStateList stateList = KeylineStateList.from(createCarouselWithWidth(100), state);
 
@@ -239,7 +244,8 @@ public void testStartArrangementWithOutOfBoundsKeyline_shouldShiftEnd() {
     float maxScroll = 5 * 40F;
 
     for (int j = 0; j < scrollSteps.length; j++) {
-      KeylineState s = stateList.getShiftedState(maxScroll - scrollSteps[j], minScroll, maxScroll);
+      KeylineState s =
+          stateList.getShiftedState(maxScroll - scrollSteps[j], minScroll, maxScroll, true);
       for (int i = 0; i < s.getKeylines().size(); i++) {
         assertThat(s.getKeylines().get(i).locOffset).isEqualTo(endStepsLocOffsets[j][i]);
       }
@@ -255,7 +261,7 @@ public void testEndArrangement_shouldShiftStart() {
           new float[] {20F, 50F, 65F}
         };
     KeylineState state =
-        new KeylineState.Builder(40F)
+        new KeylineState.Builder(40F, 70)
             .addKeyline(5F, getKeylineMaskPercentage(10F, 40F), 10F)
             .addKeyline(20F, getKeylineMaskPercentage(20F, 40F), 20F)
             .addKeyline(50F, 0F, 40F, true)
@@ -276,7 +282,7 @@ public void testEndArrangement_shouldShiftStart() {
   @Test
   public void testEndArrangement_shouldNotShiftEnd() {
     KeylineState state =
-        new KeylineState.Builder(40F)
+        new KeylineState.Builder(40F, 70)
             .addKeyline(5F, getKeylineMaskPercentage(10F, 40F), 10F)
             .addKeyline(20F, getKeylineMaskPercentage(20F, 40F), 20F)
             .addKeyline(50F, 0F, 40F, true)
@@ -290,14 +296,14 @@ public void testEndArrangement_shouldNotShiftEnd() {
   }
 
   @Test
-  public void testFullScreenArrangementWithOutOfBoundsKeylines_nothingShifts() {
+  public void testFullScreenArrangementWithAnchorKeylines_nothingShifts() {
     float[] locOffsets = new float[] {-5F, 20F, 45F};
 
     KeylineState state =
-        new KeylineState.Builder(40F)
-            .addKeyline(-5F, getKeylineMaskPercentage(210F, 40F), 10F)
+        new KeylineState.Builder(40F, 40)
+            .addAnchorKeyline(-5F, getKeylineMaskPercentage(210F, 40F), 10F)
             .addKeyline(20F, 0F, 40F, true)
-            .addKeyline(45F, getKeylineMaskPercentage(10F, 40F), 10F)
+            .addAnchorKeyline(45F, getKeylineMaskPercentage(10F, 40F), 10F)
             .build();
     KeylineStateList stateList = KeylineStateList.from(createCarouselWithWidth(40), state);
 
@@ -312,7 +318,7 @@ public void testFullScreenArrangementWithOutOfBoundsKeylines_nothingShifts() {
   @Test
   public void testMultipleFocalItems_shiftsFocalRange() {
     KeylineState state =
-        new KeylineState.Builder(100F)
+        new KeylineState.Builder(100F, 500)
             .addKeyline(25F, .5F, 50F)
             .addKeylineRange(100F, 0F, 100F, 4, true)
             .addKeyline(475F, .5F, 50F)
@@ -326,7 +332,7 @@ public void testMultipleFocalItems_shiftsFocalRange() {
   @Test
   public void testKeylineStateForPosition() {
     KeylineState state =
-        new KeylineState.Builder(100F)
+        new KeylineState.Builder(100F, 500)
             .addKeyline(25F, .5F, 50F)
             .addKeylineRange(100F, 0F, 100F, 4, true)
             .addKeyline(475F, .5F, 50F)
@@ -354,7 +360,7 @@ public void testKeylineStateForPosition() {
   @Test
   public void testKeylineStateForPositionRTL() {
     KeylineState state =
-        new KeylineState.Builder(100F)
+        new KeylineState.Builder(100F, 500)
             .addKeyline(25F, .5F, 50F)
             .addKeylineRange(100F, 0F, 100F, 4, true)
             .addKeyline(475F, .5F, 50F)
@@ -383,7 +389,7 @@ public void testKeylineStateForPositionRTL() {
   @Test
   public void testKeylineStateForPositionVertical() {
     KeylineState state =
-        new KeylineState.Builder(100F)
+        new KeylineState.Builder(100F, 500)
             .addKeyline(25F, .5F, 50F)
             .addKeylineRange(100F, 0F, 100F, 4, true)
             .addKeyline(475F, .5F, 50F)
@@ -408,4 +414,70 @@ public void testKeylineStateForPositionVertical() {
     }
     assertThat(latestKeylineLoc).isEqualTo(stateList.getEndState().getFirstFocalKeyline().loc);
   }
+
+  @Test
+  public void testCutoffEndKeylines_changeEndKeylineLocOffsets() {
+    float[][] endStepsLocOffsets =
+        new float[][] {
+            // keyline sizes are as follows: {large, large, cutoff-large}
+            new float[] {-5F, 20F, 60F, 100F, 125F},
+            // keyline sizes are as follows: {cutoff-large, large, large}
+            new float[] {-25F, 0F, 40F, 80F, 105F},
+        };
+
+    // Carousel size is 100, with 2 larges and a cutoff large
+    KeylineState state =
+        new KeylineState.Builder(40F, 100)
+            .addAnchorKeyline(-5F, getKeylineMaskPercentage(10F, 40F), 10F)
+            .addKeyline(20F, 0F, 40F, /* isFocal= */ true)
+            .addKeyline(60F, 0F, 40F, /* isFocal= */ true)
+            .addKeyline(100F, 0F, 40F, /* isFocal= */ true)
+            .addAnchorKeyline(125F, getKeylineMaskPercentage(10F, 40F), 10F)
+            .build();
+    KeylineStateList stateList = KeylineStateList.from(createCarouselWithWidth(100), state);
+
+    float[] scrollSteps = new float[] {40F, 0F};
+    float minScroll = 0F;
+    float maxScroll = 5 * 80F;
+
+    for (int j = 0; j < scrollSteps.length; j++) {
+      KeylineState s = stateList.getShiftedState(maxScroll - scrollSteps[j], minScroll, maxScroll);
+      for (int i = 0; i < s.getKeylines().size(); i++) {
+        assertThat(s.getKeylines().get(i).locOffset).isEqualTo(endStepsLocOffsets[j][i]);
+      }
+    }
+  }
+
+  @Test
+  public void testCutoffStartKeylines_doesNotChangeEndKeylineLocOffsets() {
+    float[][] endStepsLocOffsets =
+        new float[][] {
+            // keyline sizes are as follows: {cutoff-large, large, large}
+            new float[] {-25F, 0F, 40F, 80F, 105F},
+            // keyline sizes are as follows: {cutoff-large, large, large}
+            new float[] {-25F, 0F, 40F, 80F, 105F},
+        };
+
+    // Carousel size is 100, with cutoff large and 2 larges
+    KeylineState state =
+        new KeylineState.Builder(40F, 100)
+            .addAnchorKeyline(-25F, getKeylineMaskPercentage(10F, 40F), 10F)
+            .addKeyline(0F, 0F, 40F, /* isFocal= */ true)
+            .addKeyline(40F, 0F, 40F, /* isFocal= */ true)
+            .addKeyline(80F, 0F, 40F, /* isFocal= */ true)
+            .addAnchorKeyline(105F, getKeylineMaskPercentage(10F, 40F), 10F)
+            .build();
+    KeylineStateList stateList = KeylineStateList.from(createCarouselWithWidth(100), state);
+
+    float[] scrollSteps = new float[] {40F, 0F};
+    float minScroll = 0F;
+    float maxScroll = 5 * 80F;
+
+    for (int j = 0; j < scrollSteps.length; j++) {
+      KeylineState s = stateList.getShiftedState(maxScroll - scrollSteps[j], minScroll, maxScroll);
+      for (int i = 0; i < s.getKeylines().size(); i++) {
+        assertThat(s.getKeylines().get(i).locOffset).isEqualTo(endStepsLocOffsets[j][i]);
+      }
+    }
+  }
 }

lib/javatests/com/google/android/material/carousel/KeylineStateTest.java

@@ -41,13 +41,13 @@ public final class KeylineStateTest {
   public void testNoFocalRange_throwsException() {
     assertThrows(
         IllegalStateException.class,
-        () -> new KeylineState.Builder(100F).addKeyline(0, .5F, 50F).build());
+        () -> new KeylineState.Builder(100F, 0).addKeyline(0, .5F, 50F).build());
   }
 
   @Test
   public void testZeroSizedKeyline_shouldNotAddKeyline() {
     KeylineState keylineState =
-        new KeylineState.Builder(100F)
+        new KeylineState.Builder(100F, 0)
             .addKeyline(50F, 0F, 100F, true)
             .addKeyline(100F, 1F, 0F)
             .build();
@@ -57,7 +57,7 @@ public void testZeroSizedKeyline_shouldNotAddKeyline() {
   @Test
   public void testZeroCountKeylineRange_shouldNotAddKeylines() {
     KeylineState keylineState =
-        new KeylineState.Builder(100F)
+        new KeylineState.Builder(100F, 0)
             .addKeyline(50F, 0F, 100F, true)
             .addKeylineRange(110F, .8F, 20F, 0)
             .build();
@@ -69,7 +69,7 @@ public void testStartFocalItemWithDifferentSize_shouldThrowException() {
     assertThrows(
         IllegalArgumentException.class,
         () ->
-            new KeylineState.Builder(100F)
+            new KeylineState.Builder(100F, 0)
                 .addKeyline(25F, .5F, 50F, true)
                 .addKeyline(100F, 0F, 100F)
                 .addKeyline(200F, 0F, 100F, true)
@@ -81,7 +81,7 @@ public void testEndFocalItemWithDifferentSize_shouldThrowException() {
     assertThrows(
         IllegalArgumentException.class,
         () ->
-            new KeylineState.Builder(100F)
+            new KeylineState.Builder(100F, 0)
                 .addKeyline(50F, 0F, 100F, true)
                 .addKeyline(150F, 0F, 100F)
                 .addKeyline(275F, .5F, 50F, true)
@@ -93,7 +93,7 @@ public void testMiddleFocalItemWithDifferentSize_shouldThrowException() {
     assertThrows(
         IllegalArgumentException.class,
         () ->
-            new KeylineState.Builder(100F)
+            new KeylineState.Builder(100F, 0)
                 .addKeyline(50F, 0F, 100F, true)
                 .addKeyline(125F, .5F, 50F)
                 .addKeyline(200F, 0F, 100F, true)
@@ -109,23 +109,24 @@ public void testKeylines_areSortedByOffsetLocation() {
 
   @Test
   public void testReverseKeylines_shouldReverse() {
+    int recyclerWidth = 100;
     // Extra small items are 10F, Small items are 50F, large items are 100F
     KeylineState keylineState =
-        new KeylineState.Builder(100F)
+        new KeylineState.Builder(100F, recyclerWidth)
             .addKeyline(-5F, getKeylineMaskPercentage(10F, 100F), 10F)
             .addKeyline(50F, 0F, 100F, true)
             .addKeyline(125F, getKeylineMaskPercentage(50F, 100F), 50F)
             .addKeyline(155F, getKeylineMaskPercentage(10F, 100F), 10F)
             .build();
 
     KeylineState expectedState =
-        new KeylineState.Builder(100F)
+        new KeylineState.Builder(100F, recyclerWidth)
             .addKeyline(-5F, getKeylineMaskPercentage(10F, 100F), 10F)
             .addKeyline(25F, getKeylineMaskPercentage(50, 100F), 50F)
             .addKeyline(100F, 0F, 100F, true)
             .addKeyline(155F, getKeylineMaskPercentage(10F, 100F), 10F)
             .build();
-    KeylineState reversedState = KeylineState.reverse(keylineState);
+    KeylineState reversedState = KeylineState.reverse(keylineState, recyclerWidth);
 
     assertThat(reversedState.getKeylines()).hasSize(expectedState.getKeylines().size());
     for (int i = 0; i < reversedState.getKeylines().size(); i++) {
@@ -155,7 +156,7 @@ public void testCenteredArrangement_calculatesOffsetLocations() {
   public void testStartArrangement_hasFocalRangeAtFrontOfList() {
     // Create a keyline state that has a [e-e-p-p] arrangement.
     KeylineState keylineState =
-        new KeylineState.Builder(100F)
+        new KeylineState.Builder(100F, 0)
             .addKeylineRange(50F, 0F, 100F, 2, true)
             .addKeylineRange(325F, .5F, 50F, 2)
             .build();
@@ -167,27 +168,27 @@ public void testStartArrangement_hasFocalRangeAtFrontOfList() {
   @Test
   public void testAddKeyline_onlyAddsSingleKeyline() {
     KeylineState keylineState =
-        new KeylineState.Builder(100F).addKeyline(50F, 0F, 100F, true).build();
+        new KeylineState.Builder(100F, 0).addKeyline(50F, 0F, 100F, true).build();
     assertThat(keylineState.getKeylines()).hasSize(1);
   }
 
   @Test
   public void testAddKeylineRange_addsTwoKeylines() {
     KeylineState keylineState =
-        new KeylineState.Builder(100F).addKeylineRange(50F, 0F, 100F, 2, true).build();
+        new KeylineState.Builder(100F, 0).addKeylineRange(50F, 0F, 100F, 2, true).build();
     assertThat(keylineState.getKeylines()).hasSize(2);
   }
 
   @Test
   public void testLerpKeylineStates_statesHaveDifferentNumberOfKeylinesShouldThrowException() {
     KeylineState keylineDefaultState =
-        new KeylineState.Builder(100F)
+        new KeylineState.Builder(100F, 0)
             .addKeyline(25F, .5F, 50F)
             .addKeylineRange(100F, 0F, 100F, 2, true)
             .addKeyline(275F, .5F, 50F)
             .build();
     KeylineState keylineStartState =
-        new KeylineState.Builder(100F)
+        new KeylineState.Builder(100F, 0)
             .addKeylineRange(50F, 0F, 100F, 2, true)
             .addKeylineRange(225F, .5F, 50F, 3)
             .build();
@@ -200,13 +201,13 @@ public void testLerpKeylineStates_statesHaveDifferentNumberOfKeylinesShouldThrow
   @Test
   public void testLerpKeylineStates_focalIndicesShiftAtHalfWayPoint() {
     KeylineState keylineDefaultState =
-        new KeylineState.Builder(100F)
+        new KeylineState.Builder(100F, 0)
             .addKeyline(25F, .5F, 50F)
             .addKeylineRange(100F, 0F, 100F, 2, true)
             .addKeyline(275F, .5F, 50F)
             .build();
     KeylineState keylineStartState =
-        new KeylineState.Builder(100F)
+        new KeylineState.Builder(100F, 0)
             .addKeylineRange(50F, 0F, 100F, 2, true)
             .addKeylineRange(225F, .5F, 50F, 2)
             .build();
@@ -239,6 +240,49 @@ public void testLerpKeylineStates_focalIndicesShiftAtHalfWayPoint() {
         .isEqualTo(keylineDefaultState.getLastFocalKeylineIndex());
   }
 
+  @Test
+  public void testAddingAnchorKeyline_mustBeAtStartOrEnd() {
+    assertThrows(
+        IllegalArgumentException.class,
+        () ->
+            new KeylineState.Builder(100F, 0)
+                .addAnchorKeyline(25F, .5F, 50F)
+                .addAnchorKeyline(100F, 0F, 100F)
+                .addAnchorKeyline(200F, 0F, 100F)
+                .build());
+    }
+
+  @Test
+  public void testGetFirstNonAnchorKeyline() {
+    KeylineState keylineDefaultState =
+        new KeylineState.Builder(100F, 0)
+            .addAnchorKeyline(25F, .5F, 50F)
+            .addKeylineRange(100F, 0F, 100F, 2, true)
+            .build();
+    assertThat(keylineDefaultState.getFirstNonAnchorKeyline().maskedItemSize).isEqualTo(100F);
+  }
+
+  @Test
+  public void testGetLastNonAnchorKeyline() {
+    KeylineState keylineDefaultState =
+        new KeylineState.Builder(100F, 0)
+            .addAnchorKeyline(25F, .5F, 50F)
+            .addKeyline(100F, 0F, 100F, true)
+            .addAnchorKeyline(175F, .5F, 50F)
+            .build();
+    assertThat(keylineDefaultState.getFirstNonAnchorKeyline().maskedItemSize).isEqualTo(100F);
+  }
+
+  @Test
+  public void testAnchorKeyline_cannotBeFocal() {
+    assertThrows(
+        IllegalArgumentException.class,
+        () ->
+            new KeylineState.Builder(100F, 0)
+                .addKeyline(25F, .5F, 50F, /* isFocal= */ true, /* isAnchor= */ true)
+                .build());
+  }
+
   /**
    * Creates a {@link KeylineState.Builder} that has a centered focal range with three large items,
    * and one medium item, two small items, and one extra small item on each side of the focal range.
@@ -256,7 +300,7 @@ private KeylineState.Builder createKeylineStateBuilder() {
     float smallMask = 1F - (smallSize / largeSize);
     float mediumMask = 1F - (mediumSize / largeSize);
 
-    return new KeylineState.Builder(largeSize)
+    return new KeylineState.Builder(largeSize, 2470)
         .addKeyline(5F, extraSmallMask, extraSmallSize)
         .addKeylineRange(85F, smallMask, smallSize, 2)
         .addKeyline(435F, mediumMask, mediumSize)

lib/javatests/com/google/android/material/carousel/UncontainedCarouselStrategyTest.java

@@ -0,0 +1,122 @@
+/*
+ * Copyright 2023 The Android Open Source Project
+ *
+ * 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.
+ */
+package com.google.android.material.carousel;
+
+import com.google.android.material.test.R;
+
+import static com.google.android.material.carousel.CarouselHelper.createCarouselWithWidth;
+import static com.google.android.material.carousel.CarouselHelper.createViewWithSize;
+import static com.google.common.truth.Truth.assertThat;
+
+import android.view.View;
+import androidx.test.core.app.ApplicationProvider;
+import com.google.common.collect.Iterables;
+import org.junit.Test;
+import org.junit.runner.RunWith;
+import org.robolectric.RobolectricTestRunner;
+
+/** Tests for {@link UncontainedCarouselStrategy}. */
+@RunWith(RobolectricTestRunner.class)
+public class UncontainedCarouselStrategyTest {
+
+  @Test
+  public void testLargeItem_withFullCarouselWidth() {
+    Carousel carousel = createCarouselWithWidth(400);
+    UncontainedCarouselStrategy config = new UncontainedCarouselStrategy();
+    View view = createViewWithSize(ApplicationProvider.getApplicationContext(), 400, 400);
+
+    KeylineState keylineState = config.onFirstChildMeasuredWithMargins(carousel, view);
+    float xSmallSize =
+        view.getResources().getDimension(R.dimen.m3_carousel_gone_size);
+
+    // A fullscreen layout should be [xSmall-large-xSmall-xSmall] where the xSmall items are
+    // outside the bounds of the carousel container and the large item takes up the
+    // containers full width.
+    assertThat(keylineState.getKeylines()).hasSize(4);
+    assertThat(keylineState.getKeylines().get(0).locOffset).isLessThan(0F);
+    assertThat(keylineState.getKeylines().get(1).mask).isEqualTo(0F);
+    assertThat(keylineState.getKeylines().get(2).locOffset).isEqualTo(carousel.getContainerWidth() + xSmallSize/2F);
+    assertThat(Iterables.getLast(keylineState.getKeylines()).locOffset)
+        .isGreaterThan((float) carousel.getContainerWidth());
+  }
+
+  @Test
+  public void testLargeItem_largerThanFullCarouselWidth() {
+    Carousel carousel = createCarouselWithWidth(400);
+    UncontainedCarouselStrategy config = new UncontainedCarouselStrategy();
+    int cutOff = 10;
+    View view = createViewWithSize(ApplicationProvider.getApplicationContext(), 400 + cutOff, 400);
+
+    KeylineState keylineState = config.onFirstChildMeasuredWithMargins(carousel, view);
+
+    // The layout should be [xSmall-large-xSmall] where the xSmall items are
+    // outside the bounds of the carousel container and the large item takes up the
+    // containers full width.
+    assertThat(keylineState.getKeylines()).hasSize(3);
+    assertThat(keylineState.getKeylines().get(0).locOffset).isLessThan(0F);
+    assertThat(keylineState.getKeylines().get(1).mask).isEqualTo(0F);
+    assertThat(Iterables.getLast(keylineState.getKeylines()).locOffset)
+        .isGreaterThan((float) carousel.getContainerWidth());
+  }
+
+  @Test
+  public void testRemainingSpaceWithItemSize_fitsItemWithThirdCutoff() {
+    Carousel carousel = createCarouselWithWidth(400);
+    UncontainedCarouselStrategy config = new UncontainedCarouselStrategy();
+    // With size 125px, 3 large items can fit with in 400px, with 25px left over which is less than
+    // half 125px. This means that a large keyline will not fit in the remaining space
+    // such that any motion is seen when scrolling past the keyline, so a medium item
+    // should be added.
+    View view = createViewWithSize(ApplicationProvider.getApplicationContext(), 125, 400);
+
+    KeylineState keylineState = config.onFirstChildMeasuredWithMargins(carousel, view);
+
+    // The layout should be [xSmall-large-large-large-medium-xSmall] where medium is a size
+    // such that a third of it is cut off.
+    assertThat(keylineState.getKeylines()).hasSize(6);
+    assertThat(keylineState.getKeylines().get(0).locOffset).isLessThan(0F);
+    assertThat(keylineState.getKeylines().get(1).mask).isEqualTo(0F);
+    assertThat(keylineState.getKeylines().get(2).mask).isEqualTo(0F);
+    assertThat(keylineState.getKeylines().get(3).mask).isEqualTo(0F);
+    assertThat(keylineState.getKeylines().get(4).locOffset)
+        .isLessThan((float) carousel.getContainerWidth());
+    assertThat(Iterables.getLast(keylineState.getKeylines()).locOffset)
+        .isGreaterThan((float) carousel.getContainerWidth());
+  }
+
+  @Test
+  public void testRemainingSpaceWithItemSize_fitsLargeItemWithCutoff() {
+    Carousel carousel = createCarouselWithWidth(400);
+    UncontainedCarouselStrategy config = new UncontainedCarouselStrategy();
+    int itemSize = 105;
+    // With size 105px, 3 large items can fit with in 400px, with 85px left over which is more than
+    // half 105px. This means that an extra large keyline will fit in the remaining space such
+    // that motion is seen when scrolling past the keyline, so it should add a large item.
+    View view = createViewWithSize(ApplicationProvider.getApplicationContext(), itemSize, 400);
+
+    KeylineState keylineState = config.onFirstChildMeasuredWithMargins(carousel, view);
+
+    // The layout should be [xSmall-large-large-large-large-xSmall]
+    assertThat(keylineState.getKeylines()).hasSize(6);
+    assertThat(keylineState.getKeylines().get(0).locOffset).isLessThan(0F);
+    assertThat(keylineState.getKeylines().get(1).mask).isEqualTo(0F);
+    assertThat(keylineState.getKeylines().get(2).mask).isEqualTo(0F);
+    assertThat(keylineState.getKeylines().get(3).mask).isEqualTo(0F);
+    assertThat(keylineState.getKeylines().get(4).mask).isEqualTo(0F);
+    assertThat(Iterables.getLast(keylineState.getKeylines()).locOffset)
+        .isGreaterThan((float) carousel.getContainerWidth());
+  }
+}