decantr 0.9.0

package/src/test/dom.js

@@ -0,0 +1,352 @@
+class EventTarget_ {
+  constructor() {
+    /** @type {Map<string, Set<Function>>} */
+    this._listeners = new Map();
+  }
+  addEventListener(type, fn) {
+    let set = this._listeners.get(type);
+    if (!set) { set = new Set(); this._listeners.set(type, set); }
+    set.add(fn);
+  }
+  removeEventListener(type, fn) {
+    const set = this._listeners.get(type);
+    if (set) set.delete(fn);
+  }
+  dispatchEvent(event) {
+    try { event.target = this; } catch (e) { /* target may be read-only */ }
+    let node = this;
+    while (node) {
+      try { event.currentTarget = node; } catch (e) { /* currentTarget may be read-only */ }
+      const set = node._listeners ? node._listeners.get(event.type) : null;
+      if (set) for (const fn of set) fn(event);
+      node = event.bubbles ? node.parentNode : null;
+    }
+    return true;
+  }
+}
+
+class Node_ extends EventTarget_ {
+  constructor(nodeType) {
+    super();
+    this.nodeType = nodeType;
+    this.parentNode = null;
+    this.childNodes = [];
+    this.nodeValue = null;
+  }
+  get textContent() {
+    if (this.nodeType === 3) return this.nodeValue;
+    if (this.nodeType === 8) return this.nodeValue;
+    return this.childNodes.map(c => c.textContent).join('');
+  }
+  set textContent(v) {
+    if (this.nodeType === 3 || this.nodeType === 8) { this.nodeValue = v; return; }
+    this.childNodes.forEach(c => { c.parentNode = null; });
+    this.childNodes = [];
+    if (v) this.appendChild(new Text_(v));
+  }
+  appendChild(child) {
+    if (child.parentNode) child.parentNode.removeChild(child);
+    child.parentNode = this;
+    this.childNodes.push(child);
+    return child;
+  }
+  removeChild(child) {
+    const i = this.childNodes.indexOf(child);
+    if (i !== -1) { this.childNodes.splice(i, 1); child.parentNode = null; }
+    return child;
+  }
+  insertBefore(newChild, ref) {
+    if (newChild.parentNode) newChild.parentNode.removeChild(newChild);
+    const i = ref ? this.childNodes.indexOf(ref) : this.childNodes.length;
+    newChild.parentNode = this;
+    this.childNodes.splice(i === -1 ? this.childNodes.length : i, 0, newChild);
+    return newChild;
+  }
+  replaceChildren(...nodes) {
+    this.childNodes.forEach(c => { c.parentNode = null; });
+    this.childNodes = [];
+    for (const n of nodes) this.appendChild(n);
+  }
+  get firstChild() { return this.childNodes[0] || null; }
+  get lastChild() { return this.childNodes[this.childNodes.length - 1] || null; }
+  get nextSibling() {
+    if (!this.parentNode) return null;
+    const i = this.parentNode.childNodes.indexOf(this);
+    return this.parentNode.childNodes[i + 1] || null;
+  }
+  get previousSibling() {
+    if (!this.parentNode) return null;
+    const i = this.parentNode.childNodes.indexOf(this);
+    return this.parentNode.childNodes[i - 1] || null;
+  }
+  contains(other) {
+    if (this === other) return true;
+    return this.childNodes.some(c => c.contains(other));
+  }
+  cloneNode(deep) {
+    const clone = new this.constructor(this.nodeType);
+    clone.nodeValue = this.nodeValue;
+    if (deep) {
+      for (const c of this.childNodes) clone.appendChild(c.cloneNode(true));
+    }
+    return clone;
+  }
+}
+
+class Text_ extends Node_ {
+  constructor(data) {
+    super(3);
+    this.nodeValue = String(data);
+  }
+  get data() { return this.nodeValue; }
+  set data(v) { this.nodeValue = v; }
+}
+
+class Comment_ extends Node_ {
+  constructor(data) {
+    super(8);
+    this.nodeValue = data || '';
+  }
+}
+
+class ClassList_ {
+  constructor(el) { this._el = el; }
+  _classes() { return (this._el._attrs.get('class') || '').split(/\s+/).filter(Boolean); }
+  _set(arr) { this._el._attrs.set('class', arr.join(' ')); }
+  add(...tokens) { const c = this._classes(); for (const t of tokens) if (!c.includes(t)) c.push(t); this._set(c); }
+  remove(...tokens) { this._set(this._classes().filter(c => !tokens.includes(c))); }
+  toggle(token, force) {
+    const has = this.contains(token);
+    if (force !== undefined) { if (force) { if (!has) this.add(token); } else { this.remove(token); } return force; }
+    if (has) { this.remove(token); return false; }
+    this.add(token); return true;
+  }
+  contains(token) { return this._classes().includes(token); }
+  get length() { return this._classes().length; }
+}
+
+class Element_ extends Node_ {
+  constructor(tagName) {
+    super(1);
+    this.tagName = tagName.toUpperCase();
+    this.localName = tagName.toLowerCase();
+    /** @type {Map<string, string>} */
+    this._attrs = new Map();
+    this.style = {};
+    this.classList = new ClassList_(this);
+    this._defineReflectedProps();
+    this._open = false;
+  }
+  _defineReflectedProps() {
+    for (const prop of ['disabled', 'checked', 'readOnly', 'required']) {
+      const attr = prop.toLowerCase();
+      Object.defineProperty(this, prop, {
+        get() { return this._attrs.has(attr); },
+        set(v) { if (v) this._attrs.set(attr, ''); else this._attrs.delete(attr); },
+        configurable: true,
+      });
+    }
+  }
+  get open() { return this._open; }
+  showModal() { this._open = true; }
+  close() {
+    if (this._open) {
+      this._open = false;
+      this.dispatchEvent(new Event_('close'));
+    }
+  }
+  showPopover() {
+    this._popoverOpen = true;
+    const e = new Event_('toggle'); e.newState = 'open'; e.oldState = 'closed';
+    this.dispatchEvent(e);
+  }
+  hidePopover() {
+    if (this._popoverOpen) {
+      this._popoverOpen = false;
+      const e = new Event_('toggle'); e.newState = 'closed'; e.oldState = 'open';
+      this.dispatchEvent(e);
+    }
+  }
+  click() { this.dispatchEvent(new Event_('click', { bubbles: true })); }
+  getAttribute(name) { return this._attrs.get(name) ?? null; }
+  setAttribute(name, value) { this._attrs.set(name, String(value)); }
+  removeAttribute(name) { this._attrs.delete(name); }
+  hasAttribute(name) { return this._attrs.has(name); }
+  get dataset() {
+    const el = this;
+    return new Proxy({}, {
+      get(_, prop) {
+        const attr = 'data-' + prop.replace(/[A-Z]/g, m => '-' + m.toLowerCase());
+        return el._attrs.get(attr) ?? undefined;
+      },
+      set(_, prop, value) {
+        const attr = 'data-' + prop.replace(/[A-Z]/g, m => '-' + m.toLowerCase());
+        el._attrs.set(attr, String(value));
+        return true;
+      }
+    });
+  }
+  get className() { return this._attrs.get('class') || ''; }
+  set className(v) { this._attrs.set('class', v); }
+  get id() { return this._attrs.get('id') || ''; }
+  set id(v) { this._attrs.set('id', v); }
+  get innerHTML() {
+    return this.childNodes.map(c => {
+      if (c.nodeType === 3) return c.nodeValue;
+      if (c.nodeType === 8) return `<!--${c.nodeValue}-->`;
+      if (c.nodeType === 1) return c.outerHTML;
+      return '';
+    }).join('');
+  }
+  set innerHTML(v) {
+    this.replaceChildren();
+    if (v) this.appendChild(new Text_(v));
+  }
+  get outerHTML() {
+    const tag = this.localName;
+    let attrs = '';
+    for (const [k, v] of this._attrs) attrs += ` ${k}="${v}"`;
+    return `<${tag}${attrs}>${this.innerHTML}</${tag}>`;
+  }
+  append(...nodes) {
+    for (const n of nodes) {
+      this.appendChild(typeof n === 'string' ? new Text_(n) : n);
+    }
+  }
+  prepend(...nodes) {
+    const first = this.firstChild;
+    for (const n of nodes) {
+      this.insertBefore(typeof n === 'string' ? new Text_(n) : n, first);
+    }
+  }
+  remove() {
+    if (this.parentNode) this.parentNode.removeChild(this);
+  }
+  querySelector(selector) {
+    return queryOne(this, selector);
+  }
+  querySelectorAll(selector) {
+    const results = [];
+    queryAll(this, selector, results);
+    return results;
+  }
+  get children() {
+    return this.childNodes.filter(c => c.nodeType === 1);
+  }
+  closest(selector) {
+    let node = this;
+    while (node) {
+      if (node.nodeType === 1 && matchesSelector(node, selector)) return node;
+      node = node.parentNode;
+    }
+    return null;
+  }
+  matches(selector) {
+    return matchesSelector(this, selector);
+  }
+}
+
+function matchesSelector(el, selector) {
+  if (selector.startsWith('#')) return el.id === selector.slice(1);
+  if (selector.startsWith('.')) return el.className.split(/\s+/).includes(selector.slice(1));
+  if (selector.startsWith('[')) {
+    const m = selector.match(/^\[([^\]=]+)(?:="([^"]*)")?\]$/);
+    if (m) return el.hasAttribute(m[1]) && (m[2] === undefined || el.getAttribute(m[1]) === m[2]);
+    return false;
+  }
+  return el.localName === selector.toLowerCase();
+}
+
+function queryOne(el, selector) {
+  for (const child of el.childNodes) {
+    if (child.nodeType === 1) {
+      if (matchesSelector(child, selector)) return child;
+      const found = queryOne(child, selector);
+      if (found) return found;
+    }
+  }
+  return null;
+}
+
+function queryAll(el, selector, results) {
+  for (const child of el.childNodes) {
+    if (child.nodeType === 1) {
+      if (matchesSelector(child, selector)) results.push(child);
+      queryAll(child, selector, results);
+    }
+  }
+}
+
+class Document_ extends Node_ {
+  constructor() {
+    super(9);
+    this.body = this.createElement('body');
+    this.head = this.createElement('head');
+    this.documentElement = this.createElement('html');
+    this.documentElement.appendChild(this.head);
+    this.documentElement.appendChild(this.body);
+    this.appendChild(this.documentElement);
+  }
+  createElement(tag) { return new Element_(tag); }
+  createElementNS(ns, tag) { return new Element_(tag); }
+  createTextNode(data) { return new Text_(data); }
+  createComment(data) { return new Comment_(data); }
+  createDocumentFragment() { return new Element_('d-fragment'); }
+  getElementById(id) { return queryOne(this.documentElement, `#${id}`); }
+  querySelector(sel) { return queryOne(this.documentElement, sel); }
+  querySelectorAll(sel) {
+    const results = [];
+    queryAll(this.documentElement, sel, results);
+    return results;
+  }
+}
+
+class Event_ {
+  constructor(type, opts = {}) {
+    this.type = type;
+    this.bubbles = opts.bubbles || false;
+    this.cancelable = opts.cancelable || false;
+    this.target = null;
+    this.defaultPrevented = false;
+  }
+  preventDefault() { this.defaultPrevented = true; }
+  stopPropagation() { this.bubbles = false; }
+}
+
+/**
+ * @returns {{ document: Document_, window: Object, cleanup: Function }}
+ */
+export function createDOM() {
+  const doc = new Document_();
+  const win = {
+    document: doc,
+    Event: Event_,
+    location: { hash: '', pathname: '/', search: '', href: 'http://localhost/' },
+    history: {
+      _stack: [{ state: null, url: '/' }],
+      pushState(state, title, url) { this._stack.push({ state, url }); win.location.pathname = url; },
+      replaceState(state, title, url) { this._stack[this._stack.length - 1] = { state, url }; win.location.pathname = url; },
+      back() { if (this._stack.length > 1) this._stack.pop(); },
+      forward() { /* no-op in test DOM — no forward stack */ }
+    },
+    addEventListener: doc.addEventListener.bind(doc),
+    removeEventListener: doc.removeEventListener.bind(doc),
+    dispatchEvent: doc.dispatchEvent.bind(doc)
+  };
+  const prevDoc = globalThis.document;
+  const prevWin = globalThis.window;
+  globalThis.document = doc;
+  globalThis.window = win;
+  return {
+    document: doc,
+    window: win,
+    cleanup() {
+      if (prevDoc) globalThis.document = prevDoc;
+      else delete globalThis.document;
+      if (prevWin) globalThis.window = prevWin;
+      else delete globalThis.window;
+    }
+  };
+}
+
+export { Element_, Text_, Comment_, Document_, Event_ };

package/src/test/index.js

@@ -0,0 +1,62 @@
+export { describe, it, test, before, after, beforeEach, afterEach, mock } from 'node:test';
+import assert from 'node:assert/strict';
+export { assert };
+export { createDOM } from './dom.js';
+export { flushEffects, withScope, mockSignal, expectEffect, expectSignal, createTestStore, settled } from './state.js';
+import { createDOM } from './dom.js';
+import { flush as flushScheduler } from '../state/scheduler.js';
+
+/**
+ * @param {Function} component
+ * @returns {{ container: Element, getByText: Function, getByClass: Function, getById: Function }}
+ */
+export function render(component) {
+  const { document, cleanup } = createDOM();
+  const container = document.createElement('div');
+  document.body.appendChild(container);
+  const result = component();
+  if (result) container.appendChild(result);
+
+  function getByText(text) {
+    return findByText(container, text);
+  }
+
+  function getByClass(cls) {
+    return container.querySelector(`.${cls}`);
+  }
+
+  function getById(id) {
+    return container.querySelector(`#${id}`);
+  }
+
+  return { container, getByText, getByClass, getById, cleanup };
+}
+
+function findByText(el, text) {
+  for (const child of el.childNodes) {
+    if (child.nodeType === 1) {
+      if (child.textContent.trim() === text) return child;
+      const found = findByText(child, text);
+      if (found) return found;
+    }
+  }
+  return null;
+}
+
+/**
+ * @param {Element} el
+ * @param {string} event
+ * @param {Object} [detail]
+ */
+export function fire(el, event, detail) {
+  const evt = { type: event, target: el, bubbles: true, cancelable: true, defaultPrevented: false, preventDefault() { this.defaultPrevented = true; }, stopPropagation() {}, ...detail };
+  el.dispatchEvent(evt);
+}
+
+/**
+ * @returns {Promise<void>}
+ */
+export async function flush() {
+  flushScheduler();
+  await new Promise(r => setTimeout(r, 0));
+}

package/src/test/state.js

@@ -0,0 +1,306 @@
+/**
+ * Testing utilities for Decantr's reactive state system.
+ *
+ * Provides helpers for synchronous effect flushing, scoped reactive contexts,
+ * mock signals with instrumentation, and assertion wrappers.
+ *
+ * @module test/state
+ */
+
+import { createSignal, createEffect, createRoot, createStore } from '../state/index.js';
+import { flush } from '../state/scheduler.js';
+
+// ─── flushEffects ────────────────────────────────────────────
+
+/**
+ * Synchronously flush all pending batched effects.
+ * Call after mutating signals inside `batch()` to force immediate propagation.
+ */
+export function flushEffects() {
+  flush();
+}
+
+// ─── withScope ───────────────────────────────────────────────
+
+/**
+ * Run `fn` inside an isolated reactive root that auto-disposes on completion.
+ * All signals, effects, and memos created within `fn` are cleaned up automatically.
+ *
+ * @template T
+ * @param {() => T} fn
+ * @returns {T}
+ */
+export function withScope(fn) {
+  /** @type {T} */
+  let result;
+  createRoot((dispose) => {
+    try {
+      result = fn();
+    } finally {
+      dispose();
+    }
+  });
+  return result;
+}
+
+// ─── mockSignal ──────────────────────────────────────────────
+
+/**
+ * Create an instrumented signal for testing.
+ * Tracks read/write counts and value history.
+ *
+ * @template T
+ * @param {T} initialValue
+ * @returns {{
+ *   get: () => T,
+ *   set: (v: T | ((prev: T) => T)) => void,
+ *   getter: () => T,
+ *   setter: (v: T | ((prev: T) => T)) => void,
+ *   readCount: number,
+ *   writeCount: number,
+ *   history: T[],
+ *   reset: () => void
+ * }}
+ */
+export function mockSignal(initialValue) {
+  const [getter, setter] = createSignal(initialValue);
+
+  /** @type {T[]} */
+  const history = [initialValue];
+
+  const mock = {
+    readCount: 0,
+    writeCount: 0,
+    history,
+
+    /**
+     * Read the current value. Increments `readCount`.
+     * Participates in reactive tracking (safe inside effects).
+     * @returns {T}
+     */
+    get() {
+      mock.readCount++;
+      return getter();
+    },
+
+    /**
+     * Write a new value. Increments `writeCount` and appends to `history`.
+     * @param {T | ((prev: T) => T)} v
+     */
+    set(v) {
+      mock.writeCount++;
+      setter(v);
+      history.push(getter());
+    },
+
+    /** Alias — pass to APIs that expect a getter function. */
+    get getter() { return mock.get; },
+
+    /** Alias — pass to APIs that expect a setter function. */
+    get setter() { return mock.set; },
+
+    /**
+     * Reset to initial value, clear counters, and truncate history.
+     */
+    reset() {
+      mock.readCount = 0;
+      mock.writeCount = 0;
+      history.length = 0;
+      history.push(initialValue);
+      setter(initialValue);
+    }
+  };
+
+  return mock;
+}
+
+// ─── expectEffect ────────────────────────────────────────────
+
+/**
+ * Run a reactive effect and return assertion helpers.
+ * The effect is tracked for run-count and can be disposed manually.
+ *
+ * @param {Function} fn — effect body (same signature as `createEffect`)
+ * @returns {{
+ *   runCount: number,
+ *   toHaveRun: () => void,
+ *   toHaveRunTimes: (n: number) => void,
+ *   dispose: () => void
+ * }}
+ */
+export function expectEffect(fn) {
+  let runCount = 0;
+
+  const dispose = createEffect(() => {
+    runCount++;
+    return fn();
+  });
+
+  const handle = {
+    /** Current number of times the effect body has executed. */
+    get runCount() { return runCount; },
+
+    /**
+     * Assert that the effect has executed at least once.
+     * @throws {Error} if the effect never ran
+     */
+    toHaveRun() {
+      if (runCount === 0) {
+        throw new Error('Expected effect to have run, but it never executed');
+      }
+    },
+
+    /**
+     * Assert that the effect has executed exactly `n` times.
+     * @param {number} n
+     * @throws {Error} if count does not match
+     */
+    toHaveRunTimes(n) {
+      if (runCount !== n) {
+        throw new Error(
+          `Expected effect to have run ${n} time(s), but it ran ${runCount} time(s)`
+        );
+      }
+    },
+
+    /**
+     * Dispose the effect so it stops reacting to signal changes.
+     */
+    dispose
+  };
+
+  return handle;
+}
+
+// ─── expectSignal ────────────────────────────────────────────
+
+/**
+ * Wrap a signal getter with assertion helpers.
+ *
+ * @template T
+ * @param {() => T} getter — signal getter function
+ * @returns {{
+ *   toEqual: (expected: T) => void,
+ *   toBeTruthy: () => void,
+ *   toBeFalsy: () => void
+ * }}
+ */
+export function expectSignal(getter) {
+  return {
+    /**
+     * Assert that the signal's current value equals `expected` (via `Object.is`).
+     * @param {T} expected
+     * @throws {Error} if values are not equal
+     */
+    toEqual(expected) {
+      const actual = getter();
+      if (!Object.is(actual, expected)) {
+        throw new Error(
+          `Expected signal to equal ${JSON.stringify(expected)}, but got ${JSON.stringify(actual)}`
+        );
+      }
+    },
+
+    /**
+     * Assert that the signal's current value is truthy.
+     * @throws {Error} if value is falsy
+     */
+    toBeTruthy() {
+      const actual = getter();
+      if (!actual) {
+        throw new Error(
+          `Expected signal to be truthy, but got ${JSON.stringify(actual)}`
+        );
+      }
+    },
+
+    /**
+     * Assert that the signal's current value is falsy.
+     * @throws {Error} if value is truthy
+     */
+    toBeFalsy() {
+      const actual = getter();
+      if (actual) {
+        throw new Error(
+          `Expected signal to be falsy, but got ${JSON.stringify(actual)}`
+        );
+      }
+    }
+  };
+}
+
+// ─── createTestStore ─────────────────────────────────────────
+
+/**
+ * Create a reactive store with change recording.
+ * Every property mutation is captured in `changes` for later assertions.
+ *
+ * @template {Record<string, any>} T
+ * @param {T} init — initial store values
+ * @returns {{
+ *   proxy: T,
+ *   changes: Array<{ prop: string, prev: any, next: any }>,
+ *   reset: () => void
+ * }}
+ */
+export function createTestStore(init) {
+  const snapshot = { ...init };
+  const store = createStore({ ...init });
+
+  /** @type {Array<{ prop: string, prev: any, next: any }>} */
+  const changes = [];
+
+  const proxy = new Proxy(store, {
+    set(target, prop, value) {
+      const prev = target[prop];
+      target[prop] = value;
+      changes.push({ prop: /** @type {string} */ (prop), prev, next: value });
+      return true;
+    }
+  });
+
+  return {
+    proxy,
+    changes,
+
+    /**
+     * Reset all properties to initial values and clear the change log.
+     */
+    reset() {
+      changes.length = 0;
+      for (const key of Object.keys(snapshot)) {
+        store[key] = snapshot[key];
+      }
+    }
+  };
+}
+
+// ─── settled ─────────────────────────────────────────────────
+
+/**
+ * Wait for all microtasks to settle. Useful after async signal updates.
+ *
+ * @param {{ timeout?: number }} [options]
+ * @returns {Promise<void>}
+ */
+export function settled(options = {}) {
+  const { timeout } = options;
+
+  const tick = () => new Promise((resolve) => { queueMicrotask(resolve); });
+
+  if (timeout == null) {
+    // Drain two rounds of microtasks to catch cascading effects
+    return tick().then(tick);
+  }
+
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      reject(new Error(`settled() timed out after ${timeout}ms`));
+    }, timeout);
+
+    tick().then(tick).then(() => {
+      clearTimeout(timer);
+      resolve();
+    });
+  });
+}