@pack/react 4.3.4 → 4.4.0

package/dist/index.d.ts

@@ -4,7 +4,9 @@ import { usePackContext } from "./pack/pack-context";
 import { useSiteSettings } from "./use-site-settings";
 import { useLocale } from "./use-locale";
 import { useOverlayScript } from "./use-overlay-script";
+import { usePlaybookCart } from "./use-playbook-cart";
 import { registerSection } from "./register-section";
 import { registerStorefrontSettingsSchema } from "./register-storefront-settings-schema";
-export { PackProvider, PreviewProvider, RenderSection, RenderSections, registerSection, registerStorefrontSettingsSchema, useLocale, useOverlayScript, usePackContext, useSections, useSiteSettings, };
+export { PackProvider, PreviewProvider, RenderSection, RenderSections, registerSection, registerStorefrontSettingsSchema, useLocale, useOverlayScript, usePackContext, usePlaybookCart, useSections, useSiteSettings, };
+export type { PlaybookCartAdd, PlaybookCartInput } from "./use-playbook-cart";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,aAAa,EACb,cAAc,EACd,WAAW,EACZ,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACpE,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AACzC,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AACxD,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,EAAE,gCAAgC,EAAE,MAAM,uCAAuC,CAAC;AAEzF,OAAO,EACL,YAAY,EACZ,eAAe,EACf,aAAa,EACb,cAAc,EACd,eAAe,EACf,gCAAgC,EAChC,SAAS,EACT,gBAAgB,EAChB,cAAc,EACd,WAAW,EACX,eAAe,GAChB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,aAAa,EACb,cAAc,EACd,WAAW,EACZ,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACpE,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AACzC,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AACxD,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,EAAE,gCAAgC,EAAE,MAAM,uCAAuC,CAAC;AAEzF,OAAO,EACL,YAAY,EACZ,eAAe,EACf,aAAa,EACb,cAAc,EACd,eAAe,EACf,gCAAgC,EAChC,SAAS,EACT,gBAAgB,EAChB,cAAc,EACd,eAAe,EACf,WAAW,EACX,eAAe,GAChB,CAAC;AAEF,YAAY,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/index.js

@@ -4,6 +4,7 @@ import { usePackContext } from "./pack/pack-context";
 import { useSiteSettings } from "./use-site-settings";
 import { useLocale } from "./use-locale";
 import { useOverlayScript } from "./use-overlay-script";
+import { usePlaybookCart } from "./use-playbook-cart";
 import { registerSection } from "./register-section";
 import { registerStorefrontSettingsSchema } from "./register-storefront-settings-schema";
-export { PackProvider, PreviewProvider, RenderSection, RenderSections, registerSection, registerStorefrontSettingsSchema, useLocale, useOverlayScript, usePackContext, useSections, useSiteSettings, };
+export { PackProvider, PreviewProvider, RenderSection, RenderSections, registerSection, registerStorefrontSettingsSchema, useLocale, useOverlayScript, usePackContext, usePlaybookCart, useSections, useSiteSettings, };

package/dist/use-playbook-cart.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Bridges a storefront's own cart to Playbook's collection-grid "Add to cart".
+ *
+ * WHY A BRIDGE AND NOT A DIRECT WRITE. Playbook's storefront SDK adds a line on
+ * a Liquid theme through Shopify's AJAX Cart API (`/cart/add.js`). Hydrogen has
+ * no such endpoint, and the one thing Playbook must not do is write the line
+ * behind the storefront's back: it could add it through the Storefront API, but
+ * a Hydrogen cart's UI is rendered from React state that no third-party script
+ * can reach, so the line would land in Shopify while the cart icon still read
+ * zero and the drawer never opened. The shopper would click again. A correct
+ * backend behind a frontend that looks broken is worse than an honest link to
+ * the product page, which is what Playbook falls back to when no bridge exists.
+ *
+ * So the storefront — the only code that CAN update its own cart UI — supplies
+ * the write, and Playbook calls it. Registering this also wins on Liquid, where
+ * Playbook prefers a registered bridge over its own event fan-out, because the
+ * store's real drawer always beats a simulated one.
+ *
+ * OPT-IN, ALWAYS. Nothing here runs unless a storefront calls this hook. It is
+ * a `window` global, and a package installed by 50+ storefronts must never
+ * assign one on their behalf.
+ *
+ *   const { linesAdd } = useCart();
+ *   usePlaybookCart(async ({ variantId, quantity }) => {
+ *     await linesAdd([{ merchandiseId: variantId, quantity }]);
+ *   });
+ *
+ * THE OTHER HALF OF THIS CONTRACT LIVES IN PLAYBOOK, not here, and nothing in
+ * this repo can verify it: `sdk/experience/src/cart-add.ts` in
+ * `packdigital/playbook` defines the global's name, decides whether the button
+ * renders at all (`canAddToCart`), and treats a rejection as the shopper-facing
+ * failure state. Read that file before changing the shape below.
+ */
+/**
+ * What Playbook passes to the bridge.
+ *
+ * Deliberately OPEN: Playbook owns this payload, and the bridge forwards every
+ * field it receives so a later addition there (a selling plan, line attributes)
+ * reaches the storefront without a release here.
+ */
+export interface PlaybookCartInput {
+    /** Numeric variant id as Playbook sends it; normalized to a GID before the
+     *  storefront's callback sees it. */
+    variantId: string;
+    quantity: number;
+    [key: string]: unknown;
+}
+/** The storefront's own add-to-cart. Resolve = added; throw = failed. */
+export type PlaybookCartAdd = (input: PlaybookCartInput) => Promise<unknown> | unknown;
+/**
+ * Accept either form and always hand the callback a variant GID. Playbook sends
+ * the legacy numeric id (its Liquid path needs that for `/cart/add.js`), which
+ * every Hydrogen cart API rejects.
+ *
+ * This is a globally-callable entry point, so it validates rather than coercing:
+ * an empty id would otherwise build the bare prefix `gid://shopify/…/`, and a
+ * PRODUCT gid would sail through as if it were a variant. Both fail far away
+ * from here, inside the cart mutation, with a message that doesn't name Playbook.
+ */
+export declare const toVariantGid: (variantId: string) => string;
+export declare const usePlaybookCart: (addToCart: PlaybookCartAdd | null | undefined) => void;
+//# sourceMappingURL=use-playbook-cart.d.ts.map

package/dist/use-playbook-cart.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-playbook-cart.d.ts","sourceRoot":"","sources":["../src/use-playbook-cart.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH;;;;;;GAMG;AACH,MAAM,WAAW,iBAAiB;IAChC;yCACqC;IACrC,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,yEAAyE;AACzE,MAAM,MAAM,eAAe,GAAG,CAC5B,KAAK,EAAE,iBAAiB,KACrB,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC;AAmBhC;;;;;;;;;GASG;AACH,eAAO,MAAM,YAAY,cAAe,MAAM,KAAG,MAahD,CAAC;AAYF,eAAO,MAAM,eAAe,cACf,eAAe,GAAG,IAAI,GAAG,SAAS,KAC5C,IAqDF,CAAC"}

package/dist/use-playbook-cart.js

@@ -0,0 +1,87 @@
+import { useEffect, useRef } from "react";
+/** Shopify variant GID prefix — the form every Hydrogen cart API expects. */
+const VARIANT_GID_PREFIX = "gid://shopify/ProductVariant/";
+/**
+ * Accept either form and always hand the callback a variant GID. Playbook sends
+ * the legacy numeric id (its Liquid path needs that for `/cart/add.js`), which
+ * every Hydrogen cart API rejects.
+ *
+ * This is a globally-callable entry point, so it validates rather than coercing:
+ * an empty id would otherwise build the bare prefix `gid://shopify/…/`, and a
+ * PRODUCT gid would sail through as if it were a variant. Both fail far away
+ * from here, inside the cart mutation, with a message that doesn't name Playbook.
+ */
+export const toVariantGid = (variantId) => {
+    const id = String(variantId ?? "").trim();
+    if (!id)
+        throw new Error("[playbook] add-to-cart called with no variantId");
+    if (id.startsWith("gid://")) {
+        if (!id.startsWith(VARIANT_GID_PREFIX)) {
+            throw new Error(`[playbook] expected a ProductVariant gid, got "${id}"`);
+        }
+        return id;
+    }
+    if (!/^\d+$/.test(id)) {
+        throw new Error(`[playbook] variantId must be numeric or a gid, got "${id}"`);
+    }
+    return `${VARIANT_GID_PREFIX}${id}`;
+};
+/** Quantity arrives from a third-party script; a cart mutation should never see
+ *  a fraction, a negative, or `NaN`. */
+const toQuantity = (quantity) => {
+    const n = Number(quantity);
+    if (!Number.isInteger(n) || n < 1) {
+        throw new Error(`[playbook] quantity must be a positive integer, got "${quantity}"`);
+    }
+    return n;
+};
+export const usePlaybookCart = (addToCart) => {
+    // The documented usage passes an INLINE arrow, so `addToCart` is a new
+    // identity every render. Keeping it in a ref means the global is registered
+    // once and the callback stays current, instead of the handler being torn down
+    // and reassigned on every render of the component that mounts the bridge.
+    const latest = useRef(addToCart);
+    useEffect(() => {
+        latest.current = addToCart;
+    }, [addToCart]);
+    const enabled = Boolean(addToCart);
+    useEffect(() => {
+        if (!enabled)
+            return;
+        const host = window;
+        if (host.playbookAddToCart) {
+            // Two bridges racing means one silently wins and the other's cart is
+            // never used — worth a word in dev, where a storefront author can act on
+            // it. Not an throw: the page still works, and the later mount wins
+            // consistently.
+            console.warn("[playbook] window.playbookAddToCart was already registered; the most recent usePlaybookCart wins.");
+        }
+        // `async` so a SYNCHRONOUS throw from the storefront's callback (or from
+        // validation above) reaches Playbook as a REJECTION. Playbook awaits this
+        // and renders the shopper a failure state; a sync throw would escape that
+        // path entirely and the button would sit there having done nothing.
+        const handler = async (input) => {
+            const add = latest.current;
+            if (!add)
+                return;
+            // Spread FIRST so any field Playbook adds later rides along untouched;
+            // only the two we normalize are overridden.
+            return add({
+                ...input,
+                variantId: toVariantGid(input.variantId),
+                quantity: toQuantity(input.quantity),
+            });
+        };
+        host.playbookAddToCart = handler;
+        return () => {
+            // Clear ONLY our own registration, by identity. React can mount the next
+            // instance before unmounting the previous one (a route transition, or
+            // StrictMode's double-invoke in dev), so an unconditional delete would
+            // remove the NEWER handler and leave the storefront with no bridge at
+            // all — the button silently degrading to navigation, on a store that had
+            // opted in.
+            if (host.playbookAddToCart === handler)
+                delete host.playbookAddToCart;
+        };
+    }, [enabled]);
+};

package/dist/version.js

@@ -1 +1 @@
-export const VERSION = "4.3.4";
+export const VERSION = "4.4.0";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@pack/react",
   "description": "React",
-  "version": "4.3.4",
+  "version": "4.4.0",
   "exports": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "engines": {