refactor(pages): refine Project pages

* refactor ProjectOverview component to let consumers handle the value
* extract project overview depending on Github to avoid fetching
Github API if the project is not on Github
* wrap dynamic import in a useMemo hook to avoid infinite rerender
* fix table of contents by adding a useMutationObserver hook to refresh
headings tree (without it useHeadingsTree is not retriggered once the
dynamic import is done)
* add Cypress tests

2 files changed, 69 insertions, 35 deletions

diff --git a/src/utils/hooks/use-headings-tree/use-headings-tree.test.ts b/src/utils/hooks/use-headings-tree/use-headings-tree.test.ts
index 2c8ff2d..ffc5dbe 100644
--- a/src/utils/hooks/use-headings-tree/use-headings-tree.test.ts
+++ b/src/utils/hooks/use-headings-tree/use-headings-tree.test.ts
@@ -1,5 +1,5 @@
-import { describe, expect, it } from '@jest/globals';
-import { act, renderHook } from '@testing-library/react';
+import { beforeEach, describe, expect, it } from '@jest/globals';
+import { act, renderHook, waitFor } from '@testing-library/react';
 import { useHeadingsTree } from './use-headings-tree';
 
 const labels = {
@@ -9,16 +9,23 @@ const labels = {
 };
 
 describe('useHeadingsTree', () => {
-  it('returns a ref callback and the headings tree', () => {
-    const wrapper = document.createElement('div');
-
-    wrapper.innerHTML = `
+  const wrapper = document.createElement('div');
+  wrapper.innerHTML = `
 <h1>${labels.h1}</h1>
 <h2>${labels.firstH2}</h2>
 <p>Expedita et necessitatibus qui numquam sunt et ut et. Earum nostrum esse nemo nisi qui. Ab in iure qui repellat voluptatibus nostrum odit aut qui. Architecto eum fugit quod excepturi numquam qui maxime accusantium. Fugit ipsam harum tempora.</p>
 <h2>${labels.secondH2}</h2>
 <p>Totam cumque aut ipsum. Necessitatibus magnam necessitatibus. Qui illo nulla non ab. Accusamus voluptatem ab fugiat voluptas aspernatur velit dolore reprehenderit. Voluptatem quod minima asperiores voluptatum distinctio cumque quo.</p>`;
 
+  beforeEach(() => {
+    document.body.appendChild(wrapper);
+  });
+
+  afterEach(() => {
+    document.body.removeChild(wrapper);
+  });
+
+  it('returns a ref callback and the headings tree', () => {
     const { result } = renderHook(() => useHeadingsTree());
 
     act(() => result.current.ref(wrapper));
@@ -29,15 +36,6 @@ describe('useHeadingsTree', () => {
   });
 
   it('can return a headings tree starting at the specified level', () => {
-    const wrapper = document.createElement('div');
-
-    wrapper.innerHTML = `
-<h1>${labels.h1}</h1>
-<h2>${labels.firstH2}</h2>
-<p>Expedita et necessitatibus qui numquam sunt et ut et. Earum nostrum esse nemo nisi qui. Ab in iure qui repellat voluptatibus nostrum odit aut qui. Architecto eum fugit quod excepturi numquam qui maxime accusantium. Fugit ipsam harum tempora.</p>
-<h2>${labels.secondH2}</h2>
-<p>Totam cumque aut ipsum. Necessitatibus magnam necessitatibus. Qui illo nulla non ab. Accusamus voluptatem ab fugiat voluptas aspernatur velit dolore reprehenderit. Voluptatem quod minima asperiores voluptatum distinctio cumque quo.</p>`;
-
     const { result } = renderHook(() => useHeadingsTree({ fromLevel: 2 }));
 
     act(() => result.current.ref(wrapper));
@@ -48,15 +46,6 @@ describe('useHeadingsTree', () => {
   });
 
   it('can return a headings tree stopping at the specified level', () => {
-    const wrapper = document.createElement('div');
-
-    wrapper.innerHTML = `
-<h1>${labels.h1}</h1>
-<h2>${labels.firstH2}</h2>
-<p>Expedita et necessitatibus qui numquam sunt et ut et. Earum nostrum esse nemo nisi qui. Ab in iure qui repellat voluptatibus nostrum odit aut qui. Architecto eum fugit quod excepturi numquam qui maxime accusantium. Fugit ipsam harum tempora.</p>
-<h2>${labels.secondH2}</h2>
-<p>Totam cumque aut ipsum. Necessitatibus magnam necessitatibus. Qui illo nulla non ab. Accusamus voluptatem ab fugiat voluptas aspernatur velit dolore reprehenderit. Voluptatem quod minima asperiores voluptatum distinctio cumque quo.</p>`;
-
     const { result } = renderHook(() => useHeadingsTree({ toLevel: 1 }));
 
     act(() => result.current.ref(wrapper));
@@ -66,6 +55,23 @@ describe('useHeadingsTree', () => {
     expect(result.current.tree[0].children).toStrictEqual([]);
   });
 
+  it('uses a mutation observer to watch for DOM changes', async () => {
+    const newH2 = document.createElement('h2');
+    newH2.innerHTML = 'ut molestiae exercitationem';
+    const { result } = renderHook(() => useHeadingsTree({ fromLevel: 2 }));
+
+    act(() => result.current.ref(wrapper));
+
+    expect(result.current.tree.length).toBe(2);
+
+    act(() => wrapper.appendChild(newH2));
+
+    await waitFor(() => {
+      // eslint-disable-next-line @typescript-eslint/no-magic-numbers
+      expect(result.current.tree.length).toBe(3);
+    });
+  });
+
   it('throws an error if the options are invalid', () => {
     expect(() => useHeadingsTree({ fromLevel: 2, toLevel: 1 })).toThrowError(
       'Invalid options: `fromLevel` must be lower or equal to `toLevel`.'
diff --git a/src/utils/hooks/use-headings-tree/use-headings-tree.ts b/src/utils/hooks/use-headings-tree/use-headings-tree.ts
index 68bdde8..802d843 100644
--- a/src/utils/hooks/use-headings-tree/use-headings-tree.ts
+++ b/src/utils/hooks/use-headings-tree/use-headings-tree.ts
@@ -1,5 +1,7 @@
-import { useState, useCallback, type RefCallback } from 'react';
+import { useState, useCallback, type RefCallback, useEffect } from 'react';
 import type { HeadingLevel } from '../../../components';
+import type { Nullable } from '../../../types';
+import { useMutationObserver } from '../use-mutation-observer';
 
 export type HeadingsTreeNode = {
   /**
@@ -140,17 +142,43 @@ export const useHeadingsTree = <T extends HTMLElement = HTMLElement>(
       'Invalid options: `fromLevel` must be lower or equal to `toLevel`.'
     );
 
-  const [tree, setTree] = useState<HeadingsTreeNode[]>([]);
+  const [headings, setHeadings] = useState<NodeListOf<HTMLHeadingElement>>();
   const requestedHeadingTags = getHeadingTagsList(options);
   const query = requestedHeadingTags.join(', ');
-  const ref: RefCallback<T> = useCallback(
-    (el) => {
-      const headingNodes = el?.querySelectorAll<HTMLHeadingElement>(query);
 
-      if (headingNodes) setTree(buildHeadingsTreeFrom(headingNodes));
-    },
-    [query]
-  );
-
-  return { ref, tree };
+  /*
+   * With a mutable ref, the headings are not always updated because of loading
+   * states. So we need to use a RefCallback to detect when the component is
+   * effectively rendered. However, to be able to compare the mutation records,
+   * we need to keep track of the current ref so we also need to use useState...
+   */
+  const [wrapper, setWrapper] = useState<Nullable<T>>();
+  const ref: RefCallback<T> = useCallback((el) => {
+    setWrapper(el);
+  }, []);
+
+  const updateHeadings = useCallback(() => {
+    const headingNodes = wrapper?.querySelectorAll<HTMLHeadingElement>(query);
+
+    if (headingNodes) setHeadings(headingNodes);
+  }, [query, wrapper]);
+
+  useEffect(() => {
+    if (wrapper) updateHeadings();
+  }, [updateHeadings, wrapper]);
+
+  useMutationObserver({
+    callback: useCallback(
+      (records) => {
+        for (const record of records) {
+          if (record.target === wrapper) updateHeadings();
+        }
+      },
+      [updateHeadings, wrapper]
+    ),
+    options: { childList: true, subtree: true },
+    ref: { current: typeof window === 'undefined' ? null : document.body },
+  });
+
+  return { ref, tree: headings ? buildHeadingsTreeFrom(headings) : [] };
 };