@docusaurus/theme-common 3.4.0 → 3.5.0

package/src/contexts/docSidebarItemsExpandedState.tsx

@@ -1,55 +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 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;
-}

package/src/contexts/docsPreferredVersion.tsx

@@ -1,251 +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 React, {
-  useContext,
-  useEffect,
-  useMemo,
-  useState,
-  useCallback,
-  type ReactNode,
-} from 'react';
-import {
-  useAllDocsData,
-  useDocsData,
-  type GlobalPluginData,
-  type GlobalVersion,
-} from '@docusaurus/plugin-content-docs/client';
-import {DEFAULT_PLUGIN_ID} from '@docusaurus/constants';
-import {
-  useThemeConfig,
-  type DocsVersionPersistence,
-} from '../utils/useThemeConfig';
-import {isDocsPluginEnabled} from '../utils/docsUtils';
-import {ReactContextError} from '../utils/reactUtils';
-import {createStorageSlot} from '../utils/storageUtils';
-
-const storageKey = (pluginId: string) => `docs-preferred-version-${pluginId}`;
-
-const DocsPreferredVersionStorage = {
-  save: (
-    pluginId: string,
-    persistence: DocsVersionPersistence,
-    versionName: string,
-  ): void => {
-    createStorageSlot(storageKey(pluginId), {persistence}).set(versionName);
-  },
-
-  read: (
-    pluginId: string,
-    persistence: DocsVersionPersistence,
-  ): string | null =>
-    createStorageSlot(storageKey(pluginId), {persistence}).get(),
-
-  clear: (pluginId: string, persistence: DocsVersionPersistence): void => {
-    createStorageSlot(storageKey(pluginId), {persistence}).del();
-  },
-};
-
-type DocsPreferredVersionName = string | null;
-
-/** State for a single docs plugin instance */
-type DocsPreferredVersionPluginState = {
-  preferredVersionName: DocsPreferredVersionName;
-};
-
-/**
- * We need to store the state in storage globally, with one preferred version
- * per docs plugin instance.
- */
-type DocsPreferredVersionState = {
-  [pluginId: string]: DocsPreferredVersionPluginState;
-};
-
-/**
- * Initial state is always null as we can't read local storage from node SSR
- */
-const getInitialState = (pluginIds: string[]): DocsPreferredVersionState =>
-  Object.fromEntries(pluginIds.map((id) => [id, {preferredVersionName: null}]));
-
-/**
- * Read storage for all docs plugins, assigning each doc plugin a preferred
- * version (if found)
- */
-function readStorageState({
-  pluginIds,
-  versionPersistence,
-  allDocsData,
-}: {
-  pluginIds: string[];
-  versionPersistence: DocsVersionPersistence;
-  allDocsData: {[pluginId: string]: GlobalPluginData};
-}): DocsPreferredVersionState {
-  /**
-   * The storage value we read might be stale, and belong to a version that does
-   * not exist in the site anymore. In such case, we remove the storage value to
-   * avoid downstream errors.
-   */
-  function restorePluginState(
-    pluginId: string,
-  ): DocsPreferredVersionPluginState {
-    const preferredVersionNameUnsafe = DocsPreferredVersionStorage.read(
-      pluginId,
-      versionPersistence,
-    );
-    const pluginData = allDocsData[pluginId]!;
-    const versionExists = pluginData.versions.some(
-      (version) => version.name === preferredVersionNameUnsafe,
-    );
-    if (versionExists) {
-      return {preferredVersionName: preferredVersionNameUnsafe};
-    }
-    DocsPreferredVersionStorage.clear(pluginId, versionPersistence);
-    return {preferredVersionName: null};
-  }
-  return Object.fromEntries(
-    pluginIds.map((id) => [id, restorePluginState(id)]),
-  );
-}
-
-function useVersionPersistence(): DocsVersionPersistence {
-  return useThemeConfig().docs.versionPersistence;
-}
-
-type ContextValue = [
-  state: DocsPreferredVersionState,
-  api: {
-    savePreferredVersion: (pluginId: string, versionName: string) => void;
-  },
-];
-
-const Context = React.createContext<ContextValue | null>(null);
-
-function useContextValue(): ContextValue {
-  const allDocsData = useAllDocsData();
-  const versionPersistence = useVersionPersistence();
-  const pluginIds = useMemo(() => Object.keys(allDocsData), [allDocsData]);
-
-  // Initial state is empty, as we can't read browser storage in node/SSR
-  const [state, setState] = useState(() => getInitialState(pluginIds));
-
-  // On mount, we set the state read from browser storage
-  useEffect(() => {
-    setState(readStorageState({allDocsData, versionPersistence, pluginIds}));
-  }, [allDocsData, versionPersistence, pluginIds]);
-
-  // The API that we expose to consumer hooks (memo for constant object)
-  const api = useMemo(() => {
-    function savePreferredVersion(pluginId: string, versionName: string) {
-      DocsPreferredVersionStorage.save(
-        pluginId,
-        versionPersistence,
-        versionName,
-      );
-      setState((s) => ({
-        ...s,
-        [pluginId]: {preferredVersionName: versionName},
-      }));
-    }
-
-    return {
-      savePreferredVersion,
-    };
-  }, [versionPersistence]);
-
-  return [state, api];
-}
-
-function DocsPreferredVersionContextProviderUnsafe({
-  children,
-}: {
-  children: ReactNode;
-}): JSX.Element {
-  const value = useContextValue();
-  return <Context.Provider value={value}>{children}</Context.Provider>;
-}
-
-/**
- * This is a maybe-layer. If the docs plugin is not enabled, this provider is a
- * simple pass-through.
- */
-export function DocsPreferredVersionContextProvider({
-  children,
-}: {
-  children: ReactNode;
-}): JSX.Element {
-  if (isDocsPluginEnabled) {
-    return (
-      <DocsPreferredVersionContextProviderUnsafe>
-        {children}
-      </DocsPreferredVersionContextProviderUnsafe>
-    );
-  }
-  return <>{children}</>;
-}
-
-function useDocsPreferredVersionContext(): ContextValue {
-  const value = useContext(Context);
-  if (!value) {
-    throw new ReactContextError('DocsPreferredVersionContextProvider');
-  }
-  return value;
-}
-
-/**
- * Returns a read-write interface to a plugin's preferred version. The
- * "preferred version" is defined as the last version that the user visited.
- * For example, if a user is using v3, even when v4 is later published, the user
- * would still be browsing v3 docs when she opens the website next time. Note,
- * the `preferredVersion` attribute will always be `null` before mount.
- */
-export function useDocsPreferredVersion(
-  pluginId: string | undefined = DEFAULT_PLUGIN_ID,
-): {
-  preferredVersion: GlobalVersion | null;
-  savePreferredVersionName: (versionName: string) => void;
-} {
-  const docsData = useDocsData(pluginId);
-  const [state, api] = useDocsPreferredVersionContext();
-
-  const {preferredVersionName} = state[pluginId]!;
-
-  const preferredVersion =
-    docsData.versions.find(
-      (version) => version.name === preferredVersionName,
-    ) ?? null;
-
-  const savePreferredVersionName = useCallback(
-    (versionName: string) => {
-      api.savePreferredVersion(pluginId, versionName);
-    },
-    [api, pluginId],
-  );
-
-  return {preferredVersion, savePreferredVersionName};
-}
-
-export function useDocsPreferredVersionByPluginId(): {
-  [pluginId: string]: GlobalVersion | null;
-} {
-  const allDocsData = useAllDocsData();
-  const [state] = useDocsPreferredVersionContext();
-
-  function getPluginIdPreferredVersion(pluginId: string) {
-    const docsData = allDocsData[pluginId]!;
-    const {preferredVersionName} = state[pluginId]!;
-
-    return (
-      docsData.versions.find(
-        (version) => version.name === preferredVersionName,
-      ) ?? null
-    );
-  }
-  const pluginIds = Object.keys(allDocsData);
-  return Object.fromEntries(
-    pluginIds.map((id) => [id, getPluginIdPreferredVersion(id)]),
-  );
-}

package/src/contexts/docsSidebar.tsx

@@ -1,50 +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 React, {useMemo, useContext, type ReactNode} from 'react';
-import {ReactContextError} from '../utils/reactUtils';
-import type {PropSidebar} from '@docusaurus/plugin-content-docs';
-
-// Using a Symbol because null is a valid context value (a doc with no sidebar)
-// Inspired by https://github.com/jamiebuilds/unstated-next/blob/master/src/unstated-next.tsx
-const EmptyContext: unique symbol = Symbol('EmptyContext');
-
-type ContextValue = {name: string; items: PropSidebar};
-
-const Context = React.createContext<ContextValue | null | typeof EmptyContext>(
-  EmptyContext,
-);
-
-/**
- * Provide the current sidebar to your children.
- */
-export function DocsSidebarProvider({
-  children,
-  name,
-  items,
-}: {
-  children: ReactNode;
-  name: string | undefined;
-  items: PropSidebar | undefined;
-}): JSX.Element {
-  const stableValue: ContextValue | null = useMemo(
-    () => (name && items ? {name, items} : null),
-    [name, items],
-  );
-  return <Context.Provider value={stableValue}>{children}</Context.Provider>;
-}
-
-/**
- * Gets the sidebar that's currently displayed, or `null` if there isn't one
- */
-export function useDocsSidebar(): ContextValue | null {
-  const value = useContext(Context);
-  if (value === EmptyContext) {
-    throw new ReactContextError('DocsSidebarProvider');
-  }
-  return value;
-}

package/src/contexts/docsVersion.tsx

@@ -1,36 +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 React, {type ReactNode, useContext} from 'react';
-import {ReactContextError} from '../utils/reactUtils';
-import type {PropVersionMetadata} from '@docusaurus/plugin-content-docs';
-
-const Context = React.createContext<PropVersionMetadata | null>(null);
-
-/**
- * Provide the current version's metadata to your children.
- */
-export function DocsVersionProvider({
-  children,
-  version,
-}: {
-  children: ReactNode;
-  version: PropVersionMetadata | null;
-}): JSX.Element {
-  return <Context.Provider value={version}>{children}</Context.Provider>;
-}
-
-/**
- * Gets the version metadata of the current doc page.
- */
-export function useDocsVersion(): PropVersionMetadata {
-  const version = useContext(Context);
-  if (version === null) {
-    throw new ReactContextError('DocsVersionProvider');
-  }
-  return version;
-}

package/src/utils/blogUtils.ts

@@ -1,32 +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 {useMemo} from 'react';
-import {useLocation} from '@docusaurus/router';
-import {isSamePath} from './routesUtils';
-import type {BlogSidebarItem} from '@docusaurus/plugin-content-blog';
-
-function isVisible(item: BlogSidebarItem, pathname: string): boolean {
-  if (item.unlisted && !isSamePath(item.permalink, pathname)) {
-    return false;
-  }
-  return true;
-}
-
-/**
- * Return the visible blog sidebar items to display.
- * Unlisted items are filtered.
- */
-export function useVisibleBlogSidebarItems(
-  items: BlogSidebarItem[],
-): BlogSidebarItem[] {
-  const {pathname} = useLocation();
-  return useMemo(
-    () => items.filter((item) => isVisible(item, pathname)),
-    [items, pathname],
-  );
-}