@docusaurus/theme-common 2.0.0-beta.15d451942 → 2.0.0-beta.16

package/src/utils/announcementBarUtils.tsx

@@ -0,0 +1,121 @@
+/**
+ * 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,
+  type ReactNode,
+  useContext,
+  createContext,
+} from 'react';
+import useIsBrowser from '@docusaurus/useIsBrowser';
+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 isActive: boolean;
+  readonly close: () => void;
+};
+
+const useAnnouncementBarContextValue = (): AnnouncementBarAPI => {
+  const {announcementBar} = useThemeConfig();
+  const isBrowser = useIsBrowser();
+
+  const [isClosed, setClosed] = useState(() =>
+    isBrowser
+      ? // On client navigation: init with local storage 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
+    // cSpell:ignore annoucement
+    if (viewedId === 'annoucement-bar') {
+      viewedId = 'announcement-bar';
+    }
+
+    const isNewAnnouncement = id !== viewedId;
+
+    IdStorage.set(id);
+
+    if (isNewAnnouncement) {
+      setDismissedInStorage(false);
+    }
+
+    if (isNewAnnouncement || !isDismissedInStorage()) {
+      setClosed(false);
+    }
+  }, [announcementBar]);
+
+  return useMemo(
+    () => ({
+      isActive: !!announcementBar && !isClosed,
+      close: handleClose,
+    }),
+    [announcementBar, isClosed, handleClose],
+  );
+};
+
+const AnnouncementBarContext = createContext<AnnouncementBarAPI | null>(null);
+
+export function AnnouncementBarProvider({
+  children,
+}: {
+  children: ReactNode;
+}): JSX.Element {
+  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/codeBlockUtils.ts

@@ -5,8 +5,159 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-const codeBlockTitleRegex = /title=(["'])(.*?)\1/;
+import rangeParser from 'parse-numeric-range';
+
+const codeBlockTitleRegex = /title=(?<quote>["'])(?<title>.*?)\1/;
+const highlightLinesRangeRegex = /{(?<range>[\d,-]+)}/;
+
+const commentTypes = ['js', 'jsBlock', 'jsx', 'python', 'html'] as const;
+type CommentType = typeof commentTypes[number];
+
+type CommentPattern = {
+  start: string;
+  end: string;
+};
+
+// Supported types of highlight comments
+const commentPatterns: Record<CommentType, CommentPattern> = {
+  js: {
+    start: '\\/\\/',
+    end: '',
+  },
+  jsBlock: {
+    start: '\\/\\*',
+    end: '\\*\\/',
+  },
+  jsx: {
+    start: '\\{\\s*\\/\\*',
+    end: '\\*\\/\\s*\\}',
+  },
+  python: {
+    start: '#',
+    end: '',
+  },
+  html: {
+    start: '<!--',
+    end: '-->',
+  },
+};
+
+const magicCommentDirectives = [
+  'highlight-next-line',
+  'highlight-start',
+  'highlight-end',
+];
+
+const getMagicCommentDirectiveRegex = (
+  languages: readonly CommentType[] = commentTypes,
+) => {
+  // to be more reliable, the opening and closing comment must match
+  const commentPattern = languages
+    .map((lang) => {
+      const {start, end} = commentPatterns[lang];
+      return `(?:${start}\\s*(${magicCommentDirectives.join('|')})\\s*${end})`;
+    })
+    .join('|');
+  // white space is allowed, but otherwise it should be on it's own line
+  return new RegExp(`^\\s*(?:${commentPattern})\\s*$`);
+};
+
+// select comment styles based on language
+const magicCommentDirectiveRegex = (lang: string) => {
+  switch (lang) {
+    case 'js':
+    case 'javascript':
+    case 'ts':
+    case 'typescript':
+      return getMagicCommentDirectiveRegex(['js', 'jsBlock']);
+
+    case 'jsx':
+    case 'tsx':
+      return getMagicCommentDirectiveRegex(['js', 'jsBlock', 'jsx']);
+
+    case 'html':
+      return getMagicCommentDirectiveRegex(['js', 'jsBlock', 'html']);
+
+    case 'python':
+    case 'py':
+      return getMagicCommentDirectiveRegex(['python']);
+
+    default:
+      // all comment types
+      return getMagicCommentDirectiveRegex();
+  }
+};
 
 export function parseCodeBlockTitle(metastring?: string): string {
-  return metastring?.match(codeBlockTitleRegex)?.[2] ?? '';
+  return metastring?.match(codeBlockTitleRegex)?.groups!.title ?? '';
+}
+
+export function parseLanguage(className: string): string | undefined {
+  const languageClassName = className
+    .split(' ')
+    .find((str) => str.startsWith('language-'));
+  return languageClassName?.replace(/language-/, '');
+}
+
+/**
+ * @param metastring The highlight range declared here starts at 1
+ * @returns Note: all line numbers start at 0, not 1
+ */
+export function parseLines(
+  content: string,
+  metastring?: string,
+  language?: string,
+): {
+  highlightLines: number[];
+  code: string;
+} {
+  let code = content.replace(/\n$/, '');
+  // Highlighted lines specified in props: don't parse the content
+  if (metastring && highlightLinesRangeRegex.test(metastring)) {
+    const highlightLinesRange = metastring.match(highlightLinesRangeRegex)!
+      .groups!.range;
+    const highlightLines = rangeParser(highlightLinesRange)
+      .filter((n) => n > 0)
+      .map((n) => n - 1);
+    return {highlightLines, code};
+  }
+  if (language === undefined) {
+    return {highlightLines: [], code};
+  }
+  const directiveRegex = magicCommentDirectiveRegex(language);
+  // go through line by line
+  const lines = code.split('\n');
+  let highlightBlockStart: number;
+  let highlightRange = '';
+  // loop through lines
+  for (let lineNumber = 0; lineNumber < lines.length; ) {
+    const line = lines[lineNumber];
+    const match = line.match(directiveRegex);
+    if (match !== null) {
+      const directive = match.slice(1).find((item) => item !== undefined);
+      switch (directive) {
+        case 'highlight-next-line':
+          highlightRange += `${lineNumber},`;
+          break;
+
+        case 'highlight-start':
+          highlightBlockStart = lineNumber;
+          break;
+
+        case 'highlight-end':
+          highlightRange += `${highlightBlockStart!}-${lineNumber - 1},`;
+          break;
+
+        default:
+          break;
+      }
+      lines.splice(lineNumber, 1);
+    } else {
+      // lines without directives are unchanged
+      lineNumber += 1;
+    }
+  }
+  const highlightLines = rangeParser(highlightRange);
+  code = lines.join('\n');
+  return {highlightLines, code};
 }

package/src/utils/colorModeUtils.tsx

@@ -0,0 +1,156 @@
+/**
+ * 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 {ReactNode} from 'react';
+import React, {
+  useState,
+  useCallback,
+  useEffect,
+  useContext,
+  useMemo,
+} from 'react';
+
+import ExecutionEnvironment from '@docusaurus/ExecutionEnvironment';
+import {createStorageSlot} from './storageUtils';
+import {useThemeConfig} from './useThemeConfig';
+
+type ColorModeContextValue = {
+  readonly isDarkTheme: boolean;
+  readonly setLightTheme: () => void;
+  readonly setDarkTheme: () => void;
+};
+
+const ThemeStorageKey = 'theme';
+const ThemeStorage = createStorageSlot(ThemeStorageKey);
+
+const themes = {
+  light: 'light',
+  dark: 'dark',
+} as const;
+
+type Themes = typeof themes[keyof typeof themes];
+
+// Ensure to always return a valid theme even if input is invalid
+const coerceToTheme = (theme?: string | null): Themes =>
+  theme === themes.dark ? themes.dark : themes.light;
+
+const getInitialTheme = (defaultMode: Themes | undefined): Themes => {
+  if (!ExecutionEnvironment.canUseDOM) {
+    return coerceToTheme(defaultMode);
+  }
+  return coerceToTheme(document.documentElement.getAttribute('data-theme'));
+};
+
+const storeTheme = (newTheme: Themes) => {
+  ThemeStorage.set(coerceToTheme(newTheme));
+};
+
+function useColorModeContextValue(): ColorModeContextValue {
+  const {
+    colorMode: {defaultMode, disableSwitch, respectPrefersColorScheme},
+  } = useThemeConfig();
+  const [theme, setTheme] = useState(getInitialTheme(defaultMode));
+
+  const setLightTheme = useCallback(() => {
+    setTheme(themes.light);
+    storeTheme(themes.light);
+  }, []);
+  const setDarkTheme = useCallback(() => {
+    setTheme(themes.dark);
+    storeTheme(themes.dark);
+  }, []);
+
+  useEffect(() => {
+    document.documentElement.setAttribute('data-theme', coerceToTheme(theme));
+  }, [theme]);
+
+  useEffect(() => {
+    if (disableSwitch) {
+      return undefined;
+    }
+    const onChange = (e: StorageEvent) => {
+      if (e.key !== ThemeStorageKey) {
+        return;
+      }
+      try {
+        const storedTheme = ThemeStorage.get();
+        if (storedTheme !== null) {
+          setTheme(coerceToTheme(storedTheme));
+        }
+      } catch (err) {
+        console.error(err);
+      }
+    };
+    window.addEventListener('storage', onChange);
+    return () => {
+      window.removeEventListener('storage', onChange);
+    };
+  }, [disableSwitch, setTheme]);
+
+  // PCS is coerced to light mode when printing, which causes the color mode to
+  // be reset to dark when exiting print mode, disregarding user settings. When
+  // the listener fires only because of a print/screen switch, we don't change
+  // color mode. See https://github.com/facebook/docusaurus/pull/6490
+  const previousMediaIsPrint = React.useRef(false);
+
+  useEffect(() => {
+    if (disableSwitch && !respectPrefersColorScheme) {
+      return undefined;
+    }
+    const mql = window.matchMedia('(prefers-color-scheme: dark)');
+    const onChange = ({matches}: MediaQueryListEvent) => {
+      if (window.matchMedia('print').matches || previousMediaIsPrint.current) {
+        previousMediaIsPrint.current = window.matchMedia('print').matches;
+        return;
+      }
+      setTheme(matches ? themes.dark : themes.light);
+    };
+    mql.addListener(onChange);
+    return () => {
+      mql.removeListener(onChange);
+    };
+  }, [disableSwitch, respectPrefersColorScheme]);
+
+  return {
+    isDarkTheme: theme === themes.dark,
+    setLightTheme,
+    setDarkTheme,
+  };
+}
+
+const ColorModeContext = React.createContext<ColorModeContextValue | undefined>(
+  undefined,
+);
+
+export function ColorModeProvider({
+  children,
+}: {
+  children: ReactNode;
+}): JSX.Element {
+  const {isDarkTheme, setLightTheme, setDarkTheme} = useColorModeContextValue();
+  const contextValue = useMemo(
+    () => ({isDarkTheme, setLightTheme, setDarkTheme}),
+    [isDarkTheme, setLightTheme, setDarkTheme],
+  );
+  return (
+    <ColorModeContext.Provider value={contextValue}>
+      {children}
+    </ColorModeContext.Provider>
+  );
+}
+
+export function useColorMode(): ColorModeContextValue {
+  const context = useContext<ColorModeContextValue | undefined>(
+    ColorModeContext,
+  );
+  if (context == null) {
+    throw new Error(
+      '"useColorMode()" is used outside of "Layout" component. Please see https://docusaurus.io/docs/api/themes/configuration#use-color-mode.',
+    );
+  }
+  return context;
+}

package/src/utils/docSidebarItemsExpandedState.tsx

@@ -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 React, {type ReactNode, useMemo, useState, useContext} from 'react';
+
+const EmptyContext: unique symbol = Symbol('EmptyContext');
+const Context = React.createContext<
+  DocSidebarItemsExpandedState | typeof EmptyContext
+>(EmptyContext);
+type DocSidebarItemsExpandedState = {
+  expandedItem: number | null;
+  setExpandedItem: (a: number | null) => void;
+};
+
+export function DocSidebarItemsExpandedStateProvider({
+  children,
+}: {
+  children: ReactNode;
+}): JSX.Element {
+  const [expandedItem, setExpandedItem] = useState<number | null>(null);
+  const contextValue = useMemo(
+    () => ({expandedItem, setExpandedItem}),
+    [expandedItem],
+  );
+
+  return <Context.Provider value={contextValue}>{children}</Context.Provider>;
+}
+
+export function useDocSidebarItemsExpandedState(): DocSidebarItemsExpandedState {
+  const contextValue = useContext(Context);
+  if (contextValue === EmptyContext) {
+    throw new Error(
+      'This hook requires usage of <DocSidebarItemsExpandedStateProvider>',
+    );
+  }
+  return contextValue;
+}

package/src/utils/docsPreferredVersion/DocsPreferredVersionProvider.tsx

@@ -4,18 +4,22 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
+
 import React, {
   createContext,
-  ReactNode,
+  type ReactNode,
   useContext,
   useEffect,
   useMemo,
   useState,
 } from 'react';
-import {useThemeConfig, DocsVersionPersistence} from '../useThemeConfig';
+import {useThemeConfig, type DocsVersionPersistence} from '../useThemeConfig';
 import {isDocsPluginEnabled} from '../docsUtils';
 
-import {useAllDocsData} from '@theme/hooks/useDocs';
+import {
+  useAllDocsData,
+  type GlobalPluginData,
+} from '@docusaurus/plugin-content-docs/client';
 
 import DocsPreferredVersionStorage from './DocsPreferredVersionStorage';
 
@@ -34,7 +38,7 @@ type DocsPreferredVersionState = Record<
   DocsPreferredVersionPluginState
 >;
 
-// Initial state is always null as we can't read localstorage from node SSR
+// Initial state is always null as we can't read local storage from node SSR
 function getInitialState(pluginIds: string[]): DocsPreferredVersionState {
   const initialState: DocsPreferredVersionState = {};
   pluginIds.forEach((pluginId) => {
@@ -54,7 +58,7 @@ function readStorageState({
 }: {
   pluginIds: string[];
   versionPersistence: DocsVersionPersistence;
-  allDocsData: any; // TODO find a way to type it :(
+  allDocsData: Record<string, GlobalPluginData>;
 }): DocsPreferredVersionState {
   // The storage value we read might be stale,
   // and belong to a version that does not exist in the site anymore
@@ -68,14 +72,13 @@ function readStorageState({
     );
     const pluginData = allDocsData[pluginId];
     const versionExists = pluginData.versions.some(
-      (version: any) => version.name === preferredVersionNameUnsafe,
+      (version) => version.name === preferredVersionNameUnsafe,
     );
     if (versionExists) {
       return {preferredVersionName: preferredVersionNameUnsafe};
-    } else {
-      DocsPreferredVersionStorage.clear(pluginId, versionPersistence);
-      return {preferredVersionName: null};
     }
+    DocsPreferredVersionStorage.clear(pluginId, versionPersistence);
+    return {preferredVersionName: null};
   }
 
   const initialState: DocsPreferredVersionState = {};
@@ -120,7 +123,7 @@ function useContextValue() {
     return {
       savePreferredVersion,
     };
-  }, [setState]);
+  }, [versionPersistence]);
 
   return [state, api] as const;
 }
@@ -132,7 +135,7 @@ const Context = createContext<DocsPreferredVersionContextValue | null>(null);
 export function DocsPreferredVersionContextProvider({
   children,
 }: {
-  children: ReactNode;
+  children: JSX.Element;
 }): JSX.Element {
   if (isDocsPluginEnabled) {
     return (
@@ -140,9 +143,8 @@ export function DocsPreferredVersionContextProvider({
         {children}
       </DocsPreferredVersionContextProviderUnsafe>
     );
-  } else {
-    return <>{children}</>;
   }
+  return children;
 }
 
 function DocsPreferredVersionContextProviderUnsafe({
@@ -158,7 +160,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/docsPreferredVersion/DocsPreferredVersionStorage.ts

@@ -6,7 +6,7 @@
  */
 
 import {createStorageSlot} from '../storageUtils';
-import {DocsVersionPersistence} from '../useThemeConfig';
+import type {DocsVersionPersistence} from '../useThemeConfig';
 
 const storageKey = (pluginId: string) => `docs-preferred-version-${pluginId}`;
 
@@ -22,9 +22,8 @@ const DocsPreferredVersionStorage = {
   read: (
     pluginId: string,
     persistence: DocsVersionPersistence,
-  ): string | null => {
-    return createStorageSlot(storageKey(pluginId), {persistence}).get();
-  },
+  ): string | null =>
+    createStorageSlot(storageKey(pluginId), {persistence}).get(),
 
   clear: (pluginId: string, persistence: DocsVersionPersistence): void => {
     createStorageSlot(storageKey(pluginId), {persistence}).del();

package/src/utils/docsPreferredVersion/useDocsPreferredVersion.ts

@@ -4,40 +4,47 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
+
 import {useCallback} from 'react';
 import {useDocsPreferredVersionContext} from './DocsPreferredVersionProvider';
-import {useAllDocsData, useDocsData} from '@theme/hooks/useDocs';
+import {
+  useAllDocsData,
+  useDocsData,
+  type GlobalVersion,
+} from '@docusaurus/plugin-content-docs/client';
 
 import {DEFAULT_PLUGIN_ID} from '@docusaurus/constants';
 
-// TODO improve typing
-
 // Note, the preferredVersion attribute will always be null before mount
 export function useDocsPreferredVersion(
   pluginId: string | undefined = DEFAULT_PLUGIN_ID,
-) {
+): {
+  preferredVersion: GlobalVersion | null | undefined;
+  savePreferredVersionName: (versionName: string) => void;
+} {
   const docsData = useDocsData(pluginId);
   const [state, api] = useDocsPreferredVersionContext();
 
   const {preferredVersionName} = state[pluginId];
 
   const preferredVersion = preferredVersionName
-    ? docsData.versions.find(
-        (version: any) => version.name === preferredVersionName,
-      )
+    ? docsData.versions.find((version) => version.name === preferredVersionName)
     : null;
 
   const savePreferredVersionName = useCallback(
     (versionName: string) => {
       api.savePreferredVersion(pluginId, versionName);
     },
-    [api],
+    [api, pluginId],
   );
 
   return {preferredVersion, savePreferredVersionName} as const;
 }
 
-export function useDocsPreferredVersionByPluginId(): Record<string, any> {
+export function useDocsPreferredVersionByPluginId(): Record<
+  string,
+  GlobalVersion | null | undefined
+> {
   const allDocsData = useAllDocsData();
   const [state] = useDocsPreferredVersionContext();
 
@@ -47,17 +54,14 @@ export function useDocsPreferredVersionByPluginId(): Record<string, any> {
 
     return preferredVersionName
       ? docsData.versions.find(
-          (version: any) => version.name === preferredVersionName,
+          (version) => version.name === preferredVersionName,
         )
       : null;
   }
 
   const pluginIds = Object.keys(allDocsData);
 
-  const result: Record<
-    string,
-    any // TODO find a way to type this properly!
-  > = {};
+  const result: Record<string, GlobalVersion | null | undefined> = {};
   pluginIds.forEach((pluginId) => {
     result[pluginId] = getPluginIdPreferredVersion(pluginId);
   });