Add advanceOnTargetTapOnly for restricting showcase advancement to taps inside the highlighted target

Author: tahaak67

README.md

@@ -311,6 +311,22 @@ ShowcaseLayout(
 ) 
 ```
 
+#### advanceOnTargetTapOnly
+
+By default a tap anywhere on the screen advances to the next target (or dismisses the showcase). Set
+`advanceOnTargetTapOnly = true` to only advance when the user taps **inside the highlighted target
+shape** — taps elsewhere are ignored. Useful when you want the user to actually interact with (or
+notice) the highlighted element before moving on. The greeting/initial screen still advances on any
+tap. Defaults to `false`. Available on both `ShowcaseLayout` and `TargetShowcaseLayout`.
+
+```kotlin
+ShowcaseLayout(
+    isShowcasing = isShowcasing,
+    onFinish = { isShowcasing = false },
+    advanceOnTargetTapOnly = true
+)
+```
+
 #### ShowcaseMsg
 
 Use `ShowcaseMsg()` to add a message and customize it with arrow, background and more.

composeApp/src/commonMain/kotlin/App.kt

@@ -31,12 +31,10 @@ import ly.com.tahaben.showcase_layout_compose.domain.ShowcaseEventListener
 import ly.com.tahaben.showcase_layout_compose.model.*
 import org.jetbrains.compose.resources.ExperimentalResourceApi
 import org.jetbrains.compose.resources.painterResource
-import org.jetbrains.compose.ui.tooling.preview.Preview
 import showcase_layout_compose_kmp.composeapp.generated.resources.*
 import kotlin.math.roundToInt
 
 @OptIn(ExperimentalResourceApi::class, ExperimentalMaterial3Api::class)
-@Preview
 @Composable
 fun App(openUrl: (String) -> Boolean, onWebLoadFinish: () -> Unit = {}) {
     LaunchedEffect(key1 = Unit, block = { onWebLoadFinish() })
@@ -92,6 +90,7 @@ fun App(openUrl: (String) -> Boolean, onWebLoadFinish: () -> Unit = {}) {
     var durationSliderValue by remember { mutableStateOf(500) }
     var animationDuration by remember { mutableStateOf(500) }
     var animateToNextTarget by remember { mutableStateOf(true) }
+    var advanceOnTargetTapOnly by remember { mutableStateOf(true) }
     var targetShape by remember { mutableStateOf(TargetShape.CIRCLE) }
     val targetShapeName by derivedStateOf {
         when(targetShape){
@@ -120,7 +119,8 @@ fun App(openUrl: (String) -> Boolean, onWebLoadFinish: () -> Unit = {}) {
             lineThickness = lineThinckness.dp,
             animationDuration = animationDuration,
             targetShape = targetShape,
-            animateToNextTarget = animateToNextTarget
+            animateToNextTarget = animateToNextTarget,
+            advanceOnTargetTapOnly = advanceOnTargetTapOnly
         ) {
             Column(modifier = Modifier.fillMaxSize().verticalScroll(scrollState)) {
                 TopAppBar(title = {
@@ -198,7 +198,7 @@ fun App(openUrl: (String) -> Boolean, onWebLoadFinish: () -> Unit = {}) {
                             expanded = selectTargetMenuExpaned,
                             onExpandedChange = { selectTargetMenuExpaned = it }) {
                             OutlinedTextField(
-                                modifier = Modifier.menuAnchor(type = MenuAnchorType.PrimaryNotEditable).showcase(
+                                modifier = Modifier.menuAnchor(type = ExposedDropdownMenuAnchorType.PrimaryNotEditable).showcase(
                                     4, message = ShowcaseMsg(
                                         text = buildAnnotatedString {
                                             append("You can choose what target to showcase form here then click the ")
@@ -259,7 +259,7 @@ fun App(openUrl: (String) -> Boolean, onWebLoadFinish: () -> Unit = {}) {
                             expanded = selectHeadMenuExpaned,
                             onExpandedChange = { selectHeadMenuExpaned = it }) {
                             OutlinedTextField(
-                                modifier = Modifier.menuAnchor(type = MenuAnchorType.PrimaryNotEditable),
+                                modifier = Modifier.menuAnchor(type = ExposedDropdownMenuAnchorType.PrimaryNotEditable),
                                 value = selectedHead,
                                 onValueChange = {},
                                 readOnly = true,
@@ -370,7 +370,7 @@ fun App(openUrl: (String) -> Boolean, onWebLoadFinish: () -> Unit = {}) {
                             expanded = selectTargetShapeMenuExpaned,
                             onExpandedChange = { selectTargetShapeMenuExpaned = it }) {
                             OutlinedTextField(
-                                modifier = Modifier.menuAnchor(MenuAnchorType.PrimaryNotEditable, true),
+                                modifier = Modifier.menuAnchor(ExposedDropdownMenuAnchorType.PrimaryNotEditable, true),
                                 value = targetShapeName,
                                 onValueChange = {},
                                 readOnly = true,
@@ -605,7 +605,7 @@ fun App(openUrl: (String) -> Boolean, onWebLoadFinish: () -> Unit = {}) {
                                         Modifier.selectable(
                                             selected = animateHead,
                                             onClick = { if (!useTargetShowcaseLayout) animateHead = !animateHead },
-                                            role = Role.RadioButton,
+                                            role = Role.Checkbox,
                                             enabled = !useTargetShowcaseLayout
                                         ), verticalAlignment = Alignment.CenterVertically
                                     ) {
@@ -621,6 +621,20 @@ fun App(openUrl: (String) -> Boolean, onWebLoadFinish: () -> Unit = {}) {
                                     }
                                 }
                             }
+                            Row(
+                                modifier = Modifier.selectable(
+                                    selected = advanceOnTargetTapOnly,
+                                    onClick = { advanceOnTargetTapOnly = !advanceOnTargetTapOnly },
+                                    role = Role.Checkbox
+                                ),
+                                verticalAlignment = Alignment.CenterVertically,
+                            ) {
+                                Text("Advance on target tap only")
+                                Checkbox(
+                                    checked = advanceOnTargetTapOnly,
+                                    onCheckedChange = { advanceOnTargetTapOnly = it }
+                                )
+                            }
                         }
                     }
                     Row {
@@ -735,7 +749,6 @@ fun App(openUrl: (String) -> Boolean, onWebLoadFinish: () -> Unit = {}) {
     }
 }
 
-@Preview
 @Composable
 fun AppPreview() {
     MyTheme {

composeApp/src/commonMain/kotlin/ShowcaseLayoutWrapper.kt

@@ -21,6 +21,7 @@ import ly.com.tahaben.showcase_layout_compose.ui.TargetShowcaseLayout
  * @param targetShape the shape of the target highlight (RECTANGLE, CIRCLE, or ROUNDED_RECTANGLE).
  * @param cornerRadius the corner radius for the ROUNDED_RECTANGLE shape in dp.
  * @param animateToNextTarget if true, the target shape will animate smoothly from one target to the next when the index changes (only used in TargetShowcaseLayout).
+ * @param advanceOnTargetTapOnly when true, only taps inside the highlighted target advance/dismiss the showcase; the greeting always advances on any tap.
  * @param colors the colors used to draw the overlay (and pulse for TargetShowcaseLayout), created with [ShowcaseLayoutDefaults.colors].
  */
 @Composable
@@ -35,6 +36,7 @@ fun ShowcaseLayoutWrapper(
     targetShape: TargetShape = TargetShape.RECTANGLE,
     cornerRadius: Dp = 16.dp,
     animateToNextTarget: Boolean = true,
+    advanceOnTargetTapOnly: Boolean = true,
     colors: ShowcaseLayoutDefaults.Colors = ShowcaseLayoutDefaults.colors(),
     content: @Composable ShowcaseScope.() -> Unit
 ) {
@@ -49,6 +51,7 @@ fun ShowcaseLayoutWrapper(
             targetShape = targetShape,
             cornerRadius = cornerRadius,
             animateToNextTarget = animateToNextTarget,
+            advanceOnTargetTapOnly = advanceOnTargetTapOnly,
             colors = colors,
             content = content
         )
@@ -62,6 +65,7 @@ fun ShowcaseLayoutWrapper(
             lineThickness = lineThickness,
             targetShape = targetShape,
             cornerRadius = cornerRadius,
+            advanceOnTargetTapOnly = advanceOnTargetTapOnly,
             colors = colors,
             content = content
         )

gradle/libs.versions.toml

@@ -1,8 +1,9 @@
 [versions]
 agp = "8.13.2"
-android-compileSdk = "35"
+android-compileSdk = "36"
 android-minSdk = "24"
-android-targetSdk = "35"
+#noinspection EditedTargetSdkVersion
+android-targetSdk = "36"
 androidx-activityCompose = "1.13.0"
 androidx-appcompat = "1.7.1"
 androidx-constraintlayout = "2.2.1"

showcase-layout-compose/src/commonMain/kotlin/ly/com/tahaben/showcase_layout_compose/domain/usecase/TargetHitTest.kt

@@ -0,0 +1,45 @@
+package ly.com.tahaben.showcase_layout_compose.domain.usecase
+
+import androidx.compose.ui.geometry.Offset
+import androidx.compose.ui.geometry.Size
+import ly.com.tahaben.showcase_layout_compose.model.TargetShape
+import kotlin.math.hypot
+import kotlin.math.max
+
+/**
+ * Returns true if [tap] falls inside the target highlight described by [topLeft] and [size]
+ * for the given [targetShape].
+ *
+ * Used to restrict advancing/dismissing the showcase to taps on the highlighted target.
+ *
+ * @param tap the tap position, in the same coordinate space as the drawn cutout.
+ * @param topLeft the top-left corner of the target bounds.
+ * @param size the size of the target bounds.
+ * @param targetShape the shape of the target highlight.
+ * @param tolerancePx expands the hit area on every side so tiny targets and finger slop still register.
+ */
+internal fun isTapInsideTarget(
+    tap: Offset,
+    topLeft: Offset,
+    size: Size,
+    targetShape: TargetShape,
+    tolerancePx: Float = 0f,
+): Boolean {
+    val left = topLeft.x - tolerancePx
+    val top = topLeft.y - tolerancePx
+    val right = topLeft.x + size.width + tolerancePx
+    val bottom = topLeft.y + size.height + tolerancePx
+    return when (targetShape) {
+        // The rounded-rectangle corners are approximated by the bounding box: the difference is a
+        // few pixels at each corner and is irrelevant for tap intent.
+        TargetShape.RECTANGLE, TargetShape.ROUNDED_RECTANGLE ->
+            tap.x in left..right && tap.y in top..bottom
+
+        TargetShape.CIRCLE -> {
+            val centerX = topLeft.x + size.width / 2f
+            val centerY = topLeft.y + size.height / 2f
+            val radius = max(size.width, size.height) / 2f + tolerancePx
+            hypot(tap.x - centerX, tap.y - centerY) <= radius
+        }
+    }
+}

showcase-layout-compose/src/commonMain/kotlin/ly/com/tahaben/showcase_layout_compose/ui/ShowcaseLayout.kt

@@ -34,6 +34,7 @@ import kotlinx.coroutines.flow.asStateFlow
 import kotlinx.coroutines.launch
 import ly.com.tahaben.showcase_layout_compose.domain.Level
 import ly.com.tahaben.showcase_layout_compose.domain.ShowcaseEventListener
+import ly.com.tahaben.showcase_layout_compose.domain.usecase.isTapInsideTarget
 import ly.com.tahaben.showcase_layout_compose.domain.usecase.validateInitIndex
 import ly.com.tahaben.showcase_layout_compose.model.*
 import kotlin.math.PI
@@ -59,6 +60,7 @@ import kotlin.math.max
 
 private const val TAG = "ShowcaseLayout "
 private const val INDEX_RESET_DELAY = 250L
+private const val TARGET_TAP_TOLERANCE_PX = 16f
 
 /**
  * ShowcaseLayout
@@ -71,6 +73,7 @@ private const val INDEX_RESET_DELAY = 250L
  * @param lineThickness thickness of the arrow line in dp.
  * @param targetShape the shape of the target highlight (RECTANGLE, CIRCLE, or ROUNDED_RECTANGLE).
  * @param cornerRadius the corner radius for the ROUNDED_RECTANGLE shape in dp.
+ * @param advanceOnTargetTapOnly when true, only taps inside the highlighted target shape advance/dismiss the showcase; taps elsewhere are ignored. The greeting/initial screen always advances on any tap. Defaults to false (tap anywhere).
  * @param colors the colors used to draw the overlay, created with [ShowcaseLayoutDefaults.colors]. Pass a light [ShowcaseLayoutDefaults.Colors.overlayColor] for a dark UI.
  **/
 
@@ -84,6 +87,7 @@ fun ShowcaseLayout(
     lineThickness: Dp = 5.dp,
     targetShape: TargetShape = TargetShape.RECTANGLE,
     cornerRadius: Dp = 16.dp,
+    advanceOnTargetTapOnly: Boolean = false,
     colors: ShowcaseLayoutDefaults.Colors = ShowcaseLayoutDefaults.colors(),
     content: @Composable ShowcaseScope.() -> Unit
 ) {
@@ -258,6 +262,17 @@ fun ShowcaseLayout(
                     .semantics { testTag = "canvas" }
                     .pointerInput(Unit) {
                         detectTapGestures {
+                            /** when enabled, only taps inside the target shape advance the showcase
+                             * (the greeting/initial screen always advances on any tap) */
+                            if (advanceOnTargetTapOnly && currentIndex != 0 && !isSingleGreeting &&
+                                !isTapInsideTarget(it, offset, itemSize, targetShape, TARGET_TAP_TOLERANCE_PX)
+                            ) {
+                                scope.showcaseEventListener?.onEvent(
+                                    Level.VERBOSE,
+                                    TAG + "tap outside target ignored at $it"
+                                )
+                                return@detectTapGestures
+                            }
                             /** detect taps on the screen */
                             coroutineScope.launch {
 
@@ -964,7 +979,7 @@ fun ShowcaseLayout(
     message = "isDarkLayout has been replaced by the colors parameter; pass a light overlay color instead.",
     replaceWith = ReplaceWith(
         "ShowcaseLayout(isShowcasing, initIndex, animationDuration, onFinish, greeting, " +
-                "lineThickness, targetShape, cornerRadius, " +
+                "lineThickness, targetShape, cornerRadius, false, " +
                 "ShowcaseLayoutDefaults.colors(overlayColor = if (isDarkLayout) Color.White.copy(alpha = 0.9f) else Color.Black.copy(alpha = 0.9f)), content)"
     )
 )

showcase-layout-compose/src/commonMain/kotlin/ly/com/tahaben/showcase_layout_compose/ui/TargetShowcaseLayout.kt

@@ -27,6 +27,7 @@ import androidx.compose.ui.unit.dp
 import kotlinx.coroutines.delay
 import kotlinx.coroutines.launch
 import ly.com.tahaben.showcase_layout_compose.domain.Level
+import ly.com.tahaben.showcase_layout_compose.domain.usecase.isTapInsideTarget
 import ly.com.tahaben.showcase_layout_compose.domain.usecase.validateInitIndex
 import ly.com.tahaben.showcase_layout_compose.model.MsgAnimation
 import ly.com.tahaben.showcase_layout_compose.model.ShowcaseMsg
@@ -54,6 +55,7 @@ import kotlin.math.min
 
 private const val TAG = "TargetShowcaseLayout "
 private const val INDEX_RESET_DELAY = 250L
+private const val TARGET_TAP_TOLERANCE_PX = 16f
 
 /**
  * TargetShowcaseLayout
@@ -68,6 +70,7 @@ private const val INDEX_RESET_DELAY = 250L
  * @param cornerRadius the radius of the corners when targetShape is ROUNDED_RECTANGLE.
  * @param animateToNextTarget if true, the target shape will animate smoothly from one target to the next when the index changes.
  *                           If false, the shape will shrink at the current location, then expand at the new location.
+ * @param advanceOnTargetTapOnly when true, only taps inside the highlighted target shape advance/dismiss the showcase; taps elsewhere are ignored. The greeting/initial screen always advances on any tap. Defaults to false (tap anywhere).
  * @param colors the colors used to draw the overlay and pulse, created with [ShowcaseLayoutDefaults.colors]. Pass a light [ShowcaseLayoutDefaults.Colors.overlayColor] for a dark UI. A per-step [ShowcaseMsg.msgBackground] still takes precedence over [ShowcaseLayoutDefaults.Colors.overlayColor].
  **/
 @Composable
@@ -81,6 +84,7 @@ fun TargetShowcaseLayout(
     targetShape: TargetShape = TargetShape.ROUNDED_RECTANGLE,
     cornerRadius: Dp = 8.dp,
     animateToNextTarget: Boolean = true,
+    advanceOnTargetTapOnly: Boolean = false,
     colors: ShowcaseLayoutDefaults.Colors = ShowcaseLayoutDefaults.colors(),
     content: @Composable ShowcaseScope.() -> Unit
 ) {
@@ -134,6 +138,11 @@ fun TargetShowcaseLayout(
 
             val animatedX = remember { Animatable(offset.x) }
             val animatedY = remember { Animatable(offset.y) }
+            // The tap handler lives in a pointerInput(Unit) that never restarts, so it would
+            // otherwise capture the first composition's (greeting) bounds. Track the current
+            // target's resting bounds in State so the hit-test always reads the live values.
+            val currentTargetTopLeft by rememberUpdatedState(offset)
+            val currentTargetSize by rememberUpdatedState(itemSize)
             val maxDimension =
                 max(maxHeight.value, maxWidth.value)
 
@@ -316,6 +325,23 @@ fun TargetShowcaseLayout(
                                 Level.VERBOSE,
                                 TAG + "tapped here $it"
                             )
+                            /** when enabled, only taps inside the target shape advance the showcase
+                             * (the greeting/initial screen always advances on any tap) */
+                            if (advanceOnTargetTapOnly && currentIndex != 0 && !isSingleGreeting &&
+                                !isTapInsideTarget(
+                                    it,
+                                    currentTargetTopLeft,
+                                    currentTargetSize,
+                                    targetShape,
+                                    TARGET_TAP_TOLERANCE_PX
+                                )
+                            ) {
+                                scope.showcaseEventListener?.onEvent(
+                                    Level.VERBOSE,
+                                    TAG + "tap outside target ignored at $it"
+                                )
+                                return@detectTapGestures
+                            }
                             if (showCasingItem) {
                                 val shrinkDuration = animationDuration
 
@@ -1127,7 +1153,7 @@ fun TargetShowcaseLayout(
     message = "isDarkLayout has been replaced by the colors parameter; pass a light overlay color instead.",
     replaceWith = ReplaceWith(
         "TargetShowcaseLayout(isShowcasing, initIndex, animationDuration, onFinish, greeting, " +
-                "lineThickness, targetShape, cornerRadius, animateToNextTarget, " +
+                "lineThickness, targetShape, cornerRadius, animateToNextTarget, false, " +
                 "ShowcaseLayoutDefaults.colors(overlayColor = if (isDarkLayout) Color.White.copy(alpha = 0.9f) else Color.Black.copy(alpha = 0.9f)), content)"
     )
 )