API design: Child Pages

[arkivanov]

Here is a tentative proposal of an API for Child Pages, in scope of the request in Discussions.

Decompose core

sealed class ChildPages<out C : Any, out T : Any> {

    abstract val items: List<Child<C, T>>
    abstract val selectedIndex: Int?

    object Empty : ChildPages<Nothing, Nothing>() {
        override val items: List<Child<Nothing, Nothing>> = emptyList()
        override val selectedIndex: Int? = null
    }

    data class NotEmpty<out C : Any, out T : Any>(
        override val items: List<Child<C, T>>,
        override val selectedIndex: Int,
    ) : ChildPages<C, T>()
}

data class Pages<out C : Any>(
    val items: List<C>,
    val selectedIndex: Int?,
) {
    constructor() : this(items = emptyList(), selectedIndex = null)
}

interface PagesNavigationSource<C : Any> : NavigationSource<PagesNavigationSource.Event<C>> {
    class Event<C : Any>(
        val transformer: (Pages<C>) -> Pages<C>,
        val onComplete: (newPages: Pages<C>, oldPages: Pages<C>) -> Unit = { _, _ -> },
    )
}

interface PagesNavigator<C : Any> {
    fun navigate(
        transformer: (Pages<C>) -> Pages<C>,
        onComplete: (newPages: Pages<C>, oldPages: Pages<C>) -> Unit,
    )
}

interface PagesNavigation<C : Any> : PagesNavigator<C>, PagesNavigationSource<C>

fun <C : Any> PagesNavigation(): PagesNavigation<C>

inline fun <reified C : Parcelable, T : Any> ComponentContext.childPages(
    source: PagesNavigationSource<C>,
    noinline initialPages: () -> Pages<C>,
    key: String = "DefaultChildPager",
    createdDelta: Int = 1, // Keeps the specified amount of components around the selected component created and stopped 
    persistent: Boolean = true,
    handleBackButton: Boolean = false, // Selects the previous component on back button press
    noinline childFactory: (configuration: C, ComponentContext) -> T,
): Value<ChildPages<C, T>>

fun <C : Any> PagesNavigator<C>.navigate(transformer: (Pages<C>) -> Pages<C>)
fun <C : Any> PagesNavigator<C>.selectNext()
fun <C : Any> PagesNavigator<C>.selectPrev()
fun <C : Any> PagesNavigator<C>.selectFirst()
fun <C : Any> PagesNavigator<C>.selectLast()
fun <C : Any> PagesNavigator<C>.select(index: Int)
fun <C : Any> PagesNavigator<C>.clear()

Compose extensions

@Composable
fun <T : Any> Pages(
    pages: Value<ChildPages<*, T>>,
    onPageSelected: (index: Int) -> Unit,
    modifier: Modifier = Modifier,
    scrollAnimation: PagesScrollAnimation = PagesScrollAnimation.Disabled,
    pager: Pager = defaultHorizontalPager(),
    pageContent: @Composable (index: Int, page: T) -> Unit,
)

typealias Pager =
    @Composable (
        pageCount: Int,
        Modifier,
        PagerState,
        key: (index: Int) -> Any,
        pageContent: @Composable (index: Int) -> Unit,
    ) -> Unit

sealed interface PagesScrollAnimation {
    object Disabled : PagesScrollAnimation
    object Default : PagesScrollAnimation
    class Custom(val spec: AnimationSpec<Float>) : PagesScrollAnimation
}

fun defaultHorizontalPager(): Pager =
    { pageCount, modifier, state, key, pageContent ->
        HorizontalPager(
            pageCount = pageCount,
            modifier = modifier,
            state = state,
            key = key,
            pageContent = pageContent,
        )
    }

fun defaultVerticalPager(): Pager =
    { pageCount, modifier, state, key, pageContent ->
        VerticalPager(
            pageCount = pageCount,
            modifier = modifier,
            state = state,
            key = key,
            pageContent = pageContent,
        )
    }

Usage example

Components

interface PageComponent {
    val data: String
}

class DefaultPageComponent(
    componentContext: ComponentContext,
    override val data: String,
) : PageComponent

interface PagesComponent {

    val pages: Value<ChildPages<*, PageComponent>>

    fun onPageSelected(index: Int)
}


class DefaultPagesComponent(componentContext: ComponentContext) : PagesComponent, ComponentContext by componentContext {

    private val navigation = PagesNavigation<PageConfig>()

    override val pages: Value<ChildPages<*, PageComponent>> =
        childPages(
            source = navigation,
            initialPages = {
                Pages(
                    items = List(20) { PageConfig(data = "Page ${it + 1}") },
                    selectedIndex = 0,
                )
            },
            handleBackButton = true,
            childFactory = ::childPage,
        )

    private fun childPage(config: PageConfig, componentContext: ComponentContext): PageComponent =
        DefaultPageComponent(componentContext = componentContext, data = config.data)

    override fun onPageSelected(index: Int) {
        navigation.select(index = index)
    }

    @Parcelize
    private data class PageConfig(
        val data: String,
    ) : Parcelable
}

Compose UI

@Composable
fun PagesContent(component: PagesComponent, modifier: Modifier = Modifier) {
    Pages(
        pages = component.pages,
        onPageSelected = component::onPageSelected,
        modifier = modifier,
        scrollAnimation = PagesScrollAnimation.Default,
    ) { _, page ->
        PageContent(component = page)
    }
}

Custom pager

@Composable
fun PagesContent(component: PagesComponent, modifier: Modifier = Modifier) {
    Pages(
        pages = component.pages,
        onPageSelected = component::onPageSelected,
        modifier = modifier,
        scrollAnimation = PagesScrollAnimation.Default,
        pager = { pageCount, pagerModifier, state, key, pageContent ->
            HorizontalPager(
                pageCount = pageCount,
                modifier = pagerModifier,
                state = state,
                contentPadding = PaddingValues(16.dp),
                key = key,
                pageContent = pageContent,
            )
        },
    ) { _, page ->
        PageContent(component = page)
    }
}

[arkivanov]

An experimental version has been released in 2.0.0-beta-01.