add tests for sidebar item keys props + ensure the key attribute is forwarded to frontend as props for all sidebar items

packages/docusaurus-plugin-content-docs/src/__tests__/props.test.ts

@@ -5,7 +5,12 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import {toSidebarDocItemLinkProp, toTagDocListProp} from '../props';
+import {fromPartial} from '@total-typescript/shoehorn';
+import {
+  toSidebarDocItemLinkProp,
+  toSidebarsProp,
+  toTagDocListProp,
+} from '../props';
 
 describe('toTagDocListProp', () => {
   type Params = Parameters<typeof toTagDocListProp>[0];
@@ -132,3 +137,123 @@ describe('toSidebarDocItemLinkProp', () => {
     ).toBe(false);
   });
 });
+
+describe('toSidebarsProp', () => {
+  type Params = Parameters<typeof toSidebarsProp>[0];
+
+  it('works', () => {
+    const params: Params = {
+      docs: [
+        fromPartial({
+          id: 'doc-id-1',
+          frontMatter: {},
+        }),
+      ],
+      sidebars: {
+        mySidebar: [
+          {
+            type: 'link',
+            label: 'Example link',
+            key: 'link-example-key',
+            href: 'https://example.com',
+          },
+          {
+            type: 'ref',
+            label: 'Doc 1 ref',
+            key: 'ref-with-doc-id-1',
+            id: 'doc-id-1',
+          },
+          {
+            type: 'ref',
+            label: 'Doc 1 ref bis',
+            // no key on purpose
+            id: 'doc-id-1',
+          },
+          {
+            type: 'category',
+            label: 'My category',
+            key: 'my-category-key',
+            collapsible: false,
+            collapsed: true,
+            items: [
+              {
+                type: 'doc',
+                label: 'Doc 1',
+                key: 'doc-id-1',
+                id: 'doc-id-1',
+              },
+              {
+                type: 'doc',
+                label: 'Doc 1 bis',
+                // no key on purpose
+                id: 'doc-id-1',
+              },
+            ],
+          },
+        ],
+      },
+    };
+
+    const result = toSidebarsProp(params);
+
+    expect(result).toMatchInlineSnapshot(`
+      {
+        "mySidebar": [
+          {
+            "href": "https://example.com",
+            "key": "link-example-key",
+            "label": "Example link",
+            "type": "link",
+          },
+          {
+            "className": undefined,
+            "customProps": undefined,
+            "docId": "doc-id-1",
+            "href": undefined,
+            "key": "ref-with-doc-id-1",
+            "label": "Doc 1 ref",
+            "type": "link",
+            "unlisted": undefined,
+          },
+          {
+            "className": undefined,
+            "customProps": undefined,
+            "docId": "doc-id-1",
+            "href": undefined,
+            "label": "Doc 1 ref bis",
+            "type": "link",
+            "unlisted": undefined,
+          },
+          {
+            "collapsed": true,
+            "collapsible": false,
+            "items": [
+              {
+                "className": undefined,
+                "customProps": undefined,
+                "docId": "doc-id-1",
+                "href": undefined,
+                "key": "doc-id-1",
+                "label": "Doc 1",
+                "type": "link",
+                "unlisted": undefined,
+              },
+              {
+                "className": undefined,
+                "customProps": undefined,
+                "docId": "doc-id-1",
+                "href": undefined,
+                "label": "Doc 1 bis",
+                "type": "link",
+                "unlisted": undefined,
+              },
+            ],
+            "key": "my-category-key",
+            "label": "My category",
+            "type": "category",
+          },
+        ],
+      }
+    `);
+  });
+});

packages/docusaurus-plugin-content-docs/src/props.ts

@@ -41,6 +41,7 @@ export function toSidebarDocItemLinkProp({
   const {id, title, permalink, frontMatter, unlisted} = doc;
   return {
     type: 'link',
+    ...(item.key && {key: item.key}),
     href: permalink,
     // Front Matter data takes precedence over sidebars.json
     label: frontMatter.sidebar_label ?? item.label ?? title,
@@ -51,7 +52,9 @@ export function toSidebarDocItemLinkProp({
   };
 }
 
-export function toSidebarsProp(loadedVersion: LoadedVersion): PropSidebars {
+export function toSidebarsProp(
+  loadedVersion: Pick<LoadedVersion, 'docs' | 'sidebars'>,
+): PropSidebars {
   const docsById = createDocsByIdIndex(loadedVersion.docs);
 
   function getDocById(docId: string): DocMetadata {