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 for inventory management (keyboard and 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 console logging for testing
- `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)
- **NEW: 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)
- Reset button to clear all filters
- Keyboard support (press Enter to search)
- Date range validation (start date ≤ end date)

**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
```

**Available Items (20 total across all locations):**
- Pantry: Pasta (120 days), Rice (180 days), Cereal (60 days), Flour (150 days), Sugar (200 days), Salt (365 days), Olive Oil (90 days), Canned Beans (EXPIRED -10 days)
- Fridge: Milk (5 days), Cheese (30 days), Greek Yogurt (7 days), Eggs (21 days), Butter (45 days), Chicken Salad (EXPIRED -2 days)
- Freezer: Ice Cream (90 days), Frozen Vegetables (180 days), Chicken Breast (120 days), Ground Beef (150 days), Pizza (200 days), Ice (365 days)

### 📱 Barcode Scanner (`barcode.html`)
Barcode capture interface with console logging for testing.

**Features:**
- Keyboard input simulation (type barcode + press Enter)
- Hardware barcode scanner device support (ready for integration)
- Paste support (Ctrl/Cmd+V)
- Console logging with formatted output including:
  - Timestamp (HH:MM:SS.mmm format)
  - Barcode value
  - Input type detection (keyboard, hardware-scanner, keyboard-paste)
  - Metadata for debugging
- Auto-focus input field after each scan
- Visual status indicator
- Helper instructions and "Open Console" button

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

**Testing Instructions:**
1. Navigate to the Barcode Scanner page via navbar
2. Type a barcode value or use a barcode scanner device
3. Press Enter to complete the scan
4. Press F12 to open Developer Tools
5. Switch to the Console tab to view scanned barcodes with metadata

### 📦 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 interface (testing via console)
- 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
1. Open the Barcode Scanner page from the navbar
2. Click in the input field (auto-focused)
3. Enter a barcode:
   - Type manually and press Enter
   - Scan with a barcode scanner device
   - Paste a value (Ctrl/Cmd+V)
4. Press F12 to open Developer Tools Console
5. View scanned barcodes in the Console tab with timestamp and metadata

### 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
- Consider a frontend framework (React, Vue, etc.) for scale
- Add unit/integration tests
- Set up CI/CD pipeline
- Implement database for persistent storage and expiry date tracking

## 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>`)
- [ ] Add more detailed inventory tracking (expiration dates calculations, locations within rooms, batch numbers, etc.)
- [ ] 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.