upskill-event-manager/docs/WELCOME-POPUP-SYSTEM.md

# HVAC Welcome Popup System Documentation

## Overview

The Welcome Popup System provides a guided onboarding experience for new HVAC trainers, introducing them to platform features through an interactive carousel modal. The system respects user account status and provides accessibility-compliant navigation.

**Version**: 1.0.6  
**Status**: ✅ Complete  
**Deployed**: 2025-08-05

## Features

### 🎯 Core Functionality

- **Interactive Carousel**: 4-card slideshow introducing platform features
- **Account Status Filtering**: Only shows to approved users
- **Accessibility Compliant**: WCAG 2.1 AA standards
- **Responsive Design**: Works on desktop, tablet, and mobile
- **Dismissal Management**: "Don't show this again" functionality
- **WordPress Integration**: Proper theme colors and button styling

### 📱 User Experience

#### Content Structure
1. **Welcome Card**: Platform introduction with 4 key benefits
2. **Events Card**: Event management features (3 key points)
3. **Profile Card**: Trainer profile and visibility features (4 key points)  
4. **Features Card**: Reporting and analytics capabilities (3 key points)

#### Navigation
- **Arrow Buttons**: Previous/Next navigation
- **Dot Indicators**: Direct card access
- **Keyboard Support**: Tab navigation and ESC to close
- **Touch Support**: Mobile-friendly controls

## Technical Implementation

### 🏗️ Architecture

```
includes/class-hvac-welcome-popup.php    # Main popup logic
assets/css/hvac-welcome-popup.css        # Styling and layout
assets/js/hvac-welcome-popup.js          # JavaScript functionality
```

### 🎨 Styling System

#### Layout Structure
```css
.hvac-welcome-popup                    # Full-screen overlay
  .hvac-welcome-modal                  # Main modal container
    .hvac-welcome-content              # Content wrapper
      .hvac-welcome-carousel           # Carousel container
        .hvac-welcome-card             # Individual cards
      .hvac-welcome-navigation         # Navigation controls
      .hvac-welcome-footer             # Action buttons
```

#### Key CSS Specifications
- **Modal**: `max-width: 800px`, `max-height: 90vh`
- **Carousel**: `min-height: 460px` (desktop), responsive scaling
- **Navigation**: Proper spacing with `margin: 20px 0 50px`
- **Footer**: `z-index: 10` with white background
- **Colors**: Astra theme integration with CSS custom properties

### 🔒 Access Control

#### Account Status Logic
```php
private function user_can_see_popup() {
    // Admin users: Always show (for testing)
    if (current_user_can('manage_options')) return true;
    
    // Get account status via HVAC_Trainer_Status
    $account_status = HVAC_Trainer_Status::get_trainer_status($user_id);
    
    // Allow: approved, active, inactive users
    // Block: pending, disabled users
    $allowed_statuses = ['approved', 'active', 'inactive'];
    return in_array($account_status, $allowed_statuses);
}
```

#### Status Behavior Matrix
| Account Status | Popup Shown | Reason |
|---------------|-------------|---------|
| `pending` | ❌ No | Awaiting approval |
| `approved` | ✅ Yes | Account approved |
| `active` | ✅ Yes | Recently active |
| `inactive` | ✅ Yes | Approved but needs re-engagement |
| `disabled` | ❌ No | Account suspended |
| Admin | ✅ Yes | Testing/management |

### 📝 Content Management

#### Card Content
Each card contains:
- **Icon**: Dashicons integration
- **Title**: Main heading (32px, theme colors)
- **Subtitle**: Descriptive text
- **Bullet Points**: 3-4 key features with checkmarks
- **Note Section**: Additional context (card 1 only)

#### Dismissal System
- **User Meta**: `hvac_welcome_popup_dismissed`
- **AJAX Endpoints**: 
  - `hvac_check_welcome_dismissed`
  - `hvac_dismiss_welcome_popup`
- **Nonce Security**: `hvac_welcome_nonce`

## API Reference

### 🔌 AJAX Endpoints

#### Check Dismissal Status
```javascript
jQuery.post(ajaxurl, {
    action: 'hvac_check_welcome_dismissed',
    nonce: hvac_welcome.nonce
}, function(response) {
    // response.data.dismissed (boolean)
});
```

#### Dismiss Popup
```javascript
jQuery.post(ajaxurl, {
    action: 'hvac_dismiss_welcome_popup',
    nonce: hvac_welcome.nonce,
    dont_show_again: true
}, function(response) {
    // response.success (boolean)
});
```

### 🎛️ JavaScript API

#### Global Object
```javascript
window.HVACWelcomePopup = {
    showPopup(),
    hidePopup(),
    checkAndShowPopup(),
    nextCard(),
    prevCard(),
    goToCard(index)
}
```

#### Events
- `hvac:welcome:shown` - Popup displayed
- `hvac:welcome:dismissed` - Popup closed
- `hvac:welcome:card-changed` - Card navigation

## Accessibility Features

### ♿ WCAG 2.1 AA Compliance

#### Focus Management
- **Proper Tab Order**: Close → Navigation → Footer elements
- **Focus Indicators**: 2px blue outline on all interactive elements
- **Keyboard Navigation**: Arrow keys, Tab, Enter, ESC support

#### Touch Targets
- **Minimum Size**: 44px × 44px on mobile devices
- **Proper Spacing**: No overlapping clickable areas
- **Clear Boundaries**: Visual separation between elements

#### Screen Reader Support
- **ARIA Labels**: All navigation buttons properly labeled
- **Semantic HTML**: Proper heading hierarchy
- **Alternative Text**: Icons have descriptive labels

#### Motion Preferences
```css
@media (prefers-reduced-motion: reduce) {
    .hvac-welcome-modal,
    .hvac-welcome-card,
    .hvac-welcome-nav { 
        animation: none;
        transition: none;
    }
}
```

## Development History

### Version Timeline

#### v1.0.6 (2025-08-05) - ✅ **FINAL**
- **Fixed**: Navigation overlap with content
- **Improved**: Carousel height calculations
- **Enhanced**: Mobile responsive spacing
- **Status**: Production ready

#### v1.0.5 (2025-08-05)
- **Added**: Inactive users to allowed status list
- **Fixed**: Account status filtering logic

#### v1.0.4 (2025-08-05)
- **Changed**: From certification_status to account_status
- **Improved**: Status checking with HVAC_Trainer_Status class

#### v1.0.3 (2025-08-05)
- **Added**: Certification status filtering
- **Blocked**: Pending/disabled users from seeing popup

#### v1.0.2 (2025-08-05)
- **Fixed**: Accessibility overlapping elements
- **Added**: Proper z-index layering
- **Improved**: WCAG compliance

#### v1.0.1 (2025-08-05)
- **Reduced**: Bullet points from 5-6 to 3-4 per card
- **Added**: Astra theme integration
- **Fixed**: Overflow scrolling behavior

#### v1.0.0 (2025-08-05)
- **Created**: Initial welcome popup system
- **Implemented**: 4-card carousel design
- **Added**: Basic dismiss functionality

## Testing & Quality Assurance

### 🧪 Test Coverage

#### Automated Tests
- **File**: `tests/e2e/welcome-popup-visual-verification.test.ts`
- **Coverage**: Element positioning, interaction, responsiveness
- **Screenshots**: Automated visual verification

#### Manual Testing Checklist
- [ ] Popup appears for approved users
- [ ] Popup blocked for pending/disabled users
- [ ] Navigation works on all devices
- [ ] Footer elements fully clickable
- [ ] Hard refresh shows updated styles
- [ ] Dismiss functionality works
- [ ] Account status filtering accurate

#### Browser Compatibility
- ✅ Chrome 90+
- ✅ Firefox 85+
- ✅ Safari 14+
- ✅ Edge 90+
- ✅ Mobile browsers (iOS/Android)

### 🔧 Troubleshooting

#### Common Issues

**Popup not showing for approved users**
```bash
# Check user account status
wp eval "echo get_user_meta(USER_ID, 'account_status', true);"

# Reset dismissal
wp eval "delete_user_meta(USER_ID, 'hvac_welcome_popup_dismissed');"
```

**Navigation still overlapping**
```bash
# Force cache clear and hard refresh
wp cache flush
# Browser: Ctrl+Shift+R
```

**Styling not loading**
```bash
# Check CSS file exists
ls -la wp-content/plugins/hvac-community-events/assets/css/hvac-welcome-popup.css

# Verify version in file header
head -10 wp-content/plugins/hvac-community-events/assets/css/hvac-welcome-popup.css
```

## Configuration

### 🛠️ Customization Options

#### Content Modification
Edit content in: `assets/js/hvac-welcome-popup.js` lines 50-200

#### Styling Changes
Edit styles in: `assets/css/hvac-welcome-popup.css`

#### Account Status Rules
Modify logic in: `includes/class-hvac-welcome-popup.php:user_can_see_popup()`

### 🎯 Performance Optimization

- **Conditional Loading**: Only loads on trainer pages
- **Lazy Initialization**: JavaScript loads after DOM ready
- **Efficient AJAX**: Minimal server requests
- **Cache-Friendly**: Static assets with version numbers

## Security Considerations

### 🔐 Security Features

- **Nonce Verification**: All AJAX requests protected
- **Capability Checks**: User permission validation
- **Input Sanitization**: All user input sanitized
- **XSS Prevention**: Proper output escaping

### 🛡️ Security Best Practices

```php
// Nonce verification
wp_verify_nonce($_POST['nonce'], 'hvac_welcome_nonce');

// Capability check
if (!$this->user_can_see_popup()) {
    wp_send_json_error('Access denied');
}

// Input sanitization
$dont_show_again = (bool) sanitize_text_field($_POST['dont_show_again']);
```

## Conclusion

The HVAC Welcome Popup System provides a comprehensive, accessible, and user-friendly onboarding experience for HVAC trainers. The system properly integrates with WordPress standards, respects user account status, and maintains high accessibility standards.

**Key Achievements:**
- ✅ Fully accessible (WCAG 2.1 AA)
- ✅ Responsive design
- ✅ Account status aware
- ✅ WordPress standards compliant
- ✅ Production ready

**Deployment Status:** Live on staging (v1.0.6) - Ready for production deployment when requested.