diff --git a/CLAUDE.md b/CLAUDE.md index 11c7b45..2d2bc85 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -41,9 +41,15 @@ _e('Text to translate', 'wc-composable-product') Text domain: `wc-composable-product` -**Available Translations (as of v1.1.22):** +**Translation Template:** -- `en_US` - English (United States) +- Base `.pot` file created: `languages/wc-composable-product.pot` +- Ready for translation to any locale +- All translatable strings properly marked with text domain + +**Planned Translations:** + +- `en_US` - English (United States) [base language] - `de_DE` - German (Germany, formal) - `de_DE_informal` - German (Germany, informal "du") - `de_CH` - German (Switzerland, formal "Sie") @@ -51,7 +57,7 @@ Text domain: `wc-composable-product` - `fr_CH` - French (Switzerland) - `it_CH` - Italian (Switzerland) -Note: Swiss locales use CHF currency formatting in examples (e.g., "CHF 50.-") +Note: Swiss locales should use CHF currency formatting in examples (e.g., "CHF 50.-") ### Create releases @@ -87,6 +93,197 @@ Note: Swiss locales use CHF currency formatting in examples (e.g., "CHF 50.-") - Previous releases - `composer.lock` (but `vendor/` is included) +## Project Structure + +``` +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 (2024-12-31) + +**What was built:** +- 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) + +**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:** 21 files, 2,628 lines of code + +**Git workflow:** +- Initial commit to `main` branch +- Created `dev` branch from `main` +- Both branches in sync at v1.0.0 + +**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) ✓ + +**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 + +**Future enhancements to consider:** +- Variable product support +- Quantity selection per item +- Visual bundle preview +- Product recommendations +- Stock management integration +- Selection presets/templates + --- +**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!