Tesserae - Binding

Binding

Description

Bind(observable) wires a component to a SettableObservable<T> in both directions: user input flows into the observable, and changes to the observable update the component. The observable is the single source of truth, so several components bound to it stay in sync without further wiring.

Binding works on any component that implements IBindableComponent<T>, including TextBox, TextArea, CheckBox, Toggle, Slider, NumberPicker, Rating, Stepper, Pagination, Carousel, Expander, Pivot, ChoiceGroup, StepsSlider<T>, IconToggle<T>, DateRangePicker, Modal, Panel and Drawer. For a list-shaped component such as TagsInput, bind a SettableObservable<IReadOnlyList<T>>.

Usage

The component is seeded from the observable's Value when Bind is called. Any earlier SetValue, SetText or IsChecked on the component is overwritten.

The binding lives as long as the component and the observable. To release it earlier, pass a SubscriptionScope as the second argument and dispose the scope.

A bound Modal, Panel or Drawer shows while the observable is true. Closing it by the X, Escape or light dismiss sets the observable back to false.

Two components, one observable

binding-sample.cs

using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;
using Transpose.Core;
using Tesserae;
using static Transpose.Core.dom;
using static Tesserae.UI;

namespace Tesserae.Tests
{
    internal static class App
    {
        private static void Main()
        {
            var name    = SettableObservable.Of("Ada");
            var enabled = SettableObservable.Of(true);

            var component = Stack().W(320).Children(
                TextBox().Bind(name),
                TextBox().Bind(name),
                DeferSync(name, n => TextBlock("Hello, " + n + "!").SemiBold()),
                HStack().Children(
                    Button("Set to Grace").OnClick(() => name.Value = "Grace"),
                    Button("Clear").OnClick(() => name.Value = "")
                ),
                HStack().AlignItemsCenter().Children(
                    Toggle().Bind(enabled),
                    CheckBox("Enabled").Bind(enabled),
                    DeferSync(enabled, e => TextBlock(e ? "ON" : "OFF").SemiBold().ML(8))
                )
            );

            document.body.style.overflow = "hidden";
            MountCenteredToBody(component);
        }
    }
}

Typing in either text box updates the other and the read-out. The buttons set the observable directly, and both text boxes follow.

binding-modal-sample.cs

using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;
using Transpose.Core;
using Tesserae;
using static Transpose.Core.dom;
using static Tesserae.UI;

namespace Tesserae.Tests
{
    internal static class App
    {
        private static void Main()
        {
            var modalOpen = SettableObservable.Of(false);

            var modal = Modal("Bound modal")
               .Content(TextBlock("Closing this modal sets the observable back to false."))
               .LightDismiss()
               .Bind(modalOpen);

            var component = HStack().AlignItemsCenter().Children(
                Button("Open modal").OnClick(() => modalOpen.Value = true),
                DeferSync(modalOpen, o => TextBlock(o ? "modal: open" : "modal: closed").SemiBold().ML(8))
            );

            document.body.style.overflow = "hidden";
            MountCenteredToBody(component);
        }
    }
}

Signatures

Method	Description
`Bind<TComponent, T>(this TComponent component, SettableObservable<T> source)`	Two-way binding for an `IBindableComponent<T>`. Returns the component.
`Bind<TComponent, T>(..., SettableObservable<T> source, SubscriptionScope scope)`	The same, with both subscriptions registered in `scope`.
`Bind<TComponent, T>(this TComponent component, SettableObservable<IReadOnlyList<T>> source)`	Two-way binding for a list-shaped component.
`Bind<TComponent, T>(..., SettableObservable<IReadOnlyList<T>> source, SubscriptionScope scope)`	The same, with a `SubscriptionScope`.

API reference

class

BindingExtensions

public static class BindingExtensions

Provides two-way binding between a component implementing IBindableComponent{T} and a SettableObservable{T}.

Namespace: Tesserae

Methods

Name Description

Bind Wires the component to a single source of truth: user input flows into source, and programmatic changes to source are reflected in the component. The component is seeded from source.Value at call time — any prior SetValue/SetText/IsChecked configuration on the component is overwritten. The binding lives for the lifetime of component and source; use the SubscriptionScope overload if you need to tear it down earlier.

Name	Description
Bind	Wires the component to a single source of truth: user input flows into `source`, and programmatic changes to `source` are reflected in the component. The component is seeded from `source`.Value at call time — any prior SetValue/SetText/IsChecked configuration on the component is overwritten. The binding lives for the lifetime of `component` and `source`; use the `SubscriptionScope` overload if you need to tear it down earlier.

Method

BindingExtensions.Bind

Overload
Bind<TComponent, T>(TComponent, SettableObservable<T>)	Wires the component to a single source of truth: user input flows into `source`, and programmatic changes to `source` are reflected in the component. The component is seeded from `source`.Value at call time — any prior SetValue/SetText/IsChecked configuration on the component is overwritten. The binding lives for the lifetime of `component` and `source`; use the `SubscriptionScope` overload if you need to tear it down earlier.
Bind<TComponent, T>(TComponent, SettableObservable<T>, SubscriptionScope)	Two-way binding overload that registers both subscriptions with `scope`; disposing the scope releases the binding.
Bind<TComponent, T>(TComponent, SettableObservable<IReadOnlyList<T>>)	List-shaped two-way binding: wires a component implementing `IBindableListComponent{T}` to a `SettableObservable<IReadOnlyList<T>>`. User edits flow into `source`, and programmatic changes to `source` replace the component's items. The component is seeded from `source`.Value at call time.
Bind<TComponent, T>(TComponent, SettableObservable<IReadOnlyList<T>>, SubscriptionScope)	List-shaped two-way binding overload that registers both subscriptions with `scope`; disposing the scope releases the binding.

Bind<TComponent, T>(TComponent, SettableObservable<T>)

public static TComponent Bind<TComponent, T>(this TComponent component, SettableObservable<T> source) where TComponent : IBindableComponent<T>

Wires the component to a single source of truth: user input flows into source, and programmatic changes to source are reflected in the component. The component is seeded from source.Value at call time — any prior SetValue/SetText/IsChecked configuration on the component is overwritten. The binding lives for the lifetime of component and source; use the SubscriptionScope overload if you need to tear it down earlier.

Parameters

component TComponent
source SettableObservable<T>

Bind<TComponent, T>(TComponent, SettableObservable<T>, SubscriptionScope)

public static TComponent Bind<TComponent, T>(this TComponent component, SettableObservable<T> source, SubscriptionScope scope) where TComponent : IBindableComponent<T>

Two-way binding overload that registers both subscriptions with scope; disposing the scope releases the binding.

Parameters

component TComponent
source SettableObservable<T>
scope SubscriptionScope

Bind<TComponent, T>(TComponent, SettableObservable<IReadOnlyList<T>>)

public static TComponent Bind<TComponent, T>(this TComponent component, SettableObservable<IReadOnlyList<T>> source) where TComponent : IBindableListComponent<T>

List-shaped two-way binding: wires a component implementing IBindableListComponent{T} to a SettableObservable<IReadOnlyList<T>>. User edits flow into source, and programmatic changes to source replace the component's items. The component is seeded from source.Value at call time.

Parameters

component TComponent
source SettableObservable<IReadOnlyList<T>>

Bind<TComponent, T>(TComponent, SettableObservable<IReadOnlyList<T>>, SubscriptionScope)

public static TComponent Bind<TComponent, T>(this TComponent component, SettableObservable<IReadOnlyList<T>> source, SubscriptionScope scope) where TComponent : IBindableListComponent<T>

List-shaped two-way binding overload that registers both subscriptions with scope; disposing the scope releases the binding.

Parameters

component TComponent
source SettableObservable<IReadOnlyList<T>>
scope SubscriptionScope

interface

IObservableComponent<T>

public interface IObservableComponent<T>

Defines a component that exposes its value as an observable.

Type Parameters

T: The type of the value.

Namespace: Tesserae

Methods

Name	Description
AsObservable	Gets an observable that tracks the component's value.

Method

IObservableComponent.AsObservable

IObservable<T> AsObservable()

Gets an observable that tracks the component's value.

Returns

An observable.

interface

IObservableListComponent<T>

public interface IObservableListComponent<T>

Defines a component that exposes its list of values as an observable.

Type Parameters

T: The type of the items in the list.

Namespace: Tesserae

Methods

Name	Description
AsObservable	Gets an observable that tracks the component's list of values.

Method

IObservableListComponent.AsObservable

IObservable<IReadOnlyList<T>> AsObservable()

Gets an observable that tracks the component's list of values.

Returns

An observable.

interface

IBindableComponent<T>

public interface IBindableComponent<T> : IObservableComponent<T>

Defines a component whose value can both be observed and programmatically set, enabling two-way binding against a SettableObservable<T> via the .Bind extension.

Type Parameters

T: The type of the value.

Namespace: Tesserae
Implements: IObservableComponent<T>

Methods

Name	Description
SetBoundValue	Sets the component's value as the result of a binding push from a source observable. Implementations must update the visual/DOM state and the internal observable, but must not raise a user-interaction event that would echo back to the bound source.

Method

IBindableComponent.SetBoundValue

void SetBoundValue(T value)

Sets the component's value as the result of a binding push from a source observable. Implementations must update the visual/DOM state and the internal observable, but must not raise a user-interaction event that would echo back to the bound source.

interface

IBindableListComponent<T>

public interface IBindableListComponent<T> : IObservableListComponent<T>

Defines a list-shaped component whose value can both be observed and programmatically replaced, enabling two-way binding against a SettableObservable<IReadOnlyList<T>> via the .Bind extension.

Type Parameters

T: The type of the items in the list.

Namespace: Tesserae
Implements: IObservableListComponent<T>

Methods

Name	Description
SetBoundValues	Replaces the component's items as the result of a binding push from a source observable. Implementations must update the visual/DOM state and the internal observable, but must not raise a user-interaction event that would echo back to the bound source.

Method

IBindableListComponent.SetBoundValues

void SetBoundValues(IReadOnlyList<T> values)

Replaces the component's items as the result of a binding push from a source observable. Implementations must update the visual/DOM state and the internal observable, but must not raise a user-interaction event that would echo back to the bound source.

Binding

Description

Usage

Two components, one observable

A bound modal

Signatures

API reference

Methods

BindingExtensions.Bind

Bind<TComponent, T>(TComponent, SettableObservable<T>)

Parameters

Bind<TComponent, T>(TComponent, SettableObservable<T>, SubscriptionScope)

Parameters

Bind<TComponent, T>(TComponent, SettableObservable<IReadOnlyList<T>>)

Parameters

Bind<TComponent, T>(TComponent, SettableObservable<IReadOnlyList<T>>, SubscriptionScope)

Parameters

Methods

IObservableComponent.AsObservable

Returns

Methods

IObservableListComponent.AsObservable

Returns

Methods

IBindableComponent.SetBoundValue

Methods

IBindableListComponent.SetBoundValues

See also