@availity/mui-event-tracker 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+This file was generated using [@jscutlery/semver](https://github.com/jscutlery/semver).
+
+## 0.1.0 (2024-07-18)
+
+### Dependency Updates
+
+* `mui-button` updated to version `0.1.0`
+* `mui-form-utils` updated to version `0.1.0`
+* `mui-layout` updated to version `0.1.0`
+* `mui-menu` updated to version `0.1.0`
+* `mui-textfield` updated to version `0.1.0`
+* `mui-typography` updated to version `0.1.0`
+
+### Features
+
+* **mui-event-tracker:** add event tracker component ([5be1273](https://github.com/Availity/element/commit/5be12734a09a53f786579192fd54da4936855086))

package/README.md

@@ -0,0 +1,61 @@
+# @availity/mui-event-tracker
+
+> Availity MUI EventTracker component to be used with @availity/element design system.
+
+[![Version](https://img.shields.io/npm/v/@availity/mui-event-tracker.svg?style=for-the-badge)](https://www.npmjs.com/package/@availity/mui-event-tracker)
+[![NPM Downloads](https://img.shields.io/npm/dt/@availity/mui-event-tracker.svg?style=for-the-badge)](https://www.npmjs.com/package/@availity/mui-event-tracker)
+[![Dependency Status](https://img.shields.io/librariesio/release/npm/@availity/mui-event-tracker?style=for-the-badge)](https://github.com/Availity/element/blob/main/packages/mui-event-tracker/package.json)
+
+## Documentation
+
+This package extends the MUI EventTracker component: [MUI EventTracker Docs](https://mui.com/components/event-tracker/)
+
+Live demo and documentation in our [Storybook](https://availity.github.io/element/?path=/docs/components-event-tracker-introduction--docs)
+
+Availity standards for design and usage can be found in the [Availity Design Guide](https://zeroheight.com/2e36e50c7)
+
+## Installation
+
+### Import Through @availity/element (Recommended)
+
+#### NPM
+
+```bash
+npm install @availity/element
+```
+
+#### Yarn
+
+```bash
+yarn add @availity/element
+```
+
+### Direct Import
+
+#### NPM
+
+_This package has a few peer dependencies. Add `@mui/material` & `@emotion/react` to your project if not already installed._
+
+```bash
+npm install @availity/mui-event-tracker
+```
+
+#### Yarn
+
+```bash
+yarn add @availity/mui-event-tracker
+```
+
+### Usage
+
+#### Import through @availity/element
+
+```tsx
+import { EventTracker } from '@availity/element';
+```
+
+#### Direct import
+
+```tsx
+import { EventTracker } from '@availity/mui-event-tracker';
+```

package/dist/index.d.mts

@@ -0,0 +1,35 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import React from 'react';
+import { AvAnalytics } from '@availity/analytics-core';
+
+type EventTrackerProps = {
+    /** */
+    children?: React.ReactNode;
+    /** An array of plugins to pass to the underlying AvAnalytics class instance. */
+    plugins?: any[];
+    /** Enable or disable page tracking on initialization.
+     * @default true
+     */
+    pageTracking?: boolean;
+    /** Enable or disable auto tracking on initialization.
+     * @default true
+     */
+    autoTrack?: boolean;
+    /** Enable or disable recursive functionality on initialization.
+     * @default true
+     */
+    recursive?: boolean;
+    /** Customize the prefix used for data event tracker attributes used for auto tracking.
+     * @default 'data-analytics'
+     */
+    attributePrefix?: string;
+    /** Array of event modifiers enabling you to use other keywords for action instead of click for event type matching.
+     * @default ['action']
+     */
+    eventModifiers?: any[];
+};
+declare const EventTrackerContext: React.Context<AvAnalytics | null>;
+declare const useEventTracker: () => AvAnalytics;
+declare const EventTrackerProvider: ({ children, plugins, pageTracking, autoTrack, recursive, attributePrefix, eventModifiers, }: EventTrackerProps) => react_jsx_runtime.JSX.Element;
+
+export { EventTrackerContext, type EventTrackerProps, EventTrackerProvider, useEventTracker };

package/dist/index.d.ts

@@ -0,0 +1,35 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import React from 'react';
+import { AvAnalytics } from '@availity/analytics-core';
+
+type EventTrackerProps = {
+    /** */
+    children?: React.ReactNode;
+    /** An array of plugins to pass to the underlying AvAnalytics class instance. */
+    plugins?: any[];
+    /** Enable or disable page tracking on initialization.
+     * @default true
+     */
+    pageTracking?: boolean;
+    /** Enable or disable auto tracking on initialization.
+     * @default true
+     */
+    autoTrack?: boolean;
+    /** Enable or disable recursive functionality on initialization.
+     * @default true
+     */
+    recursive?: boolean;
+    /** Customize the prefix used for data event tracker attributes used for auto tracking.
+     * @default 'data-analytics'
+     */
+    attributePrefix?: string;
+    /** Array of event modifiers enabling you to use other keywords for action instead of click for event type matching.
+     * @default ['action']
+     */
+    eventModifiers?: any[];
+};
+declare const EventTrackerContext: React.Context<AvAnalytics | null>;
+declare const useEventTracker: () => AvAnalytics;
+declare const EventTrackerProvider: ({ children, plugins, pageTracking, autoTrack, recursive, attributePrefix, eventModifiers, }: EventTrackerProps) => react_jsx_runtime.JSX.Element;
+
+export { EventTrackerContext, type EventTrackerProps, EventTrackerProvider, useEventTracker };

package/dist/index.js

@@ -0,0 +1,68 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var src_exports = {};
+__export(src_exports, {
+  EventTrackerContext: () => EventTrackerContext,
+  EventTrackerProvider: () => EventTrackerProvider,
+  useEventTracker: () => useEventTracker
+});
+module.exports = __toCommonJS(src_exports);
+
+// src/lib/EventTracker.tsx
+var import_react = require("react");
+var import_analytics_core = require("@availity/analytics-core");
+var import_jsx_runtime = require("react/jsx-runtime");
+var EventTrackerContext = (0, import_react.createContext)(null);
+var useEventTracker = () => {
+  const ctx = (0, import_react.useContext)(EventTrackerContext);
+  if (!ctx) {
+    throw new Error("useEventTracker must be used within an EventTrackerProvider");
+  }
+  return ctx;
+};
+var EventTrackerProvider = ({
+  children,
+  plugins,
+  pageTracking = true,
+  autoTrack = true,
+  recursive = true,
+  attributePrefix = "data-analytics",
+  eventModifiers = ["action"]
+}) => {
+  const analytics = (0, import_react.useMemo)(
+    () => new import_analytics_core.AvAnalytics(plugins, Promise, pageTracking, autoTrack, { recursive, attributePrefix, eventModifiers }),
+    [attributePrefix, autoTrack, eventModifiers, pageTracking, plugins, recursive]
+  );
+  (0, import_react.useEffect)(() => {
+    analytics.init();
+    if (pageTracking) {
+      analytics.trackPageView();
+    }
+    return () => analytics.stopAutoTrack();
+  }, [analytics, pageTracking]);
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(EventTrackerContext.Provider, { value: analytics, children });
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  EventTrackerContext,
+  EventTrackerProvider,
+  useEventTracker
+});

package/dist/index.mjs

@@ -0,0 +1,39 @@
+// src/lib/EventTracker.tsx
+import { createContext, useContext, useEffect, useMemo } from "react";
+import { AvAnalytics } from "@availity/analytics-core";
+import { jsx } from "react/jsx-runtime";
+var EventTrackerContext = createContext(null);
+var useEventTracker = () => {
+  const ctx = useContext(EventTrackerContext);
+  if (!ctx) {
+    throw new Error("useEventTracker must be used within an EventTrackerProvider");
+  }
+  return ctx;
+};
+var EventTrackerProvider = ({
+  children,
+  plugins,
+  pageTracking = true,
+  autoTrack = true,
+  recursive = true,
+  attributePrefix = "data-analytics",
+  eventModifiers = ["action"]
+}) => {
+  const analytics = useMemo(
+    () => new AvAnalytics(plugins, Promise, pageTracking, autoTrack, { recursive, attributePrefix, eventModifiers }),
+    [attributePrefix, autoTrack, eventModifiers, pageTracking, plugins, recursive]
+  );
+  useEffect(() => {
+    analytics.init();
+    if (pageTracking) {
+      analytics.trackPageView();
+    }
+    return () => analytics.stopAutoTrack();
+  }, [analytics, pageTracking]);
+  return /* @__PURE__ */ jsx(EventTrackerContext.Provider, { value: analytics, children });
+};
+export {
+  EventTrackerContext,
+  EventTrackerProvider,
+  useEventTracker
+};

package/introduction.stories.mdx

@@ -0,0 +1,7 @@
+import { Markdown } from '@storybook/blocks';
+import { Meta } from '@storybook/addon-docs';
+import ReadMe from './README.md?raw';
+
+<Meta title="Components/EventTracker/Introduction" />
+
+<Markdown>{ReadMe}</Markdown>

package/jest.config.js

@@ -0,0 +1,12 @@
+const global = require('../../jest.config.global');
+
+const esModules = ['uuid'];
+
+module.exports = {
+  ...global,
+  displayName: 'event-tracker',
+  coverageDirectory: '../../coverage/event-tracker',
+  transformIgnorePatterns: [
+    `/node_modules/(?!${esModules})`
+  ]
+};

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@availity/mui-event-tracker",
+  "version": "0.1.0",
+  "description": "Availity MUI EventTracker Component - part of the @availity/element design system",
+  "keywords": [
+    "react",
+    "typescript",
+    "availity",
+    "mui"
+  ],
+  "homepage": "https://availity.github.io/element/?path=/docs/components-event-tracker-introduction--docs",
+  "bugs": {
+    "url": "https://github.com/Availity/element/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Availity/element.git",
+    "directory": "packages/event-tracker"
+  },
+  "license": "MIT",
+  "author": "Availity Developers <AVOSS@availity.com>",
+  "browser": "./dist/index.js",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts",
+    "dev": "tsup src/index.ts --format esm,cjs --watch --dts",
+    "clean": "rm -rf dist",
+    "clean:nm": "rm -rf node_modules",
+    "publish": "yarn npm publish --tolerate-republish --access public",
+    "publish:canary": "yarn npm publish --access public --tag canary"
+  },
+  "devDependencies": {
+    "@availity/mui-button": "^0.6.7",
+    "@availity/mui-form-utils": "^0.11.3",
+    "@availity/mui-layout": "^0.1.6",
+    "@availity/mui-menu": "^0.2.7",
+    "@availity/mui-textfield": "^0.5.21",
+    "@availity/mui-typography": "^0.2.0",
+    "@mui/material": "^5.15.15",
+    "react": "18.2.0",
+    "react-dom": "18.2.0",
+    "tsup": "^8.0.2",
+    "typescript": "^5.4.5"
+  },
+  "peerDependencies": {
+    "@mui/material": "^5.11.9",
+    "react": ">=16.3.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@availity/analytics-core": "^4.1.2"
+  }
+}

package/project.json

@@ -0,0 +1,41 @@
+{
+  "name": "mui-event-tracker",
+  "$schema": "../../node_modules/nx/schemas/project-schema.json",
+  "sourceRoot": "packages/event-tracker/src",
+  "projectType": "library",
+  "tags": [],
+  "targets": {
+    "lint": {
+      "executor": "@nx/eslint:lint",
+      "options": {
+        "eslintConfig": ".eslintrc.json",
+        "silent": false,
+        "fix": false,
+        "cache": true,
+        "cacheLocation": "./node_modules/.cache/event-tracker/.eslintcache",
+        "maxWarnings": -1,
+        "quiet": false,
+        "noEslintrc": false,
+        "hasTypeAwareRules": true,
+        "cacheStrategy": "metadata"
+      }
+    },
+    "test": {
+      "executor": "@nx/jest:jest",
+      "outputs": ["{workspaceRoot}/coverage/event-tracker"],
+      "options": {
+        "jestConfig": "packages/event-tracker/jest.config.js"
+      }
+    },
+    "version": {
+      "executor": "@jscutlery/semver:version",
+      "options": {
+        "preset": "conventional",
+        "commitMessageFormat": "chore({projectName}): release version ${version} [skip ci]",
+        "tagPrefix": "@availity/{projectName}@",
+        "trackDeps": true,
+        "skipCommitTypes": ["docs"]
+      }
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1 @@
+export * from './lib/EventTracker';

package/src/lib/EventTracker.stories.tsx

@@ -0,0 +1,139 @@
+// Each exported component in the package should have its own stories file
+
+import { useState, useMemo } from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import { Typography } from '@availity/mui-typography';
+import { Grid, Box } from '@availity/mui-layout';
+import { FormControl, FormLabel, Select, Input, SelectChangeEvent } from '@availity/mui-form-utils';
+import { TextField } from '@availity/mui-textfield';
+import { MenuItem } from '@availity/mui-menu';
+import { Button } from '@availity/mui-button';
+import { EventTrackerProvider, useEventTracker, EventTrackerProps } from './EventTracker';
+
+const meta: Meta<typeof EventTrackerProvider> = {
+  title: 'Components/EventTracker/EventTracker',
+  component: EventTrackerProvider,
+  tags: ['autodocs'],
+};
+
+export default meta;
+
+type EventTrackerUiProps = {
+  count: number;
+  state: string;
+  selectValue: string;
+  setCount: React.Dispatch<React.SetStateAction<number>>;
+  setSelectValue: React.Dispatch<React.SetStateAction<string>>;
+};
+
+const EventTrackerUI = ({ count, state, selectValue, setCount, setSelectValue }: EventTrackerUiProps) => {
+  const { trackEvent } = useEventTracker();
+
+  const handleChange = (event: SelectChangeEvent) => {
+    setSelectValue(event.target.value as string);
+  };
+  return (
+    <>
+      <Typography>
+        This example is set up to track user events. <code>Select</code> allows logging for the blur event.
+        <br />
+        <code>Textarea</code> and <code>Input</code> log when focused. Both of these buttons log when clicked.
+      </Typography>
+      <Typography>Events logged: {count}</Typography>
+      <pre>LastEvent: {state}</pre>
+      <Grid container direction="column" maxWidth="500px" data-analytics-app-name="app">
+        <FormControl>
+          <FormLabel id="select-label">Select</FormLabel>
+          <Select
+            labelId="select-label"
+            value={selectValue}
+            onChange={handleChange}
+            onBlur={() => trackEvent({ action: 'blur', appName: 'app', elemId: 'select-label', event: 'blur' })}
+          >
+            <MenuItem value="10">10</MenuItem>
+            <MenuItem value="20">20</MenuItem>
+            <MenuItem value="30">30</MenuItem>
+          </Select>
+        </FormControl>
+        <Box marginTop={2}>
+          <FormControl>
+            <FormLabel id="textarea-label" htmlFor="textarea">
+              Text Area
+            </FormLabel>
+            <TextField id="textarea" multiline data-analytics-action="focus" />
+          </FormControl>
+        </Box>
+        <FormControl>
+          <FormLabel id="input-label" htmlFor="input">
+            Input
+          </FormLabel>
+          <Input id="input" data-analytics-action="focus" />
+        </FormControl>
+        <Grid container justifyContent="space-between" data-analytics-container="buttons" marginTop={2}>
+          <Button
+            id="reset-button"
+            data-analytics-action="click"
+            data-analytics-test-id="world"
+            onClick={() => setCount(0)}
+            color="secondary"
+            children="Reset Count"
+          />
+          <Button
+            id="my-button"
+            data-analytics-action="click"
+            data-analytics-test-id="hello"
+            color="primary"
+            children="Click Me"
+          />
+        </Grid>
+      </Grid>
+    </>
+  );
+};
+
+export const _EventTracker: StoryObj<typeof EventTrackerProvider> = {
+  render: (args: EventTrackerProps) => {
+    const [state, setState] = useState('');
+    const [count, setCount] = useState(0);
+    const [selectValue, setSelectValue] = useState('');
+
+    const plugins = useMemo(
+      () => [
+        {
+          isEnabled: () => {
+            console.log('checking isEnabled');
+            return true;
+          },
+          init: () => {
+            console.log('init');
+          },
+          trackEvent(event: unknown) {
+            console.log('track event', event);
+            setState(JSON.stringify(event, null, 2));
+            setCount((current) => current + 1);
+          },
+          trackPageView(url: unknown) {
+            console.log('track page view', url);
+          },
+        },
+      ],
+      []
+    );
+
+    return (
+      <EventTrackerProvider {...args} plugins={plugins}>
+        <EventTrackerUI
+          count={count}
+          setCount={setCount}
+          state={state}
+          selectValue={selectValue}
+          setSelectValue={setSelectValue}
+        />
+      </EventTrackerProvider>
+    );
+  },
+  args: {
+    eventModifiers: ['action'],
+    recursive: true,
+  },
+};

package/src/lib/EventTracker.test.tsx

@@ -0,0 +1,69 @@
+import React from 'react';
+import { render, cleanup, fireEvent, waitFor } from '@testing-library/react';
+
+import { EventTrackerProvider, useEventTracker } from './EventTracker';
+
+const makePlugin = () => ({
+  isEnabled: jest.fn(() => true),
+  init: jest.fn(),
+  trackEvent: jest.fn(),
+  trackPageView: jest.fn(),
+});
+
+describe('EventTracker', () => {
+  afterEach(() => {
+    cleanup();
+  });
+
+  it('should allow click events', async () => {
+    const plugins = [makePlugin()];
+
+    const { getByText } = render(
+      <EventTrackerProvider plugins={plugins}>
+        <button data-analytics-on="click" data-analytics-action="click" type="button">
+          Hello World
+        </button>
+      </EventTrackerProvider>
+    );
+
+    const btn = getByText('Hello World');
+
+    fireEvent.click(btn);
+
+    expect(plugins[0].trackEvent).toHaveBeenCalledTimes(1);
+  });
+
+  it('should allow trackEvents from code', async () => {
+    const plugins = [makePlugin()];
+
+    const Button = () => {
+      const { trackEvent } = useEventTracker();
+
+      return (
+        <button
+          onClick={() =>
+            trackEvent({
+              url: '/test',
+            })
+          }
+        >
+          Hello World
+        </button>
+      );
+    };
+
+    const { getByText } = render(
+      <EventTrackerProvider plugins={plugins}>
+        <Button />
+      </EventTrackerProvider>
+    );
+
+    const btn = getByText('Hello World');
+
+    fireEvent.click(btn);
+
+    await waitFor(() => {
+      expect(plugins[0].trackEvent).toHaveBeenCalledTimes(1);
+    });
+  });
+});

package/src/lib/EventTracker.tsx

@@ -0,0 +1,68 @@
+import React, { createContext, useContext, useEffect, useMemo } from 'react';
+import { AvAnalytics } from '@availity/analytics-core';
+
+export type EventTrackerProps = {
+  /** */
+  children?: React.ReactNode;
+  /** An array of plugins to pass to the underlying AvAnalytics class instance. */
+  plugins?: any[];
+  /** Enable or disable page tracking on initialization.
+   * @default true
+   */
+  pageTracking?: boolean;
+  /** Enable or disable auto tracking on initialization.
+   * @default true
+   */
+  autoTrack?: boolean;
+  /** Enable or disable recursive functionality on initialization.
+   * @default true
+   */
+  recursive?: boolean;
+  /** Customize the prefix used for data event tracker attributes used for auto tracking.
+   * @default 'data-analytics'
+   */
+  attributePrefix?: string;
+  /** Array of event modifiers enabling you to use other keywords for action instead of click for event type matching.
+   * @default ['action']
+   */
+  eventModifiers?: any[];
+};
+
+export const EventTrackerContext = createContext<AvAnalytics | null>(null);
+
+export const useEventTracker = () => {
+  const ctx = useContext(EventTrackerContext);
+
+  if (!ctx) {
+    throw new Error('useEventTracker must be used within an EventTrackerProvider');
+  }
+
+  return ctx;
+};
+
+export const EventTrackerProvider = ({
+  children,
+  plugins,
+  pageTracking = true,
+  autoTrack = true,
+  recursive = true,
+  attributePrefix = 'data-analytics',
+  eventModifiers = ['action'],
+}: EventTrackerProps) => {
+  const analytics = useMemo(
+    () => new AvAnalytics(plugins, Promise, pageTracking, autoTrack, { recursive, attributePrefix, eventModifiers }),
+    [attributePrefix, autoTrack, eventModifiers, pageTracking, plugins, recursive]
+  );
+
+  useEffect(() => {
+    analytics.init();
+
+    if (pageTracking) {
+      analytics.trackPageView();
+    }
+
+    return () => analytics.stopAutoTrack();
+  }, [analytics, pageTracking]);
+
+  return <EventTrackerContext.Provider value={analytics}>{children}</EventTrackerContext.Provider>;
+};

package/tsconfig.json

@@ -0,0 +1,5 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "include": ["."],
+  "exclude": ["dist", "build", "node_modules"]
+}

package/tsconfig.spec.json

@@ -0,0 +1,10 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "outDir": "../../dist/out-tsc",
+    "module": "commonjs",
+    "types": ["jest", "node", "@testing-library/jest-dom"],
+    "allowJs": true
+  },
+  "include": ["**/*.test.js", "**/*.test.ts", "**/*.test.tsx", "**/*.d.ts"]
+}