wallace 0.4.0 → 0.5.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,18 +1,19 @@
 const NO_LOOKUP = "__";
 
 /**
- * The base component.
+ * The base component constructor.
  */
 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.ctrl = undefined;
+  this.props = undefined;
+  // Internal state objects (_e is created during build)
+  this._s = []; // A stash for misc objects like repeaters.
   this._p = {}; // The previous values for watches to compare against.
   this._r = {}; // The current values read during an update.
+  const root = this._n.cloneNode(true);
+  this.el = root;
+  this.ref = {};
+  this._b(this, root);
 }
 
 Component.stubs = {};
@@ -25,6 +26,9 @@ Object.defineProperty(proto, "hidden", {
   }
 });
 
+/**
+ * Gets a stub by name.
+ */
 proto._gs = function (name) {
   return this.constructor.stubs[name];
 };

package/lib/index.js

@@ -1,12 +1,10 @@
-import { mount, watch } from "./utils";
+import { mount, watch, protect } from "./utils";
 import { Component } from "./component";
 import { KeyedRepeater, SequentialRepeater } from "./repeaters";
 import {
   extendComponent,
   defineComponent,
   findElement,
-  getKeyedRepeater,
-  getSequentialRepeater,
   onEvent,
   nestComponent,
   saveRef,
@@ -18,12 +16,11 @@ export {
   defineComponent,
   extendComponent,
   findElement,
-  getKeyedRepeater,
-  getSequentialRepeater,
   KeyedRepeater,
   mount,
   nestComponent,
   onEvent,
+  protect,
   saveRef,
   SequentialRepeater,
   stashMisc,

package/lib/initCalls.js

@@ -2,8 +2,7 @@
  * 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";
+import { replaceNode } from "./utils";
 
 const throwAway = document.createElement("template");
 
@@ -37,9 +36,9 @@ export function findElement(rootElement, path) {
   return path.reduce((acc, index) => acc.childNodes[index], rootElement);
 }
 
-export function nestComponent(rootElement, path, cls) {
+export function nestComponent(rootElement, path, componentDefinition) {
   const el = findElement(rootElement, path),
-    child = buildComponent(cls);
+    child = new componentDefinition();
   replaceNode(el, child.el);
   return child;
 }
@@ -66,14 +65,6 @@ export function onEvent(element, 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;
@@ -86,23 +77,40 @@ export function defineComponent(html, watches, queries, buildFunction, inheritFr
   return ComponentDefinition;
 }
 
+/**
+ * Creates a new component definition.
+ *
+ * @param {*} base - a component definition to inherit from - defaults to Component.
+ * @returns the newly created component definition function.
+ */
 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, {
+  const proto = Object.create(base && base.prototype, {
     constructor: {
       value: ComponentDefinition,
       writable: true,
       configurable: true
     }
   });
-  ComponentDefinition.prototype.base = Component.prototype;
+  ComponentDefinition.prototype = proto;
+
+  // methods lets us assign to prototype without replacing it.
+  Object.defineProperty(ComponentDefinition, "methods", {
+    set: function (value) {
+      Object.assign(proto, value);
+    },
+    get: function () {
+      return proto;
+    }
+  });
+
+  // Set up stubs
+  ComponentDefinition.stubs = {};
+  Object.assign(ComponentDefinition.stubs, base.stubs);
+
+  // Helper to access base prototype.
+  proto.base = Component.prototype;
   return ComponentDefinition;
 }

package/lib/repeaters.js

@@ -1,5 +1,3 @@
-import { buildComponent } from "./utils";
-
 /*
  * Gets a component from the pool.
  */
@@ -8,7 +6,7 @@ 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);
@@ -136,7 +134,7 @@ SequentialRepeater.prototype.patch = function (e, items, ctrl) {
     if (i < poolCount) {
       component = pool[i];
     } else {
-      component = buildComponent(componentDefinition);
+      component = new componentDefinition();
       pool.push(component);
       poolCount++;
     }

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
 
@@ -71,7 +71,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 +100,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 +112,7 @@ MyComponent.methods({
   getName() {
     return 'wallace';
   }
-});
+};
 ```
 
 This has the same effect as setting them on the prototype:
@@ -124,11 +124,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.
@@ -201,11 +201,22 @@ Notes:
 
 ## 4. Directives
 
-Directives are attributes with special behaviours, as listed below. Each has more
+Directives are attributes with special behaviours. 
+
+You can see the list of available directives by hovering over any JSX element, like
+a `div`
+
+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`.
+
+You can define your own directives in your babel config.
+
+Each has more
 detailed information on its JSDoc, which should display as a tool tip\* when you hover
 over it in your IDE.
 
-You can also display this list by hovering over any JSX element, like `div`.
+You can also 
 
 - `apply` runs a callback to modify an element.
 - `bind` updates a value when an input is changed.
@@ -221,7 +232,6 @@ an array.
 - `style:xyz` sets a specific style property.
 - `toggle:xyz` toggles `xyz` as defined by `class:xyz` on same element, or class `xyz`.
 
-\* The tool tip won't display when you use a qualifier, like `class:danger`. 
 
 ## 5. Controllers
 
@@ -266,12 +276,12 @@ const TaskList = (_, {ctrl}) => (
   </div>
 );
 
-TaskList.methods({
+TaskList.methods = {
   render(_, ctrl) {
     this.ctrl = new TaskController(this, ctrl);
     this.update();
   }
-});
+};
 ```
 
 ## 6. Inheritance
@@ -392,12 +402,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 +455,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 +479,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:
+
+```
+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.
 
 ```
-watch(obj, () => console.log('obj modified);
+const protectedObj = protect([]);
+watchedObj[0] = 'foo';  // throws error.
 ```
+
 ---
 Report any issues to https://github.com/wallace-js/wallace (and please give it a ★)
 
@@ -495,9 +518,7 @@ declare module "wallace" {
         ctrl: Controller;
         self: ComponentInstance<Props, Controller, Methods>;
         event: Event;
-        ev: Event;
         element: HTMLElement;
-        el: HTMLElement;
       }
     ): JSX.Element;
     nest?({
@@ -518,10 +539,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.
@@ -643,8 +662,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 +688,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 +776,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 +795,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
@@ -876,13 +934,15 @@ 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.
@@ -892,9 +952,12 @@ declare namespace JSX {
      * - `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`.
+     * - `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

@@ -6,7 +6,7 @@
  * @param {object} props The props to pass to the component (optional)
  */
 export function mount(elementOrId, componentDefinition, props, ctrl) {
-  const component = buildComponent(componentDefinition);
+  const component = new componentDefinition();
   component.render(props, ctrl);
   replaceNode(getElement(elementOrId), component.el);
   return component;
@@ -22,52 +22,45 @@ export function getElement(elementOrId) {
     : elementOrId;
 }
 
+const MUTATING_METHODS = ["push", "pop", "shift", "unshift", "splice", "reverse", "sort"];
 /**
- * Builds a component's initial DOM.
- */
-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;
-}
-
-/**
- * See types for docs. Set grace to 0 for testing.
+ * 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, grace) {
-  let active = false;
-  if (grace === undefined) grace = 100;
+export function watch(target, callback) {
   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];
+      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;
-      if (grace) {
-        if (!active) {
-          setTimeout(() => {
-            active = false;
-          }, grace);
-          active = true;
-          callback();
-        }
-      } else {
-        callback();
-      }
+      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.5.0",
   "author": "Andrew Buchan",
   "description": "The framework that brings you FREEDOM!!",
   "license": "ISC",
@@ -13,8 +13,8 @@
     "test": "jest --clearCache && jest"
   },
   "dependencies": {
-    "babel-plugin-wallace": "^0.4.0",
+    "babel-plugin-wallace": "^0.5.0",
     "browserify": "^17.0.1"
   },
-  "gitHead": "286a00b51777c4b7fed9a778b93e9727ed905e2a"
+  "gitHead": "12194040c835faf9d4f29e105dd908bacdbbb944"
 }