=== Rankd Free Shipping Progress Bar ===
Contributors:      coolhuntersgt, rankd.site
Plugin URI:        https://rankd.site/
Tags:              woocommerce, free shipping, progress bar, cart, shortcode
Requires at least: 6.0
Tested up to:      6.9
Requires PHP:      7.4
Stable tag:        1.0.0
License:           GPL-2.0-or-later
License URI:       https://www.gnu.org/licenses/gpl-2.0.html

Show customers how close they are to qualifying for free shipping, with a progress bar and message that updates as they shop.

== Description ==

This plugin shows a free shipping progress message on your WooCommerce store. When a customer's cart is below your threshold, they see how much more they need to spend. When they hit it, the message updates to confirm they've qualified. The message refreshes as items are added or removed without a page reload.

You can drop it on any page using the shortcode `[rankd_free_shipping]`, or turn on auto-inject to have it appear automatically at the top of your cart and checkout pages. Settings are under **WooCommerce → Settings → Shipping → Free Shipping Progress**.

**What it does**

* Auto-injects on the cart page, checkout page, or both — no shortcode needed
* Shortcode placement works on any page, widget area, or theme template
* Updates the message and progress bar as the cart changes, including on block-based themes
* Progress bar is included by default and can be hidden with a single CSS rule
* Threshold amount is configurable
* Supports an optional coupon code — useful if your free shipping requires one
* Message text is customizable, with `{amount}` and `{coupon}` merge tags
* Role exclusions let you hide the message from specific user roles (wholesale accounts, for example)
* The settings page includes a CSS class reference so you know exactly what to target when styling

**Wholesale stores**

Most free shipping plugins have no way to hide the message from wholesale or trade customers. This one does. Check the roles you want to exclude on the settings page and those users won't see the message.

**Before you activate**

This plugin displays a message based on your WooCommerce free shipping configuration. It needs that to be set up first:

1. Go to **WooCommerce → Settings → Shipping → Shipping Zones** and add or edit a zone
2. Add **Free Shipping** as a shipping method in that zone
3. Set **"Free Shipping Requires"** to match your setup (minimum order amount, coupon, or both)
4. If using a coupon: go to **Marketing → Coupons**, create the coupon, and check **"Allow free shipping"**

[WooCommerce Free Shipping documentation](https://woocommerce.com/document/free-shipping/)

**Multiple shipping zones**

The plugin shows one threshold to all visitors. If you have zones with different minimums (say, $50 for domestic and $75 for international), customers in the non-primary zones will see the wrong number. If that's a real concern for your store, you'll want a plugin with geo-detection built in.

== Installation ==

1. Upload the `free-shipping-progress` folder to `/wp-content/plugins/`, or install via **Plugins → Add New → Upload Plugin**
2. Activate the plugin
3. Go to **WooCommerce → Settings → Shipping → Free Shipping Progress**
4. Set your threshold amount and customize your messages
5. Under **Display & Placement**, either:
   * Check **Auto-inject on Cart Page** and/or **Auto-inject on Checkout Page** for automatic display, or
   * Place `[rankd_free_shipping]` anywhere on your site manually

**Nothing will appear on your site until you complete step 5.**

== Frequently Asked Questions ==

= I activated the plugin but nothing is showing. Why? =
The message doesn't appear until you tell it where to display. Go to **WooCommerce → Settings → Shipping → Free Shipping Progress** and either enable one of the Auto-inject options, or place the shortcode `[rankd_free_shipping]` somewhere on your site.

= Where can I place the shortcode? =
Anywhere shortcodes work — pages and posts (Shortcode block in the block editor), widget areas (Text or HTML widget), theme templates via `do_shortcode( '[rankd_free_shipping]' )`, or WooCommerce action hooks in your child theme's `functions.php`.

= What's the difference between auto-inject and the shortcode? =
Auto-inject hooks into WooCommerce's cart and checkout templates — no placement needed, works even if you switch themes. The shortcode gives you full control over exactly where the message appears and works on any page. You can use both at the same time.

= Does the progress bar update live? =
Yes, on all pages. On classic cart/checkout it responds immediately when WooCommerce fires cart update events. On block-based themes and anywhere else the shortcode is placed, it checks for cart changes every 2.5 seconds and refreshes automatically. Checking pauses when the browser tab is hidden.

= My store has multiple shipping zones with different minimums. Will this work? =
Not fully — see the Known Limitation note in the Description. If your zones share the same threshold, there's no problem. If they differ significantly, a geo-aware plugin will serve you better for this specific feature.

= How do I hide the progress bar and show text only? =
Add this to **Appearance → Customize → Additional CSS**: `.rankd-fs-bar-track { display: none; }`

= How do I style the message? =
The settings page includes a full CSS class reference table. You can also refer to the Styling section below.

= Does this work with block-based themes like Twenty Twenty-Five? =
Yes. On block cart/checkout pages the plugin injects the message via JavaScript and refreshes it via polling. No extra configuration needed.

= Will this work with Elementor? =
Yes, on classic WooCommerce cart/checkout pages with Elementor. Place the shortcode in an HTML widget anywhere on your site for full control over placement.

== Styling ==

All classes and their purposes are listed on the settings page. Quick reference:

| Class               | Element                          |
|---------------------|----------------------------------|
| `.rankd-fs-wrapper`      | Outer div (both states)          |
| `.rankd-fs-notice`       | Outer div — threshold not met    |
| `.rankd-fs-success`      | Outer div — threshold met        |
| `.rankd-fs-message`      | Message text span                |
| `.rankd-fs-amount`       | Currency amount span             |
| `.rankd-fs-coupon-code`  | Coupon code span                 |
| `.rankd-fs-coupon-line`  | Coupon line beneath success msg  |
| `.rankd-fs-bar-track`    | Progress bar background track    |
| `.rankd-fs-bar-fill`     | Progress bar filled portion      |

== Screenshots ==

1. The settings page — configure threshold, messages, coupon code, role exclusions, and display placement all in one place.
2. The "Almost There" notice state on the cart page — showing the amount remaining with the progress bar partially filled.
3. The "Qualified" success state — shown when the customer's cart meets the threshold, with optional coupon code display.

== Changelog ==

= 1.0.0 =
* Initial release.
