react-event-tracking 1.0.2 → 1.0.4

package/README.md

@@ -1,4 +1,6 @@
-A convenient React context for tracking analytics events.
+
+# react-event-tracking [![NPM Version](https://img.shields.io/npm/v/react-event-tracking)](https://www.npmjs.com/package/react-event-tracking)
+A convenient React context for tracking analytics events. 
 
 ## Features
 
@@ -9,7 +11,7 @@ A convenient React context for tracking analytics events.
 ## Installation
 
 ```
-npm install treact-event-tracking
+npm install react-event-tracking
 ```
 ```
 yarn add react-event-tracking
@@ -17,7 +19,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';
 
@@ -55,18 +57,66 @@ const MyButton = () => {
 };
 ```
 
-## Example
+## Best Practices
 
-### Page View
+A common pattern is to layer data from global to specific. Here is how parameters merge:
 
 ```tsx
-export function PageView(props) {
-    const { sendEvent } = useTracker();
+// 1. ROOT: Global data (App Version, Environment)
+<TrackRoot onEvent={handleEvent} initialParams={{ 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>
+</TrackRoot>
 
-    useEffect(() => {
-        sendEvent('page_view');
-    }, []);
+// Inside AddToCartButton:
+const { sendEvent } = useTracker();
 
-    return <>{props.children}</>
+// 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   
+
+Sends an event when the component mounts.
+
+```tsx
+import { useMountEvent } from 'react-event-tracking';
+
+export function DashboardScreen(props) {
+    useMountEvent('page_view', { screen: 'dashboard' });
+
+    return <div>Dashboard</div>;
+}
+```

package/dist/index.cjs

@@ -16,7 +16,8 @@ const useTracker = () => {
 };
 const TrackRoot = ({
   onEvent,
-  children
+  children,
+  initialParams
 }) => {
   const onEventRef = React.useRef(onEvent);
   onEventRef.current = onEvent;
@@ -24,7 +25,7 @@ const TrackRoot = ({
     onEventRef.current(eventName, params);
   }, []);
   const value = React.useMemo(() => ({ sendEvent }), [sendEvent]);
-  return /* @__PURE__ */ React__default.createElement(TrackContext.Provider, { value }, children);
+  return /* @__PURE__ */ React__default.createElement(TrackContext.Provider, { value }, /* @__PURE__ */ React__default.createElement(TrackProvider, { params: initialParams || {} }, children));
 };
 const TrackProvider = ({
   params,
@@ -47,6 +48,19 @@ const TrackProvider = ({
   return /* @__PURE__ */ React__default.createElement(TrackContext.Provider, { value }, children);
 };
 
+function useMountEvent(eventName, params) {
+  const { sendEvent } = useTracker();
+  const counterRef = React.useRef(0);
+  React.useEffect(() => {
+    if (counterRef.current > 0) {
+      return;
+    }
+    counterRef.current++;
+    sendEvent(eventName, params);
+  }, []);
+}
+
 exports.TrackProvider = TrackProvider;
 exports.TrackRoot = TrackRoot;
+exports.useMountEvent = useMountEvent;
 exports.useTracker = useTracker;

package/dist/index.d.cts

@@ -2,15 +2,19 @@ import * as react_jsx_runtime from 'react/jsx-runtime';
 import { PropsWithChildren } from 'react';
 
 type EventParams = Record<string, any>;
-interface TrackContextValue {
+type TrackContextValue = {
     sendEvent: (eventName: string, params?: EventParams) => void;
-}
+};
+
 declare const useTracker: () => TrackContextValue;
-declare const TrackRoot: ({ onEvent, children }: PropsWithChildren<{
+declare const TrackRoot: ({ onEvent, children, initialParams }: PropsWithChildren<{
     onEvent: (eventName: string, params?: EventParams) => void;
+    initialParams?: EventParams;
 }>) => react_jsx_runtime.JSX.Element;
 declare const TrackProvider: ({ params, children }: PropsWithChildren<{
     params: EventParams;
 }>) => react_jsx_runtime.JSX.Element;
 
-export { TrackProvider, TrackRoot, useTracker };
+declare function useMountEvent(eventName: string, params?: EventParams): void;
+
+export { TrackProvider, TrackRoot, useMountEvent, useTracker };

package/dist/index.d.mts

@@ -2,15 +2,19 @@ import * as react_jsx_runtime from 'react/jsx-runtime';
 import { PropsWithChildren } from 'react';
 
 type EventParams = Record<string, any>;
-interface TrackContextValue {
+type TrackContextValue = {
     sendEvent: (eventName: string, params?: EventParams) => void;
-}
+};
+
 declare const useTracker: () => TrackContextValue;
-declare const TrackRoot: ({ onEvent, children }: PropsWithChildren<{
+declare const TrackRoot: ({ onEvent, children, initialParams }: PropsWithChildren<{
     onEvent: (eventName: string, params?: EventParams) => void;
+    initialParams?: EventParams;
 }>) => react_jsx_runtime.JSX.Element;
 declare const TrackProvider: ({ params, children }: PropsWithChildren<{
     params: EventParams;
 }>) => react_jsx_runtime.JSX.Element;
 
-export { TrackProvider, TrackRoot, useTracker };
+declare function useMountEvent(eventName: string, params?: EventParams): void;
+
+export { TrackProvider, TrackRoot, useMountEvent, useTracker };

package/dist/index.d.ts

@@ -2,15 +2,19 @@ import * as react_jsx_runtime from 'react/jsx-runtime';
 import { PropsWithChildren } from 'react';
 
 type EventParams = Record<string, any>;
-interface TrackContextValue {
+type TrackContextValue = {
     sendEvent: (eventName: string, params?: EventParams) => void;
-}
+};
+
 declare const useTracker: () => TrackContextValue;
-declare const TrackRoot: ({ onEvent, children }: PropsWithChildren<{
+declare const TrackRoot: ({ onEvent, children, initialParams }: PropsWithChildren<{
     onEvent: (eventName: string, params?: EventParams) => void;
+    initialParams?: EventParams;
 }>) => react_jsx_runtime.JSX.Element;
 declare const TrackProvider: ({ params, children }: PropsWithChildren<{
     params: EventParams;
 }>) => react_jsx_runtime.JSX.Element;
 
-export { TrackProvider, TrackRoot, useTracker };
+declare function useMountEvent(eventName: string, params?: EventParams): void;
+
+export { TrackProvider, TrackRoot, useMountEvent, useTracker };

package/dist/index.mjs

@@ -1,4 +1,4 @@
-import React, { useContext, useRef, useCallback, useMemo } from 'react';
+import React, { useContext, useRef, useCallback, useMemo, useEffect } from 'react';
 
 const TrackContext = React.createContext(null);
 const useTracker = () => {
@@ -10,7 +10,8 @@ const useTracker = () => {
 };
 const TrackRoot = ({
   onEvent,
-  children
+  children,
+  initialParams
 }) => {
   const onEventRef = useRef(onEvent);
   onEventRef.current = onEvent;
@@ -18,7 +19,7 @@ const TrackRoot = ({
     onEventRef.current(eventName, params);
   }, []);
   const value = useMemo(() => ({ sendEvent }), [sendEvent]);
-  return /* @__PURE__ */ React.createElement(TrackContext.Provider, { value }, children);
+  return /* @__PURE__ */ React.createElement(TrackContext.Provider, { value }, /* @__PURE__ */ React.createElement(TrackProvider, { params: initialParams || {} }, children));
 };
 const TrackProvider = ({
   params,
@@ -41,4 +42,16 @@ const TrackProvider = ({
   return /* @__PURE__ */ React.createElement(TrackContext.Provider, { value }, children);
 };
 
-export { TrackProvider, TrackRoot, useTracker };
+function useMountEvent(eventName, params) {
+  const { sendEvent } = useTracker();
+  const counterRef = useRef(0);
+  useEffect(() => {
+    if (counterRef.current > 0) {
+      return;
+    }
+    counterRef.current++;
+    sendEvent(eventName, params);
+  }, []);
+}
+
+export { TrackProvider, TrackRoot, useMountEvent, useTracker };

package/package.json

@@ -1,9 +1,10 @@
 {
   "name": "react-event-tracking",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "files": [
     "dist"
   ],
+  "repository": "git@github.com:zeeeeby/react-event-tracking.git",
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -13,7 +14,8 @@
   },
   "scripts": {
     "build": "tsc --noEmit && unbuild",
-    "test": "vitest"
+    "test": "vitest",
+    "toc": "npx markdown-toc README.md -i"
   },
   "author": "",
   "license": "ISC",