@docusaurus/theme-common 0.0.0-4238 → 0.0.0-4243

package/lib/utils/storageUtils.d.ts

@@ -13,6 +13,10 @@ export interface StorageSlot {
 }
 /**
  * Creates an object for accessing a particular key in localStorage.
+ * The API is fail-safe, and usage of browser storage should be considered unreliable
+ * Local storage might simply be unavailable (iframe + browser security) or operations might fail individually
+ * Please assume that using this API can be a NO-OP
+ * See also https://github.com/facebook/docusaurus/issues/6036
  */
 export declare const createStorageSlot: (key: string, options?: {
     persistence?: "localStorage" | "none" | "sessionStorage" | undefined;

package/lib/utils/storageUtils.js

@@ -57,6 +57,10 @@ Please only call storage APIs in effects and event handlers.`);
 }
 /**
  * Creates an object for accessing a particular key in localStorage.
+ * The API is fail-safe, and usage of browser storage should be considered unreliable
+ * Local storage might simply be unavailable (iframe + browser security) or operations might fail individually
+ * Please assume that using this API can be a NO-OP
+ * See also https://github.com/facebook/docusaurus/issues/6036
  */
 export const createStorageSlot = (key, options) => {
     if (typeof window === 'undefined') {
@@ -67,9 +71,31 @@ export const createStorageSlot = (key, options) => {
         return NoopStorageSlot;
     }
     return {
-        get: () => browserStorage.getItem(key),
-        set: (value) => browserStorage.setItem(key, value),
-        del: () => browserStorage.removeItem(key),
+        get: () => {
+            try {
+                return browserStorage.getItem(key);
+            }
+            catch (e) {
+                console.error(`Docusaurus storage error, can't get key=${key}`, e);
+                return null;
+            }
+        },
+        set: (value) => {
+            try {
+                browserStorage.setItem(key, value);
+            }
+            catch (e) {
+                console.error(`Docusaurus storage error, can't set ${key}=${value}`, e);
+            }
+        },
+        del: () => {
+            try {
+                browserStorage.removeItem(key);
+            }
+            catch (e) {
+                console.error(`Docusaurus storage error, can't delete key=${key}`, e);
+            }
+        },
     };
 };
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docusaurus/theme-common",
-  "version": "0.0.0-4238",
+  "version": "0.0.0-4243",
   "description": "Common code for Docusaurus themes.",
   "main": "./lib/index.js",
   "types": "./lib/index.d.ts",
@@ -18,10 +18,10 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@docusaurus/core": "0.0.0-4238",
-    "@docusaurus/plugin-content-blog": "0.0.0-4238",
-    "@docusaurus/plugin-content-docs": "0.0.0-4238",
-    "@docusaurus/plugin-content-pages": "0.0.0-4238",
+    "@docusaurus/core": "0.0.0-4243",
+    "@docusaurus/plugin-content-blog": "0.0.0-4243",
+    "@docusaurus/plugin-content-docs": "0.0.0-4243",
+    "@docusaurus/plugin-content-pages": "0.0.0-4243",
     "clsx": "^1.1.1",
     "fs-extra": "^10.0.0",
     "parse-numeric-range": "^1.3.0",
@@ -29,8 +29,9 @@
     "utility-types": "^3.10.0"
   },
   "devDependencies": {
-    "@docusaurus/module-type-aliases": "0.0.0-4238",
-    "@docusaurus/types": "0.0.0-4238",
+    "@docusaurus/module-type-aliases": "0.0.0-4243",
+    "@docusaurus/types": "0.0.0-4243",
+    "@testing-library/react-hooks": "^7.0.2",
     "lodash": "^4.17.20"
   },
   "peerDependencies": {
@@ -41,5 +42,5 @@
   "engines": {
     "node": ">=14"
   },
-  "gitHead": "b461d8c0ec2fcea4f614bf5eec4ca700284bb42e"
+  "gitHead": "9ff41c223c3422e3483bc1049ee9ec703d11e0cd"
 }

package/src/index.ts

@@ -32,7 +32,18 @@ export {
 
 export {docVersionSearchTag, DEFAULT_SEARCH_TAG} from './utils/searchUtils';
 
-export {isDocsPluginEnabled} from './utils/docsUtils';
+export {
+  isDocsPluginEnabled,
+  DocsVersionProvider,
+  useDocsVersion,
+  useDocById,
+  DocsSidebarProvider,
+  useDocsSidebar,
+  findSidebarCategory,
+  findFirstCategoryLink,
+  useCurrentSidebarCategory,
+  isActiveSidebarItem,
+} from './utils/docsUtils';
 
 export {isSamePath} from './utils/pathUtils';
 

package/src/utils/__tests__/docsUtils.test.tsx

@@ -0,0 +1,331 @@
+/**
+ * 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 React from 'react';
+import {renderHook} from '@testing-library/react-hooks';
+import {
+  findFirstCategoryLink,
+  isActiveSidebarItem,
+  DocsVersionProvider,
+  useDocsVersion,
+  useDocById,
+  useDocsSidebar,
+  DocsSidebarProvider,
+  findSidebarCategory,
+} from '../docsUtils';
+import {
+  PropSidebar,
+  PropSidebarItem,
+  PropSidebarItemCategory,
+  PropVersionMetadata,
+} from '@docusaurus/plugin-content-docs';
+
+// Make tests more readable with some useful category item defaults
+function testCategory(
+  data?: Partial<PropSidebarItemCategory>,
+): PropSidebarItemCategory {
+  return {
+    type: 'category',
+    href: undefined,
+    label: 'Category label',
+    items: [],
+    collapsed: true,
+    collapsible: true,
+    ...data,
+  };
+}
+
+function testVersion(data?: Partial<PropVersionMetadata>): PropVersionMetadata {
+  return {
+    version: 'versionName',
+    label: 'Version Label',
+    className: 'version className',
+    badge: true,
+    banner: 'unreleased',
+    docs: {},
+    docsSidebars: {},
+    isLast: false,
+    pluginId: 'default',
+    ...data,
+  };
+}
+
+describe('docsUtils', () => {
+  describe('useDocsVersion', () => {
+    test('should throw if context provider is missing', () => {
+      expect(
+        () => renderHook(() => useDocsVersion()).result.current,
+      ).toThrowErrorMatchingInlineSnapshot(
+        `"This hook requires usage of <DocsVersionProvider>"`,
+      );
+    });
+
+    test('should read value from context provider', () => {
+      const version = testVersion();
+      const {result} = renderHook(() => useDocsVersion(), {
+        wrapper: ({children}) => (
+          <DocsVersionProvider version={version}>
+            {children}
+          </DocsVersionProvider>
+        ),
+      });
+      expect(result.current).toBe(version);
+    });
+  });
+
+  describe('useDocsSidebar', () => {
+    test('should throw if context provider is missing', () => {
+      expect(
+        () => renderHook(() => useDocsSidebar()).result.current,
+      ).toThrowErrorMatchingInlineSnapshot(
+        `"This hook requires usage of <DocsSidebarProvider>"`,
+      );
+    });
+
+    test('should read value from context provider', () => {
+      const sidebar: PropSidebar = [];
+      const {result} = renderHook(() => useDocsSidebar(), {
+        wrapper: ({children}) => (
+          <DocsSidebarProvider sidebar={sidebar}>
+            {children}
+          </DocsSidebarProvider>
+        ),
+      });
+      expect(result.current).toBe(sidebar);
+    });
+  });
+
+  describe('useDocById', () => {
+    const version = testVersion({
+      docs: {
+        doc1: {
+          id: 'doc1',
+          title: 'Doc 1',
+          description: 'desc1',
+          sidebar: 'sidebar1',
+        },
+        doc2: {
+          id: 'doc2',
+          title: 'Doc 2',
+          description: 'desc2',
+          sidebar: 'sidebar2',
+        },
+      },
+    });
+
+    function callHook(docId: string | undefined) {
+      const {result} = renderHook(() => useDocById(docId), {
+        wrapper: ({children}) => (
+          <DocsVersionProvider version={version}>
+            {children}
+          </DocsVersionProvider>
+        ),
+      });
+      return result.current;
+    }
+
+    test('should accept undefined', () => {
+      expect(callHook(undefined)).toBeUndefined();
+    });
+
+    test('should find doc1', () => {
+      expect(callHook('doc1')).toMatchObject({id: 'doc1'});
+    });
+    test('should find doc2', () => {
+      expect(callHook('doc2')).toMatchObject({id: 'doc2'});
+    });
+
+    test('should throw for doc3', () => {
+      expect(() => callHook('doc3')).toThrowErrorMatchingInlineSnapshot(
+        `"no version doc found by id=doc3"`,
+      );
+    });
+  });
+
+  describe('findSidebarCategory', () => {
+    test('should be able to return undefined', () => {
+      expect(findSidebarCategory([], () => false)).toBeUndefined();
+      expect(
+        findSidebarCategory([testCategory(), testCategory()], () => false),
+      ).toBeUndefined();
+    });
+
+    test('should return first element matching predicate', () => {
+      const first = testCategory();
+      const second = testCategory();
+      const third = testCategory();
+      const sidebar = [first, second, third];
+      expect(findSidebarCategory(sidebar, () => true)).toEqual(first);
+      expect(findSidebarCategory(sidebar, (item) => item === first)).toEqual(
+        first,
+      );
+      expect(findSidebarCategory(sidebar, (item) => item === second)).toEqual(
+        second,
+      );
+      expect(findSidebarCategory(sidebar, (item) => item === third)).toEqual(
+        third,
+      );
+    });
+
+    test('should be able to search in sub items', () => {
+      const subsub1 = testCategory();
+      const subsub2 = testCategory();
+      const sub1 = testCategory({
+        items: [subsub1, subsub2],
+      });
+      const sub2 = testCategory();
+      const parent = testCategory({
+        items: [sub1, sub2],
+      });
+      const sidebar = [parent];
+
+      expect(findSidebarCategory(sidebar, () => true)).toEqual(parent);
+      expect(findSidebarCategory(sidebar, (item) => item === sub1)).toEqual(
+        sub1,
+      );
+      expect(findSidebarCategory(sidebar, (item) => item === sub2)).toEqual(
+        sub2,
+      );
+      expect(findSidebarCategory(sidebar, (item) => item === subsub1)).toEqual(
+        subsub1,
+      );
+      expect(findSidebarCategory(sidebar, (item) => item === subsub2)).toEqual(
+        subsub2,
+      );
+    });
+  });
+
+  describe('findFirstCategoryLink', () => {
+    test('category without link nor child', () => {
+      expect(
+        findFirstCategoryLink(
+          testCategory({
+            href: undefined,
+          }),
+        ),
+      ).toEqual(undefined);
+    });
+
+    test('category with link', () => {
+      expect(
+        findFirstCategoryLink(
+          testCategory({
+            href: '/itemPath',
+          }),
+        ),
+      ).toEqual('/itemPath');
+    });
+
+    test('category with deeply nested category link', () => {
+      expect(
+        findFirstCategoryLink(
+          testCategory({
+            href: undefined,
+            items: [
+              testCategory({
+                href: undefined,
+                items: [
+                  testCategory({
+                    href: '/itemPath',
+                  }),
+                ],
+              }),
+            ],
+          }),
+        ),
+      ).toEqual('/itemPath');
+    });
+
+    test('category with deeply nested link', () => {
+      expect(
+        findFirstCategoryLink(
+          testCategory({
+            href: undefined,
+            items: [
+              testCategory({
+                href: undefined,
+                items: [{type: 'link', href: '/itemPath', label: 'Label'}],
+              }),
+            ],
+          }),
+        ),
+      ).toEqual('/itemPath');
+    });
+  });
+
+  describe('isActiveSidebarItem', () => {
+    test('with link href', () => {
+      const item: PropSidebarItem = {
+        type: 'link',
+        href: '/itemPath',
+        label: 'Label',
+      };
+
+      expect(isActiveSidebarItem(item, '/unexistingPath')).toEqual(false);
+
+      expect(isActiveSidebarItem(item, '/itemPath')).toEqual(true);
+
+      // Ensure it's not trailing slash sensitive:
+      expect(isActiveSidebarItem(item, '/itemPath/')).toEqual(true);
+      expect(
+        isActiveSidebarItem({...item, href: '/itemPath/'}, '/itemPath'),
+      ).toEqual(true);
+    });
+
+    test('with category href', () => {
+      const item: PropSidebarItem = testCategory({
+        href: '/itemPath',
+      });
+
+      expect(isActiveSidebarItem(item, '/unexistingPath')).toEqual(false);
+
+      expect(isActiveSidebarItem(item, '/itemPath')).toEqual(true);
+
+      // Ensure it's not trailing slash sensitive:
+      expect(isActiveSidebarItem(item, '/itemPath/')).toEqual(true);
+      expect(
+        isActiveSidebarItem({...item, href: '/itemPath/'}, '/itemPath'),
+      ).toEqual(true);
+    });
+
+    test('with category nested items', () => {
+      const item: PropSidebarItem = testCategory({
+        href: '/category-path',
+        items: [
+          {
+            type: 'link',
+            href: '/sub-link-path',
+            label: 'Label',
+          },
+          testCategory({
+            href: '/sub-category-path',
+            items: [
+              {
+                type: 'link',
+                href: '/sub-sub-link-path',
+                label: 'Label',
+              },
+            ],
+          }),
+        ],
+      });
+
+      expect(isActiveSidebarItem(item, '/unexistingPath')).toEqual(false);
+
+      expect(isActiveSidebarItem(item, '/category-path')).toEqual(true);
+      expect(isActiveSidebarItem(item, '/sub-link-path')).toEqual(true);
+      expect(isActiveSidebarItem(item, '/sub-category-path')).toEqual(true);
+      expect(isActiveSidebarItem(item, '/sub-sub-link-path')).toEqual(true);
+
+      // Ensure it's not trailing slash sensitive:
+      expect(isActiveSidebarItem(item, '/category-path/')).toEqual(true);
+      expect(isActiveSidebarItem(item, '/sub-link-path/')).toEqual(true);
+      expect(isActiveSidebarItem(item, '/sub-category-path/')).toEqual(true);
+      expect(isActiveSidebarItem(item, '/sub-sub-link-path/')).toEqual(true);
+    });
+  });
+});

package/src/utils/docsUtils.tsx

@@ -0,0 +1,185 @@
+/**
+ * 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 React, {createContext, ReactNode, useContext} from 'react';
+import {useAllDocsData} from '@theme/hooks/useDocs';
+import {
+  PropSidebar,
+  PropSidebarItem,
+  PropSidebarItemCategory,
+  PropVersionDoc,
+  PropVersionMetadata,
+} from '@docusaurus/plugin-content-docs';
+import {isSamePath} from './pathUtils';
+import {useLocation} from '@docusaurus/router';
+
+// TODO not ideal, see also "useDocs"
+export const isDocsPluginEnabled: boolean = !!useAllDocsData;
+
+// Using a Symbol because null is a valid context value (a doc can have no sidebar)
+// Inspired by https://github.com/jamiebuilds/unstated-next/blob/master/src/unstated-next.tsx
+const EmptyContextValue: unique symbol = Symbol('EmptyContext');
+
+const DocsVersionContext = createContext<
+  PropVersionMetadata | typeof EmptyContextValue
+>(EmptyContextValue);
+
+export function DocsVersionProvider({
+  children,
+  version,
+}: {
+  children: ReactNode;
+  version: PropVersionMetadata | typeof EmptyContextValue;
+}): JSX.Element {
+  return (
+    <DocsVersionContext.Provider value={version}>
+      {children}
+    </DocsVersionContext.Provider>
+  );
+}
+
+export function useDocsVersion(): PropVersionMetadata {
+  const version = useContext(DocsVersionContext);
+  if (version === EmptyContextValue) {
+    throw new Error('This hook requires usage of <DocsVersionProvider>');
+  }
+  return version;
+}
+
+export function useDocById(id: string): PropVersionDoc;
+export function useDocById(id: string | undefined): PropVersionDoc | undefined;
+export function useDocById(id: string | undefined): PropVersionDoc | undefined {
+  const version = useDocsVersion();
+  if (!id) {
+    return undefined;
+  }
+  const doc = version.docs[id];
+  if (!doc) {
+    throw new Error(`no version doc found by id=${id}`);
+  }
+  return doc;
+}
+
+const DocsSidebarContext = createContext<
+  PropSidebar | null | typeof EmptyContextValue
+>(EmptyContextValue);
+
+export function DocsSidebarProvider({
+  children,
+  sidebar,
+}: {
+  children: ReactNode;
+  sidebar: PropSidebar | null;
+}): JSX.Element {
+  return (
+    <DocsSidebarContext.Provider value={sidebar}>
+      {children}
+    </DocsSidebarContext.Provider>
+  );
+}
+
+export function useDocsSidebar(): PropSidebar | null {
+  const sidebar = useContext(DocsSidebarContext);
+  if (sidebar === EmptyContextValue) {
+    throw new Error('This hook requires usage of <DocsSidebarProvider>');
+  }
+  return sidebar;
+}
+
+// Use the components props and the sidebar in context
+// to get back the related sidebar category that we want to render
+export function findSidebarCategory(
+  sidebar: PropSidebar,
+  predicate: (category: PropSidebarItemCategory) => boolean,
+): PropSidebarItemCategory | undefined {
+  // eslint-disable-next-line no-restricted-syntax
+  for (const item of sidebar) {
+    if (item.type === 'category') {
+      if (predicate(item)) {
+        return item;
+      } else {
+        const subItem = findSidebarCategory(item.items, predicate);
+        if (subItem) {
+          return subItem;
+        }
+      }
+    }
+  }
+  return undefined;
+}
+
+// If a category card has no link => link to the first subItem having a link
+export function findFirstCategoryLink(
+  item: PropSidebarItemCategory,
+): string | undefined {
+  if (item.href) {
+    return item.href;
+  }
+
+  // eslint-disable-next-line no-restricted-syntax
+  for (const subItem of item.items) {
+    if (subItem.type === 'link') {
+      return subItem.href;
+    }
+    if (subItem.type === 'category') {
+      const categoryLink = findFirstCategoryLink(subItem);
+      if (categoryLink) {
+        return categoryLink;
+      }
+    } else {
+      throw new Error(
+        `Unexpected category item type for ${JSON.stringify(subItem)}`,
+      );
+    }
+  }
+  return undefined;
+}
+
+export function useCurrentSidebarCategory(): PropSidebarItemCategory {
+  const {pathname} = useLocation();
+  const sidebar = useDocsSidebar();
+  if (!sidebar) {
+    throw new Error('Unexpected: cant find current sidebar in context');
+  }
+  const category = findSidebarCategory(sidebar, (item) =>
+    isSamePath(item.href, pathname),
+  );
+  if (!category) {
+    throw new Error(
+      `Unexpected: sidebar category could not be found for pathname='${pathname}'.
+Hook useCurrentSidebarCategory() should only be used on Category pages`,
+    );
+  }
+  return category;
+}
+
+function containsActiveSidebarItem(
+  items: PropSidebarItem[],
+  activePath: string,
+): boolean {
+  return items.some((subItem) => isActiveSidebarItem(subItem, activePath));
+}
+
+export function isActiveSidebarItem(
+  item: PropSidebarItem,
+  activePath: string,
+): boolean {
+  const isActive = (testedPath: string | undefined) =>
+    typeof testedPath !== 'undefined' && isSamePath(testedPath, activePath);
+
+  if (item.type === 'link') {
+    return isActive(item.href);
+  }
+
+  if (item.type === 'category') {
+    return (
+      isActive(item.href) || containsActiveSidebarItem(item.items, activePath)
+    );
+  }
+
+  return false;
+}

package/src/utils/storageUtils.ts

@@ -79,6 +79,10 @@ Please only call storage APIs in effects and event handlers.`);
 
 /**
  * Creates an object for accessing a particular key in localStorage.
+ * The API is fail-safe, and usage of browser storage should be considered unreliable
+ * Local storage might simply be unavailable (iframe + browser security) or operations might fail individually
+ * Please assume that using this API can be a NO-OP
+ * See also https://github.com/facebook/docusaurus/issues/6036
  */
 export const createStorageSlot = (
   key: string,
@@ -92,9 +96,28 @@ export const createStorageSlot = (
     return NoopStorageSlot;
   }
   return {
-    get: () => browserStorage.getItem(key),
-    set: (value) => browserStorage.setItem(key, value),
-    del: () => browserStorage.removeItem(key),
+    get: () => {
+      try {
+        return browserStorage.getItem(key);
+      } catch (e) {
+        console.error(`Docusaurus storage error, can't get key=${key}`, e);
+        return null;
+      }
+    },
+    set: (value) => {
+      try {
+        browserStorage.setItem(key, value);
+      } catch (e) {
+        console.error(`Docusaurus storage error, can't set ${key}=${value}`, e);
+      }
+    },
+    del: () => {
+      try {
+        browserStorage.removeItem(key);
+      } catch (e) {
+        console.error(`Docusaurus storage error, can't delete key=${key}`, e);
+      }
+    },
   };
 };
 

package/src/utils/docsUtils.ts

@@ -1,11 +0,0 @@
-/**
- * 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 {useAllDocsData} from '@theme/hooks/useDocs';
-
-// TODO not ideal, see also "useDocs"
-export const isDocsPluginEnabled: boolean = !!useAllDocsData;