@lime-bundles/react 6.0.0 → 6.2.0

package/docs/css-variables.md

@@ -67,9 +67,15 @@ The variant dropdown is an accessible custom combobox (not a native `<select>`).
 
 | `--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`.
+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
 

package/docs/hydrogen.md

@@ -12,6 +12,22 @@ npm install @lime-bundles/react @lime-bundles/core
 
 `@lime-bundles/core` is a transitive dependency. Installing it explicitly lets you call `fetchBundleData` from a loader without pulling React.
 
+Then add both packages to Vite's SSR dependency optimizer in `vite.config.ts`. On a stock Hydrogen skeleton this step is **required** — without it, the first route that imports `@lime-bundles/react` crashes MiniOxygen's SSR with `Cannot read properties of null (reading 'useState')` (the CJS/ESM interop issue the skeleton's own config documents for `set-cookie-parser` and friends):
+
+```ts
+ssr: {
+  optimizeDeps: {
+    include: [
+      "set-cookie-parser",
+      "cookie",
+      "react-router",
+      "@lime-bundles/react",
+      "@lime-bundles/core",
+    ],
+  },
+},
+```
+
 ## Environment
 
 Open `/app/settings/headless` in your Lime Bundles admin, click **Generate token**, then append the value to your Hydrogen project's `.env`:
@@ -27,7 +43,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
 
@@ -160,9 +176,18 @@ The component renders tier cards, auto-selects the configured default tier, and
 
 ## Styling and merchant widget config
 
-The React SDK does **not** automatically apply the widget styles the merchant set in the admin editor. That's deliberate. If you chose `@lime-bundles/react` on Hydrogen you likely want full control over the look so bundles match your storefront's design system.
+Styling has two layers, and the built-in components handle only one of them automatically:
+
+1. **The merchant's widget config** (colours, borders, thumbnail ratios, show/hide toggles from the admin editor) — applied automatically. Each component emits the config as `--lb-*` CSS custom properties on its root, so the merchant's choices come through with no wiring.
+2. **The structural stylesheet** — imported by you, once:
+
+```tsx
+import "@lime-bundles/react/styles.css";
+```
+
+Without the import the components render as unstyled markup; with it they match the storefront widget's look, tinted by the merchant's config.
 
-Every `ParsedBundle` that `fetchBundleData` resolves to exposes the merchant's full config as `bundle.widgetConfig`. Read any field you want from it:
+Prefer a fully custom design instead? Skip the stylesheet and read the merchant's config off any `ParsedBundle` yourself:
 
 ```tsx
 <button style={{ background: bundle.widgetConfig.cta.primaryColor }}>
@@ -170,7 +195,7 @@ Every `ParsedBundle` that `fetchBundleData` resolves to exposes the merchant's f
 </button>
 ```
 
-Want drop-in parity with the admin preview instead? Swap to the [web component](./web-component.md): it honours `widgetConfig` end-to-end without any wiring on your side.
+Want drop-in parity with the admin preview with zero wiring? Swap to the [web component](./web-component.md): it carries its styles in its shadow root.
 
 Full field list in [`packages/core/src/bundle/types.ts`](../../packages/core/src/bundle/types.ts). Helpers `WIDGET_CONFIG_DEFAULTS`, `mergeWidgetConfig`, `flattenWidgetConfig`, and `applyWidgetConfigVars` are exported from `@lime-bundles/core` if you want to apply the CSS custom properties to your own DOM.
 

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
 
@@ -160,9 +160,18 @@ export function App() {
 
 ## Styling and merchant widget config
 
-The React SDK does **not** automatically apply the widget styles the merchant set in the admin editor. That's deliberate. If you chose `@lime-bundles/react`, you almost certainly want full control over the look so bundles match your storefront's design system.
+Styling has two layers, and the built-in components handle only one of them automatically:
 
-Every `ParsedBundle` (the object `fetchBundleData` resolves to and `useBundleData` hands you) exposes the merchant's full config as `bundle.widgetConfig`. Read any field you want:
+1. **The merchant's widget config** (colours, borders, thumbnail ratios, show/hide toggles from the admin editor) — applied automatically. Each component emits the config as `--lb-*` CSS custom properties on its root, so the merchant's choices come through with no wiring.
+2. **The structural stylesheet** — imported by you, once:
+
+```tsx
+import "@lime-bundles/react/styles.css";
+```
+
+Without the import the components render as unstyled markup; with it they match the storefront widget's look, tinted by the merchant's config.
+
+Prefer a fully custom design instead? Skip the stylesheet. Every `ParsedBundle` (the object `fetchBundleData` resolves to and `useBundleData` hands you) exposes the merchant's full config as `bundle.widgetConfig`. Read any field you want:
 
 ```tsx
 function BundleCTA({ bundle }: { bundle: ParsedBundle }) {
@@ -226,7 +235,18 @@ function ProductBundles({ handle }: { handle: string }) {
           case "volume":
             return <VolumeBundle key={bundle.id} bundleGid={bundle.id} {...cartProps} />;
           case "mix_match":
-            return <MixMatchBundle key={bundle.id} bundleGid={bundle.id} {...cartProps} />;
+            // `productHandle` opts into the theme widget's courtesy seed:
+            // with no required products, the bundle starts with the viewed
+            // product pre-added at its rule minimum. Omit it on pages that
+            // aren't product pages to start empty.
+            return (
+              <MixMatchBundle
+                key={bundle.id}
+                bundleGid={bundle.id}
+                productHandle={handle}
+                {...cartProps}
+              />
+            );
         }
       })}
     </>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lime-bundles/react",
-  "version": "6.0.0",
+  "version": "6.2.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",
@@ -52,7 +52,7 @@
     "react-dom": ">=18.0.0"
   },
   "dependencies": {
-    "@lime-bundles/core": "^6.0.0"
+    "@lime-bundles/core": "^6.3.0"
   },
   "devDependencies": {
     "@shopify/hydrogen-react": "^2026.4.1",