@best-bundles/bundle-ui 0.0.14 → 0.0.16

package/README.md

@@ -0,0 +1,158 @@
+# @best-bundles/bundle-ui
+
+Bundle Builder UI components and hooks for Shopify storefronts.
+
+## Install
+
+```bash
+npm install @best-bundles/bundle-ui lucide-react
+```
+
+Peer deps: `react`, `react-dom`, and `lucide-react`.
+
+## Hydrogen setup
+
+### 1) Create a cart adapter (passthrough to Hydrogen cart handlers)
+
+Create a small adapter that forwards Bundle Builder line changes to your Hydrogen cart.
+Adjust the cart UI open/close helpers to match your storefront.
+
+`app/lib/bundleCartAdapter.tsx`
+
+```tsx
+import { useMemo } from "react";
+import type { BundleCartAdapter } from "@best-bundles/bundle-ui";
+import { useCart } from "@shopify/hydrogen";
+
+export function useHydrogenBundleCartAdapter(): BundleCartAdapter {
+  const { linesAdd, linesUpdate, linesRemove, openCart, closeCart } = useCart();
+
+  return useMemo(
+    () => ({
+      async linesAdd(lines) {
+        await linesAdd(lines);
+      },
+      async linesUpdate(lines) {
+        await linesUpdate(lines);
+      },
+      async linesRemove(lineIds) {
+        await linesRemove(lineIds);
+      },
+      openCartUI() {
+        openCart?.();
+      },
+      closeCartUI() {
+        closeCart?.();
+      },
+    }),
+    [linesAdd, linesUpdate, linesRemove, openCart, closeCart],
+  );
+}
+```
+
+If your Hydrogen setup uses `@shopify/hydrogen-react`, import `useCart` from there instead.
+
+### 2) Wrap the app in `root.tsx` with `BundleProvider`
+
+Place the provider inside your Hydrogen `CartProvider` so `useCart()` is available.
+
+```tsx
+import { BundleProvider } from "@best-bundles/bundle-ui";
+import { useHydrogenBundleCartAdapter } from "~/lib/bundleCartAdapter";
+
+export default function App() {
+  const { env } = useLoaderData<typeof loader>();
+  const cartAdapter = useHydrogenBundleCartAdapter();
+
+  return (
+    <CartProvider>
+      <BundleProvider
+        apiBaseUrl={env.BEST_BUNDLES_API_BASE_URL}
+        shop={env.PUBLIC_STORE_DOMAIN}
+        cartAdapter={cartAdapter}
+      >
+        <Layout>
+          <Outlet />
+        </Layout>
+      </BundleProvider>
+    </CartProvider>
+  );
+}
+```
+
+Required props:
+- `apiBaseUrl`: Base URL of the Best Bundles app (used for config + analytics).
+- `shop`: Your shop domain (used to fetch the bundle config).
+- `cartAdapter`: The passthrough adapter from step 1.
+
+Optional props:
+- `configHandle`: Defaults to `"default"`.
+- `analyticsEndpoint`: Defaults to `${apiBaseUrl}/api/public/bundle-analytics`.
+
+### 3) Mount the drawer UI in `Layout.tsx`
+
+Render the drawer once in your layout so it can be opened anywhere.
+
+```tsx
+import { BundleBuilderDrawer, BundleButton } from "@best-bundles/bundle-ui";
+
+export function Layout({ children }: { children: React.ReactNode }) {
+  return (
+    <>
+      <header>
+        <BundleButton>Build a bundle</BundleButton>
+      </header>
+
+      {children}
+
+      <BundleBuilderDrawer />
+    </>
+  );
+}
+```
+
+## `useBundleBuilder` hook
+
+The hook exposes drawer state, selections, and submit actions. It must be used
+inside `BundleProvider`.
+
+```tsx
+import { useBundleBuilder } from "@best-bundles/bundle-ui";
+
+export function CustomBundleTrigger() {
+  const { toggle, canSubmit, bundleSize, minRequired } = useBundleBuilder();
+
+  return (
+    <button type="button" onClick={toggle} disabled={!canSubmit && bundleSize < minRequired}>
+      Build a bundle
+    </button>
+  );
+}
+```
+
+Key fields include:
+- `isOpen`, `open`, `close`, `toggle`
+- `loading`, `submitting`, `error`
+- `config`, `eligibleVariants`
+- `selections`, `selectionOrder`, `setQuantity`, `clearSelections`
+- `bundleSize`, `minRequired`, `canSubmit`, `submit`
+
+## Bundle cart adapter shape
+
+If you need to build your own adapter, implement `BundleCartAdapter`:
+
+```ts
+export type BundleCartAdapter = {
+  linesAdd(lines: Array<{
+    merchandiseId: string;
+    quantity: number;
+    attributes?: { key: string; value: string }[];
+  }>): Promise<void> | void;
+  linesUpdate?(lines: Array<{ id: string; quantity: number; attributes?: { key: string; value: string }[] }>): Promise<void> | void;
+  linesRemove?(lineIds: string[]): Promise<void> | void;
+  openCartUI?(): void;
+  closeCartUI?(): void;
+};
+```
+
+For Liquid storefronts, `createLiquidCartAdapter()` is available.

package/dist/index.js

@@ -1235,7 +1235,7 @@ function Hn(i) {
             /* @__PURE__ */ h("button", { type: "button", onClick: re, disabled: !J, className: u.cta, children: r ? "Adding…" : b > 0 ? `Add ${b} more product${b === 1 ? "" : "s"}` : "Add to Basket" }),
             /* @__PURE__ */ R("div", { className: u.poweredBy, children: [
               "powered by ",
-              /* @__PURE__ */ h("a", { href: "https://best-bundles.onrender.com", target: "_blank", rel: "noopener noreferrer", children: " BestBundles" })
+              /* @__PURE__ */ h("a", { href: "https://apps.shopify.com/best-bundles", target: "_blank", rel: "noopener noreferrer", children: " BestBundles" })
             ] })
           ] })
         ] })