Article about Feliz and Fable React

docs/faq/faq-felizandfable.md

@@ -0,0 +1,70 @@
+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 [ prop; prop ] [ childElement; childElement ]
+```
+
+For example:
+
+```fsharp
+h1 [ Style [ Color "Tomato" ] ] [
+    p [] [ str "Hello" ] // no props
+    p [] [ str "Another paragraph" ] // no props
+    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
+Html.h1 [
+    prop.style [ style.color "Tomato" ]
+    prop.children [
+        Html.p [ prop.text "Hello" ]
+        Html.p "Another paragraph"
+        Html.h2 [ prop.style [ style.backgroundColor "Blue" ] ]
+    ]
+]
+```
+
+The `prop.children` function is required when mixing and matching attributes and elements:
+
+```fsharp
+Html.h1 [ // this is fine - just props underneath h1
+    prop.style [ style.color "Tomato" ]
+    prop.title "foo"
+]
+
+Html.h1 [ // fine - just elements underneath h1
+    Html.p [ prop.text "Hello" ]
+]
+
+Html.h1 [ // not fine - can't mix and match attributes and elements
+    prop.style [ style.color "Tomato" ]
+    Html.p [ prop.text "Hello" ]
+]
+
+Html.h1 [ // fine, adding props, and adding children using prop.children
+    prop.style [ style.color "Tomato" ]
+    prop.children [ Html.p [ prop.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.
+* Fable.React and Feliz can be mixed into your application if required (for progressive migration for example)
+
+
+* Also see [My journey with Feliz | A comparison between Fable.React and Feliz](https://github.com/Zaid-Ajaj/Feliz/issues/155).

mkdocs.yml

@@ -76,10 +76,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"
@@ -132,6 +130,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"
@@ -141,6 +140,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>