@3sln/dodo 0.0.5 → 0.0.7

package/README.md

@@ -1,12 +1,26 @@
-# dodo
+# Dodo
 
 > [!WARNING]
 > This is a work-in-progress project and is not yet ready for production use.
 
 A minimal, configurable virtual DOM library.
 
+## Documentation
+
+For detailed documentation, live demos, and advanced usage examples, please check out the [Dodo Deck](https://dodo.3sln.com).
+
 ## Quick Start
 
+Installation:
+```shell
+npm install @3sln/dodo
+# or
+bun add @3sln/dodo
+# or
+yarn add @3sln/dodo
+```
+
+Basic usage:
 ```javascript
 import { reconcile, h1, p, div } from '@3sln/dodo';
 
@@ -16,118 +30,9 @@ const container = document.getElementById('root');
 // The props object is optional.
 const myVdom = div({ id: 'app' },
   h1('Hello, dodo!'),
-  p({ $classes: ['text-lg'] }, 'This is a paragraph.')
+  p('This is a paragraph.')
 );
 
 // Reconcile the virtual DOM with the real DOM.
 reconcile(container, [myVdom]);
-```
-
-## Core Concepts
-
-## Core Concepts
-
-- **Factories for Customization:** Dodo is built around a factory pattern. While you can import and use a pre-configured default instance, you can also create custom instances for advanced use cases (like interoperating with ClojureScript). The library exports three factories:
-    - `dodo(settings)`: A unified factory that returns a complete API with VDOM functions, HTML helpers, and the scheduler.
-    - `vdom(settings)`: Creates just the core VDOM API (`h`, `alias`, `special`, `reconcile`, `settings`).
-    - `html({ h })`: Creates the HTML helper functions (`div`, `p`, etc.) bound to a specific `h` function.
-- **HTML Helpers:** Simple functions like `div()`, `p()`, `span()` are exported for convenience.
-- **`$`-Prefixed Props:** Special props that `dodo` intercepts are prefixed with a `$` to avoid conflicts with standard properties (e.g., `$classes`, `$styling`, `$attrs`, `$dataset`).
-- **`.key()`:** Chain `.key('unique-id')` to any VNode in a list to enable efficient, keyed reconciliation.
-- **`.on()`:** Chain `.on({ event: handler })` to any VNode to attach event listeners or lifecycle hooks (`$attach`, `$detach`, `$update`).
-- **`.opaque()`**: Marks an element node as opaque, meaning `dodo` will manage its props but not its children.
-
-## Keys for List Reconciliation
-
-When rendering lists of elements, always use the `.key()` method to ensure efficient updates and reordering.
-
-```javascript
-import { reconcile, div } from '@3sln/dodo';
-
-const data = [{id: 1, text: 'A'}, {id: 2, text: 'B'}, {id: 3, text: 'C'}];
-const container = document.getElementById('list');
-
-// Chain .key() to the VNode returned by the helper function.
-reconcile(container, data.map(item => div(item.text).key(item.id)));
-```
-
-## Event Listeners and Lifecycle Hooks
-
-Use the `.on()` method to attach event listeners and lifecycle hooks.
-
-```javascript
-import { reconcile, button } from '@3sln/dodo';
-
-const myButton = button('Hover over me').on({
-  // Simple function handler
-  mouseover: () => console.log('Mouse entered!'),
-  
-  // Object handler for more options
-  mouseleave: {
-    listener: () => console.log('Mouse left!'),
-    capture: true
-  },
-
-  // Lifecycle hooks
-  $attach: (domNode) => console.log('Button node was created.'),
-  $detach: (domNode) => console.log('Button has been removed.')
-});
-
-const container = document.getElementById('event-container');
-reconcile(container, myButton);
-reconcile(container, null); // Triggers $detach
-```
-
-## Understanding `reconcile()`
-
-The `reconcile` function has two distinct modes of operation:
-
--   **`reconcile(target, vnode)` (Onto):** Modifies the `target` element itself to match the `vnode`. This requires the `target`'s tag name to be compatible with the `vnode`'s tag (unless the `vnode` is an `alias` or `special`).
-
--   **`reconcile(target, [vnodes...])` (Into):** Modifies the *children* of the `target` element to match the array of `vnodes`. The `target` element's own properties are not changed.
-
--   **`reconcile(target, null)` (Cleanup):** Detaches `dodo` from the `target` and its descendants, running all necessary cleanup logic.
-
-## Advanced: Web Components with `special`
-
-The `special` component is a powerful tool for integrating with other libraries or, as shown here, for providing the rendering logic for a standard Web Component.
-
-```javascript
-import { reconcile, special, p, h, alias } from '@3sln/dodo';
-
-// 1. Create a special component to manage a shadow root.
-const shadowComponent = special({
-  attach: (domNode) => {
-    // Create a shadow root on the host element once.
-    domNode.attachShadow({ mode: 'open' });
-  },
-  update: (domNode, newContent) => {
-    // Reconcile the provided content into the shadow root.
-    reconcile(domNode.shadowRoot, newContent);
-  }
-});
-
-// 2. Define a standard Web Component class.
-class MyComponent extends HTMLElement {
-  connectedCallback() {
-    // When the element is added to the DOM, render the special component ONTO it.
-    // Pass some initial content into the special component's `update` hook.
-    reconcile(this, shadowComponent(p('Hello from inside a web component!')));
-  }
-
-  disconnectedCallback() {
-    // When the element is removed, clean up the dodo instance.
-    reconcile(this, null);
-  }
-  
-  // You can add attributeChangedCallback, properties, etc.
-  // to re-reconcile with new content.
-}
-
-// 3. Register the custom element.
-customElements.define('my-component', MyComponent);
-
-// 4. Use your new custom element with dodo!
-const container = document.getElementById('my-component-container');
-reconcile(container, h('my-component'));
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@3sln/dodo",
-  "version": "0.0.5",
+  "version": "0.0.7",
   "description": "A minimal, configurable virtual DOM library.",
   "main": "index.js",
   "type": "module",

package/src/vdom.js

@@ -13,7 +13,7 @@ class VNode {
   }
 
   key(k) {
-    this.key = k;
+    this.k = k;
     return this;
   }
 
@@ -525,35 +525,33 @@ export default userSettings => {
 
   function cleanupTarget(target) {
     const state = target[NODE_STATE];
-    if (state) {
-      switch (state.vdom.type) {
-        case ELEMENT_NODE:
-          reconcileElementProps(target, {});
-          cleanupTargetChildren(target);
-          delete target[NODE_STATE];
-          break;
-        case OPAQUE_NODE:
-          reconcileElementProps(target, {});
-          delete target[NODE_STATE];
-          break;
-        case ALIAS_NODE:
-          cleanupTargetChildren(target);
-          delete target[NODE_STATE];
-          break;
-        case SPECIAL_NODE:
-          delete target[NODE_STATE];
-          try {
-            state.vdom.tag.detach?.(target);
-          } catch (err) {
-            console.error(err);
-          }
-          break;
-      }
-      try {
-        state.vdom.hooks?.$detach?.(target);
-      } catch (err) {
-        console.error(err);
+    if (!state) {
+      return;
+    }
+
+    const {vdom} = state;
+
+    if (vdom.hooks) {
+      reconcileListeners(target, EMPTY_MAP);
+    }
+
+    if (vdom.type === ELEMENT_NODE || vdom.type === OPAQUE_NODE) {
+      reconcileElementProps(target, EMPTY_MAP);
+    }
+
+    if (vdom.type === ELEMENT_NODE || vdom.type === ALIAS_NODE) {
+      cleanupTargetChildren(target);
+    }
+
+    delete target[NODE_STATE];
+
+    try {
+      if (vdom.type === SPECIAL_NODE) {
+        vdom.tag.detach?.(target);
       }
+      vdom.hooks?.$detach?.(target);
+    } catch (err) {
+      console.error(err);
     }
   }
 
@@ -581,17 +579,17 @@ export default userSettings => {
 
       let oldNodesPoolForTag = oldVNodeNodesPool.get(vdom.tag);
       if (!oldNodesPoolForTag) {
-        oldNodesPoolForTag = {nodesForKey: new Map(), nodesWithoutKey: []};
+        oldNodesPoolForTag = {nodesForKey: newMap({}), nodesWithoutKey: []};
         oldVNodeNodesPool.set(vdom.tag, oldNodesPoolForTag);
       }
 
-      if (vdom.key !== undefined) {
-        let oldNodesPoolForKey = oldNodesPoolForTag.nodesForKey.get(vdom.key);
+      if (vdom.k !== undefined) {
+        let oldNodesPoolForKey = mapGet(oldNodesPoolForTag.nodesForKey, vdom.k);
         if (oldNodesPoolForKey === undefined) {
           oldNodesPoolForKey = [];
-          oldNodesPoolForTag.nodesForKey.set(vdom.key, oldNodesPoolForKey);
         }
         oldNodesPoolForKey.push(oldChild);
+        oldNodesPoolForTag.nodesForKey = mapPut(oldNodesPoolForTag.nodesForKey, vdom.k, oldNodesPoolForKey);
       } else {
         oldNodesPoolForTag.nodesWithoutKey.push(oldChild);
       }
@@ -605,15 +603,15 @@ export default userSettings => {
         if (!oldNodesPoolForTag) {
           newDomNode = createNode(target, newVdom);
         } else {
-          const key = newVdom.key;
+          const key = newVdom.k;
           if (key !== undefined) {
-            const pool = oldNodesPoolForTag.nodesForKey.get(key);
+            const pool = mapGet(oldNodesPoolForTag.nodesForKey, key);
             if (pool && pool.length > 0) {
               newDomNode = pool.shift();
               const state = newDomNode[NODE_STATE];
               if (shouldUpdate(state.vdom.args, newVdom.args)) {
                 if (state.vdom.hooks || newVdom.hooks) {
-                  reconcileListeners(target, newVdom.hooks);
+                  reconcileListeners(newDomNode, newVdom.hooks);
                 }
                 state.newVdom = newVdom;
               }
@@ -627,7 +625,7 @@ export default userSettings => {
               const state = newDomNode[NODE_STATE];
               if (shouldUpdate(state.vdom.args, newVdom.args)) {
                 if (state.vdom.hooks || newVdom.hooks) {
-                  reconcileListeners(target, newVdom.hooks);
+                  reconcileListeners(newDomNode, newVdom.hooks);
                 }
                 state.newVdom = newVdom;
               }