@lime-bundles/react 1.0.0 → 2.1.0

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": "1.0.0",
-  "description": "React components and hooks for Lime Bundles headless storefronts — Hydrogen, Next.js, Vite, and any React renderer.",
+  "version": "2.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",
   "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": "^1.0.0"
+    "@lime-bundles/core": "^2.1.0"
   },
   "devDependencies": {
     "@shopify/hydrogen-react": "^2026.4.1",