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

package/src/{__tests__/__snapshots__/sidebars.test.ts.snap → sidebars/__tests__/__snapshots__/index.test.ts.snap}

@@ -1,6 +1,6 @@
 // Jest Snapshot v1, https://goo.gl/fbAQLP
 
-exports[`loadSidebars sidebars link 1`] = `
+exports[`loadUnprocessedSidebars sidebars link 1`] = `
 Object {
   "docs": Array [
     Object {
@@ -20,7 +20,7 @@ Object {
 }
 `;
 
-exports[`loadSidebars sidebars with category.collapsed property 1`] = `
+exports[`loadUnprocessedSidebars sidebars with category.collapsed property 1`] = `
 Object {
   "docs": Array [
     Object {
@@ -67,7 +67,7 @@ Object {
 }
 `;
 
-exports[`loadSidebars sidebars with category.collapsed property at first level 1`] = `
+exports[`loadUnprocessedSidebars sidebars with category.collapsed property at first level 1`] = `
 Object {
   "docs": Array [
     Object {
@@ -98,7 +98,7 @@ Object {
 }
 `;
 
-exports[`loadSidebars sidebars with deep level of category 1`] = `
+exports[`loadUnprocessedSidebars sidebars with deep level of category 1`] = `
 Object {
   "docs": Array [
     Object {
@@ -165,7 +165,7 @@ Object {
 }
 `;
 
-exports[`loadSidebars sidebars with first level not a category 1`] = `
+exports[`loadUnprocessedSidebars sidebars with first level not a category 1`] = `
 Object {
   "docs": Array [
     Object {
@@ -188,7 +188,7 @@ Object {
 }
 `;
 
-exports[`loadSidebars sidebars with known sidebar item type 1`] = `
+exports[`loadUnprocessedSidebars sidebars with known sidebar item type 1`] = `
 Object {
   "docs": Array [
     Object {

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

@@ -8,10 +8,10 @@
 import {
   CategoryMetadatasFile,
   DefaultSidebarItemsGenerator,
-} from '../sidebarItemsGenerator';
+} from '../generator';
 import {Sidebar, SidebarItemsGenerator} from '../types';
 import fs from 'fs-extra';
-import {DefaultNumberPrefixParser} from '../numberPrefix';
+import {DefaultNumberPrefixParser} from '../../numberPrefix';
 
 describe('DefaultSidebarItemsGenerator', () => {
   function testDefaultSidebarItemsGenerator(

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);
+  });
+});