feat(policy): add PolicyProvider and PolicyWidget for access control management

Author: dgarciasquare1

lib/flutter_policy_engine.dart

@@ -1,3 +1,5 @@
 library flutter_policy_engine;
 
 export 'src/core/policy_manager.dart';
+export 'src/widgets/policy_widget.dart';
+export 'src/core/policy_provider.dart';

lib/src/core/policy_manager.dart

@@ -185,4 +185,24 @@ class PolicyManager extends ChangeNotifier {
       rethrow;
     }
   }
+
+  /// Checks if the specified [role] has access to the given [content].
+  ///
+  /// Returns `true` if the policy manager is initialized and the evaluator
+  /// determines that the [role] is permitted to access the [content].
+  /// Returns `false` if the policy manager is not initialized, the evaluator
+  /// is not set, or if access is denied.
+  ///
+  /// Logs an error if called before initialization or if the evaluator is missing.
+  bool hasAccess(String role, String content) {
+    if (!_isInitialized || _evaluator == null) {
+      LogHandler.error(
+        'Policy manager not initialized or evaluator not set',
+        context: {'role': role, 'content': content},
+        operation: 'policy_manager_access_check',
+      );
+      return false;
+    }
+    return _evaluator!.evaluate(role, content);
+  }
 }

lib/src/core/policy_provider.dart

@@ -0,0 +1,95 @@
+import 'package:flutter/widgets.dart';
+import 'package:flutter_policy_engine/src/core/policy_manager.dart';
+
+/// A widget that provides a [PolicyManager] instance to its descendant widgets.
+///
+/// This widget uses Flutter's [InheritedWidget] pattern to make the [PolicyManager]
+/// available throughout the widget tree without having to pass it explicitly
+/// through constructors.
+///
+/// Example usage:
+/// ```dart
+/// PolicyProvider(
+///   policyManager: myPolicyManager,
+///   child: MyApp(),
+/// )
+/// ```
+///
+/// To access the [PolicyManager] in descendant widgets:
+/// ```dart
+/// final policyManager = PolicyProvider.policyManagerOf(context);
+/// ```
+class PolicyProvider extends InheritedWidget {
+  /// Creates a [PolicyProvider] widget.
+  ///
+  /// The [policyManager] parameter is required and will be made available
+  /// to all descendant widgets in the widget tree.
+  ///
+  /// The [child] parameter is required and represents the widget subtree
+  /// that will have access to the provided [PolicyManager].
+  const PolicyProvider({
+    required this.policyManager,
+    required super.child,
+    super.key,
+  });
+
+  /// The [PolicyManager] instance that will be provided to descendant widgets.
+  final PolicyManager policyManager;
+
+  /// Returns the nearest [PolicyProvider] widget in the widget tree.
+  ///
+  /// This method uses [BuildContext.dependOnInheritedWidgetOfExactType] to
+  /// establish a dependency on the [PolicyProvider] widget, which means
+  /// the calling widget will rebuild when the [PolicyProvider] changes.
+  ///
+  /// Returns `null` if no [PolicyProvider] is found in the widget tree.
+  ///
+  /// Example:
+  /// ```dart
+  /// final provider = PolicyProvider.of(context);
+  /// if (provider != null) {
+  ///   // Use provider.policyManager
+  /// }
+  /// ```
+  static PolicyProvider? of(BuildContext context) {
+    return context.dependOnInheritedWidgetOfExactType<PolicyProvider>();
+  }
+
+  /// Returns the [PolicyManager] from the nearest [PolicyProvider] widget.
+  ///
+  /// This is a convenience method that combines finding the [PolicyProvider]
+  /// and accessing its [policyManager] property. It throws a [StateError]
+  /// if no [PolicyProvider] is found in the widget tree.
+  ///
+  /// This method establishes a dependency on the [PolicyProvider] widget,
+  /// causing the calling widget to rebuild when the provider changes.
+  ///
+  /// Throws:
+  /// - [StateError] if no [PolicyProvider] is found in the widget tree.
+  ///
+  /// Example:
+  /// ```dart
+  /// final policyManager = PolicyProvider.policyManagerOf(context);
+  /// // Use policyManager directly
+  /// ```
+  static PolicyManager policyManagerOf(BuildContext context) {
+    final provider = of(context);
+    if (provider == null) {
+      throw StateError('PolicyProvider not found in context');
+    }
+    return provider.policyManager;
+  }
+
+  /// Determines whether this widget should notify its dependents of changes.
+  ///
+  /// Returns `true` if the [policyManager] has changed, indicating that
+  /// dependent widgets should rebuild. This ensures that widgets using
+  /// the [PolicyManager] are updated when the manager instance changes.
+  ///
+  /// The comparison is done by reference equality, so a new [PolicyManager]
+  /// instance will trigger a rebuild even if it has the same configuration.
+  @override
+  bool updateShouldNotify(PolicyProvider oldWidget) {
+    return policyManager != oldWidget.policyManager;
+  }
+}

lib/src/widgets/policy_widget.dart

@@ -0,0 +1,83 @@
+import 'package:flutter/widgets.dart';
+import 'package:flutter_policy_engine/src/core/policy_provider.dart';
+import 'package:flutter_policy_engine/src/exceptions/i_policy_sdk_exceptions.dart';
+
+/// A widget that conditionally displays its [child] based on policy access control.
+///
+/// [PolicyWidget] checks if the given [role] has access to the specified [content]
+/// using the nearest [PolicyProvider] in the widget tree. If access is granted,
+/// [child] is rendered. If access is denied, [fallback] is rendered (or an empty
+/// [SizedBox] if [fallback] is null), and [onAccessDenied] is called if provided.
+///
+/// If a [IPolicySDKException] is thrown during access evaluation, an assertion
+/// error is thrown in debug mode; in release mode, access is denied silently.
+///
+/// Example usage:
+/// ```dart
+/// PolicyWidget(
+///   role: 'admin',
+///   content: 'dashboard',
+///   child: DashboardWidget(),
+///   fallback: AccessDeniedWidget(),
+///   onAccessDenied: () => log('Access denied'),
+/// )
+/// ```
+class PolicyWidget extends StatelessWidget {
+  /// Creates a [PolicyWidget].
+  ///
+  /// [role] is the user or entity role to check.
+  /// [content] is the resource or content identifier to check access for.
+  /// [child] is the widget to display if access is granted.
+  /// [fallback] is the widget to display if access is denied (optional).
+  /// [onAccessDenied] is a callback invoked when access is denied (optional).
+  const PolicyWidget({
+    required this.role,
+    required this.content,
+    required this.child,
+    this.fallback,
+    this.onAccessDenied,
+    super.key,
+  });
+
+  /// The role to check for access.
+  final String role;
+
+  /// The content or resource identifier to check access for.
+  final String content;
+
+  /// The widget to display if access is granted.
+  final Widget child;
+
+  /// The widget to display if access is denied. If null, an empty [SizedBox] is shown.
+  final Widget? fallback;
+
+  /// Callback invoked when access is denied.
+  final VoidCallback? onAccessDenied;
+
+  @override
+  Widget build(BuildContext context) {
+    final policyManager = PolicyProvider.policyManagerOf(context);
+
+    try {
+      final hasAccess = policyManager.hasAccess(role, content);
+
+      if (hasAccess) {
+        return child;
+      } else {
+        onAccessDenied?.call();
+        return fallback ?? const SizedBox.shrink();
+      }
+    } catch (e) {
+      if (e is IPolicySDKException) {
+        assert(() {
+          throw FlutterError('Error en PolicyWidget: ${e.message}');
+        }());
+
+        // On production, deny access silently
+        onAccessDenied?.call();
+        return fallback ?? const SizedBox.shrink();
+      }
+      rethrow;
+    }
+  }
+}