@pfern/elements 0.1.11 → 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,168 +1,96 @@
-# Elements.js
+# @pfern/elements
 
-Elements.js is a tiny, functional UI toolkit for building DOM trees with plain
-functions. Components are just functions; updates are just calling the function
-again with new arguments.
+A minimalist, pure functional declarative UI toolkit.
 
-## Install
-
-```bash
-npm install @pfern/elements
-```
+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.
 
-## Quick Example: Counter
-
-```js
-import { button, component, div, output } from '@pfern/elements'
+## Install
 
-export const counter = component((count = 0) =>
-  div(
-    output(count),
-    button(
-      { onclick: () => counter(count + 1) },
-      'Increment')))
+```sh
+npm i @pfern/elements
 ```
 
-## Example: Todos App
+## How Updates Work
 
-```js
-
-import { button, component, div,
-         form, input, li, span, ul } from '@pfern/elements'
-
-export const todos = component(
-  (items = [{ value: 'Add my first todo', done: true }]) => {
+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.
 
-    const add = ({ todo: { value } }) =>
-      value && todos([...items, { value, done: false }])
 
-    const remove = item =>
-      todos(items.filter(i => i !== item))
+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.
 
-    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')),
+### Routing
 
-        ul(...items.map(item =>
-          li(
-            { style:
-              { 'text-decoration': item.done ? 'line-through' : 'none' } },
-            span({ onclick: () => toggle(item) }, item.value),
-            button({ onclick: () => remove(item) }, '✕'))))))})
-
-```
-
-## 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.
+For SPAs, register a URL-change handler once:
 
 ```js
-import {
-  body, h1, h2, head, header, html,
-  link, main, meta, render, section, title
-} from './elements.js'
-import { todos } from './components/todos.js'
+import { onNavigate } from '@pfern/elements'
 
-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())))))
+onNavigate(() => App())
 ```
 
-## Declarative Events
-
-### General Behavior
+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.
 
-* 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 applied at the closest component boundary.
+### SSG / SSR
 
-### Form Events
-
-For `onsubmit`, `oninput`, and `onchange`, Elements.js provides a special
-signature:
+For build-time prerendering (static site generation) or server-side rendering,
+Elements.js can serialize vnodes to HTML:
 
 ```js
-(event.target.elements, event)
-```
-
-That is, your handler receives:
+import { div, html, head, body, title, toHtmlString } from '@pfern/elements'
 
-1. `elements`: the HTML form’s named inputs
-2. `event`: the original DOM event object
+toHtmlString(div('Hello')) // => <div>Hello</div>
 
-Elements.js will automatically call `event.preventDefault()` *only if* your
-handler returns a vnode.
+const doc =
+  html(
+    head(title('My page')),
+    body(div('Hello')))
 
-```js
-form({
-  onsubmit: ({ todo: { value } }, e) =>
-    value && todos([...items, { value, done: false }])
-})
+const htmlText = toHtmlString(doc, { doctype: true })
 ```
 
-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])`
+Notes:
+- Event handlers (function props like `onclick`) are dropped during
+  serialization.
+- `innerHTML` is treated as an explicit escape hatch and is inserted verbatim.
 
-Render a vnode into the DOM. If `vnode[0]` is `html`, `head`, or `body`, no
-`container` is required.
+## Usage
 
-### DOM Elements
+```js
+import { button, component, div, output, render } from '@pfern/elements'
 
-Every HTML and SVG tag is available as a function:
+export const counter = component((count = 0) =>
+  div(
+    output(count),
+    button({ onclick: () => counter(count + 1) }, 'Increment')))
 
-```js
-div({ id: 'box' }, 'hello')
-svg({ width: 100 }, circle({ r: 10 }))
+render(counter(), document.body)
 ```
 
-### TypeScript & JSDoc
+## MathML (curated)
 
-Each tag function (e.g. `div`, `button`, `svg`) includes a `@typedef` and
-MDN-sourced description to:
+The runtime supports rendering MathML tags natively (via the MathML namespace).
+A small curated helper set is available as a separate entrypoint:
 
-* Provide editor hints
-* Encourage accessibility and semantic markup
-* Enable intelligent autocomplete
+```js
+import { apply, ci, csymbol, math } from '@pfern/elements/mathml'
 
-### Testing Philosophy
+math(
+  apply(csymbol({ cd: 'ski' }, 'app'), ci('f'), ci('x')))
+```
 
-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
 
-## Notes
+X3DOM / X3D helpers live in `@pfern/elements-x3dom` to keep this package small:
 
-- Elements.js is intended to be small and easy to reason about.
-- For a starter app template, use `@pfern/create-elements`:
-  - https://github.com/pfernandez/create-elements
-  - `npx @pfern/create-elements my-app`
-- More examples live in `examples/`.
+```sh
+npm i @pfern/elements @pfern/elements-x3dom
+```