@docusaurus/theme-common 2.0.0-beta.17 → 2.0.0-beta.18

package/lib/utils/useThemeConfig.d.ts

@@ -12,7 +12,9 @@ export declare type NavbarItem = {
     items?: NavbarItem[];
     label?: string;
     position?: 'left' | 'right';
-} & Record<string, unknown>;
+} & {
+    [key: string]: unknown;
+};
 export declare type NavbarLogo = {
     src: string;
     srcDark?: string;
@@ -45,7 +47,7 @@ export declare type PrismConfig = {
     theme?: PrismTheme;
     darkTheme?: PrismTheme;
     defaultLanguage?: string;
-    additionalLanguages?: string[];
+    additionalLanguages: string[];
 };
 export declare type FooterLinkItem = {
     label?: string;
@@ -53,17 +55,20 @@ export declare type FooterLinkItem = {
     href?: string;
     html?: string;
     prependBaseUrlToHref?: string;
+} & {
+    [key: string]: unknown;
+};
+export declare type FooterLogo = {
+    alt?: string;
+    src: string;
+    srcDark?: string;
+    width?: string | number;
+    height?: string | number;
+    href?: string;
 };
 export declare type FooterBase = {
     style: 'light' | 'dark';
-    logo?: {
-        alt?: string;
-        src?: string;
-        srcDark?: string;
-        width?: string | number;
-        height?: string | number;
-        href?: string;
-    };
+    logo?: FooterLogo;
     copyright?: string;
 };
 export declare type MultiColumnFooter = FooterBase & {
@@ -92,10 +97,15 @@ export declare type ThemeConfig = {
     hideableSidebar: boolean;
     autoCollapseSidebarCategories: boolean;
     image?: string;
-    metadata: Array<Record<string, string>>;
+    metadata: Array<{
+        [key: string]: string;
+    }>;
     sidebarCollapsible: boolean;
     tableOfContents: TableOfContents;
 };
 export declare type UserThemeConfig = DeepPartial<ThemeConfig>;
+/**
+ * A convenient/more semantic way to get theme config from context.
+ */
 export declare function useThemeConfig(): ThemeConfig;
 //# sourceMappingURL=useThemeConfig.d.ts.map

package/lib/utils/useThemeConfig.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useThemeConfig.d.ts","sourceRoot":"","sources":["../../src/utils/useThemeConfig.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"useThemeConfig.d.ts","sourceRoot":"","sources":["../../src/utils/useThemeConfig.ts"],"names":[],"mappings":"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"}

package/lib/utils/useThemeConfig.js

@@ -5,6 +5,9 @@
  * LICENSE file in the root directory of this source tree.
  */
 import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
+/**
+ * A convenient/more semantic way to get theme config from context.
+ */
 export function useThemeConfig() {
     return useDocusaurusContext().siteConfig.themeConfig;
 }

package/lib/utils/useThemeConfig.js.map

@@ -1 +1 @@
-{"version":3,"file":"useThemeConfig.js","sourceRoot":"","sources":["../../src/utils/useThemeConfig.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,oBAAoB,MAAM,kCAAkC,CAAC;AAwHpE,MAAM,UAAU,cAAc;IAC5B,OAAO,oBAAoB,EAAE,CAAC,UAAU,CAAC,WAA0B,CAAC;AACtE,CAAC"}
+{"version":3,"file":"useThemeConfig.js","sourceRoot":"","sources":["../../src/utils/useThemeConfig.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,oBAAoB,MAAM,kCAAkC,CAAC;AA0HpE;;GAEG;AACH,MAAM,UAAU,cAAc;IAC5B,OAAO,oBAAoB,EAAE,CAAC,UAAU,CAAC,WAA0B,CAAC;AACtE,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docusaurus/theme-common",
-  "version": "2.0.0-beta.17",
+  "version": "2.0.0-beta.18",
   "description": "Common code for Docusaurus themes.",
   "main": "./lib/index.js",
   "types": "./lib/index.d.ts",
@@ -18,10 +18,10 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@docusaurus/module-type-aliases": "2.0.0-beta.17",
-    "@docusaurus/plugin-content-blog": "2.0.0-beta.17",
-    "@docusaurus/plugin-content-docs": "2.0.0-beta.17",
-    "@docusaurus/plugin-content-pages": "2.0.0-beta.17",
+    "@docusaurus/module-type-aliases": "2.0.0-beta.18",
+    "@docusaurus/plugin-content-blog": "2.0.0-beta.18",
+    "@docusaurus/plugin-content-docs": "2.0.0-beta.18",
+    "@docusaurus/plugin-content-pages": "2.0.0-beta.18",
     "clsx": "^1.1.1",
     "parse-numeric-range": "^1.3.0",
     "prism-react-renderer": "^1.3.1",
@@ -29,9 +29,8 @@
     "utility-types": "^3.10.0"
   },
   "devDependencies": {
-    "@docusaurus/core": "2.0.0-beta.17",
-    "@docusaurus/types": "2.0.0-beta.17",
-    "@testing-library/react-hooks": "^7.0.2",
+    "@docusaurus/core": "2.0.0-beta.18",
+    "@docusaurus/types": "2.0.0-beta.18",
     "fs-extra": "^10.0.1",
     "lodash": "^4.17.21"
   },
@@ -42,5 +41,5 @@
   "engines": {
     "node": ">=14"
   },
-  "gitHead": "0032c0b0480083227af2e1b4da2d3ee6ce992403"
+  "gitHead": "1a945d06993d53376e61bed2c942799fe07dc336"
 }

package/src/components/Collapsible/index.tsx

@@ -11,29 +11,28 @@ import React, {
   useEffect,
   useRef,
   useCallback,
+  useLayoutEffect,
   type RefObject,
   type Dispatch,
   type SetStateAction,
   type ReactNode,
-  useLayoutEffect,
 } from 'react';
 
 const DefaultAnimationEasing = 'ease-in-out';
 
-export type UseCollapsibleConfig = {
+/**
+ * This hook is a very thin wrapper around a `useState`.
+ */
+export function useCollapsible({
+  initialState,
+}: {
+  /** The initial state. Will be non-collapsed by default. */
   initialState: boolean | (() => boolean);
-};
-
-export type UseCollapsibleReturns = {
+}): {
   collapsed: boolean;
   setCollapsed: Dispatch<SetStateAction<boolean>>;
   toggleCollapsed: () => void;
-};
-
-// This hook just define the state
-export function useCollapsible({
-  initialState,
-}: UseCollapsibleConfig): UseCollapsibleReturns {
+} {
   const [collapsed, setCollapsed] = useState(initialState ?? false);
 
   const toggleCollapsed = useCallback(() => {
@@ -152,8 +151,10 @@ type CollapsibleElementType = React.ElementType<
   Pick<React.HTMLAttributes<unknown>, 'className' | 'onTransitionEnd' | 'style'>
 >;
 
-// Prevent hydration layout shift before animations are handled imperatively
-// with JS
+/**
+ * Prevent hydration layout shift before animations are handled imperatively
+ * with JS
+ */
 function getSSRStyle(collapsed: boolean) {
   if (ExecutionEnvironment.canUseDOM) {
     return undefined;
@@ -162,16 +163,27 @@ function getSSRStyle(collapsed: boolean) {
 }
 
 type CollapsibleBaseProps = {
+  /** The actual DOM element to be used in the markup. */
   as?: CollapsibleElementType;
+  /** Initial collapsed state. */
   collapsed: boolean;
   children: ReactNode;
+  /** Configuration of animation, like `duration` and `easing` */
   animation?: CollapsibleAnimationConfig;
+  /**
+   * A callback fired when the collapse transition animation ends. Receives
+   * the **new** collapsed state: e.g. when
+   * expanding, `collapsed` will be `false`. You can use this for some "cleanup"
+   * like applying new styles when the container is fully expanded.
+   */
   onCollapseTransitionEnd?: (collapsed: boolean) => void;
+  /** Class name for the underlying DOM element. */
   className?: string;
-
-  // This is mostly useful for details/summary component where ssrStyle is not
-  // needed (as details are hidden natively) and can mess up with the default
-  // native behavior of the browser when JS fails to load or is disabled
+  /**
+   * This is mostly useful for details/summary component where ssrStyle is not
+   * needed (as details are hidden natively) and can mess up with the browser's
+   * native behavior when JS fails to load or is disabled
+   */
   disableSSRStyle?: boolean;
 };
 
@@ -233,14 +245,20 @@ function CollapsibleLazy({collapsed, ...props}: CollapsibleBaseProps) {
 }
 
 type CollapsibleProps = CollapsibleBaseProps & {
-  // Lazy allows to delay the rendering when collapsed => it will render
-  // children only after hydration, on first expansion
-  // Required prop: it forces to think if content should be server-rendered
-  // or not! This has perf impact on the SSR output and html file sizes
-  // See https://github.com/facebook/docusaurus/issues/4753
+  /**
+   * Delay rendering of the content till first expansion. Marked as required to
+   * force us to think if content should be server-rendered or not. This has
+   * perf impact since it reduces html file sizes, but could undermine SEO.
+   * @see https://github.com/facebook/docusaurus/issues/4753
+   */
   lazy: boolean;
 };
 
+/**
+ * A headless component providing smooth and uniform collapsing behavior. The
+ * component will be invisible (zero height) when collapsed. Doesn't provide
+ * interactivity by itself: collapse state is toggled through props.
+ */
 export function Collapsible({lazy, ...props}: CollapsibleProps): JSX.Element {
   const Comp = lazy ? CollapsibleLazy : CollapsibleBase;
   return <Comp {...props} />;

package/src/components/Details/index.tsx

@@ -6,10 +6,10 @@
  */
 
 import React, {
-  type ComponentProps,
-  type ReactElement,
   useRef,
   useState,
+  type ComponentProps,
+  type ReactElement,
 } from 'react';
 import useIsBrowser from '@docusaurus/useIsBrowser';
 import clsx from 'clsx';
@@ -31,10 +31,15 @@ function hasParent(node: HTMLElement | null, parent: HTMLElement): boolean {
 }
 
 export type DetailsProps = {
+  /** Summary is provided as props, including the wrapping `<summary>` tag */
   summary?: ReactElement;
 } & ComponentProps<'details'>;
 
-export default function Details({
+/**
+ * A mostly un-styled `<details>` element with smooth collapsing. Provides some
+ * very lightweight styles, but you should bring your UI.
+ */
+export function Details({
   summary,
   children,
   ...props
@@ -45,8 +50,8 @@ export default function Details({
   const {collapsed, setCollapsed} = useCollapsible({
     initialState: !props.open,
   });
-  // Use a separate prop because it must be set only after animation completes
-  // Otherwise close anim won't work
+  // Use a separate state for the actual details prop, because it must be set
+  // only after animation completes, otherwise close animations won't work
   const [open, setOpen] = useState(props.open);
 
   return (
@@ -58,7 +63,7 @@ export default function Details({
       data-collapsed={collapsed}
       className={clsx(
         styles.details,
-        {[styles.isBrowser]: isBrowser},
+        isBrowser && styles.isBrowser,
         props.className,
       )}
       onMouseDown={(e) => {

package/src/{utils/announcementBarUtils.tsx → contexts/announcementBar.tsx}

@@ -10,14 +10,13 @@ import React, {
   useEffect,
   useCallback,
   useMemo,
-  type ReactNode,
   useContext,
-  createContext,
+  type ReactNode,
 } from 'react';
 import useIsBrowser from '@docusaurus/useIsBrowser';
-import {createStorageSlot} from './storageUtils';
-import {ReactContextError} from './reactUtils';
-import {useThemeConfig} from './useThemeConfig';
+import {createStorageSlot} from '../utils/storageUtils';
+import {ReactContextError} from '../utils/reactUtils';
+import {useThemeConfig} from '../utils/useThemeConfig';
 
 export const AnnouncementBarDismissStorageKey =
   'docusaurus.announcement.dismiss';
@@ -33,12 +32,18 @@ const isDismissedInStorage = () =>
 const setDismissedInStorage = (bool: boolean) =>
   AnnouncementBarDismissStorage.set(String(bool));
 
-type AnnouncementBarAPI = {
+type ContextValue = {
+  /** Whether the announcement bar should be displayed. */
   readonly isActive: boolean;
+  /**
+   * Callback fired when the user closes the announcement. Will be saved.
+   */
   readonly close: () => void;
 };
 
-const useAnnouncementBarContextValue = (): AnnouncementBarAPI => {
+const Context = React.createContext<ContextValue | null>(null);
+
+function useContextValue(): ContextValue {
   const {announcementBar} = useThemeConfig();
   const isBrowser = useIsBrowser();
 
@@ -94,25 +99,19 @@ const useAnnouncementBarContextValue = (): AnnouncementBarAPI => {
     }),
     [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>
-  );
+  const value = useContextValue();
+  return <Context.Provider value={value}>{children}</Context.Provider>;
 }
 
-export function useAnnouncementBar(): AnnouncementBarAPI {
-  const api = useContext(AnnouncementBarContext);
+export function useAnnouncementBar(): ContextValue {
+  const api = useContext(Context);
   if (!api) {
     throw new ReactContextError('AnnouncementBarProvider');
   }

package/src/contexts/colorMode.tsx

@@ -0,0 +1,176 @@
+/**
+ * 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,
+  useCallback,
+  useEffect,
+  useContext,
+  useMemo,
+  useRef,
+  type ReactNode,
+} from 'react';
+import {ReactContextError} from '../utils/reactUtils';
+
+import ExecutionEnvironment from '@docusaurus/ExecutionEnvironment';
+import {createStorageSlot} from '../utils/storageUtils';
+import {useThemeConfig} from '../utils/useThemeConfig';
+
+type ContextValue = {
+  /** Current color mode. */
+  readonly colorMode: ColorMode;
+  /** Set new color mode. */
+  readonly setColorMode: (colorMode: ColorMode) => void;
+
+  // TODO legacy APIs kept for retro-compatibility: deprecate them
+  readonly isDarkTheme: boolean;
+  readonly setLightTheme: () => void;
+  readonly setDarkTheme: () => void;
+};
+
+const Context = React.createContext<ContextValue | undefined>(undefined);
+
+const ColorModeStorageKey = 'theme';
+const ColorModeStorage = createStorageSlot(ColorModeStorageKey);
+
+const ColorModes = {
+  light: 'light',
+  dark: 'dark',
+} as const;
+
+export type ColorMode = typeof ColorModes[keyof typeof ColorModes];
+
+// Ensure to always return a valid colorMode even if input is invalid
+const coerceToColorMode = (colorMode?: string | null): ColorMode =>
+  colorMode === ColorModes.dark ? ColorModes.dark : ColorModes.light;
+
+const getInitialColorMode = (defaultMode: ColorMode | undefined): ColorMode =>
+  ExecutionEnvironment.canUseDOM
+    ? coerceToColorMode(document.documentElement.getAttribute('data-theme'))
+    : coerceToColorMode(defaultMode);
+
+const storeColorMode = (newColorMode: ColorMode) => {
+  ColorModeStorage.set(coerceToColorMode(newColorMode));
+};
+
+function useContextValue(): ContextValue {
+  const {
+    colorMode: {defaultMode, disableSwitch, respectPrefersColorScheme},
+  } = useThemeConfig();
+  const [colorMode, setColorModeState] = useState(
+    getInitialColorMode(defaultMode),
+  );
+
+  const setColorMode = useCallback((newColorMode: ColorMode) => {
+    setColorModeState(newColorMode);
+    storeColorMode(newColorMode);
+  }, []);
+
+  useEffect(() => {
+    document.documentElement.setAttribute(
+      'data-theme',
+      coerceToColorMode(colorMode),
+    );
+  }, [colorMode]);
+
+  useEffect(() => {
+    if (disableSwitch) {
+      return undefined;
+    }
+    const onChange = (e: StorageEvent) => {
+      if (e.key !== ColorModeStorageKey) {
+        return;
+      }
+      try {
+        const storedColorMode = ColorModeStorage.get();
+        if (storedColorMode !== null) {
+          setColorMode(coerceToColorMode(storedColorMode));
+        }
+      } catch (err) {
+        console.error(err);
+      }
+    };
+    window.addEventListener('storage', onChange);
+    return () => window.removeEventListener('storage', onChange);
+  }, [disableSwitch, setColorMode]);
+
+  // 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 = 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;
+      }
+      setColorMode(matches ? ColorModes.dark : ColorModes.light);
+    };
+    mql.addListener(onChange);
+    return () => mql.removeListener(onChange);
+  }, [setColorMode, disableSwitch, respectPrefersColorScheme]);
+
+  return useMemo(
+    () => ({
+      colorMode,
+      setColorMode,
+      get isDarkTheme() {
+        if (process.env.NODE_ENV === 'development') {
+          console.error(
+            '`useColorMode().isDarkTheme` is deprecated. Please use `useColorMode().colorMode === "dark"` instead.',
+          );
+        }
+        return colorMode === ColorModes.dark;
+      },
+      setLightTheme() {
+        if (process.env.NODE_ENV === 'development') {
+          console.error(
+            '`useColorMode().setLightTheme` is deprecated. Please use `useColorMode().setColorMode("light")` instead.',
+          );
+        }
+        setColorMode(ColorModes.light);
+        storeColorMode(ColorModes.light);
+      },
+      setDarkTheme() {
+        if (process.env.NODE_ENV === 'development') {
+          console.error(
+            '`useColorMode().setDarkTheme` is deprecated. Please use `useColorMode().setColorMode("dark")` instead.',
+          );
+        }
+        setColorMode(ColorModes.dark);
+        storeColorMode(ColorModes.dark);
+      },
+    }),
+    [colorMode, setColorMode],
+  );
+}
+
+export function ColorModeProvider({
+  children,
+}: {
+  children: ReactNode;
+}): JSX.Element {
+  const value = useContextValue();
+  return <Context.Provider value={value}>{children}</Context.Provider>;
+}
+
+export function useColorMode(): ContextValue {
+  const context = useContext(Context);
+  if (context == null) {
+    throw new ReactContextError(
+      'ColorModeProvider',
+      'Please see https://docusaurus.io/docs/api/themes/configuration#use-color-mode.',
+    );
+  }
+  return context;
+}

package/src/contexts/docSidebarItemsExpandedState.tsx

@@ -0,0 +1,55 @@
+/**
+ * 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';
+import {ReactContextError} from '../utils/reactUtils';
+
+type ContextValue = {
+  /**
+   * The item that the user last opened, `null` when there's none open. On
+   * initial render, it will always be `null`, which doesn't necessarily mean
+   * there's no category open (can have 0, 1, or many being initially open).
+   */
+  expandedItem: number | null;
+  /**
+   * Set the currently expanded item, when the user opens one. Set the value to
+   * `null` when the user closes an open category.
+   */
+  setExpandedItem: (a: number | null) => void;
+};
+
+const EmptyContext: unique symbol = Symbol('EmptyContext');
+const Context = React.createContext<ContextValue | typeof EmptyContext>(
+  EmptyContext,
+);
+
+/**
+ * Should be used to wrap one sidebar category level. This provider syncs the
+ * expanded states of all sibling categories, and categories can choose to
+ * collapse itself if another one is expanded.
+ */
+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(): ContextValue {
+  const value = useContext(Context);
+  if (value === EmptyContext) {
+    throw new ReactContextError('DocSidebarItemsExpandedStateProvider');
+  }
+  return value;
+}