@docusaurus/core 2.0.0-beta.16 → 2.0.0-beta.19

package/lib/client/PendingNavigation.js

@@ -5,19 +5,21 @@
  * 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 {
     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,72 +27,39 @@ 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 } = 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));
+        return false;
     }
     render() {
         const { children, location } = this.props;
-        return (<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/{server/loadSetup.d.ts → client/SiteMetadataDefaults.d.ts}

@@ -4,5 +4,5 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-import type { Props } from '@docusaurus/types';
-export default function loadSetup(name: string): Promise<Props>;
+/// <reference types="react" />
+export default function SiteMetadataDefaults(): JSX.Element;

package/lib/client/SiteMetadataDefaults.js

@@ -0,0 +1,19 @@
+/**
+ * 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, tagline, title }, i18n: { currentLocale, localeConfigs }, } = useDocusaurusContext();
+    const faviconUrl = useBaseUrl(favicon);
+    const { htmlLang, direction: htmlDir } = localeConfigs[currentLocale];
+    return (<Head defaultTitle={`${title}${tagline ? ` · ${tagline}` : ''}`}>
+      <html lang={htmlLang} dir={htmlDir}/>
+      {favicon && <link rel="icon" href={faviconUrl}/>}
+    </Head>);
+}

package/lib/client/clientEntry.js

@@ -5,10 +5,9 @@
  * 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 { HelmetProvider } from 'react-helmet-async';
-import routes from '@generated/routes';
 import ExecutionEnvironment from './exports/ExecutionEnvironment';
 import App from './App';
 import preload from './preload';
@@ -21,8 +20,8 @@ if (ExecutionEnvironment.canUseDOM) {
     // first-load experience.
     // For development, there is no existing markup so we had to render it.
     // 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(() => {
+    const renderMethod = process.env.NODE_ENV === 'production' ? ReactDOM.hydrate : ReactDOM.render;
+    preload(window.location.pathname).then(() => {
         renderMethod(<HelmetProvider>
         <BrowserRouter>
           <App />

package/lib/client/docusaurus.d.ts

@@ -15,8 +15,8 @@ declare global {
         };
     }
 }
-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,58 +10,51 @@ import routes from '@generated/routes';
 import prefetchHelper from './prefetch';
 import preloadHelper from './preload';
 import flat from './flat';
-const fetched = {};
-const loaded = {};
+const fetched = new Set();
+const loaded = new Set();
 // If user is on slow or constrained connection.
-const isSlowConnection = () => {
-    var _a, _b;
-    return ((_a = navigator.connection) === null || _a === void 0 ? void 0 : _a.effectiveType.includes('2g')) &&
-        ((_b = navigator.connection) === null || _b === void 0 ? void 0 : _b.saveData);
-};
-const canPrefetch = (routePath) => !isSlowConnection() && !loaded[routePath] && !fetched[routePath];
-const canPreload = (routePath) => !isSlowConnection() && !loaded[routePath];
+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) => Object.entries(routesChunkNames)
-    .filter(([routeNameWithHash]) => removeRouteNameHash(routeNameWithHash) === path)
-    .flatMap(([, routeChunks]) => 
-// flat() is useful for nested chunk names, it's not like array.flat()
-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 = 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.
+        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.
+            // 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 && !/undefined/.test(chunkAsset)) {
-                prefetchHelper(chunkAsset);
+                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/exports/BrowserOnly.d.ts

@@ -4,8 +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" />
-export default function BrowserOnly({ children, fallback, }: {
-    children: () => JSX.Element;
-    fallback?: JSX.Element;
-}): JSX.Element | null;
+import type { Props } from '@docusaurus/BrowserOnly';
+export default function BrowserOnly({ children, fallback, }: Props): JSX.Element | null;

package/lib/client/exports/BrowserOnly.js

@@ -16,7 +16,7 @@ export default function BrowserOnly({ children, fallback, }) {
             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 <>{children?.()}</>;
     }
-    return fallback || null;
+    return fallback ?? null;
 }

package/lib/client/exports/ComponentCreator.js

@@ -10,69 +10,94 @@ import Loading from '@theme/Loading';
 import routesChunkNames from '@generated/routesChunkNames';
 import registry from '@generated/registry';
 import flat from '../flat';
+import { RouteContextProvider } from '../routeContext';
 export default function ComponentCreator(path, hash) {
     // 404 page
     if (path === '*') {
         return Loadable({
             loading: Loading,
-            loader: () => import('@theme/NotFound'),
+            loader: () => import('@theme/NotFound').then(({ default: NotFound }) => (props) => (<RouteContextProvider 
+            // Do we want a better name than native-default?
+            value={{ plugin: { name: 'native', id: 'default' } }}>
+            <NotFound {...props}/>
+          </RouteContextProvider>)),
         });
     }
-    const chunkNamesKey = `${path}-${hash}`;
-    const chunkNames = routesChunkNames[chunkNamesKey];
-    const optsModules = [];
+    const chunkNames = routesChunkNames[`${path}-${hash}`];
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const loader = {};
+    const modules = [];
     const optsWebpack = [];
-    const optsLoader = {};
-    /* Prepare opts data that react-loadable needs
-    https://github.com/jamiebuilds/react-loadable#declaring-which-modules-are-being-loaded
-    Example:
-    - optsLoader:
-      {
-        component: () => import('./Pages.js'),
-        content.foo: () => import('./doc1.md'),
-      }
-    - optsModules: ['./Pages.js', './doc1.md']
-    - optsWebpack: [
-        require.resolveWeak('./Pages.js'),
-        require.resolveWeak('./doc1.md'),
-      ]
-    */
+    // A map from prop names to chunk names.
+    // e.g. Suppose the plugin added this as route:
+    //   { __comp: "...", prop: { foo: "..." }, items: ["...", "..."] }
+    // It will become:
+    //   { __comp: "...", "prop.foo": "...", "items.0": "...", "items.1": ... }
+    // Loadable.Map will _map_ over `loader` and load each key.
     const flatChunkNames = flat(chunkNames);
-    Object.keys(flatChunkNames).forEach((key) => {
-        const chunkRegistry = registry[flatChunkNames[key]];
+    Object.entries(flatChunkNames).forEach(([keyPath, chunkName]) => {
+        const chunkRegistry = registry[chunkName];
         if (chunkRegistry) {
             // eslint-disable-next-line prefer-destructuring
-            optsLoader[key] = chunkRegistry[0];
-            optsModules.push(chunkRegistry[1]);
+            loader[keyPath] = chunkRegistry[0];
+            modules.push(chunkRegistry[1]);
             optsWebpack.push(chunkRegistry[2]);
         }
     });
     return Loadable.Map({
         loading: Loading,
-        loader: optsLoader,
-        modules: optsModules,
+        loader,
+        modules,
         webpack: () => optsWebpack,
         render: (loaded, props) => {
-            // Clone the original object since we don't want to alter the original.
+            // `loaded` will be a map from key path (as returned from the flattened
+            // chunk names) to the modules loaded from the loaders. We now have to
+            // restore the chunk names' previous shape from this flat record.
+            // We do so by taking advantage of the existing `chunkNames` and replacing
+            // each chunk name with its loaded module, so we don't create another
+            // object from scratch.
             const loadedModules = JSON.parse(JSON.stringify(chunkNames));
-            Object.keys(loaded).forEach((key) => {
-                let val = loadedModules;
-                const keyPath = key.split('.');
-                for (let i = 0; i < keyPath.length - 1; i += 1) {
-                    val = val[keyPath[i]];
+            Object.entries(loaded).forEach(([keyPath, loadedModule]) => {
+                // JSON modules are also loaded as `{ default: ... }` (`import()`
+                // semantics) but we just want to pass the actual value to props.
+                const chunk = loadedModule.default;
+                // One loaded chunk can only be one of two things: a module (props) or a
+                // component. Modules are always JSON, so `default` always exists. This
+                // could only happen with a user-defined component.
+                if (!chunk) {
+                    throw new Error(`The page component at ${path} doesn't have a default export. This makes it impossible to render anything. Consider default-exporting a React component.`);
                 }
-                val[keyPath[keyPath.length - 1]] = loaded[key].default;
-                const nonDefaultKeys = Object.keys(loaded[key]).filter((k) => k !== 'default');
-                if (nonDefaultKeys && nonDefaultKeys.length) {
-                    nonDefaultKeys.forEach((nonDefaultKey) => {
-                        val[keyPath[keyPath.length - 1]][nonDefaultKey] =
-                            loaded[key][nonDefaultKey];
+                // A module can be a primitive, for example, if the user stored a string
+                // as a prop. However, there seems to be a bug with swc-loader's CJS
+                // logic, in that it would load a JSON module with content "foo" as
+                // `{ default: "foo", 0: "f", 1: "o", 2: "o" }`. Just to be safe, we
+                // first make sure that the chunk is non-primitive.
+                if (typeof chunk === 'object' || typeof chunk === 'function') {
+                    Object.keys(loadedModule)
+                        .filter((k) => k !== 'default')
+                        .forEach((nonDefaultKey) => {
+                        chunk[nonDefaultKey] = loadedModule[nonDefaultKey];
                     });
                 }
+                // We now have this chunk prepared. Go down the key path and replace the
+                // chunk name with the actual chunk.
+                let val = loadedModules;
+                const keyPaths = keyPath.split('.');
+                keyPaths.slice(0, -1).forEach((k) => {
+                    val = val[k];
+                });
+                val[keyPaths[keyPaths.length - 1]] = chunk;
             });
-            const Component = loadedModules.component;
-            delete loadedModules.component;
-            return <Component {...loadedModules} {...props}/>;
+            /* eslint-disable no-underscore-dangle */
+            const Component = loadedModules.__comp;
+            delete loadedModules.__comp;
+            const routeContext = loadedModules.__context;
+            delete loadedModules.__context;
+            /* eslint-enable no-underscore-dangle */
+            // Is there any way to put this RouteContextProvider upper in the tree?
+            return (<RouteContextProvider value={routeContext}>
+          <Component {...loadedModules} {...props}/>
+        </RouteContextProvider>);
         },
     });
 }

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

@@ -7,9 +7,9 @@
 /// <reference types="@docusaurus/module-type-aliases" />
 import React, { type ReactNode } from 'react';
 import type { Props } from '@docusaurus/ErrorBoundary';
-interface State {
+declare type State = {
     error: Error | null;
-}
+};
 export default class ErrorBoundary extends React.Component<Props, State> {
     constructor(props: Props);
     componentDidCatch(error: Error): void;

package/lib/client/exports/ErrorBoundary.js

@@ -19,18 +19,17 @@ export default class ErrorBoundary extends React.Component {
         }
     }
     render() {
-        var _a;
         const { children } = this.props;
         const { error } = this.state;
         if (error) {
-            const fallback = (_a = this.props.fallback) !== null && _a !== void 0 ? _a : DefaultFallback;
+            const fallback = this.props.fallback ?? DefaultFallback;
             return fallback({
                 error,
                 tryAgain: () => this.setState({ error: null }),
             });
         }
-        return (children !== null && children !== void 0 ? children : 
-        // See https://github.com/facebook/docusaurus/issues/6337#issuecomment-1012913647
-        null);
+        return (children ??
+            // See https://github.com/facebook/docusaurus/issues/6337#issuecomment-1012913647
+            null);
     }
 }

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

@@ -9,4 +9,4 @@ import { type ReactNode } from 'react';
 import type { InterpolateProps, InterpolateValues } from '@docusaurus/Interpolate';
 export declare function interpolate<Str extends string>(text: Str, values?: InterpolateValues<Str, string | number>): string;
 export declare function interpolate<Str extends string, Value extends ReactNode>(text: Str, values?: InterpolateValues<Str, Value>): ReactNode;
-export default function Interpolate<Str extends string>({ children, values, }: InterpolateProps<Str>): ReactNode;
+export default function Interpolate<Str extends string>({ children, values, }: InterpolateProps<Str>): JSX.Element;

package/lib/client/exports/Interpolate.js

@@ -4,53 +4,30 @@
  * 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';
-/*
-Minimal implementation of a React interpolate component.
-We don't ship a markdown parser nor a feature-complete i18n library on purpose.
-More details here: https://github.com/facebook/docusaurus/pull/4295
-*/
-const ValueRegexp = /{\w+}/g;
-const ValueFoundMarker = '{}'; // does not care much
+import React, { isValidElement } from 'react';
 export function interpolate(text, values) {
-    const elements = [];
-    const processedText = text.replace(ValueRegexp, (match) => {
-        // remove {{ and }} around the placeholder
-        const key = match.substring(1, match.length - 1);
-        const value = values === null || values === void 0 ? void 0 : values[key];
-        if (typeof value !== 'undefined') {
-            const element = React.isValidElement(value)
-                ? value
-                : // For non-React elements: basic primitive->string conversion
-                    String(value);
-            elements.push(element);
-            return ValueFoundMarker;
+    // eslint-disable-next-line prefer-named-capture-group
+    const segments = text.split(/(\{\w+\})/).map((seg, index) => {
+        // Odd indices (1, 3, 5...) of the segments are (potentially) interpolatable
+        if (index % 2 === 1) {
+            const value = values?.[seg.slice(1, -1)];
+            if (value !== undefined) {
+                return value;
+            }
+            // No match: add warning? There's no way to "escape" interpolation though
         }
-        return match; // no match? add warning?
+        return seg;
     });
-    // No interpolation to be done: just return the text
-    if (elements.length === 0) {
-        return text;
+    if (segments.some((seg) => isValidElement(seg))) {
+        return segments
+            .map((seg, index) => isValidElement(seg) ? React.cloneElement(seg, { key: index }) : seg)
+            .filter((seg) => seg !== '');
     }
-    // Basic string interpolation: returns interpolated string
-    if (elements.every((el) => typeof el === 'string')) {
-        return processedText
-            .split(ValueFoundMarker)
-            .reduce((str, value, index) => { var _a; return str.concat(value).concat((_a = elements[index]) !== null && _a !== void 0 ? _a : ''); }, '');
-    }
-    // JSX interpolation: returns ReactNode
-    return processedText.split(ValueFoundMarker).reduce((array, value, index) => [
-        ...array,
-        <React.Fragment key={index}>
-        {value}
-        {elements[index]}
-      </React.Fragment>,
-    ], []);
+    return segments.join('');
 }
 export default function Interpolate({ children, values, }) {
     if (typeof children !== 'string') {
-        console.warn('Illegal <Interpolate> children', children);
-        throw new Error('The Docusaurus <Interpolate> component only accept simple string values');
+        throw new Error(`The Docusaurus <Interpolate> component only accept simple string values. Received: ${isValidElement(children) ? 'React element' : typeof children}`);
     }
-    return interpolate(children, values);
+    return <>{interpolate(children, values)}</>;
 }