@lime-bundles/react 0.2.0 → 2.0.0

package/docs/css-variables.md

@@ -0,0 +1,158 @@
+# CSS variables reference
+
+Lime Bundles components style themselves with CSS custom properties prefixed `--lb-*`. Override any of them on the component host (or any ancestor) to brand-match the widget to your storefront.
+
+Every variable has a merchant-configurable default set in the Lime Bundles admin editor. The canonical source is [`app/lib/bundle-types.ts`](../../app/lib/bundle-types.ts) (`WidgetConfigSchema`) and the stylesheets in [`extensions/bundle-theme/assets/`](../../extensions/bundle-theme/assets).
+
+## How to override
+
+### React components
+
+Set variables on any wrapping element:
+
+```tsx
+<div style={{ "--lb-primary-color": "#e91e63", "--lb-radius": "16px" } as React.CSSProperties}>
+  <FixedBundle ... />
+</div>
+```
+
+### Web component
+
+Variables apply to the shadow-DOM host, so set them directly on `<lime-bundle>`:
+
+```html
+<lime-bundle
+  shop-domain="..."
+  style="--lb-primary-color: #e91e63; --lb-radius: 16px;"
+></lime-bundle>
+```
+
+### Merchant custom CSS
+
+Merchants can set these (and any other CSS) via Lime Bundles admin → Settings → Custom CSS. That CSS ships with the widget automatically. No code change on your side.
+
+## Layout
+
+| Variable | Default | What it styles |
+|---|---|---|
+| `--lb-bg` | `#FFFFFF` | Widget background. |
+| `--lb-text` | `#1A1A1A` | Base body text colour. |
+| `--lb-border` | `#E5E5E5` | Outer card border colour. |
+| `--lb-border-width` | `1px` | Outer card border width. |
+| `--lb-radius` | `12px` | Outer card corner radius. |
+
+## Header
+
+| Variable | Default | What it styles |
+|---|---|---|
+| `--lb-header-start` | `#C62828` | Gradient start (ignored when header style is `solid`). |
+| `--lb-header-end` | `#AD1457` | Gradient end. |
+| `--lb-header-bg` | *derived* | Final header background. Emitted as a solid colour or a gradient depending on the merchant's header-style pick. |
+| `--lb-header-text` | `#FFFFFF` | Header text colour. |
+| `--lb-countdown-bg` | `#FFF0F3` | Countdown badge background inside the header. |
+| `--lb-countdown-text` | `#C62828` | Countdown badge text colour. |
+
+## Save badge
+
+| Variable | Default | What it styles |
+|---|---|---|
+| `--lb-save-badge-bg` | `#FFFFFF` | Background. |
+| `--lb-save-badge-text` | `#AD1457` | Text colour. |
+| `--lb-save-badge-border-color` | `#FFFFFF` | Border colour. |
+| `--lb-save-badge-border-width` | `0px` | Border width. |
+| `--lb-save-badge-radius` | `8px` | Corner radius. |
+
+## Product list
+
+| Variable | Default | What it styles |
+|---|---|---|
+| `--lb-image-border-color` | `#E5E5E5` | Product thumbnail border. |
+| `--lb-image-border-width` | `0px` | Product thumbnail border width. |
+| `--lb-image-border-radius` | `8px` | Product thumbnail corner radius. |
+| `--lb-variant-border-color` | `#E5E5E5` | Variant selector border. |
+| `--lb-variant-border-width` | `1px` | Variant selector border width. |
+| `--lb-variant-radius` | `8px` | Variant selector corner radius. |
+| `--lb-variant-chevron` | *derived SVG data URL* | Chevron icon shown in the variant dropdown. Auto-coloured to match `--lb-variant-border-color`. |
+| `--lb-qty-badge-bg` | `#1A1A1A` | Quantity badge background. |
+| `--lb-qty-badge-color` | `#FFFFFF` | Quantity badge text. |
+| `--lb-qty-badge-display` | `flex` (shown) / `none` (hidden) | Toggle; merchant config controls this. |
+| `--lb-product-price-display` | `block` (shown) / `none` (hidden) | Toggle. |
+| `--lb-product-compare-display` | `inline` (shown) / `none` (hidden) | Toggle. |
+
+## CTA button
+
+| Variable | Default | What it styles |
+|---|---|---|
+| `--lb-primary-color` | `#1A1A1A` | Button background. |
+| `--lb-btn-text` | `#FFFFFF` | Button text. |
+| `--lb-cta-border-color` | `#1A1A1A` | Border colour. |
+| `--lb-cta-border-width` | `0px` | Border width. |
+| `--lb-cta-radius` | `12px` | Corner radius. |
+
+## Savings bar
+
+| Variable | Default | What it styles |
+|---|---|---|
+| `--lb-savings-bar-bg` | `#EDFBF1` | Bar background. |
+| `--lb-savings-bar-text` | `#2DB554` | Bar text colour. |
+| `--lb-savings-bar-border-color` | `#2DB554` | Border colour. |
+| `--lb-savings-bar-border-width` | `0px` | Border width. |
+| `--lb-savings-bar-radius` | `8px` | Corner radius. |
+
+## Volume tier cards
+
+| Variable | Default | What it styles |
+|---|---|---|
+| `--lb-tier-border-color` | `#E5E5E5` | Tier card border. |
+| `--lb-tier-border-width` | `1px` | Tier card border width. |
+| `--lb-tier-radius` | `12px` | Tier card corner radius. |
+| `--lb-tier-selected-border-color` | `#1A1A1A` | Border colour for the active tier. |
+| `--lb-tier-selected-border-width` | `2px` | Border width for the active tier. |
+
+## "Most popular" badge (volume bundle)
+
+| Variable | Default | What it styles |
+|---|---|---|
+| `--lb-popular-badge-bg` | `#1A1A1A` | Badge background. |
+| `--lb-popular-badge-text` | `#FFFFFF` | Badge text. |
+| `--lb-popular-badge-border-color` | `#1A1A1A` | Badge border colour. |
+| `--lb-popular-badge-border-width` | `0px` | Badge border width. |
+| `--lb-popular-badge-radius` | `12px` | Badge corner radius. |
+
+## Mix-and-match picker modal
+
+| Variable | Default | What it styles |
+|---|---|---|
+| `--lb-picker-bg` | `#FFFFFF` | Modal background. |
+| `--lb-picker-text` | `#1A1A1A` | Modal text colour. |
+| `--lb-picker-border-color` | `#E5E5E5` | Modal outer border. |
+| `--lb-picker-border-width` | `0px` | Modal outer border width. |
+| `--lb-picker-radius` | `16px` | Modal corner radius. |
+| `--lb-picker-search-border-color` | `#E5E5E5` | Search input border. |
+| `--lb-picker-search-border-width` | `1px` | Search input border width. |
+| `--lb-picker-search-radius` | `8px` | Search input corner radius. |
+| `--lb-picker-product-border-color` | `#E5E5E5` | Product thumbnail border. |
+| `--lb-picker-product-border-width` | `0px` | Product thumbnail border width. |
+| `--lb-picker-product-radius` | `8px` | Product thumbnail corner radius. |
+| `--lb-picker-qty-badge-bg` | `#1A1A1A` | Picker quantity-badge background. |
+| `--lb-picker-qty-badge-color` | `#FFFFFF` | Picker quantity-badge text. |
+| `--lb-picker-qty-badge-display` | `flex` (shown) / `none` (hidden) | Toggle; picker quantity badge visibility. |
+| `--lb-picker-variant-border-color` | `#1A1A1A` | Variant select border. |
+| `--lb-picker-variant-border-width` | `1px` | Variant select border width. |
+| `--lb-picker-variant-radius` | `8px` | Variant select corner radius. |
+| `--lb-picker-variant-chevron` | *derived SVG data URL* | Chevron icon on the picker's variant dropdown. Auto-coloured to match `--lb-picker-variant-border-color`. |
+| `--lb-picker-add-bg` | `#1A1A1A` | Add-to-bundle button background. |
+| `--lb-picker-add-label` | `#FFFFFF` | Add-to-bundle button text. |
+| `--lb-picker-add-border-color` | `#1A1A1A` | Add-to-bundle button border colour. |
+| `--lb-picker-add-border-width` | `0px` | Add-to-bundle button border width. |
+| `--lb-picker-add-radius` | `8px` | Add-to-bundle button corner radius. |
+
+## Internal variables (don't override)
+
+These exist for internal composition and are not merchant-configurable. The CSS in `extensions/bundle-theme/assets/bundle-base.css` defines them on `.lb-bundle-widget` with fixed values.
+
+- `--lb-text-muted`: muted body text colour.
+- `--lb-thumbnail-bg`: placeholder background behind images.
+- `--lb-widget-pad`: internal padding token.
+- `--lb-progress-color`: volume progress bar accent.
+

package/docs/hydrogen.md

@@ -0,0 +1,185 @@
+# Hydrogen
+
+> **Before you start:** most Hydrogen merchants don't need this guide. The [web component](./web-component.md) (`<lime-bundle>`) works inside any Hydrogen page and handles cart and checkout via Shopify's tokenless Storefront Cart API. Paste the snippet from `/app/settings/headless` into your product route and you're done. Reach for this guide only when you want React components (`<FixedBundle>`) that thread cart mutations through Hydrogen's `useCart` state.
+
+SSR-first integration: fetch the bundle server-side in a route loader, hydrate a `<FixedBundle>` (or volume / mix-match) with Hydrogen's `useCart` for the add-to-cart callback.
+
+## Install
+
+```bash
+npm install @lime-bundles/react @lime-bundles/core
+```
+
+`@lime-bundles/core` is a transitive dependency. Installing it explicitly lets you call `fetchBundleData` from a loader without pulling React.
+
+## Environment
+
+Open `/app/settings/headless` in your Lime Bundles admin, click **Generate token**, then append the value to your Hydrogen project's `.env`:
+
+```bash
+# Existing values you already had: keep these as-is
+PUBLIC_STORE_DOMAIN=my-shop.myshopify.com
+PUBLIC_STOREFRONT_API_TOKEN=<your existing Shopify Storefront token>
+
+# New: Lime Bundles' own Storefront token
+PUBLIC_LIME_BUNDLES_TOKEN=<paste the generated token>
+```
+
+The variable is intentionally namespaced so it doesn't collide with the `PUBLIC_STOREFRONT_API_TOKEN` that Shopify's Headless app issues for your primary storefront. Lime Bundles uses its own Storefront Access Token, scoped to bundle metaobjects and product listings only.
+
+Lime Bundles creates the token for you via Shopify's Admin API. No custom-app configuration needed (Shopify deprecated that flow on 2026-01-01). The token carries the read-only scopes `unauthenticated_read_metaobjects` and `unauthenticated_read_product_listings` and nothing else. To rotate, click **Regenerate** on the same page. It revokes the current token and issues a new one atomically.
+
+## Getting a bundle GID
+
+Each bundle you create in the Lime Bundles admin has a Shopify Metaobject GID (`gid://shopify/Metaobject/<numericId>`). You have two ways to use it:
+
+- **Pin one bundle**: hardcode the GID. Find it in the admin at `/app/bundles/<id>/analytics` (URL), or by inspecting a bundle's API response.
+- **Render every bundle configured against a product**: skip the explicit GID and use `fetchBundlesForProduct({ productHandle })` instead. Hand it the product handle from your loader; it returns every active bundle the merchant attached to that product. See the [React guide](./react-nextjs.md#auto-fetch-every-bundle-for-a-product) for the client-side `useBundlesForProduct` hook.
+
+Both patterns are shown below.
+
+## Fetch a specific bundle in a loader
+
+Hydrogen runs on Oxygen, where `process.env` is not available in the browser. Surface the values the route component needs through the loader. Oxygen injects environment variables as `context.env`:
+
+```tsx
+// app/routes/products.$handle.tsx
+import { fetchBundleData } from "@lime-bundles/react";
+import { useLoaderData } from "@shopify/remix-oxygen";
+import type { LoaderFunctionArgs } from "@shopify/remix-oxygen";
+
+export async function loader({ request, context }: LoaderFunctionArgs) {
+  const shopDomain = context.env.PUBLIC_STORE_DOMAIN;
+  const storefrontAccessToken = context.env.PUBLIC_LIME_BUNDLES_TOKEN;
+  const bundleGid = "gid://shopify/Metaobject/123456789";
+
+  const bundle = await fetchBundleData({
+    shopDomain,
+    storefrontAccessToken,
+    bundleGid,
+    // Required on SSR. Without it Shopify may return 430 Security Rejection
+    // for server-originated traffic on a private token. `x-forwarded-for` is
+    // set by Oxygen and most other hosts; take the first IP in the list.
+    buyerIp:
+      request.headers.get("x-forwarded-for")?.split(",")[0].trim() ?? undefined,
+  });
+
+  return { bundle, shopDomain, storefrontAccessToken, bundleGid };
+}
+```
+
+`fetchBundleData` throws `StorefrontApiError` on HTTP / GraphQL failure and `BundleParseError` when the metaobject is missing, inactive, not yet scheduled, or expired. Hydrogen surfaces thrown loader errors via its standard `ErrorBoundary`.
+
+## Fetch every bundle for a product (auto-detect)
+
+If you'd rather not pin a GID, use `fetchBundlesForProduct` in the loader. Pass it the product handle from route params and it returns every active bundle the merchant attached to that product (inactive, draft, not-yet-started, and expired bundles are filtered out):
+
+```tsx
+// app/routes/products.$handle.tsx
+import { fetchBundlesForProduct } from "@lime-bundles/react";
+import type { LoaderFunctionArgs } from "@shopify/remix-oxygen";
+
+export async function loader({ request, params, context }: LoaderFunctionArgs) {
+  const shopDomain = context.env.PUBLIC_STORE_DOMAIN;
+  const storefrontAccessToken = context.env.PUBLIC_LIME_BUNDLES_TOKEN;
+
+  const bundles = await fetchBundlesForProduct({
+    shopDomain,
+    storefrontAccessToken,
+    productHandle: params.handle!,
+    buyerIp:
+      request.headers.get("x-forwarded-for")?.split(",")[0].trim() ?? undefined,
+  });
+
+  return { bundles, shopDomain, storefrontAccessToken };
+}
+```
+
+The route component then maps the list and renders the right component per `bundleType` (see the [React guide](./react-nextjs.md#auto-fetch-every-bundle-for-a-product)). Prefer this shape when the product has more than one bundle configured or when you don't want to redeploy each time a merchant swaps bundles.
+
+For a purely client-side version (no loader), use the `useBundlesForProduct` hook in a component.
+
+## Render and wire cart
+
+```tsx
+// Same file: route component
+import { FixedBundle } from "@lime-bundles/react";
+import { useCart } from "@shopify/hydrogen-react";
+
+export default function ProductRoute() {
+  const { shopDomain, storefrontAccessToken, bundleGid } =
+    useLoaderData<typeof loader>();
+  const { linesAdd } = useCart();
+
+  return (
+    <FixedBundle
+      shopDomain={shopDomain}
+      storefrontAccessToken={storefrontAccessToken}
+      bundleGid={bundleGid}
+      onAddToCart={async (lines) => {
+        await linesAdd(lines);
+      }}
+      onError={(err) => console.error("Bundle error", err)}
+    />
+  );
+}
+```
+
+The component fetches the bundle client-side via `useBundleData` on mount. Server-side prefetching in the loader warms Shopify's CDN cache so the client-side fetch returns instantly. If you want to avoid the duplicate fetch entirely, pass the `bundle` prop from the loader into a client component that renders directly without the Lime Bundles component. See [React guide](./react-nextjs.md#ssr-without-refetch) for that pattern.
+
+## The cart contract
+
+`onAddToCart` receives a Hydrogen-compatible `CartLineInput[]`:
+
+```ts
+type CartLineInput = {
+  merchandiseId: string;       // variant GID
+  quantity: number;
+  attributes: Array<{ key: string; value: string }>;
+};
+```
+
+The `attributes` array always includes `{ key: "_lime_bundle_gid", value: <bundle GID> }`. **Do not strip this.** The `orders/create` webhook relies on it for purchase attribution. Hydrogen's `cart.linesAdd` preserves custom attributes through checkout by default.
+
+## Worked example: Volume bundle
+
+```tsx
+import { VolumeBundle } from "@lime-bundles/react";
+
+<VolumeBundle
+  shopDomain={SHOP_DOMAIN}
+  storefrontAccessToken={TOKEN}
+  bundleGid="gid://shopify/Metaobject/42"
+  onAddToCart={async (lines) => {
+    await linesAdd(lines);
+  }}
+/>
+```
+
+The component renders tier cards, auto-selects the configured default tier, and calls `onAddToCart` with the chosen tier's merchandise and quantity.
+
+## Styling and merchant widget config
+
+The React SDK does **not** automatically apply the widget styles the merchant set in the admin editor. That's deliberate. If you chose `@lime-bundles/react` on Hydrogen you likely want full control over the look so bundles match your storefront's design system.
+
+Every `ParsedBundle` that `fetchBundleData` resolves to exposes the merchant's full config as `bundle.widgetConfig`. Read any field you want from it:
+
+```tsx
+<button style={{ background: bundle.widgetConfig.cta.primaryColor }}>
+  {bundle.widgetConfig.cta.ctaText}
+</button>
+```
+
+Want drop-in parity with the admin preview instead? Swap to the [web component](./web-component.md): it honours `widgetConfig` end-to-end without any wiring on your side.
+
+Full field list in [`packages/core/src/bundle/types.ts`](../../packages/core/src/bundle/types.ts). Helpers `WIDGET_CONFIG_DEFAULTS`, `mergeWidgetConfig`, `flattenWidgetConfig`, and `applyWidgetConfigVars` are exported from `@lime-bundles/core` if you want to apply the CSS custom properties to your own DOM.
+
+## What's NOT your job
+
+- **Purchase attribution.** The Lime Bundles `orders/create` webhook scans every line item's `_lime_bundle_gid` attribute and records a `bundle_purchased` AnalyticsEvent. Don't add client-side `checkout_completed` tracking; it double-counts.
+- **Custom CSS.** If merchants configure custom CSS in `/app/settings/custom-css`, `useBundleData` auto-fetches and injects a scoped `<style>` tag. No action needed.
+
+## Next steps
+
+- [CSS variables reference](./css-variables.md): brand-match the widget to your theme.
+- [Web component guide](./web-component.md): fallback for sections of the site that aren't React-controlled.