@zoijs/core 1.0.0

package/src/core/renderer.js

@@ -0,0 +1,364 @@
+// renderer.js — fine-grained rendering engine.
+//
+// Turns an html() result into live DOM and wires each dynamic slot to a live
+// binding. No Virtual DOM, no component re-execution.
+//
+//   - A FUNCTION value is reactive (runs in an effect): text updates a Text node
+//     in place; attributes update in place.
+//   - An each() marker becomes a keyed LIST binding (reuse / move / remove).
+//   - A non-function value is static (set once, no effect).
+//   - An EVENT slot's value is the handler (addEventListener; never a string).
+//
+// Cleanup is owned: render() creates an owner scope; every effect, listener, and
+// nested render registers into it, so disposing the owner tears everything down.
+
+import { effect, untrack } from "../reactivity/effect.js";
+import { createState } from "../reactivity/state.js";
+import { createOwner, runWithOwner, disposeOwner, onCleanup } from "../reactivity/owner.js";
+import { isDev } from "../reactivity/env.js";
+import { toText, isSafeUrl, isSafeAttributeName } from "../utils/security.js";
+
+const XLINK_NS = "http://www.w3.org/1999/xlink";
+const URL_ATTRS = new Set(["href", "src", "action", "formaction", "poster", "ping", "xlink:href"]);
+const noop = () => {};
+
+/**
+ * @param {{ template: HTMLTemplateElement, parts: object[], values: any[] }} result
+ * @returns {{ node: DocumentFragment, dispose: Function }}
+ */
+export function render(result) {
+  const owner = createOwner(); // nested under the active owner
+  const fragment = result.template.content.cloneNode(true);
+  const { parts, values } = result;
+
+  // Collect every part's target node on the PRISTINE clone first (document
+  // order), so a binding that inserts children can't shadow a later part.
+  const nodes = collectNodes(fragment, parts, result.hasElements);
+
+  runWithOwner(owner, () => {
+    for (let i = 0; i < parts.length; i++) {
+      const part = parts[i];
+      const node = nodes[i];
+      if (!node) continue;
+
+      if (part.type === "child") {
+        bindChild(node, values[part.hole]);
+      } else {
+        node.removeAttribute("data-zoijs-bind");
+        for (const attr of part.attrs) bindAttribute(node, attr, values);
+      }
+    }
+  });
+
+  return { node: fragment, dispose: () => disposeOwner(owner) };
+}
+
+// Match parts to nodes by document order: a child part ↔ the next marker comment,
+// an element part ↔ the next element carrying data-zoijs-bind. Unique markers make
+// this collision-proof across nested templates and list items.
+function collectNodes(fragment, parts, hasElements) {
+  const nodes = new Array(parts.length);
+  if (!parts.length) return nodes;
+  // Child-only templates (common for list items) can walk comments only.
+  const filter = hasElements ? NodeFilter.SHOW_ELEMENT | NodeFilter.SHOW_COMMENT : NodeFilter.SHOW_COMMENT;
+  const walker = document.createTreeWalker(fragment, filter);
+  let p = 0;
+  let node;
+  while (p < parts.length && (node = walker.nextNode())) {
+    const isChildMarker = node.nodeType === 8 && node.data === "zoijs";
+    const isElementMarker = node.nodeType === 1 && node.hasAttribute("data-zoijs-bind");
+    if (isChildMarker || isElementMarker) {
+      nodes[p] = node;
+      p++;
+    }
+  }
+  return nodes;
+}
+
+function bindChild(anchor, value) {
+  if (isEach(value)) setupKeyedList(anchor, value);
+  else if (typeof value === "function") bindReactiveContent(anchor, value);
+  else insertStaticContent(anchor, value);
+}
+
+function bindAttribute(el, attr, values) {
+  if (attr.event) {
+    const handler = values[attr.holes[0]];
+    // Only real functions are accepted as handlers — a string/object is ignored,
+    // so an inline-handler string can never be wired up or executed.
+    if (typeof handler !== "function") {
+      if (isDev()) console.warn(`Zoijs: ignoring non-function event handler for "${attr.name}"`);
+      return;
+    }
+    const eventName = attr.name.slice(2).toLowerCase();
+    el.addEventListener(eventName, handler);
+    onCleanup(() => el.removeEventListener(eventName, handler));
+    return;
+  }
+
+  if (attr.whole) {
+    // A single ${} as the whole value → pass the raw value (preserves booleans,
+    // numbers, property types for value/checked).
+    const raw = values[attr.holes[0]];
+    if (typeof raw === "function") effect(() => applyAttribute(el, attr.name, raw()));
+    else applyAttribute(el, attr.name, raw);
+    return;
+  }
+
+  // Multi-part value (static text + one or more holes) → always a joined string.
+  const compute = () => {
+    let result = attr.strings[0];
+    for (let i = 0; i < attr.holes.length; i++) {
+      const hv = values[attr.holes[i]];
+      result += (typeof hv === "function" ? hv() : hv) + attr.strings[i + 1];
+    }
+    return result;
+  };
+  const reactive = attr.holes.some((h) => typeof values[h] === "function");
+  if (reactive) effect(() => applyAttribute(el, attr.name, compute()));
+  else applyAttribute(el, attr.name, compute());
+}
+
+// ---- text / content bindings -------------------------------------------------
+
+function bindReactiveContent(anchor, getValue) {
+  let mode = null; // "text" | "nodes"
+  let textNode = null;
+  let items = []; // [{ nodes, dispose }]
+
+  const clearNodes = () => {
+    for (const it of items) {
+      it.dispose();
+      for (const n of it.nodes) n.remove();
+    }
+    items = [];
+  };
+  const clearText = () => {
+    if (textNode) {
+      textNode.remove();
+      textNode = null;
+    }
+  };
+
+  effect(() => {
+    const value = getValue();
+    const t = typeof value;
+    // null/undefined/booleans render NOTHING (matches the `cond && html\`...\``
+    // idiom); numbers/strings render as text; everything else is node content.
+    const asText = value == null || t === "boolean" || t === "number" || t === "string" || t === "bigint";
+    if (asText) {
+      if (mode !== "text") {
+        clearNodes();
+        textNode = document.createTextNode("");
+        anchor.parentNode.insertBefore(textNode, anchor);
+        mode = "text";
+      }
+      textNode.data = value == null || t === "boolean" ? "" : toText(value); // in-place update
+    } else {
+      if (mode === "text") clearText();
+      else clearNodes();
+      mode = "nodes";
+      insertItems(anchor, value, items);
+    }
+  });
+
+  onCleanup(() => {
+    clearNodes();
+    clearText();
+  });
+}
+
+function insertStaticContent(anchor, value) {
+  if (value == null) return;
+  const items = [];
+  insertItems(anchor, value, items);
+  onCleanup(() => {
+    for (const it of items) {
+      it.dispose();
+      for (const n of it.nodes) n.remove();
+    }
+  });
+}
+
+function insertItems(anchor, value, items) {
+  const parent = anchor.parentNode;
+  const list = Array.isArray(value) ? value : [value];
+  for (const v of list) {
+    const item = renderChild(v);
+    for (const n of item.nodes) parent.insertBefore(n, anchor);
+    items.push(item);
+  }
+}
+
+function renderChild(value) {
+  if (value == null || value === false || value === true) return { nodes: [], dispose: noop };
+  if (value instanceof Node) return { nodes: [value], dispose: noop };
+  if (isHtmlResult(value)) {
+    const r = render(value);
+    return { nodes: [...r.node.childNodes], dispose: r.dispose };
+  }
+  return { nodes: [document.createTextNode(toText(value))], dispose: noop };
+}
+
+// ---- keyed list binding ------------------------------------------------------
+
+function isEach(v) {
+  return v != null && typeof v === "object" && v.__easyEach === true;
+}
+
+function setupKeyedList(anchor, marker) {
+  const { items, keyFn, renderFn } = marker;
+  const listOwner = createOwner(); // item subtrees nest here
+  let records = new Map();
+  let currentList = [];
+
+  const readItems = () => {
+    const raw = typeof items === "function" ? items() : items;
+    return raw == null ? [] : raw;
+  };
+
+  // Build one item. The item is a reactive proxy over a state cell, so reusing a
+  // node later (itemCell.set) refreshes only its own bindings. render() opens a
+  // child owner (nested in listOwner) so the whole item subtree disposes together.
+  const createRecord = (key, item) => {
+    const isObj = item !== null && typeof item === "object";
+    const itemCell = isObj ? createState(item) : null;
+    const arg = isObj ? makeItemProxy(itemCell) : item;
+    // Run renderFn inside this item's own owner scope, so any onCleanup() it
+    // registers fires when the item is removed (not only on full unmount).
+    const itemOwner = createOwner();
+    let nodes;
+    untrack(() =>
+      runWithOwner(itemOwner, () => {
+        const r = render(renderFn(arg));
+        nodes = [...r.node.childNodes];
+      })
+    );
+    return { key, item, itemCell, nodes, dispose: () => disposeOwner(itemOwner) };
+  };
+
+  const reconcile = (newItems) => {
+    const parent = anchor.parentNode;
+    const oldRecords = records;
+    const newRecords = new Map();
+    const ordered = [];
+    const seen = isDev() ? new Set() : null;
+
+    for (let i = 0; i < newItems.length; i++) {
+      const item = newItems[i];
+      const key = keyFn(item);
+      if (isDev()) {
+        if (seen.has(key)) {
+          console.warn(`Zoijs each(): duplicate key ${stringifyKey(key)} — keys must be unique; DOM for duplicates may be unstable.`);
+        }
+        seen.add(key);
+      }
+      let rec = oldRecords.get(key);
+      if (rec) {
+        oldRecords.delete(key);
+        if (rec.itemCell) rec.itemCell.set(item); // refresh this item's bindings only
+        rec.item = item;
+      } else {
+        rec = createRecord(key, item);
+      }
+      newRecords.set(key, rec);
+      ordered.push(rec);
+    }
+
+    // Removed keys: dispose their owner scope (effects/listeners) + remove nodes.
+    for (const rec of oldRecords.values()) {
+      rec.dispose();
+      for (const n of rec.nodes) n.remove();
+    }
+
+    // Place nodes in order before the anchor, moving only those out of position.
+    let cursor = anchor;
+    for (let i = ordered.length - 1; i >= 0; i--) {
+      const rec = ordered[i];
+      let ref = cursor;
+      for (let j = rec.nodes.length - 1; j >= 0; j--) {
+        const node = rec.nodes[j];
+        if (node.nextSibling !== ref) parent.insertBefore(node, ref);
+        ref = node;
+      }
+      cursor = rec.nodes[0] || cursor;
+    }
+
+    records = newRecords;
+    currentList = ordered;
+  };
+
+  effect(() => {
+    const newItems = readItems(); // tracked: subscribe to the list state
+    runWithOwner(listOwner, () => reconcile(newItems));
+  });
+
+  onCleanup(() => {
+    for (const rec of currentList) {
+      rec.dispose();
+      for (const n of rec.nodes) n.remove();
+    }
+  });
+}
+
+function makeItemProxy(itemCell) {
+  return new Proxy(
+    {},
+    {
+      get(_, prop) {
+        const item = itemCell.get();
+        if (item == null) return undefined;
+        const v = item[prop];
+        return typeof v === "function" ? v.bind(item) : v;
+      },
+      has(_, prop) {
+        const item = itemCell.get();
+        return item != null && prop in Object(item);
+      },
+    }
+  );
+}
+
+function stringifyKey(key) {
+  try {
+    return JSON.stringify(key);
+  } catch {
+    return String(key);
+  }
+}
+
+// ---- attribute binding -------------------------------------------------------
+
+function applyAttribute(el, name, value) {
+  if (!isSafeAttributeName(name)) {
+    if (isDev()) console.warn(`Zoijs: refusing to bind unsafe attribute "${name}"`);
+    return;
+  }
+  if (URL_ATTRS.has(name) && !isSafeUrl(toText(value))) {
+    if (isDev()) console.warn(`Zoijs: refusing unsafe URL in "${name}": ${value}`);
+    return;
+  }
+  if (name === "value" || name === "checked") {
+    el[name] = value; // form-control state lives on the property
+    return;
+  }
+  if (name.startsWith("xlink:")) {
+    // SVG namespaced attribute (e.g. xlink:href).
+    if (value === false || value == null) el.removeAttributeNS(XLINK_NS, name.slice(6));
+    else el.setAttributeNS(XLINK_NS, name, toText(value));
+    return;
+  }
+  if (value === false || value == null) {
+    el.removeAttribute(name);
+  } else if (value === true) {
+    el.setAttribute(name, "");
+  } else {
+    el.setAttribute(name, toText(value));
+  }
+}
+
+// ---- helpers -----------------------------------------------------------------
+
+function isHtmlResult(v) {
+  return v && typeof v === "object" && v.template && Array.isArray(v.parts);
+}

package/src/index.d.ts

@@ -0,0 +1,113 @@
+// Type definitions for Zoijs.
+//
+// Zoijs is authored in plain JavaScript; these declarations add editor
+// autocomplete and optional type-checking WITHOUT converting the project to
+// TypeScript. Using them is entirely opt-in — JS users are unaffected.
+
+/** A reactive value created by {@link createState}. */
+export interface State<T> {
+  /** Read the current value. Inside a binding/effect this subscribes to it. */
+  get(): T;
+  /** Write a new value. Dependents update only if the value actually changed. */
+  set(next: T): void;
+  /** Read the current value WITHOUT subscribing. */
+  peek(): T;
+}
+
+/** A lazy, cached, value-gated derived value created by {@link computed}. */
+export interface Computed<T> {
+  /** Read the current value. Recomputes only if a dependency changed. */
+  get(): T;
+  /** Read without subscribing. */
+  peek(): T;
+}
+
+declare const templateBrand: unique symbol;
+/**
+ * The result of an `html` template. Pass it to {@link mount}, return it from a
+ * component, or place it in another template. Treat it as opaque.
+ */
+export interface TemplateResult {
+  readonly [templateBrand]: true;
+}
+
+declare const eachBrand: unique symbol;
+/** The result of {@link each}. Place it in a template's child position. */
+export interface EachResult {
+  readonly [eachBrand]: true;
+}
+
+/** A component is a function that returns an `html` template. */
+export type Component = () => TemplateResult;
+
+/**
+ * Tagged-template function — write your markup as HTML.
+ *
+ * ```js
+ * html`<button onclick=${() => count.set(count.get() + 1)}>${() => count.get()}</button>`
+ * ```
+ */
+export function html(strings: TemplateStringsArray, ...values: unknown[]): TemplateResult;
+
+/**
+ * Render a component (or a template) into a DOM element or CSS selector.
+ * Returns an `unmount()` that detaches the DOM and disposes all reactivity.
+ */
+export function mount(component: Component | TemplateResult, target: Element | string): () => void;
+
+/**
+ * Create a reactive value.
+ *
+ * ```ts
+ * const count = createState(0);        // State<number>
+ * const name = createState<string>(""); // explicit
+ * ```
+ */
+export function createState<T>(initial: T, equals?: (a: T, b: T) => boolean): State<T>;
+
+/**
+ * Create a lazy, cached derived value.
+ *
+ * ```ts
+ * const fullName = computed(() => `${first.get()} ${last.get()}`); // Computed<string>
+ * ```
+ */
+export function computed<T>(fn: () => T, equals?: (a: T, b: T) => boolean): Computed<T>;
+
+/**
+ * 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.
+ *
+ * ```ts
+ * each(() => todos.get(), (t) => t.id, (t) => html`<li>${() => t.text}</li>`)
+ * ```
+ */
+export function each<T>(
+  items: () => readonly T[],
+  keyFn: (item: T) => unknown,
+  renderFn: (item: T) => TemplateResult
+): EachResult;
+export function each<T>(
+  items: readonly T[],
+  keyFn: (item: T) => unknown,
+  renderFn: (item: T) => TemplateResult
+): EachResult;
+
+/** Toggle development warnings (default: `dev` is `true`). */
+export function configure(options: { dev?: boolean }): void;
+
+/**
+ * Register a teardown function for the current component or list item. It runs
+ * when that component is unmounted or that list item is removed. Use it for
+ * timers, subscriptions, or third-party widgets created during setup.
+ *
+ * ```ts
+ * function Clock() {
+ *   const now = createState(Date.now());
+ *   const id = setInterval(() => now.set(Date.now()), 1000);
+ *   onCleanup(() => clearInterval(id));
+ *   return html`<time>${() => now.get()}</time>`;
+ * }
+ * ```
+ */
+export function onCleanup(fn: () => void): void;

package/src/index.js

@@ -0,0 +1,14 @@
+// Zoijs — public entry point.
+//
+// Re-exports the entire public API surface for the MVP. Keep this list small:
+// the whole framework is meant to be learnable in one sitting.
+//
+//   import { html, mount, createState } from "@zoijs/core";
+
+export { html } from "./core/html.js";
+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 { configure } from "./reactivity/env.js";
+export { onCleanup } from "./reactivity/owner.js";

package/src/reactivity/computed.js

@@ -0,0 +1,10 @@
+// computed() — lazy, cached, value-gated derived state.
+//
+//   const fullName = computed(() => `${first.get()} ${last.get()}`);
+//
+// Recomputes only when a dependency changed AND only on read. Crucially, if the
+// recomputed value is unchanged, subscribers are NOT woken (value gating).
+//
+// Implemented by the shared reactive core (see core.js).
+
+export { computed } from "./core.js";

package/src/reactivity/core.js

@@ -0,0 +1,205 @@
+// core.js — the reactive graph: states, computeds, effects.
+//
+// One unified push-pull algorithm (CLEAN / CHECK / DIRTY) gives value-gated,
+// lazy, cached updates:
+//
+//   - A write marks observers DIRTY and their observers CHECK ("maybe dirty"),
+//     and enqueues affected effects (batched on a microtask).
+//   - On run, an effect/computed PULLS its sources: it only recomputes if a
+//     source is actually DIRTY. A computed that recomputes to the SAME value
+//     does not wake its observers — that is the value gating (Task 1).
+//
+// Nodes:
+//   state    { value, observers, equals, fn:null }
+//   computed { value, observers, sources, state, equals, fn, isEffect:false }
+//   effect   {        observers, sources, state,         fn, isEffect:true  }
+
+import { onCleanup } from "./owner.js";
+import { isDev } from "./env.js";
+
+const CLEAN = 0;
+const CHECK = 1;
+const DIRTY = 2;
+
+let currentObserver = null;
+
+// ---- batching scheduler -----------------------------------------------------
+
+const queue = new Set();
+let scheduled = false;
+const RUNAWAY_LIMIT = 100;
+
+function enqueue(node) {
+  queue.add(node);
+  if (!scheduled) {
+    scheduled = true;
+    queueMicrotask(flush);
+  }
+}
+
+/** Run all queued effects (and anything they schedule) to completion, in order. */
+export function flush() {
+  scheduled = false;
+  const runCounts = new Map();
+  while (queue.size) {
+    const nodes = [...queue];
+    queue.clear();
+    for (const node of nodes) {
+      const count = (runCounts.get(node) || 0) + 1;
+      runCounts.set(node, count);
+      if (count === RUNAWAY_LIMIT && isDev()) {
+        console.warn(`Zoijs: an effect re-ran ${RUNAWAY_LIMIT}× in one flush — stopping it (possible infinite loop).`, node.fn);
+      }
+      if (count >= RUNAWAY_LIMIT) continue;
+      updateIfNecessary(node);
+    }
+  }
+}
+
+// ---- graph internals --------------------------------------------------------
+
+function readNode(node) {
+  if (currentObserver) {
+    node.observers.add(currentObserver);
+    currentObserver.sources.add(node);
+  }
+  if (node.fn) updateIfNecessary(node); // computed: make sure it's fresh
+  return node.value;
+}
+
+function writeNode(node, next) {
+  if (node.equals(node.value, next)) return; // equality-gated
+  node.value = next;
+  for (const observer of [...node.observers]) markStale(observer, DIRTY);
+}
+
+function markStale(node, newState) {
+  if (node === currentObserver && isDev()) {
+    warnOnce(node, "Zoijs: an effect/computed updated state it depends on (self-triggering). Derive with computed() or guard the write.");
+  }
+  if (node.state < newState) {
+    const previous = node.state;
+    node.state = newState;
+    if (previous === CLEAN) {
+      for (const observer of node.observers) markStale(observer, CHECK);
+      if (node.isEffect) enqueue(node);
+    }
+  }
+}
+
+function updateIfNecessary(node) {
+  if (node.disposed) return;
+  if (node.state === CHECK) {
+    // "maybe dirty": resolve sources; recompute only if one really changed.
+    for (const source of node.sources) {
+      if (source.fn) updateIfNecessary(source);
+      if (node.state === DIRTY) break;
+    }
+  }
+  if (node.state === DIRTY) runComputation(node);
+  node.state = CLEAN;
+}
+
+function runComputation(node) {
+  if (node.disposed) {
+    node.state = CLEAN;
+    return;
+  }
+  cleanupSources(node);
+  const previousObserver = currentObserver;
+  currentObserver = node;
+  let result;
+  let threw = false;
+  try {
+    result = node.fn();
+  } catch (err) {
+    threw = true;
+    // Task 3/5: contain the failure so other bindings keep working.
+    console.error("Zoijs: a reactive binding threw (other bindings keep working):", err);
+  } finally {
+    currentObserver = previousObserver;
+  }
+  if (threw || node.isEffect) return;
+  if (!node.equals(node.value, result)) {
+    node.value = result;
+    // Value changed → promote observers (currently CHECK) to DIRTY so they update.
+    for (const observer of node.observers) observer.state = DIRTY;
+  }
+}
+
+function cleanupSources(node) {
+  for (const source of node.sources) source.observers.delete(node);
+  node.sources.clear();
+}
+
+function disposeNode(node) {
+  if (node.disposed) return;
+  node.disposed = true;
+  cleanupSources(node);
+}
+
+const warned = new WeakSet();
+function warnOnce(node, message) {
+  if (warned.has(node)) return;
+  warned.add(node);
+  console.warn(message, node.fn);
+}
+
+// ---- public primitives ------------------------------------------------------
+
+export function createState(initial, equals = Object.is) {
+  const node = { value: initial, observers: new Set(), equals, fn: null };
+  return {
+    get: () => readNode(node),
+    set: (next) => writeNode(node, next),
+    peek: () => node.value,
+  };
+}
+
+export function computed(fn, equals = Object.is) {
+  const node = {
+    fn,
+    value: undefined,
+    observers: new Set(),
+    sources: new Set(),
+    state: DIRTY,
+    isEffect: false,
+    disposed: false,
+    equals,
+  };
+  onCleanup(() => disposeNode(node)); // disposed with its owner scope
+  return {
+    get: () => readNode(node),
+    peek: () => {
+      updateIfNecessary(node);
+      return node.value;
+    },
+  };
+}
+
+export function effect(fn) {
+  const node = {
+    fn,
+    observers: new Set(),
+    sources: new Set(),
+    state: DIRTY,
+    isEffect: true,
+    disposed: false,
+    equals: Object.is,
+  };
+  onCleanup(() => disposeNode(node)); // disposed with its owner scope
+  runComputation(node);
+  node.state = CLEAN;
+  return { dispose: () => disposeNode(node) };
+}
+
+/** Run `fn` without subscribing the current observer to what it reads. */
+export function untrack(fn) {
+  const previous = currentObserver;
+  currentObserver = null;
+  try {
+    return fn();
+  } finally {
+    currentObserver = previous;
+  }
+}