@pfern/elements 0.1.2 → 0.1.4

package/README.md

@@ -1,6 +1,7 @@
 # Elements.js
 
-A minimalist declarative UI toolkit designed around purity, immutability, and HTML semantics.
+Elements.js is a minimalist declarative UI toolkit designed around purity,
+immutability, and HTML semantics.
 
 ## Features
 
@@ -14,7 +15,8 @@ A minimalist declarative UI toolkit designed around purity, immutability, and HT
 
 ## Why Elements.js?
 
-Modern frameworks introduced declarative UI—but buried it beneath lifecycle hooks, mutable state, and complex diffing algorithms.
+Modern frameworks introduced declarative UI—but buried it beneath lifecycle
+hooks, mutable state, and complex diffing algorithms.
 
 **Elements.js goes further:**
 
@@ -36,7 +38,8 @@ Yes. Elements.js proves it.
 * No lifecycle methods or effects
 * Every component is a function
 
-To update a view: just **call the function again** with new arguments. The DOM subtree is replaced in place.
+To update a view: just **call the function again** with new arguments. The DOM
+subtree is replaced in place.
 
 ### State lives in the DOM
 
@@ -49,23 +52,22 @@ The DOM node *is the history*. Input state is passed as an argument.
 * No transpilation step
 * No reactive graph to debug
 
-Elements.js embraces the full truth of each function call as the only valid state.
+Elements.js embraces the full truth of each function call as the only valid
+state.
 
 ---
 
 ## Example: Counter
 
 ```js
-import { div, pre, button, component, render } from './elements.js';
+import { button, component, div, output } from '@pfern/elements'
 
-const counter = component((count = 0) =>
+export const counter = component((count = 0) =>
   div(
-    pre(count),
-    button({ onclick: () => counter(count + 1) }, 'Increment')
-  )
-)
-
-render(counter(), document.body);
+    output(count),
+    button(
+      { onclick: () => counter(count + 1) },
+      'Increment')))
 ```
 
 * Each click returns a new call to `counter(count + 1)`
@@ -77,30 +79,36 @@ render(counter(), document.body);
 ## Form Example: Todos App
 
 ```js
-import { button, div, component, form, input, li, span, ul } from './elements.js';
 
-export const todos = component((items = []) => {
-  const add = ({ todo: { value } }) =>
-    value && todos([...items, { value, done: false }])
+import { button, component, div,
+         form, input, li, span, ul } from '@pfern/elements'
+
+export const todos = component(
+  (items = [{ value: 'Add my first todo', done: true }]) => {
+
+    const add = ({ todo: { value } }) =>
+      value && todos([...items, { value, done: false }])
+
+    const remove = item =>
+      todos(items.filter(i => i !== item))
+
+    const toggle = item =>
+      todos(items.map(i => i === item ? { ...i, done: !item.done } : i))
+
+    return (
+      div({ class: 'todos' },
+
+        form({ onsubmit: add },
+          input({ name: 'todo', placeholder: 'What needs doing?' }),
+          button({ type: 'submit' }, 'Add')),
+
+        ul(...items.map(item =>
+          li(
+            { style:
+              { 'text-decoration': item.done ? 'line-through' : 'none' } },
+            span({ onclick: () => toggle(item) }, item.value),
+            button({ onclick: () => remove(item) }, '✕'))))))})
 
-  const remove = item =>
-    todos(items.filter(i => i !== item))
-
-  const toggle = item =>
-    todos(items.map(i => i === item ? { ...i, done: !item.done } : i))
-
-  return div({ class: 'todos' },
-    form({ onsubmit: add },
-      input({ name: 'todo', placeholder: 'What needs doing?' }),
-      button({ type: 'submit' }, 'Add')),
-    ul(...items.map(item =>
-      li({ style: { 'text-decoration': item.done ? 'line-through' : 'none' } },
-        span({ onclick: () => toggle(item) }, item.value),
-        button({ onclick: () => remove(item) }, '✕')
-      ))
-    )
-  )
-})
 ```
 
 This is a complete MVC-style app:
@@ -109,11 +117,17 @@ This is a complete MVC-style app:
 * Immutable
 * Pure
 
+You can view these examples live on [Github
+Pages](https://pfernandez.github.io/elements/) or by running them locally with
+`npm run dev`.
+
 ---
 
 ## Root Rendering Shortcut
 
-If you use `html`, `head`, or `body` as the top-level tag, `render()` will automatically mount into the corresponding document element—no need to pass a container.
+If you use `html`, `head`, or `body` as the top-level tag, `render()` will
+automatically mount into the corresponding document element—no need to pass a
+container.
 
 ```js
 import {
@@ -126,7 +140,8 @@ render(
   html(
     head(
       title('Elements.js'),
-      meta({ name: 'viewport', content: 'width=device-width, initial-scale=1.0' }),
+      meta({ name: 'viewport',
+             content: 'width=device-width, initial-scale=1.0' }),
       link({ rel: 'stylesheet', href: 'css/style.css' })
     ),
     body(
@@ -134,29 +149,29 @@ render(
       main(
         section(
           h2('Todos'),
-          todos()
-        )
-      )
-    )
-  )
-)
+          todos())))))
 ```
 
 ---
 
 ## Declarative Events
 
-All event listeners in Elements.js are pure functions. You can return a vnode from a listener to declaratively update the component tree—no mutation or imperative logic required.
+All event listeners in Elements.js are pure functions. You can return a vnode
+from a listener to declaratively update the component tree—- no mutation or
+imperative logic required.
 
 ### General Behavior
 
-* Any event handler (e.g. `onclick`, `onsubmit`, `oninput`) may return a new vnode to trigger a subtree replacement.
-* If the handler returns `undefined`, the event is treated as passive (no update occurs).
+* Any event handler (e.g. `onclick`, `onsubmit`, `oninput`) may return a new
+  vnode to trigger a subtree replacement.
+* If the handler returns `undefined`, the event is treated as passive (no update
+  occurs).
 * Returned vnodes are passed to `component()` to re-render declaratively.
 
 ### Form Events
 
-For `onsubmit`, `oninput`, and `onchange`, Elements.js provides a special signature:
+For `onsubmit`, `oninput`, and `onchange`, Elements.js provides a special
+signature:
 
 ```js
 (event.target.elements, event)
@@ -167,7 +182,8 @@ That is, your handler receives:
 1. `elements`: the HTML form’s named inputs
 2. `event`: the original DOM event object
 
-Elements.js will automatically call `event.preventDefault()` *only if* your handler returns a vnode.
+Elements.js will automatically call `event.preventDefault()` *only if* your
+handler returns a vnode.
 
 ```js
 form({
@@ -176,7 +192,8 @@ form({
 })
 ```
 
-If the handler returns nothing, `preventDefault()` is skipped and the form submits natively.
+If the handler returns nothing, `preventDefault()` is skipped and the form
+submits natively.
 
 ---
 
@@ -188,7 +205,8 @@ Wrap a recursive pure function that returns a vnode.
 
 ### `render(vnode[, container])`
 
-Render a vnode into the DOM. If `vnode[0]` is `html`, `head`, or `body`, no `container` is required.
+Render a vnode into the DOM. If `vnode[0]` is `html`, `head`, or `body`, no
+`container` is required.
 
 ### DOM Elements
 
@@ -201,17 +219,23 @@ svg({ width: 100 }, circle({ r: 10 }))
 
 ### TypeScript & JSDoc
 
-Each tag function (e.g. `div`, `button`, `svg`) includes a `@typedef` and MDN-sourced description to:
+Each tag function (e.g. `div`, `button`, `svg`) includes a `@typedef` and
+MDN-sourced description to:
 
 * Provide editor hints
 * Encourage accessibility and semantic markup
 * Enable intelligent autocomplete
 
+### Testing Philosophy
+
+Elements are data-in, data-out only, so mocking and headless browsers like
+`jsdom` are unnecessary out of the box. See the tests [in this
+repository](test/README.md) for some examples.
+
 ---
 
 ## Status
 
-* ✅ Production-ready core
 * 🧪 Fully tested (data-in/data-out behavior)
 * ⚡ Under 2kB min+gzip
 * ✅ Node and browser compatible

package/elements.js

@@ -61,14 +61,14 @@ const diffTree = (a, b) => {
   }
 }
 
-
 /**
  * Compares the children of two vnodes and returns patch list.
  *
  * @param {Array} aChildren - Previous vnode children
  * @param {Array} bChildren - New vnode children
  * @returns {Array} patches - One per child node
- */const diffChildren = (aChildren, bChildren) => {
+ */
+const diffChildren = (aChildren, bChildren) => {
   const patches = []
   const len = Math.max(aChildren.length, bChildren.length)
   for (let i = 0; i < len; i++) {
@@ -85,6 +85,8 @@ const diffTree = (a, b) => {
  *   *if* the listener returns a vnode (to support declarative form updates).
  * - Handlers for these event types receive `(elements, event)` as arguments,
  *   where `elements` is `event.target.elements` if available.
+ * - Async handlers are supported: if the listener returns a Promise,
+ *   it will be awaited and the resulting vnode (if any) will be rendered.
  *
  * @param {HTMLElement} el - The DOM element to receive props
  * @param {Object} props - Attributes and event listeners to assign
@@ -92,7 +94,7 @@ const diffTree = (a, b) => {
 const assignProperties = (el, props) =>
   Object.entries(props).forEach(([key, value]) => {
     if (key.startsWith('on') && typeof value === 'function') {
-      el[key] = (...args) => {
+      el[key] = async (...args) => {
         let target = el
         while (target && !target.__root) target = target.parentNode
         if (!target) return
@@ -102,9 +104,9 @@ const assignProperties = (el, props) =>
           const isFormEvent = /^(oninput|onsubmit|onchange)$/.test(key)
           const elements = isFormEvent && event?.target?.elements || null
 
-          const result = isFormEvent
+          const result = await (isFormEvent
             ? value.call(el, elements, event)
-            : value.call(el, event)
+            : value.call(el, event))
 
           if (isFormEvent && result !== undefined) {
             event.preventDefault()
@@ -119,11 +121,12 @@ const assignProperties = (el, props) =>
 
           if (DEBUG && result !== undefined && !Array.isArray(result)) {
             isFormEvent && event.preventDefault()
-            DEBUG && console.warn(
-              `Listener '${key}' on <${el.tagName.toLowerCase()}> returned "${result}".\n`
-                + 'If you intended a UI update, return a vnode array like: div({}, ...).\n'
-                + 'Otherwise, return undefined (or nothing) for native event listener behavior.'
-            )
+            DEBUG
+              && console.warn(
+                `Listener '${key}' on <${el.tagName.toLowerCase()}> returned "${result}".\n`
+                  + 'If you intended a UI update, return a vnode array like: div({}, ...).\n'
+                  + 'Otherwise, return undefined (or nothing) for native event listener behavior.'
+              )
           }
 
           if (Array.isArray(result)) {
@@ -153,8 +156,10 @@ const assignProperties = (el, props) =>
           el.setAttribute(key, value)
         }
       } catch {
-        DEBUG && console.warn(
-          `Illegal DOM property assignment for ${el.tagName}: ${key}: ${value}`)
+        DEBUG
+          && console.warn(
+            `Illegal DOM property assignment for ${el.tagName}: ${key}: ${value}`
+          )
       }
     }
   })
@@ -194,9 +199,12 @@ const renderTree = (node, isRoot = true) => {
   }
 
   let el =
-    tag === 'html' ? document.documentElement
-      : tag === 'head' ? document.head
-        : tag === 'body' ? document.body
+    tag === 'html'
+      ? document.documentElement
+      : tag === 'head'
+        ? document.head
+        : tag === 'body'
+          ? document.body
           : svgTagNames.includes(tag)
             ? document.createElementNS(svgNS, tag)
             : document.createElement(tag)
@@ -311,88 +319,232 @@ export const component = fn => {
 
 const htmlTagNames = [
   // Document metadata
-  'html', 'head', 'base', 'link', 'meta', 'title',
+  'html',
+  'head',
+  'base',
+  'link',
+  'meta',
+  'title',
 
   // Sections
-  'body', 'header', 'hgroup', 'nav', 'main', 'section', 'article',
-  'aside', 'footer', 'address',
+  'body',
+  'header',
+  'hgroup',
+  'nav',
+  'main',
+  'section',
+  'article',
+  'aside',
+  'footer',
+  'address',
 
   // Text content
-  'h1', 'h2', 'h3', 'h4', 'h5', 'h6', 'p', 'hr', 'menu', 'pre', 'blockquote',
-  'ol', 'ul', 'li', 'dl', 'dt', 'dd', 'figure', 'figcaption',
+  'h1',
+  'h2',
+  'h3',
+  'h4',
+  'h5',
+  'h6',
+  'p',
+  'hr',
+  'menu',
+  'pre',
+  'blockquote',
+  'ol',
+  'ul',
+  'li',
+  'dl',
+  'dt',
+  'dd',
+  'figure',
+  'figcaption',
   'div',
 
   // Inline text semantics
-  'a', 'abbr', 'b', 'bdi', 'bdo', 'br', 'cite', 'code',
-  'data', 'dfn', 'em', 'i', 'kbd', 'mark', 'q', 'rb', 'rp',
-  'rt', 'rtc', 'ruby', 's', 'samp', 'small', 'span', 'strong',
-  'sub', 'sup', 'time', 'u', 'var', 'wbr',
+  'a',
+  'abbr',
+  'b',
+  'bdi',
+  'bdo',
+  'br',
+  'cite',
+  'code',
+  'data',
+  'dfn',
+  'em',
+  'i',
+  'kbd',
+  'mark',
+  'q',
+  'rb',
+  'rp',
+  'rt',
+  'rtc',
+  'ruby',
+  's',
+  'samp',
+  'small',
+  'span',
+  'strong',
+  'sub',
+  'sup',
+  'time',
+  'u',
+  'var',
+  'wbr',
 
   // Edits
-  'ins', 'del',
+  'ins',
+  'del',
 
   // Embedded content
-  'img', 'iframe', 'embed', 'object', 'param', 'video', 'audio',
-  'source', 'track', 'picture',
+  'img',
+  'iframe',
+  'embed',
+  'object',
+  'param',
+  'video',
+  'audio',
+  'source',
+  'track',
+  'picture',
 
   // Table content
-  'table', 'caption', 'thead', 'tbody', 'tfoot', 'tr',
-  'th', 'td', 'colgroup', 'col',
+  'table',
+  'caption',
+  'thead',
+  'tbody',
+  'tfoot',
+  'tr',
+  'th',
+  'td',
+  'colgroup',
+  'col',
 
   // Forms
-  'form', 'fieldset', 'legend', 'label', 'input', 'button',
-  'select', 'datalist', 'optgroup', 'option', 'textarea',
-  'output', 'progress', 'meter',
+  'form',
+  'fieldset',
+  'legend',
+  'label',
+  'input',
+  'button',
+  'select',
+  'datalist',
+  'optgroup',
+  'option',
+  'textarea',
+  'output',
+  'progress',
+  'meter',
 
   // Interactive elements
-  'details', 'search', 'summary', 'dialog', 'slot', 'template',
+  'details',
+  'search',
+  'summary',
+  'dialog',
+  'slot',
+  'template',
 
   // Scripting and style
-  'script', 'noscript', 'style',
+  'script',
+  'noscript',
+  'style',
 
   // Web components and others
-  'canvas', 'picture', 'map', 'area', 'slot'
+  'canvas',
+  'picture',
+  'map',
+  'area',
+  'slot'
 ]
 
 const svgTagNames = [
   // Animation elements
-  'a', 'animate', 'animateMotion', 'animateTransform', 'mpath', 'set',
+  'a',
+  'animate',
+  'animateMotion',
+  'animateTransform',
+  'mpath',
+  'set',
 
   // Basic shapes
-  'circle', 'ellipse', 'line', 'path', 'polygon', 'polyline', 'rect',
+  'circle',
+  'ellipse',
+  'line',
+  'path',
+  'polygon',
+  'polyline',
+  'rect',
 
   // Container / structural
-  'defs', 'g', 'marker', 'mask', 'pattern', 'svg', 'switch', 'symbol', 'use',
+  'defs',
+  'g',
+  'marker',
+  'mask',
+  'pattern',
+  'svg',
+  'switch',
+  'symbol',
+  'use',
 
   // Descriptive
-  'desc', 'metadata', 'title',
+  'desc',
+  'metadata',
+  'title',
 
   // Filter primitives
-  'filter', 'feBlend', 'feColorMatrix', 'feComponentTransfer', 'feComposite',
-  'feConvolveMatrix', 'feDiffuseLighting', 'feDisplacementMap',
-  'feDistantLight', 'feDropShadow', 'feFlood', 'feFuncA', 'feFuncB',
-  'feFuncG', 'feFuncR', 'feGaussianBlur', 'feImage', 'feMerge',
-  'feMergeNode', 'feMorphology', 'feOffset', 'fePointLight',
-  'feSpecularLighting', 'feSpotLight', 'feTile', 'feTurbulence',
+  'filter',
+  'feBlend',
+  'feColorMatrix',
+  'feComponentTransfer',
+  'feComposite',
+  'feConvolveMatrix',
+  'feDiffuseLighting',
+  'feDisplacementMap',
+  'feDistantLight',
+  'feDropShadow',
+  'feFlood',
+  'feFuncA',
+  'feFuncB',
+  'feFuncG',
+  'feFuncR',
+  'feGaussianBlur',
+  'feImage',
+  'feMerge',
+  'feMergeNode',
+  'feMorphology',
+  'feOffset',
+  'fePointLight',
+  'feSpecularLighting',
+  'feSpotLight',
+  'feTile',
+  'feTurbulence',
 
   // Gradient / paint servers
-  'linearGradient', 'radialGradient', 'stop',
+  'linearGradient',
+  'radialGradient',
+  'stop',
 
   // Graphics elements
-  'image', 'foreignObject', // included in graphics section as non‑standard children
+  'image',
+  'foreignObject', // included in graphics section as non‑standard children
 
   // Text and text-path
-  'text', 'textPath', 'tspan',
+  'text',
+  'textPath',
+  'tspan',
 
   // Scripting/style
-  'script', 'style',
+  'script',
+  'style',
 
   // View
   'view'
 ]
 
 const tagNames = [...htmlTagNames, ...svgTagNames]
-const isPropsObject = x => typeof x === 'object'
+const isPropsObject = x =>
+  typeof x === 'object'
   && x !== null
   && !Array.isArray(x)
   && !(typeof Node !== 'undefined' && x instanceof Node)
@@ -422,18 +574,20 @@ const isPropsObject = x => typeof x === 'object'
  *
  * @type {Record<string, ElementHelper>}
  */
-export const elements = tagNames.reduce((acc, tag) => ({
-  ...acc,
-  [tag]: (propsOrChild, ...children) => {
-    const props = isPropsObject(propsOrChild) ? propsOrChild : {}
-    const actualChildren = props === propsOrChild
-      ? children
-      : [propsOrChild, ...children]
-    return [tag, props, ...actualChildren]
+export const elements = tagNames.reduce(
+  (acc, tag) => ({
+    ...acc,
+    [tag]: (propsOrChild, ...children) => {
+      const props = isPropsObject(propsOrChild) ? propsOrChild : {}
+      const actualChildren =
+        props === propsOrChild ? children : [propsOrChild, ...children]
+      return [tag, props, ...actualChildren]
+    }
+  }),
+  {
+    fragment: (...children) => ['fragment', {}, ...children]
   }
-}), {
-  fragment: (...children) => ['fragment', {}, ...children]
-})
+)
 
 /**
  * <html>
@@ -1928,4 +2082,3 @@ export const view = elements.view
 
 // TODO: MathML
 // https://developer.mozilla.org/en-US/docs/Web/MathML/Reference/Element
-

package/package.json

@@ -1,12 +1,20 @@
 {
   "name": "@pfern/elements",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "A minimalist, pure functional declarative UI toolkit.",
-  "main": "elements.js",
   "type": "module",
+  "main": "elements.js",
+  "types": "./types/index.d.ts",
   "exports": {
-    ".": "./elements.js"
+    ".": {
+      "types": "./types/index.d.ts",
+      "default": "./elements.js"
+    }
   },
+  "files": [
+    "./elements.js",
+    "./types"
+  ],
   "keywords": [
     "ui",
     "functional",
@@ -19,20 +27,21 @@
     "html"
   ],
   "scripts": {
-    "dev": "vite examples/",
+    "dev": "vite",
     "build": "vite build",
     "preview": "vite preview",
     "test": "node --test test/*.test.* --test-reporter spec"
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/pfernandez/elements.git"
+    "url": "git+https://github.com/pfernandez/elements.git"
   },
   "author": "Paul Fernandez",
   "license": "MIT",
   "devDependencies": {
+    "@types/node": "^25.0.10",
     "eslint": "^7.32.0",
-    "vite": "^5.0.0"
+    "typescript": "^5.9.3",
+    "vite": "^7.3.1"
   }
 }
-