react-event-tracking 1.0.3 → 1.0.5

package/README.md

@@ -6,6 +6,21 @@ A convenient React context for tracking analytics events.
 - **Nested Contexts**: Automatically merges parameters from parent providers.
 - **Zero Re-renders**: No need to wrap props in `useCallback`/`useMemo`.
 
+## Table of Contents
+
+<!-- toc -->
+
+- [Installation](#installation)
+- [Quickstart](#quickstart)
+- [Advanced Usage](#advanced-usage)
+  * [Multiple Trackers & Factory](#multiple-trackers--factory)
+  * [Filtering Events](#filtering-events)
+  * [Transforming Events](#transforming-events)
+- [Best Practices](#best-practices)
+- [Built-in Hooks](#built-in-hooks)
+  * [useMountEvent](#usemountevent)
+
+<!-- tocstop -->
 
 ## Installation
 
@@ -18,7 +33,7 @@ yarn add react-event-tracking
 
 ## Quickstart
 
-1. Define the root handler (e.g., send to GTM or API)
+1. Define the root handler (e.g., send to GTM, Amplitude or API)
 ```tsx
 import { TrackRoot } from 'react-event-tracking';
 
@@ -56,6 +71,140 @@ const MyButton = () => {
 };
 ```
 
+## Advanced Usage
+
+### Multiple Trackers & Factory
+
+You can chain multiple `TrackRoot` components to send events to different analytics services. Events bubble up through all providers.
+
+Use `TrackRoot.factory` to create reusable tracker components:
+
+1. Create specific trackers
+```tsx
+const TrackRootGoogle = TrackRoot.factory(
+  (name, params) => gtag('event', name, params)
+);
+
+const TrackRootAmplitude = TrackRoot.factory(
+  (name, params) => amplitude.logEvent(name, params)
+);
+```
+
+2. Compose them in your app
+```tsx
+const App = () => (
+  <TrackRootGoogle>
+    <TrackRootAmplitude>
+      <MyApp />
+    </TrackRootAmplitude>
+  </TrackRootGoogle>
+);
+```
+
+### Filtering Events
+
+You can control which events are sent to which provider using the `filter` prop (or the second argument in `factory`). If the filter returns `false`, the event is skipped for that tracker but continues to bubble up to others.
+
+```tsx
+// Google Analytics: only track page_* events
+const TrackRootGoogle = TrackRoot.factory(
+  (name, params) => gtag('event', name, params),
+  (name) => name.startsWith('page_')
+);
+
+// Amplitude: track everything (filter is optional, defaults to allowing all events)
+const TrackRootAmplitude = TrackRoot.factory(
+  (name, params) => ampltitude.logEvent(name, params),
+);
+```
+
+Compose them in your app:
+
+```tsx
+const App = () => (
+  <TrackRootGoogle>
+    <TrackRootAmplitude>
+      <MyApp />
+    </TrackRootAmplitude>
+  </TrackRootGoogle>
+);
+```
+
+### Transforming Events
+
+You can modify the event name or parameters before they reach the handler using the `transform` prop (or the third argument in `factory`).
+
+Note: Transformations apply locally and do not affect the event bubbling up to parent providers.
+
+```tsx
+// GDPR Tracker
+const AmpltitudeUS = TrackRoot.factory(
+  (name, params) => amplitude.logEvent(name, params),
+  undefined, // no filter
+  (name, params) => {
+    if (params?.userRegion === 'EU') {
+      // Remove PII (Personally Identifiable Information)
+      const { userId, email, ...safeParams } = params || {};
+      return { 
+        eventName: name, 
+        params: safeParams 
+      };
+    }
+    return { eventName: name, params };
+  }
+);
+```
+
+## Best Practices
+
+A common pattern is to layer data from global to specific. Here is how parameters merge:
+
+```tsx
+<TrackRoot onEvent={handleEvent}>
+  {/* 1. ROOT: Global data (App Version, Environment) */}
+  <TrackProvider params={{ appVersion: '1.0.0' }}>
+  
+    {/* 2. PAGE: Screen-level context */}
+    <TrackProvider params={{ page: 'ProductDetails', category: 'Shoes' }}>
+    
+      {/* 3. COMPONENT: Widget-level context */}
+      <TrackProvider params={{ productId: 'sku-999' }}>
+        <AddToCartButton />
+      </TrackProvider>
+
+    </TrackProvider>
+  </TrackProvider>
+</TrackRoot>
+
+// Inside AddToCartButton:
+const { sendEvent } = useTracker();
+
+// 4. EVENT: Action-specific data
+// When clicked, we only pass what changed right now.
+const handleClick = () => {
+  sendEvent('add_to_cart', { quantity: 1 });
+};
+```
+
+**Resulting Event Payload:**
+The library merges all layers automatically. The handler receives:
+
+
+```js
+{
+  // From Root
+  appVersion: '1.0.0',
+  // From Page Provider
+  page: 'ProductDetails',
+  category: 'Shoes',
+  // From Component Provider
+  productId: 'sku-999',
+  // From Event
+  quantity: 1
+}
+```
+
+
 ## Built-in Hooks   
 
 ### useMountEvent   

package/dist/index.cjs

@@ -14,25 +14,69 @@ const useTracker = () => {
   }
   return ctx;
 };
-const TrackRoot = ({
-  onEvent,
-  children
-}) => {
-  const onEventRef = React.useRef(onEvent);
-  onEventRef.current = onEvent;
-  const sendEvent = React.useCallback((eventName, params) => {
-    onEventRef.current(eventName, params);
-  }, []);
+const TrackRootComponent = ({ onEvent, children, filter, transform }) => {
+  const parentCtx = React.useContext(TrackContext);
+  const onEventRef = useFreshRef(onEvent);
+  const filterRef = useFreshRef(filter);
+  const transformRef = useFreshRef(transform);
+  const sendEvent = React.useCallback(
+    (eventName, params) => {
+      let localName = eventName;
+      let localParams = params;
+      let shouldProcessLocal = true;
+      try {
+        if (filterRef.current) {
+          shouldProcessLocal = filterRef.current(localName, localParams);
+        }
+      } catch (error) {
+        console.error("TrackRoot filter failed:", error);
+        shouldProcessLocal = false;
+      }
+      if (shouldProcessLocal && transformRef.current) {
+        try {
+          const paramsCopy = params ? { ...params } : params;
+          const result = transformRef.current(eventName, paramsCopy);
+          localName = result.eventName;
+          localParams = result.params;
+        } catch (error) {
+          console.error("TrackRoot transform failed:", error);
+          shouldProcessLocal = false;
+        }
+      }
+      if (shouldProcessLocal) {
+        try {
+          onEventRef.current(localName, localParams);
+        } catch (error) {
+          console.error("TrackRoot onEvent failed:", error);
+        }
+      }
+      if (parentCtx) {
+        parentCtx.sendEvent(eventName, params);
+      }
+    },
+    [parentCtx]
+  );
   const value = React.useMemo(() => ({ sendEvent }), [sendEvent]);
   return /* @__PURE__ */ React__default.createElement(TrackContext.Provider, { value }, children);
 };
+const factory = (onEvent, filter, transform) => {
+  return (props) => /* @__PURE__ */ React__default.createElement(
+    TrackRootComponent,
+    {
+      onEvent,
+      filter,
+      transform,
+      ...props
+    }
+  );
+};
+const TrackRoot = Object.assign(TrackRootComponent, { factory });
 const TrackProvider = ({
   params,
   children
 }) => {
   const ctx = useTracker();
-  const paramsRef = React.useRef(params);
-  paramsRef.current = params;
+  const paramsRef = useFreshRef(params);
   const sendEvent = React.useCallback(
     (eventName, eventParams) => {
       const currentParams = paramsRef.current;
@@ -46,6 +90,11 @@ const TrackProvider = ({
   const value = React.useMemo(() => ({ sendEvent }), [sendEvent]);
   return /* @__PURE__ */ React__default.createElement(TrackContext.Provider, { value }, children);
 };
+function useFreshRef(data) {
+  const ref = React.useRef(data);
+  ref.current = data;
+  return ref;
+}
 
 function useMountEvent(eventName, params) {
   const { sendEvent } = useTracker();

package/dist/index.d.cts

@@ -5,11 +5,22 @@ type EventParams = Record<string, any>;
 type TrackContextValue = {
     sendEvent: (eventName: string, params?: EventParams) => void;
 };
+type EventFilter = (eventName: string, params?: EventParams) => boolean;
+type TransformedEvent = {
+    eventName: string;
+    params?: EventParams;
+};
+type EventTransformer = (eventName: string, params?: EventParams) => TransformedEvent;
 
 declare const useTracker: () => TrackContextValue;
-declare const TrackRoot: ({ onEvent, children }: PropsWithChildren<{
+type TrackRootProps = PropsWithChildren<{
     onEvent: (eventName: string, params?: EventParams) => void;
-}>) => react_jsx_runtime.JSX.Element;
+    filter?: EventFilter;
+    transform?: EventTransformer;
+}>;
+declare const TrackRoot: (({ onEvent, children, filter, transform }: TrackRootProps) => react_jsx_runtime.JSX.Element) & {
+    factory: (onEvent: (eventName: string, params?: EventParams) => void, filter?: EventFilter, transform?: EventTransformer) => (props: Omit<TrackRootProps, "onEvent" | "filter" | "transform">) => react_jsx_runtime.JSX.Element;
+};
 declare const TrackProvider: ({ params, children }: PropsWithChildren<{
     params: EventParams;
 }>) => react_jsx_runtime.JSX.Element;

package/dist/index.d.mts

@@ -5,11 +5,22 @@ type EventParams = Record<string, any>;
 type TrackContextValue = {
     sendEvent: (eventName: string, params?: EventParams) => void;
 };
+type EventFilter = (eventName: string, params?: EventParams) => boolean;
+type TransformedEvent = {
+    eventName: string;
+    params?: EventParams;
+};
+type EventTransformer = (eventName: string, params?: EventParams) => TransformedEvent;
 
 declare const useTracker: () => TrackContextValue;
-declare const TrackRoot: ({ onEvent, children }: PropsWithChildren<{
+type TrackRootProps = PropsWithChildren<{
     onEvent: (eventName: string, params?: EventParams) => void;
-}>) => react_jsx_runtime.JSX.Element;
+    filter?: EventFilter;
+    transform?: EventTransformer;
+}>;
+declare const TrackRoot: (({ onEvent, children, filter, transform }: TrackRootProps) => react_jsx_runtime.JSX.Element) & {
+    factory: (onEvent: (eventName: string, params?: EventParams) => void, filter?: EventFilter, transform?: EventTransformer) => (props: Omit<TrackRootProps, "onEvent" | "filter" | "transform">) => react_jsx_runtime.JSX.Element;
+};
 declare const TrackProvider: ({ params, children }: PropsWithChildren<{
     params: EventParams;
 }>) => react_jsx_runtime.JSX.Element;

package/dist/index.d.ts

@@ -5,11 +5,22 @@ type EventParams = Record<string, any>;
 type TrackContextValue = {
     sendEvent: (eventName: string, params?: EventParams) => void;
 };
+type EventFilter = (eventName: string, params?: EventParams) => boolean;
+type TransformedEvent = {
+    eventName: string;
+    params?: EventParams;
+};
+type EventTransformer = (eventName: string, params?: EventParams) => TransformedEvent;
 
 declare const useTracker: () => TrackContextValue;
-declare const TrackRoot: ({ onEvent, children }: PropsWithChildren<{
+type TrackRootProps = PropsWithChildren<{
     onEvent: (eventName: string, params?: EventParams) => void;
-}>) => react_jsx_runtime.JSX.Element;
+    filter?: EventFilter;
+    transform?: EventTransformer;
+}>;
+declare const TrackRoot: (({ onEvent, children, filter, transform }: TrackRootProps) => react_jsx_runtime.JSX.Element) & {
+    factory: (onEvent: (eventName: string, params?: EventParams) => void, filter?: EventFilter, transform?: EventTransformer) => (props: Omit<TrackRootProps, "onEvent" | "filter" | "transform">) => react_jsx_runtime.JSX.Element;
+};
 declare const TrackProvider: ({ params, children }: PropsWithChildren<{
     params: EventParams;
 }>) => react_jsx_runtime.JSX.Element;

package/dist/index.mjs

@@ -1,4 +1,4 @@
-import React, { useContext, useRef, useCallback, useMemo, useEffect } from 'react';
+import React, { useContext, useCallback, useMemo, useRef, useEffect } from 'react';
 
 const TrackContext = React.createContext(null);
 const useTracker = () => {
@@ -8,25 +8,69 @@ const useTracker = () => {
   }
   return ctx;
 };
-const TrackRoot = ({
-  onEvent,
-  children
-}) => {
-  const onEventRef = useRef(onEvent);
-  onEventRef.current = onEvent;
-  const sendEvent = useCallback((eventName, params) => {
-    onEventRef.current(eventName, params);
-  }, []);
+const TrackRootComponent = ({ onEvent, children, filter, transform }) => {
+  const parentCtx = useContext(TrackContext);
+  const onEventRef = useFreshRef(onEvent);
+  const filterRef = useFreshRef(filter);
+  const transformRef = useFreshRef(transform);
+  const sendEvent = useCallback(
+    (eventName, params) => {
+      let localName = eventName;
+      let localParams = params;
+      let shouldProcessLocal = true;
+      try {
+        if (filterRef.current) {
+          shouldProcessLocal = filterRef.current(localName, localParams);
+        }
+      } catch (error) {
+        console.error("TrackRoot filter failed:", error);
+        shouldProcessLocal = false;
+      }
+      if (shouldProcessLocal && transformRef.current) {
+        try {
+          const paramsCopy = params ? { ...params } : params;
+          const result = transformRef.current(eventName, paramsCopy);
+          localName = result.eventName;
+          localParams = result.params;
+        } catch (error) {
+          console.error("TrackRoot transform failed:", error);
+          shouldProcessLocal = false;
+        }
+      }
+      if (shouldProcessLocal) {
+        try {
+          onEventRef.current(localName, localParams);
+        } catch (error) {
+          console.error("TrackRoot onEvent failed:", error);
+        }
+      }
+      if (parentCtx) {
+        parentCtx.sendEvent(eventName, params);
+      }
+    },
+    [parentCtx]
+  );
   const value = useMemo(() => ({ sendEvent }), [sendEvent]);
   return /* @__PURE__ */ React.createElement(TrackContext.Provider, { value }, children);
 };
+const factory = (onEvent, filter, transform) => {
+  return (props) => /* @__PURE__ */ React.createElement(
+    TrackRootComponent,
+    {
+      onEvent,
+      filter,
+      transform,
+      ...props
+    }
+  );
+};
+const TrackRoot = Object.assign(TrackRootComponent, { factory });
 const TrackProvider = ({
   params,
   children
 }) => {
   const ctx = useTracker();
-  const paramsRef = useRef(params);
-  paramsRef.current = params;
+  const paramsRef = useFreshRef(params);
   const sendEvent = useCallback(
     (eventName, eventParams) => {
       const currentParams = paramsRef.current;
@@ -40,6 +84,11 @@ const TrackProvider = ({
   const value = useMemo(() => ({ sendEvent }), [sendEvent]);
   return /* @__PURE__ */ React.createElement(TrackContext.Provider, { value }, children);
 };
+function useFreshRef(data) {
+  const ref = useRef(data);
+  ref.current = data;
+  return ref;
+}
 
 function useMountEvent(eventName, params) {
   const { sendEvent } = useTracker();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-event-tracking",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "files": [
     "dist"
   ],
@@ -13,7 +13,7 @@
     }
   },
   "scripts": {
-    "build": "tsc --noEmit && unbuild",
+    "build": "tsc --noEmit && unbuild && yarn toc",
     "test": "vitest",
     "toc": "npx markdown-toc README.md -i"
   },