@docusaurus/theme-common 2.0.0-beta.21 → 2.0.0-beta.22

package/src/utils/reactUtils.tsx

@@ -5,7 +5,15 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import {useCallback, useEffect, useLayoutEffect, useRef} from 'react';
+import React, {
+  useCallback,
+  useEffect,
+  useLayoutEffect,
+  useMemo,
+  useRef,
+  type ComponentType,
+  type ReactNode,
+} from 'react';
 import ExecutionEnvironment from '@docusaurus/ExecutionEnvironment';
 
 /**
@@ -21,18 +29,18 @@ export const useIsomorphicLayoutEffect = ExecutionEnvironment.canUseDOM
   : useEffect;
 
 /**
+ * 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.
  *
- * 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>(
+export function useEvent<T extends (...args: never[]) => unknown>(
   callback: T,
 ): T {
   const ref = useRef<T>(callback);
@@ -74,3 +82,48 @@ export class ReactContextError extends Error {
     } 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
+  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 ({children}) => (
+    <>
+      {providers.reduceRight(
+        (element, CurrentProvider) => (
+          <CurrentProvider>{element}</CurrentProvider>
+        ),
+        children,
+      )}
+    </>
+  );
+}

package/src/utils/scrollUtils.tsx

@@ -16,7 +16,7 @@ import React, {
 } from 'react';
 import ExecutionEnvironment from '@docusaurus/ExecutionEnvironment';
 import useIsBrowser from '@docusaurus/useIsBrowser';
-import {useDynamicCallback, ReactContextError} from './reactUtils';
+import {useEvent, ReactContextError} from './reactUtils';
 
 type ScrollController = {
   /** A boolean ref tracking whether scroll events are enabled. */
@@ -104,7 +104,7 @@ export function useScrollPosition(
   const {scrollEventsEnabledRef} = useScrollController();
   const lastPositionRef = useRef<ScrollPosition | null>(getScrollPosition());
 
-  const dynamicEffect = useDynamicCallback(effect);
+  const dynamicEffect = useEvent(effect);
 
   useEffect(() => {
     const handleScroll = () => {

package/src/utils/useLocationChange.ts

@@ -7,7 +7,7 @@
 
 import {useEffect} from 'react';
 import {useLocation} from '@docusaurus/router';
-import {useDynamicCallback, usePrevious} from './reactUtils';
+import {useEvent, usePrevious} from './reactUtils';
 import type {Location} from 'history';
 
 /**
@@ -24,7 +24,7 @@ export function useLocationChange(
   const location = useLocation();
   const previousLocation = usePrevious(location);
 
-  const onLocationChangeDynamic = useDynamicCallback(onLocationChange);
+  const onLocationChangeDynamic = useEvent(onLocationChange);
 
   useEffect(() => {
     if (!previousLocation) {

package/src/utils/useThemeConfig.ts

@@ -20,16 +20,20 @@ export type NavbarItem = {
   position?: 'left' | 'right';
 } & {[key: string]: unknown};
 
-export type NavbarLogo = {
+type BaseLogo = {
+  alt?: string;
   src: string;
   srcDark?: string;
+  href?: string;
   width?: string | number;
   height?: string | number;
-  href?: string;
   target?: string;
-  alt?: string;
+  style?: object;
+  className?: string;
 };
 
+export type NavbarLogo = BaseLogo;
+
 // TODO improve
 export type Navbar = {
   style?: 'dark' | 'primary';
@@ -69,14 +73,7 @@ export type FooterLinkItem = {
   prependBaseUrlToHref?: string;
 } & {[key: string]: unknown};
 
-export type FooterLogo = {
-  alt?: string;
-  src: string;
-  srcDark?: string;
-  width?: string | number;
-  height?: string | number;
-  href?: string;
-};
+export type FooterLogo = BaseLogo;
 
 export type FooterBase = {
   style: 'light' | 'dark';

package/Details.d.ts

@@ -1,14 +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.
- */
-
-// `Details` is a separate export entry because of side-effects messing with CSS
-// insertion order. See https://github.com/facebook/docusaurus/pull/7085.
-// However, because TS doesn't recognize `exports` (also a problem in
-// `content-docs`), we have to manually create a stub.
-
-// eslint-disable-next-line import/named
-export {Details, type DetailsProps} from './lib/components/Details';