Add section "Minimize the scope of DOM updates" to "Advanced Topics" page

Author: Tao-VanJS

advanced.html

@@ -85,7 +85,21 @@ <h1 class="w3-padding-16 w3-xxxlarge">
   a: 1,
   b: 2,
 })
-</code></pre><p>More granular <code class="symbol">State</code> objects can help state bindings be more locally scoped, which make reactive UI updates more efficient by eliminating unnecessary DOM tree construction and replacement.</p><h3 class="w3-large w3-text-red" id="advanced-state-derivation"><a class="self-link" href="#advanced-state-derivation">Advanced state derivation</a></h3><blockquote><i>道生一，一生二，二生三，三生万物<br>(Tao derives one, one derives two, two derive three, and three derive everything)<br><br>-- 老子，道德经</i></blockquote><p>A broad set of advanced state derivation (derived states and side effects) can indeed be defined with <code class="symbol"><a href="/tutorial#api-derive" class="w3-hover-opacity">van.derive</a></code>, as illustrated in the following piece of code:</p><pre><code class="language-js">const fullName = van.state(localStorage.getItem("fullName") ?? "Tao Xin")
+</code></pre><p>More granular <code class="symbol">State</code> objects can help state bindings be more locally scoped, which make reactive UI updates more efficient by eliminating unnecessary DOM tree construction and replacement.</p><h3 class="w3-large w3-text-red" id="minimize-the-scope-of-dom-updates"><a class="self-link" href="#minimize-the-scope-of-dom-updates">Minimize the scope of DOM updates</a></h3><p>It's encouraged to organize your code in way that the scope of DOM updates is minimized upon the changes of <code class="symbol">State</code> objects. For instance, the 2 components below (<code class="symbol">Name1</code> and <code class="symbol">Name2</code>) are semantically equivalent:</p><pre><code class="language-js">const name = van.state("")
+
+const Name1 = () =&gt; div(() =&gt; name.val.trim().length === 0 ?
+  p("Please enter your name") :
+  p("Hello ", b(name)),
+)
+
+const Name2 = () =&gt; {
+  const isNameEmpty = van.derive(() =&gt; name.val.trim().length === 0)
+  return div(() =&gt; isNameEmpty.val ?
+    p("Please enter your name") :
+    p("Hello ", b(name)),
+  )
+}
+</code></pre><p>But <code class="symbol">Name2</code>'s implementation is more preferable. With <code class="symbol">Name1</code>'s implementation, the entire <code class="language-html">&lt;p&gt;</code> element will be refreshed whenever <code class="symbol">name</code> state is updated. This is because the entire <code class="language-html">&lt;p&gt;</code> element is bound to <code class="symbol">name</code> state as specified in the binding function. On the other hand, with <code class="symbol">Name2</code>'s implementation, the <code class="language-html">&lt;p&gt;</code> element is only refreshed when <code class="symbol">name</code> state is changed from empty to non-empty, or vice versa, as the <code class="language-html">&lt;p&gt;</code> element is bound to derived state - <code class="symbol">isNameEmpty</code>. For other changes to <code class="symbol">name</code> state, only the <code class="symbol">Text node</code> inside the <code class="language-html">&lt;b&gt;</code> element will be refreshed.</p><p><a href="https://jsfiddle.net/gh/get/library/pure/vanjs-org/vanjs-org.github.io/tree/master/jsfiddle/advanced/minimize-dom-updates">Try on jsfiddle</a></p><h3 class="w3-large w3-text-red" id="advanced-state-derivation"><a class="self-link" href="#advanced-state-derivation">Advanced state derivation</a></h3><blockquote><i>道生一，一生二，二生三，三生万物<br>(Tao derives one, one derives two, two derive three, and three derive everything)<br><br>-- 老子，道德经</i></blockquote><p>A broad set of advanced state derivation (derived states and side effects) can indeed be defined with <code class="symbol"><a href="/tutorial#api-derive" class="w3-hover-opacity">van.derive</a></code>, as illustrated in the following piece of code:</p><pre><code class="language-js">const fullName = van.state(localStorage.getItem("fullName") ?? "Tao Xin")
 
 // State persistence with `localStorage`
 van.derive(() =&gt; localStorage.setItem("fullName", fullName.val))
@@ -206,7 +220,7 @@ <h1 class="w3-padding-16 w3-xxxlarge">
   return (renderPre.val ? pre : span)(text)
 })
 </code></pre><p>whenever <code class="symbol">renderPre</code> is toggled, a new <code class="symbol">text</code> state will be created and subscribe to changes of the <code class="symbol">prefix</code> state. However, the derivation from <code class="symbol">prefix</code> to the previous <code class="symbol">text</code> state will be garbage collected as the derivation was created while executing a binding function whose result DOM node no longer connects to the document tree. This is the mechanism to avoid memory leaks caused by state derivations that hold onto memory indefinitely.</p><p><a href="/code/gc-derive" class="w3-hover-opacity">Try out the example here</a> (You can use developer console to watch <code class="symbol">prefix</code>'s <code class="symbol">_listeners</code>).</p></div>
-        <aside id="toc"><ul><li><a href="#dom-attributes-vs-properties" class="w3-hover-opacity">DOM Attributes vs. Properties</a></li><li><a href="#state-and-state-binding" class="w3-hover-opacity">State and State Binding</a><ul><li><a href="#why-not-dom-valued-states" class="w3-hover-opacity">Why can't states have DOM node as values?</a></li><li><a href="#state-granularity" class="w3-hover-opacity">State granularity</a></li><li><a href="#advanced-state-derivation" class="w3-hover-opacity">Advanced state derivation</a></li><li><a href="#conditional-state-binding" class="w3-hover-opacity">Conditional state binding</a></li><li><a href="#self-referencing-in-side-effects" class="w3-hover-opacity">Self-referencing in side effects</a></li></ul></li><li><a href="#gc" class="w3-hover-opacity">Garbage Collection</a><ul><li><a href="#avoid-your-bindings-to-be-gc-ed-unexpectedly" class="w3-hover-opacity">Avoid your bindings to be GC-ed unexpectedly</a></li><li><a href="#derived-states-and-side-effects-registered-inside-a-binding-function" class="w3-hover-opacity">Derived states and side effects registered inside a binding function</a></li></ul></li></ul></aside>
+        <aside id="toc"><ul><li><a href="#dom-attributes-vs-properties" class="w3-hover-opacity">DOM Attributes vs. Properties</a></li><li><a href="#state-and-state-binding" class="w3-hover-opacity">State and State Binding</a><ul><li><a href="#why-not-dom-valued-states" class="w3-hover-opacity">Why can't states have DOM node as values?</a></li><li><a href="#state-granularity" class="w3-hover-opacity">State granularity</a></li><li><a href="#minimize-the-scope-of-dom-updates" class="w3-hover-opacity">Minimize the scope of DOM updates</a></li><li><a href="#advanced-state-derivation" class="w3-hover-opacity">Advanced state derivation</a></li><li><a href="#conditional-state-binding" class="w3-hover-opacity">Conditional state binding</a></li><li><a href="#self-referencing-in-side-effects" class="w3-hover-opacity">Self-referencing in side effects</a></li></ul></li><li><a href="#gc" class="w3-hover-opacity">Garbage Collection</a><ul><li><a href="#avoid-your-bindings-to-be-gc-ed-unexpectedly" class="w3-hover-opacity">Avoid your bindings to be GC-ed unexpectedly</a></li><li><a href="#derived-states-and-side-effects-registered-inside-a-binding-function" class="w3-hover-opacity">Derived states and side effects registered inside a binding function</a></li></ul></li></ul></aside>
       </div>
     </div>
     <script>

advanced/index.html

@@ -85,7 +85,21 @@ <h1 class="w3-padding-16 w3-xxxlarge">
   a: 1,
   b: 2,
 })
-</code></pre><p>More granular <code class="symbol">State</code> objects can help state bindings be more locally scoped, which make reactive UI updates more efficient by eliminating unnecessary DOM tree construction and replacement.</p><h3 class="w3-large w3-text-red" id="advanced-state-derivation"><a class="self-link" href="#advanced-state-derivation">Advanced state derivation</a></h3><blockquote><i>道生一，一生二，二生三，三生万物<br>(Tao derives one, one derives two, two derive three, and three derive everything)<br><br>-- 老子，道德经</i></blockquote><p>A broad set of advanced state derivation (derived states and side effects) can indeed be defined with <code class="symbol"><a href="/tutorial#api-derive" class="w3-hover-opacity">van.derive</a></code>, as illustrated in the following piece of code:</p><pre><code class="language-js">const fullName = van.state(localStorage.getItem("fullName") ?? "Tao Xin")
+</code></pre><p>More granular <code class="symbol">State</code> objects can help state bindings be more locally scoped, which make reactive UI updates more efficient by eliminating unnecessary DOM tree construction and replacement.</p><h3 class="w3-large w3-text-red" id="minimize-the-scope-of-dom-updates"><a class="self-link" href="#minimize-the-scope-of-dom-updates">Minimize the scope of DOM updates</a></h3><p>It's encouraged to organize your code in way that the scope of DOM updates is minimized upon the changes of <code class="symbol">State</code> objects. For instance, the 2 components below (<code class="symbol">Name1</code> and <code class="symbol">Name2</code>) are semantically equivalent:</p><pre><code class="language-js">const name = van.state("")
+
+const Name1 = () =&gt; div(() =&gt; name.val.trim().length === 0 ?
+  p("Please enter your name") :
+  p("Hello ", b(name)),
+)
+
+const Name2 = () =&gt; {
+  const isNameEmpty = van.derive(() =&gt; name.val.trim().length === 0)
+  return div(() =&gt; isNameEmpty.val ?
+    p("Please enter your name") :
+    p("Hello ", b(name)),
+  )
+}
+</code></pre><p>But <code class="symbol">Name2</code>'s implementation is more preferable. With <code class="symbol">Name1</code>'s implementation, the entire <code class="language-html">&lt;p&gt;</code> element will be refreshed whenever <code class="symbol">name</code> state is updated. This is because the entire <code class="language-html">&lt;p&gt;</code> element is bound to <code class="symbol">name</code> state as specified in the binding function. On the other hand, with <code class="symbol">Name2</code>'s implementation, the <code class="language-html">&lt;p&gt;</code> element is only refreshed when <code class="symbol">name</code> state is changed from empty to non-empty, or vice versa, as the <code class="language-html">&lt;p&gt;</code> element is bound to derived state - <code class="symbol">isNameEmpty</code>. For other changes to <code class="symbol">name</code> state, only the <code class="symbol">Text node</code> inside the <code class="language-html">&lt;b&gt;</code> element will be refreshed.</p><p><a href="https://jsfiddle.net/gh/get/library/pure/vanjs-org/vanjs-org.github.io/tree/master/jsfiddle/advanced/minimize-dom-updates">Try on jsfiddle</a></p><h3 class="w3-large w3-text-red" id="advanced-state-derivation"><a class="self-link" href="#advanced-state-derivation">Advanced state derivation</a></h3><blockquote><i>道生一，一生二，二生三，三生万物<br>(Tao derives one, one derives two, two derive three, and three derive everything)<br><br>-- 老子，道德经</i></blockquote><p>A broad set of advanced state derivation (derived states and side effects) can indeed be defined with <code class="symbol"><a href="/tutorial#api-derive" class="w3-hover-opacity">van.derive</a></code>, as illustrated in the following piece of code:</p><pre><code class="language-js">const fullName = van.state(localStorage.getItem("fullName") ?? "Tao Xin")
 
 // State persistence with `localStorage`
 van.derive(() =&gt; localStorage.setItem("fullName", fullName.val))
@@ -206,7 +220,7 @@ <h1 class="w3-padding-16 w3-xxxlarge">
   return (renderPre.val ? pre : span)(text)
 })
 </code></pre><p>whenever <code class="symbol">renderPre</code> is toggled, a new <code class="symbol">text</code> state will be created and subscribe to changes of the <code class="symbol">prefix</code> state. However, the derivation from <code class="symbol">prefix</code> to the previous <code class="symbol">text</code> state will be garbage collected as the derivation was created while executing a binding function whose result DOM node no longer connects to the document tree. This is the mechanism to avoid memory leaks caused by state derivations that hold onto memory indefinitely.</p><p><a href="/code/gc-derive" class="w3-hover-opacity">Try out the example here</a> (You can use developer console to watch <code class="symbol">prefix</code>'s <code class="symbol">_listeners</code>).</p></div>
-        <aside id="toc"><ul><li><a href="#dom-attributes-vs-properties" class="w3-hover-opacity">DOM Attributes vs. Properties</a></li><li><a href="#state-and-state-binding" class="w3-hover-opacity">State and State Binding</a><ul><li><a href="#why-not-dom-valued-states" class="w3-hover-opacity">Why can't states have DOM node as values?</a></li><li><a href="#state-granularity" class="w3-hover-opacity">State granularity</a></li><li><a href="#advanced-state-derivation" class="w3-hover-opacity">Advanced state derivation</a></li><li><a href="#conditional-state-binding" class="w3-hover-opacity">Conditional state binding</a></li><li><a href="#self-referencing-in-side-effects" class="w3-hover-opacity">Self-referencing in side effects</a></li></ul></li><li><a href="#gc" class="w3-hover-opacity">Garbage Collection</a><ul><li><a href="#avoid-your-bindings-to-be-gc-ed-unexpectedly" class="w3-hover-opacity">Avoid your bindings to be GC-ed unexpectedly</a></li><li><a href="#derived-states-and-side-effects-registered-inside-a-binding-function" class="w3-hover-opacity">Derived states and side effects registered inside a binding function</a></li></ul></li></ul></aside>
+        <aside id="toc"><ul><li><a href="#dom-attributes-vs-properties" class="w3-hover-opacity">DOM Attributes vs. Properties</a></li><li><a href="#state-and-state-binding" class="w3-hover-opacity">State and State Binding</a><ul><li><a href="#why-not-dom-valued-states" class="w3-hover-opacity">Why can't states have DOM node as values?</a></li><li><a href="#state-granularity" class="w3-hover-opacity">State granularity</a></li><li><a href="#minimize-the-scope-of-dom-updates" class="w3-hover-opacity">Minimize the scope of DOM updates</a></li><li><a href="#advanced-state-derivation" class="w3-hover-opacity">Advanced state derivation</a></li><li><a href="#conditional-state-binding" class="w3-hover-opacity">Conditional state binding</a></li><li><a href="#self-referencing-in-side-effects" class="w3-hover-opacity">Self-referencing in side effects</a></li></ul></li><li><a href="#gc" class="w3-hover-opacity">Garbage Collection</a><ul><li><a href="#avoid-your-bindings-to-be-gc-ed-unexpectedly" class="w3-hover-opacity">Avoid your bindings to be GC-ed unexpectedly</a></li><li><a href="#derived-states-and-side-effects-registered-inside-a-binding-function" class="w3-hover-opacity">Derived states and side effects registered inside a binding function</a></li></ul></li></ul></aside>
       </div>
     </div>
     <script>

jsfiddle/advanced/minimize-dom-updates/demo.details

@@ -0,0 +1,9 @@
+/*
+---
+authors:
+  - Tao Xin
+resources:
+  - https://cdn.jsdelivr.net/gh/vanjs-org/van/public/van-1.4.0.nomodule.min.js
+panel_js: 2
+...
+*/

jsfiddle/advanced/minimize-dom-updates/demo.js

@@ -0,0 +1,36 @@
+const {b, div, i, input, p} = van.tags
+
+const name = van.state("")
+
+const Name1 = () => {
+  const numRendered = van.state(0)
+  return div(
+    () => {
+      ++numRendered.val
+      return name.val.trim().length === 0 ?
+        p("Please enter your name") :
+        p("Hello ", b(name))
+    },
+    p(i("The <p> element has been rendered ", numRendered, " time(s).")),
+  )
+}
+
+const Name2 = () => {
+  const numRendered = van.state(0)
+  const isNameEmpty = van.derive(() => name.val.trim().length === 0)
+  return div(
+    () => {
+      ++numRendered.val
+      return isNameEmpty.val ?
+        p("Please enter your name") :
+        p("Hello ", b(name))
+    },
+    p(i("The <p> element has been rendered ", numRendered, " time(s).")),
+  )
+}
+
+van.add(document.body,
+  p("Your name is: ", input({type: "text", value: name, oninput: e => name.val = e.target.value})),
+  Name1(),
+  Name2(),
+)

minimize-dom-updates-tracking.code.js

@@ -0,0 +1,36 @@
+const {b, div, i, input, p} = van.tags
+
+const name = van.state("")
+
+const Name1 = () => {
+  const numRendered = van.state(0)
+  return div(
+    () => {
+      ++numRendered.val
+      return name.val.trim().length === 0 ?
+        p("Please enter your name") :
+        p("Hello ", b(name))
+    },
+    p(i("The <p> element has been rendered ", numRendered, " time(s).")),
+  )
+}
+
+const Name2 = () => {
+  const numRendered = van.state(0)
+  const isNameEmpty = van.derive(() => name.val.trim().length === 0)
+  return div(
+    () => {
+      ++numRendered.val
+      return isNameEmpty.val ?
+        p("Please enter your name") :
+        p("Hello ", b(name))
+    },
+    p(i("The <p> element has been rendered ", numRendered, " time(s).")),
+  )
+}
+
+van.add(document.body,
+  p("Your name is: ", input({type: "text", value: name, oninput: e => name.val = e.target.value})),
+  Name1(),
+  Name2(),
+)

minimize-dom-updates.code.js

@@ -0,0 +1,14 @@
+const name = van.state("")
+
+const Name1 = () => div(() => name.val.trim().length === 0 ?
+  p("Please enter your name") :
+  p("Hello ", b(name)),
+)
+
+const Name2 = () => {
+  const isNameEmpty = van.derive(() => name.val.trim().length === 0)
+  return div(() => isNameEmpty.val ?
+    p("Please enter your name") :
+    p("Hello ", b(name)),
+  )
+}

sitegen/advanced.ts

@@ -41,6 +41,12 @@ export default (doc: HTMLDocument) => {
 })
 `),
     p("More granular ", Symbol("State"), " objects can help state bindings be more locally scoped, which make reactive UI updates more efficient by eliminating unnecessary DOM tree construction and replacement."),
+    H3("Minimize the scope of DOM updates"),
+    p("It's encouraged to organize your code in way that the scope of DOM updates is minimized upon the changes of ", Symbol("State"), " objects. For instance, the 2 components below (", Symbol("Name1"), " and ", Symbol("Name2"), ") are semantically equivalent:"),
+    JsFile("minimize-dom-updates.code.js"),
+    p("But ", Symbol("Name2"), "'s implementation is more preferable. With ", Symbol("Name1"), "'s implementation, the entire ", InlineHtml("<p>"), " element will be refreshed whenever ", Symbol("name"), " state is updated. This is because the entire ", InlineHtml("<p>"), " element is bound to ", Symbol("name"), " state as specified in the binding function. On the other hand, with ", Symbol("Name2"), "'s implementation, the ", InlineHtml("<p>"), " element is only refreshed when ", Symbol("name"), " state is changed from empty to non-empty, or vice versa, as the ", InlineHtml("<p>"), " element is bound to derived state - ", Symbol("isNameEmpty"), ". For other changes to ", Symbol("name"), " state, only the ", Symbol("Text node"), " inside the ", InlineHtml("<b>"), " element will be refreshed."),
+    JsFile("minimize-dom-updates-tracking.code.js", {}, {hidden: true}),
+    p({id: "jsfiddle-minimize-dom-updates"}),
     H3("Advanced state derivation"),
     Quote({text: ["道生一，一生二，二生三，三生万物", br(), "(Tao derives one, one derives two, two derive three, and three derive everything)"], source: "老子，道德经"}),
     p("A broad set of advanced state derivation (derived states and side effects) can indeed be defined with ", SymLink("van.derive", "/tutorial#api-derive"), ", as illustrated in the following piece of code:"),