wallace 0.2.0 → 0.4.0

package/lib/component.js

@@ -1,4 +1,4 @@
-const ALWAYS_UPDATE = "__";
+const NO_LOOKUP = "__";
 
 /**
  * The base component.
@@ -52,7 +52,7 @@ proto._rq = function (props, key) {
 proto._ac = function (props, element, callbacks) {
   for (let key in callbacks) {
     let callback = callbacks[key];
-    if (key === ALWAYS_UPDATE) {
+    if (key === NO_LOOKUP) {
       callback(element, props, this);
     } else {
       const result = this._rq(props, key);

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

@@ -16,6 +16,7 @@
   6. Inheritance
   7. Stubs
   8. TypeScript
+  9. Utility functions
 
 For more detailed documentation go to https://github.com/wallace-js/wallace
 
@@ -97,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({
@@ -117,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
 
@@ -170,7 +188,7 @@ const TopTasks = (tasks) => (
 
 const TaskList = (tasks) => (
   <div>
-    <Task.repeat props={tasks} />
+    <Task.repeat items={tasks} />
   </div>
 );
 ```
@@ -189,9 +207,11 @@ over it in your IDE.
 
 You can also display this list by hovering over any JSX element, like `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 and element or component's hidden property.
+- `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
@@ -242,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>
 );
 
@@ -305,7 +325,7 @@ Notes:
 
 ## 8. TypeScript
 
-All typing comes from the `Uses` type which must be placed right after the comonent name:
+The main type is `Uses` which must be placed right after the comonent name:
 
 ```tsx
 import { Uses } from 'wallace';
@@ -327,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) => (
@@ -336,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>
 );
@@ -418,6 +437,43 @@ const Child = extendComponent<newProps, Controller, Methods>(Parent);
    to `any`.
 2. Each type must extend its corresponding type on base.
 
+### Other types:
+
+Wallace defines some other types you may use:
+
+ - `Component<Props, Controller, Methods>` - the base component class (it is a 
+    constructor, not a class)
+ - `ComponentInstance<Props, Controller, Methods>` - a component instance.
+
+## Utility functions
+
+Each of these has their own JSDoc, we just lsit them here.
+
+
+### extendComponent
+
+Define a new componend by extending another one:
+
+```
+const Foo = extendComponent(Base);
+const Bar = extendComponent(Base, () => <div></div>);
+```
+
+### mount
+
+Mounts an instance of a component to the DOM:
+
+```
+mount("elementId", MyComponent, props, ctrl);
+```
+
+### watch
+
+Returns a Proxy of an object which calls `callback` when keys are set:
+
+```
+watch(obj, () => console.log('obj modified);
+```
 ---
 Report any issues to https://github.com/wallace-js/wallace (and please give it a ★)
 
@@ -435,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?({
@@ -451,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;
@@ -476,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>;
@@ -504,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;
+  export class Component<Props = any, Controller = any> {
     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;
   }
 
   /**
@@ -566,15 +659,15 @@ declare module "wallace" {
    * The callback does not indicate the data has changed, only that a key was set.
    *
    * Some methods like `Array.push` set the index and then the length immediately after,
-   * so we use a grace period to avoid calling the callback twice for what is really a
+   * 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 {*} grace - Any value in ms. Defaults to 100.
+   * @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, grace?: number): T;
+  export function watch<T>(target: T, callback: CallableFunction, timeout?: number): T;
 }
 
 type MustBeExpression = Exclude<any, string>;
@@ -585,14 +678,25 @@ type MustBeExpression = Exclude<any, string>;
  */
 interface DirectiveAttributes extends AllDomEvents {
   /**
-   * ## Wallace directive: base
+   * ## Wallace directive: apply
+   *
+   * Applies a callback, typically to modify its element, which is accessible via
+   * **xargs**.
    *
-   * Specifies a base component definition to inherit from.
+   * Note that you can use `element` from **xargs** multiple times and each will refer
+   * to the element where it is used.
+   *
+   * ```
+   * const MyComponent = (_, { element }) => (
+   *   <div>
+   *     <div apply={doSomething(element)}></div>
+   *     <div apply={doSomethingElse(element)}></div>
+   *   </div>
+   * );
+   * ```
    *
-   * This allows you to inherit methods and override stubs.
-   * Must be an expression returning a component definition.
    */
-  base?: MustBeExpression;
+  apply?: MustBeExpression;
 
   /**
    * ## Wallace directive: bind
@@ -668,17 +772,34 @@ interface DirectiveAttributes extends AllDomEvents {
    */
   hide?: MustBeExpression;
 
-  /** Wallace excludes this element from the DOM if the condition is false,
-   * and does not render dynamic elements underneath. */
+  /** ## Wallace directive: html
+   *
+   * Set the element's `innnerHTML` property.
+   */
+  html?: MustBeExpression;
+
+  /** ## 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;
 
@@ -750,15 +871,24 @@ declare namespace JSX {
 
   interface IntrinsicElements {
     /**
+     * Nesting syntax:
+     *   ```
+     *   <MyComponent.nest props={singleProps} />
+     *   <MyComponent.repeat items={arrayOfProps} />
+     *   ```
+     * But note that repeat 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.
-     * - `hide` sets and element or component's hidden property.
+     * - `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.2.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.2.0",
+    "babel-plugin-wallace": "^0.4.0",
     "browserify": "^17.0.1"
   },
-  "gitHead": "fb51a4f90bd819a79515196b0fd57d36fa7d6477"
+  "gitHead": "286a00b51777c4b7fed9a778b93e9727ed905e2a"
 }