Feature/add dynamic role assignment

README.md

@@ -1,41 +1,158 @@
-# flutter_policy_engine
+# Flutter Policy Engine
 
-A lightweight, extensible policy engine for Flutter. Define, manage, and evaluate access control rules declaratively using ABAC (Attribute-Based Access Control) or RBAC (Role-Based Access Control) models.
+[![Pub Version](https://img.shields.io/pub/v/flutter_policy_engine)](https://pub.dev/packages/flutter_policy_engine)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Flutter](https://img.shields.io/badge/Flutter-3.4.1+-blue.svg)](https://flutter.dev)
 
-## Features
+A lightweight, extensible policy engine for Flutter applications. Define, manage, and evaluate access control rules declaratively using **ABAC** (Attribute-Based Access Control) or **RBAC** (Role-Based Access Control) models with a clean, intuitive API.
 
-- Attribute-Based and Role-Based Access Control (ABAC/RBAC)
-- Declarative rule definitions
-- Extensible and modular design
-- Easy integration with Flutter apps
+## ✨ Features
 
-## Installation
+- **🔐 Dual Access Control Models**: Support for both Role-Based (RBAC) and Attribute-Based (ABAC) access control
+- **🎯 Declarative Policy Definitions**: Define access rules using simple, readable configurations
+- **🏗️ Modular Architecture**: Extensible design with clear separation of concerns
+- **⚡ Lightweight & Fast**: Minimal overhead with efficient policy evaluation
+- **🔄 Real-time Updates**: Dynamic policy updates without app restarts
+- **🎨 Flutter-Native**: Built specifically for Flutter with widget integration
+- **📱 Easy Integration**: Simple setup with minimal boilerplate code
+- **🧪 Comprehensive Testing**: Full test coverage with examples
 
-Ensure you have [Flutter](https://docs.flutter.dev/get-started/install) and [Dart](https://dart.dev/get-dart) installed. [FVM](https://fvm.app/) is recommended for managing Flutter versions.
+## 🚀 Quick Start
+
+### Installation
+
+Add the package to your `pubspec.yaml`:
+
+```yaml
+dependencies:
+  flutter_policy_engine: ^1.0.1
+```
+
+Run the installation:
 
 ```bash
-# Clone the repository and enter the directory
-git clone <repo-url>
-cd flutter_policy_engine
+flutter pub get
+```
 
-# Run the setup script (requires bash, Flutter, Node.js, and npm)
-./setup.sh
+### Basic Usage
+
+```dart
+import 'package:flutter/material.dart';
+import 'package:flutter_policy_engine/flutter_policy_engine.dart';
+
+void main() async {
+  WidgetsFlutterBinding.ensureInitialized();
+
+  // Initialize policy manager
+  final policyManager = PolicyManager();
+  await policyManager.initialize({
+    "admin": ["dashboard", "users", "settings", "reports"],
+    "manager": ["dashboard", "users", "reports"],
+    "user": ["dashboard"],
+    "guest": ["login"]
+  });
+
+  runApp(MyApp(policyManager: policyManager));
+}
+
+class MyApp extends StatelessWidget {
+  final PolicyManager policyManager;
+
+  const MyApp({super.key, required this.policyManager});
+
+  @override
+  Widget build(BuildContext context) {
+    return PolicyProvider(
+      policyManager: policyManager,
+      child: MaterialApp(
+        title: 'Policy Engine Demo',
+        home: HomePage(),
+      ),
+    );
+  }
+}
+
+class HomePage extends StatelessWidget {
+  @override
+  Widget build(BuildContext context) {
+    return Scaffold(
+      appBar: AppBar(title: Text('Dashboard')),
+      body: Column(
+        children: [
+          // Only show for admin and manager roles
+          PolicyWidget(
+            role: "admin",
+            content: "users",
+            child: UserManagementCard(),
+            fallback: AccessDeniedWidget(),
+          ),
+
+          // Show for all authenticated users
+          PolicyWidget(
+            role: "user",
+            content: "dashboard",
+            child: DashboardCard(),
+          ),
+        ],
+      ),
+    );
+  }
+}
 ```
 
-The setup script will:
+## 📚 Core Concepts
+
+### Policy Manager
+
+The central orchestrator that manages all access control logic:
+
+```dart
+final policyManager = PolicyManager();
+
+// Initialize with role definitions
+await policyManager.initialize({
+  "admin": ["dashboard", "users", "settings"],
+  "user": ["dashboard"],
+});
+
+// Check access programmatically
+bool hasAccess = policyManager.evaluateAccess("admin", "users"); // true
+bool canAccess = policyManager.evaluateAccess("user", "settings"); // false
+```
+
+### Policy Widget
+
+Conditionally render content based on user roles:
+
+```dart
+PolicyWidget(
+  role: "admin",
+  content: "settings",
+  child: SettingsPage(),
+  fallback: AccessDeniedWidget(),
+)
+```
+
+### Role Management
+
+Create and manage roles dynamically:
+
+```dart
+// Add a new role
+await policyManager.addRole("moderator", ["dashboard", "comments"]);
 
-- Check for Flutter and FVM
-- Install the Flutter version from `.fvm/fvm_config.json` (if present)
-- Install Dart/Flutter dependencies (`pub get`)
-- Install Node.js dependencies (if `package.json` exists)
-- Initialize Husky for git hooks (if present)
-- Add `.fvm/` to `.gitignore` if needed
+// Update existing role
+await policyManager.updateRole("user", ["dashboard", "profile"]);
 
-## Testing
+// Remove a role
+await policyManager.removeRole("guest");
+```
+
+## 🧪 Testing
 
 ### Local Testing
 
-Run tests with coverage locally:
+Run tests with coverage:
 
 ```bash
 # Using the provided script (recommended)
@@ -48,20 +165,57 @@ genhtml coverage/lcov.info -o coverage/html
 open coverage/html/index.html
 ```
 
-## Contributing
+### Example App
+
+Explore the interactive example app:
+
+```bash
+cd example
+flutter run
+```
+
+The example includes:
+
+- Basic policy demonstrations
+- Role management interface
+- Real-time policy updates
+- Access control scenarios
+
+## 📚 Documentation
+
+- **[Quick Start Guide](docs/quick-start.mdx)** - Get up and running in minutes
+- **[Core Concepts](docs/core-concepts/)** - Deep dive into policy management
+- **[Examples](docs/examples/)** - Practical usage examples
+
+## 🤝 Contributing
+
+We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
+
+### Development Setup
+
+```bash
+# Clone the repository
+git clone https://github.com/aspicas/flutter_policy_engine.git
+cd flutter_policy_engine
+
+# Run the setup script
+./setup.sh
+
+# Run tests
+./scripts/test_with_coverage.sh
+```
 
-Contributions are welcome! Please:
+### Code Style
 
-- Follow the existing code style and patterns
-- Write clear commit messages (Commitlint and Husky are enabled)
-- Add or update tests for new features or bug fixes
-- Ensure all tests pass before submitting a pull request
-- Open a pull request with a clear description
+- Follow the existing code patterns and style
+- Write clear commit messages (Commitlint enabled)
+- Add tests for new features
+- Ensure all tests pass before submitting PRs
 
-## License
+## 📄 License
 
 MIT © 2025 David Alejandro Garcia Ruiz
 
 ---
 
-> **Tip:** If you use VSCode, restart your terminal after setup to ensure FVM is properly detected.
+> **💡 Tip**: If you use VSCode, restart your terminal after setup to ensure FVM is properly detected.

docs.json

@@ -0,0 +1,51 @@
+{
+  "name": "Flutter Policy Engine",
+  "description": "A comprehensive policy management and access control system for Flutter applications",
+  "sidebar": [
+    {
+      "group": "Getting Started",
+      "pages": [
+        {
+          "title": "Introduction",
+          "href": "/",
+          "icon": "rocket"
+        },
+        {
+          "title": "Quick Start",
+          "href": "/quick-start",
+          "icon": "play"
+        },
+        {
+          "title": "Installation",
+          "href": "/installation",
+          "icon": "download"
+        }
+      ]
+    },
+    {
+      "group": "Core Concepts",
+      "pages": [
+        {
+          "title": "Policy Management",
+          "href": "/core-concepts/policy-management",
+          "icon": "shield"
+        }
+      ]
+    },
+    {
+      "group": "Examples",
+      "pages": [
+        {
+          "title": "Basic Policy Demo",
+          "href": "/examples/basic-policy-demo",
+          "icon": "code"
+        },
+        {
+          "title": "Role Management Demo",
+          "href": "/examples/role-management-demo",
+          "icon": "settings"
+        }
+      ]
+    }
+  ]
+}