@docusaurus/theme-common 2.2.0 → 2.3.1

package/lib/utils/tabsUtils.js

@@ -0,0 +1,153 @@
+/**
+ * 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, { isValidElement, useCallback, useState, useMemo, useLayoutEffect, } from 'react';
+import { useHistory } from '@docusaurus/router';
+import { useQueryStringValue } from '@docusaurus/theme-common/internal';
+import { duplicates, useStorageSlot } from '../index';
+// A very rough duck type, but good enough to guard against mistakes while
+// allowing customization
+function isTabItem(comp) {
+    return 'value' in comp.props;
+}
+function ensureValidChildren(children) {
+    return React.Children.map(children, (child) => {
+        if (isValidElement(child) && isTabItem(child)) {
+            return child;
+        }
+        // child.type.name will give non-sensical values in prod because of
+        // minification, but we assume it won't throw in prod.
+        throw new Error(`Docusaurus error: Bad <Tabs> child <${
+        // @ts-expect-error: guarding against unexpected cases
+        typeof child.type === 'string' ? child.type : child.type.name}>: all children of the <Tabs> component should be <TabItem>, and every <TabItem> should have a unique "value" prop.`);
+    });
+}
+function extractChildrenTabValues(children) {
+    return ensureValidChildren(children).map(({ props: { value, label, attributes, default: isDefault } }) => ({
+        value,
+        label,
+        attributes,
+        default: isDefault,
+    }));
+}
+function ensureNoDuplicateValue(values) {
+    const dup = duplicates(values, (a, b) => a.value === b.value);
+    if (dup.length > 0) {
+        throw new Error(`Docusaurus error: Duplicate values "${dup
+            .map((a) => a.value)
+            .join(', ')}" found in <Tabs>. Every value needs to be unique.`);
+    }
+}
+function useTabValues(props) {
+    const { values: valuesProp, children } = props;
+    return useMemo(() => {
+        const values = valuesProp ?? extractChildrenTabValues(children);
+        ensureNoDuplicateValue(values);
+        return values;
+    }, [valuesProp, children]);
+}
+function isValidValue({ value, tabValues, }) {
+    return tabValues.some((a) => a.value === value);
+}
+function getInitialStateValue({ defaultValue, tabValues, }) {
+    if (tabValues.length === 0) {
+        throw new Error('Docusaurus error: the <Tabs> component requires at least one <TabItem> children component');
+    }
+    if (defaultValue) {
+        // Warn user about passing incorrect defaultValue as prop.
+        if (!isValidValue({ value: defaultValue, tabValues })) {
+            throw new Error(`Docusaurus error: The <Tabs> has a defaultValue "${defaultValue}" but none of its children has the corresponding value. Available values are: ${tabValues
+                .map((a) => a.value)
+                .join(', ')}. If you intend to show no default tab, use defaultValue={null} instead.`);
+        }
+        return defaultValue;
+    }
+    const defaultTabValue = tabValues.find((tabValue) => tabValue.default) ?? tabValues[0];
+    if (!defaultTabValue) {
+        throw new Error('Unexpected error: 0 tabValues');
+    }
+    return defaultTabValue.value;
+}
+function getStorageKey(groupId) {
+    if (!groupId) {
+        return null;
+    }
+    return `docusaurus.tab.${groupId}`;
+}
+function getQueryStringKey({ queryString = false, groupId, }) {
+    if (typeof queryString === 'string') {
+        return queryString;
+    }
+    if (queryString === false) {
+        return null;
+    }
+    if (queryString === true && !groupId) {
+        throw new Error(`Docusaurus error: The <Tabs> component groupId prop is required if queryString=true, because this value is used as the search param name. You can also provide an explicit value such as queryString="my-search-param".`);
+    }
+    return groupId ?? null;
+}
+function useTabQueryString({ queryString = false, groupId, }) {
+    const history = useHistory();
+    const key = getQueryStringKey({ queryString, groupId });
+    const value = useQueryStringValue(key);
+    const setValue = useCallback((newValue) => {
+        if (!key) {
+            return; // no-op
+        }
+        const searchParams = new URLSearchParams(history.location.search);
+        searchParams.set(key, newValue);
+        history.replace({ ...history.location, search: searchParams.toString() });
+    }, [key, history]);
+    return [value, setValue];
+}
+function useTabStorage({ groupId }) {
+    const key = getStorageKey(groupId);
+    const [value, storageSlot] = useStorageSlot(key);
+    const setValue = useCallback((newValue) => {
+        if (!key) {
+            return; // no-op
+        }
+        storageSlot.set(newValue);
+    }, [key, storageSlot]);
+    return [value, setValue];
+}
+export function useTabs(props) {
+    const { defaultValue, queryString = false, groupId } = props;
+    const tabValues = useTabValues(props);
+    const [selectedValue, setSelectedValue] = useState(() => getInitialStateValue({ defaultValue, tabValues }));
+    const [queryStringValue, setQueryString] = useTabQueryString({
+        queryString,
+        groupId,
+    });
+    const [storageValue, setStorageValue] = useTabStorage({
+        groupId,
+    });
+    // We sync valid querystring/storage value to state on change + hydration
+    const valueToSync = (() => {
+        const value = queryStringValue ?? storageValue;
+        if (!isValidValue({ value, tabValues })) {
+            return null;
+        }
+        return value;
+    })();
+    // Sync in a layout/sync effect is important, for useScrollPositionBlocker
+    // See https://github.com/facebook/docusaurus/issues/8625
+    useLayoutEffect(() => {
+        if (valueToSync) {
+            setSelectedValue(valueToSync);
+        }
+    }, [valueToSync]);
+    const selectValue = useCallback((newValue) => {
+        if (!isValidValue({ value: newValue, tabValues })) {
+            throw new Error(`Can't select invalid tab value=${newValue}`);
+        }
+        setSelectedValue(newValue);
+        setQueryString(newValue);
+        setStorageValue(newValue);
+    }, [setQueryString, setStorageValue, tabValues]);
+    return { selectedValue, selectValue, tabValues };
+}
+//# sourceMappingURL=tabsUtils.js.map

package/lib/utils/tabsUtils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tabsUtils.js","sourceRoot":"","sources":["../../src/utils/tabsUtils.tsx"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docusaurus/theme-common",
-  "version": "2.2.0",
+  "version": "2.3.1",
   "description": "Common code for Docusaurus themes.",
   "main": "./lib/index.js",
   "types": "./lib/index.d.ts",
@@ -30,12 +30,12 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@docusaurus/mdx-loader": "2.2.0",
-    "@docusaurus/module-type-aliases": "2.2.0",
-    "@docusaurus/plugin-content-blog": "2.2.0",
-    "@docusaurus/plugin-content-docs": "2.2.0",
-    "@docusaurus/plugin-content-pages": "2.2.0",
-    "@docusaurus/utils": "2.2.0",
+    "@docusaurus/mdx-loader": "2.3.1",
+    "@docusaurus/module-type-aliases": "2.3.1",
+    "@docusaurus/plugin-content-blog": "2.3.1",
+    "@docusaurus/plugin-content-docs": "2.3.1",
+    "@docusaurus/plugin-content-pages": "2.3.1",
+    "@docusaurus/utils": "2.3.1",
     "@types/history": "^4.7.11",
     "@types/react": "*",
     "@types/react-router-config": "*",
@@ -43,11 +43,12 @@
     "parse-numeric-range": "^1.3.0",
     "prism-react-renderer": "^1.3.5",
     "tslib": "^2.4.0",
+    "use-sync-external-store": "^1.2.0",
     "utility-types": "^3.10.0"
   },
   "devDependencies": {
-    "@docusaurus/core": "2.2.0",
-    "@docusaurus/types": "2.2.0",
+    "@docusaurus/core": "2.3.1",
+    "@docusaurus/types": "2.3.1",
     "fs-extra": "^10.1.0",
     "lodash": "^4.17.21"
   },
@@ -58,5 +59,5 @@
   "engines": {
     "node": ">=16.14"
   },
-  "gitHead": "a308fb7c81832cca354192fe2984f52749441249"
+  "gitHead": "cf12f21a10f6c5439ff931e61419c4bb03a5a2dc"
 }

package/src/hooks/useSearchPage.ts

@@ -8,6 +8,7 @@
 import {useCallback, useEffect, useState} from 'react';
 import {useHistory} from '@docusaurus/router';
 import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
+import type {ThemeConfig as AlgoliaThemeConfig} from '@docusaurus/theme-search-algolia';
 
 const SEARCH_PARAM_QUERY = 'q';
 
@@ -31,8 +32,11 @@ export function useSearchPage(): {
 } {
   const history = useHistory();
   const {
-    siteConfig: {baseUrl},
+    siteConfig: {baseUrl, themeConfig},
   } = useDocusaurusContext();
+  const {
+    algolia: {searchPagePath},
+  } = themeConfig as AlgoliaThemeConfig;
 
   const [searchQuery, setSearchQueryState] = useState('');
 
@@ -65,10 +69,11 @@ export function useSearchPage(): {
   const generateSearchPageLink = useCallback(
     (targetSearchQuery: string) =>
       // Refer to https://github.com/facebook/docusaurus/pull/2838
-      `${baseUrl}search?${SEARCH_PARAM_QUERY}=${encodeURIComponent(
-        targetSearchQuery,
-      )}`,
-    [baseUrl],
+      // Note: if searchPagePath is falsy, useSearchPage() will not be called
+      `${baseUrl}${
+        searchPagePath as string
+      }?${SEARCH_PARAM_QUERY}=${encodeURIComponent(targetSearchQuery)}`,
+    [baseUrl, searchPagePath],
   );
 
   return {

package/src/index.ts

@@ -24,7 +24,11 @@ export {
   type ColorModeConfig,
 } from './utils/useThemeConfig';
 
-export {createStorageSlot, listStorageKeys} from './utils/storageUtils';
+export {
+  createStorageSlot,
+  useStorageSlot,
+  listStorageKeys,
+} from './utils/storageUtils';
 
 export {useContextualSearchFilters} from './utils/searchUtils';
 

package/src/internal.ts

@@ -42,10 +42,8 @@ export {
   useAnnouncementBar,
 } from './contexts/announcementBar';
 
-export {
-  useTabGroupChoice,
-  TabGroupChoiceProvider,
-} from './contexts/tabGroupChoice';
+export {useTabs} from './utils/tabsUtils';
+export type {TabValue, TabsProps, TabItemProps} from './utils/tabsUtils';
 
 export {useNavbarMobileSidebar} from './contexts/navbarMobileSidebar';
 export {useNavbarSecondaryMenu} from './contexts/navbarSecondaryMenu/display';
@@ -82,7 +80,11 @@ export {useLocationChange} from './utils/useLocationChange';
 
 export {useLocalPathname} from './utils/useLocalPathname';
 
-export {useHistoryPopHandler} from './utils/historyUtils';
+export {
+  useHistoryPopHandler,
+  useHistorySelector,
+  useQueryStringValue,
+} from './utils/historyUtils';
 
 export {
   useFilteredAndTreeifiedTOC,

package/src/utils/historyUtils.ts

@@ -7,8 +7,11 @@
 
 import {useEffect} from 'react';
 import {useHistory} from '@docusaurus/router';
+// @ts-expect-error: TODO temporary until React 18 upgrade
+import {useSyncExternalStore} from 'use-sync-external-store/shim';
 import {useEvent} from './reactUtils';
-import type {Location, Action} from 'history';
+
+import type {History, Location, Action} from 'history';
 
 type HistoryBlockHandler = (location: Location, action: Action) => void | false;
 
@@ -43,3 +46,32 @@ export function useHistoryPopHandler(handler: HistoryBlockHandler): void {
     return undefined;
   });
 }
+
+/**
+ * Permits to efficiently subscribe to a slice of the history
+ * See https://thisweekinreact.com/articles/useSyncExternalStore-the-underrated-react-api
+ * @param selector
+ */
+export function useHistorySelector<Value>(
+  selector: (history: History<unknown>) => Value,
+): Value {
+  const history = useHistory();
+  return useSyncExternalStore(
+    history.listen,
+    () => selector(history),
+    () => selector(history),
+  );
+}
+
+/**
+ * Permits to efficiently subscribe to a specific querystring value
+ * @param key
+ */
+export function useQueryStringValue(key: string | null): string | null {
+  return useHistorySelector((history) => {
+    if (key === null) {
+      return null;
+    }
+    return new URLSearchParams(history.location.search).get(key);
+  });
+}

package/src/utils/scrollUtils.tsx

@@ -222,7 +222,10 @@ export function useScrollPositionBlocker(): {
   );
 
   useLayoutEffect(() => {
-    nextLayoutEffectCallbackRef.current?.();
+    // Queuing permits to restore scroll position after all useLayoutEffect
+    // have run, and yet preserve the sync nature of the scroll restoration
+    // See https://github.com/facebook/docusaurus/issues/8625
+    queueMicrotask(() => nextLayoutEffectCallbackRef.current?.());
   });
 
   return {

package/src/utils/storageUtils.ts

@@ -5,12 +5,53 @@
  * LICENSE file in the root directory of this source tree.
  */
 
+import {useCallback, useRef} from 'react';
+// @ts-expect-error: TODO temp error until React 18 upgrade
+import {useSyncExternalStore} from 'use-sync-external-store/shim';
+
 const StorageTypes = ['localStorage', 'sessionStorage', 'none'] as const;
 
 export type StorageType = typeof StorageTypes[number];
 
 const DefaultStorageType: StorageType = 'localStorage';
 
+// window.addEventListener('storage') only works for different windows...
+// so for current window we have to dispatch the event manually
+// Now we can listen for both cross-window / current-window storage changes!
+// see https://stackoverflow.com/a/71177640/82609
+// see https://stackoverflow.com/questions/26974084/listen-for-changes-with-localstorage-on-the-same-window
+function dispatchChangeEvent({
+  key,
+  oldValue,
+  newValue,
+  storage,
+}: {
+  key: string;
+  oldValue: string | null;
+  newValue: string | null;
+  storage: Storage;
+}) {
+  // If we set multiple times the same storage value, events should not be fired
+  // The native events behave this way, so our manual event dispatch should
+  // rather behave exactly the same. Not doing so might create infinite loops.
+  // See https://github.com/facebook/docusaurus/issues/8594
+  if (oldValue === newValue) {
+    return;
+  }
+  const event = document.createEvent('StorageEvent');
+  event.initStorageEvent(
+    'storage',
+    false,
+    false,
+    key,
+    oldValue,
+    newValue,
+    window.location.href,
+    storage,
+  );
+  window.dispatchEvent(event);
+}
+
 /**
  * Will return `null` if browser storage is unavailable (like running Docusaurus
  * in an iframe). This should NOT be called in SSR.
@@ -58,12 +99,14 @@ export type StorageSlot = {
   get: () => string | null;
   set: (value: string) => void;
   del: () => void;
+  listen: (onChange: (event: StorageEvent) => void) => () => void;
 };
 
 const NoopStorageSlot: StorageSlot = {
   get: () => null,
   set: () => {},
   del: () => {},
+  listen: () => () => {},
 };
 
 // Fail-fast, as storage APIs should not be used during the SSR process
@@ -78,6 +121,7 @@ Please only call storage APIs in effects and event handlers.`);
     get: throwError,
     set: throwError,
     del: throwError,
+    listen: throwError,
   };
 }
 
@@ -98,39 +142,103 @@ export function createStorageSlot(
   if (typeof window === 'undefined') {
     return createServerStorageSlot(key);
   }
-  const browserStorage = getBrowserStorage(options?.persistence);
-  if (browserStorage === null) {
+  const storage = getBrowserStorage(options?.persistence);
+  if (storage === null) {
     return NoopStorageSlot;
   }
   return {
     get: () => {
       try {
-        return browserStorage.getItem(key);
+        return storage.getItem(key);
       } catch (err) {
         console.error(`Docusaurus storage error, can't get key=${key}`, err);
         return null;
       }
     },
-    set: (value) => {
+    set: (newValue) => {
       try {
-        browserStorage.setItem(key, value);
+        const oldValue = storage.getItem(key);
+        storage.setItem(key, newValue);
+        dispatchChangeEvent({
+          key,
+          oldValue,
+          newValue,
+          storage,
+        });
       } catch (err) {
         console.error(
-          `Docusaurus storage error, can't set ${key}=${value}`,
+          `Docusaurus storage error, can't set ${key}=${newValue}`,
           err,
         );
       }
     },
     del: () => {
       try {
-        browserStorage.removeItem(key);
+        const oldValue = storage.getItem(key);
+        storage.removeItem(key);
+        dispatchChangeEvent({key, oldValue, newValue: null, storage});
       } catch (err) {
         console.error(`Docusaurus storage error, can't delete key=${key}`, err);
       }
     },
+    listen: (onChange) => {
+      try {
+        const listener = (event: StorageEvent) => {
+          if (event.storageArea === storage && event.key === key) {
+            onChange(event);
+          }
+        };
+        window.addEventListener('storage', listener);
+        return () => window.removeEventListener('storage', listener);
+      } catch (err) {
+        console.error(
+          `Docusaurus storage error, can't listen for changes of key=${key}`,
+          err,
+        );
+        return () => {};
+      }
+    },
   };
 }
 
+export function useStorageSlot(
+  key: string | null,
+  options?: {persistence?: StorageType},
+): [string | null, StorageSlot] {
+  // Not ideal but good enough: assumes storage slot config is constant
+  const storageSlot = useRef(() => {
+    if (key === null) {
+      return NoopStorageSlot;
+    }
+    return createStorageSlot(key, options);
+  }).current();
+
+  const listen: StorageSlot['listen'] = useCallback(
+    (onChange) => {
+      // Do not try to add a listener during SSR
+      if (typeof window === 'undefined') {
+        return () => {};
+      }
+      return storageSlot.listen(onChange);
+    },
+    [storageSlot],
+  );
+
+  const currentValue = useSyncExternalStore(
+    listen,
+    () => {
+      // TODO this check should be useless after React 18
+      if (typeof window === 'undefined') {
+        return null;
+      }
+      return storageSlot.get();
+    },
+    () => null,
+  );
+
+  return [currentValue, storageSlot];
+}
+
 /**
  * Returns a list of all the keys currently stored in browser storage,
  * or an empty list if browser storage can't be accessed.