littleshop/VARIANT_COLLECTIONS_USER_GUIDE.md

# Variant Collections Spreadsheet Editor - User Guide

> **Professional spreadsheet interface for managing product variant properties with mobile-first design**

## Overview

The Variant Collections Spreadsheet Editor replaces the traditional JSON textarea with a professional, Excel-like spreadsheet interface powered by Handsontable. This makes it significantly easier to create and manage complex product variant configurations without manually writing JSON.

## Key Features

### ✨ Core Functionality
- **Excel-like Interface**: Familiar spreadsheet editing experience
- **Property Presets**: Pre-configured property types (Size, Color, Material, Storage, Custom)
- **Inline Editing**: Click any cell to edit values directly
- **Dynamic Rows/Columns**: Add or remove rows and columns on-the-fly
- **Auto-save**: Changes automatically serialize to JSON on form submission
- **Mobile Optimized**: Touch gestures and responsive design for mobile devices

### 📱 Mobile Features
- **Touch Gestures**: Swipe left/right on rows to delete
- **Responsive Layout**: Adapts to screen size automatically
- **Large Touch Targets**: Easy to interact with on mobile devices

### ⌨️ Keyboard Shortcuts
- **Tab**: Move to next cell (right)
- **Shift+Tab**: Move to previous cell (left)
- **Enter**: Move down to next row
- **Ctrl+D**: Delete selected rows or columns
- **Ctrl+Enter**: Save form immediately
- **Ctrl+Z**: Undo last action
- **Ctrl+Y**: Redo last undone action

## Getting Started

### Accessing the Editor

1. Navigate to **Admin Panel** → **Variants** → **Variant Collections**
2. Click **Create New** or **Edit** on an existing collection
3. The spreadsheet editor appears under "Properties Spreadsheet"

### Creating Your First Variant Collection

**Example: Creating a Clothing Size/Color Variant**

1. **Set Collection Name**: Enter "Clothing Variants" in the Collection Name field
2. **Configure Properties**:
   - **Column 1 (Size)**: Click the first column header → Select "Size" → Pre-populated with XS, S, M, L, XL, XXL
   - **Column 2 (Color)**: Click the second column header → Select "Color" → Pre-populated with Black, White, Red, Blue, etc.
3. **Edit Values**: Click any cell to modify or add custom values
4. **Save**: Click "Save Changes" at the bottom (or press Ctrl+Enter)

## Property Types

### 1. **Size** (Preset)
Pre-configured with standard clothing sizes:
- XS, S, M, L, XL, XXL

**Use Cases**:
- Clothing items
- Shoe sizes (edit values to match your sizing system)
- General size categories

### 2. **Color** (Preset)
Pre-configured with common colors:
- Black, White, Red, Blue, Green, Yellow, Pink, Purple, Gray, Brown

**Use Cases**:
- Clothing colors
- Product variants with color options
- Packaging color variations

### 3. **Material** (Preset)
Pre-configured with fabric/material types:
- Cotton, Polyester, Silk, Wool, Leather, Denim, Linen

**Use Cases**:
- Clothing materials
- Product composition
- Manufacturing materials

### 4. **Storage** (Preset)
Pre-configured with common storage capacities:
- 16GB, 32GB, 64GB, 128GB, 256GB, 512GB, 1TB

**Use Cases**:
- Electronics (phones, tablets, laptops)
- Storage devices
- Memory cards

### 5. **Custom** (Freeform)
Create your own property type with custom name and values.

**Use Cases**:
- Specialty product attributes
- Unique variant properties
- Industry-specific classifications

## Common Use Cases

### Use Case 1: Electronics Store (Phones)

**Scenario**: Sell smartphones with storage and color variants

```
Collection Name: Smartphone Variants

Property 1: Storage (16GB, 32GB, 64GB, 128GB, 256GB)
Property 2: Color (Space Gray, Silver, Gold, Rose Gold)
```

**Steps**:
1. Click first column header → Select "Storage"
2. Edit cells to keep only: 64GB, 128GB, 256GB (delete others if not needed)
3. Click second column header → Select "Color"
4. Edit cells to: Space Gray, Silver, Gold, Rose Gold
5. Click "Add Row" (right-click menu) if you need more color options
6. Save collection

### Use Case 2: Clothing Store (Apparel)

**Scenario**: Sell t-shirts with size and color variants

```
Collection Name: T-Shirt Variants

Property 1: Size (S, M, L, XL, XXL)
Property 2: Color (Black, White, Navy, Red)
```

**Steps**:
1. Click first column header → Select "Size"
2. Keep S, M, L, XL, XXL (delete XS if not needed)
3. Click second column header → Select "Color"
4. Edit to: Black, White, Navy, Red
5. Save collection

### Use Case 3: Jewelry Store (Rings)

**Scenario**: Sell rings with material and ring size variants

```
Collection Name: Ring Variants

Property 1: Material (Gold, Silver, Platinum, Rose Gold)
Property 2: Ring Size (6, 7, 8, 9, 10)
```

**Steps**:
1. Click first column header → Select "Material"
2. Edit cells to: Gold, Silver, Platinum, Rose Gold
3. Click second column header → Select "Custom..."
4. Enter "Ring Size" as custom property name
5. Enter sizes: 6, 7, 8, 9, 10 in cells
6. Save collection

### Use Case 4: Book Store (Formats)

**Scenario**: Sell books in different formats

```
Collection Name: Book Format

Property 1: Format (Hardcover, Paperback, eBook, Audiobook)
```

**Steps**:
1. Click first column header → Select "Custom..."
2. Enter "Format" as property name
3. Enter: Hardcover, Paperback, eBook, Audiobook
4. Save collection (single-property variant)

## Advanced Techniques

### Adding Multiple Columns

You can create variants with up to **8 properties** (columns):

1. Click the rightmost column header
2. Right-click → Select "Insert column right"
3. Configure the new column with a property type
4. Repeat as needed

**Example: Complex Electronics Variant**
```
Property 1: Storage (64GB, 128GB, 256GB)
Property 2: Color (Black, White, Blue)
Property 3: Memory (4GB RAM, 8GB RAM, 16GB RAM)
Property 4: Screen Size (6.1", 6.5", 6.7")
```

### Bulk Editing

For efficiency when editing many values:

1. **Copy/Paste**: Use Ctrl+C and Ctrl+V to copy cell values
2. **Fill Down**: Select a cell, drag the fill handle (bottom-right corner) down to replicate values
3. **Multi-Select**: Click and drag to select multiple cells, then type to replace all

### Deleting Unwanted Data

#### Delete Individual Rows:
- **Desktop**: Right-click row header → "Remove row"
- **Mobile**: Swipe row left or right → Confirm delete
- **Keyboard**: Select row → Press Ctrl+D

#### Delete Columns:
- Right-click column header → "Remove column"
- Or select column and press Ctrl+D

#### Clear Cell Contents:
- Click cell → Press Delete key
- Or select cells → Right-click → "Clear selected"

## Mobile Usage Tips

### Touch Navigation
- **Tap**: Select cell for editing
- **Double-tap**: Enter edit mode
- **Swipe left/right**: Delete row (with confirmation)
- **Pinch zoom**: Not needed - layout auto-adjusts

### Mobile-Specific Features
- **Larger touch targets**: Cells are sized for finger taps
- **Horizontal scrolling**: Swipe left/right to see more columns
- **Full-screen mode**: Rotate device to landscape for better view

## Data Validation and Error Handling

### Automatic Validation

The editor performs validation before saving:

1. **Empty Property Names**: All columns must have names (click headers to set)
2. **Valid JSON**: Data must serialize to valid JSON format
3. **Array Structure**: Properties must have array structure

### Common Errors

#### Error: "All property columns must have names"
**Cause**: One or more columns don't have property names set

**Solution**: Click each column header and select a property type or enter custom name

#### Error: "Failed to save variant properties"
**Cause**: Invalid data structure or JSON serialization failure

**Solution**:
1. Check for special characters in cell values
2. Ensure all columns have names
3. Try refreshing the page and re-entering data

## Best Practices

### 1. Plan Your Variant Structure

Before creating a variant collection:
- List all property types you need
- Identify which properties have fixed values vs. freeform text
- Consider how many variants this will create (combinations multiply)

**Example**:
- 3 Sizes × 4 Colors = 12 variant combinations
- 5 Storage options × 3 Colors × 2 Memory sizes = 30 combinations

### 2. Use Presets When Possible

Presets save time and ensure consistency:
- Use "Size" preset for standard clothing sizes
- Use "Color" preset for common colors
- Use "Storage" preset for electronics

### 3. Keep Property Names Clear

Use descriptive property names that customers will understand:
- ✅ "Ring Size" instead of "Size"
- ✅ "Frame Material" instead of "Material"
- ✅ "Battery Capacity" instead of "Storage"

### 4. Organize Properties Logically

Order properties from most to least important:
1. Primary differentiator (e.g., Storage, Size)
2. Secondary attributes (e.g., Color)
3. Optional features (e.g., Memory, Screen Size)

### 5. Test Your Variants

After creating a variant collection:
1. Save the collection
2. Assign it to a product
3. Edit the product and verify variants are generated correctly
4. Check product display on the store front

## Troubleshooting

### Issue: Spreadsheet Not Loading

**Symptoms**: Blank area where spreadsheet should appear

**Solutions**:
1. Check browser console for JavaScript errors (F12)
2. Ensure you're using a modern browser (Chrome, Firefox, Edge, Safari)
3. Clear browser cache and reload page
4. Verify Handsontable libraries are loaded (check Network tab)

### Issue: Changes Not Saving

**Symptoms**: Click "Save Changes" but data reverts

**Solutions**:
1. Check for validation errors (red alert boxes)
2. Ensure all columns have property names set
3. Check browser console for error messages
4. Try manually clicking in each cell to trigger validation

### Issue: Context Menu Not Appearing

**Symptoms**: Right-click doesn't show menu

**Solutions**:
1. Ensure you're right-clicking on the grid area (not outside)
2. Try on different cell locations
3. Use keyboard shortcuts as alternative (Ctrl+D, etc.)
4. Check if browser is blocking context menus

### Issue: Mobile Gestures Not Working

**Symptoms**: Swipe gestures don't delete rows

**Solutions**:
1. Ensure Hammer.js library is loaded
2. Try swiping with more force/distance
3. Use desktop context menu as alternative
4. Check if device/browser supports touch events

## Technical Details

### JSON Format

The spreadsheet automatically converts to this JSON structure:

```json
[
  {
    "name": "Size",
    "values": ["S", "M", "L", "XL"]
  },
  {
    "name": "Color",
    "values": ["Black", "White", "Red"]
  }
]
```

### Freeform Properties

To create a freeform property (no predefined values):
- Select "Custom" property type
- Leave all cell values empty
- Customers will be able to enter any text value

**JSON Example**:
```json
[
  {
    "name": "Custom Text",
    "values": null
  }
]
```

### Browser Compatibility

**Fully Supported**:
- Chrome 90+
- Firefox 88+
- Edge 90+
- Safari 14+
- Mobile Safari (iOS 13+)
- Chrome Mobile (Android 8+)

**Limited Support**:
- IE 11 (basic functionality, no touch gestures)
- Older Android browsers (may have touch issues)

## Keyboard Reference Card

| Shortcut | Action |
|----------|--------|
| **Navigation** | |
| Tab | Move right |
| Shift+Tab | Move left |
| Enter | Move down |
| Shift+Enter | Move up |
| Arrow Keys | Navigate cells |
| Home | First column |
| End | Last column |
| **Editing** | |
| F2 | Edit cell |
| Delete | Clear cell |
| Backspace | Clear and edit |
| Escape | Cancel edit |
| **Selection** | |
| Shift+Arrows | Extend selection |
| Ctrl+A | Select all |
| **Operations** | |
| Ctrl+C | Copy |
| Ctrl+V | Paste |
| Ctrl+X | Cut |
| Ctrl+Z | Undo |
| Ctrl+Y | Redo |
| Ctrl+D | Delete selected |
| Ctrl+Enter | Save form |

## Support and Feedback

### Getting Help

If you encounter issues not covered in this guide:

1. **Check Browser Console**: Press F12 and look for error messages in the Console tab
2. **Review Validation Messages**: Red alert boxes show specific error details
3. **Test in Different Browser**: Some issues may be browser-specific

### Feature Requests

To request new features or report bugs:
- Document the issue with screenshots
- Include browser version and device information
- Describe expected vs. actual behavior

## Appendix: Example Configurations

### Electronics Store (Complete Setup)

```
Collection 1: Smartphone Variants
- Storage: 64GB, 128GB, 256GB, 512GB
- Color: Midnight, Starlight, Blue, Red, Green

Collection 2: Laptop Variants
- Processor: i5, i7, i9
- RAM: 8GB, 16GB, 32GB
- Storage: 256GB SSD, 512GB SSD, 1TB SSD
```

### Fashion Store (Complete Setup)

```
Collection 1: Clothing Variants
- Size: XS, S, M, L, XL, XXL
- Color: Black, White, Navy, Gray, Olive

Collection 2: Shoe Variants
- Size: 7, 8, 9, 10, 11, 12
- Width: Narrow, Regular, Wide

Collection 3: Accessories Variants
- One Size: Fits Most
- Color: Black, Brown, Tan
```

### Specialty Store (Complete Setup)

```
Collection 1: Custom Engraving Products
- Material: Silver, Gold, Platinum
- Size: Small, Medium, Large
- Engraving: (freeform - leave values empty)

Collection 2: Made-to-Order Furniture
- Wood Type: Oak, Walnut, Maple, Cherry
- Finish: Natural, Stained, Painted
- Dimensions: (freeform - custom dimensions)
```

---

## Quick Start Summary

1. **Navigate** to Admin → Variants → Create/Edit Collection
2. **Name** your collection (e.g., "Clothing Variants")
3. **Click column headers** to select property types
4. **Edit cells** to customize values
5. **Add/remove** rows and columns as needed
6. **Save** your collection (Ctrl+Enter)
7. **Assign** collection to products
8. **Test** by editing a product and viewing variants

**That's it!** You now have a professional variant collection system without writing a single line of JSON.

---

*Last Updated: November 13, 2025*
*LittleShop Admin Panel - Phase 2.5*