@granularjs/core 1.0.0

package/src/core/dom/virtual-list.js

@@ -0,0 +1,242 @@
+import { Renderable } from '../renderable/renderable.js';
+import { Renderer } from '../renderable/renderer.js';
+import { isObservableArray } from '../collections/observable-array.js';
+import { isSignal, readSignal, subscribeSignal } from '../reactivity/signal.js';
+import { isState, isStatePath, readState, subscribeState } from '../reactivity/state.js';
+
+function clamp(value, min, max) {
+  return Math.max(min, Math.min(max, value));
+}
+
+function isNumber(value) {
+  return typeof value === 'number' && !Number.isNaN(value);
+}
+
+export class VirtualListNode extends Renderable {
+  #items;
+  #renderItem;
+  #direction;
+  #overscan;
+  #itemSize;
+  #container = null;
+  #spacer = null;
+  #itemsEl = null;
+  #mounted = false;
+  #unsub = null;
+  #resizeObserver = null;
+  #viewportSize = 0;
+  #startIndex = 0;
+  #endIndex = -1;
+  #mountedValues = [];
+  #measuring = false;
+
+  constructor(items, options = {}) {
+    super();
+    this.#items = items;
+    this.#renderItem = options.render;
+    this.#direction = options.direction === 'horizontal' ? 'horizontal' : 'vertical';
+    this.#overscan = isNumber(options.overscan) ? Math.max(0, options.overscan) : 2;
+    this.#itemSize = isNumber(options.itemSize) ? options.itemSize : null;
+  }
+
+  mountInto(parent, beforeNode) {
+    if (this.#mounted) return;
+    if (typeof this.#renderItem !== 'function') {
+      throw new Error('virtualList(items, options): options.render is required');
+    }
+    this.#mounted = true;
+
+    const container = document.createElement('div');
+    container.style.position = 'relative';
+    container.style.overflow = 'auto';
+    container.style.width = '100%';
+    container.style.height = '100%';
+    container.style.contain = 'layout paint';
+
+    const spacer = document.createElement('div');
+    spacer.style.position = 'relative';
+    spacer.style.width = this.#direction === 'horizontal' ? '0px' : '100%';
+    spacer.style.height = this.#direction === 'horizontal' ? '100%' : '0px';
+
+    const itemsEl = document.createElement('div');
+    itemsEl.style.position = 'absolute';
+    itemsEl.style.top = '0';
+    itemsEl.style.left = '0';
+    itemsEl.style.willChange = 'transform';
+    if (this.#direction === 'horizontal') {
+      itemsEl.style.display = 'flex';
+      itemsEl.style.flexDirection = 'row';
+    }
+
+    container.appendChild(spacer);
+    container.appendChild(itemsEl);
+    parent.insertBefore(container, beforeNode);
+
+    this.#container = container;
+    this.#spacer = spacer;
+    this.#itemsEl = itemsEl;
+
+    container.addEventListener('scroll', this.#onScroll);
+    this.#observeResize(parent);
+    this.#updateViewport(parent);
+    this.#render();
+    this.#wire();
+  }
+
+  unmount() {
+    if (!this.#mounted) return;
+    this.#mounted = false;
+    if (this.#unsub) this.#unsub();
+    this.#unsub = null;
+    if (this.#container) {
+      this.#container.removeEventListener('scroll', this.#onScroll);
+    }
+    if (this.#resizeObserver) {
+      this.#resizeObserver.disconnect();
+      this.#resizeObserver = null;
+    }
+    this.#cleanup();
+    this.#container?.remove();
+    this.#container = null;
+    this.#spacer = null;
+    this.#itemsEl = null;
+  }
+
+  #readItems() {
+    if (isObservableArray(this.#items)) return this.#items;
+    if (isSignal(this.#items)) return readSignal(this.#items) || [];
+    if (isState(this.#items) || isStatePath(this.#items)) return readState(this.#items) || [];
+    return Array.isArray(this.#items) ? this.#items : [];
+  }
+
+  #wire() {
+    if (isObservableArray(this.#items)) {
+      this.#unsub = this.#items.subscribe(() => this.#render());
+      return;
+    }
+    if (isSignal(this.#items)) {
+      this.#unsub = subscribeSignal(this.#items, () => this.#render());
+      return;
+    }
+    if (isState(this.#items) || isStatePath(this.#items)) {
+      this.#unsub = subscribeState(this.#items, () => this.#render());
+    }
+  }
+
+  #observeResize(parent) {
+    if (typeof ResizeObserver === 'undefined') return;
+    this.#resizeObserver = new ResizeObserver(() => {
+      this.#updateViewport(parent);
+      this.#render();
+    });
+    this.#resizeObserver.observe(parent);
+  }
+
+  #updateViewport(parent) {
+    const rect = parent?.getBoundingClientRect?.();
+    if (!rect) return;
+    this.#viewportSize = this.#direction === 'horizontal' ? rect.width : rect.height;
+  }
+
+  #measureItemSize() {
+    if (this.#itemSize != null) return;
+    if (!this.#itemsEl) return;
+    const first = this.#itemsEl.firstElementChild;
+    if (!first) return;
+    const rect = first.getBoundingClientRect();
+    const size = this.#direction === 'horizontal' ? rect.width : rect.height;
+    if (isNumber(size) && size > 0) this.#itemSize = size;
+  }
+
+  #cleanup() {
+    for (const r of this.#mountedValues) Renderer.unmount(r);
+    this.#mountedValues = [];
+    if (this.#itemsEl) this.#itemsEl.replaceChildren();
+  }
+
+  #renderRange(items, start, end, offset) {
+    if (!this.#itemsEl) return;
+    this.#cleanup();
+    const slice = items.slice(start, end + 1);
+    const values = [];
+    for (let i = 0; i < slice.length; i++) {
+      const index = start + i;
+      const value = this.#renderItem(slice[i], index);
+      const normalized = Renderer.normalize(value);
+      for (const r of normalized) values.push(r);
+    }
+    this.#mountedValues = values;
+    for (const r of values) {
+      if (Renderer.isRenderable(r)) {
+        r.mountInto(this.#itemsEl, null);
+      } else if (Renderer.isDomNode(r)) {
+        this.#itemsEl.appendChild(r);
+      }
+    }
+    if (this.#direction === 'horizontal') {
+      this.#itemsEl.style.transform = `translateX(${offset}px)`;
+    } else {
+      this.#itemsEl.style.transform = `translateY(${offset}px)`;
+    }
+  }
+
+  #render() {
+    if (!this.#mounted || !this.#container) return;
+    const items = this.#readItems();
+    const count = items.length;
+    if (!this.#spacer) return;
+
+    if (count === 0) {
+      this.#spacer.style.width = this.#direction === 'horizontal' ? '0px' : '100%';
+      this.#spacer.style.height = this.#direction === 'horizontal' ? '100%' : '0px';
+      this.#cleanup();
+      return;
+    }
+
+    if (this.#itemSize == null && !this.#measuring) {
+      this.#measuring = true;
+      this.#renderRange(items, 0, 0, 0);
+      requestAnimationFrame(() => {
+        this.#measureItemSize();
+        this.#measuring = false;
+        this.#render();
+      });
+      return;
+    }
+
+    const size = this.#itemSize || 1;
+    const viewport = this.#viewportSize || (this.#direction === 'horizontal' ? this.#container.clientWidth : this.#container.clientHeight);
+    const scrollPos = this.#direction === 'horizontal' ? this.#container.scrollLeft : this.#container.scrollTop;
+    const visibleCount = Math.ceil(viewport / size);
+    const start = clamp(Math.floor(scrollPos / size) - this.#overscan, 0, Math.max(0, count - 1));
+    const end = clamp(start + visibleCount + this.#overscan * 2 - 1, 0, count - 1);
+    const offset = start * size;
+
+    const total = count * size;
+    if (this.#direction === 'horizontal') {
+      this.#spacer.style.width = `${total}px`;
+      this.#spacer.style.height = '100%';
+    } else {
+      this.#spacer.style.height = `${total}px`;
+      this.#spacer.style.width = '100%';
+    }
+
+    if (start === this.#startIndex && end === this.#endIndex) return;
+    this.#startIndex = start;
+    this.#endIndex = end;
+    this.#renderRange(items, start, end, offset);
+  }
+
+  #onScroll = () => {
+    this.#render();
+  };
+
+  renderToString(render) {
+    const items = this.#readItems();
+    return items.map((item, index) => render(this.#renderItem(item, index))).join('');
+  }
+}
+
+export function virtualList(items, options) {
+  return new VirtualListNode(items, options);
+}

package/src/core/dom/when.js

@@ -0,0 +1,138 @@
+import { Renderable } from '../renderable/renderable.js';
+import { Renderer } from '../renderable/renderer.js';
+import { createComment, clearBetween } from './dom.js';
+import { isState, isStatePath, readState, subscribeState } from '../reactivity/state.js';
+import { isSignal, readSignal, subscribeSignal } from '../reactivity/signal.js';
+
+const WHEN = Symbol('zb.when');
+
+function isValidAttributeValue(value) {
+  if (value == null) return true;
+  const type = typeof value;
+  if (type === 'string' || type === 'number' || type === 'boolean') return true;
+  if (type === 'object' && !Array.isArray(value)) return true;
+  return false;
+}
+
+export class WhenNode extends Renderable {
+  #source;
+  #renderTrue;
+  #renderFalse;
+  #start = null;
+  #end = null;
+  #mounted = false;
+  #unsub = null;
+  #mountedValues = [];
+
+  constructor(source, renderTrue, renderFalse) {
+    super();
+    this.#source = source;
+    this.#renderTrue = renderTrue;
+    this.#renderFalse = renderFalse;
+    Object.defineProperty(this, WHEN, { value: true });
+  }
+
+  mountInto(parent, beforeNode) {
+    if (this.#mounted) return;
+    this.#mounted = true;
+    this.#start = createComment('zb:when:start', 'when');
+    this.#end = createComment('zb:when:end', 'when');
+    parent.insertBefore(this.#start, beforeNode);
+    parent.insertBefore(this.#end, beforeNode);
+
+    this.#update();
+    this.#wire();
+  }
+
+  unmount() {
+    if (!this.#mounted) return;
+    this.#mounted = false;
+    if (this.#unsub) this.#unsub();
+    this.#unsub = null;
+    this.#cleanup();
+    if (this.#start && this.#end) {
+      clearBetween(this.#start, this.#end);
+      this.#start.remove();
+      this.#end.remove();
+    }
+    this.#start = null;
+    this.#end = null;
+  }
+
+  #wire() {
+    if (isState(this.#source) || isStatePath(this.#source)) {
+      this.#unsub = subscribeState(this.#source, () => this.#update());
+      return;
+    }
+    if (isSignal(this.#source)) {
+      this.#unsub = subscribeSignal(this.#source, () => this.#update());
+    }
+  }
+
+  #read() {
+    if (isState(this.#source) || isStatePath(this.#source)) return !!readState(this.#source);
+    if (isSignal(this.#source)) return !!readSignal(this.#source);
+    return !!this.#source;
+  }
+
+  readValue() {
+    const predicate = this.#read();
+    const value = predicate ? this.#renderTrue() : this.#renderFalse?.();
+    if (Renderer.isRenderable(value) || Renderer.isDomNode(value)) return undefined;
+    if (!isValidAttributeValue(value)) return undefined;
+    return value;
+  }
+
+  subscribeValue(fn) {
+    if (isState(this.#source) || isStatePath(this.#source)) {
+      return subscribeState(this.#source, () => fn(this.readValue()));
+    }
+    if (isSignal(this.#source)) {
+      return subscribeSignal(this.#source, () => fn(this.readValue()));
+    }
+    return null;
+  }
+
+  #cleanup() {
+    for (const r of this.#mountedValues) Renderer.unmount(r);
+    this.#mountedValues = [];
+    if (this.#start && this.#end) clearBetween(this.#start, this.#end);
+  }
+
+  #update() {
+    this.#cleanup();
+    const predicate = this.#read();
+    const value = predicate ? this.#renderTrue() : this.#renderFalse?.();
+    const values = Renderer.normalize(value);
+    this.#mountedValues = values;
+    for (const r of values) {
+      if (Renderer.isRenderable(r)) {
+        r.mountInto(this.#end.parentNode, this.#end);
+      } else if (Renderer.isDomNode(r)) {
+        this.#end.parentNode.insertBefore(r, this.#end);
+      }
+    }
+  }
+
+  renderToString(render) {
+    const predicate = this.#read();
+    const value = predicate ? this.#renderTrue() : this.#renderFalse?.();
+    return render(value);
+  }
+}
+
+export function when(source, renderTrue, renderFalse) {
+  return new WhenNode(source, renderTrue, renderFalse);
+}
+
+export function isWhen(value) {
+  return !!value && value[WHEN] === true;
+}
+
+export function readWhenValue(value) {
+  return value?.readValue?.();
+}
+
+export function subscribeWhenValue(value, fn) {
+  return value?.subscribeValue?.(fn);
+}

package/src/core/events/event-hub.js

@@ -0,0 +1,97 @@
+/**
+ * Minimal before/after event hub.
+ *
+ * - `before` handlers may return `false` to cancel the operation.
+ * - `after` handlers are fire-and-forget.
+ */
+export class EventHub {
+  #before = new Map(); // type -> Set<fn>
+  #after = new Map(); // type -> Set<fn>
+  #afterAny = new Set();
+
+  /**
+   * @param {'before'|'after'} phase
+   * @param {string} type
+   * @param {(payload: any, ctx: any) => (void|boolean)} fn
+   * @returns {() => void}
+   */
+  on(phase, type, fn) {
+    const map = phase === 'before' ? this.#before : this.#after;
+    if (phase === 'after' && type === '*') {
+      this.#afterAny.add(fn);
+      return () => this.#afterAny.delete(fn);
+    }
+    let set = map.get(type);
+    if (!set) {
+      set = new Set();
+      map.set(type, set);
+    }
+    set.add(fn);
+    return () => set.delete(fn);
+  }
+
+  /**
+   * Emits a before event. Returns false when cancelled.
+   * @param {string} type
+   * @param {any} payload
+   * @param {any} ctx
+   * @returns {boolean}
+   */
+  emitBefore(type, payload, ctx) {
+    const set = this.#before.get(type);
+    if (!set) return true;
+    for (const fn of set) {
+      const r = fn(payload, ctx);
+      if (r === false) return false;
+    }
+    return true;
+  }
+
+  /**
+   * Emits an after event.
+   * @param {string} type
+   * @param {any} payload
+   * @param {any} ctx
+   */
+  emitAfter(type, payload, ctx) {
+    const set = this.#after.get(type);
+    if (set) {
+      for (const fn of set) fn(payload, ctx);
+    }
+    for (const fn of this.#afterAny) fn(payload, ctx);
+  }
+
+  /**
+   * Returns a fluent API for registering hooks.
+   * @param {'before'|'after'} phase
+   */
+  phase(phase) {
+    const hub = this;
+    const api = {
+      /**
+       * Registers a handler for a given type.
+       * @param {string} type
+       * @param {(payload: any, ctx: any) => (void|boolean)} fn
+       */
+      on(type, fn) {
+        return hub.on(phase, type, fn);
+      },
+      /**
+       * Registers a handler for any type.
+       * @param {(payload: any, ctx: any) => (void|boolean)} fn
+       */
+      any(fn) {
+        return hub.on(phase, '*', fn);
+      },
+    };
+
+    return new Proxy(api, {
+      get(target, prop) {
+        if (typeof prop !== 'string') return target[prop];
+        if (prop in target) return target[prop];
+        return (fn) => hub.on(phase, prop, fn);
+      },
+    });
+  }
+}
+

package/src/core/forms/form.js

@@ -0,0 +1,127 @@
+import { state } from '../reactivity/state.js';
+import { after } from '../reactivity/observe.js';
+
+function isObject(value) {
+  return value !== null && typeof value === 'object';
+}
+
+function cloneValue(value) {
+  if (!isObject(value)) return value;
+  if (Array.isArray(value)) return value.map(cloneValue);
+  const out = {};
+  for (const [k, v] of Object.entries(value)) {
+    out[k] = cloneValue(v);
+  }
+  return out;
+}
+
+function deepEqual(a, b) {
+  if (a === b) return true;
+  if (typeof a !== typeof b) return false;
+  if (!isObject(a) || !isObject(b)) return false;
+  if (Array.isArray(a) !== Array.isArray(b)) return false;
+  if (Array.isArray(a)) {
+    if (a.length !== b.length) return false;
+    for (let i = 0; i < a.length; i++) {
+      if (!deepEqual(a[i], b[i])) return false;
+    }
+    return true;
+  }
+  const aKeys = Object.keys(a);
+  const bKeys = Object.keys(b);
+  if (aKeys.length !== bKeys.length) return false;
+  for (const k of aKeys) {
+    if (!Object.prototype.hasOwnProperty.call(b, k)) return false;
+    if (!deepEqual(a[k], b[k])) return false;
+  }
+  return true;
+}
+
+function mergeErrors(target, value) {
+  if (value == null || value === true) return target;
+  if (value === false) {
+    target._form = true;
+    return target;
+  }
+  if (typeof value === 'string') {
+    target._form = value;
+    return target;
+  }
+  if (isObject(value)) {
+    for (const [k, v] of Object.entries(value)) {
+      target[k] = v;
+    }
+    return target;
+  }
+  return target;
+}
+
+export function form(initial) {
+  const initialSnapshot = cloneValue(initial);
+  const values = state(cloneValue(initial));
+  const meta = state({});
+  const errors = state({});
+  const touched = state({});
+  const dirty = state(false);
+  const validators = new Set();
+
+  let runId = 0;
+
+  const runValidators = () => {
+    const current = ++runId;
+    const nextErrors = {};
+    const snapshot = values.get();
+    const tasks = [];
+
+    for (const validator of validators) {
+      try {
+        const result = validator(snapshot);
+        if (result && typeof result.then === 'function') {
+          tasks.push(
+            result.then((value) => {
+              mergeErrors(nextErrors, value);
+            })
+          );
+        } else {
+          mergeErrors(nextErrors, result);
+        }
+      } catch (err) {
+        mergeErrors(nextErrors, err?.message || true);
+      }
+    }
+
+    if (tasks.length) {
+      Promise.all(tasks).then(() => {
+        if (current !== runId) return;
+        errors.set(nextErrors);
+      });
+      return;
+    }
+
+    errors.set(nextErrors);
+  };
+
+  after(values).change(() => {
+    const isDirty = !deepEqual(values.get(), initialSnapshot);
+    if (dirty.get() !== isDirty) dirty.set(isDirty);
+    if (validators.size) runValidators();
+  });
+
+  const reset = () => {
+    values.set(cloneValue(initialSnapshot));
+    touched.set({});
+    errors.set({});
+    dirty.set(false);
+    meta.set({});
+  };
+
+  return {
+    values,
+    meta,
+    errors,
+    touched,
+    dirty,
+    validators,
+    reset,
+  };
+}

package/src/core/internal/symbols.js

@@ -0,0 +1,5 @@
+export const INTERNAL = Object.freeze({
+  instrumentBoundProp: Symbol('zb.instrumentBoundProp'),
+  subscribeProp: Symbol('zb.subscribeProp'),
+});
+