# 🎨 Modern MessageBox System for UZRS Inventory

A beautiful, branded replacement for JavaScript's `alert()`, `confirm()`, and `prompt()` dialogs. Works across all modules (Sales, Purchase, Items, Reports, etc.) with a consistent, professional look.

![Version](https://img.shields.io/badge/version-1.0-blue.svg)
![Status](https://img.shields.io/badge/status-production-green.svg)
![License](https://img.shields.io/badge/license-proprietary-orange.svg)

---

## ✨ Features

- ✅ **Branded Interface** - Displays your store name, location, and logo
- ✅ **5 Message Types** - Success, Error, Warning, Info, Confirm
- ✅ **Modern Design** - Beautiful gradients and smooth animations
- ✅ **Fully Responsive** - Works on desktop, tablet, and mobile
- ✅ **Keyboard Shortcuts** - Enter to confirm, Escape to cancel
- ✅ **Focus Management** - Returns focus after closing
- ✅ **Promise-based** - Modern async/await syntax
- ✅ **Global Access** - Works in all modules without code duplication
- ✅ **Zero Dependencies** - Only requires jQuery (already in your project)

---

## 📸 Screenshots

### Success Message
![Success](https://via.placeholder.com/400x200/11998e/ffffff?text=Success+Message)

### Error Message
![Error](https://via.placeholder.com/400x200/eb3349/ffffff?text=Error+Message)

### Confirmation Dialog
![Confirm](https://via.placeholder.com/400x200/667eea/ffffff?text=Confirmation+Dialog)

---

## 🚀 Quick Start (3 Steps)

### Step 1: Files Already Included
The system includes these files:
```
js/modern-messagebox.js       ← Global JavaScript
css/modern-messagebox.css     ← Global CSS
api/get-store-info.php        ← API endpoint
```

### Step 2: Add to Your Page
```html
<!-- In <head> section -->
<link rel="stylesheet" href="../css/modern-messagebox.css">

<!-- Before </body> tag -->
<script src="../js/modern-messagebox.js"></script>
```

### Step 3: Use in Your Code
```javascript
// Make your function async
async function saveItem() {
    // Show success message
    await MsgBox.success('Item saved successfully!');
}
```

**That's it!** You're ready to use modern message boxes! 🎉

---

## 📖 Documentation

| Document | Description |
|----------|-------------|
| **[QUICK_REFERENCE.md](QUICK_REFERENCE.md)** | One-page cheat sheet with all methods |
| **[MODERN_MESSAGEBOX_GUIDE.md](MODERN_MESSAGEBOX_GUIDE.md)** | Complete documentation with examples |
| **[IMPLEMENTATION_GUIDE.md](IMPLEMENTATION_GUIDE.md)** | Step-by-step migration guide |
| **[test-messagebox.php](test-messagebox.php)** | Interactive test page with all features |

---

## 💻 Usage Examples

### Simple Alert
```javascript
await MsgBox.alert('Hello World!', 'info');
```

### Success Message
```javascript
await MsgBox.success('Item saved successfully!');
```

### Error Message
```javascript
await MsgBox.error('Failed to save item!');
```

### Warning Message
```javascript
await MsgBox.warning('Please check your input!');
```

### Confirmation
```javascript
if (await MsgBox.confirm('Delete this item?')) {
    deleteItem();
}
```

### Delete Confirmation (Red)
```javascript
if (await MsgBox.confirmDelete()) {
    deleteRecord();
}
```

### User Input (Prompt)
```javascript
const qty = await MsgBox.prompt('Enter quantity:', '1');
if (qty !== null) {
    addToCart(qty);
}
```

### Custom Options
```javascript
await MsgBox.confirm('Save changes?', {
    confirmText: 'Save',
    cancelText: 'Discard',
    type: 'warning'
});
```

---

## 🎯 Real-World Examples

### Sales Module - Add to Cart
```javascript
async function addToCart(productId) {
    const qty = await MsgBox.prompt('Enter quantity:', '1', 'Qty');
    
    if (qty && qty > 0) {
        // Add to cart logic
        await MsgBox.success('✓ Added to cart!');
    }
}
```

### Purchase Module - Delete Bill
```javascript
async function deleteBill(billId) {
    if (await MsgBox.confirmDelete('Delete this bill?')) {
        // Delete logic
        await MsgBox.success('✓ Bill deleted!');
    }
}
```

### Items Module - Validation
```javascript
async function saveItem() {
    if (!itemName) {
        await MsgBox.error('Please enter item name!');
        return;
    }
    
    // Save logic
    await MsgBox.success('✓ Item saved!');
}
```

---

## 🔧 API Reference

### Methods

| Method | Description | Returns |
|--------|-------------|---------|
| `MsgBox.alert(message, type)` | Show alert message | Promise |
| `MsgBox.confirm(message, options)` | Ask for confirmation | Promise\<boolean\> |
| `MsgBox.prompt(message, default, placeholder)` | Get user input | Promise\<string\|null\> |
| `MsgBox.success(message)` | Show success message | Promise |
| `MsgBox.error(message)` | Show error message | Promise |
| `MsgBox.warning(message)` | Show warning message | Promise |
| `MsgBox.confirmDelete(message)` | Delete confirmation | Promise\<boolean\> |
| `MsgBox.custom(options)` | Custom message box | Promise |
| `MsgBox.preload()` | Pre-load store info | void |

### Message Types

| Type | Color | Icon | Usage |
|------|-------|------|-------|
| `success` | Green | ✓ | Operation completed |
| `error` | Red | ✗ | Error occurred |
| `warning` | Pink | ⚠ | Warning/caution |
| `info` | Blue | ℹ | Information |
| `confirm` | Purple | ? | Ask question |

---

## ⌨️ Keyboard Shortcuts

| Key | Action |
|-----|--------|
| **Enter** | Confirms/submits the dialog |
| **Escape** | Cancels and closes the dialog |
| **Tab** | Navigate between buttons |

---

## 📱 Browser Compatibility

✅ **Desktop Browsers**
- Chrome 60+
- Firefox 55+
- Safari 11+
- Edge 79+

✅ **Mobile Browsers**
- iOS Safari 11+
- Chrome Mobile
- Samsung Internet

✅ **Other Features**
- Touch screen support
- Responsive design
- Keyboard navigation
- Focus management

---

## 🎨 Customization

The message box automatically uses your store information from the database:
- Store name
- Store location (City, State)
- Store logo (if available)

This is loaded from `tblstore_settings` table via the API endpoint.

### Colors & Styles
Edit `css/modern-messagebox.css` to customize:
- Gradient colors
- Button styles
- Animation effects
- Responsive breakpoints

---

## 🔄 Migration from Old Code

### Quick Find & Replace

In your JavaScript files:

| Find | Replace |
|------|---------|
| `alert('...')` | `await MsgBox.alert('...', 'info')` |
| `if (confirm('...'))` | `if (await MsgBox.confirm('...'))` |
| `prompt('...')` | `await MsgBox.prompt('...')` |

**Important:** Add `async` to function definitions!

---

## 📂 File Structure

```
UZRS-inventory/
├── css/
│   └── modern-messagebox.css          ← Global styles
├── js/
│   └── modern-messagebox.js           ← Global script
├── api/
│   └── get-store-info.php             ← Store info API
├── test-messagebox.php                ← Test page
├── MODERN_MESSAGEBOX_GUIDE.md         ← Complete guide
├── IMPLEMENTATION_GUIDE.md            ← Migration guide
├── QUICK_REFERENCE.md                 ← Quick reference
└── README_MESSAGEBOX.md               ← This file
```

---

## 🆘 Troubleshooting

### MessageBox doesn't appear
1. ✅ Check CSS is loaded in `<head>`
2. ✅ Check JS is loaded before `</body>`
3. ✅ Check Font Awesome is loaded
4. ✅ Open browser console for errors

### "MsgBox is not defined"
- Make sure `modern-messagebox.js` is loaded
- Check the script path is correct

### Store name shows "Store"
- Check `api/get-store-info.php` is accessible
- Verify database table `tblstore_settings` exists
- Make sure user is logged in

### Buttons don't work
- Add `async` keyword to function definition
- Use `await` before MsgBox calls
- Check browser console for errors

---

## 🧪 Testing

### Test Page
Open `test-messagebox.php` in your browser to test all features:
- All message types
- Confirmations
- Prompts
- Keyboard shortcuts
- Multi-line messages
- Real-world examples

### Manual Testing Checklist
- [ ] Success messages display correctly
- [ ] Error messages display correctly
- [ ] Confirmations return correct boolean
- [ ] Prompts return correct values
- [ ] Keyboard shortcuts work (Enter, Escape)
- [ ] Mobile responsive layout works
- [ ] Store name appears correctly
- [ ] Focus returns after closing

---

## 📊 Performance

- **Initial Load:** < 5KB (gzipped)
- **Store Info Cache:** Loaded once per page
- **Animation Speed:** 200ms open, 200ms close
- **Memory Usage:** Minimal (removes DOM after close)

---

## 🔐 Security

- ✅ HTML escaping prevents XSS attacks
- ✅ Session validation in API endpoint
- ✅ No external dependencies
- ✅ Secure database queries

---

## 🎓 Best Practices

1. **Always use `await`**
   ```javascript
   // Good
   await MsgBox.success('Saved!');
   
   // Bad (won't work properly)
   MsgBox.success('Saved!');
   ```

2. **Make functions `async`**
   ```javascript
   // Good
   async function save() {
       await MsgBox.success('Saved!');
   }
   
   // Bad
   function save() {
       await MsgBox.success('Saved!'); // Error!
   }
   ```

3. **Pre-load for better performance**
   ```javascript
   $(document).ready(function() {
       MsgBox.preload();
   });
   ```

4. **Use appropriate message types**
   - Success: Operation completed
   - Error: Something went wrong
   - Warning: Proceed with caution
   - Info: General information

---

## 📝 License

Proprietary - UZRS Inventory System
© 2025 All Rights Reserved

---

## 🤝 Support

For help with implementation:
1. Check the documentation files
2. Review the test page examples
3. Check browser console for errors
4. Contact system administrator

---

## 📅 Version History

### Version 1.0 (November 6, 2025)
- ✨ Initial release
- ✅ All basic message types
- ✅ Confirmation dialogs
- ✅ Prompt dialogs
- ✅ Store branding integration
- ✅ Keyboard shortcuts
- ✅ Mobile responsive
- ✅ Complete documentation

---

## 🎉 Get Started Now!

1. **Open** `test-messagebox.php` to see it in action
2. **Read** `QUICK_REFERENCE.md` for common patterns
3. **Integrate** into your first module
4. **Enjoy** beautiful, branded message boxes!

---

**Made with ❤️ for UZRS Inventory System**
