@tapcart/mobile-components 0.14.6 → 0.15.1

package/dist/components/hooks/use-search-analytics-open-product.d.ts

@@ -0,0 +1,123 @@
+interface SearchAnalyticsProduct {
+    id?: string;
+    objectID?: string;
+    variants?: Array<{
+        id?: string;
+    } | undefined | null>;
+}
+interface EmitProductInteractionPayload {
+    client: unknown;
+    surface: string;
+    product: {
+        productId?: string;
+        variantId?: string;
+        objectId?: string;
+        position?: number;
+    };
+}
+interface OpenProductProps {
+    productId?: string;
+    variantId?: string;
+    [key: string]: unknown;
+}
+interface UseSearchAnalyticsOpenProductParams {
+    products?: Array<SearchAnalyticsProduct | undefined | null>;
+    searchClient?: unknown;
+    emitProductClick?: (payload: EmitProductInteractionPayload) => void;
+    action?: (name: string, params?: unknown) => void;
+    surface?: string;
+}
+/**
+ * Returns a stable `openProduct` handler that opens the product AND emits a
+ * search-analytics click, looking up the clicked product's Algolia `objectID`
+ * and 1-based position from the current results.
+ *
+ * Provider-agnostic: `emitProductClick` reads attribution from whatever search
+ * client is active, so this same wiring works for every search provider. The
+ * click analytics no-op when the grid isn't search-backed (`searchClient`
+ * falsy) or the emitter isn't injected, so non-search grids stay clean.
+ *
+ * Centralizes the wiring shared by every search-backed grid block
+ * (CollectionProductGrid, ProductGrid, TabbedProductGrid, the product
+ * carousels, ...) so there's one implementation to maintain. The results are
+ * held in a ref so the returned callback keeps a stable identity (preserving
+ * a memoized ProductCard) while still reading the latest list on click.
+ */
+export declare function useSearchAnalyticsOpenProduct({ products, searchClient, emitProductClick, action, surface, }: UseSearchAnalyticsOpenProductParams): (props: OpenProductProps) => void;
+interface AddToCartProps {
+    lineItems?: Array<{
+        variantId?: string;
+        quantity?: number;
+    } | undefined | null>;
+    [key: string]: unknown;
+}
+interface UseSearchAnalyticsAddToCartParams {
+    products?: Array<SearchAnalyticsProduct | undefined | null>;
+    searchClient?: unknown;
+    emitProductConversion?: (payload: EmitProductInteractionPayload) => void;
+    action?: (name: string, params?: unknown) => void | Promise<unknown>;
+    surface?: string;
+}
+/**
+ * Sibling of `useSearchAnalyticsOpenProduct` for the add-to-cart path. Returns a
+ * stable `addToCart` handler that adds the item AND emits a search-analytics
+ * `add_to_cart` conversion, attributed to the originating search via the
+ * product's Algolia `objectID` + the active client's attribution.
+ *
+ * Unlike open-product, ProductCard's `addToCart` receives a line-item shape
+ * (`{ lineItems: [{ variantId }] }`) with no productId, so the results lookup
+ * matches on the added variant. Same ref-based stability as the sibling hook.
+ *
+ * The conversion is emitted only AFTER the add succeeds — `cart/add` is awaited,
+ * so a failed add (rejection) never counts as a conversion. This matches the
+ * quick-add drawer's on-success semantics (`useSearchAnalyticsConversionEmit`),
+ * which the drawer fires from its own add's `onSuccess`. The attribution target
+ * is captured from the results BEFORE the await so a list change mid-add can't
+ * misattribute. Awaiting a non-promise `action` (e.g. in tests) resolves
+ * immediately and still emits, so the conversion is never silently dropped.
+ *
+ * No-op (the item is still added) when the grid isn't search-backed
+ * (`searchClient` falsy), the emitter isn't injected, or the added variant
+ * isn't in the current results — without a matched hit there's no `objectID` to
+ * attribute, so we skip the emit rather than send a provider-less event.
+ */
+export declare function useSearchAnalyticsAddToCart({ products, searchClient, emitProductConversion, action, surface, }: UseSearchAnalyticsAddToCartParams): (props: AddToCartProps) => Promise<void>;
+/**
+ * Emit-only sibling of `useSearchAnalyticsAddToCart` for the quick-add drawer
+ * path. Multi-variant products open the quick-add drawer (rendered at app-layout
+ * level, OUTSIDE the page's SearchClientProvider), which performs its own
+ * `actions.addToCart`. So the drawer can't read the search context or call the
+ * combined add-and-emit handler without double-adding. This returns a stable
+ * `emitAddToCartConversion(variantId)` the drawer invokes on add success to emit
+ * the `add_to_cart` conversion only — attributed via the originating result's
+ * Algolia `objectID` + 1-based position, no cart mutation. No-ops when the grid
+ * isn't search-backed (`searchClient` falsy), the emitter isn't injected, the
+ * variant is missing, or the variant isn't found in the current results.
+ */
+export declare function useSearchAnalyticsConversionEmit({ products, searchClient, emitProductConversion, surface, }: UseSearchAnalyticsAddToCartParams): (variantId?: string) => void;
+interface UseSearchAnalyticsImpressionParams {
+    searchClient?: unknown;
+    emitProductImpression?: (payload: EmitProductInteractionPayload) => void;
+    surface?: string;
+    /**
+     * Whether search-analytics is enabled (the `app-studio-search-analytics`
+     * flag). Required to gate setup: `emitProductImpression` is a truthy no-op
+     * when the flag is off, so without this the IntersectionObserver would still
+     * be constructed per-card on every search-backed grid. Defaults on for
+     * backward compatibility with callers that don't pass it yet.
+     */
+    enabled?: boolean;
+}
+/**
+ * Returns an `onImpression(product)` callback for ProductCard to fire when a
+ * result first scrolls into view, emitting a search-analytics `impression`
+ * (Algolia `viewedObjectIDs` — objectID only, no position). Dedupes so each
+ * product emits at most once per session, even across virtualized remounts.
+ *
+ * Returns `undefined` when the grid isn't search-backed or no emitter is
+ * injected, so ProductCard skips setting up an IntersectionObserver entirely on
+ * non-search surfaces.
+ */
+export declare function useSearchAnalyticsImpression({ searchClient, emitProductImpression, surface, enabled, }: UseSearchAnalyticsImpressionParams): ((product: SearchAnalyticsProduct | undefined | null) => void) | undefined;
+export {};
+//# sourceMappingURL=use-search-analytics-open-product.d.ts.map

package/dist/components/hooks/use-search-analytics-open-product.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-search-analytics-open-product.d.ts","sourceRoot":"","sources":["../../../components/hooks/use-search-analytics-open-product.ts"],"names":[],"mappings":"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"}

package/dist/components/hooks/use-search-analytics-open-product.js

@@ -0,0 +1,191 @@
+"use client";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+import React from "react";
+import { getIdFromGid } from "../../lib/utils";
+/**
+ * Returns a stable `openProduct` handler that opens the product AND emits a
+ * search-analytics click, looking up the clicked product's Algolia `objectID`
+ * and 1-based position from the current results.
+ *
+ * Provider-agnostic: `emitProductClick` reads attribution from whatever search
+ * client is active, so this same wiring works for every search provider. The
+ * click analytics no-op when the grid isn't search-backed (`searchClient`
+ * falsy) or the emitter isn't injected, so non-search grids stay clean.
+ *
+ * Centralizes the wiring shared by every search-backed grid block
+ * (CollectionProductGrid, ProductGrid, TabbedProductGrid, the product
+ * carousels, ...) so there's one implementation to maintain. The results are
+ * held in a ref so the returned callback keeps a stable identity (preserving
+ * a memoized ProductCard) while still reading the latest list on click.
+ */
+export function useSearchAnalyticsOpenProduct({ products, searchClient, emitProductClick, action, surface = "collection", }) {
+    const productsRef = React.useRef(products);
+    productsRef.current = products;
+    // Hold `action` in a ref and read the latest at fire time so the returned
+    // callback stays a stable reference regardless of whether `Tapcart.action`
+    // is stable across renders — otherwise an unstable `action` would rebuild it
+    // every render and re-render every memoized ProductCard, defeating the whole
+    // point of this hook. Mirrors useSearchAnalyticsEmitter.
+    const actionRef = React.useRef(action);
+    actionRef.current = action;
+    return React.useCallback((props) => {
+        const action = actionRef.current;
+        action === null || action === void 0 ? void 0 : action("trigger/haptic");
+        action === null || action === void 0 ? void 0 : action("product/open", props);
+        if (!searchClient || !emitProductClick)
+            return;
+        const list = productsRef.current || [];
+        const index = list.findIndex((item) => getIdFromGid(item === null || item === void 0 ? void 0 : item.id) === (props === null || props === void 0 ? void 0 : props.productId));
+        const hit = list[index];
+        emitProductClick({
+            client: searchClient,
+            surface,
+            product: {
+                productId: props === null || props === void 0 ? void 0 : props.productId,
+                variantId: props === null || props === void 0 ? void 0 : props.variantId,
+                objectId: hit === null || hit === void 0 ? void 0 : hit.objectID,
+                position: index >= 0 ? index + 1 : undefined,
+            },
+        });
+    }, [searchClient, emitProductClick, surface]);
+}
+/**
+ * Sibling of `useSearchAnalyticsOpenProduct` for the add-to-cart path. Returns a
+ * stable `addToCart` handler that adds the item AND emits a search-analytics
+ * `add_to_cart` conversion, attributed to the originating search via the
+ * product's Algolia `objectID` + the active client's attribution.
+ *
+ * Unlike open-product, ProductCard's `addToCart` receives a line-item shape
+ * (`{ lineItems: [{ variantId }] }`) with no productId, so the results lookup
+ * matches on the added variant. Same ref-based stability as the sibling hook.
+ *
+ * The conversion is emitted only AFTER the add succeeds — `cart/add` is awaited,
+ * so a failed add (rejection) never counts as a conversion. This matches the
+ * quick-add drawer's on-success semantics (`useSearchAnalyticsConversionEmit`),
+ * which the drawer fires from its own add's `onSuccess`. The attribution target
+ * is captured from the results BEFORE the await so a list change mid-add can't
+ * misattribute. Awaiting a non-promise `action` (e.g. in tests) resolves
+ * immediately and still emits, so the conversion is never silently dropped.
+ *
+ * No-op (the item is still added) when the grid isn't search-backed
+ * (`searchClient` falsy), the emitter isn't injected, or the added variant
+ * isn't in the current results — without a matched hit there's no `objectID` to
+ * attribute, so we skip the emit rather than send a provider-less event.
+ */
+export function useSearchAnalyticsAddToCart({ products, searchClient, emitProductConversion, action, surface = "collection", }) {
+    const productsRef = React.useRef(products);
+    productsRef.current = products;
+    const actionRef = React.useRef(action);
+    actionRef.current = action;
+    return React.useCallback((props) => __awaiter(this, void 0, void 0, function* () {
+        var _a, _b;
+        const action = actionRef.current;
+        action === null || action === void 0 ? void 0 : action("trigger/haptic");
+        // Not search-backed (or no emitter): just add — nothing to attribute.
+        if (!searchClient || !emitProductConversion) {
+            action === null || action === void 0 ? void 0 : action("cart/add", props);
+            return;
+        }
+        // Resolve the attribution target from the CURRENT results up front, so a
+        // list change while the add is in flight can't misattribute the emit.
+        const variantId = (_b = (_a = props === null || props === void 0 ? void 0 : props.lineItems) === null || _a === void 0 ? void 0 : _a[0]) === null || _b === void 0 ? void 0 : _b.variantId;
+        const list = productsRef.current || [];
+        const index = variantId
+            ? list.findIndex((item) => { var _a; return (_a = item === null || item === void 0 ? void 0 : item.variants) === null || _a === void 0 ? void 0 : _a.some((v) => getIdFromGid(v === null || v === void 0 ? void 0 : v.id) === variantId); })
+            : -1;
+        const hit = index >= 0 ? list[index] : undefined;
+        // Emit only on a successful add (see JSDoc): a rejected cart/add skips it.
+        try {
+            yield (action === null || action === void 0 ? void 0 : action("cart/add", props));
+        }
+        catch (_c) {
+            return;
+        }
+        // No matched result → no objectID to attribute; skip.
+        if (!variantId || index < 0)
+            return;
+        emitProductConversion({
+            client: searchClient,
+            surface,
+            product: {
+                productId: getIdFromGid(hit === null || hit === void 0 ? void 0 : hit.id),
+                variantId,
+                objectId: hit === null || hit === void 0 ? void 0 : hit.objectID,
+                position: index + 1,
+            },
+        });
+    }), [searchClient, emitProductConversion, surface]);
+}
+/**
+ * Emit-only sibling of `useSearchAnalyticsAddToCart` for the quick-add drawer
+ * path. Multi-variant products open the quick-add drawer (rendered at app-layout
+ * level, OUTSIDE the page's SearchClientProvider), which performs its own
+ * `actions.addToCart`. So the drawer can't read the search context or call the
+ * combined add-and-emit handler without double-adding. This returns a stable
+ * `emitAddToCartConversion(variantId)` the drawer invokes on add success to emit
+ * the `add_to_cart` conversion only — attributed via the originating result's
+ * Algolia `objectID` + 1-based position, no cart mutation. No-ops when the grid
+ * isn't search-backed (`searchClient` falsy), the emitter isn't injected, the
+ * variant is missing, or the variant isn't found in the current results.
+ */
+export function useSearchAnalyticsConversionEmit({ products, searchClient, emitProductConversion, surface = "collection", }) {
+    const productsRef = React.useRef(products);
+    productsRef.current = products;
+    return React.useCallback((variantId) => {
+        if (!searchClient || !emitProductConversion || !variantId)
+            return;
+        const list = productsRef.current || [];
+        const index = list.findIndex((item) => { var _a; return (_a = item === null || item === void 0 ? void 0 : item.variants) === null || _a === void 0 ? void 0 : _a.some((v) => getIdFromGid(v === null || v === void 0 ? void 0 : v.id) === variantId); });
+        if (index < 0)
+            return;
+        const hit = list[index];
+        emitProductConversion({
+            client: searchClient,
+            surface,
+            product: {
+                productId: getIdFromGid(hit === null || hit === void 0 ? void 0 : hit.id),
+                variantId,
+                objectId: hit === null || hit === void 0 ? void 0 : hit.objectID,
+                position: index + 1,
+            },
+        });
+    }, [searchClient, emitProductConversion, surface]);
+}
+/**
+ * Returns an `onImpression(product)` callback for ProductCard to fire when a
+ * result first scrolls into view, emitting a search-analytics `impression`
+ * (Algolia `viewedObjectIDs` — objectID only, no position). Dedupes so each
+ * product emits at most once per session, even across virtualized remounts.
+ *
+ * Returns `undefined` when the grid isn't search-backed or no emitter is
+ * injected, so ProductCard skips setting up an IntersectionObserver entirely on
+ * non-search surfaces.
+ */
+export function useSearchAnalyticsImpression({ searchClient, emitProductImpression, surface = "collection", enabled = true, }) {
+    const seenRef = React.useRef(new Set());
+    return React.useMemo(() => {
+        if (!searchClient || !emitProductImpression || !enabled)
+            return undefined;
+        return (product) => {
+            const objectId = product === null || product === void 0 ? void 0 : product.objectID;
+            const productId = getIdFromGid(product === null || product === void 0 ? void 0 : product.id);
+            const key = objectId || productId;
+            if (!key || seenRef.current.has(key))
+                return;
+            seenRef.current.add(key);
+            emitProductImpression({
+                client: searchClient,
+                surface,
+                product: { productId, objectId },
+            });
+        };
+    }, [searchClient, emitProductImpression, surface, enabled]);
+}

package/dist/components/hooks/use-search-analytics-open-product.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=use-search-analytics-open-product.test.d.ts.map

package/dist/components/hooks/use-search-analytics-open-product.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-search-analytics-open-product.test.d.ts","sourceRoot":"","sources":["../../../components/hooks/use-search-analytics-open-product.test.ts"],"names":[],"mappings":""}

package/dist/components/hooks/use-search-analytics-open-product.test.js

@@ -0,0 +1,315 @@
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+import { renderHook } from "@testing-library/react";
+import { useSearchAnalyticsOpenProduct, useSearchAnalyticsAddToCart, useSearchAnalyticsImpression, } from "./use-search-analytics-open-product";
+const products = [
+    { id: "gid://shopify/Product/1", objectID: "obj-1" },
+    { id: "gid://shopify/Product/2", objectID: "obj-2" },
+    { id: "gid://shopify/Product/3", objectID: "obj-3" },
+];
+describe("useSearchAnalyticsOpenProduct", () => {
+    it("always opens the product (haptic + product/open) even when not search-backed", () => {
+        const action = jest.fn();
+        const emitProductClick = jest.fn();
+        const { result } = renderHook(() => useSearchAnalyticsOpenProduct({
+            products,
+            searchClient: undefined,
+            emitProductClick,
+            action,
+        }));
+        result.current({ productId: "2", variantId: "v2" });
+        expect(action).toHaveBeenCalledWith("trigger/haptic");
+        expect(action).toHaveBeenCalledWith("product/open", {
+            productId: "2",
+            variantId: "v2",
+        });
+        // No search to attribute to -> no click emitted.
+        expect(emitProductClick).not.toHaveBeenCalled();
+    });
+    it("does not throw and opens the product when no emitter is injected", () => {
+        const action = jest.fn();
+        const { result } = renderHook(() => useSearchAnalyticsOpenProduct({
+            products,
+            searchClient: {},
+            emitProductClick: undefined,
+            action,
+        }));
+        expect(() => result.current({ productId: "1" })).not.toThrow();
+        expect(action).toHaveBeenCalledWith("product/open", { productId: "1" });
+    });
+    it("emits a click with the hit objectID and 1-based position for a search-backed grid", () => {
+        const action = jest.fn();
+        const emitProductClick = jest.fn();
+        const searchClient = { provider: "algolia" };
+        const { result } = renderHook(() => useSearchAnalyticsOpenProduct({
+            products,
+            searchClient,
+            emitProductClick,
+            action,
+            surface: "collection",
+        }));
+        result.current({ productId: "2", variantId: "v2" });
+        expect(emitProductClick).toHaveBeenCalledTimes(1);
+        expect(emitProductClick).toHaveBeenCalledWith({
+            client: searchClient,
+            surface: "collection",
+            product: {
+                productId: "2",
+                variantId: "v2",
+                objectId: "obj-2",
+                position: 2, // 1-based index of the second product
+            },
+        });
+    });
+    it("emits with undefined objectId/position when the clicked product isn't in the list", () => {
+        const action = jest.fn();
+        const emitProductClick = jest.fn();
+        const { result } = renderHook(() => useSearchAnalyticsOpenProduct({
+            products,
+            searchClient: { provider: "algolia" },
+            emitProductClick,
+            action,
+        }));
+        result.current({ productId: "999" });
+        expect(emitProductClick).toHaveBeenCalledWith(expect.objectContaining({
+            product: expect.objectContaining({
+                objectId: undefined,
+                position: undefined,
+            }),
+        }));
+    });
+    it("keeps a stable callback identity across re-renders (preserves memoized cards)", () => {
+        const action = jest.fn();
+        const emitProductClick = jest.fn();
+        const searchClient = { provider: "algolia" };
+        const { result, rerender } = renderHook(({ list }) => useSearchAnalyticsOpenProduct({
+            products: list,
+            searchClient,
+            emitProductClick,
+            action,
+        }), { initialProps: { list: products } });
+        const first = result.current;
+        // New products array reference (e.g. next infinite-scroll page) must NOT
+        // rebuild the callback, or every ProductCard would re-render.
+        rerender({
+            list: [...products, { id: "gid://shopify/Product/4", objectID: "obj-4" }],
+        });
+        expect(result.current).toBe(first);
+        // ...but the stable callback still reads the latest list on click.
+        result.current({ productId: "4" });
+        expect(emitProductClick).toHaveBeenCalledWith(expect.objectContaining({
+            product: expect.objectContaining({ objectId: "obj-4", position: 4 }),
+        }));
+    });
+    it("stays stable across an unstable `action` and still fires the latest one", () => {
+        const emitProductClick = jest.fn();
+        const searchClient = { provider: "algolia" };
+        const firstAction = jest.fn();
+        const { result, rerender } = renderHook(({ action }) => useSearchAnalyticsOpenProduct({
+            products,
+            searchClient,
+            emitProductClick,
+            action,
+        }), { initialProps: { action: firstAction } });
+        const first = result.current;
+        // A new `action` identity (e.g. useTapcart() returning a fresh fn) must NOT
+        // rebuild the callback — it's held in a ref.
+        const secondAction = jest.fn();
+        rerender({ action: secondAction });
+        expect(result.current).toBe(first);
+        // The stable callback still invokes the *latest* action, not the stale one.
+        result.current({ productId: "1" });
+        expect(secondAction).toHaveBeenCalledWith("product/open", {
+            productId: "1",
+        });
+        expect(firstAction).not.toHaveBeenCalled();
+    });
+});
+const cartProducts = [
+    {
+        id: "gid://shopify/Product/1",
+        objectID: "obj-1",
+        variants: [{ id: "gid://shopify/ProductVariant/11" }],
+    },
+    {
+        id: "gid://shopify/Product/2",
+        objectID: "obj-2",
+        variants: [
+            { id: "gid://shopify/ProductVariant/22" },
+            { id: "gid://shopify/ProductVariant/23" },
+        ],
+    },
+];
+// ProductCard's add-to-cart payload: line items keyed by numeric variant id.
+const addProps = (variantId) => ({
+    lineItems: [{ variantId, quantity: 1 }],
+    cartAttributes: [],
+});
+describe("useSearchAnalyticsAddToCart", () => {
+    it("always adds the item (haptic + cart/add) even when not search-backed", () => __awaiter(void 0, void 0, void 0, function* () {
+        const action = jest.fn();
+        const emitProductConversion = jest.fn();
+        const { result } = renderHook(() => useSearchAnalyticsAddToCart({
+            products: cartProducts,
+            searchClient: undefined,
+            emitProductConversion,
+            action,
+        }));
+        yield result.current(addProps("22"));
+        expect(action).toHaveBeenCalledWith("trigger/haptic");
+        expect(action).toHaveBeenCalledWith("cart/add", addProps("22"));
+        expect(emitProductConversion).not.toHaveBeenCalled();
+    }));
+    it("emits an add_to_cart conversion (after the add succeeds) with the matched product's objectID + 1-based position", () => __awaiter(void 0, void 0, void 0, function* () {
+        const action = jest.fn();
+        const emitProductConversion = jest.fn();
+        const searchClient = { provider: "algolia" };
+        const { result } = renderHook(() => useSearchAnalyticsAddToCart({
+            products: cartProducts,
+            searchClient,
+            emitProductConversion,
+            action,
+        }));
+        // Add the second variant of the second product.
+        yield result.current(addProps("23"));
+        expect(action).toHaveBeenCalledWith("cart/add", addProps("23"));
+        expect(emitProductConversion).toHaveBeenCalledTimes(1);
+        expect(emitProductConversion).toHaveBeenCalledWith({
+            client: searchClient,
+            surface: "collection",
+            product: {
+                productId: "2",
+                variantId: "23",
+                objectId: "obj-2",
+                position: 2,
+            },
+        });
+    }));
+    it("does NOT emit the conversion when the add fails (cart/add rejects)", () => __awaiter(void 0, void 0, void 0, function* () {
+        const action = jest.fn((name) => name === "cart/add" ? Promise.reject(new Error("add failed")) : undefined);
+        const emitProductConversion = jest.fn();
+        const { result } = renderHook(() => useSearchAnalyticsAddToCart({
+            products: cartProducts,
+            searchClient: { provider: "algolia" },
+            emitProductConversion,
+            action,
+        }));
+        yield result.current(addProps("23"));
+        expect(action).toHaveBeenCalledWith("cart/add", addProps("23"));
+        expect(emitProductConversion).not.toHaveBeenCalled();
+    }));
+    it("does not emit when the added variant isn't in the current results", () => __awaiter(void 0, void 0, void 0, function* () {
+        const action = jest.fn();
+        const emitProductConversion = jest.fn();
+        const { result } = renderHook(() => useSearchAnalyticsAddToCart({
+            products: cartProducts,
+            searchClient: { provider: "algolia" },
+            emitProductConversion,
+            action,
+        }));
+        yield result.current(addProps("999"));
+        expect(action).toHaveBeenCalledWith("cart/add", addProps("999"));
+        expect(emitProductConversion).not.toHaveBeenCalled();
+    }));
+    it("does not throw and still adds when no emitter is injected", () => {
+        const action = jest.fn();
+        const { result } = renderHook(() => useSearchAnalyticsAddToCart({
+            products: cartProducts,
+            searchClient: { provider: "algolia" },
+            emitProductConversion: undefined,
+            action,
+        }));
+        expect(() => result.current(addProps("11"))).not.toThrow();
+        expect(action).toHaveBeenCalledWith("cart/add", addProps("11"));
+    });
+    it("keeps a stable callback identity across a new products array", () => __awaiter(void 0, void 0, void 0, function* () {
+        const action = jest.fn();
+        const emitProductConversion = jest.fn();
+        const searchClient = { provider: "algolia" };
+        const { result, rerender } = renderHook(({ list }) => useSearchAnalyticsAddToCart({
+            products: list,
+            searchClient,
+            emitProductConversion,
+            action,
+        }), { initialProps: { list: cartProducts } });
+        const first = result.current;
+        rerender({
+            list: [
+                ...cartProducts,
+                {
+                    id: "gid://shopify/Product/3",
+                    objectID: "obj-3",
+                    variants: [{ id: "gid://shopify/ProductVariant/33" }],
+                },
+            ],
+        });
+        expect(result.current).toBe(first);
+        // Stable callback still reads the latest list.
+        yield result.current(addProps("33"));
+        expect(emitProductConversion).toHaveBeenCalledWith(expect.objectContaining({
+            product: expect.objectContaining({ objectId: "obj-3", position: 3 }),
+        }));
+    }));
+});
+describe("useSearchAnalyticsImpression", () => {
+    it("returns undefined when not search-backed (ProductCard skips the observer)", () => {
+        const { result } = renderHook(() => useSearchAnalyticsImpression({
+            searchClient: undefined,
+            emitProductImpression: jest.fn(),
+        }));
+        expect(result.current).toBeUndefined();
+    });
+    it("returns undefined when no emitter is injected", () => {
+        const { result } = renderHook(() => useSearchAnalyticsImpression({
+            searchClient: {},
+            emitProductImpression: undefined,
+        }));
+        expect(result.current).toBeUndefined();
+    });
+    it("returns undefined when disabled, even with a search client and a callable no-op emitter (flag OFF skips the observer)", () => {
+        // The real NOOP_EMITTER exposes callable no-ops, not undefined, so a truthy
+        // emitter must not be enough to set up the observer — the flag must gate it.
+        const { result } = renderHook(() => useSearchAnalyticsImpression({
+            searchClient: { provider: "algolia" },
+            emitProductImpression: () => { },
+            enabled: false,
+        }));
+        expect(result.current).toBeUndefined();
+    });
+    it("emits one impression with objectId + productId when a card becomes visible", () => {
+        var _a;
+        const emitProductImpression = jest.fn();
+        const searchClient = { provider: "algolia" };
+        const { result } = renderHook(() => useSearchAnalyticsImpression({
+            searchClient,
+            emitProductImpression,
+            surface: "collection",
+        }));
+        (_a = result.current) === null || _a === void 0 ? void 0 : _a.call(result, { id: "gid://shopify/Product/2", objectID: "obj-2" });
+        expect(emitProductImpression).toHaveBeenCalledTimes(1);
+        expect(emitProductImpression).toHaveBeenCalledWith({
+            client: searchClient,
+            surface: "collection",
+            product: { productId: "2", objectId: "obj-2" },
+        });
+    });
+    it("dedupes repeat impressions of the same product", () => {
+        var _a, _b;
+        const emitProductImpression = jest.fn();
+        const { result } = renderHook(() => useSearchAnalyticsImpression({
+            searchClient: { provider: "algolia" },
+            emitProductImpression,
+        }));
+        const product = { id: "gid://shopify/Product/2", objectID: "obj-2" };
+        (_a = result.current) === null || _a === void 0 ? void 0 : _a.call(result, product);
+        (_b = result.current) === null || _b === void 0 ? void 0 : _b.call(result, product);
+        expect(emitProductImpression).toHaveBeenCalledTimes(1);
+    });
+});

package/dist/index.d.ts

@@ -10,6 +10,7 @@ export * from "./components/hooks/use-infinite-scroll";
 export * from "./components/hooks/swr-retry";
 export * from "./components/hooks/use-infinite-wishlist";
 export * from "./components/hooks/use-recommendations";
+export * from "./components/hooks/use-search-analytics-open-product";
 export * from "./components/hooks/use-products";
 export * from "./components/hooks/use-personalized-cluster-feed";
 export * from "./components/hooks/use-order-details";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"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"}