# Bongo Dashboard Package - Cursor Rules

## Project Overview

This is the **Bongo Dashboard** package (`bongo/dashboard`), a Laravel package that provides a backend admin dashboard with widget-based quick links and quick-create functionality for registered packages.

**Key Purpose**: Renders the main admin dashboard landing page with quick access to all registered CMS/admin packages.

## Project Structure

```
dashboard/
├── src/
│   ├── Http/Controllers/Backend/
│   │   └── DashboardController.php    # Main dashboard controller
│   ├── Routes/
│   │   └── backend.php                # Backend route (admin dashboard)
│   ├── Views/backend/
│   │   ├── index.blade.php            # Main dashboard view
│   │   └── partials/
│   │       ├── widget.blade.php       # Package link widget
│   │       └── quick_create.blade.php # Quick create dropdown item
│   ├── Translations/en/
│   │   └── backend.php                # English translations
│   └── DashboardServiceProvider.php   # Service provider (extends AbstractServiceProvider)
├── tests/
│   ├── TestCase.php                   # Orchestra Testbench base test case
│   ├── Unit/
│   └── Feature/
├── composer.json
└── phpunit.xml
```

## Architecture

### Service Provider Pattern

**File**: `src/DashboardServiceProvider.php`

```php
class DashboardServiceProvider extends AbstractServiceProvider
{
    protected string $module = 'dashboard';
}
```

This package extends `Bongo\Framework\Providers\AbstractServiceProvider` which automatically registers:
- Routes from `src/Routes/backend.php` → mounted at `/admin` with `auth` + `employee` middleware
- Views from `src/Views/` → accessible as `dashboard::backend.index`
- Translations from `src/Translations/` → accessible as `dashboard::backend.index`

### Controller Architecture

**File**: `src/Http/Controllers/Backend/DashboardController.php`

- **Extends**: `Bongo\Framework\Http\Controllers\AbstractController`
- **Purpose**: Renders the main dashboard view
- **Key Method**: `index()` - returns the dashboard view with `$packages` data

```php
public function index()
{
    return view('dashboard::backend.index');
}
```

**Note**: The `$packages` variable is provided by the framework/middleware and contains registered admin packages.

### Routes

**File**: `src/Routes/backend.php`

```php
Route::get('/', [DashboardController::class, 'index'])->name('index');
```

This registers as `backend.dashboard.index` route at `/admin`.

### View Components

#### Main Dashboard View
**File**: `src/Views/backend/index.blade.php`

- Extends `framework::backend.layouts.app`
- Displays page title and actions (website link, quick-create dropdown)
- Renders package widgets in a responsive grid (2 cols mobile, 4 cols desktop)
- Uses `blade::` components for consistent UI

#### Widget Partial
**File**: `src/Views/backend/partials/widget.blade.php`

- Renders individual package link as a card
- Displays package icon (if available) and name
- Links to package index route

#### Quick Create Partial
**File**: `src/Views/backend/partials/quick_create.blade.php`

- Renders dropdown item for quick-creating package records
- Only shown if package has a `.create` route
- Uses alternating styling and dividers

## Coding Conventions

### PHP Standards
- **PHP Version**: 8.2+
- **Laravel Version**: 10+
- **Namespace**: `Bongo\Dashboard`
- **Code Style**: Laravel Pint (PSR-12 with Laravel preset)
- **Type Declarations**: Always use strict types, return types required
- **Controllers**: Extend `AbstractController` from bongo/framework

### Naming Conventions
- Controllers: Singular name + `Controller` suffix (e.g., `DashboardController`)
- Views: Kebab-case (e.g., `index.blade.php`, `quick_create.blade.php`)
- Routes: Named routes using `name()` method
- Translations: Namespaced with package name (e.g., `dashboard::backend.index`)

### View Conventions
- Use `@extends('framework::backend.layouts.app')` for backend layouts
- Use `blade::` components for UI elements (buttons, forms, icons)
- Translation keys: `dashboard::backend.{key}`
- View namespace: `dashboard::{path}`

## Common Tasks

### Adding a New Dashboard Feature

1. **Modify the controller** (`src/Http/Controllers/Backend/DashboardController.php`):
   ```php
   public function index()
   {
       // Add custom data fetching logic here
       $customData = $this->fetchCustomData();

       return view('dashboard::backend.index', compact('customData'));
   }
   ```

2. **Update the view** (`src/Views/backend/index.blade.php`):
   ```blade
   @component('blade::content_body')
       <!-- Add new dashboard section here -->
   @endcomponent
   ```

3. **Add translations** (`src/Translations/en/backend.php`):
   ```php
   return [
       'new_feature' => 'New Feature Label',
   ];
   ```

### Modifying Widget Display

Edit `src/Views/backend/partials/widget.blade.php` to customize:
- Widget styling (Tailwind classes)
- Icon display logic
- Link behaviour

### Customizing Quick Create Dropdown

Edit `src/Views/backend/partials/quick_create.blade.php` to customize:
- Dropdown item layout
- Icon rendering
- Filtering logic (currently excludes 'Settings')

## Testing

### Running Tests

```bash
# Run all tests
vendor/bin/phpunit

# Run specific test
vendor/bin/phpunit --filter TestName

# Run with coverage
vendor/bin/phpunit --coverage-html coverage
```

### Test Structure

- **TestCase**: Extends Orchestra Testbench for package testing
- **Service Provider**: Automatically registered in test environment
- Tests should be added to `tests/Feature/` or `tests/Unit/`

### Writing Tests

```php
namespace Bongo\Dashboard\Tests\Feature;

use Bongo\Dashboard\Tests\TestCase;

class DashboardTest extends TestCase
{
    /** @test */
    public function it_displays_the_dashboard()
    {
        $response = $this->get(route('backend.dashboard.index'));
        $response->assertStatus(200);
    }
}
```

## Available Commands

```bash
# Install dependencies
composer install

# Run tests
vendor/bin/phpunit

# Fix code style
vendor/bin/pint

# Check code style
vendor/bin/pint --test

# Update dependencies
rm -f composer.lock && composer update -W
```

## Dependencies

### Required
- `php` >= 8.2
- `illuminate/contracts` ^10.0
- `bongo/framework` ^3.0 (provides AbstractServiceProvider, AbstractController)

### Dev Dependencies
- `laravel/pint` - Code style fixer
- `phpunit/phpunit` - Testing framework
- `orchestra/testbench` - Laravel package testing
- `nunomaduro/larastan` - Static analysis

## Integration with Bongo Framework

This package relies heavily on `bongo/framework`:

1. **AbstractServiceProvider**: Auto-registers routes, views, translations
2. **AbstractController**: Base controller with common functionality
3. **Backend Layout**: Uses `framework::backend.layouts.app`
4. **Blade Components**: Uses `blade::` components for UI elements
5. **Package Registration**: Framework provides `$packages` variable to views

## Key Concepts

### Package Registration System

The dashboard dynamically displays all packages registered with the Bongo framework. Each package provides:
- `name` - Display name
- `route` - Route prefix for links
- `url` - Index URL
- `icon` - Icon identifier (optional)

The framework injects this `$packages` array into the dashboard view.

### Route Structure

This package registers **only backend routes**:
- Mounted at `/admin` prefix
- Protected by `auth` + `employee` middleware
- Single route: `backend.dashboard.index` → `/admin`

### View Composition

The dashboard uses a component-based view structure:
- `@component('blade::content_header')` - Page header with title and actions
- `@component('blade::content_body')` - Main content wrapper
- `@include()` - Partials for widgets and quick-create items

## Notes

- This is a **presentation-only package** - no models, migrations, or data persistence
- The `$packages` variable is provided by the framework, not fetched in the controller
- Widget display is automatic based on package registration
- Quick-create dropdown filters out packages without `.create` routes
- Icons are optional and loaded from `blade::icons.{icon_name}`
