@lime-bundles/react 6.1.0 → 6.2.0

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`:
@@ -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

@@ -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.1.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.2.0"
+    "@lime-bundles/core": "^6.3.0"
   },
   "devDependencies": {
     "@shopify/hydrogen-react": "^2026.4.1",