orion/docs/frontend/shared/sidebar.md

# Admin Sidebar Navigation

## Overview

The admin sidebar provides navigation across all admin pages. It features collapsible sections with state persistence, active page indicators, and responsive mobile support.

**File Location:** `app/templates/admin/partials/sidebar.html`

---

## Sidebar Structure

The sidebar is organized into the following sections:

| Section | Collapsible | Pages |
|---------|-------------|-------|
| Dashboard | No | Dashboard |
| Platform Administration | Yes | Merchants, Stores, Users, Customers |
| Product Catalog | Yes | Marketplace Products, Store Products, Import |
| Content Management | Yes | Platform Homepage, Content Pages, Store Themes |
| Developer Tools | Yes | Components, Icons |
| Platform Health | Yes | Testing Hub, Code Quality, Background Tasks |
| Platform Monitoring | Yes | Import Jobs, Application Logs |
| Settings | Yes | General, Profile, API Keys, Notifications |

---

## Collapsible Sections

### How It Works

Sections can be expanded/collapsed by clicking the section header. The state is persisted to `localStorage` so sections remain open/closed across page navigation and browser sessions.

### State Management

**File:** `static/admin/js/init-alpine.js`

```javascript
// Default state: Platform Administration open, others closed
const defaultSections = {
    platformAdmin: true,
    productCatalog: false,
    contentMgmt: false,
    devTools: false,
    platformHealth: false,
    monitoring: false,
    settingsSection: false
};

// State stored in localStorage under this key
const SIDEBAR_STORAGE_KEY = 'admin_sidebar_sections';
```

### Available Methods

| Method | Description |
|--------|-------------|
| `toggleSection(section)` | Toggle a section open/closed |
| `expandSectionForCurrentPage()` | Auto-expand section containing current page |
| `openSections.platformAdmin` | Check if Platform Administration is open |
| `openSections.productCatalog` | Check if Product Catalog is open |
| `openSections.contentMgmt` | Check if Content Management is open |
| `openSections.devTools` | Check if Developer Tools is open |
| `openSections.platformHealth` | Check if Platform Health is open |
| `openSections.monitoring` | Check if Platform Monitoring is open |
| `openSections.settingsSection` | Check if Settings is open |

### CSS Transitions

Sections animate smoothly using CSS transitions (no plugins required):

```html
<ul
    x-show="openSections.platformAdmin"
    x-transition:enter="transition-all duration-200 ease-out"
    x-transition:enter-start="opacity-0 -translate-y-2"
    x-transition:enter-end="opacity-100 translate-y-0"
    x-transition:leave="transition-all duration-150 ease-in"
    x-transition:leave-start="opacity-100 translate-y-0"
    x-transition:leave-end="opacity-0 -translate-y-2"
    class="mt-1 overflow-hidden"
>
```

### Chevron Icon Rotation

The chevron icon rotates 180 degrees when a section is expanded:

```html
<span
    x-html="$icon('chevron-down', 'w-4 h-4 transition-transform duration-200')"
    :class="{ 'rotate-180': openSections.platformAdmin }"
></span>
```

---

## Page-to-Section Mapping

Pages are mapped to their parent sections for auto-expansion:

```javascript
const pageSectionMap = {
    // Platform Administration
    merchants: 'platformAdmin',
    stores: 'platformAdmin',
    users: 'platformAdmin',
    customers: 'platformAdmin',
    // Product Catalog
    'marketplace-products': 'productCatalog',
    'store-products': 'productCatalog',
    marketplace: 'productCatalog',
    // Content Management
    'platform-homepage': 'contentMgmt',
    'content-pages': 'contentMgmt',
    'store-theme': 'contentMgmt',
    // Developer Tools
    components: 'devTools',
    icons: 'devTools',
    // Platform Health
    testing: 'platformHealth',
    'code-quality': 'platformHealth',
    'background-tasks': 'platformHealth',
    // Platform Monitoring
    imports: 'monitoring',
    logs: 'monitoring',
    // Settings
    settings: 'settingsSection',
    profile: 'settingsSection',
    'api-keys': 'settingsSection',
    'notifications-settings': 'settingsSection'
};
```

---

## Complete Page Mapping

| Page | `currentPage` Value | Section | URL |
|------|---------------------|---------|-----|
| Dashboard | `'dashboard'` | (always visible) | `/admin/dashboard` |
| Merchants | `'merchants'` | Platform Administration | `/admin/merchants` |
| Stores | `'stores'` | Platform Administration | `/admin/stores` |
| Users | `'users'` | Platform Administration | `/admin/users` |
| Customers | `'customers'` | Platform Administration | `/admin/customers` |
| Marketplace Products | `'marketplace-products'` | Product Catalog | `/admin/marketplace-products` |
| Store Products | `'store-products'` | Product Catalog | `/admin/store-products` |
| Import | `'marketplace'` | Product Catalog | `/admin/marketplace` |
| Platform Homepage | `'platform-homepage'` | Content Management | `/admin/platform-homepage` |
| Content Pages | `'content-pages'` | Content Management | `/admin/content-pages` |
| Store Themes | `'store-theme'` | Content Management | `/admin/store-themes` |
| Components | `'components'` | Developer Tools | `/admin/components` |
| Icons | `'icons'` | Developer Tools | `/admin/icons` |
| Testing Hub | `'testing'` | Platform Health | `/admin/testing` |
| Code Quality | `'code-quality'` | Platform Health | `/admin/code-quality` |
| Background Tasks | `'background-tasks'` | Platform Health | `/admin/background-tasks` |
| Import Jobs | `'imports'` | Platform Monitoring | `/admin/imports` |
| Application Logs | `'logs'` | Platform Monitoring | `/admin/logs` |
| General Settings | `'settings'` | Settings | `/admin/settings` |
| Profile | `'profile'` | Settings | `/admin/profile` |
| API Keys | `'api-keys'` | Settings | `/admin/api-keys` |
| Notifications | `'notifications-settings'` | Settings | `/admin/notifications-settings` |

---

## Active Page Indicator

Each menu item shows a purple vertical bar when active:

```html
<li class="relative px-6 py-3">
    <!-- Purple bar indicator (shows when page is active) -->
    <span x-show="currentPage === 'stores'"
          class="absolute inset-y-0 left-0 w-1 bg-purple-600 rounded-tr-lg rounded-br-lg"
          aria-hidden="true"></span>

    <!-- Link with active text styling -->
    <a class="inline-flex items-center w-full text-sm font-semibold transition-colors duration-150 hover:text-gray-800 dark:hover:text-gray-200"
       :class="currentPage === 'stores' ? 'text-gray-800 dark:text-gray-100' : ''"
       href="/admin/stores">
        <span x-html="$icon('shopping-bag')"></span>
        <span class="ml-4">Stores</span>
    </a>
</li>
```

### Setting currentPage in Components

Each page component must set `currentPage` to match the sidebar:

```javascript
function adminStores() {
    return {
        ...data(),                    // Inherit base (includes openSections)
        currentPage: 'stores',       // Must match sidebar check
        // ... rest of component
    };
}
```

---

## Jinja2 Macros

The sidebar uses Jinja2 macros for DRY code:

### section_header

Creates a collapsible section header with chevron:

```jinja2
{% macro section_header(title, section_key) %}
<button
    @click="toggleSection('{{ section_key }}')"
    class="flex items-center justify-between w-full px-6 py-2 ..."
>
    <span>{{ title }}</span>
    <span x-html="$icon('chevron-down', '...')"
          :class="{ 'rotate-180': openSections.{{ section_key }} }"></span>
</button>
{% endmacro %}
```

### section_content

Wraps section items with collapse animation:

```jinja2
{% macro section_content(section_key) %}
<ul x-show="openSections.{{ section_key }}" x-transition:...>
    {{ caller() }}
</ul>
{% endmacro %}
```

### menu_item

Creates a menu item with active indicator:

```jinja2
{% macro menu_item(page_id, url, icon, label) %}
<li class="relative px-6 py-3">
    <span x-show="currentPage === '{{ page_id }}'" class="..."></span>
    <a href="{{ url }}">
        <span x-html="$icon('{{ icon }}')"></span>
        <span class="ml-4">{{ label }}</span>
    </a>
</li>
{% endmacro %}
```

### Usage Example

```jinja2
{{ section_header('Platform Administration', 'platformAdmin') }}
{% call section_content('platformAdmin') %}
    {{ menu_item('merchants', '/admin/merchants', 'office-building', 'Merchants') }}
    {{ menu_item('stores', '/admin/stores', 'shopping-bag', 'Stores') }}
{% endcall %}
```

---

## Adding a New Page

### Step 1: Add Route

Add the route in `app/routes/admin_pages.py`:

```python
@router.get("/new-page", response_class=HTMLResponse, include_in_schema=False)
async def admin_new_page(
    request: Request,
    current_user: User = Depends(get_current_admin_from_cookie_or_header),
):
    return templates.TemplateResponse(
        "admin/new-page.html",
        {"request": request, "user": current_user},
    )
```

### Step 2: Create Template

Create `app/templates/admin/new-page.html`:

```jinja2
{% extends "admin/base.html" %}
{% block title %}New Page{% endblock %}
{% block alpine_data %}adminNewPage(){% endblock %}
{% block content %}
    <!-- Your content -->
{% endblock %}
```

### Step 3: Create JavaScript Component

Create `static/admin/js/new-page.js`:

```javascript
function adminNewPage() {
    return {
        ...data(),
        currentPage: 'new-page',  // Must match sidebar
        // ...
    };
}
```

### Step 4: Add to Sidebar

Edit `app/templates/admin/partials/sidebar.html`:

```jinja2
{# Add to appropriate section #}
{{ menu_item('new-page', '/admin/new-page', 'icon-name', 'New Page') }}
```

### Step 5: Update Page-Section Map (if in collapsible section)

Edit `static/admin/js/init-alpine.js`:

```javascript
const pageSectionMap = {
    // ... existing mappings
    'new-page': 'platformAdmin',  // Add mapping
};
```

---

## Mobile Sidebar

The sidebar has a mobile version that slides in from the left:

- **Toggle:** Click hamburger menu in header
- **Close:** Click outside, press Escape, or navigate
- **State:** Controlled by `isSideMenuOpen`

```javascript
// In base data()
isSideMenuOpen: false,
toggleSideMenu() {
    this.isSideMenuOpen = !this.isSideMenuOpen
},
closeSideMenu() {
    this.isSideMenuOpen = false
}
```

---

## Testing Checklist

- [ ] Sections expand/collapse on header click
- [ ] Chevron rotates when section opens/closes
- [ ] Section state persists after page reload
- [ ] Section state persists across different pages
- [ ] Active page shows purple bar indicator
- [ ] Active page text is highlighted
- [ ] Mobile sidebar opens/closes correctly
- [ ] Collapsible sections work on mobile
- [ ] All navigation links work correctly