@docusaurus/theme-common 2.0.0-beta.8bda3b2db → 2.0.0-beta.9

package/lib/components/Details/index.js

@@ -0,0 +1,64 @@
+/**
+ * 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, { useRef, useState } from 'react';
+import useIsBrowser from '@docusaurus/useIsBrowser';
+import clsx from 'clsx';
+import { useCollapsible, Collapsible } from '../Collapsible';
+import styles from './styles.module.css';
+function isInSummary(node) {
+    if (!node) {
+        return false;
+    }
+    return node.tagName === 'SUMMARY' || isInSummary(node.parentElement);
+}
+function hasParent(node, parent) {
+    if (!node) {
+        return false;
+    }
+    return node === parent || hasParent(node.parentElement, parent);
+}
+const Details = ({ summary, children, ...props }) => {
+    const isBrowser = useIsBrowser();
+    const detailsRef = useRef(null);
+    const { collapsed, setCollapsed } = useCollapsible({
+        initialState: !props.open,
+    });
+    // We use a separate prop because it must be set only after animation completes
+    // Otherwise close anim won't work
+    const [open, setOpen] = useState(props.open);
+    return (React.createElement("details", { ...props, ref: detailsRef, open: open, "data-collapsed": collapsed, className: clsx(styles.details, { [styles.isBrowser]: isBrowser }, props.className), onMouseDown: (e) => {
+            const target = e.target;
+            // Prevent a double-click to highlight summary text
+            if (isInSummary(target) && e.detail > 1) {
+                e.preventDefault();
+            }
+        }, onClick: (e) => {
+            e.stopPropagation(); // For isolation of multiple nested details/summary
+            const target = e.target;
+            const shouldToggle = isInSummary(target) && hasParent(target, detailsRef.current);
+            if (!shouldToggle) {
+                return;
+            }
+            e.preventDefault();
+            if (collapsed) {
+                setCollapsed(false);
+                setOpen(true);
+            }
+            else {
+                setCollapsed(true);
+                // setOpen(false); // Don't do this, it breaks close animation!
+            }
+        } },
+        summary,
+        React.createElement(Collapsible, { lazy: false, collapsed: collapsed, disableSSRStyle // Allows component to work fine even with JS disabled!
+            : true, onCollapseTransitionEnd: (newCollapsed) => {
+                setCollapsed(newCollapsed);
+                setOpen(!newCollapsed);
+            } },
+            React.createElement("div", { className: styles.collapsibleContent }, children))));
+};
+export default Details;

package/lib/components/Details/styles.module.css

@@ -0,0 +1,58 @@
+/**
+ * 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.
+ */
+
+/*
+CSS variables, meant to be overriden by final theme
+ */
+.details {
+  --docusaurus-details-summary-arrow-size: 0.38rem;
+  --docusaurus-details-transition: transform 200ms ease;
+  --docusaurus-details-decoration-color: grey;
+}
+
+.details > summary {
+  position: relative;
+  cursor: pointer;
+  list-style: none;
+  padding-left: 1rem;
+}
+
+/* TODO: deprecation, need to remove this after Safari will support `::marker` */
+.details > summary::-webkit-details-marker {
+  display: none;
+}
+
+.details > summary:before {
+  position: absolute;
+  top: 0.45rem;
+  left: 0;
+
+  /* CSS-only Arrow */
+  content: '';
+  border-width: var(--docusaurus-details-summary-arrow-size);
+  border-style: solid;
+  border-color: transparent transparent transparent
+    var(--docusaurus-details-decoration-color);
+
+  /* Arrow rotation anim */
+  transform: rotate(0deg);
+  transition: var(--docusaurus-details-transition);
+  transform-origin: calc(var(--docusaurus-details-summary-arrow-size) / 2) 50%;
+}
+
+/* When JS disabled/failed to load: we use the open property for arrow animation: */
+.details[open]:not(.isBrowser) > summary:before,
+/* When JS works: we use the data-attribute for arrow animation */
+.details[data-collapsed='false'].isBrowser > summary:before {
+  transform: rotate(90deg);
+}
+
+.collapsibleContent {
+  margin-top: 1rem;
+  border-top: 1px solid var(--docusaurus-details-decoration-color);
+  padding-top: 1rem;
+}

package/lib/index.d.ts

@@ -5,7 +5,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 export { useThemeConfig } from './utils/useThemeConfig';
-export type { ThemeConfig, Navbar, NavbarItem, NavbarLogo, Footer, FooterLinks, FooterLinkItem, } from './utils/useThemeConfig';
+export type { ThemeConfig, UserThemeConfig, Navbar, NavbarItem, NavbarLogo, Footer, FooterLinks, FooterLinkItem, } from './utils/useThemeConfig';
 export { createStorageSlot, listStorageKeys } from './utils/storageUtils';
 export { useAlternatePageUtils } from './utils/useAlternatePageUtils';
 export { parseCodeBlockTitle } from './utils/codeBlockUtils';
@@ -16,6 +16,24 @@ export { useTitleFormatter } from './utils/generalUtils';
 export { usePluralForm } from './utils/usePluralForm';
 export { useLocationChange } from './utils/useLocationChange';
 export { usePrevious } from './utils/usePrevious';
+export { useCollapsible, Collapsible } from './components/Collapsible';
+export type { UseCollapsibleConfig, UseCollapsibleReturns, } from './components/Collapsible';
+export { default as Details } from './components/Details';
+export type { DetailsProps } from './components/Details';
+export { MobileSecondaryMenuProvider, MobileSecondaryMenuFiller, useMobileSecondaryMenuRenderer, } from './utils/mobileSecondaryMenu';
+export type { MobileSecondaryMenuComponent } from './utils/mobileSecondaryMenu';
 export { useDocsPreferredVersion, useDocsPreferredVersionByPluginId, } from './utils/docsPreferredVersion/useDocsPreferredVersion';
+export { duplicates } from './utils/jsUtils';
 export { DocsPreferredVersionContextProvider } from './utils/docsPreferredVersion/DocsPreferredVersionProvider';
 export { ThemeClassNames } from './utils/ThemeClassNames';
+export { AnnouncementBarProvider, useAnnouncementBar, } from './utils/announcementBarUtils';
+export { useLocalPathname } from './utils/useLocalPathname';
+export { translateTagsPageTitle, listTagsByLetters } from './utils/tagsUtils';
+export type { TagLetterEntry } from './utils/tagsUtils';
+export { useHistoryPopHandler } from './utils/historyUtils';
+export { default as useTOCHighlight } from './utils/useTOCHighlight';
+export type { TOCHighlightConfig } from './utils/useTOCHighlight';
+export { useTOCFilter } from './utils/tocUtils';
+export { ScrollControllerProvider, useScrollController, useScrollPosition, useScrollPositionBlocker, } from './utils/scrollUtils';
+export { useIsomorphicLayoutEffect, useDynamicCallback, } from './utils/reactUtils';
+export { isRegexpStringMatch } from './utils/regexpUtils';

package/lib/index.js

@@ -15,6 +15,19 @@ export { useTitleFormatter } from './utils/generalUtils';
 export { usePluralForm } from './utils/usePluralForm';
 export { useLocationChange } from './utils/useLocationChange';
 export { usePrevious } from './utils/usePrevious';
+export { useCollapsible, Collapsible } from './components/Collapsible';
+export { default as Details } from './components/Details';
+export { MobileSecondaryMenuProvider, MobileSecondaryMenuFiller, useMobileSecondaryMenuRenderer, } from './utils/mobileSecondaryMenu';
 export { useDocsPreferredVersion, useDocsPreferredVersionByPluginId, } from './utils/docsPreferredVersion/useDocsPreferredVersion';
+export { duplicates } from './utils/jsUtils';
 export { DocsPreferredVersionContextProvider } from './utils/docsPreferredVersion/DocsPreferredVersionProvider';
 export { ThemeClassNames } from './utils/ThemeClassNames';
+export { AnnouncementBarProvider, useAnnouncementBar, } from './utils/announcementBarUtils';
+export { useLocalPathname } from './utils/useLocalPathname';
+export { translateTagsPageTitle, listTagsByLetters } from './utils/tagsUtils';
+export { useHistoryPopHandler } from './utils/historyUtils';
+export { default as useTOCHighlight } from './utils/useTOCHighlight';
+export { useTOCFilter } from './utils/tocUtils';
+export { ScrollControllerProvider, useScrollController, useScrollPosition, useScrollPositionBlocker, } from './utils/scrollUtils';
+export { useIsomorphicLayoutEffect, useDynamicCallback, } from './utils/reactUtils';
+export { isRegexpStringMatch } from './utils/regexpUtils';

package/lib/utils/ThemeClassNames.d.ts

@@ -5,18 +5,42 @@
  * LICENSE file in the root directory of this source tree.
  */
 export declare const ThemeClassNames: {
-    page: {
-        blogListPage: string;
-        blogPostPage: string;
-        blogTagsListPage: string;
-        blogTagsPostPage: string;
-        docPage: string;
-        mdxPage: string;
+    readonly page: {
+        readonly blogListPage: "blog-list-page";
+        readonly blogPostPage: "blog-post-page";
+        readonly blogTagsListPage: "blog-tags-list-page";
+        readonly blogTagPostListPage: "blog-tags-post-list-page";
+        readonly docsDocPage: "docs-doc-page";
+        readonly docsTagsListPage: "docs-tags-list-page";
+        readonly docsTagDocListPage: "docs-tags-doc-list-page";
+        readonly mdxPage: "mdx-page";
     };
-    wrapper: {
-        main: string;
-        blogPages: string;
-        docPages: string;
-        mdxPages: string;
+    readonly wrapper: {
+        readonly main: "main-wrapper";
+        readonly blogPages: "blog-wrapper";
+        readonly docsPages: "docs-wrapper";
+        readonly mdxPages: "mdx-wrapper";
     };
+    readonly common: {
+        readonly editThisPage: "theme-edit-this-page";
+        readonly lastUpdated: "theme-last-updated";
+        readonly backToTopButton: "theme-back-to-top-button";
+    };
+    readonly layout: {};
+    readonly docs: {
+        readonly docVersionBanner: "theme-doc-version-banner";
+        readonly docVersionBadge: "theme-doc-version-badge";
+        readonly docMarkdown: "theme-doc-markdown";
+        readonly docTocMobile: "theme-doc-toc-mobile";
+        readonly docTocDesktop: "theme-doc-toc-desktop";
+        readonly docFooter: "theme-doc-footer";
+        readonly docFooterTagsRow: "theme-doc-footer-tags-row";
+        readonly docFooterEditMetaRow: "theme-doc-footer-edit-meta-row";
+        readonly docSidebarMenu: "theme-doc-sidebar-menu";
+        readonly docSidebarItemCategory: "theme-doc-sidebar-item-category";
+        readonly docSidebarItemLink: "theme-doc-sidebar-item-link";
+        readonly docSidebarItemCategoryLevel: (level: number) => `theme-doc-sidebar-item-category-level-${number}`;
+        readonly docSidebarItemLinkLevel: (level: number) => `theme-doc-sidebar-item-link-level-${number}`;
+    };
+    readonly blog: {};
 };

package/lib/utils/ThemeClassNames.js

@@ -5,19 +5,52 @@
  * LICENSE file in the root directory of this source tree.
  */
 // These class names are used to style page layouts in Docusaurus
+// Those are meant to be targeted by user-provided custom CSS selectors
+// /!\ Please do not modify the classnames! This is a breaking change, and annoying for users!
 export const ThemeClassNames = {
     page: {
         blogListPage: 'blog-list-page',
         blogPostPage: 'blog-post-page',
         blogTagsListPage: 'blog-tags-list-page',
-        blogTagsPostPage: 'blog-tags-post-page',
-        docPage: 'doc-page',
+        blogTagPostListPage: 'blog-tags-post-list-page',
+        docsDocPage: 'docs-doc-page',
+        docsTagsListPage: 'docs-tags-list-page',
+        docsTagDocListPage: 'docs-tags-doc-list-page',
         mdxPage: 'mdx-page',
     },
     wrapper: {
         main: 'main-wrapper',
         blogPages: 'blog-wrapper',
-        docPages: 'docs-wrapper',
+        docsPages: 'docs-wrapper',
         mdxPages: 'mdx-wrapper',
     },
+    // /!\ Please keep the naming convention consistent!
+    // Something like: "theme-{blog,doc,version,page}?-<suffix>"
+    common: {
+        editThisPage: 'theme-edit-this-page',
+        lastUpdated: 'theme-last-updated',
+        backToTopButton: 'theme-back-to-top-button',
+    },
+    layout: {
+    // TODO add other stable classNames here
+    },
+    docs: {
+        docVersionBanner: 'theme-doc-version-banner',
+        docVersionBadge: 'theme-doc-version-badge',
+        docMarkdown: 'theme-doc-markdown',
+        docTocMobile: 'theme-doc-toc-mobile',
+        docTocDesktop: 'theme-doc-toc-desktop',
+        docFooter: 'theme-doc-footer',
+        docFooterTagsRow: 'theme-doc-footer-tags-row',
+        docFooterEditMetaRow: 'theme-doc-footer-edit-meta-row',
+        docSidebarMenu: 'theme-doc-sidebar-menu',
+        docSidebarItemCategory: 'theme-doc-sidebar-item-category',
+        docSidebarItemLink: 'theme-doc-sidebar-item-link',
+        docSidebarItemCategoryLevel: (level) => `theme-doc-sidebar-item-category-level-${level}`,
+        docSidebarItemLinkLevel: (level) => `theme-doc-sidebar-item-link-level-${level}`,
+        // TODO add other stable classNames here
+    },
+    blog: {
+    // TODO add other stable classNames here
+    },
 };

package/lib/utils/announcementBarUtils.d.ts

@@ -0,0 +1,17 @@
+/**
+ * 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';
+export declare const AnnouncementBarDismissStorageKey = "docusaurus.announcement.dismiss";
+declare type AnnouncementBarAPI = {
+    readonly isActive: boolean;
+    readonly close: () => void;
+};
+export declare const AnnouncementBarProvider: ({ children, }: {
+    children: ReactNode;
+}) => JSX.Element;
+export declare const useAnnouncementBar: () => AnnouncementBarAPI;
+export {};

package/lib/utils/announcementBarUtils.js

@@ -0,0 +1,73 @@
+/**
+ * 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, { useState, useEffect, useCallback, useMemo, useContext, createContext, } from 'react';
+import useIsBrowser from '@docusaurus/useIsBrowser';
+import { createStorageSlot } from './storageUtils';
+import { useThemeConfig } from './useThemeConfig';
+export const AnnouncementBarDismissStorageKey = 'docusaurus.announcement.dismiss';
+const AnnouncementBarIdStorageKey = 'docusaurus.announcement.id';
+const AnnouncementBarDismissStorage = createStorageSlot(AnnouncementBarDismissStorageKey);
+const IdStorage = createStorageSlot(AnnouncementBarIdStorageKey);
+const isDismissedInStorage = () => AnnouncementBarDismissStorage.get() === 'true';
+const setDismissedInStorage = (bool) => AnnouncementBarDismissStorage.set(String(bool));
+const useAnnouncementBarContextValue = () => {
+    const { announcementBar } = useThemeConfig();
+    const isBrowser = useIsBrowser();
+    const [isClosed, setClosed] = useState(() => {
+        return isBrowser
+            ? // On client navigation: init with localstorage value
+                isDismissedInStorage()
+            : // On server/hydration: always visible to prevent layout shifts (will be hidden with css if needed)
+                false;
+    });
+    // Update state after hydration
+    useEffect(() => {
+        setClosed(isDismissedInStorage());
+    }, []);
+    const handleClose = useCallback(() => {
+        setDismissedInStorage(true);
+        setClosed(true);
+    }, []);
+    useEffect(() => {
+        if (!announcementBar) {
+            return;
+        }
+        const { id } = announcementBar;
+        let viewedId = IdStorage.get();
+        // retrocompatibility due to spelling mistake of default id
+        // see https://github.com/facebook/docusaurus/issues/3338
+        if (viewedId === 'annoucement-bar') {
+            viewedId = 'announcement-bar';
+        }
+        const isNewAnnouncement = id !== viewedId;
+        IdStorage.set(id);
+        if (isNewAnnouncement) {
+            setDismissedInStorage(false);
+        }
+        if (isNewAnnouncement || !isDismissedInStorage()) {
+            setClosed(false);
+        }
+    }, [announcementBar]);
+    return useMemo(() => {
+        return {
+            isActive: !!announcementBar && !isClosed,
+            close: handleClose,
+        };
+    }, [announcementBar, isClosed, handleClose]);
+};
+const AnnouncementBarContext = createContext(null);
+export const AnnouncementBarProvider = ({ children, }) => {
+    const value = useAnnouncementBarContextValue();
+    return (React.createElement(AnnouncementBarContext.Provider, { value: value }, children));
+};
+export const useAnnouncementBar = () => {
+    const api = useContext(AnnouncementBarContext);
+    if (!api) {
+        throw new Error('useAnnouncementBar(): AnnouncementBar not found in React context: make sure to use the AnnouncementBarProvider on top of the tree');
+    }
+    return api;
+};

package/lib/utils/docsPreferredVersion/DocsPreferredVersionProvider.js

@@ -69,7 +69,7 @@ function useContextValue() {
         return {
             savePreferredVersion,
         };
-    }, [setState]);
+    }, [versionPersistence]);
     return [state, api];
 }
 const Context = createContext(null);

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

@@ -1,5 +1,7 @@
+/// <reference types="@docusaurus/plugin-content-docs" />
+import { GlobalVersion } from '@theme/hooks/useDocs';
 export declare function useDocsPreferredVersion(pluginId?: string | undefined): {
-    readonly preferredVersion: any;
-    readonly savePreferredVersionName: (versionName: string) => void;
+    preferredVersion: GlobalVersion | null | undefined;
+    savePreferredVersionName: (versionName: string) => void;
 };
-export declare function useDocsPreferredVersionByPluginId(): Record<string, any>;
+export declare function useDocsPreferredVersionByPluginId(): Record<string, GlobalVersion | null | undefined>;

package/lib/utils/docsPreferredVersion/useDocsPreferredVersion.js

@@ -8,7 +8,6 @@ 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);
@@ -19,7 +18,7 @@ export function useDocsPreferredVersion(pluginId = DEFAULT_PLUGIN_ID) {
         : null;
     const savePreferredVersionName = useCallback((versionName) => {
         api.savePreferredVersion(pluginId, versionName);
-    }, [api]);
+    }, [api, pluginId]);
     return { preferredVersion, savePreferredVersionName };
 }
 export function useDocsPreferredVersionByPluginId() {

package/lib/utils/generalUtils.js

@@ -6,8 +6,8 @@
  */
 import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
 export const useTitleFormatter = (title) => {
-    const { siteConfig = {} } = useDocusaurusContext();
-    const { title: siteTitle, titleDelimiter = '|' } = siteConfig;
+    const { siteConfig } = useDocusaurusContext();
+    const { title: siteTitle, titleDelimiter } = siteConfig;
     return title && title.trim().length
         ? `${title.trim()} ${titleDelimiter} ${siteTitle}`
         : siteTitle;

package/lib/utils/historyUtils.d.ts

@@ -0,0 +1,11 @@
+/**
+ * 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 { Location, Action } from '@docusaurus/history';
+declare type HistoryBlockHandler = (location: Location, action: Action) => void | false;
+export declare function useHistoryActionHandler(handler: HistoryBlockHandler): void;
+export declare function useHistoryPopHandler(handler: HistoryBlockHandler): void;
+export {};

package/lib/utils/historyUtils.js

@@ -0,0 +1,42 @@
+/**
+ * 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 { useEffect, useRef } from 'react';
+import { useHistory } from '@docusaurus/router';
+/*
+Permits to register a handler that will be called on history actions (pop,push,replace)
+If the handler returns false, the navigation transition will be blocked/cancelled
+ */
+export function useHistoryActionHandler(handler) {
+    const { block } = useHistory();
+    // Avoid stale closure issues without triggering useless re-renders
+    const lastHandlerRef = useRef(handler);
+    useEffect(() => {
+        lastHandlerRef.current = handler;
+    }, [handler]);
+    useEffect(() => {
+        // See https://github.com/remix-run/history/blob/main/docs/blocking-transitions.md
+        return block((location, action) => {
+            return lastHandlerRef.current(location, action);
+        });
+    }, [block, lastHandlerRef]);
+}
+/*
+Permits to register a handler that will be called on history pop navigation (backward/forward)
+If the handler returns false, the backward/forward transition will be blocked
+
+Unfortunately there's no good way to detect the "direction" (backward/forward) of the POP event.
+ */
+export function useHistoryPopHandler(handler) {
+    useHistoryActionHandler((location, action) => {
+        if (action === 'POP') {
+            // Eventually block navigation if handler returns false
+            return handler(location, action);
+        }
+        // Don't block other navigation actions
+        return undefined;
+    });
+}

package/lib/utils/jsUtils.d.ts

@@ -0,0 +1,13 @@
+/**
+ * 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.
+ */
+/**
+ * Gets the duplicate values in an array.
+ * @param arr The array.
+ * @param comparator Compares two values and returns `true` if they are equal (duplicated).
+ * @returns Value of the elements `v` that have a preceding element `u` where `comparator(u, v) === true`. Values within the returned array are not guaranteed to be unique.
+ */
+export declare function duplicates<T>(arr: readonly T[], comparator?: (a: T, b: T) => boolean): T[];

package/lib/utils/jsUtils.js

@@ -0,0 +1,16 @@
+/**
+ * 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.
+ */
+// A replacement of lodash in client code
+/**
+ * Gets the duplicate values in an array.
+ * @param arr The array.
+ * @param comparator Compares two values and returns `true` if they are equal (duplicated).
+ * @returns Value of the elements `v` that have a preceding element `u` where `comparator(u, v) === true`. Values within the returned array are not guaranteed to be unique.
+ */
+export function duplicates(arr, comparator = (a, b) => a === b) {
+    return arr.filter((v, vIndex) => arr.findIndex((u) => comparator(u, v)) !== vIndex);
+}

package/lib/utils/mobileSecondaryMenu.d.ts

@@ -0,0 +1,20 @@
+/**
+ * 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, ComponentType } from 'react';
+declare type ExtraProps = {
+    toggleSidebar: () => void;
+};
+export declare type MobileSecondaryMenuComponent<Props extends unknown> = ComponentType<Props & ExtraProps>;
+export declare function MobileSecondaryMenuProvider({ children, }: {
+    children: ReactNode;
+}): JSX.Element;
+export declare function useMobileSecondaryMenuRenderer(): (extraProps: ExtraProps) => ReactNode | undefined;
+export declare function MobileSecondaryMenuFiller<Props extends Record<string, unknown>>({ component, props, }: {
+    component: MobileSecondaryMenuComponent<Props & ExtraProps>;
+    props: Props;
+}): JSX.Element | null;
+export {};

package/lib/utils/mobileSecondaryMenu.js

@@ -0,0 +1,51 @@
+/**
+ * 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, { useState, useContext, createContext, useEffect, useMemo, } from 'react';
+function useContextValue() {
+    return useState(null);
+}
+const Context = createContext(null);
+export function MobileSecondaryMenuProvider({ children, }) {
+    return (React.createElement(Context.Provider, { value: useContextValue() }, children));
+}
+function useMobileSecondaryMenuContext() {
+    const value = useContext(Context);
+    if (value === null) {
+        throw new Error('MobileSecondaryMenuProvider was not used correctly, context value is null');
+    }
+    return value;
+}
+export function useMobileSecondaryMenuRenderer() {
+    const [state] = useMobileSecondaryMenuContext();
+    if (state) {
+        const Comp = state.component;
+        return function render(extraProps) {
+            return React.createElement(Comp, { ...state.props, ...extraProps });
+        };
+    }
+    return () => undefined;
+}
+function useShallowMemoizedObject(obj) {
+    return useMemo(() => obj, 
+    // Is this safe?
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [...Object.keys(obj), ...Object.values(obj)]);
+}
+// Fill the secondary menu placeholder with some real content
+export function MobileSecondaryMenuFiller({ component, props, }) {
+    const [, setState] = useMobileSecondaryMenuContext();
+    // To avoid useless context re-renders, props are memoized shallowly
+    const memoizedProps = useShallowMemoizedObject(props);
+    useEffect(() => {
+        // @ts-expect-error: context is not 100% typesafe but it's ok
+        setState({ component, props: memoizedProps });
+    }, [setState, component, memoizedProps]);
+    useEffect(() => {
+        return () => setState(null);
+    }, [setState]);
+    return null;
+}

package/lib/utils/reactUtils.d.ts

@@ -0,0 +1,9 @@
+/**
+ * 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 { useLayoutEffect } from 'react';
+export declare const useIsomorphicLayoutEffect: typeof useLayoutEffect;
+export declare function useDynamicCallback<T extends (...args: never[]) => unknown>(callback: T): T;

package/lib/utils/reactUtils.js

@@ -0,0 +1,26 @@
+/**
+ * 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, useEffect, useLayoutEffect, useRef } from 'react';
+// This hook is like useLayoutEffect, but without the SSR warning
+// It seems hacky but it's used in many React libs (Redux, Formik...)
+// Also mentioned here: https://github.com/facebook/react/issues/16956
+// It is useful when you need to update a ref as soon as possible after a React render (before useEffect)
+export const useIsomorphicLayoutEffect = typeof window !== 'undefined' ? useLayoutEffect : useEffect;
+// Permits to transform an unstable callback (like an arrow function provided as props)
+// to a "stable" callback that is safe to use in a useEffect dependency array
+// Useful to avoid React stale closure problems + avoid useless effect re-executions
+//
+// Workaround until the React team recommends a good solution, see https://github.com/facebook/react/issues/16956
+// This generally works has some potential drawbacks, such as https://github.com/facebook/react/issues/16956#issuecomment-536636418
+export function useDynamicCallback(callback) {
+    const ref = useRef(callback);
+    useIsomorphicLayoutEffect(() => {
+        ref.current = callback;
+    }, [callback]);
+    // @ts-expect-error: TODO, not sure how to fix this TS error
+    return useCallback((...args) => ref.current(...args), []);
+}

package/lib/utils/regexpUtils.d.ts

@@ -0,0 +1,10 @@
+/**
+ * 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.
+ */
+/**
+ * Utility to convert an optional string into a Regex case sensitive and global
+ */
+export declare function isRegexpStringMatch(regexAsString?: string, valueToTest?: string): boolean;