@metron-labs/quote-react 0.1.20 → 0.1.22

package/dist/index.d.ts

@@ -4,6 +4,8 @@ export { default as EstimatingTools } from "./app/EstimatingTools";
 export type { EstimatingToolsProps } from "./app/EstimatingTools";
 export { QuoteProvider } from "./lib/QuoteProvider";
 export type { QuoteConfig } from "./lib/config";
+export { STEP_EVENT, DATALAYER_EVENT } from "./lib/analytics";
+export type { Step, WidgetEvent, WidgetName } from "./lib/analytics";
 export { ESTIMATOR_TOOLS } from "./components/estimators/registry";
 export type { EstimatorToolId } from "./components/estimators/registry";
 export type { EstimatorRequirement } from "./lib/estimators/types";

package/dist/index.js

@@ -5,4 +5,5 @@
 export { default as QuickQuote } from "./app/QuickQuote";
 export { default as EstimatingTools } from "./app/EstimatingTools";
 export { QuoteProvider } from "./lib/QuoteProvider";
+export { STEP_EVENT, DATALAYER_EVENT } from "./lib/analytics";
 export { ESTIMATOR_TOOLS } from "./components/estimators/registry";

package/dist/lib/analytics.d.ts

@@ -0,0 +1,16 @@
+import type { RefObject } from "react";
+export declare const STEP_EVENT = "metron:step";
+export declare const DATALAYER_EVENT = "metron_step";
+export type WidgetName = "quick-quote" | "estimating-tools";
+export type Step = "viewed" | "method_selected" | "list_submitted" | "results_shown" | "error" | "calculator_selected" | "estimate_completed" | "basket_viewed" | "downloaded" | "quote_requested";
+export interface WidgetEvent {
+    widget: WidgetName;
+    step: Step;
+    [field: string]: string | number | boolean | undefined;
+}
+export type Track = (step: Step, fields?: Omit<WidgetEvent, "widget" | "step">) => void;
+/** The tracker for the widget a component sits in. Outside a widget, a no-op. */
+export declare const TrackContext: import("react").Context<Track>;
+export declare const useTrack: () => Track;
+/** Creates the tracker a widget provides to its steps, reporting from its root element. */
+export declare function useTracker(widget: WidgetName, root: RefObject<HTMLElement | null>): Track;

package/dist/lib/analytics.js

@@ -0,0 +1,37 @@
+import { createContext, useCallback, useContext } from "react";
+import { getQuoteConfig } from "./config";
+// Funnel events, so a host site can see where customers drop off. The widgets never load a
+// tracker of their own: they only report steps, and the host's analytics decides what to do.
+// Each event goes to up to three places:
+//
+//   1. A "metron:step" DOM event from the widget's root. It bubbles out of the script-tag
+//      build's shadow root (composed), so the host listens on the element or on document.
+//   2. config.onEvent, for React hosts.
+//   3. window.dataLayer, if the page already has one (Google Tag Manager), as
+//      { event: "metron_step", widget, step, ... }. Never created here.
+//
+// config.analytics "events-only" skips the dataLayer; "none" sends nothing at all.
+//
+// The step names and fields are a contract: hosts build GTM triggers on them, so rename one only
+// alongside a new major embed version (see the v1 note in the Quote-Package README). Events carry
+// counts and names only, never what a customer typed.
+export const STEP_EVENT = "metron:step";
+export const DATALAYER_EVENT = "metron_step";
+/** The tracker for the widget a component sits in. Outside a widget, a no-op. */
+export const TrackContext = createContext(() => { });
+export const useTrack = () => useContext(TrackContext);
+/** Creates the tracker a widget provides to its steps, reporting from its root element. */
+export function useTracker(widget, root) {
+    return useCallback((step, fields = {}) => {
+        const config = getQuoteConfig();
+        const mode = config.analytics ?? "all";
+        if (mode === "none")
+            return;
+        const event = { ...fields, widget, step };
+        root.current?.dispatchEvent(new CustomEvent(STEP_EVENT, { detail: event, bubbles: true, composed: true }));
+        config.onEvent?.(event);
+        const dataLayer = window.dataLayer;
+        if (mode === "all" && Array.isArray(dataLayer))
+            dataLayer.push({ event: DATALAYER_EVENT, ...event });
+    }, [widget, root]);
+}

package/dist/lib/config.d.ts

@@ -1,3 +1,4 @@
+import type { WidgetEvent } from "./analytics";
 export interface QuoteConfig {
     /**
      * Origin serving Metron's API, e.g. "https://api.metronlabs.ai". No trailing slash needed.
@@ -22,6 +23,14 @@ export interface QuoteConfig {
      * { "--accent": "#ffc72c", "--navy": "#002e5f" }.
      */
     theme?: Record<string, string>;
+    /**
+     * Funnel events (see analytics.ts). "all" (the default) dispatches metron:step DOM events,
+     * calls onEvent and pushes to window.dataLayer when the page has one; "events-only" skips the
+     * dataLayer; "none" sends nothing.
+     */
+    analytics?: "all" | "events-only" | "none";
+    /** Called with each funnel event, e.g. to forward it to your own analytics. */
+    onEvent?: (event: WidgetEvent) => void;
 }
 /** Called by QuoteProvider. Not part of the public API. */
 export declare function setModuleConfig(config: QuoteConfig): void;

package/dist/lib/productImage.js

@@ -23,26 +23,26 @@ export function productImageSrc(description, productId, pdpPhotoUrl) {
     if (photo)
         return assetUrl(photo.path);
     if (text.includes("insulation")) {
-        return encodeSvg(`
-      <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 640 420">
-        <rect width="640" height="420" fill="#fbf1cf"/>
-        <rect x="88" y="78" width="432" height="264" rx="16" fill="#f0c43f"/>
-        <rect x="120" y="110" width="368" height="200" rx="10" fill="#ffd95e"/>
-        <g stroke="#e2b12e" stroke-width="8" opacity="0.75">
-          <line x1="140" y1="140" x2="468" y2="140"/>
-          <line x1="140" y1="190" x2="468" y2="190"/>
-          <line x1="140" y1="240" x2="468" y2="240"/>
-        </g>
-      </svg>
+        return encodeSvg(`
+      <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 640 420">
+        <rect width="640" height="420" fill="#fbf1cf"/>
+        <rect x="88" y="78" width="432" height="264" rx="16" fill="#f0c43f"/>
+        <rect x="120" y="110" width="368" height="200" rx="10" fill="#ffd95e"/>
+        <g stroke="#e2b12e" stroke-width="8" opacity="0.75">
+          <line x1="140" y1="140" x2="468" y2="140"/>
+          <line x1="140" y1="190" x2="468" y2="190"/>
+          <line x1="140" y1="240" x2="468" y2="240"/>
+        </g>
+      </svg>
     `);
     }
-    return encodeSvg(`
-    <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 640 420">
-      <rect width="640" height="420" fill="#edf1f5"/>
-      <rect x="132" y="108" width="376" height="204" rx="18" fill="#d5dde6"/>
-      <rect x="168" y="144" width="304" height="24" rx="12" fill="#9aa6b2"/>
-      <rect x="168" y="188" width="250" height="24" rx="12" fill="#aab5c0"/>
-      <rect x="168" y="232" width="220" height="24" rx="12" fill="#aab5c0"/>
-    </svg>
+    return encodeSvg(`
+    <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 640 420">
+      <rect width="640" height="420" fill="#edf1f5"/>
+      <rect x="132" y="108" width="376" height="204" rx="18" fill="#d5dde6"/>
+      <rect x="168" y="144" width="304" height="24" rx="12" fill="#9aa6b2"/>
+      <rect x="168" y="188" width="250" height="24" rx="12" fill="#aab5c0"/>
+      <rect x="168" y="232" width="220" height="24" rx="12" fill="#aab5c0"/>
+    </svg>
   `);
 }