feat(bloc): add a lot of docs, fix onWrap, and add repo provider

2022-07-17 15:25:57 +02:00
parent 5300e684de
commit b99664856d
32 changed files with 724 additions and 155 deletions
@@ -17,39 +17,62 @@
 import 'package:flutter/widgets.dart';
 import 'package:flutter_bloc/flutter_bloc.dart';

-abstract class BlocBaseConsumerScreen<B extends BlocBase<S>, S extends Object>
-    extends StatelessWidget {
+/// {@template bloc_base_consumer}
+/// [BlocBaseConsumerScreen] exposes [onBuild] and [onListen] in order react
+/// to new states.
+///
+/// An optional [shouldBuildWhen] and [shouldListenWhen] can be implemented
+/// for more granular control over when [onListen] and [onBuild] are called.
+/// The [shouldListenWhen] and [shouldBuildWhen] will be invoked on
+/// each [Bloc] or `state` change.
+/// They each take the previous `state` and current `state` and must return
+/// a [bool] which determines whether or not the [onBuild] and/or [onListen]
+/// function will be invoked.
+/// The previous `state` will be initialized to the `state` of the [Bloc] when
+/// the [BlocConsumer] is initialized.
+/// [shouldListenWhen] and [shouldBuildWhen] are optional and if they
+/// aren't implemented, they will default to `true`.
+///
+/// An optional [onWrap] can also be implemented. This build a wrapper arround
+/// the built [BlocConsumer] that is **not** rebuild on each state.
+/// {@endtemplate}
+abstract class BlocBaseConsumerScreen<Bloc extends BlocBase<State>,
+    State extends Object> extends StatelessWidget {
+  /// {@macro bloc_base_consumer}
  const BlocBaseConsumerScreen({super.key});

  /// Takes the previous `state` and the current `state` and is responsible for
  /// returning a [bool] which determines whether or not to trigger
  /// [onBuild] with the current `state`.
-  bool shouldBuildWhen(S previous, S current) => true;
+  bool shouldBuildWhen(State previous, State current) => true;

  /// Takes the previous `state` and the current `state` and is responsible for
  /// returning a [bool] which determines whether or not to trigger
  /// [onListen] with the current `state`.
-  bool shouldListenWhen(S previous, S current) => true;
+  bool shouldListenWhen(State previous, State current) => true;
+
+  /// The [onWrap] function which will be invoked on build.
+  /// The [onWrap] takes a `BuildContext` that **doesn't have** access
+  /// to the [Bloc] or [Cubit].
+  Widget onWrap(BuildContext context, Widget child) => child;

  /// The [onBuild] function which will be invoked on each widget build.
  /// The [onBuild] takes the `BuildContext` and current `state` and
  /// must return a widget.
-  Widget onBuild(BuildContext context, S state);
-
-  /// The [onWrap] function which will be invoked on each widget build.
-  /// The [onWrap] takes the `BuildContext`
-  /// Used to wrap which depends on the state.
-  Widget onWrap(BuildContext context, Widget child) => child;
+  Widget onBuild(BuildContext context, State state);

  /// Takes the `BuildContext` along with the `state`
  /// and is responsible for executing in response to `state` changes.
-  void onListen(BuildContext context, S state) {}
+  void onListen(BuildContext context, State state) {}

  @override
-  Widget build(BuildContext context) => BlocConsumer<B, S>(
-        listenWhen: shouldListenWhen,
-        listener: onListen,
-        buildWhen: shouldBuildWhen,
-        builder: (context, state) => onWrap(context, onBuild(context, state)),
+  Widget build(BuildContext context) => onWrap(
+        context,
+        BlocConsumer<Bloc, State>(
+          listenWhen: shouldListenWhen,
+          listener: onListen,
+          buildWhen: shouldBuildWhen,
+          builder: onBuild,
+        ),
      );
 }
@@ -16,20 +16,53 @@

 import 'package:flutter/widgets.dart';
 import 'package:flutter_bloc/flutter_bloc.dart';
+import 'package:wyatt_bloc_helper/src/utils/smart_provider.dart';

-abstract class BlocBaseProviderScreen<B extends BlocBase<S>, S extends Object>
-    extends StatelessWidget {
-  const BlocBaseProviderScreen({super.key});
+/// {@template bloc_base_provider}
+/// Need to implement a [create] function that is responsible for
+/// creating the [Bloc] or [Cubit] and a [builder] which will return a child
+/// that have access to the instance via `context.read<Bloc>()`.
+/// It is used as a dependency injection (DI) widget so that a single instance
+/// of a [Bloc] or [Cubit] can be provided to multiple widgets within a subtree.
+///
+/// It automatically handles closing the instance when used with [create].
+/// By default, [create] is called only when the instance is accessed.
+/// To override this behavior, set [lazy] to `false`.
+/// 
+/// By default, it provide already provided instance found in the tree.
+/// To override this behavior, set [smart] to `false`.
+/// {@endtemplate}
+abstract class BlocBaseProviderScreen<Bloc extends BlocBase<State>,
+    State extends Object> extends StatelessWidget {
+  /// {@macro bloc_base_provider}
+  const BlocBaseProviderScreen({
+    super.key,
+    this.lazy = true,
+    this.smart = true,
+  });

-  /// Creates the [Cubit] or [Bloc] to be used.
-  B create(BuildContext context);
+  /// Whether the [Bloc] or [Cubit] should be created lazily.
+  /// Defaults to `true` which means the [Bloc] or [Cubit] is created only when
+  /// accessed the first time, not when provided.
+  final bool lazy;
+
+  /// Whether this uses [SmartProvider].
+  /// Defaults to `true`. But if you want to provide new [Bloc] or [Cubit] 
+  /// of a same type in a sub-tree you may have to disable this.
+  final bool smart;
+
+  /// Creates the [Bloc] or [Cubit] to be used.
+  Bloc create(BuildContext context);

  /// Creates the child [Widget] to be used.
-  Widget buildChild(BuildContext context);
+  Widget builder(BuildContext context);

  @override
-  Widget build(BuildContext context) => BlocProvider<B>(
+  Widget build(BuildContext context) => SmartProvider.bloc<Bloc, State>(
+        context,
+        lazy: lazy,
+        enable: smart,
        create: (_) => create(context),
-        child: Builder(builder: buildChild),
+        child: Builder(builder: builder),
      );
 }
@@ -17,17 +17,44 @@
 import 'package:flutter/widgets.dart';
 import 'package:flutter_bloc/flutter_bloc.dart';
 import 'package:wyatt_bloc_helper/src/bloc_base/bloc_base_consumer_screen.dart';
+import 'package:wyatt_bloc_helper/src/utils/smart_provider.dart';

-abstract class BlocBaseScreen<B extends BlocBase<S>, S extends Object>
-    extends BlocBaseConsumerScreen<B, S> {
-  const BlocBaseScreen({super.key});
+/// {@template bloc_base_screen}
+/// Provide AND access to a [Bloc] or [Cubit].
+///
+/// This extends [BlocBaseConsumerScreen] with the methods
+// ignore: comment_references
+/// of [BlocBaseProviderScreen].
+/// {@endtemplate}
+abstract class BlocBaseScreen<Bloc extends BlocBase<State>,
+    State extends Object> extends BlocBaseConsumerScreen<Bloc, State> {
+  /// {@macro bloc_base_screen}
+  const BlocBaseScreen({
+    super.key,
+    this.lazy = true,
+    this.smart = true,
+  });
+
+  /// Whether the [Bloc] or [Cubit] should be created lazily.
+  /// Defaults to `true` which means the [Bloc] is created only when
+  /// accessed the first time, not when provided.
+  final bool lazy;
+
+
+  /// Whether this uses [SmartProvider].
+  /// Defaults to `true`. But if you want to provide new Bloc of a same type,
+  /// in a sub-tree you may have to disable this.
+  final bool smart;

  /// Creates the [Cubit] or [Bloc] to be used.
-  B create(BuildContext context);
+  Bloc create(BuildContext context);

  @override
-  Widget build(BuildContext context) => BlocProvider<B>(
-        create: (_) => create(context),
-        child: super.build(context),
-      );
+  Widget build(BuildContext context) => SmartProvider.bloc<Bloc, State>(
+      context,
+      lazy: lazy,
+      enable: smart,
+      create: (_) => create(context),
+      child: super.build(context),
+    );
 }