@docusaurus/core 2.0.0-beta.fbdeefcac → 2.0.0-rc.1

package/lib/client/ClientLifecyclesDispatcher.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 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 ReactElement } from 'react';
+import type { ClientModule } from '@docusaurus/types';
+import type { Location } from 'history';
+export declare function dispatchLifecycleAction<K extends keyof ClientModule>(lifecycleAction: K, ...args: Parameters<NonNullable<ClientModule[K]>>): () => void;
+declare function ClientLifecyclesDispatcher({ children, location, previousLocation, }: {
+    children: ReactElement;
+    location: Location;
+    previousLocation: Location | null;
+}): JSX.Element;
+export default ClientLifecyclesDispatcher;

package/lib/client/ClientLifecyclesDispatcher.js

@@ -0,0 +1,39 @@
+/**
+ * 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 { useLayoutEffect } from 'react';
+import clientModules from '@generated/client-modules';
+export function dispatchLifecycleAction(lifecycleAction, ...args) {
+    const callbacks = clientModules.map((clientModule) => {
+        const lifecycleFunction = (clientModule.default?.[lifecycleAction] ??
+            clientModule[lifecycleAction]);
+        return lifecycleFunction?.(...args);
+    });
+    return () => callbacks.forEach((cb) => cb?.());
+}
+function scrollAfterNavigation(location) {
+    const { hash } = location;
+    if (!hash) {
+        window.scrollTo(0, 0);
+    }
+    else {
+        const id = decodeURIComponent(hash.substring(1));
+        const element = document.getElementById(id);
+        element?.scrollIntoView();
+    }
+}
+function ClientLifecyclesDispatcher({ children, location, previousLocation, }) {
+    useLayoutEffect(() => {
+        if (previousLocation !== location) {
+            if (previousLocation) {
+                scrollAfterNavigation(location);
+            }
+            dispatchLifecycleAction('onRouteDidUpdate', { previousLocation, location });
+        }
+    }, [previousLocation, location]);
+    return children;
+}
+export default ClientLifecyclesDispatcher;

package/lib/client/LinksCollector.d.ts

@@ -4,7 +4,7 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-import { ReactNode } from 'react';
+import { type ReactNode } from 'react';
 declare type LinksCollector = {
     collectLink: (link: string) => void;
 };
@@ -13,8 +13,8 @@ declare type StatefulLinksCollector = LinksCollector & {
 };
 export declare const createStatefulLinksCollector: () => StatefulLinksCollector;
 export declare const useLinksCollector: () => LinksCollector;
-export declare const ProvideLinksCollector: ({ children, linksCollector, }: {
+export declare function LinksCollectorProvider({ children, linksCollector, }: {
     children: ReactNode;
     linksCollector: LinksCollector;
-}) => JSX.Element;
+}): JSX.Element;
 export {};

package/lib/client/LinksCollector.js

@@ -4,7 +4,7 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-import React, { useContext, createContext } from 'react';
+import React, { useContext } from 'react';
 export const createStatefulLinksCollector = () => {
     // Set to dedup, as it's not useful to collect multiple times the same link
     const allLinks = new Set();
@@ -12,20 +12,15 @@ export const createStatefulLinksCollector = () => {
         collectLink: (link) => {
             allLinks.add(link);
         },
-        getCollectedLinks: () => {
-            return [...allLinks];
-        },
+        getCollectedLinks: () => [...allLinks],
     };
 };
-const Context = createContext({
+const Context = React.createContext({
     collectLink: () => {
-        // noop by default for client
-        // we only use the broken links checker server-side
+        // No-op for client. We only use the broken links checker server-side.
     },
 });
-export const useLinksCollector = () => {
-    return useContext(Context);
-};
-export const ProvideLinksCollector = ({ children, linksCollector, }) => {
-    return React.createElement(Context.Provider, { value: linksCollector }, children);
-};
+export const useLinksCollector = () => useContext(Context);
+export function LinksCollectorProvider({ children, linksCollector, }) {
+    return <Context.Provider value={linksCollector}>{children}</Context.Provider>;
+}

package/lib/client/PendingNavigation.d.ts

@@ -4,6 +4,20 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-import './nprogress.css';
-declare const _default: any;
-export default _default;
+import React from 'react';
+import type { Location } from 'history';
+declare type Props = {
+    readonly location: Location;
+    readonly children: JSX.Element;
+};
+declare type State = {
+    nextRouteHasLoaded: boolean;
+};
+declare class PendingNavigation extends React.Component<Props, State> {
+    private previousLocation;
+    private routeUpdateCleanupCb;
+    constructor(props: Props);
+    shouldComponentUpdate(nextProps: Props, nextState: State): boolean;
+    render(): JSX.Element;
+}
+export default PendingNavigation;

package/lib/client/PendingNavigation.js

@@ -5,19 +5,23 @@
  * LICENSE file in the root directory of this source tree.
  */
 import React from 'react';
-import { Route, withRouter } from 'react-router-dom';
-import nprogress from 'nprogress';
-import clientLifecyclesDispatcher from './client-lifecycles-dispatcher';
+import { Route } from 'react-router-dom';
+import ClientLifecyclesDispatcher, { dispatchLifecycleAction, } from './ClientLifecyclesDispatcher';
+import ExecutionEnvironment from './exports/ExecutionEnvironment';
 import preload from './preload';
-import normalizeLocation from './normalizeLocation';
-import './nprogress.css';
-nprogress.configure({ showSpinner: false });
 class PendingNavigation extends React.Component {
+    previousLocation;
+    routeUpdateCleanupCb;
     constructor(props) {
         super(props);
         // previousLocation doesn't affect rendering, hence not stored in state.
         this.previousLocation = null;
-        this.progressBarTimeout = null;
+        this.routeUpdateCleanupCb = ExecutionEnvironment.canUseDOM
+            ? dispatchLifecycleAction('onRouteUpdate', {
+                previousLocation: null,
+                location: this.props.location,
+            })
+            : () => { };
         this.state = {
             nextRouteHasLoaded: true,
         };
@@ -25,74 +29,45 @@ class PendingNavigation extends React.Component {
     // Intercept location update and still show current route until next route
     // is done loading.
     shouldComponentUpdate(nextProps, nextState) {
-        const routeDidChange = nextProps.location !== this.props.location;
-        const { routes, delay = 1000 } = this.props;
-        // If `routeDidChange` is true, means the router is trying to navigate to a new
-        // route. We will preload the new route.
-        if (routeDidChange) {
-            const nextLocation = normalizeLocation(nextProps.location);
-            this.startProgressBar(delay);
-            // Save the location first.
-            this.previousLocation = normalizeLocation(this.props.location);
-            this.setState({
-                nextRouteHasLoaded: false,
-            });
-            // Load data while the old screen remains.
-            preload(routes, nextLocation.pathname)
-                .then(() => {
-                clientLifecyclesDispatcher.onRouteUpdate({
-                    previousLocation: this.previousLocation,
-                    location: nextLocation,
-                });
-                // Route has loaded, we can reset previousLocation.
-                this.previousLocation = null;
-                this.setState({
-                    nextRouteHasLoaded: true,
-                }, this.stopProgressBar);
-                const { hash } = nextLocation;
-                if (!hash) {
-                    window.scrollTo(0, 0);
-                }
-                else {
-                    const id = decodeURIComponent(hash.substring(1));
-                    const element = document.getElementById(id);
-                    if (element) {
-                        element.scrollIntoView();
-                    }
-                }
-            })
-                .catch((e) => console.warn(e));
-            return false;
+        if (nextProps.location === this.props.location) {
+            // `nextRouteHasLoaded` is false means there's a pending route transition.
+            // Don't update until it's done.
+            return nextState.nextRouteHasLoaded;
         }
-        // There's a pending route transition. Don't update until it's done.
-        if (!nextState.nextRouteHasLoaded) {
-            return false;
-        }
-        // Route has loaded, we can update now.
-        return true;
-    }
-    clearProgressBarTimeout() {
-        if (this.progressBarTimeout) {
-            clearTimeout(this.progressBarTimeout);
-            this.progressBarTimeout = null;
-        }
-    }
-    startProgressBar(delay) {
-        this.clearProgressBarTimeout();
-        this.progressBarTimeout = setTimeout(() => {
-            clientLifecyclesDispatcher.onRouteUpdateDelayed({
-                location: normalizeLocation(this.props.location),
-            });
-            nprogress.start();
-        }, delay);
-    }
-    stopProgressBar() {
-        this.clearProgressBarTimeout();
-        nprogress.done();
+        // props.location being different means the router is trying to navigate to
+        // a new route. We will preload the new route.
+        const nextLocation = nextProps.location;
+        // Save the location first.
+        this.previousLocation = this.props.location;
+        this.setState({ nextRouteHasLoaded: false });
+        this.routeUpdateCleanupCb = dispatchLifecycleAction('onRouteUpdate', {
+            previousLocation: this.previousLocation,
+            location: nextLocation,
+        });
+        // Load data while the old screen remains. Force preload instead of using
+        // `window.docusaurus`, because we want to avoid loading screen even when
+        // user is on saveData
+        preload(nextLocation.pathname)
+            .then(() => {
+            this.routeUpdateCleanupCb();
+            this.setState({ nextRouteHasLoaded: true });
+        })
+            .catch((e) => {
+            console.warn(e);
+            // If chunk loading failed, it could be because the path to a chunk
+            // no longer exists due to a new deployment. Force refresh the page
+            // instead of just not navigating.
+            window.location.reload();
+        });
+        return false;
     }
     render() {
         const { children, location } = this.props;
-        return (React.createElement(Route, { location: normalizeLocation(location), render: () => children }));
+        // Use a controlled <Route> to trick all descendants into rendering the old
+        // location.
+        return (<ClientLifecyclesDispatcher previousLocation={this.previousLocation} location={location}>
+        <Route location={location} render={() => children}/>
+      </ClientLifecyclesDispatcher>);
     }
 }
-export default withRouter(PendingNavigation);
+export default PendingNavigation;

package/lib/client/{baseUrlIssueBanner/BaseUrlIssueBanner.d.ts → SiteMetadataDefaults.d.ts}

@@ -5,5 +5,4 @@
  * LICENSE file in the root directory of this source tree.
  */
 /// <reference types="react" />
-import './styles.module.css';
-export default function BaseUrlIssueBanner(): JSX.Element | null;
+export default function SiteMetadataDefaults(): JSX.Element;

package/lib/client/SiteMetadataDefaults.js

@@ -0,0 +1,21 @@
+/**
+ * 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 from 'react';
+import Head from '@docusaurus/Head';
+import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
+import useBaseUrl from '@docusaurus/useBaseUrl';
+export default function SiteMetadataDefaults() {
+    const { siteConfig: { favicon, title }, i18n: { currentLocale, localeConfigs }, } = useDocusaurusContext();
+    const faviconUrl = useBaseUrl(favicon);
+    const { htmlLang, direction: htmlDir } = localeConfigs[currentLocale];
+    return (<Head>
+      <html lang={htmlLang} dir={htmlDir}/>
+      <title>{title}</title>
+      <meta property="og:title" content={title}/>
+      {favicon && <link rel="icon" href={faviconUrl}/>}
+    </Head>);
+}

package/lib/{choosePort.d.ts → client/browserContext.d.ts}

@@ -4,8 +4,8 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-/**
- * Detects if program is running on port and prompts user
- * to choose another if port is already being used
- */
-export default function choosePort(host: string, defaultPort: number): Promise<number | null>;
+import React, { type ReactNode } from 'react';
+export declare const Context: React.Context<boolean>;
+export declare function BrowserContextProvider({ children, }: {
+    children: ReactNode;
+}): JSX.Element;

package/lib/client/browserContext.js

@@ -0,0 +1,22 @@
+/**
+ * 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, { useEffect, useState } from 'react';
+// Encapsulate the logic to avoid React hydration problems
+// See https://www.joshwcomeau.com/react/the-perils-of-rehydration/
+// On first client-side render, we need to render exactly as the server rendered
+// isBrowser is set to true only after a successful hydration
+// Note, isBrowser is not part of useDocusaurusContext() for perf reasons
+// Using useDocusaurusContext() (much more common need) should not trigger
+// re-rendering after a successful hydration
+export const Context = React.createContext(false);
+export function BrowserContextProvider({ children, }) {
+    const [isBrowser, setIsBrowser] = useState(false);
+    useEffect(() => {
+        setIsBrowser(true);
+    }, []);
+    return <Context.Provider value={isBrowser}>{children}</Context.Provider>;
+}

package/lib/client/clientEntry.js

@@ -5,23 +5,28 @@
  * LICENSE file in the root directory of this source tree.
  */
 import React from 'react';
-import { hydrate, render } from 'react-dom';
+import ReactDOM from 'react-dom';
 import { BrowserRouter } from 'react-router-dom';
-import routes from '@generated/routes';
+import { HelmetProvider } from 'react-helmet-async';
 import ExecutionEnvironment from './exports/ExecutionEnvironment';
 import App from './App';
 import preload from './preload';
 import docusaurus from './docusaurus';
-// Client-side render (e.g: running in browser) to become single-page application (SPA).
+// Client-side render (e.g: running in browser) to become single-page
+// application (SPA).
 if (ExecutionEnvironment.canUseDOM) {
     window.docusaurus = docusaurus;
-    // For production, attempt to hydrate existing markup for performant first-load experience.
+    // For production, attempt to hydrate existing markup for performant
+    // first-load experience.
     // For development, there is no existing markup so we had to render it.
-    // Note that we also preload async component to avoid first-load loading screen.
-    const renderMethod = process.env.NODE_ENV === 'production' ? hydrate : render;
-    preload(routes, window.location.pathname).then(() => {
-        renderMethod(React.createElement(BrowserRouter, null,
-            React.createElement(App, null)), document.getElementById('__docusaurus'));
+    // We also preload async component to avoid first-load loading screen.
+    const renderMethod = process.env.NODE_ENV === 'production' ? ReactDOM.hydrate : ReactDOM.render;
+    preload(window.location.pathname).then(() => {
+        renderMethod(<HelmetProvider>
+        <BrowserRouter>
+          <App />
+        </BrowserRouter>
+      </HelmetProvider>, document.getElementById('__docusaurus'));
     });
     // Webpack Hot Module Replacement API
     if (module.hot) {

package/lib/client/docusaurus.d.ts

@@ -1,16 +1,22 @@
+/**
+ * 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.
+ */
 declare global {
     const __webpack_require__: {
         gca: (name: string) => string;
     };
     interface Navigator {
-        connection: {
+        connection?: {
             effectiveType: string;
             saveData: boolean;
         };
     }
 }
-declare const docusaurus: {
-    prefetch: (routePath: string) => boolean;
-    preload: (routePath: string) => boolean;
-};
-export default docusaurus;
+declare const _default: Readonly<{
+    prefetch(routePath: string): false | Promise<void[]>;
+    preload(routePath: string): false | Promise<void[]>;
+}>;
+export default _default;

package/lib/client/docusaurus.js

@@ -10,64 +10,51 @@ import routes from '@generated/routes';
 import prefetchHelper from './prefetch';
 import preloadHelper from './preload';
 import flat from './flat';
-const fetched = {};
-const loaded = {};
-const isSlowConnection = () => {
-    // If user is on slow or constrained connection.
-    if (`connection` in navigator) {
-        if ((navigator.connection.effectiveType || ``).indexOf(`2g`) !== -1 &&
-            navigator.connection.saveData) {
-            return true;
-        }
-    }
-    return false;
-};
-const canPrefetch = (routePath) => !isSlowConnection() && !loaded[routePath] && !fetched[routePath];
-const canPreload = (routePath) => !isSlowConnection() && !loaded[routePath];
-const flatten = (arrays) => Array.prototype.concat.apply([], arrays);
+const fetched = new Set();
+const loaded = new Set();
+// If user is on slow or constrained connection.
+const isSlowConnection = () => navigator.connection?.effectiveType.includes('2g') ||
+    navigator.connection?.saveData;
+const canPrefetch = (routePath) => !isSlowConnection() && !loaded.has(routePath) && !fetched.has(routePath);
+const canPreload = (routePath) => !isSlowConnection() && !loaded.has(routePath);
+const getChunkNamesToLoad = (path) => Object.entries(routesChunkNames)
+    .filter(
 // Remove the last part containing the route hash
 // input: /blog/2018/12/14/Happy-First-Birthday-Slash-fe9
 // output: /blog/2018/12/14/Happy-First-Birthday-Slash
-const removeRouteNameHash = (str) => str.replace(/(-[^-]+)$/, '');
-const getChunkNamesToLoad = (path) => {
-    return flatten(Object.entries(routesChunkNames)
-        .filter(([routeNameWithHash]) => removeRouteNameHash(routeNameWithHash) === path)
-        .map(([, routeChunks]) => {
-        // flat() is useful for nested chunk names, it's not like array.flat()
-        return Object.values(flat(routeChunks));
-    }));
-};
+([routeNameWithHash]) => routeNameWithHash.replace(/-[^-]+$/, '') === path)
+    .flatMap(([, routeChunks]) => Object.values(flat(routeChunks)));
 const docusaurus = {
-    prefetch: (routePath) => {
+    prefetch(routePath) {
         if (!canPrefetch(routePath)) {
             return false;
         }
-        // Prevent future duplicate prefetch of routePath.
-        fetched[routePath] = true;
+        fetched.add(routePath);
         // Find all webpack chunk names needed.
         const matches = matchRoutes(routes, routePath);
-        const chunkNamesNeeded = flatten(matches.map((match) => getChunkNamesToLoad(match.route.path)));
+        const chunkNamesNeeded = matches.flatMap((match) => getChunkNamesToLoad(match.route.path));
         // Prefetch all webpack chunk assets file needed.
-        chunkNamesNeeded.forEach((chunkName) => {
-            // "__webpack_require__.gca" is a custom function provided by ChunkAssetPlugin.
-            // Pass it the chunkName or chunkId you want to load and it will return the URL for that chunk.
-            // eslint-disable-next-line no-undef
+        return Promise.all(chunkNamesNeeded.map((chunkName) => {
+            // "__webpack_require__.gca" is injected by ChunkAssetPlugin. Pass it
+            // the name of the chunk you want to load and it will return its URL.
+            // eslint-disable-next-line camelcase
             const chunkAsset = __webpack_require__.gca(chunkName);
-            // In some cases, webpack might decide to optimize further & hence the chunk assets are merged to another chunk/previous chunk.
-            // Hence, we can safely filter it out/don't need to load it.
-            if (chunkAsset && !/undefined/.test(chunkAsset)) {
-                prefetchHelper(chunkAsset);
+            // In some cases, webpack might decide to optimize further, leading to
+            // the chunk assets being merged to another chunk. In this case, we can
+            // safely filter it out and don't need to load it.
+            if (chunkAsset && !chunkAsset.includes('undefined')) {
+                return prefetchHelper(chunkAsset);
             }
-        });
-        return true;
+            return Promise.resolve();
+        }));
     },
-    preload: (routePath) => {
+    preload(routePath) {
         if (!canPreload(routePath)) {
             return false;
         }
-        loaded[routePath] = true;
-        preloadHelper(routes, routePath);
-        return true;
+        loaded.add(routePath);
+        return preloadHelper(routePath);
     },
 };
-export default docusaurus;
+// This object is directly mounted onto window, better freeze it
+export default Object.freeze(docusaurus);

package/lib/client/docusaurusContext.d.ts

@@ -0,0 +1,12 @@
+/**
+ * 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 type { DocusaurusContext } from '@docusaurus/types';
+export declare const Context: React.Context<DocusaurusContext>;
+export declare function DocusaurusContextProvider({ children, }: {
+    children: ReactNode;
+}): JSX.Element;

package/lib/client/docusaurusContext.js

@@ -0,0 +1,25 @@
+/**
+ * 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 from 'react';
+import siteConfig from '@generated/docusaurus.config';
+import globalData from '@generated/globalData';
+import i18n from '@generated/i18n';
+import codeTranslations from '@generated/codeTranslations';
+import siteMetadata from '@generated/site-metadata';
+// Static value on purpose: don't make it dynamic!
+// Using context is still useful for testability reasons.
+const contextValue = {
+    siteConfig,
+    siteMetadata,
+    globalData,
+    i18n,
+    codeTranslations,
+};
+export const Context = React.createContext(contextValue);
+export function DocusaurusContextProvider({ children, }) {
+    return <Context.Provider value={contextValue}>{children}</Context.Provider>;
+}

package/lib/client/exports/BrowserOnly.d.ts

@@ -4,9 +4,7 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
+/// <reference types="@docusaurus/module-type-aliases" />
 /// <reference types="react" />
-declare function BrowserOnly({ children, fallback, }: {
-    children?: () => JSX.Element;
-    fallback?: JSX.Element;
-}): JSX.Element | null;
-export default BrowserOnly;
+import type { Props } from '@docusaurus/BrowserOnly';
+export default function BrowserOnly({ children, fallback, }: Props): JSX.Element | null;

package/lib/client/exports/BrowserOnly.js

@@ -4,13 +4,19 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-import React from 'react';
-import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
-function BrowserOnly({ children, fallback, }) {
-    const { isClient } = useDocusaurusContext();
-    if (isClient && children != null) {
-        return React.createElement(React.Fragment, null, children());
+import React, { isValidElement } from 'react';
+import useIsBrowser from '@docusaurus/useIsBrowser';
+// Similar comp to the one described here:
+// https://www.joshwcomeau.com/react/the-perils-of-rehydration/#abstractions
+export default function BrowserOnly({ children, fallback, }) {
+    const isBrowser = useIsBrowser();
+    if (isBrowser) {
+        if (typeof children !== 'function' &&
+            process.env.NODE_ENV === 'development') {
+            throw new Error(`Docusaurus error: The children of <BrowserOnly> must be a "render function", e.g. <BrowserOnly>{() => <span>{window.location.href}</span>}</BrowserOnly>.
+Current type: ${isValidElement(children) ? 'React element' : typeof children}`);
+        }
+        return <>{children?.()}</>;
     }
-    return fallback || null;
+    return fallback ?? null;
 }
-export default BrowserOnly;

package/lib/client/exports/ComponentCreator.d.ts

@@ -5,5 +5,9 @@
  * LICENSE file in the root directory of this source tree.
  */
 import Loadable from 'react-loadable';
-declare function ComponentCreator(path: string, hash: string): ReturnType<typeof Loadable>;
-export default ComponentCreator;
+declare global {
+    interface NodeRequire {
+        resolveWeak: (name: string) => number;
+    }
+}
+export default function ComponentCreator(path: string, hash: string): ReturnType<typeof Loadable>;