wallace 0.2.0 → 0.3.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/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
 
@@ -189,9 +190,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
@@ -305,7 +308,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';
@@ -418,6 +421,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 ★)
 
@@ -514,7 +554,7 @@ declare module "wallace" {
   /**
    * The component constructor function (typed as a class, but isn't).
    */
-  export class Component__<Props = any, Controller = any> {
+  export class Component<Props = any, Controller = any> {
     update(): void;
     render(props: Props, ctrl?: Controller): void;
   }
@@ -566,15 +606,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 +625,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**.
+   *
+   * Note that you can use `element` from **xargs** multiple times and each will refer
+   * to the element where it is used.
    *
-   * Specifies a base component definition to inherit from.
+   * ```
+   * 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,6 +719,12 @@ interface DirectiveAttributes extends AllDomEvents {
    */
   hide?: MustBeExpression;
 
+  /** ## Wallace directive: html
+   *
+   * Set the element's `innnerHTML` property.
+   */
+  html?: MustBeExpression;
+
   /** Wallace excludes this element from the DOM if the condition is false,
    * and does not render dynamic elements underneath. */
   if?: MustBeExpression;
@@ -750,11 +807,20 @@ declare namespace JSX {
 
   interface IntrinsicElements {
     /**
+     * Nesting syntax:
+     *   ```
+     *   <MyComponent.nest props={singleProps} />
+     *   <MyComponent.repeat props={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.
      * - `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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wallace",
-  "version": "0.2.0",
+  "version": "0.3.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.3.0",
     "browserify": "^17.0.1"
   },
-  "gitHead": "fb51a4f90bd819a79515196b0fd57d36fa7d6477"
+  "gitHead": "d5f2ea2912b6ec729775d2ccf17973a9e791115f"
 }