Reveal: A Jetpack Compose Library for Engaging Reveal Effects

Introducing the Reveal Library for Jetpack Compose: Create Stunning Onboarding Experiences

Installation

dependencies {
    implementation("com.svenjacobs.reveal:reveal-core:$REVEAL_VERSION")
}

Demo App: Reveal Library in Action

Key Components: RevealOverlayEffect and Reveal Classes

RevealOverlayEffect

Reveal

Additional Components: Balloon and Arrow Classes

Balloon

Arrow

Conclusion

Reference

Source Code Explanation: Exploring Interesting Code from the Reveal Library

@Composable
public fun Reveal(
	onRevealableClick: (key: Key) -> Unit,
	onOverlayClick: (key: Key) -> Unit,
	modifier: Modifier = Modifier,
	revealState: RevealState = rememberRevealState(),
	overlayEffect: RevealOverlayEffect = DimRevealOverlayEffect(),
	overlayEffectAnimationSpec: AnimationSpec<Float> = tween(durationMillis = 500),
	overlayContent: @Composable RevealOverlayScope.(key: Key) -> Unit = {},
	content: @Composable RevealScope.() -> Unit,
) {
	val animatedOverlayAlpha by animateFloatAsState(
		targetValue = if (revealState.isVisible) 1.0f else 0.0f,
		animationSpec = overlayEffectAnimationSpec,
		finishedListener = { alpha ->
			if (alpha == 0.0f) {
				revealState.onHideAnimationFinished()
			}
		},
	)
	val layoutDirection = LocalLayoutDirection.current
	val density = LocalDensity.current

	Box(
		modifier = modifier,
	) {
		content(RevealScopeInstance(revealState))

		val currentRevealable = remember {
			derivedStateOf {
				revealState.currentRevealable?.toActual(
					density = density,
					layoutDirection = layoutDirection,
				)
			}
		}

		val previousRevealable = remember {
			derivedStateOf {
				revealState.previousRevealable?.toActual(
					density = density,
					layoutDirection = layoutDirection,
				)
			}
		}

		val rev by rememberUpdatedState(currentRevealable.value)

		val clickModifier = when {
			revealState.isVisible &amp;&amp; rev != null -> Modifier.pointerInput(Unit) {
				detectTapGestures(
					onPress = { offset ->
						rev?.key?.let(
							if (rev?.area?.contains(offset) == true) {
								onRevealableClick
							} else {
								onOverlayClick
							},
						)
					},
				)
			}
			else -> Modifier
		}

		if (animatedOverlayAlpha > 0.0f) {
			Fullscreen {
				overlayEffect.Overlay(
					revealState = revealState,
					currentRevealable = currentRevealable,
					previousRevealable = previousRevealable,
					modifier = clickModifier
						.semantics { testTag = "overlay" }
						.fillMaxSize()
						.alpha(animatedOverlayAlpha),
					content = overlayContent,
				)
			}
		}
	}
}

private fun Revealable.toActual(
	density: Density,
	layoutDirection: LayoutDirection,
): ActualRevealable = ActualRevealable(
	key = key,
	shape = shape,
	padding = padding,
	area = computeArea(
		density = density,
		layoutDirection = layoutDirection,
	),
)

@Stable
@Suppress("MemberVisibilityCanBePrivate")
public class RevealState internal constructor(
	visible: Boolean = false,
	private val restoreCurrentRevealableKey: Key? = null,
) {

	private val mutex = Mutex()
	private var didRestoreCurrentRevealable = false
	private var visible by mutableStateOf(visible)
	private val revealables = mutableStateMapOf<Key, Revealable>()
	internal var currentRevealable by mutableStateOf<Revealable?>(null)
		private set
	internal var previousRevealable by mutableStateOf<Revealable?>(null)
		private set

	public val isVisible: Boolean
		get() = visible

	public val currentRevealableKey: Key?
		get() = currentRevealable?.key

	public val previousRevealableKey: Key?
		get() = previousRevealable?.key

	public val revealableKeys: Set<Key>
		get() = revealables.keys

	public suspend fun reveal(key: Key) {
		require(revealables.containsKey(key)) { "Revealable with key \\"$key\\" not found" }
		mutex.withLock {
			previousRevealable = currentRevealable
			currentRevealable = revealables[key]
			visible = true
		}
	}

	public suspend fun hide() {
		mutex.withLock {
			visible = false
		}
	}

	public fun containsRevealable(key: Key): Boolean = revealableKeys.contains(key)

	internal fun onHideAnimationFinished() {
		currentRevealable = null
		previousRevealable = null
	}

	public fun putRevealable(revealable: Revealable) {
		revealables[revealable.key] = revealable

		if (!didRestoreCurrentRevealable &amp;&amp; restoreCurrentRevealableKey == revealable.key) {
			currentRevealable = revealable
			didRestoreCurrentRevealable = true
		}
	}

	public fun removeRevealable(key: Key) {
		revealables.remove(key)

		if (currentRevealableKey == key) {
			visible = false
		}

		if (previousRevealableKey == key) {
			previousRevealable = null
		}
	}

	internal companion object {

			save = {
				listOf(
					it.isVisible,
					it.currentRevealableKey?.let { key -> with(keySaver) { save(key) } },
				)
			},
			restore = {
				RevealState(
					visible = it[0] as Boolean,
					restoreCurrentRevealableKey = it[1]?.let { keySaveable ->
						keySaver.restore(keySaveable)
					},
				)
			},
		)
	}
}

@Composable
public fun rememberRevealState(keySaver: Saver<Key, Any> = autoSaver()): RevealState =
	rememberSaveable(saver = RevealState.newSaver(keySaver)) { RevealState() }

@Immutable
public data class Revealable(
	val key: Key,
	val shape: RevealShape,
	val padding: PaddingValues,
	val layout: Layout,
) {

	@Immutable
	public data class Layout(
		val offset: Offset,
		val size: Size,
	)
}

@Immutable
public data class ActualRevealable(
	val key: Key,
	val shape: RevealShape,
	val padding: PaddingValues,
	val area: Rect,
)

internal fun Revealable.computeArea(density: Density, layoutDirection: LayoutDirection): Rect =
	with(density) {
		val rect = Rect(
			left = layout.offset.x - padding.calculateLeftPadding(layoutDirection).toPx(),
			top = layout.offset.y - padding.calculateTopPadding().toPx(),
			right = layout.offset.x + padding.calculateRightPadding(layoutDirection).toPx() +
				layout.size.width,
			bottom = layout.offset.y + padding.calculateBottomPadding().toPx() +
				layout.size.height,
		)

		if (shape == RevealShape.Circle) {
			Rect(rect.center, rect.maxDimension / 2.0f)
		} else {
			rect
		}
	}

@Immutable
public interface RevealScope {

	public fun Modifier.revealable(
		key: Key,
		shape: RevealShape = RevealShape.RoundRect(4.dp),
		padding: PaddingValues = PaddingValues(8.dp),
	): Modifier

	public fun Modifier.revealable(
		vararg keys: Key,
		shape: RevealShape = RevealShape.RoundRect(4.dp),
		padding: PaddingValues = PaddingValues(8.dp),
	): Modifier

	public fun Modifier.revealable(
		keys: Iterable<Key>,
		shape: RevealShape = RevealShape.RoundRect(4.dp),
		padding: PaddingValues = PaddingValues(8.dp),
	): Modifier
}

internal class RevealScopeInstance(
	private val revealState: RevealState,
) : RevealScope {

	override fun Modifier.revealable(key: Key, shape: RevealShape, padding: PaddingValues): Modifier =
		revealable(
			keys = listOf(key),
			shape = shape,
			padding = padding,
		)

	override fun Modifier.revealable(
		vararg keys: Key,
		shape: RevealShape,
		padding: PaddingValues,
	): Modifier = revealable(
		keys = keys.toList(),
		shape = shape,
		padding = padding,
	)

	override fun Modifier.revealable(
		keys: Iterable<Key>,
		shape: RevealShape,
		padding: PaddingValues,
	): Modifier = this.then(
		Modifier
			.onGloballyPositioned { layoutCoordinates ->
				for (key in keys) {
					revealState.putRevealable(
						Revealable(
							key = key,
							shape = shape,
							padding = padding,
							layout = Revealable.Layout(
								offset = layoutCoordinates.positionInRoot(),
								size = layoutCoordinates.size.toSize(),
							),
						),
					)
				}
			}
			.composed {
				DisposableEffect(Unit) {
					onDispose {
						for (key in keys) {
							revealState.removeRevealable(key)
						}
					}
				}
				this
			},
	)
}

public typealias Key = Any

public interface RevealOverlayEffect {

	@Composable
	public fun Overlay(
		revealState: RevealState,
		currentRevealable: State<ActualRevealable?>,
		previousRevealable: State<ActualRevealable?>,
		modifier: Modifier,
		content: @Composable RevealOverlayScope.(key: Key) -> Unit,
	)
}

@Immutable
public class DimRevealOverlayEffect(
	private val color: Color = Color.Black.copy(alpha = 0.8f),
	private val contentAnimationSpec: AnimationSpec<Float> = tween(durationMillis = 500),
) : RevealOverlayEffect {
	@Composable
	override fun Overlay(
		revealState: RevealState,
		currentRevealable: State<ActualRevealable?>,
		previousRevealable: State<ActualRevealable?>,
		modifier: Modifier,
		content: @Composable RevealOverlayScope.(key: Key) -> Unit,
	) {
		val currentItemHolder = currentRevealable.value?.let {
			rememberDimItemHolder(
				revealable = it,
				fromState = Gone,
				toState = Visible,
				contentAnimationSpec = contentAnimationSpec,
			)
		}

		val prevItemHolder = previousRevealable.value?.let {
			rememberDimItemHolder(
				revealable = it,
				fromState = Visible,
				toState = Gone,
				contentAnimationSpec = contentAnimationSpec,
			)
		}

		val density = LocalDensity.current

		Box(
			modifier = modifier
				.graphicsLayer(alpha = 0.99f)
				.drawBehind {
					drawRect(color)
					prevItemHolder?.let { with(it) { drawCutout(density) } }
					currentItemHolder?.let { with(it) { drawCutout(density) } }
				},
		) {
			prevItemHolder?.let { with(it) { Container(content = content) } }
			currentItemHolder?.let { with(it) { Container(content = content) } }
		}
	}
}

@Stable
private class DimItemHolder(
	val revealable: ActualRevealable,
	val contentAlpha: State<Float>,
) {

	@Composable
	fun BoxScope.Container(
		modifier: Modifier = Modifier,
		content: @Composable RevealOverlayScope.(key: Key) -> Unit,
	) {
		if (contentAlpha.value == 0.0f) return

		Box(
			modifier = modifier
				.matchParentSize()
				.alpha(contentAlpha.value),
			content = {
				RevealOverlayScopeInstance(
					revealableRect = revealable.area.toIntRect(),
				).content(revealable.key)
			},
		)
	}

	fun DrawScope.drawCutout(density: Density) {
		val path = revealable.createShapePath(
			density = density,
			layoutDirection = layoutDirection,
		)

		drawPath(
			path,
			Color.Transparent.copy(alpha = 1.0f - contentAlpha.value),
			blendMode = BlendMode.DstIn,
		)
	}
}

private enum class DimItemState { Visible, Gone }

@Composable
private fun rememberDimItemHolder(
	revealable: ActualRevealable,
	fromState: DimItemState,
	toState: DimItemState,
	contentAnimationSpec: AnimationSpec<Float>,
): DimItemHolder = key(revealable.key) {
	val targetState = remember { mutableStateOf(fromState) }
	val contentAlpha = animateFloatAsState(
		targetValue = if (targetState.value == Visible) 1.0f else 0.0f,
		animationSpec = contentAnimationSpec,
	)

	LaunchedEffect(Unit) {
		targetState.value = toState
	}

	remember {
		DimItemHolder(
			revealable = revealable,
			contentAlpha = contentAlpha,
		)
	}
}

Source Code Explanation: Exploring Code from the Demo App

private enum class Keys { Fab, Explanation }

@Composable
@OptIn(ExperimentalMaterial3Api::class)
fun MainScreen(modifier: Modifier = Modifier) {
	val revealState = rememberRevealState()

	LaunchedEffect(Unit) {
		if (revealState.isVisible) return@LaunchedEffect
		delay(2.seconds)
		revealState.reveal(Keys.Fab)
	}

	DemoTheme {
		val scope = rememberCoroutineScope()

		Reveal(
			modifier = modifier,
			revealState = revealState,
			onRevealableClick = { key ->
				scope.launch {
					if (key == Keys.Fab) {
						revealState.reveal(Keys.Explanation)
					} else {
						revealState.hide()
					}
				}
			},
			onOverlayClick = { scope.launch { revealState.hide() } },
			overlayContent = { key -> RevealOverlayContent(key) },
		) {
			Scaffold(
				modifier = Modifier.fillMaxSize(),
				topBar = {
					CenterAlignedTopAppBar(
						title = { Text("Reveal Demo") },
					)
				},
				floatingActionButton = {
					FloatingActionButton(
						modifier = Modifier.revealable(
							key = Keys.Fab,
							shape = RevealShape.RoundRect(16.dp),
						),
						onClick = {
							scope.launch { revealState.reveal(Keys.Explanation) }
						},
					) {
						Icon(
							Icons.Filled.Add,
							contentDescription = null,
						)
					}
				},
			) { contentPadding ->
				Column(
					modifier = Modifier
						.fillMaxSize()
						.padding(contentPadding)
						.padding(horizontal = 16.dp),
					horizontalAlignment = Alignment.CenterHorizontally,
				) {
					Text(
						modifier = Modifier
							.padding(top = 16.dp)
							.revealable(
								key = Keys.Explanation,
							),
						text = "Reveal is a lightweight, simple reveal effect (also known as " +
							"coach mark or onboarding) library for Jetpack Compose.",
						style = MaterialTheme.typography.bodyLarge,
						textAlign = TextAlign.Justify,
					)
				}
			}
		}
	}
}

@Composable
private fun RevealOverlayScope.RevealOverlayContent(key: Key) {
	when (key) {
		Keys.Fab -> OverlayText(
			modifier = Modifier.align(
				horizontalArrangement = RevealOverlayArrangement.Start,
			),
			text = "Click button to get started",
			arrow = Arrow.end(),
		)
		Keys.Explanation -> OverlayText(
			modifier = Modifier.align(
				verticalArrangement = RevealOverlayArrangement.Bottom,
			),
			text = "Actually we already started. This was an example of the reveal effect.",
			arrow = Arrow.top(),
		)
	}
}

@Composable
private fun OverlayText(text: String, arrow: Arrow, modifier: Modifier = Modifier) {
	Balloon(
		modifier = modifier.padding(8.dp),
		arrow = arrow,
		backgroundColor = MaterialTheme.colorScheme.secondaryContainer,
		elevation = 2.dp,
	) {
		Text(
			modifier = Modifier.padding(8.dp),
			text = text,
			style = MaterialTheme.typography.labelLarge,
			textAlign = TextAlign.Center,
		)
	}
}

@Composable
@Preview(showBackground = true)
private fun MainScreenPreview() {
	DemoTheme {
		MainScreen()
	}
}