feat(core): make event track great again (#7695)

![image.png](https://graphite-user-uploaded-assets-prod.s3.amazonaws.com/5c0ymolP9B7QStCsS1RP/6a3941d9-4409-4eda-987b-88ae41bd72d4.png)

![image.png](https://graphite-user-uploaded-assets-prod.s3.amazonaws.com/5c0ymolP9B7QStCsS1RP/3e9cedec-5457-4e7a-9125-63aab7247cd2.png)

packages/frontend/core/src/mixpanel/__tests__/auto.spec.ts

@@ -0,0 +1,148 @@
+/**
+ * @vitest-environment happy-dom
+ */
+import { beforeAll, beforeEach, describe, expect, test, vi } from 'vitest';
+
+import { enableAutoTrack, makeTracker } from '../auto';
+
+describe('callable events chain', () => {
+  const call = vi.fn();
+  const track = makeTracker(call);
+
+  beforeEach(() => {
+    call.mockClear();
+  });
+
+  test('should call track with event and props', () => {
+    // @ts-expect-error fake chain
+    track.pageA.segmentA.moduleA.eventA();
+
+    expect(call).toBeCalledWith('eventA', {
+      page: 'pageA',
+      segment: 'segmentA',
+      module: 'moduleA',
+    });
+  });
+
+  test('should be able to override props', () => {
+    // @ts-expect-error fake chain
+    track.pageA.segmentA.moduleA.eventA({ page: 'pageB', control: 'controlA' });
+
+    expect(call).toBeCalledWith('eventA', {
+      page: 'pageB',
+      segment: 'segmentA',
+      module: 'moduleA',
+      control: 'controlA',
+    });
+  });
+
+  test('should be able to append custom props', () => {
+    // @ts-expect-error fake chain
+    track.pageA.segmentA.moduleA.eventA({ custom: 'prop' });
+
+    expect(call).toBeCalledWith('eventA', {
+      page: 'pageA',
+      segment: 'segmentA',
+      module: 'moduleA',
+      custom: 'prop',
+    });
+  });
+
+  test('should be able to ignore matrix named with placeholder `$`', () => {
+    // @ts-expect-error fake chain
+    track.$.segmentA.moduleA.eventA();
+    // @ts-expect-error fake chain
+    track.pageA.$.moduleA.eventA();
+    // @ts-expect-error fake chain
+    track.pageA.segmentA.$.eventA();
+    // @ts-expect-error fake chain
+    track.$.$.$.eventA();
+
+    const args = [
+      {
+        segment: 'segmentA',
+        module: 'moduleA',
+      },
+      {
+        page: 'pageA',
+        module: 'moduleA',
+      },
+      {
+        page: 'pageA',
+        segment: 'segmentA',
+      },
+      {},
+    ];
+
+    args.forEach((arg, i) => {
+      expect(call).toHaveBeenNthCalledWith(i + 1, 'eventA', arg);
+    });
+  });
+});
+
+describe('auto track with dom dataset', () => {
+  const root = document.createElement('div');
+  const call = vi.fn();
+  beforeAll(() => {
+    call.mockReset();
+    root.innerHTML = '';
+    return enableAutoTrack(root, call);
+  });
+
+  test('should ignore if data-event-props not set', () => {
+    const nonTrackBtn = document.createElement('button');
+    root.append(nonTrackBtn);
+
+    nonTrackBtn.click();
+
+    expect(call).not.toBeCalled();
+  });
+
+  test('should track event with props', () => {
+    const btn = document.createElement('button');
+    btn.dataset.eventProps = 'allDocs.header.actions.createDoc';
+    root.append(btn);
+
+    btn.click();
+
+    expect(call).toBeCalledWith('createDoc', {
+      page: 'allDocs',
+      segment: 'header',
+      module: 'actions',
+    });
+  });
+
+  test('should track event with single', () => {
+    const btn = document.createElement('button');
+    btn.dataset.eventProps = 'allDocs.header.actions.createDoc';
+    btn.dataset.eventArg = 'test';
+    root.append(btn);
+
+    btn.click();
+
+    expect(call).toBeCalledWith('createDoc', {
+      page: 'allDocs',
+      segment: 'header',
+      module: 'actions',
+      arg: 'test',
+    });
+  });
+
+  test('should track event with multiple args', () => {
+    const btn = document.createElement('button');
+    btn.dataset.eventProps = 'allDocs.header.actions.createDoc';
+    btn.dataset.eventArgsFoo = 'bar';
+    btn.dataset.eventArgsBaz = 'qux';
+    root.append(btn);
+
+    btn.click();
+
+    expect(call).toBeCalledWith('createDoc', {
+      page: 'allDocs',
+      segment: 'header',
+      module: 'actions',
+      foo: 'bar',
+      baz: 'qux',
+    });
+  });
+});

packages/frontend/core/src/mixpanel/auto.ts

@@ -0,0 +1,118 @@
+import { DebugLogger } from '@affine/debug';
+
+import type { CallableEventsChain, EventsUnion } from './types';
+
+const logger = new DebugLogger('mixpanel');
+
+interface TrackFn {
+  (event: string, props: Record<string, any>): void;
+}
+
+const levels = ['page', 'segment', 'module', 'event'] as const;
+export function makeTracker(trackFn: TrackFn): CallableEventsChain {
+  function makeTrackerInner(level: number, info: Record<string, string>) {
+    const proxy = new Proxy({} as Record<string, any>, {
+      get(target, prop) {
+        if (
+          typeof prop !== 'string' ||
+          prop === '$$typeof' /* webpack hot load reading this prop */
+        ) {
+          return undefined;
+        }
+
+        if (levels[level] === 'event') {
+          return (arg: string | Record<string, any>) => {
+            trackFn(prop, {
+              ...info,
+              ...(typeof arg === 'string' ? { arg } : arg),
+            });
+          };
+        } else {
+          let levelProxy = target[prop];
+          if (levelProxy) {
+            return levelProxy;
+          }
+
+          levelProxy = makeTrackerInner(
+            level + 1,
+            prop === '$' ? { ...info } : { ...info, [levels[level]]: prop }
+          );
+          target[prop] = levelProxy;
+          return levelProxy;
+        }
+      },
+    });
+
+    return proxy;
+  }
+
+  return makeTrackerInner(0, {}) as CallableEventsChain;
+}
+
+/**
+ * listen on clicking on all subtree elements and auto track events if defined
+ *
+ * @example
+ *
+ * ```html
+ * <button data-event-chain='$.cmdk.settings.quicksearch.changeLanguage' data-event-arg='cn' />
+ * ```
+ */
+export function enableAutoTrack(root: HTMLElement, trackFn: TrackFn) {
+  const listener = (e: Event) => {
+    const el = e.target as HTMLElement | null;
+    if (!el) {
+      return;
+    }
+    const dataset = el.dataset;
+
+    if (dataset['eventProps']) {
+      const args: Record<string, any> = {};
+      if (dataset['eventArg'] !== undefined) {
+        args['arg'] = dataset['event-arg'];
+      } else {
+        for (const argName of Object.keys(dataset)) {
+          if (argName.startsWith('eventArgs')) {
+            args[argName.slice(9).toLowerCase()] = dataset[argName];
+          }
+        }
+      }
+
+      const props = dataset['eventProps']
+        .split('.')
+        .map(name => (name === '$' ? undefined : name));
+      if (props.length !== levels.length) {
+        logger.error('Invalid event props on element', el);
+        return;
+      }
+
+      const event = props[3];
+
+      if (!event) {
+        logger.error('Invalid event props on element', el);
+        return;
+      }
+
+      trackFn(event, {
+        page: props[0] as any,
+        segment: props[1],
+        module: props[2],
+        ...args,
+      });
+    }
+  };
+
+  root.addEventListener('click', listener, {});
+  return () => {
+    root.removeEventListener('click', listener);
+  };
+}
+
+declare module 'react' {
+  //  we have to declare `T` but it's actually not used
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  interface HTMLAttributes<T> {
+    'data-event-props'?: EventsUnion;
+    'data-event-arg'?: string;
+  }
+}

packages/frontend/core/src/mixpanel/events.ts

@@ -0,0 +1,43 @@
+// let '$' stands for unspecific matrix
+/* eslint-disable rxjs/finnish */
+export interface Events {
+  $: {
+    cmdk: {
+      settings: ['openSettings', 'changeLanguage'];
+    };
+    navigationPanel: {
+      generalFunction: [
+        'quickSearch',
+        'createDoc',
+        'goToAllPage',
+        'goToJournals',
+        'openSettings',
+      ];
+      collection: ['createDoc'];
+      bottomButtong: ['downloadApp', 'restartAndInstallUpdate'];
+      others: ['openTrash', 'export'];
+    };
+  };
+  doc: {
+    editor: {
+      formatToolbar: ['bold'];
+    };
+  };
+  edgeless: {
+    editor: {
+      formatToolbar: ['drawConnector'];
+    };
+  };
+  // remove when type added
+  // eslint-disable-next-line @typescript-eslint/ban-types
+  allDocs: {};
+  // remove when type added
+  // eslint-disable-next-line @typescript-eslint/ban-types
+  collection: {};
+  // remove when type added
+  // eslint-disable-next-line @typescript-eslint/ban-types
+  tag: {};
+  // remove when type added
+  // eslint-disable-next-line @typescript-eslint/ban-types
+  trash: {};
+}

packages/frontend/core/src/mixpanel/events/index.ts

@@ -1,23 +0,0 @@
-import type { PlanChangeStartedEvent } from './plan-change-started';
-import type { PlanChangeSucceededEvent } from './plan-change-succeed';
-
-export interface MixpanelEvents {
-  PlanChangeStarted: PlanChangeStartedEvent;
-  PlanChangeSucceeded: PlanChangeSucceededEvent;
-  OAuth: {
-    provider: string;
-  };
-}
-
-export interface GeneralMixpanelEvent {
-  // location
-  page?: string | null;
-  segment?: string | null;
-  module?: string | null;
-  control?: string | null;
-
-  // entity
-  type?: string | null;
-  category?: string | null;
-  id?: string | null;
-}

packages/frontend/core/src/mixpanel/events/plan-change-started.ts

@@ -1,16 +0,0 @@
-import type { SubscriptionPlan, SubscriptionRecurring } from '@affine/graphql';
-
-/**
- * Before subscription plan changed
- */
-export interface PlanChangeStartedEvent {
-  segment?: 'settings panel';
-  module?: 'pricing plan list' | 'billing subscription list';
-  control?:
-    | 'new subscription' // no subscription before
-    | 'cancel'
-    | 'paying' // resume: subscribed before
-    | 'plan cancel action';
-  type?: SubscriptionPlan;
-  category?: SubscriptionRecurring;
-}

packages/frontend/core/src/mixpanel/events/plan-change-succeed.ts

@@ -1,9 +0,0 @@
-import type { PlanChangeStartedEvent } from './plan-change-started';
-
-/**
- * Subscription plan changed successfully
- */
-export type PlanChangeSucceededEvent = Pick<
-  PlanChangeStartedEvent,
-  'control' | 'type' | 'category' | 'segment'
->;

packages/frontend/core/src/mixpanel/index.ts

@@ -1,108 +1,8 @@
-import { DebugLogger } from '@affine/debug';
-import type { OverridedMixpanel } from 'mixpanel-browser';
-import mixpanelBrowser from 'mixpanel-browser';
+import { enableAutoTrack, makeTracker } from './auto';
+import { mixpanel } from './mixpanel';
 
-import type { GeneralMixpanelEvent, MixpanelEvents } from './events';
+export const track = makeTracker((event, props) => {
+  mixpanel.track(event, props);
+});
 
-const logger = new DebugLogger('mixpanel');
-
-type Middleware = (
-  name: string,
-  properties?: Record<string, unknown>
-) => Record<string, unknown>;
-
-function createMixpanel() {
-  let mixpanel;
-  if (process.env.MIXPANEL_TOKEN) {
-    mixpanelBrowser.init(process.env.MIXPANEL_TOKEN || '', {
-      track_pageview: true,
-      persistence: 'localStorage',
-      api_host: 'https://telemetry.affine.run',
-    });
-    mixpanel = mixpanelBrowser;
-  } else {
-    mixpanel = new Proxy(
-      function () {} as unknown as OverridedMixpanel,
-      createProxyHandler()
-    );
-  }
-
-  const middlewares = new Set<Middleware>();
-
-  const wrapped = {
-    reset() {
-      mixpanel.reset();
-      mixpanel.register({
-        appVersion: runtimeConfig.appVersion,
-        environment: runtimeConfig.appBuildType,
-        editorVersion: runtimeConfig.editorVersion,
-        isSelfHosted: Boolean(runtimeConfig.isSelfHosted),
-        isDesktop: environment.isDesktop,
-      });
-    },
-    track<
-      T extends string,
-      P extends (T extends keyof MixpanelEvents
-        ? MixpanelEvents[T]
-        : Record<string, unknown>) &
-        GeneralMixpanelEvent,
-    >(event_name: T, properties?: P) {
-      const middlewareProperties = Array.from(middlewares).reduce(
-        (acc, middleware) => {
-          return middleware(event_name, acc);
-        },
-        properties as Record<string, unknown>
-      );
-      logger.debug('track', event_name, middlewareProperties);
-
-      mixpanel.track(event_name as string, middlewareProperties);
-    },
-    middleware(cb: Middleware): () => void {
-      middlewares.add(cb);
-      return () => {
-        middlewares.delete(cb);
-      };
-    },
-    opt_out_tracking() {
-      mixpanel.opt_out_tracking();
-    },
-    opt_in_tracking() {
-      mixpanel.opt_in_tracking();
-    },
-    has_opted_in_tracking() {
-      mixpanel.has_opted_in_tracking();
-    },
-    has_opted_out_tracking() {
-      mixpanel.has_opted_out_tracking();
-    },
-    identify(unique_id?: string) {
-      mixpanel.identify(unique_id);
-    },
-    get people() {
-      return mixpanel.people;
-    },
-    track_pageview(properties?: { location?: string }) {
-      logger.debug('track_pageview', properties);
-      mixpanel.track_pageview(properties);
-    },
-  };
-
-  wrapped.reset();
-
-  return wrapped;
-}
-
-export const mixpanel = createMixpanel();
-
-function createProxyHandler() {
-  const handler = {
-    get: () => {
-      return new Proxy(
-        function () {} as unknown as OverridedMixpanel,
-        createProxyHandler()
-      );
-    },
-    apply: () => {},
-  } as ProxyHandler<OverridedMixpanel>;
-  return handler;
-}
+export { enableAutoTrack, mixpanel };

packages/frontend/core/src/mixpanel/mixpanel.d.ts

@@ -1,19 +0,0 @@
-// eslint-disable-next-line @typescript-eslint/no-unused-vars, unused-imports/no-unused-imports
-import * as mixpanel from 'mixpanel-browser';
-
-import type { GeneralMixpanelEvent, MixpanelEvents } from './events';
-
-declare module 'mixpanel-browser' {
-  export interface OverridedMixpanel {
-    track<
-      T extends string,
-      P extends (T extends keyof MixpanelEvents
-        ? MixpanelEvents[T]
-        : Record<string, unknown>) &
-        GeneralMixpanelEvent,
-    >(
-      event_name: T,
-      properties?: P
-    ): void;
-  }
-}

packages/frontend/core/src/mixpanel/mixpanel.ts

@@ -0,0 +1,101 @@
+// eslint-disable-next-line @typescript-eslint/no-unused-vars, unused-imports/no-unused-imports
+import { DebugLogger } from '@affine/debug';
+import type { OverridedMixpanel } from 'mixpanel-browser';
+import mixpanelBrowser from 'mixpanel-browser';
+
+const logger = new DebugLogger('mixpanel');
+
+type Middleware = (
+  name: string,
+  properties?: Record<string, unknown>
+) => Record<string, unknown>;
+
+function createMixpanel() {
+  let mixpanel;
+  if (process.env.MIXPANEL_TOKEN) {
+    mixpanelBrowser.init(process.env.MIXPANEL_TOKEN || '', {
+      track_pageview: true,
+      persistence: 'localStorage',
+      api_host: 'https://telemetry.affine.run',
+    });
+    mixpanel = mixpanelBrowser;
+  } else {
+    mixpanel = new Proxy(
+      function () {} as unknown as OverridedMixpanel,
+      createProxyHandler()
+    );
+  }
+
+  const middlewares = new Set<Middleware>();
+
+  const wrapped = {
+    reset() {
+      mixpanel.reset();
+      mixpanel.register({
+        appVersion: runtimeConfig.appVersion,
+        environment: runtimeConfig.appBuildType,
+        editorVersion: runtimeConfig.editorVersion,
+        isSelfHosted: Boolean(runtimeConfig.isSelfHosted),
+        isDesktop: environment.isDesktop,
+      });
+    },
+    track(event_name: string, properties?: Record<string, any>) {
+      const middlewareProperties = Array.from(middlewares).reduce(
+        (acc, middleware) => {
+          return middleware(event_name, acc);
+        },
+        properties as Record<string, unknown>
+      );
+      logger.debug('track', event_name, middlewareProperties);
+
+      mixpanel.track(event_name as string, middlewareProperties);
+    },
+    middleware(cb: Middleware): () => void {
+      middlewares.add(cb);
+      return () => {
+        middlewares.delete(cb);
+      };
+    },
+    opt_out_tracking() {
+      mixpanel.opt_out_tracking();
+    },
+    opt_in_tracking() {
+      mixpanel.opt_in_tracking();
+    },
+    has_opted_in_tracking() {
+      mixpanel.has_opted_in_tracking();
+    },
+    has_opted_out_tracking() {
+      mixpanel.has_opted_out_tracking();
+    },
+    identify(unique_id?: string) {
+      mixpanel.identify(unique_id);
+    },
+    get people() {
+      return mixpanel.people;
+    },
+    track_pageview(properties?: { location?: string }) {
+      logger.debug('track_pageview', properties);
+      mixpanel.track_pageview(properties);
+    },
+  };
+
+  wrapped.reset();
+
+  return wrapped;
+}
+
+export const mixpanel = createMixpanel();
+
+function createProxyHandler() {
+  const handler = {
+    get: () => {
+      return new Proxy(
+        function () {} as unknown as OverridedMixpanel,
+        createProxyHandler()
+      );
+    },
+    apply: () => {},
+  } as ProxyHandler<OverridedMixpanel>;
+  return handler;
+}

packages/frontend/core/src/mixpanel/types.ts

@@ -0,0 +1,60 @@
+import type { Events } from './events';
+
+export type CallableEventsChain = {
+  [Page in keyof Events]: {
+    [Segment in keyof Events[Page]]: {
+      [Module in keyof Events[Page][Segment]]: {
+        // @ts-expect-error ignore `symbol | number` as key
+        [Control in Events[Page][Segment][Module][number]]: (
+          arg?: string
+        ) => void;
+      };
+    };
+  };
+};
+
+export type EventsUnion = {
+  [Page in keyof Events]: {
+    [Segment in keyof Events[Page]]: {
+      [Module in keyof Events[Page][Segment]]: {
+        // @ts-expect-error ignore `symbol | number` as key
+        [Control in Events[Page][Segment][Module][number]]: `${Page}.${Segment}.${Module}.${Control}`;
+        // @ts-expect-error ignore `symbol | number` as key
+      }[Events[Page][Segment][Module][number]];
+    }[keyof Events[Page][Segment]];
+  }[keyof Events[Page]];
+}[keyof Events];
+
+// page > segment > module > [controls]
+type IsFourLevelsDeep<
+  T,
+  Depth extends number[] = [],
+> = Depth['length'] extends 3
+  ? T extends Array<any>
+    ? true
+    : false
+  : T extends object
+    ? {
+        [K in keyof T]: IsFourLevelsDeep<T[K], [...Depth, 0]>;
+      }[keyof T] extends true
+      ? true
+      : false
+    : false;
+
+// for type checking
+export const _assertIsAllEventsDefinedInFourLevels: IsFourLevelsDeep<Events> =
+  true;
+
+export interface EventProps {
+  // location
+  page?: keyof Events;
+  segment?: string;
+  module?: string;
+  control?: string;
+  arg?: string;
+
+  // entity
+  type?: string;
+  category?: string;
+  id?: string;
+}