@lime-bundles/widget 1.0.0 → 2.0.0

package/README.md

@@ -1,6 +1,8 @@
 # @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.
+Drop-in `<lime-bundle>` web component for the **Lime Bundles Shopify app**. Embed merchant-configured bundles on any JavaScript-enabled headless storefront (Hydrogen, Astro, Vue, Svelte, plain HTML). If you're not a merchant using Lime Bundles, this package probably isn't what you're looking for.
+
+Ships the full widget your merchants see in the admin preview: header, save badge, product list with count bubbles, savings bar, pricing footer, themed CTA.
 
 ## Install
 
@@ -20,9 +22,9 @@ Or via CDN, zero build step:
 <script type="module" src="https://unpkg.com/@lime-bundles/widget"></script>
 ```
 
-## Usage: the paste-and-go default
+## Paste-and-go
 
-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.
+One snippet in your product page template. The widget resolves the current product from the URL (`/products/<handle>`) and renders every active bundle configured for it. Clicking **Add bundle** calls Shopify's tokenless Storefront Cart API and redirects to checkout with the discount applied.
 
 ```html
 <script type="module" src="https://unpkg.com/@lime-bundles/widget"></script>
@@ -32,124 +34,126 @@ One snippet in your product page template. The widget auto-detects the current p
 ></lime-bundle>
 ```
 
-### BYO cart
+Generate the token at `/app/settings/headless` in your Lime Bundles admin. It's a read-only Storefront Access Token (bundle metaobjects + product listings only), safe to ship in HTML.
 
-If you have your own cart, listen for `lime-bundle:add-to-cart` and call `event.preventDefault()` to suppress the default redirect:
+## BYO cart
 
-```html
-<script>
-  document.querySelector("lime-bundle").addEventListener(
-    "lime-bundle:add-to-cart",
-    async (event) => {
-      event.preventDefault();
-      await myCart.linesAdd(event.detail.lines);
-    },
-  );
-</script>
+Listen for `lime-bundle:add-to-cart` and call `event.preventDefault()` to suppress the default redirect:
+
+```js
+document.querySelector("lime-bundle").addEventListener(
+  "lime-bundle:add-to-cart",
+  async (event) => {
+    event.preventDefault();
+    await myCart.linesAdd(event.detail.lines);
+  },
+);
 ```
 
 ## 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. |
+| `shop-domain` | ✓ | `*.myshopify.com` domain. |
+| `storefront-token` | ✓ | Storefront Access Token from `/app/settings/headless`. |
+| `bundle-gid` |  | Render one specific bundle. Overrides auto-detect. |
+| `product-handle` |  | Render bundles for this handle. Overrides URL detection. |
+| `app-url` |  | Enables impression + add-to-cart analytics when set. |
+| `analytics` |  | `"false"` suppresses analytics even when `app-url` is set. |
+| `locale` |  | BCP-47 tag forwarded to the Storefront API. |
 
-Product resolution cascade when `bundle-gid` is absent: explicit `product-handle` → `<meta name="shopify:product-handle">` → `/products/<handle>` URL segment.
+**Product resolution** (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
 
+All events bubble and pierce shadow-DOM boundaries (`composed: true`), so you can listen on any ancestor.
+
 ### `lime-bundle:add-to-cart`
 
-Fired on CTA click. `event.detail`:
+Fired on CTA click. Cancelable: `event.preventDefault()` suppresses the default checkout redirect.
 
 ```ts
-{
-  lines: CartLineInput[];
-  bundleType: "fixed" | "volume" | "mix_match";
-  bundleId: string;
+event.detail: {
+  lines: CartLineInput[];  // merchandiseId + quantity + attributes
 }
 ```
 
-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.
+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.
 
-## Framework snippets
+### `lime-bundle:loaded`
 
-**Astro:**
+Fired once the bundle(s) have been fetched and parsed.
 
-```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>
+```ts
+event.detail: {
+  bundleCount: number;
+  bundleTypes: Array<"fixed" | "volume" | "mix_match">;
+}
 ```
 
-**Vue 3:**
+### `lime-bundle:error`
 
-```vue
-<lime-bundle
-  shop-domain="my-shop.myshopify.com"
-  :storefront-token="token"
-  bundle-gid="..."
-  @lime-bundle:add-to-cart="handle"
-/>
+Fired if fetch or parse fails.
+
+```ts
+event.detail: { message: string; code: string }  // e.g. "LOAD_ERROR"
 ```
 
-Configure `app.config.compilerOptions.isCustomElement = (tag) => tag === "lime-bundle"` to silence Vue's warning.
+The widget renders its own inline fallback; listen for this event if you want to hide the parent or report to your own telemetry.
 
-**Svelte:**
+## What the widget handles for you
 
-```svelte
-<lime-bundle
-  shop-domain="my-shop.myshopify.com"
-  storefront-token={TOKEN}
-  bundle-gid="..."
-  on:lime-bundle:add-to-cart={handle}
-/>
-```
+- **Merchant styling.** Every `--lb-*` CSS variable the merchant configured in the admin is applied inside the shadow root on render.
+- **Custom CSS.** `shop.metafields["$app"].custom_css` is auto-fetched, sanitized, and injected.
+- **Countdown timer.** When a bundle has `endsAt`, the widget ticks live and hides on expiry.
+- **Variant dropdowns.** Products with multiple eligible variants render a `<select>`; switching live-updates the row price and bundle total.
+- **Mix-match picker modal.** Full modal with search, quantity stepper, progress bar, focus trap, and keyboard navigation.
+- **Out-of-stock handling.** Honours `widgetConfig.outOfStockBehavior` (`hide` vs `show_greyed_out`); hides the widget when the bundle is unfulfillable.
+- **A/B testing.** Reads the merchant's A/B config, buckets the visitor via a first-party cookie, applies Variant B overrides.
+- **Analytics.** Impression and add-to-cart events fire regardless of whether you override the cart.
 
 ## Styling
 
-Render happens inside a closed Shadow DOM. Override CSS custom properties on the host:
+Override any CSS custom property on the host element:
 
 ```html
 <lime-bundle
-  style="--lb-primary-color: #e91e63; --lb-radius: 16px;"
   shop-domain="..."
+  style="--lb-primary-color: #e91e63; --lb-radius: 16px;"
 ></lime-bundle>
 ```
 
-Merchant custom CSS from `/app/settings/custom-css` is auto-fetched and injected on mount.
+Full variable reference: [css-variables.md](./docs/css-variables.md).
+
+## Non-React framework snippets
+
+**Astro:**
+
+```astro
+<lime-bundle shop-domain="..." storefront-token={import.meta.env.PUBLIC_LIME_BUNDLES_TOKEN} />
+<script>
+  import "@lime-bundles/widget";
+</script>
+```
+
+**Vue 3.** Configure `app.config.compilerOptions.isCustomElement = (tag) => tag === "lime-bundle"` to silence the unknown-element warning.
 
-Full variable list: [css-variables.md](https://github.com/lime-app-dev/lime-bundles-app/blob/main/docs/headless/css-variables.md).
+**Svelte.** No configuration needed; use `on:lime-bundle:add-to-cart={handler}`.
 
 ## Bundle size
 
-`lime-bundle.js` (IIFE, gzipped) is <30 KB. No runtime framework dependency.
+IIFE build, gzipped: <30 KB. No runtime framework dependency.
 
-## Versioning
+## Version policy
 
-Major versions bump together with `@lime-bundles/core` and `@lime-bundles/react`.
+All three packages (`core`, `react`, `widget`) bump majors together. The v2.0.0 release closes full rendering parity with the admin preview.
 
 ## License
 
-MIT. See repo root.
+MIT.
 
-## Links
+## Support
 
-- [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)
+Merchant support and bug reports: email via the Lime Bundles listing on the Shopify App Store.