# Layout Components

This directory contains the core layout and navigation components for the Black Canyon Tickets React rebuild.

## Components Overview

### AppLayout
The main application layout component that provides the overall structure for authenticated pages.

**Features:**
- Responsive sidebar with mobile overlay
- Header with breadcrumbs and user menu  
- Main content area with optional title/subtitle/actions
- Skip-to-content link for accessibility
- Keyboard navigation support
- Mobile-first responsive design

**Usage:**
```tsx
import { AppLayout } from './components/layout/AppLayout';

<AppLayout 
  title="Dashboard" 
  subtitle="Overview of your events and performance"
  actions={<Button>Create Event</Button>}
>
  <YourPageContent />
</AppLayout>
```

**Props:**
- `children: React.ReactNode` - Page content
- `title?: string` - Page title (optional)
- `subtitle?: string` - Page subtitle (optional)  
- `actions?: React.ReactNode` - Action buttons for page header (optional)

### Header
Top navigation bar with glassmorphism styling.

**Features:**
- Mobile hamburger menu toggle
- Breadcrumb navigation based on current route
- Theme toggle button (light/dark)
- User menu dropdown with profile and logout
- Responsive design with mobile-friendly interactions

**Props:**
- `onToggleSidebar: () => void` - Function to toggle mobile sidebar
- `sidebarCollapsed: boolean` - Whether desktop sidebar is collapsed

### Sidebar
Collapsible navigation menu with keyboard support.

**Features:**
- Navigation items with active state highlighting
- Collapsible for desktop (icon-only mode)
- Mobile overlay with close button
- User profile section at bottom
- Keyboard navigation (arrow keys, home/end)
- ARIA landmarks and screen reader support

**Navigation Items:**
- Dashboard (/)
- Events (/events)
- Tickets (/tickets)
- Customers (/customers)
- Analytics (/analytics)
- Settings (/settings)

**Props:**
- `collapsed: boolean` - Whether sidebar is collapsed (desktop)
- `onToggleCollapse: () => void` - Function to toggle collapse state
- `onCloseMobile: () => void` - Function to close mobile sidebar

### MainContainer
Content wrapper that provides consistent spacing and optional page header.

**Features:**
- Responsive padding and margins
- Optional page title and subtitle
- Action button area
- Maximum width constraint for readability

**Props:**
- `children: React.ReactNode` - Page content
- `title?: string` - Page title (optional)
- `subtitle?: string` - Page subtitle (optional)
- `actions?: React.ReactNode` - Action buttons (optional)
- `className?: string` - Additional CSS classes (optional)

## Design System Integration

All layout components use the established design token system:

### Colors
- Uses CSS variables from `src/styles/tokens.css`
- Supports both light and dark themes
- Gold accent color for branding (`--color-gold-*`)
- Slate color palette for neutral elements

### Spacing
- Consistent spacing using design tokens (`--spacing-*`)
- Responsive padding and margins
- Mobile-first approach with progressive enhancement

### Glassmorphism Effects
- Backdrop blur for navigation elements
- Semi-transparent backgrounds
- Subtle border and shadow effects
- Premium aesthetic for upscale venues

## Accessibility Features

### Keyboard Navigation
- Tab order follows logical flow
- Arrow key navigation in sidebar menu
- Escape key closes mobile overlays
- Enter/Space activates buttons and links

### Screen Reader Support
- ARIA landmarks (banner, navigation, main)
- ARIA expanded/current states for dynamic elements
- Skip-to-content link for keyboard users
- Proper heading hierarchy

### Focus Management
- Visible focus indicators
- Focus trap in mobile sidebar
- Logical tab order
- Custom focus styles using design tokens

## Responsive Breakpoints

### Mobile (< 768px)
- Sidebar hidden by default with overlay when open
- Header with hamburger menu
- Stacked layout for content
- Touch-friendly interactive elements

### Tablet (768px - 1024px)
- Sidebar overlay when open
- Breadcrumbs visible
- Two-column layouts where appropriate

### Desktop (1024px+)
- Persistent sidebar with collapse option
- Full breadcrumb navigation
- Multi-column layouts
- Hover states for interactive elements

## Usage Examples

### Basic Layout
```tsx
function DashboardPage() {
  return (
    <AppLayout title="Dashboard" subtitle="Overview of your performance">
      <div className="space-y-8">
        {/* Your dashboard content */}
      </div>
    </AppLayout>
  );
}
```

### Layout with Actions
```tsx
function EventsPage() {
  return (
    <AppLayout 
      title="Events" 
      subtitle="Manage your upcoming events"
      actions={
        <Button variant="primary">
          <Plus className="h-5 w-5 mr-2" />
          Create Event
        </Button>
      }
    >
      <EventsList />
    </AppLayout>
  );
}
```

### Standalone Components
```tsx
// Using individual components
<div className="min-h-screen bg-gradient-to-br from-slate-50 to-slate-100">
  <Header onToggleSidebar={toggleSidebar} sidebarCollapsed={false} />
  <div className="flex">
    <Sidebar 
      collapsed={false}
      onToggleCollapse={() => {}}
      onCloseMobile={() => {}}
    />
    <main className="flex-1">
      <MainContainer title="Custom Layout">
        <YourContent />
      </MainContainer>
    </main>
  </div>
</div>
```

## Performance Considerations

### Code Splitting
Components use dynamic imports where appropriate to reduce initial bundle size.

### Re-render Optimization
- Uses React.memo for expensive components
- Proper dependency arrays in useEffect hooks
- Minimal state updates to prevent cascading re-renders

### Mobile Performance
- Touch events are optimized for responsiveness
- Animations use CSS transforms (not layout properties)
- Backdrop blur effects are conditionally applied

## Browser Support

### Modern Browsers
- Chrome 90+
- Firefox 88+
- Safari 14+
- Edge 90+

### Fallbacks
- Backdrop blur gracefully degrades
- CSS Grid falls back to Flexbox
- JavaScript features use polyfills where needed

## Contributing

When modifying layout components:

1. **Maintain accessibility** - Test with keyboard and screen readers
2. **Follow design tokens** - Use CSS variables, not hardcoded values
3. **Test responsiveness** - Verify on mobile, tablet, and desktop
4. **Update documentation** - Keep this README current
5. **Performance testing** - Ensure no layout thrashing or unnecessary re-renders

## Known Issues

### Current Limitations
- User authentication is mocked (displays placeholder data)
- Navigation state is not persisted across page refreshes
- Some animations may not perform well on low-end devices

### Future Enhancements
- Add breadcrumb customization options
- Implement notification center in header
- Add search functionality to header
- Support for nested navigation menus