=== Layout Foundry Quantities ===
Contributors: layoutfoundry
Tags: quantity calculator, tiles, paint, decking, woocommerce
Requires at least: 6.5
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 0.1.1
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

A quantity planner for tile, flooring, paving, wallpaper, paint, decking, fencing, gravel and turf shops. Shoppers add whole packs to the basket.

== Description ==

Layout Foundry Quantities adds a planner to WooCommerce product pages. The shopper enters the size of their room, walls, deck, fence run or garden. The planner works out how many whole packs, rolls, tins, boards, panels or bags of that product to buy, and one button adds them to the basket.

The planner shows its working as text: the area, the layout count, the allowance, the rounding up to whole packs or rolls, and the material left over. A diagram sits beside the text where one helps.

= Product types =

* Tiles and paving: piece size, pieces per pack, joint width and laying pattern (straight or half bond). The planner lays out every piece and counts the cut pieces.
* Flooring: coverage per pack, or plank size with planks per pack.
* Wallpaper: roll width, roll length, pattern repeat and match (straight or half drop). Shoppers enter the wall height and up to four wall widths.
* Paint: coverage per litre for one coat, coats and tin size. Shoppers enter their walls and the number of doors and windows to take off.
* Decking: board width (as laid) and length, the gap between boards, boards per pack if sold in packs, and an optional joist spacing. The result counts whole boards with a cutting allowance, and joists when a spacing is set.
* Fencing: panel width and post width. The result counts panels, posts and, if the shopper asks, gravel boards.
* Gravel and aggregates: density in tonnes per m³ and bag weight, such as a 20 kg bag or an 850 kg bulk bag. Shoppers enter the area and the depth.
* Turf: roll width and length, or the area one roll covers.

Metric shops use centimetres, metres, square metres, litres and kilograms. Imperial shops use inches, feet, square feet, US gallons and pounds.

= Setting up products =

* One product at a time: edit a simple product and open Product data > Quantities.
* Many products at once: Products > Quantities > Import. Upload a CSV file with a `sku` or `product_id` column and the settings you need. You see a preview with a status for every row, and nothing changes until you apply it.

The planner shows above the add-to-basket button on the product page. In a block theme you can also place the Quantity planner block in the single product template, and turn off the automatic placement under Products > Quantities.

= Privacy =

* The planner runs in the shopper's browser. Sizes they enter stay on their device.
* The plugin makes no requests to Layout Foundry or any other outside service. It sets no cookies and adds no tracking.

= Free =

Every feature on this page is free, with no limit on products.

= Source code =

The planner is written in TypeScript. The files in `assets/embed/` are built from the TypeScript in the `source/` folder of this plugin with esbuild. The build steps are in `source/BUILD.md`.

== Installation ==

1. Install and activate WooCommerce 8.5 or later.
2. Install Layout Foundry Quantities from Plugins > Add New, or upload the plugin folder to `wp-content/plugins/`, then activate it.
3. Edit a simple product whose price is per pack or per roll. Open Product data > Quantities, tick Quantity planner and fill in the sizes.
4. Open the product page and try the planner.

== Frequently Asked Questions ==

= What does the CSV file look like? =

The first row names the columns. For example:

`sku,product,units,tile_size,pieces_per_pack,joint,allowance`
`GREY-3060,tiles,cm,30x60,8,3,10`

The columns are `sku` or `product_id`, then any of `enabled`, `product`, `units`, `tile_size`, `pieces_per_pack`, `coverage`, `joint`, `pattern`, `allowance`, `roll_width`, `roll_length`, `pattern_repeat`, `match`, `spread_rate`, `coats`, `tin_size`, `joist_spacing`, `panel_width`, `post_width`, `density` and `bag_size`. A blank cell clears that setting. The full list with allowed values is on the import page.

= Why does the planner not show on a product? =

The planner shows on simple products whose settings are complete. Tiles, flooring and paving need a piece size with pieces per pack, or a coverage per pack. Wallpaper needs a roll width and a roll length. Paint needs a coverage and a tin size, decking a board size, fencing a panel width, gravel a density and a bag weight, and turf a roll size or a coverage per roll. When a setting is missing, the product screen says what to add and keeps the planner off.

= Can paint come in several tin sizes? =

Each simple product is one tin size, so the planner counts whole tins of that size. Set up each size as its own product.

= Does the planner check the shopper's measurements? =

No. It works out quantities from the sizes the shopper enters and the allowance shown. Shoppers should measure carefully and check the result before they buy.

= Does it work with a CDN or a script optimisation plugin? =

The planner starts a background worker from the file beside its script, and browsers only allow that from your own domain. If a CDN or optimisation plugin moves scripts to another domain, exclude `wp-content/plugins/layout-foundry-quantities/assets/embed/` from it.

== Screenshots ==

1. The planner on a tile product page, with the text result and the layout diagram.
2. The add button with the number of packs, and the basket quantity it sets.
3. Product data > Quantities on a tile product.
4. The CSV import preview with a status for every row.

== Changelog ==

= 0.1.1 =
* Fix: the CSV import screen's column list now wraps instead of scrolling sideways.

= 0.1.0 =
* First release: planner for tiles, flooring, paving, wallpaper, paint, decking, fencing, gravel and aggregates, and turf, product settings, CSV import with preview, and the Quantity planner block.

== Upgrade Notice ==

= 0.1.1 =
The CSV import screen no longer scrolls sideways.

= 0.1.0 =
First release.
