@docusaurus/theme-common 2.2.0 → 2.3.1

package/src/utils/tabsUtils.tsx

@@ -0,0 +1,270 @@
+/**
+ * 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,
+  type ReactNode,
+  type ReactElement,
+  useLayoutEffect,
+} 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>[]
+    | 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;
+  })();
+  // 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: 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};
+}

package/lib/contexts/tabGroupChoice.d.ts

@@ -1,21 +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 { type ReactNode } from 'react';
-declare type ContextValue = {
-    /** 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;
-};
-export declare function TabGroupChoiceProvider({ children, }: {
-    children: ReactNode;
-}): JSX.Element;
-export declare function useTabGroupChoice(): ContextValue;
-export {};
-//# sourceMappingURL=tabGroupChoice.d.ts.map

package/lib/contexts/tabGroupChoice.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"tabGroupChoice.d.ts","sourceRoot":"","sources":["../../src/contexts/tabGroupChoice.tsx"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAc,EAMZ,KAAK,SAAS,EACf,MAAM,OAAO,CAAC;AAMf,aAAK,YAAY,GAAG;IAClB,+DAA+D;IAC/D,QAAQ,CAAC,eAAe,EAAE;QAAC,QAAQ,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAAA;KAAC,CAAC;IAC/D,2CAA2C;IAC3C,QAAQ,CAAC,kBAAkB,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,KAAK,IAAI,CAAC;CAC3E,CAAC;AA4CF,wBAAgB,sBAAsB,CAAC,EACrC,QAAQ,GACT,EAAE;IACD,QAAQ,EAAE,SAAS,CAAC;CACrB,GAAG,GAAG,CAAC,OAAO,CAGd;AAED,wBAAgB,iBAAiB,IAAI,YAAY,CAMhD"}

package/lib/contexts/tabGroupChoice.js

@@ -1,49 +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, } from 'react';
-import { createStorageSlot, listStorageKeys } from '../utils/storageUtils';
-import { ReactContextError } from '../utils/reactUtils';
-const TAB_CHOICE_PREFIX = 'docusaurus.tab.';
-const Context = React.createContext(undefined);
-function useContextValue() {
-    const [tabGroupChoices, setChoices] = useState({});
-    const setChoiceSyncWithLocalStorage = useCallback((groupId, newChoice) => {
-        createStorageSlot(`${TAB_CHOICE_PREFIX}${groupId}`).set(newChoice);
-    }, []);
-    useEffect(() => {
-        try {
-            const localStorageChoices = {};
-            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);
-        }
-    }, []);
-    const setTabGroupChoices = useCallback((groupId, newChoice) => {
-        setChoices((oldChoices) => ({ ...oldChoices, [groupId]: newChoice }));
-        setChoiceSyncWithLocalStorage(groupId, newChoice);
-    }, [setChoiceSyncWithLocalStorage]);
-    return useMemo(() => ({ tabGroupChoices, setTabGroupChoices }), [tabGroupChoices, setTabGroupChoices]);
-}
-export function TabGroupChoiceProvider({ children, }) {
-    const value = useContextValue();
-    return <Context.Provider value={value}>{children}</Context.Provider>;
-}
-export function useTabGroupChoice() {
-    const context = useContext(Context);
-    if (context == null) {
-        throw new ReactContextError('TabGroupChoiceProvider');
-    }
-    return context;
-}
-//# sourceMappingURL=tabGroupChoice.js.map

package/lib/contexts/tabGroupChoice.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"tabGroupChoice.js","sourceRoot":"","sources":["../../src/contexts/tabGroupChoice.tsx"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,EACZ,QAAQ,EACR,WAAW,EACX,SAAS,EACT,OAAO,EACP,UAAU,GAEX,MAAM,OAAO,CAAC;AACf,OAAO,EAAC,iBAAiB,EAAE,eAAe,EAAC,MAAM,uBAAuB,CAAC;AACzE,OAAO,EAAC,iBAAiB,EAAC,MAAM,qBAAqB,CAAC;AAEtD,MAAM,iBAAiB,GAAG,iBAAiB,CAAC;AAS5C,MAAM,OAAO,GAAG,KAAK,CAAC,aAAa,CAA2B,SAAS,CAAC,CAAC;AAEzE,SAAS,eAAe;IACtB,MAAM,CAAC,eAAe,EAAE,UAAU,CAAC,GAAG,QAAQ,CAE3C,EAAE,CAAC,CAAC;IACP,MAAM,6BAA6B,GAAG,WAAW,CAC/C,CAAC,OAAe,EAAE,SAAiB,EAAE,EAAE;QACrC,iBAAiB,CAAC,GAAG,iBAAiB,GAAG,OAAO,EAAE,CAAC,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;IACrE,CAAC,EACD,EAAE,CACH,CAAC;IAEF,SAAS,CAAC,GAAG,EAAE;QACb,IAAI;YACF,MAAM,mBAAmB,GAAgC,EAAE,CAAC;YAC5D,eAAe,EAAE,CAAC,OAAO,CAAC,CAAC,UAAU,EAAE,EAAE;gBACvC,IAAI,UAAU,CAAC,UAAU,CAAC,iBAAiB,CAAC,EAAE;oBAC5C,MAAM,OAAO,GAAG,UAAU,CAAC,SAAS,CAAC,iBAAiB,CAAC,MAAM,CAAC,CAAC;oBAC/D,mBAAmB,CAAC,OAAO,CAAC,GAAG,iBAAiB,CAAC,UAAU,CAAC,CAAC,GAAG,EAAG,CAAC;iBACrE;YACH,CAAC,CAAC,CAAC;YACH,UAAU,CAAC,mBAAmB,CAAC,CAAC;SACjC;QAAC,OAAO,GAAG,EAAE;YACZ,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;SACpB;IACH,CAAC,EAAE,EAAE,CAAC,CAAC;IAEP,MAAM,kBAAkB,GAAG,WAAW,CACpC,CAAC,OAAe,EAAE,SAAiB,EAAE,EAAE;QACrC,UAAU,CAAC,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC,EAAC,GAAG,UAAU,EAAE,CAAC,OAAO,CAAC,EAAE,SAAS,EAAC,CAAC,CAAC,CAAC;QACpE,6BAA6B,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC;IACpD,CAAC,EACD,CAAC,6BAA6B,CAAC,CAChC,CAAC;IAEF,OAAO,OAAO,CACZ,GAAG,EAAE,CAAC,CAAC,EAAC,eAAe,EAAE,kBAAkB,EAAC,CAAC,EAC7C,CAAC,eAAe,EAAE,kBAAkB,CAAC,CACtC,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,sBAAsB,CAAC,EACrC,QAAQ,GAGT;IACC,MAAM,KAAK,GAAG,eAAe,EAAE,CAAC;IAChC,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC;AACvE,CAAC;AAED,MAAM,UAAU,iBAAiB;IAC/B,MAAM,OAAO,GAAG,UAAU,CAAC,OAAO,CAAC,CAAC;IACpC,IAAI,OAAO,IAAI,IAAI,EAAE;QACnB,MAAM,IAAI,iBAAiB,CAAC,wBAAwB,CAAC,CAAC;KACvD;IACD,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/src/contexts/tabGroupChoice.tsx

@@ -1,85 +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 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 [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);
-    }
-  }, []);
-
-  const setTabGroupChoices = useCallback(
-    (groupId: string, newChoice: string) => {
-      setChoices((oldChoices) => ({...oldChoices, [groupId]: newChoice}));
-      setChoiceSyncWithLocalStorage(groupId, newChoice);
-    },
-    [setChoiceSyncWithLocalStorage],
-  );
-
-  return useMemo(
-    () => ({tabGroupChoices, setTabGroupChoices}),
-    [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;
-}