@pfern/create-elements 0.0.1

package/README.md

@@ -0,0 +1,23 @@
+# create-elements
+
+A CLI package to generate a minimal template project with Elements.js.
+
+## Usage
+
+### Installation
+```js
+npm install -g \@pfern/create-elements
+```
+
+### Usage
+
+```sh
+npm \@pfern/create-elements [project-name]
+
+# Enter a project name if none was provided
+
+cd project-name
+npm install
+npm run dev
+```
+

package/index.js

@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import readline from 'node:readline/promises';
+import { stdin as input, stdout as output } from 'node:process';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+async function init() {
+  let projectName = process.argv[2];
+
+  if (!projectName) {
+    const rl = readline.createInterface({ input, output });
+    projectName = await rl.question('Project name: (elements-app) ');
+    rl.close();
+
+    projectName = projectName.trim() || 'elements-app';
+  }
+
+  const targetDir = path.resolve(process.cwd(), projectName);
+  const templateDir = path.resolve(__dirname, 'template');
+
+  if (fs.existsSync(targetDir) && fs.readdirSync(targetDir).length > 0) {
+    console.error(`✖ Error: Directory "${projectName}" is not empty.`);
+    process.exit(1);
+  }
+
+  console.log(`\nScaffolding project in ${targetDir}...`);
+
+  try {
+    fs.cpSync(templateDir, targetDir, { recursive: true });
+
+    const gitignorePath = path.join(targetDir, 'gitignore');
+    if (fs.existsSync(gitignorePath)) {
+      fs.renameSync(gitignorePath, path.join(targetDir, '.gitignore'));
+    }
+
+    console.log(`\n✔ Done! To get started:`);
+    console.log(`  cd ${projectName}`);
+    console.log(`  npm install\n`);
+  } catch (err) {
+    console.error('✖ Error copying template:', err.message);
+    process.exit(1);
+  }
+}
+
+init().catch(console.error);
+

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@pfern/create-elements",
+  "version": "0.0.1",
+  "description": "A CLI script to generate a starter app with elements.js",
+  "main": "index.js",
+  "keywords": [
+    "ui",
+    "functional",
+    "declarative",
+    "frontend",
+    "vdom",
+    "jsx-free",
+    "stateless",
+    "recursive",
+    "html"
+  ],
+  "author": "Paul Fernandez",
+  "license": "ISC",
+  "type": "module",
+  "bin": {
+    "create-elements": "./index.js"
+  },
+  "files": ["index.js", "template/"]
+}

package/template/.eslintrc.json

@@ -0,0 +1,205 @@
+{ "root": true,
+  "parserOptions": { "ecmaVersion": "latest", "sourceType": "module" },
+  "env": { "browser": true, "es2021": true },
+
+  "rules": {
+    "array-bracket-newline": [ "warn", "consistent" ],
+    "arrow-parens": [ "warn", "as-needed" ],
+    "arrow-spacing": "warn",
+    "comma-spacing": [ "warn", { "before": false, "after": true } ],
+    "comma-style": [ "warn", "last" ],
+    "computed-property-spacing": [ "warn", "never" ],
+    "eol-last": [ "warn", "always" ],
+    "indent": [ "warn", 2, {
+        "ImportDeclaration": "first",
+        "ObjectExpression": "first",
+        "VariableDeclarator": {
+          "var": 2,
+          "let": 2,
+          "const": 3 } } ],
+    "key-spacing": [ "warn", { "mode": "minimum" } ],
+    "linebreak-style": [ "error", "unix" ],
+    "no-extra-parens": "warn",
+    "no-multiple-empty-lines": [ "warn", { "max": 2, "maxEOF": 1 } ],
+    "no-multi-spaces": [ "warn", {
+        "ignoreEOLComments": true,
+        "exceptions": { "Property": false } } ],
+    "no-trailing-spaces": "warn",
+    "no-undef": "warn",
+    "no-unused-vars": [ "warn", {
+        "args": "all",
+        "varsIgnorePattern": "^_",
+        "argsIgnorePattern": "^_" } ],
+
+    "object-curly-newline": [ "warn", { "consistent": true } ],
+    "object-curly-spacing": [ "warn", "always" ],
+    "operator-linebreak": [ "warn", "before", {
+        "overrides": {
+          "=": "ignore" } } ],
+    "prefer-rest-params": "warn",
+    "quote-props": [ "warn", "as-needed" ],
+    "quotes": [ "warn", "single" ],
+    "semi": [ "warn", "never" ],
+    "sort-imports": "warn",
+    "space-before-function-paren": [ "warn", {
+        "anonymous": "never",
+        "asyncArrow": "always",
+        "named": "never" } ],
+    "spaced-comment": [ "warn", "always" ],
+    "space-in-parens": "warn",
+    "space-infix-ops": "warn" },
+
+  "globals": {
+    "process": "readonly",
+    "test": "readonly",
+
+    "apply": "readonly",
+    "bool": "readonly",
+    "deepMap": "readonly",
+    "each": "readonly",
+    "entries": "readonly",
+    "eq": "readonly",
+    "evaluate": "readonly",
+    "exists": "readonly",
+    "filter": "readonly",
+    "first": "readonly",
+    "globalize": "readonly",
+    "identity": "readonly",
+    "instance": "readonly",
+    "isArray": "readonly",
+    "isFunction": "readonly",
+    "join": "readonly",
+    "keys": "readonly",
+    "last": "readonly",
+    "length": "readonly",
+    "log": "readonly",
+    "omap": "readonly",
+    "omit": "readonly",
+    "partial": "readonly",
+    "push": "readonly",
+    "rest": "readonly",
+    "reverse": "readonly",
+    "slice": "readonly",
+    "split": "readonly",
+    "store": "readonly",
+    "sum": "readonly",
+    "type": "readonly",
+    "walk": "readonly",
+
+    "a": "readonly",
+    "abbr": "readonly",
+    "address": "readonly",
+    "area": "readonly",
+    "article": "readonly",
+    "aside": "readonly",
+    "audio": "readonly",
+    "b": "readonly",
+    "base": "readonly",
+    "bdi": "readonly",
+    "bdo": "readonly",
+    "blockquote": "readonly",
+    "body": "readonly",
+    "br": "readonly",
+    "button": "readonly",
+    "canvas": "readonly",
+    "caption": "readonly",
+    "cite": "readonly",
+    "code": "readonly",
+    "col": "readonly",
+    "colgroup": "readonly",
+    "data": "readonly",
+    "datalist": "readonly",
+    "dd": "readonly",
+    "del": "readonly",
+    "details": "readonly",
+    "dfn": "readonly",
+    "dialog": "readonly",
+    "div": "readonly",
+    "dl": "readonly",
+    "doctype": "readonly",
+    "dt": "readonly",
+    "el": "readonly",
+    "element": "readonly",
+    "em": "readonly",
+    "embed": "readonly",
+    "fieldset": "readonly",
+    "figcaption": "readonly",
+    "figure": "readonly",
+    "footer": "readonly",
+    "form": "readonly",
+    "fragment": "readonly",
+    "h1": "readonly",
+    "h2": "readonly",
+    "h3": "readonly",
+    "h4": "readonly",
+    "h5": "readonly",
+    "h6": "readonly",
+    "head": "readonly",
+    "header": "readonly",
+    "hgroup": "readonly",
+    "hr": "readonly",
+    "html": "readonly",
+    "i": "readonly",
+    "iframe": "readonly",
+    "img": "readonly",
+    "input": "readonly",
+    "ins": "readonly",
+    "kbd": "readonly",
+    "label": "readonly",
+    "legend": "readonly",
+    "li": "readonly",
+    "link": "readonly",
+    "main": "readonly",
+    "map": "readonly",
+    "mark": "readonly",
+    "menu": "readonly",
+    "meta": "readonly",
+    "meter": "readonly",
+    "nav": "readonly",
+    "noscript": "readonly",
+    "object": "readonly",
+    "ol": "readonly",
+    "optgroup": "readonly",
+    "option": "readonly",
+    "output": "readonly",
+    "p": "readonly",
+    "param": "readonly",
+    "picture": "readonly",
+    "pre": "readonly",
+    "progress": "readonly",
+    "q": "readonly",
+    "rp": "readonly",
+    "rt": "readonly",
+    "ruby": "readonly",
+    "s": "readonly",
+    "samp": "readonly",
+    "script": "readonly",
+    "section": "readonly",
+    "select": "readonly",
+    "slot": "readonly",
+    "small": "readonly",
+    "source": "readonly",
+    "span": "readonly",
+    "strong": "readonly",
+    "style": "readonly",
+    "sub": "readonly",
+    "summary": "readonly",
+    "sup": "readonly",
+    "table": "readonly",
+    "tbody": "readonly",
+    "td": "readonly",
+    "template": "readonly",
+    "textarea": "readonly",
+    "tfoot": "readonly",
+    "th": "readonly",
+    "thead": "readonly",
+    "time": "readonly",
+    "title": "readonly",
+    "tr": "readonly",
+    "track": "readonly",
+    "u": "readonly",
+    "ul": "readonly",
+    "var": "readonly",
+    "video": "readonly",
+    "wbr": "readonly" } }
+

package/template/README.md

@@ -0,0 +1,279 @@
+# Elements.js Starter App
+
+Elements.js is 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 { button, component, div, output } from '@pfern/elements'
+
+export const counter = component((count = 0) =>
+  div(
+    output(count),
+    button(
+      { onclick: () => counter(count + 1) },
+      'Increment')))
+```
+
+* 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, 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) }, '✕'))))))})
+
+```
+
+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`.
+
+---
+
+## 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
+
+### 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
+
+* 🧪 Fully tested (data-in/data-out behavior)
+* ⚡ Under 2kB min+gzip
+* ✅ Node and browser compatible
+
+---
+
+## Installation
+
+```bash
+npm install @pfern/elements
+```
+
+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.
+

package/template/gitignore

@@ -0,0 +1,2 @@
+node_modules
+dist

package/template/index.html

@@ -0,0 +1,4 @@
+<!doctype html>
+<link rel="icon" href="data:x-icon">
+<script type="module" src="src/index.js"></script>
+