Merge pull request #6333 from Blargian/galaxy-on-page

Add useGalaxyOnPage hook and wire it into docs pages and KB articles

Author: Blargian

src/lib/galaxy/galaxy.js

@@ -114,6 +114,9 @@ export const useInitGalaxy = () => {
 
     const [galaxy, stopGalaxy] = Galaxy.init(galaxyOptions);
     window.galaxy = galaxy;
+    // Signal readiness so page-level effects that mounted before init (the
+    // common case on a cold visit) can fire their queued load events.
+    window.dispatchEvent(new Event("galaxy:ready"));
 
     return () => {
       void stopGalaxy();
@@ -138,7 +141,7 @@ export const galaxyOnLoad = (event) => {
  */
 export const galaxyOnFocus = (event, depsArray) => {
   const listener = () => {
-    window.galaxy.track(event, { interaction: "trigger" });
+    window.galaxy?.track(event, { interaction: "trigger" });
   };
 
   useEffect(() => {
@@ -157,7 +160,7 @@ export const galaxyOnFocus = (event, depsArray) => {
  */
 export const galaxyOnBlur = (event, depsArray) => {
   const listener = () => {
-    window.galaxy.track(event, { interaction: "trigger" });
+    window.galaxy?.track(event, { interaction: "trigger" });
   };
 
   useEffect(() => {
@@ -171,14 +174,34 @@ export const galaxyOnBlur = (event, depsArray) => {
 /**
  * Instrument galaxy for this page for load, blur and focus events.
  *
+ * Fires `${prefix}.window.load` once each time the page (or `depsArray`)
+ * changes, and tracks blur/focus for the lifetime of the component.
+ *
  * @param prefix used to name the events sent to galaxy (`${prefix}.window.load`, `${prefix}.window.blur` and `${prefix}.window.focus`)
  * @param depsArray used to trigger a rerender of the component that will re-run the useEffect
  *
  */
-export const galaxyOnPage = (prefix, depsArray = []) => {
-  galaxyOnLoad(`${prefix}.window.load`);
-  galaxyOnBlur(`${prefix}.window.blur`, depsArray);
-  galaxyOnFocus(`${prefix}.window.focus`, depsArray);
+export const useGalaxyOnPage = (prefix, depsArray = []) => {
+  // Fire the load event once per page change. Galaxy is initialised in an
+  // effect of its own (see useInitGalaxy) in an unrelated subtree, so on a
+  // cold visit this effect usually runs before galaxy is ready. If it isn't
+  // ready yet, wait for the one-shot `galaxy:ready` signal instead of dropping
+  // the event with no retry.
+  useEffect(() => {
+    const track = () =>
+      window.galaxy.track(`${prefix}.window.load`, { interaction: "trigger" });
+
+    if (window.galaxy) {
+      track();
+      return;
+    }
+
+    window.addEventListener("galaxy:ready", track, { once: true });
+    return () => window.removeEventListener("galaxy:ready", track);
+  }, [prefix, ...depsArray]);
+
+  galaxyOnBlur(`${prefix}.window.blur`, [prefix, ...depsArray]);
+  galaxyOnFocus(`${prefix}.window.focus`, [prefix, ...depsArray]);
 };
 
 // Pass String with convention 'namespace.component.eventName'

src/theme/BlogPostPage/index.js

@@ -0,0 +1,84 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * Swizzled to instrument knowledge base articles with galaxy
+ * load/blur/focus events. The KB is served by the blog plugin
+ * (routeBasePath "/knowledgebase"), so it does not pass through
+ * the docs DocItem/Layout where docs pages are instrumented.
+ */
+import React from 'react';
+import clsx from 'clsx';
+import {HtmlClassNameProvider, ThemeClassNames} from '@docusaurus/theme-common';
+import {
+  BlogPostProvider,
+  useBlogPost,
+} from '@docusaurus/plugin-content-blog/client';
+import BlogLayout from '@theme/BlogLayout';
+import BlogPostItem from '@theme/BlogPostItem';
+import BlogPostPaginator from '@theme/BlogPostPaginator';
+import BlogPostPageMetadata from '@theme/BlogPostPage/Metadata';
+import BlogPostPageStructuredData from '@theme/BlogPostPage/StructuredData';
+import TOC from '@theme/TOC';
+import ContentVisibility from '@theme/ContentVisibility';
+import {useGalaxyOnPage} from '../../lib/galaxy/galaxy';
+import styles from './styles.module.scss';
+function BlogPostPageContent({sidebar, children}) {
+  const {metadata, toc} = useBlogPost();
+  const {nextItem, prevItem, frontMatter} = metadata;
+  const {
+    hide_table_of_contents: hideTableOfContents,
+    toc_min_heading_level: tocMinHeadingLevel,
+    toc_max_heading_level: tocMaxHeadingLevel,
+  } = frontMatter;
+
+  // Instrument every KB article, keyed on its permalink. Mirrors the
+  // `docs.page.*` convention used for docs pages in DocItem/Layout.
+  useGalaxyOnPage(`knowledgebase.page.${metadata.permalink}`, [
+    metadata.permalink,
+  ]);
+
+  return (
+    <BlogLayout
+      sidebar={sidebar}
+      toc={
+        !hideTableOfContents && toc.length > 0 ? (
+          <div className={styles.tocWrapper}>
+            <TOC
+              toc={toc}
+              minHeadingLevel={tocMinHeadingLevel}
+              maxHeadingLevel={tocMaxHeadingLevel}
+            />
+          </div>
+        ) : undefined
+      }>
+      <ContentVisibility metadata={metadata} />
+
+      <BlogPostItem>{children}</BlogPostItem>
+
+      {(nextItem || prevItem) && (
+        <BlogPostPaginator nextItem={nextItem} prevItem={prevItem} />
+      )}
+    </BlogLayout>
+  );
+}
+export default function BlogPostPage(props) {
+  const BlogPostContent = props.content;
+  return (
+    <BlogPostProvider content={props.content} isBlogPostPage>
+      <HtmlClassNameProvider
+        className={clsx(
+          ThemeClassNames.wrapper.blogPages,
+          ThemeClassNames.page.blogPostPage,
+        )}>
+        <BlogPostPageMetadata />
+        <BlogPostPageStructuredData />
+        <BlogPostPageContent sidebar={props.sidebar}>
+          <BlogPostContent />
+        </BlogPostPageContent>
+      </HtmlClassNameProvider>
+    </BlogPostProvider>
+  );
+}

src/theme/BlogPostPage/styles.module.scss

@@ -0,0 +1,15 @@
+/* Align the KB article TOC with the left sidebar's search bar, which is
+ * offset from the top of the row by `margin-top: 2rem`
+ * (see BlogSidebar/Desktop .sidebarSearchContainer). The TOC's sticky
+ * element has no top offset in normal flow, so without this it sits ~2rem
+ * higher than the search bar.
+ *
+ * The wrapper stretches to the full column height (height: 100% +
+ * border-box) so the sticky TOC inside still travels with the article as
+ * you scroll; padding-top (not margin) provides the 2rem offset without
+ * changing the row height. */
+.tocWrapper {
+  height: 100%;
+  padding-top: 2rem;
+  box-sizing: border-box;
+}

src/theme/DocItem/Layout/index.js

@@ -17,7 +17,7 @@ import IconClose from "@theme/Icon/Close";
 import {useLocation} from "@docusaurus/router";
 import useDocusaurusContext from "@docusaurus/useDocusaurusContext";
 import RelatedBlogs from "../../../components/RelatedBlogs/RelatedBlogs";
-import {galaxyOnClick} from "../../../lib/galaxy/galaxy";
+import {galaxyOnClick, useGalaxyOnPage} from "../../../lib/galaxy/galaxy";
 /**
  * Decide if the toc should be rendered, on mobile or desktop viewports
  */
@@ -43,6 +43,10 @@ export default function DocItemLayout({children}) {
   const {metadata, frontMatter} = useDoc();
   const {editUrl} = metadata;
 
+  // Instrument every docs page with galaxy load/blur/focus events, keyed on
+  // the page's permalink so each page reports under its own prefix.
+  useGalaxyOnPage(`docs.page.${metadata.permalink}`, [metadata.permalink]);
+
   const location = useLocation();
   const context = useDocusaurusContext();