@pfern/elements 0.1.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025 Paul Fernandez
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell     
+copies of the Software, and to permit persons to whom the Software is         
+furnished to do so, subject to the following conditions:                      
+
+The above copyright notice and this permission notice shall be included in    
+all copies or substantial portions of the Software.                           
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR    
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,      
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE   
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER        
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN     
+THE SOFTWARE.
+

package/README.md

@@ -0,0 +1,255 @@
+# Elements.js
+
+A minimalist declarative UI toolkit designed around purity, immutability, and HTML semantics.
+
+## Features
+
+* Zero-dependency functional UI engine
+* Stateless components defined as pure functions
+* Fully declarative, deeply composable view trees
+* HTML element functions with JSDoc and TypeScript-friendly signatures
+* No hooks, no classes, no virtual DOM heuristics
+
+---
+
+## Why Elements.js?
+
+Modern frameworks introduced declarative UI—but buried it beneath lifecycle hooks, mutable state, and complex diffing algorithms.
+
+**Elements.js goes further:**
+
+* Pure functions represent both logic and view
+* The DOM *is* your state model
+* Re-rendering is *recursion*, not reconciliation
+
+> Can UI be defined as a tree of pure function calls—nothing more?
+
+Yes. Elements.js proves it.
+
+---
+
+## Philosophy
+
+### Declarative from top to bottom
+
+* No internal component state
+* 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.
+
+### State lives in the DOM
+
+There is no observer graph, no `useState`, and no memory of previous renders.
+The DOM node *is the history*. Input state is passed as an argument.
+
+### Minimal abstraction
+
+* No keys, refs, proxies, or context systems
+* No transpilation step
+* No reactive graph to debug
+
+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';
+
+const counter = component((count = 0) =>
+  div(
+    pre(count),
+    button({ onclick: () => counter(count + 1) }, 'Increment')
+  )
+)
+
+render(counter(), document.body);
+```
+
+* Each click returns a new call to `counter(count + 1)`
+* The old DOM node is replaced with the new one
+* No virtual DOM, no diffing
+
+---
+
+## 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 }])
+
+  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:
+
+* Stateless
+* Immutable
+* Pure
+
+---
+
+## 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.
+
+```js
+import {
+  body, h1, h2, head, header, html,
+  link, main, meta, render, section, title
+} from './elements.js'
+import { todos } from './components/todos.js'
+
+render(
+  html(
+    head(
+      title('Elements.js'),
+      meta({ name: 'viewport', content: 'width=device-width, initial-scale=1.0' }),
+      link({ rel: 'stylesheet', href: 'css/style.css' })
+    ),
+    body(
+      header(h1('Elements.js Demo')),
+      main(
+        section(
+          h2('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.
+
+### 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).
+* Returned vnodes are passed to `component()` to re-render declaratively.
+
+### Form Events
+
+For `onsubmit`, `oninput`, and `onchange`, Elements.js provides a special signature:
+
+```js
+(event.target.elements, event)
+```
+
+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.
+
+```js
+form({
+  onsubmit: ({ todo: { value } }, e) =>
+    value && todos([...items, { value, done: false }])
+})
+```
+
+If the handler returns nothing, `preventDefault()` is skipped and the form submits natively.
+
+---
+
+## API
+
+### `component(fn)`
+
+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.
+
+### DOM Elements
+
+Every HTML and SVG tag is available as a function:
+
+```js
+div({ id: 'box' }, 'hello')
+svg({ width: 100 }, circle({ r: 10 }))
+```
+
+### TypeScript & JSDoc
+
+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
+
+---
+
+## Status
+
+* ✅ Production-ready core
+* 🧪 Fully tested (data-in/data-out behavior)
+* ⚡ Under 2kB min+gzip
+* ✅ Node and browser compatible
+
+---
+
+## Installation
+
+```bash
+npm install elements-js
+```
+
+Or clone the repo and use as an ES module:
+
+```js
+import { render, div, component, ... } from './elements.js';
+```
+
+---
+
+## Summary
+
+Elements.js is a thought experiment turned practical:
+
+> Can UI be nothing but functions?
+
+Turns out, yes.
+
+* No diffing
+* No state hooks
+* No lifecycle
+* No reconciliation heuristics
+
+Just pure declarative HTML—rewritten in JavaScript.
+
+---
+
+**Lightweight. Immutable. Composable.**
+
+Give it a try. You might never go back.
+