@lime-bundles/widget 0.2.0 → 2.0.0

package/README.md

@@ -0,0 +1,159 @@
+# @lime-bundles/widget
+
+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
+
+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>
+```
+
+## Paste-and-go
+
+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>
+<lime-bundle
+  shop-domain="my-shop.myshopify.com"
+  storefront-token="<YOUR_LIME_BUNDLES_TOKEN>"
+></lime-bundle>
+```
+
+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.
+
+## BYO cart
+
+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` | ✓ | `*.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** (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. Cancelable: `event.preventDefault()` suppresses the default checkout redirect.
+
+```ts
+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:loaded`
+
+Fired once the bundle(s) have been fetched and parsed.
+
+```ts
+event.detail: {
+  bundleCount: number;
+  bundleTypes: Array<"fixed" | "volume" | "mix_match">;
+}
+```
+
+### `lime-bundle:error`
+
+Fired if fetch or parse fails.
+
+```ts
+event.detail: { message: string; code: string }  // e.g. "LOAD_ERROR"
+```
+
+The widget renders its own inline fallback; listen for this event if you want to hide the parent or report to your own telemetry.
+
+## What the widget handles for you
+
+- **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
+
+Override any CSS custom property on the host element:
+
+```html
+<lime-bundle
+  shop-domain="..."
+  style="--lb-primary-color: #e91e63; --lb-radius: 16px;"
+></lime-bundle>
+```
+
+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.
+
+**Svelte.** No configuration needed; use `on:lime-bundle:add-to-cart={handler}`.
+
+## Bundle size
+
+IIFE build, gzipped: <30 KB. No runtime framework dependency.
+
+## Version policy
+
+All three packages (`core`, `react`, `widget`) bump majors together. The v2.0.0 release closes full rendering parity with the admin preview.
+
+## License
+
+MIT.
+
+## Support
+
+Merchant support and bug reports: email via the Lime Bundles listing on the Shopify App Store.