# Workspace Queue Page - Implementation Reference

## File Map

### Templates (`userfrosting/templates/themes/default/workspace/`)
- `workspace.html` - SPA container, includes all views
- `partials/queue/queue-enhanced.html` - Tabbed view (5 tabs: Remote, Queued, Sorting, Sorted, Processing)
- `partials/queue/queue-classic.html` - Legacy 5-list view (ULs: #buysProcessing, #buysSorted, #buysSorting, #buysQueued, #buysRemote)
- `partials/queue/queue-item-template.html` - Handlebars template for individual items
- `partials/queue/queue-controls.html` - Wait time buttons, view toggle

### CSS
- `public_html/css/workspace/workspace.css` - All workspace styles (1,400+ lines)

### JavaScript
| File | Role |
|------|------|
| `public_html/js/workspace/workspace.js` | Init, module creation, initial data load |
| `public_html/view/common/js/buyQueue.js` | Legacy core: rendering, timers, Ably, modals |
| `public_html/js/workspace/modules/queue/QueueAPI.js` | API wrapper |
| `public_html/js/workspace/modules/queue/QueueRenderer.js` | DOM rendering |
| `public_html/js/workspace/modules/queue/QueueManager.js` | Item lifecycle |
| `public_html/js/workspace/modules/queue/QueueAbly.js` | WebSocket real-time |
| `public_html/js/workspace/modules/common/spa-navigation.js` | View switching |

### Backend
- `userfrosting/routes/workbook/pages.php` - Routes: `/:typeNum/workspace/`, `/:typeNum/workbook/`
- `userfrosting/controllers/Workbook/WorkbookPageController.php` - `pageWorkspace()`, `pageWorkbook()`

## Architecture

### SPA Views
Views are `<main class="workspace-view">` elements. Active view has `.active` class.
- Body attribute: `data-active-view="queue|workbook|completed|printlog|support"`
- Navigation: `.spa-nav` links handled by `spa-navigation.js`

### Queue View Modes
- **Enhanced**: `.enhanced-view` class on `#buyQueuePanels` - shows tabbed interface
- **Classic**: No class - shows 5 stacked UL lists

### Queue Item Flow
```
remote → queued → sorting → sorted → processing → (completed)
```

### Data Flow
1. Controller loads store + queue data
2. Template renders empty containers + Handlebars template
3. `workspace.js` fetches `/:typeNum/json`, categorizes by status, renders
4. `buyQueue.js` handles timers (1s interval), Ably real-time updates

## Key Selectors

### Queue Containers (Classic)
```css
#buysProcessing, #buysSorted, #buysSorting, #buysQueued, #buysRemote
```

### Queue Containers (Enhanced)
```css
#tabRemote, #tabQueued, #tabSorting, #tabSorted, #tabProcessing
.queue-items-list  /* UL inside each tab */
```

### Queue Item Structure
```css
.buyqueue-container     /* Main wrapper */
.buyqueue-time          /* Timer section */
.buyqueue-body          /* Content area */
.buyqueue-icon          /* Action buttons */
.buyqueue-content-name  /* Customer name */
.buyqueue-content-bins  /* Container count */
.buyqueue-right         /* Right side (bins, delete) */
.buyqueue-detail        /* Mobile expandable */
.actionButton           /* Action button wrapper */
```

### Status Classes
Applied to `.buyqueue-container`: `.processing`, `.sorted`, `.sorting`, `.queued`, `.remote`

## CSS Variables (`workspace.css`)
```css
--sidebar-width: 200px;
--header-height: 50px;
--kpi-bar-height: 50px;
--primary-color: #667eea;
--secondary-color: #14b8a6;
```

## Meta Tags (Config passed to JS)
```html
typeNum, storeType, csrf_token, yellowTime, redTime,
enableQueueSignIn, workbookEnabled, timezone, activePage
```

## Key Functions

### buyQueue.js
- `generateQueueItemHTML(item)` - Create item HTML from data
- `populateQueueViews()` - Render items to classic view
- `updateQueueTimers()` - Update all timers (runs every 1s)
- `updateWaitTime()` - Fetch/display estimated wait
- `addToProcessing(item)`, `addToSorted(item)`, etc. - Add to specific list

### workspace.js
- `init()` - Bootstrap workspace
- `loadInitialQueue()` - Fetch from `/:typeNum/json`
- `categorizeItems(items)` - Sort by status into arrays
- `updateQueueCounts()` - Update tab badges

## Global State
```javascript
window.globalQueueArrays = {
  processingItems: [],
  sortedItems: [],
  sortingItems: [],
  queuedItems: [],
  remoteItems: []
}
```

## Common Modifications

### Add queue item field
1. Update `queue-item-template.html` (Handlebars)
2. Add CSS in `workspace.css`
3. Ensure field in API response (`/:typeNum/json`)

### Change queue item styling
1. Edit `workspace.css` - search for `.buyqueue-*`

### Add new action button
1. Add to `queue-item-template.html`
2. Add click handler in `buyQueue.js`
3. Add API endpoint if needed

### Modify tab behavior
1. Edit `queue-enhanced.html` for structure
2. Edit `workspace.js` for count updates
3. Edit `buyQueue.js` for item placement logic