GITBOOK-40: Timothé's Jan 28 changes

Author: TimLariviere

.gitbook/assets/image (1).png

@@ -1 +1,10 @@
-# docs.fabulous.dev
+# Welcome
+
+Fabulous is a modern declarative UI framework for crafting cross-platform mobile and desktop apps in .NET. It aims to bring you a great development experience and confidence in your code by combining an expressive UI syntax, the simple & robust Model-View-Update (MVU) architecture, and functional programming.
+
+### About Fabulous 
+
+Fabulous aims to provide all the tools to let you create your own mobile and desktop apps using only F# and the [Model-View-Update architecture](https://guide.elm-lang.org/architecture/) (shorten to MVU), with a great F# DSL for building dynamic UIs.\
+The combination of F# and MVU makes for a great development experience.
+
+Note that Fabulous itself does not provide UI controls, so you’ll need to combine it with another framework like Xamarin.Forms, .NET MAUI or AvaloniaUI.

.gitbook/assets/image (2).png

@@ -0,0 +1,52 @@
+# Table of contents
+
+* [Welcome](README.md)
+* [Get Started](get-started.md)
+* [Samples & Tutorials](samples-and-tutorials/README.md)
+  * [Samples](samples-and-tutorials/samples.md)
+  * [Videos](samples-and-tutorials/videos.md)
+* [Basics](basics/README.md)
+  * [MVU](basics/mvu.md)
+  * [Application state](basics/application-state/README.md)
+    * [Commands](basics/application-state/commands.md)
+    * [State validation](basics/application-state/state-validation.md)
+  * [User interface](basics/user-interface/README.md)
+    * [Widgets and modifiers](basics/user-interface/widgets-and-modifiers.md)
+    * [Styling](basics/user-interface/styling.md)
+    * [Animations](basics/user-interface/animations.md)
+  * [Testing](basics/testing.md)
+  * [Error monitoring](basics/error-monitoring.md)
+* [Advanced](advanced/README.md)
+  * [Saving and Restoring app state](advanced/saving-and-restoring-app-state.md)
+  * [Performance optimization](advanced/performance-optimization.md)
+  * [Composing larger applications](advanced/composing-larger-applications/README.md)
+    * [Splitting into independent MVU states](advanced/composing-larger-applications/splitting-into-independent-mvu-states.md)
+    * [Integrating commands](advanced/composing-larger-applications/integrating-commands.md)
+    * [Communicating between MVU states](advanced/composing-larger-applications/communicating-between-mvu-states.md)
+* [Architecture](architecture/README.md)
+  * [Attribute definitions](architecture/attribute-definitions.md)
+  * [Virtualized collections](architecture/virtualized-collections.md)
+  * [Using nightly builds](architecture/using-nightly-builds.md)
+
+## Xamarin.Forms <a href="#xamarinforms" id="xamarinforms"></a>
+
+* [Get Started](xamarinforms/get-started.md)
+* [User interface](xamarinforms/user-interface/README.md)
+  * [Custom controls](xamarinforms/user-interface/custom-controls.md)
+  * [Effects](xamarinforms/user-interface/effects.md)
+  * [Navigation](xamarinforms/user-interface/navigation.md)
+  * [Pop-ups](xamarinforms/user-interface/pop-ups.md)
+* [Extensions](xamarinforms/extensions/README.md)
+  * [FFImageLoading](xamarinforms/extensions/ffimageloading.md)
+  * [OxyPlot](xamarinforms/extensions/oxyplot.md)
+  * [SkiaSharp](xamarinforms/extensions/skiasharp.md)
+  * [VideoManager](xamarinforms/extensions/videomanager.md)
+  * [Xamarin.Forms.Maps](xamarinforms/extensions/xamarin.forms.maps.md)
+
+## .NET MAUI <a href="#maui" id="maui"></a>
+
+* [Get Started](maui/get-started.md)
+
+## Avalonia
+
+* [Get Started](avalonia/get-started.md)

.gitbook/assets/image (3).png

@@ -0,0 +1,2 @@
+# Advanced
+

.gitbook/assets/image (4).png

@@ -0,0 +1,3 @@
+# Composing larger applications
+
+Composing larger MVU applications is covered in great details in [The Elmish Book](https://zaid-ajaj.github.io/the-elmish-book/#/chapters/scaling/). This documentation will cover mainly how to integrate those concepts into Fabulous apps.

.gitbook/assets/image.png

@@ -0,0 +1,135 @@
+---
+description: >-
+  Learn how to use the Intent pattern to communicate between independent MVU
+  states
+---
+
+# Communicating between MVU states
+
+Like we saw in the previous sections, most MVU apps adopt the following signatures to model how their state changes and the side effects to be executed:
+
+```fsharp
+val init : unit -> Model * Cmd<Msg>
+val update : Msg -> Model -> Model * Cmd<Msg>
+```
+
+MVU programs are meant to be well isolated from the outside world to be reliable and predictable, producing only pure init and update functions. But how does a program communicate with other programs when something goes out of its scope such as navigating to another page?
+
+### Communicating from child to parent
+
+While technically the parent could peek into the child's Model to eventually react to a specific state and do additional work (see [Splitting into independent MVU states](splitting-into-independent-mvu-states.md)). This approach is pretty bad because it depends greatly on the internal implementation of the child which can change at any time.
+
+Since we know the parent will always call the child's init and update functions, we can take advantage of this by returning a new value specifically for the parent.
+
+Comes in the Intent pattern:
+
+```fsharp
+val init: unit -> Model * Cmd<Msg> * Intent option
+val update: Msg -> Model -> Model * Cmd<Msg> * Intent option
+```
+
+As you can see, we are returning one more value after executing init and update: Intent option.
+
+The Intent is a discriminated union created by you just like Msg. Its goal is to notify the caller of extra intention that needs to be taken care of outside the child.
+
+Let's take the example of an app going through several pages of forms that the user needs to fill in.
+
+The App module will take care of the whole workflow between the pages, but each individual page has its own MVU state. By returning an intent, the page can notify the app to do cross-page actions.
+
+{% code title="Form1.fs" %}
+```fsharp
+type Msg =
+    | TextChanged of string
+    | Complete
+
+type Intent =
+    | SaveDraft of string
+    | GoToNextStep
+    
+let init () =
+    { ... }, Cmd.none, None
+    
+let update msg model =
+    match msg with
+    | TextChanged newValue -> { model with Text = newValue }, Cmd.none, Some (SaveDraft draft)
+    | Complete -> model, Cmd.none, Some GoToNextStep
+```
+{% endcode %}
+
+{% code title="App.fs" %}
+```fsharp
+type Msg =
+    | NextStep
+    | ...
+            
+let saveDraftOnDisk draft =
+    Cmd.ofAsyncMsg(async { ... })
+
+let update msg model =
+    match msg with
+    | Form1Msg f1 ->
+        let m, c, i = Form1.update f1 model.Form1Model
+        let intentCmd =
+            match i with
+            | Some Form1.Intent.SaveDraft draft -> saveDraftOnDisk draft
+            | Some Form1.Intent.GoToNextStep -> Cmd.ofMsg NextStep
+            | _ -> Cmd.none
+            
+        { model with Form1Model = m },
+        Cmd.batch [
+            intentCmd
+            Cmd.map Form1Msg c
+        ]
+```
+{% endcode %}
+
+### Communicating between siblings
+
+Just like parent-child communication, communicating between siblings involves using an intent. Except the intent this time tells the parent to forward a message to the child's sibling.
+
+{% code title="Form1.fs" %}
+```fsharp
+type Intent =
+    | SelectNextField
+
+let update msg model =
+    match msg with
+    | FocusNextForm -> model, Cmd.none, Some SelectNextField
+```
+{% endcode %}
+
+{% code title="Form2.fs" %}
+```fsharp
+let update msg model =
+    match msg with
+    | FocusFirstField -> { model with ... }, Cmd.none, None
+```
+{% endcode %}
+
+{% code title="App.fs" %}
+```fsharp
+let update msg model =
+    match msg with
+    | Form1Msg f1 ->
+        let m, c, i = Form1.update f1 model.Form1Model
+        let intentCmd =
+            match i with
+            | Some Form1.Intent.SelectNextField -> Cmd.ofMsg (Form2Msg Form2.Msg.FocusFirstField)
+            | _ -> Cmd.none
+        { model with Form1Model = m },
+        Cmd.batch [
+            intentCmd
+            Cmd.map Form1Msg c
+        ]
+        
+    | Form2Msg f2 ->
+        let m, c, i = Form2.update f2 model.Form2Model
+        let intentCmd =
+            match i with
+            | _ -> Cmd.none
+        { model with Form2Model = m },
+        Cmd.map Form2Msg c
+```
+{% endcode %}
+
+To learn more about the Intent pattern, please read [The Elmish Book - The Intent Pattern](https://zaid-ajaj.github.io/the-elmish-book/#/chapters/scaling/intent).

README.md

@@ -0,0 +1,98 @@
+---
+description: >-
+  Learn how to use Cmd.map and Cmd.batch to compose Cmds from independent MVU
+  states
+---
+
+# Integrating commands
+
+In [Splitting into independent MVU states](splitting-into-independent-mvu-states.md), we learned how to decompose larger apps into individual MVU states by using simple init and update functions returning only a Model, like in those signatures:
+
+```fsharp
+val init: unit -> Model
+val update: Msg -> Model -> Model
+```
+
+Though most apps will need more complex signatures to handle side effects such as processing data, network calls, access to the camera or storage, etc. Those apps will use commands to model those side-effects:
+
+```fsharp
+val init: unit -> Model * Cmd<Msg>
+val update: Msg -> Model -> Model * Cmd<Msg>
+```
+
+If we simply do the same than in the previous section, we will face the same compilation issue we saw by composing views with different Msg types.
+
+```fsharp
+let update msg model =
+    match msg with
+    | Form1Msg f1 ->
+        let m, c = Form1.update f1 model.Form1Model
+        { model with Form1Model = m }, c
+        
+    | Form1Msg f2 ->
+        let m, c = Form2.update f2 model.Form2Model
+        { model with Form2Model = m }, c // ERROR: Expected Cmd<Form1.Msg>, got Cmd<Form2.Msg>
+```
+
+We solved that issue with View.map previously. Since the issue is similar, the solution is also similar.
+
+### Converting a command's Msg type
+
+Just like View.map to convert a widget's Msg type to the parent's Msg type  to allow for composition, Fabulous has Cmd.map to do the same for commands.
+
+```fsharp
+val Cmd.map : ('oldMsg -> 'newMsg) -> Cmd<'oldMsg> -> Cmd<'newMsg>
+```
+
+Using Cmd.map is very similar to View.map.
+
+```fsharp
+Cmd.map Form1Msg form1Cmd
+```
+
+{% code title="App.fs" %}
+```fsharp
+type Msg =
+    | Form1Msg of Form1.Msg
+    | Form2Msg of Form2.Msg
+
+let init () =
+    let m, c = Form1.init()
+    { Form1Model = m }, Cmd.map Form1Msg c
+    
+let update msg model =
+    match msg with
+    | Form1Msg f1 ->
+        let m, c = Form1.update f1 model.Form1Model
+        { model with Form1Model = m }, Cmd.map Form1Msg c
+        
+    | Form2Msg f2 ->
+        let m, c = Form1.update f2 model.Form2Model
+        { model with Form2Model = m }, Cmd.map Form2Msg c
+```
+{% endcode %}
+
+### Batching several Cmds together
+
+Sometimes, an app needs to execute several side effects at the same time. To enable that, Fabulous provides a Cmd.batch function to merge several commands into a single one.
+
+```fsharp
+val Cmd.batch : Cmd<'msg> list -> Cmd<'msg>
+```
+
+We can combine Cmd.batch with Cmd.map as we want.
+
+```fsharp
+let init () =
+    let m1, c1 = Counter.init()
+    let m2, c2 = Input.init()
+    { CounterModel = m1
+      InputModel = m2 },
+    Cmd.batch [
+        Cmd.ofAsyncMsg(loadDataAsync())
+        Cmd.map CounterMsg c1
+        Cmd.map InputMsg c2
+    ]
+```
+
+To learn more about integrating commands, read [The Elmish Book - Integrating Commands](https://zaid-ajaj.github.io/the-elmish-book/#/chapters/scaling/integrating-commands).