Typed reactive values
This reference documents every current public declaration in this part of Pine. Examples run inside App.Mount(), a component factory, or an explicit UI.Root(...) unless they only create state/configuration. Explicit UI.Mount(...) remains available for advanced ownership. Variable names such as count, items and label refer to the typed values described by each example. All APIs run on Unity’s main thread.
Value
Value<T>
A typed literal-or-getter adapter for mutable UI inputs. A literal is applied once; a getter is evaluated in an owned reactive effect and tracks the sources it reads. Source, ReadOnly, Derived and Spring convert implicitly. Structural native types and identity keys are declared separately.
| Type parameter | Meaning |
|---|---|
T | Typed value, native result or identity contract; see the summary for its role. |
var width = UI.Source(value: 240f);
Value<UnityEngine.Vector2> size = new(() =>
new UnityEngine.Vector2(x: width.Value, y: 48)
);
UI.Frame(UI.Size(size: size));
public Value(T literal)
Constructs this value with the supplied typed arguments. A typed literal-or-getter adapter for mutable UI inputs. A literal is applied once; a getter is evaluated in an owned reactive effect and tracks the sources it reads. Source, ReadOnly, Derived and Spring convert implicitly. Structural native types and identity keys are declared separately.
| Parameter | Meaning |
|---|---|
literal | The typed literal input (T); literals and supported reactive adapters follow this overload's documented behavior. |
var width = UI.Source(value: 240f);
Value<UnityEngine.Vector2> size = new(() =>
new UnityEngine.Vector2(x: width.Value, y: 48)
);
UI.Frame(UI.Size(size: size));
public Value(Func<T> read)
Constructs this value with the supplied typed arguments. A typed literal-or-getter adapter for mutable UI inputs. A literal is applied once; a getter is evaluated in an owned reactive effect and tracks the sources it reads. Source, ReadOnly, Derived and Spring convert implicitly. Structural native types and identity keys are declared separately.
| Parameter | Meaning |
|---|---|
read | The getter whose source reads establish reactive dependencies; supply a stable native result where required. |
var width = UI.Source(value: 240f);
Value<UnityEngine.Vector2> size = new(() =>
new UnityEngine.Vector2(x: width.Value, y: 48)
);
UI.Frame(UI.Size(size: size));
Value.IsDynamic
bool IsDynamic
Reports whether this adapter wraps a getter. Sources, derived values, springs and read-only values convert to dynamic adapters.
bool reactive = value.IsDynamic;
Value.Read
public T Read()
Returns the literal or invokes its getter with normal dependency tracking.
Returns: The literal or getter result; getter reads participate in the active observer’s dependency tracking.
var current = value.Read();
Value.implicit
public static implicit operator Value<T>(T value)
Converts a typed literal, getter or supported reactive value into a literal-or-getter adapter. Conversions preserve the value type and reactive dependency reads.
| Parameter | Meaning |
|---|---|
value | The typed value or reactive input to read/apply; sources remain observable for the owning lifetime. |
Returns: A typed Value adapter that reads this reactive value when evaluated; the conversion does not write to its source.
Value<int> value = UI.Source(value: 0);
public static implicit operator Value<T>(Func<T> getter)
Converts a typed literal, getter or supported reactive value into a literal-or-getter adapter. Conversions preserve the value type and reactive dependency reads.
| Parameter | Meaning |
|---|---|
getter | The typed getter to evaluate with normal dependency tracking. |
Returns: A typed Value adapter that reads this reactive value when evaluated; the conversion does not write to its source.
Value<int> value = UI.Source(value: 0);
public static implicit operator Value<T>(Source<T> source)
Converts a typed literal, getter or supported reactive value into a literal-or-getter adapter. Conversions preserve the value type and reactive dependency reads.
| Parameter | Meaning |
|---|---|
source | The source, derived, spring or read-only value to observe through this adapter. This conversion preserves reads and does not grant write access. |
Returns: A typed Value adapter that reads this reactive value when evaluated; the conversion does not write to its source.
Value<int> value = UI.Source(value: 0);
public static implicit operator Value<T>(ReadOnly<T> source)
Converts a typed literal, getter or supported reactive value into a literal-or-getter adapter. Conversions preserve the value type and reactive dependency reads.
| Parameter | Meaning |
|---|---|
source | The source, derived, spring or read-only value to observe through this adapter. This conversion preserves reads and does not grant write access. |
Returns: A typed Value adapter that reads this reactive value when evaluated; the conversion does not write to its source.
Value<int> value = UI.Source(value: 0);
public static implicit operator Value<T>(Derived<T> source)
Converts a typed literal, getter or supported reactive value into a literal-or-getter adapter. Conversions preserve the value type and reactive dependency reads.
| Parameter | Meaning |
|---|---|
source | The source, derived, spring or read-only value to observe through this adapter. This conversion preserves reads and does not grant write access. |
Returns: A typed Value adapter that reads this reactive value when evaluated; the conversion does not write to its source.
Value<int> value = UI.Source(value: 0);
public static implicit operator Value<T>(Spring<T> source)
Converts a typed literal, getter or supported reactive value into a literal-or-getter adapter. Conversions preserve the value type and reactive dependency reads.
| Parameter | Meaning |
|---|---|
source | The source, derived, spring or read-only value to observe through this adapter. This conversion preserves reads and does not grant write access. |
Returns: A typed Value adapter that reads this reactive value when evaluated; the conversion does not write to its source.
Value<int> value = UI.Source(value: 0);
ReadOnly
ReadOnly<T>
A framework-owned reactive value that callers can observe without replacing it. Dynamic operators expose their output, row values, indices and presence through this type. Value tracks dependency reads; Peek reads without tracking. Change the source collection or selection to update these values.
| Type parameter | Meaning |
|---|---|
T | Typed value, native result or identity contract; see the summary for its role. |
var rows = UI.Values(
read: () => new[] { "A" },
build: (value, index) => UI.Label(text: () => $"{index.Value}: {value}")
);
UI.Column(UI.Children(read: () => rows.Value));
ReadOnly.Value
T Value
Reads the framework-owned value with dependency tracking. There is no public setter; update the controlling collection or selector instead.
UI.Label(text: () => index.Value.ToString());
ReadOnly.Peek
public T Peek()
Reads the framework-owned snapshot without collecting a dependency.
Returns: The current value without registering a dependency on this read.
int snapshot = index.Peek();
Source
Source<T>
Mutable typed reactive state. Reading Value inside an observer registers a dependency; assigning Value notifies observers under the configured equality policy. Sources can be stored on an owner outside any UI lifetime. Equal values and strings are suppressed by default, while mutable reference assignments notify unless a comparer changes that behavior.
| Type parameter | Meaning |
|---|---|
T | Typed value, native result or identity contract; see the summary for its role. |
var count = UI.Source(value: 0);
UI.Label(text: () => count.Value.ToString());
count.Value++;
Source.Value
T Value
Reads with dependency tracking and writes with notifications under the source equality policy. Writes from a derived calculation are rejected.
count.Value++;
Source.Peek
public T Peek()
Returns a source snapshot without collecting a dependency. Use Value when a reactive binding should follow changes.
Returns: The current value without registering a dependency on this read.
int snapshot = count.Peek();
Source.Set
public T Set(T value)
Assigns the typed source value and returns the value supplied. The same equality and notification policy as the Value setter applies.
| Parameter | Meaning |
|---|---|
value | The typed value or reactive input to read/apply; sources remain observable for the owning lifetime. |
Returns: The assigned value, after synchronously notifying observers outside a batch.
int next = count.Set(10);
Source.Notify
public void Notify()
Explicitly notifies observers after mutating a referenced value in place. It increments the source revision and settles tracked observers synchronously outside a batch.
items.Peek().Add("New");
items.Notify();
Derived
Derived<T>
An owned cached pure calculation with dynamically tracked dependencies. Reading Value tracks downstream consumers; equal outputs suppress their reruns. Create in a stable ownership scope and keep the calculation free of source writes. Disposal releases dependencies and is idempotent.
| Type parameter | Meaning |
|---|---|
T | Typed value, native result or identity contract; see the summary for its role. |
var count = UI.Source(value: 2);
var doubled = UI.Derive(compute: () => count.Value * 2);
UI.Label(text: () => doubled.Value.ToString());
Derived.Value
T Value
Returns the current cached pure result and tracks downstream reads. Within a batch it first settles stale upstream derived calculations.
UI.Label(text: () => total.Value.ToString());
Derived.Dispose
public void Dispose()
Ends this owned lifetime idempotently. Dependencies and native event/clock registrations are released; Scope/Mount cleanup attempts all resources and aggregates failures. Explicit owners may dispose their mount early; automatic applications end when their root is destroyed.
total.Dispose();