@azerion/bunosaurus-theme-common 0.0.0-stage → 4.0.0

package/src/contexts/announcementBar.tsx

@@ -0,0 +1,117 @@
+/**
+ * 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,
+  type ReactNode,
+} from 'react';
+import useIsBrowser from '@docusaurus/useIsBrowser';
+import {createStorageSlot} from '../utils/storageUtils';
+import {ReactContextError} from '../utils/reactUtils';
+import {useThemeConfig} from '../utils/useThemeConfig';
+
+// Keep these keys in sync with the inlined script
+// See packages/docusaurus-theme-classic/src/inlineScripts.ts
+const AnnouncementBarDismissStorage = createStorageSlot(
+  'docusaurus.announcement.dismiss',
+);
+const IdStorage = createStorageSlot('docusaurus.announcement.id');
+
+const isDismissedInStorage = () =>
+  AnnouncementBarDismissStorage.get() === 'true';
+const setDismissedInStorage = (bool: boolean) =>
+  AnnouncementBarDismissStorage.set(String(bool));
+
+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 Context = React.createContext<ContextValue | null>(null);
+
+function useContextValue(): ContextValue {
+  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],
+  );
+}
+
+export function AnnouncementBarProvider({
+  children,
+}: {
+  children: ReactNode;
+}): ReactNode {
+  const value = useContextValue();
+  return <Context value={value}>{children}</Context>;
+}
+
+export function useAnnouncementBar(): ContextValue {
+  const api = useContext(Context);
+  if (!api) {
+    throw new ReactContextError('AnnouncementBarProvider');
+  }
+  return api;
+}

package/src/contexts/colorMode.tsx

@@ -0,0 +1,257 @@
+/**
+ * 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,
+  type ReactNode,
+} from 'react';
+import useIsBrowser from '@docusaurus/useIsBrowser';
+import {ReactContextError} from '../utils/reactUtils';
+import {createStorageSlot} from '../utils/storageUtils';
+import {useThemeConfig} from '../utils/useThemeConfig';
+
+// The "effective" color mode
+export type ColorMode = 'light' | 'dark';
+
+// The color mode explicitly chosen by the user
+// null => no choice has been made, or the choice has been reverted to OS value
+type ColorModeChoice = ColorMode | null;
+
+function getSystemColorMode(): ColorMode {
+  return window.matchMedia('(prefers-color-scheme: dark)').matches
+    ? 'dark'
+    : 'light';
+}
+
+function subscribeToMedia(
+  query: string,
+  listener: (event: MediaQueryListEvent) => void,
+): () => void {
+  const mql = window.matchMedia(query);
+  mql.addEventListener('change', listener);
+  return () => mql.removeEventListener('change', listener);
+}
+
+function subscribeToSystemColorModeChange(
+  onChange: (newSystemColorMode: ColorMode) => void,
+): () => void {
+  return subscribeToMedia('(prefers-color-scheme: dark)', () =>
+    onChange(getSystemColorMode()),
+  );
+}
+
+type ContextValue = {
+  /** The effective color mode. */
+  readonly colorMode: ColorMode;
+  /** The explicitly chosen color mode */
+  readonly colorModeChoice: ColorModeChoice;
+  /** Set new color mode. */
+  readonly setColorMode: (colorMode: ColorModeChoice) => void;
+};
+
+const Context = React.createContext<ContextValue | undefined>(undefined);
+
+const ColorModeStorageKey = 'theme';
+const ColorModeStorage = createStorageSlot(ColorModeStorageKey);
+
+// We use data-theme-choice="system", not an absent attribute
+// This is easier to handle for users with CSS
+const SystemAttribute = 'system';
+
+// Ensure to always return a valid colorMode even if input is invalid
+const coerceToColorMode = (colorMode: string | null): ColorMode =>
+  colorMode === 'dark' ? 'dark' : 'light';
+const coerceToColorModeChoice = (colorMode: string | null): ColorModeChoice =>
+  colorMode === null || colorMode === SystemAttribute
+    ? null
+    : coerceToColorMode(colorMode);
+
+const ColorModeAttribute = {
+  get: () => {
+    return coerceToColorMode(
+      document.documentElement.getAttribute('data-theme'),
+    );
+  },
+  set: (colorMode: ColorMode) => {
+    document.documentElement.setAttribute(
+      'data-theme',
+      coerceToColorMode(colorMode),
+    );
+  },
+};
+
+const ColorModeChoiceAttribute = {
+  get: () => {
+    return coerceToColorModeChoice(
+      document.documentElement.getAttribute('data-theme-choice'),
+    );
+  },
+  set: (colorMode: ColorModeChoice) => {
+    document.documentElement.setAttribute(
+      'data-theme-choice',
+      coerceToColorModeChoice(colorMode) ?? SystemAttribute,
+    );
+  },
+};
+
+const persistColorModeChoice = (newColorMode: ColorModeChoice) => {
+  if (newColorMode === null) {
+    ColorModeStorage.del();
+  } else {
+    ColorModeStorage.set(coerceToColorMode(newColorMode));
+  }
+};
+
+// The color mode state is initialized in useEffect on purpose
+// to avoid a React hydration mismatch errors
+// The useColorMode() hook value lags behind on purpose
+// This helps users avoid hydration mismatch errors in their code
+// See also https://github.com/facebook/docusaurus/issues/7986
+function useColorModeState() {
+  const {
+    colorMode: {defaultMode},
+  } = useThemeConfig();
+  const isBrowser = useIsBrowser();
+
+  // Since the provider may unmount/remount on client navigation, we need to
+  // reinitialize the state with the correct values to avoid visual glitches.
+  // See also https://github.com/facebook/docusaurus/issues/11399#issuecomment-3279181314
+  const [colorMode, setColorModeState] = useState<ColorMode>(
+    isBrowser ? ColorModeAttribute.get() : defaultMode,
+  );
+  const [colorModeChoice, setColorModeChoiceState] = useState<ColorModeChoice>(
+    isBrowser ? ColorModeChoiceAttribute.get() : null,
+  );
+
+  useEffect(() => {
+    setColorModeState(ColorModeAttribute.get());
+    setColorModeChoiceState(ColorModeChoiceAttribute.get());
+  }, []);
+
+  return {
+    colorMode,
+    setColorModeState,
+    colorModeChoice,
+    setColorModeChoiceState,
+  } as const;
+}
+
+function useContextValue(): ContextValue {
+  const {
+    colorMode: {defaultMode, disableSwitch, respectPrefersColorScheme},
+  } = useThemeConfig();
+  const {
+    colorMode,
+    setColorModeState,
+    colorModeChoice,
+    setColorModeChoiceState,
+  } = useColorModeState();
+
+  useEffect(() => {
+    // A site is deployed without disableSwitch
+    // => User visits the site and has a persisted value
+    // => Site later enabled disableSwitch
+    // => Clear the previously stored value to apply the site's setting
+    if (disableSwitch) {
+      ColorModeStorage.del();
+    }
+  }, [disableSwitch]);
+
+  const setColorMode = useCallback(
+    (
+      newColorModeChoice: ColorModeChoice,
+      options: {persist?: boolean} = {},
+    ) => {
+      const {persist = true} = options;
+
+      // Reset to system/default color mode
+      if (newColorModeChoice === null) {
+        // Set the effective color
+        const newColorMode = respectPrefersColorScheme
+          ? getSystemColorMode()
+          : defaultMode;
+        ColorModeAttribute.set(newColorMode);
+        setColorModeState(newColorMode);
+        // Set the chosen color
+        ColorModeChoiceAttribute.set(null);
+        setColorModeChoiceState(null);
+      }
+      // Happy case, when an explicit color is provided
+      else {
+        ColorModeAttribute.set(newColorModeChoice);
+        ColorModeChoiceAttribute.set(newColorModeChoice);
+        setColorModeState(newColorModeChoice);
+        setColorModeChoiceState(newColorModeChoice);
+      }
+
+      if (persist) {
+        persistColorModeChoice(newColorModeChoice);
+      }
+    },
+    [
+      setColorModeState,
+      setColorModeChoiceState,
+      respectPrefersColorScheme,
+      defaultMode,
+    ],
+  );
+
+  // Synchronize theme color/choice mode with browser storage
+  useEffect(() => {
+    return ColorModeStorage.listen((e) => {
+      setColorMode(coerceToColorModeChoice(e.newValue));
+    });
+  }, [setColorMode]);
+
+  // Synchronize theme color with system color
+  useEffect(() => {
+    if (colorModeChoice !== null || !respectPrefersColorScheme) {
+      return undefined;
+    }
+    return subscribeToSystemColorModeChange((newSystemColorMode) => {
+      // Note: we don't use "setColorMode" on purpose
+      // The system changes should never be considered an explicit theme choice
+      // They only affect the "effective" color, and should never be persisted
+      // Note: this listener also fire when printing, see https://github.com/facebook/docusaurus/pull/6490
+      setColorModeState(newSystemColorMode);
+      ColorModeAttribute.set(newSystemColorMode);
+    });
+  }, [respectPrefersColorScheme, colorModeChoice, setColorModeState]);
+
+  return useMemo(
+    () => ({
+      colorMode,
+      colorModeChoice,
+      setColorMode,
+    }),
+    [colorMode, colorModeChoice, setColorMode],
+  );
+}
+
+export function ColorModeProvider({
+  children,
+}: {
+  children: ReactNode;
+}): ReactNode {
+  const value = useContextValue();
+  return <Context value={value}>{children}</Context>;
+}
+
+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/navbarMobileSidebar.tsx

@@ -0,0 +1,119 @@
+/**
+ * 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, {
+  useCallback,
+  useEffect,
+  useState,
+  useMemo,
+  type ReactNode,
+} from 'react';
+import {useNavbarSecondaryMenuContent} from './navbarSecondaryMenu/content';
+import {useWindowSize} from '../hooks/useWindowSize';
+import {useHistoryPopHandler} from '../utils/historyUtils';
+import {useThemeConfig} from '../utils/useThemeConfig';
+import {ReactContextError} from '../utils/reactUtils';
+
+type ContextValue = {
+  /**
+   * Mobile sidebar should be disabled in case it's empty, i.e. no secondary
+   * menu + no navbar items). If disabled, the toggle button should not be
+   * displayed at all.
+   */
+  disabled: boolean;
+  /**
+   * Signals whether the actual sidebar should be displayed (contrary to
+   * `disabled` which is about the toggle button). Sidebar should not visible
+   * until user interaction to avoid SSR rendering.
+   */
+  shouldRender: boolean;
+  /** The displayed state. Can be toggled with the `toggle` callback. */
+  shown: boolean;
+  /** Toggle the `shown` attribute. */
+  toggle: () => void;
+};
+
+const Context = React.createContext<ContextValue | undefined>(undefined);
+
+function useIsNavbarMobileSidebarDisabled() {
+  const secondaryMenuContent = useNavbarSecondaryMenuContent();
+  const {items} = useThemeConfig().navbar;
+  return items.length === 0 && !secondaryMenuContent.component;
+}
+
+function useContextValue(): ContextValue {
+  const disabled = useIsNavbarMobileSidebarDisabled();
+  const windowSize = useWindowSize();
+
+  const shouldRender = !disabled && windowSize === 'mobile';
+
+  const [shown, setShown] = useState(false);
+
+  const toggle = useCallback(() => {
+    setShown((s) => !s);
+  }, []);
+
+  useEffect(() => {
+    if (windowSize === 'desktop') {
+      setShown(false);
+    }
+  }, [windowSize]);
+
+  return useMemo(
+    () => ({disabled, shouldRender, toggle, shown}),
+    [disabled, shouldRender, toggle, shown],
+  );
+}
+
+// A component hook wrapper enables conditional rendering
+// See reason here: https://github.com/facebook/docusaurus/issues/10988
+function OnHistoryPop({
+  handler,
+}: {
+  handler: Parameters<typeof useHistoryPopHandler>[0];
+}) {
+  useHistoryPopHandler(handler);
+  return null;
+}
+
+export function NavbarMobileSidebarProvider({
+  children,
+}: {
+  children: ReactNode;
+}): ReactNode {
+  const value = useContextValue();
+  return (
+    <>
+      {
+        // Close mobile sidebar on navigation pop
+        // Most likely firing when using the Android back button (but not only)
+        // Important: we can only have a single history blocker at a time
+        // That's why this needs to be rendered conditionally
+        // See bug report https://github.com/facebook/docusaurus/issues/10988
+        value.shown && (
+          <OnHistoryPop
+            handler={() => {
+              value.toggle();
+              // Prevent pop navigation; seems desirable enough
+              // See https://github.com/facebook/docusaurus/pull/5462#issuecomment-911699846
+              return false;
+            }}
+          />
+        )
+      }
+      <Context value={value}>{children}</Context>
+    </>
+  );
+}
+
+export function useNavbarMobileSidebar(): ContextValue {
+  const context = React.useContext(Context);
+  if (context === undefined) {
+    throw new ReactContextError('NavbarMobileSidebarProvider');
+  }
+  return context;
+}

package/src/contexts/navbarSecondaryMenu/content.tsx

@@ -0,0 +1,100 @@
+/**
+ * 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,
+  useContext,
+  useEffect,
+  type ReactNode,
+  type ComponentType,
+} from 'react';
+import {ReactContextError, useShallowMemoObject} from '../../utils/reactUtils';
+
+// This context represents a "global layout store". A component (usually a
+// layout component) can request filling this store through
+// `NavbarSecondaryMenuFiller`. It doesn't actually control rendering by itself,
+// and this context should be considered internal implementation. The user-
+// facing value comes from `display.tsx`, which takes the `component` and
+// `props` stored here and renders the actual element.
+
+export type NavbarSecondaryMenuComponent<Props> = ComponentType<Props>;
+
+/** @internal */
+export type Content =
+  | {
+      component: NavbarSecondaryMenuComponent<object>;
+      props: object;
+    }
+  | {component: null; props: null};
+
+type ContextValue = [
+  content: Content,
+  setContent: React.Dispatch<React.SetStateAction<Content>>,
+];
+
+const Context = React.createContext<ContextValue | null>(null);
+
+/** @internal */
+export function NavbarSecondaryMenuContentProvider({
+  children,
+}: {
+  children: ReactNode;
+}): ReactNode {
+  const value = useState({component: null, props: null});
+  return (
+    // @ts-expect-error: this context is hard to type
+    <Context value={value}>{children}</Context>
+  );
+}
+
+/** @internal */
+export function useNavbarSecondaryMenuContent(): Content {
+  const value = useContext(Context);
+  if (!value) {
+    throw new ReactContextError('NavbarSecondaryMenuContentProvider');
+  }
+  return value[0];
+}
+
+/**
+ * This component renders nothing by itself, but it fills the placeholder in the
+ * generic secondary menu layout. This reduces coupling between the main layout
+ * and the specific page.
+ *
+ * This kind of feature is often called portal/teleport/gateway/outlet...
+ * Various unmaintained React libs exist. Most up-to-date one:
+ * https://github.com/gregberge/react-teleporter
+ * Not sure any of those is safe regarding concurrent mode.
+ */
+export function NavbarSecondaryMenuFiller<P extends object>({
+  component,
+  props,
+}: {
+  component: NavbarSecondaryMenuComponent<P>;
+  props: P;
+}): ReactNode {
+  const context = useContext(Context);
+  if (!context) {
+    throw new ReactContextError('NavbarSecondaryMenuContentProvider');
+  }
+  const [, setContent] = context;
+
+  // To avoid useless context re-renders, props are memoized shallowly
+  const memoizedProps = useShallowMemoObject(props);
+
+  useEffect(() => {
+    // @ts-expect-error: this context is hard to type
+    setContent({component, props: memoizedProps});
+  }, [setContent, component, memoizedProps]);
+
+  useEffect(
+    () => () => setContent({component: null, props: null}),
+    [setContent],
+  );
+
+  return null;
+}

package/src/contexts/navbarSecondaryMenu/display.tsx

@@ -0,0 +1,102 @@
+/**
+ * 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,
+  useContext,
+  useEffect,
+  useMemo,
+  useCallback,
+  type ReactNode,
+} from 'react';
+import {ReactContextError, usePrevious} from '../../utils/reactUtils';
+import {useNavbarMobileSidebar} from '../navbarMobileSidebar';
+import {useNavbarSecondaryMenuContent, type Content} from './content';
+
+type ContextValue = [
+  shown: boolean,
+  setShown: React.Dispatch<React.SetStateAction<boolean>>,
+];
+
+const Context = React.createContext<ContextValue | null>(null);
+
+function useContextValue(): ContextValue {
+  const mobileSidebar = useNavbarMobileSidebar();
+  const content = useNavbarSecondaryMenuContent();
+
+  const [shown, setShown] = useState(false);
+
+  const hasContent = content.component !== null;
+  const previousHasContent = usePrevious(hasContent);
+
+  // When content is become available for the first time (set in useEffect)
+  // we set this content to be shown!
+  useEffect(() => {
+    const contentBecameAvailable = hasContent && !previousHasContent;
+    if (contentBecameAvailable) {
+      setShown(true);
+    }
+  }, [hasContent, previousHasContent]);
+
+  // On sidebar close, secondary menu is set to be shown on next re-opening
+  // (if any secondary menu content available)
+  useEffect(() => {
+    if (!hasContent) {
+      setShown(false);
+      return;
+    }
+    if (!mobileSidebar.shown) {
+      setShown(true);
+    }
+  }, [mobileSidebar.shown, hasContent]);
+
+  return useMemo(() => [shown, setShown], [shown]);
+}
+
+/** @internal */
+export function NavbarSecondaryMenuDisplayProvider({
+  children,
+}: {
+  children: ReactNode;
+}): ReactNode {
+  const value = useContextValue();
+  return <Context value={value}>{children}</Context>;
+}
+
+function renderElement(content: Content): ReactNode {
+  if (content.component) {
+    const Comp = content.component;
+    return <Comp {...content.props} />;
+  }
+  return undefined;
+}
+
+/** Wires the logic for rendering the mobile navbar secondary menu. */
+export function useNavbarSecondaryMenu(): {
+  /** Whether secondary menu is displayed. */
+  shown: boolean;
+  /**
+   * Hide the secondary menu; fired either when hiding the entire sidebar, or
+   * when going back to the primary menu.
+   */
+  hide: () => void;
+  /** The content returned from the current secondary menu filler. */
+  content: ReactNode;
+} {
+  const value = useContext(Context);
+  if (!value) {
+    throw new ReactContextError('NavbarSecondaryMenuDisplayProvider');
+  }
+  const [shown, setShown] = value;
+  const hide = useCallback(() => setShown(false), [setShown]);
+  const content = useNavbarSecondaryMenuContent();
+
+  return useMemo(
+    () => ({shown, hide, content: renderElement(content)}),
+    [hide, content, shown],
+  );
+}