=== LanternWP Companion ===
Contributors: lanternwp
Tags: woocommerce, demo import, block theme
Requires at least: 7.0
Tested up to: 7.1
Requires PHP: 8.2
Stable tag: 0.1.1
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Companion to the LanternWP theme: demo store import and store features WooCommerce does not have.

== Description ==

LanternWP Companion is the plugin of the LanternWP block theme for WooCommerce. The theme works fully without it; the plugin brings what belongs to plugins rather than themes:

* Demo import: any LanternWP demo store, with its products, pages, menus, look and structure, into your store, again whenever you like.
* Store features WooCommerce does not have yet, as blocks that extend WooCommerce's own.

Product badges: the Product Badges block shows a product's Bestseller and New badges in the theme's product cards and above the product page's title, where the plugin places it by itself. Each badge is set on the product (Product data, General: Automatic, Show or Hide); Automatic follows the rules in WooCommerce → Settings → Products, off until you turn them on: New for a number of days after a product is published, Bestseller for a number of best-selling products, by their sales in the last 7, 30 or 90 days, the last 12 months or of all time. Under each rule the screen shows the products it marks now and how many products show or hide the badge themselves, which the rule skips (after a demo import, all of them). WooCommerce's sale badge shows the discount, such as −20%, or Up to −30% when a product's variations are discounted unevenly.

Product swatches: the Product Swatches block shows the colours a product comes in as round swatches on the theme's product cards, beside the rating, where the plugin places it by itself. The colours are those of the product's terms in a colour attribute (WooCommerce's visual attribute type, which needs WooCommerce's visual attributes feature; a demo import turns it on), a term's image when it has one (a pattern or a material), shown when a product has at least two; beyond five, the rest is a count. While the store hides out-of-stock products, a product with variations leaves out the colours none of its in-stock variations comes in. When the colours make the product's variations, the shopper can choose one on the card: hovering or focusing a colour shows its photo and price, choosing it keeps them and opens the product with that colour chosen; a colour sold out is shown faded.

Free shipping progress: the Free Shipping Progress block shows how far the cart is from free shipping ("You are $12 away from free shipping", then "Your order ships free.") over a bar, in the cart drawer before its products and on the cart page above them, where the plugin places it by itself. The amount is the lowest minimum of an enabled Free shipping method in WooCommerce → Settings → Shipping, in the shipping zone of the customer's address, and the cart counts as WooCommerce counts it for that method; a customer whose zone has no such method sees no bar, and until a customer has an address (when the store sets no default customer location) the amount is the lowest of all zones. The LanternWP header promises the same amount. Without such a method in any zone the block shows nothing. It follows the cart and the address as they change.

Lowest price before a discount: required in the EU by the Omnibus Directive and off until you turn it on in WooCommerce → Settings → Products. Under a discounted product's price, where WooCommerce prints it (the product cards, the product page, products listed in a page or post), a line gives the lowest price the product had in the 30 days before the discount; on the product page it follows the chosen variation (the basket and checkout show none), and a variable product's own price takes its discounted variations' lowest. The plugin keeps each product's and variation's price history from when it is active, so a discount that started before has no line; a demo import gives its products a history, so its sales show one at once.

Appearance → Demos shows the gallery of LanternWP demo stores, marks the one your store has and imports any of them with its progress shown: checking the demo, downloading its images, adding them to the media library, importing the store. An import that stops can be tried again and continues where it stopped. Importing the same demo again brings the store up to date with it.

The import makes the demo's look the store's starting look, which the LanternWP theme lays under your changes in Styles, so Reset styles in Styles comes back to it rather than to the theme's own look, and it stays if the plugin is deactivated. Use the look only, on each demo's card, takes a demo's look alone, its colours, fonts, shape and spacing, and leaves the store's products, pages, menus, templates and settings as they are; if Styles has changes, you choose whether to keep them or replace them (Revisions in Styles keeps them). Common Goods' look is the theme's own.

Until the store has a demo, the plugin points to the screen: activating the plugin opens it once, the dashboard, Themes and Plugins show a notice you can dismiss for good, and the LanternWP theme's welcome screen (Appearance → LanternWP) gets a step to start from a demo.

The same import is a WP-CLI command: `wp lanternwp demo import base` downloads the latest version of the Base demo from lanternwp.com and imports it; `base@2` names a version, and `--dir` imports a demo directory instead. `wp lanternwp demo look kilowatt` takes only the Kilowatt demo's look; `--keep-styles` keeps the changes in Styles.

The import also sets up the store the way the demo shows it: the checkout page's content, accounts at checkout, local pickup at the store's address, the footer's menus, and the demo's returns, terms and privacy policy pages, unless the store already has published pages of its own, which it keeps. A demo store's terms and privacy policy say that it is a demo. Demo orders show the order numbers of the demo (#1042) instead of their ids; WooCommerce's order search does not find them by that number.

LanternWP Companion is distributed and updated from lanternwp.com, not from the WordPress.org plugin directory.

== External services ==

The demo import downloads LanternWP demo stores from the demo store at lanternwp.com, run by LanternWP. The plugin connects to it only when a site administrator opens Appearance → Demos, to fetch the list of demos (kept for an hour), or runs an import or uses a demo's look, to fetch the demo's list of versions and files and the files themselves, only its manifest for a look (https://lanternwp.com/api/demos/), which it checks against their checksums. On the Demos screen the administrator's browser also loads each demo's logo or screenshot from lanternwp.com. The requests carry what every request from WordPress carries: the site's IP address and WordPress's user agent, which names the WordPress version and the site's address. Nothing else is sent.

Updates also come from lanternwp.com, since the plugin is not in the WordPress.org directory: when WordPress checks for plugin updates, about twice a day and when an administrator asks it to, the plugin fetches the latest version's number, requirements and release notes (https://lanternwp.com/api/companion, kept for an hour), and an update downloads the new version from lanternwp.com. These requests carry the same: the site's IP address and WordPress's user agent. Privacy policy: https://lanternwp.com/privacy

The demo photographs are licensed under CC0 1.0.

== Changelog ==

= 0.1.1 =
* New: Updates from lanternwp.com: Dashboard → Updates, automatic updates and `wp plugin update` offer a new version of LanternWP Companion, as they do for plugins from WordPress.org.

= 0.1.0 =
* New: Demo import from lanternwp.com or a directory: `wp lanternwp demo import`.
* New: The import sets the checkout, local pickup, footer menus and policy pages; demo orders show their numbers.
* New: Appearance → Demos: the demo gallery and the import with its progress.
* New: The import makes the demo's look the store's starting look, which Reset styles in Styles comes back to; Use the look only and `wp lanternwp demo look` take a demo's look alone.
* New: The Product Badges block (Bestseller, New) with its product settings and rules; the sale badge shows the discount.
* New: The lowest price in the 30 days before a discount (EU Omnibus Directive), from each product's price history.
* New: The Product Swatches block: a product's colours on its card, chosen there when they make its variations.
* New: The Free Shipping Progress block in the cart drawer and on the cart page.
* New: A store without a demo is led to Appearance → Demos: after activation, by a dismissible notice and on the theme's welcome screen.
