Merge pull request #688 from fable-hub/v3/rework_memo

V3/rework memo

Author: Freymaurer

README.md

@@ -37,12 +37,12 @@ root.render (Counter())
 ### ✨ Features
 
  - Flexible **API design**: Combine the reliability of F# type safety with the flexibility to interop easily with native JavaScript.
- - Discoverable **attributes** with no more functions, `Html` attributes or css properties globally available so they are easy to find.
+ - Discoverable **attributes** with no more functions, `Html` attributes or CSS properties globally available so they are easy to find.
  - Proper **documentation**: each attribute and CSS property
  - Full **React API** support: Feliz aims to support the React API for building components using hooks, context and more.
  - Fully **Type-safe**: no more `Margin of obj` but instead utilizing a plethora of overloaded functions to account for the overloaded nature of `CSS` attributes, covering 90%+ of the CSS styles, values and properties.
  - **Compatible** with [Femto](https://github.com/Zaid-Ajaj/Femto).
- - Approximately **Zero** bundle size increase where everything function body is erased from the generated javascript unless you actually use said function.
+ - Approximately **Zero** bundle size increase where everything function body is erased from the generated JavaScript unless you actually use said function.
 
 ### 🚀 Quick Start
 
@@ -63,4 +63,4 @@ npm start
 
 ### 📚 Documentation
 
-Feliz has extensive documentation at [https://zaid-ajaj.github.io/Feliz](https://zaid-ajaj.github.io/Feliz) with live examples along side code samples, check them out and if you have any question, let us know!
+Feliz has extensive documentation at [https://zaid-ajaj.github.io/Feliz](https://zaid-ajaj.github.io/Feliz) with live examples alongside code samples, check them out and if you have any question, let us know!

docs/docs/api-docs/feliz/react-component.mdx

@@ -192,40 +192,105 @@ import ReactComponentImport from '../../feliz-docs/fableoutput/Examples/Feliz/Re
 
 React `memo` components can be created using the `[<ReactMemoComponent>]` attribute. It works the same way as `[<ReactComponent>]`, but wraps the component in `React.memo` and ensures that it is defined as a `const` in the generated JavaScript code.
 
-<Tabs>
+import MemoAttribute from '../../feliz-docs/fableoutput/Examples/React/MemoAttribute'
+import RawMemoAttribute from '!!raw-loader!../../feliz-docs/Examples/React/MemoAttribute.fs'
 
-<TabItem value="F#" label="F#">
+<ComponentRender code={RawMemoAttribute}>
+  <MemoAttribute />
+</ComponentRender>
+
+### areEqual with js emit
+
+You can pass a custom equality function to the `[<ReactMemoComponent>]` attribute using the `areEqual` parameter. The value must be a JavaScript function expressed as a string. This function will be used to determine whether the component should re-render based on its props.
 
 ```fsharp
-[<ReactMemoComponent>]
-let Component(text: string, count: int) =
-    Html.div [
-        for i in 1 .. count do
-            Html.p [
-                prop.key i
-                prop.text (sprintf "%d: %s" i text)
-            ]
-    ]
+[<ReactMemoComponent("(prevProps, nextProps) => 
+    prevProps.fruits.length === nextProps.fruits.length 
+    && prevProps.fruits.every((value, index) => 
+        value === nextProps.fruits[index]
+    )"
+)>]
+let RenderTextWithEffect (fruits: string []) =
+```
+
+This behavior is similiar to the `[<Emit>]` attribute in Fable. 
+
+:::info
+`areEqual` is implemented using the `[<StringSyntax("javascript")>]` attribute. This will provide syntax highlighting and basic validation in supported editors.
+
+<details>
+<summary>Example: Rider</summary>
+
+
+import RiderStringSyntax from '../../../static/img/rider-stringsyntax-attribute.png'
+
+<img src={RiderStringSyntax} alt="Rider StringSyntax Attribute" />;
+
+
+</details>
+
+:::
+
+:::danger
+The areEqual functions runs on the transformed js output, so you must assume, that your params are passed as a single object containing all props!
+:::
+
+import MemoAttributeAreEqualEmit from '../../feliz-docs/fableoutput/Examples/React/MemoAttributeAreEqualEmit'
+import RawMemoAttributeAreEqualEmit from '!!raw-loader!../../feliz-docs/Examples/React/MemoAttributeAreEqualEmit.fs'
+
+<ComponentRender code={RawMemoAttributeAreEqualEmit}>
+  <MemoAttributeAreEqualEmit />
+</ComponentRender>
+
+### areEqual with F# function
+
+We can also emit a call to a f# function defined in the same file. This function must have the correct signature to be used as an equality function.
 
+```fsharp
+let areEqualFn prop1 prop2 =
+    prop1 = prop2
+
+[<ReactMemoComponent(nameof areEqualFn)>] // or "areEqualFn"
+let RenderTextWithEffect (fruits: string []) =
+    React.useEffect (fun () -> console.log("Rerender!") )
+    Html.div [ 
+        prop.text (fruits |> String.concat ", "); 
+        prop.testId "memo-attribute" 
+    ]
 ```
 
-</TabItem>
+:::info
+This works as f# equality does not check reference equality for arrays and sequences, but checks the content of them. Which is what is used by shallow comparison of React.memo.
+:::
 
-<TabItem value="JSX" label="JSX">
+:::danger
+The areEqual functions runs on the transformed js output, so you must assume, that your params are passed as a single object containing all props!
+
+In the example above, if you want to compare the `fruits` prop, you need to access it as `prop1.fruits` and `prop2.fruits` in the `areEqualFn` function:
 
-```jsx
-export const Component = memo((componentInputProps) => {
-    const count = componentInputProps.count;
-    const text = componentInputProps.text;
-    // ... 
-});
+```fsharp
+let areEqualFn (prop1: {|fruits: string []|}) (prop2: {|fruits: string []|}) =
+    prop1.fruits = prop2.fruits
 ```
+:::
 
-</TabItem>
+:::danger[Name Mangling]
+If you define your equality function as static member or inside a module, Fable might mangle the name of the function during transpilation. In this case, you need to provide the mangled name to the `areEqual` parameter. You can see this behavior int his [Fable Repl](https://fable.io/repl/#?code=PYBwpgdgBAYghgIwDZgHQGFgCcwChcC2wAJgK4pQCiAjqXEgJYAuAnjNALy5Q9QpNQ4OGnSTsoILKACMEqSABMULr1VyZy9Yvz8oAD00Q4BMMABmVWvWZsIqIWBH1xAehdQAzgAtg5YlAQwAC5LURt2AH0HJzEIfFZwUOtWdnQkOA8PWRVeDyY4JgYAYygTAkCsQWErWK1ZSVAlHLU6zQbtXF0WQ2NTCxjwiDSMrPtq0Vd3AZSh9MzpKPHnCCA&html=Q&css=Q).
 
+```fsharp
+module EqualityFn =
+    let areEqualFn prop1 prop2 =
+        prop1 = prop2
+```
+:::
 
-</Tabs>
+import MemoAttributeAreEqualFnEmit from '../../feliz-docs/fableoutput/Examples/React/MemoAttributeAreEqualEmitFnName'
+import RawMemoAttributeAreEqualFnEmit from '!!raw-loader!../../feliz-docs/Examples/React/MemoAttributeAreEqualEmitFnName.fs'
+import RawMemoAttributeAreEqualFnEmitJS from '!!raw-loader!../../feliz-docs/fableoutput/Examples/React/MemoAttributeAreEqualEmitFnName.jsx'
 
+<ComponentRender code={[{language: 'fsharp', fileName: 'MemoAttributeAreEqualEmitFnName.fs', content: RawMemoAttributeAreEqualFnEmit}, {language: 'jsx', fileName: 'MemoAttributeAreEqualEmitFnName.jsx', content: RawMemoAttributeAreEqualFnEmitJS}]}>
+  <MemoAttributeAreEqualFnEmit />
+</ComponentRender>
 
 ## `[<ReactLazyComponent>]`
 

docs/docs/api-docs/guides/fable.mdx

@@ -13,6 +13,10 @@ import TabItem from '@theme/TabItem';
 
 The following is a collection of short guides and tips for common pitfalls when using Fable for frontend development. Feel free to checkout the categories on the in-page table of contents in the sidebar and navigate to the topic you are interested in.
 
+:::info[Fable]
+More on Fable can be found in the ecosystem section [here](../../ecosystem/01_Tools/Fable.mdx). 
+:::
+
 :::tip[Fable official docs]
 
 Altough I might repeat some of the content here, I highly recommend you to check out the [official Fable JavaScript documentation](https://fable.io/docs/javascript/features.html). It contains a lot of useful information.

docs/docs/api-docs/react/apis/memo.mdx

@@ -11,15 +11,58 @@ import ReactRefAdmonition from '@site/src/components/ReactRefAdmonition';
 
 `React.memo` lets you optimize components by memoizing their output. This prevents unnecessary rerenders when the props haven't changed, improving performance for pure components.
 
+Without memoization, a component will rerender whenever its parent rerenders, even if its props remain the same. By wrapping a component with `React.memo`, React will skip rendering the component and reuse the last rendered output if the props are unchanged.
+
+## ReactMemoComponentAttribute
+
+The `[<ReactMemoComponent>]` attribute provides a convenient way to memoize functional components in Feliz. It does the transformation on transpile level so you don't have to wrap your component manually.
+
 ```fsharp
 [<ReactMemoComponent>] // memoizes component to prevent rerender whenever parent rerenders
 let ChildComponent (onClick: unit -> unit) = 
     // ... component implementation
 ```
 
-import UseCallback from '../../../feliz-docs/fableoutput/Examples/React/UseCallback'
-import RawUseCallback from '!!raw-loader!../../../feliz-docs/Examples/React/UseCallback.fs'
+Check out the [ReactMemoComponentAttribute documentation](../../feliz/react-component.mdx) for more details.
+
+import MemoAttribute from '../../../feliz-docs/fableoutput/Examples/React/MemoAttribute'
+import RawMemoAttribute from '!!raw-loader!../../../feliz-docs/Examples/React/MemoAttribute.fs'
+
+<ComponentRender code={RawMemoAttribute}>
+  <MemoAttribute />
+</ComponentRender>
+
+## React.memo function
+
+:::warning
+This approach has several limitations compared to using the `[<ReactMemoComponent>]` attribute (see example below):
+- You must use a `let` binding for your component, to ensure Fable transpiling as `const`.
+- You must use any F# type transpiling to a JavaScript object for props (e.g., anonymous record, `[<PojoAttribute>]`).
+:::
+
+```fsharp
+let MemoizedComponent =
+    React.memo<{|text: string|}> (fun props ->
+    // ... component implementation
+    )
+```
+
+import MemoFunction from '../../../feliz-docs/fableoutput/Examples/React/MemoFunction'
+import RawMemoFunction from '!!raw-loader!../../../feliz-docs/Examples/React/MemoFunction.fs'
+
+<ComponentRender code={RawMemoFunction}>
+  <MemoFunction />
+</ComponentRender>
+
+## areEqual 
+
+The `React.memo` function also accepts an optional second argument, `areEqual`, which is a custom comparison function for props. This function receives the previous and next props and should return `true` if they are equal (i.e., no rerender needed) or `false` if they are different (i.e., rerender needed).
+
+This is useful as memo only does a shallow comparison of props by default. If your props are complex objects or arrays, you may need to provide a custom comparison function to accurately determine equality.
+
+import MemoFunctionAreEqual from '../../../feliz-docs/fableoutput/Examples/React/MemoFunctionAreEqual'
+import RawMemoFunctionAreEqual from '!!raw-loader!../../../feliz-docs/Examples/React/MemoFunctionAreEqual.fs'
 
-<ComponentRender code={RawUseCallback}>
-  <UseCallback />
+<ComponentRender code={RawMemoFunctionAreEqual}>
+  <MemoFunctionAreEqual />
 </ComponentRender>

docs/docs/feliz-docs/Examples/React/MemoAttribute.fs

@@ -0,0 +1,36 @@
+module Example.MemoAttribute
+
+open Feliz
+open Browser.Dom
+
+[<ReactMemoComponent>]
+let RenderTextWithEffect (text: string) =
+    React.useEffect (fun () -> console.log("Rerender!", text) )
+    Html.div [ 
+        prop.text text; 
+        prop.testId "memo-attribute" 
+    ]
+
+
+[<ReactComponent(true)>]
+let Main () =
+    let isDark, setIsDark = React.useState(false)
+    let text, setText = React.useState("Hello, world!")
+    let fgColor = if isDark then color.white else color.black
+    let bgColor = if isDark then color.black else color.white
+    Html.div [
+        prop.style [style.border(1, borderStyle.solid, fgColor); style.padding 20; style.color fgColor; style.backgroundColor bgColor]
+        prop.children [
+            Html.h3 "Check the output in the browser console"
+            Html.p "The child component below is memoized using the [<ReactMemoComponent>] attribute. It only rerenders when its props change."
+            Html.button [
+                prop.text "Toggle Dark Mode"
+                prop.onClick (fun _ -> setIsDark(not isDark))
+            ]
+            Html.input [
+                prop.value text
+                prop.onChange setText
+            ]
+            RenderTextWithEffect(text)
+        ]
+    ]

docs/docs/feliz-docs/Examples/React/MemoAttributeAreEqualEmit.fs

@@ -0,0 +1,56 @@
+module Example.MemoAttributeAreEqualEmit
+
+open Feliz
+open Browser.Dom
+
+[<ReactMemoComponent("(prevProps, nextProps) => 
+    prevProps.fruits.length === nextProps.fruits.length 
+    && prevProps.fruits.every((value, index) => 
+        value === nextProps.fruits[index]
+    )"
+)>]
+let RenderTextWithEffect (fruits: string []) =
+    React.useEffect (fun () -> console.log("Rerender!") )
+    Html.div [ 
+        prop.text (fruits |> String.concat ", "); 
+        prop.testId "memo-attribute" 
+    ]
+
+[<ReactComponent(true)>]
+let Main () =
+    let isDark, setIsDark = React.useState(false)
+    let input, setInput = React.useState("")
+    // This will stay the same array if it does not change 
+    let fruits, setFruits = React.useState([|"apple"; "orange"; "banana"|])
+    // This creates a new array reference on every render, triggering a rerender of the child component, without custom equality check
+    let sortedFruits = 
+        fruits 
+        |> Array.sort 
+    let isValidInput = System.String.IsNullOrEmpty input |> not && fruits |> Array.contains input |> not
+    let fgColor = if isDark then color.white else color.black
+    let bgColor = if isDark then color.black else color.white
+    Html.div [
+        prop.style [style.border(1, borderStyle.solid, fgColor); style.padding 20; style.color fgColor; style.backgroundColor bgColor]
+        prop.children [
+            Html.h3 "Check the output in the browser console"
+            Html.p "The child component below is memoized using the [<ReactMemoComponent>] attribute. It only rerenders when the areEqual function returns false."
+            Html.button [
+                prop.text "Toggle Dark Mode"
+                prop.onClick (fun _ -> setIsDark(not isDark))
+            ]
+            Html.input [
+                prop.value input
+                prop.onChange setInput
+            ]
+            Html.button [
+                prop.text "Change Fruits Array"
+                prop.disabled (not isValidInput)
+                prop.onClick (fun _ ->
+                    if isValidInput then
+                        [|yield! fruits; input|] |> setFruits
+                        setInput ""
+                )
+            ]
+            RenderTextWithEffect(sortedFruits)
+        ]
+    ]

docs/docs/feliz-docs/Examples/React/MemoAttributeAreEqualEmitFnName.fs

@@ -0,0 +1,54 @@
+module Example.MemoAttributeAreEqualEmitFnName
+
+open Feliz
+open Browser.Dom
+
+let areEqualFn prop1 prop2 =
+    prop1 = prop2
+
+[<ReactMemoComponent(nameof areEqualFn)>] // or "areEqualFn"
+let RenderTextWithEffect (fruits: string []) =
+    React.useEffect (fun () -> console.log("Rerender!") )
+    Html.div [ 
+        prop.text (fruits |> String.concat ", "); 
+        prop.testId "memo-attribute" 
+    ]
+
+[<ReactComponent(true)>]
+let Main () =
+    let isDark, setIsDark = React.useState(false)
+    let input, setInput = React.useState("")
+    // This will stay the same array if it does not change 
+    let fruits, setFruits = React.useState([|"apple"; "orange"; "banana"|])
+    // This creates a new array reference on every render, triggering a rerender of the child component, without custom equality check
+    let sortedFruits = 
+        fruits 
+        |> Array.sort 
+    let isValidInput = System.String.IsNullOrEmpty input |> not && fruits |> Array.contains input |> not
+    let fgColor = if isDark then color.white else color.black
+    let bgColor = if isDark then color.black else color.white
+    Html.div [
+        prop.style [style.border(1, borderStyle.solid, fgColor); style.padding 20; style.color fgColor; style.backgroundColor bgColor]
+        prop.children [
+            Html.h3 "Check the output in the browser console"
+            Html.p "The child component below is memoized using the [<ReactMemoComponent>] attribute. It only rerenders when the areEqual function returns false."
+            Html.button [
+                prop.text "Toggle Dark Mode"
+                prop.onClick (fun _ -> setIsDark(not isDark))
+            ]
+            Html.input [
+                prop.value input
+                prop.onChange setInput
+            ]
+            Html.button [
+                prop.text "Change Fruits Array"
+                prop.disabled (not isValidInput)
+                prop.onClick (fun _ ->
+                    if isValidInput then
+                        [|yield! fruits; input|] |> setFruits
+                        setInput ""
+                )
+            ]
+            RenderTextWithEffect(sortedFruits)
+        ]
+    ]