wallace 0.8.0 → 0.11.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

@@ -115,10 +115,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 +137,22 @@ export function initConstructor(ComponentFunction, BaseComponentFunction) {
       }
     }
   ));
-  Object.defineProperty(ComponentFunction, "methods", {
-    set: function (value) {
-      Object.assign(proto, value);
-    },
-    get: function () {
-      return proto;
-    }
-  });
-  ComponentFunction.stubs = Object.assign({}, BaseComponentFunction.stubs);
+
+  if (wallaceConfig.flags.useMethods) {
+    Object.defineProperty(ComponentFunction, "methods", {
+      set: function (value) {
+        Object.assign(proto, value);
+      },
+      get: function () {
+        return proto;
+      }
+    });
+  }
+
+  if (wallaceConfig.flags.useStubs) {
+    ComponentFunction.stubs = Object.assign({}, BaseComponentFunction.stubs);
+  }
+
   return ComponentFunction;
 }
 

package/lib/repeaters/keyed.js

@@ -1,33 +1,3 @@
-import { trimChildren } from "../utils";
-
-/*
- * Gets a component from the pool.
- */
-function getComponent(pool, componentDefinition, ctrl, key, props) {
-  let component;
-  if (pool.hasOwnProperty(key)) {
-    component = pool[key];
-  } else {
-    component = new componentDefinition();
-    pool[key] = component;
-  }
-  component.render(props, ctrl);
-  return component;
-}
-
-/**
- * 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]);
-  }
-}
-
 /**
  * Repeats nested components, reusing items based on key.
  *
@@ -37,20 +7,9 @@ function pull(arr, item, to) {
 export function KeyedRepeater(componentDefinition, keyFn) {
   this.def = componentDefinition;
   this.keyFn = keyFn;
-  this.keys = []; // keys
-  this.pool = {}; // pool of component instances
+  this.keys = []; // array of keys as last set.
+  this.pool = {}; // pool of component instances.
 }
-const proto = KeyedRepeater.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.
- */
-proto.getOne = function (item, ctrl) {
-  return getComponent(this.pool, this.def, ctrl, this.keyFn(item), item);
-};
 
 /**
  * Updates the element's childNodes to match the items.
@@ -58,33 +17,63 @@ proto.getOne = function (item, ctrl) {
  *
  * @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.
  */
-proto.patch = function (e, items, ctrl) {
-  // 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.pool;
-  const componentDefinition = this.def;
-  const keyFn = this.keyFn;
-  const childNodes = e.childNodes;
-  const itemsLength = items.length;
-  const oldKeySequence = this.keys;
-  const newKeys = [];
+KeyedRepeater.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,
-    childElementCount = oldKeySequence.length + 1;
-  for (let i = 0; i < itemsLength; i++) {
+    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 = getComponent(pool, componentDefinition, ctrl, key, item);
-    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);
+    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--;
   }
-  this.keys = newKeys;
-  trimChildren(e, childNodes, itemsLength);
+
+  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

@@ -1,5 +1,3 @@
-import { trimChildren } from "../utils";
-
 /**
  * Repeats nested components, yielding from its pool sequentially.
  *
@@ -44,5 +42,9 @@ SequentialRepeater.prototype.patch = function (e, items, ctrl) {
     i++;
   }
   this.count = itemsLength;
-  trimChildren(e, childNodes, itemsLength);
+  let lastIndex = childNodes.length - 1;
+  let keepIndex = itemsLength - 1;
+  for (let i = lastIndex; i > keepIndex; i--) {
+    e.removeChild(childNodes[i]);
+  }
 };

package/lib/types.d.ts

@@ -8,17 +8,53 @@
 
 ### Contents
 
+  0. Configuration
   1. Components
   2. JSX
   3. Nesting
-  4. Directives
-  5. Controllers
-  6. Inheritance
-  7. Stubs
-  8. TypeScript
-  9. Helpers
+  4. Repeating
+  5. Directives
+  6. Controllers
+  7. Inheritance
+  8. Stubs
+  9. TypeScript
+ 10. Helpers
 
-For more detailed documentation go to https://github.com/wallace-js/wallace
+For more detailed documentation go to https://wallace.js.org/docs/
+
+
+## 0. Configuration
+
+You need to set flags in your babel config to use certain features:
+
+ 1. useControllers - enables use of `ctrl` in components.
+ 2. useMethods - adds the `methods` helper to components.
+ 3. useStubs - enables the use of stubs.
+
+The types (and therefore tool tips) are unaffected by these flags, and will treat them
+all as being true.
+
+```tsx
+module.exports = {
+  plugins: [
+    [
+      "babel-plugin-wallace",
+      {
+        flags: {
+          useControllers: true,
+          useMethods: true,
+          useStubs: true
+        },
+        directives: [...]
+      }
+    ],
+    "@babel/plugin-syntax-jsx"
+  ],
+  presets: ["@babel/preset-typescript", ...]
+};
+```
+
+The `directives` option lets you override or define new directives. See main docs.
 
 ## 1. Components
 
@@ -179,7 +215,7 @@ Other than that, its standard JSX, except for three special cases:
 
 ## 3. Nesting
 
-To nest or repeat components use its name followed by `.nest` or `.repeat`:
+To nest a component use its name followed by `.nest` and pass `props` if needed:
 
 ```tsx
 const Task = (task) => (<div></div>);
@@ -200,11 +236,46 @@ const TaskList = (tasks) => (
 
 Notes:
 
- - You cannot use nest or repeat on the root element.
+ - You cannot use nest on the root element.
+
+## 4. Repeating
+
+To repeat a component use its name followed by `.repeat` and pass `items`:
+
+```tsx
+const Task = (task) => (<div></div>);
+
+const TaskList = (tasks) => (
+  <div>
+    <Task.repeat items={tasks} />
+  </div>
+);
+```
+
+This form reuses components sequentially, which may cause issues with CSS animations
+and focus, in which case you should use a keyed repeater by passing `key` which can
+be a string or a function:
+
+```tsx
+const TaskList = (tasks) => (
+  <div>
+    <Task.repeat items={tasks} key="id"/>
+  </div>
+);
+
+const TaskList = (tasks) => (
+  <div>
+    <Task.repeat items={tasks} key={(x) => x.id}/>
+  </div>
+);
+```
+
+Notes:
+
+ - You cannot repeat on the root element.
  - Repeat must be the only child element under its parent.
- - The `props` expects an array on repeat (See **TypeScript** below) 
 
-## 4. Directives
+## 5. Directives
 
 Directives are attributes with special behaviours. 
 
@@ -217,7 +288,7 @@ temporarily change it to something `class x:danger`.
 
 You can define your own directives in your babel config.
 
-## 5. Controllers
+## 6. Controllers
 
 A controller is just an object you create which gets passed down to every nested
 component, making it a convenient place to handle:
@@ -268,7 +339,7 @@ TaskList.methods = {
 };
 ```
 
-## 6. Inheritance
+## 7. Inheritance
 
 You can creat new component defintion by extending another one, either preserving the
 base's structure, or overriding it:
@@ -284,7 +355,7 @@ const Child2 = extendComponent(Parent, ({name}) => <h3>{name}</h3>);
 
 Either way the new component definition inherits the parent *prototype* and *stubs*.
 
-## 7. Stubs
+## 8. Stubs
 
 Stubs are named placeholders for nested components which are requested in the JSX:
 
@@ -317,7 +388,7 @@ Notes:
  - Stubs are separate components, so cannot access methods on the containing component
    through `self` (use the controller for that kind of thing).
 
-## 8. TypeScript
+## 9. TypeScript
 
 The main type is `Uses` which must be placed right after the comonent name:
 
@@ -341,7 +412,7 @@ const Task: Uses<null> = () => <div>Hello</div>;
 
 ### Props
 
-TypeScript will ensure you pass correct props during mounting or nesting:
+TypeScript will ensure you pass correct props during mounting, nesting and repeating:
 
 ```
 const TaskList: Uses<iTask[]> = (tasks) => (
@@ -353,6 +424,8 @@ const TaskList: Uses<iTask[]> = (tasks) => (
     </div>
   </div>
 );
+
+mount("main", TaskList, [{test: 'foo'}]);
 ```
 
 ### Controller
@@ -439,7 +512,7 @@ Wallace defines some other types you may use:
     constructor, not a class)
  - `ComponentInstance<Props, Controller, Methods>` - a component instance.
 
-## 9. Helpers
+## 10. Helpers
 
 Each of these has their own JSDoc, we just lsit them here.
 
@@ -517,10 +590,12 @@ declare module "wallace" {
     }): JSX.Element;
     repeat?({
       items,
+      key,
       show,
       hide
     }: {
       items: Array<Props>;
+      key?: string | ((item: Props) => any);
       show?: boolean;
       hide?: boolean;
     }): JSX.Element;
@@ -880,6 +955,15 @@ interface DirectiveAttributes extends AllDomEvents {
    */
   items?: MustBeExpression;
 
+  /** ## Wallace directive: key
+   *
+   * Specifies a key for repeated components, creating an association between the key
+   * and the nested component.
+   *
+   * You can specify a property as a string or a function.
+   */
+  key?: any;
+
   /**
    * ## Wallace directive: part
    *
@@ -963,9 +1047,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 {
@@ -977,8 +1063,10 @@ declare namespace JSX {
      *   ```
      *   <MyComponent.nest props={singleProps} />
      *   <MyComponent.repeat items={arrayOfProps} />
+     *   <MyComponent.repeat items={arrayOfProps} key="id"/>
+     *   <MyComponent.repeat items={arrayOfProps} key={(i) => i.id}/>
      *   ```
-     * Note that repeated components must not have siblings.
+     * Note that repeated components may not have siblings.
      *
      * Available Wallace directives:
      *
@@ -990,6 +1078,7 @@ declare namespace JSX {
      * - `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
@@ -999,6 +1088,7 @@ declare namespace JSX {
      * - `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 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/lib/utils.js

@@ -6,21 +6,6 @@ export function replaceNode(nodeToReplace, newNode) {
   nodeToReplace.parentNode.replaceChild(newNode, nodeToReplace);
 }
 
-/**
- * Trims the unwanted child elements from the end.
- *
- * @param {Node} e
- * @param {Array} childNodes
- * @param {Int} itemsLength
- */
-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]);
-  }
-}
-
 /**
  * Stash something on the component. Returns the element.
  * The generated code is expected to keep track of the position.

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "wallace",
-  "version": "0.8.0",
+  "version": "0.11.0",
   "author": "Andrew Buchan",
-  "description": "The framework that brings you FREEDOM!!",
+  "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.8.0",
+    "babel-plugin-wallace": "^0.11.0",
     "browserify": "^17.0.1"
   },
-  "gitHead": "7e497347a84b4326da188f11b7a71c85cc70bf41"
+  "gitHead": "f145fe3b852025e2c851c27d75e7a104c5ec2bda"
 }