@lime-bundles/react 0.2.0 → 2.0.0

package/docs/react-nextjs.md

@@ -0,0 +1,379 @@
+# React / Next.js / Vite
+
+> **Before you start:** you may not need this guide. The [web component](./web-component.md) (`<lime-bundle>`) works inside any React app. Paste it into your JSX like any other custom element, handle cart and checkout via Shopify's tokenless Storefront Cart API, zero configuration. Use this guide only when you want React components (`<FixedBundle>`, `<VolumeBundle>`, `<MixMatchBundle>`) with type-safe props and cart integration through your existing React state.
+
+`@lime-bundles/react` works anywhere React does. This guide covers Next.js App Router, Pages Router, and Vite / CRA. For Remix on Oxygen, see the [Hydrogen guide](./hydrogen.md). Hydrogen is Remix under the hood, and the loader pattern there applies unchanged. BYO-cart: Lime Bundles renders and tracks analytics; you wire up your own cart mutation.
+
+## Install
+
+```bash
+npm install @lime-bundles/react @lime-bundles/core
+```
+
+React ≥18 and react-dom ≥18 are peer dependencies.
+
+## Environment
+
+Open `/app/settings/headless` in your Lime Bundles admin, click **Generate token**, then append the value to your project. Don't overwrite the Shopify Storefront token your app already uses:
+
+```bash
+# .env.local (Next.js) or .env (Vite)
+NEXT_PUBLIC_SHOPIFY_STORE_DOMAIN=my-shop.myshopify.com
+NEXT_PUBLIC_LIME_BUNDLES_TOKEN=<paste the generated token>
+
+# Vite: same name with the VITE_ prefix instead
+# VITE_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.
+
+## Pick a rendering mode
+
+Before you drop a component into a route, decide which bundles you want to show.
+
+- **All bundles on this product** (the standard Shopify behaviour). Use [`useBundlesForProduct({ productHandle })`](#auto-fetch-every-bundle-for-a-product). Hand it a product handle from your router (`params.handle`, `params.slug`, etc.) and render whatever comes back.
+- **One specific bundle, pinned to this page.** Hardcode the bundle's Shopify Metaobject GID (you can copy it from the URL of the bundle's analytics page in the admin) and pass it to `<FixedBundle>` / `<VolumeBundle>` / `<MixMatchBundle>` via `bundleGid`.
+
+Most product-page integrations want the first pattern. Landing-pages / curated placements want the second.
+
+## Next.js App Router (client-only, pin one bundle)
+
+```tsx
+// app/bundles/[id]/page.tsx
+"use client";
+
+import { FixedBundle } from "@lime-bundles/react";
+
+export default function BundlePage({ params }: { params: { id: string } }) {
+  return (
+    <FixedBundle
+      shopDomain={process.env.NEXT_PUBLIC_SHOPIFY_STORE_DOMAIN!}
+      storefrontAccessToken={process.env.NEXT_PUBLIC_LIME_BUNDLES_TOKEN!}
+      bundleGid={`gid://shopify/Metaobject/${params.id}`}
+      onAddToCart={async (lines) => {
+        // Wire your cart here. Storefront Cart API, a Route Handler, etc.
+        await fetch("/api/cart/add", {
+          method: "POST",
+          body: JSON.stringify(lines),
+        });
+      }}
+      onError={(err) => console.error(err)}
+    />
+  );
+}
+```
+
+The component fetches the bundle on mount via `useBundleData`, manages loading / error state internally, and calls `onAddToCart` when the merchant clicks the CTA.
+
+## Next.js App Router (server-fetch + client-render)
+
+Fetch the bundle in a Server Component, render it in a Client Component. This avoids the client-side network round-trip on first paint.
+
+```tsx
+// app/bundles/[id]/page.tsx (server component, no "use client")
+import { fetchBundleData } from "@lime-bundles/react";
+import { BundleClient } from "./BundleClient";
+import { headers } from "next/headers";
+
+export default async function BundlePage({ params }: { params: { id: string } }) {
+  const h = await headers();
+  const bundle = await fetchBundleData({
+    shopDomain: process.env.NEXT_PUBLIC_SHOPIFY_STORE_DOMAIN!,
+    storefrontAccessToken: process.env.NEXT_PUBLIC_LIME_BUNDLES_TOKEN!,
+    bundleGid: `gid://shopify/Metaobject/${params.id}`,
+    buyerIp: h.get("x-forwarded-for")?.split(",")[0] ?? undefined,
+  });
+
+  return <BundleClient bundle={bundle} />;
+}
+```
+
+```tsx
+// app/bundles/[id]/BundleClient.tsx
+"use client";
+import type { ParsedBundle } from "@lime-bundles/react";
+
+export function BundleClient({ bundle }: { bundle: ParsedBundle }) {
+  // Render directly from the prop. No fetch needed.
+  // Wire up your own UI here, or pass to <FixedBundle> if you still
+  // want the components to double-check liveness via useBundleData.
+  return <pre>{JSON.stringify(bundle, null, 2)}</pre>;
+}
+```
+
+### SSR without refetch
+
+If you want server-rendered HTML *and* the Lime Bundles React components, pass the server-fetched bundle through React Query / SWR / a context, and have the inner component skip its own `useBundleData` call. A lightweight pattern: fork `<FixedBundle>` into your own component and copy the rendering logic (~80 lines). The SDK exports the bundle data type so this is straightforward.
+
+## Next.js Pages Router
+
+Use `getServerSideProps`:
+
+```tsx
+import { fetchBundleData, FixedBundle, type ParsedBundle } from "@lime-bundles/react";
+import type { GetServerSideProps } from "next";
+
+export const getServerSideProps: GetServerSideProps = async ({ req, params }) => {
+  const bundle = await fetchBundleData({
+    shopDomain: process.env.NEXT_PUBLIC_SHOPIFY_STORE_DOMAIN!,
+    storefrontAccessToken: process.env.NEXT_PUBLIC_LIME_BUNDLES_TOKEN!,
+    bundleGid: `gid://shopify/Metaobject/${params!.id}`,
+    buyerIp: (req.headers["x-forwarded-for"] as string)?.split(",")[0],
+  });
+  return { props: { bundle } };
+};
+
+export default function Page({ bundle }: { bundle: ParsedBundle }) {
+  return (
+    <FixedBundle
+      shopDomain={process.env.NEXT_PUBLIC_SHOPIFY_STORE_DOMAIN!}
+      storefrontAccessToken={process.env.NEXT_PUBLIC_LIME_BUNDLES_TOKEN!}
+      bundleGid={bundle.id}
+      onAddToCart={async (lines) => {
+        await fetch("/api/cart/add", { method: "POST", body: JSON.stringify(lines) });
+      }}
+    />
+  );
+}
+```
+
+## Vite / CRA
+
+```tsx
+import { FixedBundle } from "@lime-bundles/react";
+
+export function App() {
+  return (
+    <FixedBundle
+      shopDomain={import.meta.env.VITE_SHOPIFY_STORE_DOMAIN}
+      storefrontAccessToken={import.meta.env.VITE_LIME_BUNDLES_TOKEN}
+      bundleGid="gid://shopify/Metaobject/123"
+      onAddToCart={async (lines) => {
+        await fetch("/cart/add", { method: "POST", body: JSON.stringify(lines) });
+      }}
+    />
+  );
+}
+```
+
+## 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.
+
+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 }) {
+  return (
+    <button style={{ background: bundle.widgetConfig.cta.primaryColor }}>
+      {bundle.widgetConfig.cta.ctaText}
+    </button>
+  );
+}
+```
+
+Want drop-in parity with the admin preview (same header, save badge, product list, etc.) without writing markup? Swap to the [web component](./web-component.md) instead; it honours `widgetConfig` end-to-end.
+
+The shape of `widgetConfig` is stable at v2.0.0. See [`packages/core/src/bundle/types.ts`](../../packages/core/src/bundle/types.ts) for the full field list. Helpers `WIDGET_CONFIG_DEFAULTS`, `mergeWidgetConfig`, `flattenWidgetConfig`, and `applyWidgetConfigVars` are exported from `@lime-bundles/core` if you want to apply the CSS custom properties onto your own DOM instead of reading fields one at a time.
+
+## Auto-fetch every bundle for a product
+
+The web component's default mode is "show every active bundle configured against the current product." The React SDK equivalent is `useBundlesForProduct`:
+
+```tsx
+import {
+  useBundlesForProduct,
+  FixedBundle,
+  VolumeBundle,
+  MixMatchBundle,
+  type CartLineInput,
+} from "@lime-bundles/react";
+
+const SHOP_DOMAIN = process.env.NEXT_PUBLIC_SHOPIFY_STORE_DOMAIN!;
+const TOKEN = process.env.NEXT_PUBLIC_LIME_BUNDLES_TOKEN!;
+
+function ProductBundles({ handle }: { handle: string }) {
+  const result = useBundlesForProduct({
+    shopDomain: SHOP_DOMAIN,
+    storefrontAccessToken: TOKEN,
+    productHandle: handle,
+  });
+
+  if (result.status === "loading") return null;          // or your own skeleton
+  if (result.status === "error") return null;
+  if (result.bundles.length === 0) return null;
+
+  const cartProps = {
+    shopDomain: SHOP_DOMAIN,
+    storefrontAccessToken: TOKEN,
+    onAddToCart: async (lines: CartLineInput[]) => {
+      await fetch("/api/cart/add", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ lines }),
+      });
+    },
+  };
+
+  return (
+    <>
+      {result.bundles.map((bundle) => {
+        switch (bundle.bundleType) {
+          case "fixed":
+            return <FixedBundle key={bundle.id} bundleGid={bundle.id} {...cartProps} />;
+          case "volume":
+            return <VolumeBundle key={bundle.id} bundleGid={bundle.id} {...cartProps} />;
+          case "mix_match":
+            return <MixMatchBundle key={bundle.id} bundleGid={bundle.id} {...cartProps} />;
+        }
+      })}
+    </>
+  );
+}
+```
+
+Inactive, draft, not-yet-started, and expired bundles are filtered out by the hook; consumers don't need to guard.
+
+For SSR / Hydrogen loaders, use `fetchBundlesForProduct` (the async helper `useBundlesForProduct` wraps) and pass the list as a prop to a client component.
+
+## Build your own UI (DIY path)
+
+If the built-in `<FixedBundle>` / `<VolumeBundle>` / `<MixMatchBundle>` components aren't the right fit (you want a radically different layout, or you want to compose bundles into an existing design system), `@lime-bundles/react` re-exports every primitive the first-party widget uses. You never have to reverse-engineer our totals or CSS variables.
+
+**Data + parsing:**
+
+```tsx
+import {
+  createStorefrontClient,
+  fetchBundlesForProduct,
+  parseMetaobjectBundle,
+  BUNDLE_METAOBJECT_QUERY,
+  BUNDLES_FOR_PRODUCT_QUERY,
+} from "@lime-bundles/react";
+```
+
+**Pricing math (matches Shopify Discount Function per-unit floor rounding):**
+
+```tsx
+import {
+  parseCents,
+  formatCents,
+  percentageDiscountUnit,
+  computeFixedPricing,
+  computeBundleSaleCents,
+  calculateTierSavings,
+  getActiveTier,
+} from "@lime-bundles/react";
+
+const pricing = computeFixedPricing(bundle);
+// { rows, totalCents, saleCents, savingsCents, headerBadge, currency }
+```
+
+**Merchant widget config → CSS variables:**
+
+```tsx
+import {
+  WIDGET_CONFIG_DEFAULTS,
+  mergeWidgetConfig,
+  applyWidgetConfigVars,
+  CSS_VAR_MAP,
+} from "@lime-bundles/react";
+
+useEffect(() => {
+  if (wrapperRef.current) {
+    applyWidgetConfigVars(wrapperRef.current, bundle.widgetConfig);
+  }
+}, [bundle.widgetConfig]);
+```
+
+**Image URL transforms (Shopify CDN 152×152 thumbnails):**
+
+```tsx
+import { transformImageUrl } from "@lime-bundles/react";
+
+<img
+  src={transformImageUrl(product.featuredImage.url, { width: 152, height: 152, crop: "center" })}
+  width={152}
+  height={152}
+  loading="lazy"
+  alt={product.title}
+/>
+```
+
+**Countdown timer:**
+
+```tsx
+import { formatCountdown } from "@lime-bundles/react";
+
+const [msLeft, setMsLeft] = useState(Date.parse(bundle.endsAt!) - Date.now());
+useEffect(() => {
+  const id = setInterval(() => setMsLeft(Date.parse(bundle.endsAt!) - Date.now()), 1000);
+  return () => clearInterval(id);
+}, [bundle.endsAt]);
+
+return <span>{formatCountdown(msLeft)}</span>;
+```
+
+**A/B variant resolution:**
+
+```tsx
+import { getABTestAssignment, applyABVariantB } from "@lime-bundles/react";
+
+// appUrl is your Lime Bundles app URL (same value your theme app block uses).
+// shopDomain is the merchant's *.myshopify.com domain.
+const appUrl = process.env.NEXT_PUBLIC_LIME_BUNDLES_APP_URL!;
+const shopDomain = process.env.NEXT_PUBLIC_SHOPIFY_STORE_DOMAIN!;
+
+const assignment = await getABTestAssignment(
+  appUrl,
+  shopDomain,
+  bundle.abTestId!,
+  bundle.id,
+);
+const bundleForRender = assignment?.variant === "B" ? applyABVariantB(bundle) : bundle;
+```
+
+**Analytics + consent:**
+
+```tsx
+import {
+  reportImpression,
+  reportAddToCart,
+  observeImpression,
+  setConsent,
+  hasConsent,
+} from "@lime-bundles/react";
+```
+
+**Custom CSS injection:**
+
+```tsx
+import { injectCustomCss, sanitizeCustomCss } from "@lime-bundles/react";
+```
+
+**Mix-match quantity validation:**
+
+```tsx
+import { validateQuantity } from "@lime-bundles/react";
+
+const { valid, message } = validateQuantity(selectedCount, 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.
+
+## Cart mutation patterns
+
+You choose how `onAddToCart` talks to Shopify. Three common patterns:
+
+1. **Storefront Cart API directly from the client.** Call `cartLinesAdd` via `createStorefrontClient` (from `@lime-bundles/core`). Public token, safe in the browser.
+2. **Proxy via your own API route.** POST to `/api/cart/add` (Next.js Route Handler) which calls Storefront Cart API server-side. Lets you validate inventory, tack on UTM params, or enforce per-shop rate limits before forwarding.
+3. **Existing cart context.** If you already use Hydrogen-React's `CartProvider`, call `useCart().linesAdd` inside the callback. See [Hydrogen guide](./hydrogen.md).
+
+In all three, preserve the `attributes` array on each `CartLineInput` verbatim. `_lime_bundle_gid` and `_lime_bundle_type` drive purchase attribution on the Lime Bundles `orders/create` webhook.
+
+## Next steps
+
+- [CSS variables reference](./css-variables.md): brand-match the widget.
+- [Web component guide](./web-component.md): fallback for non-React sections.

package/docs/web-component.md

@@ -0,0 +1,282 @@
+# Web component
+
+`<lime-bundle>` is a standards-compliant custom element that renders Lime Bundles wherever you can drop an HTML tag into a product page template. **One tag, done.** It's the same widget your merchants see in the Lime Bundles admin preview, with every setting and colour choice honoured.
+
+Two delivery paths, same widget:
+
+- **HTML path**: paste a `<script>` tag and an HTML element. Works on any storefront that can include a `<script type="module">`. Zero build step.
+- **React path**: install via npm, import in your client entry, use `<lime-bundle>` like any JSX element. Recommended for Hydrogen / Next.js / Vite because it avoids Content Security Policy issues with third-party script origins.
+
+## <a id="html-storefronts"></a>HTML storefronts
+
+Zero build step, zero npm install. Paste two lines into your product page template:
+
+```html
+<!-- Paste once in your product page template -->
+<script type="module" src="https://unpkg.com/@lime-bundles/widget"></script>
+<lime-bundle
+  shop-domain="my-shop.myshopify.com"
+  storefront-token="<YOUR_LIME_BUNDLES_TOKEN>"
+></lime-bundle>
+```
+
+Generate your token by visiting `/app/settings/headless` in your Lime Bundles admin and clicking **Generate token**. The token is a read-only public Storefront Access Token, safe to ship in HTML. If it leaks, click **Regenerate** on the same page.
+
+The widget auto-detects the current product from the URL (`/products/<handle>`) and renders every active bundle configured for it. On **Add bundle**, the widget calls Shopify's tokenless Storefront Cart API and redirects to checkout with the discount applied. No cart code needed.
+
+## <a id="react-storefronts"></a>React storefronts (Hydrogen, Next.js, Vite)
+
+Same `<lime-bundle>` element, but installed via npm so it ships through your bundler instead of a CDN. Recommended for React storefronts because:
+
+1. Hydrogen's default Content Security Policy blocks third-party script origins. Importing the package through your own bundle avoids the CSP exception.
+2. You get a pinned version in `package.json` instead of the CDN's "latest."
+3. Tree-shaking and nonce handling are automatic.
+
+**1. Install:**
+
+```bash
+npm install @lime-bundles/widget
+```
+
+**2. Import once in your client entry.** This registers `<lime-bundle>` as a global custom element:
+
+```tsx
+// Hydrogen          → app/entry.client.tsx
+// Next.js App Router → app/layout.tsx  (client component)
+// Vite              → src/main.tsx
+import "@lime-bundles/widget";
+```
+
+**3. Use anywhere in JSX** (product page template is the typical placement):
+
+```tsx
+export default function ProductBundles({ token }: { token: string }) {
+  return (
+    <lime-bundle
+      shop-domain="my-shop.myshopify.com"
+      storefront-token={token}
+    />
+  );
+}
+```
+
+Pull the token from your framework's environment variables:
+
+- **Hydrogen**: `context.env.PUBLIC_LIME_BUNDLES_TOKEN` inside your loader, pass it as a prop.
+- **Next.js**: `process.env.NEXT_PUBLIC_LIME_BUNDLES_TOKEN`.
+- **Vite**: `import.meta.env.VITE_LIME_BUNDLES_TOKEN`.
+
+### TypeScript
+
+TypeScript doesn't know about `<lime-bundle>` by default. Add a small ambient declaration to silence the JSX error:
+
+```ts
+// app/types/lime-bundle.d.ts
+declare namespace JSX {
+  interface IntrinsicElements {
+    "lime-bundle": React.DetailedHTMLProps<
+      React.HTMLAttributes<HTMLElement> & {
+        "shop-domain": string;
+        "storefront-token": string;
+        "bundle-gid"?: string;
+        "product-handle"?: string;
+      },
+      HTMLElement
+    >;
+  }
+}
+```
+
+### Providing the product handle explicitly
+
+If your storefront's product URL doesn't follow `/products/<handle>` (for example, some storefronts use `/shop/<handle>` or put the handle in a query param), set `product-handle` explicitly:
+
+```html
+<lime-bundle
+  shop-domain="my-shop.myshopify.com"
+  storefront-token="<TOKEN>"
+  product-handle="cool-tshirt"
+></lime-bundle>
+```
+
+### Taking over the cart (BYO)
+
+If you have your own cart (Hydrogen `useCart`, custom cart drawer, etc.), listen for `lime-bundle:add-to-cart` and call `event.preventDefault()` to suppress the default redirect:
+
+```html
+<script>
+  document.querySelector("lime-bundle").addEventListener(
+    "lime-bundle:add-to-cart",
+    async (event) => {
+      event.preventDefault(); // skip the default "redirect to Shopify checkout" flow
+      await myCart.linesAdd(event.detail.lines);
+    },
+  );
+</script>
+```
+
+The event is always dispatched; only the default action is conditional.
+
+## Attributes
+
+| Attribute | Required | Purpose |
+|---|:-:|---|
+| `shop-domain` | ✓ | Your shop domain, e.g. `my-shop.myshopify.com`. |
+| `storefront-token` | ✓ | Generated in `/app/settings/headless`. Read-only Storefront Access Token (not the admin API key). |
+| `bundle-gid` |  | Pin one specific bundle. When set, overrides auto-detect. |
+| `product-handle` |  | Render bundles for a specific product handle. Overrides URL detection. |
+| `app-url` |  | Lime Bundles app URL (sends impression / add-to-cart analytics). Omit to disable analytics. |
+| `analytics` |  | Set to `"false"` to suppress analytics even if `app-url` is set. |
+| `locale` |  | BCP-47 tag for the buyer's locale. Forwarded to Storefront API. |
+
+**Product resolution cascade** (when `bundle-gid` is absent): explicit `product-handle` → `<meta name="shopify:product-handle">` → `/products/<handle>` URL segment → error.
+
+Changing any attribute at runtime re-fetches and re-renders. Safe to drive from a framework's reactivity.
+
+## Events
+
+All events bubble and cross shadow-DOM boundaries (`composed: true`), so you can listen on any ancestor.
+
+### `lime-bundle:add-to-cart`
+
+Fired when the customer clicks the CTA. The `detail` object carries the cart payload:
+
+```ts
+type AddToCartDetail = {
+  lines: CartLineInput[];
+};
+
+type CartLineInput = {
+  merchandiseId: string;  // variant GID
+  quantity: number;
+  attributes: Array<{ key: string; value: string }>;
+};
+```
+
+Every `CartLineInput.attributes` array includes `{ key: "_lime_bundle_gid", value: <bundle GID> }`. Preserve it on the way to Shopify cart mutation or purchase attribution breaks.
+
+### `lime-bundle:loaded`
+
+Fired once bundle data has been fetched and parsed successfully. Useful for hiding a placeholder or triggering analytics in non-SDK systems. The event fires even when zero bundles apply to the current product (product has no bundles attached); check `bundleCount` to tell the difference.
+
+```ts
+type LoadedDetail = {
+  bundleCount: number;
+  bundleTypes: Array<"fixed" | "volume" | "mix_match">;
+  // Legacy single-bundle fields; undefined when bundleCount === 0.
+  bundleType?: "fixed" | "volume" | "mix_match";
+  title?: string;
+};
+```
+
+**Migrating from v1.** Earlier versions emitted only `bundleType` and `title`, scoped to the first bundle rendered. v2 adds `bundleCount` and `bundleTypes` so listeners can see every bundle on the page. The legacy fields are still populated when at least one bundle renders but are `undefined` when `bundleCount === 0`. Guard accordingly, or migrate to the new fields:
+
+```ts
+el.addEventListener("lime-bundle:loaded", (e) => {
+  const d = e.detail as LoadedDetail;
+  if (d.bundleCount === 0) return;
+  // d.bundleType / d.title are safe to read here.
+});
+```
+
+### `lime-bundle:error`
+
+Fired if bundle fetch or parse fails. The widget renders its own inline fallback, but listen for this event if you want to hide the widget entirely or report to your own telemetry:
+
+```ts
+type ErrorDetail = {
+  message: string;
+  code: string; // e.g. "LOAD_ERROR"
+};
+```
+
+## Other framework integrations
+
+Non-React stacks that follow the same npm-install-plus-import pattern.
+
+### Astro
+
+```astro
+---
+// any component file
+---
+<lime-bundle
+  shop-domain="my-shop.myshopify.com"
+  storefront-token={import.meta.env.PUBLIC_LIME_BUNDLES_TOKEN}
+  bundle-gid="gid://shopify/Metaobject/42"
+></lime-bundle>
+<script>
+  import "@lime-bundles/widget";
+  document.querySelector("lime-bundle")!.addEventListener("lime-bundle:add-to-cart", async (e: any) => {
+    await fetch("/api/cart-add", { method: "POST", body: JSON.stringify(e.detail.lines) });
+  });
+</script>
+```
+
+### Vue 3
+
+```vue
+<template>
+  <lime-bundle
+    shop-domain="my-shop.myshopify.com"
+    :storefront-token="token"
+    bundle-gid="gid://shopify/Metaobject/42"
+    @lime-bundle:add-to-cart="handleAdd"
+  />
+</template>
+
+<script setup lang="ts">
+import "@lime-bundles/widget";
+const token = import.meta.env.VITE_LIME_BUNDLES_TOKEN;
+async function handleAdd(e: CustomEvent) {
+  await fetch("/cart/add", { method: "POST", body: JSON.stringify(e.detail.lines) });
+}
+</script>
+```
+
+Vue's custom-element handling needs `app.config.compilerOptions.isCustomElement = (tag) => tag === "lime-bundle"` if you hit warnings.
+
+### Svelte
+
+```svelte
+<script>
+  import "@lime-bundles/widget";
+  function handle(e) {
+    fetch("/cart/add", { method: "POST", body: JSON.stringify(e.detail.lines) });
+  }
+</script>
+
+<lime-bundle
+  shop-domain="my-shop.myshopify.com"
+  storefront-token={import.meta.env.VITE_LIME_BUNDLES_TOKEN}
+  bundle-gid="gid://shopify/Metaobject/42"
+  on:lime-bundle:add-to-cart={handle}
+></lime-bundle>
+```
+
+## Styling
+
+`<lime-bundle>` renders inside a closed Shadow DOM. Merchant custom CSS set in `/app/settings/custom-css` is auto-fetched and injected into the shadow root on `connectedCallback`. To override the built-in look, set CSS custom properties on the host:
+
+```html
+<lime-bundle
+  shop-domain="..."
+  style="--lb-primary-color: #e91e63; --lb-radius: 16px;"
+></lime-bundle>
+```
+
+Full variable list: [css-variables.md](./css-variables.md).
+
+## What's automatic
+
+Every part of the widget a merchant configures in the admin is wired up for you:
+
+- **Widget styling.** Every `--lb-*` CSS variable the merchant set in the admin editor (header colours, save badge, savings bar, product list styling, popular tier badge, mix-match picker styling, etc.) is applied inside the shadow root on render. Same widget, same look.
+- **Shop custom CSS.** The sanitized CSS at `shop.metafields["$app"].custom_css` is injected into the shadow root alongside the built-in stylesheets so rules like `.lb-bundle-widget { ... }` hit the widget.
+- **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`.
+- **A/B test assignment.** The widget bucketises the visitor via `getABTestAssignment` (cookie-persisted, consent-gated) and merges Variant B overrides (title, description, discount, volume tiers) when the visitor lands in B. Honours Shopify's `customerPrivacy` framework or the SDK's `setConsent(true)` helper.
+- **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,7 +1,7 @@
 {
   "name": "@lime-bundles/react",
-  "version": "0.2.0",
-  "description": "React components and hooks for Lime Bundles headless storefronts — Hydrogen, Next.js, Vite, and any React renderer.",
+  "version": "2.0.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",
   "module": "./dist/index.js",
@@ -16,7 +16,8 @@
     "./package.json": "./package.json"
   },
   "files": [
-    "dist"
+    "dist",
+    "docs"
   ],
   "publishConfig": {
     "access": "public"
@@ -51,7 +52,7 @@
     "react-dom": ">=18.0.0"
   },
   "dependencies": {
-    "@lime-bundles/core": "^0.2.0"
+    "@lime-bundles/core": "^2.0.0"
   },
   "devDependencies": {
     "@shopify/hydrogen-react": "^2026.4.1",