hooks library
Optional flutter_hooks integration for cell_flutter.
Status: Experimental, paired with cell_flutter 0.6.0 (hardening —
see the cell_flutter library docs and README.md Status for what
is and is not claimed).
This library is the Hooks Layer of the binding: a set of use*
functions that express the same reactive contracts as the widget
counterparts (CellBuilder, CellSelector, CellAsyncBuilder,
CellListener) but compose with flutter_hooks primitives. It is
opt-in — application code that does not use HookWidget should
import package:cell_flutter/cell_flutter.dart instead.
Import this library from any widget that extends HookWidget (or uses
HookBuilder):
import 'package:cell_flutter/hooks.dart';
Rules inherited from flutter_hooks
Every hook in this library must be called:
- Unconditionally — not inside an
if, loop, or short-circuit. - At the top of
HookWidget.build(before any early return that precedes another hook). - In the same order on every build.
Violations trigger flutter_hooks' own assertion. The contract is not
relaxed here — the hooks are thin wrappers around flutter_hooks
primitives and inherit its lifecycle model verbatim.
Requirements
flutter_hooks must be in your pubspec.yaml. It is a regular
dependency of cell_flutter, so it resolves automatically; pinning its
version explicitly is recommended for stability, since this library is
coupled to flutter_hooks' hook API.
Inherited caveats (please read)
useCellAsync inherits the per-source error-pulse behavior and the
concurrent-asyncMap caveat documented in CellAsyncBuilder.
In short: only Cell.fromFuture emits error pulses today; fromStream
and asyncMap do not. A useCellAsync over an asyncMap source with
concurrency > 0 inherits the concurrent-effect-attribution
caveat. The hooks' own observation is correct; the caveats concern the
source's replay fidelity and the per-source error surface.
What this library exports
- useCell — the selector hook (equivalent of
CellSelector). - useCellValue — the full-value shortcut for useCell.
- useCellNotifier — the CellNotifier hook for composing with
flutter_hooksprimitives orValueListenableBuilder. useCellListener— the side-effect hook (equivalent ofCellListener).useCellAsync— the async-snapshot hook (equivalent ofCellAsyncBuilder).
It also re-exports cell_flutter and flutter_hooks, so a single
import suffices in a HookWidget.
See Also:
cell_flutter— the widget-layer binding this library builds on.flutter_hooks— the hook primitives and rules this library obeys.CellBuilder,CellSelector,CellAsyncBuilder,CellListener— the widget equivalents each hook mirrors.
Classes
-
ApplyAccepted<
R> - The command was authorized, safety-checked, and successfully executed.
- ApplyCommandRunner
- A helper class used to set up and execute an action on a cell.
- ApplyLedger
- The framework's internal Record Keeper and receipt generator.
-
ApplyOutcome<
R> - The official, auditable result of submitting an ApplyCommand.
-
ApplyRejected<
R> - The command was denied by the framework's safety rules (the Integrity Gate).
- ApplyStaged
- The command was accepted and placed into a transaction to be run later.
- ApplyTransactionScope
- Handle for a staged command transaction — the mechanism behind Cell.txApply.
- ApplyVeto
- A special signal used by a function to cancel its own operation.
-
Async<
C> -
A foundational marker interface and architectural contract representing
an Asynchronous Proxy or Controller for a core component
C. -
AsyncPriorityQueue<
E> -
AsyncQueueList<
E> -
AsyncSynapses<
P extends Pulse, L extends Cell> - An Asynchronous Projection of a Synapses instance for non‑blocking signal distribution.
-
Box<
T> - A specialized, lightweight container used to provide a mutable state anchor within the framework's immutable Record architecture.
- Cell
- A reactive node: holds state (or relays signals), validates every incoming change against a policy, and broadcasts accepted changes to whatever else is listening.
-
CellAsyncBuilder<
V> - A widget that renders the asynchronous state of any Cell as an AsyncSnapshot<V>.
- CellBase
- The foundational abstract implementation of the Cell interface.
-
CellBuilder<
V> - A widget that rebuilds its builder whenever cell's value changes.
- CellEditingController
- A TextEditingController bound two-way to a ValueCell<String>.
- CellErrorBoundary
- Renders a fallback instead of Flutter's error screen when a cell-driven error is thrown while building the subtree below it.
- CellErrorBoundaryState
- The state behind CellErrorBoundary.
- CellFlutterDevTools
- The in-app Cell Inspector.
-
CellFormField<
T> - A FormField whose value is bound two-way to a ValueCell<T>.
- CellGraph
- A registered cell graph: the unit of identity and replay in the framework.
- CellGraphBuilder
- The entry point for constructing a CellGraph.
- CellGraphRegistry
- Public read-only access to the cell id registry.
- CellGraphSnapshot
- A serialisable snapshot of an entire cell graph.
- CellInspectorOverlay
- A floating in-app Cell Inspector panel.
-
CellListener<
V> - A widget that invokes onPulse for every pulse emitted by cell, without rebuilding its subtree.
-
CellListView<
T> - A virtualized list whose item collection is bound to a Cell.
-
CellNotifier<
V> - Adapts a ValueCell to Flutter's ValueNotifier contract as a read-only bridge.
- CellPulseRecord
- One recorded pulse, display-formatted.
- CellRegistry
- The live registry behind CellFlutterDevTools.
- CellRegistryEntry
- One registered cell and its journal.
- CellRestorationScope
- Provides a RestorationBucket to descendant RestorableCells and registers them automatically with Flutter's restoration protocol.
- CellRestorationScopeState
- The stateful, mixin-bearing half of CellRestorationScope.
- CellScope
- An InheritedWidget that provides a small set of app-level cells to the subtree below it, addressed by Symbol.
-
CellSelector<
V, S> - A widget that rebuilds its builder only when a selected slice of cell's value changes.
- CellSnapshot
- A serialisable projection of one cell's identity and current value.
- CellTextField
- A TextFormField whose value is bound two-way to a ValueCell<String>.
-
CellValueBuilder<
V> - A widget that rebuilds its builder whenever any Cell emits a new value.
- ClockEffect
- A read of the system clock. Records the epoch millis.
-
CollectivePulse<
P> - A Collective Pulse — a flat bundle of independent pulses travelling together as a single atomic wave.
-
CollectivePulseBase<
P> - The abstract base class for CollectivePulse implementations.
- CompensationFailure
- Describes a single failed compensation attempt.
- Context
- Metadata describing a Cell's tier, domain, and operational boundaries — used by TestCell rules to make context-aware decisions.
- ContextBase
- The foundational implementation of the Operational Environment, providing the core logic for Prototype-based Inheritance and Ontological Resolution.
- ContextTranslator
- Bridges a DeputyContext across mandate schema versions.
- ContextTranslatorRegistry
-
A simple registry of translators keyed by
(from, to). - CycleChecker
- A specialized Traversal Guard and Topology Validator, responsible for preventing infinite recursion and ensuring the reactive graph remains a Directed Acyclic Graph (DAG) during signal propagation.
- DefaultValue
-
DefaultValue is a metadata annotation primarily used by the code generation
framework (such as
build_model) to define a fallback or initial value for fields in a model class. - DeputyContext
- Represents the Formal Mandate and declaration of intention for a Deputy.
- DivergenceReport
- A single point at which a replay diverged from its recording.
- EffectJournal
- The boundary between a receptor and the outside world.
- EffectRecord
- A single recorded non-deterministic observation.
- EmailPattern
- EmailPattern is a specialized EntryPattern metadata annotation designed to validate whether a string conforms to a standard email address format.
- EntryPattern
- EntryPattern is a specialized TestRule metadata annotation that validates whether a string input matches a specific Regular Expression (RegExp).
-
EphemeralPolicy<
C extends Cell> - Defines the Lifecycle Governance for transient reactive nodes.
-
EvolvedPulse<
P> - An immutable signal derived from a previous pulse through a transformation step — a causal link in the signal's journey.
-
EvolvedPulseBase<
P> - The abstract base class for EvolvedPulse implementations.
-
FilterRule<
P extends Pulse> - A filter that can transform, redact, or suppress a Pulse before it is broadcast to downstream observers.
-
FinalBox<
T> - A specialized, write-once container providing a thread-safe, immutable anchor for state that is initialized after construction.
- ForkHandle
- A forked history.
- ForkLedgerStore
- A LedgerStore wrapper that injects a synthetic ForkRecord entry at seq 0.
- ForkRecord
- The genesis record of a fork ledger.
- FunctionObject
- Simple wrapper for functions or records containing function information. Used to pass function metadata through the system.
-
FunctionTypeObject<
T> - Lazy-evaluated version of TypeObject that executes a function to get the value. Useful for deferred initialization or expensive object creation.
-
Governance<
V> - The foundational Authority Protocol for defining structural and behavioral guardrails within the framework's Mandate ontology.
-
GovernanceEntry<
G extends Governance< V> , V> - A strongly-typed key-value pair that represents a single dimension of governance within the framework's Scene-Driven Ontology.
- HashChain
- The rolling hash chain that binds ledger entries.
-
Hook<
R> - Hook is similar to a StatelessWidget, but is not associated to an Element.
- HookBuilder
-
A HookWidget that delegates its
buildto a callback. -
HookState<
R, T extends Hook< R> > - The logic and internal state for a HookWidget
- HookWidget
- A Widget that can use a Hook.
- Identity
- A utility for materializing unique identities within the somatic graph.
- Inheritable
- InMemoryLedgerStore
- An in-memory LedgerStore, suitable for tests and for ephemeral graphs whose ledger does not need to survive the process.
-
Instruction<
C extends Cell, I extends Pulse, O extends Pulse> - A discrete logic unit that defines how a Receptor reacts to a Pulse.
-
InstructionBase<
C extends Cell, I extends Pulse, O extends Pulse> - The foundational implementation and architectural base for all Instruction variants.
-
InstructionChain<
C extends Cell, I extends Pulse, O extends Pulse> - A composite Instruction that orchestrates a sequence of processing units.
- IoEffect
-
A single I/O call (network, disk, database). Records the label, the
request digest, and the response digest; the raw response is held
only if the caller supplied
rawOutput. For replay,rawOutputis required — the digest alone cannot reconstruct the response. - JournalScope
- The task-local stack of active journals.
- Ledger
- The durable, hash-chained record of every state transition.
- LedgerEntry
- A single, immutable row in the ledger.
- LedgerScope
- The graph-scoped ambient that coordinates state capture and ledger append.
- LedgerScopeImpl
- The per-graph implementation of the scope.
- LedgerStore
- The persistence backend for a Ledger.
- Lock
-
A mutual-exclusion lock: serializes access to a shared resource across
asynchronous code, similar to Java's
synchronized. - MaxLength
-
MaxLength is a specialized TestRule metadata annotation used primarily by
the code generation framework (such as
build_model) to enforce structural and data-integrity constraints on model fields. - Modifiable
- A specialized architectural marker and base interface for objects that support controlled mutation through the framework's dynamic command pattern.
-
ModifiableAsync<
C extends Cell> - Provides asynchronous execution of operations on a Cell.
- MultiLock
- A Lock that atomically acquires several other locks together.
- Nucleolus
- A specialized, terminal implementation of the Nucleus contract representing the framework's "zero-state" and Ontological Root.
- Nucleus
- The immutable blueprint underlying every Cell — its receptor, testRule, context, synapses, and lifecycle policy, stored separately from the live cell instance.
- NucleusBase
- The foundational base implementation of the Nucleus contract, providing a memory-optimized storage engine for reactive cell properties.
- NullJournal
- The "no journal in scope" sentinel. Every effectful operation fails loudly.
-
ObjectRef<
T> - A class that stores a single value.
- OpenCell
- A specialized, interactive Cell that serves as a Reactive Bridge for external stimulus injection and dynamic topology management.
- OpenCellAsync
- Represents the Asynchronous Governance Interface for an OpenCell.
- PolicyReplay
- Policy-tick journaling for EphemeralPolicy.
- PolicyTickEffect
- A single tick of an EphemeralPolicy.
-
PriorityQueue<
E> - A collection of elements that maintains a Deterministic Priority Order, serving as a specialized Ranked Execution Buffer for the reactive fabric.
- PropagationPolicy
- A declarative blueprint defining the Temporal Dynamics and Operational Governance of pulse propagation.
-
Pulse<
P> - A reactive signal — the fundamental unit of communication in the framework.
-
PulseBase<
P> - The foundational blueprint for all nervous signals within the reactive graph.
- PulseCodec
- Canonical serialiser for Pulse.
- PulseContext
- Represents the Causal Identity and ontological Provenance of a Pulse.
- PulseContextCodec
- Serialises and deserialises PulseContext, preserving the full parent chain.
- PulseEphemeralPolicy
- A governance policy that defines the Lifecycle Constraints and Termination Logic for a Pulse as it traverses the reactive graph.
- PulseReconstructor
- Reconstructs the input Pulse that produced a LedgerEntry.
-
PulseShell<
P, R extends Receptor< Cell> > - A specialized Shell providing a Perceptual Projection of a Pulse to facilitate pre-execution validation and security gating.
-
QueueList<
E> -
Receptor<
C extends Cell> - The transformation pipeline that decides how a Cell responds to an incoming Pulse.
-
ReceptorAsync<
C extends Cell> - An asynchronous execution handle for a Receptor that facilitates non‑blocking pulse processing and lifecycle synchronization.
-
ReceptorBase<
C extends Cell> - The foundational base implementation of Receptor that provides the core synchronization and pulse propagation engine.
- RecordingJournal
- The recording side of the journal.
- RegisteredCell
- A thin wrapper that pairs a Cell with its graph-scoped name.
- ReplayEngine
- The replay engine.
- ReplayJournal
- The replay side of the journal.
- ReplayOptions
- Strictness flags that control the replay engine's behaviour when the replayed state diverges from the recorded state.
- ReplayResult
- The result of a ReplayEngine.replay call.
-
RestorableCell<
V> - A ValueCell whose value participates in Flutter's state restoration.
-
RestorableCellDelegate<
V> -
The internal
RestorablePropertythat bridges a RestorableCell to Flutter's restoration protocol. -
Shell<
T> - A specialized Defensive Perimeter and Projection Layer representing a formal contract for Bidirectional Mutual Authorization.
- StateDelta
- A single cell's state change within a ledger entry.
- StatefulHookWidget
- A StatefulWidget that can use a Hook.
-
Store<
StateT, ActionT> - A store of mutable state that allows mutations by dispatching actions.
- StreamEffect
- A stream event. Records the event's stream label, the digest of the value, and optionally the raw value.
-
Synapses<
P extends Pulse, L extends Cell> - The distribution fabric for a Cell's outgoing signals—defining how, when, and to whom a pulse is delivered.
-
SynapsesBase<
P extends Pulse, C extends Cell> -
The foundational base implementation for Synapses, serving as the
Transmission Engine of the
cell.corereactive framework. -
SyncBox<
T> - A synchronized variant of Box providing Thread-Safe Access and facilitating Atomic State Transitions across concurrent execution boundaries.
- SyncCycleChecker
- A thread-safe, Synchronized Circular Dependency Guard for asynchronous reactive flows.
-
SyncQueue<
E> - A thread-safe implementation of a PriorityQueue, providing Synchronized Access for prioritized collection-based state.
-
SyncSet<
E> - A thread-safe implementation of a Set, providing Synchronized Access for collection-based state.
- SynthesisCell
- Represents a Synthesis Cell—a specialized structural node that aggregates signals from multiple source cells into a single unified stream.
-
TestActionRule<
C extends Cell> - A specialized behavioral guard for validating imperative logic and functional action execution within the reactive graph.
-
TestCell<
C extends Cell> - The central validation gate for a Cell – it decides what's allowed.
- TestCellReplay
- Purity-aware invocation of a TestCell.
-
TestLinkRule<
C extends Cell> - A specialized behavioral guard for validating Topological Synapses and graph formation within the reactive framework.
- TestPasses
- A sentinel implementation of TestCell that always authorises every operation.
-
TestPulseRule<
C extends Cell> - A rule that validates incoming Pulse signals before they reach a cell.
-
TestRule<
C> - A fundamental architectural component representing an Integrity Gate or Validation Guard, responsible for enforcing structural and business invariants across the reactive graph.
- TimerEffect
- A timer firing. Records the scheduled duration and the actual fire time; the pair is what makes debounce/throttle replayable.
- TransactionBegun
- Emitted when a transaction begins.
- TransactionCommitted
- Emitted when a transaction commits successfully.
- TransactionEvent
- Base class for all transaction lifecycle events.
- TransactionOptions
- Configuration options for a Cell.transaction.
- TransactionRolledBack
- Emitted when a transaction is rolled back.
- TransactionTimedOut
- Emitted when a transaction times out.
- TransactionUpdated
- Emitted when a cell is updated during a transaction.
- TxApplyBegun
- Emitted once, immediately after ApplyTransactionScope.begin succeeds.
- TxApplyCommitted
- Emitted after a successful ApplyTransactionScope.commit.
- TxApplyCompensationFailed
- Emitted each time a compensation attempt fails.
- TxApplyCompensationRetry
- Emitted before each retry of a compensation function.
- TxApplyEvent
- Base class for all lifecycle events emitted by an ApplyTransactionScope.
- TxApplyOptions
- Configuration for Cell.txApply.
- TxApplyRejected
- Emitted when a staged command is refused.
- TxApplyRolledBack
- Emitted after a rollback (full or savepoint-scoped).
- TxApplyStaged
- Emitted once per successful ApplyTransactionScope.enqueueCommand.
-
TypeObject<
T> - Wrapper class for holding typed objects. Provides type safety when working with generic containers.
- Unmodifiable
- A specialized Marker Interface and architectural anchor used to identify reactive nodes and data structures that have been restricted to Read-Only access.
-
UnmodifiableCollectivePulse<
P> -
UnmodifiableEvolvedPulse<
P> -
UnmodifiablePulse<
P> - A read‑only projection of a pulse that enforces structural finality.
-
UnmodifiablePulseBase<
P> -
UnmodifiableValueCell<
V> -
A specialized read‑only proxy of a
ValueCellthat enforces immutability. - UuidEffect
- A UUID generation. Records the generated UUID.
- ValidationFailure
- Represents a validation failure for a specific cell.
-
ValueCell<
V> - A state‑bearing reactive node – the primary way to manage persistent state in the Cell Framework.
-
ValueCellAsync<
V> - A specialized asynchronous controller for ValueCell, providing a thread‑safe and non‑blocking interface for state interaction.
-
ValueNucleus<
V> -
A specialized Nucleus blueprint designed to manage and propagate a
discrete, persistent state value of type
V. - ValueRange
- ValueRange is a specialized TestRule metadata annotation designed to validate whether a numeric input falls within a specific inclusive boundary.
- Values
- Values is a specialized TestRule that validates whether a given input is present within a predefined collection of allowed values.
- VerdictEffect
-
The decision reached by an
effectfulTestCell. - VersionRegistry
-
Maps
(cellId, version)to the receptor and test rule that implemented that version. - WebsiteUrlPattern
- WebsiteUrlPattern is a specialized EntryPattern metadata annotation designed to validate whether a string conforms to a standard web URL format.
Enums
- AuditLevel
- Defines the Observability Granularity and XAI Verbosity required for a Deputy's operations.
- Clearance
- Defines the Sovereign Physical Laws and structural boundaries of reactive operations within the framework.
- CompensationErrorPolicy
- Determines how the transaction scope behaves when a compensation attempt fails.
- ForkPolicy
- How a fork handles the parent graph's state.
- HubRouting
- Defines how a Cell.hub decides which spoke (child cell) should receive an incoming signal.
- Isolation
- Defines the Architectural Boundary & State Visibility of a Deputy.
- IsolationLevel
- Defines the consistency and visibility guarantees for a transaction.
- LineageArgument
-
Defines the specific data field to be extracted when traversing a Pulse's
Causal History via the
lineagemethod. - LockOrdering
- Defines the order in which locks are acquired during commit.
-
Mandate<
V> - Defines the Capability Profile and Authorization Scope for a Deputy.
-
Ontology<
V> - Defines the Structural Taxonomy, Static Identity, and Architectural Shape of a Cell.
- PriorityTier
- Defines the Semantic Urgency Tiers for signal execution.
- PropagationStrategy
- Defines the tactical execution models for Pulse Propagation within the Cell framework's reactive graph.
-
Provenance<
V> - Defines the Causal Accountability, Audit Trail, and Operational Intent of a Pulse.
- Purity
- Classifies a Receptor or TestCell by its effect footprint.
- ReasoningStrategy
- Defines the Logical Pedigree and algorithmic origin of a Pulse.
- Sensitivity
- Defines the Information Classification and data-privacy tier of a Pulse.
- Sovereignty
- Defines the Commitment Authority and Escalation Protocol assigned to a Deputy.
Mixins
-
Deputy<
C extends Cell> - The mixin implementing proxy behavior for Cell.deputy — you don't use this directly.
- Effectful
- The declarative marker for effectful receptors and rules.
- EffectfulReadOnly
- A variant of Effectful for receptors that read the outside world but do not mutate it (clocks, environment variables, read-only database lookups). Reports Purity.readOnlyExternal.
-
GovernanceMixin<
G extends Governance< V> , V> - A convenient mixin that provides default implementations for the Governance interface methods.
- HookElement
- An Element that uses a HookWidget as its configuration.
-
InstructionChainMixin<
C extends Cell, I extends Pulse, O extends Pulse> - A mixin that provides the core execution engine for composite instructions.
- OpenReceptorMixin
- A mixin that implements the Manual Control Interface for the reactive network.
- OpenSynapsesMixin
- A mixin that implements the Reactive Topology Interface for OpenCell architectures.
Extensions
- ApplyCommandDSL on Cell
- A "fluent" shortcut that makes it easier to create and run commands on a cell.
- CellAsStream on Cell
-
Bridges a Cell to a Dart
Stream<V?>. - CellAsValue on Cell
- An extension that mirrors any Cell into a fresh ValueCell.
- CellGraphFork on CellGraph
- Forking extensions for CellGraph.
- CellGraphTranslators on CellGraph
- The graph-scoped translator registry.
- CellGraphVersions on CellGraph
- The graph-scoped version registry (see VersionRegistry).
- CellGraphVisualise on CellGraph
- Visualisation for CellGraph and Ledger.
- CellRestoration on Cell
- Static factory access for RestorableCell.
- ForkParentLookup on Ledger
- The parent ledger's hash at a given sequence.
- ForkVerify on ForkHandle
-
Fork-aware verification. A fork's verify requires the parent
ledger's
verify()to pass. - LedgerVisualise on Ledger
- Visualisation for a Ledger's entries (also used by the CLI).
-
PulseExtension
on Pulse<
P> - Provides a fluent, functional API for operating on individual Pulse instances.
-
PulseIterableExtension
on Iterable<
Pulse> - Fluent extensions for collections of Pulse objects.
- ReplayEngineFork on ReplayEngine
- Fork-aware replay: replays a parent ledger into a fork handle, applying a Mutation to each entry.
- TekartikLockExtension on Lock
-
Extension on Lock providing synchronous execution when possible, for
synchronous
computations that don't need to always go through a Future. -
ValueCellBuilder
on ValueCell<
V> - Fluent constructor for a CellBuilder over a ValueCell.
Constants
- useTextEditingController → const _TextEditingControllerHookCreator
- Creates a TextEditingController, either via an initial text or an initial TextEditingValue.
Properties
- debugHotReloadHooksEnabled ↔ bool
-
Whether to behave like in release mode or allow hot-reload for hooks.
getter/setter pair
Functions
-
canonicalJsonDecode(
String source) → Object? - Decodes a canonical JSON string into a JSON-encodable object tree.
-
canonicalJsonEncode(
Object? value, {bool omitNulls = false}) → String -
Encodes
valueinto deterministic, canonical JSON. -
cellEditingController(
ValueCell< String> cell) → CellEditingController -
Creates a CellEditingController bound to
cell. -
fingerprint(
Object? value) → String -
Computes the SHA-256 fingerprint of
value's canonical JSON form, hex-encoded. -
get<
T> (Function fn, {Function? fallback, T? orElse}) → T -
A robust functional utility for safely executing operations of type
Twith multi-stage recovery logic and hierarchical fallbacks. -
mapMerge<
K, V> (Map< String, dynamic> map, Map<String, dynamic> other) → Map<String, dynamic> -
restorableState<
V> ({required String restorationId, V? initial, V? fromPrimitives(Object? data)?, Object? toPrimitives(V? value)?}) → RestorableCell< V> - The unqualified alias for CellRestoration.restorableState.
-
snapshotForCell<
V> (Cell cell) → AsyncSnapshot< V> ? -
Returns the AsyncSnapshot the widget should show for
cell's currently retained pulse, ornullwhen nothing usable is retained. -
snapshotForPulse<
V> (Pulse< Object?> pulse) → AsyncSnapshot<V> -
Projects a single Pulse into an AsyncSnapshot for a
CellAsyncBuilder. -
use<
R> (Hook< R> hook) → R - Registers a Hook and returns its value.
-
useAnimation<
T> (Animation< T> animation) → T - Subscribes to an Animation and returns its value.
-
useAnimationController(
{Duration? duration, Duration? reverseDuration, String? debugLabel, double initialValue = 0, double lowerBound = 0, double upperBound = 1, TickerProvider? vsync, AnimationBehavior animationBehavior = AnimationBehavior.normal, List< Object?> ? keys}) → AnimationController - Creates an AnimationController and automatically disposes it when necessary.
-
useAppLifecycleState(
) → AppLifecycleState? - Returns the current AppLifecycleState value and rebuilds the widget when it changes.
-
useAutomaticKeepAlive(
{bool wantKeepAlive = true}) → void - Mark a widget using this hook as needing to stay alive even when it's in a lazy list that would otherwise remove it.
-
useCallback<
T extends Function> (T callback, [List< Object?> keys = const <Object>[]]) → T - Cache a function across rebuilds based on a list of keys.
-
useCarouselController(
{int initialItem = 0, List< Object?> ? keys}) → CarouselController - Creates a CarouselController that will be disposed automatically.
-
useCell<
V, S> ({required ValueCell< V> cell, required S select(V? value), bool equals(S previous, S next)?}) → S -
Reads the slice of
cellproduced byselect, rebuilding only when that slice changes. -
useCellAsync<
V> (Cell cell, {AsyncSnapshot< V> ? initialSnapshot}) → AsyncSnapshot<V> -
Returns the async state of
cellas an AsyncSnapshot, updating on every pulse. -
useCellListener<
V> ({required Cell cell, required void onPulse(BuildContext context, Pulse< V> pulse)}) → void -
Invokes
onPulsefor every pulse emitted bycell, without rebuilding the widget. -
useCellNotifier<
V> (ValueCell< V> cell) → CellNotifier<V> -
Returns a CellNotifier bound to
cell, disposed on unmount. -
useCellValue<
V> (ValueCell< V> cell) → V? - A convenience wrapper for "rebuild on every value change".
-
useContext(
) → BuildContext - Obtains the BuildContext of the building HookWidget.
-
useCupertinoTabController(
{int initialIndex = 0, List< Object?> ? keys}) → CupertinoTabController - Creates a CupertinoTabController that will be disposed automatically.
-
useDebounced<
T> (T toDebounce, Duration timeout) → T? -
Returns a debounced version of the provided value
toDebounce, triggering widget updates accordingly after a specifiedtimeoutduration. -
useDraggableScrollableController(
{List< Object?> ? keys}) → DraggableScrollableController - Creates a DraggableScrollableController that will be disposed automatically.
-
useEffect(
Dispose? effect(), [List< Object?> ? keys]) → void - Useful for side-effects and optionally canceling them.
-
useExpansibleController(
{List< Object?> ? keys}) → ExpansibleController - Creates a ExpansibleController that will be disposed automatically.
-
useExpansionTileController(
{List< Object?> ? keys}) → ExpansionTileController - Creates a ExpansionTileController that will be disposed automatically.
-
useFixedExtentScrollController(
{int initialItem = 0, ScrollControllerCallback? onAttach, ScrollControllerCallback? onDetach, List< Object?> ? keys}) → FixedExtentScrollController - Creates FixedExtentScrollController that will be disposed automatically.
-
useFocusNode(
{String? debugLabel, FocusOnKeyEventCallback? onKeyEvent, bool skipTraversal = false, bool canRequestFocus = true, bool descendantsAreFocusable = true, bool descendantsAreTraversable = true}) → FocusNode - Creates an automatically disposed FocusNode.
-
useFocusScopeNode(
{String? debugLabel, FocusOnKeyEventCallback? onKeyEvent, bool skipTraversal = false, bool canRequestFocus = true}) → FocusScopeNode - Creates an automatically disposed FocusScopeNode.
-
useFuture<
T> (Future< T> ? future, {T? initialData, bool preserveState = true}) → AsyncSnapshot<T> - Subscribes to a Future and returns its current state as an AsyncSnapshot.
-
useIsMounted(
) → IsMounted - Returns an IsMounted object that you can use to check if the State is mounted.
-
useListenable<
T extends Listenable?> (T listenable) → T - Subscribes to a Listenable and marks the widget as needing build whenever the listener is called.
-
useListenableSelector<
R> (Listenable? listenable, R selector()) → R - Rebuild only when there is a change in the selector result.
-
useMemoized<
T> (T valueBuilder(), [List< Object?> keys = const <Object>[]]) → T - Caches the instance of a complex object.
-
useOnAppLifecycleStateChange(
LifecycleCallback? onStateChanged) → void - Listens to the AppLifecycleState.
-
useOnListenableChange(
Listenable? listenable, VoidCallback listener) → void -
Adds a given
listenerto a Listenable and removes it when the hook is disposed. -
useOnPlatformBrightnessChange(
BrightnessCallback onBrightnessChange) → void - Listens to the platform Brightness.
-
useOnStreamChange<
T> (Stream< T> ? stream, {void onData(T event)?, void onError(Object error, StackTrace stackTrace)?, void onDone()?, bool? cancelOnError}) → StreamSubscription<T> ? -
Subscribes to a Stream and calls the Stream.listen to register the
onData,onError, andonDone. -
useOverlayPortalController(
{List< Object?> ? keys}) → OverlayPortalController - Creates a OverlayPortalController that will be disposed automatically.
-
usePageController(
{int initialPage = 0, bool keepPage = true, double viewportFraction = 1.0, ScrollControllerCallback? onAttach, ScrollControllerCallback? onDetach, List< Object?> ? keys}) → PageController - Creates a PageController that will be disposed automatically.
-
usePlatformBrightness(
) → Brightness - Returns the current platform Brightness value and rebuilds the widget when it changes.
-
usePrevious<
T> (T val) → T? -
Returns the previous value passed to usePrevious (from the previous widget
build). -
useReassemble(
VoidCallback callback) → void -
Runs the callback on every hot reload,
similar to
reassemblein the stateful widgets. -
useReducer<
StateT, ActionT> (Reducer< StateT, ActionT> reducer, {required StateT initialState, required ActionT initialAction}) → Store<StateT, ActionT> - An alternative to useState for more complex states.
-
useRef<
T> (T initialValue) → ObjectRef< T> - Creates an object that contains a single mutable property.
-
useScrollController(
{double initialScrollOffset = 0.0, bool keepScrollOffset = true, String? debugLabel, ScrollControllerCallback? onAttach, ScrollControllerCallback? onDetach, List< Object?> ? keys}) → ScrollController - Creates ScrollController that will be disposed automatically.
-
useSearchController(
{List< Object?> ? keys}) → SearchController - Creates a SearchController that will be disposed automatically.
-
useSingleTickerProvider(
{List< Object?> ? keys}) → TickerProvider - Creates a single usage TickerProvider.
-
useSnapshotController(
{bool allowSnapshotting = false}) → SnapshotController - Creates and disposes a SnapshotController.
-
useState<
T> (T initialData) → ValueNotifier< T> - Creates a variable and subscribes to it.
-
useStream<
T> (Stream< T> ? stream, {T? initialData, bool preserveState = true}) → AsyncSnapshot<T> - Subscribes to a Stream and returns its current state as an AsyncSnapshot.
-
useStreamController<
T> ({bool sync = false, VoidCallback? onListen, VoidCallback? onCancel, List< Object?> ? keys}) → StreamController<T> - Creates a StreamController which is automatically disposed when necessary.
-
useTabController(
{required int initialLength, Duration? animationDuration = kTabScrollDuration, TickerProvider? vsync, int initialIndex = 0, List< Object?> ? keys}) → TabController - Creates a TabController that will be disposed automatically.
-
useTransformationController(
{Matrix4? initialValue, List< Object?> ? keys}) → TransformationController - Creates and disposes a TransformationController.
-
useTreeSliverController(
) → TreeSliverController - Creates a TreeSliverController that will be disposed automatically.
-
useValueChanged<
T, R> (T value, R? valueChange(T oldValue, R? oldResult)) → R? - Watches a value and triggers a callback whenever the value changed.
-
useValueListenable<
T> (ValueListenable< T> valueListenable) → T - Subscribes to a ValueListenable and returns its value.
-
useValueNotifier<
T> (T initialData, [List< Object?> ? keys]) → ValueNotifier<T> - Creates a ValueNotifier that is automatically disposed.
-
useWidgetStatesController(
{Set< WidgetState> ? values, List<Object?> ? keys}) → WidgetStatesController - Creates a WidgetStatesController that will be disposed automatically.
-
withCellLocks<
T> (Iterable< Cell> cells, Future<T> body(), {int order(Cell a, Cell b)?}) → Future<T> -
Acquires the locks of
cellsin a deterministic total order. -
withLocks<
T> (Iterable< Lock?> locks, Future<T> body()) → Future<T> - Creates a cell that emits the values of a Dart Stream.
Typedefs
-
ApplyArguments
= ({Map<
Symbol, Object?> ? namedArguments, List<Object?> ? positionalArguments}) - A structured container for function arguments that allows for auditing and reversals.
- ApplyCommand = ({ApplyArguments arguments, ApplyCompensation? compensation, Function function})
- A complete request to perform an action or change state within a cell.
- ApplyCompensation = ({ApplyArguments arguments, Cell? cell, Function function})
- A set of instructions used to undo or "roll back" a change if it fails.
- ApplyReceipt = ({ApplyArguments arguments, Cell cell, String? contextVersion, Function function, String id, int? ledgerSeq, String? pulseDigest, String? receptorVersion, String? ruleVersion, DateTime timestamp, int? txSequence, bool vetted})
- The permanent, official record of a specific action taken by a cell.
-
Arguments
= ({Map<
Symbol, dynamic> ? namedArguments, List? positionalArguments}) - Represents a tuple of positional and named arguments for function calls. Used when validating or processing function applications in cells.
-
BrightnessCallback
= FutureOr<
void> Function(Brightness previous, Brightness current) - A callback triggered when the platform brightness changes.
- Dispose = void Function()
- A function called when the state of a widget is destroyed.
-
EgressHandle<
S extends Pulse> = ({Cell cell, void Function() start, void Function() stop}) - A management handle for an Output Terminal, providing a controlled interface to manage an external side-effect listener.
-
FunctionType<
R> = R Function() - Generic function type that takes no parameters and returns RNA. Used in FunctionTypeObject for lazy evaluation.
-
HubHandle
= ({Pulse? Function(Pulse pulse) emit, Future<
Pulse?> Function(Pulse pulse) emitAsync, Future<void> Function(Pulse pulse, {bool serializedCompletion}) ingest, Cell root, Iterable<Cell> spokes}) - A management handle for a Signal Distribution Hub, providing a unified interface to control a multi-destination routing cluster.
-
IngressHandle<
I> = ({Cell cell, bool Function(I input) emit, Future< bool> Function(I input) emitAsync, Future<void> Function(Pulse<I> pulse, {bool serializedCompletion}) ingest}) - A management handle for an Input Gateway, providing a controlled interface for injecting external imperative stimuli into the reactive graph.
-
InheritableHandle
= ({Cell? bind, Context context, EphemeralPolicy<
Cell> ? ephemeralPolicy, Receptor<Cell> receptor, TestCell<Cell> testRule}) - A structured grouping of the Governance & Logic properties that define a node's operational identity and can be cascaded through the inheritance chain.
- IsMounted = bool Function()
- Used by useIsMounted to allow widgets to determine if the Widget is still in the widget tree or not.
-
LifecycleCallback
= FutureOr<
void> Function(AppLifecycleState? previous, AppLifecycleState current) - A callback triggered when the app life cycle changes.
-
MirroredCell<
V> = ({ValueCell< V> cell, void Function() dispose}) - The paired result of CellAsValue.asValueCell: a mirror cell and the callback that releases it.
- Mutation = Pulse? Function(LedgerEntry entry, Pulse pulse)
- A what-if mutation hook.
- NucleusSimplest = Nucleolus
- A semantic type alias representing the framework's Zero-Overhead Root and the terminal ancestor of all reactive blueprints.
- OpenCellBase = _OpenCell
- Base class for all OpenCell types.
-
Reducer<
State, Action> = State Function(State state, Action action) -
Composes an
Actionand aStateto create a newState. -
SpokeRegistration
= ({DeputyContext? context, Pulse? Function(Cell cell, Pulse pulse, {dynamic user})? handler, String key, bool Function(String? type)? match, int priority, Receptor<
Cell> ? receptor}) - A configuration record for an individual Spoke (Destination) within a Cell.hub.
-
StateHandle<
V> = ({ValueCell< V> cell, Future<void> Function(Pulse<V> pulse, {bool serializedCompletion}) ingest, bool Function(V? value) update, Future<bool> Function(V? value) updateAsync}) - A management record that bundles a ValueCell with its imperative update functions — the standard way to create and interact with a state atom.
-
SynthesisHandle
= ({bool Function(Cell cell) add, void Function(Iterable<
Cell> cells) addAll, SynthesisCell cell, bool Function() clear, bool Function() isEmpty, bool Function(Cell cell) remove, void Function(Iterable<Cell> cells) removeAll, void Function() start, void Function() stop, List<Cell> Function() toList}) - An Administrative Record providing a control interface for dynamic SynthesisCell topographies.
-
TransactionScope
= ({Future<
void> Function(Iterable<Cell> cells) begin, Future<void> Function() commit, dynamic Function(Cell cell) pending, dynamic Function(Cell cell) read, Future<void> Function({Object? savepoint}) rollback, Object Function() savepoint, void Function(Cell cell, dynamic value) update}) - A handle for coordinating atomic, multi‑cell transactions.
Exceptions / Errors
- ForkIntegrityException
- Thrown by ForkVerify.verify when a fork's parent ledger, fork ledger, or genesis binding is invalid.
- LedgerIntegrityException
- Thrown by Ledger.verify when an entry's hash, sequence, or predecessor chain does not match.
- ReplayDivergenceException
- Thrown when a replay diverges from the recording.
- TransactionConflictException
- Thrown when an isolation conflict is detected during commit.
- TransactionTimeoutException
- Thrown when a transaction exceeds its timeout duration.
- TransactionValidationException
- Thrown when validation of buffered writes fails during commit.
- TxApplyCompensationException
- Raised when one or more compensations fail under CompensationErrorPolicy.collectThenThrow or CompensationErrorPolicy.failFast.
- TxApplyException
-
Raised for control-flow problems in a ApplyTransactionScope: wrong
phase (e.g.
commitbeforebegin), non-modifiable function, non- participant cell, or a rejected command at commit time.