pantry-management-frontend/README.md

# Webpage Playground

A modern inventory management demo app featuring multiple pages for browsing, searching, and scanning barcodes. Built with vanilla HTML, CSS, and JavaScript.

## Overview

Webpage Playground is a lightweight, responsive web application for managing and tracking inventory across multiple storage locations (Pantry, Fridge, Freezer). The app includes:

- **Dynamic Navigation** — Easy page switching with a responsive navbar
- **Inventory Demo** — Display items using reusable item components
- **Advanced Search** — Filter inventory by name, location, quantity range, and expiry date
- **Barcode Scanner** — Scan barcodes using camera or keyboard (hardware scanner support)
- **Data Visualization** — Pie chart showing inventory distribution
- **Responsive Design** — Works on desktop, tablet, and mobile devices

## Project Structure

### Pages
- `index.html` — Homepage with item component demo and inventory pie chart
- `search.html` — Search and filter inventory by name, location, quantity, and expiry date
- `barcode.html` — Barcode scanner with camera and keyboard input modes
- `pantry.html` — Pantry inventory container
- `fridge.html` — Fridge inventory container  
- `freezer.html` — Freezer inventory container

### Core Modules
- `navbar.js` — Dynamic navigation bar system loaded by all pages
- `main.css` — Global styles and responsive design
- `item-component.js` — Reusable ES6 module for displaying inventory items in a grid
- `search.js` — Search and filtering logic with 20 sample inventory items including expiry dates
- `barcode-scanner.js` — Barcode capture and console logging module
- `piechart.js` — Inventory distribution pie chart visualization

### Documentation
- `ITEM_COMPONENT.md` — Detailed documentation for the item component factory
- `README.md` — This file

## Features Overview

### 🏠 Homepage (`index.html`)
The landing page showcasing the project with:
- Interactive item component grid (3 sample items)
- Inventory breakdown pie chart showing distribution across storage locations
- Responsive grid layout that adapts to screen size

**Sample Data:**
- Pantry: 104 items
- Fridge: 30 items
- Freezer: 87 items

### 🔍 Search Page (`search.html`)
Advanced inventory search and filtering interface.

**Features:**
- Search by item name (case-insensitive)
- Filter by storage location (All, Pantry, Fridge, Freezer)
- Filter by quantity range (min/max values)
- Filter by expiry date range (start date and end date)
- Real-time result display with item cards
- Visual expiry status indicators (Fresh, Expiring Soon, Expired)
- **Pagination** — Results displayed with configurable items per page (15, 30, or 60)
- Reset button to clear all filters
- Keyboard support (press Enter to search)
- Date range validation (start date ≤ end date)

**Pagination Features:**
- **Items Per Page Dropdown** — Choose between 15, 30, or 60 items per page
- **Previous/Next Navigation** — Browse through pages of results
- **Page Information** — Shows current page and total pages (e.g., "Page 2 of 5")
- **Result Summary** — Displays showing item count (e.g., "Found 47 items (16-30)")
- **Smart Boundaries** — Previous button disabled on page 1, Next disabled on last page
- **Auto-Reset** — Returns to page 1 when search filters change
- **Dynamic Page Count** — Automatically updates total pages when page size changes

**Expiry Date Features:**
- Each inventory item includes an expiry date
- Visual badges show expiry status:
  - 🟢 **Fresh** — Items expiring in more than 7 days
  - 🟠 **Expiring Soon** — Items expiring within 7 days
  - 🔴 **Expired** — Items past expiry date
- Formatted expiry dates displayed on item cards
- Filter by start and end date to find items expiring in a specific timeframe

**Sample Usage:**
```
Search for items expiring between March 15 and April 15
Results show all items with expiry dates in that range
Items display formatted dates and expiry status badges
```

### 📱 Barcode Scanner (`barcode.html`)
Dual-mode barcode scanning interface with keyboard input and camera scanning.

**Features:**

#### Keyboard Input Mode
- Type or paste barcode values
- Hardware barcode scanner device support
- Real-time console logging
- Auto-focus field for seamless entry
- Enter key to scan

#### Camera Scanning Mode (**NEW**)
- **Real-time barcode detection** using device camera
- **Supported formats:** UPC-A, UPC-E, EAN-13, EAN-8, Code-128, Code-39, and more
- **Browser-based detection** (uses Quagga2 library - local version)
- **Mode toggle** between keyboard and camera input
- **Camera controls** with start/stop buttons
- **Real-time feedback** showing detected barcodes
- **Error handling** with user-friendly messages
- **Mobile support** — Works on iOS and Android devices with camera access
- **Console logging** of all detections with metadata

**Camera Usage:**
1. Switch to "Camera Scan" mode by clicking the button
2. Click "Start Camera" to begin
3. Browser will request camera permission (grant access)
4. Position barcode in front of camera
5. Barcode is detected automatically in real-time
6. Detected barcodes logged to console (press F12)
7. Click "Stop Camera" to end scanning

**Keyboard Usage:**
1. Stay in "Keyboard Input" mode
2. Type barcode value or paste from clipboard
3. Press Enter to complete scan
4. Barcode logged to console

**Console Output Format:**
```
[Barcode Scanned] 14:07:32.456 | Barcode: 5901234123457 | Input: keyboard
[Barcode Scanned] 14:07:45.123 | Barcode: 123456789012 | Input: camera
```

**Browser Support:**
- Chrome 53+, Firefox 55+, Safari 11+, Edge 79+
- Camera access requires HTTPS or localhost
- Mobile browsers support camera scanning

**Testing Instructions:**
1. Navigate to the Barcode Scanner page via navbar
2. Try keyboard input mode: Type a barcode and press Enter
3. Try camera mode: Switch to "Camera Scan" and point at a barcode
4. Press F12 to open DevTools Console
5. View logged barcodes with timestamps and input type

### 📦 Storage Location Pages
- `pantry.html` — Pantry inventory (expandable for displaying specific items)
- `fridge.html` — Fridge inventory
- `freezer.html` — Freezer inventory

These pages are currently placeholder containers ready for future development (e.g., displaying items specific to each location).

## Quick Start

The project is a static site. For best results, serve it over HTTP (ES module imports can be blocked when opened via the `file://` protocol in some browsers).

### Python 3 (Recommended)

```bash
# From the project root
python -m http.server 8000

# Then open http://localhost:8000 in your browser
```

### Alternative Options

- **VS Code Live Server Extension** — Right-click `index.html` → "Open with Live Server"
- **Node.js http-server** — `npx http-server`
- **Any static file server**

## Usage

### Navigation
The navbar appears at the top of every page and provides links to:
- Homepage — Main demo page with pie chart
- Search — Advanced inventory search and filtering with expiry date support
- Barcode Scanner — Barcode capture with camera and keyboard modes
- Pantry, Fridge, Freezer — Individual storage location pages

### Using the Search Page
1. Open the Search page from the navbar
2. Enter search criteria:
   - Item name (optional)
   - Storage location (optional, defaults to "All")
   - Quantity range (optional, defaults to 0-999)
   - Expiry date range (optional) — Leave blank to ignore
3. Click "Search" or press Enter
4. Results display as item cards using the item component with expiry status badges
5. Click "Reset" to clear all filters

**Expiry Date Search Examples:**
- Find items expiring soon: Set start date to today, end date to 7 days from today
- Find expired items: Set start date to 100 days ago, end date to today
- Find fresh items: Set start date to tomorrow, end date to 90 days from today

### Using the Barcode Scanner

#### Keyboard Mode
1. Open the Barcode Scanner page from the navbar
2. Make sure "Keyboard Input" mode is selected
3. Click in the input field (auto-focused)
4. Enter a barcode:
   - Type manually and press Enter
   - Scan with a barcode scanner device
   - Paste a value (Ctrl/Cmd+V)
5. Press F12 to open Developer Tools Console
6. View scanned barcodes in the Console tab with metadata

#### Camera Mode
1. Open the Barcode Scanner page from the navbar
2. Click "Camera Scan" to switch to camera mode
3. Click "Start Camera"
4. Browser will request camera permission (grant access)
5. Position barcode in front of camera lens
6. Barcode is detected automatically and displayed
7. Press F12 to view console logs
8. Click "Stop Camera" to end

**Tips:**
- Ensure good lighting for better barcode detection
- Hold barcode steady and clearly in frame
- Device must have a working camera
- Camera mode requires HTTPS or localhost

### The Item Component
The `item-component` is a reusable UI building block used throughout the app. See `ITEM_COMPONENT.md` for detailed documentation on using it in your own pages.

**Quick Example:**
```html
<script type="module">
  import createItemComponent from './item-component.js';
  
  const item = createItemComponent({
    imgSrc: 'https://picsum.photos/seed/1/200/200',
    imgAlt: 'Milk',
    text1: 'Milk',
    text2: 'Fridge — 1 carton',
    text3: 'Expires Mar 15, 2026'
  });
  
  document.getElementById('container').appendChild(item);
</script>
```

## Customizing and Extending

### Adding New Items to Search
Edit `search.js` and add items to the `inventoryData` array:
```javascript
export const inventoryData = [
  { 
    id: 21, 
    name: 'Coffee', 
    location: 'Pantry', 
    quantity: 2, 
    unit: 'bags', 
    expiryDate: '2026-06-15',
    img: 'https://picsum.photos/seed/coffee/200/200' 
  },
  // ... more items
];
```

**Date Format:** Use ISO 8601 format (YYYY-MM-DD) for expiry dates.

### Styling
- Override styles in `main.css` for global changes
- Page-specific styles are included in `<style>` tags within each HTML file
- The item component injects responsive grid CSS automatically
- Expiry badge styles can be customized via `.expiry-fresh`, `.expiry-soon`, `.expiry-expired` classes

### Creating New Pages
1. Create a new `.html` file following the template:
```html
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <link rel="stylesheet" href="main.css">
  <title>Page Title</title>
</head>
<body>
  <div id="navbar-placeholder"></div>
  <div id="page-content">
    <h2>Page Title</h2>
    <!-- Your content here -->
  </div>
  <script src="navbar.js"></script>
</body>
</html>
```

2. Update `navbar.js` to add a link to your new page:
```javascript
<li><a href="yourpage.html" data-route="yourpage.html">Your Page</a></li>
```

### Converting to Production
- Replace placeholder images with real inventory photos
- Implement backend storage (currently using static data)
- Add user authentication
- Integrate with real barcode/UPC database
- Deploy camera barcode detection to server (for performance optimization)
- Consider a frontend framework (React, Vue, etc.) for scale
- Add unit/integration tests
- Set up CI/CD pipeline
- Implement database for persistent storage and inventory tracking

## Technical Notes

### Barcode Scanning Library
- **Library:** Quagga2 (local version v1.12.1)
- **Location:** `./quagga2/quagga2-1.12.1/docs/examples/dist/quagga.min.js` (153 KB)
- **Why Quagga2:** Improved barcode detection accuracy and performance compared to original Quagga
- **Supported Formats:** UPC-A, UPC-E, EAN-13, EAN-8, Code-128, Code-39
- **API:** Backward compatible with original Quagga.js; no code changes needed
- **Initialization:** See `barcode.html` lines 268-290 for camera initialization logic

### Camera Access
- Requires browser permission (user must grant access)
- Works over HTTPS or localhost only (security requirement)
- Uses HTML5 MediaDevices API (`getUserMedia`)
- Video constraints: 800x600 resolution, environment-facing camera
- Real-time frame processing for barcode detection

### Performance Considerations
- Camera scanning is CPU-intensive on older devices
- Frame processing happens in real-time on main thread
- Consider WebWorkers for production optimization
- Network-free operation: all detection happens client-side

## Contributing

Contributions are welcome! Suggested improvements:

- [ ] Add unit and visual tests
- [ ] Replace placeholder images with real inventory photos
- [ ] Implement barcode scanner backend integration (save to database)
- [ ] Add user accounts and authentication
- [ ] Implement item editing/deletion on storage pages
- [ ] Add barcode/UPC lookup for real products
- [ ] Convert item-component to custom element (`<item-component>`)
- [ ] Optimize camera barcode detection for performance
- [ ] Add more barcode format support
- [ ] Add email/notification alerts for items expiring soon
- [ ] Implement CSV import/export for inventory

## License

Use as you like; no license file is included by default.