From 553fa52f06d3c6eec045b45233ca59a8c283de6c Mon Sep 17 00:00:00 2001 From: Isaac Abraham Date: Fri, 5 Jan 2024 16:18:36 +0000 Subject: [PATCH 1/7] Article about Feliz and Fable React --- docs/faq/faq-felizandfable.md | 75 +++++++++++++++++++ .../upgrading => v4-recipes}/v2-to-v3.md | 0 .../upgrading => v4-recipes}/v3-to-v4.md | 0 mkdocs.yml | 10 ++- theme/partials/footer.html | 21 ++---- 5 files changed, 87 insertions(+), 19 deletions(-) create mode 100644 docs/faq/faq-felizandfable.md rename docs/{recipes/upgrading => v4-recipes}/v2-to-v3.md (100%) rename docs/{recipes/upgrading => v4-recipes}/v3-to-v4.md (100%) diff --git a/docs/faq/faq-felizandfable.md b/docs/faq/faq-felizandfable.md new file mode 100644 index 000000000..d98282a7a --- /dev/null +++ b/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. \ No newline at end of file diff --git a/docs/recipes/upgrading/v2-to-v3.md b/docs/v4-recipes/v2-to-v3.md similarity index 100% rename from docs/recipes/upgrading/v2-to-v3.md rename to docs/v4-recipes/v2-to-v3.md diff --git a/docs/recipes/upgrading/v3-to-v4.md b/docs/v4-recipes/v3-to-v4.md similarity index 100% rename from docs/recipes/upgrading/v3-to-v4.md rename to docs/v4-recipes/v3-to-v4.md diff --git a/mkdocs.yml b/mkdocs.yml index 8c458ed00..27092316c 100644 --- a/mkdocs.yml +++ b/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" diff --git a/theme/partials/footer.html b/theme/partials/footer.html index 085062a6c..48e9d3e3b 100644 --- a/theme/partials/footer.html +++ b/theme/partials/footer.html @@ -9,11 +9,8 @@ {% if page.previous_page %} -
- λFactory - and Compositional IT
{% block social %} - {% include "partials/social.html" %} + {% include "partials/social.html" %} {% endblock %}
- + \ No newline at end of file From 16818da4d47d91da3746fae1f4ecac6a9a1e35be Mon Sep 17 00:00:00 2001 From: Isaac Abraham Date: Fri, 12 Jan 2024 13:04:41 +0000 Subject: [PATCH 2/7] Code sample fixes --- docs/faq/faq-felizandfable.md | 54 +++++++++++++++++------------------ 1 file changed, 26 insertions(+), 28 deletions(-) diff --git a/docs/faq/faq-felizandfable.md b/docs/faq/faq-felizandfable.md index d98282a7a..b94ce7630 100644 --- a/docs/faq/faq-felizandfable.md +++ b/docs/faq/faq-felizandfable.md @@ -8,18 +8,16 @@ In a nutshell Fable.React and Feliz are two F# libraries which perform a similar The main distinction between the two libraries is that Fable.React follows a layout as follows: ```fsharp -element [ attribute; attribute ] [ childElement; childElement ] +element [ prop; prop ] [ 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 +h1 [ Style [ Color "Tomato" ] ] [ + p [] [ text [ Value "Hello" ] [] ] // no props + p [] [ text [ Value "Another paragraph" ] [] ] // no props + h2 [ Style [ Color "Blue" ] ] [] // no child elements ] ``` @@ -30,46 +28,46 @@ Feliz adopts a different style, in which instead of an element having two lists, 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" ] +Html.h1 [ + prop.style [ style.color "Tomato" ] + prop.children [ + Html.p [ prop.text "Hello" ] + Html.p [ prop.text "Another paragraph" ] + Html.h2 [ prop.style [ style.backgroundColor "Blue" ] ] ] ] ``` -The `children` function is required when mixing and matching attributes and elements: +The `prop.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" +Html.h1 [ // this is fine - just props underneath h1 + prop.style [ style.color "Tomato" ] + prop.title "foo" ] -h1 [ // fine - just elements underneath h1 - p [ text "Hello" ] +Html.h1 [ // fine - just elements underneath h1 + Html.p [ prop.text "Hello" ] ] -h1 [ // not fine - can't mix and match attributes and elements - style "color:Tomato" - p [ text "Hello" ] +Html.h1 [ // not fine - can't mix and match attributes and elements + prop.style [ style.color "Tomato" ] + Html.p [ prop.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" ] - ] +Html.h1 [ // this is now fine + 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. -* 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. \ No newline at end of file +* 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. + +* Also see [My journey with Feliz | A comparison between Fable.React and Feliz](https://github.com/Zaid-Ajaj/Feliz/issues/155). \ No newline at end of file From bb76f3726232be80a84b2e73b22231af618b7101 Mon Sep 17 00:00:00 2001 From: Joost Kaptein Date: Fri, 27 Sep 2024 17:00:40 +0200 Subject: [PATCH 3/7] remove redundant `text [ Value...` code in setting p text --- docs/faq/faq-felizandfable.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/faq/faq-felizandfable.md b/docs/faq/faq-felizandfable.md index b94ce7630..7fffbb1bb 100644 --- a/docs/faq/faq-felizandfable.md +++ b/docs/faq/faq-felizandfable.md @@ -15,8 +15,8 @@ For example: ```fsharp h1 [ Style [ Color "Tomato" ] ] [ - p [] [ text [ Value "Hello" ] [] ] // no props - p [] [ text [ Value "Another paragraph" ] [] ] // no props + p [] [ str "Hello" ] // no props + p [] [ str "Another paragraph" ] // no props h2 [ Style [ Color "Blue" ] ] [] // no child elements ] ``` From 86a00f9fc3a597bc66aafbd6302ba25f95c396d0 Mon Sep 17 00:00:00 2001 From: Joost Kaptein Date: Fri, 27 Sep 2024 17:04:51 +0200 Subject: [PATCH 4/7] Showcase Html.p string overload --- docs/faq/faq-felizandfable.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/faq/faq-felizandfable.md b/docs/faq/faq-felizandfable.md index 7fffbb1bb..ee8fef83a 100644 --- a/docs/faq/faq-felizandfable.md +++ b/docs/faq/faq-felizandfable.md @@ -32,7 +32,7 @@ Html.h1 [ prop.style [ style.color "Tomato" ] prop.children [ Html.p [ prop.text "Hello" ] - Html.p [ prop.text "Another paragraph" ] + Html.p "Another paragraph" Html.h2 [ prop.style [ style.backgroundColor "Blue" ] ] ] ] From 53864d711a08e45de00dffb3dfeca1faad628b97 Mon Sep 17 00:00:00 2001 From: Joost Kaptein Date: Fri, 27 Sep 2024 17:06:54 +0200 Subject: [PATCH 5/7] simplify comment about interoperability of Fable.React and Feliz --- docs/faq/faq-felizandfable.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/faq/faq-felizandfable.md b/docs/faq/faq-felizandfable.md index ee8fef83a..4ca74d3f5 100644 --- a/docs/faq/faq-felizandfable.md +++ b/docs/faq/faq-felizandfable.md @@ -68,6 +68,7 @@ Html.h1 [ // this is now fine ## 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. +* 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). \ No newline at end of file From d59c9892a38ba9c15ebec855dc485010a229e8ae Mon Sep 17 00:00:00 2001 From: Joost Kaptein Date: Fri, 27 Sep 2024 17:10:44 +0200 Subject: [PATCH 6/7] make prop.children snippet a bit more compact --- docs/faq/faq-felizandfable.md | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/docs/faq/faq-felizandfable.md b/docs/faq/faq-felizandfable.md index 4ca74d3f5..558fb2815 100644 --- a/docs/faq/faq-felizandfable.md +++ b/docs/faq/faq-felizandfable.md @@ -54,12 +54,9 @@ Html.h1 [ // not fine - can't mix and match attributes and elements prop.style [ style.color "Tomato" ] Html.p [ prop.text "Hello" ] ] -``` - -In order to allow both attributes and elements in the same list, Feliz introduces the `children` node: -```fsharp -Html.h1 [ // this is now fine +Html.h1 [ + // fine, adding props, and adding children using prop.children prop.style [ style.color "Tomato" ] prop.children [ Html.p [ prop.text "Hello" ] ] ] From 36377cc15fd047b9a241c49afa422100fb767360 Mon Sep 17 00:00:00 2001 From: Joost Kaptein Date: Fri, 27 Sep 2024 17:19:19 +0200 Subject: [PATCH 7/7] consistent placement of comments --- docs/faq/faq-felizandfable.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/faq/faq-felizandfable.md b/docs/faq/faq-felizandfable.md index 558fb2815..0a4123978 100644 --- a/docs/faq/faq-felizandfable.md +++ b/docs/faq/faq-felizandfable.md @@ -55,8 +55,7 @@ Html.h1 [ // not fine - can't mix and match attributes and elements Html.p [ prop.text "Hello" ] ] -Html.h1 [ - // fine, adding props, and adding children using prop.children +Html.h1 [ // fine, adding props, and adding children using prop.children prop.style [ style.color "Tomato" ] prop.children [ Html.p [ prop.text "Hello" ] ] ]