Merge branch 'main' into z/stateInTabs

slackhq · Mar 24, 2024 · 848ca4e · 848ca4e
2 parents 924ecab + 98410c0
commit 848ca4e
Show file tree

Hide file tree

Showing 169 changed files with 13,159 additions and 6,423 deletions.
diff --git a/.github/workflows/benchmark.yml b/.github/workflows/benchmark.yml
@@ -40,13 +40,12 @@ jobs:
           distribution: 'zulu'
           java-version: '21'
 
+      - name: Setup Gradle
+        uses: gradle/actions/setup-gradle@v3
+
       - name: Build benchmark
         id: gradle
-        uses: gradle/gradle-build-action@v2
-        with:
-          arguments: ':samples:star:apk:assembleBenchmarkRelease :samples:star:benchmark:compileBenchmarkReleaseSources'
-          gradle-home-cache-cleanup: true
-          cache-read-only: false
+        run: ./gradlew :samples:star:apk:assembleBenchmarkRelease :samples:star:benchmark:compileBenchmarkReleaseSources
 
       - name: AVD cache
         uses: actions/cache@v4

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -31,11 +31,8 @@ jobs:
           distribution: 'zulu'
           java-version: '21'
 
-      - name: Setup Gradle cache
-        uses: gradle/gradle-build-action@v2
-        with:
-          gradle-home-cache-cleanup: true
-          cache-read-only: false
+      - name: Setup Gradle
+        uses: gradle/actions/setup-gradle@v3
 
       - name: Build and run checks
         id: gradle-build
@@ -115,11 +112,8 @@ jobs:
         with:
           xcode-version: '15.2'
 
-      - name: Setup Gradle cache
-        uses: gradle/gradle-build-action@v2
-        with:
-          gradle-home-cache-cleanup: true
-          cache-read-only: false
+      - name: Setup Gradle
+        uses: gradle/actions/setup-gradle@v3
 
       - run: brew install swiftlint
 
@@ -152,13 +146,12 @@ jobs:
           distribution: 'zulu'
           java-version: '21'
 
+      - name: Setup Gradle
+        uses: gradle/actions/setup-gradle@v3
+
       - name: Verify Snapshots
         id: gradle-snapshots
-        uses: gradle/gradle-build-action@v2
-        with:
-          arguments: verifyRoborazzi
-          gradle-home-cache-cleanup: true
-          cache-read-only: false
+        run: ./gradlew verifyRoborazzi
 
       - name: (Fail-only) Upload reports
         if: failure()
@@ -184,11 +177,8 @@ jobs:
           distribution: 'zulu'
           java-version: '21'
 
-      - name: Setup Gradle cache
-        uses: gradle/gradle-build-action@v2
-        with:
-          gradle-home-cache-cleanup: true
-          cache-read-only: false
+      - name: Setup Gradle
+        uses: gradle/actions/setup-gradle@v3
 
       - name: Publish snapshot (main branch only)
         run: ./gradlew publish -PmavenCentralUsername=${{ secrets.SONATYPEUSERNAME }} -PmavenCentralPassword=${{ secrets.SONATYPEPASSWORD }} --no-configuration-cache
diff --git a/.github/workflows/mkdocs-requirements.txt b/.github/workflows/mkdocs-requirements.txt
@@ -1,17 +1,17 @@
 click==8.1.7
-future==0.18.3
+future==1.0.0
 Jinja2==3.1.3
 livereload==2.6.3
 lunr==0.7.0.post1
-Markdown==3.5.2
-MarkupSafe==2.1.4
+Markdown==3.6
+MarkupSafe==2.1.5
 mkdocs==1.5.3
 mkdocs-macros-plugin==1.0.5
-mkdocs-material==9.5.6
+mkdocs-material==9.5.15
 mkdocs-material-extensions==1.3.1
 Pygments==2.17.2
-pymdown-extensions==10.7
-python-dateutil==2.8.2
+pymdown-extensions==10.7.1
+python-dateutil==2.9.0.post0
 PyYAML==6.0.1
 repackage==0.7.3
 six==1.16.0

diff --git a/.github/workflows/update-baseline-profiles.yml b/.github/workflows/update-baseline-profiles.yml
@@ -33,11 +33,8 @@ jobs:
             sudo udevadm control --reload-rules
             sudo udevadm trigger --name-match=kvm
 
-      - name: Set up Gradle
-        uses: gradle/gradle-build-action@v2
-        with:
-          gradle-home-cache-cleanup: true
-          cache-read-only: false
+      - name: Setup Gradle
+        uses: gradle/actions/setup-gradle@v3
 
       - name: Generate baseline profiles
         run: ./scripts/update-baseline-profiles.sh

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,6 +1,152 @@
 Changelog
 =========
 
+**Unreleased**
+--------------
+
+0.20.0
+------
+
+_2024-03-18_
+
+- **New**: Enable `RememberObserver` to work with `rememberRetained`.
+- **New**: Add `Navigator.popRoot()`. extension (#1274)
+- **Behavior change**: Add a key to `CircuitContent` to keep `Ui` and `Presenter` consistent. We already did this for presenters, this just makes it consistent for both.
+- [circuitx-android] Implement `ToastEffect`.
+- **Fix**: Fix `rememberImpressionNavigator()` not delegating `PopResult`.
+- **Fix**: Navigator - Pass `PopResult` to `onRootPop()`.
+- **Fix**: Check `canRetainCheck` when saving `RetainedStateRegistry`.
+- **Enhancement**: Improve error messaging when using assisted inject.
+- Force `com.google.guava:listenablefuture` to `1.0` to avoid conflicts with Guava.
+- Update compose-compiler to `1.5.10.1`.
+- Update coroutines to `1.8.0`.
+- Update to Compose Multiplatform `1.6.1`.
+- Update Android compose dependencies to `1.6.3`.
+- Update molecule to `1.4.1`.
+- Update dagger to `2.51`.
+- Update turbine to `1.1.0`.
+- Update uuid to `0.8.3`.
+- Update kotlin to `1.9.23`.
+- Update KSP to `1.9.23-1.0.19`.
+
+Special thanks to [@chrisbanes](https://github.com/chrisbanes), [@aschulz90](https://github.com/aschulz90), and [@alexvanyo](https://github.com/alexvanyo) for contributing to this release!
+
+0.19.1
+------
+
+_2024-02-12_
+
+This is a small bug fix release focused `SaveableBackStack` consistency and `FakeNavigator` API improvements.
+
+- Fix `FakeNavigator.awaitNextScreen()` not suspending.
+- Fix `FakeNavigator.resetRoot()` not returning the actual popped screens.
+- Make `Navigator.peekBackStack()` and `Navigator.resetRoot()` return `ImmutableList`.
+- Make `BackStack.popUntil()` return the `ImmutableList` of the popped records.
+- Support `FakeNavigator.peekBackStack()` return the `ImmutableList` of the popped records.
+- Strongly pop events and resetRoot events in `FakeNavigator`. This should offer much more information about the events.
+- Use a real `BackStack` instance in `FakeNavigator` + allow for specifying a user-provided instance.
+- Require an initial root screen to construct `FakeNavigator` unless using a custom `BackStack`.
+  - Note this slightly changes semantics, as now the root screen will not be recorded as the first `goTo` event.
+- Require an initial root screen (or list of screens) for `rememberSaveableBackStack()`.
+- Expose a top-level non-composable `Navigator()` factory function.
+
+0.19.0
+------
+
+_2024-02-09_
+
+### Navigation with results
+
+This release introduces support for inter-screen navigation results. This is useful for scenarios where you want to pass data back to the previous screen after a navigation event, such as when a user selects an item from a list and you want to pass the selected item back to the previous screen.
+
+```kotlin
+var photoUrl by remember { mutableStateOf<String?>(null) }
+val takePhotoNavigator = rememberAnsweringNavigator<TakePhotoScreen.Result>(navigator) { result ->
+  photoUrl = result.url
+}
+
+// Elsewhere
+takePhotoNavigator.goTo(TakePhotoScreen)
+
+// In TakePhotoScreen.kt
+data object TakePhotoScreen : Screen {
+  @Parcelize
+  data class Result(val url: String) : PopResult
+}
+
+class TakePhotoPresenter {
+  @Composable fun present(): State {
+    // ...
+    navigator.pop(result = TakePhotoScreen.Result(newFilters))
+  }
+}
+```
+
+See the [new section in the navigation docs](https://slackhq.github.io/circuit/navigation/#results) for more details, as well as [updates to the Overlays](https://slackhq.github.io/circuit/overlays/#overlay-vs-popresult) docs that help explain when to use an `Overlay` vs navigating to a `Screen` with a result.
+
+### Support for multiple back stacks
+
+This release introduces support for saving/restoring navigation state on root resets (aka multi back stack). This is useful for scenarios where you want to reset the back stack to a new root but still want to retain the previous back stack's state, such as an app UI that has a persistent bottom navigation bar with different back stacks for each tab.
+
+This works by adding two new optional `saveState` and `restoreState` parameters to `Navigator.resetRoot()`.
+
+```kotlin
+navigator.resetRoot(HomeNavTab1, saveState = true, restoreState = true)
+// User navigates to a details screen
+navigator.push(EntityDetails(id = foo))
+// Later, user clicks on a bottom navigation item
+navigator.resetRoot(HomeNavTab2, saveState = true, restoreState = true)
+// Later, user switches back to the first navigation item
+navigator.resetRoot(HomeNavTab1, saveState = true, restoreState = true)
+// The existing back stack is restored, and EntityDetails(id = foo) will be top of
+// the back stack
+```
+
+There are times when saving and restoring the back stack may not be appropriate, so use this feature only when it makes sense. A common example where it probably does not make sense is launching screens which define a UX flow which has a defined completion, such as onboarding.
+
+### New Tutorial!
+
+On top of Circuit's existing docs, we've added a new tutorial to help you get started with Circuit. It's a step-by-step guide that walks you through building a simple inbox app using Circuit, intended to serve as a sort of small code lab that one could do in 1-2 hours. Check it out [here](https://slackhq.github.io/circuit/tutorial/).
+
+### Overlay Improvements
+
+- **New**: Promote `AlertDialogOverlay`, `BasicAlertDialogOverlay`, and `BasicDialogOverlay` to `circuitx-overlay`.
+- **New**: Add `OverlayEffect` to `circuit-overlay`. This offers a simple composable effect to show an overlay and await a result.
+  ```kotlin
+  OverlayEffect(state) { host ->
+    val result = host.show(AlertDialogOverlay(...))
+    // Do something with the result
+  }
+  ```
+- Add `OverlayState` and `LocalOverlayState` to `circuit-overlay`. This allows you to check the current overlay state (`UNAVAILABLE`, `HIDDEN`, or `SHOWING`).
+- Mark `OverlayHost` as `@ReadOnlyOverlayApi` to indicate that it's not intended for direct implementation by consumers.
+- Mark `Overlay` as `@Stable`.
+
+### Misc
+
+- Make `NavEvent.screen` public.
+- Change `Navigator.popUntil` to be exclusive.
+- Add `Navigator.peek()` to peek the top screen of the back stack.
+- Add `Navigator.peekBackStack()` to peek the top screen of the back stack.
+- Align spelling of back stack parameters across all APIs to `backStack`.
+- Refreshed iOS Counter sample using SPM and SKIE.
+- Convert STAR sample to KMP. Starting with Android and Desktop.
+- Fix baseline profiles packaging. Due to a bug in the baseline profile plugin, we were not packaging the baseline profiles in the artifacts. This is now fixed.
+- Mark `BackStack.Record` as `@Stable`.
+- Fix an infinite loop in the `onRootPop` of the Android `rememberCircuitNavigator`.
+- Update the default decoration to better match the android 34 transitions.
+- Update androidx.lifecycle to `2.7.0`.
+- Update to compose multiplatform to `1.5.12`.
+- Update to compose to `1.6.1`.
+- Update to compose-bom to `2024.02.00`.
+- Update compose-compiler to `1.5.9`.
+- Update AtomicFu to `0.23.2`.
+- Update Anvil to `2.4.9`.
+- Update KotlinPoet to `1.16.0`.
+- Compile against KSP `1.9.22-1.0.17`.
+
+Special thanks to [@milis92](https://github.com/milis92), [@ChrisBanes](https://github.com/ChrisBanes), and [@vulpeszerda](https://github.com/vulpeszerda) for contributing to this release!
+
 0.18.2
 ------
 
@@ -56,7 +202,7 @@ Special thanks to [@alexvanyo](https://github.com/alexvanyo) for contributing to
 
 _2023-11-28_
 
-## **New**: circuitx-effects artifact
+### **New**: circuitx-effects artifact
 
 The circuitx-effects artifact provides some effects for use with logging/analytics. These effects
 are typically used in Circuit presenters for tracking `impressions` and will run only once until
@@ -70,11 +216,11 @@ dependencies {
 
 Docs: https://slackhq.github.io/circuit/circuitx/#effects
 
-## **New**: Add codegen mode to support both Anvil and Hilt
+### **New**: Add codegen mode to support both Anvil and Hilt
 
 Circuit's code gen artifact now supports generating for Hilt projects. See the docs for usage instructions: https://slackhq.github.io/circuit/code-gen/
 
-## Misc
+### Misc
 
 - Decompose various `CircuitContent` internals like `rememberPresenter()`, `rememberUi`, etc for reuse.
 - Make `CircuitContent()` overload that accepts a pre-constructed presenter/ui parameters public to allow for more control over content.
@@ -124,7 +270,7 @@ _2023-11-01_
 
 _2023-09-20_
 
-## **New**: Allow retained state to be retained whilst UIs and Presenters are on the back stack.
+### **New**: Allow retained state to be retained whilst UIs and Presenters are on the back stack.
 
 Originally, `circuit-retained` was implemented as a solution for preserving arbitrary data across configuration changes on Android. With this change it now also acts as a solution for retaining state _across the back stack_, meaning that traversing the backstack no longer causes restored contents to re-run through their empty states anymore.
 
@@ -134,7 +280,7 @@ Note that `circuit-retained` is still optional for now, but we are considering m
 
 Full details + demos can be found in https://github.com/slackhq/circuit/pull/888. Big thank you to [@chrisbanes](https://github.com/chrisbanes) for the implementation!
 
-## Other changes
+### Other changes
 
 - **New**: Add `collectAsRetainedState` utility function, analogous to `collectAsState` but will retain the previous value across configuration changes and back stack entries.
 - **Enhancement**: Optimize `rememberRetained` with a port of the analogous optimization in `rememberSaveable`. See [#850](https://github.com/slackhq/circuit/pull/850).
@@ -310,15 +456,15 @@ _2023-06-02_
 
 _2023-05-26_
 
-## Preliminary support for iOS targets
+### Preliminary support for iOS targets
 
 Following the announcement of Compose for iOS alpha, this release adds `ios()` and `iosSimulatorArm64()` targets for the Circuit core artifacts. Note that this support doesn't come with any extra APIs yet for iOS, just basic target support only. We're not super sure what direction we want to take with iOS, but encourage others to try it out and let us know what patterns you like. We have updated the Counter sample to include an iOS app target as well, using Circuit for the presentation layer only and SwiftUI for the UI.
 
 Note that circuit-codegen and circuit-codegen-annotations don't support these yet, as Anvil and Dagger only support JVM targets.
 
 More details can be found in the PR: https://github.com/slackhq/circuit/pull/583
 
-## Misc
+### Misc
 
 - Use new baseline profile plugin for generating baseline profiles.
 - Misc sample app fixes and updates.
@@ -329,7 +475,7 @@ More details can be found in the PR: https://github.com/slackhq/circuit/pull/583
 
 Note that we unintentionally used an experimental animation API for `NavigatorDefaults.DefaultDecotration`, which may cause R8 issues if you use a newer, experimental version of Compose animation. To avoid issues, copy the animation code and use your own copy compiled against the newest animation APIs. We'll fix this after Compose 1.5.0 is released.
 
-## Dependency updates
+### Dependency updates
 
 ```
 androidx.activity -> 1.7.2
@@ -346,7 +492,7 @@ turbine -> 0.13.0
 
 _2023-04-06_
 
-## [Core] Split up core artifacts.
+### [Core] Split up core artifacts.
 - `circuit-runtime`: common runtime components like `Screen`, `Navigator`, etc.
 - `circuit-runtime-presenter`: the `Presenter` API, depends on `circuit-runtime`.
 - `circuit-runtime-ui`: the `Ui` API, depends on `circuit-runtime`.
@@ -356,7 +502,7 @@ The goal in this is to allow more granular dependencies and easier building agai
 
 Where we think this could really shine is in multiplatform projects where Circuit's UI APIs may be more or less abstracted away in service of using native UI, like in iOS.
 
-### `circuit-runtime` artifact
+#### `circuit-runtime` artifact
 | Before                           | After                                    |
 |----------------------------------|------------------------------------------|
 | com.slack.circuit.CircuitContext | com.slack.circuit.runtime.CircuitContext |
@@ -365,17 +511,17 @@ Where we think this could really shine is in multiplatform projects where Circui
 | com.slack.circuit.Navigator      | com.slack.circuit.runtime.Navigator      |
 | com.slack.circuit.Screen         | com.slack.circuit.runtime.Screen         |
 
-### `circuit-runtime-presenter` artifact
+#### `circuit-runtime-presenter` artifact
 | Before                      | After                                         |
 |-----------------------------|-----------------------------------------------|
 | com.slack.circuit.Presenter | com.slack.circuit.runtime.presenter.Presenter |
 
-### `circuit-runtime-ui` artifact
+#### `circuit-runtime-ui` artifact
 | Before               | After                                  |
 |----------------------|----------------------------------------|
 | com.slack.circuit.Ui | com.slack.circuit.runtime.presenter.Ui |
 
-### `circuit-foundation` artifact
+#### `circuit-foundation` artifact
 | Before                                     | After                                                 |
 |--------------------------------------------|-------------------------------------------------------|
 | com.slack.circuit.CircuitCompositionLocals | com.slack.circuit.foundation.CircuitCompositionLocals |
@@ -390,7 +536,7 @@ Where we think this could really shine is in multiplatform projects where Circui
 | com.slack.circuit.push                     | com.slack.circuit.foundation.push                     |
 | com.slack.circuit.screen                   | com.slack.circuit.foundation.screen                   |
 
-## More Highlights
+### More Highlights
 - [Core] Remove Android-specific `NavigableCircuitContent` and just use common one. Back handling still runs through `BackHandler`, but is now configured in `rememberCircuitNavigator`.
 - [Core] Add `defaultNavDecoration` to `CircuitConfig` to allow for customizing the default `NavDecoration` used in `NavigableCircuitContent`.
 - [Core] Mark `CircuitUiState` as `@Stable` instead of `@Immutable`.