@zoijs/core 1.0.0 → 1.2.0

package/CHANGELOG.md

@@ -4,7 +4,40 @@ All notable changes to Zoijs are documented here. The format is based on
 [Keep a Changelog](https://keepachangelog.com/), and Zoijs follows
 [Semantic Versioning](https://semver.org/) (see `VERSIONING.md`).
 
-## [1.0.0] — Unreleased
+## [1.2.0] — 2026-06-26
+
+### Added
+- **`effect(fn)`.** A public reactive effect — runs a side effect immediately and
+  re-runs whenever a reactive value it reads changes (automatic dependency
+  tracking, microtask-batched). The function may return a cleanup that runs before
+  the next run and on dispose (same convention as a `ref`); `effect` auto-disposes
+  with its owner (component / list item) and returns `{ dispose }` for early
+  teardown. This is the public completion of the reactive trio (`createState` /
+  `computed` / `effect`) — the engine already used it internally for bindings. Use
+  it for side effects *outside* the view (persist on change, sync `document.title`,
+  drive a non-Zoijs widget); for on-screen content, keep using a binding
+  (`${() => …}`). The public surface is now **eight** functions (additive MINOR per
+  `VERSIONING.md`). See [RFC 0003](docs/rfcs/0003-effect-and-svg.md).
+
+### Notes
+- The **`svg`** helper considered alongside `effect` was **deferred**: templates
+  rooted at `<svg>` already render correctly, and only dynamic-SVG *composition* is
+  affected — a minority need. See [RFC 0003](docs/rfcs/0003-effect-and-svg.md) §6.
+
+## [1.1.0] — 2026-06-25
+
+### Added
+- **Element refs.** A new `ref` binding gives you the rendered DOM element:
+  `html\`<input ref=${(el) => el.focus()} />\``. The callback runs once, just after
+  the element is inserted (so `focus`/`scroll`/`measure`/`canvas` work), is not
+  reactive, and may return a cleanup function that runs on unmount or list-item
+  removal. Works inside keyed `each` lists. Non-function values are ignored with a
+  dev-mode warning and never become a DOM attribute. No new export — `ref` is a
+  binding semantic, so the seven-function public surface is unchanged (additive
+  MINOR per `VERSIONING.md`). See [Element refs](docs/concepts/refs.md) and
+  [RFC 0001](docs/rfcs/0001-element-refs.md).
+
+## [1.0.0] — 2026-06-24
 
 First stable release. The public API is frozen at seven functions.
 
@@ -33,4 +66,5 @@ First stable release. The public API is frozen at seven functions.
   (Playwright), and TypeScript type tests.
 - No build step required at any point.
 
-[1.0.0]: https://github.com/Zoijs/zoijs/releases/tag/v1.0.0
+[1.1.0]: https://github.com/Zoijs/zoijs/releases/tag/core-v1.1.0
+[1.0.0]: https://github.com/Zoijs/zoijs/releases/tag/core-v1.0.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Easy Framework contributors
+Copyright (c) 2026 Zoijs contributors
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -2,7 +2,7 @@
 
 A lightweight frontend framework you don't have to learn before you use it — **plain HTML, CSS, and JavaScript**, no JSX, no build step, no Virtual DOM.
 
-**[Website](https://zoijs.com)** · **[Documentation](https://zoijs.dev)** · **[GitHub](https://github.com/Zoijs)** · **[npm](https://www.npmjs.com/package/@zoijs/core)**
+**[Documentation](https://zoijs.dev)** · **[GitHub](https://github.com/Zoijs)** · **[npm](https://www.npmjs.com/package/@zoijs/core)**
 
 ```bash
 npm install @zoijs/core
@@ -54,7 +54,7 @@ No build step is required — the framework is plain ES modules.
 
 # run the counter example (serves the project root over http so ES modules resolve)
 npm run dev
-# then open: http://localhost:3000/examples/counter/   (keep the trailing slash)
+# then open: http://localhost:7310/examples/counter/   (keep the trailing slash)
 
 # run the tests (DOM tests run automatically via jsdom)
 npm test
@@ -81,7 +81,7 @@ npx playwright install chromium firefox webkit
 npm run test:browser
 ```
 
-Playwright starts a static server automatically (`npx serve` on port 3000) — still no build step.
+Playwright starts a static server automatically (`npx serve` on port 7310) — still no build step.
 
 ## Browser support
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zoijs/core",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "Zoijs — a beginner-friendly, no-build, no-Virtual-DOM frontend framework. Plain HTML, CSS, and JavaScript.",
   "type": "module",
   "main": "src/index.js",
@@ -21,9 +21,9 @@
   "engines": {
     "node": ">=18"
   },
-  "author": "Zoijs contributors (https://zoijs.com)",
+  "author": "Zoijs contributors (https://zoijs.dev)",
   "license": "MIT",
-  "homepage": "https://zoijs.com",
+  "homepage": "https://zoijs.dev",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/Zoijs/zoijs.git",
@@ -49,11 +49,11 @@
     "spa"
   ],
   "scripts": {
-    "test": "node --test --import ./tests/setup-dom.js \"tests/**/*.test.js\"",
-    "test:unit": "node --test \"tests/**/*.test.js\"",
+    "test": "node --test --import ./tests/setup-dom.js",
+    "test:unit": "node --test",
     "test:types": "tsc --noEmit -p tsconfig.json",
     "test:browser": "playwright test",
-    "dev": "npx serve -l 3000 ."
+    "dev": "npx serve -l 7310 ."
   },
   "devDependencies": {
     "@playwright/test": "^1.61.1",

package/src/core/each.js

@@ -17,8 +17,8 @@
  * @param {Function|Array} items    a function returning the array, or an array
  * @param {Function} keyFn          item -> unique key
  * @param {Function} renderFn       item -> html() result
- * @returns {{ __easyEach: true, items: any, keyFn: Function, renderFn: Function }}
+ * @returns {{ __zoijsEach: true, items: any, keyFn: Function, renderFn: Function }}
  */
 export function each(items, keyFn, renderFn) {
-  return { __easyEach: true, items, keyFn, renderFn };
+  return { __zoijsEach: true, items, keyFn, renderFn };
 }

package/src/core/renderer.js

@@ -82,6 +82,13 @@ function bindChild(anchor, value) {
 }
 
 function bindAttribute(el, attr, values) {
+  if (attr.name === "ref") {
+    // A callback ref. Only a single ${fn} is meaningful; anything else (a string,
+    // a number, a multi-part value) is rejected by bindRef without touching the DOM.
+    bindRef(el, attr.whole ? values[attr.holes[0]] : undefined);
+    return;
+  }
+
   if (attr.event) {
     const handler = values[attr.holes[0]];
     // Only real functions are accepted as handlers — a string/object is ignored,
@@ -119,6 +126,35 @@ function bindAttribute(el, attr, values) {
   else applyAttribute(el, attr.name, compute());
 }
 
+// A callback ref: hand the real element to user code AFTER the current render is
+// inserted, so focus/scroll/measure see a CONNECTED node. We defer one microtask
+// (render binds while the DOM is still a detached fragment; insertion happens
+// right after render returns, synchronously, so a microtask runs once it's live).
+// Not reactive — the function is read once. An optional returned function is an
+// owner-scoped cleanup, disposed on unmount or list-item removal, exactly like a
+// listener. A non-function value is ignored (with a dev warning) and never sets a
+// "ref" attribute — so an inert string can't be wired up.
+function bindRef(el, fn) {
+  if (typeof fn !== "function") {
+    if (isDev()) console.warn(`Zoijs: "ref" expects a function (el) => …; ignoring ${typeof fn} value`);
+    return;
+  }
+  let active = true;
+  let cleanup = null;
+  onCleanup(() => {
+    active = false;
+    if (cleanup) { cleanup(); cleanup = null; }
+  });
+  queueMicrotask(() => {
+    if (!active) return; // removed before the microtask fired
+    const c = fn(el);
+    if (typeof c === "function") {
+      if (active) cleanup = c;
+      else c(); // disposed during fn(): tear down immediately
+    }
+  });
+}
+
 // ---- text / content bindings -------------------------------------------------
 
 function bindReactiveContent(anchor, getValue) {
@@ -203,7 +239,7 @@ function renderChild(value) {
 // ---- keyed list binding ------------------------------------------------------
 
 function isEach(v) {
-  return v != null && typeof v === "object" && v.__easyEach === true;
+  return v != null && typeof v === "object" && v.__zoijsEach === true;
 }
 
 function setupKeyedList(anchor, marker) {

package/src/index.d.ts

@@ -40,12 +40,29 @@ export interface EachResult {
 /** A component is a function that returns an `html` template. */
 export type Component = () => TemplateResult;
 
+/**
+ * A callback ref. Place it on an element as `ref=${fn}`; it receives the real DOM
+ * element once the surrounding render has been inserted (deferred one microtask,
+ * so `focus()` / `scrollIntoView()` / `getBoundingClientRect()` work). It may
+ * return a cleanup function, which runs on unmount or list-item removal. It runs
+ * once and is not reactive.
+ *
+ * ```ts
+ * html`<input ref=${(el: HTMLInputElement) => el.focus()} />`
+ * html`<div ref=${(el) => { const c = chart(el); return () => c.destroy(); }}></div>`
+ * ```
+ */
+export type Ref<E extends Element = Element> = (element: E) => void | (() => void);
+
 /**
  * Tagged-template function — write your markup as HTML.
  *
  * ```js
  * html`<button onclick=${() => count.set(count.get() + 1)}>${() => count.get()}</button>`
  * ```
+ *
+ * To reach the rendered DOM element, add a callback `ref` (see {@link Ref}):
+ * `html\`<input ref=${(el) => el.focus()} />\``.
  */
 export function html(strings: TemplateStringsArray, ...values: unknown[]): TemplateResult;
 
@@ -74,6 +91,40 @@ export function createState<T>(initial: T, equals?: (a: T, b: T) => boolean): St
  */
 export function computed<T>(fn: () => T, equals?: (a: T, b: T) => boolean): Computed<T>;
 
+/** A disposable handle returned by {@link effect}. */
+export interface EffectHandle {
+  /** Dispose the effect now. It also auto-disposes with its owner (component/list item). */
+  dispose(): void;
+}
+
+/**
+ * Run a side effect that re-runs whenever a reactive value it reads changes.
+ * Runs once immediately, then again (batched on a microtask) on any change.
+ * Dependencies are tracked automatically — there is no dependency array.
+ *
+ * The function may return a cleanup function (same convention as a `ref`); it
+ * runs **before the next run** and **on dispose**. Use the return value for
+ * per-run teardown — `onCleanup` is component-scoped (fires on unmount), not
+ * per-run.
+ *
+ * Created inside a component or list item, it auto-disposes with that scope;
+ * created at module top level, it lives until you call `dispose()`.
+ *
+ * ```ts
+ * // persist on change
+ * effect(() => localStorage.setItem("theme", theme.get()));
+ *
+ * // per-run cleanup
+ * effect(() => {
+ *   const id = setInterval(() => poll(query.get()), 1000);
+ *   return () => clearInterval(id);
+ * });
+ * ```
+ *
+ * For reactive *content on screen*, use a binding (`${() => …}`), not an effect.
+ */
+export function effect(fn: () => void | (() => void)): EffectHandle;
+
 /**
  * Keyed list rendering. `items` may be a reactive function or a plain array;
  * `keyFn` returns a stable unique key; `renderFn` returns the template for one item.

package/src/index.js

@@ -10,5 +10,6 @@ export { mount } from "./core/mount.js";
 export { each } from "./core/each.js";
 export { createState } from "./reactivity/state.js";
 export { computed } from "./reactivity/computed.js";
+export { effect } from "./reactivity/effect.js";
 export { configure } from "./reactivity/env.js";
 export { onCleanup } from "./reactivity/owner.js";

package/src/reactivity/core.js

@@ -105,6 +105,7 @@ function runComputation(node) {
     node.state = CLEAN;
     return;
   }
+  if (node.isEffect) runEffectCleanup(node); // per-run teardown before re-running
   cleanupSources(node);
   const previousObserver = currentObserver;
   currentObserver = node;
@@ -119,7 +120,13 @@ function runComputation(node) {
   } finally {
     currentObserver = previousObserver;
   }
-  if (threw || node.isEffect) return;
+  if (node.isEffect) {
+    // An effect may return a cleanup function (same convention as a ref): it runs
+    // before the next run and on dispose. Anything else is ignored.
+    if (!threw) node.cleanup = typeof result === "function" ? result : null;
+    return;
+  }
+  if (threw) return;
   if (!node.equals(node.value, result)) {
     node.value = result;
     // Value changed → promote observers (currently CHECK) to DIRTY so they update.
@@ -132,10 +139,23 @@ function cleanupSources(node) {
   node.sources.clear();
 }
 
+/** Run (and clear) an effect's returned cleanup — before a re-run and on dispose. */
+function runEffectCleanup(node) {
+  const cleanup = node.cleanup;
+  if (!cleanup) return;
+  node.cleanup = null;
+  try {
+    cleanup();
+  } catch (err) {
+    console.error("Zoijs: an effect cleanup threw (other bindings keep working):", err);
+  }
+}
+
 function disposeNode(node) {
   if (node.disposed) return;
   node.disposed = true;
   cleanupSources(node);
+  if (node.isEffect) runEffectCleanup(node); // final cleanup on dispose
 }
 
 const warned = new WeakSet();
@@ -186,6 +206,7 @@ export function effect(fn) {
     isEffect: true,
     disposed: false,
     equals: Object.is,
+    cleanup: null,
   };
   onCleanup(() => disposeNode(node)); // disposed with its owner scope
   runComputation(node);