Scroll<T> class

Scroll — A form field with validation, dirty tracking, and reset.

A Scroll is a Core (reactive mutable value) enhanced with form capabilities: validation, error tracking, dirty/pristine state, and reset to initial value.

Why "Scroll"?

A scroll holds ancient text — structured, validated, readable. Form fields are the modern equivalent: structured input that must be validated before it can be trusted.

Usage

class ProfilePillar extends Pillar {
  late final name = scroll('', validator: (v) =>
    v.isEmpty ? 'Name is required' : null,
  );

  late final email = scroll('', validator: (v) =>
    v.contains('@') ? null : 'Invalid email',
  );

  bool get isFormValid => name.isValid && email.isValid;
  bool get isFormDirty => name.isDirty || email.isDirty;

  void submit() {
    name.validate();
    email.validate();
    if (!isFormValid) return;
    // Process form...
  }
}

Inheritance

Available extensions

Constructors

Scroll(T initialValue, {String? validator(T value)?, Future<String?> asyncValidator(T value)?, String? name, bool equals(T previous, T next)?}): Creates a form field with an initial value and optional validator.

Properties

conduits → List<Conduit<T>>: The list of currently attached Conduits (read-only view).
no setterinherited
dependentCount → int: The number of active dependents.
no setterinherited
error → String?: The current validation error, or null if valid.
no setter
hashCode → int: The hash code for this object.
no setterinherited
initialValue → T: The initial value this field was created with.
no setter
isDirty → bool: Whether the current value differs from the initial value.
no setter
isDisposed → bool: Whether this node has been disposed.
no setterinherited
isPristine → bool: Whether the current value equals the initial value.
no setter
isTouched → bool: Whether this field has been touched.
no setter
isValid → bool: Whether the field has no validation error.
no setter
isValidating → bool: Whether an async validation is currently in progress.
no setter
listenerCount → int: The number of active listeners.
no setterinherited
managedNodes → List<ReactiveNode>: Returns all managed reactive nodes (for disposal by Pillar).
no setter
name → String?: The debug name of this state, if provided.
no setterinherited
onChange → Stream<void>: Available on ReactiveNode, provided by the FluxNodeExtensions extension
Converts this node to a stream that emits on every change.
no setter
previousValue → T?: The previous value before the most recent change.
no setterinherited
runtimeType → Type: A representation of the runtime type of the object.
no setterinherited
stream → Stream<T>: Available on TitanState<T>, provided by the FluxStateExtensions extension
Convenience getter for asStream().
no setter
value ↔ T: The current value.
getter/setter pairinherited

Methods

add(T item) → void: Available on TitanState<List<T>>, provided by the CoreListExtensions extension
Appends an item to the list (immutable update).
addAll(Iterable<T> items) → void: Available on TitanState<List<T>>, provided by the CoreListExtensions extension
Appends all items to the list (immutable update).
addConduit(Conduit<T> conduit) → void: Adds a Conduit to this Core's pipeline.
inherited
addListener(ReactiveListener listener) → void: Adds an imperative listener that is called when this node changes.
inherited
asStream() → Stream<T>: Available on TitanState<T>, provided by the FluxStateExtensions extension
Converts this Core to a Stream that emits on every value change.
clear() → void: Available on TitanState<Map<K, V>>, provided by the CoreMapExtensions extension
Clears all entries.
clear() → void: Available on TitanState<List<T>>, provided by the CoreListExtensions extension
Clears all items.
clearConduits() → void: Removes all Conduits from this Core.
inherited
clearError() → void: Clear the error without re-validating.
debounce(Duration duration, {String? name}) → DebouncedState<T>: Available on TitanState<T>, provided by the FluxStateExtensions extension
Creates a debounced version of this Core.
decrement([int amount = 1]) → void: Available on TitanState<int>, provided by the CoreIntExtensions extension
Decrements the value by amount (default: 1).
decrement([double amount = 1.0]) → void: Available on TitanState<double>, provided by the CoreDoubleExtensions extension
Decrements the value by amount (default: 1.0).
dispose() → void: Disposes this node, clearing all dependents and listeners.
override
increment([int amount = 1]) → void: Available on TitanState<int>, provided by the CoreIntExtensions extension
Increments the value by amount (default: 1).
increment([double amount = 1.0]) → void: Available on TitanState<double>, provided by the CoreDoubleExtensions extension
Increments the value by amount (default: 1.0).
insert(int index, T item) → void: Available on TitanState<List<T>>, provided by the CoreListExtensions extension
Inserts an item at index (immutable update).
listen(void callback(T value)) → void Function(): Listens for value changes with a typed callback.
inherited
map<R>(R transform(T value)) → TitanComputed<R>: Available on TitanState<T>, provided by the FluxStateExtensions extension
Maps this Core's value through a transformation into a Derived.
noSuchMethod(Invocation invocation) → dynamic: Invoked when a nonexistent method or property is accessed.
inherited
notifyDependents() → void: Notifies all dependents and listeners that this node changed.
inherited
onDependencyChanged(ReactiveNode dependency) → void: Called when a dependency of this node has changed.
inherited
onTracked(ReactiveNode source) → void: Called when this node is registered as tracking source.
inherited
peek() → T: Returns the current value without tracking it as a dependency.
inherited
prism<R>(R selector(T value), {String? name, bool equals(R previous, R next)?}) → Prism<R>: Available on TitanState<T>, provided by the PrismCoreExtension extension
Creates a Prism that projects a sub-value from this Core.
remove(K key) → void: Available on TitanState<Map<K, V>>, provided by the CoreMapExtensions extension
Removes a key (immutable update).
removeAt(int index) → void: Available on TitanState<List<T>>, provided by the CoreListExtensions extension
Removes the item at index (immutable update).
removeConduit(Conduit<T> conduit) → bool: Removes a previously added Conduit.
inherited
removeListener(ReactiveListener listener) → void: Removes a previously added listener.
inherited
removeWhere(bool test(T item)) → void: Available on TitanState<List<T>>, provided by the CoreListExtensions extension
Removes the first item matching test (immutable update).
reset() → void: Reset to the initial value and clear the error.
select<R>(R selector(T value)) → TitanComputed<R>: Creates a TitanComputed that selects a sub-value from this state.
inherited
set(K key, V val) → void: Available on TitanState<Map<K, V>>, provided by the CoreMapExtensions extension
Sets a key-value pair (immutable update).
setError(String? errorMessage) → void: Set the error manually (e.g., from server-side validation).
silent(T newValue) → void: Silently sets the value without notifying dependents.
inherited
throttle(Duration duration, {String? name}) → ThrottledState<T>: Available on TitanState<T>, provided by the FluxStateExtensions extension
Creates a throttled version of this Core.
toggle() → void: Available on TitanState<bool>, provided by the CoreBoolExtensions extension
Flips the boolean value.
toString() → String: A string representation of this object.
inherited
touch() → void: Mark this field as touched (e.g., when the user focuses and blurs it).
track() → void: Registers the current tracker (if any) as a dependent of this node.
inherited
update(T updater(T current)) → void: Updates the value using a transformation function.
inherited
validate() → bool: Run the synchronous validator against the current value and update error.
validateAsync() → Future<bool>: Run both synchronous and asynchronous validators.
where(bool predicate(T value)) → TitanComputed<bool>: Available on TitanState<T>, provided by the FluxStateExtensions extension
Creates a Derived<bool> that is true when predicate passes.

Operators

operator ==(Object other) → bool: The equality operator.
inherited