# POS Items Page Documentation

## Overview
The `items.php` page is the main point-of-sale interface that displays products in a grid layout with touch-optimized interactions. It provides functionality for viewing products, managing cart items, processing sales, and handling various user interactions.

## Features

### 1. Product Grid Display
- Responsive grid layout that adapts to screen size
- Each product card shows:
  - Product image
  - Name
  - Price
  - Quantity counter (when items are in cart)
  - Favorite status indicator
- Touch-optimized scrolling with momentum
- Support for both unit and fractional (weight-based) items

### 2. Touch Interactions
#### Scrolling
- Swipe up/down anywhere in the grid to scroll
- Smooth momentum scrolling with inertia
- Works on both product images and empty spaces
- Prevents accidental item selection while scrolling

#### Item Selection
- Tap: Adds item to cart
- Long Press (500ms): Decrements item quantity
- Double-tap prevention (300ms debounce)
- Touch event handling:
  ```javascript
  touchstart: Records initial touch position
  touchmove: Handles scrolling
  touchend: Processes item selection
  touchcancel: Resets touch states
  ```

### 3. Cart Management
- Real-time cart counter
- Visual feedback for cart updates
- Cart operations:
  - Add items (tap)
  - Remove items (long press)
  - Edit quantities
  - Apply discounts
  - Mark items as free
- Cart modal with detailed view

### 4. Fractional Items
- Special handling for weight-based items
- Input modes:
  1. Weight input (kg)
  2. Amount input (₱)
- Validation and precision handling
- Custom modal for fraction input

### 5. Item Editing
Features available in edit mode:
- Quantity adjustment
- Price modification
- Discount application:
  - Percentage based
  - Fixed amount
- Free item marking
- Item removal from cart

### 6. Visual Feedback
- Flying animation when adding to cart
- Sound effects:
  - Click sound on item addition
  - Cash register sound on sale completion
- Counter animations
- Loading states

### 7. Sale Processing
- Validates cart contents
- Handles customer association
- Updates customer balance
- Processes transaction
- Clears cart after successful sale
- Error handling and user feedback

## Technical Details

### CSS Classes
```css
.product-grid {
    display: grid;
    grid-template-columns: repeat(auto-fill, minmax(150px, 1fr));
    gap: 1rem;
    padding: 1rem;
    -webkit-overflow-scrolling: touch;
    touch-action: pan-y;
    height: calc(100vh - 60px);
    overflow-y: auto;
}

.product-item {
    background: white;
    border-radius: 8px;
    padding: 1rem;
    text-align: center;
    position: relative;
    cursor: pointer;
    touch-action: none;
}
```

### Key JavaScript Functions

#### Cart Management
```javascript
window.handleCartClick(): Processes cart checkout
window.incrementItem(): Adds item to cart
window.updateItemCount(): Updates item quantity
window.updateCartModal(): Refreshes cart display
```

#### Touch Handling
```javascript
handleStart(): Initializes touch interaction
handleMove(): Processes touch movement
handleEnd(): Finalizes touch interaction
handleCancel(): Resets touch states
```

#### Sale Processing
```javascript
window.processSale(): Handles sale completion
window.flyToCart(): Animates item addition
window.updateCartMenuCounter(): Updates cart totals
```

### Database Tables
- m001_items: Product information
- m001_sales: Sales transactions
- m001_sale_items: Sale line items
- m001_items_cat: Product categories

### Dependencies
1. Bootstrap 4 (UI Framework)
2. Font Awesome 6.5.1 (Icons)
3. SweetAlert2 (Notifications)
4. Custom sound effects:
   - click.mp3
   - cash-register.mp3

## Usage Examples

### Adding Items to Cart
```javascript
// Single tap on product
window.handleItemClick(item);

// Long press to decrement
pressTimer = setTimeout(() => {
    if (!isSwiping) {
        // Decrement logic
    }
}, 500);
```

### Processing Sales
```javascript
window.processSale(cartData, total)
    .then(result => {
        if (result.success) {
            // Clear cart and refresh
        }
    });
```

### Fraction Input
```javascript
// Weight-based item input
if (fractionInputType === '1') {
    quantity = value; // Direct kg value
} else {
    quantity = value / item.price; // Calculated from amount
}
```

## Error Handling
- Network errors
- Invalid quantities
- Database errors
- Customer balance issues
- Input validation

## Best Practices
1. Always validate input values
2. Provide visual feedback for actions
3. Handle all touch events properly
4. Clean up event listeners
5. Maintain cart state
6. Handle errors gracefully

## Security Considerations
1. Input sanitization
2. CSRF protection
3. User authentication
4. Session management
5. SQL injection prevention

## Performance Optimization
1. Debounced event handlers
2. Efficient DOM updates
3. Cached selectors
4. Optimized animations
5. Proper touch event flags

## Troubleshooting
Common issues and solutions:
1. Touch events not working
   - Check touch-action CSS
   - Verify event listener passive flags
2. Cart not updating
   - Check cart state management
   - Verify event handlers
3. Sales not processing
   - Check network requests
   - Verify database connections