wallace 0.4.0 → 0.6.0

package/README.md

@@ -0,0 +1,29 @@
+# Wallace
+
+This package contains the library for the [Wallace](https://github.com/wallace-js/wallace) framework, which you import into your source files:
+
+```jsx
+import { mount } from "wallace";
+
+const MyComponent = () => <div>Hello world</div>;
+
+mount("main", Component);
+```
+
+It requires the [babel-plugin-wallace](https://www.npmjs.com/package/babel-plugin-wallace) to work, which is a dependency of this package, always at the same version.
+
+Although you can install these packages with:
+
+```
+npm i wallace -D
+```
+
+You are better off creating an empty project with:
+
+```
+npx create-wallace-app
+```
+
+As that sets up your babel and webpack configurations for you.
+
+For more detailed documentation see the [Wallace repository on github](https://github.com/wallace-js/wallace).

package/lib/component.js

@@ -1,154 +1,170 @@
+const throwAway = document.createElement("template");
 const NO_LOOKUP = "__";
 
-/**
- * The base component.
- */
-export function Component() {
-  this.ctrl = undefined; // The controller.
-  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._e = {}; // The dynamic elements in the DOM.
-  this._s = []; // A stash for misc objects.
-  this._p = {}; // The previous values for watches to compare against.
-  this._r = {}; // The current values read during an update.
-}
+const ComponentBase = {
+  stubs: {},
+  prototype: {
+    /**
+     * The render function that gets called by parent components.
+     */
+    render: function (props, ctrl) {
+      this.props = props;
+      this.ctrl = ctrl;
+      this.update();
+    },
 
-Component.stubs = {};
+    /**
+     * Updates the DOM and renders nested components.
+     */
+    update: function () {
+      this._u(0, this._l);
+    },
 
-var proto = Component.prototype;
+    _u: function (i, il) {
+      let watch,
+        element,
+        parent,
+        displayToggle,
+        detacher,
+        lookupTrue,
+        shouldBeVisible,
+        detachedElements,
+        detachedElement,
+        index,
+        adjustedIndex;
 
-Object.defineProperty(proto, "hidden", {
-  set: function (value) {
-    this.el.hidden = value;
-  }
-});
+      const watches = this._w,
+        props = this.props,
+        previous = this._p;
+      /*
+      Watches is an array of objects with keys:
+        e: the element index (number)
+        c: the callbacks (object)
+        ?v: visibility toggle (object)
 
-proto._gs = function (name) {
-  return this.constructor.stubs[name];
-};
+      The callback is an object whose key is the lookup and value is a function which
+      applies the effect.
 
-/**
- * Reads a query during update, returns an array with (oldValue, newValue, changed)
- * and saves the old value. Must reset this._r before each run.
- */
-proto._rq = function (props, key) {
-  const run = this._r;
-  if (run[key] === undefined) {
-    let oldValue = this._p[key];
-    const newValue = this._q[key](props, this);
-    this._p[key] = newValue;
-    const rtn = [newValue, oldValue, newValue !== oldValue];
-    run[key] = rtn;
-    return rtn;
-  }
-  return run[key];
-};
+      The visibility toggle has keys:
+        q: the query key in lookup
+        s: the number of watches to skip as their node is underneath
+        r: reversed
+        ?d: detacher 
 
-/**
- * Applies the callbacks.
- */
-proto._ac = function (props, element, callbacks) {
-  for (let key in callbacks) {
-    let callback = callbacks[key];
-    if (key === NO_LOOKUP) {
-      callback(element, props, this);
-    } else {
-      const result = this._rq(props, key);
-      if (result[2]) {
-        callback(element, props, this, result[0]);
+      The detacher has keys:
+        i: the initial element index
+        s: the stash key of the detacher (plain object)
+        e: the parent element key
+      */
+      while (i < il) {
+        watch = watches[i];
+        element = this._e[watch.e];
+        displayToggle = watch.v;
+        shouldBeVisible = true;
+        if (displayToggle) {
+          lookupTrue = !!this._q[displayToggle.q](props, this);
+          shouldBeVisible = displayToggle.r ? lookupTrue : !lookupTrue;
+          detacher = displayToggle.d;
+          if (detacher) {
+            index = detacher.i;
+            parent = this._e[detacher.e];
+            detachedElements = this._s[detacher.s];
+            detachedElement = detachedElements[index];
+            if (shouldBeVisible && detachedElement) {
+              adjustedIndex =
+                index -
+                Object.keys(detachedElements).filter(function (k) {
+                  return k < index && detachedElements[k];
+                }).length;
+              parent.insertBefore(detachedElement, parent.childNodes[adjustedIndex]);
+              detachedElements[index] = null;
+            } else if (!shouldBeVisible && !detachedElement) {
+              parent.removeChild(element);
+              detachedElements[index] = element;
+            }
+          } else {
+            element.hidden = !shouldBeVisible;
+          }
+          if (!shouldBeVisible) {
+            i += displayToggle.s;
+          }
+        }
+        if (shouldBeVisible) {
+          const prev = previous[i],
+            callbacks = watch.c;
+          for (let key in callbacks) {
+            if (key === NO_LOOKUP) {
+              callbacks[key](element, props, this);
+            } else {
+              const oldValue = prev[key],
+                newValue = this._q[key](props, this);
+              if (oldValue !== newValue) {
+                callbacks[key](element, props, this, newValue);
+                prev[key] = newValue;
+              }
+            }
+          }
+        }
+        i++;
       }
     }
   }
 };
 
-/**
- * The render function that gets called by parent components.
- */
-proto.render = function (props, ctrl) {
-  this.props = props;
-  this.ctrl = ctrl;
-  this.update();
-};
+Object.defineProperty(ComponentBase.prototype, "hidden", {
+  set: function (value) {
+    this.el.hidden = value;
+  }
+});
 
 /**
- * Updates the DOM.
- * Loops over watches, skipping n watches if elements are hidden.
+ * Creates the constructor function for a component definition.
+ *
+ * @param {*} baseComponent - a component definition to inherit from.
+ * @returns the newly created component definition function.
  */
-proto.update = function () {
-  let i = 0,
-    watch,
-    element,
-    parent,
-    displayToggle,
-    detacher,
-    lookupTrue,
-    shouldBeVisible,
-    detachedElements,
-    detachedElement,
-    index,
-    adjustedIndex,
-    thisElement;
+export function createConstructor(baseComponent) {
+  const Component = function () {
+    const root = (this.el = this._n.cloneNode(true)),
+      dynamicElements = (this._e = []),
+      stash = (this._s = []),
+      previous = (this._p = []),
+      refs = (this.refs = {});
+    this.ctrl = {};
+    this.props = {};
+    this._l = this._w.length;
+    this._b(this, root, dynamicElements, stash, previous, refs);
+  };
 
-  const watches = this._w;
-  const props = this.props;
-  const il = watches.length;
-  this._r = {};
-  /*
-  Watches is an array of objects with keys:
-    e: the element reference (string)
-    c: the callbacks (object)
-    ?v: visibility toggle (object)
-
-  The display toggle has keys:
-    q: the query key in lookup
-    s: the number of watches to skip as their node is underneath
-    r: reversed
-    ?d: detacher 
-
-  The detacher has keys:
-    i: the initial element index
-    s: the stash key of the detacher (plain object)
-    e: the parent element key
-  */
-  while (i < il) {
-    watch = watches[i];
-    element = this._e[watch.e];
-    displayToggle = watch.v;
-    i++;
-    shouldBeVisible = true;
-    if (displayToggle) {
-      lookupTrue = !!this._rq(props, displayToggle.q)[0];
-      shouldBeVisible = displayToggle.r ? lookupTrue : !lookupTrue;
-      detacher = displayToggle.d;
-      if (detacher) {
-        index = detacher.i;
-        parent = this._e[detacher.e];
-        detachedElements = this._s[detacher.s];
-        detachedElement = detachedElements[index];
-        if (shouldBeVisible && detachedElement) {
-          adjustedIndex =
-            index -
-            Object.keys(detachedElements).filter(function (k) {
-              return k < index && detachedElements[k];
-            }).length;
-          parent.insertBefore(detachedElement, parent.childNodes[adjustedIndex]);
-          detachedElements[index] = null;
-        } else if (!shouldBeVisible && !detachedElement) {
-          thisElement = this._e[watch.e];
-          parent.removeChild(thisElement);
-          detachedElements[index] = thisElement;
-        }
-      } else {
-        element.hidden = !shouldBeVisible;
-      }
-      if (!shouldBeVisible) {
-        i += displayToggle.s;
-      }
+  const proto = (Component.prototype = Object.create(baseComponent.prototype, {
+    constructor: {
+      value: Component
     }
-    if (shouldBeVisible) {
-      this._ac(props, element, watch.c);
+  }));
+
+  // This lets us assign to prototype without replacing it.
+  Object.defineProperty(Component, "methods", {
+    set: function (value) {
+      Object.assign(proto, value);
+    },
+    get: function () {
+      return proto;
     }
-  }
-};
+  });
+
+  Component.stubs = {} && baseComponent.stubs;
+  return Component;
+}
+
+export function defineComponent(html, watches, queries, buildFunction, inheritFrom) {
+  const ComponentDefinition = createConstructor(inheritFrom || ComponentBase);
+  const proto = ComponentDefinition.prototype;
+  throwAway.innerHTML = html;
+  //Ensure these do not clash with fields on the component itself.
+  proto._w = watches;
+  proto._q = queries;
+  proto._b = buildFunction;
+  proto._n = throwAway.content.firstChild;
+  proto.base = ComponentBase.prototype;
+  return ComponentDefinition;
+}

package/lib/extend.js

@@ -0,0 +1,20 @@
+import { createConstructor } from "./component";
+
+/**
+ * Calls to this function which provide the 2nd argument:
+ *
+ *   const Foo = extendComponent(Bar, () => <div></div>))
+ *
+ * Are modified by the Babel plugin to become this:
+ *
+ *   const Foo = defineComponent(,,,,Bar);
+ *
+ * So it should never be called with 2nd arg in real life.
+ */
+export function extendComponent(base, componentDef) {
+  // This function call will have been replaced if 2nd arg is a valid component func.
+  // and therefore we would not receive it.
+  if (componentDef)
+    throw new Error("2nd arg to extendComponent must be a JSX arrow function");
+  return createConstructor(base);
+}

package/lib/index.js

@@ -1,31 +1,10 @@
-import { mount, watch } from "./utils";
-import { Component } from "./component";
-import { KeyedRepeater, SequentialRepeater } from "./repeaters";
-import {
-  extendComponent,
-  defineComponent,
-  findElement,
-  getKeyedRepeater,
-  getSequentialRepeater,
-  onEvent,
-  nestComponent,
-  saveRef,
-  stashMisc
-} from "./initCalls";
-
-export {
-  Component,
-  defineComponent,
-  extendComponent,
-  findElement,
-  getKeyedRepeater,
-  getSequentialRepeater,
-  KeyedRepeater,
-  mount,
-  nestComponent,
-  onEvent,
-  saveRef,
-  SequentialRepeater,
-  stashMisc,
-  watch
-};
+export { defineComponent } from "./component";
+export { extendComponent } from "./extend";
+export { mount } from "./mount";
+export { nestComponent } from "./nest";
+export { saveRef } from "./refs";
+export { KeyedRepeater } from "./repeaters/keyed";
+export { SequentialRepeater } from "./repeaters/sequential";
+export { getStub } from "./stubs";
+export { findElement, onEvent, stashMisc } from "./utils";
+export { watch, protect } from "./watch";

package/lib/mount.js

@@ -0,0 +1,17 @@
+import { replaceNode } from "./utils";
+
+/**
+ * Creates and mounts a component onto an element.
+ *
+ * @param {any} elementOrId Either a string representing an id, or an element.
+ * @param {callable} componentDefinition The class of Component to create
+ * @param {object} props The props to pass to the component (optional)
+ */
+export function mount(elementOrId, componentDefinition, props, ctrl) {
+  const component = new componentDefinition();
+  component.render(props, ctrl);
+  const element =
+    typeof elementOrId === "string" ? document.getElementById(elementOrId) : elementOrId;
+  replaceNode(element, component.el);
+  return component;
+}

package/lib/nest.js

@@ -0,0 +1,8 @@
+import { findElement, replaceNode } from "./utils";
+
+export function nestComponent(rootElement, path, componentDefinition) {
+  const el = findElement(rootElement, path),
+    child = new componentDefinition();
+  replaceNode(el, child.el);
+  return child;
+}

package/lib/refs.js

@@ -0,0 +1,19 @@
+function Ref(component, node, start, end) {
+  this.node = node;
+  this._c = component;
+  this._s = start;
+  this._e = end;
+}
+
+Ref.prototype.update = function () {
+  this._c._u(this._s, this._e);
+};
+
+/**
+ * Saves a reference to a node (element or nested component)
+ * Returns the node.
+ */
+export function saveRef(node, component, refs, name, start, end) {
+  refs[name] = new Ref(component, node, start, end);
+  return node;
+}

package/lib/{repeaters.js → repeaters/keyed.js}

@@ -1,4 +1,4 @@
-import { buildComponent } from "./utils";
+import { trimChildren } from "../utils";
 
 /*
  * Gets a component from the pool.
@@ -8,28 +8,13 @@ function getComponent(pool, componentDefinition, ctrl, key, props) {
   if (pool.hasOwnProperty(key)) {
     component = pool[key];
   } else {
-    component = buildComponent(componentDefinition);
+    component = new componentDefinition();
     pool[key] = component;
   }
   component.render(props, ctrl);
   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
@@ -103,48 +88,3 @@ proto.patch = function (e, items, ctrl) {
   this.keys = newKeys;
   trimChildren(e, childNodes, itemsLength);
 };
-
-/**
- * Repeats nested components, yielding from its pool sequentially.
- *
- * @param {componentDefinition} componentDefinition - The class ComponentDefinition to create.
- */
-export function SequentialRepeater(componentDefinition) {
-  this.def = componentDefinition;
-  this.pool = []; // pool of component instances
-  this.count = 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 {any} ctrl - The parent item's controller.
- */
-SequentialRepeater.prototype.patch = function (e, items, ctrl) {
-  const pool = this.pool;
-  const componentDefinition = this.def;
-  const childNodes = e.childNodes;
-  const itemsLength = items.length;
-  let component,
-    poolCount = pool.length,
-    childElementCount = this.count;
-
-  for (let i = 0; i < itemsLength; i++) {
-    if (i < poolCount) {
-      component = pool[i];
-    } else {
-      component = buildComponent(componentDefinition);
-      pool.push(component);
-      poolCount++;
-    }
-    component.render(items[i], ctrl);
-    if (i >= childElementCount) {
-      e.appendChild(component.el);
-    }
-  }
-  this.count = itemsLength;
-  trimChildren(e, childNodes, itemsLength);
-};

package/lib/repeaters/sequential.js

@@ -0,0 +1,46 @@
+import { trimChildren } from "../utils";
+
+/**
+ * Repeats nested components, yielding from its pool sequentially.
+ *
+ * @param {componentDefinition} componentDefinition - The ComponentDefinition to create.
+ */
+export function SequentialRepeater(componentDefinition) {
+  this.def = componentDefinition;
+  this.pool = []; // pool of component instances
+  this.count = 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 {any} ctrl - The parent item's controller.
+ */
+SequentialRepeater.prototype.patch = function (e, items, ctrl) {
+  const pool = this.pool;
+  const componentDefinition = this.def;
+  const childNodes = e.childNodes;
+  const itemsLength = items.length;
+  let component,
+    poolCount = pool.length,
+    childElementCount = this.count;
+
+  for (let i = 0; i < itemsLength; i++) {
+    if (i < poolCount) {
+      component = pool[i];
+    } else {
+      component = new componentDefinition();
+      pool.push(component);
+      poolCount++;
+    }
+    component.render(items[i], ctrl);
+    if (i >= childElementCount) {
+      e.appendChild(component.el);
+    }
+  }
+  this.count = itemsLength;
+  trimChildren(e, childNodes, itemsLength);
+};

package/lib/stubs.js

@@ -0,0 +1,6 @@
+/**
+ * Gets a stub by name.
+ */
+export function getStub(component, name) {
+  return component.constructor.stubs[name];
+}

package/lib/types.d.ts

@@ -16,7 +16,7 @@
   6. Inheritance
   7. Stubs
   8. TypeScript
-  9. Utility functions
+  9. Helpers
 
 For more detailed documentation go to https://github.com/wallace-js/wallace
 
@@ -47,9 +47,11 @@ const MyComponent = ({title}, {ctrl, event}) => (
 
 The **xargs** contains:
 
-- `ctrl` a reference to a controller object.
-- `self` a reference to the component instance (as `this` is not allowed).
-- `event` for use in event callbacks, signifies the event.
+- `ctrl` refers to the controller.
+- `props` refers to the props, in case you want the non-destructured version too.
+- `self` refers to the component instance (as `this` is not allowed).
+- `event` refers to the event in an event callback.
+- `element` refers to the element in an event callback, or in `apply`.
 
 The function will be replaced by a very different one during compilation, therefore:
 
@@ -71,7 +73,7 @@ The arguments are:
 3. props for the element (optional)
 4. controller (optional)
 
-`mount` returns the component instance, allowing you to call it methods:
+`mount` returns the component instance, allowing you to call its methods:
 
 ```tsx
 root.update();
@@ -100,11 +102,11 @@ places.
 
 #### Overriding
 
-You can override these methods, and add new ones using `methods` directly on the
+You can override these methods, and add new ones using `methods` property of the
 component definition:
 
 ```tsx
-MyComponent.methods({
+MyComponent.methods = {
   render(props) {
     this.ctrl = new MyController(this, props);
     this.update();
@@ -112,7 +114,7 @@ MyComponent.methods({
   getName() {
     return 'wallace';
   }
-});
+};
 ```
 
 This has the same effect as setting them on the prototype:
@@ -124,11 +126,11 @@ MyComponent.prototype.render = function () {};
 You can use `this.base` to access methods on the base `Component` class:
 
 ```tsx
-MyComponent.methods({
+MyComponent.methods = {
   render(props) {
     this.base.render.call(this, props, ctrl);
   }
-});
+};
 ```
 
 Note that `base` is not the same as `super` in classes which access the lowest override.
@@ -141,10 +143,9 @@ so use `self` from the **xargs** in component functions.
 
 Component instances have the following fields:
 
-- `props` the data for this component instance, stored as reference to original, not a 
-copy.
-- `ctrl` an object to help coordinate things, also stored as reference.
-- `ref` a dictionary of named elements.
+- `props` the data for this component instance.
+- `ctrl` the controller object.
+- `refs` an object with references to node.
 - `el` the component instance's root element.
 
 Both `props` and `ctrl` are set during the `render` method before calling `update`.
@@ -201,27 +202,16 @@ Notes:
 
 ## 4. Directives
 
-Directives are attributes with special behaviours, as listed below. Each has more
-detailed information on its JSDoc, which should display as a tool tip\* when you hover
-over it in your IDE.
+Directives are attributes with special behaviours. 
 
-You can also display this list by hovering over any JSX element, like `div`.
+You can see the list of available directives by hovering over any JSX element, like
+a `div`
 
-- `apply` runs a callback to modify an element.
-- `bind` updates a value when an input is changed.
-- `class:xyz` defines a set of classes to be toggled.
-- `hide` sets an element or component's hidden property.
-- `html` Set the element's `innnerHTML` property.
-- `if` excludes an element from the DOM.
-- `on[EventName]` creates an event handler (note the code is copied)
-- `props` specifes props for a nested or repeated component, in which case it must be
-an array.
-- `ref` saves a reference to an element or nested component.
-- `show` sets and element or component's hidden property.
-- `style:xyz` sets a specific style property.
-- `toggle:xyz` toggles `xyz` as defined by `class:xyz` on same element, or class `xyz`.
+You will get more details by hovering on the directive itself, but unfortunetely the
+tool tip won't display when you use a qualifier, like `class:danger`. To see it you can
+temporarily change it to something `class x:danger`.
 
-\* The tool tip won't display when you use a qualifier, like `class:danger`. 
+You can define your own directives in your babel config.
 
 ## 5. Controllers
 
@@ -266,12 +256,12 @@ const TaskList = (_, {ctrl}) => (
   </div>
 );
 
-TaskList.methods({
+TaskList.methods = {
   render(_, ctrl) {
     this.ctrl = new TaskController(this, ctrl);
     this.update();
   }
-});
+};
 ```
 
 ## 6. Inheritance
@@ -392,12 +382,12 @@ const Task: Uses<null, null, TaskMethods> = (_, { self }) => (
   <div>{self.getName()}</div>
 ));
 
-Task.methods({
+Task.methods = {
   getName() { return 'wallace' },
   render(props, ctrl) {  // types are already known
     this.props = { ...props, notallowed: 1 };  // type error
   }
-});
+};
 ```
 
 The type will pass into the object passed into `methods` so it recognises custom methods
@@ -445,7 +435,7 @@ Wallace defines some other types you may use:
     constructor, not a class)
  - `ComponentInstance<Props, Controller, Methods>` - a component instance.
 
-## Utility functions
+## 9. Helpers
 
 Each of these has their own JSDoc, we just lsit them here.
 
@@ -469,11 +459,24 @@ mount("elementId", MyComponent, props, ctrl);
 
 ### watch
 
-Returns a Proxy of an object which calls `callback` when keys are set:
+Returns a Proxy of an object which calls `callback` when it, or its nested objects are
+modified:
 
 ```
-watch(obj, () => console.log('obj modified);
+const watchedObj = watch([], () => console.log('obj modified));
+watchedObj[0] = 'foo;  // Calls callback.
 ```
+
+### protect
+
+Returns a Proxy of an object which throws an error if it, or its nested objects are
+modified.
+
+```
+const protectedObj = protect([]);
+watchedObj[0] = 'foo';  // throws error.
+```
+
 ---
 Report any issues to https://github.com/wallace-js/wallace (and please give it a ★)
 
@@ -493,11 +496,10 @@ declare module "wallace" {
       props: Props,
       xargs?: {
         ctrl: Controller;
+        props: Props;
         self: ComponentInstance<Props, Controller, Methods>;
         event: Event;
-        ev: Event;
         element: HTMLElement;
-        el: HTMLElement;
       }
     ): JSX.Element;
     nest?({
@@ -518,10 +520,8 @@ declare module "wallace" {
       show?: boolean;
       hide?: boolean;
     }): JSX.Element;
-    methods?(
-      object: ComponenMethods<Props, Controller> &
-        ThisType<ComponentInstance<Props, Controller, Methods>>
-    ): void;
+    methods?: ComponenMethods<Props, Controller> &
+      ThisType<ComponentInstance<Props, Controller, Methods>>;
     readonly prototype?: ComponenMethods<Props, Controller> &
       ThisType<ComponentInstance<Props, Controller, Methods>>;
     // Methods will not be available on nested component, so omit.
@@ -555,6 +555,11 @@ declare module "wallace" {
     Methods extends object = {}
   > = ComponentFunction<Props, Controller, Methods>;
 
+  export interface Ref {
+    node: HTMLElement | ComponentInstance;
+    update(): void;
+  }
+
   /**
    * The type for a component instance.
    */
@@ -566,7 +571,7 @@ declare module "wallace" {
     el: HTMLElement;
     props: Props;
     ctrl: Controller;
-    ref: { [key: string]: HTMLElement };
+    refs: { [key: string]: Ref };
     base: Component<Props, Controller>;
   } & Component<Props, Controller> &
     Methods;
@@ -643,8 +648,21 @@ declare module "wallace" {
   ): ComponentInstance<Props, Controller, Methods>;
 
   /**
-   * Returns a Proxy of an object which calls `callback` when keys are set, and this
-   * extends to nested objects:
+   * Returns a Proxy of an object which throws an error when it, or its nested objects
+   * are modified:
+   *
+   * ```js
+   * const protectedObj = protect([]);
+   * watchedObj[0] = 'foo';  // throws error.
+   * ```
+   */
+  export function protect<T>(target: T): T;
+
+  type WatchCallback = (target: any, key: string, value: any) => void;
+
+  /**
+   * Returns a Proxy of an object which calls `callback` when it, or its nested objects
+   * are modified:
    *
    * ```js
    * ar = watch([], callback)
@@ -656,18 +674,23 @@ declare module "wallace" {
    * obj.y = {}
    * obj.y.z = 1000
    * ```
-   * The callback does not indicate the data has changed, only that a key was set.
+   * The callback accepts parameters:
+   *
+   *  - `target` - the object which is being modified.
+   *  - `key` - the key being set.
+   *  - `value` - the value it is being set to.
+   *
+   * The callback is called after the modification has occured.
    *
    * Some methods like `Array.push` set the index and then the length immediately after,
    * so we use a timeout period to avoid calling the callback twice for what is really a
    * single operation.
    *
    * @param {*} target - Any object, including arrays.
-   * @param {*} timeout - Any value in ms. Defaults to 100.
    * @param {*} callback - A callback function.
    * @returns a Proxy of the object.
    */
-  export function watch<T>(target: T, callback: CallableFunction, timeout?: number): T;
+  export function watch<T>(target: T, callback: WatchCallback): T;
 }
 
 type MustBeExpression = Exclude<any, string>;
@@ -739,8 +762,6 @@ interface DirectiveAttributes extends AllDomEvents {
    * );
    * ```
    *
-   * Unfortunately you lose the tooltip in that format.
-   *
    * Note that destructured props are converted to member expressions, so these examples
    * work even though it looks like you're setting a local variable.
    */
@@ -760,11 +781,34 @@ interface DirectiveAttributes extends AllDomEvents {
    * ```
    * <div class:danger="danger red" toggle:danger={expr}></div>
    * ```
-   *
-   * Unfortunately you lose the tooltip in that format.
    */
   class?: any;
 
+  /**
+   * ## Wallace directive: css
+   *
+   * Shorthand for `fixed:class`:
+   *
+   * ```
+   * <div css={foo} ></div>
+   * ```
+   */
+  css?: string;
+
+  /**
+   * ## Wallace directive: fixed
+   *
+   * Sets the value of an attribute from an expression at point of component definition,
+   * as such the expression may not access props or xargs. See also `css` directive.
+   *
+   * Requires a qualifer, which is the name of the attribute to set.
+   *
+   * ```
+   * <div fixed:class={foo} ></div>
+   * ```
+   */
+  fixed?: string;
+
   /** ## Wallace directive: hide
    *
    * Set the element's `hidden` property and if true, does not render dynamic elements
@@ -806,19 +850,25 @@ interface DirectiveAttributes extends AllDomEvents {
   /**
    * ## Wallace directive: ref
    *
-   * Saves a reference to the element on the component, allowing it to be accessed.
+   * Saves a reference to a node allowing you to:
+   *
+   * 1. Access the element or component as `ref.node`
+   * 2. Update the all nested elements using `ref.update()`.
    *
    * ```
-   * <div ref:title></div>
+   * <div ref:title>
+   *   {name}
+   * </div>
    * ```
    *
    * ```
-   * component.ref.title.textContent = 'hello';
+   * component.refs.title.update();
+   * component.refs.title.node.textContent = 'hello';
    * ```
    *
    * Requires a qualifier, but you lose the tooltip in that format.
    */
-  ref?: string;
+  ref?: null;
 
   /** ## Wallace directive: show
    *
@@ -876,25 +926,30 @@ declare namespace JSX {
      *   <MyComponent.nest props={singleProps} />
      *   <MyComponent.repeat items={arrayOfProps} />
      *   ```
-     * But note that repeat must not have siblings.
+     * Note that repeated components must not have siblings.
      *
      * Available Wallace directives:
      *
      * - `apply` runs a callback to modify an element.
      * - `bind` updates a value when an input is changed.
      * - `class:xyz` defines a set of classes to be toggled.
+     * - `css` shorthand for `fixed:class`.
+     * - `fixed:xyz` sets a attribute from an expression at definition.
      * - `hide` sets an element or component's hidden property.
      * - `html` Set the element's `innnerHTML` property.
      * - `if` excludes an element from the DOM.
      * - `items` set items for repeated component, must be an array of props.
      * - `on[EventName]` creates an event handler (note the code is copied)
      * - `props` specifes props for a nested components.
-     * - `ref` saves a reference to an element or nested component.
+     * - `ref:xyz` saves a reference to node, allowing partial updates or access to element/component.
      * - `show` sets and element or component's hidden property.
      * - `style:xyz` sets a specific style property.
-     * - `toggle:xyz` toggles `xyz` as defined by `class:xyz` on same element, or class `xyz`.
+     * - `toggle:xyz` toggles `xyz` as defined by `class:xyz` on same element, or class
+     *   `xyz`.
      *
-     * Note the tool tip won't display when you use a qualifier, like `class:danger`.
+     * You will get more details by hovering on the directive itself, but unfortunetely
+     * the tool tip won't display when you use a qualifier, like `class:danger`. To see
+     * it you cantemporarily change it to something `class x:danger`.
      */
     [elemName: string]: DirectiveAttributes & Record<string, any>;
   }

package/lib/utils.js

@@ -1,73 +1,36 @@
-/**
- * Creates and mounts a component onto an element.
- *
- * @param {any} elementOrId Either a string representing an id, or an element.
- * @param {callable} componentDefinition The class of Component to create
- * @param {object} props The props to pass to the component (optional)
- */
-export function mount(elementOrId, componentDefinition, props, ctrl) {
-  const component = buildComponent(componentDefinition);
-  component.render(props, ctrl);
-  replaceNode(getElement(elementOrId), component.el);
-  return component;
+export function findElement(rootElement, path) {
+  return path.reduce((acc, index) => acc.childNodes[index], rootElement);
 }
 
 export function replaceNode(nodeToReplace, newNode) {
   nodeToReplace.parentNode.replaceChild(newNode, nodeToReplace);
 }
 
-export function getElement(elementOrId) {
-  return typeof elementOrId === "string"
-    ? document.getElementById(elementOrId)
-    : elementOrId;
-}
-
 /**
- * Builds a component's initial DOM.
+ * Trims the unwanted child elements from the end.
+ *
+ * @param {Node} e
+ * @param {Array} childNodes
+ * @param {Int} itemsLength
  */
-export function buildComponent(componentDefinition) {
-  // TODO: add a dev warning here:
-  // if "componentDefinition is not a constructor" then we're probably missing a stub.
-  const component = new componentDefinition();
-  const proto = componentDefinition.prototype;
-  const dom = proto._n.cloneNode(true);
-  component.el = dom;
-  proto._b(component, dom);
-  return component;
+export 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]);
+  }
 }
 
 /**
- * See types for docs. Set grace to 0 for testing.
+ * Stash something on the component. Returns the element.
+ * The generated code is expected to keep track of the position.
  */
-export function watch(target, callback, grace) {
-  let active = false;
-  if (grace === undefined) grace = 100;
-  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];
-    },
+export function stashMisc(element, stash, object) {
+  stash.push(object);
+  return element;
+}
 
-    set(target, key, value) {
-      target[key] = value;
-      if (grace) {
-        if (!active) {
-          setTimeout(() => {
-            active = false;
-          }, grace);
-          active = true;
-          callback();
-        }
-      } else {
-        callback();
-      }
-      return true;
-    }
-  };
-  return new Proxy(target, handler);
+export function onEvent(element, eventName, callback) {
+  element.addEventListener(eventName, callback);
+  return element;
 }

package/lib/watch.js

@@ -0,0 +1,42 @@
+const MUTATING_METHODS = ["push", "pop", "shift", "unshift", "splice", "reverse", "sort"];
+/**
+ * Returns a proxy which calls a callback when the object or its nested objects are
+ * modified.
+ *
+ * Note that proxies have property `isProxy` set to true.
+ */
+export function watch(target, callback) {
+  const handler = {
+    get(target, key) {
+      if (key == "isProxy") return true;
+      const prop = target[key];
+      if (typeof prop == "undefined") return;
+      if (typeof prop === "object") return new Proxy(prop, handler);
+      if (
+        Array.isArray(target) &&
+        typeof target[key] === "function" &&
+        MUTATING_METHODS.includes(key)
+      ) {
+        return (...args) => {
+          const result = target[key](...args);
+          callback(target, key, args);
+          return result;
+        };
+      }
+      return prop;
+    },
+    set(target, key, value) {
+      target[key] = value;
+      callback(target, key, value);
+      return true;
+    }
+  };
+  return new Proxy(target, handler);
+}
+
+export function protect(obj) {
+  return watch(obj, (target, key, value) => {
+    console.log("target", target, "key", key, "value", value);
+    throw new Error("Attempted to modify protected object");
+  });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wallace",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "author": "Andrew Buchan",
   "description": "The framework that brings you FREEDOM!!",
   "license": "ISC",
@@ -8,13 +8,14 @@
   "files": [
     "/lib"
   ],
+  "sideEffects": false,
   "types": "./lib/types.d.ts",
   "scripts": {
     "test": "jest --clearCache && jest"
   },
   "dependencies": {
-    "babel-plugin-wallace": "^0.4.0",
+    "babel-plugin-wallace": "^0.6.0",
     "browserify": "^17.0.1"
   },
-  "gitHead": "286a00b51777c4b7fed9a778b93e9727ed905e2a"
+  "gitHead": "451efab81055751fbda64eb80252ec150460e375"
 }

package/lib/initCalls.js

@@ -1,108 +0,0 @@
-/**
- * Everything in here is used by or modified by the Babel plugin.
- */
-import { Component } from "./component";
-import { buildComponent, replaceNode } from "./utils";
-import { KeyedRepeater, SequentialRepeater } from "./repeaters";
-
-const throwAway = document.createElement("template");
-
-/**
- * A utility function that has to be in here because it needs _createConstructor and
- * we'd otherwise get cirular inmports.
- *
- * Calls to this function which provide the 2nd argument:
- *
- *   const Foo = extendComponent(Bar, () => <div></div>))
- *
- * Are modified by the Babel plugin to become this:
- *
- *   const Foo = defineComponent(,,,,Bar);
- *
- * So it should never be called with 2nd arg in real life.
- */
-export function extendComponent(base, componentDef) {
-  // This function call will have been replaced if 2nd arg is a valid component func.
-  // and therefor we would not receive it.
-  if (componentDef)
-    throw new Error("2nd arg to extendComponent must be a JSX arrow function");
-  return _createConstructor(base);
-}
-
-/*
-Everything after this is used by code generated by the Babel plugin.
-*/
-
-export function findElement(rootElement, path) {
-  return path.reduce((acc, index) => acc.childNodes[index], rootElement);
-}
-
-export function nestComponent(rootElement, path, cls) {
-  const el = findElement(rootElement, path),
-    child = buildComponent(cls);
-  replaceNode(el, child.el);
-  return child;
-}
-
-/**
- * Saves a reference to element or nested component. Returns the element.
- */
-export function saveRef(element, component, name) {
-  component.ref[name] = element;
-  return element;
-}
-
-/**
- * Stash something on the component. Returns the element.
- * The generated code is expected to keep track of the position.
- */
-export function stashMisc(element, component, object) {
-  component._s.push(object);
-  return element;
-}
-
-export function onEvent(element, eventName, callback) {
-  element.addEventListener(eventName, callback);
-  return element;
-}
-
-export function getKeyedRepeater(cls, keyFn) {
-  return new KeyedRepeater(cls, keyFn);
-}
-
-export function getSequentialRepeater(cls) {
-  return new SequentialRepeater(cls);
-}
-
-export function defineComponent(html, watches, queries, buildFunction, inheritFrom) {
-  const ComponentDefinition = _createConstructor(inheritFrom || Component);
-  const prototype = ComponentDefinition.prototype;
-  throwAway.innerHTML = html;
-  //Ensure these do not clash with fields on the component itself.
-  prototype._w = watches;
-  prototype._q = queries;
-  prototype._b = buildFunction;
-  prototype._n = throwAway.content.firstChild;
-  return ComponentDefinition;
-}
-
-function _createConstructor(base) {
-  const ComponentDefinition = function () {
-    base.call(this);
-  };
-  ComponentDefinition.stubs = {};
-  Object.assign(ComponentDefinition.stubs, base.stubs);
-  // This is a helper function for the user.
-  ComponentDefinition.methods = function (obj) {
-    Object.assign(ComponentDefinition.prototype, obj);
-  };
-  ComponentDefinition.prototype = Object.create(base && base.prototype, {
-    constructor: {
-      value: ComponentDefinition,
-      writable: true,
-      configurable: true
-    }
-  });
-  ComponentDefinition.prototype.base = Component.prototype;
-  return ComponentDefinition;
-}