@docusaurus/theme-common 2.0.0-beta.1ec2c95e3 → 2.0.0-beta.21

package/src/utils/historyUtils.ts

@@ -0,0 +1,45 @@
+/**
+ * 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 {useEffect} from 'react';
+import {useHistory} from '@docusaurus/router';
+import {useDynamicCallback} from './reactUtils';
+import type {Location, Action} from 'history';
+
+type HistoryBlockHandler = (location: Location, action: Action) => void | false;
+
+/**
+ * Permits to register a handler that will be called on history actions (pop,
+ * push, replace). If the handler returns `false`, the navigation transition
+ * will be blocked/cancelled.
+ */
+function useHistoryActionHandler(handler: HistoryBlockHandler): void {
+  const {block} = useHistory();
+  const stableHandler = useDynamicCallback(handler);
+  useEffect(
+    // See https://github.com/remix-run/history/blob/main/docs/blocking-transitions.md
+    () => block((location, action) => stableHandler(location, action)),
+    [block, stableHandler],
+  );
+}
+
+/**
+ * Permits to register a handler that will be called on history pop navigation
+ * (backward/forward). If the handler returns `false`, the backward/forward
+ * transition will be blocked. Unfortunately there's no good way to detect the
+ * "direction" (backward/forward) of the POP event.
+ */
+export function useHistoryPopHandler(handler: HistoryBlockHandler): void {
+  useHistoryActionHandler((location, action) => {
+    if (action === 'POP') {
+      // Maybe block navigation if handler returns false
+      return handler(location, action);
+    }
+    // Don't block other navigation actions
+    return undefined;
+  });
+}

package/src/utils/jsUtils.ts

@@ -0,0 +1,36 @@
+/**
+ * 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.
+ */
+
+// A replacement of lodash in client code
+
+/**
+ * Gets the duplicate values in an array.
+ * @param arr The array.
+ * @param comparator Compares two values and returns `true` if they are equal
+ * (duplicated).
+ * @returns Value of the elements `v` that have a preceding element `u` where
+ * `comparator(u, v) === true`. Values within the returned array are not
+ * guaranteed to be unique.
+ */
+export function duplicates<T>(
+  arr: readonly T[],
+  comparator: (a: T, b: T) => boolean = (a, b) => a === b,
+): T[] {
+  return arr.filter(
+    (v, vIndex) => arr.findIndex((u) => comparator(u, v)) !== vIndex,
+  );
+}
+
+/**
+ * Remove duplicate array items (similar to `_.uniq`)
+ * @param arr The array.
+ * @returns An array with duplicate elements removed by reference comparison.
+ */
+export function uniq<T>(arr: T[]): T[] {
+  // Note: had problems with [...new Set()]: https://github.com/facebook/docusaurus/issues/4972#issuecomment-863895061
+  return Array.from(new Set(arr));
+}

package/src/utils/metadataUtils.tsx

@@ -0,0 +1,115 @@
+/**
+ * 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';
+import clsx from 'clsx';
+import Head from '@docusaurus/Head';
+import useRouteContext from '@docusaurus/useRouteContext';
+import {useBaseUrlUtils} from '@docusaurus/useBaseUrl';
+import {useTitleFormatter} from './generalUtils';
+
+type PageMetadataProps = {
+  readonly title?: string;
+  readonly description?: string;
+  readonly keywords?: readonly string[] | string;
+  readonly image?: string;
+  readonly children?: ReactNode;
+};
+
+/**
+ * Helper component to manipulate page metadata and override site defaults.
+ * Works in the same way as Helmet.
+ */
+export function PageMetadata({
+  title,
+  description,
+  keywords,
+  image,
+  children,
+}: PageMetadataProps): JSX.Element {
+  const pageTitle = useTitleFormatter(title);
+  const {withBaseUrl} = useBaseUrlUtils();
+  const pageImage = image ? withBaseUrl(image, {absolute: true}) : undefined;
+
+  return (
+    <Head>
+      {title && <title>{pageTitle}</title>}
+      {title && <meta property="og:title" content={pageTitle} />}
+
+      {description && <meta name="description" content={description} />}
+      {description && <meta property="og:description" content={description} />}
+
+      {keywords && (
+        <meta
+          name="keywords"
+          content={
+            // https://github.com/microsoft/TypeScript/issues/17002
+            (Array.isArray(keywords) ? keywords.join(',') : keywords) as string
+          }
+        />
+      )}
+
+      {pageImage && <meta property="og:image" content={pageImage} />}
+      {pageImage && <meta name="twitter:image" content={pageImage} />}
+
+      {children}
+    </Head>
+  );
+}
+
+const HtmlClassNameContext = React.createContext<string | undefined>(undefined);
+
+/**
+ * Every layer of this provider will append a class name to the HTML element.
+ * There's no consumer for this hook: it's side-effect-only. This wrapper is
+ * necessary because Helmet does not "merge" classes.
+ * @see https://github.com/staylor/react-helmet-async/issues/161
+ */
+export function HtmlClassNameProvider({
+  className: classNameProp,
+  children,
+}: {
+  className: string;
+  children: ReactNode;
+}): JSX.Element {
+  const classNameContext = React.useContext(HtmlClassNameContext);
+  const className = clsx(classNameContext, classNameProp);
+  return (
+    <HtmlClassNameContext.Provider value={className}>
+      <Head>
+        <html className={className} />
+      </Head>
+      {children}
+    </HtmlClassNameContext.Provider>
+  );
+}
+
+function pluginNameToClassName(pluginName: string) {
+  return `plugin-${pluginName.replace(
+    /docusaurus-(?:plugin|theme)-(?:content-)?/gi,
+    '',
+  )}`;
+}
+
+/**
+ * A very thin wrapper around `HtmlClassNameProvider` that adds the plugin ID +
+ * name to the HTML class name.
+ */
+export function PluginHtmlClassNameProvider({
+  children,
+}: {
+  children: ReactNode;
+}): JSX.Element {
+  const routeContext = useRouteContext();
+  const nameClass = pluginNameToClassName(routeContext.plugin.name);
+  const idClass = `plugin-id-${routeContext.plugin.id}`;
+  return (
+    <HtmlClassNameProvider className={clsx(nameClass, idClass)}>
+      {children}
+    </HtmlClassNameProvider>
+  );
+}

package/src/utils/navbarUtils.tsx

@@ -0,0 +1,45 @@
+/**
+ * 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';
+import {NavbarMobileSidebarProvider} from '../contexts/navbarMobileSidebar';
+import {NavbarSecondaryMenuContentProvider} from '../contexts/navbarSecondaryMenu/content';
+import {NavbarSecondaryMenuDisplayProvider} from '../contexts/navbarSecondaryMenu/display';
+
+const DefaultNavItemPosition = 'right';
+
+/**
+ * Split links by left/right. If position is unspecified, fallback to right.
+ */
+export function splitNavbarItems<T extends {position?: 'left' | 'right'}>(
+  items: T[],
+): [leftItems: T[], rightItems: T[]] {
+  function isLeft(item: T): boolean {
+    return (item.position ?? DefaultNavItemPosition) === 'left';
+  }
+
+  const leftItems = items.filter(isLeft);
+  const rightItems = items.filter((item) => !isLeft(item));
+
+  return [leftItems, rightItems];
+}
+
+/**
+ * Composes multiple navbar state providers that are mutually dependent and
+ * hence can't be re-ordered.
+ */
+export function NavbarProvider({children}: {children: ReactNode}): JSX.Element {
+  return (
+    <NavbarSecondaryMenuContentProvider>
+      <NavbarMobileSidebarProvider>
+        <NavbarSecondaryMenuDisplayProvider>
+          {children}
+        </NavbarSecondaryMenuDisplayProvider>
+      </NavbarMobileSidebarProvider>
+    </NavbarSecondaryMenuContentProvider>
+  );
+}

package/src/utils/reactUtils.tsx

@@ -0,0 +1,76 @@
+/**
+ * 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 {useCallback, useEffect, useLayoutEffect, useRef} from 'react';
+import ExecutionEnvironment from '@docusaurus/ExecutionEnvironment';
+
+/**
+ * This hook is like `useLayoutEffect`, but without the SSR warning.
+ * It seems hacky but it's used in many React libs (Redux, Formik...).
+ * Also mentioned here: https://github.com/facebook/react/issues/16956
+ *
+ * It is useful when you need to update a ref as soon as possible after a React
+ * render (before `useEffect`).
+ */
+export const useIsomorphicLayoutEffect = ExecutionEnvironment.canUseDOM
+  ? useLayoutEffect
+  : useEffect;
+
+/**
+ * Permits to transform an unstable callback (like an arrow function provided as
+ * props) to a "stable" callback that is safe to use in a `useEffect` dependency
+ * array. Useful to avoid React stale closure problems + avoid useless effect
+ * re-executions.
+ *
+ * Workaround until the React team recommends a good solution, see
+ * https://github.com/facebook/react/issues/16956
+ *
+ * This generally works but has some potential drawbacks, such as
+ * https://github.com/facebook/react/issues/16956#issuecomment-536636418
+ */
+export function useDynamicCallback<T extends (...args: never[]) => unknown>(
+  callback: T,
+): T {
+  const ref = useRef<T>(callback);
+
+  useIsomorphicLayoutEffect(() => {
+    ref.current = callback;
+  }, [callback]);
+
+  // @ts-expect-error: TS is right that this callback may be a supertype of T,
+  // but good enough for our use
+  return useCallback<T>((...args) => ref.current(...args), []);
+}
+
+/**
+ * Gets `value` from the last render.
+ */
+export function usePrevious<T>(value: T): T | undefined {
+  const ref = useRef<T>();
+
+  useIsomorphicLayoutEffect(() => {
+    ref.current = value;
+  });
+
+  return ref.current;
+}
+
+/**
+ * This error is thrown when a context is consumed outside its provider. Allows
+ * reusing a generic error message format and reduces bundle size. The hook's
+ * name will be extracted from its stack, so only the provider's name is needed.
+ */
+export class ReactContextError extends Error {
+  constructor(providerName: string, additionalInfo?: string) {
+    super();
+    this.name = 'ReactContextError';
+    this.message = `Hook ${
+      this.stack?.split('\n')[1]?.match(/at (?:\w+\.)?(?<name>\w+)/)?.groups!
+        .name ?? ''
+    } is called outside the <${providerName}>. ${additionalInfo ?? ''}`;
+  }
+}

package/src/utils/regexpUtils.ts

@@ -0,0 +1,24 @@
+/**
+ * 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.
+ */
+
+/**
+ * Matches a string regex (as provided from the config) against a target in a
+ * null-safe fashion, case insensitive and global.
+ */
+export function isRegexpStringMatch(
+  regexAsString?: string,
+  valueToTest?: string,
+): boolean {
+  if (
+    typeof regexAsString === 'undefined' ||
+    typeof valueToTest === 'undefined'
+  ) {
+    return false;
+  }
+
+  return new RegExp(regexAsString, 'gi').test(valueToTest);
+}

package/src/utils/routesUtils.ts

@@ -0,0 +1,75 @@
+/**
+ * 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 {useMemo} from 'react';
+import generatedRoutes from '@generated/routes';
+import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
+import type {RouteConfig} from 'react-router-config';
+
+/**
+ * Compare the 2 paths, case insensitive and ignoring trailing slash
+ */
+export function isSamePath(
+  path1: string | undefined,
+  path2: string | undefined,
+): boolean {
+  const normalize = (pathname: string | undefined) =>
+    (!pathname || pathname.endsWith('/')
+      ? pathname
+      : `${pathname}/`
+    )?.toLowerCase();
+  return normalize(path1) === normalize(path2);
+}
+
+/**
+ * Note that sites don't always have a homepage in practice, so we can't assume
+ * that linking to '/' is always safe.
+ * @see https://github.com/facebook/docusaurus/pull/6517#issuecomment-1048709116
+ */
+export function findHomePageRoute({
+  baseUrl,
+  routes: initialRoutes,
+}: {
+  routes: RouteConfig[];
+  baseUrl: string;
+}): RouteConfig | undefined {
+  function isHomePageRoute(route: RouteConfig): boolean {
+    return route.path === baseUrl && route.exact === true;
+  }
+
+  function isHomeParentRoute(route: RouteConfig): boolean {
+    return route.path === baseUrl && !route.exact;
+  }
+
+  function doFindHomePageRoute(routes: RouteConfig[]): RouteConfig | undefined {
+    if (routes.length === 0) {
+      return undefined;
+    }
+    const homePage = routes.find(isHomePageRoute);
+    if (homePage) {
+      return homePage;
+    }
+    const indexSubRoutes = routes
+      .filter(isHomeParentRoute)
+      .flatMap((route) => route.routes ?? []);
+    return doFindHomePageRoute(indexSubRoutes);
+  }
+
+  return doFindHomePageRoute(initialRoutes);
+}
+
+/**
+ * Fetches the route that points to "/". Use this instead of the naive "/",
+ * because the homepage may not exist.
+ */
+export function useHomePageRoute(): RouteConfig | undefined {
+  const {baseUrl} = useDocusaurusContext().siteConfig;
+  return useMemo(
+    () => findHomePageRoute({routes: generatedRoutes, baseUrl}),
+    [baseUrl],
+  );
+}