@docusaurus/plugin-content-docs 0.0.0-4235 → 0.0.0-4242

package/src/sidebars/__tests__/index.test.ts

@@ -7,27 +7,31 @@
 
 import path from 'path';
 import {
-  loadUnprocessedSidebars,
+  loadNormalizedSidebars,
   DefaultSidebars,
   DisabledSidebars,
 } from '../index';
-import type {SidebarOptions} from '../../types';
+import type {NormalizeSidebarsParams, VersionMetadata} from '../../types';
 
-describe('loadUnprocessedSidebars', () => {
+describe('loadNormalizedSidebars', () => {
   const fixtureDir = path.join(__dirname, '__fixtures__', 'sidebars');
-  const options: SidebarOptions = {
+  const options: NormalizeSidebarsParams = {
     sidebarCollapsed: true,
     sidebarCollapsible: true,
+    version: {
+      versionName: 'version',
+      versionPath: 'versionPath',
+    } as VersionMetadata,
   };
   test('sidebars with known sidebar item type', async () => {
     const sidebarPath = path.join(fixtureDir, 'sidebars.json');
-    const result = loadUnprocessedSidebars(sidebarPath, options);
+    const result = loadNormalizedSidebars(sidebarPath, options);
     expect(result).toMatchSnapshot();
   });
 
   test('sidebars with deep level of category', async () => {
     const sidebarPath = path.join(fixtureDir, 'sidebars-category.js');
-    const result = loadUnprocessedSidebars(sidebarPath, options);
+    const result = loadNormalizedSidebars(sidebarPath, options);
     expect(result).toMatchSnapshot();
   });
 
@@ -37,8 +41,8 @@ describe('loadUnprocessedSidebars', () => {
       fixtureDir,
       'sidebars-category-shorthand.js',
     );
-    const sidebar1 = loadUnprocessedSidebars(sidebarPath1, options);
-    const sidebar2 = loadUnprocessedSidebars(sidebarPath2, options);
+    const sidebar1 = loadNormalizedSidebars(sidebarPath1, options);
+    const sidebar2 = loadNormalizedSidebars(sidebarPath2, options);
     expect(sidebar1).toEqual(sidebar2);
   });
 
@@ -47,7 +51,7 @@ describe('loadUnprocessedSidebars', () => {
       fixtureDir,
       'sidebars-category-wrong-items.json',
     );
-    expect(() => loadUnprocessedSidebars(sidebarPath, options))
+    expect(() => loadNormalizedSidebars(sidebarPath, options))
       .toThrowErrorMatchingInlineSnapshot(`
       "{
         \\"type\\": \\"category\\",
@@ -64,7 +68,7 @@ describe('loadUnprocessedSidebars', () => {
       fixtureDir,
       'sidebars-category-wrong-label.json',
     );
-    expect(() => loadUnprocessedSidebars(sidebarPath, options))
+    expect(() => loadNormalizedSidebars(sidebarPath, options))
       .toThrowErrorMatchingInlineSnapshot(`
       "{
         \\"type\\": \\"category\\",
@@ -83,7 +87,7 @@ describe('loadUnprocessedSidebars', () => {
       fixtureDir,
       'sidebars-doc-id-not-string.json',
     );
-    expect(() => loadUnprocessedSidebars(sidebarPath, options))
+    expect(() => loadNormalizedSidebars(sidebarPath, options))
       .toThrowErrorMatchingInlineSnapshot(`
       "{
         \\"type\\": \\"doc\\",
@@ -101,19 +105,19 @@ describe('loadUnprocessedSidebars', () => {
       fixtureDir,
       'sidebars-first-level-not-category.js',
     );
-    const result = loadUnprocessedSidebars(sidebarPath, options);
+    const result = loadNormalizedSidebars(sidebarPath, options);
     expect(result).toMatchSnapshot();
   });
 
   test('sidebars link', async () => {
     const sidebarPath = path.join(fixtureDir, 'sidebars-link.json');
-    const result = loadUnprocessedSidebars(sidebarPath, options);
+    const result = loadNormalizedSidebars(sidebarPath, options);
     expect(result).toMatchSnapshot();
   });
 
   test('sidebars link wrong label', async () => {
     const sidebarPath = path.join(fixtureDir, 'sidebars-link-wrong-label.json');
-    expect(() => loadUnprocessedSidebars(sidebarPath, options))
+    expect(() => loadNormalizedSidebars(sidebarPath, options))
       .toThrowErrorMatchingInlineSnapshot(`
       "{
         \\"type\\": \\"link\\",
@@ -127,7 +131,7 @@ describe('loadUnprocessedSidebars', () => {
 
   test('sidebars link wrong href', async () => {
     const sidebarPath = path.join(fixtureDir, 'sidebars-link-wrong-href.json');
-    expect(() => loadUnprocessedSidebars(sidebarPath, options))
+    expect(() => loadNormalizedSidebars(sidebarPath, options))
       .toThrowErrorMatchingInlineSnapshot(`
       "{
         \\"type\\": \\"link\\",
@@ -143,7 +147,7 @@ describe('loadUnprocessedSidebars', () => {
 
   test('sidebars with unknown sidebar item type', async () => {
     const sidebarPath = path.join(fixtureDir, 'sidebars-unknown-type.json');
-    expect(() => loadUnprocessedSidebars(sidebarPath, options))
+    expect(() => loadNormalizedSidebars(sidebarPath, options))
       .toThrowErrorMatchingInlineSnapshot(`
       "{
         \\"type\\": \\"superman\\",
@@ -156,7 +160,7 @@ describe('loadUnprocessedSidebars', () => {
 
   test('sidebars with known sidebar item type but wrong field', async () => {
     const sidebarPath = path.join(fixtureDir, 'sidebars-wrong-field.json');
-    expect(() => loadUnprocessedSidebars(sidebarPath, options))
+    expect(() => loadNormalizedSidebars(sidebarPath, options))
       .toThrowErrorMatchingInlineSnapshot(`
       "{
         \\"type\\": \\"category\\",
@@ -170,24 +174,22 @@ describe('loadUnprocessedSidebars', () => {
   });
 
   test('unexisting path', () => {
-    expect(loadUnprocessedSidebars('badpath', options)).toEqual(
+    expect(loadNormalizedSidebars('badpath', options)).toEqual(
       DisabledSidebars,
     );
   });
 
   test('undefined path', () => {
-    expect(loadUnprocessedSidebars(undefined, options)).toEqual(
-      DefaultSidebars,
-    );
+    expect(loadNormalizedSidebars(undefined, options)).toEqual(DefaultSidebars);
   });
 
   test('literal false path', () => {
-    expect(loadUnprocessedSidebars(false, options)).toEqual(DisabledSidebars);
+    expect(loadNormalizedSidebars(false, options)).toEqual(DisabledSidebars);
   });
 
   test('sidebars with category.collapsed property', async () => {
     const sidebarPath = path.join(fixtureDir, 'sidebars-collapsed.json');
-    const result = loadUnprocessedSidebars(sidebarPath, options);
+    const result = loadNormalizedSidebars(sidebarPath, options);
     expect(result).toMatchSnapshot();
   });
 
@@ -196,7 +198,7 @@ describe('loadUnprocessedSidebars', () => {
       fixtureDir,
       'sidebars-collapsed-first-level.json',
     );
-    const result = loadUnprocessedSidebars(sidebarPath, options);
+    const result = loadNormalizedSidebars(sidebarPath, options);
     expect(result).toMatchSnapshot();
   });
 });

package/src/sidebars/__tests__/processor.test.ts

@@ -5,7 +5,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import {processSidebars} from '../processor';
+import {processSidebars, SidebarProcessorParams} from '../processor';
 import type {
   SidebarItem,
   SidebarItemsGenerator,
@@ -13,23 +13,50 @@ import type {
   NormalizedSidebars,
 } from '../types';
 import {DefaultSidebarItemsGenerator} from '../generator';
+import {createSlugger} from '@docusaurus/utils';
+import {VersionMetadata} from '../../types';
+import {DefaultNumberPrefixParser} from '../../numberPrefix';
 
 describe('processSidebars', () => {
+  function createStaticSidebarItemGenerator(
+    sidebarSlice: SidebarItem[],
+  ): SidebarItemsGenerator {
+    return jest.fn(async () => sidebarSlice);
+  }
+
   const StaticGeneratedSidebarSlice: SidebarItem[] = [
     {type: 'doc', id: 'doc-generated-id-1'},
     {type: 'doc', id: 'doc-generated-id-2'},
   ];
 
-  const StaticSidebarItemsGenerator: SidebarItemsGenerator = jest.fn(
-    async () => StaticGeneratedSidebarSlice,
-  );
+  const StaticSidebarItemsGenerator: SidebarItemsGenerator =
+    createStaticSidebarItemGenerator(StaticGeneratedSidebarSlice);
+
+  // @ts-expect-error: good enough for this test
+  const version: VersionMetadata = {
+    versionName: '1.0.0',
+    versionPath: '/docs/1.0.0',
+  };
+
+  const params: SidebarProcessorParams = {
+    sidebarItemsGenerator: StaticSidebarItemsGenerator,
+    docs: [],
+    version,
+    numberPrefixParser: DefaultNumberPrefixParser,
+    categoryLabelSlugger: createSlugger(),
+    sidebarOptions: {
+      sidebarCollapsed: true,
+      sidebarCollapsible: true,
+    },
+  };
 
-  async function testProcessSidebars(unprocessedSidebars: NormalizedSidebars) {
+  async function testProcessSidebars(
+    unprocessedSidebars: NormalizedSidebars,
+    paramsOverrides: Partial<SidebarProcessorParams> = {},
+  ) {
     return processSidebars(unprocessedSidebars, {
-      sidebarItemsGenerator: StaticSidebarItemsGenerator,
-      docs: [],
-      // @ts-expect-error: useless for this test
-      version: {},
+      ...params,
+      ...paramsOverrides,
     });
   }
 
@@ -69,13 +96,18 @@ describe('processSidebars', () => {
         {type: 'doc', id: 'doc1'},
         {
           type: 'category',
+          label: 'Category',
+          link: {
+            type: 'generated-index',
+            slug: 'category-generated-index-slug',
+            permalink: 'category-generated-index-permalink',
+          },
           collapsed: false,
           collapsible: true,
           items: [
             {type: 'doc', id: 'doc2'},
             {type: 'autogenerated', dirName: 'dir1'},
           ],
-          label: 'Category',
         },
         {type: 'link', href: 'https://facebook.com', label: 'FB'},
       ],
@@ -86,10 +118,10 @@ describe('processSidebars', () => {
         {type: 'autogenerated', dirName: 'dir3'},
         {
           type: 'category',
+          label: 'Category',
           collapsed: false,
           collapsible: true,
           items: [{type: 'doc', id: 'doc4'}],
-          label: 'Category',
         },
       ],
     };
@@ -100,20 +132,32 @@ describe('processSidebars', () => {
     expect(StaticSidebarItemsGenerator).toHaveBeenCalledWith({
       defaultSidebarItemsGenerator: DefaultSidebarItemsGenerator,
       item: {type: 'autogenerated', dirName: 'dir1'},
-      docs: [],
-      version: {},
+      docs: params.docs,
+      version: {
+        versionName: version.versionName,
+      },
+      numberPrefixParser: DefaultNumberPrefixParser,
+      options: params.sidebarOptions,
     });
     expect(StaticSidebarItemsGenerator).toHaveBeenCalledWith({
       defaultSidebarItemsGenerator: DefaultSidebarItemsGenerator,
       item: {type: 'autogenerated', dirName: 'dir2'},
-      docs: [],
-      version: {},
+      docs: params.docs,
+      version: {
+        versionName: version.versionName,
+      },
+      numberPrefixParser: DefaultNumberPrefixParser,
+      options: params.sidebarOptions,
     });
     expect(StaticSidebarItemsGenerator).toHaveBeenCalledWith({
       defaultSidebarItemsGenerator: DefaultSidebarItemsGenerator,
       item: {type: 'autogenerated', dirName: 'dir3'},
-      docs: [],
-      version: {},
+      docs: params.docs,
+      version: {
+        versionName: version.versionName,
+      },
+      numberPrefixParser: DefaultNumberPrefixParser,
+      options: params.sidebarOptions,
     });
 
     expect(processedSidebar).toEqual({
@@ -121,10 +165,15 @@ describe('processSidebars', () => {
         {type: 'doc', id: 'doc1'},
         {
           type: 'category',
+          label: 'Category',
+          link: {
+            type: 'generated-index',
+            slug: 'category-generated-index-slug',
+            permalink: 'category-generated-index-permalink',
+          },
           collapsed: false,
           collapsible: true,
           items: [{type: 'doc', id: 'doc2'}, ...StaticGeneratedSidebarSlice],
-          label: 'Category',
         },
         {type: 'link', href: 'https://facebook.com', label: 'FB'},
       ],
@@ -135,10 +184,52 @@ describe('processSidebars', () => {
         ...StaticGeneratedSidebarSlice,
         {
           type: 'category',
+          label: 'Category',
           collapsed: false,
           collapsible: true,
           items: [{type: 'doc', id: 'doc4'}],
-          label: 'Category',
+        },
+      ],
+    } as Sidebars);
+  });
+
+  test('ensure generated items are normalized', async () => {
+    const sidebarSliceContainingCategoryGeneratedIndex: SidebarItem[] = [
+      {
+        type: 'category',
+        label: 'Generated category',
+        link: {
+          type: 'generated-index',
+          slug: 'generated-cat-index-slug',
+          // @ts-expect-error: TODO undefined should be allowed here, typing error needing refactor
+          permalink: undefined,
+        },
+      },
+    ];
+
+    const unprocessedSidebars: NormalizedSidebars = {
+      someSidebar: [{type: 'autogenerated', dirName: 'dir2'}],
+    };
+
+    const processedSidebar = await testProcessSidebars(unprocessedSidebars, {
+      sidebarItemsGenerator: createStaticSidebarItemGenerator(
+        sidebarSliceContainingCategoryGeneratedIndex,
+      ),
+    });
+
+    expect(processedSidebar).toEqual({
+      someSidebar: [
+        {
+          type: 'category',
+          label: 'Generated category',
+          link: {
+            type: 'generated-index',
+            slug: 'generated-cat-index-slug',
+            permalink: '/docs/1.0.0/generated-cat-index-slug',
+          },
+          items: [],
+          collapsible: true,
+          collapsed: true,
         },
       ],
     } as Sidebars);