refactor(v2): docs plugin refactor (#3245)

* safe refactorings

* safe refactors

* add code to read versions more generically

* refactor docs plugin

* refactors

* stable docs refactor

* progress on refactor

* stable docs refactor

* stable docs refactor

* stable docs refactor

* attempt to fix admonition :(

* configureWebpack docs: better typing

* more refactors

* rename cli

* refactor docs metadata processing => move to pure function

* stable docs refactor

* stable docs refactor

* named exports

* basic sidebars refactor

* add getElementsAround utils

* refactor sidebar + ordering/navigation logic

* stable retrocompatible refactor

* add proper versions metadata tests

* fix docs metadata tests

* fix docs tests

* fix test due to absolute path

* fix webpack tests

* refactor linkify + add broken markdown links warning

* fix DOM warning due to forwarding legacy prop to div element

* add todo

packages/docusaurus-utils/src/__tests__/index.test.ts

@@ -26,6 +26,7 @@ import {
   removePrefix,
   getFilePathForRoutePath,
   addLeadingSlash,
+  getElementsAround,
 } from '../index';
 
 describe('load utils', () => {
@@ -477,3 +478,37 @@ describe('getFilePathForRoutePath', () => {
     );
   });
 });
+
+describe('getElementsAround', () => {
+  test('can return elements around', () => {
+    expect(getElementsAround(['a', 'b', 'c', 'd'], 0)).toEqual({
+      previous: undefined,
+      next: 'b',
+    });
+    expect(getElementsAround(['a', 'b', 'c', 'd'], 1)).toEqual({
+      previous: 'a',
+      next: 'c',
+    });
+    expect(getElementsAround(['a', 'b', 'c', 'd'], 2)).toEqual({
+      previous: 'b',
+      next: 'd',
+    });
+    expect(getElementsAround(['a', 'b', 'c', 'd'], 3)).toEqual({
+      previous: 'c',
+      next: undefined,
+    });
+  });
+
+  test('throws if bad index is provided', () => {
+    expect(() =>
+      getElementsAround(['a', 'b', 'c', 'd'], -1),
+    ).toThrowErrorMatchingInlineSnapshot(
+      `"Valid aroundIndex for array (of size 4) are between 0 and 3, but you provided aroundIndex=-1"`,
+    );
+    expect(() =>
+      getElementsAround(['a', 'b', 'c', 'd'], 4),
+    ).toThrowErrorMatchingInlineSnapshot(
+      `"Valid aroundIndex for array (of size 4) are between 0 and 3, but you provided aroundIndex=4"`,
+    );
+  });
+});

packages/docusaurus-utils/src/index.ts

@@ -403,3 +403,22 @@ export function getFilePathForRoutePath(routePath: string): string {
   const filePath = path.dirname(routePath);
   return path.join(filePath, `${fileName}/index.html`);
 }
+
+export function getElementsAround<T extends unknown>(
+  array: T[],
+  aroundIndex: number,
+): {
+  next: T | undefined;
+  previous: T | undefined;
+} {
+  const min = 0;
+  const max = array.length - 1;
+  if (aroundIndex < min || aroundIndex > max) {
+    throw new Error(
+      `Valid aroundIndex for array (of size ${array.length}) are between ${min} and ${max}, but you provided aroundIndex=${aroundIndex}`,
+    );
+  }
+  const previous = aroundIndex === min ? undefined : array[aroundIndex - 1];
+  const next = aroundIndex === max ? undefined : array[aroundIndex + 1];
+  return {previous, next};
+}