@docusaurus/theme-common 2.0.0-beta.1ab8aa0af → 2.0.0-beta.2

package/lib/index.d.ts

@@ -14,7 +14,9 @@ export { isDocsPluginEnabled } from './utils/docsUtils';
 export { isSamePath } from './utils/pathUtils';
 export { useTitleFormatter } from './utils/generalUtils';
 export { usePluralForm } from './utils/usePluralForm';
-export { useChangeRoute } from './utils/useChangeRoute';
+export { useLocationChange } from './utils/useLocationChange';
+export { usePrevious } from './utils/usePrevious';
 export { useDocsPreferredVersion, useDocsPreferredVersionByPluginId, } from './utils/docsPreferredVersion/useDocsPreferredVersion';
 export { DocsPreferredVersionContextProvider } from './utils/docsPreferredVersion/DocsPreferredVersionProvider';
 export { ThemeClassNames } from './utils/ThemeClassNames';
+export { AnnouncementBarProvider, useAnnouncementBar, } from './utils/announcementBarUtils';

package/lib/index.js

@@ -13,7 +13,9 @@ export { isDocsPluginEnabled } from './utils/docsUtils';
 export { isSamePath } from './utils/pathUtils';
 export { useTitleFormatter } from './utils/generalUtils';
 export { usePluralForm } from './utils/usePluralForm';
-export { useChangeRoute } from './utils/useChangeRoute';
+export { useLocationChange } from './utils/useLocationChange';
+export { usePrevious } from './utils/usePrevious';
 export { useDocsPreferredVersion, useDocsPreferredVersionByPluginId, } from './utils/docsPreferredVersion/useDocsPreferredVersion';
 export { DocsPreferredVersionContextProvider } from './utils/docsPreferredVersion/DocsPreferredVersionProvider';
 export { ThemeClassNames } from './utils/ThemeClassNames';
+export { AnnouncementBarProvider, useAnnouncementBar, } from './utils/announcementBarUtils';

package/lib/utils/announcementBarInlineJavaScript.js

@@ -0,0 +1 @@
+"use strict";

package/lib/utils/announcementBarUtils.d.ts

@@ -0,0 +1,17 @@
+/**
+ * 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 { ReactNode } from 'react';
+export declare const AnnouncementBarDismissStorageKey = "docusaurus.announcement.dismiss";
+declare type AnnouncementBarAPI = {
+    readonly isClosed: boolean;
+    readonly close: () => void;
+};
+export declare const AnnouncementBarProvider: ({ children }: {
+    children: ReactNode;
+}) => JSX.Element;
+export declare const useAnnouncementBar: () => AnnouncementBarAPI;
+export {};

package/lib/utils/announcementBarUtils.js

@@ -0,0 +1,73 @@
+/**
+ * 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, useEffect, useCallback, useMemo, useContext, createContext, } from 'react';
+import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
+import { createStorageSlot } from './storageUtils';
+import { useThemeConfig } from './useThemeConfig';
+export const AnnouncementBarDismissStorageKey = 'docusaurus.announcement.dismiss';
+const AnnouncementBarIdStorageKey = 'docusaurus.announcement.id';
+const AnnouncementBarDismissStorage = createStorageSlot(AnnouncementBarDismissStorageKey);
+const IdStorage = createStorageSlot(AnnouncementBarIdStorageKey);
+const isDismissedInStorage = () => AnnouncementBarDismissStorage.get() === 'true';
+const setDismissedInStorage = (bool) => AnnouncementBarDismissStorage.set(String(bool));
+const useAnnouncementBarContextValue = () => {
+    const { announcementBar } = useThemeConfig();
+    const { isClient } = useDocusaurusContext();
+    const [isClosed, setClosed] = useState(() => {
+        return isClient
+            ? // On client navigation: init with localstorage value
+                isDismissedInStorage()
+            : // On server/hydration: always visible to prevent layout shifts (will be hidden with css if needed)
+                false;
+    });
+    // Update state after hydration
+    useEffect(() => {
+        setClosed(isDismissedInStorage());
+    }, []);
+    const handleClose = useCallback(() => {
+        setDismissedInStorage(true);
+        setClosed(true);
+    }, []);
+    useEffect(() => {
+        if (!announcementBar) {
+            return;
+        }
+        const { id } = announcementBar;
+        let viewedId = IdStorage.get();
+        // retrocompatibility due to spelling mistake of default id
+        // see https://github.com/facebook/docusaurus/issues/3338
+        if (viewedId === 'annoucement-bar') {
+            viewedId = 'announcement-bar';
+        }
+        const isNewAnnouncement = id !== viewedId;
+        IdStorage.set(id);
+        if (isNewAnnouncement) {
+            setDismissedInStorage(false);
+        }
+        if (isNewAnnouncement || !isDismissedInStorage()) {
+            setClosed(false);
+        }
+    }, []);
+    return useMemo(() => {
+        return {
+            isClosed,
+            close: handleClose,
+        };
+    }, [isClosed]);
+};
+const AnnouncementBarContext = createContext(null);
+export const AnnouncementBarProvider = ({ children }) => {
+    const value = useAnnouncementBarContextValue();
+    return (React.createElement(AnnouncementBarContext.Provider, { value: value }, children));
+};
+export const useAnnouncementBar = () => {
+    const api = useContext(AnnouncementBarContext);
+    if (!api) {
+        throw new Error('useAnnouncementBar(): AnnouncementBar not found in React context: make sure to use the AnnouncementBarProvider on top of the tree');
+    }
+    return api;
+};

package/lib/utils/docsPreferredVersion/DocsPreferredVersionProvider.js

@@ -88,7 +88,7 @@ function DocsPreferredVersionContextProviderUnsafe({ children, }) {
 export function useDocsPreferredVersionContext() {
     const value = useContext(Context);
     if (!value) {
-        throw new Error("Can't find docs preferred context, maybe you forgot to use the DocsPreferredVersionContextProvider ?");
+        throw new Error('Can\'t find docs preferred context, maybe you forgot to use the "DocsPreferredVersionContextProvider"?');
     }
     return value;
 }

package/lib/utils/storageUtils.js

@@ -10,7 +10,7 @@ const DefaultStorageType = 'localStorage';
 // See https://github.com/facebook/docusaurus/pull/4501
 function getBrowserStorage(storageType = DefaultStorageType) {
     if (typeof window === 'undefined') {
-        throw new Error('Browser storage is not available on NodeJS / Docusaurus SSR process');
+        throw new Error('Browser storage is not available on Node.js/Docusaurus SSR process.');
     }
     if (storageType === 'none') {
         return null;
@@ -33,7 +33,7 @@ let hasLoggedBrowserStorageNotAvailableWarning = false;
 function logOnceBrowserStorageNotAvailableWarning(error) {
     if (!hasLoggedBrowserStorageNotAvailableWarning) {
         console.warn(`Docusaurus browser storage is not available.
-Possible reasons: running Docusaurus in an Iframe, in an Incognito browser session, or using too strict browser privacy settings.`, error);
+Possible reasons: running Docusaurus in an iframe, in an incognito browser session, or using too strict browser privacy settings.`, error);
         hasLoggedBrowserStorageNotAvailableWarning = true;
     }
 }
@@ -45,7 +45,7 @@ const NoopStorageSlot = {
 //  Fail-fast, as storage APIs should not be used during the SSR process
 function createServerStorageSlot(key) {
     function throwError() {
-        throw new Error(`Illegal storage API usage for storage key=${key}.
+        throw new Error(`Illegal storage API usage for storage key "${key}".
 Docusaurus storage APIs are not supposed to be called on the server-rendering process.
 Please only call storage APIs in effects and event handlers.`);
     }

package/lib/utils/useLocationChange.d.ts

@@ -0,0 +1,14 @@
+/**
+ * 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 { Location } from '@docusaurus/history';
+declare type LocationChangeEvent = {
+    location: Location;
+    previousLocation: Location | undefined;
+};
+declare type OnLocationChange = (locationChangeEvent: LocationChangeEvent) => void;
+export declare function useLocationChange(onLocationChange: OnLocationChange): void;
+export {};

package/lib/utils/useLocationChange.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 { useEffect, useRef } from 'react';
+import { useLocation } from '@docusaurus/router';
+import { usePrevious } from './usePrevious';
+export function useLocationChange(onLocationChange) {
+    const location = useLocation();
+    const previousLocation = usePrevious(location);
+    const isFirst = useRef(true);
+    useEffect(() => {
+        // Prevent first effect to trigger the listener on mount
+        if (isFirst.current) {
+            isFirst.current = false;
+            return;
+        }
+        onLocationChange({
+            location,
+            previousLocation,
+        });
+    }, [location]);
+}

package/lib/utils/usePluralForm.js

@@ -54,7 +54,7 @@ function useLocalePluralForms() {
                 return createLocalePluralForms(currentLocale);
             }
             catch (e) {
-                console.error(`Failed to use Intl.PluralRules for locale=${currentLocale}.
+                console.error(`Failed to use Intl.PluralRules for locale "${currentLocale}".
 Docusaurus will fallback to a default/fallback (English) Intl.PluralRules implementation.
 `);
                 return EnglishPluralForms;

package/lib/utils/{useChangeRoute.d.ts → usePrevious.d.ts}

@@ -4,4 +4,4 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-export declare function useChangeRoute(onRouteChange: () => void): void;
+export declare function usePrevious<T>(value: T): T | undefined;

package/lib/utils/usePrevious.js

@@ -0,0 +1,14 @@
+/**
+ * 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 { useRef, useEffect } from 'react';
+export function usePrevious(value) {
+    const ref = useRef();
+    useEffect(() => {
+        ref.current = value;
+    });
+    return ref.current;
+}

package/lib/utils/useThemeConfig.d.ts

@@ -78,5 +78,6 @@ export declare type ThemeConfig = {
     footer?: Footer;
     hideableSidebar: boolean;
     image: string;
+    metadatas: Array<Record<string, string>>;
 };
 export declare function useThemeConfig(): ThemeConfig;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docusaurus/theme-common",
-  "version": "2.0.0-beta.1ab8aa0af",
+  "version": "2.0.0-beta.2",
   "description": "Common code for Docusaurus themes.",
   "main": "./lib/index.js",
   "types": "./lib/index.d.ts",
@@ -18,23 +18,23 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@docusaurus/core": "2.0.0-beta.1ab8aa0af",
-    "@docusaurus/plugin-content-blog": "2.0.0-beta.1ab8aa0af",
-    "@docusaurus/plugin-content-docs": "2.0.0-beta.1ab8aa0af",
-    "@docusaurus/plugin-content-pages": "2.0.0-beta.1ab8aa0af",
-    "@docusaurus/types": "2.0.0-beta.1ab8aa0af",
+    "@docusaurus/core": "2.0.0-beta.2",
+    "@docusaurus/plugin-content-blog": "2.0.0-beta.2",
+    "@docusaurus/plugin-content-docs": "2.0.0-beta.2",
+    "@docusaurus/plugin-content-pages": "2.0.0-beta.2",
+    "@docusaurus/types": "2.0.0-beta.2",
     "tslib": "^2.1.0"
   },
   "devDependencies": {
-    "@docusaurus/module-type-aliases": "2.0.0-beta.1ab8aa0af"
+    "@docusaurus/module-type-aliases": "2.0.0-beta.2"
   },
   "peerDependencies": {
-    "prism-react-renderer": "^1.1.1",
+    "prism-react-renderer": "^1.2.1",
     "react": "^16.8.4 || ^17.0.0",
     "react-dom": "^16.8.4 || ^17.0.0"
   },
   "engines": {
     "node": ">=12.13.0"
   },
-  "gitHead": "63c06baac39707a1a4c3cc4c0031cb2163f256c4"
+  "gitHead": "883f07fddffaf1657407c8e202e370cc436e25f7"
 }

package/src/index.ts

@@ -33,7 +33,9 @@ export {useTitleFormatter} from './utils/generalUtils';
 
 export {usePluralForm} from './utils/usePluralForm';
 
-export {useChangeRoute} from './utils/useChangeRoute';
+export {useLocationChange} from './utils/useLocationChange';
+
+export {usePrevious} from './utils/usePrevious';
 
 export {
   useDocsPreferredVersion,
@@ -43,3 +45,8 @@ export {
 export {DocsPreferredVersionContextProvider} from './utils/docsPreferredVersion/DocsPreferredVersionProvider';
 
 export {ThemeClassNames} from './utils/ThemeClassNames';
+
+export {
+  AnnouncementBarProvider,
+  useAnnouncementBar,
+} from './utils/announcementBarUtils';

package/src/utils/announcementBarUtils.tsx

@@ -0,0 +1,115 @@
+/**
+ * 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,
+  useEffect,
+  useCallback,
+  useMemo,
+  ReactNode,
+  useContext,
+  createContext,
+} from 'react';
+import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
+import {createStorageSlot} from './storageUtils';
+import {useThemeConfig} from './useThemeConfig';
+
+export const AnnouncementBarDismissStorageKey =
+  'docusaurus.announcement.dismiss';
+const AnnouncementBarIdStorageKey = 'docusaurus.announcement.id';
+
+const AnnouncementBarDismissStorage = createStorageSlot(
+  AnnouncementBarDismissStorageKey,
+);
+const IdStorage = createStorageSlot(AnnouncementBarIdStorageKey);
+
+const isDismissedInStorage = () =>
+  AnnouncementBarDismissStorage.get() === 'true';
+const setDismissedInStorage = (bool: boolean) =>
+  AnnouncementBarDismissStorage.set(String(bool));
+
+type AnnouncementBarAPI = {
+  readonly isClosed: boolean;
+  readonly close: () => void;
+};
+
+const useAnnouncementBarContextValue = (): AnnouncementBarAPI => {
+  const {announcementBar} = useThemeConfig();
+  const {isClient} = useDocusaurusContext();
+
+  const [isClosed, setClosed] = useState(() => {
+    return isClient
+      ? // On client navigation: init with localstorage value
+        isDismissedInStorage()
+      : // On server/hydration: always visible to prevent layout shifts (will be hidden with css if needed)
+        false;
+  });
+  // Update state after hydration
+  useEffect(() => {
+    setClosed(isDismissedInStorage());
+  }, []);
+
+  const handleClose = useCallback(() => {
+    setDismissedInStorage(true);
+    setClosed(true);
+  }, []);
+
+  useEffect(() => {
+    if (!announcementBar) {
+      return;
+    }
+    const {id} = announcementBar;
+
+    let viewedId = IdStorage.get();
+
+    // retrocompatibility due to spelling mistake of default id
+    // see https://github.com/facebook/docusaurus/issues/3338
+    if (viewedId === 'annoucement-bar') {
+      viewedId = 'announcement-bar';
+    }
+
+    const isNewAnnouncement = id !== viewedId;
+
+    IdStorage.set(id);
+
+    if (isNewAnnouncement) {
+      setDismissedInStorage(false);
+    }
+
+    if (isNewAnnouncement || !isDismissedInStorage()) {
+      setClosed(false);
+    }
+  }, []);
+
+  return useMemo(() => {
+    return {
+      isClosed,
+      close: handleClose,
+    };
+  }, [isClosed]);
+};
+
+const AnnouncementBarContext = createContext<AnnouncementBarAPI | null>(null);
+
+export const AnnouncementBarProvider = ({children}: {children: ReactNode}) => {
+  const value = useAnnouncementBarContextValue();
+  return (
+    <AnnouncementBarContext.Provider value={value}>
+      {children}
+    </AnnouncementBarContext.Provider>
+  );
+};
+
+export const useAnnouncementBar = (): AnnouncementBarAPI => {
+  const api = useContext(AnnouncementBarContext);
+  if (!api) {
+    throw new Error(
+      'useAnnouncementBar(): AnnouncementBar not found in React context: make sure to use the AnnouncementBarProvider on top of the tree',
+    );
+  }
+  return api;
+};

package/src/utils/docsPreferredVersion/DocsPreferredVersionProvider.tsx

@@ -158,7 +158,7 @@ export function useDocsPreferredVersionContext(): DocsPreferredVersionContextVal
   const value = useContext(Context);
   if (!value) {
     throw new Error(
-      "Can't find docs preferred context, maybe you forgot to use the DocsPreferredVersionContextProvider ?",
+      'Can\'t find docs preferred context, maybe you forgot to use the "DocsPreferredVersionContextProvider"?',
     );
   }
   return value;

package/src/utils/storageUtils.ts

@@ -18,7 +18,7 @@ function getBrowserStorage(
 ): Storage | null {
   if (typeof window === 'undefined') {
     throw new Error(
-      'Browser storage is not available on NodeJS / Docusaurus SSR process',
+      'Browser storage is not available on Node.js/Docusaurus SSR process.',
     );
   }
   if (storageType === 'none') {
@@ -42,7 +42,7 @@ function logOnceBrowserStorageNotAvailableWarning(error: Error) {
   if (!hasLoggedBrowserStorageNotAvailableWarning) {
     console.warn(
       `Docusaurus browser storage is not available.
-Possible reasons: running Docusaurus in an Iframe, in an Incognito browser session, or using too strict browser privacy settings.`,
+Possible reasons: running Docusaurus in an iframe, in an incognito browser session, or using too strict browser privacy settings.`,
       error,
     );
     hasLoggedBrowserStorageNotAvailableWarning = true;
@@ -65,7 +65,7 @@ const NoopStorageSlot: StorageSlot = {
 //  Fail-fast, as storage APIs should not be used during the SSR process
 function createServerStorageSlot(key: string): StorageSlot {
   function throwError(): never {
-    throw new Error(`Illegal storage API usage for storage key=${key}.
+    throw new Error(`Illegal storage API usage for storage key "${key}".
 Docusaurus storage APIs are not supposed to be called on the server-rendering process.
 Please only call storage APIs in effects and event handlers.`);
   }

package/src/utils/useAlternatePageUtils.ts

@@ -11,7 +11,15 @@ import {useLocation} from '@docusaurus/router';
 // Permits to obtain the url of the current page in another locale
 // Useful to generate hreflang meta headers etc...
 // See https://developers.google.com/search/docs/advanced/crawling/localized-versions
-export function useAlternatePageUtils() {
+export function useAlternatePageUtils(): {
+  createUrl: ({
+    locale,
+    fullyQualified,
+  }: {
+    locale: string;
+    fullyQualified: boolean;
+  }) => string;
+} {
   const {
     siteConfig: {baseUrl, url},
     i18n: {defaultLocale, currentLocale},

package/src/utils/useLocationChange.ts

@@ -0,0 +1,37 @@
+/**
+ * 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 {useLocation} from '@docusaurus/router';
+import {Location} from '@docusaurus/history';
+import {usePrevious} from './usePrevious';
+
+type LocationChangeEvent = {
+  location: Location;
+  previousLocation: Location | undefined;
+};
+
+type OnLocationChange = (locationChangeEvent: LocationChangeEvent) => void;
+
+export function useLocationChange(onLocationChange: OnLocationChange): void {
+  const location = useLocation();
+  const previousLocation = usePrevious(location);
+  const isFirst = useRef<boolean>(true);
+
+  useEffect(() => {
+    // Prevent first effect to trigger the listener on mount
+    if (isFirst.current) {
+      isFirst.current = false;
+      return;
+    }
+
+    onLocationChange({
+      location,
+      previousLocation,
+    });
+  }, [location]);
+}

package/src/utils/usePluralForm.ts

@@ -70,7 +70,7 @@ function useLocalePluralForms(): LocalePluralForms {
       try {
         return createLocalePluralForms(currentLocale);
       } catch (e) {
-        console.error(`Failed to use Intl.PluralRules for locale=${currentLocale}.
+        console.error(`Failed to use Intl.PluralRules for locale "${currentLocale}".
 Docusaurus will fallback to a default/fallback (English) Intl.PluralRules implementation.
 `);
         return EnglishPluralForms;
@@ -107,7 +107,9 @@ function selectPluralMessage(
   }
 }
 
-export function usePluralForm() {
+export function usePluralForm(): {
+  selectMessage: (count: number, pluralMessages: string) => string;
+} {
   const localePluralForm = useLocalePluralForms();
   return {
     selectMessage: (count: number, pluralMessages: string): string => {

package/src/utils/usePrevious.ts

@@ -0,0 +1,18 @@
+/**
+ * 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 {useRef, useEffect} from 'react';
+
+export function usePrevious<T>(value: T): T | undefined {
+  const ref = useRef<T>();
+
+  useEffect(() => {
+    ref.current = value;
+  });
+
+  return ref.current;
+}

package/src/utils/useThemeConfig.ts

@@ -102,6 +102,7 @@ export type ThemeConfig = {
   footer?: Footer;
   hideableSidebar: boolean;
   image: string;
+  metadatas: Array<Record<string, string>>;
 };
 
 export function useThemeConfig(): ThemeConfig {

package/lib/utils/useChangeRoute.js

@@ -1,18 +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.
- */
-import { useRef, useEffect } from 'react';
-import { useLocation } from '@docusaurus/router';
-export function useChangeRoute(onRouteChange) {
-    const { pathname } = useLocation();
-    const latestPathnameRef = useRef(pathname);
-    useEffect(() => {
-        if (pathname !== latestPathnameRef.current) {
-            latestPathnameRef.current = pathname;
-            onRouteChange();
-        }
-    }, [pathname, latestPathnameRef, onRouteChange]);
-}

package/src/utils/useChangeRoute.ts

@@ -1,21 +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.
- */
-
-import {useRef, useEffect} from 'react';
-import {useLocation} from '@docusaurus/router';
-
-export function useChangeRoute(onRouteChange: () => void): void {
-  const {pathname} = useLocation();
-  const latestPathnameRef = useRef(pathname);
-
-  useEffect(() => {
-    if (pathname !== latestPathnameRef.current) {
-      latestPathnameRef.current = pathname;
-      onRouteChange();
-    }
-  }, [pathname, latestPathnameRef, onRouteChange]);
-}