@docusaurus/theme-common 2.0.0-beta.1decd6f80 → 2.0.0-beta.20

package/src/utils/useAlternatePageUtils.ts

@@ -8,10 +8,32 @@
 import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
 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() {
+/**
+ * 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(): {
+  /**
+   * Everything (pathname, base URL, etc.) is read from the context. Just tell
+   * it which locale to link to and it will give you the alternate link for the
+   * current page.
+   */
+  createUrl: ({
+    /** The locale name to link to. */
+    locale,
+    /**
+     * For hreflang SEO headers, we need it to be fully qualified (full
+     * protocol/domain/path...); but for locale dropdowns, using a pathname is
+     * good enough.
+     */
+    fullyQualified,
+  }: {
+    locale: string;
+    fullyQualified: boolean;
+  }) => string;
+} {
   const {
     siteConfig: {baseUrl, url},
     i18n: {defaultLocale, currentLocale},
@@ -31,14 +53,13 @@ export function useAlternatePageUtils() {
       : `${baseUrlUnlocalized}${locale}/`;
   }
 
-  // TODO support correct alternate url when localized site is deployed on another domain
+  // TODO support correct alternate url when localized site is deployed on
+  // another domain
   function createUrl({
     locale,
     fullyQualified,
   }: {
     locale: string;
-    // For hreflang SEO headers, we need it to be fully qualified (full protocol/domain/path...)
-    // For locale dropdown, using a path is good enough
     fullyQualified: boolean;
   }) {
     return `${fullyQualified ? url : ''}${getLocalizedBaseUrl(

package/src/utils/useLocalPathname.ts

@@ -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 {useLocation} from '@docusaurus/router';
+import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
+
+/**
+ * Get the pathname of current route, without the optional site baseUrl.
+ * - `/docs/myDoc` => `/docs/myDoc`
+ * - `/baseUrl/docs/myDoc` => `/docs/myDoc`
+ */
+export function useLocalPathname(): string {
+  const {
+    siteConfig: {baseUrl},
+  } = useDocusaurusContext();
+  const {pathname} = useLocation();
+  return pathname.replace(baseUrl, '/');
+}

package/src/utils/useLocationChange.ts

@@ -0,0 +1,41 @@
+/**
+ * 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} from 'react';
+import {useLocation} from '@docusaurus/router';
+import type {Location} from 'history';
+import {useDynamicCallback, usePrevious} from './reactUtils';
+
+/**
+ * Fires an effect when the location changes (which includes hash, query, etc.).
+ * Importantly, doesn't fire when there's no previous location: see
+ * https://github.com/facebook/docusaurus/pull/6696
+ */
+export function useLocationChange(
+  onLocationChange: (locationChangeEvent: {
+    location: Location;
+    previousLocation: Location | undefined;
+  }) => void,
+): void {
+  const location = useLocation();
+  const previousLocation = usePrevious(location);
+
+  const onLocationChangeDynamic = useDynamicCallback(onLocationChange);
+
+  useEffect(() => {
+    if (!previousLocation) {
+      return;
+    }
+
+    if (location !== previousLocation) {
+      onLocationChangeDynamic({
+        location,
+        previousLocation,
+      });
+    }
+  }, [onLocationChangeDynamic, location, previousLocation]);
+}

package/src/utils/usePluralForm.ts

@@ -49,36 +49,34 @@ function createLocalePluralForms(locale: string): LocalePluralForms {
   };
 }
 
-// Poor man's PluralSelector implementation, using an english fallback.
-// We want a lightweight, future-proof and good-enough solution.
-// We don't want a perfect and heavy solution.
-//
-// Docusaurus classic theme has only 2 deeply nested labels requiring complex plural rules
-// We don't want to use Intl + PluralRules polyfills + full ICU syntax (react-intl) just for that.
-//
-// Notes:
-// - 2021: 92+% Browsers support Intl.PluralRules, and support will increase in the future
-// - NodeJS >= 13 has full ICU support by default
-// - In case of "mismatch" between SSR and Browser ICU support, React keeps working!
+/**
+ * Poor man's `PluralSelector` implementation, using an English fallback. We
+ * want a lightweight, future-proof and good-enough solution. We don't want a
+ * perfect and heavy solution.
+ *
+ * Docusaurus classic theme has only 2 deeply nested labels requiring complex
+ * plural rules. We don't want to use `Intl` + `PluralRules` polyfills + full
+ * ICU syntax (react-intl) just for that.
+ *
+ * Notes:
+ * - 2021: 92+% Browsers support `Intl.PluralRules`, and support will increase
+ * in the future
+ * - NodeJS >= 13 has full ICU support by default
+ * - In case of "mismatch" between SSR and Browser ICU support, React keeps
+ * working!
+ */
 function useLocalePluralForms(): LocalePluralForms {
   const {
     i18n: {currentLocale},
   } = useDocusaurusContext();
   return useMemo(() => {
-    // @ts-expect-error checking Intl.PluralRules in case browser doesn't have it (e.g Safari 12-)
-    if (Intl.PluralRules) {
-      try {
-        return createLocalePluralForms(currentLocale);
-      } catch (e) {
-        console.error(`Failed to use Intl.PluralRules for locale=${currentLocale}.
-Docusaurus will fallback to a default/fallback (English) Intl.PluralRules implementation.
+    try {
+      return createLocalePluralForms(currentLocale);
+    } catch (err) {
+      console.error(`Failed to use Intl.PluralRules for locale "${currentLocale}".
+Docusaurus will fallback to the default (English) implementation.
+Error: ${(err as Error).message}
 `);
-        return EnglishPluralForms;
-      }
-    } else {
-      console.error(`Intl.PluralRules not available!
-Docusaurus will fallback to a default/fallback (English) Intl.PluralRules implementation.
-        `);
       return EnglishPluralForms;
     }
   }, [currentLocale]);
@@ -93,25 +91,37 @@ function selectPluralMessage(
   const parts = pluralMessages.split(separator);
 
   if (parts.length === 1) {
-    return parts[0];
-  } else {
-    if (parts.length > localePluralForms.pluralForms.length) {
-      console.error(
-        `For locale=${localePluralForms.locale}, a maximum of ${localePluralForms.pluralForms.length} plural forms are expected (${localePluralForms.pluralForms}), but the message contains ${parts.length} plural forms: ${pluralMessages} `,
-      );
-    }
-    const pluralForm = localePluralForms.select(count);
-    const pluralFormIndex = localePluralForms.pluralForms.indexOf(pluralForm);
-    // In case of not enough plural form messages, we take the last one (other) instead of returning undefined
-    return parts[Math.min(pluralFormIndex, parts.length - 1)];
+    return parts[0]!;
+  }
+  if (parts.length > localePluralForms.pluralForms.length) {
+    console.error(
+      `For locale=${localePluralForms.locale}, a maximum of ${localePluralForms.pluralForms.length} plural forms are expected (${localePluralForms.pluralForms}), but the message contains ${parts.length}: ${pluralMessages}`,
+    );
   }
+  const pluralForm = localePluralForms.select(count);
+  const pluralFormIndex = localePluralForms.pluralForms.indexOf(pluralForm);
+  // In case of not enough plural form messages, we take the last one (other)
+  // instead of returning undefined
+  return parts[Math.min(pluralFormIndex, parts.length - 1)]!;
 }
 
-export function usePluralForm() {
+/**
+ * Reads the current locale and returns an interface very similar to
+ * `Intl.PluralRules`.
+ */
+export function usePluralForm(): {
+  /**
+   * Give it a `count` and it will select the relevant message from
+   * `pluralMessages`. `pluralMessages` should be separated by `|`, and in the
+   * order of "zero", "one", "two", "few", "many", "other". The actual selection
+   * is done by `Intl.PluralRules`, which tells us all plurals the locale has
+   * and which plural we should use for `count`.
+   */
+  selectMessage: (count: number, pluralMessages: string) => string;
+} {
   const localePluralForm = useLocalePluralForms();
   return {
-    selectMessage: (count: number, pluralMessages: string): string => {
-      return selectPluralMessage(pluralMessages, count, localePluralForm);
-    },
+    selectMessage: (count: number, pluralMessages: string): string =>
+      selectPluralMessage(pluralMessages, count, localePluralForm),
   };
 }

package/src/utils/useThemeConfig.ts

@@ -4,9 +4,11 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
+
 import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
-import {PrismTheme} from 'prism-react-renderer';
-import {CSSProperties} from 'react';
+import type {PrismTheme} from 'prism-react-renderer';
+import type {DeepPartial} from 'utility-types';
+import type {MagicCommentConfig} from './codeBlockUtils';
 
 export type DocsVersionPersistence = 'localStorage' | 'none';
 
@@ -16,11 +18,13 @@ export type NavbarItem = {
   items?: NavbarItem[];
   label?: string;
   position?: 'left' | 'right';
-};
+} & {[key: string]: unknown};
 
 export type NavbarLogo = {
   src: string;
   srcDark?: string;
+  width?: string | number;
+  height?: string | number;
   href?: string;
   target?: string;
   alt?: string;
@@ -39,12 +43,6 @@ export type ColorModeConfig = {
   defaultMode: 'light' | 'dark';
   disableSwitch: boolean;
   respectPrefersColorScheme: boolean;
-  switchConfig: {
-    darkIcon: string;
-    darkIconStyle: CSSProperties;
-    lightIcon: string;
-    lightIconStyle: CSSProperties;
-  };
 };
 
 export type AnnouncementBarConfig = {
@@ -56,10 +54,11 @@ export type AnnouncementBarConfig = {
 };
 
 export type PrismConfig = {
-  theme?: PrismTheme;
+  theme: PrismTheme;
   darkTheme?: PrismTheme;
   defaultLanguage?: string;
-  additionalLanguages?: string[];
+  additionalLanguages: string[];
+  magicComments: MagicCommentConfig[];
 };
 
 export type FooterLinkItem = {
@@ -68,26 +67,49 @@ export type FooterLinkItem = {
   href?: string;
   html?: string;
   prependBaseUrlToHref?: string;
+} & {[key: string]: unknown};
+
+export type FooterLogo = {
+  alt?: string;
+  src: string;
+  srcDark?: string;
+  width?: string | number;
+  height?: string | number;
+  href?: string;
 };
-export type FooterLinks = {
-  title?: string;
-  items: FooterLinkItem[];
-};
-export type Footer = {
+
+export type FooterBase = {
   style: 'light' | 'dark';
-  logo?: {
-    alt?: string;
-    src?: string;
-    srcDark?: string;
-    href?: string;
-  };
+  logo?: FooterLogo;
   copyright?: string;
-  links: FooterLinks[];
 };
 
+export type MultiColumnFooter = FooterBase & {
+  links: Array<{
+    title: string | null;
+    items: FooterLinkItem[];
+  }>;
+};
+
+export type SimpleFooter = FooterBase & {
+  links: FooterLinkItem[];
+};
+
+export type Footer = MultiColumnFooter | SimpleFooter;
+
+export type TableOfContents = {
+  minHeadingLevel: number;
+  maxHeadingLevel: number;
+};
+
+// Theme config after validation/normalization
 export type ThemeConfig = {
   docs: {
     versionPersistence: DocsVersionPersistence;
+    sidebar: {
+      hideable: boolean;
+      autoCollapseCategories: boolean;
+    };
   };
 
   // TODO we should complete this theme config type over time
@@ -100,10 +122,17 @@ export type ThemeConfig = {
   announcementBar?: AnnouncementBarConfig;
   prism: PrismConfig;
   footer?: Footer;
-  hideableSidebar: boolean;
-  image: string;
+  image?: string;
+  metadata: Array<{[key: string]: string}>;
+  tableOfContents: TableOfContents;
 };
 
+// User-provided theme config, unnormalized
+export type UserThemeConfig = DeepPartial<ThemeConfig>;
+
+/**
+ * A convenient/more semantic way to get theme config from context.
+ */
 export function useThemeConfig(): ThemeConfig {
   return useDocusaurusContext().siteConfig.themeConfig as ThemeConfig;
 }