First Commit

services/appnavstate/api/build.gradle.kts

@@ -0,0 +1,23 @@
+/*
+ * Copyright (c) 2025 Element Creations Ltd.
+ * Copyright 2022-2024 New Vector Ltd.
+ *
+ * SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial.
+ * Please see LICENSE files in the repository root for full details.
+ */
+
+plugins {
+    id("io.element.android-library")
+}
+
+android {
+    namespace = "io.element.android.services.appnavstate.api"
+}
+
+dependencies {
+    implementation(libs.coroutines.core)
+    implementation(libs.androidx.lifecycle.runtime)
+    implementation(libs.androidx.lifecycle.process)
+    implementation(libs.androidx.startup)
+    implementation(projects.libraries.matrix.api)
+}

services/appnavstate/api/src/main/kotlin/io/element/android/services/appnavstate/api/ActiveRoomsHolder.kt

@@ -0,0 +1,43 @@
+/*
+ * Copyright (c) 2025 Element Creations Ltd.
+ * Copyright 2025 New Vector Ltd.
+ *
+ * SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial.
+ * Please see LICENSE files in the repository root for full details.
+ */
+
+package io.element.android.services.appnavstate.api
+
+import io.element.android.libraries.matrix.api.core.RoomId
+import io.element.android.libraries.matrix.api.core.SessionId
+import io.element.android.libraries.matrix.api.room.JoinedRoom
+
+/**
+ * Holds the active rooms for a given session so they can be reused instead of instantiating new ones.
+ */
+interface ActiveRoomsHolder {
+    /**
+     * Adds a new held room for the given sessionId.
+     */
+    fun addRoom(room: JoinedRoom)
+
+    /**
+     * Returns the last room added for the given [sessionId] or null if no room was added.
+     */
+    fun getActiveRoom(sessionId: SessionId): JoinedRoom?
+
+    /**
+     * Returns an active room associated to the given [sessionId], with the given [roomId], or null if none match.
+     */
+    fun getActiveRoomMatching(sessionId: SessionId, roomId: RoomId): JoinedRoom?
+
+    /**
+     * Removes any room matching the provided [sessionId] and [roomId].
+     */
+    fun removeRoom(sessionId: SessionId, roomId: RoomId)
+
+    /**
+     * Clears all the rooms for the given sessionId.
+     */
+    fun clear(sessionId: SessionId)
+}

services/appnavstate/api/src/main/kotlin/io/element/android/services/appnavstate/api/AppForegroundStateService.kt

@@ -0,0 +1,56 @@
+/*
+ * Copyright (c) 2025 Element Creations Ltd.
+ * Copyright 2023-2025 New Vector Ltd.
+ *
+ * SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial.
+ * Please see LICENSE files in the repository root for full details.
+ */
+
+package io.element.android.services.appnavstate.api
+
+import kotlinx.coroutines.flow.StateFlow
+
+/**
+ * A service that tracks the foreground state of the app.
+ */
+interface AppForegroundStateService {
+    /**
+     * Any updates to the foreground state of the app will be emitted here.
+     */
+    val isInForeground: StateFlow<Boolean>
+
+    /**
+     * Updates to whether the app is active because an incoming ringing call is happening will be emitted here.
+     */
+    val hasRingingCall: StateFlow<Boolean>
+
+    /**
+     * Updates to whether the app is in an active call or not will be emitted here.
+     */
+    val isInCall: StateFlow<Boolean>
+
+    /**
+     * Updates to whether the app is syncing a notification event or not will be emitted here.
+     */
+    val isSyncingNotificationEvent: StateFlow<Boolean>
+
+    /**
+     * Start observing the foreground state.
+     */
+    fun startObservingForeground()
+
+    /**
+     * Update the in-call state.
+     */
+    fun updateIsInCallState(isInCall: Boolean)
+
+    /**
+     * Update the 'has ringing call' state.
+     */
+    fun updateHasRingingCall(hasRingingCall: Boolean)
+
+    /**
+     * Update the active state for the syncing notification event flow.
+     */
+    fun updateIsSyncingNotificationEvent(isSyncingNotificationEvent: Boolean)
+}

services/appnavstate/api/src/main/kotlin/io/element/android/services/appnavstate/api/AppNavigationState.kt

@@ -0,0 +1,17 @@
+/*
+ * Copyright (c) 2025 Element Creations Ltd.
+ * Copyright 2023-2025 New Vector Ltd.
+ *
+ * SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial.
+ * Please see LICENSE files in the repository root for full details.
+ */
+
+package io.element.android.services.appnavstate.api
+
+/**
+ * A wrapper for the current navigation state of the app, along with its foreground/background state.
+ */
+data class AppNavigationState(
+    val navigationState: NavigationState,
+    val isInForeground: Boolean,
+)

services/appnavstate/api/src/main/kotlin/io/element/android/services/appnavstate/api/AppNavigationStateService.kt

@@ -0,0 +1,34 @@
+/*
+ * Copyright (c) 2025 Element Creations Ltd.
+ * Copyright 2023-2025 New Vector Ltd.
+ *
+ * SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial.
+ * Please see LICENSE files in the repository root for full details.
+ */
+
+package io.element.android.services.appnavstate.api
+
+import io.element.android.libraries.matrix.api.core.RoomId
+import io.element.android.libraries.matrix.api.core.SessionId
+import io.element.android.libraries.matrix.api.core.SpaceId
+import io.element.android.libraries.matrix.api.core.ThreadId
+import kotlinx.coroutines.flow.StateFlow
+
+/**
+ * A service that tracks the navigation and foreground states of the app.
+ */
+interface AppNavigationStateService {
+    val appNavigationState: StateFlow<AppNavigationState>
+
+    fun onNavigateToSession(owner: String, sessionId: SessionId)
+    fun onLeavingSession(owner: String)
+
+    fun onNavigateToSpace(owner: String, spaceId: SpaceId)
+    fun onLeavingSpace(owner: String)
+
+    fun onNavigateToRoom(owner: String, roomId: RoomId)
+    fun onLeavingRoom(owner: String)
+
+    fun onNavigateToThread(owner: String, threadId: ThreadId)
+    fun onLeavingThread(owner: String)
+}

services/appnavstate/api/src/main/kotlin/io/element/android/services/appnavstate/api/IntentNavigationExtras.kt

@@ -0,0 +1,10 @@
+/*
+ * Copyright (c) 2025 Element Creations Ltd.
+ *
+ * SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial.
+ * Please see LICENSE files in the repository root for full details.
+ */
+
+package io.element.android.services.appnavstate.api
+
+const val ROOM_OPENED_FROM_NOTIFICATION = "opened_from_notification"

services/appnavstate/api/src/main/kotlin/io/element/android/services/appnavstate/api/NavigationState.kt

@@ -0,0 +1,50 @@
+/*
+ * Copyright (c) 2025 Element Creations Ltd.
+ * Copyright 2023-2025 New Vector Ltd.
+ *
+ * SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial.
+ * Please see LICENSE files in the repository root for full details.
+ */
+
+package io.element.android.services.appnavstate.api
+
+import io.element.android.libraries.matrix.api.core.RoomId
+import io.element.android.libraries.matrix.api.core.SessionId
+import io.element.android.libraries.matrix.api.core.SpaceId
+import io.element.android.libraries.matrix.api.core.ThreadId
+
+/**
+ * Can represent the current global app navigation state.
+ * @param owner mostly a Node identifier associated with the state.
+ * We are using the owner parameter to check when calling onLeaving methods is still using the same owner than his companion onNavigate.
+ * Why this is needed : for now we rely on lifecycle methods of the node, which are async.
+ * If you navigate quickly between nodes, onCreate of the new node is called before onDestroy of the previous node.
+ * So we assume if we don't get the same owner, we can skip the onLeaving action as we already replaced it.
+ */
+sealed class NavigationState(open val owner: String) {
+    data object Root : NavigationState("ROOT")
+
+    data class Session(
+        override val owner: String,
+        val sessionId: SessionId,
+    ) : NavigationState(owner)
+
+    data class Space(
+        override val owner: String,
+        // Can be fake value, if no space is selected
+        val spaceId: SpaceId,
+        val parentSession: Session,
+    ) : NavigationState(owner)
+
+    data class Room(
+        override val owner: String,
+        val roomId: RoomId,
+        val parentSpace: Space,
+    ) : NavigationState(owner)
+
+    data class Thread(
+        override val owner: String,
+        val threadId: ThreadId,
+        val parentRoom: Room,
+    ) : NavigationState(owner)
+}

services/appnavstate/api/src/main/kotlin/io/element/android/services/appnavstate/api/NavigationStateExtension.kt

@@ -0,0 +1,54 @@
+/*
+ * Copyright (c) 2025 Element Creations Ltd.
+ * Copyright 2023-2025 New Vector Ltd.
+ *
+ * SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial.
+ * Please see LICENSE files in the repository root for full details.
+ */
+
+package io.element.android.services.appnavstate.api
+
+import io.element.android.libraries.matrix.api.core.RoomId
+import io.element.android.libraries.matrix.api.core.SessionId
+import io.element.android.libraries.matrix.api.core.SpaceId
+import io.element.android.libraries.matrix.api.core.ThreadId
+
+fun NavigationState.currentSessionId(): SessionId? {
+    return when (this) {
+        NavigationState.Root -> null
+        is NavigationState.Session -> sessionId
+        is NavigationState.Space -> parentSession.sessionId
+        is NavigationState.Room -> parentSpace.parentSession.sessionId
+        is NavigationState.Thread -> parentRoom.parentSpace.parentSession.sessionId
+    }
+}
+
+fun NavigationState.currentSpaceId(): SpaceId? {
+    return when (this) {
+        NavigationState.Root -> null
+        is NavigationState.Session -> null
+        is NavigationState.Space -> spaceId
+        is NavigationState.Room -> parentSpace.spaceId
+        is NavigationState.Thread -> parentRoom.parentSpace.spaceId
+    }
+}
+
+fun NavigationState.currentRoomId(): RoomId? {
+    return when (this) {
+        NavigationState.Root -> null
+        is NavigationState.Session -> null
+        is NavigationState.Space -> null
+        is NavigationState.Room -> roomId
+        is NavigationState.Thread -> parentRoom.roomId
+    }
+}
+
+fun NavigationState.currentThreadId(): ThreadId? {
+    return when (this) {
+        NavigationState.Root -> null
+        is NavigationState.Session -> null
+        is NavigationState.Space -> null
+        is NavigationState.Room -> null
+        is NavigationState.Thread -> threadId
+    }
+}