=== Dynamic Metal Price Calculator ===
Contributors: aolo
Donate link: https://tresifylab.com/
Tags: woocommerce, jewellery, jewelry, gold, silver
Requires at least: 5.8
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 4.0.1
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Live metal pricing for WooCommerce jewellery with karat, weight, GST, markup, shipping, price rounding, and full metal management.

== Description ==

Dynamic Metal Price Calculator provides live market-rate pricing for WooCommerce jewellery and precious metals. It automatically computes product prices based on daily gold and silver rates, metal purity (karat), product weight, and store pricing rules.

= Core Highlights =

* **Daily Metal Rates**: Set daily 24K Gold and Silver base prices per gram from your admin dashboard.
* **Metals & Purities**: Complete catalog management for 24K, 22K, 18K, 14K, Silver, Platinum, and custom formulas or fixed rates.
* **Deterministic Pricing**: (Metal Rate * Purity % * Weight) + Base Price + Making Charges + Wastage + Markup + Tax + Shipping.
* **Authoritative Price Rounding**: Clean up odd price totals into shopper-friendly figures (None, Nearest 10, 50, 100, or Custom) across cart and checkout.
* **Product Whitelists**: Restrict metal selections per product.
* **Variable Products**: Set custom weights, metals, and charges per variation.
* **Automatic Sale Pricing**: Displays dynamic metal prices as sale prices with strikethrough regular prices.
* **100% Private**: Fully self-contained on your server with zero external calls and zero tracking.

== Installation ==

1. Log in to your WordPress administrator dashboard.
2. Navigate to **Plugins** -> **Add New**.
3. Click **Upload Plugin** and select the `dynamic-metal-price-calculator.zip` package, or search for `Dynamic Metal Price Calculator`.
4. Click **Install Now**, then click **Activate**.
5. Open **Metal Prices** -> **Metal Rates** in your admin menu.
6. Enter current 24K Gold and Silver rates per gram and save.
7. Open any WooCommerce product to assign metal type, weight, and pricing rules.

== Frequently Asked Questions ==

= How does the pricing calculation work? =

The pricing engine computes the product price deterministically:
1. Resolves base metal rate (e.g. Gold Rate * Purity % / 100).
2. Multiplies rate by item weight in grams.
3. Adds fixed base price (e.g. stones, diamonds, packaging).
4. Adds percentage making/labour charge.
5. Adds percentage wastage allowance.
6. Adds percentage retail markup.
7. Adds percentage GST / sales tax.
8. Adds flat shipping fees.
9. Applies authoritative price rounding (Nearest 10, 50, 100, or Custom increment).

= What is the difference between Active and Show in Dropdown? =

* **Active (On/Off)**: Master switch. Inactive metals cannot be used in calculations for new items.
* **Show in Dropdown (On/Off)**: Visibility switch. Turning this OFF hides the metal from new product selectors while allowing existing products using this metal to continue calculating prices accurately.

= How do I restrict available metals for a specific product? =

On the product edit screen, use the **Allowed Metals for this Product** checklist. Leaving all unchecked allows all globally active metals. Checking one or more metals restricts that product and its variations to only the checked options.

= How does Price Rounding work? =

Price rounding is applied once to the final calculated price using standard half-up arithmetic:
* **None**: Exact calculated price.
* **Nearest 10**: e.g. 2,254 -> 2,250; 2,256 -> 2,260.
* **Nearest 50**: e.g. 2,201 -> 2,200; 2,249 -> 2,250; 2,276 -> 2,300.
* **Nearest 100**: e.g. 2,249 -> 2,200; 2,250 -> 2,300.
* **Custom Increment**: Any numeric increment (e.g. 25, 5, or 0.50).
Rounding is authoritative and carries through into the cart, checkout, payment gateway, and placed orders.

= How do I configure Variable Products? =

1. In a Variable Product, go to the **Variations** tab and expand a variation.
2. Check the box: **"Use Dynamic Metal Price Calculator for this variation"**.
3. Select the metal type and enter the variation's weight in grams.
4. Leave charge fields blank to inherit parent product or global defaults.
5. Save variations.

= Can I use custom formulas or fixed rates? =

Yes. In the Metals & Purities Manager, choose the **Custom** group:
* Enter a mathematical formula referencing variables `gold_rate` or `silver_rate` with `+`, `-`, `*`, `/`, `(`, `)` (e.g. `gold_rate * 1.25`).
* Or simply enter a fixed rate (e.g. `500`) without any formula.
All formulas are parsed using a safe Reverse Polish Notation (RPN) stack with zero arbitrary code execution.

= What if a metal option does not appear in the product dropdown? =

1. Verify that the metal is **Active** and **Show in Dropdown** is enabled in the Metals & Purities Manager.
2. Check if the product has an **Allowed Metals** whitelist that excludes this metal.
3. Save settings and refresh the product editor page.

= Does this plugin fetch live rates from an external API? =

No. Store owners enter manual daily rates in **Metal Prices** -> **Metal Rates**. This gives merchants absolute control over pricing without relying on third-party API keys or rate limits.

= Can I hide certain charge details from shoppers on the product page? =

Yes. In **Metal Prices** -> **Frontend Display Controls**, toggle individual components on or off. Hidden components remain active in the background calculation.

= Does this plugin send data outside my server? =

No. Dynamic Metal Price Calculator is 100% self-contained. It makes zero external HTTP requests, contains zero tracking, and does not collect or transmit store or customer data.

= Is the plugin compatible with High-Performance Order Storage (HPOS)? =

Yes. The plugin declares official compatibility with WooCommerce HPOS (`custom_order_tables`) and WooCommerce Cart & Checkout Blocks.

== Screenshots ==

1. Metal Rates and Setup Checklist admin screen
2. Metals & Purities Manager with custom options and usage tracking
3. Authoritative Price Rounding configuration
4. Product-level allowed metal selection and dynamic pricing fields
5. Frontend product display with optional transparent price breakdown

== Changelog ==

= 4.0.1 =
* Feature: Added authoritative Price Rounding on final calculated prices with None, Nearest 10, Nearest 50, Nearest 100, and Custom increment modes.
* Feature: Complete Metals & Purities Manager allowing store owners to add, edit, rename, activate, deactivate, and safely delete metal options.
* Feature: Product-Level Metal Selection whitelist allowing individual products to restrict available metals.
* Feature: Decoupled Active status from Dropdown visibility controls.
* Feature: Safe In-Use deletion guard preventing data corruption on referenced metals.
* Feature: Built-in options (Gold, Silver, Karats) can be managed, disabled, or safely deleted when unused.
* Feature: Safe formula evaluator using Reverse Polish Notation (RPN) with zero eval() execution.
* Privacy: 100% self-contained architecture with zero external requests, no external tracking, and no external popups.
* Privacy: Added registered WordPress Privacy Policy guide via wp_add_privacy_policy_content().
* Security: Hardened variation save nonce verification and capability checks on all product saves.
* UX: Redesigned admin interface with setup checklist, collapsible sections, usage badges, and admin footer credits.

= 3.0.3 =
* Improved admin panel layout with collapsible sections
* Clearer field explanations and setup guidance
* Fixed WooCommerce regular/sale price display for dynamic metal pricing products
* Added automatic calculated sale price behavior when manual sale price is blank

= 3.0.2 =
* Added frontend extra charges display settings to selectively hide or show breakdown components

= 3.0.1 =
* Updated documentation and confirmed compatibility with WordPress 7.0

= 3.0.0 =
* Major update: Added full variable product support with variation-level pricing fields

= 2.2.1 =
* Added per-product shipping override
* Improved sanitization of input fields

= 2.2.0 =
* Introduced markup percentage option
* Performance improvements

= 2.1.0 =
* Initial public release

== Upgrade Notice ==

= 4.0.1 =
Upgrade to 4.0.1 for authoritative price rounding, full Metals & Purities catalog management, product-level metal controls, and enhanced security. Fully backward-compatible with all existing products and rates.
