refactor(ads): convert AdmobNativeAdWidget to StatefulWidget

- AdmobNativeAdWidget is now a StatefulWidget to properly manage the lifecycle of the native ad object.
- Added logic to dispose of the native ad when the widget is removed from the tree or when the underlying ad object changes.
- Implemented error handling for incorrect ad object types.
- Updated documentation to reflect the new implementation and responsibilities of the widget.

Author: fulleni

lib/ads/widgets/admob_native_ad_widget.dart

@@ -12,25 +12,80 @@ import 'package:logging/logging.dart';
 /// It expects the `adObject` within the [app_ad_models.NativeAd] to be a fully
 /// loaded [admob.NativeAd] instance.
 /// {@endtemplate}
-class AdmobNativeAdWidget extends StatelessWidget {
+/// {@template admob_native_ad_widget}
+/// A widget that specifically renders a Google AdMob native ad.
+///
+/// This widget is responsible for taking the generic [app_ad_models.NativeAd]
+/// and rendering it using the `AdWidget` from the `google_mobile_ads` package.
+/// It expects the `adObject` within the [app_ad_models.NativeAd] to be a fully
+/// loaded [admob.NativeAd] instance.
+///
+/// This is a [StatefulWidget] to properly manage the lifecycle of the native
+/// ad object, ensuring it is disposed when the widget is removed from the tree
+/// or when the underlying ad object changes.
+/// {@endtemplate}
+class AdmobNativeAdWidget extends StatefulWidget {
   /// {@macro admob_native_ad_widget}
   const AdmobNativeAdWidget({required this.nativeAd, super.key});
 
   /// The generic native ad model which contains the provider-specific ad object.
   final app_ad_models.NativeAd nativeAd;
 
   @override
-  Widget build(BuildContext context) {
-    final adObject = nativeAd.adObject;
+  State<AdmobNativeAdWidget> createState() => _AdmobNativeAdWidgetState();
+}
 
-    // Safely cast the generic ad object to the expected AdMob native ad type.
-    if (adObject is! admob.NativeAd) {
-      Logger('AdmobNativeAdWidget').severe(
+class _AdmobNativeAdWidgetState extends State<AdmobNativeAdWidget> {
+  admob.NativeAd? _ad;
+  final Logger _logger = Logger('AdmobNativeAdWidget');
+
+  @override
+  void initState() {
+    super.initState();
+    _setAd();
+  }
+
+  @override
+  void didUpdateWidget(covariant AdmobNativeAdWidget oldWidget) {
+    super.didUpdateWidget(oldWidget);
+    // If the nativeAd object itself has changed (e.g., a new ad was loaded
+    // for the same placeholder ID), dispose the old ad and set the new one.
+    if (widget.nativeAd.id != oldWidget.nativeAd.id) {
+      _ad?.dispose();
+      _setAd();
+    }
+  }
+
+  @override
+  void dispose() {
+    // Dispose the native ad when the widget is removed from the tree.
+    // This is crucial for releasing native resources and preventing crashes.
+    _ad?.dispose();
+    _logger.info('AdmobNativeAdWidget disposed and native ad released.');
+    super.dispose();
+  }
+
+  /// Sets the internal [_ad] object from the widget's [nativeAd].
+  ///
+  /// This method ensures that the adObject is of the correct type and
+  /// logs an error if it's not.
+  void _setAd() {
+    if (widget.nativeAd.adObject is admob.NativeAd) {
+      _ad = widget.nativeAd.adObject as admob.NativeAd;
+    } else {
+      _ad = null; // Ensure _ad is null if the type is incorrect
+      _logger.severe(
         'The provided ad object is not of type admob.NativeAd. '
-        'Received: ${adObject.runtimeType}. Ad will not be displayed.',
+        'Received: ${widget.nativeAd.adObject.runtimeType}. Ad will not be displayed.',
       );
+    }
+  }
+
+  @override
+  Widget build(BuildContext context) {
+    if (_ad == null) {
       // Return an empty widget if the ad object is not of the correct type
-      // to prevent runtime errors.
+      // or if it was explicitly set to null due to an error.
       return const SizedBox.shrink();
     }
 
@@ -39,14 +94,14 @@ class AdmobNativeAdWidget extends StatelessWidget {
     // We wrap it in a SizedBox to provide explicit height constraints,
     // which is crucial for platform views (like native ads) within scrollable
     // lists to prevent "unbounded height" errors.
-    final adHeight = switch (nativeAd.templateType) {
-      app_ad_models.NativeAdTemplateType.small => 120, // Example height for small template
-      app_ad_models.NativeAdTemplateType.medium => 340, // Example height for medium template
+    final adHeight = switch (widget.nativeAd.templateType) {
+      app_ad_models.NativeAdTemplateType.small => 120,
+      app_ad_models.NativeAdTemplateType.medium => 340,
     };
 
     return SizedBox(
       height: adHeight.toDouble(),
-      child: admob.AdWidget(ad: adObject),
+      child: admob.AdWidget(ad: _ad!),
     );
   }
 }