@docusaurus/theme-common 2.0.0-beta.fbdeefcac → 2.0.0-rc.1

package/lib/utils/scrollUtils.js

@@ -0,0 +1,200 @@
+/**
+ * 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, { useCallback, useContext, useEffect, useLayoutEffect, useMemo, useRef, } from 'react';
+import ExecutionEnvironment from '@docusaurus/ExecutionEnvironment';
+import useIsBrowser from '@docusaurus/useIsBrowser';
+import { useEvent, ReactContextError } from './reactUtils';
+function useScrollControllerContextValue() {
+    const scrollEventsEnabledRef = useRef(true);
+    return useMemo(() => ({
+        scrollEventsEnabledRef,
+        enableScrollEvents: () => {
+            scrollEventsEnabledRef.current = true;
+        },
+        disableScrollEvents: () => {
+            scrollEventsEnabledRef.current = false;
+        },
+    }), []);
+}
+const ScrollMonitorContext = React.createContext(undefined);
+export function ScrollControllerProvider({ children, }) {
+    const value = useScrollControllerContextValue();
+    return (<ScrollMonitorContext.Provider value={value}>
+      {children}
+    </ScrollMonitorContext.Provider>);
+}
+/**
+ * We need a way to update the scroll position while ignoring scroll events
+ * so as not to toggle Navbar/BackToTop visibility.
+ *
+ * This API permits to temporarily disable/ignore scroll events. Motivated by
+ * https://github.com/facebook/docusaurus/pull/5618
+ */
+export function useScrollController() {
+    const context = useContext(ScrollMonitorContext);
+    if (context == null) {
+        throw new ReactContextError('ScrollControllerProvider');
+    }
+    return context;
+}
+const getScrollPosition = () => ExecutionEnvironment.canUseDOM
+    ? {
+        scrollX: window.pageXOffset,
+        scrollY: window.pageYOffset,
+    }
+    : null;
+/**
+ * This hook fires an effect when the scroll position changes. The effect will
+ * be provided with the before/after scroll positions. Note that the effect may
+ * not be always run: if scrolling is disabled through `useScrollController`, it
+ * will be a no-op.
+ *
+ * @see {@link useScrollController}
+ */
+export function useScrollPosition(effect, deps = []) {
+    const { scrollEventsEnabledRef } = useScrollController();
+    const lastPositionRef = useRef(getScrollPosition());
+    const dynamicEffect = useEvent(effect);
+    useEffect(() => {
+        const handleScroll = () => {
+            if (!scrollEventsEnabledRef.current) {
+                return;
+            }
+            const currentPosition = getScrollPosition();
+            dynamicEffect(currentPosition, lastPositionRef.current);
+            lastPositionRef.current = currentPosition;
+        };
+        const opts = {
+            passive: true,
+        };
+        handleScroll();
+        window.addEventListener('scroll', handleScroll, opts);
+        return () => window.removeEventListener('scroll', handleScroll, opts);
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [dynamicEffect, scrollEventsEnabledRef, ...deps]);
+}
+function useScrollPositionSaver() {
+    const lastElementRef = useRef({
+        elem: null,
+        top: 0,
+    });
+    const save = useCallback((elem) => {
+        lastElementRef.current = {
+            elem,
+            top: elem.getBoundingClientRect().top,
+        };
+    }, []);
+    const restore = useCallback(() => {
+        const { current: { elem, top }, } = lastElementRef;
+        if (!elem) {
+            return { restored: false };
+        }
+        const newTop = elem.getBoundingClientRect().top;
+        const heightDiff = newTop - top;
+        if (heightDiff) {
+            window.scrollBy({ left: 0, top: heightDiff });
+        }
+        lastElementRef.current = { elem: null, top: 0 };
+        return { restored: heightDiff !== 0 };
+    }, []);
+    return useMemo(() => ({ save, restore }), [restore, save]);
+}
+/**
+ * This hook permits to "block" the scroll position of a DOM element.
+ * The idea is that we should be able to update DOM content above this element
+ * but the screen position of this element should not change.
+ *
+ * Feature motivated by the Tabs groups: clicking on a tab may affect tabs of
+ * the same group upper in the tree, yet to avoid a bad UX, the clicked tab must
+ * remain under the user mouse.
+ *
+ * @see https://github.com/facebook/docusaurus/pull/5618
+ */
+export function useScrollPositionBlocker() {
+    const scrollController = useScrollController();
+    const scrollPositionSaver = useScrollPositionSaver();
+    const nextLayoutEffectCallbackRef = useRef(undefined);
+    const blockElementScrollPositionUntilNextRender = useCallback((el) => {
+        scrollPositionSaver.save(el);
+        scrollController.disableScrollEvents();
+        nextLayoutEffectCallbackRef.current = () => {
+            const { restored } = scrollPositionSaver.restore();
+            nextLayoutEffectCallbackRef.current = undefined;
+            // Restoring the former scroll position will trigger a scroll event. We
+            // need to wait for next scroll event to happen before enabling the
+            // scrollController events again.
+            if (restored) {
+                const handleScrollRestoreEvent = () => {
+                    scrollController.enableScrollEvents();
+                    window.removeEventListener('scroll', handleScrollRestoreEvent);
+                };
+                window.addEventListener('scroll', handleScrollRestoreEvent);
+            }
+            else {
+                scrollController.enableScrollEvents();
+            }
+        };
+    }, [scrollController, scrollPositionSaver]);
+    useLayoutEffect(() => {
+        nextLayoutEffectCallbackRef.current?.();
+    });
+    return {
+        blockElementScrollPositionUntilNextRender,
+    };
+}
+function smoothScrollNative(top) {
+    window.scrollTo({ top, behavior: 'smooth' });
+    return () => {
+        // Nothing to cancel, it's natively cancelled if user tries to scroll down
+    };
+}
+function smoothScrollPolyfill(top) {
+    let raf = null;
+    const isUpScroll = document.documentElement.scrollTop > top;
+    function rafRecursion() {
+        const currentScroll = document.documentElement.scrollTop;
+        if ((isUpScroll && currentScroll > top) ||
+            (!isUpScroll && currentScroll < top)) {
+            raf = requestAnimationFrame(rafRecursion);
+            window.scrollTo(0, Math.floor((currentScroll - top) * 0.85) + top);
+        }
+    }
+    rafRecursion();
+    // Break the recursion. Prevents the user from "fighting" against that
+    // recursion producing a weird UX
+    return () => raf && cancelAnimationFrame(raf);
+}
+/**
+ * A "smart polyfill" of `window.scrollTo({ top, behavior: "smooth" })`.
+ * This currently always uses a polyfilled implementation unless
+ * `scroll-behavior: smooth` has been set in CSS, because native support
+ * detection for scroll behavior seems unreliable.
+ *
+ * This hook does not do anything by itself: it returns a start and a stop
+ * handle. You can execute either handle at any time.
+ */
+export function useSmoothScrollTo() {
+    const cancelRef = useRef(null);
+    const isBrowser = useIsBrowser();
+    // Not all have support for smooth scrolling (particularly Safari mobile iOS)
+    // TODO proper detection is currently unreliable!
+    // see https://github.com/wessberg/scroll-behavior-polyfill/issues/16
+    // For now, we only use native scroll behavior if smooth is already set,
+    // because otherwise the polyfill produces a weird UX when both CSS and JS try
+    // to scroll a page, and they cancel each other.
+    const supportsNativeSmoothScrolling = isBrowser &&
+        getComputedStyle(document.documentElement).scrollBehavior === 'smooth';
+    return {
+        startScroll: (top) => {
+            cancelRef.current = supportsNativeSmoothScrolling
+                ? smoothScrollNative(top)
+                : smoothScrollPolyfill(top);
+        },
+        cancelScroll: () => cancelRef.current?.(),
+    };
+}
+//# sourceMappingURL=scrollUtils.js.map

package/lib/utils/scrollUtils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scrollUtils.js","sourceRoot":"","sources":["../../src/utils/scrollUtils.tsx"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,EACZ,WAAW,EACX,UAAU,EACV,SAAS,EACT,eAAe,EACf,OAAO,EACP,MAAM,GAEP,MAAM,OAAO,CAAC;AACf,OAAO,oBAAoB,MAAM,kCAAkC,CAAC;AACpE,OAAO,YAAY,MAAM,0BAA0B,CAAC;AACpD,OAAO,EAAC,QAAQ,EAAE,iBAAiB,EAAC,MAAM,cAAc,CAAC;AAWzD,SAAS,+BAA+B;IACtC,MAAM,sBAAsB,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC;IAE5C,OAAO,OAAO,CACZ,GAAG,EAAE,CAAC,CAAC;QACL,sBAAsB;QACtB,kBAAkB,EAAE,GAAG,EAAE;YACvB,sBAAsB,CAAC,OAAO,GAAG,IAAI,CAAC;QACxC,CAAC;QACD,mBAAmB,EAAE,GAAG,EAAE;YACxB,sBAAsB,CAAC,OAAO,GAAG,KAAK,CAAC;QACzC,CAAC;KACF,CAAC,EACF,EAAE,CACH,CAAC;AACJ,CAAC;AAED,MAAM,oBAAoB,GAAG,KAAK,CAAC,aAAa,CAC9C,SAAS,CACV,CAAC;AAEF,MAAM,UAAU,wBAAwB,CAAC,EACvC,QAAQ,GAGT;IACC,MAAM,KAAK,GAAG,+BAA+B,EAAE,CAAC;IAChD,OAAO,CACL,CAAC,oBAAoB,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAC1C;MAAA,CAAC,QAAQ,CACX;IAAA,EAAE,oBAAoB,CAAC,QAAQ,CAAC,CACjC,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,mBAAmB;IACjC,MAAM,OAAO,GAAG,UAAU,CAAC,oBAAoB,CAAC,CAAC;IACjD,IAAI,OAAO,IAAI,IAAI,EAAE;QACnB,MAAM,IAAI,iBAAiB,CAAC,0BAA0B,CAAC,CAAC;KACzD;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAID,MAAM,iBAAiB,GAAG,GAA0B,EAAE,CACpD,oBAAoB,CAAC,SAAS;IAC5B,CAAC,CAAC;QACE,OAAO,EAAE,MAAM,CAAC,WAAW;QAC3B,OAAO,EAAE,MAAM,CAAC,WAAW;KAC5B;IACH,CAAC,CAAC,IAAI,CAAC;AAEX;;;;;;;GAOG;AACH,MAAM,UAAU,iBAAiB,CAC/B,MAGS,EACT,OAAkB,EAAE;IAEpB,MAAM,EAAC,sBAAsB,EAAC,GAAG,mBAAmB,EAAE,CAAC;IACvD,MAAM,eAAe,GAAG,MAAM,CAAwB,iBAAiB,EAAE,CAAC,CAAC;IAE3E,MAAM,aAAa,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC;IAEvC,SAAS,CAAC,GAAG,EAAE;QACb,MAAM,YAAY,GAAG,GAAG,EAAE;YACxB,IAAI,CAAC,sBAAsB,CAAC,OAAO,EAAE;gBACnC,OAAO;aACR;YACD,MAAM,eAAe,GAAG,iBAAiB,EAAG,CAAC;YAC7C,aAAa,CAAC,eAAe,EAAE,eAAe,CAAC,OAAO,CAAC,CAAC;YACxD,eAAe,CAAC,OAAO,GAAG,eAAe,CAAC;QAC5C,CAAC,CAAC;QAEF,MAAM,IAAI,GAAmD;YAC3D,OAAO,EAAE,IAAI;SACd,CAAC;QAEF,YAAY,EAAE,CAAC;QACf,MAAM,CAAC,gBAAgB,CAAC,QAAQ,EAAE,YAAY,EAAE,IAAI,CAAC,CAAC;QAEtD,OAAO,GAAG,EAAE,CAAC,MAAM,CAAC,mBAAmB,CAAC,QAAQ,EAAE,YAAY,EAAE,IAAI,CAAC,CAAC;QACtE,uDAAuD;IACzD,CAAC,EAAE,CAAC,aAAa,EAAE,sBAAsB,EAAE,GAAG,IAAI,CAAC,CAAC,CAAC;AACvD,CAAC;AAYD,SAAS,sBAAsB;IAC7B,MAAM,cAAc,GAAG,MAAM,CAA0C;QACrE,IAAI,EAAE,IAAI;QACV,GAAG,EAAE,CAAC;KACP,CAAC,CAAC;IAEH,MAAM,IAAI,GAAG,WAAW,CAAC,CAAC,IAAiB,EAAE,EAAE;QAC7C,cAAc,CAAC,OAAO,GAAG;YACvB,IAAI;YACJ,GAAG,EAAE,IAAI,CAAC,qBAAqB,EAAE,CAAC,GAAG;SACtC,CAAC;IACJ,CAAC,EAAE,EAAE,CAAC,CAAC;IAEP,MAAM,OAAO,GAAG,WAAW,CAAC,GAAG,EAAE;QAC/B,MAAM,EACJ,OAAO,EAAE,EAAC,IAAI,EAAE,GAAG,EAAC,GACrB,GAAG,cAAc,CAAC;QACnB,IAAI,CAAC,IAAI,EAAE;YACT,OAAO,EAAC,QAAQ,EAAE,KAAK,EAAC,CAAC;SAC1B;QACD,MAAM,MAAM,GAAG,IAAI,CAAC,qBAAqB,EAAE,CAAC,GAAG,CAAC;QAChD,MAAM,UAAU,GAAG,MAAM,GAAG,GAAG,CAAC;QAChC,IAAI,UAAU,EAAE;YACd,MAAM,CAAC,QAAQ,CAAC,EAAC,IAAI,EAAE,CAAC,EAAE,GAAG,EAAE,UAAU,EAAC,CAAC,CAAC;SAC7C;QACD,cAAc,CAAC,OAAO,GAAG,EAAC,IAAI,EAAE,IAAI,EAAE,GAAG,EAAE,CAAC,EAAC,CAAC;QAE9C,OAAO,EAAC,QAAQ,EAAE,UAAU,KAAK,CAAC,EAAC,CAAC;IACtC,CAAC,EAAE,EAAE,CAAC,CAAC;IAEP,OAAO,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC,EAAC,IAAI,EAAE,OAAO,EAAC,CAAC,EAAE,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC,CAAC;AAC3D,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,wBAAwB;IAOtC,MAAM,gBAAgB,GAAG,mBAAmB,EAAE,CAAC;IAC/C,MAAM,mBAAmB,GAAG,sBAAsB,EAAE,CAAC;IAErD,MAAM,2BAA2B,GAAG,MAAM,CACxC,SAAS,CACV,CAAC;IAEF,MAAM,yCAAyC,GAAG,WAAW,CAC3D,CAAC,EAAe,EAAE,EAAE;QAClB,mBAAmB,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QAC7B,gBAAgB,CAAC,mBAAmB,EAAE,CAAC;QACvC,2BAA2B,CAAC,OAAO,GAAG,GAAG,EAAE;YACzC,MAAM,EAAC,QAAQ,EAAC,GAAG,mBAAmB,CAAC,OAAO,EAAE,CAAC;YACjD,2BAA2B,CAAC,OAAO,GAAG,SAAS,CAAC;YAEhD,uEAAuE;YACvE,mEAAmE;YACnE,iCAAiC;YACjC,IAAI,QAAQ,EAAE;gBACZ,MAAM,wBAAwB,GAAG,GAAG,EAAE;oBACpC,gBAAgB,CAAC,kBAAkB,EAAE,CAAC;oBACtC,MAAM,CAAC,mBAAmB,CAAC,QAAQ,EAAE,wBAAwB,CAAC,CAAC;gBACjE,CAAC,CAAC;gBACF,MAAM,CAAC,gBAAgB,CAAC,QAAQ,EAAE,wBAAwB,CAAC,CAAC;aAC7D;iBAAM;gBACL,gBAAgB,CAAC,kBAAkB,EAAE,CAAC;aACvC;QACH,CAAC,CAAC;IACJ,CAAC,EACD,CAAC,gBAAgB,EAAE,mBAAmB,CAAC,CACxC,CAAC;IAEF,eAAe,CAAC,GAAG,EAAE;QACnB,2BAA2B,CAAC,OAAO,EAAE,EAAE,CAAC;IAC1C,CAAC,CAAC,CAAC;IAEH,OAAO;QACL,yCAAyC;KAC1C,CAAC;AACJ,CAAC;AAID,SAAS,kBAAkB,CAAC,GAAW;IACrC,MAAM,CAAC,QAAQ,CAAC,EAAC,GAAG,EAAE,QAAQ,EAAE,QAAQ,EAAC,CAAC,CAAC;IAC3C,OAAO,GAAG,EAAE;QACV,0EAA0E;IAC5E,CAAC,CAAC;AACJ,CAAC;AAED,SAAS,oBAAoB,CAAC,GAAW;IACvC,IAAI,GAAG,GAAkB,IAAI,CAAC;IAC9B,MAAM,UAAU,GAAG,QAAQ,CAAC,eAAe,CAAC,SAAS,GAAG,GAAG,CAAC;IAC5D,SAAS,YAAY;QACnB,MAAM,aAAa,GAAG,QAAQ,CAAC,eAAe,CAAC,SAAS,CAAC;QACzD,IACE,CAAC,UAAU,IAAI,aAAa,GAAG,GAAG,CAAC;YACnC,CAAC,CAAC,UAAU,IAAI,aAAa,GAAG,GAAG,CAAC,EACpC;YACA,GAAG,GAAG,qBAAqB,CAAC,YAAY,CAAC,CAAC;YAC1C,MAAM,CAAC,QAAQ,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,aAAa,GAAG,GAAG,CAAC,GAAG,IAAI,CAAC,GAAG,GAAG,CAAC,CAAC;SACpE;IACH,CAAC;IACD,YAAY,EAAE,CAAC;IAEf,sEAAsE;IACtE,iCAAiC;IACjC,OAAO,GAAG,EAAE,CAAC,GAAG,IAAI,oBAAoB,CAAC,GAAG,CAAC,CAAC;AAChD,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,iBAAiB;IAc/B,MAAM,SAAS,GAAG,MAAM,CAAyB,IAAI,CAAC,CAAC;IACvD,MAAM,SAAS,GAAG,YAAY,EAAE,CAAC;IACjC,6EAA6E;IAC7E,iDAAiD;IACjD,qEAAqE;IACrE,wEAAwE;IACxE,8EAA8E;IAC9E,gDAAgD;IAChD,MAAM,6BAA6B,GACjC,SAAS;QACT,gBAAgB,CAAC,QAAQ,CAAC,eAAe,CAAC,CAAC,cAAc,KAAK,QAAQ,CAAC;IACzE,OAAO;QACL,WAAW,EAAE,CAAC,GAAW,EAAE,EAAE;YAC3B,SAAS,CAAC,OAAO,GAAG,6BAA6B;gBAC/C,CAAC,CAAC,kBAAkB,CAAC,GAAG,CAAC;gBACzB,CAAC,CAAC,oBAAoB,CAAC,GAAG,CAAC,CAAC;QAChC,CAAC;QACD,YAAY,EAAE,GAAG,EAAE,CAAC,SAAS,CAAC,OAAO,EAAE,EAAE;KAC1C,CAAC;AACJ,CAAC"}

package/lib/utils/searchUtils.d.ts

@@ -5,4 +5,17 @@
  * LICENSE file in the root directory of this source tree.
  */
 export declare const DEFAULT_SEARCH_TAG = "default";
+/** The search tag to append as each doc's metadata. */
 export declare function docVersionSearchTag(pluginId: string, versionName: string): string;
+/**
+ * Gets the relevant context information for contextual search.
+ *
+ * The value is generic and not coupled to Algolia/DocSearch, since we may want
+ * to support multiple search engines, or allowing users to use their own search
+ * engine solution.
+ */
+export declare function useContextualSearchFilters(): {
+    locale: string;
+    tags: string[];
+};
+//# sourceMappingURL=searchUtils.d.ts.map

package/lib/utils/searchUtils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"searchUtils.d.ts","sourceRoot":"","sources":["../../src/utils/searchUtils.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AASH,eAAO,MAAM,kBAAkB,YAAY,CAAC;AAE5C,uDAAuD;AACvD,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,MAAM,GAClB,MAAM,CAER;AAED;;;;;;GAMG;AACH,wBAAgB,0BAA0B,IAAI;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,EAAE,CAAA;CAAC,CAkC7E"}

package/lib/utils/searchUtils.js

@@ -4,7 +4,44 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
+import { useAllDocsData, useActivePluginAndVersion, } from '@docusaurus/plugin-content-docs/client';
+import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
+import { useDocsPreferredVersionByPluginId } from '../contexts/docsPreferredVersion';
 export const DEFAULT_SEARCH_TAG = 'default';
+/** The search tag to append as each doc's metadata. */
 export function docVersionSearchTag(pluginId, versionName) {
     return `docs-${pluginId}-${versionName}`;
 }
+/**
+ * Gets the relevant context information for contextual search.
+ *
+ * The value is generic and not coupled to Algolia/DocSearch, since we may want
+ * to support multiple search engines, or allowing users to use their own search
+ * engine solution.
+ */
+export function useContextualSearchFilters() {
+    const { i18n } = useDocusaurusContext();
+    const allDocsData = useAllDocsData();
+    const activePluginAndVersion = useActivePluginAndVersion();
+    const docsPreferredVersionByPluginId = useDocsPreferredVersionByPluginId();
+    // This can't use more specialized hooks because we are mapping over all
+    // plugin instances.
+    function getDocPluginTags(pluginId) {
+        const activeVersion = activePluginAndVersion?.activePlugin.pluginId === pluginId
+            ? activePluginAndVersion.activeVersion
+            : undefined;
+        const preferredVersion = docsPreferredVersionByPluginId[pluginId];
+        const latestVersion = allDocsData[pluginId].versions.find((v) => v.isLast);
+        const version = activeVersion ?? preferredVersion ?? latestVersion;
+        return docVersionSearchTag(pluginId, version.name);
+    }
+    const tags = [
+        DEFAULT_SEARCH_TAG,
+        ...Object.keys(allDocsData).map(getDocPluginTags),
+    ];
+    return {
+        locale: i18n.currentLocale,
+        tags,
+    };
+}
+//# sourceMappingURL=searchUtils.js.map

package/lib/utils/searchUtils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"searchUtils.js","sourceRoot":"","sources":["../../src/utils/searchUtils.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EACL,cAAc,EACd,yBAAyB,GAC1B,MAAM,wCAAwC,CAAC;AAChD,OAAO,oBAAoB,MAAM,kCAAkC,CAAC;AACpE,OAAO,EAAC,iCAAiC,EAAC,MAAM,kCAAkC,CAAC;AAEnF,MAAM,CAAC,MAAM,kBAAkB,GAAG,SAAS,CAAC;AAE5C,uDAAuD;AACvD,MAAM,UAAU,mBAAmB,CACjC,QAAgB,EAChB,WAAmB;IAEnB,OAAO,QAAQ,QAAQ,IAAI,WAAW,EAAE,CAAC;AAC3C,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,0BAA0B;IACxC,MAAM,EAAC,IAAI,EAAC,GAAG,oBAAoB,EAAE,CAAC;IACtC,MAAM,WAAW,GAAG,cAAc,EAAE,CAAC;IACrC,MAAM,sBAAsB,GAAG,yBAAyB,EAAE,CAAC;IAC3D,MAAM,8BAA8B,GAAG,iCAAiC,EAAE,CAAC;IAE3E,wEAAwE;IACxE,oBAAoB;IACpB,SAAS,gBAAgB,CAAC,QAAgB;QACxC,MAAM,aAAa,GACjB,sBAAsB,EAAE,YAAY,CAAC,QAAQ,KAAK,QAAQ;YACxD,CAAC,CAAC,sBAAsB,CAAC,aAAa;YACtC,CAAC,CAAC,SAAS,CAAC;QAEhB,MAAM,gBAAgB,GAAG,8BAA8B,CAAC,QAAQ,CAAC,CAAC;QAElE,MAAM,aAAa,GAAG,WAAW,CAAC,QAAQ,CAAE,CAAC,QAAQ,CAAC,IAAI,CACxD,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,CACf,CAAC;QAEH,MAAM,OAAO,GAAG,aAAa,IAAI,gBAAgB,IAAI,aAAa,CAAC;QAEnE,OAAO,mBAAmB,CAAC,QAAQ,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IACrD,CAAC;IAED,MAAM,IAAI,GAAG;QACX,kBAAkB;QAClB,GAAG,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,GAAG,CAAC,gBAAgB,CAAC;KAClD,CAAC;IAEF,OAAO;QACL,MAAM,EAAE,IAAI,CAAC,aAAa;QAC1B,IAAI;KACL,CAAC;AACJ,CAAC"}

package/lib/utils/storageUtils.d.ts

@@ -6,20 +6,28 @@
  */
 declare const StorageTypes: readonly ["localStorage", "sessionStorage", "none"];
 export declare type StorageType = typeof StorageTypes[number];
-export interface StorageSlot {
+export declare type StorageSlot = {
     get: () => string | null;
     set: (value: string) => void;
     del: () => void;
-}
+};
 /**
- * Creates an object for accessing a particular key in localStorage.
+ * Creates an interface to work on a particular key in the storage model.
+ * Note that this function only initializes the interface, but doesn't allocate
+ * anything by itself (i.e. no side-effects).
+ *
+ * The API is fail-safe, since usage of browser storage should be considered
+ * unreliable. Local storage might simply be unavailable (iframe + browser
+ * security) or operations might fail individually. Please assume that using
+ * this API can be a no-op. See also https://github.com/facebook/docusaurus/issues/6036
  */
-export declare const createStorageSlot: (key: string, options?: {
-    persistence?: "localStorage" | "none" | "sessionStorage" | undefined;
-} | undefined) => StorageSlot;
+export declare function createStorageSlot(key: string, options?: {
+    persistence?: StorageType;
+}): StorageSlot;
 /**
- * Returns a list of all the keys currently stored in browser storage
+ * Returns a list of all the keys currently stored in browser storage,
  * or an empty list if browser storage can't be accessed.
  */
 export declare function listStorageKeys(storageType?: StorageType): string[];
 export {};
+//# sourceMappingURL=storageUtils.d.ts.map

package/lib/utils/storageUtils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storageUtils.d.ts","sourceRoot":"","sources":["../../src/utils/storageUtils.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,QAAA,MAAM,YAAY,qDAAsD,CAAC;AAEzE,oBAAY,WAAW,GAAG,OAAO,YAAY,CAAC,MAAM,CAAC,CAAC;AA+CtD,oBAAY,WAAW,GAAG;IACxB,GAAG,EAAE,MAAM,MAAM,GAAG,IAAI,CAAC;IACzB,GAAG,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAC7B,GAAG,EAAE,MAAM,IAAI,CAAC;CACjB,CAAC;AAuBF;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE;IAAC,WAAW,CAAC,EAAE,WAAW,CAAA;CAAC,GACpC,WAAW,CAmCb;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,WAAW,GAAE,WAAgC,GAC5C,MAAM,EAAE,CAcV"}

package/lib/utils/storageUtils.js

@@ -6,8 +6,12 @@
  */
 const StorageTypes = ['localStorage', 'sessionStorage', 'none'];
 const DefaultStorageType = 'localStorage';
-// Will return null browser storage is unavailable (like running Docusaurus in iframe)
-// See https://github.com/facebook/docusaurus/pull/4501
+/**
+ * Will return `null` if browser storage is unavailable (like running Docusaurus
+ * in an iframe). This should NOT be called in SSR.
+ *
+ * @see https://github.com/facebook/docusaurus/pull/4501
+ */
 function getBrowserStorage(storageType = DefaultStorageType) {
     if (typeof window === 'undefined') {
         throw new Error('Browser storage is not available on Node.js/Docusaurus SSR process.');
@@ -15,21 +19,20 @@ function getBrowserStorage(storageType = DefaultStorageType) {
     if (storageType === 'none') {
         return null;
     }
-    else {
-        try {
-            return window[storageType];
-        }
-        catch (e) {
-            logOnceBrowserStorageNotAvailableWarning(e);
-            return null;
-        }
+    try {
+        return window[storageType];
+    }
+    catch (err) {
+        logOnceBrowserStorageNotAvailableWarning(err);
+        return null;
     }
 }
+let hasLoggedBrowserStorageNotAvailableWarning = false;
 /**
- * Poor man's memoization to avoid logging multiple times the same warning
- * Sometimes, localStorage/sessionStorage is unavailable due to browser policies
+ * Poor man's memoization to avoid logging multiple times the same warning.
+ * Sometimes, `localStorage`/`sessionStorage` is unavailable due to browser
+ * policies.
  */
-let hasLoggedBrowserStorageNotAvailableWarning = false;
 function logOnceBrowserStorageNotAvailableWarning(error) {
     if (!hasLoggedBrowserStorageNotAvailableWarning) {
         console.warn(`Docusaurus browser storage is not available.
@@ -42,7 +45,7 @@ const NoopStorageSlot = {
     set: () => { },
     del: () => { },
 };
-//  Fail-fast, as storage APIs should not be used during the SSR process
+// Fail-fast, as storage APIs should not be used during the SSR process
 function createServerStorageSlot(key) {
     function throwError() {
         throw new Error(`Illegal storage API usage for storage key "${key}".
@@ -56,24 +59,53 @@ Please only call storage APIs in effects and event handlers.`);
     };
 }
 /**
- * Creates an object for accessing a particular key in localStorage.
+ * Creates an interface to work on a particular key in the storage model.
+ * Note that this function only initializes the interface, but doesn't allocate
+ * anything by itself (i.e. no side-effects).
+ *
+ * The API is fail-safe, since usage of browser storage should be considered
+ * unreliable. Local storage might simply be unavailable (iframe + browser
+ * security) or operations might fail individually. Please assume that using
+ * this API can be a no-op. See also https://github.com/facebook/docusaurus/issues/6036
  */
-export const createStorageSlot = (key, options) => {
+export function createStorageSlot(key, options) {
     if (typeof window === 'undefined') {
         return createServerStorageSlot(key);
     }
-    const browserStorage = getBrowserStorage(options === null || options === void 0 ? void 0 : options.persistence);
+    const browserStorage = getBrowserStorage(options?.persistence);
     if (browserStorage === null) {
         return NoopStorageSlot;
     }
     return {
-        get: () => browserStorage.getItem(key),
-        set: (value) => browserStorage.setItem(key, value),
-        del: () => browserStorage.removeItem(key),
+        get: () => {
+            try {
+                return browserStorage.getItem(key);
+            }
+            catch (err) {
+                console.error(`Docusaurus storage error, can't get key=${key}`, err);
+                return null;
+            }
+        },
+        set: (value) => {
+            try {
+                browserStorage.setItem(key, value);
+            }
+            catch (err) {
+                console.error(`Docusaurus storage error, can't set ${key}=${value}`, err);
+            }
+        },
+        del: () => {
+            try {
+                browserStorage.removeItem(key);
+            }
+            catch (err) {
+                console.error(`Docusaurus storage error, can't delete key=${key}`, err);
+            }
+        },
     };
-};
+}
 /**
- * Returns a list of all the keys currently stored in browser storage
+ * Returns a list of all the keys currently stored in browser storage,
  * or an empty list if browser storage can't be accessed.
  */
 export function listStorageKeys(storageType = DefaultStorageType) {
@@ -90,3 +122,4 @@ export function listStorageKeys(storageType = DefaultStorageType) {
     }
     return keys;
 }
+//# sourceMappingURL=storageUtils.js.map

package/lib/utils/storageUtils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"storageUtils.js","sourceRoot":"","sources":["../../src/utils/storageUtils.ts"],"names":[],"mappings":"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"}

package/lib/utils/tagsUtils.d.ts

@@ -0,0 +1,18 @@
+/**
+ * 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 { TagsListItem } from '@docusaurus/utils';
+export declare const translateTagsPageTitle: () => string;
+export declare type TagLetterEntry = {
+    letter: string;
+    tags: TagsListItem[];
+};
+/**
+ * Takes a list of tags (as provided by the content plugins), and groups them by
+ * their initials.
+ */
+export declare function listTagsByLetters(tags: readonly TagsListItem[]): TagLetterEntry[];
+//# sourceMappingURL=tagsUtils.d.ts.map

package/lib/utils/tagsUtils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tagsUtils.d.ts","sourceRoot":"","sources":["../../src/utils/tagsUtils.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,mBAAmB,CAAC;AAEpD,eAAO,MAAM,sBAAsB,QAAO,MAKtC,CAAC;AAEL,oBAAY,cAAc,GAAG;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,YAAY,EAAE,CAAA;CAAC,CAAC;AAMpE;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,SAAS,YAAY,EAAE,GAC5B,cAAc,EAAE,CAoBlB"}

package/lib/utils/tagsUtils.js

@@ -0,0 +1,36 @@
+/**
+ * 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 { translate } from '@docusaurus/Translate';
+export const translateTagsPageTitle = () => translate({
+    id: 'theme.tags.tagsPageTitle',
+    message: 'Tags',
+    description: 'The title of the tag list page',
+});
+function getTagLetter(tag) {
+    return tag[0].toUpperCase();
+}
+/**
+ * Takes a list of tags (as provided by the content plugins), and groups them by
+ * their initials.
+ */
+export function listTagsByLetters(tags) {
+    const groups = {};
+    Object.values(tags).forEach((tag) => {
+        const initial = getTagLetter(tag.label);
+        groups[initial] ??= [];
+        groups[initial].push(tag);
+    });
+    return (Object.entries(groups)
+        // Sort letters
+        .sort(([letter1], [letter2]) => letter1.localeCompare(letter2))
+        .map(([letter, letterTags]) => {
+        // Sort tags inside a letter
+        const sortedTags = letterTags.sort((tag1, tag2) => tag1.label.localeCompare(tag2.label));
+        return { letter, tags: sortedTags };
+    }));
+}
+//# sourceMappingURL=tagsUtils.js.map

package/lib/utils/tagsUtils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tagsUtils.js","sourceRoot":"","sources":["../../src/utils/tagsUtils.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAC,SAAS,EAAC,MAAM,uBAAuB,CAAC;AAGhD,MAAM,CAAC,MAAM,sBAAsB,GAAG,GAAW,EAAE,CACjD,SAAS,CAAC;IACR,EAAE,EAAE,0BAA0B;IAC9B,OAAO,EAAE,MAAM;IACf,WAAW,EAAE,gCAAgC;CAC9C,CAAC,CAAC;AAIL,SAAS,YAAY,CAAC,GAAW;IAC/B,OAAO,GAAG,CAAC,CAAC,CAAE,CAAC,WAAW,EAAE,CAAC;AAC/B,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAC/B,IAA6B;IAE7B,MAAM,MAAM,GAAwC,EAAE,CAAC;IACvD,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,OAAO,CAAC,CAAC,GAAG,EAAE,EAAE;QAClC,MAAM,OAAO,GAAG,YAAY,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QACxC,MAAM,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;QACvB,MAAM,CAAC,OAAO,CAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC7B,CAAC,CAAC,CAAC;IAEH,OAAO,CACL,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC;QACpB,eAAe;SACd,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,OAAO,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC;SAC9D,GAAG,CAAC,CAAC,CAAC,MAAM,EAAE,UAAU,CAAC,EAAE,EAAE;QAC5B,4BAA4B;QAC5B,MAAM,UAAU,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,IAAI,EAAE,EAAE,CAChD,IAAI,CAAC,KAAK,CAAC,aAAa,CAAC,IAAI,CAAC,KAAK,CAAC,CACrC,CAAC;QACF,OAAO,EAAC,MAAM,EAAE,IAAI,EAAE,UAAU,EAAC,CAAC;IACpC,CAAC,CAAC,CACL,CAAC;AACJ,CAAC"}

package/lib/utils/tocUtils.d.ts

@@ -0,0 +1,36 @@
+/**
+ * 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 { TOCItem } from '@docusaurus/mdx-loader';
+export declare type TOCTreeNode = {
+    readonly value: string;
+    readonly id: string;
+    readonly level: number;
+    readonly children: readonly TOCTreeNode[];
+};
+/**
+ * Takes a flat TOC list (from the MDX loader) and treeifies it into what the
+ * TOC components expect. Memoized for performance.
+ */
+export declare function useTreeifiedTOC(toc: TOCItem[]): readonly TOCTreeNode[];
+/**
+ * Takes a flat TOC list (from the MDX loader) and treeifies it into what the
+ * TOC components expect, applying the `minHeadingLevel` and `maxHeadingLevel`.
+ * Memoized for performance.
+ *
+ * **Important**: this is not the same as `useTreeifiedTOC(toc.filter(...))`,
+ * because we have to filter the TOC after it has been treeified. This is mostly
+ * to ensure that weird TOC structures preserve their semantics. For example, an
+ * h3-h2-h4 sequence should not be treeified as an "h3 > h4" hierarchy with
+ * min=3, max=4, but should rather be "[h3, h4]" (since the h2 heading has split
+ * the two headings and they are not parent-children)
+ */
+export declare function useFilteredAndTreeifiedTOC({ toc, minHeadingLevel, maxHeadingLevel, }: {
+    toc: readonly TOCItem[];
+    minHeadingLevel: number;
+    maxHeadingLevel: number;
+}): readonly TOCTreeNode[];
+//# sourceMappingURL=tocUtils.d.ts.map

package/lib/utils/tocUtils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tocUtils.d.ts","sourceRoot":"","sources":["../../src/utils/tocUtils.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAC,OAAO,EAAC,MAAM,wBAAwB,CAAC;AAEpD,oBAAY,WAAW,GAAG;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,EAAE,SAAS,WAAW,EAAE,CAAC;CAC3C,CAAC;AAuCF;;;GAGG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,SAAS,WAAW,EAAE,CAEtE;AAiCD;;;;;;;;;;;GAWG;AACH,wBAAgB,0BAA0B,CAAC,EACzC,GAAG,EACH,eAAe,EACf,eAAe,GAChB,EAAE;IACD,GAAG,EAAE,SAAS,OAAO,EAAE,CAAC;IACxB,eAAe,EAAE,MAAM,CAAC;IACxB,eAAe,EAAE,MAAM,CAAC;CACzB,GAAG,SAAS,WAAW,EAAE,CAKzB"}

package/lib/utils/tocUtils.js

@@ -0,0 +1,84 @@
+/**
+ * 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';
+function treeifyTOC(flatTOC) {
+    const headings = flatTOC.map((heading) => ({
+        ...heading,
+        parentIndex: -1,
+        children: [],
+    }));
+    // Keep track of which previous index would be the current heading's direct
+    // parent. Each entry <i> is the last index of the `headings` array at heading
+    // level <i>. We will modify these indices as we iterate through all headings.
+    // e.g. if an ### H3 was last seen at index 2, then prevIndexForLevel[3] === 2
+    // indices 0 and 1 will remain unused.
+    const prevIndexForLevel = Array(7).fill(-1);
+    headings.forEach((curr, currIndex) => {
+        // Take the last seen index for each ancestor level. the highest index will
+        // be the direct ancestor of the current heading.
+        const ancestorLevelIndexes = prevIndexForLevel.slice(2, curr.level);
+        curr.parentIndex = Math.max(...ancestorLevelIndexes);
+        // Mark that curr.level was last seen at the current index.
+        prevIndexForLevel[curr.level] = currIndex;
+    });
+    const rootNodes = [];
+    // For a given parentIndex, add each Node into that parent's `children` array
+    headings.forEach((heading) => {
+        const { parentIndex, ...rest } = heading;
+        if (parentIndex >= 0) {
+            headings[parentIndex].children.push(rest);
+        }
+        else {
+            rootNodes.push(rest);
+        }
+    });
+    return rootNodes;
+}
+/**
+ * Takes a flat TOC list (from the MDX loader) and treeifies it into what the
+ * TOC components expect. Memoized for performance.
+ */
+export function useTreeifiedTOC(toc) {
+    return useMemo(() => treeifyTOC(toc), [toc]);
+}
+function filterTOC({ toc, minHeadingLevel, maxHeadingLevel, }) {
+    function isValid(item) {
+        return item.level >= minHeadingLevel && item.level <= maxHeadingLevel;
+    }
+    return toc.flatMap((item) => {
+        const filteredChildren = filterTOC({
+            toc: item.children,
+            minHeadingLevel,
+            maxHeadingLevel,
+        });
+        if (isValid(item)) {
+            return [
+                {
+                    ...item,
+                    children: filteredChildren,
+                },
+            ];
+        }
+        return filteredChildren;
+    });
+}
+/**
+ * Takes a flat TOC list (from the MDX loader) and treeifies it into what the
+ * TOC components expect, applying the `minHeadingLevel` and `maxHeadingLevel`.
+ * Memoized for performance.
+ *
+ * **Important**: this is not the same as `useTreeifiedTOC(toc.filter(...))`,
+ * because we have to filter the TOC after it has been treeified. This is mostly
+ * to ensure that weird TOC structures preserve their semantics. For example, an
+ * h3-h2-h4 sequence should not be treeified as an "h3 > h4" hierarchy with
+ * min=3, max=4, but should rather be "[h3, h4]" (since the h2 heading has split
+ * the two headings and they are not parent-children)
+ */
+export function useFilteredAndTreeifiedTOC({ toc, minHeadingLevel, maxHeadingLevel, }) {
+    return useMemo(() => filterTOC({ toc: treeifyTOC(toc), minHeadingLevel, maxHeadingLevel }), [toc, minHeadingLevel, maxHeadingLevel]);
+}
+//# sourceMappingURL=tocUtils.js.map

package/lib/utils/tocUtils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tocUtils.js","sourceRoot":"","sources":["../../src/utils/tocUtils.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAC,OAAO,EAAC,MAAM,OAAO,CAAC;AAU9B,SAAS,UAAU,CAAC,OAA2B;IAC7C,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;QACzC,GAAG,OAAO;QACV,WAAW,EAAE,CAAC,CAAC;QACf,QAAQ,EAAE,EAAmB;KAC9B,CAAC,CAAC,CAAC;IAEJ,2EAA2E;IAC3E,8EAA8E;IAC9E,8EAA8E;IAC9E,8EAA8E;IAC9E,sCAAsC;IACtC,MAAM,iBAAiB,GAAG,KAAK,CAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;IAEpD,QAAQ,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,SAAS,EAAE,EAAE;QACnC,2EAA2E;QAC3E,iDAAiD;QACjD,MAAM,oBAAoB,GAAG,iBAAiB,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC;QACpE,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,oBAAoB,CAAC,CAAC;QACrD,2DAA2D;QAC3D,iBAAiB,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,SAAS,CAAC;IAC5C,CAAC,CAAC,CAAC;IAEH,MAAM,SAAS,GAAkB,EAAE,CAAC;IAEpC,6EAA6E;IAC7E,QAAQ,CAAC,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;QAC3B,MAAM,EAAC,WAAW,EAAE,GAAG,IAAI,EAAC,GAAG,OAAO,CAAC;QACvC,IAAI,WAAW,IAAI,CAAC,EAAE;YACpB,QAAQ,CAAC,WAAW,CAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;SAC5C;aAAM;YACL,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;SACtB;IACH,CAAC,CAAC,CAAC;IACH,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,GAAc;IAC5C,OAAO,OAAO,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;AAC/C,CAAC;AAED,SAAS,SAAS,CAAC,EACjB,GAAG,EACH,eAAe,EACf,eAAe,GAKhB;IACC,SAAS,OAAO,CAAC,IAAiB;QAChC,OAAO,IAAI,CAAC,KAAK,IAAI,eAAe,IAAI,IAAI,CAAC,KAAK,IAAI,eAAe,CAAC;IACxE,CAAC;IAED,OAAO,GAAG,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,EAAE;QAC1B,MAAM,gBAAgB,GAAG,SAAS,CAAC;YACjC,GAAG,EAAE,IAAI,CAAC,QAAQ;YAClB,eAAe;YACf,eAAe;SAChB,CAAC,CAAC;QACH,IAAI,OAAO,CAAC,IAAI,CAAC,EAAE;YACjB,OAAO;gBACL;oBACE,GAAG,IAAI;oBACP,QAAQ,EAAE,gBAAgB;iBAC3B;aACF,CAAC;SACH;QACD,OAAO,gBAAgB,CAAC;IAC1B,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,0BAA0B,CAAC,EACzC,GAAG,EACH,eAAe,EACf,eAAe,GAKhB;IACC,OAAO,OAAO,CACZ,GAAG,EAAE,CAAC,SAAS,CAAC,EAAC,GAAG,EAAE,UAAU,CAAC,GAAG,CAAC,EAAE,eAAe,EAAE,eAAe,EAAC,CAAC,EACzE,CAAC,GAAG,EAAE,eAAe,EAAE,eAAe,CAAC,CACxC,CAAC;AACJ,CAAC"}