@docusaurus/plugin-content-docs 2.0.0-beta.8bda3b2db → 2.0.0-beta.9

package/src/{__tests__/sidebarItemsGenerator.test.ts → sidebars/__tests__/generator.test.ts}

@@ -8,15 +8,14 @@
 import {
   CategoryMetadatasFile,
   DefaultSidebarItemsGenerator,
-} from '../sidebarItemsGenerator';
-import {DefaultCategoryCollapsedValue} from '../sidebars';
+} from '../generator';
 import {Sidebar, SidebarItemsGenerator} from '../types';
 import fs from 'fs-extra';
-import {DefaultNumberPrefixParser} from '../numberPrefix';
+import {DefaultNumberPrefixParser} from '../../numberPrefix';
 
 describe('DefaultSidebarItemsGenerator', () => {
   function testDefaultSidebarItemsGenerator(
-    options: Partial<Parameters<SidebarItemsGenerator>[0]>,
+    params: Partial<Parameters<SidebarItemsGenerator>[0]>,
   ) {
     return DefaultSidebarItemsGenerator({
       numberPrefixParser: DefaultNumberPrefixParser,
@@ -29,7 +28,11 @@ describe('DefaultSidebarItemsGenerator', () => {
         contentPath: 'docs',
       },
       docs: [],
-      ...options,
+      options: {
+        sidebarCollapsed: true,
+        sidebarCollapsible: true,
+      },
+      ...params,
     });
   }
 
@@ -110,6 +113,10 @@ describe('DefaultSidebarItemsGenerator', () => {
           frontMatter: {},
         },
       ],
+      options: {
+        sidebarCollapsed: true,
+        sidebarCollapsible: true,
+      },
     });
 
     expect(sidebarSlice).toEqual([
@@ -190,6 +197,10 @@ describe('DefaultSidebarItemsGenerator', () => {
           frontMatter: {},
         },
       ],
+      options: {
+        sidebarCollapsed: true,
+        sidebarCollapsible: true,
+      },
     });
 
     expect(sidebarSlice).toEqual([
@@ -197,7 +208,8 @@ describe('DefaultSidebarItemsGenerator', () => {
       {
         type: 'category',
         label: 'Tutorials',
-        collapsed: DefaultCategoryCollapsedValue,
+        collapsed: true,
+        collapsible: true,
         items: [
           {type: 'doc', id: 'tutorial1'},
           {type: 'doc', id: 'tutorial2'},
@@ -207,12 +219,14 @@ describe('DefaultSidebarItemsGenerator', () => {
         type: 'category',
         label: 'Guides',
         collapsed: false,
+        collapsible: true,
         items: [
           {type: 'doc', id: 'guide1'},
           {
             type: 'category',
             label: 'SubGuides (metadata file label)',
-            collapsed: DefaultCategoryCollapsedValue,
+            collapsed: true,
+            collapsible: true,
             items: [{type: 'doc', id: 'nested-guide'}],
           },
           {type: 'doc', id: 'guide2'},
@@ -233,6 +247,7 @@ describe('DefaultSidebarItemsGenerator', () => {
       'subfolder/subsubfolder/subsubsubfolder3/_category_.json': {
         position: 1,
         label: 'subsubsubfolder3 (_category_.json label)',
+        collapsible: false,
         collapsed: false,
       },
     });
@@ -305,6 +320,10 @@ describe('DefaultSidebarItemsGenerator', () => {
           frontMatter: {},
         },
       ],
+      options: {
+        sidebarCollapsed: true,
+        sidebarCollapsible: true,
+      },
     });
 
     expect(sidebarSlice).toEqual([
@@ -312,6 +331,7 @@ describe('DefaultSidebarItemsGenerator', () => {
         type: 'category',
         label: 'subsubsubfolder3 (_category_.json label)',
         collapsed: false,
+        collapsible: false,
         items: [
           {type: 'doc', id: 'doc8'},
           {type: 'doc', id: 'doc7'},
@@ -321,6 +341,7 @@ describe('DefaultSidebarItemsGenerator', () => {
         type: 'category',
         label: 'subsubsubfolder2 (_category_.yml label)',
         collapsed: true,
+        collapsible: true,
         items: [{type: 'doc', id: 'doc6'}],
       },
       {type: 'doc', id: 'doc1'},
@@ -329,6 +350,7 @@ describe('DefaultSidebarItemsGenerator', () => {
         type: 'category',
         label: 'subsubsubfolder',
         collapsed: true,
+        collapsible: true,
         items: [{type: 'doc', id: 'doc5'}],
       },
     ] as Sidebar);

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

@@ -0,0 +1,202 @@
+/**
+ * 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.
+ */
+
+import path from 'path';
+import {
+  loadUnprocessedSidebars,
+  DefaultSidebars,
+  DisabledSidebars,
+} from '../index';
+import type {SidebarOptions} from '../../types';
+
+describe('loadUnprocessedSidebars', () => {
+  const fixtureDir = path.join(__dirname, '__fixtures__', 'sidebars');
+  const options: SidebarOptions = {
+    sidebarCollapsed: true,
+    sidebarCollapsible: true,
+  };
+  test('sidebars with known sidebar item type', async () => {
+    const sidebarPath = path.join(fixtureDir, 'sidebars.json');
+    const result = loadUnprocessedSidebars(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);
+    expect(result).toMatchSnapshot();
+  });
+
+  test('sidebars shorthand and longform lead to exact same sidebar', async () => {
+    const sidebarPath1 = path.join(fixtureDir, 'sidebars-category.js');
+    const sidebarPath2 = path.join(
+      fixtureDir,
+      'sidebars-category-shorthand.js',
+    );
+    const sidebar1 = loadUnprocessedSidebars(sidebarPath1, options);
+    const sidebar2 = loadUnprocessedSidebars(sidebarPath2, options);
+    expect(sidebar1).toEqual(sidebar2);
+  });
+
+  test('sidebars with category but category.items is not an array', async () => {
+    const sidebarPath = path.join(
+      fixtureDir,
+      'sidebars-category-wrong-items.json',
+    );
+    expect(() => loadUnprocessedSidebars(sidebarPath, options))
+      .toThrowErrorMatchingInlineSnapshot(`
+      "{
+        \\"type\\": \\"category\\",
+        \\"label\\": \\"Category Label\\",
+        \\"items\\" [1]: \\"doc1\\"
+      }
+      
+      [1] \\"items\\" must be an array"
+    `);
+  });
+
+  test('sidebars with category but category label is not a string', async () => {
+    const sidebarPath = path.join(
+      fixtureDir,
+      'sidebars-category-wrong-label.json',
+    );
+    expect(() => loadUnprocessedSidebars(sidebarPath, options))
+      .toThrowErrorMatchingInlineSnapshot(`
+      "{
+        \\"type\\": \\"category\\",
+        \\"items\\": [
+          \\"doc1\\"
+        ],
+        \\"label\\" [1]: true
+      }
+      
+      [1] \\"label\\" must be a string"
+    `);
+  });
+
+  test('sidebars item doc but id is not a string', async () => {
+    const sidebarPath = path.join(
+      fixtureDir,
+      'sidebars-doc-id-not-string.json',
+    );
+    expect(() => loadUnprocessedSidebars(sidebarPath, options))
+      .toThrowErrorMatchingInlineSnapshot(`
+      "{
+        \\"type\\": \\"doc\\",
+        \\"id\\" [1]: [
+          \\"doc1\\"
+        ]
+      }
+      
+      [1] \\"id\\" must be a string"
+    `);
+  });
+
+  test('sidebars with first level not a category', async () => {
+    const sidebarPath = path.join(
+      fixtureDir,
+      'sidebars-first-level-not-category.js',
+    );
+    const result = loadUnprocessedSidebars(sidebarPath, options);
+    expect(result).toMatchSnapshot();
+  });
+
+  test('sidebars link', async () => {
+    const sidebarPath = path.join(fixtureDir, 'sidebars-link.json');
+    const result = loadUnprocessedSidebars(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))
+      .toThrowErrorMatchingInlineSnapshot(`
+      "{
+        \\"type\\": \\"link\\",
+        \\"href\\": \\"https://github.com\\",
+        \\"label\\" [1]: false
+      }
+      
+      [1] \\"label\\" must be a string"
+    `);
+  });
+
+  test('sidebars link wrong href', async () => {
+    const sidebarPath = path.join(fixtureDir, 'sidebars-link-wrong-href.json');
+    expect(() => loadUnprocessedSidebars(sidebarPath, options))
+      .toThrowErrorMatchingInlineSnapshot(`
+      "{
+        \\"type\\": \\"link\\",
+        \\"label\\": \\"GitHub\\",
+        \\"href\\" [1]: [
+          \\"example.com\\"
+        ]
+      }
+      
+      [1] \\"href\\" contains an invalid value"
+    `);
+  });
+
+  test('sidebars with unknown sidebar item type', async () => {
+    const sidebarPath = path.join(fixtureDir, 'sidebars-unknown-type.json');
+    expect(() => loadUnprocessedSidebars(sidebarPath, options))
+      .toThrowErrorMatchingInlineSnapshot(`
+      "{
+        \\"type\\": \\"superman\\",
+        \\"undefined\\" [1]: -- missing --
+      }
+      
+      [1] Unknown sidebar item type \\"superman\\"."
+    `);
+  });
+
+  test('sidebars with known sidebar item type but wrong field', async () => {
+    const sidebarPath = path.join(fixtureDir, 'sidebars-wrong-field.json');
+    expect(() => loadUnprocessedSidebars(sidebarPath, options))
+      .toThrowErrorMatchingInlineSnapshot(`
+      "{
+        \\"type\\": \\"category\\",
+        \\"label\\": \\"category\\",
+        \\"href\\": \\"https://github.com\\",
+        \\"items\\" [1]: -- missing --
+      }
+      
+      [1] \\"items\\" is required"
+    `);
+  });
+
+  test('unexisting path', () => {
+    expect(loadUnprocessedSidebars('badpath', options)).toEqual(
+      DisabledSidebars,
+    );
+  });
+
+  test('undefined path', () => {
+    expect(loadUnprocessedSidebars(undefined, options)).toEqual(
+      DefaultSidebars,
+    );
+  });
+
+  test('literal false path', () => {
+    expect(loadUnprocessedSidebars(false, options)).toEqual(DisabledSidebars);
+  });
+
+  test('sidebars with category.collapsed property', async () => {
+    const sidebarPath = path.join(fixtureDir, 'sidebars-collapsed.json');
+    const result = loadUnprocessedSidebars(sidebarPath, options);
+    expect(result).toMatchSnapshot();
+  });
+
+  test('sidebars with category.collapsed property at first level', async () => {
+    const sidebarPath = path.join(
+      fixtureDir,
+      'sidebars-collapsed-first-level.json',
+    );
+    const result = loadUnprocessedSidebars(sidebarPath, options);
+    expect(result).toMatchSnapshot();
+  });
+});

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

@@ -0,0 +1,148 @@
+/**
+ * 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.
+ */
+
+import {processSidebars} from '../processor';
+import type {
+  SidebarItem,
+  SidebarItemsGenerator,
+  Sidebars,
+  NormalizedSidebars,
+} from '../types';
+import {DefaultSidebarItemsGenerator} from '../generator';
+
+describe('processSidebars', () => {
+  const StaticGeneratedSidebarSlice: SidebarItem[] = [
+    {type: 'doc', id: 'doc-generated-id-1'},
+    {type: 'doc', id: 'doc-generated-id-2'},
+  ];
+
+  const StaticSidebarItemsGenerator: SidebarItemsGenerator = jest.fn(
+    async () => {
+      return StaticGeneratedSidebarSlice;
+    },
+  );
+
+  async function testProcessSidebars(unprocessedSidebars: NormalizedSidebars) {
+    return processSidebars(unprocessedSidebars, {
+      sidebarItemsGenerator: StaticSidebarItemsGenerator,
+      docs: [],
+      // @ts-expect-error: useless for this test
+      version: {},
+    });
+  }
+
+  test('let sidebars without autogenerated items untouched', async () => {
+    const unprocessedSidebars: NormalizedSidebars = {
+      someSidebar: [
+        {type: 'doc', id: 'doc1'},
+        {
+          type: 'category',
+          collapsed: false,
+          collapsible: true,
+          items: [{type: 'doc', id: 'doc2'}],
+          label: 'Category',
+        },
+        {type: 'link', href: 'https://facebook.com', label: 'FB'},
+      ],
+      secondSidebar: [
+        {type: 'doc', id: 'doc3'},
+        {type: 'link', href: 'https://instagram.com', label: 'IG'},
+        {
+          type: 'category',
+          collapsed: false,
+          collapsible: true,
+          items: [{type: 'doc', id: 'doc4'}],
+          label: 'Category',
+        },
+      ],
+    };
+
+    const processedSidebar = await testProcessSidebars(unprocessedSidebars);
+    expect(processedSidebar).toEqual(unprocessedSidebars);
+  });
+
+  test('replace autogenerated items by generated sidebars slices', async () => {
+    const unprocessedSidebars: NormalizedSidebars = {
+      someSidebar: [
+        {type: 'doc', id: 'doc1'},
+        {
+          type: 'category',
+          collapsed: false,
+          collapsible: true,
+          items: [
+            {type: 'doc', id: 'doc2'},
+            {type: 'autogenerated', dirName: 'dir1'},
+          ],
+          label: 'Category',
+        },
+        {type: 'link', href: 'https://facebook.com', label: 'FB'},
+      ],
+      secondSidebar: [
+        {type: 'doc', id: 'doc3'},
+        {type: 'autogenerated', dirName: 'dir2'},
+        {type: 'link', href: 'https://instagram.com', label: 'IG'},
+        {type: 'autogenerated', dirName: 'dir3'},
+        {
+          type: 'category',
+          collapsed: false,
+          collapsible: true,
+          items: [{type: 'doc', id: 'doc4'}],
+          label: 'Category',
+        },
+      ],
+    };
+
+    const processedSidebar = await testProcessSidebars(unprocessedSidebars);
+
+    expect(StaticSidebarItemsGenerator).toHaveBeenCalledTimes(3);
+    expect(StaticSidebarItemsGenerator).toHaveBeenCalledWith({
+      defaultSidebarItemsGenerator: DefaultSidebarItemsGenerator,
+      item: {type: 'autogenerated', dirName: 'dir1'},
+      docs: [],
+      version: {},
+    });
+    expect(StaticSidebarItemsGenerator).toHaveBeenCalledWith({
+      defaultSidebarItemsGenerator: DefaultSidebarItemsGenerator,
+      item: {type: 'autogenerated', dirName: 'dir2'},
+      docs: [],
+      version: {},
+    });
+    expect(StaticSidebarItemsGenerator).toHaveBeenCalledWith({
+      defaultSidebarItemsGenerator: DefaultSidebarItemsGenerator,
+      item: {type: 'autogenerated', dirName: 'dir3'},
+      docs: [],
+      version: {},
+    });
+
+    expect(processedSidebar).toEqual({
+      someSidebar: [
+        {type: 'doc', id: 'doc1'},
+        {
+          type: 'category',
+          collapsed: false,
+          collapsible: true,
+          items: [{type: 'doc', id: 'doc2'}, ...StaticGeneratedSidebarSlice],
+          label: 'Category',
+        },
+        {type: 'link', href: 'https://facebook.com', label: 'FB'},
+      ],
+      secondSidebar: [
+        {type: 'doc', id: 'doc3'},
+        ...StaticGeneratedSidebarSlice,
+        {type: 'link', href: 'https://instagram.com', label: 'IG'},
+        ...StaticGeneratedSidebarSlice,
+        {
+          type: 'category',
+          collapsed: false,
+          collapsible: true,
+          items: [{type: 'doc', id: 'doc4'}],
+          label: 'Category',
+        },
+      ],
+    } as Sidebars);
+  });
+});