Add docs and debugging option

packages/docs/src/en/plugins/morph.md

@@ -0,0 +1,251 @@
+---
+order: 5
+title: Morph
+description: Morph an element into the provided HTML
+graph_image: https://alpinejs.dev/social_morph.jpg
+---
+
+# Morph Plugin
+
+Alpine's Morph plugin allows you to "morph" an element on the page into the provided HTML template, all while preserving any browser or Alpine state within the "morphed" element.
+
+This is useful for updating HTML from a server request without loosing Alpine's on-page state. A utility like this is at the core of full-stack frameworks like [Laravel Livewire](https://laravel-livewire.com/) and [Phoenix LiveView](https://dockyard.com/blog/2018/12/12/phoenix-liveview-interactive-real-time-apps-no-need-to-write-javascript).
+
+The best way to understand its purpose is with the following interactive visualization. Give it a try!
+
+<!-- START_VERBATIM -->
+<div x-data="{ slide: 1 }" class="border rounded">
+    <div>
+        <img :src="'/img/morphs/morph'+slide+'.png'">
+    </div>
+
+    <div class="flex w-full justify-between" style="padding-bottom: 1rem">
+        <div class="w-1/2 px-4">
+            <button @click="slide = (slide === 1) ? 13 : slide - 1" class="w-full bg-brand rounded-full text-center py-3 font-bold text-white">Previous</button>
+        </div>
+        <div class="w-1/2 px-4">
+            <button @click="slide = (slide % 13) + 1" class="w-full bg-brand rounded-full text-center py-3 font-bold text-white">Next</button>
+        </div>
+    </div>
+</div>
+<!-- END_VERBATIM -->
+
+<a name="installation"></a>
+## Installation
+
+You can use this plugin by either including it from a `<script>` tag or installing it via NPM:
+
+### Via CDN
+
+You can include the CDN build of this plugin as a `<script>` tag, just make sure to include it BEFORE Alpine's core JS file.
+
+```alpine
+<!-- Alpine Plugins -->
+<script defer src="https://unpkg.com/@alpinejs/morph@3.x.x/dist/cdn.min.js"></script>
+
+<!-- Alpine Core -->
+<script defer src="https://unpkg.com/alpinejs@3.x.x/dist/cdn.min.js"></script>
+```
+
+### Via NPM
+
+You can install Morph from NPM for use inside your bundle like so:
+
+```shell
+npm install @alpinejs/morph
+```
+
+Then initialize it from your bundle:
+
+```js
+import Alpine from 'alpinejs'
+import morph from '@alpinejs/morph'
+
+Alpine.plugin(morph)
+
+...
+```
+
+<a name="alpine-morph"></a>
+## Alpine.morph()
+
+The `Alpine.morph(el, newHtml)` allows you to imperatively morph a dom node based on passed in HTML. It accepts the following parameters:
+
+| Parameter | Description |
+| ---       | --- |
+| `el`      | A DOM element on the page. |
+| `newHtml` | A string of HTML to use as the template to morph the dom element into. |
+| `options` (optional) | An options object used mainly for [injecting lifecycle hooks](#lifecycle-hooks). |
+
+Here's an example of using `Alpine.morph()` to update an Alpine component with new HTML: (In real apps, this new HTML would likely be coming from the server)
+
+```alpine
+<div x-data="{ message: 'Change me, then press the button!' }">
+    <input type="text" x-model="message"> 
+    <span x-text="message"></span> 
+</div>
+
+<button>Run Morph</button>
+
+<script>
+    document.querySelector('button').addEventListener('click', () => {
+        let el = document.querySelector('div')
+
+        Alpine.morph(el, `
+            <div x-data="{ message: 'Change me, then press the button!' }">
+                <h2>See how new elements have been added</h2>
+                
+                <input type="text" x-model="message"> 
+                <span x-text="message"></span> 
+
+                <h2>but the state of this component hasn't changed? Magical.</h2>
+            </div>
+        `)
+    })
+</script>
+```
+
+<!-- START_VERBATIM -->
+<div class="demo">
+    <div x-data="{ message: 'Change me, then press the button!' }" id="morph-demo-1" class="space-y-2">
+        <input type="text" x-model="message" class="w-full">
+        <span x-text="message"></span> 
+    </div>
+    
+    <button id="morph-button-1" class="mt-4">Run Morph</button>
+</div>
+
+<script>
+    document.querySelector('#morph-button-1').addEventListener('click', () => {
+        let el = document.querySelector('#morph-demo-1')
+
+        Alpine.morph(el, `
+            <div x-data="{ message: 'Change me, then press the button!' }" id="morph-demo-1" class="space-y-2">
+                <h4>See how new elements have been added</h4>
+                <input type="text" x-model="message" class="w-full"> 
+                <span x-text="message"></span> 
+                <h4>but the state of this component hasn't changed? Magical.</h4>
+            </div>
+        `)
+    })
+</script>
+<!-- END_VERBATIM -->
+
+<a name="lifecycle-hooks"></a>
+### Lifecycle Hooks
+
+The "Morph" plugin works by comparing two DOM trees, the live element, and the passed in HTML.
+
+Morph walks both trees simultaneusly and compares each node and its children. If it finds differences, it "patches" (changes) the current DOM tree to match the passed in HTML's tree.
+
+While the default algorithm is very capable, there are cases where you may want to hook into its lifecycle and observe or change its behavior as it's happening.
+
+Before we jump into the available Lifecycle hooks themselves, let's first list out all the potential parameters they receive and explain what each one is:
+
+| Parameter | Description |
+| ---       | --- |
+| `el` | This is always the actual, current, DOM element on the page that will be "patched" (changed by Morph). |
+| `toEl` | This is a "template element". It's a temporary element representing what the live `el` will be patched to. It will never actually live on the page and should only be used for reference purposes. |
+| `childrenOnly()` | This is a function that can be called inside the hook to tell Morph to skip the current element and only "patch" its children. |
+| `skip()` | A function that when called within the hook will "skip" comparing/patching itself and the children of the current element. |
+
+Here are the available lifecycle hooks (passed in as the third parameter to `Alpine.morph(..., options)`):
+
+| Option | Description |
+| ---       | --- |
+| `updating(el, toEl, childrenOnly, skip)` | Called before patching the `el` with the comparison `toEl`.  |
+| `updated(el, toEl)` | Called after Morph has patched `el`. |
+| `removing(el, skip)` | Called before Morph removes an element from the live DOM. |
+| `removed(el)` | Called after Morph has removed an element from the live DOM. |
+| `adding(el, sip)` | Called before adding a new element. |
+| `added(el)` | Called after adding a new element to the live DOM tree. |
+| `key(el)` | A re-usable function to determine how Morph "keys" elements in the tree before comparing/patching. [More on that here](#keys) |
+| `lookahead` | A boolean value telling Morph to enable an extra feature in its algorithm that "looks ahead" to make sure a DOM element that's about to be removed should instead just be "moved" to a later sibling. |
+
+Here is code of all these lifecycle hooks for a more concrete reference:
+
+```js
+Alpine.morph(el, newHtml, {
+    updating(el, toEl, childrenOnly, skip) {
+        //
+    },
+
+    updated(el, toEl) {
+        //
+    },
+
+    removing(el, skip) {
+        //
+    },
+
+    removed(el) {
+        //
+    },
+
+    adding(el, skip) {
+        //
+    },
+
+    added(el) {
+        //
+    },
+
+    key(el) {
+        // By default Alpine uses the `key=""` HTML attribute.
+        return el.id
+    },
+
+    lookahead: true, // Default: false
+})
+```
+
+<a name="keys"></a>
+### Keys
+
+Dom-diffing utilities like Morph try their best to accurately "morph" the original DOM into the new HTML. However, there are cases where it's impossible to determine if an element should be just changed, or replaced completely.
+
+Because of this limitation, Morph has a "key" system that allows developers to "force" preserving certain elements rather than replacing them.
+
+The most common use-case for them is a list of siblings within a loop. Below is an example of why keys are necessary sometimes:
+
+```html
+<!-- "Live" Dom on the page: -->
+<ul>
+    <li>Mark</li>
+    <li>Tom</li>
+    <li>Travis</li>
+</ul>
+
+<!-- New HTML to "morph to": -->
+<ul>
+    <li>Travis</li>
+    <li>Mark</li>
+    <li>Tom</li>
+</ul>
+```
+
+Given the above situation, Morph has no way to know that the "Travis" node has been moved in the DOM tree. It just thinks that "Mark" has been changed to "Travis" and "Travis" changed to "Tom".
+
+This is not what we actually want, we want Morph to preserve the original elements and instead of changing them, MOVE them within the `<ul>`.
+
+By adding keys to each node, we can accomplish this like so:
+
+```html
+<!-- "Live" Dom on the page: -->
+<ul>
+    <li key="1">Mark</li>
+    <li key="2">Tom</li>
+    <li key="3">Travis</li>
+</ul>
+
+<!-- New HTML to "morph to": -->
+<ul>
+    <li key="3">Travis</li>
+    <li key="1">Mark</li>
+    <li key="2">Tom</li>
+</ul>
+```
+
+Now that there are "keys" on the `<li>`s, Morph will match them in both trees and move them accordingly.
+
+You can configure what Morph considers a "key" with the `key:` configutation option. [More on that here](#lifecycle-hooks)

packages/morph/src/index.js

@@ -2,18 +2,6 @@ import { morph } from './morph'
 
 export default function (Alpine) {
     Alpine.morph = morph
-    
-    Alpine.directive('morph', (el, { expression }, { effect, evaluateLater }) => {
-        let evaluate = evaluateLater(expression)
-
-        effect(() => {
-            evaluate(value => {
-                let child = el.firstElementChild || el.firstChild || el.appendChild(document.createTextNode(''))
-
-                morph(child, value)
-            })
-        })
-    })
 }
 
 export { morph }

packages/morph/src/morph.js

@@ -1,5 +1,16 @@
+let resolveStep = () => {}
 
-export function morph(dom, toHtml, options) {
+let logger = () => {}
+
+function breakpoint(message) {
+    if (! debug) return
+
+    message && logger(message.replace('\n', '\\n'))
+   
+    return new Promise(resolve => resolveStep = () => resolve())
+}
+
+export async function morph(dom, toHtml, options) {
     assignOptions(options)
     
     let toEl = createElement(toHtml)
@@ -11,12 +22,19 @@ export function morph(dom, toHtml, options) {
         
         toEl._x_dataStack && window.Alpine.clone(dom, toEl)
     }
+    
+    await breakpoint()
 
     patch(dom, toEl)
 
     return dom
 }
 
+morph.step = () => resolveStep()
+morph.log = (theLogger) => {
+    logger = theLogger
+}
+
 let key
 ,lookahead
 ,updating
@@ -25,31 +43,37 @@ let key
 ,removed
 ,adding
 ,added
+,debug
 
 let noop = () => {}
 
 function assignOptions(options = {}) {
     let defaultGetKey = el => el.getAttribute('key')
 
-    key = options.key || defaultGetKey
-    lookahead = options.lookahead || false
     updating = options.updating || noop
     updated = options.updated || noop
     removing = options.removing || noop
     removed = options.removed || noop
     adding = options.adding || noop
     added = options.added || noop
+    key = options.key || defaultGetKey
+    lookahead = options.lookahead || true 
+    debug = options.debug || false
 }
 
 function createElement(html) {
     return document.createRange().createContextualFragment(html).firstElementChild
 }
 
-function patch(dom, to) {
-   if (dom.isEqualNode(to)) return
-
+async function patch(dom, to) {
+    if (dom.isEqualNode(to)) return
+   
     if (differentElementNamesTypesOrKeys(dom, to)) {
-        return patchElement(dom, to)
+        let result = patchElement(dom, to)
+        
+        await breakpoint('Swap elements')
+       
+        return result
     }
 
     let updateChildrenOnly = false
@@ -59,18 +83,19 @@ function patch(dom, to) {
     window.Alpine && initializeAlpineOnTo(dom, to, () => updateChildrenOnly = true)
 
     if (textOrComment(to)) {
-        patchNodeValue(dom, to)
+        await patchNodeValue(dom, to)
         updated(dom, to)
+        
         return
     }
 
     if (! updateChildrenOnly) {
-        patchAttributes(dom, to)
+        await patchAttributes(dom, to)
     }
 
     updated(dom, to)
 
-    patchChildren(dom, to)
+    await patchChildren(dom, to)
 }
 
 function differentElementNamesTypesOrKeys(dom, to) {
@@ -85,11 +110,11 @@ function textOrComment(el) {
 }
 
 function patchElement(dom, to) {
-    if(shouldSkip(removing, dom)) return
+    if (shouldSkip(removing, dom)) return
 
     let toCloned = to.cloneNode(true)
 
-    if(shouldSkip(adding, toCloned)) return
+    if (shouldSkip(adding, toCloned)) return
 
     dom.parentNode.replaceChild(toCloned, dom)
 
@@ -97,20 +122,22 @@ function patchElement(dom, to) {
     added(toCloned)
 }
 
-function patchNodeValue(dom, to) {
+async function patchNodeValue(dom, to) {
     let value = to.nodeValue
 
-    if (dom.nodeValue !== value) dom.nodeValue = value
+    if (dom.nodeValue !== value) {
+        dom.nodeValue = value
+
+        await breakpoint('Change text node to: ' + value)
+    }
 }
 
-function patchAttributes(dom, to) {
+async function patchAttributes(dom, to) {
     if (dom._x_isShown && ! to._x_isShown) {
         return
-        // dom._x_hide()
     }
     if (! dom._x_isShown && to._x_isShown) {
         return
-        // dom._x_show()
     }
 
     let domAttributes = Array.from(dom.attributes)
@@ -119,18 +146,26 @@ function patchAttributes(dom, to) {
     for (let i = domAttributes.length - 1; i >= 0; i--) {
         let name = domAttributes[i].name;
 
-        if (! to.hasAttribute(name)) dom.removeAttribute(name)
+        if (! to.hasAttribute(name)) {
+            dom.removeAttribute(name)
+           
+            await breakpoint('Remove attribute')
+        }
     }
 
     for (let i = toAttributes.length - 1; i >= 0; i--) {
         let name = toAttributes[i].name
         let value = toAttributes[i].value
 
-        if (dom.getAttribute(name) !== value) dom.setAttribute(name, value)
+        if (dom.getAttribute(name) !== value) {
+            dom.setAttribute(name, value)
+
+            await breakpoint(`Set [${name}] attribute to: "${value}"`)
+        }
     }
 }
 
-function patchChildren(dom, to) {
+async function patchChildren(dom, to) {
     let domChildren = dom.childNodes
     let toChildren = to.childNodes
 
@@ -153,9 +188,15 @@ function patchChildren(dom, to) {
 
                 dom.appendChild(holdover)
                 currentFrom = holdover
+
+                await breakpoint('Add element (from key)')
             } else {
-                addNodeTo(currentTo, dom)
+                let added = addNodeTo(currentTo, dom)
+
+                await breakpoint('Add element: ' + added.outerHTML || added.nodeValue)
+
                 currentTo = currentTo.nextSibling
+
                 continue
             }
         }
@@ -167,6 +208,8 @@ function patchChildren(dom, to) {
                 currentFrom = addNodeBefore(currentTo, currentFrom)
 
                 domKey = getKey(currentFrom)
+                
+                await breakpoint('Move element (lookahead)')
             }
         }
 
@@ -177,6 +220,9 @@ function patchChildren(dom, to) {
                 domKeyHoldovers[domKey].remove()
                 currentFrom = currentFrom.nextSibling
                 currentTo = currentTo.nextSibling
+
+                await breakpoint('No "to" key')
+
                 continue
             }
 
@@ -184,6 +230,8 @@ function patchChildren(dom, to) {
                 if (domKeyDomNodeMap[toKey]) {
                     currentFrom.parentElement.replaceChild(domKeyDomNodeMap[toKey], currentFrom)
                     currentFrom = domKeyDomNodeMap[toKey]
+                    
+                    await breakpoint('No "from" key')
                 }
             }
 
@@ -194,19 +242,24 @@ function patchChildren(dom, to) {
                 if (domKeyNode) {
                     currentFrom.parentElement.replaceChild(domKeyNode, currentFrom)
                     currentFrom = domKeyNode
+                    
+                    await breakpoint('Move "from" key')
                 } else {
                     domKeyHoldovers[domKey] = currentFrom
                     currentFrom = addNodeBefore(currentTo, currentFrom)
                     domKeyHoldovers[domKey].remove()
                     currentFrom = currentFrom.nextSibling
                     currentTo = currentTo.nextSibling
+                   
+                    await breakpoint('I dont even know what this does')
+                    
                     continue
                 }
             }
         }
 
         // Patch elements
-        patch(currentFrom, currentTo)
+        await patch(currentFrom, currentTo)
 
         currentTo = currentTo && currentTo.nextSibling
         currentFrom = currentFrom && currentFrom.nextSibling
@@ -219,6 +272,8 @@ function patchChildren(dom, to) {
 
             dom.removeChild(domForRemoval)
 
+            await breakpoint('remove el')
+
             removed(domForRemoval)
         }
 
@@ -259,6 +314,8 @@ function addNodeTo(node, parent) {
         parent.appendChild(clone);
 
         added(clone)
+
+        return clone
     }
 }