@3sln/dodo 0.0.4 → 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,113 +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
-
-- **VDOM Factory:** The library exports a `vdom(settings)` factory to create custom instances. The default export is a pre-configured instance.
-- **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/index.js

@@ -1,10 +1,131 @@
-import vdom from './src/vdom.js';
+import vdomFactory from './src/vdom.js';
+import htmlFactory from './src/html.js';
+import * as scheduler from './src/scheduler.js';
 
-// Create a default API instance by calling the factory with no settings.
-const {h, alias, special, reconcile, settings} = vdom();
+function dodoFactory(userSettings) {
+  const vdomInstance = vdomFactory(userSettings);
+  const htmlInstance = htmlFactory(vdomInstance);
+  return {
+    ...vdomInstance,
+    ...htmlInstance,
+    ...scheduler,
+  };
+}
 
-export {vdom, h, alias, special, reconcile, settings};
+const defaultDodo = dodoFactory();
 
-// Export all the HTML helpers.
-export * from './src/html.js';
-export {schedule, flush, clear} from './src/scheduler.js';
+export {vdomFactory as vdom, htmlFactory as html, dodoFactory as dodo};
+
+export const {
+  h,
+  alias,
+  special,
+  reconcile,
+  settings,
+  title,
+  meta,
+  link,
+  style,
+  script,
+  noscript,
+  address,
+  article,
+  aside,
+  footer,
+  header,
+  h1,
+  h2,
+  h3,
+  h4,
+  h5,
+  h6,
+  main,
+  nav,
+  section,
+  blockquote,
+  dd,
+  div,
+  dl,
+  dt,
+  figcaption,
+  figure,
+  hr,
+  li,
+  ol,
+  p,
+  pre,
+  ul,
+  a,
+  abbr,
+  b,
+  br,
+  cite,
+  code,
+  data,
+  del,
+  dfn,
+  em,
+  i,
+  ins,
+  kbd,
+  mark,
+  q,
+  s,
+  samp,
+  small,
+  span,
+  strong,
+  sub,
+  sup,
+  time,
+  u,
+  wbr,
+  area,
+  audio,
+  img,
+  map,
+  track,
+  video,
+  embed,
+  iframe,
+  object,
+  param,
+  picture,
+  portal,
+  source,
+  svg,
+  math,
+  canvas,
+  caption,
+  col,
+  colgroup,
+  table,
+  tbody,
+  td,
+  tfoot,
+  th,
+  thead,
+  tr,
+  button,
+  datalist,
+  fieldset,
+  form,
+  input,
+  label,
+  legend,
+  meter,
+  optgroup,
+  option,
+  output,
+  progress,
+  select,
+  textarea,
+  details,
+  dialog,
+  summary,
+  slot,
+  template,
+  schedule,
+  flush,
+  clear,
+} = defaultDodo;

package/package.json

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

package/src/html.js

@@ -1,128 +1,130 @@
-import {h} from '../index.js';
+export default function htmlFactory({h}) {
+  return {
+    // Document metadata
+    title: (...args) => h('title', ...args),
+    meta: props => h('meta', props),
+    link: props => h('link', props),
+    style: (...args) => h('style', ...args),
+    script: (...args) => h('script', ...args),
+    noscript: (...args) => h('noscript', ...args),
 
-// Document metadata
-export const title = (...args) => h('title', ...args);
-export const meta = props => h('meta', props);
-export const link = props => h('link', props);
-export const style = (...args) => h('style', ...args);
-export const script = (...args) => h('script', ...args);
-export const noscript = (...args) => h('noscript', ...args);
+    // Content sectioning
+    address: (...args) => h('address', ...args),
+    article: (...args) => h('article', ...args),
+    aside: (...args) => h('aside', ...args),
+    footer: (...args) => h('footer', ...args),
+    header: (...args) => h('header', ...args),
+    h1: (...args) => h('h1', ...args),
+    h2: (...args) => h('h2', ...args),
+    h3: (...args) => h('h3', ...args),
+    h4: (...args) => h('h4', ...args),
+    h5: (...args) => h('h5', ...args),
+    h6: (...args) => h('h6', ...args),
+    main: (...args) => h('main', ...args),
+    nav: (...args) => h('nav', ...args),
+    section: (...args) => h('section', ...args),
 
-// Content sectioning
-export const address = (...args) => h('address', ...args);
-export const article = (...args) => h('article', ...args);
-export const aside = (...args) => h('aside', ...args);
-export const footer = (...args) => h('footer', ...args);
-export const header = (...args) => h('header', ...args);
-export const h1 = (...args) => h('h1', ...args);
-export const h2 = (...args) => h('h2', ...args);
-export const h3 = (...args) => h('h3', ...args);
-export const h4 = (...args) => h('h4', ...args);
-export const h5 = (...args) => h('h5', ...args);
-export const h6 = (...args) => h('h6', ...args);
-export const main = (...args) => h('main', ...args);
-export const nav = (...args) => h('nav', ...args);
-export const section = (...args) => h('section', ...args);
+    // Text content
+    blockquote: (...args) => h('blockquote', ...args),
+    dd: (...args) => h('dd', ...args),
+    div: (...args) => h('div', ...args),
+    dl: (...args) => h('dl', ...args),
+    dt: (...args) => h('dt', ...args),
+    figcaption: (...args) => h('figcaption', ...args),
+    figure: (...args) => h('figure', ...args),
+    hr: () => h('hr'),
+    li: (...args) => h('li', ...args),
+    ol: (...args) => h('ol', ...args),
+    p: (...args) => h('p', ...args),
+    pre: (...args) => h('pre', ...args),
+    ul: (...args) => h('ul', ...args),
 
-// Text content
-export const blockquote = (...args) => h('blockquote', ...args);
-export const dd = (...args) => h('dd', ...args);
-export const div = (...args) => h('div', ...args);
-export const dl = (...args) => h('dl', ...args);
-export const dt = (...args) => h('dt', ...args);
-export const figcaption = (...args) => h('figcaption', ...args);
-export const figure = (...args) => h('figure', ...args);
-export const hr = () => h('hr');
-export const li = (...args) => h('li', ...args);
-export const ol = (...args) => h('ol', ...args);
-export const p = (...args) => h('p', ...args);
-export const pre = (...args) => h('pre', ...args);
-export const ul = (...args) => h('ul', ...args);
+    // Inline text semantics
+    a: (...args) => h('a', ...args),
+    abbr: (...args) => h('abbr', ...args),
+    b: (...args) => h('b', ...args),
+    br: () => h('br'),
+    cite: (...args) => h('cite', ...args),
+    code: (...args) => h('code', ...args),
+    data: (...args) => h('data', ...args),
+    del: (...args) => h('del', ...args),
+    dfn: (...args) => h('dfn', ...args),
+    em: (...args) => h('em', ...args),
+    i: (...args) => h('i', ...args),
+    ins: (...args) => h('ins', ...args),
+    kbd: (...args) => h('kbd', ...args),
+    mark: (...args) => h('mark', ...args),
+    q: (...args) => h('q', ...args),
+    s: (...args) => h('s', ...args),
+    samp: (...args) => h('samp', ...args),
+    small: (...args) => h('small', ...args),
+    span: (...args) => h('span', ...args),
+    strong: (...args) => h('strong', ...args),
+    sub: (...args) => h('sub', ...args),
+    sup: (...args) => h('sup', ...args),
+    time: (...args) => h('time', ...args),
+    u: (...args) => h('u', ...args),
+    wbr: () => h('wbr'),
 
-// Inline text semantics
-export const a = (...args) => h('a', ...args);
-export const abbr = (...args) => h('abbr', ...args);
-export const b = (...args) => h('b', ...args);
-export const br = () => h('br');
-export const cite = (...args) => h('cite', ...args);
-export const code = (...args) => h('code', ...args);
-export const data = (...args) => h('data', ...args);
-export const del = (...args) => h('del', ...args);
-export const dfn = (...args) => h('dfn', ...args);
-export const em = (...args) => h('em', ...args);
-export const i = (...args) => h('i', ...args);
-export const ins = (...args) => h('ins', ...args);
-export const kbd = (...args) => h('kbd', ...args);
-export const mark = (...args) => h('mark', ...args);
-export const q = (...args) => h('q', ...args);
-export const s = (...args) => h('s', ...args);
-export const samp = (...args) => h('samp', ...args);
-export const small = (...args) => h('small', ...args);
-export const span = (...args) => h('span', ...args);
-export const strong = (...args) => h('strong', ...args);
-export const sub = (...args) => h('sub', ...args);
-export const sup = (...args) => h('sup', ...args);
-export const time = (...args) => h('time', ...args);
-export const u = (...args) => h('u', ...args);
-export const wbr = () => h('wbr');
+    // Image and multimedia
+    area: props => h('area', props),
+    audio: (...args) => h('audio', ...args),
+    img: props => h('img', props),
+    map: (...args) => h('map', ...args),
+    track: props => h('track', props),
+    video: (...args) => h('video', ...args),
 
-// Image and multimedia
-export const area = props => h('area', props);
-export const audio = (...args) => h('audio', ...args);
-export const img = props => h('img', props);
-export const map = (...args) => h('map', ...args);
-export const track = props => h('track', props);
-export const video = (...args) => h('video', ...args);
+    // Embedded content
+    embed: props => h('embed', props),
+    iframe: (...args) => h('iframe', ...args),
+    object: (...args) => h('object', ...args),
+    param: props => h('param', props),
+    picture: (...args) => h('picture', ...args),
+    portal: (...args) => h('portal', ...args),
+    source: props => h('source', props),
 
-// Embedded content
-export const embed = props => h('embed', props);
-export const iframe = (...args) => h('iframe', ...args);
-export const object = (...args) => h('object', ...args);
-export const param = props => h('param', props);
-export const picture = (...args) => h('picture', ...args);
-export const portal = (...args) => h('portal', ...args);
-export const source = props => h('source', props);
+    // SVG and MathML
+    svg: (...args) => h('svg', ...args),
+    math: (...args) => h('math', ...args),
 
-// SVG and MathML
-export const svg = (...args) => h('svg', ...args);
-export const math = (...args) => h('math', ...args);
+    // Scripting
+    canvas: (...args) => h('canvas', ...args),
 
-// Scripting
-export const canvas = (...args) => h('canvas', ...args);
+    // Table content
+    caption: (...args) => h('caption', ...args),
+    col: props => h('col', props),
+    colgroup: (...args) => h('colgroup', ...args),
+    table: (...args) => h('table', ...args),
+    tbody: (...args) => h('tbody', ...args),
+    td: (...args) => h('td', ...args),
+    tfoot: (...args) => h('tfoot', ...args),
+    th: (...args) => h('th', ...args),
+    thead: (...args) => h('thead', ...args),
+    tr: (...args) => h('tr', ...args),
 
-// Table content
-export const caption = (...args) => h('caption', ...args);
-export const col = props => h('col', props);
-export const colgroup = (...args) => h('colgroup', ...args);
-export const table = (...args) => h('table', ...args);
-export const tbody = (...args) => h('tbody', ...args);
-export const td = (...args) => h('td', ...args);
-export const tfoot = (...args) => h('tfoot', ...args);
-export const th = (...args) => h('th', ...args);
-export const thead = (...args) => h('thead', ...args);
-export const tr = (...args) => h('tr', ...args);
+    // Forms
+    button: (...args) => h('button', ...args),
+    datalist: (...args) => h('datalist', ...args),
+    fieldset: (...args) => h('fieldset', ...args),
+    form: (...args) => h('form', ...args),
+    input: props => h('input', props),
+    label: (...args) => h('label', ...args),
+    legend: (...args) => h('legend', ...args),
+    meter: (...args) => h('meter', ...args),
+    optgroup: (...args) => h('optgroup', ...args),
+    option: (...args) => h('option', ...args),
+    output: (...args) => h('output', ...args),
+    progress: (...args) => h('progress', ...args),
+    select: (...args) => h('select', ...args),
+    textarea: (...args) => h('textarea', ...args),
 
-// Forms
-export const button = (...args) => h('button', ...args);
-export const datalist = (...args) => h('datalist', ...args);
-export const fieldset = (...args) => h('fieldset', ...args);
-export const form = (...args) => h('form', ...args);
-export const input = props => h('input', props);
-export const label = (...args) => h('label', ...args);
-export const legend = (...args) => h('legend', ...args);
-export const meter = (...args) => h('meter', ...args);
-export const optgroup = (...args) => h('optgroup', ...args);
-export const option = (...args) => h('option', ...args);
-export const output = (...args) => h('output', ...args);
-export const progress = (...args) => h('progress', ...args);
-export const select = (...args) => h('select', ...args);
-export const textarea = (...args) => h('textarea', ...args);
+    // Interactive elements
+    details: (...args) => h('details', ...args),
+    dialog: (...args) => h('dialog', ...args),
+    summary: (...args) => h('summary', ...args),
 
-// Interactive elements
-export const details = (...args) => h('details', ...args);
-export const dialog = (...args) => h('dialog', ...args);
-export const summary = (...args) => h('summary', ...args);
-
-// Web Components
-export const slot = (...args) => h('slot', ...args);
-export const template = (...args) => h('template', ...args);
+    // Web Components
+    slot: (...args) => h('slot', ...args),
+    template: (...args) => h('template', ...args),
+  };
+}