Merge pull request #110 from zsoltk/documentation

Documentation update

documentation/apps/structure.md

@@ -0,0 +1,62 @@
+# Structuring your app navigation
+
+As seen in [Composable navigation](../navigation/composable-navigation.md), you can make `NavModels` composable. 
+
+To achieve this, Appyx offers the `Node` class as the structural element.
+
+
+## Node illustration
+
+In many of the examples you'll see this panel as an illustration of a very simple `Node` – it has some local state (id, colour, and a counter).
+
+<img src="https://i.imgur.com/09qR6zl.png" width="150">
+
+If you launch the sample app in the `:app` module, you can also change its state (colour) by tapping it. Its counter is stepped automatically. This is to illustrate that it has its own state, persisted and restored.
+
+
+## Node overview
+
+You can think of a `Node` as a standalone component with:
+
+- Its own simplified lifecycle
+- State restoration
+-  A `@Composable` view
+- Business logic that's kept alive even when the view isn't added to the composition
+- The ability to host generic [Plugins](../apps/plugins.md) to extract extra concerns without enforcing any particular architectural pattern
+
+
+## Parent nodes, child nodes
+
+`ParentNodes` can have other `Nodes` as children. This means you can represent your whole application as a tree of Appyx nodes.
+
+<img src="https://i.imgur.com/iwSxuZi.png" width="450">
+
+You can go as granular or as high-level as it fits you. This allows to keep the complexity low in individual `Nodes` by extracting responsibilities to children, as well as composing other components to build more complex functionality.
+
+
+## Composable navigation
+
+<img src="https://i.imgur.com/hKvOs3w.gif" width="450">
+
+`Nodes` offer the structure – `NavModels` add dynamism to it.
+
+Read more in [Composable navigation](../navigation/composable-navigation.md)
+
+
+## Lifecycle
+
+Nodes have their own lifecycles, directly using the related classes of `androidx.lifecycle`.
+
+Read more in [Lifecycle](../apps/lifecycle.md)
+
+
+## Summary
+
+A summary of Appyx's approach to structuring applications:
+
+- Compose your app out of `Nodes` with their own lifecycles and state
+- Navigation is local, composed of individual pieces of `NavModels`
+- Navigation is stateful
+- Navigation is unit-testable
+- You're free to implement your own navigable components by utilising `NavModels`
+- Avoid global navigation concerns, like shared modules needing to know about the application, or the application needing to know about all its possible modules

documentation/faq.md

@@ -0,0 +1,78 @@
+# FAQ
+
+
+## Navigation-related
+
+#### **Q: How does Appyx relate to Jetpack Compose Navigation?**
+
+We wrote an article on this: [Appyx vs Jetpack Compose Navigation](https://medium.com/bumble-tech/appyx-vs-jetpack-compose-navigation-b91bd23369f2)
+
+While Appyx represents a different paradigm, it can also co-exist with Jetpack Compose Navigation. This can be helpful if you want to use Appyx for in-screen mechanisms only, or if you plan to migrate gradually.
+
+See [Sample apps](how-to-use-appyx/sample-apps.md) for more details.
+
+---
+
+#### **Q: How does Appyx compare against other navigation solutions?**
+
+The core concepts of navigation in Appyx differ from most navigation libraries: 
+
+1. You don't have a concept of the "screen" present in the model
+2. You can define your own navigation models
+3. On the UI level you can transform what feels like the "screen" itself
+
+See [Model-driven navigation](navigation/model-driven-navigation.md) for more details.
+
+---
+
+
+#### **Q: What about dialogs & bottom sheets?**
+
+You can use Appyx in conjunction with Accompanist or any other Compose mechanism.
+
+If you wish, you can model your own Modal with Appyx too. We'll add an example soon.
+
+---
+
+## Using Appyx in an app
+
+
+#### **Q: What architectural patterns can I use?**
+
+Appyx is agnostic of architectural patterns. You can use any architectural pattern in the `Nodes` you'd like. You can even use a different one in each.
+
+---
+
+#### **Q: Can I use it with ViewModel?**
+
+Yes, we'll add an example soon.
+
+---
+
+
+#### **Q: Can I use it with Hilt?**
+
+Yes, we'll add an example soon.
+
+---
+
+
+## On the project itself
+
+#### **Q: Is it production ready?**
+
+We do use it at Bumble in production, and as such, we're committed to maintaining and improving it.
+
+The project is currently in an alpha stage only to allow API changes for now. However, we commit ourselves to communicating all such changes in the [Changelog](releases/changelog.md).
+
+---
+
+#### **Q: What's your roadmap?**
+
+We're full with ideas where to take Appyx further! A more detailed roadmap will be added later. Come back for more updates.
+
+---
+
+## Other
+
+Have a question? Raise it in [Discussions](https://github.com/bumble-tech/appyx/discussions)!.

documentation/how-to-use-appyx/codelabs.md

@@ -2,4 +2,4 @@
 
 ## Coming soon!
 
-ETA week of 15 Aug
+ETA week of 12 Sep

documentation/how-to-use-appyx/quick-start.md

@@ -1,9 +1,23 @@
 # Quick start guide
 
+## Scope of this guide
+
+The steps below will cover:
+
+1. Integrating Appyx into your project
+2. Creating a very simple `Node` hierarchy
+3. We'll use a simple back stack for navigation
+4. We'll add some simple transitions to it
+
+This should be enough to get you started as a rudimentary application structure.
+
+Tutorials & codelabs on more advanced topics & the full power of Appyx to follow soon.
+
+
 ## Suggestions
 
 - Check out the project and launch the `:app` module for a quick demonstration
-- Check out [Nodes and routing](../composable-navigation/index.md), which explains the concepts you'll encounter in this guide.
+- Check out [App structure](../apps/structure.md), which explains the concepts you'll encounter in this guide.
 
 
 ## 1. Add Appyx to your project
@@ -212,4 +226,8 @@ You can repeat the same pattern and make any embedded children also a `ParentNod
 3. At some point extract the increasing complexity from a placeholder to another `Node` 
 4. Repeat the same on children, go to `1.`
 
-You can (and probably should) also extract local business logic, the view, any any other components into separate classes and [plugins](../other/plugins.md).
+
+## Further reading
+
+- Check out [Model-driven navigation](../navigation/model-driven-navigation.md) how to take your navigation to the next level
+- You can (and probably should) also extract local business logic, the view, any any other components into separate classes and [Plugins](../apps/plugins.md).

documentation/index.md

@@ -11,6 +11,7 @@ Model-driven navigation for Jetpack Compose
 - **Navigate directly from code** – In a type-safe way, without boilerplate
 - **Gain control of navigation state** – Making your navigation unit-testable
 - **Complete control over operations and behaviour** – Use and extend the back stack or the view pager from the library, or build your own 
+- **Your own navigation** – With Appyx, you can define your own navigation models
 - **Use any animation for transitions** – Anything you can represent with Compose `Modifiers`
 
 
@@ -35,6 +36,8 @@ With Appyx you can break down screen boundaries and transform the screen itself:
 
 <img src="https://i.imgur.com/pbDENSc.gif" width="150">
 
+See [Model-driven navigation](navigation/model-driven-navigation.md) for more details.
+
 
 ## Launch the demo app
 

documentation/navigation/composable-navigation.md

@@ -0,0 +1,46 @@
+# Composable navigation
+
+[NavModels](../navmodel/index.md) in Appyx are composable. 
+
+As a single `NavModel` won't be enough for the whole of your whole app, you can use many in a composable way. That is, any navigation target of a `NavModel` can also host its own `NavModel`.
+
+
+## Structural element for composing navigation
+
+```Nodes``` are the main structural element in Appyx. They can host `NavModels`, and they form a tree.
+
+This allows you to make your app's business logic also composable by leveraging `Nodes` as lifecycled components.
+
+Read more in [Structuring your app navigation](../apps/structure.md)
+
+
+## Navigation in the tree
+
+<img src="https://i.imgur.com/hKvOs3w.gif" width="450">
+
+Once you've structured your navigation in a composable way, you can add `NavModels` to `Node` of this tree and make it dynamic:
+
+- Some parts in this tree are active while others ore not
+- The activate parts define what state the application is in, and what the user sees on the screen
+- We can change what's active by using `NavModels` on each level of the tree
+- Changes will feel like navigation to the user
+
+
+## How NavModels affect Nodes
+
+NavModel operations will typically result in:
+
+- Adding or removing child `Nodes` of a `ParentNode`
+- Move them on and off the screen
+- Change their states
+
+As an illustration:
+
+<img src="https://i.imgur.com/8gy3Ghb.gif" width="200"> <img src="https://i.imgur.com/N8rEPrJ.gif" width="200">
+
+Here:
+
+- `Back stack` illustrates adding and removing child `Nodes`
+- `Tiles` illustrates changing the state of children and removing them from the `ParentNode`
+
+These are just two examples, you're of course not limited to using them.

documentation/navigation/model-driven-navigation.md

@@ -0,0 +1,41 @@
+# Model-driven navigation
+
+
+## Your own navigation model
+
+Generally speaking, most navigation solutions have fixed navigation mechanisms (e.g. a back stack).
+
+Appyx gives you the freedom to define your own navigation model. For example, you can implement any of the examples you see here with with the same approach:
+
+<img src="https://i.imgur.com/N8rEPrJ.gif" width="150"> <img src="https://i.imgur.com/esLXh61.gif" width="150"> <img src="https://i.imgur.com/8gy3Ghb.gif" width="150"> <img src="https://i.imgur.com/V3bks8c.gif" width="150">
+
+
+## No screen, only a viewport
+
+Generally speaking, most navigation solutions model a "Screen" and focus on how to get from one screen to another.
+
+Appyx does not have the concept of the screen in its model – there's only a viewport, and whatever fills the available space will feel like the screen to the user.
+
+This freedom allows you to implement:
+
+- navigation that feels like going from "screen to screen"
+- navigation "inside the screen"
+- navigation that bridges between the two
+
+For example, you can transform the screen itself as part of navigation:
+
+<img src="https://i.imgur.com/pbDENSc.gif" width="150">
+
+
+## NavModels
+
+A `NavModel` implements any of the above mechanisms. 
+
+See [NavModels](../navmodel/index.md) for more details. 
+
+
+## Composable navigation
+
+`NavModels` in Appyx are composable.
+
+See [Composable navigation](composable-navigation.md) for more details.