BloomProvider<T> class

An InheritedWidget providing a reactive Bloom<T> node to descendant widgets with rebuild wave suppression.

In standard Flutter development, updating inherited widget state triggers wide subtree rebuilds across all dependent elements. BloomProvider eliminates these rebuild storms by decoupling structural element scoping from reactive state propagation:

  • updateShouldNotify only returns true if the underlying bloom node reference itself changes (!identical).
  • Descendant widgets observe state via via.of<T>(context) or via(context.bloomOf<T>()).
  • Mutations to the Bloom node's payload propagate surgically through Bloom's 2-Phase LPDAG engine directly to leaf terminals, leaving intermediate and sibling widgets completely untouched.

System Architectural Flow

┌────────────────────────────────────────────────────────────────────────┐
│                    BloomProvider Element Architecture                   │
├────────────────────────────────────────────────────────────────────────┤
│                                                                        │
│   [ BloomProvider<T>(bloom: myBloom) ] ── (InheritedWidget In Element Tree)
│                  │                                                     │
│                  │ (updateShouldNotify returns !identical(old, new))   │
│                  ▼                                                     │
│   [ Intermediate Static Widgets ]  ──► Bypasses Rebuilds (0 Rebuilds!) │
│                  │                                                     │
│                  ▼                                                     │
│   [ Descendant BloomWidget / composed ]                                 │
│                  │                                                     │
│                  ├─► context.bloomOf<T>()    ──► Fetches Bloom<T> node   │
│                  └─► via.of<T>(context)     ──► Registers in 2-Phase   │
│                                                 LPDAG (Leaf Only Rebuild)
│                                                                        │
└────────────────────────────────────────────────────────────────────────┘

Key Invariants & Architectural Benefits

  1. Zero Subtree Rebuild Storms: State mutations inside bloom never trigger wide InheritedWidget rebuild passes.
  2. Surgical Leaf Rebuilds: Only widgets explicitly observing the state via BloomVia are invalidated (Rebuild Scope: Leaf Only).
  3. Sound Scoped Discovery: Seamless context lookup via BloomBuildContextProviderExtension.bloomOf and BloomViaContextExtension.of.
  4. Exact Type Resolution: InheritedWidget resolution relies on exact reified type keys (BloomProvider<T>). Subtypes or base classes do not match automatically. If polymorphic consumption is needed, explicitly provision as the base type (e.g. BloomProvider<FooBase>(bloom: fooBloom)).

Warning (Anti-Pattern Prevention):

  • Avoid wrapping transient subtrees with new BloomProvider instances repeatedly in build methods with newly constructed Bloom nodes, which forces tree replacement.

BAD:

// [Anti-Pattern] New controller instantiated per frame in provider
Widget build(BuildContext context) {
  return BloomProvider(bloom: blooming(0).bloom, child: const ChildWidget());
}

GOOD:

// [Recommended] Provide stable cached state
class FeaturePage extends StatelessWidget {
  FeaturePage({super.key});
  final counter = blooming(0);

  @override
  Widget build(BuildContext context) {
    return BloomProvider<int>(bloom: counter.bloom, child: const CounterDisplay());
  }
}

Examples

// Providing state at an ancestor level
BloomProvider<CounterState>(
  bloom: counterController.bloom,
  child: const CounterDisplay(),
);

// Consuming in a descendant BloomWidget
base class CounterDisplay extends BloomWidget {
  const CounterDisplay({super.key});

  @override
  Widget build(BuildContext context, BloomVia via) {
    final state = via.of<CounterState>(context);
    return Text('Count: ${state.count}');
  }
}
Inheritance

Constructors

BloomProvider({Key? key, required Bloom<T> bloom, required Widget child})
Creates a BloomProvider binding bloom into the widget subtree.
const

Properties

bloom → Bloom<T>
The provided reactive state carrier node.
final
child → Widget
The widget below this widget in the tree.
finalinherited
hashCode → int
The hash code for this object.
no setterinherited
key → Key?
Controls how one widget replaces another widget in the tree.
finalinherited
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited

Methods

createElement() → InheritedElement
Inflates this configuration to a concrete instance.
inherited
debugDescribeChildren() → List<DiagnosticsNode>
Returns a list of DiagnosticsNode objects describing this node's children.
inherited
debugFillProperties(DiagnosticPropertiesBuilder properties) → void
Add additional properties associated with the node.
inherited
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
toDiagnosticsNode({String? name, DiagnosticsTreeStyle? style}) → DiagnosticsNode
Returns a debug representation of the object that is used by debugging tools and by DiagnosticsNode.toStringDeep.
inherited
toString({DiagnosticLevel minLevel = DiagnosticLevel.info}) → String
A string representation of this object.
inherited
toStringDeep({String prefixLineOne = '', String? prefixOtherLines, DiagnosticLevel minLevel = DiagnosticLevel.debug, int wrapWidth = 65}) → String
Returns a string representation of this node and its descendants.
inherited
toStringShallow({String joiner = ', ', DiagnosticLevel minLevel = DiagnosticLevel.debug}) → String
Returns a one-line detailed description of the object.
inherited
toStringShort() → String
A short, textual description of this widget.
inherited
updateShouldNotify(covariant BloomProvider<T> oldWidget) → bool
Returns true only if the bloom node reference has changed.
override

Operators

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

Static Methods

maybeOf<T>(BuildContext context) → Bloom<T?>
Retrieves the Bloom<T?> state from the nearest ancestor BloomProvider<T>, if present.
of<T>(BuildContext context) → Bloom<T>
Retrieves the Bloom<T> state from the nearest ancestor BloomProvider<T>.