allow customization

Assisted-By: devx/6db0ff39-6d19-4074-ab7f-a027dc8b067f

Author: kiftio

platforms/android/README.md

@@ -168,13 +168,15 @@ Configure global presentation defaults before presenting checkout:
 ```kotlin
 ShopifyCheckoutKit.configure {
     it.colorScheme = ColorScheme.Automatic()
+    it.sheetStyle = CheckoutSheetStyle()
     it.logLevel = LogLevel.ERROR
 }
 ```
 
 | Option | Default | Purpose |
 | --- | --- | --- |
 | `colorScheme` | `ColorScheme.Automatic()` | Use device appearance, force `Light` or `Dark`, or use `Web` to match web checkout branding. |
+| `sheetStyle` | `CheckoutSheetStyle()` | Customize native sheet chrome such as the top gap, corner radius, title alignment, toolbar elevation, close icon styling, and the optional drag handle. |
 | `logLevel` | `LogLevel.WARN` | SDK logging verbosity. Use `LogLevel.DEBUG` during integration. |
 | `preloading` | `Preloading(enabled = true)` | Enables best-effort checkout preloading before presentation. |
 
@@ -199,29 +201,40 @@ ShopifyCheckoutKit.configure {
             headerFont = Color.ResourceId(R.color.checkout_header_text_light)
             webViewBackground = Color.ResourceId(R.color.checkout_background_light)
             progressIndicator = Color.ResourceId(R.color.checkout_progress_light)
-            closeIconTint = Color.ResourceId(R.color.checkout_close_light)
         },
         dark = {
             headerBackground = Color.ResourceId(R.color.checkout_header_dark)
             headerFont = Color.ResourceId(R.color.checkout_header_text_dark)
             webViewBackground = Color.ResourceId(R.color.checkout_background_dark)
             progressIndicator = Color.ResourceId(R.color.checkout_progress_dark)
-            closeIconTint = Color.ResourceId(R.color.checkout_close_dark)
         },
     )
 }
 ```
 
-If both `closeIcon` and `closeIconTint` are set, the custom drawable takes precedence:
+### Sheet style
+
+Customize native sheet chrome independently from checkout colors:
 
 ```kotlin
 ShopifyCheckoutKit.configure {
-    it.colorScheme = ColorScheme.Light().customize {
-        closeIcon = DrawableResource(R.drawable.ic_checkout_close)
-    }
+    it.sheetStyle = CheckoutSheetStyle(
+        topGapDp = 24f,
+        cornerRadiusDp = 32f,
+        titleAlignment = CheckoutSheetTitleAlignment.CENTER,
+        toolbarElevationDp = 0f,
+        closeIconTint = Color.ResourceId(R.color.checkout_close),
+        dragHandleVisible = false,
+    )
 }
 ```
 
+Use `closeIcon = DrawableResource(R.drawable.ic_checkout_close)` to provide a custom close drawable. If both
+`closeIcon` and `closeIconTint` are set, the custom drawable takes precedence.
+
+Set `dragHandleVisible = true` to show a fixed, visual-only drag handle at the top of the sheet. The handle is hidden
+when `dragToDismissEnabled = false` so disabled drag gestures are not presented as available.
+
 ### Title localization
 
 Override `checkout_web_view_title` in your app resources:

platforms/android/lib/api/lib.api

@@ -90,6 +90,51 @@ public final class com/shopify/checkoutkit/CheckoutProtocol$Client {
 	public final fun on (Lcom/shopify/ucp/embedded/checkout/RequestDescriptor;Lkotlin/jvm/functions/Function1;)Lcom/shopify/checkoutkit/CheckoutProtocol$Client;
 }
 
+public final class com/shopify/checkoutkit/CheckoutSheetStyle {
+	public fun <init> ()V
+	public fun <init> (F)V
+	public fun <init> (FLcom/shopify/checkoutkit/CheckoutSheetTitleAlignment;)V
+	public fun <init> (FLcom/shopify/checkoutkit/CheckoutSheetTitleAlignment;F)V
+	public fun <init> (FLcom/shopify/checkoutkit/CheckoutSheetTitleAlignment;FLcom/shopify/checkoutkit/DrawableResource;)V
+	public fun <init> (FLcom/shopify/checkoutkit/CheckoutSheetTitleAlignment;FLcom/shopify/checkoutkit/DrawableResource;Lcom/shopify/checkoutkit/Color;)V
+	public fun <init> (FLcom/shopify/checkoutkit/CheckoutSheetTitleAlignment;FLcom/shopify/checkoutkit/DrawableResource;Lcom/shopify/checkoutkit/Color;Lcom/shopify/checkoutkit/Color;)V
+	public fun <init> (FLcom/shopify/checkoutkit/CheckoutSheetTitleAlignment;FLcom/shopify/checkoutkit/DrawableResource;Lcom/shopify/checkoutkit/Color;Lcom/shopify/checkoutkit/Color;Z)V
+	public fun <init> (FLcom/shopify/checkoutkit/CheckoutSheetTitleAlignment;FLcom/shopify/checkoutkit/DrawableResource;Lcom/shopify/checkoutkit/Color;Lcom/shopify/checkoutkit/Color;ZZ)V
+	public fun <init> (FLcom/shopify/checkoutkit/CheckoutSheetTitleAlignment;FLcom/shopify/checkoutkit/DrawableResource;Lcom/shopify/checkoutkit/Color;Lcom/shopify/checkoutkit/Color;ZZF)V
+	public synthetic fun <init> (FLcom/shopify/checkoutkit/CheckoutSheetTitleAlignment;FLcom/shopify/checkoutkit/DrawableResource;Lcom/shopify/checkoutkit/Color;Lcom/shopify/checkoutkit/Color;ZZFILkotlin/jvm/internal/DefaultConstructorMarker;)V
+	public final fun component1 ()F
+	public final fun component2 ()Lcom/shopify/checkoutkit/CheckoutSheetTitleAlignment;
+	public final fun component3 ()F
+	public final fun component4 ()Lcom/shopify/checkoutkit/DrawableResource;
+	public final fun component5 ()Lcom/shopify/checkoutkit/Color;
+	public final fun component6 ()Lcom/shopify/checkoutkit/Color;
+	public final fun component7 ()Z
+	public final fun component8 ()Z
+	public final fun component9 ()F
+	public final fun copy (FLcom/shopify/checkoutkit/CheckoutSheetTitleAlignment;FLcom/shopify/checkoutkit/DrawableResource;Lcom/shopify/checkoutkit/Color;Lcom/shopify/checkoutkit/Color;ZZF)Lcom/shopify/checkoutkit/CheckoutSheetStyle;
+	public static synthetic fun copy$default (Lcom/shopify/checkoutkit/CheckoutSheetStyle;FLcom/shopify/checkoutkit/CheckoutSheetTitleAlignment;FLcom/shopify/checkoutkit/DrawableResource;Lcom/shopify/checkoutkit/Color;Lcom/shopify/checkoutkit/Color;ZZFILjava/lang/Object;)Lcom/shopify/checkoutkit/CheckoutSheetStyle;
+	public fun equals (Ljava/lang/Object;)Z
+	public final fun getCloseIcon ()Lcom/shopify/checkoutkit/DrawableResource;
+	public final fun getCloseIconTint ()Lcom/shopify/checkoutkit/Color;
+	public final fun getCornerRadiusDp ()F
+	public final fun getDragHandleVisible ()Z
+	public final fun getDragToDismissEnabled ()Z
+	public final fun getScrimColor ()Lcom/shopify/checkoutkit/Color;
+	public final fun getTitleAlignment ()Lcom/shopify/checkoutkit/CheckoutSheetTitleAlignment;
+	public final fun getToolbarElevationDp ()F
+	public final fun getTopGapDp ()F
+	public fun hashCode ()I
+	public fun toString ()Ljava/lang/String;
+}
+
+public final class com/shopify/checkoutkit/CheckoutSheetTitleAlignment : java/lang/Enum {
+	public static final field CENTER Lcom/shopify/checkoutkit/CheckoutSheetTitleAlignment;
+	public static final field START Lcom/shopify/checkoutkit/CheckoutSheetTitleAlignment;
+	public static fun getEntries ()Lkotlin/enums/EnumEntries;
+	public static fun valueOf (Ljava/lang/String;)Lcom/shopify/checkoutkit/CheckoutSheetTitleAlignment;
+	public static fun values ()[Lcom/shopify/checkoutkit/CheckoutSheetTitleAlignment;
+}
+
 public class com/shopify/checkoutkit/CheckoutUnavailableException : com/shopify/checkoutkit/CheckoutException {
 	public static final field CLIENT_ERROR Ljava/lang/String;
 	public static final field Companion Lcom/shopify/checkoutkit/CheckoutUnavailableException$Companion;
@@ -374,19 +419,22 @@ public final class com/shopify/checkoutkit/ColorsBuilder {
 public final class com/shopify/checkoutkit/Configuration {
 	public fun <init> ()V
 	public final fun component1 ()Lcom/shopify/checkoutkit/ColorScheme;
-	public final fun component2 ()Lcom/shopify/checkoutkit/Platform;
-	public final fun component3 ()Lcom/shopify/checkoutkit/LogLevel;
-	public final fun component4 ()Lcom/shopify/checkoutkit/Preloading;
+	public final fun component2 ()Lcom/shopify/checkoutkit/CheckoutSheetStyle;
+	public final fun component3 ()Lcom/shopify/checkoutkit/Platform;
+	public final fun component4 ()Lcom/shopify/checkoutkit/LogLevel;
+	public final fun component5 ()Lcom/shopify/checkoutkit/Preloading;
 	public fun equals (Ljava/lang/Object;)Z
 	public final fun getColorScheme ()Lcom/shopify/checkoutkit/ColorScheme;
 	public final fun getLogLevel ()Lcom/shopify/checkoutkit/LogLevel;
 	public final fun getPlatform ()Lcom/shopify/checkoutkit/Platform;
 	public final fun getPreloading ()Lcom/shopify/checkoutkit/Preloading;
+	public final fun getSheetStyle ()Lcom/shopify/checkoutkit/CheckoutSheetStyle;
 	public fun hashCode ()I
 	public final fun setColorScheme (Lcom/shopify/checkoutkit/ColorScheme;)V
 	public final fun setLogLevel (Lcom/shopify/checkoutkit/LogLevel;)V
 	public final fun setPlatform (Lcom/shopify/checkoutkit/Platform;)V
 	public final fun setPreloading (Lcom/shopify/checkoutkit/Preloading;)V
+	public final fun setSheetStyle (Lcom/shopify/checkoutkit/CheckoutSheetStyle;)V
 	public fun toString ()Ljava/lang/String;
 }
 

platforms/android/lib/src/main/java/com/shopify/checkoutkit/CheckoutBottomSheet.kt

@@ -29,6 +29,7 @@ import androidx.core.view.WindowCompat
 import androidx.core.view.WindowInsetsCompat
 import androidx.core.view.children
 import com.shopify.checkoutkit.ShopifyCheckoutKit.log
+import kotlin.math.roundToInt
 
 internal class CheckoutBottomSheet(
     private val checkoutUrl: String,
@@ -68,12 +69,13 @@ internal class CheckoutBottomSheet(
         dismissFinalized = false
 
         setContentView(R.layout.checkout_sheet_content)
+        val colorScheme = ShopifyCheckoutKit.configuration.colorScheme
+        val sheetStyle = ShopifyCheckoutKit.configuration.sheetStyle
         window?.configureCheckoutBottomSheetWindow()
-        configureSheet()
+        configureSheet(sheetStyle)
 
-        val colorScheme = ShopifyCheckoutKit.configuration.colorScheme
         log.d(LOG_TAG, "Configured colorScheme $colorScheme")
-        val sheetColors = applySheetColors(colorScheme)
+        val sheetColors = applySheetColors(colorScheme, sheetStyle)
 
         onBackPressedDispatcher.addCallback(backNavigationCallback)
 
@@ -110,7 +112,10 @@ internal class CheckoutBottomSheet(
     /**
      * Applies configured colors to native sheet chrome and returns colors needed by WebView-owned surfaces.
      */
-    private fun applySheetColors(colorScheme: ColorScheme): SheetColors {
+    private fun applySheetColors(
+        colorScheme: ColorScheme,
+        sheetStyle: CheckoutSheetStyle,
+    ): SheetColors {
         val isDarkTheme = activity.isDarkTheme()
         val headerBackgroundColor = colorScheme.headerBackgroundColor(isDarkTheme).getValue(activity)
         val headerFontColor = colorScheme.headerFontColor(isDarkTheme).getValue(activity)
@@ -119,23 +124,45 @@ internal class CheckoutBottomSheet(
         findViewById<Toolbar>(R.id.checkoutKitHeader)?.apply {
             log.d(LOG_TAG, "Applying configured header colors and inflating menu.")
             title = ""
-            background = roundedTopCornerDrawable(activity, headerBackgroundColor)
+            background = roundedTopCornerDrawable(activity, headerBackgroundColor, sheetStyle.cornerRadiusDp)
+            elevation = sheetStyle.toolbarElevationDp.dpToPx(activity)
             setTitleTextColor(headerFontColor)
             inflateMenu(R.menu.checkout_menu)
-            menu.findItem(R.id.shopify_checkout_kit_close_button).setupCloseButton(activity, colorScheme) {
+            menu.findItem(R.id.shopify_checkout_kit_close_button).setupCloseButton(activity, colorScheme, sheetStyle) {
                 cancel()
             }
         }
 
-        findViewById<TextView>(R.id.checkoutKitHeaderTitle)
-            ?.setTextColor(headerFontColor)
+        findViewById<View>(R.id.checkoutKitDragHandle)?.applyCheckoutSheetDragHandleStyle(
+            color = headerFontColor,
+            sheetStyle = sheetStyle,
+        )
+
+        findViewById<TextView>(R.id.checkoutKitHeaderTitle)?.apply {
+            setTextColor(headerFontColor)
+            (layoutParams as? Toolbar.LayoutParams)?.let { params ->
+                params.topMargin = if (sheetStyle.showsDragHandle) {
+                    resources.getDimensionPixelSize(R.dimen.checkout_sheet_drag_handle_title_top_margin)
+                } else {
+                    0
+                }
+                params.gravity = when (sheetStyle.titleAlignment) {
+                    CheckoutSheetTitleAlignment.START -> Gravity.START or Gravity.CENTER_VERTICAL
+                    CheckoutSheetTitleAlignment.CENTER -> Gravity.CENTER
+                }
+                layoutParams = params
+            }
+        }
 
         findViewById<RelativeLayout>(R.id.checkoutKitContainer)
             ?.setBackgroundColor(webViewBackgroundColor)
 
         findViewById<View>(R.id.checkoutKitLoadingBackground)
             ?.setBackgroundColor(webViewBackgroundColor)
 
+        findViewById<View>(R.id.checkoutKitOutsideTouchTarget)
+            ?.setBackgroundColor(sheetStyle.scrimColor.getValue(activity))
+
         return SheetColors(
             webViewBackgroundColor = webViewBackgroundColor,
             progressIndicatorColor = colorScheme.progressIndicatorColor(isDarkTheme).getValue(activity),
@@ -145,14 +172,15 @@ internal class CheckoutBottomSheet(
     /**
      * Wires native sheet dismissal affordances after the layout has been inflated.
      */
-    private fun configureSheet() {
+    private fun configureSheet(sheetStyle: CheckoutSheetStyle) {
         findViewById<View>(R.id.checkoutKitOutsideTouchTarget)?.setOnClickListener {
             log.d(LOG_TAG, "Outside touch cancel invoked.")
             cancel()
         }
 
         findViewById<CheckoutBottomSheetLayout>(R.id.checkoutKitSheet)?.apply {
-            applySystemBarTopMargin()
+            dragToDismissEnabled = sheetStyle.dragToDismissEnabled
+            applySystemBarTopMargin(sheetStyle.topGapDp.dpToPx(activity).roundToInt())
             onDismissRequested = {
                 if (!dismissing) {
                     log.d(LOG_TAG, "Bottom sheet dismissed by gesture, cancelling checkout.")
@@ -337,14 +365,16 @@ private fun ComponentActivity.isDarkTheme() =
 private fun MenuItem.setupCloseButton(
     activity: ComponentActivity,
     colorScheme: ColorScheme,
+    sheetStyle: CheckoutSheetStyle,
     onClick: () -> Unit,
 ) {
-    val customCloseIcon = colorScheme.closeIcon(activity.isDarkTheme())
+    val isDarkTheme = activity.isDarkTheme()
+    val customCloseIcon = sheetStyle.closeIcon ?: colorScheme.closeIcon(isDarkTheme)
     if (customCloseIcon != null) {
         log.d(LOG_TAG, "Setting custom menu item drawable.")
         icon = AppCompatResources.getDrawable(activity, customCloseIcon.id)
     } else {
-        val customTint = colorScheme.closeIconTint(activity.isDarkTheme())
+        val customTint = sheetStyle.closeIconTint ?: colorScheme.closeIconTint(isDarkTheme)
         val closeIcon = icon
         if (customTint != null && closeIcon != null) {
             log.d(LOG_TAG, "Setting menu item tint.")
@@ -376,14 +406,14 @@ private fun View.applyBottomInsetPadding() {
 /**
  * Keeps the intended top gap visible below the status bar while the dialog window draws edge-to-edge.
  */
-private fun View.applySystemBarTopMargin() {
+private fun View.applySystemBarTopMargin(topGapPx: Int) {
     val initialLayoutParams = layoutParams as? ViewGroup.MarginLayoutParams ?: return
-    val initialTopMargin = initialLayoutParams.topMargin
     val initialBottomMargin = initialLayoutParams.bottomMargin
+    updateVerticalMargins(topMargin = topGapPx, bottomMargin = initialBottomMargin)
     ViewCompat.setOnApplyWindowInsetsListener(this) { view, insets ->
         val systemBars = insets.getInsets(WindowInsetsCompat.Type.systemBars())
         view.updateVerticalMargins(
-            topMargin = initialTopMargin + systemBars.top,
+            topMargin = topGapPx + systemBars.top,
             bottomMargin = initialBottomMargin,
         )
         insets
@@ -437,9 +467,9 @@ private fun Window.configureCheckoutBottomSheetWindow() {
     setTransparentSystemBars()
     WindowCompat.setDecorFitsSystemWindows(this, false)
     setSoftInputMode(WindowManager.LayoutParams.SOFT_INPUT_ADJUST_RESIZE)
-    addFlags(WindowManager.LayoutParams.FLAG_DIM_BEHIND)
+    clearFlags(WindowManager.LayoutParams.FLAG_DIM_BEHIND)
     attributes = attributes.apply {
-        dimAmount = WINDOW_DIM_AMOUNT
+        dimAmount = 0f
         windowAnimations = 0
     }
 }
@@ -464,4 +494,3 @@ private fun Window.setTransparentSystemBars() {
 }
 
 private const val LOG_TAG = "CheckoutBottomSheet"
-private const val WINDOW_DIM_AMOUNT = 0.32f

platforms/android/lib/src/main/java/com/shopify/checkoutkit/CheckoutBottomSheetDragHandle.kt

@@ -0,0 +1,36 @@
+package com.shopify.checkoutkit
+
+import android.graphics.Color
+import android.graphics.drawable.GradientDrawable
+import android.view.View
+import androidx.annotation.ColorInt
+
+/**
+ * Configures the optional Material-style visual drag affordance. Dismissal remains exposed through close/back/outside
+ * tap; the handle is decorative and intentionally hidden from accessibility focus.
+ */
+internal fun View.applyCheckoutSheetDragHandleStyle(
+    @ColorInt color: Int,
+    sheetStyle: CheckoutSheetStyle,
+) {
+    visibility = if (sheetStyle.showsDragHandle) View.VISIBLE else View.GONE
+    importantForAccessibility = View.IMPORTANT_FOR_ACCESSIBILITY_NO
+    isFocusable = false
+    isClickable = false
+
+    if (!sheetStyle.showsDragHandle) return
+
+    val handleHeight = resources.getDimension(R.dimen.checkout_sheet_drag_handle_height)
+    val handleAlpha = (Color.alpha(color) * CHECKOUT_SHEET_DRAG_HANDLE_ALPHA).toInt().coerceIn(0, ALPHA_MAX)
+    background = GradientDrawable().apply {
+        shape = GradientDrawable.RECTANGLE
+        cornerRadius = handleHeight / 2f
+        setColor(Color.argb(handleAlpha, Color.red(color), Color.green(color), Color.blue(color)))
+    }
+}
+
+internal val CheckoutSheetStyle.showsDragHandle: Boolean
+    get() = dragToDismissEnabled && dragHandleVisible
+
+private const val CHECKOUT_SHEET_DRAG_HANDLE_ALPHA = 0.4f
+private const val ALPHA_MAX = 255

platforms/android/lib/src/main/java/com/shopify/checkoutkit/CheckoutBottomSheetLayout.kt

@@ -24,6 +24,7 @@ internal class CheckoutBottomSheetLayout @JvmOverloads constructor(
 ) : RelativeLayout(context, attrs, defStyleAttr) {
 
     var onDismissRequested: (() -> Unit)? = null
+    var dragToDismissEnabled = true
 
     private val touchSlop = ViewConfiguration.get(context).scaledTouchSlop
     private val minimumFlingVelocity = ViewConfiguration.get(context).scaledMinimumFlingVelocity
@@ -71,6 +72,8 @@ internal class CheckoutBottomSheetLayout @JvmOverloads constructor(
      * Starts tracking a gesture that began inside the scrollable child.
      */
     fun startScrollableChildGesture(event: MotionEvent) {
+        if (!canHandleDragToDismiss) return
+
         animate().cancel()
         val currentOffsetY = (renderedDragOffsetY + translationY).coerceAtLeast(0f)
         translationY = 0f
@@ -89,7 +92,7 @@ internal class CheckoutBottomSheetLayout @JvmOverloads constructor(
      * Moves the sheet by drag distance the scrollable child hands off.
      */
     fun dragScrollableChildBy(dragDistance: Float, event: MotionEvent): Boolean {
-        val canDrag = isEnabled && !dismissAnimationRunning && dragDistance != 0f
+        val canDrag = canHandleDragToDismiss && dragDistance != 0f
         var sheetDragDistance = 0f
         if (canDrag && dragging) {
             sheetDragDistance = dragDistance
@@ -213,7 +216,7 @@ internal class CheckoutBottomSheetLayout @JvmOverloads constructor(
      * Intercepts downward drags that start outside the scrollable child so they can move the sheet.
      */
     override fun onInterceptTouchEvent(event: MotionEvent): Boolean {
-        if (!isEnabled || dismissAnimationRunning) return false
+        if (!canHandleDragToDismiss) return false
 
         var shouldIntercept = false
         when (event.actionMasked) {
@@ -247,7 +250,7 @@ internal class CheckoutBottomSheetLayout @JvmOverloads constructor(
      * Handles direct sheet drags and settles to either the expanded or dismissed position.
      */
     override fun onTouchEvent(event: MotionEvent): Boolean {
-        if (!isEnabled || dismissAnimationRunning) return false
+        if (!canHandleDragToDismiss) return false
 
         velocityTracker?.addMovement(event)
 
@@ -403,6 +406,9 @@ internal class CheckoutBottomSheetLayout @JvmOverloads constructor(
         return shouldHandle
     }
 
+    private val canHandleDragToDismiss: Boolean
+        get() = isEnabled && dragToDismissEnabled && !dismissAnimationRunning
+
     private companion object {
         private const val OPEN_ANIMATION_DURATION_MS = 260L
         private const val DISMISS_ANIMATION_DURATION_MS = 200L