# Keyboard Shortcuts Documentation
## UZRS Inventory - POS System

---

## 📋 Overview

The UZRS Inventory POS system now supports complete keyboard navigation, allowing you to perform all tasks without using a mouse. This dramatically increases data entry speed and efficiency for experienced users.

**Quick Start:** Press `F1` at any time to view the interactive keyboard shortcuts help guide.

---

## 🎯 Key Features

- **100% Mouse-Free Operation** - Every function accessible via keyboard
- **Visual Focus Indicators** - Clear highlighting shows where you are
- **Context-Aware Shortcuts** - Different shortcuts work in different contexts
- **Modal Navigation** - Full keyboard support in all popups
- **Cart Navigation** - Arrow keys to browse and edit items
- **Quick Actions** - Function keys for common operations

---

## 🔑 Complete Shortcut Reference

### 🧭 Navigation & Focus (F-Keys)

| Shortcut | Action | Description |
|----------|--------|-------------|
| `F1` | **Help Guide** | Open keyboard shortcuts help modal |
| `F2` | **Product Code** | Focus on product code input field |
| `F3` | **Product Search** | Open product search modal |
| `F4` | **Rate/Price** | Focus on rate/price input |
| `F5` | **Quantity** | Focus on quantity input |
| `F6` | **Add to Cart** | Add current item to cart |
| `F7` | **Customer Search** | Focus on customer search field |
| `F8` | **Barcode Scanner** | Open barcode scanner camera |
| `F9` | **Save & Print** | Save bill and print receipt |
| `F10` | **GST Details** | View GST breakdown |
| `F11` | **Full Screen** | Toggle full screen mode |
| `F12` | **Quick Actions** | Open quick actions menu |

### 🛒 Cart Operations

| Shortcut | Action | Description |
|----------|--------|-------------|
| `↑` `↓` | **Navigate Cart** | Move between cart items |
| `Enter` | **Edit Item** | Edit selected cart item |
| `Delete` | **Remove Item** | Delete selected cart item |
| `Space` | **Select Item** | Toggle item selection |
| `Ctrl+A` | **Select All** | Select all cart items |
| `Ctrl+K` | **Clear Cart** | Remove all items from cart |
| `Ctrl+D` | **Discount** | Focus on discount field |

### 📄 Bill Operations (Ctrl + Letter)

| Shortcut | Action | Description |
|----------|--------|-------------|
| `Ctrl+S` | **Save Bill** | Save current bill |
| `Ctrl+N` | **New Sale** | Start new sale transaction |
| `Ctrl+H` | **Hold Bill** | Hold current bill for later |
| `Ctrl+L` | **Load Held Bill** | View and load held bills |
| `Ctrl+P` | **Print Preview** | Preview before printing |
| `Ctrl+G` | **GST Details** | View GST breakdown (alt) |

### ⚙️ Additional Features (Ctrl + Letter)

| Shortcut | Action | Description |
|----------|--------|-------------|
| `Ctrl+M` | **Add Customer** | Open add customer modal |
| `Ctrl+E` | **Expenses** | Register expense modal |
| `Ctrl+T` | **Transport** | Transport details modal |
| `Ctrl+I` | **Shipping** | Shipping details modal |
| `Ctrl+Y` | **Loyalty Points** | Loyalty points modal |
| `Ctrl+U` | **Loyalty Settings** | Configure loyalty settings |

### 🔢 Quick Sales Type Switch

| Shortcut | Action |
|----------|--------|
| `Alt+1` to `Alt+9` | Switch to sales type (by position) |

### 🪟 Modal Navigation

| Shortcut | Action | Description |
|----------|--------|-------------|
| `Enter` | **Confirm** | Click primary button in modal |
| `Esc` | **Close** | Close current modal |
| `Ctrl+W` | **Close** | Close modal (alternative) |
| `Tab` | **Next Field** | Move to next input field |
| `Shift+Tab` | **Previous Field** | Move to previous field |
| `↑` `↓` | **Navigate Results** | Browse search results |
| `1` to `9` | **Quick Select** | Select item in hold bills |

### 🌐 Global Shortcuts

| Shortcut | Action | Description |
|----------|--------|-------------|
| `F1` | **Help** | Show keyboard shortcuts guide |
| `Alt+H` | **Home** | Go to dashboard |
| `Esc` | **Exit/Clear** | Close modal or clear focus |

---

## 💡 Usage Tips & Best Practices

### ⚡ Speed Entry Workflow

**For maximum speed, use this workflow:**

1. Press `F2` - Jump to product code
2. Type/scan product code
3. Press `Tab` or `F4` - Jump to rate (usually auto-filled)
4. Press `Tab` or `F5` - Jump to quantity
5. Type quantity
6. Press `F6` - Add to cart
7. Repeat steps 1-6 for more items
8. Press `F7` - Add customer (optional)
9. Press `F9` - Save and print

**Estimated time per item: 3-5 seconds**

### 🎯 Focus Management

- **Auto-select on focus**: Number inputs automatically select text when focused
- **Visual indicators**: Blue outline shows keyboard focus
- **Cart highlighting**: Selected cart item has blue left border
- **Esc to blur**: Press `Esc` from any input to clear focus

### 🎨 Visual Feedback

The system provides visual cues:

- **Blue outline** - Element has keyboard focus
- **Blue left border** - Selected cart item
- **Yellow background** - Multiple selected items
- **Hover effect** - Available for interaction
- **Pulsing indicator** - Keyboard mode active

### 📋 Modal Best Practices

When a modal opens:

1. **Auto-focus**: First input field is automatically focused
2. **Tab navigation**: Use `Tab` to move between fields
3. **Enter to save**: Press `Enter` to submit (works in most modals)
4. **Esc to cancel**: Quick exit without saving
5. **Focus trap**: Tab cycles within modal only

### 🛒 Cart Navigation Tips

- **Arrow keys work**: Only when not in an input field
- **Click to focus**: Click a row to make it keyboard-focused
- **Visual highlight**: Focused row has blue background
- **Quick edit**: `Enter` to edit, `Delete` to remove
- **Multi-select**: `Space` to select, `Ctrl+A` for all

---

## 📖 Common Workflows

### Workflow 1: Standard Sale

```
F2          → Focus product code
[Type/Scan] → Enter product
Tab         → Move to rate
Tab         → Move to quantity
[Type qty]  → Enter quantity
F6          → Add to cart
[Repeat]    → Add more items
F9          → Save & print
```

### Workflow 2: Edit Cart Item

```
↓ or ↑      → Navigate to item
Enter       → Open edit modal
Tab         → Move between fields
Enter       → Save changes
```

### Workflow 3: Hold & Resume

```
[Build cart]
Ctrl+H      → Hold current bill
[Enter name]
Ctrl+N      → Start new sale
...
Ctrl+L      → View hold bills
1-9         → Quick select bill
Enter       → Resume bill
```

### Workflow 4: Customer Sale with Discount

```
F7          → Focus customer search
[Type name] → Search customer
↓ Enter     → Select customer
F2          → Focus product code
[Add items]
Ctrl+D      → Focus discount
[Enter disc]
F9          → Save & print
```

---

## 🔧 Technical Details

### Context Awareness

The keyboard system is **context-aware**:

- **Main screen**: All F-keys and Ctrl shortcuts work
- **Input focused**: Only `Esc` and `Tab` work (don't interfere with typing)
- **Modal open**: Modal-specific shortcuts active
- **Cart focused**: Arrow keys navigate items

### Shortcuts Disabled During Typing

When typing in inputs, most shortcuts are disabled to prevent conflicts:

- ✅ **Allowed**: `Esc`, `Tab`, `Enter`
- ❌ **Disabled**: F-keys, Ctrl shortcuts, arrow keys

**Exception**: Product code and customer search inputs allow shortcuts

### Focus Indicators

Three levels of visual feedback:

1. **Browser default**: Thin outline (removed for mouse users)
2. **Keyboard focus**: Blue 3px outline + shadow
3. **Enhanced focus**: Transform + scale animation

### Accessibility Features

- **Tab trapping** in modals (keyboard can't escape)
- **Auto-focus** on modal open
- **Skip links** for screen readers
- **ARIA labels** on all interactive elements
- **Visible focus** always shown for keyboard users

---

## 🎨 Customization

### Adding Hints to Custom Buttons

```javascript
// Automatically done by system
// Hints appear as small badges on buttons
```

### Styling Focus Indicators

See `css/keyboard-shortcuts.css` for customization:

```css
.keyboard-focus-active {
    outline: 3px solid #4e73df !important;
    /* Customize color, width, style */
}
```

---

## 🐛 Troubleshooting

### Shortcuts Not Working?

1. **Check if typing**: Click outside input first, then try shortcut
2. **Modal open**: Some shortcuts only work without modals
3. **Browser conflicts**: Some browsers override F-keys (e.g., F11)
4. **JavaScript errors**: Check browser console

### Focus Not Visible?

1. **CSS overrides**: Check for custom CSS blocking outlines
2. **Browser settings**: Ensure accessibility features enabled
3. **Contrast**: Increase monitor contrast if needed

### Cart Navigation Not Working?

1. **Click cart first**: Click a cart row to initialize focus
2. **Must be outside input**: Blur any focused input first
3. **Empty cart**: No items to navigate

---

## 📝 File Structure

```
Sales/
├── js/
│   └── keyboard-shortcuts.js      # Main keyboard handler
├── css/
│   └── keyboard-shortcuts.css     # Visual styling
├── keyboard-shortcuts-help.php    # Help modal
└── index.php                      # Includes all above
```

---

## 🚀 Performance

- **Zero impact** on page load (deferred initialization)
- **Event delegation** for efficient handling
- **Debounced** where appropriate
- **Lightweight**: ~15KB total (JS + CSS)

---

## 🔮 Future Enhancements

Planned features:

- [ ] Customizable shortcut keys
- [ ] Voice command integration
- [ ] Keyboard macro recording
- [ ] Multi-language shortcut hints
- [ ] Touch gesture equivalents
- [ ] Gamepad support

---

## 📞 Support

If you encounter issues or have suggestions:

1. Press `F1` to view help
2. Check this documentation
3. Contact system administrator
4. Review browser console for errors

---

## ✅ Checklist for New Users

- [ ] Press `F1` to view help guide
- [ ] Try `F2` → `F6` workflow for adding items
- [ ] Practice cart navigation with arrow keys
- [ ] Test `Ctrl+H` to hold a bill
- [ ] Use `Esc` to close modals quickly
- [ ] Experiment with `Alt+1-9` for sales types
- [ ] Enable full screen with `F11` for immersive experience

---

**Version:** 1.0  
**Last Updated:** 2025-11-03  
**Compatibility:** All modern browsers (Chrome, Firefox, Edge, Safari)

---

## 🎓 Keyboard Shortcut Mastery Levels

### Level 1: Beginner
Master these shortcuts first:
- `F2`, `F6`, `F9` - Basic entry workflow
- `Tab`, `Enter`, `Esc` - Navigation basics
- `Ctrl+N` - Start new sale

### Level 2: Intermediate  
Add these to your arsenal:
- Arrow keys for cart navigation
- `Ctrl+H`, `Ctrl+L` - Hold bills
- `F7` - Customer search
- `Ctrl+K` - Clear cart

### Level 3: Advanced
Become a power user:
- `Alt+1-9` - Sales type switching
- `Ctrl+D` - Quick discounts
- Modal shortcuts
- Multi-select operations

### Level 4: Expert
Maximum efficiency:
- Combine shortcuts in sequences
- Never touch mouse
- Custom workflows
- Sub-3-second item entry

---

**Happy keyboard navigation!** 🎹✨
