fix(theme): refactor Tabs, make groupId + queryString work fine together (#8486)

packages/docusaurus-theme-common/src/contexts/tabGroupChoice.tsx

@@ -1,89 +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 React, {
-  useState,
-  useCallback,
-  useEffect,
-  useMemo,
-  useContext,
-  type ReactNode,
-} from 'react';
-import {createStorageSlot, listStorageKeys} from '../utils/storageUtils';
-import {ReactContextError} from '../utils/reactUtils';
-
-const TAB_CHOICE_PREFIX = 'docusaurus.tab.';
-
-type ContextValue = {
-  /** A boolean that tells if choices have already been restored from storage */
-  readonly ready: boolean;
-  /** A map from `groupId` to the `value` of the saved choice. */
-  readonly tabGroupChoices: {readonly [groupId: string]: string};
-  /** Set the new choice value of a group. */
-  readonly setTabGroupChoices: (groupId: string, newChoice: string) => void;
-};
-
-const Context = React.createContext<ContextValue | undefined>(undefined);
-
-function useContextValue(): ContextValue {
-  const [ready, setReady] = useState(false);
-  const [tabGroupChoices, setChoices] = useState<{
-    readonly [groupId: string]: string;
-  }>({});
-  const setChoiceSyncWithLocalStorage = useCallback(
-    (groupId: string, newChoice: string) => {
-      createStorageSlot(`${TAB_CHOICE_PREFIX}${groupId}`).set(newChoice);
-    },
-    [],
-  );
-
-  useEffect(() => {
-    try {
-      const localStorageChoices: {[groupId: string]: string} = {};
-      listStorageKeys().forEach((storageKey) => {
-        if (storageKey.startsWith(TAB_CHOICE_PREFIX)) {
-          const groupId = storageKey.substring(TAB_CHOICE_PREFIX.length);
-          localStorageChoices[groupId] = createStorageSlot(storageKey).get()!;
-        }
-      });
-      setChoices(localStorageChoices);
-    } catch (err) {
-      console.error(err);
-    }
-    setReady(true);
-  }, []);
-
-  const setTabGroupChoices = useCallback(
-    (groupId: string, newChoice: string) => {
-      setChoices((oldChoices) => ({...oldChoices, [groupId]: newChoice}));
-      setChoiceSyncWithLocalStorage(groupId, newChoice);
-    },
-    [setChoiceSyncWithLocalStorage],
-  );
-
-  return useMemo(
-    () => ({ready, tabGroupChoices, setTabGroupChoices}),
-    [ready, tabGroupChoices, setTabGroupChoices],
-  );
-}
-
-export function TabGroupChoiceProvider({
-  children,
-}: {
-  children: ReactNode;
-}): JSX.Element {
-  const value = useContextValue();
-  return <Context.Provider value={value}>{children}</Context.Provider>;
-}
-
-export function useTabGroupChoice(): ContextValue {
-  const context = useContext(Context);
-  if (context == null) {
-    throw new ReactContextError('TabGroupChoiceProvider');
-  }
-  return context;
-}

packages/docusaurus-theme-common/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';
 

packages/docusaurus-theme-common/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';
@@ -84,7 +82,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,

packages/docusaurus-theme-common/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,28 @@ 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));
+}
+
+/**
+ * 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);
+  });
+}

packages/docusaurus-theme-common/src/utils/storageUtils.ts

@@ -5,12 +5,46 @@
  * 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;
+}) {
+  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 +92,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 +114,7 @@ Please only call storage APIs in effects and event handlers.`);
     get: throwError,
     set: throwError,
     del: throwError,
+    listen: throwError,
   };
 }
 
@@ -98,39 +135,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.

packages/docusaurus-theme-common/src/utils/tabsUtils.tsx

@@ -0,0 +1,266 @@
+/**
+ * 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,
+  useEffect,
+  useState,
+  useMemo,
+  type ReactNode,
+  type ReactElement,
+} from 'react';
+import {useHistory} from '@docusaurus/router';
+import {useQueryStringValue} from '@docusaurus/theme-common/internal';
+import {duplicates, useStorageSlot} from '../index';
+
+/**
+ * TabValue is the "config" of a given Tab
+ * Provided through <Tabs> "values" prop or through the children <TabItem> props
+ */
+export interface TabValue {
+  readonly value: string;
+  readonly label?: string;
+  readonly attributes?: {[key: string]: unknown};
+  readonly default?: boolean;
+}
+
+export interface TabsProps {
+  readonly lazy?: boolean;
+  readonly block?: boolean;
+  readonly children: readonly ReactElement<TabItemProps>[];
+  readonly defaultValue?: string | null;
+  readonly values?: readonly TabValue[];
+  readonly groupId?: string;
+  readonly className?: string;
+  readonly queryString?: string | boolean;
+}
+
+export interface TabItemProps {
+  readonly children: ReactNode;
+  readonly value: string;
+  readonly default?: boolean;
+  readonly label?: string;
+  readonly hidden?: boolean;
+  readonly className?: string;
+  readonly attributes?: {[key: string]: unknown};
+}
+
+// A very rough duck type, but good enough to guard against mistakes while
+// allowing customization
+function isTabItem(
+  comp: ReactElement<object>,
+): comp is ReactElement<TabItemProps> {
+  return 'value' in comp.props;
+}
+
+function ensureValidChildren(children: TabsProps['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: TabsProps['children']): TabValue[] {
+  return ensureValidChildren(children).map(
+    ({props: {value, label, attributes, default: isDefault}}) => ({
+      value,
+      label,
+      attributes,
+      default: isDefault,
+    }),
+  );
+}
+
+function ensureNoDuplicateValue(values: readonly TabValue[]) {
+  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: Pick<TabsProps, 'values' | 'children'>,
+): readonly TabValue[] {
+  const {values: valuesProp, children} = props;
+  return useMemo(() => {
+    const values = valuesProp ?? extractChildrenTabValues(children);
+    ensureNoDuplicateValue(values);
+    return values;
+  }, [valuesProp, children]);
+}
+
+function isValidValue({
+  value,
+  tabValues,
+}: {
+  value: string | null | undefined;
+  tabValues: readonly TabValue[];
+}) {
+  return tabValues.some((a) => a.value === value);
+}
+
+function getInitialStateValue({
+  defaultValue,
+  tabValues,
+}: {
+  defaultValue: TabsProps['defaultValue'];
+  tabValues: readonly TabValue[];
+}): string {
+  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: string | undefined) {
+  if (!groupId) {
+    return null;
+  }
+  return `docusaurus.tab.${groupId}`;
+}
+
+function getQueryStringKey({
+  queryString = false,
+  groupId,
+}: Pick<TabsProps, 'queryString' | '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,
+}: Pick<TabsProps, 'queryString' | 'groupId'>) {
+  const history = useHistory();
+  const key = getQueryStringKey({queryString, groupId});
+  const value = useQueryStringValue(key);
+
+  const setValue = useCallback(
+    (newValue: string) => {
+      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] as const;
+}
+
+function useTabStorage({groupId}: Pick<TabsProps, 'groupId'>) {
+  const key = getStorageKey(groupId);
+  const [value, storageSlot] = useStorageSlot(key);
+
+  const setValue = useCallback(
+    (newValue: string) => {
+      if (!key) {
+        return; // no-op
+      }
+      storageSlot.set(newValue);
+    },
+    [key, storageSlot],
+  );
+
+  return [value, setValue] as const;
+}
+
+export function useTabs(props: TabsProps): {
+  selectedValue: string;
+  selectValue: (value: string) => void;
+  tabValues: readonly TabValue[];
+} {
+  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;
+  })();
+  useEffect(() => {
+    if (valueToSync) {
+      setSelectedValue(valueToSync);
+    }
+  }, [valueToSync]);
+
+  const selectValue = useCallback(
+    (newValue: string) => {
+      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};
+}