MyClub/DOCS/ENHANCED_NAVIGATION_SYSTEM.md

# Enhanced Navigation Management System

## Overview

The navigation system has been completely rebuilt with advanced features for managing complex, hierarchical navigation structures. It now supports unlimited levels of dropdown menus, custom pages, and dynamic navigation from database.

## Key Features

### 🎨 **Admin Interface**
- **Card-based layout** with visual hierarchy
- **Expandable/collapsible** navigation items
- **Drag-and-drop reordering** (up/down buttons)
- **Visual indicators** for item type, visibility, and children count
- **Nested item management** - add sub-items to dropdown menus
- **Real-time preview** of navigation structure

### 🔧 **Navigation Types**
1. **Page** - Links to existing pages (Blog, Calendar, etc.)
2. **Internal** - Custom internal URLs (/custom-page)
3. **External** - Links to external websites
4. **Dropdown** - Container for sub-navigation items

### 🌳 **Hierarchical Structure**
- **Parent-child relationships** - Unlimited nesting
- **Dropdown menus** - Hover to reveal sub-items
- **Visual indentation** in admin panel
- **Automatic URL resolution** for page types

### 📱 **Frontend Integration**
- **Dynamic loading** from API
- **Automatic fallback** to hardcoded navigation if API fails
- **Mobile-responsive** - Different layouts for mobile/desktop
- **Hover menus** on desktop, expandable lists on mobile

## Usage Guide

### Accessing the Admin Panel

Navigate to `/admin` → **Navigace** to manage navigation items.

### Creating Navigation Items

#### 1. Add a Standard Page Link
```
Label: Články
Type: Page
Page: blog (/blog)
Visible: Yes
```

#### 2. Add a Custom Internal Link
```
Label: Naše Historie
Type: Internal
URL: /nase-historie
Visible: Yes
```

#### 3. Add an External Link
```
Label: Facebook Page
Type: External
URL: https://facebook.com/yourpage
Target: New Window (_blank)
Visible: Yes
```

#### 4. Create a Dropdown Menu
```
Label: Týmy
Type: Dropdown
Visible: Yes
```

Then click "Přidat podpoložku" to add child items:
```
Parent: Týmy
Label: A-tým
Type: Page
Page: players (/hraci)
```

### Reordering Items

Use the **up/down arrow buttons** on each card to change the order. Changes are saved immediately.

### Managing Visibility

Toggle the **Viditelné** (Visible) switch to hide items without deleting them. Hidden items appear grayed out in the admin panel.

### Navigation Item Properties

| Property | Description | Required |
|----------|-------------|----------|
| **Label** | Display name in navigation | Yes |
| **Type** | Page, Internal, External, or Dropdown | Yes |
| **Page Type** | Pre-defined page to link to (for Page type) | Conditional |
| **URL** | Custom URL (for Internal/External types) | Conditional |
| **Target** | Open in same or new window (for External) | No |
| **Visible** | Show/hide in navigation | Yes |
| **Parent ID** | Parent item for nested navigation | No |
| **Description** | Admin notes (stored in css_class field) | No |

## Technical Architecture

### Database Schema

```sql
navigation_items (
    id SERIAL PRIMARY KEY,
    label VARCHAR(255) NOT NULL,
    url TEXT,
    type VARCHAR(50) NOT NULL, -- 'internal', 'external', 'dropdown', 'page'
    page_type VARCHAR(100), -- 'home', 'blog', 'calendar', etc.
    visible BOOLEAN DEFAULT true,
    display_order INTEGER DEFAULT 0,
    parent_id INTEGER REFERENCES navigation_items(id),
    target VARCHAR(20) DEFAULT '_self',
    css_class VARCHAR(255), -- Used for admin description
    ...
)
```

### API Endpoints

#### Public Endpoints
- `GET /api/v1/navigation` - Get visible navigation items with children
- `GET /api/v1/social-links` - Get visible social media links

#### Admin Endpoints
- `GET /api/v1/admin/navigation` - Get all navigation items (including hidden)
- `POST /api/v1/admin/navigation` - Create new navigation item
- `PUT /api/v1/admin/navigation/:id` - Update navigation item
- `DELETE /api/v1/admin/navigation/:id` - Delete navigation item
- `POST /api/v1/admin/navigation/reorder` - Reorder multiple items

### Frontend Components

#### NavigationAdminPage
- Location: `frontend/src/pages/admin/NavigationAdminPage.tsx`
- Features: Card-based management interface with expand/collapse
- Dependencies: Chakra UI, React Icons

#### Navbar
- Location: `frontend/src/components/Navbar.tsx`
- Features: Dynamic navigation loading, hover dropdowns, mobile responsive
- Fallback: Hardcoded navigation if API fails

#### NavItemCard
- Component for displaying individual navigation items in admin
- Supports nested rendering with indentation
- Shows badges for type, visibility, and child count

## Page Type URLs

Default mapping of page types to URLs:

| Page Type | URL | Description |
|-----------|-----|-------------|
| home | / | Homepage |
| about | /o-klubu | About page |
| calendar | /kalendar | Event calendar |
| matches | /zapasy | Match schedule |
| activities | /aktivity | Club activities |
| players | /hraci | Player roster |
| tables | /tabulky | League tables |
| blog | /blog | Articles/News |
| videos | /videa | Video gallery |
| gallery | /galerie | Photo gallery |
| sponsors | /sponzori | Sponsors page |
| contact | /kontakt | Contact page |
| search | /hledat | Search page |

## Migration Guide

### From Hardcoded to Dynamic Navigation

The system automatically creates default navigation items on first migration. To customize:

1. **Log in as admin** and navigate to Navigation management
2. **Review default items** - they match your current hardcoded nav
3. **Reorder, hide, or modify** items as needed
4. **Add custom items** for new pages or external links
5. **Create dropdowns** for categorized navigation

### Backward Compatibility

If navigation API fails or returns empty:
- Navbar falls back to hardcoded navigation
- No visual disruption to users
- Admin panel shows loading state

### Settings Integration

Custom navigation from `settings.custom_nav` is still supported as fallback. To migrate to database navigation:

1. Create equivalent items in Navigation admin
2. Test thoroughly
3. Remove `custom_nav` from settings

## Best Practices

### 🎯 Navigation Structure

- **Keep it simple** - Max 7-9 top-level items
- **Group related pages** - Use dropdowns for categories
- **Logical ordering** - Most important pages first
- **Descriptive labels** - Clear, concise names

### 🔒 Performance

- Navigation is **cached** on frontend after first load
- Changes require **page refresh** to take effect
- API response includes all children in single request

### ♿ Accessibility

- Proper **ARIA labels** on all buttons
- **Keyboard navigation** support
- **Screen reader friendly** text and structure

### 📱 Mobile Considerations

- Dropdowns expand as nested lists on mobile
- Touch-friendly buttons and spacing
- Collapsed by default to save space

## Troubleshooting

### Navigation not updating
- Check API connectivity
- Verify admin permissions
- Clear browser cache and refresh

### Dropdown not working
- Ensure parent item type is "dropdown"
- Check child items are properly linked (parent_id)
- Verify children are visible

### Items out of order
- Use up/down buttons to reorder
- display_order is automatically managed
- Refresh page after reordering

### Missing pages
- Check visibility toggle
- Verify user permissions (requires_auth, requires_admin)
- Confirm page_type matches existing route

## Future Enhancements

Potential improvements for future versions:

- **Drag-and-drop** reordering with library like dnd-kit
- **Icon picker** for custom icons on nav items
- **Permissions** - Show different nav to logged-in users
- **A/B testing** - Multiple navigation configurations
- **Analytics** - Track which nav items are clicked
- **Bulk operations** - Import/export navigation config
- **Preview mode** - See navigation changes before publishing

## Support

For issues or questions:
- Check this documentation first
- Review code comments in NavigationAdminPage.tsx
- Check browser console for API errors
- Verify database migrations are up to date

---

**Version:** 1.0  
**Last Updated:** October 2025  
**Status:** Production Ready ✅