Module binding 

Ergonomic binding utilities for connecting Observable values to UI state.

A Binding<T> encapsulates an observable source plus an optional transform, making it easy to derive display values from reactive state. The [bind!] and [bind_map!] macros provide syntactic sugar.

Usage

use ftui_runtime::reactive::{Observable, Binding, bind, bind_map};

let count = Observable::new(0);

// Direct binding — get() returns the observable's value.
let b = bind!(count);
assert_eq!(b.get(), 0);

// Mapped binding — get() returns the transformed value.
let label = bind_map!(count, |c| format!("Count: {c}"));
assert_eq!(label.get(), "Count: 0");

count.set(5);
assert_eq!(b.get(), 5);
assert_eq!(label.get(), "Count: 5");

Two-Way Bindings

TwoWayBinding<T> connects two Observables so changes to either propagate to the other, with cycle prevention.

let source = Observable::new(42);
let target = Observable::new(0);
let _binding = TwoWayBinding::new(&source, &target);

source.set(10);
assert_eq!(target.get(), 10);

target.set(20);
assert_eq!(source.get(), 20);

Invariants

1. Binding::get() always returns the current (not stale) value.
2. A binding’s transform is applied on every get() call (no caching). Use Computed when memoization is needed.
3. TwoWayBinding prevents infinite cycles via a re-entrancy guard.
4. Dropping a TwoWayBinding cleanly unsubscribes both directions.
5. Bindings are Clone when the source Observable is (shared state).

Failure Modes

• Transform panic: propagates to caller of get().
• Source dropped while binding alive: binding still works (Rc keeps inner alive).

Structs

Binding

A read-only binding to an Observable value with an optional transform.

BindingScope

Collects subscriptions and bindings for a logical scope (e.g., a widget).

TwoWayBinding

Bidirectional binding between two Observables of the same type.

Functions

bind_mapped

Create a mapped binding: source value transformed by map.

bind_mapped2

Create a binding from two observables combined by map.

bind_observable

Create a direct binding to an observable (identity transform).