Support two-way binding on non-widget objects

This allows @Bind({all: bindings]) to establish multiple two-way
bindings between the object assigned to the decorated property and the
component children. @Bindall is a shorthand for this syntax since
overloading @Bind to take the bindings directly would be ambiguous.

The implementation of this feature is (and has to be) fundamentally
different from the way @Bind(path) works, has the latter is really just
a re-direct. However, the perceived behavior is the same.

Add one example "bind-two-way-model" and extend the example
"bind-two-way-change-events", both linked in the documentation.

The "utils" module was getting too lengthy according to ts-lint rules
and was split in to "utils" and "utils-databinding". Module
"bind-one-way" was split in to "processOneWayBindings" and
"applyJsxBindings" to make it more similar to the modules implementing
the two-way binding.

Author: tbuschto

doc/databinding/@bind.md

@@ -4,34 +4,117 @@
 
 > :point_right: Make sure to first read the [introduction to data binding](./index.md).
 
-This decorator creates two-way bindings within a custom component. Changes to the decorated *component property* are reflected on the *target property* of a *target element* (child) and the other way around.
+This decorator creates two-way bindings within a custom component. Changes to the decorated *component property* value are reflected on the *target property* of a *target element* (child) and the other way around.
 
 `@bind` can by applied to any property of a class decorated with [`@component`](./@component.md). It also implies [`@property`](./@property.md) and includes its [typeGuard](./@property.md) feature. Only one of the two can be applied to the same property.
 
-`@bind` requires exactly one parameter:
+`@bind` has several signatures:
 
-## @bind(options)
+## @bind({path: string, typeGuard?: Function})
+
+Where `path` has the format `'#<targetElementId>.<targetProperty>'`.
+
+Binds the decorated *component property* to the property `<targetProperty>` of the *target element* (descendant widget) with an `id` of `<targetElementId>`. Example:
 
-Where `options` is of the type
 ```ts
-{
-  path: "#<targetElementId>.<targetProperty>",
-  typeGuard?: Function
-}
+@bind({path: '#source.selection'})
+public myNumber: number = 50;
 ```
 
-> See example app ["bind-two-way"](../../examples/bind-two-way).
+This establishes a two-way binding from the `myNumber` property to the property `selection` of the child with the id `'source'`. The binding is established after `append` is called the first time on the component, there needs to be exactly one descendant widget with the given id, and it has to have a property of the same type.
 
-Binds the decorated *component property* to the property `<targetProperty>` of the *target element* (descendant widget) with an `id` of `<targetElementId>`. The binding is established after `append` is called the first time on the component, there needs to be exactly one descendant widget with the given id, and it has to have a property of the same type.
+> See example app ["bind-two-way"](../../examples/bind-two-way).
 
-Change events are fired for the decorated *component property* if (and only if) the *target element* fires change events.
+Change events are fired for the decorated *component property* when the *target element* fires change events.
 
 > See example app ["bind-two-way-change-events"](../../examples/bind-two-way-change-events).
 
-A [`typeGuard`](./@property.md#propertytypeguard). may be given to perform value checks.
+A [`typeGuard`](./@property.md#propertytypeguard) may be given to perform value checks.
 
-As with one-way bindings, setting the *component property* to `undefined` resets the *target property* to its initial value.
+As with one-way bindings, setting the *component property* to `undefined` resets the *target property* to its initial value for when the binding was first established.
 
 ## @bind(path)
 
-Shorthand for `@bind({path: path})`
+Shorthand for `@bind({path: path})`.
+
+Example:
+
+```ts
+@bind('#source.selection')
+public myNumber: number = 50;
+```
+
+## @bind({all: Bindings, typeGuard?: Function})
+
+Where `Bindings` is in the format of:
+```
+{
+  <sourceProperty>: '#<targetElementId>.<targetProperty>'
+}
+```
+Establish a two-way binding between the property `<sourceProperty>` of the *object assigned to the decorated property* and the property `<targetProperty>` of the *target element* (descendant widget) with an `id` of `<targetElementId>`. Multiple bindings may be established this way. Example:
+
+```ts
+@bind({all:{
+  myText: '#input1.text',
+  myNumber: '#input2.selection'
+}})
+public model: Model;
+```
+
+This establishes 2 two-way bindings:
+* One between the `myText` property of the assigned `Model` object and the property `text` of the child with the id `input1`.
+* And one between the `myNumber` property of the assigned `Model` object and the property `selection` of the child with the id `input2`.
+
+> See example app ["bind-two-way-model"](../../examples/bind-two-way-model).
+
+The bindings are first established when `append` is called the first time on the component. Again, the bindings are established after `append` is called the first time on the component, there needs to be exactly one descendant widget with the given id for each binding, and they have to have a property of the same type as the source property.
+
+The `model` property can be set at any time and the bindings will update accordingly. However, the target elements will always stay the same.
+
+See also [`@bindAll`](./@bindAll.md).
+
+### Properties eligible for bindings
+
+Both source and target property need to generate change events for the two-way binding to work. The quickest way to implement this is using [`@property`](./@property.md), which can be used on non-widget classes as well:
+
+```ts
+class Model {
+  @property public myText: string;
+  @property public myNumber: number;
+}
+```
+
+Note that there is no need to explicitly create an event API, `@bind` can 'talk' directly to `@property`. However, an explicit implementation is also possible:
+
+```ts
+class Model {
+
+  @event public onMyTextChanged: ChangeListeners<Model, 'myText'>;
+  private _myText: string;
+
+  public set myText(value: string) {
+    if (this._myText !== value) {
+      this._myText = value;
+      this.onMyTextChanged.trigger({value});
+    }
+  }
+
+  public get myText() {
+    return this._myText;
+  }
+
+}
+```
+
+### Edge Cases
+
+The component property (`model` in the above example) may also be set to `null` (or `undefined`) at any time. In that case all the target properties will be set back to their initial values. The initial value in this case refers to the value a target property had the moment the target element was attached to the component.
+
+When a new two-way binding is established all the target properties will be set to the current value of the their respective source property. There is one exception to this behavior: If the source property is set to `undefined` (but not `null`) at that moment it will be assigned the current value of the target property. If a source property is set to `undefined` later both properties are set to the initial value of the target property.
+
+If a source property converts or ignores the incoming value of the target property, the target property will follow and change again to contain the new source property value.
+
+If a target property converts or ignores the incoming value of a source property, the source property will ignore that and keep its own value. The two properties are out-of-sync in this case.
+
+If either property throws, the error will be propagated to the caller that originally caused the value change. In this case the two properties *may* end up out-of-sync.

doc/databinding/@bindAll.md

@@ -0,0 +1,9 @@
+---
+---
+# @bindAll
+
+> :point_right: Make sure to first read the [introduction to data binding](./index.md).
+
+## @bindAll(bindings)
+
+This decorators is simply a shorthand for [`@bind({all: bindings})`](./@bind.md). It can be used for object-to-widget two-way bindings if no `typeGuard` parameter is needed.

doc/di/@shared.md

@@ -1,6 +1,6 @@
 ---
 ---
-## @shared
+# @shared
 
 > :point_right: Make sure to first read the [introduction to dependency injection](./index.md) and the [`@inject`](./@inject.md) documentation.
 

examples/bind-two-way-change-events/src/ExampleComponent.tsx

@@ -1,14 +1,19 @@
 import { ChangeListeners, Composite, Properties, Slider, Stack, TextInput, TextView } from 'tabris';
-import { bind, component, event } from 'tabris-decorators';
+import { bind, bindAll, component, event, property } from 'tabris-decorators';
+
+export class Model {
+  @event public onMyTextChanged: ChangeListeners<Model, 'myText'>;
+  @property public myText: string;
+}
 
 @component
 export class ExampleComponent extends Composite {
 
-  @bind('#source1.selection') public myNumber: number = 50;
+  @bind('#source1.selection') public myNumber: number;
   @event public onMyNumberChanged: ChangeListeners<ExampleComponent, 'myNumber'>;
 
-  @bind('#source2.text') public myText: string = 'Hello World!';
-  @event public onMyTextChanged: ChangeListeners<ExampleComponent, 'myText'>;
+  @bindAll({myText: '#source2.text'})
+  public model: Model;
 
   constructor(properties: Properties<ExampleComponent>) {
     super();
@@ -19,7 +24,7 @@ export class ExampleComponent extends Composite {
         <TextView>Source of "myNumber":</TextView>
         <Slider id='source1' width={200}/>
 
-        <TextView>Source of "myText":</TextView>
+        <TextView>Source of "model.myText":</TextView>
         <TextInput id='source2' width={200}/>
 
       </Stack>

examples/bind-two-way-change-events/src/app.tsx

@@ -1,21 +1,24 @@
 import { contentView, ProgressBar, PropertyChangedEvent, Stack, TextView } from 'tabris';
-import { ExampleComponent } from './ExampleComponent';
+import { ExampleComponent, Model } from './ExampleComponent';
+
+const model = new Model();
 
 contentView.append(
   <Stack layoutData='stretch' alignment='stretchX' padding={12} spacing={12}>
-    <ExampleComponent background='silver'
-        onMyNumberChanged={updateProgressBar}
-        onMyTextChanged={updateTextView}/>
+    <ExampleComponent background='silver' model={model}
+        onMyNumberChanged={updateProgressBar}/>
     <TextView font='18px'>Current values:</TextView>
     <ProgressBar width={200}/>
     <TextView font='18px'/>
   </Stack>
 );
 
+model.onMyTextChanged(updateTextView);
+
 function updateProgressBar(ev: PropertyChangedEvent<ExampleComponent, number>) {
   $(ProgressBar).only().selection = ev.value;
 }
 
-function updateTextView(ev: PropertyChangedEvent<ExampleComponent, string>) {
+function updateTextView(ev: PropertyChangedEvent<Model, string>) {
   $(TextView).last().text = ev.value;
 }

examples/bind-two-way-model/README.md

@@ -0,0 +1,9 @@
+# Example "bind-one-way"
+
+Demonstrates the use of the `bind` JSX attribute prefix to create one-way bindings from a custom component instance to its children. This app creates an instance of the included `ExampleComponent` class and a checkbox that allows to change the property values of that instance.
+
+The `ExampleComponent` property `myText` is bound to the `text` properties of multiple `TextView` children. The first two variants have the same effect, just using different syntax. The third variant demonstrates how to define a fallback value. It will be displayed when the property `myText` is set to `undefined`, which is the case when the checkbox is not checked.
+
+The other property `myObject` is of the type `Model`, which is defined in the same file as `ExampleComponent`. In the component the `Model` field `someString` is bound to the `TextView` property `text` and `someNumber` to the `ProgressBar` property `selection` properties, once with and without a fallback value.
+
+One-way bindings require the `@component` decorator on the custom component class and the `@property` decorator on the component properties.

examples/bind-two-way-model/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "bind-one-way",
+  "version": "3.1.0",
+  "dependencies": {
+    "reflect-metadata": "^0.1.13",
+    "tabris": "^3.0.0",
+    "tabris-decorators": "^3.0.0",
+    "typescript": "3.3.x"
+  },
+  "main": "dist/app.js",
+  "scripts": {
+    "start": "tabris serve -w -a",
+    "build": "tsc -p .",
+    "watch": "tsc -p . -w --preserveWatchOutput --inlineSourceMap"
+  }
+}

examples/bind-two-way-model/src/ExampleComponent.tsx

@@ -0,0 +1,35 @@
+import { Composite, Properties, Slider, Stack, TextInput, TextView } from 'tabris';
+import { bindAll, component, property } from 'tabris-decorators';
+
+export class Model {
+  @property public myText: string;
+  @property public myNumber: number;
+}
+
+@component
+export class ExampleComponent extends Composite {
+
+  @bindAll({
+    myText: '#input1.text',
+    myNumber: '#input2.selection'
+  })
+  public model: Model;
+
+  constructor(properties: Properties<ExampleComponent>) {
+    super();
+    this.set(properties);
+    this.append(
+      <Stack spacing={12} padding={12} >
+
+        <TextView>Bound to "myText"</TextView>
+        <TextInput id='input1' width={200} text='Fallback Text'/>
+
+        <TextView>Bound to "myNumber"</TextView>
+        <Slider id='input2' width={200}/>
+
+      </Stack>
+    );
+    this._find(TextView).set({font: {size: 18}});
+  }
+
+}

examples/bind-two-way-model/src/Model.ts

@@ -0,0 +1,34 @@
+import { CheckBox, CheckBoxSelectEvent, Color, contentView, Stack, Button, TextView } from 'tabris';
+import { ExampleComponent, Model } from './ExampleComponent';
+
+const model = new Model();
+resetValues();
+
+contentView.append(
+  <Stack stretch alignment='stretchX' padding={12} spacing={12}>
+    <CheckBox font={{size: 24}} onSelect={toggleModelAttached}>
+      Attach Model
+    </CheckBox>
+    <Button onSelect={resetValues}>
+      Reset Model Values
+    </Button>
+    <Button onSelect={printValues}>
+      Print Model Values
+    </Button>
+    <ExampleComponent background={Color.silver}/>
+    <TextView/>
+  </Stack>
+);
+
+function toggleModelAttached({checked}: CheckBoxSelectEvent) {
+  $(ExampleComponent).only().model = checked ? model : null;
+}
+
+function resetValues() {
+  model.myText = 'Initial Model Text';
+  model.myNumber = 50;
+}
+
+function printValues() {
+  $(TextView).only().text = model.myText + '/' + model.myNumber;
+}