=== IDTRACE – Variation Quantity Rules for WooCommerce ===
Contributors: idtrace
Tags: woocommerce, minimum quantity, variation, quantity step, min qty
Requires at least: 6.0
Tested up to: 7.0
Requires PHP: 8.0
Stable tag: 1.0.0
Requires Plugins: woocommerce
WC requires at least: 8.0
WC tested up to: 9.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Set a minimum quantity, step, and maximum per WooCommerce variation. Perfect for products sold in rolls, packs, boxes or any batch-based unit.

== Description ==

**IDTRACE – Variation Quantity Rules for WooCommerce** lets you define independent quantity rules for each variation of a variable product: minimum quantity, quantity step (increment), and optional maximum quantity.

WooCommerce natively applies the same quantity constraints to all variations of a product. This plugin removes that limitation — each variation gets its own rules.

= Who is this for? =

Any WooCommerce store selling products where quantity depends on the variation:

* **Labels & stationery** — rolls of 500, 1000 or 2000 units with different minimums per reference
* **Food & wholesale** — packs of 6, 12 or 24 depending on the product format
* **Hardware & industrial supplies** — screws, bolts, fittings sold by the box of 50 or 100
* **Printing & packaging** — reams, cartons, palettes with format-specific batch sizes
* **Cosmetics & pharmacy** — consumables sold in boxes with regulated minimum quantities
* **Textiles & haberdashery** — spools or bobbins sold by the lot

In short: if your variations have different packaging constraints, this plugin handles them cleanly.

= How it works =

1. Open any variable product in WooCommerce admin
2. Expand a variation — three new fields appear below the price: **Minimum quantity**, **Step**, **Maximum quantity** (optional)
3. Save — done

On the product page, as soon as a customer selects a variation:

* The quantity field is automatically set to the minimum
* The `min`, `step` and `max` HTML attributes are updated accordingly
* Any invalid quantity triggers an error message before the customer can add to cart

= Features =

* **Per-variation minimum quantity** — independent value for each variation
* **Per-variation step (increment)** — customers can only order in multiples of the defined step, starting from the minimum
* **Per-variation maximum quantity** — optional upper limit
* **Dynamic quantity field** — updates instantly on variation selection (no page reload)
* **Dual validation** — JavaScript for immediate user feedback + PHP server-side validation that cannot be bypassed
* **Cart update validation** — rules are also enforced when quantities are edited directly in the cart
* **Translatable error messages** — uses `wc_add_notice()`, compatible with any language
* **Clean uninstall** — all plugin data is removed on uninstall; deactivation leaves data intact
* **OOP architecture** — clean, maintainable, extendable codebase

= Step examples =

Minimum = 4 / Step = 4 → customer can order: 4, 8, 12, 16, 20...
Minimum = 4 / Step = 1 → customer can order: 4, 5, 6, 7, 8...
Minimum = 1 / Step = 1 → standard WooCommerce behavior (no constraint)

== Installation ==

= From the WordPress plugin directory =

1. Go to **Plugins > Add New** in your WordPress admin
2. Search for **IDTRACE Variation Quantity Rules**
3. Click **Install Now**, then **Activate**

= Manual installation =

1. Download the ZIP file
2. Go to **Plugins > Add New > Upload Plugin**
3. Upload the ZIP and click **Install Now**, then **Activate**

= Setup =

1. Make sure WooCommerce is installed and active
2. Open any **variable product**
3. Go to the **Variations** tab and expand a variation
4. Fill in **Minimum quantity**, **Step**, and optionally **Maximum quantity**
5. Save the product — rules are applied immediately on the product page

== Frequently Asked Questions ==

= What happens if I leave all fields empty? =

Default WooCommerce behavior applies: minimum 1, step 1, no maximum. The plugin only overrides values you explicitly set.

= Does it work if the customer changes the quantity directly in the cart? =

Yes. PHP validation runs on both `woocommerce_add_to_cart_validation` (add to cart) and `woocommerce_update_cart_validation` (cart update). Rules cannot be bypassed even if JavaScript is disabled.

= Does it work with simple products? =

No. This plugin targets variable products only — it manages rules at the variation level. Simple products are not affected.

= Can I set a step without setting a minimum? =

Yes. If you only set a step (e.g. step = 5), the minimum defaults to 1 and the customer can order 1, 6, 11, 16... If you set both minimum = 5 and step = 5, the customer can order 5, 10, 15, 20...

= Will disabling the plugin delete my data? =

No. Deactivation leaves all stored rules intact. Data is only deleted when you fully uninstall (delete) the plugin from the Plugins screen.

= Is it compatible with WooCommerce AJAX variation saving? =

Yes. The plugin hooks into `woocommerce_save_product_variation`, which fires in both standard product save and AJAX variation save contexts.

= Can I use this with a page builder like Divi or Elementor? =

Yes, as long as the standard WooCommerce variable product form is rendered. The plugin uses native WooCommerce JavaScript events (`found_variation`, `reset_data`) which are independent of the page builder.

== Screenshots ==

1. Quantity rule fields in WooCommerce admin — minimum, step and maximum per variation.
2. Frontend product page — quantity field automatically set to the minimum on variation selection.
3. Validation message displayed when a customer enters an invalid quantity.

== Changelog ==

= 1.0.0 =
* Initial release
* Per-variation minimum quantity, step and maximum quantity fields in WooCommerce admin
* Dynamic quantity field update on variation selection (JS)
* Server-side validation on add to cart and cart update (PHP)
* Translatable error messages via wc_add_notice()
* Clean uninstall via uninstall.php

== Upgrade Notice ==

= 1.0.0 =
Initial release. No upgrade required.