Update documentation to v1.1.20 with current features

- Updated all version references to 1.1.20 - Updated WordPress requirement to 6.0+ (tested up to 6.9.x) - Updated WooCommerce requirement to 8.0+ (tested up to 10.x) - Added comprehensive file structure showing Twig templates - Added WooCommerce Blocks compatibility documentation - Added tier labels feature documentation (v1.1.7) - Added quantity restrictions feature documentation (v1.1.0) - Added new usage examples for tier labels and quantity restrictions - Updated INSTALLATION.md with complete directory structure - Updated README.md with current version changelog - Updated QUICKSTART.md with 8 pro tips including new features - Updated USAGE_EXAMPLES.md with 6 complete examples - Documented WooCommerce Blocks support and v1.1.20 critical fix 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
2025-12-23 00:32:19 +01:00
parent 556cba20fa
commit 0c75234dcb
5 changed files with 192 additions and 47 deletions
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -301,7 +301,7 @@ sha256sum wc-tier-and-package-prices-X.X.X.zip > wc-tier-and-package-prices-X.X.

 ### What's Excluded
 - Git metadata (`.git/`)
- Development files (`.vscode/`, `.idea/`, `.claude/`, `CLAUDE.md`)
+- Development files (`.vscode/`, `.claude/`, `CLAUDE.md`)
 - Logs and cache files
 - Previous releases
 - `composer.lock` (but `vendor/` is included)
--- a/INSTALLATION.md
+++ b/INSTALLATION.md
@@ -90,8 +90,8 @@ After activation, you should see:

 Before installation, verify:

- ✓ WordPress 5.8 or higher
- ✓ WooCommerce 5.0 or higher installed and activated
+- ✓ WordPress 6.0 or higher (tested up to 6.9.x)
+- ✓ WooCommerce 8.0 or higher (tested up to 10.x) installed and activated
 - ✓ PHP 7.4 or higher
 - ✓ Write permissions in `/wp-content/plugins/` directory

@@ -153,16 +153,34 @@ wp-content/
        ├── USAGE_EXAMPLES.md
        ├── includes/
        │   ├── class-wc-tpp-admin.php
+        │   ├── class-wc-tpp-settings.php
        │   ├── class-wc-tpp-cart.php
        │   ├── class-wc-tpp-frontend.php
-        │   └── class-wc-tpp-product-meta.php
-        └── assets/
-            ├── css/
-            │   ├── admin.css
-            │   └── frontend.css
-            └── js/
-                ├── admin.js
-                └── frontend.js
+        │   ├── class-wc-tpp-product-meta.php
+        │   └── class-wc-tpp-template-loader.php
+        ├── templates/
+        │   ├── admin/
+        │   │   ├── tier-row.twig
+        │   │   └── package-row.twig
+        │   └── frontend/
+        │       ├── pricing-table.twig
+        │       ├── tier-pricing-table.twig
+        │       └── package-pricing-display.twig
+        ├── assets/
+        │   ├── css/
+        │   │   ├── admin.css
+        │   │   └── frontend.css
+        │   └── js/
+        │       ├── admin.js
+        │       └── frontend.js
+        ├── languages/
+        │   ├── wc-tier-package-prices.pot
+        │   ├── wc-tier-package-prices-de_DE.po
+        │   ├── wc-tier-package-prices-de_DE.mo
+        │   ├── wc-tier-package-prices-de_CH_informal.po
+        │   └── wc-tier-package-prices-de_CH_informal.mo
+        └── vendor/
+            └── (Twig and dependencies)
 ```

 ## Getting Help
--- a/QUICKSTART.md
+++ b/QUICKSTART.md
@@ -1,6 +1,6 @@
 # Quick Start Guide

-Get started with WooCommerce Tier and Package Prices in 5 minutes!
+Get started with WooCommerce Tier and Package Prices (v1.1.20) in 5 minutes!

 ## Step 1: Install (2 minutes)

@@ -79,8 +79,11 @@ Use packages for common bundles (6-pack, dozen, case)
 1. **Round Numbers**: Use 10, 25, 50, 100 for tiers
 2. **Meaningful Savings**: Offer at least 10% off per tier
 3. **Label Packages**: "Family Pack" sells better than "4-pack"
-4. **Test Checkout**: Always complete a test order
-5. **Mobile Check**: View on phone to verify responsiveness
+4. **Label Tiers**: Use descriptive labels like "Wholesale Price" or "Bulk Discount"
+5. **Test Checkout**: Always complete a test order
+6. **Mobile Check**: View on phone to verify responsiveness
+7. **Quantity Restrictions**: Enable package restrictions to prevent arbitrary quantities
+8. **Blocks Compatible**: Works with both classic and block-based carts/checkout

 ## Need More Help?

--- a/README.md
+++ b/README.md
@@ -110,12 +110,22 @@ When editing a product, scroll to the **Product data** panel:

 ```
 wc-tier-and-package-prices/
-├── wc-tier-and-package-prices.php    # Main plugin file
+├── wc-tier-and-package-prices.php    # Main plugin file (v1.1.20)
 ├── includes/
-│   ├── class-wc-tpp-admin.php        # Admin settings
+│   ├── class-wc-tpp-admin.php        # Admin settings integration
+│   ├── class-wc-tpp-settings.php     # WooCommerce settings page
 │   ├── class-wc-tpp-product-meta.php # Product meta boxes
-│   ├── class-wc-tpp-frontend.php     # Frontend display
-│   └── class-wc-tpp-cart.php         # Cart price calculations
+│   ├── class-wc-tpp-frontend.php     # Frontend display logic
+│   ├── class-wc-tpp-cart.php         # Cart price calculations
+│   └── class-wc-tpp-template-loader.php # Twig template engine
+├── templates/
+│   ├── admin/
+│   │   ├── tier-row.twig            # Tier pricing input row
+│   │   └── package-row.twig         # Package pricing input row
+│   └── frontend/
+│       ├── pricing-table.twig        # Main pricing display wrapper
+│       ├── tier-pricing-table.twig   # Tier pricing table
+│       └── package-pricing-display.twig # Package selection UI
 ├── assets/
 │   ├── css/
 │   │   ├── admin.css                 # Admin styles
@@ -123,7 +133,16 @@ wc-tier-and-package-prices/
 │   └── js/
 │       ├── admin.js                  # Admin JavaScript
 │       └── frontend.js               # Frontend JavaScript
-└── README.md
+├── languages/
+│   ├── wc-tier-package-prices.pot    # Translation template
+│   ├── wc-tier-package-prices-*.po   # Translation sources
+│   └── wc-tier-package-prices-*.mo   # Compiled translations
+├── vendor/                            # Composer dependencies (Twig)
+├── CHANGELOG.md                       # Complete version history
+├── INSTALLATION.md                    # Installation guide
+├── QUICKSTART.md                      # Quick start guide
+├── USAGE_EXAMPLES.md                  # Usage examples
+└── README.md                          # This file
 ```

 ## Requirements
@@ -164,39 +183,51 @@ This plugin is licensed under the GPL v2 or later.

 ## Changelog

-### Version 1.0.0 - 2025-12-21
+### Version 1.1.20 - 2025-12-23

-#### Compatibility Updates
+**Current Release** - Latest stable version with full WooCommerce Blocks support

- ✅ Updated for WooCommerce 10.x compatibility
- ✅ Updated for WordPress 6.9.x compatibility
- ✅ Added HPOS (High-Performance Order Storage) support
- ✅ Declared compatibility with WooCommerce Custom Order Tables
+#### Fixed
+- **CRITICAL:** WooCommerce Blocks fatal error in mini-cart and cart blocks
+- Fixed `woocommerce_store_api_product_quantity_editable` filter signature mismatch
+- Filter now correctly accepts `WC_Product` object instead of cart item array
+- Resolves "Cannot use object of type WC_Product_Simple as array" fatal error

-#### Security Enhancements
+#### Technical Details
+- Updated `block_quantity_editable()` method signature to accept product object
+- Changed parameter from `$cart_item` array to `WC_Product $product`
+- Uses `$product->get_id()` instead of array access for product ID
+- Full compatibility with WooCommerce Store API and block-based cart/checkout

- ✅ Added nonce verification for product meta save operations
- ✅ Added capability checks for user permissions
- ✅ Enhanced data escaping and sanitization
- ✅ Implemented autosave prevention
+### Recent Major Updates

-#### Code Improvements
+#### Version 1.1.7 - Enhanced Tier Pricing
+- Added optional text labels for tier pricing
+- Clickable tier rows that auto-populate quantity field
+- Add to Cart button auto-disable when quantity is invalid

- ✅ Enhanced cart object validation
- ✅ Improved product object type checking
- ✅ Better error handling for edge cases
- ✅ Updated data storage methods for cart items
- ✅ Modernized JavaScript localization with proper escaping
+#### Version 1.1.4 - WooCommerce Blocks Support
+- Full support for WooCommerce block-based cart and checkout
+- Quantity restrictions work with both classic and block carts
+- Enhanced "View Options" button styling

-#### Initial Features
+#### Version 1.1.0 - Package Quantity Restrictions
+- Global and per-product package quantity restrictions
+- Prevents customers from ordering non-package quantities
+- Automatic quantity field hiding when restrictions enabled

- Initial release with tier pricing functionality
- Package pricing with fixed quantities
- Customizable pricing tables
- Global settings page
- Product-level configuration
- Cart integration with dynamic pricing
- Responsive frontend design
+#### Version 1.0.1 - Twig Template Engine
+- Migrated to Twig templating system
+- Enhanced security with automatic HTML escaping
+- Added German (Switzerland, Informal) translation
+
+#### Version 1.0.0 - Initial Release
+- Tier pricing functionality (quantity-based discounts)
+- Package pricing functionality (fixed-price bundles)
+- WooCommerce HPOS compatibility
+- Multilingual support (English, German)
+
+For complete version history, see [CHANGELOG.md](CHANGELOG.md)

 ## Credits

--- a/USAGE_EXAMPLES.md
+++ b/USAGE_EXAMPLES.md
@@ -1,5 +1,8 @@
 # Usage Examples

+**Plugin Version:** 1.1.20
+**Last Updated:** 2025-12-23
+
 ## Example 1: T-Shirt Store with Volume Discounts

 ### Tier Pricing Setup
@@ -16,9 +19,9 @@ For a t-shirt that normally costs $20:
 **How to configure:**
 1. Edit your t-shirt product
 2. Set regular price to $20.00
-3. Add tier: Min Qty = 10, Price = $18.00
-4. Add tier: Min Qty = 25, Price = $16.00
-5. Add tier: Min Qty = 50, Price = $14.00
+3. Add tier: Min Qty = 10, Price = $18.00, Label = "Bulk Discount"
+4. Add tier: Min Qty = 25, Price = $16.00, Label = "Volume Pricing"
+5. Add tier: Min Qty = 50, Price = $14.00, Label = "Wholesale Rate"
 6. Save product

 **Customer experience:**
@@ -97,6 +100,62 @@ Regular mug price: $10.00
 - Package 2: Qty = 4, Price = $32.00, Label = "Family Set"
 - Package 3: Qty = 10, Price = $70.00, Label = "Office Bundle"

+## Example 5: Quantity Restrictions (New in v1.1.0)
+
+### Party Supplies with Fixed Packages
+
+For products that should ONLY be sold in specific package quantities:
+
+**Product:** Balloons - Regular price $1.00 each
+
+**Package Configuration:**
+- Package 1: Qty = 12, Price = $10.00, Label = "Dozen Pack"
+- Package 2: Qty = 24, Price = $18.00, Label = "Party Pack"
+- Package 3: Qty = 50, Price = $40.00, Label = "Event Pack"
+
+**How to configure:**
+1. Edit balloon product
+2. Set regular price to $1.00
+3. Add packages as shown above
+4. **Check "Restrict to package quantities only"** (per-product setting)
+5. Save product
+
+**Customer experience:**
+- Quantity input field is hidden on product page
+- Customer MUST select a package using the package selection buttons
+- Attempting to add custom quantities via URL or API will fail with validation error
+- Cart displays selected package quantity (cannot be edited)
+- "View Options" button appears on shop/category pages instead of "Add to Cart"
+
+**When to use quantity restrictions:**
+- Pre-packaged items (dozen eggs, 6-pack drinks, etc.)
+- Products with fixed manufacturing quantities
+- Promotional bundles where you don't want individual sales
+- Subscription boxes with specific item counts
+
+## Example 6: Tier Labels for Enhanced UX (New in v1.1.7)
+
+### Office Supplies with Clickable Tiers
+
+**Product:** Premium Notebooks - Regular price $8.00 each
+
+**Tier Configuration with Labels:**
+- Tier 1: Min Qty = 5, Price = $7.50, Label = "Small Business Discount"
+- Tier 2: Min Qty = 10, Price = $7.00, Label = "Wholesale Pricing"
+- Tier 3: Min Qty = 25, Price = $6.50, Label = "Corporate Rate"
+
+**Customer experience:**
+- Tier labels appear below quantity in pricing table (italicized)
+- Clicking a tier row auto-fills the quantity field with that tier's minimum quantity
+- Smooth scroll animation highlights the quantity field
+- Add to Cart button automatically disables when quantity is 0 or invalid
+
+**Benefits of tier labels:**
+- Helps customers understand pricing context
+- Makes tiers more appealing with descriptive names
+- Improves conversion by highlighting value propositions
+- Clickable rows improve user experience
+
 ## Tips for Best Results

 ### Tier Pricing Best Practices
@@ -113,6 +172,11 @@ Regular mug price: $10.00
   - Minimum 5-10% per tier level
   - Higher tiers should have progressively better deals

+4. **Use Labels** (v1.1.7+): Add descriptive labels to tiers
+   - "Wholesale Price" instead of just showing the number
+   - "Bulk Discount", "Volume Pricing", "Corporate Rate"
+   - Makes pricing more professional and appealing
+
 ### Package Pricing Best Practices

 1. **Strategic Quantities**: Match common use cases
@@ -169,3 +233,32 @@ Regular mug price: $10.00
 - Package 2: Medium party (25 pieces) = $110
 - Package 3: Large party (50 pieces) = $200
 - Package 4: Event package (100 pieces) = $350
+
+## WooCommerce Blocks Compatibility (v1.1.4+, Fixed in v1.1.20)
+
+This plugin is **fully compatible** with WooCommerce block-based cart and checkout:
+
+### Supported Block Types
+- Cart Block (`woocommerce/cart`)
+- Mini Cart Block (`woocommerce/mini-cart`)
+- Checkout Block (`woocommerce/checkout`)
+- All Store API endpoints
+
+### Block-Specific Features
+- Quantity restrictions work in block-based carts
+- Package-restricted products hide quantity selectors in blocks
+- Tier and package pricing applies correctly in block checkout
+- Mini cart displays correct prices and restrictions
+
+### Technical Notes
+- v1.1.20 fixed critical fatal error in WooCommerce Blocks
+- Uses `woocommerce_store_api_product_quantity_editable` filter
+- Works with both classic and block-based themes
+- No configuration needed - blocks work automatically
+
+### Testing Your Block Setup
+1. Add block-based cart to a page (`/cart`)
+2. Add mini-cart block to your header
+3. Add block-based checkout to a page (`/checkout`)
+4. Test tier pricing, package pricing, and quantity restrictions
+5. Verify prices calculate correctly at checkout