@pfern/create-elements 1.0.1 → 1.0.3

package/README.md

@@ -1,6 +1,11 @@
 # create-elements
 
-A CLI package to generate a minimal template project with Elements.js.
+A CLI package to generate a minimal Vite app using `@pfern/elements`.
+
+If you’re looking for the core UI library docs, see the `@pfern/elements`
+README:
+
+- https://github.com/pfernandez/elements
 
 ## Usage
 
@@ -21,3 +26,6 @@ npm install
 npm run dev
 ```
 
+## Related
+
+- `@pfern/elements`: https://github.com/pfernandez/elements

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pfern/create-elements",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "description": "A CLI script to generate a starter app with elements.js",
   "main": "index.js",
   "keywords": [
@@ -18,7 +18,10 @@
   "license": "MIT",
   "type": "module",
   "bin": {
-    "create-elements": "./index.js"
+    "create-elements": "index.js"
   },
-  "files": ["index.js", "template/"]
+  "files": [
+    "index.js",
+    "template/"
+  ]
 }

package/template/README.md

@@ -1,279 +1,31 @@
-# Elements.js Starter App
+# elements-app
 
-Elements.js is a minimalist declarative UI toolkit designed around purity,
-immutability, and HTML semantics.
+A tiny Vite template using `@pfern/elements`.
 
-## Features
+Includes:
 
-* 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
+- Minimal client-side routing (history + `popstate`)
+- A todos example (`src/components/todos.js`)
+- Two independent counters (`src/components/counter.js`)
+- Pico.css styling (`src/style.css`)
 
----
-
-## 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
+## Getting started
 
 ```bash
-npm install @pfern/elements
+npm install
+npm run dev
 ```
 
-Or clone the repo and use as an ES module:
+## Scripts
 
-```js
-import { render, div, component, ... } from './elements.js';
+```bash
+npm run dev
+npm run build
+npm run preview
+npm test
 ```
 
----
-
-## 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.
+## Routing
 
+Routes are defined in `src/router.js` and used from `src/components/app.js`.
+Navigation uses the History API so the address bar stays in sync.

package/template/index.html

@@ -1,4 +1,12 @@
 <!doctype html>
-<link rel="icon" href="data:x-icon">
-<script type="module" src="src/index.js"></script>
-
+<html lang="en">
+  <head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <link rel="icon" href="data:x-icon">
+    <title>elements.js app</title>
+  </head>
+  <body>
+    <script type="module" src="src/index.js"></script>
+  </body>
+</html>

package/template/package.json

@@ -16,13 +16,13 @@
     "url": ""
   },
   "author": "",
-  "license": "ISC",
+  "license": "MIT",
   "devDependencies": {
     "eslint": "^9.39.2",
     "vite": "^7.3.1"
   },
   "dependencies": {
-    "@pfern/elements": "^0.1.3",
+    "@pfern/elements": "latest",
     "@picocss/pico": "^2.1.1"
   }
 }

package/template/src/components/app.js

@@ -0,0 +1,50 @@
+import { a, component, div, h2, main, nav, section } from '@pfern/elements'
+import { counter } from './counter.js'
+import { todos } from './todos.js'
+import { currentPath, go, normalizePath } from '../router.js'
+
+const link = (path, label, active) =>
+  a({
+    href: path,
+    class: active ? 'active' : '',
+    onclick: () => app(go(path, { force: true }))
+  }, label)
+
+const navbar = path =>
+  nav(
+    link('/', 'Home', path === '/'),
+    link('/todos', 'Todos', path === '/todos'),
+    link('/counters', 'Counters', path === '/counters'))
+
+const home = () =>
+  section(
+    h2('Home'),
+    div(`This template shows a tiny router (history + popstate), a todos app,
+         and independent counters.`))
+
+const counters = () =>
+  section({ class: 'grid' },
+    div(
+      h2('Counter 1'),
+      counter()),
+    div(
+      h2('Counter 2'),
+      counter()))
+
+export const app = component((path = currentPath()) => {
+  path = normalizePath(path)
+
+  const view =
+    path === '/todos' ? todos()
+    : path === '/counters' ? counters()
+    : home()
+
+  return main(
+    navbar(path),
+    view)
+})
+
+if (typeof window !== 'undefined') {
+  window.addEventListener('popstate', () => app(currentPath()))
+}
+

package/template/src/components/counter.js

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

package/template/src/components/todos.js

@@ -21,8 +21,7 @@ export const todos = component(
           button({ type: 'submit' }, 'Add')),
 
         ul(...items.map(item =>
-          li(
-            { style:
+          li({ style:
               { 'text-decoration': item.done ? 'line-through' : 'none' } },
             span({ onclick: () => toggle(item) }, item.value),
             button({ onclick: () => remove(item) }, '✕'))))))})

package/template/src/index.js

@@ -1,8 +1,7 @@
 import './style.css'
-import { body, div, h1, h2, head, header, html,
-         main, meta, render, section, title } from '@pfern/elements'
-import { counter } from './components/counter.js'
-import { todos } from './components/todos.js'
+import { body, h1, head, header, html,
+         meta, render, title } from '@pfern/elements'
+import { app } from './components/app.js'
 
 render(
   html(
@@ -13,15 +12,5 @@ render(
     body(
       header(
         h1('Elements.js Demo')),
-      main(
-        section(
-          h2('Todos'),
-          todos()),
-        section({ class: 'grid' },
-          div(
-            h2('Counter 1'),
-            counter()),
-          div(
-            h2('Counter 2'),
-            counter()))))))
+      app())))
 

package/template/src/router.js

@@ -0,0 +1,40 @@
+export const routes = [
+  '/',
+  '/todos',
+  '/counters',
+]
+
+export const navigate = (path, { replace = false, force = false } = {}) => {
+  if (typeof window === 'undefined') return
+
+  const url = new URL(path, window.location.origin)
+  const isSame =
+    url.pathname === window.location.pathname
+    && url.search === window.location.search
+    && url.hash === window.location.hash
+
+  if (!force && isSame) return
+
+  const fn = replace ? 'replaceState' : 'pushState'
+  window.history[fn]({}, '', url)
+
+  try {
+    window.dispatchEvent(new PopStateEvent('popstate'))
+  } catch {
+    window.dispatchEvent(new Event('popstate'))
+  }
+}
+
+export const currentPath = () =>
+  (typeof window === 'undefined')
+    ? '/'
+    : window.location.pathname || '/'
+
+export const normalizePath = (path = '/') =>
+  routes.includes(path) ? path : '/'
+
+export const go = (path, { force = false } = {}) => {
+  const next = normalizePath(path)
+  navigate(next, { force })
+  return next
+}

package/template/src/style.css

@@ -1,30 +1,8 @@
-
 /*******************************************************************************
  * 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;
-}
+@import '@picocss/pico/css/pico.grey.css';
 
 /*******************************************************************************
  * Layout
@@ -43,6 +21,16 @@ body>header, header {
   padding-bottom: 0;
 }
 
+nav {
+  display: inline-flex;
+  gap: 1em;
+  padding-bottom: 1em;
+}
+
+nav a.active {
+  text-decoration: underline;
+}
+
 section {
   border-top: 1px solid #ddd;
   padding-top: 1em;
@@ -78,15 +66,16 @@ li > button {
  ******************************************************************************/
 
 .todos form {
-  max-width: 600px;
+  max-width: 512px;
 }
 
 .todos form input {
-  width: 75%;
+  width: 78%;
 }
 
 .todos form button {
-  width: 25%;
+  width: 20%;
+  margin-left: 2%;
 }
 
 .todos li {