Adds docs for AmbientAware (#1681)

* Adds support for enabling or disabling always-on mode.

This is useful if different screens in the app may need or not need this behaviour, for example a workout screen vs an end-of-workout summary.

* Adds docs for AmbientAware

docs/compose-layout.md

@@ -74,6 +74,40 @@ Box(
 
 ![](fade_away.png){: loading=lazy width=70% align=center }
 
+## AmbientAware composable
+
+`AmbientAware` allows your UI to react to ambient mode changes. For more information on how Ambient
+mode and Always-on work on Wear OS, see the [developer guidance][always-on].
+
+You should place this composable high up in your design, as it alters the behavior of the Activity.
+
+```kotlin
+@Composable
+fun WearApp() {
+    AmbientAware { ambientStateUpdate ->
+        // App Content here
+    }
+}
+```
+
+If you need some screens to use always-on, and others not to, then you can use the additional
+argument supplied to `AmbientAware`.
+
+For example, in a workout app, it is desirable that the main  workout screen uses always-on, but the
+workout summary at the end does not. See the [`ExerciseClient`][exercise-client]
+guide and [samples][health-samples] for more information on building a workout app.
+
+```kotlin
+@Composable
+fun WearApp() {
+    // Hoist state here for your current screen logic
+
+    AmbientAware(isAlwaysOnScreen = currentScreen.useAlwaysOn) { ambientStateUpdate ->
+        // App Content here
+    }
+}
+```
+
 ## Download
 
 ```groovy
@@ -85,3 +119,8 @@ dependencies {
     implementation "com.google.android.horologist:horologist-compose-layout:<version>"
 }
 ```
+
+
+[always-on]: https://developer.android.com/training/wearables/views/always-on
+[exercise-client]: https://developer.android.com/training/wearables/health-services/active-data#work-with-data
+[health-samples]: https://github.com/android/health-samples