From b959983fb0c9c2a709e644842c0e1817aae43b14 Mon Sep 17 00:00:00 2001
From: garanj <garan@google.com>
Date: Sat, 16 Sep 2023 07:23:09 +0100
Subject: [PATCH] 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 | 39 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 39 insertions(+)

diff --git a/docs/compose-layout.md b/docs/compose-layout.md
index d09db74c09..b939f3da4b 100644
--- a/docs/compose-layout.md
+++ b/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