@docusaurus/theme-common 2.1.0 → 2.3.0

package/lib/utils/tabsUtils.d.ts

@@ -0,0 +1,46 @@
+/**
+ * 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, type ReactElement } from 'react';
+/**
+ * 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;
+    };
+}
+export declare function useTabs(props: TabsProps): {
+    selectedValue: string;
+    selectValue: (value: string) => void;
+    tabValues: readonly TabValue[];
+};
+//# sourceMappingURL=tabsUtils.d.ts.map

package/lib/utils/tabsUtils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tabsUtils.d.ts","sourceRoot":"","sources":["../../src/utils/tabsUtils.tsx"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAc,EAMZ,KAAK,SAAS,EACd,KAAK,YAAY,EAClB,MAAM,OAAO,CAAC;AAKf;;;GAGG;AACH,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,UAAU,CAAC,EAAE;QAAC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;KAAC,CAAC;IAC/C,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,SAAS,YAAY,CAAC,YAAY,CAAC,EAAE,CAAC;IACzD,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtC,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,QAAQ,EAAE,CAAC;IACtC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CACzC;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,QAAQ,EAAE,SAAS,CAAC;IAC7B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,UAAU,CAAC,EAAE;QAAC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;KAAC,CAAC;CAChD;AAuKD,wBAAgB,OAAO,CAAC,KAAK,EAAE,SAAS,GAAG;IACzC,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACrC,SAAS,EAAE,SAAS,QAAQ,EAAE,CAAC;CAChC,CA4CA"}

package/lib/utils/tabsUtils.js

@@ -0,0 +1,151 @@
+/**
+ * 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, } 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;
+    })();
+    useEffect(() => {
+        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.1.0",
+  "version": "2.3.0",
   "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.1.0",
-    "@docusaurus/module-type-aliases": "2.1.0",
-    "@docusaurus/plugin-content-blog": "2.1.0",
-    "@docusaurus/plugin-content-docs": "2.1.0",
-    "@docusaurus/plugin-content-pages": "2.1.0",
-    "@docusaurus/utils": "2.1.0",
+    "@docusaurus/mdx-loader": "2.3.0",
+    "@docusaurus/module-type-aliases": "2.3.0",
+    "@docusaurus/plugin-content-blog": "2.3.0",
+    "@docusaurus/plugin-content-docs": "2.3.0",
+    "@docusaurus/plugin-content-pages": "2.3.0",
+    "@docusaurus/utils": "2.3.0",
     "@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.1.0",
-    "@docusaurus/types": "2.1.0",
+    "@docusaurus/core": "2.3.0",
+    "@docusaurus/types": "2.3.0",
     "fs-extra": "^10.1.0",
     "lodash": "^4.17.21"
   },
@@ -58,5 +59,5 @@
   "engines": {
     "node": ">=16.14"
   },
-  "gitHead": "be9b0942641184213485eba7fd75ceb0b328d3f4"
+  "gitHead": "ad477781bdca6a11fa9c6daef5048bdcec0ee37e"
 }

package/src/hooks/useHideableNavbar.ts

@@ -62,7 +62,13 @@ export function useHideableNavbar(hideOnScroll: boolean): {
       return;
     }
 
-    if (locationChangeEvent.location.hash) {
+    // See https://github.com/facebook/docusaurus/pull/8059#issuecomment-1239639480
+    const currentHash = locationChangeEvent.location.hash;
+    const currentHashAnchor = currentHash
+      ? document.getElementById(currentHash.substring(1))
+      : undefined;
+
+    if (currentHashAnchor) {
       isFocusedAnchor.current = true;
       setIsNavbarVisible(false);
       return;

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';
 
@@ -78,3 +82,10 @@ export {duplicates, uniq} from './utils/jsUtils';
 export {usePrismTheme} from './hooks/usePrismTheme';
 
 export {useDocsPreferredVersion} from './contexts/docsPreferredVersion';
+
+export {processAdmonitionProps} from './utils/admonitionUtils';
+
+export {
+  SkipToContentFallbackId,
+  SkipToContentLink,
+} from './utils/skipToContentUtils';

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,
@@ -117,6 +119,5 @@ export {
 export {useLockBodyScroll} from './hooks/useLockBodyScroll';
 export {useSearchPage} from './hooks/useSearchPage';
 export {useCodeWordWrap} from './hooks/useCodeWordWrap';
-export {useSkipToContent} from './hooks/useSkipToContent';
 export {getPrismCssVariables} from './utils/codeBlockUtils';
 export {useBackToTopButton} from './hooks/useBackToTopButton';

package/src/utils/admonitionUtils.tsx

@@ -0,0 +1,43 @@
+/**
+ * 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, {type ReactNode} from 'react';
+
+// Workaround because it's difficult in MDX v1 to provide a MDX title as props
+// See https://github.com/facebook/docusaurus/pull/7152#issuecomment-1145779682
+function extractMDXAdmonitionTitle(children: ReactNode): {
+  mdxAdmonitionTitle: ReactNode | undefined;
+  rest: ReactNode;
+} {
+  const items = React.Children.toArray(children);
+  const mdxAdmonitionTitle = items.find(
+    (item) =>
+      React.isValidElement(item) &&
+      (item.props as {mdxType: string} | null)?.mdxType ===
+        'mdxAdmonitionTitle',
+  ) as JSX.Element | undefined;
+  const rest = <>{items.filter((item) => item !== mdxAdmonitionTitle)}</>;
+  return {
+    mdxAdmonitionTitle: mdxAdmonitionTitle?.props.children,
+    rest,
+  };
+}
+
+export function processAdmonitionProps<
+  Props extends {readonly children: ReactNode; readonly title?: ReactNode},
+>(props: Props): Props {
+  const {mdxAdmonitionTitle, rest} = extractMDXAdmonitionTitle(props.children);
+  const title = props.title ?? mdxAdmonitionTitle;
+  return {
+    ...props,
+    // Do not return "title: undefined" prop
+    // this might create unwanted props overrides when merging props
+    // For example: {...default,...props}
+    ...(title && {title}),
+    children: rest,
+  };
+}

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,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);
+  });
+}

package/src/utils/skipToContentUtils.tsx

@@ -0,0 +1,103 @@
+/**
+ * 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, {useCallback, useRef, type ComponentProps} from 'react';
+import {useHistory} from '@docusaurus/router';
+import {translate} from '@docusaurus/Translate';
+import {useLocationChange} from './useLocationChange';
+
+/**
+ * The id of the element that should become focused on a page
+ * that does not have a <main> html tag.
+ * Focusing the Docusaurus Layout children is a reasonable fallback.
+ */
+export const SkipToContentFallbackId = 'docusaurus_skipToContent_fallback';
+
+/**
+ * Returns the skip to content element to focus when the link is clicked.
+ */
+function getSkipToContentTarget(): HTMLElement | null {
+  return (
+    // Try to focus the <main> in priority
+    // Note: this will only work if JS is enabled
+    // See https://github.com/facebook/docusaurus/issues/6411#issuecomment-1284136069
+    document.querySelector('main:first-of-type') ??
+    // Then try to focus the fallback element (usually the Layout children)
+    document.getElementById(SkipToContentFallbackId)
+  );
+}
+
+function programmaticFocus(el: HTMLElement) {
+  el.setAttribute('tabindex', '-1');
+  el.focus();
+  el.removeAttribute('tabindex');
+}
+
+/** This hook wires the logic for a skip-to-content link. */
+function useSkipToContent(): {
+  /**
+   * The ref to the container. On page transition, the container will be focused
+   * so that keyboard navigators can instantly interact with the link and jump
+   * to content.
+   */
+  containerRef: React.RefObject<HTMLDivElement>;
+  /**
+   * Callback fired when the skip to content link has been clicked.
+   * It will programmatically focus the main content.
+   */
+  onClick: (e: React.MouseEvent<HTMLAnchorElement>) => void;
+} {
+  const containerRef = useRef<HTMLDivElement>(null);
+  const {action} = useHistory();
+
+  const onClick = useCallback((e: React.MouseEvent<HTMLAnchorElement>) => {
+    e.preventDefault();
+    const targetElement = getSkipToContentTarget();
+    if (targetElement) {
+      programmaticFocus(targetElement);
+    }
+  }, []);
+
+  // "Reset" focus when navigating.
+  // See https://github.com/facebook/docusaurus/pull/8204#issuecomment-1276547558
+  useLocationChange(({location}) => {
+    if (containerRef.current && !location.hash && action === 'PUSH') {
+      programmaticFocus(containerRef.current);
+    }
+  });
+
+  return {containerRef, onClick};
+}
+
+const DefaultSkipToContentLabel = translate({
+  id: 'theme.common.skipToMainContent',
+  description:
+    'The skip to content label used for accessibility, allowing to rapidly navigate to main content with keyboard tab/enter navigation',
+  message: 'Skip to main content',
+});
+
+type SkipToContentLinkProps = Omit<ComponentProps<'a'>, 'href' | 'onClick'>;
+
+export function SkipToContentLink(props: SkipToContentLinkProps): JSX.Element {
+  const linkLabel = props.children ?? DefaultSkipToContentLabel;
+  const {containerRef, onClick} = useSkipToContent();
+  return (
+    <div
+      ref={containerRef}
+      role="region"
+      aria-label={DefaultSkipToContentLabel}>
+      <a
+        {...props}
+        // Note this is a fallback href in case JS is disabled
+        // It has limitations, see https://github.com/facebook/docusaurus/issues/6411#issuecomment-1284136069
+        href={`#${SkipToContentFallbackId}`}
+        onClick={onClick}>
+        {linkLabel}
+      </a>
+    </div>
+  );
+}