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:

[
  {
    "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:

[
  {
    "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