wallace 0.0.2 → 0.0.6

package/LICENSE.md

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2023 Andrew Buchan
+Copyright (c) 2025 Andrew Buchan
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/lib/component.js

@@ -0,0 +1,64 @@
+/**
+ * The base component.
+ */
+export function Component(parent) {
+  this.parent = parent; // The parent component
+  this.props = undefined; // The props passed to the component. May be changed.
+  this.el = null; // the element - will be set during build
+  this.ref = {}; // user set references to elements or components
+  // Internal state objects
+  this._o = []; // stashed objects like pools.
+  this._e = {}; // stashed elements.
+  this._p = {}; // The previous values for watches to compare against
+}
+
+var proto = Component.prototype;
+
+Object.defineProperty(proto, "hidden", {
+  set: function (value) {
+    this.el.hidden = value;
+  },
+});
+
+/**
+ * Sets the props and updates the component.
+ */
+proto.render = function (props) {
+  this.props = props;
+  this.update();
+};
+
+/**
+ * Updates the DOM.
+ * Loops over watches, skipping n watches if elements are hidden.
+ */
+proto.update = function () {
+  let i = 0,
+    watch,
+    element,
+    shieldQuery,
+    shieldQueryResult,
+    shouldBeVisible;
+
+  const watches = this.__wc;
+  const lookup = this._l;
+  const props = this.props;
+  lookup.reset();
+  const il = watches.length;
+  while (i < il) {
+    watch = watches[i];
+    element = this._e[watch.wk];
+    shieldQuery = watch.sq;
+    i++;
+    shouldBeVisible = true;
+    if (shieldQuery) {
+      shieldQueryResult = !!lookup.get(this, props, shieldQuery).n;
+      shouldBeVisible = watch.rv ? shieldQueryResult : !shieldQueryResult;
+      element.hidden = !shouldBeVisible;
+      i += shouldBeVisible ? 0 : watch.sc;
+    }
+    if (shouldBeVisible) {
+      lookup.applyCallbacks(this, props, element, watch.cb);
+    }
+  }
+};

package/lib/index.js

@@ -0,0 +1,34 @@
+import { createComponent, createProxy, mount } from "./utils";
+import { Component } from "./component";
+import { KeyedPool, SequentialPool } from "./pool";
+import {
+  extendComponent,
+  findElement,
+  getKeyedPool,
+  getSequentialPool,
+  onEvent,
+  nestComponent,
+  defineComponent,
+  extendPrototype,
+  saveMiscObject,
+  saveRef,
+} from "./initCalls";
+
+export {
+  extendComponent,
+  Component,
+  createComponent,
+  createProxy,
+  defineComponent,
+  extendPrototype,
+  findElement,
+  getKeyedPool,
+  getSequentialPool,
+  KeyedPool,
+  mount,
+  nestComponent,
+  onEvent,
+  saveMiscObject,
+  saveRef,
+  SequentialPool,
+};

package/lib/initCalls.js

@@ -0,0 +1,110 @@
+import { Component } from "./component";
+import { Lookup } from "./lookup";
+import { buildComponent, replaceNode } from "./utils";
+import { KeyedPool, SequentialPool } from "./pool";
+const throwAway = document.createElement("template");
+
+/**
+ * Create an element from html string
+ */
+function makeEl(html) {
+  throwAway.innerHTML = html;
+  return throwAway.content.firstChild;
+}
+
+export const getProps = (component) => {
+  return component.props;
+};
+
+export const findElement = (rootElement, path) => {
+  return path.reduce((acc, index) => acc.childNodes[index], rootElement);
+};
+
+export const nestComponent = (rootElement, path, cls, parent) => {
+  const el = findElement(rootElement, path),
+    child = buildComponent(cls, parent);
+  replaceNode(el, child.el);
+  return child;
+};
+
+/**
+ * Saves a reference to element or nested component. Can be used to wrap a stash call.
+ */
+export const saveRef = (element, component, name) => {
+  component.ref[name] = element;
+  return element;
+};
+
+/**
+ * Saves a misc object (anything that's not an element). Can be used to wrap a stash call.
+ */
+export const saveMiscObject = (element, component, object) => {
+  component._o.push(object);
+  return element;
+};
+
+export const onEvent = (element, eventName, callback) => {
+  element.addEventListener(eventName, callback);
+  return element;
+};
+
+/**
+ * Creates a pool.
+ */
+export const getKeyedPool = (cls, keyFn) => {
+  return new KeyedPool(cls, keyFn);
+};
+
+export const getSequentialPool = (cls) => {
+  return new SequentialPool(cls);
+};
+
+export function defineComponent(
+  html,
+  watches,
+  lookups,
+  buildFunction,
+  inheritFrom,
+  prototypeExtras,
+) {
+  const Constructor = extendPrototype(
+    inheritFrom || Component,
+    prototypeExtras,
+  );
+  extendComponent(Constructor.prototype, html, watches, lookups, buildFunction);
+  return Constructor;
+}
+
+export function extendComponent(
+  prototype,
+  html,
+  watches,
+  lookups,
+  buildFunction,
+) {
+  prototype.__wc = watches.map((arr) => ({
+    wk: arr[0], // The key of the corresponding element.
+    sq: arr[1], // The shield query key
+    rv: arr[2], // whether shieldQuery should be flipped
+    sc: arr[3], // The number of items to shield
+    cb: arr[4], // The callbacks - object
+  }));
+  prototype._l = new Lookup(lookups);
+  prototype._b = buildFunction;
+  prototype._n = makeEl(html);
+}
+
+export function extendPrototype(base, prototypeExtras) {
+  const Constructor = function (parent) {
+    base.call(this, parent);
+  };
+  Constructor.prototype = Object.create(base && base.prototype, {
+    constructor: {
+      value: Constructor,
+      writable: true,
+      configurable: true,
+    },
+  });
+  Object.assign(Constructor.prototype, prototypeExtras);
+  return Constructor;
+}

package/lib/lookup.js

@@ -0,0 +1,62 @@
+const ALWAYS_UPDATE = "__";
+
+/**
+ * Used internally.
+ * An object which pools the results of lookup queries so we don't have to
+ * repeat them in the same component.
+ * The Lookup instance will be shared between instances of a component.
+ * Must call reset() on every update.
+ */
+export function Lookup(callbacks) {
+  this.callbacks = callbacks;
+  this.run = {};
+}
+
+Lookup.prototype = {
+  /**
+   * Lookup a watched value during update. Returns an object with {o, n, c}
+   * (oldValue, newValue, changed).
+   * You must resetLookups before calling get during an update.
+   * The point is to pool the result so it doesn't have to be repeated.
+   */
+  get: function (component, props, key) {
+    const run = this.run;
+    if (run[key] === undefined) {
+      // Verbose but efficient way as it avoids lookups?
+      // Or is this harmful to performance because we're just reading values more than calling functions?
+      let o = component._p[key];
+      // TODO: is this checking for watchOnce?
+      o = o === undefined ? "" : o;
+      const n = this.callbacks[key](props, component);
+      const c = n !== o;
+      component._p[key] = n;
+      const rtn = { n, o, c };
+      run[key] = rtn;
+      return rtn;
+    }
+    return run[key];
+  },
+  reset: function () {
+    this.run = {};
+  },
+  applyCallbacks: function (component, props, element, callbacks) {
+    for (let key in callbacks) {
+      let callback = callbacks[key];
+      if (key === ALWAYS_UPDATE) {
+        callback.call(component, element, component.props, component);
+      } else {
+        const result = this.get(component, props, key);
+        if (result.c) {
+          callback.call(
+            component,
+            result.n,
+            result.o,
+            element,
+            props,
+            component,
+          );
+        }
+      }
+    }
+  },
+};

package/lib/pool.js

@@ -0,0 +1,155 @@
+import { createComponent } from "./utils";
+
+/*
+ * Gets a component from the pool.
+ */
+const getComponent = (pool, componentClass, key, item, parent) => {
+  let component;
+  if (pool.hasOwnProperty(key)) {
+    component = pool[key];
+    component.render(item);
+  } else {
+    component = createComponent(componentClass, parent, item);
+    pool[key] = component;
+  }
+  return component;
+};
+
+/**
+ * Trims the unwanted child elements from the end.
+ *
+ * @param {Node} e
+ * @param {Array} childNodes
+ * @param {Int} itemsLength
+ */
+function trimChildren(e, childNodes, itemsLength) {
+  let lastIndex = childNodes.length - 1;
+  let keepIndex = itemsLength - 1;
+  for (let i = lastIndex; i > keepIndex; i--) {
+    e.removeChild(childNodes[i]);
+  }
+}
+
+/**
+ * Pulls an item forward in an array, to replicate insertBefore.
+ * @param {Array} arr
+ * @param {any} item
+ * @param {Int} to
+ */
+function pull(arr, item, to) {
+  const position = arr.indexOf(item);
+  if (position != to) {
+    arr.splice(to, 0, arr.splice(position, 1)[0]);
+  }
+}
+
+/**
+ * Pools same type components, retrieving by key.
+ * Must not be shared.
+ *
+ * @param {class} componentClass - The class of Component to create.
+ * @param {function} keyFn - A function which obtains the key to pool by
+ */
+export function KeyedPool(componentClass, keyFn) {
+  this._v = componentClass;
+  this._f = keyFn;
+  this._k = []; // keys
+  this._p = {}; // pool of component instances
+}
+const proto = KeyedPool.prototype;
+
+/**
+ * Retrieves a single component. Though not used in wallace itself, it may
+ * be used elsewhere, such as in the router.
+ *
+ * @param {Object} item - The item which will be passed as props.
+ * @param {Component} parent - The parent component.
+ */
+proto.getOne = function (item, parent) {
+  return getComponent(this._p, this._v, this._f(item), item, parent);
+};
+
+/**
+ * Updates the element's childNodes to match the items.
+ * Performance is important.
+ *
+ * @param {DOMElement} e - The DOM element to patch.
+ * @param {Array} items - Array of items which will be passed as props.
+ * @param {Component} parent - The parent component.
+ */
+proto.patch = function (e, items, parent) {
+  // Attempt to speed up by reducing lookups. Does this even do anything?
+  // Does webpack undo this/do it for for me? Does the engine?
+  const pool = this._p;
+  const componentClass = this._v;
+  const keyFn = this._f;
+  const childNodes = e.childNodes;
+  const itemsLength = items.length;
+  const oldKeySequence = this._k;
+  const newKeys = [];
+  let item,
+    key,
+    component,
+    childElementCount = oldKeySequence.length + 1;
+  for (let i = 0; i < itemsLength; i++) {
+    item = items[i];
+    key = keyFn(item);
+    component = getComponent(pool, componentClass, key, item, parent);
+    newKeys.push(key);
+    if (i > childElementCount) {
+      e.appendChild(component.el);
+    } else if (key !== oldKeySequence[i]) {
+      e.insertBefore(component.el, childNodes[i]);
+      pull(oldKeySequence, key, i);
+    }
+  }
+  this._k = newKeys;
+  trimChildren(e, childNodes, itemsLength);
+};
+
+/**
+ * Pools same type components, retrieving by sequence.
+ *
+ * @param {class} componentClass - The class of Component to create.
+ */
+export function SequentialPool(componentClass) {
+  this._v = componentClass;
+  this._p = []; // pool of component instances
+  this._c = 0; // Child element count
+}
+
+/**
+ * Updates the element's childNodes to match the items.
+ * Performance is important.
+ *
+ * @param {DOMElement} e - The DOM element to patch.
+ * @param {Array} items - Array of items which will be passed as props.
+ * @param {Component} parent - The parent component.
+ */
+SequentialPool.prototype.patch = function (e, items, parent) {
+  const pool = this._p;
+  const componentClass = this._v;
+  const childNodes = e.childNodes;
+  const itemsLength = items.length;
+  let item,
+    component,
+    poolCount = pool.length,
+    childElementCount = this._c;
+
+  for (let i = 0; i < itemsLength; i++) {
+    item = items[i];
+    if (i < poolCount) {
+      component = pool[i];
+      component.render(item);
+    } else {
+      component = createComponent(componentClass, parent, item);
+      pool.push(component);
+      poolCount++;
+    }
+    if (i >= childElementCount) {
+      e.appendChild(component.el);
+    }
+  }
+  this._c = itemsLength;
+  trimChildren(e, childNodes, itemsLength);
+};

package/lib/types.d.ts

@@ -0,0 +1,50 @@
+// This module lies about several definitions in order to make TypeScript work with JSX.
+// Note that docstrings will appear in most IDE tooltips, but only the latest overload.
+
+declare module "wallace" {
+  interface ComponentFunction<Type> extends Function {
+    (props: Type, ...rest: Array<any>): JSX.Element;
+    nest?({ props, showIf }: { props?: Type; showIf?: boolean }): JSX.Element;
+    repeat?({
+      props,
+      showIf,
+    }: {
+      props: Array<Type>;
+      showIf?: boolean;
+    }): JSX.Element;
+  }
+
+  export type Accepts<Type> = ComponentFunction<Type>;
+
+  export interface Component<T> {
+    update(): void;
+    render(props: T): void;
+    el: HTMLElement;
+  }
+
+  // TODO: add more to this, maybe overload for each case.
+  export function mount<T>(
+    element: string | HTMLElement,
+    component: Accepts<T>,
+    props?: T,
+  ): Component<T>;
+
+  export function createProxy<T>(obj: T, component: Component<T>): T;
+
+  export function extendPrototype<T>(
+    base: Accepts<T>,
+    extras?: { [key: string]: any },
+  ): Accepts<T>;
+}
+
+// TODO: beef these up.
+declare namespace JSX {
+  interface Element {}
+  interface IntrinsicElements {}
+  interface ElementClass {}
+  interface IntrinsicAttributes {}
+  interface ElementAttributesProperty {}
+}
+
+// This is necessary for weird TypeScript reasons.
+export {};

package/lib/utils.js

@@ -0,0 +1,75 @@
+/**
+ * Creates and mounts a component onto an element.
+ *
+ * @param {unsure} elementOrId Either a string representing an id, or an element.
+ * @param {class} cls The class of Component to create
+ * @param {object} props The props to pass to the component (optional)
+ * @param {object} parent The parent component (optional)
+ */
+export function mount(elementOrId, cls, props, parent) {
+  const component = createComponent(cls, parent, props);
+  replaceNode(getElement(elementOrId), component.el);
+  return component;
+}
+
+export function replaceNode(nodeToReplace, newNode) {
+  nodeToReplace.parentNode.replaceChild(newNode, nodeToReplace);
+}
+
+export function getElement(elementOrId) {
+  return typeof elementOrId === "string"
+    ? document.getElementById(elementOrId)
+    : elementOrId;
+}
+
+/**
+ * Creates a component and initialises it.
+ *
+ * @param {class} cls The class of Component to create
+ * @param {object} parent The parent component (optional)
+ * @param {object} props The props to pass to the component (optional)
+ */
+export function createComponent(cls, parent, props) {
+  const component = buildComponent(cls, parent);
+  component.render(props);
+  return component;
+}
+
+/**
+ * Builds a component.
+ */
+export function buildComponent(cls, parent) {
+  const component = new cls(parent);
+  const prototype = cls.prototype;
+  const dom = prototype._n.cloneNode(true);
+  component.el = dom;
+  component._b(component, dom);
+  return component;
+}
+
+/**
+ * Wraps target in a Proxy which calls component.update() whenever it is modified.
+ *
+ * @param {*} target - Any object, including arrays.
+ * @param {*} component - A component.
+ * @returns a Proxy object.
+ */
+export const createProxy = (target, component) => {
+  const handler = {
+    get(target, key) {
+      if (key == "isProxy") return true;
+      const prop = target[key];
+      if (typeof prop == "undefined") return;
+      // set value as proxy if object
+      if (!prop.isProxy && typeof prop === "object")
+        target[key] = new Proxy(prop, handler);
+      return target[key];
+    },
+    set(target, key, value) {
+      target[key] = value;
+      component.update();
+      return true;
+    },
+  };
+  return new Proxy(target, handler);
+};

package/package.json

@@ -1,38 +1,20 @@
 {
   "name": "wallace",
-  "version": "0.0.2",
-  "description": "The framework that brings you freedom.",
-  "babel": {
-    "presets": [
-      "@babel/preset-env"
-    ],
-    "plugins": [
-      "babel-plugin-wallace",
-      "@babel/plugin-syntax-jsx",
-      "@babel/plugin-proposal-class-properties"
-    ]
-  },
+  "version": "0.0.6",
+  "author": "Andrew Buchan",
+  "description": "The framework that brings you glee.",
+  "license": "ISC",
+  "main": "lib/index.js",
   "files": [
-    "dist",
-    "src"
+    "/lib"
   ],
-  "main": "dist/wallace.js",
+  "types": "./lib/types.d.ts",
   "scripts": {
-    "prepublish": "npm run build",
-    "build": "NODE_ENV=production rollup -c",
-    "test": "jest --clearCache && jest",
-    "jest-clear": "jest --clearCache"
+    "test": "jest --clearCache && jest"
   },
-  "author": "Andrew Buchan",
-  "license": "MIT",
   "dependencies": {
-    "@babel/plugin-proposal-class-properties": "^7.18.6",
-    "@babel/plugin-syntax-jsx": "^7.22.5",
-    "babel-plugin-wallace": "^0.0.2",
-    "jest-summary-reporter": "^0.0.2"
+    "babel-plugin-wallace": "^0.0.6",
+    "browserify": "^17.0.1"
   },
-  "gitHead": "922a989fa10d19dbcd2aaffe725d075a85214a73",
-  "devDependencies": {
-    "rollup": "^3.27.0"
-  }
+  "gitHead": "3742fbcfdc21146c90252c2436fde91634fafa9e"
 }

package/README.md

@@ -1,3 +0,0 @@
-# Wallace
-
-See https://github.com/andyhasit/wallace