@pfern/elements 0.1.10 → 0.2.0

package/LICENSE

@@ -5,18 +5,18 @@ 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:                      
+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 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 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

@@ -1,279 +1,96 @@
-# Elements.js
+# @pfern/elements
 
-Elements.js is a minimalist declarative UI toolkit designed around purity,
-immutability, and HTML semantics.
+A minimalist, pure functional declarative UI toolkit.
 
-## Features
+Elements.js is JS-first: TypeScript is not required at runtime. This package
+ships `.d.ts` files so editors like VSCode can provide rich inline docs and
+autocomplete.
 
-* 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
+## Install
 
----
-
-## 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
+```sh
+npm i @pfern/elements
+```
 
-To update a view: just **call the function again** with new arguments. The DOM
-subtree is replaced in place.
+## How Updates Work
 
-### State lives in the DOM
+Most apps call `render()` once on page load. You can force a full remount via `render(vtree, container, { replace: true })`. After that, updates happen when a
+DOM event handler (e.g. `onclick`, `onsubmit`) returns the next vnode: Elements.js
+replaces the closest component boundary.
 
-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
+Note: for `<a href>` links, if an `onclick` handler returns a vnode, Elements.js
+calls `event.preventDefault()` for unmodified left-clicks so SPAs can use real
+links without manual boilerplate.
 
-* 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.
 
----
+### Routing
 
-## Example: Counter
+For SPAs, register a URL-change handler once:
 
 ```js
-import { button, component, div, output } from '@pfern/elements'
+import { onNavigate } from '@pfern/elements'
 
-export const counter = component((count = 0) =>
-  div(
-    output(count),
-    button(
-      { onclick: () => counter(count + 1) },
-      'Increment')))
+onNavigate(() => App())
 ```
 
-* 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
+With a handler registered, `a({ href: '/path' }, ...)` intercepts unmodified
+left-clicks for same-origin links and uses the History API instead of reloading
+the page.
 
----
+### SSG / SSR
 
-## Form Example: Todos App
+For build-time prerendering (static site generation) or server-side rendering,
+Elements.js can serialize vnodes to HTML:
 
 ```js
+import { div, html, head, body, title, toHtmlString } from '@pfern/elements'
 
-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' },
+toHtmlString(div('Hello')) // => <div>Hello</div>
 
-        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 doc =
+  html(
+    head(title('My page')),
+    body(div('Hello')))
 
+const htmlText = toHtmlString(doc, { doctype: true })
 ```
 
-This is a complete MVC-style app:
-
-* Stateless
-* 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`.
-
----
+Notes:
+- Event handlers (function props like `onclick`) are dropped during
+  serialization.
+- `innerHTML` is treated as an explicit escape hatch and is inserted verbatim.
 
-## 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.
+## Usage
 
 ```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())))))
-```
+import { button, component, div, output, render } from '@pfern/elements'
 
----
-
-## 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:
+export const counter = component((count = 0) =>
+  div(
+    output(count),
+    button({ onclick: () => counter(count + 1) }, 'Increment')))
 
-```js
-(event.target.elements, event)
+render(counter(), document.body)
 ```
 
-That is, your handler receives:
-
-1. `elements`: the HTML form’s named inputs
-2. `event`: the original DOM event object
+## MathML (curated)
 
-Elements.js will automatically call `event.preventDefault()` *only if* your
-handler returns a vnode.
+The runtime supports rendering MathML tags natively (via the MathML namespace).
+A small curated helper set is available as a separate entrypoint:
 
 ```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])`
+import { apply, ci, csymbol, math } from '@pfern/elements/mathml'
 
-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 }))
+math(
+  apply(csymbol({ cd: 'ski' }, 'app'), ci('f'), ci('x')))
 ```
 
-### 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
-
-### 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.
-
----
+## Optional 3D
 
-## Status
+X3DOM / X3D helpers live in `@pfern/elements-x3dom` to keep this package small:
 
-* 🧪 Fully tested (data-in/data-out behavior)
-* ⚡ Under 2kB min+gzip
-* ✅ Node and browser compatible
-
----
-
-## Installation
-
-```bash
-npm install @pfern/elements
+```sh
+npm i @pfern/elements @pfern/elements-x3dom
 ```
-
-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.
-