@docusaurus/theme-common 2.0.0-beta.1decd6f80 → 2.0.0-beta.20

package/lib/utils/docsPreferredVersion/DocsPreferredVersionProvider.d.ts

@@ -1,21 +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 { ReactNode } from 'react';
-declare type DocsPreferredVersionName = string | null;
-declare type DocsPreferredVersionPluginState = {
-    preferredVersionName: DocsPreferredVersionName;
-};
-declare type DocsPreferredVersionState = Record<string, DocsPreferredVersionPluginState>;
-declare function useContextValue(): readonly [DocsPreferredVersionState, {
-    savePreferredVersion: (pluginId: string, versionName: string) => void;
-}];
-declare type DocsPreferredVersionContextValue = ReturnType<typeof useContextValue>;
-export declare function DocsPreferredVersionContextProvider({ children, }: {
-    children: ReactNode;
-}): JSX.Element;
-export declare function useDocsPreferredVersionContext(): DocsPreferredVersionContextValue;
-export {};

package/lib/utils/docsPreferredVersion/DocsPreferredVersionProvider.js

@@ -1,94 +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, { createContext, useContext, useEffect, useMemo, useState, } from 'react';
-import { useThemeConfig } from '../useThemeConfig';
-import { isDocsPluginEnabled } from '../docsUtils';
-import { useAllDocsData } from '@theme/hooks/useDocs';
-import DocsPreferredVersionStorage from './DocsPreferredVersionStorage';
-// Initial state is always null as we can't read localstorage from node SSR
-function getInitialState(pluginIds) {
-    const initialState = {};
-    pluginIds.forEach((pluginId) => {
-        initialState[pluginId] = {
-            preferredVersionName: null,
-        };
-    });
-    return initialState;
-}
-// Read storage for all docs plugins
-// Assign to each doc plugin a preferred version (if found)
-function readStorageState({ pluginIds, versionPersistence, allDocsData, }) {
-    // 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) {
-        const preferredVersionNameUnsafe = DocsPreferredVersionStorage.read(pluginId, versionPersistence);
-        const pluginData = allDocsData[pluginId];
-        const versionExists = pluginData.versions.some((version) => version.name === preferredVersionNameUnsafe);
-        if (versionExists) {
-            return { preferredVersionName: preferredVersionNameUnsafe };
-        }
-        else {
-            DocsPreferredVersionStorage.clear(pluginId, versionPersistence);
-            return { preferredVersionName: null };
-        }
-    }
-    const initialState = {};
-    pluginIds.forEach((pluginId) => {
-        initialState[pluginId] = restorePluginState(pluginId);
-    });
-    return initialState;
-}
-function useVersionPersistence() {
-    return useThemeConfig().docs.versionPersistence;
-}
-// Value that  will be accessible through context: [state,api]
-function useContextValue() {
-    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, versionName) {
-            DocsPreferredVersionStorage.save(pluginId, versionPersistence, versionName);
-            setState((s) => ({
-                ...s,
-                [pluginId]: { preferredVersionName: versionName },
-            }));
-        }
-        return {
-            savePreferredVersion,
-        };
-    }, [setState]);
-    return [state, api];
-}
-const Context = createContext(null);
-export function DocsPreferredVersionContextProvider({ children, }) {
-    if (isDocsPluginEnabled) {
-        return (React.createElement(DocsPreferredVersionContextProviderUnsafe, null, children));
-    }
-    else {
-        return React.createElement(React.Fragment, null, children);
-    }
-}
-function DocsPreferredVersionContextProviderUnsafe({ children, }) {
-    const contextValue = useContextValue();
-    return React.createElement(Context.Provider, { value: contextValue }, children);
-}
-export function useDocsPreferredVersionContext() {
-    const value = useContext(Context);
-    if (!value) {
-        throw new Error("Can't find docs preferred context, maybe you forgot to use the DocsPreferredVersionContextProvider ?");
-    }
-    return value;
-}

package/lib/utils/docsPreferredVersion/DocsPreferredVersionStorage.d.ts

@@ -1,13 +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 { DocsVersionPersistence } from '../useThemeConfig';
-declare const DocsPreferredVersionStorage: {
-    save: (pluginId: string, persistence: DocsVersionPersistence, versionName: string) => void;
-    read: (pluginId: string, persistence: DocsVersionPersistence) => string | null;
-    clear: (pluginId: string, persistence: DocsVersionPersistence) => void;
-};
-export default DocsPreferredVersionStorage;

package/lib/utils/docsPreferredVersion/DocsPreferredVersionStorage.js

@@ -1,20 +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 { createStorageSlot } from '../storageUtils';
-const storageKey = (pluginId) => `docs-preferred-version-${pluginId}`;
-const DocsPreferredVersionStorage = {
-    save: (pluginId, persistence, versionName) => {
-        createStorageSlot(storageKey(pluginId), { persistence }).set(versionName);
-    },
-    read: (pluginId, persistence) => {
-        return createStorageSlot(storageKey(pluginId), { persistence }).get();
-    },
-    clear: (pluginId, persistence) => {
-        createStorageSlot(storageKey(pluginId), { persistence }).del();
-    },
-};
-export default DocsPreferredVersionStorage;

package/lib/utils/docsPreferredVersion/useDocsPreferredVersion.d.ts

@@ -1,5 +0,0 @@
-export declare function useDocsPreferredVersion(pluginId?: string | undefined): {
-    readonly preferredVersion: any;
-    readonly savePreferredVersionName: (versionName: string) => void;
-};
-export declare function useDocsPreferredVersionByPluginId(): Record<string, any>;

package/lib/utils/docsPreferredVersion/useDocsPreferredVersion.js

@@ -1,41 +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 { useCallback } from 'react';
-import { useDocsPreferredVersionContext } from './DocsPreferredVersionProvider';
-import { useAllDocsData, useDocsData } from '@theme/hooks/useDocs';
-import { DEFAULT_PLUGIN_ID } from '@docusaurus/constants';
-// TODO improve typing
-// Note, the preferredVersion attribute will always be null before mount
-export function useDocsPreferredVersion(pluginId = DEFAULT_PLUGIN_ID) {
-    const docsData = useDocsData(pluginId);
-    const [state, api] = useDocsPreferredVersionContext();
-    const { preferredVersionName } = state[pluginId];
-    const preferredVersion = preferredVersionName
-        ? docsData.versions.find((version) => version.name === preferredVersionName)
-        : null;
-    const savePreferredVersionName = useCallback((versionName) => {
-        api.savePreferredVersion(pluginId, versionName);
-    }, [api]);
-    return { preferredVersion, savePreferredVersionName };
-}
-export function useDocsPreferredVersionByPluginId() {
-    const allDocsData = useAllDocsData();
-    const [state] = useDocsPreferredVersionContext();
-    function getPluginIdPreferredVersion(pluginId) {
-        const docsData = allDocsData[pluginId];
-        const { preferredVersionName } = state[pluginId];
-        return preferredVersionName
-            ? docsData.versions.find((version) => version.name === preferredVersionName)
-            : null;
-    }
-    const pluginIds = Object.keys(allDocsData);
-    const result = {};
-    pluginIds.forEach((pluginId) => {
-        result[pluginId] = getPluginIdPreferredVersion(pluginId);
-    });
-    return result;
-}

package/lib/utils/pathUtils.js

@@ -1,13 +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.
- */
-// Compare the 2 paths, ignoring trailing /
-export const isSamePath = (path1, path2) => {
-    const normalize = (pathname) => {
-        return !pathname || (pathname === null || pathname === void 0 ? void 0 : pathname.endsWith('/')) ? pathname : `${pathname}/`;
-    };
-    return normalize(path1) === normalize(path2);
-};

package/lib/utils/useChangeRoute.js

@@ -1,18 +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 { useRef, useEffect } from 'react';
-import { useLocation } from '@docusaurus/router';
-export function useChangeRoute(onRouteChange) {
-    const { pathname } = useLocation();
-    const latestPathnameRef = useRef(pathname);
-    useEffect(() => {
-        if (pathname !== latestPathnameRef.current) {
-            latestPathnameRef.current = pathname;
-            onRouteChange();
-        }
-    }, [pathname, latestPathnameRef, onRouteChange]);
-}

package/src/utils/__tests__/codeBlockUtils.test.ts

@@ -1,54 +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 {parseCodeBlockTitle} from '../codeBlockUtils';
-
-describe('parseCodeBlockTitle', () => {
-  test('should parse double quote delimited title', () => {
-    expect(parseCodeBlockTitle(`title="index.js"`)).toEqual(`index.js`);
-  });
-
-  test('should parse single quote delimited title', () => {
-    expect(parseCodeBlockTitle(`title='index.js'`)).toEqual(`index.js`);
-  });
-
-  test('should not parse mismatched quote delimiters', () => {
-    expect(parseCodeBlockTitle(`title="index.js'`)).toEqual(``);
-  });
-
-  test('should parse undefined metastring', () => {
-    expect(parseCodeBlockTitle(undefined)).toEqual(``);
-  });
-
-  test('should parse metastring with no title specified', () => {
-    expect(parseCodeBlockTitle(`{1,2-3}`)).toEqual(``);
-  });
-
-  test('should parse with multiple metadatas title first', () => {
-    expect(parseCodeBlockTitle(`title="index.js" label="JavaScript"`)).toEqual(
-      `index.js`,
-    );
-  });
-
-  test('should parse with multiple metadatas title last', () => {
-    expect(parseCodeBlockTitle(`label="JavaScript" title="index.js"`)).toEqual(
-      `index.js`,
-    );
-  });
-
-  test('should parse double quotes when delimited by single quotes', () => {
-    expect(parseCodeBlockTitle(`title='console.log("Hello, World!")'`)).toEqual(
-      `console.log("Hello, World!")`,
-    );
-  });
-
-  test('should parse single quotes when delimited by double quotes', () => {
-    expect(parseCodeBlockTitle(`title="console.log('Hello, World!')"`)).toEqual(
-      `console.log('Hello, World!')`,
-    );
-  });
-});

package/src/utils/__tests__/pathUtils.test.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 {isSamePath} from '../pathUtils';
-
-describe('isSamePath', () => {
-  test('should be true for compared path without trailing slash', () => {
-    expect(isSamePath('/docs', '/docs')).toBeTruthy();
-  });
-
-  test('should be true for compared path with trailing slash', () => {
-    expect(isSamePath('/docs', '/docs/')).toBeTruthy();
-  });
-
-  test('should be false for compared path with double trailing slash', () => {
-    expect(isSamePath('/docs', '/docs//')).toBeFalsy();
-  });
-
-  test('should be true for twice undefined/null', () => {
-    expect(isSamePath(undefined, undefined)).toBeTruthy();
-    expect(isSamePath(undefined, undefined)).toBeTruthy();
-  });
-
-  test('should be false when one undefined', () => {
-    expect(isSamePath('/docs', undefined)).toBeFalsy();
-    expect(isSamePath(undefined, '/docs')).toBeFalsy();
-  });
-});

package/src/utils/docsPreferredVersion/DocsPreferredVersionProvider.tsx

@@ -1,165 +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, {
-  createContext,
-  ReactNode,
-  useContext,
-  useEffect,
-  useMemo,
-  useState,
-} from 'react';
-import {useThemeConfig, DocsVersionPersistence} from '../useThemeConfig';
-import {isDocsPluginEnabled} from '../docsUtils';
-
-import {useAllDocsData} from '@theme/hooks/useDocs';
-
-import DocsPreferredVersionStorage from './DocsPreferredVersionStorage';
-
-type DocsPreferredVersionName = string | null;
-
-// State for a single docs plugin instance
-type DocsPreferredVersionPluginState = {
-  preferredVersionName: DocsPreferredVersionName;
-};
-
-// We need to store in state/storage globally
-// one preferred version per docs plugin instance
-// pluginId => pluginState
-type DocsPreferredVersionState = Record<
-  string,
-  DocsPreferredVersionPluginState
->;
-
-// Initial state is always null as we can't read localstorage from node SSR
-function getInitialState(pluginIds: string[]): DocsPreferredVersionState {
-  const initialState: DocsPreferredVersionState = {};
-  pluginIds.forEach((pluginId) => {
-    initialState[pluginId] = {
-      preferredVersionName: null,
-    };
-  });
-  return initialState;
-}
-
-// Read storage for all docs plugins
-// Assign to each doc plugin a preferred version (if found)
-function readStorageState({
-  pluginIds,
-  versionPersistence,
-  allDocsData,
-}: {
-  pluginIds: string[];
-  versionPersistence: DocsVersionPersistence;
-  allDocsData: any; // TODO find a way to type it :(
-}): 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: any) => version.name === preferredVersionNameUnsafe,
-    );
-    if (versionExists) {
-      return {preferredVersionName: preferredVersionNameUnsafe};
-    } else {
-      DocsPreferredVersionStorage.clear(pluginId, versionPersistence);
-      return {preferredVersionName: null};
-    }
-  }
-
-  const initialState: DocsPreferredVersionState = {};
-  pluginIds.forEach((pluginId) => {
-    initialState[pluginId] = restorePluginState(pluginId);
-  });
-  return initialState;
-}
-
-function useVersionPersistence(): DocsVersionPersistence {
-  return useThemeConfig().docs.versionPersistence;
-}
-
-// Value that  will be accessible through context: [state,api]
-function useContextValue() {
-  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,
-    };
-  }, [setState]);
-
-  return [state, api] as const;
-}
-
-type DocsPreferredVersionContextValue = ReturnType<typeof useContextValue>;
-
-const Context = createContext<DocsPreferredVersionContextValue | null>(null);
-
-export function DocsPreferredVersionContextProvider({
-  children,
-}: {
-  children: ReactNode;
-}): JSX.Element {
-  if (isDocsPluginEnabled) {
-    return (
-      <DocsPreferredVersionContextProviderUnsafe>
-        {children}
-      </DocsPreferredVersionContextProviderUnsafe>
-    );
-  } else {
-    return <>{children}</>;
-  }
-}
-
-function DocsPreferredVersionContextProviderUnsafe({
-  children,
-}: {
-  children: ReactNode;
-}): JSX.Element {
-  const contextValue = useContextValue();
-  return <Context.Provider value={contextValue}>{children}</Context.Provider>;
-}
-
-export function useDocsPreferredVersionContext(): DocsPreferredVersionContextValue {
-  const value = useContext(Context);
-  if (!value) {
-    throw new Error(
-      "Can't find docs preferred context, maybe you forgot to use the DocsPreferredVersionContextProvider ?",
-    );
-  }
-  return value;
-}

package/src/utils/docsPreferredVersion/DocsPreferredVersionStorage.ts

@@ -1,34 +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 {createStorageSlot} from '../storageUtils';
-import {DocsVersionPersistence} from '../useThemeConfig';
-
-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 => {
-    return createStorageSlot(storageKey(pluginId), {persistence}).get();
-  },
-
-  clear: (pluginId: string, persistence: DocsVersionPersistence): void => {
-    createStorageSlot(storageKey(pluginId), {persistence}).del();
-  },
-};
-
-export default DocsPreferredVersionStorage;

package/src/utils/docsPreferredVersion/useDocsPreferredVersion.ts

@@ -1,66 +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 {useCallback} from 'react';
-import {useDocsPreferredVersionContext} from './DocsPreferredVersionProvider';
-import {useAllDocsData, useDocsData} from '@theme/hooks/useDocs';
-
-import {DEFAULT_PLUGIN_ID} from '@docusaurus/constants';
-
-// TODO improve typing
-
-// Note, the preferredVersion attribute will always be null before mount
-export function useDocsPreferredVersion(
-  pluginId: string | undefined = DEFAULT_PLUGIN_ID,
-) {
-  const docsData = useDocsData(pluginId);
-  const [state, api] = useDocsPreferredVersionContext();
-
-  const {preferredVersionName} = state[pluginId];
-
-  const preferredVersion = preferredVersionName
-    ? docsData.versions.find(
-        (version: any) => version.name === preferredVersionName,
-      )
-    : null;
-
-  const savePreferredVersionName = useCallback(
-    (versionName: string) => {
-      api.savePreferredVersion(pluginId, versionName);
-    },
-    [api],
-  );
-
-  return {preferredVersion, savePreferredVersionName} as const;
-}
-
-export function useDocsPreferredVersionByPluginId(): Record<string, any> {
-  const allDocsData = useAllDocsData();
-  const [state] = useDocsPreferredVersionContext();
-
-  function getPluginIdPreferredVersion(pluginId: string) {
-    const docsData = allDocsData[pluginId];
-    const {preferredVersionName} = state[pluginId];
-
-    return preferredVersionName
-      ? docsData.versions.find(
-          (version: any) => version.name === preferredVersionName,
-        )
-      : null;
-  }
-
-  const pluginIds = Object.keys(allDocsData);
-
-  const result: Record<
-    string,
-    any // TODO find a way to type this properly!
-  > = {};
-  pluginIds.forEach((pluginId) => {
-    result[pluginId] = getPluginIdPreferredVersion(pluginId);
-  });
-
-  return result;
-}

package/src/utils/docsUtils.ts

@@ -1,11 +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 {useAllDocsData} from '@theme/hooks/useDocs';
-
-// TODO not ideal, see also "useDocs"
-export const isDocsPluginEnabled: boolean = !!useAllDocsData;

package/src/utils/pathUtils.ts

@@ -1,17 +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.
- */
-
-// Compare the 2 paths, ignoring trailing /
-export const isSamePath = (
-  path1: string | undefined,
-  path2: string | undefined,
-): boolean => {
-  const normalize = (pathname: string | undefined) => {
-    return !pathname || pathname?.endsWith('/') ? pathname : `${pathname}/`;
-  };
-  return normalize(path1) === normalize(path2);
-};

package/src/utils/useChangeRoute.ts

@@ -1,21 +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 {useRef, useEffect} from 'react';
-import {useLocation} from '@docusaurus/router';
-
-export function useChangeRoute(onRouteChange: () => void): void {
-  const {pathname} = useLocation();
-  const latestPathnameRef = useRef(pathname);
-
-  useEffect(() => {
-    if (pathname !== latestPathnameRef.current) {
-      latestPathnameRef.current = pathname;
-      onRouteChange();
-    }
-  }, [pathname, latestPathnameRef, onRouteChange]);
-}

package/tsconfig.json

@@ -1,10 +0,0 @@
-{
-  "extends": "../../tsconfig.json",
-  "compilerOptions": {
-    "incremental": true,
-    "tsBuildInfoFile": "./lib/.tsbuildinfo",
-    "module": "esnext",
-    "rootDir": "src",
-    "outDir": "lib"
-  }
-}