Capture documentation search analytics & improve legacy docs handling (…

…#534)

apps/web/package.json

@@ -72,7 +72,7 @@
     "unique-names-generator": "^4.7.1",
     "unist-util-filter": "^4.0.1",
     "unist-util-visit": "^4.1.1",
-    "usehooks-ts": "^2.9.1",
+    "usehooks-ts": "^2.16.0",
     "uuid": "^9.0.1",
     "zustand": "^4.3.2"
   },

apps/web/src/components/LegacyBanner.tsx

@@ -0,0 +1,28 @@
+'use client'
+
+import { AlertCircle } from 'lucide-react'
+import { usePathname } from 'next/navigation'
+
+export default function LegacyBanner() {
+  const pathname = usePathname()
+
+  const isLegacy = pathname?.startsWith('/docs/legacy')
+
+  if (!isLegacy) return null
+
+  return (
+    <>
+      <div className="sticky top-[5rem] inset-x-0 z-10">
+        <div className="flex items-center gap-2 max-w-6xl mx-auto w-fit px-4 py-3 rounded-2xl bg-gradient-to-b from-zinc-800 to-zinc-900 text-zinc-400 ring-1 ring-inset ring-zinc-700">
+          <AlertCircle className="h-4 w-4 text-brand-400/80" />
+          <span>
+            You are reading a{' '}
+            <span className="text-brand-400/90">legacy (pre v.1.0)</span>{' '}
+            document.
+          </span>
+        </div>
+      </div>
+      <div className="h-16" />
+    </>
+  )
+}

apps/web/src/components/Search.tsx

@@ -25,6 +25,8 @@ import clsx from 'clsx'
 import { type Result } from '@/mdx/search.mjs'
 import { DialogAnimated } from '@/components/DialogAnimated'
 import { docRoutes } from './Navigation/routes'
+import { usePostHog } from 'posthog-js/react'
+import { useDebounceCallback } from 'usehooks-ts'
 
 type EmptyObject = Record<string, never>
 
@@ -38,16 +40,38 @@ type Autocomplete = AutocompleteApi<
 function useAutocomplete({ close }: { close: () => void }) {
   const id = useId()
   const router = useRouter()
+  const posthog = usePostHog()
   const [autocompleteState, setAutocompleteState] = useState<
     AutocompleteState<Result> | EmptyObject
   >({})
 
-  function navigate({ itemUrl }: { itemUrl?: string }) {
+  const captureSearchEvent = useDebounceCallback(
+    (query: string, results_count: number) =>
+      posthog.capture('searched docs', {
+        query,
+        results_count,
+      }),
+    500
+  )
+
+  const navigate = ({
+    itemUrl,
+    state,
+  }: {
+    itemUrl?: string
+    state: AutocompleteState<Result>
+  }) => {
     if (!itemUrl) {
       return
     }
 
     itemUrl = itemUrl.replace('(docs)/', '')
+
+    posthog.capture('selected docs search result', {
+      query: state.query,
+      selected_url: itemUrl,
+    })
+
     router.push(itemUrl)
 
     if (
@@ -70,6 +94,13 @@ function useAutocomplete({ close }: { close: () => void }) {
       defaultActiveItemId: 0,
       onStateChange({ state }) {
         setAutocompleteState(state)
+
+        if (state.query) {
+          captureSearchEvent(
+            state.query,
+            state.collections[0]?.items.length || 0
+          )
+        }
       },
       shouldPanelOpen({ state }) {
         return state.query !== ''
@@ -83,7 +114,7 @@ function useAutocomplete({ close }: { close: () => void }) {
             {
               sourceId: 'documentation',
               getItems() {
-                const results = search(query, { limit: 5 })
+                const results = search(query, { limit: 20 })
                 return results.sort((a, b) => {
                   if (a.badge === 'Legacy' && b.badge !== 'Legacy') return 1
                   if (a.badge !== 'Legacy' && b.badge === 'Legacy') return -1
@@ -294,7 +325,10 @@ function SearchResults({
   }
 
   return (
-    <ul {...autocomplete.getListProps()}>
+    <ul
+      className="max-h-[80dvh] sm:max-h-[50dvh] overflow-y-auto"
+      {...autocomplete.getListProps()}
+    >
       {collection.items.map((result, resultIndex) => (
         <SearchResult
           key={result.url}
@@ -429,15 +463,16 @@ function SearchDialog({
           {...autocomplete.getPanelProps({})}
         >
           {/* @ts-ignore */}
-          {autocompleteState.isOpen && (
-            <SearchResults
-              autocomplete={autocomplete}
-              // @ts-ignore
-              query={autocompleteState.query}
-              // @ts-ignore
-              collection={autocompleteState.collections[0]}
-            />
-          )}
+          {autocompleteState.collections?.[0] &&
+            autocompleteState.query.length > 0 && (
+              <SearchResults
+                autocomplete={autocomplete}
+                // @ts-ignore
+                query={autocompleteState.query}
+                // @ts-ignore
+                collection={autocompleteState.collections[0]}
+              />
+            )}
         </div>
       </form>
     </DialogAnimated>

apps/web/src/components/mdx.tsx

@@ -3,76 +3,68 @@ import clsx from 'clsx'
 
 import { Heading } from '@/components/Heading'
 import { Prose } from '@/components/Prose'
+import LegacyBanner from './LegacyBanner'
 
 export const a = Link
 export { Button } from '@/components/Button'
-export { CodeGroupAutoload, CodeGroup, Code as code, Pre as pre } from '@/components/Code'
+export {
+  CodeGroupAutoload,
+  CodeGroup,
+  Code as code,
+  Pre as pre,
+} from '@/components/Code'
 export { LanguageSpecificText } from '@/components/LanguageSpecificText'
 
 export function wrapper({ children }: { children: React.ReactNode }) {
   return (
     <article className="mx-auto flex h-full max-w-6xl flex-col pb-10 pt-20 md:pt-18">
-      <Prose className="flex-auto">{children}</Prose>
+      <Prose className="flex-auto">
+        <LegacyBanner />
+        {children}
+      </Prose>
     </article>
   )
 }
 
 export const h2 = function H2(
-  props: Omit<React.ComponentPropsWithoutRef<typeof Heading>, 'level'>,
+  props: Omit<React.ComponentPropsWithoutRef<typeof Heading>, 'level'>
 ) {
-  return (
-    <Heading
-      level={2}
-      {...props}
-    />
-  )
+  return <Heading level={2} {...props} />
 }
 
 export const h3 = function H3(
-  props: Omit<React.ComponentPropsWithoutRef<typeof Heading>, 'level'>,
+  props: Omit<React.ComponentPropsWithoutRef<typeof Heading>, 'level'>
 ) {
-  return (
-    <Heading
-      level={3}
-      {...props}
-    />
-  )
+  return <Heading level={3} {...props} />
 }
 
 function InfoIcon(props: React.ComponentPropsWithoutRef<'svg'>) {
   return (
-    <svg
-      viewBox="0 0 16 16"
-      aria-hidden="true"
-      {...props}
-    >
-      <circle
-        cx="8"
-        cy="8"
-        r="8"
-        strokeWidth="0"
-      />
+    <svg viewBox="0 0 16 16" aria-hidden="true" {...props}>
+      <circle cx="8" cy="8" r="8" strokeWidth="0" />
       <path
         fill="none"
         strokeLinecap="round"
         strokeLinejoin="round"
         strokeWidth="1.5"
         d="M6.75 7.75h1.5v3.5"
       />
-      <circle
-        cx="8"
-        cy="4"
-        r=".5"
-        fill="none"
-      />
+      <circle cx="8" cy="4" r=".5" fill="none" />
     </svg>
   )
 }
 
-export function Note({ title, children }: { title?: string, children: React.ReactNode }) {
+export function Note({
+  title,
+  children,
+}: {
+  title?: string
+  children: React.ReactNode
+}) {
   return (
     <div
-      className={clsx(`
+      className={clsx(
+        `
         bg-brand-50/50
         my-6
         flex
@@ -90,9 +82,11 @@ export function Note({ title, children }: { title?: string, children: React.Reac
         dark:[--tw-prose-links:theme(colors.white)]
       `,
         title && 'flex-col items-start justify-start'
-      )}>
+      )}
+    >
       <div className="flex gap-2.5 justify-start items-start">
-        <InfoIcon className="
+        <InfoIcon
+          className="
           mt-1
           h-4
           w-4
@@ -101,11 +95,14 @@ export function Note({ title, children }: { title?: string, children: React.Reac
           stroke-white
           dark:fill-brand-200/20
           dark:stroke-brand-200
-        "/>
+        "
+        />
         {title && <span className="font-bold">{title}</span>}
       </div>
 
-      <div className="[&>:first-child]:mt-0 [&>:last-child]:mb-0">{children}</div>
+      <div className="[&>:first-child]:mt-0 [&>:last-child]:mb-0">
+        {children}
+      </div>
     </div>
   )
 }
@@ -129,7 +126,7 @@ export function Col({
     <div
       className={clsx(
         '[&>:first-child]:mt-0 [&>:last-child]:mb-0',
-        sticky && 'xl:sticky xl:top-24',
+        sticky && 'xl:sticky xl:top-24'
       )}
     >
       {children}
@@ -166,12 +163,17 @@ export function Option({
         {type && (
           <>
             <dt className="sr-only">Flags</dt>
-            <dd className="font-mono text-xs text-zinc-600 dark:text-white"> {type}</dd>
+            <dd className="font-mono text-xs text-zinc-600 dark:text-white">
+              {' '}
+              {type}
+            </dd>
           </>
         )}
-        {name && <dd>
-          <code className="text-zinc-300 dark:text-zinc-400">{name}</code>
-        </dd>}
+        {name && (
+          <dd>
+            <code className="text-zinc-300 dark:text-zinc-400">{name}</code>
+          </dd>
+        )}
         <dt className="sr-only">Description</dt>
         <dd className="w-full flex-none [&>:first-child]:mt-0 [&>:last-child]:mb-0">
           {children}