# Dashboard System Documentation

## Overview

The Mnaaqla platform has three separate dashboards for different user types:

| Dashboard | Path | Type Constant | Theme Color |
|-----------|------|---------------|-------------|
| Individual User (فرد) | `/dashboard/` | `user` | Primary (Blue) |
| Company (شركة) | `/dashboard-company/` | `company` | Indigo |
| Fund (صندوق) | `/dashboard-fund/` | `fund` | Amber |

## Directory Structure

```
mnaaqla/
├── includes/
│   └── dashboard/
│       ├── config.php        # Configuration & helper functions
│       ├── header.php        # HTML head & opening body
│       ├── sidebar.php       # Sticky sidebar navigation
│       ├── topbar.php        # Top navigation bar
│       ├── footer.php        # Footer & sidebar JS
│       ├── entity-card.php   # User/Company/Fund info card
│       └── stats-card.php    # Colored statistics cards
│
├── dashboard/                # User dashboard
│   ├── index.php
│   ├── create-ad.php
│   ├── ads.php
│   └── ...
│
├── dashboard-company/        # Company dashboard
│   └── index.php
│
└── dashboard-fund/           # Fund dashboard
    └── index.php
```

## Creating a New Dashboard Page

### Step 1: Define Dashboard Type

At the top of your PHP file, define the dashboard type BEFORE including config:

```php
<?php
// Define dashboard type BEFORE including config
define('DASHBOARD_TYPE', 'user');  // or 'company' or 'fund'

require_once __DIR__ . '/../includes/dashboard/config.php';
```

### Step 2: Set Required Variables

```php
// Page configuration
$page_title = 'عنوان الصفحة';
$page_description = 'وصف اختياري';  // Optional
$current_page = 'page-id';  // For sidebar active state

// Notifications count (for topbar badge)
$notifications_count = 3;

// Entity info for sidebar card
$entity_info = [
    'name' => 'اسم المستخدم',
    'verified' => true,
    'account_type' => 'فردي',  // For user
    // 'cr_number' => '123456',  // For company
    // 'license_number' => '789',  // For fund
];

// Sidebar menu items
$sidebar_menu = [
    ['id' => 'home', 'title' => 'الرئيسية', 'icon' => 'home', 'url' => 'index.php'],
    ['id' => 'ads', 'title' => 'إعلاناتي', 'icon' => 'ads', 'url' => 'ads.php', 'badge' => 3],
    // ... more menu items
];
```

### Step 3: Include Components

```php
// Include header (HTML head, opening body)
include __DIR__ . '/../includes/dashboard/header.php';

// Include sidebar (sticky navigation)
include __DIR__ . '/../includes/dashboard/sidebar.php';

// Include topbar (page title, notifications)
include __DIR__ . '/../includes/dashboard/topbar.php';
?>

<!-- Your page content here -->
<div class="your-content">
    ...
</div>

<?php
// Include footer (closing tags, sidebar JS)
include __DIR__ . '/../includes/dashboard/footer.php';
?>
```

## Available Sidebar Icons

Use these icon names in the `icon` field of sidebar menu items:

| Icon Name | Description |
|-----------|-------------|
| `home` | Home/Dashboard |
| `ads` | Advertisements |
| `offers` | Offers |
| `verification` | Verification requests |
| `companies` | Companies |
| `funds` | Funds |
| `wallet` | Wallet |
| `notifications` | Notifications |
| `profile` | Profile |
| `settings` | Settings |
| `assemblies` | General assemblies |
| `communication` | Communication portal |
| `favorites` | Favorites |
| `messages` | Messages/Chat |
| `blog` | Blog |
| `shareholders` | Shareholders |
| `unitholders` | Unit holders |
| `reports` | Reports |
| `news` | News/Announcements |
| `distributions` | Distributions |

## Using Statistics Cards

### Include the stats-card component:

```php
require_once __DIR__ . '/../includes/dashboard/stats-card.php';
```

### Define stats data:

```php
$stats_cards = [
    [
        'value' => 1250,
        'label' => 'إعلان منشور',
        'color' => 'blue',      // blue, green, red, amber, indigo, purple, cyan, emerald, gray
        'icon' => $stat_icons['ads'],
        'format' => 'number',   // number, currency, percentage
    ],
    [
        'value' => 15000.50,
        'label' => 'إجمالي المبيعات',
        'color' => 'green',
        'icon' => $stat_icons['money'],
        'format' => 'currency',
    ],
];
```

### Render the grid:

```php
// Render 8-column grid (default)
render_stats_grid($stats_cards, 8);

// Or specify columns: 4, 5, 6, or 8
render_stats_grid($stats_cards, 4);
```

### Available stat icons:

```php
$stat_icons['ads']       // Documents
$stat_icons['check']     // Checkmark circle
$stat_icons['x']         // X circle
$stat_icons['badge']     // Verified badge
$stat_icons['arrows']    // Exchange arrows
$stat_icons['users']     // Multiple users
$stat_icons['fund']      // Coins/Fund
$stat_icons['company']   // Building
$stat_icons['clipboard'] // Clipboard
$stat_icons['document']  // Single document
$stat_icons['news']      // Newspaper
$stat_icons['assembly']  // Group meeting
$stat_icons['chat']      // Chat bubbles
$stat_icons['money']     // Money/Currency
```

## Helper Functions

### get_base_path()

Returns the base path for assets based on dashboard type:

```php
$base_path = get_base_path();
// Returns '../' for dashboard pages
```

### get_dashboard_theme()

Returns theme configuration for current dashboard type:

```php
$theme = get_dashboard_theme();
// Returns: [
//     'accent' => 'primary',  // or 'indigo', 'amber'
//     'label' => 'لوحة التحكم',
//     'label_color' => 'text-primary-600',
// ]
```

### get_sidebar_icon($icon_name)

Returns SVG path for sidebar icons:

```php
echo get_sidebar_icon('home');
// Returns: <path ... />
```

## Entity Card Types

The entity card (`entity-card.php`) automatically adapts based on `DASHBOARD_TYPE`:

### User Card
```php
$entity_info = [
    'name' => 'محمد أحمد',
    'avatar' => null,  // or image URL
    'verified' => true,
    'account_type' => 'فردي',
];
```

### Company Card
```php
$entity_info = [
    'name' => 'شركة الرياض للتقنية',
    'logo' => null,  // or image URL
    'verified' => true,
    'cr_number' => '1234567890',
    'total_shares' => 1000000,
    'shareholders_count' => 150,
];
```

### Fund Card
```php
$entity_info = [
    'name' => 'صندوق النمو',
    'logo' => null,
    'verified' => true,
    'type' => 'صندوق عقاري',
    'license_number' => '12345',
    'nav' => 12.50,
    'unitholders_count' => 500,
    'risk_level' => 'متوسط',  // منخفض, متوسط, مرتفع
];
```

## Responsive Behavior

### Sidebar
- **Desktop (lg+)**: Sticky sidebar, always visible
- **Mobile**: Slide-in overlay, toggle with hamburger menu

### Stats Grid
- **Mobile**: 2 columns
- **Tablet (sm)**: 3-4 columns
- **Desktop (lg)**: Full columns (4, 5, 6, or 8)

## Example: Complete Page

```php
<?php
/**
 * My Custom Page - منصة مناقلة
 */

define('DASHBOARD_TYPE', 'user');

require_once __DIR__ . '/../includes/dashboard/config.php';
require_once __DIR__ . '/../includes/dashboard/stats-card.php';

// Page configuration
$page_title = 'صفحتي المخصصة';
$page_description = 'وصف الصفحة';
$current_page = 'custom';
$notifications_count = 3;

// Entity info
$entity_info = [
    'name' => 'محمد أحمد',
    'verified' => true,
    'account_type' => 'فردي',
];

// Sidebar menu
$sidebar_menu = [
    ['id' => 'home', 'title' => 'الرئيسية', 'icon' => 'home', 'url' => 'index.php'],
    ['id' => 'custom', 'title' => 'صفحتي', 'icon' => 'document', 'url' => 'custom.php'],
];

// Include components
include __DIR__ . '/../includes/dashboard/header.php';
include __DIR__ . '/../includes/dashboard/sidebar.php';
include __DIR__ . '/../includes/dashboard/topbar.php';
?>

<div class="bg-white rounded-2xl border border-gray-100 p-6">
    <h2 class="text-lg font-bold text-gray-800 mb-4">محتوى الصفحة</h2>
    <p class="text-gray-600">هذا هو محتوى صفحتك المخصصة.</p>
</div>

<?php include __DIR__ . '/../includes/dashboard/footer.php'; ?>
```

## Notes

1. Always define `DASHBOARD_TYPE` before including `config.php`
2. The sidebar is sticky on desktop and slides in on mobile
3. Use Tailwind CSS classes for styling
4. RTL support is built-in via `dir="rtl"` and `font-rtl` class
5. Primary color is defined in `input.min.css` as CSS custom properties
