@lime-bundles/widget 0.2.0 → 1.0.0

package/README.md

@@ -0,0 +1,155 @@
+# @lime-bundles/widget
+
+Framework-agnostic `<lime-bundle>` custom element for rendering Lime Bundles on any storefront: Astro, Vue, Svelte, plain HTML, classic Shopify themes via `<script>` tag.
+
+## Install
+
+Via npm:
+
+```bash
+npm install @lime-bundles/widget
+```
+
+```ts
+import "@lime-bundles/widget"; // registers <lime-bundle> globally
+```
+
+Or via CDN, zero build step:
+
+```html
+<script type="module" src="https://unpkg.com/@lime-bundles/widget"></script>
+```
+
+## Usage: the paste-and-go default
+
+One snippet in your product page template. The widget auto-detects the current product from the URL (`/products/<handle>`) and renders every active bundle for it. On "Add bundle", the widget calls Shopify's tokenless Storefront Cart API and redirects to checkout with the bundle discount applied. No cart code required.
+
+```html
+<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>
+```
+
+### BYO cart
+
+If you have your own cart, 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();
+      await myCart.linesAdd(event.detail.lines);
+    },
+  );
+</script>
+```
+
+## Attributes
+
+| Attribute | Required | Purpose |
+|---|:-:|---|
+| `shop-domain` | ✓ | Your shop domain, e.g. `my-shop.myshopify.com`. |
+| `storefront-token` | ✓ | Public Storefront Access Token. Generated in `/app/settings/headless`. |
+| `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; enables analytics when set. |
+| `analytics` |  | Set to `"false"` to suppress analytics even with `app-url` set. |
+| `locale` |  | BCP-47 tag forwarded to Storefront API. |
+
+Product resolution cascade when `bundle-gid` is absent: explicit `product-handle` → `<meta name="shopify:product-handle">` → `/products/<handle>` URL segment.
+
+Changing any attribute at runtime re-fetches and re-renders.
+
+## Events
+
+### `lime-bundle:add-to-cart`
+
+Fired on CTA click. `event.detail`:
+
+```ts
+{
+  lines: CartLineInput[];
+  bundleType: "fixed" | "volume" | "mix_match";
+  bundleId: string;
+}
+```
+
+Every line's `attributes` array includes `{ key: "_lime_bundle_gid", value: bundleId }`. Preserve it on the way to Shopify cart mutation or purchase attribution breaks.
+
+### `lime-bundle:error`
+
+Fired if bundle fetch / parse fails. `event.detail.error` is an `Error`. Render your own fallback UI in response.
+
+## Framework snippets
+
+**Astro:**
+
+```astro
+<lime-bundle shop-domain="..." storefront-token={import.meta.env.PUBLIC_LIME_BUNDLES_TOKEN} bundle-gid="..." />
+<script>
+  import "@lime-bundles/widget";
+  document.querySelector("lime-bundle")!.addEventListener("lime-bundle:add-to-cart", (e: any) => {
+    fetch("/api/cart-add", { method: "POST", body: JSON.stringify(e.detail.lines) });
+  });
+</script>
+```
+
+**Vue 3:**
+
+```vue
+<lime-bundle
+  shop-domain="my-shop.myshopify.com"
+  :storefront-token="token"
+  bundle-gid="..."
+  @lime-bundle:add-to-cart="handle"
+/>
+```
+
+Configure `app.config.compilerOptions.isCustomElement = (tag) => tag === "lime-bundle"` to silence Vue's warning.
+
+**Svelte:**
+
+```svelte
+<lime-bundle
+  shop-domain="my-shop.myshopify.com"
+  storefront-token={TOKEN}
+  bundle-gid="..."
+  on:lime-bundle:add-to-cart={handle}
+/>
+```
+
+## Styling
+
+Render happens inside a closed Shadow DOM. Override CSS custom properties on the host:
+
+```html
+<lime-bundle
+  style="--lb-primary-color: #e91e63; --lb-radius: 16px;"
+  shop-domain="..."
+></lime-bundle>
+```
+
+Merchant custom CSS from `/app/settings/custom-css` is auto-fetched and injected on mount.
+
+Full variable list: [css-variables.md](https://github.com/lime-app-dev/lime-bundles-app/blob/main/docs/headless/css-variables.md).
+
+## Bundle size
+
+`lime-bundle.js` (IIFE, gzipped) is <30 KB. No runtime framework dependency.
+
+## Versioning
+
+Major versions bump together with `@lime-bundles/core` and `@lime-bundles/react`.
+
+## License
+
+MIT. See repo root.
+
+## Links
+
+- [Web component guide](https://github.com/lime-app-dev/lime-bundles-app/blob/main/docs/headless/web-component.md)
+- [Report issues](https://github.com/lime-app-dev/lime-bundles-app/issues)

package/dist/index.cjs

@@ -382,19 +382,35 @@ var WIDGET_STYLES = `
 `;
 
 // src/lime-bundle.ts
+var cartStorageKey = (shopDomain) => `lb_cart_id:${shopDomain}`;
+function resolveProductHandle(explicit) {
+  if (explicit) return explicit.trim() || null;
+  if (typeof document !== "undefined") {
+    const meta = document.querySelector(
+      'meta[name="shopify:product-handle"]'
+    );
+    if (meta?.content) return meta.content.trim() || null;
+  }
+  if (typeof window !== "undefined") {
+    const match = window.location.pathname.match(/\/products\/([^/?#]+)/);
+    if (match?.[1]) return decodeURIComponent(match[1]);
+  }
+  return null;
+}
 var LimeBundleElement = class extends HTMLElement {
   static observedAttributes = [
     "shop-domain",
     "storefront-token",
     "bundle-gid",
+    "product-handle",
     "app-url",
     "analytics",
     "locale"
   ];
   shadow;
-  bundle = null;
+  bundles = [];
   abortController = null;
-  impressionCleanup = null;
+  impressionCleanups = [];
   constructor() {
     super();
     this.shadow = this.attachShadow({ mode: "open" });
@@ -405,16 +421,16 @@ var LimeBundleElement = class extends HTMLElement {
   }
   disconnectedCallback() {
     this.abortController?.abort();
-    this.teardownImpression();
+    this.teardownImpressions();
   }
-  teardownImpression() {
-    this.impressionCleanup?.();
-    this.impressionCleanup = null;
+  teardownImpressions() {
+    for (const cleanup of this.impressionCleanups) cleanup();
+    this.impressionCleanups = [];
   }
   attributeChangedCallback(name, oldValue, newValue) {
     if (oldValue === newValue || !this.isConnected) return;
-    if (name === "bundle-gid" || name === "shop-domain" || name === "storefront-token") {
-      if (this.shopDomain && this.storefrontToken && this.bundleGid) {
+    if (name === "bundle-gid" || name === "product-handle" || name === "shop-domain" || name === "storefront-token") {
+      if (this.shopDomain && this.storefrontToken) {
         this.fetchBundle();
       }
     }
@@ -428,6 +444,9 @@ var LimeBundleElement = class extends HTMLElement {
   get bundleGid() {
     return this.getAttribute("bundle-gid") ?? "";
   }
+  get productHandleAttr() {
+    return this.getAttribute("product-handle") ?? "";
+  }
   get appUrl() {
     return this.getAttribute("app-url") ?? "";
   }
@@ -435,9 +454,9 @@ var LimeBundleElement = class extends HTMLElement {
     return this.getAttribute("analytics") !== "false";
   }
   async fetchBundle() {
-    if (!this.shopDomain || !this.storefrontToken || !this.bundleGid) {
+    if (!this.shopDomain || !this.storefrontToken) {
       this.renderError(
-        "Missing required attributes: shop-domain, storefront-token, bundle-gid"
+        "Missing required attributes: shop-domain, storefront-token"
       );
       return;
     }
@@ -445,147 +464,255 @@ var LimeBundleElement = class extends HTMLElement {
     const controller = new AbortController();
     this.abortController = controller;
     this.renderLoading();
+    const client = (0, import_core4.createStorefrontClient)({
+      shopDomain: this.shopDomain,
+      accessToken: this.storefrontToken
+    });
     try {
-      const client = (0, import_core4.createStorefrontClient)({
-        shopDomain: this.shopDomain,
-        accessToken: this.storefrontToken
-      });
-      const [bundleData, cssData] = await Promise.all([
-        client.query(
-          import_core4.BUNDLE_METAOBJECT_QUERY,
-          { id: this.bundleGid },
-          { signal: controller.signal }
-        ),
-        client.query(
-          import_core4.SHOP_CUSTOM_CSS_QUERY,
-          void 0,
-          { signal: controller.signal }
-        ).catch(() => null)
-      ]);
+      let bundlePromise;
+      let singleBundleMode = false;
+      if (this.bundleGid) {
+        singleBundleMode = true;
+        bundlePromise = this.fetchSingleBundle(client, controller.signal);
+      } else {
+        const handle = resolveProductHandle(this.productHandleAttr);
+        if (!handle) {
+          this.teardownImpressions();
+          this.renderError(
+            "No bundle-gid or product-handle provided, and the current URL doesn't match /products/<handle>."
+          );
+          return;
+        }
+        bundlePromise = this.fetchProductBundles(
+          client,
+          controller.signal,
+          handle
+        );
+      }
+      const cssPromise = client.query(import_core4.SHOP_CUSTOM_CSS_QUERY, void 0, {
+        signal: controller.signal
+      }).catch(() => null);
+      await bundlePromise;
       if (controller.signal.aborted) return;
-      if (!bundleData.metaobject) {
-        this.bundle = null;
-        this.teardownImpression();
+      if (singleBundleMode && this.bundles.length === 0) {
+        this.teardownImpressions();
         this.renderError("Bundle not found");
         return;
       }
-      this.bundle = (0, import_core4.parseMetaobjectBundle)(
-        bundleData.metaobject.id,
-        bundleData.metaobject.fields
-      );
-      if (!this.bundle) {
-        this.teardownImpression();
-        this.renderError("Bundle is not active or has expired");
-        return;
+      const css = await cssPromise;
+      if (css?.shop?.metafield?.value) {
+        (0, import_core4.injectCustomCss)(this.shopDomain, css.shop.metafield.value);
       }
-      if (cssData?.shop?.metafield?.value) {
-        (0, import_core4.injectCustomCss)(this.shopDomain, cssData.shop.metafield.value);
-      }
-      this.renderBundle();
-      this.setupImpression();
+      this.renderBundles();
     } catch (err) {
       if (controller.signal.aborted) return;
-      this.bundle = null;
-      this.teardownImpression();
+      this.bundles = [];
+      this.teardownImpressions();
       this.renderError(
         err instanceof Error ? err.message : "Failed to load bundle"
       );
     }
   }
+  async fetchSingleBundle(client, signal) {
+    const data = await client.query(
+      import_core4.BUNDLE_METAOBJECT_QUERY,
+      { id: this.bundleGid },
+      { signal }
+    );
+    if (!data.metaobject) {
+      this.bundles = [];
+      return;
+    }
+    const parsed = (0, import_core4.parseMetaobjectBundle)(
+      data.metaobject.id,
+      data.metaobject.fields
+    );
+    this.bundles = parsed ? [parsed] : [];
+  }
+  async fetchProductBundles(client, signal, productHandle) {
+    const data = await client.query(
+      import_core4.BUNDLES_FOR_PRODUCT_QUERY,
+      { handle: productHandle },
+      { signal }
+    );
+    if (!data.product) {
+      this.bundles = [];
+      return;
+    }
+    const refs = data.product.metafield?.references?.nodes ?? [];
+    const bundles = [];
+    for (const ref of refs) {
+      const parsed = (0, import_core4.parseMetaobjectBundle)(ref.id, ref.fields);
+      if (parsed) bundles.push(parsed);
+    }
+    this.bundles = bundles;
+  }
   /**
-   * Dispatch add-to-cart for merchant handling. Returns true — the widget
-   * reports success optimistically. If the merchant's cart mutation fails,
-   * they're responsible for surfacing that error in their own UI.
+   * Dispatch add-to-cart with a cancelable event, then — unless a listener
+   * called preventDefault — execute the default cart-and-checkout flow.
+   *
+   * `fire-and-forget` against `reportAddToCart` runs regardless so merchants
+   * with BYO cart still get analytics.
    */
-  dispatchAddToCart = (lines) => {
-    this.dispatchEvent(
-      new CustomEvent("lime-bundle:add-to-cart", {
-        detail: { lines },
-        bubbles: true,
-        composed: true
-      })
-    );
-    if (this.analyticsEnabled && this.appUrl && this.bundle) {
-      const quantity = lines.reduce((sum, l) => sum + l.quantity, 0);
-      const totalPrice = lines.reduce((sum, line) => {
-        const product = this.bundle.products.find(
-          (p) => p.variants.nodes.some((v) => v.id === line.merchandiseId)
-        );
-        const variant = product?.variants.nodes.find(
-          (v) => v.id === line.merchandiseId
-        );
-        const price = variant ? parseFloat(variant.price.amount) : 0;
-        return sum + price * line.quantity;
-      }, 0);
-      (0, import_core4.reportAddToCart)(
-        { shopDomain: this.shopDomain, appUrl: this.appUrl },
-        {
-          bundleGid: this.bundleGid,
-          bundleType: this.bundle.bundleType,
-          productId: this.bundle.products[0]?.id ?? "",
-          quantity,
-          totalPrice: Math.round(totalPrice * 100) / 100
-        }
-      );
+  handleAddToCart = async (bundle, lines) => {
+    const ev = new CustomEvent("lime-bundle:add-to-cart", {
+      detail: { lines },
+      bubbles: true,
+      composed: true,
+      cancelable: true
+    });
+    const allowDefault = this.dispatchEvent(ev);
+    this.reportAddToCartEvent(bundle, lines);
+    if (allowDefault) {
+      await this.defaultAddToCart(lines);
     }
   };
-  renderBundle() {
-    if (!this.bundle) return;
-    const container = document.createElement("div");
-    container.className = "lb-bundle";
-    container.setAttribute("role", "region");
-    container.setAttribute("aria-label", this.bundle.title);
-    switch (this.bundle.bundleType) {
-      case "fixed":
-        renderFixedBundle(
-          container,
-          this.bundle,
-          this.dispatchAddToCart
+  /**
+   * Default cart flow: Shopify's Storefront Cart API is tokenless, so we
+   * don't need any additional scopes. Persist the cart ID in localStorage
+   * so subsequent adds on the same browser session join the existing cart
+   * instead of creating a new one every click.
+   */
+  async defaultAddToCart(lines) {
+    if (typeof window === "undefined") return;
+    const client = (0, import_core4.createStorefrontClient)({
+      shopDomain: this.shopDomain,
+      accessToken: this.storefrontToken
+    });
+    const storage = window.localStorage;
+    const key = cartStorageKey(this.shopDomain);
+    const existingCartId = storage?.getItem(key) ?? null;
+    try {
+      let checkoutUrl = null;
+      if (existingCartId) {
+        const res = await client.query(
+          import_core4.CART_LINES_ADD_MUTATION,
+          { cartId: existingCartId, lines }
         );
-        break;
-      case "mix_match":
-        renderMixMatchBundle(
-          container,
-          this.bundle,
-          this.dispatchAddToCart
+        const payload = res.cartLinesAdd;
+        if (payload?.userErrors?.length) {
+          storage?.removeItem(key);
+        } else if (payload?.cart) {
+          checkoutUrl = payload.cart.checkoutUrl;
+        }
+      }
+      if (!checkoutUrl) {
+        const res = await client.query(
+          import_core4.CART_CREATE_MUTATION,
+          { input: { lines } }
         );
-        break;
-      case "volume":
-        renderVolumeBundle(
-          container,
-          this.bundle,
-          this.dispatchAddToCart
+        const payload = res.cartCreate;
+        if (payload?.cart) {
+          storage?.setItem(key, payload.cart.id);
+          checkoutUrl = payload.cart.checkoutUrl;
+        }
+      }
+      if (checkoutUrl) {
+        window.location.assign(checkoutUrl);
+      } else {
+        this.dispatchEvent(
+          new CustomEvent("lime-bundle:error", {
+            detail: { message: "Cart creation failed", code: "CART_ERROR" },
+            bubbles: true,
+            composed: true
+          })
         );
-        break;
+      }
+    } catch (err) {
+      this.dispatchEvent(
+        new CustomEvent("lime-bundle:error", {
+          detail: {
+            message: err instanceof Error ? err.message : "Cart mutation failed",
+            code: "CART_ERROR"
+          },
+          bubbles: true,
+          composed: true
+        })
+      );
     }
+  }
+  reportAddToCartEvent(bundle, lines) {
+    if (!this.analyticsEnabled || !this.appUrl) return;
+    const quantity = lines.reduce((sum, l) => sum + l.quantity, 0);
+    const totalPrice = lines.reduce((sum, line) => {
+      const product = bundle.products.find(
+        (p) => p.variants.nodes.some((v) => v.id === line.merchandiseId)
+      );
+      const variant = product?.variants.nodes.find(
+        (v) => v.id === line.merchandiseId
+      );
+      const price = variant ? parseFloat(variant.price.amount) : 0;
+      return sum + price * line.quantity;
+    }, 0);
+    (0, import_core4.reportAddToCart)(
+      { shopDomain: this.shopDomain, appUrl: this.appUrl },
+      {
+        bundleGid: bundle.id,
+        bundleType: bundle.bundleType,
+        productId: bundle.products[0]?.id ?? "",
+        quantity,
+        totalPrice: Math.round(totalPrice * 100) / 100
+      }
+    );
+  }
+  renderBundles() {
+    this.teardownImpressions();
     this.shadow.innerHTML = "";
     const style = document.createElement("style");
     style.textContent = WIDGET_STYLES;
     this.shadow.appendChild(style);
-    this.shadow.appendChild(container);
+    for (const bundle of this.bundles) {
+      const container = document.createElement("div");
+      container.className = "lb-bundle";
+      container.setAttribute("role", "region");
+      container.setAttribute("aria-label", bundle.title);
+      const dispatch = (lines) => this.handleAddToCart(bundle, lines);
+      switch (bundle.bundleType) {
+        case "fixed":
+          renderFixedBundle(container, bundle, dispatch);
+          break;
+        case "mix_match":
+          renderMixMatchBundle(
+            container,
+            bundle,
+            dispatch
+          );
+          break;
+        case "volume":
+          renderVolumeBundle(container, bundle, dispatch);
+          break;
+      }
+      this.shadow.appendChild(container);
+      this.setupImpressionFor(bundle, container);
+    }
+    const first = this.bundles[0];
     this.dispatchEvent(
       new CustomEvent("lime-bundle:loaded", {
         detail: {
-          bundleType: this.bundle.bundleType,
-          title: this.bundle.title
+          bundleCount: this.bundles.length,
+          bundleTypes: this.bundles.map((b) => b.bundleType),
+          // Legacy fields — meaningful only in single-bundle mode. Preserved
+          // for merchants who attached listeners against the pre-1.0 shape.
+          bundleType: first?.bundleType,
+          title: first?.title
         },
         bubbles: true,
         composed: true
       })
     );
   }
-  setupImpression() {
-    if (!this.analyticsEnabled || !this.bundle || !this.appUrl) return;
-    this.impressionCleanup?.();
-    this.impressionCleanup = (0, import_core4.observeImpression)(this, () => {
+  setupImpressionFor(bundle, element) {
+    if (!this.analyticsEnabled || !this.appUrl) return;
+    const cleanup = (0, import_core4.observeImpression)(element, () => {
       (0, import_core4.reportImpression)(
         { shopDomain: this.shopDomain, appUrl: this.appUrl },
         {
-          bundleGid: this.bundleGid,
-          bundleType: this.bundle.bundleType
+          bundleGid: bundle.id,
+          bundleType: bundle.bundleType
         }
       );
     });
+    this.impressionCleanups.push(cleanup);
   }
   renderLoading() {
     this.shadow.innerHTML = `