@docusaurus/theme-common 2.0.0-beta.15a2b59f9 → 2.0.0-beta.17

package/src/utils/docsUtils.tsx

@@ -0,0 +1,231 @@
+/**
+ * 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, {createContext, type ReactNode, useContext} from 'react';
+import {
+  useActivePlugin,
+  useAllDocsData,
+} from '@docusaurus/plugin-content-docs/client';
+import type {
+  PropSidebar,
+  PropSidebarItem,
+  PropSidebarItemCategory,
+  PropVersionDoc,
+  PropVersionMetadata,
+  PropSidebarBreadcrumbsItem,
+} from '@docusaurus/plugin-content-docs';
+import {isSamePath} from './pathUtils';
+import {ReactContextError} from './reactUtils';
+import {useLocation} from '@docusaurus/router';
+
+// TODO not ideal, see also "useDocs"
+export const isDocsPluginEnabled: boolean = !!useAllDocsData;
+
+// Using a Symbol because null is a valid context value (a doc with no sidebar)
+// Inspired by https://github.com/jamiebuilds/unstated-next/blob/master/src/unstated-next.tsx
+const EmptyContextValue: unique symbol = Symbol('EmptyContext');
+
+const DocsVersionContext = createContext<
+  PropVersionMetadata | typeof EmptyContextValue
+>(EmptyContextValue);
+
+export function DocsVersionProvider({
+  children,
+  version,
+}: {
+  children: ReactNode;
+  version: PropVersionMetadata | typeof EmptyContextValue;
+}): JSX.Element {
+  return (
+    <DocsVersionContext.Provider value={version}>
+      {children}
+    </DocsVersionContext.Provider>
+  );
+}
+
+export function useDocsVersion(): PropVersionMetadata {
+  const version = useContext(DocsVersionContext);
+  if (version === EmptyContextValue) {
+    throw new ReactContextError('DocsVersionProvider');
+  }
+  return version;
+}
+
+export function useDocById(id: string): PropVersionDoc;
+export function useDocById(id: string | undefined): PropVersionDoc | undefined;
+export function useDocById(id: string | undefined): PropVersionDoc | undefined {
+  const version = useDocsVersion();
+  if (!id) {
+    return undefined;
+  }
+  const doc = version.docs[id];
+  if (!doc) {
+    throw new Error(`no version doc found by id=${id}`);
+  }
+  return doc;
+}
+
+const DocsSidebarContext = createContext<
+  PropSidebar | null | typeof EmptyContextValue
+>(EmptyContextValue);
+
+export function DocsSidebarProvider({
+  children,
+  sidebar,
+}: {
+  children: ReactNode;
+  sidebar: PropSidebar | null;
+}): JSX.Element {
+  return (
+    <DocsSidebarContext.Provider value={sidebar}>
+      {children}
+    </DocsSidebarContext.Provider>
+  );
+}
+
+export function useDocsSidebar(): PropSidebar | null {
+  const sidebar = useContext(DocsSidebarContext);
+  if (sidebar === EmptyContextValue) {
+    throw new ReactContextError('DocsSidebarProvider');
+  }
+  return sidebar;
+}
+
+// Use the components props and the sidebar in context
+// to get back the related sidebar category that we want to render
+export function findSidebarCategory(
+  sidebar: PropSidebar,
+  predicate: (category: PropSidebarItemCategory) => boolean,
+): PropSidebarItemCategory | undefined {
+  for (const item of sidebar) {
+    if (item.type === 'category') {
+      if (predicate(item)) {
+        return item;
+      }
+      const subItem = findSidebarCategory(item.items, predicate);
+      if (subItem) {
+        return subItem;
+      }
+    }
+  }
+  return undefined;
+}
+
+// If a category card has no link => link to the first subItem having a link
+export function findFirstCategoryLink(
+  item: PropSidebarItemCategory,
+): string | undefined {
+  if (item.href) {
+    return item.href;
+  }
+
+  for (const subItem of item.items) {
+    if (subItem.type === 'link') {
+      return subItem.href;
+    } else if (subItem.type === 'category') {
+      const categoryLink = findFirstCategoryLink(subItem);
+      if (categoryLink) {
+        return categoryLink;
+      }
+    } else if (subItem.type === 'html') {
+      // skip
+    } else {
+      throw new Error(
+        `Unexpected category item type for ${JSON.stringify(subItem)}`,
+      );
+    }
+  }
+  return undefined;
+}
+
+export function useCurrentSidebarCategory(): PropSidebarItemCategory {
+  const {pathname} = useLocation();
+  const sidebar = useDocsSidebar();
+  if (!sidebar) {
+    throw new Error('Unexpected: cant find current sidebar in context');
+  }
+  const category = findSidebarCategory(sidebar, (item) =>
+    isSamePath(item.href, pathname),
+  );
+  if (!category) {
+    throw new Error(
+      `Unexpected: sidebar category could not be found for pathname='${pathname}'.
+Hook useCurrentSidebarCategory() should only be used on Category pages`,
+    );
+  }
+  return category;
+}
+
+function containsActiveSidebarItem(
+  items: PropSidebarItem[],
+  activePath: string,
+): boolean {
+  return items.some((subItem) => isActiveSidebarItem(subItem, activePath));
+}
+
+export function isActiveSidebarItem(
+  item: PropSidebarItem,
+  activePath: string,
+): boolean {
+  const isActive = (testedPath: string | undefined) =>
+    typeof testedPath !== 'undefined' && isSamePath(testedPath, activePath);
+
+  if (item.type === 'link') {
+    return isActive(item.href);
+  }
+
+  if (item.type === 'category') {
+    return (
+      isActive(item.href) || containsActiveSidebarItem(item.items, activePath)
+    );
+  }
+
+  return false;
+}
+
+export function getBreadcrumbs({
+  sidebar,
+  pathname,
+}: {
+  sidebar: PropSidebar;
+  pathname: string;
+}): PropSidebarBreadcrumbsItem[] {
+  const breadcrumbs: PropSidebarBreadcrumbsItem[] = [];
+
+  function extract(items: PropSidebar) {
+    for (const item of items) {
+      if (
+        item.type === 'category' &&
+        (isSamePath(item.href, pathname) || extract(item.items))
+      ) {
+        breadcrumbs.push(item);
+        return true;
+      } else if (item.type === 'link' && isSamePath(item.href, pathname)) {
+        breadcrumbs.push(item);
+        return true;
+      }
+    }
+
+    return false;
+  }
+
+  extract(sidebar);
+
+  return breadcrumbs.reverse();
+}
+
+export function useSidebarBreadcrumbs(): PropSidebarBreadcrumbsItem[] | null {
+  const sidebar = useDocsSidebar();
+  const {pathname} = useLocation();
+  const breadcrumbsOption = useActivePlugin()?.pluginData.breadcrumbs;
+
+  if (breadcrumbsOption === false || !sidebar) {
+    return null;
+  }
+
+  return getBreadcrumbs({sidebar, pathname});
+}

package/src/utils/generalUtils.ts

@@ -4,11 +4,12 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
+
 import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
 
 export const useTitleFormatter = (title?: string | undefined): string => {
-  const {siteConfig = {}} = useDocusaurusContext();
-  const {title: siteTitle, titleDelimiter = '|'} = siteConfig;
+  const {siteConfig} = useDocusaurusContext();
+  const {title: siteTitle, titleDelimiter} = siteConfig;
   return title && title.trim().length
     ? `${title.trim()} ${titleDelimiter} ${siteTitle}`
     : siteTitle;

package/src/utils/historyUtils.ts

@@ -0,0 +1,51 @@
+/**
+ * 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, useRef} from 'react';
+import {useHistory} from '@docusaurus/router';
+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
+ */
+export function useHistoryActionHandler(handler: HistoryBlockHandler): void {
+  const {block} = useHistory();
+
+  // Avoid stale closure issues without triggering useless re-renders
+  const lastHandlerRef = useRef(handler);
+  useEffect(() => {
+    lastHandlerRef.current = handler;
+  }, [handler]);
+
+  useEffect(
+    () =>
+      // See https://github.com/remix-run/history/blob/main/docs/blocking-transitions.md
+      block((location, action) => lastHandlerRef.current(location, action)),
+    [block, lastHandlerRef],
+  );
+}
+
+/**
+ * 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') {
+      // Eventually 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/mobileSecondaryMenu.tsx

@@ -0,0 +1,114 @@
+/**
+ * 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,
+  type ReactNode,
+  useContext,
+  createContext,
+  useEffect,
+  type ComponentType,
+  useMemo,
+} from 'react';
+import {ReactContextError} from './reactUtils';
+
+/*
+The idea behind all this is that a specific component must be able to fill a
+placeholder in the generic layout. The doc page should be able to fill the
+secondary menu of the main mobile navbar. This permits to reduce coupling
+between the main layout and the specific page.
+
+This kind of feature is often called portal/teleport/gateway... various
+unmaintained React libs exist. Most up-to-date one: https://github.com/gregberge/react-teleporter
+Not sure any of those is safe regarding concurrent mode.
+ */
+
+type ExtraProps = {
+  toggleSidebar: () => void;
+};
+
+export type MobileSecondaryMenuComponent<Props> = ComponentType<
+  Props & ExtraProps
+>;
+
+type State = {
+  component: MobileSecondaryMenuComponent<unknown>;
+  props: unknown;
+} | null;
+
+function useContextValue() {
+  return useState<State>(null);
+}
+
+type ContextValue = ReturnType<typeof useContextValue>;
+
+const Context = createContext<ContextValue | null>(null);
+
+export function MobileSecondaryMenuProvider({
+  children,
+}: {
+  children: ReactNode;
+}): JSX.Element {
+  return (
+    <Context.Provider value={useContextValue()}>{children}</Context.Provider>
+  );
+}
+
+function useMobileSecondaryMenuContext(): ContextValue {
+  const value = useContext(Context);
+  if (value === null) {
+    throw new ReactContextError('MobileSecondaryMenuProvider');
+  }
+  return value;
+}
+
+export function useMobileSecondaryMenuRenderer(): (
+  extraProps: ExtraProps,
+) => ReactNode | undefined {
+  const [state] = useMobileSecondaryMenuContext();
+  if (state) {
+    const Comp = state.component;
+    return function render(extraProps) {
+      return <Comp {...state.props} {...extraProps} />;
+    };
+  }
+  return () => undefined;
+}
+
+function useShallowMemoizedObject<O extends Record<string, unknown>>(obj: O) {
+  return useMemo(
+    () => obj,
+    // Is this safe?
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [...Object.keys(obj), ...Object.values(obj)],
+  );
+}
+
+// Fill the secondary menu placeholder with some real content
+export function MobileSecondaryMenuFiller<
+  Props extends Record<string, unknown>,
+>({
+  component,
+  props,
+}: {
+  component: MobileSecondaryMenuComponent<Props & ExtraProps>;
+  props: Props;
+}): JSX.Element | null {
+  const [, setState] = useMobileSecondaryMenuContext();
+
+  // To avoid useless context re-renders, props are memoized shallowly
+  const memoizedProps = useShallowMemoizedObject(props);
+
+  useEffect(() => {
+    // @ts-expect-error: context is not 100% type-safe but it's ok
+    setState({component, props: memoizedProps});
+  }, [setState, component, memoizedProps]);
+
+  useEffect(() => () => setState(null), [setState]);
+
+  return null;
+}

package/src/utils/pathUtils.ts

@@ -5,13 +5,15 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-// Compare the 2 paths, ignoring trailing /
+// Compare the 2 paths, case insensitive and ignoring trailing slash
 export const isSamePath = (
   path1: string | undefined,
   path2: string | undefined,
 ): boolean => {
-  const normalize = (pathname: string | undefined) => {
-    return !pathname || pathname?.endsWith('/') ? pathname : `${pathname}/`;
-  };
+  const normalize = (pathname: string | undefined) =>
+    (!pathname || pathname?.endsWith('/')
+      ? pathname
+      : `${pathname}/`
+    )?.toLowerCase();
   return normalize(path1) === normalize(path2);
 };

package/src/utils/reactUtils.tsx

@@ -0,0 +1,53 @@
+/**
+ * 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';
+
+/**
+ * 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 =
+  typeof window !== 'undefined' ? 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), []);
+}
+
+export class ReactContextError extends Error {
+  constructor(providerName: string, additionalInfo?: string) {
+    super();
+    this.name = 'ReactContextError';
+    this.message = `Hook ${
+      this.stack?.split('\n')[1]?.match(/at (?<name>\w+)/)?.groups!.name
+    } is called outside the <${providerName}>. ${additionalInfo || ''}`;
+  }
+}

package/src/utils/regexpUtils.ts

@@ -0,0 +1,23 @@
+/**
+ * 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.
+ */
+
+/**
+ * Converts an optional string into a Regex 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,56 @@
+/**
+ * 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 GeneratedRoutes, {type Route} from '@generated/routes';
+import {useMemo} from 'react';
+import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
+
+// Note that all sites don't always have a homepage in practice
+// See https://github.com/facebook/docusaurus/pull/6517#issuecomment-1048709116
+export function findHomePageRoute({
+  baseUrl,
+  routes: initialRoutes,
+}: {
+  routes: Route[];
+  baseUrl: string;
+}): Route | undefined {
+  function isHomePageRoute(route: Route): boolean {
+    return route.path === baseUrl && route.exact === true;
+  }
+
+  function isHomeParentRoute(route: Route): boolean {
+    return route.path === baseUrl && !route.exact;
+  }
+
+  function doFindHomePageRoute(routes: Route[]): Route | 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);
+}
+
+export function useHomePageRoute(): Route | undefined {
+  const {baseUrl} = useDocusaurusContext().siteConfig;
+  return useMemo(
+    () =>
+      findHomePageRoute({
+        routes: GeneratedRoutes,
+        baseUrl,
+      }),
+    [baseUrl],
+  );
+}