Optimize rendering & dispose(s)

packages/rad/lib/rad.dart

@@ -42,8 +42,9 @@ export 'src/core/common/enums.dart' show WrapType;
 export 'src/core/common/enums.dart' show SpellCheckType;
 export 'src/core/common/enums.dart' show ScopeType;
 
-export 'src/core/common/enums.dart' show DomEventType;
 export 'src/core/common/enums.dart' show DomTagType;
+export 'src/core/common/enums.dart' show DomEventType;
+export 'src/core/common/enums.dart' show RenderEventType;
 
 export 'src/core/common/enums.dart' show UpdateType;
 
@@ -80,6 +81,7 @@ export 'src/core/interface/window/abstract.dart' show WindowDelegate;
 export 'src/core/common/objects/key.dart' show Key;
 export 'src/widgets/abstract/widget.dart' show Widget;
 export 'src/core/services/events/emitted_event.dart' show EmittedEvent;
+export 'src/core/common/objects/render_event.dart' show RenderEvent;
 export 'src/core/common/abstract/build_context.dart' show BuildContext;
 export 'src/core/common/abstract/render_element.dart' show RenderElement;
 export 'src/core/common/objects/common_render_elements.dart'

packages/rad/lib/src/core/common/abstract/render_element.dart

@@ -12,6 +12,8 @@ import 'package:rad/src/core/common/enums.dart';
 import 'package:rad/src/core/common/objects/dom_node_patch.dart';
 import 'package:rad/src/core/common/objects/key.dart';
 import 'package:rad/src/core/common/objects/meta_information.dart';
+import 'package:rad/src/core/common/objects/render_event.dart';
+import 'package:rad/src/core/common/types.dart';
 import 'package:rad/src/core/interface/meta/meta.dart';
 import 'package:rad/src/core/services/services.dart';
 import 'package:rad/src/widgets/abstract/widget.dart';
@@ -158,6 +160,15 @@ abstract class RenderElement implements BuildContext {
   |--------------------------------------------------------------------------
   */
 
+  /// Register hook.
+  ///
+  /// This is the first method that framework calls as part of rendering
+  /// this widget on screen. It's safe to register event callbacks in this
+  /// method using [addRenderEventListeners].
+  ///
+  @protected
+  void register() {}
+
   /// Render hook.
   ///
   /// This hook gets called exactly once during lifetime of an element. This
@@ -376,6 +387,31 @@ abstract class RenderElement implements BuildContext {
     );
   }
 
+  /// Register RenderEvent listeners.
+  ///
+  @protected
+  void addRenderEventListeners(
+    Map<RenderEventType, RenderEventCallback> listeners,
+  ) {
+    assert(
+      _isInRegistrationPhase,
+      'addRenderEventListeners should be called in register()',
+    );
+    assert(
+      !_isEventsRegistered,
+      'addRenderEventListeners should be called exactly once',
+    );
+
+    _eventListeners = listeners;
+
+    if (_eventListeners.containsKey(RenderEventType.didUnMount) ||
+        _eventListeners.containsKey(RenderEventType.willUnMount)) {
+      _announceUnMountListeners();
+    }
+
+    _isEventsRegistered = true;
+  }
+
   /*
   |--------------------------------------------------------------------------
   | Below are framework reserved objects & APIs.
@@ -385,6 +421,14 @@ abstract class RenderElement implements BuildContext {
   |--------------------------------------------------------------------------
   */
 
+  /// Whether execution of [RenderElement.register] is pending.
+  ///
+  var _isInRegistrationPhase = true;
+
+  /// Whether addRenderEventListeners has been called.
+  ///
+  var _isEventsRegistered = false;
+
   /// @nodoc
   @nonVirtual
   @internal
@@ -415,6 +459,69 @@ abstract class RenderElement implements BuildContext {
   List<RenderElement> get frameworkChildElements => _childElements;
   final _childElements = <RenderElement>[];
 
+  /*
+  |--------------------------------------------------------------------------
+  | framework reserved | RenderEvents APIs
+  |--------------------------------------------------------------------------
+  */
+
+  var _eventListeners = const <RenderEventType, RenderEventCallback>{};
+
+  /// @nodoc
+  @internal
+  @nonVirtual
+  Map<RenderEventType, RenderEventCallback> get frameworkRenderEventListeners {
+    return _eventListeners;
+  }
+
+  /// @nodoc
+  @internal
+  @nonVirtual
+  bool frameworkHasEventListenerOfType(RenderEventType type) {
+    return _eventListeners.containsKey(type);
+  }
+
+  /// @nodoc
+  @internal
+  @nonVirtual
+  void frameworkDispatchRenderEvent(RenderEventType renderEventType) {
+    if (_eventListeners.isEmpty) {
+      return;
+    }
+
+    var listener = _eventListeners[renderEventType];
+    if (null != listener) {
+      listener(const RenderEvent());
+    }
+  }
+
+  /*
+  |--------------------------------------------------------------------------
+  | framework reserved | event announce APIs
+  |--------------------------------------------------------------------------
+  */
+
+  /// Whether this part of tree contains any un-mount event listener.
+  ///
+  /// @nodoc
+  @internal
+  @nonVirtual
+  bool get frameworkContainsUnMountListeners => _containsUnMountListeners;
+  var _containsUnMountListeners = false;
+
+  /// @nodoc
+  @nonVirtual
+  void _announceUnMountListeners() {
+    visitAncestorElements((renderElement) {
+      if (renderElement.frameworkContainsUnMountListeners) {
+        return false;
+      }
+
+      renderElement._containsUnMountListeners = true;
+      return true;
+    });
+  }
+
   /*
   |--------------------------------------------------------------------------
   | framework reserved | lifecycle api
@@ -447,6 +554,16 @@ abstract class RenderElement implements BuildContext {
     }
   }
 
+  /// @nodoc
+  @internal
+  @nonVirtual
+  void frameworkInitRenderElement() {
+    assert(_isInRegistrationPhase, 'RenderElement already registered');
+
+    register();
+    _isInRegistrationPhase = false;
+  }
+
   /// @nodoc
   @internal
   @nonVirtual

packages/rad/lib/src/core/common/abstract/watchful_render_element.dart

@@ -5,13 +5,14 @@
 import 'package:meta/meta.dart';
 
 import 'package:rad/src/core/common/abstract/render_element.dart';
+import 'package:rad/src/core/common/enums.dart';
+import 'package:rad/src/core/common/objects/render_event.dart';
 
-/// Base class for render elements that are watching their position in the tree.
+/// A render element show casing lifecycle events.
 ///
-/// Watchful elements differs from other render elements in that framework
-/// consider them alive in tree and framework will let them know when it
-/// mounts or un-mounts them from tree so that these elements can take
-/// appropriate actions.
+/// This class serves as an example that shows additional functionality
+/// (such as lifecycle events) provided by [RenderElement]s. It can be used
+/// as-it-is as well.
 ///
 abstract class WatchfulRenderElement extends RenderElement {
   WatchfulRenderElement(super.widget, super.parent);
@@ -28,6 +29,20 @@ abstract class WatchfulRenderElement extends RenderElement {
   bool get isMounted => _isMounted;
   bool _isMounted = false;
 
+  /// @nodoc
+  @nonVirtual
+  @override
+  void register() {
+    addRenderEventListeners({
+      RenderEventType.didRender: frameworkDidRender,
+      RenderEventType.didUpdate: frameworkDidUpdate,
+      RenderEventType.willUnMount: frameworkWillUnMount,
+      RenderEventType.didUnMount: frameworkDidUnMount,
+    });
+
+    init();
+  }
+
   /*
   |--------------------------------------------------------------------------
   | lifecycle hooks
@@ -82,14 +97,7 @@ abstract class WatchfulRenderElement extends RenderElement {
   /// @nodoc
   @internal
   @nonVirtual
-  void frameworkInit() {
-    init();
-  }
-
-  /// @nodoc
-  @internal
-  @nonVirtual
-  void frameworkAfterMount() {
+  void frameworkDidRender(RenderEvent event) {
     assert(!isMounted, 'Widget is already mounted');
 
     _isMounted = true;
@@ -100,21 +108,21 @@ abstract class WatchfulRenderElement extends RenderElement {
   /// @nodoc
   @internal
   @nonVirtual
-  void frameworkAfterUpdate() {
+  void frameworkDidUpdate(RenderEvent event) {
     afterUpdate();
   }
 
   /// @nodoc
   @internal
   @nonVirtual
-  void frameworkDispose() {
+  void frameworkWillUnMount(RenderEvent event) {
     dispose();
   }
 
   /// @nodoc
   @internal
   @nonVirtual
-  void frameworkAfterUnMount() {
+  void frameworkDidUnMount(RenderEvent event) {
     assert(isMounted, 'Widget is not mounted yet');
 
     _isMounted = false;

packages/rad/lib/src/core/common/enums.dart

@@ -4,6 +4,7 @@
 
 import 'package:meta/meta.dart';
 
+import 'package:rad/src/core/common/abstract/render_element.dart';
 import 'package:rad/src/widgets/gesture_detector.dart';
 
 /// The two cardinal directions in two dimensions.
@@ -405,6 +406,30 @@ enum ReferrerPolicyType {
   const ReferrerPolicyType(this.nativeValue);
 }
 
+/// Type of Render event.
+///
+enum RenderEventType {
+  /// A event that's fired after framework finishes rendering the output
+  /// of [RenderElement.render] to the DOM.
+  ///
+  didRender,
+
+  /// A event that's fired after framework finishes rendering the output
+  /// of [RenderElement.update] to the DOM.
+  ///
+  didUpdate,
+
+  /// A event that's fired when framework is about to remove the widget from
+  /// the DOM.
+  ///
+  willUnMount,
+
+  /// A event that's fired after framework finishes removing the widget from
+  /// the DOM.
+  ///
+  didUnMount,
+}
+
 /// Type of DOM event.
 ///
 enum DomEventType {

packages/rad/lib/src/core/common/objects/render_event.dart

@@ -0,0 +1,14 @@
+// Copyright (c) 2022, Rad developers. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+/// A RenderElement's event.
+///
+/// Render events don't carry any information, they serves as mere signals
+/// for the listeners(for now).
+///
+class RenderEvent {
+  /// Create render event.
+  ///
+  const RenderEvent();
+}

packages/rad/lib/src/core/common/types.dart

@@ -10,6 +10,7 @@ import 'package:meta/meta.dart';
 import 'package:rad/src/core/common/abstract/build_context.dart';
 import 'package:rad/src/core/common/abstract/render_element.dart';
 import 'package:rad/src/core/common/enums.dart';
+import 'package:rad/src/core/common/objects/render_event.dart';
 import 'package:rad/src/core/services/events/emitted_event.dart';
 import 'package:rad/src/core/services/scheduler/abstract.dart';
 import 'package:rad/src/widgets/abstract/widget.dart';
@@ -21,6 +22,8 @@ typedef EventCallback = void Function(EmittedEvent event);
 
 typedef NativeEventCallback = void Function(Event event);
 
+typedef RenderEventCallback = void Function(RenderEvent event);
+
 typedef ExceptionCallback = void Function(Exception event);
 
 typedef PopStateEventCallback = void Function(PopStateEvent event);