@granularjs/core 1.0.0

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@granularjs/core",
+  "version": "1.0.0",
+  "description": "JS-first frontend framework with granular reactivity. No Virtual DOM, no build step, no magic — just explicit reactivity and direct DOM updates.",
+  "type": "module",
+  "main": "./dist/granular.min.js",
+  "module": "./dist/granular.min.js",
+  "types": "./types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./types/index.d.ts",
+      "import": "./dist/granular.min.js",
+      "default": "./dist/granular.min.js"
+    }
+  },
+  "files": [
+    "dist",
+    "types",
+    "src"
+  ],
+  "scripts": {
+    "build:minify": "npx -y esbuild src/index.js --bundle --minify --sourcemap --format=esm --outfile=./dist/granular.min.js && npx -y -p typescript@latest tsc -p tsconfig.json",
+    "build:debug": "npx -y esbuild src/index.js --bundle --sourcemap --format=esm --outfile=./dist/granular.js && npx -y -p typescript@latest tsc -p tsconfig.json",
+    "build:watch": "npx -y esbuild src/index.js --bundle --minify --sourcemap --format=esm --outfile=./dist/granular.min.js --watch",
+    "version": "npm run build:minify && git add -A",
+    "postversion": "git push && git push --tags"
+  },
+  "author": "Guilherme Ferreira",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/zerobytes/granular.git"
+  },
+  "homepage": "https://granular.web.app",
+  "bugs": {
+    "url": "https://github.com/zerobytes/granular/issues"
+  },
+  "keywords": [
+    "granular",
+    "granularjs",
+    "framework",
+    "frontend",
+    "reactive",
+    "reactivity",
+    "signals",
+    "state",
+    "dom",
+    "no-vdom",
+    "no-virtual-dom",
+    "fine-grained",
+    "javascript",
+    "ui"
+  ]
+}

package/src/core/bootstrap.js

@@ -0,0 +1,63 @@
+import { Renderer } from './renderable/renderer.js';
+
+/**
+ * Creates and attaches a component instance or render function to a target element.
+ *
+ * @template T
+ * @param {new (...args: any[]) => T | (() => any)} ComponentClass
+ * @param {string|Element} target
+ * @returns {Promise<T|{ unmount(): void }>}
+ */
+export async function bootstrap(ComponentClass, target) {
+  const el = typeof target === 'string' ? document.querySelector(target) : target;
+  if (!el) throw new Error('bootstrap target not found');
+
+  if (typeof ComponentClass !== 'function') {
+    throw new Error('bootstrap: component must be a function or class');
+  }
+
+  let instance = null;
+  if (ComponentClass.__zbFactory) {
+    instance = ComponentClass();
+  } else {
+    try {
+      instance = new ComponentClass();
+    } catch {
+      instance = null;
+    }
+  }
+
+  if (instance) {
+    if (typeof instance.attach === 'function') {
+      await instance.attach(el);
+      return instance;
+    }
+    if (typeof instance.mountInto === 'function') {
+      instance.mountInto(el, null);
+      return instance;
+    }
+  }
+
+  const root = ComponentClass();
+  const values = Renderer.normalize(root);
+  for (const r of values) {
+    if (Renderer.isRenderable(r)) {
+      r.mountInto(el, null);
+    } else if (Renderer.isDomNode(r)) {
+      el.appendChild(r);
+    }
+  }
+
+  return {
+    unmount() {
+      for (const r of values) {
+        if (Renderer.isRenderable(r)) {
+          r.unmount();
+        } else if (Renderer.isDomNode(r)) {
+          r.remove();
+        }
+      }
+    },
+  };
+}
+

package/src/core/collections/observable-array.js

@@ -0,0 +1,204 @@
+import { EventHub } from '../events/event-hub.js';
+
+const ObservableArrayMeta = new WeakMap();
+
+export function isObservableArray(value) {
+  return !!value && typeof value === 'object' && ObservableArrayMeta.has(value);
+}
+
+function clampIndex(index, length) {
+  if (index < 0) return Math.max(0, length + index);
+  return Math.min(index, length);
+}
+
+export function observableArray(initial = []) {
+  const target = Array.isArray(initial) ? initial.slice() : [];
+  const subs = new Set();
+  const hub = new EventHub();
+
+  const notify = (patch, ctx) => {
+    for (const fn of subs) fn(patch, ctx);
+    hub.emitAfter(patch.type, patch, ctx || { array: proxy });
+  };
+
+  const proxy = new Proxy(target, {
+    get(t, prop, receiver) {
+      // Public API (preferred)
+      if (prop === 'subscribe') {
+        return (fn) => {
+          subs.add(fn);
+          return () => subs.delete(fn);
+        };
+      }
+      if (prop === 'reset') {
+        return (nextArray) => {
+          const prevItems = t.slice();
+          const nextItems = Array.isArray(nextArray) ? nextArray.slice() : [];
+          const ctx = { array: proxy, op: 'reset', args: [nextArray], prevLength: t.length, nextLength: nextItems.length };
+          const patch = { type: 'reset', items: nextItems, prevItems };
+          if (!hub.emitBefore('reset', patch, ctx)) return;
+          t.length = 0;
+          if (Array.isArray(nextArray)) t.push(...nextArray);
+          notify({ type: 'reset', items: t.slice(), prevItems }, ctx);
+        };
+      }
+      if (prop === 'after') {
+        return () => hub.phase('after');
+      }
+      if (prop === 'before') {
+        return () => hub.phase('before');
+      }
+
+      const value = Reflect.get(t, prop, receiver);
+      if (typeof value !== 'function') return value;
+
+      if (prop === 'push') {
+        return (...items) => {
+          const index = t.length;
+          const ctx = { array: proxy, op: 'push', args: items, prevLength: t.length, nextLength: t.length + items.length };
+          const patch = { type: 'insert', index, items: items.slice() };
+          if (items.length && !hub.emitBefore('insert', patch, ctx)) return t.length;
+          const result = Array.prototype.push.apply(t, items);
+          if (items.length) notify({ type: 'insert', index, items }, ctx);
+          return result;
+        };
+      }
+      if (prop === 'pop') {
+        return () => {
+          if (t.length === 0) return undefined;
+          const index = t.length - 1;
+          const removed = [t[index]];
+          const ctx = { array: proxy, op: 'pop', args: [], prevLength: t.length, nextLength: t.length - 1 };
+          const patch = { type: 'remove', index, count: 1, items: removed };
+          if (!hub.emitBefore('remove', patch, ctx)) return undefined;
+          const result = Array.prototype.pop.apply(t);
+          notify({ type: 'remove', index, count: 1, items: removed }, ctx);
+          return result;
+        };
+      }
+      if (prop === 'unshift') {
+        return (...items) => {
+          const ctx = { array: proxy, op: 'unshift', args: items, prevLength: t.length, nextLength: t.length + items.length };
+          const patch = { type: 'insert', index: 0, items: items.slice() };
+          if (items.length && !hub.emitBefore('insert', patch, ctx)) return t.length;
+          const result = Array.prototype.unshift.apply(t, items);
+          if (items.length) notify({ type: 'insert', index: 0, items }, ctx);
+          return result;
+        };
+      }
+      if (prop === 'shift') {
+        return () => {
+          if (t.length === 0) return undefined;
+          const removed = [t[0]];
+          const ctx = { array: proxy, op: 'shift', args: [], prevLength: t.length, nextLength: t.length - 1 };
+          const patch = { type: 'remove', index: 0, count: 1, items: removed };
+          if (!hub.emitBefore('remove', patch, ctx)) return undefined;
+          const result = Array.prototype.shift.apply(t);
+          notify({ type: 'remove', index: 0, count: 1, items: removed }, ctx);
+          return result;
+        };
+      }
+      if (prop === 'splice') {
+        return (start, deleteCount, ...items) => {
+          const lenBefore = t.length;
+          const index = clampIndex(Number(start) || 0, lenBefore);
+          const dc =
+            deleteCount === undefined ? lenBefore - index : Math.max(0, Number(deleteCount) || 0);
+          const ctx = { array: proxy, op: 'splice', args: [start, deleteCount, ...items], prevLength: t.length, nextLength: t.length - dc + items.length };
+          if (dc) {
+            const removePatch = { type: 'remove', index, count: dc, items: t.slice(index, index + dc) };
+            if (!hub.emitBefore('remove', removePatch, ctx)) return [];
+          }
+          if (items.length) {
+            const insertPatch = { type: 'insert', index, items: items.slice() };
+            if (!hub.emitBefore('insert', insertPatch, ctx)) return [];
+          }
+          const removed = Array.prototype.splice.apply(t, [index, dc, ...items]);
+          if (dc) notify({ type: 'remove', index, count: dc, items: removed }, ctx);
+          if (items.length) notify({ type: 'insert', index, items }, ctx);
+          return removed;
+        };
+      }
+
+      return value.bind(t);
+    },
+    set(t, prop, value, receiver) {
+      if (prop === 'length') {
+        const prev = t.length;
+        const next = Number(value) || 0;
+        const prevItems = t.slice();
+        const removed = next < prev ? t.slice(next, prev) : [];
+        const ctx = { array: proxy, op: 'length', args: [next], prevLength: prev, nextLength: next };
+        const ok = Reflect.set(t, prop, next, receiver);
+        if (ok && next < prev) {
+          const patch = { type: 'remove', index: next, count: prev - next, items: removed };
+          if (hub.emitBefore('remove', patch, ctx)) notify(patch, ctx);
+        }
+        if (ok && next > prev) {
+          notify({ type: 'reset', items: t.slice(), prevItems }, ctx);
+        }
+        return ok;
+      }
+
+      const index = typeof prop === 'string' && /^\d+$/.test(prop) ? Number(prop) : null;
+      if (index == null) return Reflect.set(t, prop, value, receiver);
+
+      const lenBefore = t.length;
+      const prevValue = index < t.length ? t[index] : undefined;
+      const ctx = { array: proxy, op: 'set', args: [prop, value], prevLength: t.length, nextLength: t.length };
+      const ok = Reflect.set(t, prop, value, receiver);
+      if (!ok) return false;
+
+      if (index < lenBefore) {
+        const patch = { type: 'set', index, value, prev: prevValue };
+        if (hub.emitBefore('set', patch, ctx)) notify(patch, ctx);
+        return true;
+      }
+
+      if (index === lenBefore) {
+        const patch = { type: 'insert', index, items: [value] };
+        ctx.nextLength = t.length;
+        if (hub.emitBefore('insert', patch, ctx)) notify(patch, ctx);
+        return true;
+      }
+
+      const prevItems = t.slice(0, lenBefore);
+      notify({ type: 'reset', items: t.slice(), prevItems }, ctx);
+      return true;
+    },
+  });
+
+  ObservableArrayMeta.set(proxy, { target, subs });
+  return proxy;
+}
+
+/**
+ * @typedef {Object} ObservableArrayPatchInsert
+ * @property {'insert'} type
+ * @property {number} index
+ * @property {any[]} items
+ */
+/**
+ * @typedef {Object} ObservableArrayPatchRemove
+ * @property {'remove'} type
+ * @property {number} index
+ * @property {number} count
+ * @property {any[]} items
+ */
+/**
+ * @typedef {Object} ObservableArrayPatchSet
+ * @property {'set'} type
+ * @property {number} index
+ * @property {any} value
+ * @property {any} prev
+ */
+/**
+ * @typedef {Object} ObservableArrayPatchReset
+ * @property {'reset'} type
+ * @property {any[]} items
+ * @property {any[]} prevItems
+ */
+/**
+ * @typedef {ObservableArrayPatchInsert|ObservableArrayPatchRemove|ObservableArrayPatchSet|ObservableArrayPatchReset} ObservableArrayPatch
+ */
+

package/src/core/component/function-component.js

@@ -0,0 +1,82 @@
+import { DirtyHost } from '../reactivity/dirty-host.js';
+import { Renderer } from '../renderable/renderer.js';
+
+function createProxy(host) {
+  return new Proxy(host, {
+    get: (target, prop) => {
+      if (prop === 'onCleanup') return target.onCleanup.bind(target);
+      if (prop === '$') {
+        return (name) => target[name];
+      }
+      if (typeof prop === 'string' && prop.startsWith('$')) {
+        return target[prop.slice(1)];
+      }
+      const value = target[prop];
+      if (typeof value === 'function') return value.bind(target);
+      return value;
+    },
+    set: (target, prop, value) => {
+      target[prop] = value;
+      return true;
+    },
+  });
+}
+
+class FunctionComponentInstance extends DirtyHost {
+  #root = null;
+  #rootValues = [];
+  #cleanups = [];
+
+  constructor(renderFn, props) {
+    super();
+    this.props = props || {};
+    const proxy = createProxy(this);
+    const root = renderFn.call(proxy, props);
+    this.#root = root;
+    this.#rootValues = Renderer.normalize(root);
+  }
+
+  mountInto(parent, beforeNode) {
+    for (const r of this.#rootValues) {
+      if (Renderer.isRenderable(r)) {
+        r.mountInto(parent, beforeNode);
+        continue;
+      }
+      if (Renderer.isDomNode(r)) {
+        parent.insertBefore(r, beforeNode);
+      }
+    }
+  }
+
+  unmount() {
+    for (const fn of this.#cleanups) fn();
+    this.#cleanups = [];
+    for (const r of this.#rootValues) {
+      if (Renderer.isRenderable(r)) {
+        r.unmount();
+        continue;
+      }
+      if (Renderer.isDomNode(r)) {
+        r.remove();
+      }
+    }
+  }
+
+  renderToString(render) {
+    return render(this.#root);
+  }
+
+  onCleanup(fn) {
+    if (typeof fn !== 'function') return;
+    this.#cleanups.push(fn);
+  }
+}
+
+export function component(renderFn) {
+  if (typeof renderFn !== 'function') {
+    throw new Error('component(fn): fn must be a function');
+  }
+  const factory = (props) => new FunctionComponentInstance(renderFn, props);
+  factory.__zbFactory = true;
+  return factory;
+}

package/src/core/context.js

@@ -0,0 +1,172 @@
+import { signal, readSignal, setSignal, subscribeSignal } from './reactivity/signal.js';
+import { createStateFromAdapter } from './reactivity/state.js';
+import { Renderable } from './renderable/renderable.js';
+
+class ContextProvider extends Renderable {
+  #child;
+  #providerSignal;
+  #consumers;
+  #mountStack;
+  #mountTimeConsumers = [];
+  #mounted = false;
+
+  constructor(child, providerSignal, consumers, mountStack) {
+    super();
+    this.#child = child;
+    this.#providerSignal = providerSignal;
+    this.#consumers = consumers;
+    this.#mountStack = mountStack;
+  }
+
+  mountInto(parent, beforeNode) {
+    if (this.#mounted) return;
+    this.#mounted = true;
+    for (const consumer of this.#consumers) {
+      consumer._connect(this.#providerSignal);
+    }
+    this.#mountStack.push({ signal: this.#providerSignal, consumers: this.#mountTimeConsumers });
+    this.#child.mountInto(parent, beforeNode);
+    this.#mountStack.pop();
+  }
+
+  unmount() {
+    if (!this.#mounted) return;
+    this.#mounted = false;
+    this.#child.unmount();
+    for (const consumer of this.#consumers) {
+      consumer._disconnect();
+    }
+    for (const consumer of this.#mountTimeConsumers) {
+      consumer._disconnect();
+    }
+    this.#mountTimeConsumers = [];
+  }
+
+  renderToString(render) {
+    for (const consumer of this.#consumers) {
+      consumer._connect(this.#providerSignal);
+    }
+    this.#mountStack.push({ signal: this.#providerSignal, consumers: this.#mountTimeConsumers });
+    const html = render(this.#child);
+    this.#mountStack.pop();
+    return html;
+  }
+}
+
+function createContextConsumer(defaultValue) {
+  const localSignal = signal(defaultValue);
+  const subscribers = new Set();
+  let activeProviderSignal = null;
+  let providerUnsub = null;
+  let localUnsub = null;
+
+  const notify = (...args) => {
+    for (const fn of subscribers) fn(...args);
+  };
+
+  localUnsub = subscribeSignal(localSignal, notify);
+
+  const getActive = () => activeProviderSignal || localSignal;
+
+  const adapter = {
+    kind: 'state',
+    get: () => readSignal(getActive()),
+    set: (next) => setSignal(getActive(), next, true),
+    subscribe: (fn) => {
+      subscribers.add(fn);
+      return () => subscribers.delete(fn);
+    },
+    before: localSignal.before,
+  };
+
+  const consumerState = createStateFromAdapter(adapter);
+
+  return {
+    state: consumerState,
+    _connect(providerSignal) {
+      activeProviderSignal = providerSignal;
+      if (localUnsub) { localUnsub(); localUnsub = null; }
+      providerUnsub = subscribeSignal(providerSignal, notify);
+      const newVal = readSignal(providerSignal);
+      const oldVal = readSignal(localSignal);
+      if (newVal !== oldVal) {
+        notify(newVal, oldVal);
+      }
+    },
+    _disconnect() {
+      if (providerUnsub) { providerUnsub(); providerUnsub = null; }
+      activeProviderSignal = null;
+      localUnsub = subscribeSignal(localSignal, notify);
+    },
+  };
+}
+
+/**
+ * Creates a context for sharing reactive state across a component tree
+ * without prop drilling.
+ *
+ * Returns { scope, state }:
+ * - scope(value?) — creates a new provider level. Returns a state with
+ *     .get(), .set(), path access, and .serve(renderable) to wrap children.
+ * - state() — returns a reactive state bound to the nearest ancestor provider.
+ *
+ * Usage:
+ *   const sizeCtx = context([1, 2, 3]);
+ *
+ *   const Parent = (...children) => {
+ *     const sizes = sizeCtx.scope();
+ *     sizes.set([10, 20, 30]);
+ *     return sizes.serve(Div(...children));
+ *   };
+ *
+ *   const Child = () => {
+ *     const sizes = sizeCtx.state();
+ *     return Div(sizes[0]);
+ *   };
+ *
+ *   Parent(Child());
+ */
+export function context(defaultValue) {
+  const pending = [];
+  const mountStack = [];
+
+  const scope = (value) => {
+    const providerSignal = signal(value !== undefined ? value : defaultValue);
+
+    const adapter = {
+      kind: 'state',
+      get: () => readSignal(providerSignal),
+      set: (next) => setSignal(providerSignal, next, true),
+      subscribe: (fn) => subscribeSignal(providerSignal, fn),
+      before: providerSignal.before,
+    };
+
+    const providerState = createStateFromAdapter(adapter);
+
+    const serve = (renderable) => {
+      const consumers = pending.splice(0, pending.length);
+      return new ContextProvider(renderable, providerSignal, consumers, mountStack);
+    };
+
+    return new Proxy(providerState, {
+      get(target, prop) {
+        if (prop === 'serve') return serve;
+        return Reflect.get(target, prop);
+      },
+    });
+  };
+
+  const state = () => {
+    const consumer = createContextConsumer(defaultValue);
+    if (mountStack.length > 0) {
+      const top = mountStack[mountStack.length - 1];
+      consumer._connect(top.signal);
+      top.consumers.push(consumer);
+    } else {
+      pending.push(consumer);
+    }
+    return consumer.state;
+  };
+
+  return { scope, state };
+}

package/src/core/dom/dom.js

@@ -0,0 +1,25 @@
+/**
+ * Creates a comment node used as a stable DOM anchor.
+ * @param {string} label
+ * @param {string} name
+ */
+export function createComment(label, name) {
+  return document.createComment(`${label}:${name}`);
+}
+
+/**
+ * Removes all sibling nodes between two anchors.
+ * @param {Comment} start
+ * @param {Comment} end
+ * @param {(node: Node) => void} [disposer]
+ */
+export function clearBetween(start, end, disposer) {
+  let current = start.nextSibling;
+  while (current && current !== end) {
+    const next = current.nextSibling;
+    disposer?.(current);
+    current.remove();
+    current = next;
+  }
+}
+