wallace 0.3.0 → 0.4.0

package/lib/initCalls.js

@@ -1,16 +1,38 @@
+/**
+ * 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");
 
 /**
- * Create an element from html string.
+ * 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.
  */
-function makeEl(html) {
-  throwAway.innerHTML = html;
-  return throwAway.content.firstChild;
+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);
 }
@@ -52,22 +74,15 @@ export function getSequentialRepeater(cls) {
   return new SequentialRepeater(cls);
 }
 
-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);
-}
-
 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 = makeEl(html);
+  prototype._n = throwAway.content.firstChild;
   return ComponentDefinition;
 }
 
@@ -88,5 +103,6 @@ function _createConstructor(base) {
       configurable: true
     }
   });
+  ComponentDefinition.prototype.base = Component.prototype;
   return ComponentDefinition;
 }

package/lib/types.d.ts

@@ -98,7 +98,10 @@ render(props, ctrl) {
 Updates the DOM. Only called internally by `render`, but you can call it from other
 places.
 
-You can override these methods, and add new ones:
+#### Overriding
+
+You can override these methods, and add new ones using `methods` directly on the
+component definition:
 
 ```tsx
 MyComponent.methods({
@@ -118,7 +121,21 @@ This has the same effect as setting them on the prototype:
 MyComponent.prototype.render = function () {};
 ```
 
-You access the instance as `this` in methods, but `self` in the JSX.
+You can use `this.base` to access methods on the base `Component` class:
+
+```tsx
+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.
+
+You access the instance as `this` in methods, but cannot use `this` in arrow functions,
+so use `self` from the **xargs** in component functions.
+
 
 ### 1.4 Fields
 
@@ -171,7 +188,7 @@ const TopTasks = (tasks) => (
 
 const TaskList = (tasks) => (
   <div>
-    <Task.repeat props={tasks} />
+    <Task.repeat items={tasks} />
   </div>
 );
 ```
@@ -245,7 +262,7 @@ const Task = (task) => (<div>{task.name}</div>);
 
 const TaskList = (_, {ctrl}) => (
   <div>
-    <Task.repeat props={ctrl.getTasks()} />
+    <Task.repeat items={ctrl.getTasks()} />
   </div>
 );
 
@@ -330,8 +347,7 @@ const Task: Uses<null> = () => <div>Hello</div>;
 
 ### Props
 
-TypeScript will ensure you pass correct props during mounting or nesting,
-including repeat, which expects an arry of the type:
+TypeScript will ensure you pass correct props during mounting or nesting:
 
 ```
 const TaskList: Uses<iTask[]> = (tasks) => (
@@ -339,7 +355,7 @@ const TaskList: Uses<iTask[]> = (tasks) => (
     First task:
     <Task.nest props={tasks[0]} />
     <div>
-      <Task.repeat props={tasks.slice(1)} />
+      <Task.repeat items={tasks.slice(1)} />
     </div>
   </div>
 );
@@ -475,10 +491,13 @@ declare module "wallace" {
   > {
     (
       props: Props,
-      other?: {
+      xargs?: {
         ctrl: Controller;
         self: ComponentInstance<Props, Controller, Methods>;
         event: Event;
+        ev: Event;
+        element: HTMLElement;
+        el: HTMLElement;
       }
     ): JSX.Element;
     nest?({
@@ -491,11 +510,11 @@ declare module "wallace" {
       hide?: boolean;
     }): JSX.Element;
     repeat?({
-      props,
+      items,
       show,
       hide
     }: {
-      props: Array<Props>;
+      items: Array<Props>;
       show?: boolean;
       hide?: boolean;
     }): JSX.Element;
@@ -516,7 +535,7 @@ declare module "wallace" {
   };
 
   /**
-   * A type which ust be placed as shown:
+   * A type which must be placed as shown:
    *
    * ```tsx
    * const Task: Uses<iTask> = ({text}) => <div>{text}</div>;
@@ -544,19 +563,53 @@ declare module "wallace" {
     Controller = any,
     Methods extends object = {}
   > = {
-    update(): void;
-    render(props: Props, ctrl?: Controller): void;
     el: HTMLElement;
     props: Props;
     ctrl: Controller;
-  } & Methods;
+    ref: { [key: string]: HTMLElement };
+    base: Component<Props, Controller>;
+  } & Component<Props, Controller> &
+    Methods;
 
   /**
    * The component constructor function (typed as a class, but isn't).
    */
   export class Component<Props = any, Controller = any> {
-    update(): void;
     render(props: Props, ctrl?: Controller): void;
+    /**
+     * The base render method looks like this:
+     *
+     * ```
+     * render(props?: Props, ctrl?: Controller) {
+     *   this.props = props;
+     *   this.ctrl = ctrl;
+     *   this.update();
+     * }
+     * ```
+     *
+     * You can override like so:
+     *
+     * ```
+     * render(props?: Props, ctrl?: Controller) {
+     *   // do your thing
+     *   this.base.render.call(this, props, ctrl);
+     * }
+     * ```
+     */
+    render(props?: Props, ctrl?: Controller): void;
+    /**
+     * Updates the DOM.
+     *
+     * You can override like so:
+     *
+     * ```
+     * update() {
+     *   // do your thing
+     *   this.base.update.call(this);
+     * }
+     * ```
+     */
+    update(): void;
   }
 
   /**
@@ -725,17 +778,28 @@ interface DirectiveAttributes extends AllDomEvents {
    */
   html?: MustBeExpression;
 
-  /** Wallace excludes this element from the DOM if the condition is false,
-   * and does not render dynamic elements underneath. */
+  /** ## Wallace directive: if
+   *
+   * Excludes this element from the DOM completely if the condition is false,
+   * and does not render dynamic elements underneath.
+   * When the condition becomes true, the element is reattached.
+   */
   if?: MustBeExpression;
 
+  /**
+   * ## Wallace directive: items
+   *
+   * Specifies items for repeated component. Must be an array of the props which the
+   * nested item accepts.
+   *
+   */
+  items?: MustBeExpression;
+
   /**
    * ## Wallace directive: props
    *
-   * Specifies props for a nested or repeated component.
+   * Specifies props for a nested component.
    *
-   * If it is a repeated component, the props should be an array of whatever type it
-   * accepts.
    */
   props?: MustBeExpression;
 
@@ -810,7 +874,7 @@ declare namespace JSX {
      * Nesting syntax:
      *   ```
      *   <MyComponent.nest props={singleProps} />
-     *   <MyComponent.repeat props={arrayOfProps} />
+     *   <MyComponent.repeat items={arrayOfProps} />
      *   ```
      * But note that repeat must not have siblings.
      *
@@ -822,9 +886,9 @@ 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.
+     * - `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 or repeated component, in which case it must be
-     * an array.
+     * - `props` specifes props for a nested components.
      * - `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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wallace",
-  "version": "0.3.0",
+  "version": "0.4.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.3.0",
+    "babel-plugin-wallace": "^0.4.0",
     "browserify": "^17.0.1"
   },
-  "gitHead": "d5f2ea2912b6ec729775d2ccf17973a9e791115f"
+  "gitHead": "286a00b51777c4b7fed9a778b93e9727ed905e2a"
 }