diff options
Diffstat (limited to 'src/utils/hooks')
6 files changed, 148 insertions, 35 deletions
diff --git a/src/utils/hooks/index.ts b/src/utils/hooks/index.ts index f4d1583..95cb717 100644 --- a/src/utils/hooks/index.ts +++ b/src/utils/hooks/index.ts @@ -9,6 +9,7 @@ export * from './use-github-repo-meta'; export * from './use-headings-tree'; export * from './use-local-storage'; export * from './use-match-media'; +export * from './use-mutation-observer'; export * from './use-on-click-outside'; export * from './use-on-route-change'; export * from './use-pagination'; 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) : [] }; }; diff --git a/src/utils/hooks/use-mutation-observer/index.ts b/src/utils/hooks/use-mutation-observer/index.ts new file mode 100644 index 0000000..16780fe --- /dev/null +++ b/src/utils/hooks/use-mutation-observer/index.ts @@ -0,0 +1 @@ +export * from './use-mutation-observer'; diff --git a/src/utils/hooks/use-mutation-observer/use-mutation-observer.test.ts b/src/utils/hooks/use-mutation-observer/use-mutation-observer.test.ts new file mode 100644 index 0000000..62ed559 --- /dev/null +++ b/src/utils/hooks/use-mutation-observer/use-mutation-observer.test.ts @@ -0,0 +1,42 @@ +import { beforeEach, describe, expect, it, jest } from '@jest/globals'; +import { renderHook } from '@testing-library/react'; +import { useMutationObserver } from './use-mutation-observer'; + +describe('useMutationObserver', () => { + beforeEach(() => { + jest.restoreAllMocks(); + }); + + it('can create a new observer', () => { + const callback = jest.fn(); + const observerSpy = jest.spyOn(MutationObserver.prototype, 'observe'); + const wrapper = document.createElement('div'); + const options: MutationObserverInit = { childList: true }; + + renderHook(() => + useMutationObserver({ + callback, + options, + ref: { current: wrapper }, + }) + ); + + expect(observerSpy).toHaveBeenCalledTimes(1); + expect(observerSpy).toHaveBeenCalledWith(wrapper, options); + }); + + it('does not create a new observer when ref is null', () => { + const callback = jest.fn(); + const observerSpy = jest.spyOn(MutationObserver.prototype, 'observe'); + + renderHook(() => + useMutationObserver({ + callback, + options: { childList: true }, + ref: { current: null }, + }) + ); + + expect(observerSpy).not.toHaveBeenCalled(); + }); +}); diff --git a/src/utils/hooks/use-mutation-observer/use-mutation-observer.ts b/src/utils/hooks/use-mutation-observer/use-mutation-observer.ts new file mode 100644 index 0000000..6043055 --- /dev/null +++ b/src/utils/hooks/use-mutation-observer/use-mutation-observer.ts @@ -0,0 +1,35 @@ +import { type RefObject, useEffect } from 'react'; +import type { Nullable } from '../../../types'; + +type UseMutationObserverProps<T extends Nullable<HTMLElement>> = { + /** + * A callback to execute when mutations are observed. + */ + callback: MutationCallback; + /** + * The options passed to mutation observer. + */ + options: MutationObserverInit; + /** + * A reference to the DOM node to observe. + */ + ref: RefObject<T>; +}; + +export const useMutationObserver = <T extends Nullable<HTMLElement>>({ + callback, + options, + ref, +}: UseMutationObserverProps<T>) => { + useEffect(() => { + if (!ref.current) return undefined; + + const observer = new MutationObserver(callback); + + observer.observe(ref.current, options); + + return () => { + observer.disconnect(); + }; + }, [callback, options, ref]); +}; |