@3sln/dodo 0.0.5 → 0.0.6

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.6",
   "description": "A minimal, configurable virtual DOM library.",
   "main": "index.js",
   "type": "module",