Observables

Description

The observable helpers in Tesserae provide lightweight state containers that can notify components when values change. They are useful for UI state, reactive rendering, and collections that need to trigger updates when their contents change.

This page covers the most commonly used observable types:

• SettableObservable<T> for mutable single values
• ConstantObservable<T> for immutable values that should still satisfy an observable contract
• ObservableList<T> for observable ordered collections
• ObservableDictionary<TKey, TValue> for observable keyed collections

Usage

Use SettableObservable<T> when your code owns a value and needs to update it over time. Use ConstantObservable<T> when a consumer expects an IObservable<T> but the value never changes. Use ObservableList<T> and ObservableDictionary<TKey, TValue> when you need collection mutations to trigger UI updates.

using System;
using System.Collections.Generic;
using H5.Core;
using Tesserae;
using static H5.Core.dom;
using static Tesserae.UI;

namespace Tesserae.Tests
{
    internal static class App
    {
        private static void Main()
        {
            var sampleComponent = new ObservablesExample();
            document.body.style.overflow = "hidden";
            MountCenteredToBody(sampleComponent);
        }
    }

    public class ObservablesExample : IComponent
    {
        public HTMLElement Render()
        {
            var status = SettableObservable.For("Idle");
            var items = new ObservableList<string>("Alpha", "Beta");
            var lookup = new ObservableDictionary<string, string>(new Dictionary<string, string>
            {
                ["A"] = "Alpha",
                ["B"] = "Beta"
            });
            var fixedValue = new ConstantObservable<string>("Always available");

            var output = TextBlock();
            status.Observe(value => output.Text($"Status: {value}"));

            var addButton = Button("Add item").OnClick(() =>
            {
                items.Add($"Item {items.Count + 1}");
                status.Value = $"{items.Count} items";
            });

            var updateButton = Button("Update map").OnClick(() =>
            {
                lookup["C"] = "Gamma";
                status.Value = $"Dictionary size: {lookup.Count}";
            });

            return Stack().Children(
                output,
                TextBlock($"Constant: {fixedValue.Value}"),
                addButton,
                updateButton
            ).Render();
        }
    }
}

SettableObservable

SettableObservable<T> is the mutable observable for single values. It derives from ReadOnlyObservable<T>, exposes a writable Value property, and supports an Update(Action<T>) helper for mutating reference types while still raising change notifications.

Key members:

• SettableObservable.For<T>(value, comparer) creates a typed observable with inference.
• Value gets or sets the current value.
• Update(Action<T>) mutates the current value and forces a notification.
• Observe(...), ObserveFutureChanges(...), and StopObserving(...) come from the underlying observable implementation.

ConstantObservable

ConstantObservable<T> wraps a fixed value in an IObservable<T> implementation. It immediately invokes Observe(...) with the stored value but never emits future changes.

Key members:

• Value gets the current value.
• Observe(...) invokes the callback immediately.
• ObserveFutureChanges(...) is a no-op.
• StopObserving(...) is a no-op.

ObservableList

ObservableList<T> implements IList<T>, ICollection<T>, and IObservable<IReadOnlyList<T>>. It raises change events when items are added, removed, inserted, replaced, or cleared.

Key members:

• Delay controls the debounce delay before notifications are emitted.
• Value returns the current list as IReadOnlyList<T>.
• Add(...), AddRange(...), Insert(...), Update(...), Remove(...), RemoveAt(...), RemoveAll(...), and Clear() mutate the list.
• ReplaceAll(...) swaps the entire contents in one operation.

If T is itself observable, ObservableList<T> can hook nested observables and propagate future changes automatically.

ObservableDictionary<TKey, TValue>

ObservableDictionary<TKey, TValue> implements IDictionary<TKey, TValue> and IObservable<IReadOnlyDictionary<TKey, TValue>>. It is useful for lookup state, keyed caches, and dynamic maps that should refresh dependent UI.

Key members:

• Value returns the current dictionary as IReadOnlyDictionary<TKey, TValue>.
• Add(...), AddRange(...), indexer assignment, Remove(...), and Clear() mutate the dictionary.
• Observe(...), ObserveFutureChanges(...), and StopObserving(...) subscribe or unsubscribe listeners.

Like ObservableList<T>, it can optionally hook nested observable values and emit updates when those inner values change.

See also

• ObservableStack
• Defer
• Validator