wc-composable-product/CLAUDE.md

# WooCommerce plugin for user composable products - AI Context Document

**Author:** Marco Graetsch

## Project Overview

This plugin implements a special product type, for which users can select a limited number of product from a configurable set of simple or variable products. The limit of selectable products should be a global and per-product setting, for which global is the fallback. The set of selectable products can be defined per category, tag or SKU. The price is either a fixed price or the sum of the prices of the selected products. Think of a package of stickers as composable product, where each package can contain $limit number of stickers.

### Key Fact: 100% AI-Generated

This project is proudly **"vibe-coded"** using Claude.AI - the entire codebase was created through AI assistance.

## Technical Stack

- **Language:** PHP 8.3+
- **Framework:** Latest WordPress Plugin API
- **E-commerce:** WooCommerce 10.0+
- **Template Engine:** Twig 3.0 (via Composer)
- **Frontend:** Vanilla JavaScript + jQuery
- **Styling:** Custom CSS
- **Dependency Management:** Composer
- **Internationalization:** WordPress i18n (.pot/.po/.mo files)

## Implementation Details

### Security Best Practices

- All user inputs are sanitized (integers for quantities/prices)
- Nonce verification on form submissions
- Output escaping in templates (`esc_attr`, `esc_html`, `esc_js`)
- Direct file access prevention via `ABSPATH` check

### Translation Ready

All user-facing strings use:

```php
__('Text to translate', 'wc-composable-product')
_e('Text to translate', 'wc-composable-product')
```

Text domain: `wc-composable-product`

**Translation Template:**

- Base `.pot` file created: `languages/wc-composable-product.pot`
- Ready for translation to any locale
- All translatable strings properly marked with text domain

**Available Translations:**

- `en_US` - English (United States) [base language - .pot template]
- `de_DE` - German (Germany, formal) ✓ Complete
- `de_DE_informal` - German (Germany, informal "du") ✓ Complete
- `de_CH` - German (Switzerland, formal "Sie") ✓ Complete
- `de_CH_informal` - German (Switzerland, informal "du") ✓ Complete
- `fr_CH` - French (Switzerland) ✓ Complete
- `it_CH` - Italian (Switzerland) ✓ Complete

All .po files created with 40+ translated strings. Swiss locales include CHF currency formatting in examples (e.g., "CHF 50.-").

To compile translations to .mo files for production:

```bash
for po in languages/*.po; do msgfmt -o "${po%.po}.mo" "$po"; done
```

### Create releases

- The `vendor/` directory MUST be included in releases (Twig dependency required for runtime)
- Running zip from wrong directory creates empty or malformed archives
- Exclusion patterns must match the relative path structure used in zip command
- Always verify the package with `unzip -l` and test extraction before committing
- The `wp-core/` and `wp-plugins/` directories MUST NOT be included in releases
- Releases are stored in `releases/` including checksums

**Important Git Notes:**

- Always commit from `dev` branch first
- Tags should use format `vX.X.X` (e.g., `v1.1.22`)
- Use annotated tags (`-a`) not lightweight tags
- Commit messages should follow the established format with Claude Code attribution
- `.claude/settings.local.json` changes are typically local-only (stash before rebasing)

#### What Gets Released

- All plugin source files
- Compiled vendor dependencies
- Translation files (.mo compiled from .po)
- Assets (CSS, JS)
- Documentation (README, CHANGELOG, etc.)

#### What's Excluded

- Git metadata (`.git/`)
- Development files (`.vscode/`, `.claude/`, `CLAUDE.md`)
- Logs and cache files
- Previous releases
- `composer.lock` (but `vendor/` is included)

## Project Structure

```txt
wc-composable-product/
├── assets/
│   ├── css/
│   │   ├── admin.css          # Admin panel styling
│   │   └── frontend.css       # Customer-facing styles
│   └── js/
│       ├── admin.js           # Product edit interface logic
│       └── frontend.js        # AJAX cart & selection UI
├── cache/                     # Twig template cache (writable)
├── includes/
│   ├── Admin/
│   │   ├── Product_Data.php   # Product data tab & meta boxes
│   │   └── Settings.php       # WooCommerce settings integration
│   ├── Cart_Handler.php       # Add-to-cart & cart display logic
│   ├── Plugin.php             # Main plugin class (Singleton)
│   ├── Product_Selector.php   # Frontend product selector renderer
│   └── Product_Type.php       # Custom WC_Product extension
├── languages/
│   └── wc-composable-product.pot  # Translation template
├── templates/
│   └── product-selector.twig  # Frontend selection interface
├── vendor/                    # Composer dependencies (gitignored)
├── composer.json              # Dependency configuration
├── wc-composable-product.php  # Main plugin file
└── [Documentation files]      # README, INSTALL, IMPLEMENTATION, etc.
```

## Architecture Overview

### Core Classes

1. **Plugin.php** - Main singleton class
   - Initializes Twig template engine
   - Registers hooks and filters
   - Manages asset enqueuing
   - Provides template rendering API

2. **Product_Type.php** - Custom WooCommerce product type
   - Extends `WC_Product`
   - Handles selection criteria (category/tag/SKU)
   - Manages pricing modes (fixed/sum)
   - Queries available products dynamically

3. **Cart_Handler.php** - Cart integration
   - Validates product selections
   - Stores selected products in cart meta
   - Calculates dynamic pricing
   - Displays selections in cart/checkout

4. **Product_Selector.php** - Frontend renderer
   - Renders Twig template with product data
   - Applies display settings (images/prices/total)

5. **Admin/Product_Data.php** - Product edit interface
   - Adds "Composable Options" tab
   - Category/tag/SKU selection fields
   - Saves product metadata

6. **Admin/Settings.php** - Global settings
   - WooCommerce settings tab integration
   - Default limits and pricing mode
   - Display preferences

### Data Flow

**Product Creation:**

1. Admin selects "Composable product" type
2. Configures criteria, limits, pricing in product data tab
3. Metadata saved: `_composable_*` fields

**Frontend Display:**

1. `Cart_Handler::render_product_selector()` called on product page
2. `Product_Type::get_available_products()` queries matching products
3. `Product_Selector::render()` passes data to Twig template
4. JavaScript handles selection UI and AJAX

**Add to Cart:**

1. Customer selects products (JS validates limit)
2. AJAX request with `composable_products[]` array
3. `Cart_Handler::validate_add_to_cart()` server-side validation
4. `Cart_Handler::add_cart_item_data()` stores selections
5. `Cart_Handler::calculate_cart_item_price()` applies pricing

## Development Workflow

### Initial Setup

```bash
composer install
```

### Making Changes

1. **PHP Classes:** Edit files in `includes/` or `includes/Admin/`
2. **Templates:** Modify `templates/*.twig` (cache clears on auto-reload)
3. **Styles:** Update `assets/css/*.css`
4. **JavaScript:** Edit `assets/js/*.js`
5. **Translations:** Update `.pot` file, create `.po` translations

### Testing Checklist

- [ ] Create composable product in admin
- [ ] Test each selection criteria type (category/tag/SKU)
- [ ] Verify selection limit enforcement
- [ ] Test both pricing modes (fixed/sum)
- [ ] Check AJAX add-to-cart functionality
- [ ] Verify cart display shows selected products
- [ ] Test checkout process
- [ ] Check responsive design on mobile
- [ ] Validate all strings are translatable

### Creating Releases

```bash
# From project root
zip -r wc-composable-product-vX.X.X.zip . \
  -x "*.git*" "*.vscode*" "*.claude*" "CLAUDE.md" \
  "wp-core" "wp-plugins" "*.log" "composer.lock" \
  "cache/*" "releases/*" "*.zip"

# Verify contents
unzip -l wc-composable-product-vX.X.X.zip

# IMPORTANT: Ensure vendor/ is included!
```

## Session History

### v1.0.0 - Initial Implementation & Release (2024-12-31)

#### Session 1: Core Implementation

- Complete plugin implementation from scratch
- All 6 core PHP classes with PSR-4 autoloading
- Twig template system integration
- Responsive frontend with AJAX functionality
- Admin interface with WooCommerce integration
- Full i18n support with .pot template
- Comprehensive documentation (README, INSTALL, IMPLEMENTATION)
- Initial commit to `main` branch (1edb0be)

#### Session 2: Documentation & Translations

- Enhanced CLAUDE.md with complete architecture documentation
- Created 6 complete translation files (.po):
  - German (Germany - formal & informal)
  - German (Switzerland - formal & informal)
  - French (Switzerland)
  - Italian (Switzerland)
- All 40+ strings translated with locale-specific terminology
- Swiss locales include CHF currency formatting examples

#### Session 3: Release Creation

- Created annotated git tag `v1.0.0`
- Generated release package: `wc-composable-product-v1.0.0.zip` (371 KB)
- Verified vendor/ directory inclusion (336 Twig files)
- Created SHA-256 and MD5 checksums
- Stored in `releases/` directory (gitignored)

**Key decisions made:**

- Used Singleton pattern for main Plugin class
- Twig for templating (per requirements)
- Vanilla JS + jQuery for frontend (WooCommerce standard)
- Grid layout for product selector (responsive)
- AJAX add-to-cart for better UX
- Meta-based configuration storage

**Files created:** 28 files total (21 PHP/templates + 7 translations), 3,842 lines of code

**Git workflow:**

- Main branch: Initial implementation (1edb0be)
- Dev branch: +2 commits for documentation and translations
- Tagged: v1.0.0 on dev branch (8c17734)

**What works:**

- Product type registration ✓
- Admin product data tab ✓
- Category/tag/SKU selection ✓
- Frontend product selector ✓
- AJAX add-to-cart ✓
- Cart integration ✓
- Pricing calculation (both modes) ✓
- Full multilingual support (6 locales) ✓
- Production-ready release package ✓

**Known limitations:**

- Currently only simple products in selection (not variable)
- No grouped product support
- No automatic stock deduction for selected items
- Template cache requires manual clearing after updates
- Translations are .po files only (not compiled to .mo yet)

**Release details:**

- Package size: 371 KB
- Includes: All source + vendor dependencies + translations
- Checksums: SHA-256 and MD5 provided
- Ready for WordPress installation (no composer install needed)

**Future enhancements to consider:**

- Variable product support
- Quantity selection per item
- Visual bundle preview
- Product recommendations
- Stock management integration
- Selection presets/templates
- Compile .mo translation files

---

**For AI Assistants:**

When starting a new session on this project:

1. Read this CLAUDE.md file first
2. Review IMPLEMENTATION.md for technical details
3. Check git log for recent changes
4. Verify you're on the `dev` branch before making changes
5. Run `composer install` if vendor/ is missing
6. Test changes before committing
7. Follow commit message format with Claude Code attribution
8. Update this session history section with learnings

Always refer to this document when starting work on this project. Good luck!