kalendar.state#

com.himanshoe.kalendar.state

Navigation state, selection state, and the clock. Each state class wraps a Compose scroll state and exposes it in date terms; each is created by a remember* factory rather than a constructor, so it survives configuration changes and is keyed on the things that should rebuild it.

import com.himanshoe.kalendar.state.rememberKalendarMonthState

Navigation state#

KalendarViewState#

@Stable
public class KalendarViewState

The paged views' state — a PagerState and a KalendarPager, presented as dates. Returned by rememberKalendarWeekState, rememberKalendarMonthState, rememberKalendarYearState and rememberKalendarScheduleState.

val state = rememberKalendarMonthState(initialDate = today)
val scope = rememberCoroutineScope()

Text("${state.visibleDate.month} ${state.visibleDate.year}")
KalendarMonth(selectedDate = today, state = state)
Button(onClick = { scope.launch { state.animateScrollTo(LocalDate(2026, 12, 25)) } }) {
    Text("Jump to December")
}

Note: there is deliberately no today property here. A clock-derived value stored on a @Stable object notifies nobody when the clock moves on, so it would go stale at midnight and no recomposition would ever be scheduled to fix it. Read it in composition instead: rememberKalendarToday(state.timeSource).

KalendarTimelineState#

@Stable
public class KalendarTimelineState

KalendarTimeline's state — a LazyListState and a KalendarPager. A timeline scrolls continuously, so it has no pages and therefore no canScrollBackward/Forward and no per-page animation.

val state = rememberKalendarTimelineState(initialDate = today)
KalendarTimeline(selectedDate = today, state = state)

Warning: minDate/maxDate bound the buttons, not the swipe. On the paged views they disable the header's arrows and clamp animateScrollTo, but a swipe can carry you past them. On KalendarTimeline the bounds do clamp the scroll itself, because the list is built with a finite item count.

The factories#

All five take the same parameters, except rememberKalendarScheduleState, which has no startDayOfWeek — a single day has no week columns to align.

val state = rememberKalendarMonthState(
    initialDate = today,
    startDayOfWeek = DayOfWeek.SUNDAY,
    minDate = LocalDate(2020, 1, 1),
    maxDate = LocalDate(2030, 12, 31),
)

initialDate defaults to today as read through timeSource, so wrapping a screen in ProvideKalendarTimeSource(fixed) { … } pins every view's idea of the current date at once.

Selection state#

KalendarSelectionState#

@Stable
public class KalendarSelectionState

A rememberSaveable-backed holder over KalendarSelection. It implements the tap behaviour of one KalendarSelectionMode and survives configuration changes and process death — including a half-finished range.

rememberKalendarSelectionState#

@Composable
public fun rememberKalendarSelectionState(
    mode: KalendarSelectionMode = KalendarSelectionMode.Single,
    initialSelection: Set<LocalDate> = emptySet(),
): KalendarSelectionState

val selection = rememberKalendarSelectionState(mode = KalendarSelectionMode.Range)

KalendarMonth(
    selectedDate = today,
    selectedDates = selection.selectedDates,
    onDateClick = { date, _ -> selection.onDateClick(date) },
    onDateRangeSelect = selection::onRangeDrag,
    onDateRangeSelectEnd = selection::onRangeDragEnd,
)

For anything the three modes do not cover — a minimum range length, disallowed end dates — hold the Set<LocalDate> yourself, or reduce a KalendarSelection directly.

The clock#

Every view, state factory and now-indicator reads "today" through a KalendarTimeSource rather than calling Clock.System.

ProvideKalendarTimeSource#

@Composable
public fun ProvideKalendarTimeSource(
    timeSource: KalendarTimeSource,
    content: @Composable () -> Unit,
)

Provides a time source to every view inside. The single injection point — a view's state, its initialDate default, and its now-indicator all end up reading the same clock.

val fixed = remember {
    KalendarTimeSource(
        timeZone = TimeZone.UTC,
        clock = object : Clock {
            override fun now(): Instant = Instant.parse("2026-03-10T10:20:00Z")
        },
    )
}

ProvideKalendarTimeSource(fixed) {
    KalendarMonth(selectedDate = LocalDate(2026, 3, 12))
}

Every picture on this documentation site is generated this way.

rememberKalendarTimeSource#

@Composable
public fun rememberKalendarTimeSource(): KalendarTimeSource

The ambient time source, or a composition-scoped default when nothing provided one.

val timeSource = rememberKalendarTimeSource()

rememberKalendarToday#

@Composable
public fun rememberKalendarToday(
    timeSource: KalendarTimeSource = rememberKalendarTimeSource(),
): LocalDate

Today's date, re-read when the day changes — so a calendar left open overnight highlights the new day instead of yesterday's.

val today = rememberKalendarToday(state.timeSource)

rememberKalendarNow#

@Composable
public fun rememberKalendarNow(
    timeSource: KalendarTimeSource = rememberKalendarTimeSource(),
    tick: Duration = 1.minutes,
): LocalDateTime

The current date and time, re-read every tick. This is what a now-indicator is positioned from.

val now = rememberKalendarNow(tick = 30.seconds)

Warning: this recomposes its caller every tick. The built-in grids instead hold the reading as a State and read it inside Modifier.offset { }, so a minute passing re-places one line rather than recomposing the indicator, its slot content, and everything above the read. Prefer that shape if you are building your own hour grid.