feat(platform): Add reusable hook for custom plausible events (#12380)

Author: chargome

src/components/track-reader-depth.tsx

@@ -1,23 +1,19 @@
 'use client';
 import {useEffect} from 'react';
-import {usePlausible} from 'next-plausible';
 
+import {usePlausibleEvent} from 'sentry-docs/hooks/usePlausibleEvent';
+import {PROGRESS_MILESTONES, ReadProgressMilestone} from 'sentry-docs/types/plausible';
 import {debounce} from 'sentry-docs/utils';
 
-const EVENT = 'Read Progress';
-const milestones = [25, 50, 75, 100] as const;
-type Milestone = (typeof milestones)[number];
-type EVENT_PROPS = {page: string; readProgress: Milestone};
-
 export function ReaderDepthTracker() {
-  const plausible = usePlausible<{[EVENT]: EVENT_PROPS}>();
+  const {emit} = usePlausibleEvent();
 
-  const sendProgressToPlausible = (progress: Milestone) => {
-    plausible(EVENT, {props: {readProgress: progress, page: document.title}});
+  const sendProgressToPlausible = (progress: ReadProgressMilestone) => {
+    emit('Read Progress', {props: {readProgress: progress, page: document.title}});
   };
 
   useEffect(() => {
-    const reachedMilestones = new Set<Milestone>();
+    const reachedMilestones = new Set<ReadProgressMilestone>();
 
     const trackProgress = () => {
       // calculate the progress based on the scroll position
@@ -30,7 +26,7 @@ export function ReaderDepthTracker() {
       }
 
       // find the biggest milestone that has not been reached yet
-      const milestone = milestones.findLast(
+      const milestone = PROGRESS_MILESTONES.findLast(
         m =>
           progress >= m &&
           !reachedMilestones.has(m) &&

src/hooks/usePlausibleEvent.tsx

@@ -0,0 +1,44 @@
+import {usePlausible} from 'next-plausible';
+
+import {ReadProgressMilestone} from 'sentry-docs/types/plausible';
+
+// Adding custom events here will make them available via the hook
+type PlausibleEventProps = {
+  ['Read Progress']: {
+    page: string;
+    readProgress: ReadProgressMilestone;
+  };
+};
+
+/**
+ * A hook that provides type-safe access to Plausible Analytics events.
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const {emit} = usePlausibleEvent();
+ *
+ *   return (
+ *     <button
+ *       onClick={() => {
+ *         emit('Some Typed Event', {
+ *           props: {
+ *             page: document.title,
+ *           }
+ *         });
+ *       }}
+ *     >
+ *       Trigger event
+ *     </button>
+ *   );
+ * }
+ * ```
+ */
+
+export const usePlausibleEvent = () => {
+  const plausible = usePlausible<PlausibleEventProps>();
+
+  return {
+    emit: plausible,
+  };
+};

src/types/plausible.ts

@@ -0,0 +1,2 @@
+export const PROGRESS_MILESTONES = [25, 50, 75, 100] as const;
+export type ReadProgressMilestone = (typeof PROGRESS_MILESTONES)[number];