@lime-bundles/widget 0.1.1 → 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)