@azerion/bunosaurus-theme-common 0.0.0-stage → 4.0.0

package/src/utils/historyUtils.ts

@@ -0,0 +1,199 @@
+/**
+ * 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, useMemo, useSyncExternalStore} from 'react';
+import {useHistory} from '@docusaurus/router';
+import {useEvent} from './reactUtils';
+
+import type {History, 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 history = useHistory();
+  const stableHandler = useEvent(handler);
+  useEffect(
+    // See https://github.com/remix-run/history/blob/main/docs/blocking-transitions.md
+    () => history.block((location, action) => stableHandler(location, action)),
+    [history, 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;
+  });
+}
+
+/**
+ * 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),
+    () =>
+      selector({
+        ...history,
+        location: {
+          ...history.location,
+          // On the server/hydration, these attributes should always be empty
+          // Forcing empty state makes this hook safe from hydration errors
+          search: '',
+          hash: '',
+          state: undefined,
+        },
+      }),
+  );
+}
+
+/**
+ * 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);
+  });
+}
+
+function useQueryStringUpdater(
+  key: string,
+): (newValue: string | null, options?: {push: boolean}) => void {
+  const history = useHistory();
+  return useCallback(
+    (newValue, options) => {
+      const searchParams = new URLSearchParams(history.location.search);
+      if (newValue) {
+        searchParams.set(key, newValue);
+      } else {
+        searchParams.delete(key);
+      }
+      const updateHistory = options?.push ? history.push : history.replace;
+      updateHistory({
+        search: searchParams.toString(),
+      });
+    },
+    [key, history],
+  );
+}
+
+export function useQueryString(
+  key: string,
+): [string, (newValue: string | null, options?: {push: boolean}) => void] {
+  const value = useQueryStringValue(key) ?? '';
+  const update = useQueryStringUpdater(key);
+  return [value, update];
+}
+
+function useQueryStringListValues(key: string): string[] {
+  // Unfortunately we can't just use searchParams.getAll(key) in the selector
+  // It would create a new array every time and lead to an infinite loop...
+  // The selector has to return a primitive/string value to avoid that...
+  const arrayJsonString = useHistorySelector((history) => {
+    const values = new URLSearchParams(history.location.search).getAll(key);
+    return JSON.stringify(values);
+  });
+  return useMemo(() => JSON.parse(arrayJsonString), [arrayJsonString]);
+}
+
+type ListUpdate = string[] | ((oldValues: string[]) => string[]);
+type ListUpdateFunction = (
+  update: ListUpdate,
+  options?: {push: boolean},
+) => void;
+
+function useQueryStringListUpdater(key: string): ListUpdateFunction {
+  const history = useHistory();
+  const setValues: ListUpdateFunction = useCallback(
+    (update, options) => {
+      const searchParams = new URLSearchParams(history.location.search);
+      const newValues = Array.isArray(update)
+        ? update
+        : update(searchParams.getAll(key));
+      searchParams.delete(key);
+      newValues.forEach((v) => searchParams.append(key, v));
+
+      const updateHistory = options?.push ? history.push : history.replace;
+      updateHistory({
+        search: searchParams.toString(),
+      });
+    },
+    [history, key],
+  );
+  return setValues;
+}
+
+export function useQueryStringList(
+  key: string,
+): [string[], ListUpdateFunction] {
+  const values = useQueryStringListValues(key);
+  const setValues = useQueryStringListUpdater(key);
+  return [values, setValues];
+}
+
+export function useClearQueryString(): () => void {
+  const history = useHistory();
+  return useCallback(() => {
+    history.replace({
+      search: undefined,
+    });
+  }, [history]);
+}
+
+export function mergeSearchParams(
+  params: URLSearchParams[],
+  strategy: 'append' | 'set',
+): URLSearchParams {
+  const result = new URLSearchParams();
+  for (const item of params) {
+    for (const [key, value] of item.entries()) {
+      if (strategy === 'append') {
+        result.append(key, value);
+      } else {
+        result.set(key, value);
+      }
+    }
+  }
+  return result;
+}
+
+export function mergeSearchStrings(
+  searchStrings: (string | undefined)[],
+  strategy: 'append' | 'set',
+): string {
+  const params = mergeSearchParams(
+    searchStrings.map((s) => new URLSearchParams(s ?? '')),
+    strategy,
+  );
+  const str = params.toString();
+  return str ? `?${str}` : str;
+}

package/src/utils/jsUtils.ts

@@ -0,0 +1,54 @@
+/**
+ * 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));
+}
+
+// TODO 2025: replace by std Object.groupBy ?
+// This is a local polyfill with exact same TS signature
+// see https://github.com/microsoft/TypeScript/blob/main/src/lib/esnext.object.d.ts
+export function groupBy<K extends PropertyKey, T>(
+  items: Iterable<T>,
+  keySelector: (item: T, index: number) => K,
+): Partial<Record<K, T[]>> {
+  const result: Partial<Record<K, T[]>> = {};
+  let index = 0;
+  for (const item of items) {
+    const key = keySelector(item, index);
+    result[key] ??= [];
+    result[key]!.push(item);
+    index += 1;
+  }
+  return result;
+}

package/src/utils/metadataUtils.tsx

@@ -0,0 +1,145 @@
+/**
+ * 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 './titleFormatterUtils';
+
+type PageMetadataProps = {
+  readonly title?: string;
+  readonly description?: string;
+  readonly keywords?: readonly string[] | string;
+  readonly image?: string;
+  readonly children?: ReactNode;
+};
+
+function TitleMetadata({title}: {title: string}) {
+  const titleFormatter = useTitleFormatter();
+  const formattedTitle = titleFormatter.format(title);
+  return (
+    <Head>
+      <title>{formattedTitle}</title>
+      <meta property="og:title" content={formattedTitle} />
+    </Head>
+  );
+}
+
+function DescriptionMetadata({description}: {description: string}) {
+  return (
+    <Head>
+      <meta name="description" content={description} />
+      <meta property="og:description" content={description} />
+    </Head>
+  );
+}
+
+function ImageMetadata({image}: {image: string}) {
+  const {withBaseUrl} = useBaseUrlUtils();
+  const pageImage = withBaseUrl(image, {absolute: true});
+  return (
+    <Head>
+      <meta property="og:image" content={pageImage} />
+      <meta name="twitter:image" content={pageImage} />
+    </Head>
+  );
+}
+
+function KeywordsMetadata({
+  keywords,
+}: {
+  keywords: PageMetadataProps['keywords'];
+}) {
+  return (
+    <Head>
+      <meta
+        name="keywords"
+        content={
+          // https://github.com/microsoft/TypeScript/issues/17002
+          (Array.isArray(keywords) ? keywords.join(',') : keywords) as string
+        }
+      />
+    </Head>
+  );
+}
+
+/**
+ * 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): ReactNode {
+  return (
+    <>
+      {title && <TitleMetadata title={title} />}
+      {description && <DescriptionMetadata description={description} />}
+      {keywords && <KeywordsMetadata keywords={keywords} />}
+      {image && <ImageMetadata image={image} />}
+      {children && <Head>{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;
+}): ReactNode {
+  const classNameContext = React.useContext(HtmlClassNameContext);
+  const className = clsx(classNameContext, classNameProp);
+  return (
+    <HtmlClassNameContext value={className}>
+      <Head>
+        <html className={className} />
+      </Head>
+      {children}
+    </HtmlClassNameContext>
+  );
+}
+
+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;
+}): ReactNode {
+  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 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}): ReactNode {
+  return (
+    <NavbarSecondaryMenuContentProvider>
+      <NavbarMobileSidebarProvider>
+        <NavbarSecondaryMenuDisplayProvider>
+          {children}
+        </NavbarSecondaryMenuDisplayProvider>
+      </NavbarMobileSidebarProvider>
+    </NavbarSecondaryMenuContentProvider>
+  );
+}

package/src/utils/reactUtils.tsx

@@ -0,0 +1,120 @@
+/**
+ * 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,
+  useLayoutEffect,
+  useMemo,
+  useRef,
+  type ComponentType,
+  type ReactNode,
+} from 'react';
+
+/**
+ * Temporary userland implementation until an official hook is implemented
+ * See RFC: https://github.com/reactjs/rfcs/pull/220
+ *
+ * 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.
+ *
+ * This generally works but has some potential drawbacks, such as
+ * https://github.com/facebook/react/issues/16956#issuecomment-536636418
+ */
+export function useEvent<T extends (...args: never[]) => unknown>(
+  callback: T,
+): T {
+  const ref = useRef<T>(callback);
+
+  useLayoutEffect(() => {
+    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>(undefined);
+
+  useLayoutEffect(() => {
+    ref.current = value;
+  });
+
+  // TODO need to fix this React Compiler lint error
+  //  probably requires changing the API though
+  // eslint-disable-next-line react-hooks/refs
+  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 ?? ''}`;
+  }
+}
+
+/**
+ * Shallow-memoize an object. This means the returned object will be the same as
+ * the previous render if the property keys and values did not change. This
+ * works for simple cases: when property values are primitives or stable
+ * objects.
+ *
+ * @param obj
+ */
+export function useShallowMemoObject<O extends object>(obj: O): O {
+  const deps = Object.entries(obj);
+  // Sort by keys to make it order-insensitive
+  deps.sort((a, b) => a[0].localeCompare(b[0]));
+  // eslint-disable-next-line react-hooks/exhaustive-deps,react-hooks/use-memo
+  return useMemo(() => obj, deps.flat());
+}
+
+type SimpleProvider = ComponentType<{children: ReactNode}>;
+
+/**
+ * Creates a single React provider from an array of existing providers
+ * assuming providers only take "children" as props.
+ *
+ * Prevents the annoying React element nesting
+ * Example here: https://getfrontend.tips/compose-multiple-react-providers/
+ *
+ * The order matters:
+ * - The first provider is at the top of the tree.
+ * - The last provider is the most nested one
+ *
+ * @param providers array of providers to compose
+ */
+export function composeProviders(providers: SimpleProvider[]): SimpleProvider {
+  // Creates a single React component: it's cheaper to compose JSX elements
+  return function ComposedProvider({children}: {children: ReactNode}) {
+    return (
+      <>
+        {providers.reduceRight(
+          (element, CurrentProvider) => (
+            <CurrentProvider>{element}</CurrentProvider>
+          ),
+          children,
+        )}
+      </>
+    );
+  };
+}

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