@docusaurus/plugin-content-docs 3.4.0 → 3.5.0

package/src/client/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 '@docusaurus/theme-common/internal';
+
+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/client/docsClientUtils.ts

@@ -63,14 +63,23 @@ export function getActiveVersion(
   data: GlobalPluginData,
   pathname: string,
 ): GlobalVersion | undefined {
-  const lastVersion = getLatestVersion(data);
-  // Last version is a route like /docs/*,
-  // we need to match it last or it would match /docs/version-1.0/* as well
-  const orderedVersionsMetadata = [
-    ...data.versions.filter((version) => version !== lastVersion),
-    lastVersion,
-  ];
-  return orderedVersionsMetadata.find(
+  // Sort paths so that a match-all version like /docs/* is matched last
+  // Otherwise /docs/* would match /docs/1.0.0/* routes
+  // This is simplified but similar to the core sortRoutes() logic
+  const sortedVersions = [...data.versions].sort((a, b) => {
+    if (a.path === b.path) {
+      return 0;
+    }
+    if (a.path.includes(b.path)) {
+      return -1;
+    }
+    if (b.path.includes(a.path)) {
+      return 1;
+    }
+    return 0;
+  });
+
+  return sortedVersions.find(
     (version) =>
       !!matchPath(pathname, {
         path: version.path,

package/src/client/docsPreferredVersion.tsx

@@ -0,0 +1,248 @@
+/**
+ * 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 ThemeConfig} from '@docusaurus/theme-common';
+import {
+  ReactContextError,
+  createStorageSlot,
+} from '@docusaurus/theme-common/internal';
+
+type DocsVersionPersistence = ThemeConfig['docs']['versionPersistence'];
+
+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 {
+  return (
+    <DocsPreferredVersionContextProviderUnsafe>
+      {children}
+    </DocsPreferredVersionContextProviderUnsafe>
+  );
+}
+
+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/client/docsSearch.test.ts

@@ -0,0 +1,14 @@
+/**
+ * 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 {getDocsVersionSearchTag} from './docsSearch';
+
+describe('getDocsVersionSearchTag', () => {
+  it('works', () => {
+    expect(getDocsVersionSearchTag('foo', 'bar')).toBe('docs-foo-bar');
+  });
+});

package/src/client/docsSearch.ts

@@ -0,0 +1,57 @@
+/**
+ * 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 {
+  useAllDocsData,
+  useActivePluginAndVersion,
+} from '@docusaurus/plugin-content-docs/client';
+import {useDocsPreferredVersionByPluginId} from './docsPreferredVersion';
+
+/** The search tag to append as each doc's metadata. */
+export function getDocsVersionSearchTag(
+  pluginId: string,
+  versionName: string,
+): string {
+  return `docs-${pluginId}-${versionName}`;
+}
+
+/**
+ * Gets the relevant docs tags to search.
+ * This is the logic that powers the contextual search feature.
+ *
+ * If user is browsing Android 1.4 docs, he'll get presented with:
+ * - Android '1.4' docs
+ * - iOS 'preferred | latest' docs
+ *
+ * The result is generic and not coupled to Algolia/DocSearch on purpose.
+ */
+export function useDocsContextualSearchTags(): string[] {
+  const allDocsData = useAllDocsData();
+  const activePluginAndVersion = useActivePluginAndVersion();
+  const docsPreferredVersionByPluginId = useDocsPreferredVersionByPluginId();
+
+  // This can't use more specialized hooks because we are mapping over all
+  // plugin instances.
+  function getDocPluginTags(pluginId: string) {
+    const activeVersion =
+      activePluginAndVersion?.activePlugin.pluginId === pluginId
+        ? activePluginAndVersion.activeVersion
+        : undefined;
+
+    const preferredVersion = docsPreferredVersionByPluginId[pluginId];
+
+    const latestVersion = allDocsData[pluginId]!.versions.find(
+      (v) => v.isLast,
+    )!;
+
+    const version = activeVersion ?? preferredVersion ?? latestVersion;
+
+    return getDocsVersionSearchTag(pluginId, version.name);
+  }
+
+  return [...Object.keys(allDocsData).map(getDocPluginTags)];
+}

package/src/client/docsSidebar.tsx

@@ -0,0 +1,50 @@
+/**
+ * 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 '@docusaurus/theme-common/internal';
+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;
+}