Consolidate documentation, bump to v1.2.1

Condense CLAUDE.md from ~1960 to ~160 lines keeping only essential architecture and lessons learned. Merge INSTALL.md into README.md and IMPLEMENTATION.md into CLAUDE.md, then delete the source files. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Update .gitignore: add logs/ dir and compiled .mo files
2026-03-01 12:14:07 +01:00 · 2026-03-01 12:04:34 +01:00
7 changed files with 205 additions and 2491 deletions
--- a/.gitignore
+++ b/.gitignore
@@ -1,14 +1,8 @@
-# Linked sources
-wp-core
-wp-plugins
-tpp
-
 # Editor swap files
 *.*swp

 # Composer
 vendor/
-composer.lock

 # Cache
 cache/
@@ -16,9 +10,14 @@ cache/
 # Development files
 .vscode/
 .idea/
+logs/
 *.log

 # OS files
 .DS_Store
 Thumbs.db
+.directory
+
+# Binary files
+languages/*.mo

--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,6 +5,20 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

+## [1.2.1] - 2026-03-01
+
+### Changed
+
+- Consolidated documentation: merged INSTALL.md into README.md, merged IMPLEMENTATION.md into CLAUDE.md
+- Condensed CLAUDE.md from ~1960 lines to ~160 lines, keeping only essential architecture and lessons learned
+- README.md now includes full installation guide, usage tutorial, and troubleshooting section
+- Cleaned up .gitignore
+
+### Removed
+
+- INSTALL.md (content merged into README.md)
+- IMPLEMENTATION.md (content merged into CLAUDE.md)
+
 ## [1.2.0] - 2026-03-01

 ### Fixed
--- a/CLAUDE.md
+++ b/CLAUDE.md
--- a/IMPLEMENTATION.md
+++ b/IMPLEMENTATION.md
@@ -1,434 +0,0 @@
-# WooCommerce Composable Products - Implementation Summary
-
-## Overview
-
-This document provides a technical overview of the WooCommerce Composable Products plugin implementation.
-
-**Version:** 1.0.0
-**Created:** 2024-12-31
-**AI-Generated:** 100% created with Claude.AI assistance
-
-## Architecture
-
-### Plugin Structure
-
-```txt
-wc-composable-product/
-├── assets/                  # Frontend assets
-│   ├── css/
-│   │   ├── admin.css       # Admin styles
-│   │   └── frontend.css    # Frontend styles
-│   └── js/
-│       ├── admin.js        # Admin JavaScript
-│       └── frontend.js     # Frontend JavaScript
-├── cache/                  # Twig template cache
-├── includes/               # PHP classes
-│   ├── Admin/
-│   │   ├── Product_Data.php    # Product data tab
-│   │   └── Settings.php        # Settings page
-│   ├── Cart_Handler.php        # Cart integration
-│   ├── Plugin.php              # Main plugin class
-│   ├── Product_Selector.php    # Frontend selector
-│   └── Product_Type.php        # Custom product type
-├── languages/              # Translation files
-│   └── wc-composable-product.pot
-├── templates/              # Twig templates
-│   └── product-selector.twig
-└── wc-composable-product.php   # Main plugin file
-```
-
-## Core Components
-
-### 1. Main Plugin Class (`Plugin.php`)
-
-**Responsibilities:**
-
- Singleton pattern implementation
- Twig template engine initialization
- Hook registration
- Component initialization
- Asset enqueuing
-
-**Key Methods:**
-
- `instance()`: Get singleton instance
- `init_twig()`: Initialize Twig with WordPress functions
- `render_template()`: Render Twig templates
- `add_product_type()`: Register composable product type
-
-### 2. Product Type (`Product_Type.php`)
-
-**Extends:** `WC_Product`
-
-**Key Features:**
-
- Custom product type: `composable`
- Selection limit management (per-product or global)
- Pricing mode (fixed or sum)
- Product selection criteria (category/tag/SKU)
- Dynamic product availability
- Price calculation
-
-**Key Methods:**
-
- `get_selection_limit()`: Get max selectable items
- `get_pricing_mode()`: Get pricing calculation mode
- `get_available_products()`: Query available products
- `calculate_composed_price()`: Calculate final price
-
-### 3. Admin Settings (`Admin/Settings.php`)
-
-**Extends:** `WC_Settings_Page`
-
-**Global Settings:**
-
- Default selection limit
- Default pricing mode
- Display options (images, prices, total)
-
-**Integration:** Adds tab to WooCommerce Settings
-
-### 4. Product Data Tab (`Admin/Product_Data.php`)
-
-**Responsibilities:**
-
- Add "Composable Options" tab to product edit page
- Render selection criteria fields
- Save product meta data
- Dynamic field visibility based on criteria type
-
-**Saved Meta:**
-
- `_composable_selection_limit`: Item limit
- `_composable_pricing_mode`: Pricing calculation
- `_composable_criteria_type`: Selection method
- `_composable_categories`: Selected categories
- `_composable_tags`: Selected tags
- `_composable_skus`: SKU list
-
-### 5. Product Selector (`Product_Selector.php`)
-
-**Responsibilities:**
-
- Render frontend product selection interface
- Prepare data for Twig template
- Apply display settings
-
-**Template Variables:**
-
- `products`: Available products array
- `selection_limit`: Max selections
- `pricing_mode`: Pricing calculation
- `show_images/prices/total`: Display flags
-
-### 6. Cart Handler (`Cart_Handler.php`)
-
-**Responsibilities:**
-
- Validate product selection
- Add selected products to cart data
- Calculate dynamic pricing
- Display selected products in cart
-
-**Hooks:**
-
- `woocommerce_add_to_cart_validation`: Validate selections
- `woocommerce_add_cart_item_data`: Store selections
- `woocommerce_before_calculate_totals`: Update prices
- `woocommerce_get_item_data`: Display in cart
-
-## Frontend Implementation
-
-### Product Selector Template (`product-selector.twig`)
-
-**Features:**
-
- Responsive grid layout
- Checkbox-based selection
- Product images and prices
- Real-time total calculation
- AJAX add-to-cart
-
-**Data Attributes:**
-
- `data-product-id`: Composable product ID
- `data-selection-limit`: Max selections
- `data-pricing-mode`: Pricing mode
- `data-price`: Individual product prices
-
-### JavaScript (`frontend.js`)
-
-**Functionality:**
-
- Selection limit enforcement
- Visual feedback on selection
- Real-time price updates (sum mode)
- AJAX cart operations
- Error/success messages
-
-**Key Functions:**
-
- `handleCheckboxChange()`: Selection logic
- `updateTotalPrice()`: Calculate total
- `addToCart()`: AJAX add-to-cart
- `showMessage()`: User feedback
-
-### CSS Styling
-
-**Approach:**
-
- Grid-based layout (responsive)
- Card-style product items
- Visual selection states
- Mobile-first design
- Breakpoints: 768px, 480px
-
-## Data Flow
-
-### Creating a Composable Product
-
-1. Admin selects "Composable product" type
-2. Configure selection limit and pricing mode
-3. Choose selection criteria (category/tag/SKU)
-4. Save product metadata
-5. WooCommerce registers product with custom type
-
-### Frontend Display
-
-1. Customer visits product page
-2. `Cart_Handler` renders `Product_Selector`
-3. `Product_Type::get_available_products()` queries products
-4. Twig template renders grid with products
-5. JavaScript handles interactions
-
-### Adding to Cart
-
-1. Customer selects products (JavaScript validation)
-2. Click "Add to Cart" button
-3. AJAX request with selected product IDs
-4. `Cart_Handler::validate_add_to_cart()` validates
-5. `Cart_Handler::add_cart_item_data()` stores selections
-6. `Cart_Handler::calculate_cart_item_price()` updates price
-7. Product added to cart with custom data
-
-### Cart Display
-
-1. WooCommerce loads cart
-2. `Cart_Handler::get_cart_item_from_session()` restores data
-3. `Cart_Handler::display_cart_item_data()` shows selections
-4. Price calculated dynamically on each cart load
-
-## Security Implementation
-
-### Input Sanitization
-
- **Integers:** `absint()` for IDs and limits
- **Text:** `sanitize_text_field()` for modes and types
- **Textarea:** `sanitize_textarea_field()` for SKUs
- **Arrays:** `array_map()` with sanitization functions
-
-### Output Escaping
-
- **HTML:** `esc_html()`, `esc_html_e()`
- **Attributes:** `esc_attr()`
- **URLs:** `esc_url()`
- **JavaScript:** Localized scripts with escaped data
-
-### Validation
-
- Selection limit enforcement
- Product availability verification
- Cart data validation
- Nonce verification (via WooCommerce)
-
-## Internationalization
-
-### Text Domain
-
-`wc-composable-product`
-
-### Translation Functions
-
- `__()`: Return translated string
- `_e()`: Echo translated string
- `sprintf()` with `__()`: Variable substitution
-
-### POT File
-
-Generated template: `languages/wc-composable-product.pot`
-
-**Supported Locales (per CLAUDE.md):**
-
- en_US (English)
- de_DE, de_DE_informal (German - Germany)
- de_CH, de_CH_informal (German - Switzerland)
- fr_CH (French - Switzerland)
- it_CH (Italian - Switzerland)
-
-## Performance Considerations
-
-### Caching
-
- Twig templates cached in `cache/` directory
- Auto-reload enabled in debug mode
- Optimized Composer autoloader
-
-### Database Queries
-
- Efficient `WP_Query` for product selection
- Meta queries for SKU filtering
- Taxonomy queries for category/tag filtering
-
-### Asset Loading
-
- Scripts only on relevant pages
- Minification ready (use build tools)
- Conditional enqueuing
-
-## Extensibility
-
-### Hooks & Filters
-
-**Available Filters:**
-
- `wc_composable_settings`: Modify settings array
- `woocommerce_product_class`: Custom product class
- `product_type_selector`: Product type registration
-
-**Customization Points:**
-
- Twig templates (override in theme)
- CSS styling (enqueue custom styles)
- JavaScript behavior (extend object)
-
-### Developer API
-
-```php
-// Get composable product
-$product = wc_get_product($product_id);
-
-// Check if composable
-if ($product->get_type() === 'composable') {
-    // Get available products
-    $products = $product->get_available_products();
-
-    // Get selection limit
-    $limit = $product->get_selection_limit();
-
-    // Calculate price
-    $price = $product->calculate_composed_price($selected_ids);
-}
-```
-
-## Testing Checklist
-
-### Admin Testing
-
- [ ] Product type appears in dropdown
- [ ] Composable Options tab displays
- [ ] Selection criteria toggle works
- [ ] Meta data saves correctly
- [ ] Settings page accessible
- [ ] Global defaults apply
-
-### Frontend Testing
-
- [ ] Product selector renders
- [ ] Selection limit enforced
- [ ] Price calculation accurate (both modes)
- [ ] AJAX add-to-cart works
- [ ] Cart displays selections
- [ ] Checkout processes correctly
-
-### Edge Cases
-
- [ ] Empty criteria (no products)
- [ ] Out of stock products excluded
- [ ] Invalid product selections rejected
- [ ] Multiple cart items unique
- [ ] Session persistence
-
-## Known Limitations
-
-1. **Variable Products:** Currently supports simple products in selection
-2. **Grouped Products:** Cannot be used as selectable items
-3. **Stock Management:** No automatic stock reduction for selected items
-4. **Caching:** Template cache needs manual clearing after updates
-
-## Future Enhancements
-
-Potential features for future versions:
-
- Variable product support in selection
- Quantity selection per item (not just presence)
- Visual bundle previews
- Advanced pricing rules
- Stock management integration
- Product recommendations
- Selection templates/presets
- Multi-currency support enhancements
-
-## Dependencies
-
-### Runtime
-
- PHP 8.3+
- WordPress 6.0+
- WooCommerce 8.0+
- Twig 3.0 (via Composer)
-
-### Development
-
- Composer for dependency management
- WP-CLI for i18n operations (optional)
-
-## Deployment
-
-### Production Checklist
-
-1. Run `composer install --no-dev --optimize-autoloader`
-2. Ensure `vendor/` directory is included
-3. Ensure `cache/` directory is writable
-4. Test on staging environment
-5. Clear all caches after activation
-6. Verify WooCommerce compatibility
-
-### Release Package
-
-Must include:
-
- All PHP files
- `vendor/` directory
- Assets (CSS, JS)
- Templates
- Language files
- Documentation
-
-Must exclude:
-
- `.git/` directory
- `composer.lock`
- Development files
- `wp-core/`, `wp-plugins/` symlinks
-
-## Support & Maintenance
-
-### Code Standards
-
- WordPress Coding Standards
- WooCommerce best practices
- PSR-4 autoloading
- Inline documentation
-
-### Version Control
-
- Semantic versioning (MAJOR.MINOR.PATCH)
- Changelog maintained
- Annotated git tags
- Development on `dev` branch
-
---
-
-**Last Updated:** 2024-12-31
-**Maintainer:** Marco Graetsch
-**AI Assistant:** Claude.AI (Anthropic)
--- a/INSTALL.md
+++ b/INSTALL.md
@@ -1,150 +0,0 @@
-# Installation Guide
-
-## Requirements
-
-Before installing the WooCommerce Composable Products plugin, ensure your system meets these requirements:
-
- **PHP**: 8.3 or higher
- **WordPress**: 6.0 or higher
- **WooCommerce**: 8.0 or higher
- **Composer**: For dependency management
-
-## Installation Steps
-
-### 1. Upload Plugin Files
-
-Upload the plugin directory to your WordPress installation:
-
-```bash
-/wp-content/plugins/wc-composable-product/
-```
-
-### 2. Install Dependencies
-
-Navigate to the plugin directory and install dependencies:
-
-```bash
-cd /wp-content/plugins/wc-composable-product/
-composer install --no-dev --optimize-autoloader
-```
-
-### 3. Activate Plugin
-
-1. Log in to your WordPress admin panel
-2. Navigate to **Plugins > Installed Plugins**
-3. Find "WooCommerce Composable Products"
-4. Click **Activate**
-
-### 4. Configure Settings
-
-After activation, configure the plugin:
-
-1. Navigate to **WooCommerce > Settings**
-2. Click on the **Composable Products** tab
-3. Configure default settings:
-   - **Default Selection Limit**: Number of items customers can select (default: 5)
-   - **Default Pricing Mode**: Choose between "Sum of selected products" or "Fixed price"
-   - **Display Options**: Toggle product images, prices, and totals
-
-## Creating Your First Composable Product
-
-### Step 1: Create a New Product
-
-1. Go to **Products > Add New**
-2. Enter a product name (e.g., "Custom Sticker Pack")
-
-### Step 2: Set Product Type
-
-1. In the **Product Data** panel, select **Composable product** from the dropdown
-
-### Step 3: Configure General Settings
-
-In the **General** tab:
- Set a **Regular price** (used if pricing mode is "Fixed")
- Configure **Selection Limit** (leave empty to use global default)
- Choose **Pricing Mode** (leave empty to use global default)
-
-### Step 4: Configure Composable Options
-
-Click on the **Composable Options** tab:
-
-1. **Selection Criteria**: Choose how to select available products
-   - **By Category**: Select product categories
-   - **By Tag**: Select product tags
-   - **By SKU**: Enter comma-separated SKUs
-
-2. Based on your selection:
-   - **Categories**: Select one or more categories from the dropdown
-   - **Tags**: Select one or more tags from the dropdown
-   - **SKUs**: Enter SKUs like: `STICKER-01, STICKER-02, STICKER-03`
-
-### Step 5: Publish
-
-Click **Publish** to make your composable product live.
-
-## Frontend Usage
-
-When customers visit your composable product:
-
-1. They see a grid of available products based on your criteria
-2. They can select up to the configured limit
-3. The total price updates in real-time (if using sum pricing mode)
-4. Click "Add to Cart" to add the composition to their cart
-5. Selected products are displayed in the cart
-
-## Troubleshooting
-
-### Plugin Won't Activate
-
- Ensure WooCommerce is installed and activated first
- Check PHP version (must be 8.3+)
- Verify Composer dependencies are installed
-
-### Products Not Showing in Selector
-
- Check that products are published and in stock
- Verify the selection criteria (category/tag/SKU) is correct
- Ensure products match the criteria you configured
-
-### Twig Template Errors
-
- Ensure the `vendor/` directory exists and contains Twig
- Run `composer install` again
- Check that the `cache/` directory is writable
-
-### JavaScript Not Working
-
- Clear browser cache
- Check browser console for errors
- Ensure jQuery is loaded (WooCommerce includes it)
-
-## Updating
-
-When updating the plugin:
-
-1. Deactivate the plugin
-2. Replace plugin files
-3. Run `composer install --no-dev --optimize-autoloader`
-4. Reactivate the plugin
-5. Clear all caches (WordPress, browser, CDN)
-
-## Uninstallation
-
-To completely remove the plugin:
-
-1. Deactivate the plugin
-2. Delete the plugin from the Plugins page
-3. Optionally clean up database entries (WooCommerce will handle this automatically)
-
-## Support
-
-For issues and feature requests:
- GitHub: https://github.com/magdev/wc-composable-product/issues
- Documentation: See README.md
-
-## Next Steps
-
- Customize the template by editing `templates/product-selector.twig`
- Modify styles in `assets/css/frontend.css`
- Translate the plugin using the provided `.pot` file
- Create categories/tags for easier product organization
--- a/README.md
+++ b/README.md
@@ -1,12 +1,8 @@
 # WooCommerce Composable Products

-Create composable products where customers can select a limited number of items from a configurable set of products.
+Create composable products where customers can select a limited number of items from a configurable set of products. Think of it as a "build your own gift box" or "create your sticker pack" feature.

-## Description
-
-This plugin adds a new product type to WooCommerce that allows customers to build their own product bundles by selecting from a predefined set of simple or variable products. Think of it as a "build your own gift box" or "create your sticker pack" feature.
-
-### Key Features
+## Key Features

 - **Custom Product Type**: New "Composable Product" type in WooCommerce
 - **Flexible Selection**: Define available products by category, tag, or SKU
@@ -23,33 +19,94 @@ This plugin adds a new product type to WooCommerce that allows customers to buil
 - PHP 8.3 or higher
 - WordPress 6.0 or higher
 - WooCommerce 8.0 or higher
+- Composer (for dependency management)

 ## Installation

-1. Upload the plugin files to `/wp-content/plugins/wc-composable-product/`
-2. Run `composer install --no-dev` in the plugin directory
-3. Activate the plugin through the 'Plugins' menu in WordPress
-4. Configure global settings under WooCommerce > Settings > Composable Products
+### From Release Package
+
+1. Download the latest release ZIP from the releases page
+2. In WordPress admin, go to **Plugins > Add New > Upload Plugin**
+3. Upload the ZIP file and click **Install Now**
+4. Activate the plugin through the **Plugins** menu
+5. Configure global settings under **WooCommerce > Settings > Composable Products**
+
+### From Source
+
+1. Upload the plugin directory to `/wp-content/plugins/wc-composable-product/`
+2. Install dependencies:
+
+   ```bash
+   cd /wp-content/plugins/wc-composable-product/
+   composer install --no-dev --optimize-autoloader
+   ```
+
+3. Activate the plugin through the **Plugins** menu in WordPress
+4. Configure global settings under **WooCommerce > Settings > Composable Products**

 ## Usage

-### Creating a Composable Product
-
-1. Go to Products > Add New
-2. Select "Composable Product" as the product type
-3. Configure product details:
-   - Set the selection limit (or use global default)
-   - Choose pricing mode (fixed or sum)
-   - Define available products by category, tag, or SKU
-4. Publish the product
-
 ### Global Settings

-Navigate to WooCommerce > Settings > Composable Products to configure:
+Navigate to **WooCommerce > Settings > Composable Products** to configure:

- Default selection limit
- Default pricing mode
- Display options
+- **Default Selection Limit**: Number of items customers can select (default: 5)
+- **Default Pricing Mode**: Choose between "Sum of selected products" or "Fixed price"
+- **Display Options**: Toggle product images, prices, and totals
+
+### Creating a Composable Product
+
+1. Go to **Products > Add New**
+2. Select **Composable product** from the Product Data dropdown
+3. In the **General** tab:
+   - Set a **Regular price** (used when pricing mode is "Fixed")
+   - Configure **Selection Limit** (leave empty to use global default)
+   - Choose **Pricing Mode** (leave empty to use global default)
+4. Click the **Composable Options** tab:
+   - **Selection Criteria**: Choose how to define available products
+     - **By Category**: Select one or more product categories
+     - **By Tag**: Select one or more product tags
+     - **By SKU**: Enter comma-separated SKUs (e.g., `STICKER-01, STICKER-02`)
+5. Click **Publish**
+
+### Frontend Behavior
+
+When customers visit a composable product page:
+
+1. A grid of available products is displayed based on configured criteria
+2. Customers select up to the configured limit via checkboxes
+3. Total price updates in real-time (in sum pricing mode)
+4. Stock indicators show availability (green/orange/red badges)
+5. Click "Add to Cart" to add the composition to cart
+6. Selected products are listed in the cart and checkout
+
+## Troubleshooting
+
+### Plugin Won't Activate
+
+- Ensure WooCommerce is installed and activated first
+- Check PHP version (must be 8.3+)
+- Verify Composer dependencies are installed (`vendor/` directory exists)
+
+### Products Not Showing in Selector
+
+- Check that products are published
+- Verify the selection criteria (category/tag/SKU) matches existing products
+- Ensure the criteria type and values are saved in the Composable Options tab
+
+### Twig Template Errors
+
+- Ensure the `vendor/` directory exists and contains Twig
+- Run `composer install` again
+- Check that the `cache/` directory is writable
+
+### Updating
+
+1. Deactivate the plugin
+2. Replace plugin files (or upload new release ZIP)
+3. If installed from source: run `composer install --no-dev --optimize-autoloader`
+4. Reactivate the plugin
+5. Clear all caches (WordPress, browser, CDN)

 ## Development

@@ -96,4 +153,4 @@ Marco Graetsch

 ## Support

-For issues and feature requests, please use the GitHub issue tracker.
+For issues and feature requests, please use the issue tracker.
--- a/wc-composable-product.php
+++ b/wc-composable-product.php
@@ -4,7 +4,7 @@
 * Plugin Name: WooCommerce Composable Products
 * Plugin URI: https://src.bundespruefstelle.ch/magdev/wc-composable-product
 * Description: Create composable products where customers select a limited number of items from a configurable set
- * Version: 1.2.0
+ * Version: 1.2.1
 * Author: Marco Graetsch
 * Author URI: https://src.bundespruefstelle.ch/magdev
 * License: GPL v3 or later
@@ -20,7 +20,7 @@
 defined('ABSPATH') || exit;

 // Define plugin constants
-define('WC_COMPOSABLE_PRODUCT_VERSION', '1.2.0');
+define('WC_COMPOSABLE_PRODUCT_VERSION', '1.2.1');
 define('WC_COMPOSABLE_PRODUCT_FILE', __FILE__);
 define('WC_COMPOSABLE_PRODUCT_PATH', plugin_dir_path(__FILE__));
 define('WC_COMPOSABLE_PRODUCT_URL', plugin_dir_url(__FILE__));