refactor(ad): improve interstitial ad config management

- Replace single config object with map for better role-based frequency control
- Add checkbox to toggle ad visibility for each user role
- Update controllers initialization and updates logic
- Simplify transitions retrieval and update methods
- Enhance comments and code structure for better readability

Author: fulleni

lib/app_configuration/widgets/interstitial_ad_settings_form.dart

@@ -31,8 +31,11 @@ class InterstitialAdSettingsForm extends StatefulWidget {
 class _InterstitialAdSettingsFormState extends State<InterstitialAdSettingsForm>
     with SingleTickerProviderStateMixin {
   late TabController _tabController;
+
+  /// Controllers for transitions before showing interstitial ads, mapped by user role.
+  /// These are used to manage text input for each role's interstitial ad frequency.
   late final Map<AppUserRole, TextEditingController>
-  _transitionsBeforeShowingInterstitialAdsControllers;
+      _transitionsBeforeShowingInterstitialAdsControllers;
 
   @override
   void initState() {
@@ -45,6 +48,51 @@ class _InterstitialAdSettingsFormState extends State<InterstitialAdSettingsForm>
     _tabController.addListener(_onTabChanged);
   }
 
+  /// Initializes text editing controllers for each user role based on current
+  /// remote config values.
+  void _initializeControllers() {
+    final interstitialConfig =
+        widget.remoteConfig.adConfig.interstitialAdConfiguration;
+    _transitionsBeforeShowingInterstitialAdsControllers = {
+      for (final role in AppUserRole.values)
+        role: TextEditingController(
+          text: _getTransitionsBeforeInterstitial(
+            interstitialConfig,
+            role,
+          ).toString(),
+        )..selection = TextSelection.collapsed(
+            offset: _getTransitionsBeforeInterstitial(
+              interstitialConfig,
+              role,
+            ).toString().length,
+          ),
+    };
+  }
+
+  /// Updates text editing controllers when the widget's remote config changes.
+  /// This ensures the form fields reflect the latest configuration.
+  void _updateControllers() {
+    final interstitialConfig =
+        widget.remoteConfig.adConfig.interstitialAdConfiguration;
+    for (final role in AppUserRole.values) {
+      final newInterstitialValue = _getTransitionsBeforeInterstitial(
+        interstitialConfig,
+        role,
+      ).toString();
+      if (_transitionsBeforeShowingInterstitialAdsControllers[role]?.text !=
+          newInterstitialValue) {
+        _transitionsBeforeShowingInterstitialAdsControllers[role]?.text =
+            newInterstitialValue;
+        _transitionsBeforeShowingInterstitialAdsControllers[role]?.selection =
+            TextSelection.collapsed(
+          offset: newInterstitialValue.length,
+        );
+      }
+    }
+  }
+
+  /// Listener for tab changes to enforce business rules, specifically for
+  /// premium users who should not see ads.
   void _onTabChanged() {
     if (_tabController.indexIsChanging) return;
 
@@ -55,18 +103,19 @@ class _InterstitialAdSettingsFormState extends State<InterstitialAdSettingsForm>
 
       // If the value for premium is not 0, update the config.
       // This enforces the business rule that premium users do not see ads.
-      if (interstitialAdConfig
-              .feedInterstitialAdFrequencyConfig
-              .premiumUserTransitionsBeforeShowingInterstitialAds !=
-          0) {
-        final updatedFrequencyConfig = interstitialAdConfig
-            .feedInterstitialAdFrequencyConfig
-            .copyWith(
-              premiumUserTransitionsBeforeShowingInterstitialAds: 0,
-            );
-        final updatedInterstitialAdConfig = interstitialAdConfig.copyWith(
-          feedInterstitialAdFrequencyConfig: updatedFrequencyConfig,
-        );
+      final premiumRoleConfig =
+          interstitialAdConfig.visibleTo[AppUserRole.premiumUser];
+      if (premiumRoleConfig != null &&
+          premiumRoleConfig.transitionsBeforeShowingInterstitialAds != 0) {
+        final updatedVisibleTo = Map<AppUserRole, InterstitialAdFrequencyConfig>.from(
+          interstitialAdConfig.visibleTo,
+        )..[AppUserRole.premiumUser] = const InterstitialAdFrequencyConfig(
+            transitionsBeforeShowingInterstitialAds: 0,
+          );
+
+        final updatedInterstitialAdConfig =
+            interstitialAdConfig.copyWith(visibleTo: updatedVisibleTo);
+
         widget.onConfigChanged(
           widget.remoteConfig.copyWith(
             adConfig: adConfig.copyWith(
@@ -87,47 +136,6 @@ class _InterstitialAdSettingsFormState extends State<InterstitialAdSettingsForm>
     }
   }
 
-  void _initializeControllers() {
-    final interstitialConfig =
-        widget.remoteConfig.adConfig.interstitialAdConfiguration;
-    _transitionsBeforeShowingInterstitialAdsControllers = {
-      for (final role in AppUserRole.values)
-        role:
-            TextEditingController(
-                text: _getTransitionsBeforeInterstitial(
-                  interstitialConfig,
-                  role,
-                ).toString(),
-              )
-              ..selection = TextSelection.collapsed(
-                offset: _getTransitionsBeforeInterstitial(
-                  interstitialConfig,
-                  role,
-                ).toString().length,
-              ),
-    };
-  }
-
-  void _updateControllers() {
-    final interstitialConfig =
-        widget.remoteConfig.adConfig.interstitialAdConfiguration;
-    for (final role in AppUserRole.values) {
-      final newInterstitialValue = _getTransitionsBeforeInterstitial(
-        interstitialConfig,
-        role,
-      ).toString();
-      if (_transitionsBeforeShowingInterstitialAdsControllers[role]?.text !=
-          newInterstitialValue) {
-        _transitionsBeforeShowingInterstitialAdsControllers[role]?.text =
-            newInterstitialValue;
-        _transitionsBeforeShowingInterstitialAdsControllers[role]?.selection =
-            TextSelection.collapsed(
-              offset: newInterstitialValue.length,
-            );
-      }
-    }
-  }
-
   @override
   void dispose() {
     _tabController
@@ -220,90 +228,92 @@ class _InterstitialAdSettingsFormState extends State<InterstitialAdSettingsForm>
     );
   }
 
+  /// Builds role-specific configuration fields for interstitial ad frequency.
+  ///
+  /// This widget displays an input field for `transitionsBeforeShowingInterstitialAds`
+  /// for a given [AppUserRole]. Premium users have this field disabled
+  /// as they should not see ads.
   Widget _buildInterstitialRoleSpecificFields(
     BuildContext context,
     AppLocalizations l10n,
     AppUserRole role,
     InterstitialAdConfiguration config,
   ) {
-    // Premium users do not see ads, so their settings are disabled.
+    final roleConfig = config.visibleTo[role];
     final isEnabled = role != AppUserRole.premiumUser;
 
     return Column(
       children: [
-        AppConfigIntField(
-          label: l10n.transitionsBeforeInterstitialAdsLabel,
-          description: l10n.transitionsBeforeInterstitialAdsDescription,
-          value: _getTransitionsBeforeInterstitial(config, role),
-          onChanged: (value) {
-            widget.onConfigChanged(
-              widget.remoteConfig.copyWith(
-                adConfig: widget.remoteConfig.adConfig.copyWith(
-                  interstitialAdConfiguration:
-                      _updateTransitionsBeforeInterstitial(
-                        config,
-                        value,
-                        role,
+        CheckboxListTile(
+          title: Text(l10n.visibleToRoleLabel(role.l10n(context))),
+          value: roleConfig != null && isEnabled,
+          onChanged: isEnabled
+              ? (value) {
+                  final newVisibleTo =
+                      Map<AppUserRole, InterstitialAdFrequencyConfig>.from(
+                    config.visibleTo,
+                  );
+                  if (value ?? false) {
+                    // Default value when enabling for a role
+                    newVisibleTo[role] = const InterstitialAdFrequencyConfig(
+                      transitionsBeforeShowingInterstitialAds: 5,
+                    );
+                  } else {
+                    newVisibleTo.remove(role);
+                  }
+                  widget.onConfigChanged(
+                    widget.remoteConfig.copyWith(
+                      adConfig: widget.remoteConfig.adConfig.copyWith(
+                        interstitialAdConfiguration: config.copyWith(
+                          visibleTo: newVisibleTo,
+                        ),
                       ),
-                ),
-              ),
-            );
-          },
-          controller: _transitionsBeforeShowingInterstitialAdsControllers[role],
-          enabled: isEnabled,
+                    ),
+                  );
+                }
+              : null,
         ),
+        if (roleConfig != null)
+          Padding(
+            padding: const EdgeInsets.symmetric(
+              horizontal: AppSpacing.lg,
+              vertical: AppSpacing.sm,
+            ),
+            child: AppConfigIntField(
+              label: l10n.transitionsBeforeInterstitialAdsLabel,
+              description: l10n.transitionsBeforeInterstitialAdsDescription,
+              value: roleConfig.transitionsBeforeShowingInterstitialAds,
+              onChanged: (value) {
+                final newRoleConfig =
+                    roleConfig.copyWith(transitionsBeforeShowingInterstitialAds: value);
+                final newVisibleTo =
+                    Map<AppUserRole, InterstitialAdFrequencyConfig>.from(
+                  config.visibleTo,
+                )..[role] = newRoleConfig;
+                widget.onConfigChanged(
+                  widget.remoteConfig.copyWith(
+                    adConfig: widget.remoteConfig.adConfig.copyWith(
+                      interstitialAdConfiguration: config.copyWith(
+                        visibleTo: newVisibleTo,
+                      ),
+                    ),
+                  ),
+                );
+              },
+              controller: _transitionsBeforeShowingInterstitialAdsControllers[role],
+              enabled: isEnabled,
+            ),
+          ),
       ],
     );
   }
 
+  /// Retrieves the number of transitions before showing an interstitial ad
+  /// for a specific role from the configuration.
   int _getTransitionsBeforeInterstitial(
     InterstitialAdConfiguration config,
     AppUserRole role,
   ) {
-    switch (role) {
-      case AppUserRole.guestUser:
-        return config
-            .feedInterstitialAdFrequencyConfig
-            .guestTransitionsBeforeShowingInterstitialAds;
-      case AppUserRole.standardUser:
-        return config
-            .feedInterstitialAdFrequencyConfig
-            .standardUserTransitionsBeforeShowingInterstitialAds;
-      case AppUserRole.premiumUser:
-        return config
-            .feedInterstitialAdFrequencyConfig
-            .premiumUserTransitionsBeforeShowingInterstitialAds;
-    }
-  }
-
-  InterstitialAdConfiguration _updateTransitionsBeforeInterstitial(
-    InterstitialAdConfiguration config,
-    int value,
-    AppUserRole role,
-  ) {
-    final currentFrequencyConfig = config.feedInterstitialAdFrequencyConfig;
-
-    InterstitialAdFrequencyConfig newFrequencyConfig;
-
-    switch (role) {
-      case AppUserRole.guestUser:
-        newFrequencyConfig = currentFrequencyConfig.copyWith(
-          guestTransitionsBeforeShowingInterstitialAds: value,
-        );
-      case AppUserRole.standardUser:
-        newFrequencyConfig = currentFrequencyConfig.copyWith(
-          standardUserTransitionsBeforeShowingInterstitialAds: value,
-        );
-      case AppUserRole.premiumUser:
-        // Premium users should not see ads, so their frequency is always 0.
-        // The UI field is disabled, but this is a safeguard.
-        newFrequencyConfig = currentFrequencyConfig.copyWith(
-          premiumUserTransitionsBeforeShowingInterstitialAds: 0,
-        );
-    }
-
-    return config.copyWith(
-      feedInterstitialAdFrequencyConfig: newFrequencyConfig,
-    );
+    return config.visibleTo[role]?.transitionsBeforeShowingInterstitialAds ?? 0;
   }
 }