@granularjs/core 1.0.0

package/src/core/reactivity/state.js

@@ -0,0 +1,294 @@
+import { signal, setSignal, readSignal, subscribeSignal } from './signal.js';
+
+const STATE = Symbol('zb.state');
+const STATE_META = Symbol('zb.state.meta');
+
+function isObject(value) {
+  return value !== null && typeof value === 'object';
+}
+
+function splitPath(path) {
+  if (!path) return [];
+  if (Array.isArray(path)) return path;
+  return String(path)
+    .split('.')
+    .map((p) => p.trim())
+    .filter(Boolean);
+}
+
+function getAtPath(obj, path) {
+  let cur = obj;
+  for (const key of path) {
+    if (!cur) return undefined;
+    cur = cur[key];
+  }
+  return cur;
+}
+
+function mergeDefaults(base, next) {
+  if (!isObject(base) || !isObject(next)) return isObject(next) ? { ...next } : next;
+  const out = { ...base };
+  for (const key of Object.keys(next)) {
+    const baseValue = base[key];
+    const nextValue = next[key];
+    if (isObject(baseValue) && isObject(nextValue)) {
+      out[key] = mergeDefaults(baseValue, nextValue);
+      continue;
+    }
+    out[key] = nextValue;
+  }
+  return out;
+}
+
+function normalizeWhen(when) {
+  if (typeof when === 'function') return when;
+  if (when === 'nullish') return (value) => value == null;
+  return (value) => value === undefined;
+}
+
+function resolveValue(adapter, path, root) {
+  const currentRoot = root === undefined ? adapter.get() : root;
+  const value = getAtPath(currentRoot, path);
+  const defaults = adapter.defaults;
+  if (!defaults) return value;
+  const shouldDefault = adapter.defaultsWhen(value);
+  if (!shouldDefault) return value;
+  const fallback = getAtPath(defaults, path);
+  if (fallback === undefined) return value;
+  if (typeof fallback === 'function') {
+    return fallback({ value, path, root: currentRoot });
+  }
+  return fallback;
+}
+
+function setAtPath(obj, path, value) {
+  if (!path.length) return value;
+  const root = Array.isArray(obj) ? obj.slice() : { ...(obj || {}) };
+  let cur = root;
+  for (let i = 0; i < path.length - 1; i++) {
+    const key = path[i];
+    const next = cur[key];
+    const cloned = Array.isArray(next) ? next.slice() : { ...(next || {}) };
+    cur[key] = cloned;
+    cur = cloned;
+  }
+  cur[path[path.length - 1]] = value;
+  return root;
+}
+
+function createSetterProxy(adapter, basePath) {
+  return new Proxy(
+    {},
+    {
+      get(_t, prop) {
+        if (prop === 'increment') {
+          return () => {
+            const current = getAtPath(adapter.get(), basePath);
+            const next = (Number(current) || 0) + 1;
+            adapter.set(setAtPath(adapter.get(), basePath, next));
+          };
+        }
+        if (prop === 'decrement') {
+          return () => {
+            const current = getAtPath(adapter.get(), basePath);
+            const next = (Number(current) || 0) - 1;
+            adapter.set(setAtPath(adapter.get(), basePath, next));
+          };
+        }
+        if (prop === 'mutate') {
+          return (...args) => adapter.mutate?.(...args);
+        }
+        if (typeof prop === 'string') {
+          return createSetterProxy(adapter, basePath.concat(prop));
+        }
+        return undefined;
+      },
+      set(_t, prop, value) {
+        const path = basePath.concat(String(prop));
+        adapter.set(setAtPath(adapter.get(), path, value));
+        return true;
+      },
+    }
+  );
+}
+
+function createStateProxy(adapter, path = []) {
+  const meta = { adapter, path };
+  return new Proxy(
+    {},
+    {
+      get(_t, prop) {
+        if (prop === STATE) return true;
+        if (prop === STATE_META) return meta;
+        if (prop === 'get') {
+          return (p) => {
+            if (p === undefined) return adapter.get();
+            return resolveValue(adapter, path.concat(splitPath(p)));
+          };
+        }
+        if (prop === 'set') {
+          return (...args) => {
+            if (args.length === 0) return createSetterProxy(adapter, path);
+            if (args.length === 1) {
+              return adapter.set(setAtPath(adapter.get(), path, args[0]));
+            }
+            const [p, v] = args;
+            if (typeof p === 'string') {
+              return adapter.set(setAtPath(adapter.get(), path.concat(splitPath(p)), v));
+            }
+            return adapter.set(setAtPath(adapter.get(), path, p));
+          };
+        }
+        if (prop === 'subscribe') {
+          return (fn) => adapter.subscribe(fn);
+        }
+        if (prop === 'before') {
+          return adapter.before;
+        }
+        if (prop === 'mutate') {
+          return (...args) => adapter.mutate?.(...args);
+        }
+        if (prop === Symbol.toPrimitive) return () => resolveValue(adapter, path);
+        if (prop === 'valueOf') return () => resolveValue(adapter, path);
+        if (prop === 'toString') return () => String(resolveValue(adapter, path));
+
+        const current = resolveValue(adapter, path);
+        if (Array.isArray(current) && prop === 'map') {
+          return (fn) => {
+            const out = current.map(fn);
+            Object.defineProperty(out, STATE_META, { value: { adapter, path, mapFn: fn } });
+            return out;
+          };
+        }
+
+        if (isObject(current) && typeof prop === 'string') {
+          return createStateProxy(adapter, path.concat(prop));
+        }
+        return undefined;
+      },
+      set(_t, prop, value) {
+        if (typeof prop === 'string') {
+          throw new Error(`Direct mutation is not allowed. Use .set().${prop} = value or .set("${path.concat(prop).join('.')}", value).`);
+        }
+        return false;
+      },
+    }
+  );
+}
+
+export function state(initial) {
+  const rootSignal = signal(initial);
+  const adapter = {
+    kind: 'state',
+    get: () => readSignal(rootSignal),
+    set: (next) => setSignal(rootSignal, next, true),
+    subscribe: (fn) => subscribeSignal(rootSignal, fn),
+    before: rootSignal.before,
+    mutate: (optimistic, mutation, options = {}) => mutateAdapter(adapter, optimistic, mutation, options),
+  };
+  return createStateFromAdapter(adapter);
+}
+
+export function createStateFromAdapter(adapter) {
+  const proxy = createStateProxy(adapter, []);
+  Object.defineProperty(proxy, STATE, { value: true });
+  return proxy;
+}
+
+function cloneForSnapshot(value, options) {
+  if (typeof options.clone === 'function') return options.clone(value);
+  return value;
+}
+
+export async function mutateAdapter(adapter, optimistic, mutation, options = {}) {
+  if (typeof optimistic !== 'function' || typeof mutation !== 'function') {
+    throw new Error('mutate(optimistic, mutation, options?): invalid arguments');
+  }
+  const prev = cloneForSnapshot(adapter.get(), options);
+  optimistic();
+  try {
+    const result = await mutation();
+    return result;
+  } catch (err) {
+    if (typeof options.rollback === 'function') {
+      options.rollback(err, prev);
+    } else {
+      adapter.set(prev);
+    }
+    throw err;
+  }
+}
+
+export function isState(value) {
+  return !!value && value[STATE] === true;
+}
+
+export function isComputed(value) {
+  const meta = value?.[STATE_META];
+  return !!meta && meta.adapter?.kind === 'computed';
+}
+
+export function isStatePath(value) {
+  return !!value && value[STATE_META];
+}
+
+export function readState(value) {
+  const meta = value?.[STATE_META];
+  if (!meta) return undefined;
+  return resolveValue(meta.adapter, meta.path);
+}
+
+export function readStateFromRoot(value, root) {
+  const meta = value?.[STATE_META];
+  if (!meta) return undefined;
+  return resolveValue(meta.adapter, meta.path, root);
+}
+
+export function subscribeState(value, fn) {
+  const meta = value?.[STATE_META];
+  if (!meta) return null;
+  return meta.adapter.subscribe((nextRoot, prevRoot) => {
+    const next = resolveValue(meta.adapter, meta.path, nextRoot);
+    const prev = resolveValue(meta.adapter, meta.path, prevRoot);
+    if (next === prev) return;
+    fn(next, prev);
+  });
+}
+
+export function readStateMeta(meta) {
+  if (!meta) return undefined;
+  return resolveValue(meta.adapter, meta.path);
+}
+
+export function subscribeStateMeta(meta, fn) {
+  if (!meta) return null;
+  return meta.adapter.subscribe((nextRoot, prevRoot) => {
+    const next = resolveValue(meta.adapter, meta.path, nextRoot);
+    const prev = resolveValue(meta.adapter, meta.path, prevRoot);
+    if (next === prev) return;
+    fn(next, prev);
+  });
+}
+
+export function setStateValue(value, next) {
+  const meta = value?.[STATE_META];
+  if (!meta) return;
+  return meta.adapter.set(setAtPath(meta.adapter.get(), meta.path, next));
+}
+
+export function getMappedMeta(value) {
+  const meta = value?.[STATE_META];
+  if (!meta || !meta.mapFn) return null;
+  return meta;
+}
+
+export function withDefaults(target, defaults, options = {}) {
+  const meta = target?.[STATE_META];
+  if (!meta) {
+    throw new Error('withDefaults(target, defaults, options?): target must be a state or state path');
+  }
+  const adapter = meta.adapter;
+  adapter.defaultsWhen = options.when === undefined ? (adapter.defaultsWhen ?? normalizeWhen()) : normalizeWhen(options.when);
+  adapter.defaults = adapter.defaults ? mergeDefaults(adapter.defaults, defaults) : defaults;
+  return target;
+}

package/src/core/renderable/render-string.js

@@ -0,0 +1,51 @@
+import { Renderable } from './renderable.js';
+import { Renderer } from './renderer.js';
+import { ElementNode } from '../dom/element.js';
+import { isSignal, readSignal } from '../reactivity/signal.js';
+import { isState, isStatePath, readState } from '../reactivity/state.js';
+
+function escapeHtml(value) {
+  return String(value)
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;');
+}
+
+function renderValue(value, render) {
+  if (value == null || value === false) return '';
+  if (Array.isArray(value)) return value.map((v) => render(v)).join('');
+  if (isSignal(value)) return render(readSignal(value));
+  if (isState(value) || isStatePath(value)) return render(readState(value));
+  if (value instanceof Renderable && typeof value.renderToString === 'function') {
+    return value.renderToString(render);
+  }
+  if (value instanceof ElementNode) {
+    return value.renderToString(render);
+  }
+  if (Renderer.isDomNode(value)) {
+    return value.outerHTML || '';
+  }
+  return escapeHtml(Renderer.toText(value));
+}
+
+export function renderToString(value) {
+  const render = (v) => renderValue(v, render);
+  render.escape = escapeHtml;
+  return render(value);
+}
+
+export function hydrate(target, value) {
+  const el = typeof target === 'string' ? document.querySelector(target) : target;
+  if (!el) throw new Error('hydrate(target): target not found');
+  while (el.firstChild) el.removeChild(el.firstChild);
+  const values = Renderer.normalize(value);
+  for (const r of values) {
+    if (Renderer.isRenderable(r)) {
+      r.mountInto(el, null);
+    } else if (Renderer.isDomNode(r)) {
+      el.appendChild(r);
+    }
+  }
+}

package/src/core/renderable/renderable.js

@@ -0,0 +1,21 @@
+/**
+ * Base contract for objects that can be mounted/unmounted by the core renderer.
+ */
+export class Renderable {
+  /**
+   * Mounts the instance into the DOM.
+   * @param {Node} parent
+   * @param {Node|null} beforeNode
+   */
+  mountInto() {
+    throw new Error('Renderable.mountInto() must be implemented');
+  }
+
+  /**
+   * Unmounts and releases DOM/resources owned by the instance.
+   */
+  unmount() {
+    throw new Error('Renderable.unmount() must be implemented');
+  }
+}
+

package/src/core/renderable/renderer.js

@@ -0,0 +1,66 @@
+import { Renderable } from './renderable.js';
+
+/**
+ * Core rendering rules for "values".
+ * This is intentionally separate from the Renderable contract.
+ */
+export class Renderer {
+  /**
+   * @param {unknown} value
+   * @returns {value is Node}
+   */
+  static isDomNode(value) {
+    return !!value && typeof value === 'object' && typeof value.nodeType === 'number';
+  }
+
+  /**
+   * @param {unknown} value
+   * @returns {value is Renderable}
+   */
+  static isRenderable(value) {
+    return value instanceof Renderable;
+  }
+
+  /**
+   * Converts a non-renderable value into string for text rendering.
+   * @param {unknown} value
+   * @returns {string}
+   */
+  static toText(value) {
+    if (value == null || value === false) return '';
+    if (typeof value === 'string') return value;
+    if (typeof value === 'number') return String(value);
+    if (typeof value === 'bigint') return String(value);
+    if (typeof value === 'boolean') return value ? 'true' : '';
+    try {
+      return String(value);
+    } catch {
+      return '';
+    }
+  }
+
+  /**
+   * Normalizes a value into a flat list of renderables:
+   * - Renderable instances
+   * - DOM Nodes
+   * - TextNodes created from primitives/objects
+   *
+   * @param {unknown} value
+   * @returns {(Renderable|Node)[]}
+   */
+  static normalize(value) {
+    if (value == null || value === false) return [];
+    if (Array.isArray(value)) return value.flatMap((v) => Renderer.normalize(v));
+    if (Renderer.isRenderable(value) || Renderer.isDomNode(value)) return /** @type {(Renderable|Node)[]} */ ([value]);
+    return [document.createTextNode(Renderer.toText(value))];
+  }
+
+  /**
+   * Unmounts a renderable value if applicable.
+   * @param {unknown} value
+   */
+  static unmount(value) {
+    if (Renderer.isRenderable(value)) value.unmount();
+  }
+}
+