Rename 'article' functions and variables to use 'post' instead. Update KDocs and README

Author: bsagmoe

JetNews/README.md

@@ -15,23 +15,28 @@ project from Android Studio following the steps
 
 ## Features
 
-This sample contains three screens: a list of articles, a detail page for articles, and a page to
-subscribe to topics of interest. The navigation from the the list of articles to the interests
+This sample contains three screens: a list of posts, a detail page for a post, and a page to
+subscribe to topics of interest. The navigation from the list of posts to the interests
 screen uses a navigation drawer.
 
 ### App scaffolding
 
 Package [`com.example.jetnews.ui`][1]
 
-[`JetnewsApp.kt`][2] arranges the different screens in the `NavDrawerLayout`. 
+[`JetnewsApp.kt`][2] sets up the app's navigation state and the modal drawer used for navigation
+on smaller windows.
 
-[`JetnewsNavGraph.kt`][3] configures the navigation routes and actions in the app. 
+[`JetnewsNavDisplay.kt`][3] displays the primary content of the app: the list of posts, the
+posts themselves, and the interests page. It uses a list-detail scene strategy to adaptively
+display more or less content depending on the window size.
+
+<img src="screenshots/jetnews_all_screens.png" alt="Screenshot">
 
 [1]: app/src/main/java/com/example/jetnews/ui
 [2]: app/src/main/java/com/example/jetnews/ui/JetnewsApp.kt
-[3]: app/src/main/java/com/example/jetnews/ui/JetnewsNavGraph.kt
+[3]: app/src/main/java/com/example/jetnews/ui/JetnewsNavDisplay.kt
 
-### Main article list
+### Main post list
 
 Package [`com.example.jetnews.ui.home`][4]
 
@@ -47,14 +52,14 @@ See how to:
 
 [4]: app/src/main/java/com/example/jetnews/ui/home
 
-### Article detail
+### Post detail
 
-Package [`com.example.jetnews.ui.article`][5]
+Package [`com.example.jetnews.ui.post`][5]
 
 This screen dives into the Text API, showing how to use different fonts than the ones defined in
 [`Typography`][6]. It also adds a bottom app bar, with custom actions.
 
-[5]: app/src/main/java/com/example/jetnews/ui/article
+[5]: app/src/main/java/com/example/jetnews/ui/post
 [6]: app/src/main/java/com/example/jetnews/ui/theme/Type.kt
 
 ### Interests screen
@@ -99,20 +104,6 @@ UI tests can be run on device/emulators or on JVM with Robolectric.
 * To run Instrumented tests use the "Instrumented tests" run configuration or run the `./gradlew connectedCheck` command.
 * To run tests with Robolectric use the "Robolectric tests" run configuration or run the `./gradlew testDebug` command.
 
-## Jetnews for every screen
-
-<img src="screenshots/jetnews_all_screens.png" alt="Screenshot">
-
-We recently updated Jetnews to enhance its behavior across all mobile devices, both big and small.
-Jetnews already had support for “traditional” mobile screens, so it was tempting to describe all of
-our changes as “adding large screen support.” While that is true, it misses the point of having
-adaptive UI. For example, if your app is running in split screen mode on a tablet, it shouldn't try
-to display “tablet UI” unless it actually has enough space for it. With all of these changes,
-Jetnews is working better than ever on large screens, but also on small screens too.
-
-Check out the blog post that explains all the changes in more details:
-https://medium.com/androiddevelopers/jetnews-for-every-screen-4d8e7927752
-
 ## License
 
 ```

JetNews/app/src/androidTest/java/com/example/jetnews/JetnewsTests.kt

@@ -53,7 +53,7 @@ class JetnewsTests {
     }
 
     @Test
-    fun app_opensArticle() {
+    fun app_opensPost() {
         composeTestRule.onAllNodes(hasText(manuel.name, substring = true))[0]
             .performScrollTo()
             .performClick()

JetNews/app/src/main/java/com/example/jetnews/ui/home/HomeRoute.kt

@@ -30,11 +30,13 @@ import androidx.compose.runtime.getValue
 import androidx.compose.runtime.remember
 import androidx.compose.ui.Alignment
 import androidx.compose.ui.Modifier
+import androidx.compose.ui.res.stringResource
 import androidx.compose.ui.unit.dp
 import androidx.lifecycle.compose.collectAsStateWithLifecycle
 import androidx.lifecycle.viewmodel.compose.viewModel
 import androidx.navigation3.runtime.EntryProviderScope
 import androidx.navigation3.runtime.NavKey
+import com.example.jetnews.R
 import com.example.jetnews.data.posts.PostsRepository
 import com.example.jetnews.ui.navigation.ListDetailScene
 import kotlinx.serialization.Serializable
@@ -56,7 +58,7 @@ fun EntryProviderScope<NavKey>.homeEntry(
                     Surface(modifier = Modifier.fillMaxSize()) {
                         Box(contentAlignment = Alignment.Center) {
                             Text(
-                                "Select an article",
+                                stringResource(R.string.home_detail_placeholder),
                                 style = MaterialTheme.typography.labelLarge,
                             )
                         }
@@ -85,6 +87,7 @@ fun EntryProviderScope<NavKey>.homeEntry(
  * @param homeViewModel ViewModel that handles the business logic of this screen
  * @param isExpandedScreen (state) whether the screen is expanded
  * @param openDrawer (event) request opening the app drawer
+ * @param navigateToPost (event) request navigation to Post screen
  * @param snackbarHostState (state) state for the [Scaffold] component on this screen
  */
 @Composable

JetNews/app/src/main/java/com/example/jetnews/ui/home/HomeScreens.kt

@@ -93,7 +93,7 @@ import com.example.jetnews.ui.theme.JetnewsTheme
 import kotlinx.coroutines.runBlocking
 
 /**
- * The home screen displaying just the article feed.
+ * The home screen displaying just the post feed.
  */
 @Composable
 fun HomeFeedScreen(
@@ -123,7 +123,7 @@ fun HomeFeedScreen(
             postsFeed = hasPostsUiState.postsFeed,
             favorites = hasPostsUiState.favorites,
             showExpandedSearch = !showTopAppBar,
-            onArticleTapped = onSelectPost,
+            onPostTapped = onSelectPost,
             onToggleFavorite = onToggleFavorite,
             contentPadding = contentPadding,
             modifier = contentModifier,
@@ -289,18 +289,25 @@ private fun LoadingContent(
 /**
  * Display a feed of posts.
  *
- * When a post is clicked on, [onArticleTapped] will be called.
+ * When a post is clicked on, [onPostTapped] will be called.
  *
  * @param postsFeed (state) the feed to display
- * @param onArticleTapped (event) request navigation to Article screen
+ * @param favorites (state) a set of favorite posts
+ * @param showExpandedSearch (state) whether the expanded search is shown
+ * @param onPostTapped (event) request navigation to Post screen
+ * @param onToggleFavorite (event) request that this post toggle its favorite state
  * @param modifier modifier for the root element
+ * @param contentPadding the padding to apply to the content
+ * @param state the state object to be used to control or observe the list's state
+ * @param searchInput (state) the search input
+ * @param onSearchInputChanged (event) request that the search input changed
  */
 @Composable
 private fun PostList(
     postsFeed: PostsFeed,
     favorites: Set<String>,
     showExpandedSearch: Boolean,
-    onArticleTapped: (postId: String) -> Unit,
+    onPostTapped: (postId: String) -> Unit,
     onToggleFavorite: (String) -> Unit,
     modifier: Modifier = Modifier,
     contentPadding: PaddingValues = PaddingValues(0.dp),
@@ -322,12 +329,12 @@ private fun PostList(
                 )
             }
         }
-        item { PostListTopSection(postsFeed.highlightedPost, onArticleTapped) }
+        item { PostListTopSection(postsFeed.highlightedPost, onPostTapped) }
         if (postsFeed.recommendedPosts.isNotEmpty()) {
             item {
                 PostListSimpleSection(
                     postsFeed.recommendedPosts,
-                    onArticleTapped,
+                    onPostTapped,
                     favorites,
                     onToggleFavorite,
                 )
@@ -336,12 +343,12 @@ private fun PostList(
         if (postsFeed.popularPosts.isNotEmpty() && !showExpandedSearch) {
             item {
                 PostListPopularSection(
-                    postsFeed.popularPosts, onArticleTapped,
+                    postsFeed.popularPosts, onPostTapped,
                 )
             }
         }
         if (postsFeed.recentPosts.isNotEmpty()) {
-            item { PostListHistorySection(postsFeed.recentPosts, onArticleTapped) }
+            item { PostListHistorySection(postsFeed.recentPosts, onPostTapped) }
         }
     }
 }
@@ -364,18 +371,18 @@ private fun FullScreenLoading() {
  * Top section of [PostList]
  *
  * @param post (state) highlighted post to display
- * @param navigateToArticle (event) request navigation to Article screen
+ * @param navigateToPost (event) request navigation to Post screen
  */
 @Composable
-private fun PostListTopSection(post: Post, navigateToArticle: (String) -> Unit) {
+private fun PostListTopSection(post: Post, navigateToPost: (String) -> Unit) {
     Text(
         modifier = Modifier.padding(start = 16.dp, top = 16.dp, end = 16.dp),
         text = stringResource(id = R.string.home_top_section_title),
         style = MaterialTheme.typography.titleMedium,
     )
     PostCardTop(
         post = post,
-        modifier = Modifier.clickable(onClick = { navigateToArticle(post.id) }),
+        modifier = Modifier.clickable(onClick = { navigateToPost(post.id) }),
     )
     PostListDivider()
 }
@@ -384,20 +391,22 @@ private fun PostListTopSection(post: Post, navigateToArticle: (String) -> Unit)
  * Full-width list items for [PostList]
  *
  * @param posts (state) to display
- * @param navigateToArticle (event) request navigation to Article screen
+ * @param navigateToPost (event) request navigation to Post screen
+ * @param favorites (state) a set of favorite posts
+ * @param onToggleFavorite (event) request that this post toggle its favorite state
  */
 @Composable
 private fun PostListSimpleSection(
     posts: List<Post>,
-    navigateToArticle: (String) -> Unit,
+    navigateToPost: (String) -> Unit,
     favorites: Set<String>,
     onToggleFavorite: (String) -> Unit,
 ) {
     Column {
         posts.forEach { post ->
             PostCardSimple(
                 post = post,
-                navigateToArticle = navigateToArticle,
+                navigateToPost = navigateToPost,
                 isFavorite = favorites.contains(post.id),
                 onToggleFavorite = { onToggleFavorite(post.id) },
             )
@@ -410,10 +419,10 @@ private fun PostListSimpleSection(
  * Horizontal scrolling cards for [PostList]
  *
  * @param posts (state) to display
- * @param navigateToArticle (event) request navigation to Article screen
+ * @param navigateToPost (event) request navigation to Post screen
  */
 @Composable
-private fun PostListPopularSection(posts: List<Post>, navigateToArticle: (String) -> Unit) {
+private fun PostListPopularSection(posts: List<Post>, navigateToPost: (String) -> Unit) {
     Column {
         Text(
             modifier = Modifier.padding(16.dp),
@@ -430,7 +439,7 @@ private fun PostListPopularSection(posts: List<Post>, navigateToArticle: (String
             for (post in posts) {
                 PostCardPopular(
                     post,
-                    navigateToArticle,
+                    navigateToPost,
                 )
             }
         }
@@ -443,13 +452,13 @@ private fun PostListPopularSection(posts: List<Post>, navigateToArticle: (String
  * Full-width list items that display "based on your history" for [PostList]
  *
  * @param posts (state) to display
- * @param navigateToArticle (event) request navigation to Article screen
+ * @param navigateToPost (event) request navigation to Post screen
  */
 @Composable
-private fun PostListHistorySection(posts: List<Post>, navigateToArticle: (String) -> Unit) {
+private fun PostListHistorySection(posts: List<Post>, navigateToPost: (String) -> Unit) {
     Column {
         posts.forEach { post ->
-            PostCardHistory(post, navigateToArticle)
+            PostCardHistory(post, navigateToPost)
             PostListDivider()
         }
     }

JetNews/app/src/main/java/com/example/jetnews/ui/home/PostCardYourNetwork.kt

@@ -51,9 +51,9 @@ import com.example.jetnews.ui.theme.JetnewsTheme
 
 @OptIn(ExperimentalMaterial3Api::class)
 @Composable
-fun PostCardPopular(post: Post, navigateToArticle: (String) -> Unit, modifier: Modifier = Modifier) {
+fun PostCardPopular(post: Post, navigateToPost: (String) -> Unit, modifier: Modifier = Modifier) {
     Card(
-        onClick = { navigateToArticle(post.id) },
+        onClick = { navigateToPost(post.id) },
         shape = MaterialTheme.shapes.medium,
         modifier = modifier
             .width(280.dp),

JetNews/app/src/main/java/com/example/jetnews/ui/home/PostCards.kt

@@ -87,11 +87,11 @@ fun PostTitle(post: Post) {
 }
 
 @Composable
-fun PostCardSimple(post: Post, navigateToArticle: (String) -> Unit, isFavorite: Boolean, onToggleFavorite: () -> Unit) {
+fun PostCardSimple(post: Post, navigateToPost: (String) -> Unit, isFavorite: Boolean, onToggleFavorite: () -> Unit) {
     val bookmarkAction = stringResource(if (isFavorite) R.string.unbookmark else R.string.bookmark)
     Row(
         modifier = Modifier
-            .clickable(onClick = { navigateToArticle(post.id) })
+            .clickable(onClick = { navigateToPost(post.id) })
             .semantics {
                 // By defining a custom action, we tell accessibility services that this whole
                 // composable has an action attached to it. The accessibility service can choose
@@ -128,12 +128,12 @@ fun PostCardSimple(post: Post, navigateToArticle: (String) -> Unit, isFavorite:
 }
 
 @Composable
-fun PostCardHistory(post: Post, navigateToArticle: (String) -> Unit) {
+fun PostCardHistory(post: Post, navigateToPost: (String) -> Unit) {
     var openDialog by remember { mutableStateOf(false) }
 
     Row(
         Modifier
-            .clickable(onClick = { navigateToArticle(post.id) }),
+            .clickable(onClick = { navigateToPost(post.id) }),
     ) {
         PostImage(
             post = post,

…xample/jetnews/ui/article/PostContent.kt …m/example/jetnews/ui/post/PostContent.ktJetNews/app/src/main/java/com/example/jetnews/ui/article/PostContent.kt renamed to JetNews/app/src/main/java/com/example/jetnews/ui/post/PostContent.kt JetNews/app/src/main/java/com/example/jetnews/ui/article/PostContent.kt renamed to JetNews/app/src/main/java/com/example/jetnews/ui/post/PostContent.kt

@@ -14,7 +14,7 @@
  * limitations under the License.
  */
 
-package com.example.jetnews.ui.article
+package com.example.jetnews.ui.post
 
 import android.content.res.Configuration.UI_MODE_NIGHT_YES
 import androidx.compose.foundation.Image
@@ -146,7 +146,7 @@ private fun PostMetadata(metadata: Metadata, modifier: Modifier = Modifier) {
 
             Text(
                 text = stringResource(
-                    id = R.string.article_post_min_read,
+                    id = R.string.post_min_read,
                     metadata.date, metadata.readTimeMinutes,
                 ),
                 style = MaterialTheme.typography.bodySmall,

JetNews/app/src/main/java/com/example/jetnews/ui/post/PostRoute.kt

@@ -35,7 +35,6 @@ import androidx.lifecycle.viewmodel.compose.viewModel
 import androidx.navigation3.runtime.EntryProviderScope
 import androidx.navigation3.runtime.NavKey
 import com.example.jetnews.data.posts.PostsRepository
-import com.example.jetnews.ui.article.ArticleScreen
 import com.example.jetnews.ui.home.HomeKey
 import com.example.jetnews.ui.navigation.DeepLinkKey
 import com.example.jetnews.ui.navigation.ListDetailScene
@@ -106,7 +105,7 @@ fun PostRoute(
                     }
             }
 
-            ArticleScreen(
+            PostScreen(
                 post = post,
                 isExpandedScreen = isExpandedScreen,
                 onBack = onBack,