react-event-tracking 1.0.9 → 2.0.0

package/README.md

@@ -3,6 +3,7 @@ A convenient React context for tracking analytics events.
 
 ## Features
 
+- **Elegant Type-Safe Api**: enjoy a seamless dot-notation experience with full TypeScript autocompletion.
 - **Nested Contexts**: Automatically merges parameters from parent providers.
 - **Zero Re-renders**: No need to wrap props in `useCallback`/`useMemo`.
 - **Multiple Providers**: Send events to different analytics services.
@@ -15,6 +16,10 @@ A convenient React context for tracking analytics events.
 
 - [Installation](#installation)
 - [Quickstart](#quickstart)
+- [Usage Guide](#usage-guide)
+  * [Basic Hook](#basic-hook)
+  * [Typed Hook Factory](#typed-hook-factory)
+  * [Custom Handlers](#custom-handlers)
 - [Advanced Usage](#advanced-usage)
   * [Multiple Trackers & Factory](#multiple-trackers--factory)
   * [Filtering Events](#filtering-events)
@@ -47,6 +52,7 @@ const Main = () => (
   </TrackRoot>
 );
 ``` 
+
 2. Wrap any component with shared parameters
 ```tsx
 import { TrackProvider } from 'react-event-tracking';
@@ -58,29 +64,129 @@ const Dashboard = () => (
 );
 ```
 
-3. Send events conveniently. On button click, parameters will be merged.
+## Usage Guide
+
+### Basic Hook
+
+Use `useReactEventTracking` for simple event tracking  
+
 ```tsx
-import { useTracker } from 'react-event-tracking';
+import { useReactEventTracking } from 'react-event-tracking';
 
 const MyButton = () => {
-  const { sendEvent } = useTracker();
+  const { track } = useReactEventTracking();
 
   return (
-    <>
-    // event sent with parameters: { screen: 'dashboard', button_id: '123' }
-    <button onClick={() => sendEvent('click', { button_id: '123' })}>
+    {/* Option A: String } */}
+    <button onClick={() => track('click', { button_id: '123' })}>
+      Click me
+    </button>
+
+    {/* Option B: Object call */} 
+    <button onClick={() => track({ eventName: 'click', params: { button_id: '456' } })}>
       Click me
     </button>
 
-    {/* Option B: Object call */}                                                                                                           
-    <button onClick={() => sendEvent({ eventName: 'click', params: { button_id: '456' } })}>                                                
-      Click me too                                                                                                                          
-    </button>  
-    </>
   );
 };
 ```
 
+### Typed Hook Factory
+
+For a more convenient dot-notation syntax and full TypeScript support, create your own hook using `createReactEventTrackingHook`.
+
+1. Create a hook:
+```tsx
+import { createReactEventTrackingHook } from 'react-event-tracking';
+
+// LoadingScreen.tsx
+export type LoginScreenEvents = {
+	forgot_password: { from: "footer" | "button" }
+	logged_in: { timePassed: number }
+}
+
+type SystemEvents = {
+	app_updated: { previous_version: string; current_version: string }
+}
+
+// analytics.ts
+export type AnalyticsEvents = SystemEvents & {
+	login_screen: LoginScreenEvents
+}
+
+export const useTracking = createReactEventTrackingHook<AnalyticsEvents>();
+```
+
+2. Use it in your components:
+```tsx
+const LoginButton = () => {
+  const { track } = useTracking();
+
+  const handleLogin = () => {
+    // This call transforms into "login_screen.logged_in" event with parameters 
+    track.login_screen.logged_in({ timePassed: 3000 });
+  };
+  return (    
+    <button onClick={handleLogin}>
+      Login with Google
+    </button>
+  );
+};
+```
+
+### Custom Handlers
+
+Sometimes you need to expose more than just the `track` function, for example, a way to identify users. You can pass custom handlers to the factory.
+
+1. Define your handlers type and create the hook:
+```tsx
+type MyCustomHandlers = {
+  setUserId: (id: string) => void;
+}
+
+export const useTracking = createReactEventTrackingHook<AnalyticsEvents, MyCustomHandlers>();
+```
+
+2. Create a custom Root using [TrackRoot.factory](#multiple-trackers--factory):
+```tsx
+import { TrackRoot } from 'react-event-tracking';
+
+const CustomTrackRoot = TrackRoot.factory<MyCustomHandlers>({
+  onEvent: (name, params) => {
+    amplitude.logEvent(name, params);
+  },
+  customHandlers: {
+    setUserId: (id) => {
+      amplitude.setUserId(id);
+    }
+  }
+});
+
+const App = () => (
+  <CustomTrackRoot>
+    <Main />
+  </CustomTrackRoot>
+);
+```
+
+3. Use it in your components:
+```tsx
+const Profile = () => {
+  const { track, setUserId } = useTracking();
+
+const handleLogin = () => {
+    track.login_screen.logged_in({ timePassed: 3000 });
+    setUserId('user_123')
+  };
+
+  return (
+    <button onClick={handleLogin}>
+      Login
+    </button>
+  );
+}
+```
+
 ## Advanced Usage
 
 ### Multiple Trackers & Factory
@@ -91,13 +197,13 @@ Use `TrackRoot.factory` to create reusable tracker components:
 
 1. Create specific trackers
 ```tsx
-const TrackRootGoogle = TrackRoot.factory(
-  (name, params) => gtag('event', name, params)
-);
+const TrackRootGoogle = TrackRoot.factory({
+  onEvent: (name, params) => gtag('event', name, params)
+});
 
-const TrackRootAmplitude = TrackRoot.factory(
-  (name, params) => amplitude.logEvent(name, params)
-);
+const TrackRootAmplitude = TrackRoot.factory({
+  onEvent: (name, params) => amplitude.logEvent(name, params)
+});
 ```
 
 2. Compose them in your app
@@ -113,19 +219,19 @@ const App = () => (
 
 ### 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.
+You can control which events are sent to which provider using the `filter` prop 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),
-);
+const TrackRootGoogle = TrackRoot.factory({
+  onEvent: (name, params) => gtag('event', name, params),
+  filter: (name) => name.startsWith('page_')
+});
+
+// Amplitude: track everything
+const TrackRootAmplitude = TrackRoot.factory({
+  onEvent: (name, params) => amplitude.logEvent(name, params),
+});
 ```
 
 Compose them in your app:
@@ -142,16 +248,15 @@ const App = () => (
 
 ### 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`).
+You can modify the event name or parameters before they are sent to the handler using the `transform` prop 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) => {
+const AmplitudeUS = TrackRoot.factory({
+  onEvent: (name, params) => amplitude.logEvent(name, params),
+  transform: (name, params) => {
     if (params?.userRegion === 'EU') {
       // Remove PII (Personally Identifiable Information)
       const { userId, email, ...safeParams } = params;
@@ -162,7 +267,7 @@ const AmpltitudeUS = TrackRoot.factory(
     }
     return { eventName: name, params };
   }
-);
+});
 ```
 
 ### TypeScript Generics Support
@@ -170,13 +275,12 @@ const AmpltitudeUS = TrackRoot.factory(
 `TrackProvider` supports generics for strict typing of the passed parameters.
 
 ```tsx
-interface PageParams {
-  screenId: string;
-  isAuthorized: boolean;
+interface ScreenParams {
+  screen: "dashboard" | "authScreen"
 }
 
 const MyPage = () => (
-  <TrackProvider<PageParams> params={{ screenId: 'main', isAuthorized: true }}>
+  <TrackProvider<ScreenParams> params={{ screen: 'dashboard' }}>
     <Content />
   </TrackProvider>
 );
@@ -204,12 +308,12 @@ A common pattern is to layer data from global to specific. Here is how parameter
 </TrackRoot>
 
 // Inside AddToCartButton:
-const { sendEvent } = useTracker();
+const { track } = useReactEventTracking();
 
 // 4. EVENT: Action-specific data
 // When clicked, we only pass what changed right now.
 const handleClick = () => {
-  sendEvent('add_to_cart', { quantity: 1 });
+  track('add_to_cart', { quantity: 1 });
 };
 ```
 

package/dist/index.cjs

@@ -20,20 +20,27 @@ function parseEventArgs(eventNameOrObject, eventParams) {
 }
 
 const TrackContext = React__default.createContext(null);
-const useTracker = () => {
+const useReactEventTracking = () => {
   const ctx = React.useContext(TrackContext);
   if (!ctx) {
-    throw new Error("useTracker must be used within TrackRoot");
+    throw new Error("useReactEventTracking must be used within TrackRoot");
   }
   return ctx;
 };
 const EmptyParams = {};
-const TrackRootComponent = ({ onEvent, children, filter, transform }) => {
+const TrackRootComponent = ({
+  onEvent,
+  children,
+  filter,
+  transform,
+  customHandlers
+}) => {
   const parentCtx = React.useContext(TrackContext);
   const onEventRef = useFreshRef(onEvent);
   const filterRef = useFreshRef(filter);
   const transformRef = useFreshRef(transform);
-  function sendEvent(eventNameOrObject, eventParams) {
+  const customHandlersRef = useFreshRef(customHandlers);
+  function track(eventNameOrObject, eventParams) {
     const { eventName, params: incomingParams } = parseEventArgs(
       eventNameOrObject,
       eventParams
@@ -68,20 +75,44 @@ const TrackRootComponent = ({ onEvent, children, filter, transform }) => {
       }
     }
     if (parentCtx) {
-      parentCtx.sendEvent(eventName, incomingParams);
+      parentCtx.track(eventName, incomingParams);
     }
   }
-  const sendEventCached = React.useCallback(sendEvent, [parentCtx]);
-  const value = React.useMemo(() => ({ sendEvent: sendEventCached }), [sendEventCached]);
+  const value = React.useMemo(() => {
+    return new Proxy({}, {
+      get(_, prop) {
+        if (prop === track.name) return track;
+        const handler = customHandlersRef.current?.[prop];
+        if (typeof handler === "function") {
+          return (...args) => handler(...args);
+        }
+        return void 0;
+      },
+      has(_, prop) {
+        return prop === track.name || (customHandlersRef.current ? prop in customHandlersRef.current : false);
+      },
+      ownKeys() {
+        const customKeys = customHandlersRef.current ? Object.keys(customHandlersRef.current) : [];
+        return Array.from(/* @__PURE__ */ new Set([track.name, ...customKeys]));
+      },
+      getOwnPropertyDescriptor(_, prop) {
+        return {
+          enumerable: true,
+          configurable: true
+        };
+      }
+    });
+  }, [parentCtx]);
   return /* @__PURE__ */ React__default.createElement(TrackContext.Provider, { value }, children);
 };
-const factory = (onEvent, filter, transform) => {
+const factory = (args) => {
   return (props) => /* @__PURE__ */ React__default.createElement(
     TrackRootComponent,
     {
-      onEvent,
-      filter,
-      transform,
+      onEvent: args.onEvent,
+      filter: args.filter,
+      transform: args.transform,
+      customHandlers: args.customHandlers,
       ...props
     }
   );
@@ -91,21 +122,20 @@ const TrackProvider = ({
   params,
   children
 }) => {
-  const ctx = useTracker();
+  const ctx = useReactEventTracking();
   const paramsRef = useFreshRef(params);
-  function sendEvent(eventNameOrObject, eventParams) {
+  function track(eventNameOrObject, eventParams) {
     const { eventName, params: incomingParams } = parseEventArgs(
       eventNameOrObject,
       eventParams
     );
     const currentParams = paramsRef.current;
-    ctx.sendEvent(eventName, {
+    ctx.track(eventName, {
       ...currentParams,
       ...incomingParams
     });
   }
-  const sendEventCached = React.useCallback(sendEvent, [ctx]);
-  const value = React.useMemo(() => ({ sendEvent: sendEventCached }), [sendEventCached]);
+  const value = React.useMemo(() => ({ ...ctx, track }), [ctx]);
   return /* @__PURE__ */ React__default.createElement(TrackContext.Provider, { value }, children);
 };
 function useFreshRef(data) {
@@ -115,7 +145,7 @@ function useFreshRef(data) {
 }
 
 function useMountEvent(eventNameOrObject, eventParams) {
-  const { sendEvent } = useTracker();
+  const { track } = useReactEventTracking();
   const counterRef = React.useRef(0);
   const { eventName, params } = parseEventArgs(eventNameOrObject, eventParams);
   React.useEffect(() => {
@@ -123,11 +153,40 @@ function useMountEvent(eventNameOrObject, eventParams) {
       return;
     }
     counterRef.current++;
-    sendEvent(eventName, params);
+    track(eventName, params);
   }, []);
 }
 
+function createTracker(path = [], track) {
+  return new Proxy(() => {
+  }, {
+    get(_, prop) {
+      return createTracker([...path, prop], track);
+    },
+    apply(_, __, [params]) {
+      const eventName = path.join(".");
+      track(eventName, params);
+    }
+  });
+}
+
+function createReactEventTrackingHook() {
+  function useTracking(scope) {
+    const ctx = useReactEventTracking();
+    const tracker = React.useMemo(() => {
+      const prefix = scope ? [String(scope)] : [];
+      return {
+        ...ctx,
+        track: createTracker(prefix, ctx.track)
+      };
+    }, [ctx, scope]);
+    return tracker;
+  }
+  return useTracking;
+}
+
 exports.TrackProvider = TrackProvider;
 exports.TrackRoot = TrackRoot;
+exports.createReactEventTrackingHook = createReactEventTrackingHook;
 exports.useMountEvent = useMountEvent;
-exports.useTracker = useTracker;
+exports.useReactEventTracking = useReactEventTracking;

package/dist/index.d.cts

@@ -2,13 +2,19 @@ import * as react_jsx_runtime from 'react/jsx-runtime';
 import { PropsWithChildren } from 'react';
 
 type EventParams<T extends Record<string, any> = Record<string, any>> = T;
-interface TrackContextValue {
-    sendEvent(eventName: string, params?: EventParams): void;
-    sendEvent(event: EventObject): void;
+type EventsMap = Record<string, any>;
+type AnyFunction = (...args: any[]) => any;
+type IsLeaf<T> = T extends Record<string, any> ? (keyof T extends never ? true : T[keyof T] extends Record<string, any> ? false : true) : true;
+type FlatTracker<T> = {
+    [K in keyof T]: IsLeaf<T[K]> extends true ? (params: T[K]) => void : FlatTracker<T[K]>;
+};
+interface TrackContextValueLegacy {
+    track(eventName: string, params?: EventParams): void;
+    track(event: EventObject): void;
 }
-type EventObject = {
-    eventName: string;
-    params?: EventParams;
+type EventObject<E extends string = string, P = EventParams> = {
+    eventName: E;
+    params?: P;
 };
 type EventFilter = (eventName: string, params: EventParams) => boolean;
 type TransformedEvent = {
@@ -17,14 +23,15 @@ type TransformedEvent = {
 };
 type EventTransformer = (eventName: string, params: EventParams) => TransformedEvent;
 
-declare const useTracker: () => TrackContextValue;
-type TrackRootProps = PropsWithChildren<{
+declare const useReactEventTracking: () => TrackContextValueLegacy;
+type TrackRootProps<CustomHandlers extends Record<string, AnyFunction>> = PropsWithChildren<{
     onEvent: (eventName: string, params: EventParams) => void;
     filter?: EventFilter;
     transform?: EventTransformer;
+    customHandlers?: CustomHandlers;
 }>;
-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 TrackRoot: (<CustomHandlers extends Record<string, AnyFunction> = {}>({ onEvent, children, filter, transform, customHandlers }: TrackRootProps<CustomHandlers>) => react_jsx_runtime.JSX.Element) & {
+    factory: <T extends Record<string, AnyFunction> = {}>(args: TrackRootProps<T>) => (props: Omit<TrackRootProps<T>, "onEvent" | "filter" | "transform" | "customHandlers">) => react_jsx_runtime.JSX.Element;
 };
 declare const TrackProvider: <T extends Record<string, any>>({ params, children }: PropsWithChildren<{
     params: EventParams<T>;
@@ -33,4 +40,13 @@ declare const TrackProvider: <T extends Record<string, any>>({ params, children
 declare function useMountEvent(eventName: string, params?: EventParams): void;
 declare function useMountEvent(event: EventObject): void;
 
-export { TrackProvider, TrackRoot, useMountEvent, useTracker };
+declare function createReactEventTrackingHook<Map extends EventsMap, CustomHandlers extends Record<string, AnyFunction> = {}>(): {
+    (): {
+        track: FlatTracker<Map>;
+    } & CustomHandlers;
+    <K extends keyof Map>(scope: K): {
+        track: FlatTracker<Map>[K];
+    } & CustomHandlers;
+};
+
+export { TrackProvider, TrackRoot, createReactEventTrackingHook, useMountEvent, useReactEventTracking };

package/dist/index.d.mts

@@ -2,13 +2,19 @@ import * as react_jsx_runtime from 'react/jsx-runtime';
 import { PropsWithChildren } from 'react';
 
 type EventParams<T extends Record<string, any> = Record<string, any>> = T;
-interface TrackContextValue {
-    sendEvent(eventName: string, params?: EventParams): void;
-    sendEvent(event: EventObject): void;
+type EventsMap = Record<string, any>;
+type AnyFunction = (...args: any[]) => any;
+type IsLeaf<T> = T extends Record<string, any> ? (keyof T extends never ? true : T[keyof T] extends Record<string, any> ? false : true) : true;
+type FlatTracker<T> = {
+    [K in keyof T]: IsLeaf<T[K]> extends true ? (params: T[K]) => void : FlatTracker<T[K]>;
+};
+interface TrackContextValueLegacy {
+    track(eventName: string, params?: EventParams): void;
+    track(event: EventObject): void;
 }
-type EventObject = {
-    eventName: string;
-    params?: EventParams;
+type EventObject<E extends string = string, P = EventParams> = {
+    eventName: E;
+    params?: P;
 };
 type EventFilter = (eventName: string, params: EventParams) => boolean;
 type TransformedEvent = {
@@ -17,14 +23,15 @@ type TransformedEvent = {
 };
 type EventTransformer = (eventName: string, params: EventParams) => TransformedEvent;
 
-declare const useTracker: () => TrackContextValue;
-type TrackRootProps = PropsWithChildren<{
+declare const useReactEventTracking: () => TrackContextValueLegacy;
+type TrackRootProps<CustomHandlers extends Record<string, AnyFunction>> = PropsWithChildren<{
     onEvent: (eventName: string, params: EventParams) => void;
     filter?: EventFilter;
     transform?: EventTransformer;
+    customHandlers?: CustomHandlers;
 }>;
-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 TrackRoot: (<CustomHandlers extends Record<string, AnyFunction> = {}>({ onEvent, children, filter, transform, customHandlers }: TrackRootProps<CustomHandlers>) => react_jsx_runtime.JSX.Element) & {
+    factory: <T extends Record<string, AnyFunction> = {}>(args: TrackRootProps<T>) => (props: Omit<TrackRootProps<T>, "onEvent" | "filter" | "transform" | "customHandlers">) => react_jsx_runtime.JSX.Element;
 };
 declare const TrackProvider: <T extends Record<string, any>>({ params, children }: PropsWithChildren<{
     params: EventParams<T>;
@@ -33,4 +40,13 @@ declare const TrackProvider: <T extends Record<string, any>>({ params, children
 declare function useMountEvent(eventName: string, params?: EventParams): void;
 declare function useMountEvent(event: EventObject): void;
 
-export { TrackProvider, TrackRoot, useMountEvent, useTracker };
+declare function createReactEventTrackingHook<Map extends EventsMap, CustomHandlers extends Record<string, AnyFunction> = {}>(): {
+    (): {
+        track: FlatTracker<Map>;
+    } & CustomHandlers;
+    <K extends keyof Map>(scope: K): {
+        track: FlatTracker<Map>[K];
+    } & CustomHandlers;
+};
+
+export { TrackProvider, TrackRoot, createReactEventTrackingHook, useMountEvent, useReactEventTracking };

package/dist/index.d.ts

@@ -2,13 +2,19 @@ import * as react_jsx_runtime from 'react/jsx-runtime';
 import { PropsWithChildren } from 'react';
 
 type EventParams<T extends Record<string, any> = Record<string, any>> = T;
-interface TrackContextValue {
-    sendEvent(eventName: string, params?: EventParams): void;
-    sendEvent(event: EventObject): void;
+type EventsMap = Record<string, any>;
+type AnyFunction = (...args: any[]) => any;
+type IsLeaf<T> = T extends Record<string, any> ? (keyof T extends never ? true : T[keyof T] extends Record<string, any> ? false : true) : true;
+type FlatTracker<T> = {
+    [K in keyof T]: IsLeaf<T[K]> extends true ? (params: T[K]) => void : FlatTracker<T[K]>;
+};
+interface TrackContextValueLegacy {
+    track(eventName: string, params?: EventParams): void;
+    track(event: EventObject): void;
 }
-type EventObject = {
-    eventName: string;
-    params?: EventParams;
+type EventObject<E extends string = string, P = EventParams> = {
+    eventName: E;
+    params?: P;
 };
 type EventFilter = (eventName: string, params: EventParams) => boolean;
 type TransformedEvent = {
@@ -17,14 +23,15 @@ type TransformedEvent = {
 };
 type EventTransformer = (eventName: string, params: EventParams) => TransformedEvent;
 
-declare const useTracker: () => TrackContextValue;
-type TrackRootProps = PropsWithChildren<{
+declare const useReactEventTracking: () => TrackContextValueLegacy;
+type TrackRootProps<CustomHandlers extends Record<string, AnyFunction>> = PropsWithChildren<{
     onEvent: (eventName: string, params: EventParams) => void;
     filter?: EventFilter;
     transform?: EventTransformer;
+    customHandlers?: CustomHandlers;
 }>;
-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 TrackRoot: (<CustomHandlers extends Record<string, AnyFunction> = {}>({ onEvent, children, filter, transform, customHandlers }: TrackRootProps<CustomHandlers>) => react_jsx_runtime.JSX.Element) & {
+    factory: <T extends Record<string, AnyFunction> = {}>(args: TrackRootProps<T>) => (props: Omit<TrackRootProps<T>, "onEvent" | "filter" | "transform" | "customHandlers">) => react_jsx_runtime.JSX.Element;
 };
 declare const TrackProvider: <T extends Record<string, any>>({ params, children }: PropsWithChildren<{
     params: EventParams<T>;
@@ -33,4 +40,13 @@ declare const TrackProvider: <T extends Record<string, any>>({ params, children
 declare function useMountEvent(eventName: string, params?: EventParams): void;
 declare function useMountEvent(event: EventObject): void;
 
-export { TrackProvider, TrackRoot, useMountEvent, useTracker };
+declare function createReactEventTrackingHook<Map extends EventsMap, CustomHandlers extends Record<string, AnyFunction> = {}>(): {
+    (): {
+        track: FlatTracker<Map>;
+    } & CustomHandlers;
+    <K extends keyof Map>(scope: K): {
+        track: FlatTracker<Map>[K];
+    } & CustomHandlers;
+};
+
+export { TrackProvider, TrackRoot, createReactEventTrackingHook, useMountEvent, useReactEventTracking };

package/dist/index.mjs

@@ -1,4 +1,4 @@
-import React, { useContext, useCallback, useMemo, useRef, useEffect } from 'react';
+import React, { useContext, useMemo, useRef, useEffect } from 'react';
 
 function parseEventArgs(eventNameOrObject, eventParams) {
   if (typeof eventNameOrObject === "object") {
@@ -14,20 +14,27 @@ function parseEventArgs(eventNameOrObject, eventParams) {
 }
 
 const TrackContext = React.createContext(null);
-const useTracker = () => {
+const useReactEventTracking = () => {
   const ctx = useContext(TrackContext);
   if (!ctx) {
-    throw new Error("useTracker must be used within TrackRoot");
+    throw new Error("useReactEventTracking must be used within TrackRoot");
   }
   return ctx;
 };
 const EmptyParams = {};
-const TrackRootComponent = ({ onEvent, children, filter, transform }) => {
+const TrackRootComponent = ({
+  onEvent,
+  children,
+  filter,
+  transform,
+  customHandlers
+}) => {
   const parentCtx = useContext(TrackContext);
   const onEventRef = useFreshRef(onEvent);
   const filterRef = useFreshRef(filter);
   const transformRef = useFreshRef(transform);
-  function sendEvent(eventNameOrObject, eventParams) {
+  const customHandlersRef = useFreshRef(customHandlers);
+  function track(eventNameOrObject, eventParams) {
     const { eventName, params: incomingParams } = parseEventArgs(
       eventNameOrObject,
       eventParams
@@ -62,20 +69,44 @@ const TrackRootComponent = ({ onEvent, children, filter, transform }) => {
       }
     }
     if (parentCtx) {
-      parentCtx.sendEvent(eventName, incomingParams);
+      parentCtx.track(eventName, incomingParams);
     }
   }
-  const sendEventCached = useCallback(sendEvent, [parentCtx]);
-  const value = useMemo(() => ({ sendEvent: sendEventCached }), [sendEventCached]);
+  const value = useMemo(() => {
+    return new Proxy({}, {
+      get(_, prop) {
+        if (prop === track.name) return track;
+        const handler = customHandlersRef.current?.[prop];
+        if (typeof handler === "function") {
+          return (...args) => handler(...args);
+        }
+        return void 0;
+      },
+      has(_, prop) {
+        return prop === track.name || (customHandlersRef.current ? prop in customHandlersRef.current : false);
+      },
+      ownKeys() {
+        const customKeys = customHandlersRef.current ? Object.keys(customHandlersRef.current) : [];
+        return Array.from(/* @__PURE__ */ new Set([track.name, ...customKeys]));
+      },
+      getOwnPropertyDescriptor(_, prop) {
+        return {
+          enumerable: true,
+          configurable: true
+        };
+      }
+    });
+  }, [parentCtx]);
   return /* @__PURE__ */ React.createElement(TrackContext.Provider, { value }, children);
 };
-const factory = (onEvent, filter, transform) => {
+const factory = (args) => {
   return (props) => /* @__PURE__ */ React.createElement(
     TrackRootComponent,
     {
-      onEvent,
-      filter,
-      transform,
+      onEvent: args.onEvent,
+      filter: args.filter,
+      transform: args.transform,
+      customHandlers: args.customHandlers,
       ...props
     }
   );
@@ -85,21 +116,20 @@ const TrackProvider = ({
   params,
   children
 }) => {
-  const ctx = useTracker();
+  const ctx = useReactEventTracking();
   const paramsRef = useFreshRef(params);
-  function sendEvent(eventNameOrObject, eventParams) {
+  function track(eventNameOrObject, eventParams) {
     const { eventName, params: incomingParams } = parseEventArgs(
       eventNameOrObject,
       eventParams
     );
     const currentParams = paramsRef.current;
-    ctx.sendEvent(eventName, {
+    ctx.track(eventName, {
       ...currentParams,
       ...incomingParams
     });
   }
-  const sendEventCached = useCallback(sendEvent, [ctx]);
-  const value = useMemo(() => ({ sendEvent: sendEventCached }), [sendEventCached]);
+  const value = useMemo(() => ({ ...ctx, track }), [ctx]);
   return /* @__PURE__ */ React.createElement(TrackContext.Provider, { value }, children);
 };
 function useFreshRef(data) {
@@ -109,7 +139,7 @@ function useFreshRef(data) {
 }
 
 function useMountEvent(eventNameOrObject, eventParams) {
-  const { sendEvent } = useTracker();
+  const { track } = useReactEventTracking();
   const counterRef = useRef(0);
   const { eventName, params } = parseEventArgs(eventNameOrObject, eventParams);
   useEffect(() => {
@@ -117,8 +147,36 @@ function useMountEvent(eventNameOrObject, eventParams) {
       return;
     }
     counterRef.current++;
-    sendEvent(eventName, params);
+    track(eventName, params);
   }, []);
 }
 
-export { TrackProvider, TrackRoot, useMountEvent, useTracker };
+function createTracker(path = [], track) {
+  return new Proxy(() => {
+  }, {
+    get(_, prop) {
+      return createTracker([...path, prop], track);
+    },
+    apply(_, __, [params]) {
+      const eventName = path.join(".");
+      track(eventName, params);
+    }
+  });
+}
+
+function createReactEventTrackingHook() {
+  function useTracking(scope) {
+    const ctx = useReactEventTracking();
+    const tracker = useMemo(() => {
+      const prefix = scope ? [String(scope)] : [];
+      return {
+        ...ctx,
+        track: createTracker(prefix, ctx.track)
+      };
+    }, [ctx, scope]);
+    return tracker;
+  }
+  return useTracking;
+}
+
+export { TrackProvider, TrackRoot, createReactEventTrackingHook, useMountEvent, useReactEventTracking };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-event-tracking",
-  "version": "1.0.9",
+  "version": "2.0.0",
   "files": [
     "dist"
   ],