Article about Feliz and Fable React

docs/faq/faq-felizandfable.md

@@ -0,0 +1,75 @@
+In a nutshell Fable.React and Feliz are two F# libraries which perform a similar function:
+
+* Provide a typesafe F# wrapper to allow you to interact with React.
+* Provide a way to create your own wrappers around existing React components.
+* Provide a DSL for you to consume and create React wrappers in a consistent way.
+
+## DSL differences
+The main distinction between the two libraries is that Fable.React follows a layout as follows:
+
+```fsharp
+element [ attribute; attribute ] [ childElement; childElement ]
+```
+
+> Note: Code snippets below are for illustrative purposes only and do not compile.
+
+For example:
+
+```fsharp
+h1 [ style "color:Tomato" ] [
+    p [] [ text "Hello" ] // no attributes
+    p [] [ text "Another paragraph" ] // no attributes
+    h2 [ style "color:Blue" ] [] // no child elements
+]
+```
+
+In this example, `h1` is the "top level" element, with a single attribute and three children, two of which have their own children.
+
+Feliz adopts a different style, in which instead of an element having two lists, there is only one. The list directly contains *either* attributes *or* child elements, but not both:
+
+The above snippet would convert into Feliz as follows:
+
+```fsharp
+h1 [
+    style "color:Tomato"
+    children [
+        p [ text "Hello" ]
+        p [ text "Another paragraph" ]
+        h2 [ style "color:Blue" ]
+    ]
+]
+```
+
+The `children` function is required when mixing and matching attributes and elements:
+
+```fsharp
+h1 [ // this is fine - just attributes underneath h1
+    style "color:Tomato"
+    title "foo"
+]
+
+h1 [  // fine - just elements underneath h1
+    p [ text "Hello" ]
+]
+
+h1 [  // not fine - can't mix and match attributes and elements
+    style "color:Tomato"
+    p [ text "Hello" ]
+]
+```
+
+In order to allow both attributes and elements in the same list, Feliz introduces the `children` node:
+
+```fsharp
+h1 [ // this is now fine
+    style "color:Tomato"
+    children [
+        p [ text "Hello" ]
+    ]
+]
+```
+
+## Guidance
+* Fable.React was created initially, whilst Feliz was developed some time later.
+* Feliz has better support for React interop and the majority of the community nowadays uses the Feliz DSL style for developing components.
+* As they are both wrappers around the same underlying technology (React) and Feliz uses some parts of Fable.React, you can actually mix and match the two in your applications as required.

mkdocs.yml

@@ -42,7 +42,7 @@ extra:
   analytics:
     provider: google
     property: G-WED2S9FLSL
-    
+
 nav:
   - Home: "index.md"
   - Introduction: "intro.md"
@@ -69,10 +69,8 @@ nav:
       - Overview: "template-overview.md"
       - Commands: "template-safe-commands.md"
   - How do I...:
-      - Upgrade from V2 to V3: "recipes/upgrading/v2-to-v3.md"
-      - Upgrade from V3 to V4: "recipes/upgrading/v3-to-v4.md"
-      - Upgrade from V4 to V5: "recipes/upgrading/v4-to-v5.md"
       - Create a new Recipe: "recipes/template.md"
+      - Upgrade from V4 to V5: "recipes/upgrading/v4-to-v5.md"
       - Build:
           - Add build automation: "recipes/build/add-build-script.md"
           - Create a docker image: "recipes/build/docker-image.md"
@@ -122,6 +120,7 @@ nav:
   - FAQs:
       - Moving from dev to prod: "faq/faq-build.md"
       - Troubleshooting: "faq/faq-troubleshooting.md"
+      - Feliz and Fable React: "faq/faq-felizandfable.md"
   - Learning Resources:
       - SAFE-Compatible UI Components: "awesome-safe-components.md"
       - Learning: "learning.md"
@@ -131,6 +130,9 @@ nav:
   - Support: "support.md"
   - Testimonials: "testimonials.md"
   - Legacy recipes (v4):
+      - Upgrading:
+          - Upgrade from V2 to V3: "v4-recipes/upgrading/v2-to-v3.md"
+          - Upgrade from V3 to V4: "v4-recipes/upgrading/v3-to-v4.md"
       - Build:
           - Add build automation: "v4-recipes/build/add-build-script.md"
           - Remove FAKE: "v4-recipes/build/remove-fake.md"

theme/partials/footer.html

@@ -9,11 +9,8 @@
 
     <!-- Link to previous page -->
     {% if page.previous_page %}
-    <a href="{{ page.previous_page.abs_url }}"
-      title="{{ page.previous_page.title }}"
-      class="md-footer__link md-footer__link--prev"
-      aria-label="{{ page.previous_page.title }}"
-      rel="prev">
+    <a href="{{ page.previous_page.abs_url }}" title="{{ page.previous_page.title }}"
+      class="md-footer__link md-footer__link--prev" aria-label="{{ page.previous_page.title }}" rel="prev">
       <div class="md-footer__button md-icon">
         <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24">
           <path d="M20 11v2H8l5.5 5.5-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5 8 11h12Z"></path>
@@ -32,11 +29,8 @@
 
     <!-- Link to next page -->
     {% if page.next_page %}
-    <a href="{{ page.next_page.abs_url }}"
-      title="{{ page.next_page.title }}"
-      class="md-footer__link md-footer__link--next"
-      aria-label="{{ page.next_page.title }}"
-      rel="next">
+    <a href="{{ page.next_page.abs_url }}" title="{{ page.next_page.title }}"
+      class="md-footer__link md-footer__link--next" aria-label="{{ page.next_page.title }}" rel="next">
       <div class="md-footer__title">
         <span class="md-footer__direction">
           {{ lang.t("footer.next") }}
@@ -63,17 +57,14 @@
       <!-- Copyright and theme information -->
       <div class="md-footer-copyright">
         Supported by
-        <a href="http://lambdafactory.pl">
-          λFactory</a>
-        and
         <a href="https://compositional-it.com/">
           Compositional IT</a>
       </div>
 
       <!-- Social links -->
       {% block social %}
-        {% include "partials/social.html" %}
+      {% include "partials/social.html" %}
       {% endblock %}
     </div>
   </div>
-</footer>
+</footer>