react-event-tracking 1.0.0

package/README.md

@@ -0,0 +1,72 @@
+A convenient React context for tracking analytics events.
+
+## Features
+
+- **Nested Contexts**: Automatically merges parameters from parent providers.
+- **Zero Re-renders**: No need to wrap props in `useCallback`/`useMemo`.
+
+
+## Installation
+
+```
+npm install treact-event-tracking
+```
+```
+yarn add react-event-tracking
+```
+
+## Quickstart
+
+1. Define the root handler (e.g., send to GTM or API)
+```tsx
+import { AnalyticsRoot } from 'react-event-tracking';
+
+const Main = () => (
+  <AnalyticsRoot onEvent={(name, params) => gtag('event', name, params)}>
+    <App/>
+  </AnalyticsRoot>
+);
+``` 
+2. Wrap any component with shared parameters
+```tsx
+import { AnalyticsProvider } from 'react-event-tracking';
+
+const Dashboard = () => (
+  <AnalyticsProvider params={{ screen: 'dashboard' }}>
+    <DashboardView/>
+  </AnalyticsProvider>
+);
+```
+
+3. Send events conveniently. On button click, parameters will be merged.
+
+```tsx
+import { useAnalytics } from 'react-event-tracking';
+
+const MyButton = () => {
+  const { sendEvent } = useAnalytics();
+
+  return (
+    // event sent with parameters: { screen: 'dashboard', button_id: '123' }
+    <button onClick={() => sendEvent('click', { button_id: '123' })}>
+      Click me
+    </button>
+  );
+};
+```
+
+## Example
+
+### Page View
+
+```tsx
+export function PageView(props) {
+    const { sendEvent } = useAnalytics();
+
+    useEffect(() => {
+        sendEvent('page_view');
+    }, []);
+
+    return <>{props.children}</>
+}
+```

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "react-event-tracking",
+  "version": "1.0.0",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "scripts": {
+    "build": "tsc --noEmit && unbuild",
+    "test": "vitest"
+  },
+  "author": "",
+  "license": "ISC",
+  "description": "",
+  "devDependencies": {
+    "@testing-library/dom": "^10.4.1",
+    "@testing-library/react": "^16.3.2",
+    "@testing-library/user-event": "^14.6.1",
+    "@types/react": "^18.0.0",
+    "@types/react-dom": "^18.0.0",
+    "jsdom": "^28.1.0",
+    "react": "^18.0.0",
+    "react-dom": "^18.0.0",
+    "typescript": "^5.9.3",
+    "unbuild": "^3.6.1",
+    "vitest": "^4.0.18"
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0",
+    "react-dom": ">=18.0.0"
+  }
+}

package/src/index.tsx

@@ -0,0 +1,70 @@
+import React, {
+	useCallback,
+	useContext,
+	useMemo,
+	useRef,
+	type PropsWithChildren
+} from "react"
+
+export type AnalyticsParams = Record<string, any>
+
+interface AnalyticsContextValue {
+	sendEvent: (eventName: string, params?: AnalyticsParams) => void
+}
+
+export const AnalyticsContext = React.createContext<AnalyticsContextValue | null>(null)
+
+export const useAnalytics = () => {
+	const ctx = useContext(AnalyticsContext)
+	if (!ctx) {
+		throw new Error("useAnalytics must be used within AnalyticsRoot")
+	}
+
+	return ctx
+}
+
+export const AnalyticsRoot = ({
+	onEvent,
+	children
+}: PropsWithChildren<{
+	onEvent: (eventName: string, params?: AnalyticsParams) => void
+}>) => {
+	const onEventRef = useRef(onEvent)
+	onEventRef.current = onEvent
+
+	const sendEvent = useCallback((eventName: string, params?: AnalyticsParams) => {
+		onEventRef.current(eventName, params)
+	}, [])
+
+	const value = useMemo(() => ({ sendEvent }), [sendEvent])
+
+	return <AnalyticsContext.Provider value={value}>{children}</AnalyticsContext.Provider>
+}
+
+export const AnalyticsProvider = ({
+	params,
+	children
+}: PropsWithChildren<{
+	params: AnalyticsParams
+}>) => {
+	const ctx = useAnalytics()
+
+	const paramsRef = useRef(params)
+	paramsRef.current = params
+
+	const sendEvent = useCallback(
+		(eventName: string, eventParams?: AnalyticsParams) => {
+			const currentParams = paramsRef.current
+
+			ctx.sendEvent(eventName, {
+				...currentParams,
+				...eventParams
+			})
+		},
+		[ctx]
+	)
+
+	const value = useMemo(() => ({ sendEvent }), [sendEvent])
+
+	return <AnalyticsContext.Provider value={value}>{children}</AnalyticsContext.Provider>
+}

package/tests/context.test.tsx

@@ -0,0 +1,162 @@
+import { describe, it, expect, vi } from "vitest"
+import React from "react"
+import { render, screen } from "@testing-library/react"
+import userEvent from "@testing-library/user-event"
+import { AnalyticsRoot, AnalyticsProvider, useAnalytics } from "../src"
+
+const TestButton = ({
+	eventName,
+	params,
+	label = "Click me"
+}: {
+	eventName: string
+	params?: Record<string, any>
+	label?: string
+}) => {
+	const { sendEvent } = useAnalytics()
+	return <button onClick={() => sendEvent(eventName, params)}>{label}</button>
+}
+
+describe("Analytics Context", () => {
+	it("should send event from root", async () => {
+		const onEvent = vi.fn()
+
+		render(
+			<AnalyticsRoot onEvent={onEvent}>
+				<TestButton
+					eventName="test_click"
+					params={{ foo: "bar" }}
+					label="Root Click"
+				/>
+			</AnalyticsRoot>
+		)
+
+		await userEvent.click(screen.getByText("Root Click"))
+
+		expect(onEvent).toHaveBeenCalledTimes(1)
+		expect(onEvent).toHaveBeenCalledWith("test_click", { foo: "bar" })
+	})
+
+	it("should merge params from nested providers", async () => {
+		const onEvent = vi.fn()
+
+		render(
+			<AnalyticsRoot onEvent={onEvent}>
+				<AnalyticsProvider params={{ section: "header" }}>
+					<AnalyticsProvider params={{ item: "logo" }}>
+						<TestButton
+							eventName="logo_click"
+							params={{ action: "click" }}
+							label="Nested Click"
+						/>
+					</AnalyticsProvider>
+				</AnalyticsProvider>
+			</AnalyticsRoot>
+		)
+
+		await userEvent.click(screen.getByText("Nested Click"))
+
+		expect(onEvent).toHaveBeenCalledWith("logo_click", {
+			section: "header",
+			item: "logo",
+			action: "click"
+		})
+	})
+
+	it("should override params from child to parent", async () => {
+		const onEvent = vi.fn()
+
+		render(
+			<AnalyticsRoot onEvent={onEvent}>
+				<AnalyticsProvider params={{ page: "home", id: 1 }}>
+					{/* Переопределяем id */}
+					<AnalyticsProvider params={{ id: 2 }}>
+						<TestButton
+							eventName="click"
+							params={{ id: 3 }}
+							label="Override Click"
+						/>
+					</AnalyticsProvider>
+				</AnalyticsProvider>
+			</AnalyticsRoot>
+		)
+
+		await userEvent.click(screen.getByText("Override Click"))
+
+		expect(onEvent).toHaveBeenCalledWith("click", {
+			page: "home",
+			id: 3
+		})
+	})
+
+	it("should use latest params without re-rendering children", async () => {
+		const onEvent = vi.fn()
+
+		const Wrapper = ({ count }: { count: number }) => (
+			<AnalyticsProvider params={{ count }}>
+				<TestButton eventName="count_click" label="Rerender Click" />
+			</AnalyticsProvider>
+		)
+
+		const { rerender } = render(
+			<AnalyticsRoot onEvent={onEvent}>
+				<Wrapper count={1} />
+			</AnalyticsRoot>
+		)
+
+		await userEvent.click(screen.getByText("Rerender Click"))
+		expect(onEvent).toHaveBeenLastCalledWith("count_click", { count: 1 })
+
+		rerender(
+			<AnalyticsRoot onEvent={onEvent}>
+				<Wrapper count={2} />
+			</AnalyticsRoot>
+		)
+
+		await userEvent.click(screen.getByText("Rerender Click"))
+		expect(onEvent).toHaveBeenLastCalledWith("count_click", { count: 2 })
+	})
+
+	it("should NOT trigger re-render in consumers when params update (optimization check)", () => {
+		const renderFn = vi.fn()
+
+		const MemoChild = React.memo(() => {
+			useAnalytics()
+			renderFn()
+			return <div>Memo Child</div>
+		})
+
+		// eslint-disable-next-line react/display-name
+		MemoChild.displayName = "MemoChild"
+
+		const { rerender } = render(
+			<AnalyticsRoot onEvent={() => {}}>
+				<AnalyticsProvider params={{ val: 1 }}>
+					<MemoChild />
+				</AnalyticsProvider>
+			</AnalyticsRoot>
+		)
+
+		expect(renderFn).toHaveBeenCalledTimes(1)
+
+		rerender(
+			<AnalyticsRoot onEvent={() => {}}>
+				<AnalyticsProvider params={{ val: 2 }}>
+					<MemoChild />
+				</AnalyticsProvider>
+			</AnalyticsRoot>
+		)
+
+		expect(renderFn).toHaveBeenCalledTimes(1)
+	})
+
+	it("should throw error if used outside of AnalyticsRoot", () => {
+		const consoleSpy = vi.spyOn(console, "error").mockImplementation(() => {})
+
+		expect(() => {
+			render(<TestButton eventName="fail" label="Fail Click" />)
+		}).toThrow("useAnalytics must be used within AnalyticsRoot")
+
+		consoleSpy.mockRestore()
+	})
+})

package/tests/setup.ts

@@ -0,0 +1,6 @@
+import { afterEach } from 'vitest'
+import { cleanup } from '@testing-library/react'
+
+afterEach(() => {
+    cleanup()
+})  

package/tsconfig.json

@@ -0,0 +1,17 @@
+{
+	"compilerOptions": {
+		"target": "ES2020",
+		"module": "ESNext",
+		"jsx": "react-jsx",
+		"declaration": true,
+		"declarationMap": true,
+		"outDir": "./dist",
+		"rootDir": "./src",
+		"strict": true,
+		"moduleResolution": "node",
+		"esModuleInterop": true,
+		"skipLibCheck": true
+	},
+	"include": ["src/**/*"],
+	"exclude": ["node_modules", "dist"]
+}

package/vitest.config.ts

@@ -0,0 +1,10 @@
+import { defineConfig } from 'vitest/config'
+
+
+export default defineConfig({
+    test: {
+        globals: true,
+        environment: 'jsdom',
+        setupFiles: './tests/setup.ts',
+    },
+})