@lime-bundles/react 5.0.0 → 6.1.0

package/docs/css-variables.md

@@ -39,48 +39,43 @@ Merchants can set these (and any other CSS) via Lime Bundles admin → Settings
 | `--lb-text` | `#1A1A1A` | Base body text colour. |
 | `--lb-border` | `#E5E5E5` | Outer card border colour. |
 | `--lb-border-width` | `1px` | Outer card border width. |
-| `--lb-radius` | `12px` | Outer card corner radius. |
+| `--lb-radius` | `12px` | Global corner radius. The merchant picks a preset (none / subtle / rounded / round) and every element derives its rounding from this value. |
 
 ## Header
 
-| Variable | Default | What it styles |
-|---|---|---|
-| `--lb-header-start` | `#C62828` | Gradient start (ignored when header style is `solid`). |
-| `--lb-header-end` | `#AD1457` | Gradient end. |
-| `--lb-header-bg` | *derived* | Final header background. Emitted as a solid colour or a gradient depending on the merchant's header-style pick. |
-| `--lb-header-text` | `#FFFFFF` | Header text colour. |
-| `--lb-countdown-bg` | `#FFF0F3` | Countdown badge background inside the header. |
-| `--lb-countdown-text` | `#C62828` | Countdown badge text colour. |
-
-## Save badge
+The bundle title renders as a plain section heading in the host theme's own
+type, using `--lb-text`. There is no colored header band and no save-badge pill.
+Only the countdown timer carries its own colours.
 
 | Variable | Default | What it styles |
 |---|---|---|
-| `--lb-save-badge-bg` | `#FFFFFF` | Background. |
-| `--lb-save-badge-text` | `#AD1457` | Text colour. |
-| `--lb-save-badge-border-color` | `#FFFFFF` | Border colour. |
-| `--lb-save-badge-border-width` | `0px` | Border width. |
-| `--lb-save-badge-radius` | `8px` | Corner radius. |
+| `--lb-countdown-bg` | `#FFF0F3` | Countdown bar background. |
+| `--lb-countdown-text` | `#C62828` | Countdown bar text colour. |
 
 ## Product list
 
+Product thumbnails carry no border; they round to a tighter radius derived from
+`--lb-radius`. The variant selector inherits the global `--lb-border` /
+`--lb-border-width` and the same derived radius, so there are no per-element
+border variables here.
+
 | Variable | Default | What it styles |
 |---|---|---|
-| `--lb-image-border-color` | `#E5E5E5` | Product thumbnail border. |
-| `--lb-image-border-width` | `0px` | Product thumbnail border width. |
-| `--lb-image-border-radius` | `8px` | Product thumbnail corner radius. |
-| `--lb-variant-border-color` | `#E5E5E5` | Variant selector border. |
-| `--lb-variant-border-width` | `1px` | Variant selector border width. |
-| `--lb-variant-radius` | `8px` | Variant selector corner radius. |
-| `--lb-variant-chevron` | *derived SVG data URL* | Chevron icon shown in the variant dropdown. Auto-coloured to match `--lb-variant-border-color`. |
-
-The variant dropdown is an accessible custom combobox (not a native `<select>`). Its open panel reuses `--lb-variant-border-color`, `--lb-variant-border-width`, and `--lb-variant-radius` for the panel border, `--lb-bg` for the panel background, `--lb-text` for option text and the 4px scrollbar thumb, and `--lb-primary-color` for the focus ring. No additional variables required — adjusting the border or text/background colour automatically restyles the open panel to match.
-
-| `--lb-qty-badge-bg` | `#1A1A1A` | Quantity badge background. |
-| `--lb-qty-badge-color` | `#FFFFFF` | Quantity badge text. |
-| `--lb-qty-badge-display` | `flex` (shown) / `none` (hidden) | Toggle; merchant config controls this. |
+| `--lb-variant-chevron` | *derived SVG data URL* | Chevron icon shown in the variant dropdown. Auto-coloured to match `--lb-border`. |
+
+The variant dropdown is an accessible custom combobox (not a native `<select>`). Its open panel reuses `--lb-border` and `--lb-border-width` for the panel border, `--lb-bg` for the panel background, `--lb-text` for option text and the scrollbar thumb, and `--lb-primary-color` for the focus ring. No additional variables required: adjusting the global border or text/background colour automatically restyles the open panel to match.
+
 | `--lb-product-price-display` | `block` (shown) / `none` (hidden) | Toggle. |
 | `--lb-product-compare-display` | `inline` (shown) / `none` (hidden) | Toggle. |
+| `--lb-product-unit-price-display` | `block` (shown) / `none` (hidden) | Toggle for the per-unit line (`$4.99/kg`) under a product's price. Separate from the bundle summary's per-item figure. |
+| `--lb-product-qty-chip-display` | `inline-flex` (shown) / `none` (hidden) | Toggle for the fixed bundle's right-slot quantity chip. |
+| `--lb-product-qty-inline-display` | `inline` (shown) / `none` (hidden) | Toggle for the inline `×N` count used by every other bundle type. |
+
+Per-product quantity renders as inline `×N` text beside the price (no floating
+count badge), using the widget's own `--lb-text`. The fixed bundle instead puts
+its count in a chip in the row's right slot, which is why one merchant setting
+drives two variables: the chip is a flex box and the inline count is text, so a
+single "shown" value cannot serve both.
 
 ## CTA button
 
@@ -88,29 +83,24 @@ The variant dropdown is an accessible custom combobox (not a native `<select>`).
 |---|---|---|
 | `--lb-primary-color` | `#1A1A1A` | Button background. |
 | `--lb-btn-text` | `#FFFFFF` | Button text. |
-| `--lb-cta-border-color` | `#1A1A1A` | Border colour. |
+| `--lb-cta-border-color` | `#1A1A1A` | Border colour. The button keeps its own border (the global border does not touch it). |
 | `--lb-cta-border-width` | `0px` | Border width. |
-| `--lb-cta-radius` | `12px` | Corner radius. |
 
-## Savings bar
+## Savings line
 
-| Variable | Default | What it styles |
-|---|---|---|
-| `--lb-savings-bar-bg` | `#EDFBF1` | Bar background. |
-| `--lb-savings-bar-text` | `#2DB554` | Bar text colour. |
-| `--lb-savings-bar-border-color` | `#2DB554` | Border colour. |
-| `--lb-savings-bar-border-width` | `0px` | Border width. |
-| `--lb-savings-bar-radius` | `8px` | Corner radius. |
+The "You save {amount} ({percent}%)" line sits beneath the receipt total. It is
+quiet text with no colours of its own — it inherits the widget's `--lb-text`
+(lime is reserved for the CTA). Toggle it via the `savingsBar.visible` config
+field; there are no savings-line CSS variables.
 
 ## Volume tier cards
 
-| Variable | Default | What it styles |
-|---|---|---|
-| `--lb-tier-border-color` | `#E5E5E5` | Tier card border. |
-| `--lb-tier-border-width` | `1px` | Tier card border width. |
-| `--lb-tier-radius` | `12px` | Tier card corner radius. |
-| `--lb-tier-selected-border-color` | `#1A1A1A` | Border colour for the active tier. |
-| `--lb-tier-selected-border-width` | `2px` | Border width for the active tier. |
+Tier cards inherit the global border (`--lb-border` / `--lb-border-width`) and the
+global corner radius (`--lb-radius`), so they have no dedicated border variables.
+
+The selected tier is highlighted with a quiet neutral tint and a stronger
+border derived from `--lb-text` (matching the mix & match in-bundle card), so it
+has no dedicated CSS variables.
 
 ## "Most popular" badge (volume bundle)
 
@@ -120,7 +110,9 @@ The variant dropdown is an accessible custom combobox (not a native `<select>`).
 | `--lb-popular-badge-text` | `#FFFFFF` | Badge text. |
 | `--lb-popular-badge-border-color` | `#1A1A1A` | Badge border colour. |
 | `--lb-popular-badge-border-width` | `0px` | Badge border width. |
-| `--lb-popular-badge-radius` | `12px` | Badge corner radius. |
+
+The badge keeps its own border width + colour, but its corner radius follows the
+global radius preset (the derived `--lb-radius-sm`).
 
 ## "Only X left" low-stock badge
 
@@ -135,34 +127,23 @@ Surfaces when a variant's `quantityAvailable` is at or below
 
 ## Mix-and-match picker modal
 
+One "Borders" group drives every border inside the modal (the modal itself, the
+search input, product tiles, the variant select, and the quantity stepper).
+Thumbnails take the radius only (no border). The Add button keeps its own border
+width + colour but shares the radius.
+
 | Variable | Default | What it styles |
 |---|---|---|
 | `--lb-picker-bg` | `#FFFFFF` | Modal background. |
 | `--lb-picker-text` | `#1A1A1A` | Modal text colour. |
-| `--lb-picker-border-color` | `#E5E5E5` | Modal outer border. |
-| `--lb-picker-border-width` | `0px` | Modal outer border width. |
-| `--lb-picker-radius` | `16px` | Modal corner radius. |
-| `--lb-picker-search-border-color` | `#E5E5E5` | Search input border. |
-| `--lb-picker-search-border-width` | `1px` | Search input border width. |
-| `--lb-picker-search-radius` | `8px` | Search input corner radius. |
-| `--lb-picker-product-border-color` | `#E5E5E5` | Product thumbnail border. |
-| `--lb-picker-product-border-width` | `0px` | Product thumbnail border width. |
-| `--lb-picker-product-radius` | `8px` | Product thumbnail corner radius. |
-| `--lb-picker-qty-badge-bg` | `#1A1A1A` | Picker quantity-badge background. |
-| `--lb-picker-qty-badge-color` | `#FFFFFF` | Picker quantity-badge text. |
-| `--lb-picker-qty-badge-display` | `flex` (shown) / `none` (hidden) | Toggle; picker quantity badge visibility. |
-| `--lb-picker-variant-border-color` | `#1A1A1A` | Variant select border. |
-| `--lb-picker-variant-border-width` | `1px` | Variant select border width. |
-| `--lb-picker-variant-radius` | `8px` | Variant select corner radius. |
-| `--lb-picker-variant-chevron` | *derived SVG data URL* | Chevron icon on the picker's variant dropdown. Auto-coloured to match `--lb-picker-variant-border-color`. |
-| `--lb-picker-qty-stepper-border-color` | `#1A1A1A` | Per-pick quantity stepper border. |
-| `--lb-picker-qty-stepper-border-width` | `1px` | Per-pick quantity stepper border width. |
-| `--lb-picker-qty-stepper-radius` | `8px` | Per-pick quantity stepper corner radius. |
+| `--lb-picker-border-color` | `#E5E5E5` | Border colour for every element in the modal. |
+| `--lb-picker-border-width` | `1px` | Border width for every element in the modal. |
+| `--lb-picker-radius` | `16px` | Corner radius every element in the modal rounds to. |
+| `--lb-picker-variant-chevron` | *derived SVG data URL* | Chevron icon on the picker's variant dropdown. Auto-coloured to match `--lb-picker-border-color`. |
 | `--lb-picker-add-bg` | `#1A1A1A` | Add-to-bundle button background. |
 | `--lb-picker-add-label` | `#FFFFFF` | Add-to-bundle button text. |
-| `--lb-picker-add-border-color` | `#1A1A1A` | Add-to-bundle button border colour. |
-| `--lb-picker-add-border-width` | `0px` | Add-to-bundle button border width. |
-| `--lb-picker-add-radius` | `8px` | Add-to-bundle button corner radius. |
+| `--lb-picker-add-border-color` | `#1A1A1A` | Add-to-bundle button border colour (its own, not the modal Borders). |
+| `--lb-picker-add-border-width` | `0px` | Add-to-bundle button border width (its own). |
 
 ## Internal variables (don't override)
 
@@ -170,7 +151,6 @@ These exist for internal composition and are not merchant-configurable. The CSS
 
 - `--lb-thumbnail-bg`: placeholder background behind images.
 - `--lb-widget-pad`: internal padding token.
-- `--lb-progress-color`: volume progress bar accent.
 - `--lb-thumbnail-aspect-ratio`: derived from the merchant's `thumbnailRatio` setting (`square`/`tall`/`wide`/`original`). `1 / 1`, `3 / 4`, `4 / 3`, or `auto`. Override only if you need a custom thumb shape that isn't one of the four presets.
 - `--lb-thumbnail-img-fit`: derived from `thumbnailRatio`. `cover` for the cropping presets, `contain` for `original`.
 - `--lb-thumbnail-img-height`: derived from `thumbnailRatio`. `100%` for the cropping presets, `auto` for `original` so the image renders at its intrinsic ratio.

package/docs/hydrogen.md

@@ -27,7 +27,7 @@ PUBLIC_LIME_BUNDLES_TOKEN=<paste the generated token>
 
 The variable is intentionally namespaced so it doesn't collide with the `PUBLIC_STOREFRONT_API_TOKEN` that Shopify's Headless app issues for your primary storefront. Lime Bundles uses its own Storefront Access Token, scoped to bundle metaobjects and product listings only.
 
-Lime Bundles creates the token for you via Shopify's Admin API. No custom-app configuration needed (Shopify deprecated that flow on 2026-01-01). The token carries the read-only scopes `unauthenticated_read_metaobjects` and `unauthenticated_read_product_listings` and nothing else. To rotate, click **Regenerate** on the same page. It revokes the current token and issues a new one atomically.
+Lime Bundles creates the token for you via Shopify's Admin API. No custom-app configuration needed (Shopify deprecated that flow on 2026-01-01). The token carries the read-only scopes `unauthenticated_read_metaobjects`, `unauthenticated_read_product_listings` and `unauthenticated_read_product_inventory` and nothing else. To rotate, click **Regenerate** on the same page. It revokes the current token and issues a new one atomically.
 
 ## Getting a bundle GID
 

package/docs/react-nextjs.md

@@ -27,7 +27,7 @@ NEXT_PUBLIC_LIME_BUNDLES_TOKEN=<paste the generated token>
 
 The variable is intentionally namespaced to `LIME_BUNDLES_` so it doesn't collide with the Storefront API token Shopify's own Headless app issues for your primary storefront. Lime Bundles uses its own Storefront Access Token, scoped to bundle metaobjects and product listings only.
 
-The `NEXT_PUBLIC_` prefix (or `VITE_` for Vite) exposes the value to client bundles. Lime Bundles creates the token for you via Shopify's Admin API. No custom-app setup needed (Shopify deprecated that flow on 2026-01-01). The token is a read-only public Storefront Access Token with `unauthenticated_read_metaobjects` and `unauthenticated_read_product_listings` scopes, safe to ship in client code. To rotate, click **Regenerate** in the admin. It atomically revokes the old token and issues a new one.
+The `NEXT_PUBLIC_` prefix (or `VITE_` for Vite) exposes the value to client bundles. Lime Bundles creates the token for you via Shopify's Admin API. No custom-app setup needed (Shopify deprecated that flow on 2026-01-01). The token is a read-only public Storefront Access Token with `unauthenticated_read_metaobjects`, `unauthenticated_read_product_listings` and `unauthenticated_read_product_inventory` scopes, safe to ship in client code. To rotate, click **Regenerate** in the admin. It atomically revokes the old token and issues a new one.
 
 ## Pick a rendering mode
 
@@ -357,7 +357,9 @@ import { injectCustomCss, sanitizeCustomCss } from "@lime-bundles/react";
 ```tsx
 import { validateQuantity } from "@lime-bundles/react";
 
-const { valid, message } = validateQuantity(selectedCount, bundle.minQuantity, bundle.maxQuantity);
+// Pass the total units selected (sum of per-product quantities) — completion
+// counts units, so one product at quantity 3 satisfies minQuantity: 3.
+const { valid, message } = validateQuantity(totalUnits, bundle.minQuantity, bundle.maxQuantity);
 ```
 
 Anything the web component does, a developer importing from `@lime-bundles/react` can do too. The built-in components are one way to arrange these primitives; ship your own the moment you need a different one.

package/docs/web-component.md

@@ -295,7 +295,7 @@ Every part of the widget a merchant configures in the admin is wired up for you:
 - **Countdown timer.** When a bundle has `endsAt`, the widget ticks a live countdown every second and hides the bar once the offer expires.
 - **Variant dropdowns on fixed bundles.** Products with multiple eligible variants (filtered by the merchant's `selectedVariantIds`) render a `<select>`; switching variants live-updates the row price and the bundle total.
 - **Mix-match picker modal.** Click any empty slot to open the modal; search, quantity stepper, progress bar, and pricing update as selections change. Keyboard: Escape closes, Tab traps inside the modal.
-- **Out-of-stock behaviour.** Honours `widgetConfig.outOfStockBehavior` (`"hide"` removes OOS products from the list; `"show_greyed_out"` renders them disabled). Fixed bundles hide the whole widget when required products are OOS; mix-match hides when the available count can't satisfy `minQuantity`.
+- **Out-of-stock behaviour.** Honours `widgetConfig.outOfStockBehavior` (`"hide"` removes OOS products from the list; `"show_greyed_out"` renders them disabled). Fixed bundles hide the whole widget when required products are OOS; mix-match hides when the count of in-stock products falls below `minQuantity` (completion itself counts total units selected, not distinct products).
 - **A/B test assignment (link-group model).** When a bundle is the primary of an A/B test, the widget reads the link group's variant weights from `data-link-group-variants`, walks the cumulative FNV-1a weight distribution via `getLinkGroupAssignment`, and renders the assigned variant (which is a real Bundle with its own products, discount, and widget config — not an overlay). Cookie-persisted, consent-gated; honours Shopify's `customerPrivacy` framework or the SDK's `setConsent(true)` helper. Without consent the primary renders and no cookie is written.
 - **Impression + add-to-cart analytics.** Fire on visibility + CTA click regardless of whether the merchant takes over the cart via `preventDefault`. Disable by setting `analytics="false"` or omitting `app-url`.
 - **Purchase attribution.** The `orders/create` webhook ingests `bundle_purchased` events server-side from the `_lime_bundle_gid` cart attribute the widget adds automatically. No `checkout_completed` handler needed.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lime-bundles/react",
-  "version": "5.0.0",
+  "version": "6.1.0",
   "description": "React components and hooks for the Lime Bundles Shopify app. Use on Hydrogen, Next.js, Vite, or any React-based headless storefront.",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -32,7 +32,7 @@
     "url": "https://github.com/lime-app-dev/lime-bundles-app/issues"
   },
   "license": "MIT",
-  "author": "lime-app-dev",
+  "author": "Lime App Dev (Pty) Ltd",
   "keywords": [
     "shopify",
     "bundles",
@@ -52,7 +52,7 @@
     "react-dom": ">=18.0.0"
   },
   "dependencies": {
-    "@lime-bundles/core": "^5.0.0"
+    "@lime-bundles/core": "^6.2.0"
   },
   "devDependencies": {
     "@shopify/hydrogen-react": "^2026.4.1",