=== IDS Areamiq — Coverage Calculator for WooCommerce ===
Contributors: idsources
Tags: woocommerce, calculator, flooring, m2, coverage
Requires at least: 6.5
Tested up to: 7.1
Requires PHP: 8.1
Stable tag: 1.2.0
License: GPL-2.0-or-later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Coverage calculator for flooring and other m²-based WooCommerce products, with area and direct-unit purchasing.

== Description ==

IDS Areamiq helps customers buy flooring and other coverage-based products by area. Customers enter the area they need, or length × width, and the calculator converts it to the required number of whole packs or units. Products can also allow direct whole-unit purchases.

= Calculator features =

* Area-based calculation with an optional waste allowance.
* Direct whole-unit purchasing, area-only purchasing, or both methods on one product.
* Pack, bucket, liter, bag and roll coverage modes with configurable singular and plural unit labels.
* Thickness-aware calculation for bagged products such as screeds and self-levelling compounds.
* Configurable coverage per unit, minimum quantity and unit-content text.
* Pack/unit pricing or price-per-m² configuration for supported simple products.
* Live calculation and price presentation on the product page.
* Server-side purchase validation and quantity calculation.
* Calculator details in the WooCommerce cart and order line-item metadata.
* HPOS compatibility through WooCommerce order APIs.

= Store and administration tools =

* `[ids_floorcalc id="123"]` shortcode for placing a product calculator in a page or post.
* Optional iframe Embed utility with domain restrictions and rate limiting. Off by default; enable Embed widget under Settings > Features. Configure allowed domains in Embed Widget; an empty list allows any site once enabled.
* Setup Wizard for applying initial calculator settings to products.
* Per-product calculator settings and global Free defaults.
* Free CSV import/export for calculator product configuration.
* Product-list bulk actions for enabling, disabling and configuring calculator fields.
* Free System Status diagnostics.
* Optional shop-loop coverage badge, result sharing controls and live price display.
* Bulgarian translation included.
* Theme template override at `your-theme/ids-areamiq/calculator.php`, with the legacy `ids-floorcalc` path retained.

== Installation ==

1. Upload the `ids-areamiq` folder to `/wp-content/plugins/`, or upload the plugin ZIP through Plugins → Add New → Upload Plugin.
2. Activate IDS Areamiq.
3. Complete the Setup Wizard or open IDS Areamiq → Settings to configure Free defaults and features.
4. Edit a WooCommerce product, open the IDS Areamiq product-data tab, enable the calculator and configure its coverage settings.

== Frequently Asked Questions ==

= How does area purchasing work? =

The customer enters an area or length × width. IDS Areamiq applies the configured waste allowance, divides the adjusted area by the effective coverage per unit, rounds up to whole units and respects the configured minimum quantity.

= Can customers buy a direct number of packs or units? =

Yes. Each product can use area-only purchasing, direct whole-unit purchasing, or allow the customer to choose either method.

= How are screeds and other thickness-dependent products handled? =

Bag mode uses the configured reference thickness. Effective coverage scales inversely when the customer chooses a different layer thickness.

= Does it work with variable products? =

The calculator supports simple and variable product pages, with calculator configuration stored on the parent product. Automatic price-per-m² conversion is limited to supported simple products; variations continue to use their normal WooCommerce prices.

= Can I override the calculator template? =

Yes. Copy `templates/calculator.php` to `your-theme/ids-areamiq/calculator.php` and customise the copy. The legacy `your-theme/ids-floorcalc/calculator.php` path remains supported.

= What does the current Free development implementation support? =

The following describes the Free 1.2.0 release preparation, not a publication announcement or confirmation that the final package audit has passed. The repository guide at `docs/free-theming-and-plank-dimensions.md` contains the full contracts and examples; it is repository documentation, not a bundled plugin file.

Template lookup checks child `ids-areamiq/calculator.php`, parent `ids-areamiq/calculator.php`, child `ids-floorcalc/calculator.php`, then parent `ids-floorcalc/calculator.php`, with `templates/calculator.php` as the bundled fallback. A preferred parent override therefore precedes a legacy child override. With no child theme, only the active theme is checked for each path. If the first located override is invalid or unreadable, resolution falls back to the bundle rather than continuing through other theme candidates.

The filter `ids_floorcalc_calculator_template_path` receives the resolved path and the product (`WC_Product`, or null when unavailable). Return a readable local file with a `.php` extension. Malformed values, missing/unreadable files, directories and stream wrappers are rejected, retaining the valid unfiltered path. If there is no valid unfiltered path, no template is rendered and the filter is not called. Never construct an include path from customer input.

The bundled template has `@version 1.2.0`. System Status compares the bundled and default theme-override headers only, before the path filter; it does not assess product-dependent filtered templates. Missing, malformed or unreadable versions are unknown. Matching versions do not guarantee behavioural compatibility. Preserve template variables, classes, data attributes, form fields, unique per-instance IDs, labels, keyboard controls and the persistent result announcement when customising.

= What are plank dimensions? =

Optional thickness, width and length describe an individual board, not its shipping carton. Store them on the ordinary product or variable-product parent; variations inherit the parent's data. Values must be greater than zero and at most 100000, with up to three decimal places; decimal comma is accepted. Units are exactly `mm`, `cm` or `in`, without conversion. Missing or invalid stored dimensions are omitted; an absent or invalid display unit defaults to mm without saving that default.

Mixed Length displays the translated word Mixed instead of numeric length, retaining any stored numeric length. The row uses locale-formatted numbers without unnecessary trailing zeros. Missing dimensions are omitted; when none remain, the row and its icons disappear. A unit alone does not create a row. The product editor reads stored values, not integration display overrides: blanks delete, while invalid fields retain their saved values and report an error.

Plank dimensions are informational only: they do not affect coverage, waste, price or quantity. Plank thickness is separate from reference/application thickness used in bag calculations. No plank data is added to cart/order data, sharing or Embed.

= How do the development CSV plank columns work? =

The existing 16 columns retain their order, followed by `plank_thickness`, `plank_width`, `plank_length`, `plank_length_mixed`, `plank_unit`. An omitted column or missing trailing cell preserves that value; an explicit blank (including whitespace) deletes it. Existing 1.1.0 CSV files remain importable without changing plank data. Mixed Length accepts lowercase yes/true/1 (stores yes) and no/false/0 or blank (deletes). Units are mm/cm/in; CSV cell whitespace is trimmed. Quote decimal commas, for example `"14,125"`.

An invalid plank cell rejects the row before its product writes and reports a row/column error. Any supplied plank cell, even blank, rejects a variation row. This does not make all CSV errors atomic: invalid mode/purchase-method or later pricing errors can coexist with writes to other fields. There is no transaction or rollback guarantee. Review import errors and back up data before bulk updates.

Export uses persisted plank metadata, not display filters or default units. Missing/corrupt values export blank; mixed true exports yes. Plank decimals use a point, no grouping and no redundant zeros. The format is comma-separated UTF-8 with a BOM, double-quoted cells where required and doubled embedded quotes, not backslash escaping. Existing text-cell formula protection is retained. The repository guide includes the complete 21-column example.

= Can I style the Free calculator without replacing its template? =

Yes, within the existing CSS surface. Set properties directly on a suitably scoped `.ids-floorcalc` element, with rules that win the cascade; setting them only on an outer wrapper may be overridden by the calculator's own defaults. Examples are `--ids-floorcalc-accent`, `--ids-floorcalc-accent-soft`, `--ids-floorcalc-text`, `--ids-floorcalc-surface` and `--ids-floorcalc-radius`. The repository guide lists defined, consumed storefront properties and their defaults. These use the existing scoped internal fallbacks; private `--fc-*` tokens are not a new public API. This is not a promise that every visual detail is customisable, nor a way to style a separate Embed iframe from the parent page.

= How do I place a calculator in a page or post? =

Use `[ids_floorcalc id="123"]`, replacing `123` with the WooCommerce product ID.

= Can other websites embed the calculator? =

Yes. Enable the Free Embed feature and use IDS Areamiq → Embed to generate an iframe snippet. Embed settings can restrict which domains may frame the calculator.

== Screenshots ==

1. Coverage calculator on a WooCommerce product page.
2. Per-product calculator configuration in the IDS Areamiq product-data tab.
3. Free defaults and feature settings.
4. Calculator details shown in the cart and order line-item metadata.

== Changelog ==

= 1.2.0 =

* Add optional parent-product plank dimensions, Mixed Length and mm/cm/in units, with product-editor fields and an informational calculator row.
* Append five plank-dimension CSV columns with stored-data export, omitted-value preservation, blank deletion and plank-cell validation before row writes.
* Support preferred ids-areamiq theme overrides and a validated local-template path filter while retaining legacy ids-floorcalc overrides.
* Improve mobile input sizing, touch targets, text wrapping, percentage spacing and colour fallbacks; add an accessible plank-dimensions note.
* Preserve native keyboard operation of method-selector radios and announce current calculation results, including visible total prices, without repeating unchanged messages.
* Restore shared-estimate area, supported thickness and explicit waste settings while retaining existing area-link precision.
* Hide incompletely configured calculators from customers, show setup guidance to product editors and validate Setup Wizard coverage before saving.
* Clarify basket notices for unavailable products, estimates requiring recalculation and purchases that cannot be validated.
* Add product-configuration and template-version diagnostics, identifying partial checks and product-read failures.
* Format Embed prices using store currency settings and display fractional waste percentages and configured singular/plural unit labels.
* Stop further uninstall cleanup when product-metadata or transient database reads fail.
* Refresh the complete Bulgarian translation and document Free template, styling, plank-dimension and CSV contracts.

= 1.1.0 =

* Use WooCommerce General Regular/Sale prices as the sole pricing authority: per m² in sqm mode, per purchasable unit in pack mode.
* Derive purchase-unit and equivalent per-m² prices from the selected basis without rewriting General values.
* Keep calculator cart quantities editable above their minimum; preserve explicit-unit lines on below-minimum updates.
* Preserve native WooCommerce variation pricing, including products with retained per-m² metadata.
* Correct tax-aware price display, disabled-calculator presentation and repeated price-filter handling.
* Align frontend and server calculations and avoid extra units at exact coverage boundaries.
* Improve CSV configuration and formula-safe round trips; prevent CSV export deprecations on PHP 8.4/8.5.
* Clarify pack, bucket, bag, roll and container pricing labels and read-only admin previews.
* Refine shop-loop price hierarchy and respect the badge setting without hiding per-m² pricing.
* Reject malformed admin nonce inputs before verification and prevent calculator purchases with invalid calculation snapshots.
* Default Embed to off for new configurations while preserving saved preferences.
* Skip Setup Wizard redirects after bulk or network activation.
* Refresh Bulgarian translations and bundled translation catalogs.

= 1.0.0 =

* Initial public release.
* Area and direct-unit purchasing for packs, buckets, liters, bags and rolls.
* Waste, minimum quantity and thickness-aware coverage calculations.
* WooCommerce cart integration and order line-item metadata.
* Shortcode, Embed, Setup Wizard, Free CSV tools, bulk actions and System Status.

== Upgrade Notice ==

= 1.2.0 =

Adds informational plank dimensions, accessible mobile controls, restored shared estimates and clearer setup diagnostics. Review calculator template overrides for the 1.2.0 template hooks and accessibility markup. Plank dimensions do not change coverage, pricing or quantities.

= 1.1.0 =

Review existing products' WooCommerce General Regular/Sale prices before upgrading. In per-m² mode, these values now mean prices per m². No legacy prices are migrated or converted automatically; switching pricing modes reinterprets General values without converting them.

= 1.0.0 =

First release.
