# Admin Aside Navigation Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Rebuild the admin aside into permission-aware collapsible operational sections with responsive UX and preserved active navigation behavior.

**Architecture:** Keep the shared sidebar component as the rendering entry point because both admin layouts already use it. Restructure only the admin menu data and admin section renderer while retaining student, instructor, and finance menu behavior. Feature tests verify sidebar structure, RBAC visibility, and existing scroll behavior before and after the Blade change.

**Tech Stack:** Laravel 12, Blade, Alpine.js, TailwindCSS 4, Spatie permissions, PHPUnit feature tests.

---

### Task 1: Lock Sidebar Behavior With Tests

**Files:**
- Modify: `tests/Feature/Admin/AdminSidebarScrollTest.php`

- [ ] **Step 1: Add a failing test for collapsible domain sections**

```php
public function test_admin_sidebar_groups_navigation_into_collapsible_domains(): void
{
    $admin = User::factory()->create(['role' => 'admin']);
    $admin->assignRole('admin');

    $this->actingAs($admin)
        ->get(route('admin.dashboard'))
        ->assertOk()
        ->assertSee('data-admin-nav-section="admissions"', false)
        ->assertSee('data-admin-nav-section="training"', false)
        ->assertSee(__('admin_nav.section_admissions'))
        ->assertSee(__('admin_nav.section_training'));
}
```

- [ ] **Step 2: Add a failing RBAC visibility test**

```php
public function test_registration_user_sidebar_hides_finance_and_corporate_domains_without_permissions(): void
{
    $user = User::factory()->create(['role' => 'registration_officer']);
    $user->givePermissionTo('admin.dashboard.view', 'enrollments.view');

    $this->actingAs($user)
        ->get(route('admin.registrations'))
        ->assertOk()
        ->assertDontSee(__('admin_nav.section_finance'))
        ->assertDontSee(__('admin_nav.corporate_invoices'));
}
```

- [ ] **Step 3: Run the test and confirm the new assertions fail**

Run: `DB_CONNECTION=sqlite DB_DATABASE=:memory: php artisan test tests/Feature/Admin/AdminSidebarScrollTest.php --stop-on-failure`

Expected: failure because the existing sidebar has no new domain-section markers.

### Task 2: Restructure Admin Menu Data And Translations

**Files:**
- Modify: `resources/views/components/portal/sidebar.blade.php`
- Modify: `lang/ar/admin_nav.php`
- Modify: `lang/fr/admin_nav.php`

- [ ] **Step 1: Add section translation keys**

```php
'section_main' => 'الرئيسية',
'section_admissions' => 'التسجيلات والطلاب',
'section_training' => 'إدارة التكوين',
'section_corporate' => 'المؤسسات',
'section_finance' => 'المالية',
'section_communication' => 'التواصل والمحتوى',
'section_security' => 'الأمان والنظام',
```

- [ ] **Step 2: Rebuild `$adminItems` into the approved sections**

Use permission checks on every admin link, filter null links, and omit sections with no visible links.

- [ ] **Step 3: Preserve legacy menu types**

Do not alter `$financeItems`, `$instructorItems`, or `$studentItems` except where shared rendering requires backward-compatible defaults.

### Task 3: Add Collapsible Section Rendering

**Files:**
- Modify: `resources/views/components/portal/sidebar.blade.php`

- [ ] **Step 1: Add Alpine state for per-section open state**

Initialize sections with active sections open and main domain open by default.

- [ ] **Step 2: Render section header buttons**

Buttons expose the section label, active state, arrow rotation, and section marker such as `data-admin-nav-section="training"`.

- [ ] **Step 3: Keep icon-only collapsed sidebar usable**

Collapsed desktop state must show links without broken section headings, horizontal overflow, or missing tooltips.

### Task 4: Verify

**Files:**
- Verify: `tests/Feature/Admin/AdminSidebarScrollTest.php`

- [ ] **Step 1: Run focused tests**

Run: `DB_CONNECTION=sqlite DB_DATABASE=:memory: php artisan test tests/Feature/Admin/AdminSidebarScrollTest.php --stop-on-failure`

- [ ] **Step 2: Run related sidebar and RBAC smoke tests**

Run: `DB_CONNECTION=sqlite DB_DATABASE=:memory: php artisan test tests/Feature/Admin/AdminSidebarScrollTest.php tests/Feature/Security/RbacAccessTest.php --stop-on-failure`

- [ ] **Step 3: Clear compiled views**

Run: `php artisan view:clear`