@azerion/bunosaurus-plugin-content-docs 0.0.0-stage → 4.0.0

package/lib/client/docsSidebar.d.ts

@@ -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 { type ReactNode } from 'react';
+import type { PropSidebar } from '@docusaurus/plugin-content-docs';
+type ContextValue = {
+    name: string;
+    items: PropSidebar;
+};
+/**
+ * Provide the current sidebar to your children.
+ */
+export declare function DocsSidebarProvider({ children, name, items, }: {
+    children: ReactNode;
+    name: string | undefined;
+    items: PropSidebar | undefined;
+}): ReactNode;
+/**
+ * Gets the sidebar that's currently displayed, or `null` if there isn't one
+ */
+export declare function useDocsSidebar(): ContextValue | null;
+export {};

package/lib/client/docsSidebar.js

@@ -0,0 +1,29 @@
+/**
+ * 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 } from 'react';
+import { ReactContextError } from '@docusaurus/theme-common';
+// 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 = Symbol('EmptyContext');
+const Context = React.createContext(EmptyContext);
+/**
+ * Provide the current sidebar to your children.
+ */
+export function DocsSidebarProvider({ children, name, items, }) {
+    const stableValue = useMemo(() => (name && items ? { name, items } : null), [name, items]);
+    return <Context value={stableValue}>{children}</Context>;
+}
+/**
+ * Gets the sidebar that's currently displayed, or `null` if there isn't one
+ */
+export function useDocsSidebar() {
+    const value = useContext(Context);
+    if (value === EmptyContext) {
+        throw new ReactContextError('DocsSidebarProvider');
+    }
+    return value;
+}

package/lib/client/docsUtils.d.ts

@@ -0,0 +1,112 @@
+/**
+ * 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 GlobalVersion, type GlobalSidebar, type GlobalDoc } from '@docusaurus/plugin-content-docs/client';
+import type { Props as DocRootProps } from '@theme/DocRoot';
+import type { PropSidebar, PropSidebarItem, PropSidebarItemCategory, PropVersionDoc, PropSidebarBreadcrumbsItem } from '@docusaurus/plugin-content-docs';
+/**
+ * A null-safe way to access a doc's data by ID in the active version.
+ */
+export declare function useDocById(id: string): PropVersionDoc;
+/**
+ * A null-safe way to access a doc's data by ID in the active version.
+ */
+export declare function useDocById(id: string | undefined): PropVersionDoc | undefined;
+/**
+ * Pure function, similar to `Array#find`, but works on the sidebar tree.
+ */
+export declare function findSidebarCategory(sidebar: PropSidebar, predicate: (category: PropSidebarItemCategory) => boolean): PropSidebarItemCategory | 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 declare function findFirstSidebarItemCategoryLink(item: PropSidebarItemCategory): string | undefined;
+/**
+ * Best effort to assign a link to a sidebar item.
+ */
+export declare function findFirstSidebarItemLink(item: PropSidebarItem): string | undefined;
+/**
+ * Gets the category associated with the current location. Should only be used
+ * on category index pages.
+ */
+export declare function useCurrentSidebarCategory(): PropSidebarItemCategory;
+/**
+ * Gets the category associated with the current location. Should only be used
+ * on category index pages.
+ */
+export declare function useCurrentSidebarSiblings(): PropSidebarItem[];
+/**
+ * Checks if a sidebar item should be active, based on the active path.
+ */
+export declare function isActiveSidebarItem(item: PropSidebarItem, activePath: string): boolean;
+export declare function isVisibleSidebarItem(item: PropSidebarItem, activePath: string): boolean;
+export declare function useVisibleSidebarItems(items: readonly PropSidebarItem[], activePath: string): PropSidebarItem[];
+/**
+ * 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 declare function useSidebarBreadcrumbs(): PropSidebarBreadcrumbsItem[] | null;
+/**
+ * "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 declare function useDocsVersionCandidates(docsPluginId?: string): [GlobalVersion, ...GlobalVersion[]];
+/**
+ * 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 declare function useLayoutDocsSidebar(sidebarId: string, docsPluginId?: string): GlobalSidebar;
+/**
+ * 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 declare function useLayoutDoc(docId: string, docsPluginId?: string): GlobalDoc | null;
+/**
+ * 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 declare function useDocRootMetadata({ route }: DocRootProps): null | {
+    /** The element that should be rendered at the current location. */
+    docElement: ReactNode;
+    /**
+     * The name of the sidebar associated with the current doc. `sidebarName` and
+     * `sidebarItems` correspond to the value of {@link useDocsSidebar}.
+     */
+    sidebarName: string | undefined;
+    /** The items of the sidebar associated with the current doc. */
+    sidebarItems: PropSidebar | undefined;
+};
+/**
+ * Filter items we don't want to display on the doc card list view
+ * @param items
+ */
+export declare function filterDocCardListItems(items: PropSidebarItem[]): PropSidebarItem[];

package/lib/client/docsUtils.js

@@ -0,0 +1,299 @@
+/**
+ * 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;
+}
+/**
+ * Gets the category associated with the current location. Should only be used
+ * on category index pages.
+ */
+export function useCurrentSidebarSiblings() {
+    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];
+    return deepestCategory?.items ?? sidebar.items;
+}
+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) ||
+                (typeof item.href !== 'undefined' && !item.linkUnlisted) ||
+                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) {
+            // Extract category item
+            if (item.type === 'category') {
+                if (isSamePath(item.href, pathname) || extract(item.items)) {
+                    breadcrumbs.unshift(item);
+                    return true;
+                }
+            }
+            // Extract doc item
+            else if (item.type === 'link' &&
+                item.docId &&
+                isSamePath(item.href, pathname)) {
+                if (!onlyCategories) {
+                    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;
+}): ReactNode;
+/**
+ * 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';
+const Context = React.createContext(null);
+/**
+ * Provide the current version's metadata to your children.
+ */
+export function DocsVersionProvider({ children, version, }) {
+    return <Context value={version}>{children}</Context>;
+}
+/**
+ * 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

@@ -0,0 +1,91 @@
+/**
+ * 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 { UseDataOptions } from '@docusaurus/types';
+export { useDocById, findSidebarCategory, findFirstSidebarItemLink, isActiveSidebarItem, isVisibleSidebarItem, useVisibleSidebarItems, useSidebarBreadcrumbs, useDocsVersionCandidates, useLayoutDoc, useLayoutDocsSidebar, useDocRootMetadata, useCurrentSidebarCategory, useCurrentSidebarSiblings, 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 { useBreadcrumbsStructuredData } from './structuredDataUtils';
+export type ActivePlugin = {
+    pluginId: string;
+    pluginData: GlobalPluginData;
+};
+export type ActiveDocContext = {
+    activeVersion?: GlobalVersion;
+    activeDoc?: GlobalDoc;
+    alternateDocVersions: {
+        [versionName: string]: GlobalDoc;
+    };
+};
+export type GlobalDoc = {
+    /**
+     * For generated index pages, this is the `slug`, **not** `permalink`
+     * (without base URL). Because slugs have leading slashes but IDs don't,
+     * there won't be clashes.
+     */
+    id: string;
+    path: string;
+    sidebar?: string;
+    unlisted?: boolean;
+};
+export type GlobalVersion = {
+    name: string;
+    label: string;
+    isLast: boolean;
+    path: string;
+    /** The doc with `slug: /`, or first doc in first sidebar */
+    mainDocId: string;
+    docs: GlobalDoc[];
+    /** Unversioned IDs. In development, this list is empty. */
+    draftIds: string[];
+    sidebars?: {
+        [sidebarId: string]: GlobalSidebar;
+    };
+};
+export type GlobalSidebar = {
+    link?: {
+        label: string;
+        path: string;
+    };
+};
+export type GlobalPluginData = {
+    path: string;
+    versions: GlobalVersion[];
+    breadcrumbs: boolean;
+};
+export type DocVersionSuggestions = {
+    /** Suggest the latest version */
+    latestVersionSuggestion: GlobalVersion;
+    /** Suggest the same doc, in latest version (if one exists) */
+    latestDocSuggestion?: GlobalDoc;
+};
+export declare const useAllDocsData: () => {
+    [pluginId: string]: GlobalPluginData;
+};
+export declare const useDocsData: (pluginId: string | undefined) => GlobalPluginData;
+export declare function useActivePlugin(options?: UseDataOptions): ActivePlugin | undefined;
+export declare function useActivePluginAndVersion(options?: UseDataOptions): {
+    activePlugin: ActivePlugin;
+    activeVersion: GlobalVersion | undefined;
+} | undefined;
+/** Versions are returned ordered (most recent first). */
+export declare function useVersions(pluginId: string | undefined): GlobalVersion[];
+export declare function useLatestVersion(pluginId: string | undefined): GlobalVersion;
+/**
+ * Returns `undefined` on doc-unrelated pages, because there's no version
+ * currently considered as active.
+ */
+export declare function useActiveVersion(pluginId: string | undefined): GlobalVersion | undefined;
+export declare function useActiveDocContext(pluginId: string | undefined): ActiveDocContext;
+/**
+ * Useful to say "hey, you are not on the latest docs version, please switch"
+ */
+export declare function useDocVersionSuggestions(pluginId: string | undefined): DocVersionSuggestions;