Wear Compose M3

Foundation components in androidx.wear.compose.foundation.*

Capability 4: Component guidance

Mandatory: Use this capability as a checklist against any component use. It provides more holistic guidance on how to use each component in practice, beyond the component syntax.

1. AppScaffold and ScreenScaffold

   • [ ] Use AppScaffold as the outer container, with ScreenScaffold children.
   • [ ] Use only ONE AppScaffold and any number of ScreenScaffold.

2. ScalingLazyColumn - Use TransformingLazyColumn instead.

3. TransformingLazyColumn - You will need the following imports:

   <br />

   import androidx.wear.compose.foundation.lazy.TransformingLazyColumn
   import androidx.wear.compose.foundation.lazy.TransformingLazyColumnDefaults
   import androidx.wear.compose.foundation.lazy.rememberTransformingLazyColumnState
   // ...
   import androidx.wear.compose.material3.lazy.rememberTransformationSpec
   import androidx.wear.compose.material3.lazy.transformedHeight
         

   <br />

   Canonical example:

   <br />

   val columnState = rememberTransformingLazyColumnState()
   val transformationSpec = rememberTransformationSpec()
   ScreenScaffold(
       scrollState = columnState
   ) { contentPadding ->
       TransformingLazyColumn(
           state = columnState,
           contentPadding = contentPadding
       ) {
           item {
               ListHeader(
                   modifier = Modifier
                       .fillMaxWidth()
                       .transformedHeight(this, transformationSpec)
                       .minimumVerticalContentPadding(ListHeaderDefaults.minimumTopListContentPadding),
                   transformation = SurfaceTransformation(transformationSpec)
               ) {
                   Text(text = "Header")
               }
           }
           // ... other items
           item {
               Button(
                   modifier = Modifier
                       .fillMaxWidth()
                       .transformedHeight(this, transformationSpec)
                       .minimumVerticalContentPadding(ButtonDefaults.minimumVerticalListContentPadding),
                   transformation = SurfaceTransformation(transformationSpec),
                   onClick = { /* ... */ },
                   icon = {
                       Icon(
                           imageVector = Icons.Default.Build,
                           contentDescription = "build",
                       )
                   },
               ) {
                   Text(
                       text = "Build",
                       maxLines = 1,
                       overflow = TextOverflow.Ellipsis,
                   )
               }
           }
       }
   }
        

   <br />

   • [ ] Use TransformingLazyColumn instead of ScalingLazyColumn.
   • [ ] You must pass the contentPadding parameter from ScreenScaffold to the TransformingLazyColumn.
   • [ ] Use the minimumVerticalContentPadding modifier to achieve required padding top and bottom.
     • This expects a value from defaults, such as ButtonDefaults, CardDefaults, `ListHeaderDefaults.
     • Note: This is a scoped modifier available within TransformingLazyColumnItemScope.
   • [ ] Ensure the list morphs and scales.
   • [ ] Use transformedHeight modifier.
   • [ ] Use transform = SurfaceTransform(...).
   • [ ] If configuring a list for snapping, use flingBehavior and rotaryScrollableBehavior together:

   <br />

   val columnState = rememberTransformingLazyColumnState()
   ScreenScaffold(scrollState = columnState) { contentPadding ->
       TransformingLazyColumn(
           state = columnState,
           flingBehavior = TransformingLazyColumnDefaults.snapFlingBehavior(columnState),
           rotaryScrollableBehavior = RotaryScrollableDefaults.snapBehavior(columnState)
       ) {
           // ...
           // ...
       }
   }
        

   <br />

4. ScreenScaffold

   • [ ] Guard the scrollIndicator with !LocalScrollCaptureInProgress.current.

5. EdgeButton

   • [ ] Do NOT use as the final item within a TransformingLazyColumn. Instead, use the slot in ScreenScaffold.
   • [ ] When used in a TransformingLazyColumn, add the required overscroll behavior:

   <br />

   val columnState = rememberTransformingLazyColumnState()
   ScreenScaffold(
       scrollState = columnState,
       edgeButton = {
           EdgeButton(
               onClick = { /* TODO */ },
               modifier = Modifier.scrollable(
                   columnState,
                   orientation = Orientation.Vertical,
                   reverseDirection = true,
                   // Apply overscroll to the EdgeButton for proper scrolling behavior.
                   overscrollEffect = rememberOverscrollEffect(),
               )
           ) {
               Text("More")
           }
       }
   ) { contentPadding ->
       TransformingLazyColumn(
           contentPadding = contentPadding,
           state = columnState,
       ) {
           // ...
           // ...
       }
   }
        

   <br />

6. Column

   • [ ] USE as a direct child of ScreenScaffold if the screen is will never scroll, even with the largest system font.
   • [ ] Use TransformingLazyColumn instead for all other cases.

7. Styles

   • [ ] Do NOT hard-code text sizes, use typography from MaterialTheme.
   • [ ] Do NOT hard-code colors, use colorScheme from MaterialTheme.

8. Use component defaults:

   • [ ] Components such as Button have a corresponding ButtonDefaults object.
   • [ ] Check for and use the *Defaults object for any component when working with padding and styling values, in preference to hard-coded values.

9. Use Wear specific previews:

   • [ ] WearPreviewDevices
   • [ ] WearPreviewFontScales

10. Ambient mode

    • [ ] Use LocalAmbientModeManager instead of AmbientLifecycleObserver.

11. Navigation

    • [ ] When adding navigation fresh, use Navigation3.
    • [ ] For Navigation3 in Wear OS, use SwipeDismissableSceneStrategy() from the Wear Compose compose-navigation3 library.

12. Comments

    • [ ] Where any Kotlin file has been modified, ensure that the existing comments are up to date and accurately reflect any changes to the implementation.

13. HorizontalPager or VerticalPager

    • [ ] Use the Composable hierarchy in this order: AppScaffold, HorizontalPagerScaffold, HorizontalPager, AnimatedPage, ScreenScaffold. Or similarly for VerticalPager.