wallace 0.10.0 → 0.12.0

package/README.md

@@ -1,6 +1,6 @@
 # Wallace
 
-This package contains the library for the [Wallace](https://github.com/wallace-js/wallace) framework, which you import into your source files:
+This package contains the library for the [Wallace](https://wallace.js.org) framework, which you import into your source files:
 
 ```jsx
 import { mount } from 'wallace';
@@ -26,4 +26,4 @@ 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).
+For more detailed documentation see the [Wallace repository on github](https://wallace.js.org/docs/).

package/lib/component.js

@@ -2,22 +2,33 @@ const throwAway = document.createElement("template");
 const NO_LOOKUP = "__";
 
 const ComponentPrototype = {
-  /**
-   * The render function that gets called by parent components.
-   */
+  /*
+  COMPILER_MODS:
+    if useController is false:
+     - param `ctrl` is removed.
+     - `this.ctrl = ctrl` is removed.
+  */
   render: function (props, ctrl) {
     this.props = props;
     this.ctrl = ctrl;
     this.update();
   },
 
-  /**
-   * Updates the DOM and renders nested components.
-   */
+  /*
+  COMPILER_MODS:
+    if useFlags is false this is deleted.
+  */
   update: function () {
     this._u(0, this._l);
   },
 
+  /*
+  COMPILER_MODS:
+  if useFlags is false:
+    - gets renamed to `update`
+    - parameters are removed
+    - add `i = 0, il = this._l` to variable declarator.
+  */
   _u: function (i, il) {
     let watch,
       element,
@@ -115,10 +126,13 @@ Object.defineProperty(ComponentPrototype, "hidden", {
 });
 
 const ComponentBase = {
-  stubs: {},
   prototype: ComponentPrototype
 };
 
+if (wallaceConfig.flags.useStubs) {
+  ComponentBase.stubs = {};
+}
+
 /**
  *
  * @param {function} ComponentFunction - The Component definition function to add bits to.
@@ -134,15 +148,37 @@ export function initConstructor(ComponentFunction, BaseComponentFunction) {
       }
     }
   ));
-  Object.defineProperty(ComponentFunction, "methods", {
-    set: function (value) {
-      Object.assign(proto, value);
-    },
-    get: function () {
-      return proto;
+
+  if (wallaceConfig.flags.useMethods) {
+    Object.defineProperty(ComponentFunction, "methods", {
+      set: function (value) {
+        Object.assign(proto, value);
+      },
+      get: function () {
+        return proto;
+      }
+    });
+  } else {
+    if (process.env.NODE_ENV !== "production") {
+      Object.defineProperty(ComponentFunction, "name", {
+        set: function (value) {
+          throw new Error(
+            'Flag "useMethods" must be set to true in the config for this feature.'
+          );
+        },
+        get: function () {
+          throw new Error(
+            'Flag "useMethods" must be set to true in the config for this feature.'
+          );
+        }
+      });
     }
-  });
-  ComponentFunction.stubs = Object.assign({}, BaseComponentFunction.stubs);
+  }
+
+  if (wallaceConfig.flags.useStubs) {
+    ComponentFunction.stubs = Object.assign({}, BaseComponentFunction.stubs);
+  }
+
   return ComponentFunction;
 }
 
@@ -153,6 +189,24 @@ export function defineComponent(html, watches, queries, contructor, inheritFrom)
   proto._w = watches;
   proto._q = queries;
   proto._t = throwAway.content.firstChild;
-  proto.base = ComponentPrototype;
+  if (wallaceConfig.flags.useBase) {
+    proto.base = ComponentPrototype;
+  } else {
+    if (process.env.NODE_ENV !== "production") {
+      Object.defineProperty(proto, "base", {
+        set: function (value) {
+          throw new Error(
+            'Flag "useBase" must be set to true in the config for this feature.'
+          );
+        },
+        get: function () {
+          throw new Error(
+            'Flag "useBase" must be set to true in the config for this feature.'
+          );
+        }
+      });
+    }
+  }
+
   return ComponentDefinition;
 }

package/lib/index.js

@@ -6,6 +6,7 @@ export { nestComponent } from "./nestComponent";
 export { saveRef } from "./refs";
 export { savePart } from "./part";
 export { KeyedRepeater } from "./repeaters/keyed";
+export { KeyedFnRepeater } from "./repeaters/keyedFn";
 export { SequentialRepeater } from "./repeaters/sequential";
 export { Router, route } from "./router";
 export { getStub } from "./stubs";

package/lib/repeaters/keyed.js

@@ -1,12 +1,14 @@
+// WARNING: Code here is near duplicated in keyedFn.
+
 /**
  * Repeats nested components, reusing items based on key.
  *
  * @param {function} componentDefinition - The ComponentDefinition to create.
- * @param {function} keyFn - A function which obtains the key.
+ * @param {string} keyName - The name of the key property.
  */
-export function KeyedRepeater(componentDefinition, keyFn) {
+export function KeyedRepeater(componentDefinition, keyName) {
   this.def = componentDefinition;
-  this.keyFn = keyFn;
+  this.keyName = keyName;
   this.keys = []; // array of keys as last set.
   this.pool = {}; // pool of component instances.
 }
@@ -22,7 +24,7 @@ export function KeyedRepeater(componentDefinition, keyFn) {
 KeyedRepeater.prototype.patch = function (e, items, ctrl) {
   const pool = this.pool,
     componentDefinition = this.def,
-    keyFn = this.keyFn,
+    keyName = this.keyName,
     childNodes = e.childNodes,
     itemsLength = items.length,
     previousKeys = this.keys,
@@ -44,7 +46,7 @@ KeyedRepeater.prototype.patch = function (e, items, ctrl) {
   const frag = document.createDocumentFragment();
   while (i >= 0) {
     item = items[i];
-    key = keyFn(item);
+    key = item[keyName];
     component = pool[key] || (pool[key] = new componentDefinition());
     component.render(item, ctrl);
     el = component.el;

package/lib/repeaters/keyedFn.js

@@ -0,0 +1,81 @@
+// WARNING: Code here is near duplicated in keyedFn.
+
+/**
+ * Repeats nested components, reusing items based on key.
+ *
+ * @param {function} componentDefinition - The ComponentDefinition to create.
+ * @param {function} keyFn - A function which obtains the key.
+ */
+export function KeyedFnRepeater(componentDefinition, keyFn) {
+  this.def = componentDefinition;
+  this.keyFn = keyFn;
+  this.keys = []; // array of keys as last set.
+  this.pool = {}; // pool of component instances.
+}
+
+/**
+ * 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.
+ */
+KeyedFnRepeater.prototype.patch = function (e, items, ctrl) {
+  const pool = this.pool,
+    componentDefinition = this.def,
+    keyFn = this.keyFn,
+    childNodes = e.childNodes,
+    itemsLength = items.length,
+    previousKeys = this.keys,
+    previousKeysLength = previousKeys.length,
+    newKeys = [],
+    previousKeysSet = new Set(previousKeys);
+  let item,
+    el,
+    key,
+    component,
+    anchor = null,
+    fragAnchor = null,
+    untouched = true,
+    append = false,
+    offset = previousKeysLength - itemsLength,
+    i = itemsLength - 1;
+
+  // Working backwards saves us having to track moves.
+  const frag = document.createDocumentFragment();
+  while (i >= 0) {
+    item = items[i];
+    key = keyFn(item);
+    component = pool[key] || (pool[key] = new componentDefinition());
+    component.render(item, ctrl);
+    el = component.el;
+    if (untouched && !previousKeysSet.has(key)) {
+      frag.insertBefore(el, fragAnchor);
+      fragAnchor = el;
+      append = true;
+      offset++;
+    } else {
+      if (key !== previousKeys[i + offset]) {
+        e.insertBefore(el, anchor);
+        untouched = false;
+      }
+      anchor = el;
+    }
+    newKeys.push(key);
+    previousKeysSet.delete(key);
+    i--;
+  }
+
+  if (append) {
+    e.appendChild(frag);
+  }
+
+  let toStrip = previousKeysSet.size;
+  while (toStrip > 0) {
+    e.removeChild(childNodes[0]);
+    toStrip--;
+  }
+
+  this.keys = newKeys.reverse();
+};

package/lib/repeaters/sequential.js

@@ -43,7 +43,7 @@ SequentialRepeater.prototype.patch = function (e, items, ctrl) {
   }
   this.count = itemsLength;
   let lastIndex = childNodes.length - 1;
-  let keepIndex = itemsLength - 1;
+  const keepIndex = itemsLength - 1;
   for (let i = lastIndex; i > keepIndex; i--) {
     e.removeChild(childNodes[i]);
   }

package/lib/types.d.ts

@@ -18,8 +18,10 @@
   8. Stubs
   9. TypeScript
  10. Helpers
+ 11. Flags
+
+For more detailed documentation go to https://wallace.js.org/docs/
 
-For more detailed documentation go to https://github.com/wallace-js/wallace
 
 ## 1. Components
 
@@ -519,6 +521,42 @@ const protectedObj = protect([]);
 watchedObj[0] = 'foo';  // throws error.
 ```
 
+## 11. Flags
+
+You can toggle flags in your babel config to disable certain features for cutting edge
+performance and bundle size:
+
+1.  useBase - enables use of `base` in components.
+2.  useControllers - enables use of `ctrl` in components.
+3.  useMethods - adds the `methods` helper to components.
+4.  useParts - enables use of parts.
+5.  useStubs - enables the use of stubs.
+
+These flags default to true, unless you specify `flags` in the plugin config, in which
+case they default to false and you need to explicitly enable those you want:
+
+
+```tsx
+module.exports = {
+  plugins: [
+    [
+      "babel-plugin-wallace",
+      {
+        flags: {
+          useControllers: true,
+          useStubs: false
+        },
+      }
+    ],
+    "@babel/plugin-syntax-jsx"
+  ],
+  presets: ["@babel/preset-typescript", ...]
+};
+```
+
+The types (and therefore tool tips) are unaffected by these flags, and will treat them
+all as being true.
+
 ---
 Report any issues to https://github.com/wallace-js/wallace (and please give it a ★)
 
@@ -550,19 +588,18 @@ declare module "wallace" {
       hide
     }: {
       props?: Props;
+      ctrl?: Controller;
       show?: boolean;
       hide?: boolean;
     }): JSX.Element;
     repeat?({
       items,
-      key,
-      show,
-      hide
+      ctrl,
+      key
     }: {
       items: Array<Props>;
+      ctrl?: Controller;
       key?: string | ((item: Props) => any);
-      show?: boolean;
-      hide?: boolean;
     }): JSX.Element;
     methods?: ComponenMethods<Props, Controller> &
       ThisType<ComponentInstance<Props, Controller, Methods>>;
@@ -716,7 +753,7 @@ declare module "wallace" {
   type WatchCallback = (target: any, key: string, value: any) => void;
 
   /**
-   * Returns a Proxy of an object which calls `callback` when it, or its nested objects
+   * Returns a Proxy of the target which calls `callback` when it, or its nested objects
    * are modified:
    *
    * ```js
@@ -729,6 +766,9 @@ declare module "wallace" {
    * obj.y = {}
    * obj.y.z = 1000
    * ```
+   *
+   * The original object is also modified.
+   *
    * The callback accepts parameters:
    *
    *  - `target` - the object which is being modified.
@@ -737,10 +777,6 @@ declare module "wallace" {
    *
    * 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 {*} callback - A callback function.
    * @returns a Proxy of the object.
@@ -876,6 +912,17 @@ interface DirectiveAttributes extends AllDomEvents {
    */
   css?: string;
 
+  /**
+   * ## Wallace directive: ctrl
+   *
+   * Specifies ctrl for nested/repeated components.
+   *
+   * ```
+   * <MyComponent.nest ctrl={aController} />
+   * ```
+   */
+  ctrl?: any;
+
   /**
    * ## Wallace directive: fixed
    *
@@ -1012,9 +1059,11 @@ interface DirectiveAttributes extends AllDomEvents {
   toggle?: string;
 
   /**
-   * Foo
+   * ## Wallace directive: unique
+   *
+   * Performance optimisation that can be applied to a component which is only used once.
    */
-  "class-a"?: string;
+  unique?: boolean;
 }
 
 declare namespace JSX {
@@ -1037,20 +1086,22 @@ declare namespace JSX {
      * - `bind` updates a value when an input is changed.
      * - `class:xyz` defines a set of classes to be toggled.
      * - `css` shorthand for `fixed:class`.
+     * - `ctrl` specifies ctrl for nested/repeated components.
      * - `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.
      * - `key` specifies a key for repeated items.
      * - `items` set items for repeated component, must be an array of props.
-     * - `on[EventName]` creates an event handler (note the code is copied)
-     * - `part:xyz` saves a reference to part of a component so it can be updated
-     * - `props` specifes props for a nested components.
-     * - `ref:xyz` saves a reference to an element or nested omponent.
+     * - `on[EventName]` creates an event handler (note the code is copied).
+     * - `part:xyz` saves a reference to part of a component so it can be updated.
+     * - `props` specifies props for a nested components.
+     * - `ref:xyz` 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`.
+     * - `unique` can be set on components which are only used once for better performance.
      *
      * 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

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "wallace",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "author": "Andrew Buchan",
   "description": "An insanely small, fast, intuitive and extendable front-end framework",
+  "homepage": "https://wallace.js.org",
   "license": "ISC",
   "main": "lib/index.js",
   "files": [
@@ -14,8 +15,8 @@
     "test": "jest --clearCache && jest"
   },
   "dependencies": {
-    "babel-plugin-wallace": "^0.10.0",
+    "babel-plugin-wallace": "^0.12.0",
     "browserify": "^17.0.1"
   },
-  "gitHead": "5516e673ca0e4c0a01644701b914ca923e000580"
+  "gitHead": "bbaf61dd2313ba947efc3f35580626ca6f71fc84"
 }