@docusaurus/plugin-content-docs 0.0.0-6001 → 0.0.0-6004

package/lib/client/docsUtils.js

@@ -0,0 +1,273 @@
+/**
+ * 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 { matchPath, useLocation } from '@docusaurus/router';
+import renderRoutes from '@docusaurus/renderRoutes';
+import { useActivePlugin, useActiveDocContext, useLatestVersion, } from '@docusaurus/plugin-content-docs/client';
+import { isSamePath } from '@docusaurus/theme-common/internal';
+import { uniq } from '@docusaurus/theme-common';
+import { useDocsPreferredVersion } from './docsPreferredVersion';
+import { useDocsVersion } from './docsVersion';
+import { useDocsSidebar } from './docsSidebar';
+export function useDocById(id) {
+    const version = useDocsVersion();
+    if (!id) {
+        return undefined;
+    }
+    const doc = version.docs[id];
+    if (!doc) {
+        throw new Error(`no version doc found by id=${id}`);
+    }
+    return doc;
+}
+/**
+ * Pure function, similar to `Array#find`, but works on the sidebar tree.
+ */
+export function findSidebarCategory(sidebar, predicate) {
+    for (const item of sidebar) {
+        if (item.type === 'category') {
+            if (predicate(item)) {
+                return item;
+            }
+            const subItem = findSidebarCategory(item.items, predicate);
+            if (subItem) {
+                return subItem;
+            }
+        }
+    }
+    return undefined;
+}
+/**
+ * Best effort to assign a link to a sidebar category. If the category doesn't
+ * have a link itself, we link to the first sub item with a link.
+ */
+export function findFirstSidebarItemCategoryLink(item) {
+    if (item.href && !item.linkUnlisted) {
+        return item.href;
+    }
+    for (const subItem of item.items) {
+        const link = findFirstSidebarItemLink(subItem);
+        if (link) {
+            return link;
+        }
+    }
+    return undefined;
+}
+/**
+ * Best effort to assign a link to a sidebar item.
+ */
+export function findFirstSidebarItemLink(item) {
+    if (item.type === 'link' && !item.unlisted) {
+        return item.href;
+    }
+    if (item.type === 'category') {
+        return findFirstSidebarItemCategoryLink(item);
+    }
+    // Other items types, like "html"
+    return undefined;
+}
+/**
+ * Gets the category associated with the current location. Should only be used
+ * on category index pages.
+ */
+export function useCurrentSidebarCategory() {
+    const { pathname } = useLocation();
+    const sidebar = useDocsSidebar();
+    if (!sidebar) {
+        throw new Error('Unexpected: cant find current sidebar in context');
+    }
+    const categoryBreadcrumbs = getSidebarBreadcrumbs({
+        sidebarItems: sidebar.items,
+        pathname,
+        onlyCategories: true,
+    });
+    const deepestCategory = categoryBreadcrumbs.slice(-1)[0];
+    if (!deepestCategory) {
+        throw new Error(`${pathname} is not associated with a category. useCurrentSidebarCategory() should only be used on category index pages.`);
+    }
+    return deepestCategory;
+}
+const isActive = (testedPath, activePath) => typeof testedPath !== 'undefined' && isSamePath(testedPath, activePath);
+const containsActiveSidebarItem = (items, activePath) => items.some((subItem) => isActiveSidebarItem(subItem, activePath));
+/**
+ * Checks if a sidebar item should be active, based on the active path.
+ */
+export function isActiveSidebarItem(item, activePath) {
+    if (item.type === 'link') {
+        return isActive(item.href, activePath);
+    }
+    if (item.type === 'category') {
+        return (isActive(item.href, activePath) ||
+            containsActiveSidebarItem(item.items, activePath));
+    }
+    return false;
+}
+export function isVisibleSidebarItem(item, activePath) {
+    switch (item.type) {
+        case 'category':
+            return (isActiveSidebarItem(item, activePath) ||
+                item.items.some((subItem) => isVisibleSidebarItem(subItem, activePath)));
+        case 'link':
+            // An unlisted item remains visible if it is active
+            return !item.unlisted || isActiveSidebarItem(item, activePath);
+        default:
+            return true;
+    }
+}
+export function useVisibleSidebarItems(items, activePath) {
+    return useMemo(() => items.filter((item) => isVisibleSidebarItem(item, activePath)), [items, activePath]);
+}
+/**
+ * Get the sidebar the breadcrumbs for a given pathname
+ * Ordered from top to bottom
+ */
+function getSidebarBreadcrumbs({ sidebarItems, pathname, onlyCategories = false, }) {
+    const breadcrumbs = [];
+    function extract(items) {
+        for (const item of items) {
+            if ((item.type === 'category' &&
+                (isSamePath(item.href, pathname) || extract(item.items))) ||
+                (item.type === 'link' && isSamePath(item.href, pathname))) {
+                const filtered = onlyCategories && item.type !== 'category';
+                if (!filtered) {
+                    breadcrumbs.unshift(item);
+                }
+                return true;
+            }
+        }
+        return false;
+    }
+    extract(sidebarItems);
+    return breadcrumbs;
+}
+/**
+ * Gets the breadcrumbs of the current doc page, based on its sidebar location.
+ * Returns `null` if there's no sidebar or breadcrumbs are disabled.
+ */
+export function useSidebarBreadcrumbs() {
+    const sidebar = useDocsSidebar();
+    const { pathname } = useLocation();
+    const breadcrumbsOption = useActivePlugin()?.pluginData.breadcrumbs;
+    if (breadcrumbsOption === false || !sidebar) {
+        return null;
+    }
+    return getSidebarBreadcrumbs({ sidebarItems: sidebar.items, pathname });
+}
+/**
+ * "Version candidates" are mostly useful for the layout components, which must
+ * be able to work on all pages. For example, if a user has `{ type: "doc",
+ * docId: "intro" }` as a navbar item, which version does that refer to? We
+ * believe that it could refer to at most three version candidates:
+ *
+ * 1. The **active version**, the one that the user is currently browsing. See
+ * {@link useActiveDocContext}.
+ * 2. The **preferred version**, the one that the user last visited. See
+ * {@link useDocsPreferredVersion}.
+ * 3. The **latest version**, the "default". See {@link useLatestVersion}.
+ *
+ * @param docsPluginId The plugin ID to get versions from.
+ * @returns An array of 1~3 versions with priorities defined above, guaranteed
+ * to be unique and non-sparse. Will be memoized, hence stable for deps array.
+ */
+export function useDocsVersionCandidates(docsPluginId) {
+    const { activeVersion } = useActiveDocContext(docsPluginId);
+    const { preferredVersion } = useDocsPreferredVersion(docsPluginId);
+    const latestVersion = useLatestVersion(docsPluginId);
+    return useMemo(() => uniq([activeVersion, preferredVersion, latestVersion].filter(Boolean)), [activeVersion, preferredVersion, latestVersion]);
+}
+/**
+ * The layout components, like navbar items, must be able to work on all pages,
+ * even on non-doc ones where there's no version context, so a sidebar ID could
+ * be ambiguous. This hook would always return a sidebar to be linked to. See
+ * also {@link useDocsVersionCandidates} for how this selection is done.
+ *
+ * @throws This hook throws if a sidebar with said ID is not found.
+ */
+export function useLayoutDocsSidebar(sidebarId, docsPluginId) {
+    const versions = useDocsVersionCandidates(docsPluginId);
+    return useMemo(() => {
+        const allSidebars = versions.flatMap((version) => version.sidebars ? Object.entries(version.sidebars) : []);
+        const sidebarEntry = allSidebars.find((sidebar) => sidebar[0] === sidebarId);
+        if (!sidebarEntry) {
+            throw new Error(`Can't find any sidebar with id "${sidebarId}" in version${versions.length > 1 ? 's' : ''} ${versions.map((version) => version.name).join(', ')}".
+Available sidebar ids are:
+- ${allSidebars.map((entry) => entry[0]).join('\n- ')}`);
+        }
+        return sidebarEntry[1];
+    }, [sidebarId, versions]);
+}
+/**
+ * The layout components, like navbar items, must be able to work on all pages,
+ * even on non-doc ones where there's no version context, so a doc ID could be
+ * ambiguous. This hook would always return a doc to be linked to. See also
+ * {@link useDocsVersionCandidates} for how this selection is done.
+ *
+ * @throws This hook throws if a doc with said ID is not found.
+ */
+export function useLayoutDoc(docId, docsPluginId) {
+    const versions = useDocsVersionCandidates(docsPluginId);
+    return useMemo(() => {
+        const allDocs = versions.flatMap((version) => version.docs);
+        const doc = allDocs.find((versionDoc) => versionDoc.id === docId);
+        if (!doc) {
+            const isDraft = versions
+                .flatMap((version) => version.draftIds)
+                .includes(docId);
+            // Drafts should be silently filtered instead of throwing
+            if (isDraft) {
+                return null;
+            }
+            throw new Error(`Couldn't find any doc with id "${docId}" in version${versions.length > 1 ? 's' : ''} "${versions.map((version) => version.name).join(', ')}".
+Available doc ids are:
+- ${uniq(allDocs.map((versionDoc) => versionDoc.id)).join('\n- ')}`);
+        }
+        return doc;
+    }, [docId, versions]);
+}
+// TODO later read version/route directly from context
+/**
+ * The docs plugin creates nested routes, with the top-level route providing the
+ * version metadata, and the subroutes creating individual doc pages. This hook
+ * will match the current location against all known sub-routes.
+ *
+ * @param props The props received by `@theme/DocRoot`
+ * @returns The data of the relevant document at the current location, or `null`
+ * if no document associated with the current location can be found.
+ */
+export function useDocRootMetadata({ route }) {
+    const location = useLocation();
+    const versionMetadata = useDocsVersion();
+    const docRoutes = route.routes;
+    const currentDocRoute = docRoutes.find((docRoute) => matchPath(location.pathname, docRoute));
+    if (!currentDocRoute) {
+        return null;
+    }
+    // For now, the sidebarName is added as route config: not ideal!
+    const sidebarName = currentDocRoute.sidebar;
+    const sidebarItems = sidebarName
+        ? versionMetadata.docsSidebars[sidebarName]
+        : undefined;
+    const docElement = renderRoutes(docRoutes);
+    return {
+        docElement,
+        sidebarName,
+        sidebarItems,
+    };
+}
+/**
+ * Filter items we don't want to display on the doc card list view
+ * @param items
+ */
+export function filterDocCardListItems(items) {
+    return items.filter((item) => {
+        const canHaveLink = item.type === 'category' || item.type === 'link';
+        if (canHaveLink) {
+            return !!findFirstSidebarItemLink(item);
+        }
+        return true;
+    });
+}

package/lib/client/docsVersion.d.ts

@@ -0,0 +1,19 @@
+/**
+ * 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 type { PropVersionMetadata } from '@docusaurus/plugin-content-docs';
+/**
+ * Provide the current version's metadata to your children.
+ */
+export declare function DocsVersionProvider({ children, version, }: {
+    children: ReactNode;
+    version: PropVersionMetadata | null;
+}): JSX.Element;
+/**
+ * Gets the version metadata of the current doc page.
+ */
+export declare function useDocsVersion(): PropVersionMetadata;

package/lib/client/docsVersion.js

@@ -0,0 +1,25 @@
+/**
+ * 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 } from 'react';
+import { ReactContextError } from '@docusaurus/theme-common/internal';
+const Context = React.createContext(null);
+/**
+ * Provide the current version's metadata to your children.
+ */
+export function DocsVersionProvider({ children, version, }) {
+    return <Context.Provider value={version}>{children}</Context.Provider>;
+}
+/**
+ * Gets the version metadata of the current doc page.
+ */
+export function useDocsVersion() {
+    const version = useContext(Context);
+    if (version === null) {
+        throw new ReactContextError('DocsVersionProvider');
+    }
+    return version;
+}

package/lib/client/index.d.ts

@@ -5,6 +5,14 @@
  * LICENSE file in the root directory of this source tree.
  */
 import type { UseDataOptions } from '@docusaurus/types';
+export { useDocById, findSidebarCategory, findFirstSidebarItemLink, isActiveSidebarItem, isVisibleSidebarItem, useVisibleSidebarItems, useSidebarBreadcrumbs, useDocsVersionCandidates, useLayoutDoc, useLayoutDocsSidebar, useDocRootMetadata, useCurrentSidebarCategory, filterDocCardListItems, } from './docsUtils';
+export { useDocsPreferredVersion } from './docsPreferredVersion';
+export { DocSidebarItemsExpandedStateProvider, useDocSidebarItemsExpandedState, } from './docSidebarItemsExpandedState';
+export { DocsVersionProvider, useDocsVersion } from './docsVersion';
+export { DocsSidebarProvider, useDocsSidebar } from './docsSidebar';
+export { DocProvider, useDoc, type DocContextValue } from './doc';
+export { useDocsPreferredVersionByPluginId, DocsPreferredVersionContextProvider, } from './docsPreferredVersion';
+export { useDocsContextualSearchTags, getDocsVersionSearchTag, } from './docsSearch';
 export type ActivePlugin = {
     pluginId: string;
     pluginData: GlobalPluginData;

package/lib/client/index.js

@@ -7,6 +7,14 @@
 import { useLocation } from '@docusaurus/router';
 import { useAllPluginInstancesData, usePluginData, } from '@docusaurus/useGlobalData';
 import { getActivePlugin, getLatestVersion, getActiveVersion, getActiveDocContext, getDocVersionSuggestions, } from './docsClientUtils';
+export { useDocById, findSidebarCategory, findFirstSidebarItemLink, isActiveSidebarItem, isVisibleSidebarItem, useVisibleSidebarItems, useSidebarBreadcrumbs, useDocsVersionCandidates, useLayoutDoc, useLayoutDocsSidebar, useDocRootMetadata, useCurrentSidebarCategory, filterDocCardListItems, } from './docsUtils';
+export { useDocsPreferredVersion } from './docsPreferredVersion';
+export { DocSidebarItemsExpandedStateProvider, useDocSidebarItemsExpandedState, } from './docSidebarItemsExpandedState';
+export { DocsVersionProvider, useDocsVersion } from './docsVersion';
+export { DocsSidebarProvider, useDocsSidebar } from './docsSidebar';
+export { DocProvider, useDoc } from './doc';
+export { useDocsPreferredVersionByPluginId, DocsPreferredVersionContextProvider, } from './docsPreferredVersion';
+export { useDocsContextualSearchTags, getDocsVersionSearchTag, } from './docsSearch';
 // Important to use a constant object to avoid React useEffect executions etc.
 // see https://github.com/facebook/docusaurus/issues/5089
 const StableEmptyObject = {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docusaurus/plugin-content-docs",
-  "version": "0.0.0-6001",
+  "version": "0.0.0-6004",
   "description": "Docs plugin for Docusaurus.",
   "main": "lib/index.js",
   "sideEffects": false,
@@ -35,14 +35,15 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@docusaurus/core": "0.0.0-6001",
-    "@docusaurus/logger": "0.0.0-6001",
-    "@docusaurus/mdx-loader": "0.0.0-6001",
-    "@docusaurus/module-type-aliases": "0.0.0-6001",
-    "@docusaurus/types": "0.0.0-6001",
-    "@docusaurus/utils": "0.0.0-6001",
-    "@docusaurus/utils-common": "0.0.0-6001",
-    "@docusaurus/utils-validation": "0.0.0-6001",
+    "@docusaurus/core": "0.0.0-6004",
+    "@docusaurus/logger": "0.0.0-6004",
+    "@docusaurus/mdx-loader": "0.0.0-6004",
+    "@docusaurus/module-type-aliases": "0.0.0-6004",
+    "@docusaurus/theme-common": "0.0.0-6004",
+    "@docusaurus/types": "0.0.0-6004",
+    "@docusaurus/utils": "0.0.0-6004",
+    "@docusaurus/utils-common": "0.0.0-6004",
+    "@docusaurus/utils-validation": "0.0.0-6004",
     "@types/react-router-config": "^5.0.7",
     "combine-promises": "^1.1.0",
     "fs-extra": "^11.1.1",
@@ -66,5 +67,5 @@
   "engines": {
     "node": ">=18.0"
   },
-  "gitHead": "17774ee60e041b816785ddc45ef63e01d746d8e3"
+  "gitHead": "70e1069f65cbb7416b20d8e828293b3d537cc3de"
 }

package/src/client/doc.tsx

@@ -0,0 +1,71 @@
+/**
+ * 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, type ReactNode, useContext} from 'react';
+import {ReactContextError} from '@docusaurus/theme-common/internal';
+import type {PropDocContent} from '@docusaurus/plugin-content-docs';
+
+/**
+ * The React context value returned by the `useDoc()` hook.
+ * It contains useful data related to the currently browsed doc.
+ */
+export type DocContextValue = Pick<
+  PropDocContent,
+  'metadata' | 'frontMatter' | 'toc' | 'assets' | 'contentTitle'
+>;
+
+const Context = React.createContext<DocContextValue | null>(null);
+
+/**
+ * Note: we don't use `PropDoc` as context value on purpose. Metadata is
+ * currently stored inside the MDX component, but we may want to change that in
+ * the future. This layer is a good opportunity to decouple storage from
+ * consuming API, potentially allowing us to provide metadata as both props and
+ * route context without duplicating the chunks in the future.
+ */
+function useContextValue(content: PropDocContent): DocContextValue {
+  return useMemo(
+    () => ({
+      metadata: content.metadata,
+      frontMatter: content.frontMatter,
+      assets: content.assets,
+      contentTitle: content.contentTitle,
+      toc: content.toc,
+    }),
+    [content],
+  );
+}
+
+/**
+ * This is a very thin layer around the `content` received from the MDX loader.
+ * It provides metadata about the doc to the children tree.
+ */
+export function DocProvider({
+  children,
+  content,
+}: {
+  children: ReactNode;
+  content: PropDocContent;
+}): JSX.Element {
+  const contextValue = useContextValue(content);
+  return <Context.Provider value={contextValue}>{children}</Context.Provider>;
+}
+
+/**
+ * Returns the data of the currently browsed doc. Gives access to the doc's MDX
+ * Component, front matter, metadata, TOC, etc. When swizzling a low-level
+ * component (e.g. the "Edit this page" link) and you need some extra metadata,
+ * you don't have to drill the props all the way through the component tree:
+ * simply use this hook instead.
+ */
+export function useDoc(): DocContextValue {
+  const doc = useContext(Context);
+  if (doc === null) {
+    throw new ReactContextError('DocProvider');
+  }
+  return doc;
+}

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;
+}