@pfern/create-elements 0.0.1

package/template/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "elements-template",
+  "version": "0.0.1",
+  "description": "An elements.js app.",
+  "main": "./src/index.js",
+  "type": "module",
+  "keywords": [],
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "preview": "vite preview",
+    "test": "node --test test/*.test.* --test-reporter spec"
+  },
+  "repository": {
+    "type": "git",
+    "url": ""
+  },
+  "author": "",
+  "license": "ISC",
+  "devDependencies": {
+    "eslint": "^9.39.2",
+    "vite": "^7.3.1"
+  },
+  "dependencies": {
+    "@pfern/elements": "^0.1.3",
+    "@picocss/pico": "^2.1.1"
+  }
+}

package/template/src/components/counter.js

@@ -0,0 +1,9 @@
+import { button, component, div, output } from '@pfern/elements'
+
+export const counter = component((count = 0) =>
+  div(
+    output(count),
+    button(
+      { onclick: () => counter(count + 1) },
+      'Increment')))
+

package/template/src/components/todos.js

@@ -0,0 +1,29 @@
+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) }, '✕'))))))})
+

package/template/src/index.js

@@ -0,0 +1,27 @@
+import { body, div, h1, h2, head, header, html,
+         link, main, meta, render, section, title } from '@pfern/elements'
+import { counter } from './components/counter.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: 'src/style.css' })),
+    body(
+      header(
+        h1('Elements.js Demo')),
+      main(
+        section(
+          h2('Todos'),
+          todos()),
+        section({ class: 'grid' },
+          div(
+            h2('Counter 1'),
+            counter()),
+          div(
+            h2('Counter 2'),
+            counter()))))))
+

package/template/src/style.css

@@ -0,0 +1,95 @@
+
+/*******************************************************************************
+ * Reset & base theme
+ ******************************************************************************/
+
+@import '@picocss/pico/css/pico.sand.css';
+
+:root {
+  --pico-font-family-sans-serif: 'Arial', sans-serif;
+  --pico-border-radius: 0;
+}
+
+/* Light color scheme (Default) */
+/* Can be forced with data-theme="light" */
+[data-theme="light"],
+:root:not([data-theme="dark"]) {
+  --pico-primary-background: #ccc;
+  --pico-primary-border: #ccc;
+  --pico-primary-hover-color: var(--pico-primary-inverse);
+  --pico-primary-hover-background: transparent;
+  --pico-primary-hover-border: var(--pico-primary-hover-color);
+  --pico-button-hover-box-shadow: var(--pico-primary-hover-background);
+}
+
+input:not([type=checkbox],[type=radio],[type=range]) {
+  height: auto;
+}
+
+/*******************************************************************************
+ * Layout
+ ******************************************************************************/
+
+body {
+  padding: 20px;
+}
+
+body>main, main {
+  border-bottom: 1px solid #ddd;
+  padding-top: 0;
+}
+
+body>header, header {
+  padding-bottom: 0;
+}
+
+section {
+  border-top: 1px solid #ddd;
+  padding-top: 1em;
+  margin: 0;
+}
+
+/*******************************************************************************
+ * General
+ ******************************************************************************/
+
+output {
+  font-size: xx-large;
+  font-weight: bold;
+  font-family: monospace;
+  padding: 1em;
+}
+
+li > span:hover {
+  opacity: 0.8;
+}
+
+form > * {
+  display: inline-block;
+}
+
+li > button {
+  padding: 2px 8px 1px;
+  margin-left: 10px;
+}
+
+/*******************************************************************************
+ * Apps
+ ******************************************************************************/
+
+.todos form {
+  max-width: 600px;
+}
+
+.todos form input {
+  width: 75%;
+}
+
+.todos form button {
+  width: 25%;
+}
+
+.todos li {
+  cursor: pointer;
+}
+

package/template/test/README.md

@@ -0,0 +1,77 @@
+# Testing Philosophy: Elements.js
+
+Elements.js is designed around **purity**, **immutability**, and **data-in/data-out UI logic**.
+
+This testing suite reflects that philosophy:
+
+---
+
+## What We Test
+
+### Element Structure
+
+* Every exported tag (e.g. `div`, `svg`, `form`) is a pure function.
+* It returns a **vnode array**: `['tag', props, ...children]`
+* Props and children must appear in the correct positions.
+
+### Event Listeners
+
+* Event handlers return vnodes to declaratively update the view.
+* Special cases like `onsubmit`, `oninput`, `onchange` receive `(elements, event)`.
+* Listeners returning falsy values (`null`, `false`, `''`) are treated as passive.
+
+### Components
+
+* `component(fn)` wraps a recursive, stateless function that can call itself with new arguments.
+* Recursive updates should return well-formed vnodes and trigger no side effects.
+
+---
+
+## What We Don't Test
+
+We **do not** test:
+
+* Real DOM rendering or patching (that’s internal)
+* Whether `preventDefault()` was called (covered by behavior, not inspection)
+* Any mutation of the DOM
+* Internal utilities like `assignProperties`, `diffTree`, or `render` directly
+
+Instead, we test only what is **observable through public exports**.
+
+---
+
+## Purity Contract
+
+> **Every test must be resolvable by examining the return value.**
+> No test depends on the DOM, mutation, timers, side effects, or internal state.
+
+This allows the entire system to be:
+
+* Predictable
+* Stateless
+* Transparent
+
+And trivially portable to other runtimes (SSR, testing, WASM, etc).
+
+---
+
+## Running Tests
+
+```bash
+node --test
+```
+
+All tests use native `node:test` and `assert`—no external dependencies.
+
+---
+
+## Adding New Tests
+
+When adding features, ask:
+
+* Is this behavior observable at the vnode or component level?
+* Can it be tested using only function return values and inputs?
+
+If yes → write a test.
+If not → consider whether the feature belongs in this framework at all.
+

package/template/test/elements.test.js

@@ -0,0 +1,36 @@
+import { button, div, form, input } from '@pfern/elements'
+import { describe, test } from 'node:test'
+import assert from 'node:assert/strict'
+
+describe('Elements.js example tests', () => {
+  test('div() returns a vnode with tag "div"', () => {
+    const vnode = div({ id: 'test' }, 'hello')
+    assert.deepEqual(vnode, ['div', { id: 'test' }, 'hello'])
+  })
+
+  test('button with onclick handler returns new vnode', () => {
+    const handler = () => ['span', {}, 'clicked']
+    const b = button({ onclick: handler }, 'Click Me')
+    const result = b[1].onclick()
+    assert.deepEqual(result, ['span', {}, 'clicked'])
+  })
+
+  test('form onsubmit handler receives elements and event', () => {
+    let receivedElements, receivedEvent
+    const handler = (elements, event) => {
+      receivedElements = elements
+      receivedEvent = event
+      return ['div', {}, 'submitted']
+    }
+
+    const fakeElements = { task: { value: 'buy milk' } }
+    const fakeEvent = { type: 'submit', foo: 'bar' }
+
+    const f = form({ onsubmit: handler }, input({ name: 'task' }))
+    const result = f[1].onsubmit(fakeElements, fakeEvent)
+
+    assert.equal(receivedElements.task.value, 'buy milk')
+    assert.equal(receivedEvent.foo, 'bar')
+    assert.deepEqual(result, ['div', {}, 'submitted'])
+  })
+})