docusaurus-theme-openapi-docs 5.0.2 → 5.1.0

package/src/theme/utils/scrollUtils.tsx

@@ -0,0 +1,153 @@
+/* ============================================================================
+ * Portions Copyright (c) Meta Platforms, Inc. and affiliates.
+ * Portions Copyright (c) Palo Alto Networks
+ *
+ * Vendored subset of @docusaurus/theme-common/src/utils/scrollUtils.tsx (MIT)
+ * to remove the dependency on @docusaurus/theme-common/internal. Only the
+ * ScrollControllerProvider + useScrollPositionBlocker surface is kept, since
+ * that's all our tab renderers need. The ScrollControllerProvider must be
+ * mounted in the React tree above any consumer of useScrollPositionBlocker
+ * (see ApiItem/index.tsx).
+ * See: https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/issues/1140
+ *
+ * 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,
+  useMemo,
+  useRef,
+  type ReactNode,
+} from "react";
+
+import useIsomorphicLayoutEffect from "@docusaurus/useIsomorphicLayoutEffect";
+import { ReactContextError } from "@docusaurus/theme-common";
+
+type ScrollController = {
+  scrollEventsEnabledRef: React.RefObject<boolean>;
+  enableScrollEvents: () => void;
+  disableScrollEvents: () => void;
+};
+
+function useScrollControllerContextValue(): ScrollController {
+  const scrollEventsEnabledRef = useRef(true);
+
+  return useMemo(
+    () => ({
+      scrollEventsEnabledRef,
+      enableScrollEvents: () => {
+        scrollEventsEnabledRef.current = true;
+      },
+      disableScrollEvents: () => {
+        scrollEventsEnabledRef.current = false;
+      },
+    }),
+    []
+  );
+}
+
+const ScrollMonitorContext = React.createContext<ScrollController | undefined>(
+  undefined
+);
+
+export function ScrollControllerProvider({
+  children,
+}: {
+  children: ReactNode;
+}): ReactNode {
+  const value = useScrollControllerContextValue();
+  return (
+    <ScrollMonitorContext.Provider value={value}>
+      {children}
+    </ScrollMonitorContext.Provider>
+  );
+}
+
+function useScrollController(): ScrollController {
+  const context = useContext(ScrollMonitorContext);
+  if (context == null) {
+    throw new ReactContextError("ScrollControllerProvider");
+  }
+  return context;
+}
+
+type UseScrollPositionSaver = {
+  save: (elem: HTMLElement) => void;
+  restore: () => { restored: boolean };
+};
+
+function useScrollPositionSaver(): UseScrollPositionSaver {
+  const lastElementRef = useRef<{ elem: HTMLElement | null; top: number }>({
+    elem: null,
+    top: 0,
+  });
+
+  const save = useCallback((elem: HTMLElement) => {
+    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]);
+}
+
+export function useScrollPositionBlocker(): {
+  blockElementScrollPositionUntilNextRender: (el: HTMLElement) => void;
+} {
+  const scrollController = useScrollController();
+  const scrollPositionSaver = useScrollPositionSaver();
+
+  const nextLayoutEffectCallbackRef = useRef<(() => void) | undefined>(
+    undefined
+  );
+
+  const blockElementScrollPositionUntilNextRender = useCallback(
+    (el: HTMLElement) => {
+      scrollPositionSaver.save(el);
+      scrollController.disableScrollEvents();
+      nextLayoutEffectCallbackRef.current = () => {
+        const { restored } = scrollPositionSaver.restore();
+        nextLayoutEffectCallbackRef.current = undefined;
+
+        if (restored) {
+          const handleScrollRestoreEvent = () => {
+            scrollController.enableScrollEvents();
+            window.removeEventListener("scroll", handleScrollRestoreEvent);
+          };
+          window.addEventListener("scroll", handleScrollRestoreEvent);
+        } else {
+          scrollController.enableScrollEvents();
+        }
+      };
+    },
+    [scrollController, scrollPositionSaver]
+  );
+
+  useIsomorphicLayoutEffect(() => {
+    queueMicrotask(() => nextLayoutEffectCallbackRef.current?.());
+  });
+
+  return {
+    blockElementScrollPositionUntilNextRender,
+  };
+}

package/src/theme/utils/tabsUtils.tsx

@@ -0,0 +1,329 @@
+/* ============================================================================
+ * Portions Copyright (c) Meta Platforms, Inc. and affiliates.
+ * Portions Copyright (c) Palo Alto Networks
+ *
+ * Vendored from @docusaurus/theme-common/src/utils/tabsUtils.tsx (MIT) to
+ * remove the dependency on @docusaurus/theme-common/internal. The
+ * useQueryStringValue dependency from theme-common's historyUtils is inlined
+ * below to avoid pulling another internal module.
+ * See: https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/issues/1140
+ *
+ * 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,
+  isValidElement,
+  useCallback,
+  useMemo,
+  useState,
+  useSyncExternalStore,
+  type ReactElement,
+  type ReactNode,
+} from "react";
+
+import { useHistory } from "@docusaurus/router";
+import { duplicates, useStorageSlot } from "@docusaurus/theme-common";
+import useIsomorphicLayoutEffect from "@docusaurus/useIsomorphicLayoutEffect";
+
+import { ScrollControllerProvider } from "./scrollUtils";
+
+export interface TabValue {
+  readonly value: string;
+  readonly label?: string;
+  readonly attributes?: { [key: string]: unknown };
+  readonly default?: boolean;
+}
+
+export interface TabsProps {
+  readonly lazy?: boolean;
+  readonly block?: boolean;
+  readonly children: ReactNode;
+  readonly defaultValue?: string | null;
+  readonly values?: readonly TabValue[];
+  readonly groupId?: string;
+  readonly className?: string;
+  readonly queryString?: string | boolean;
+}
+
+// Extended Tabs type used across the OpenAPI theme; preserves the historical
+// shape that included an optional `length` field.
+export interface TabProps extends TabsProps {
+  length?: number;
+}
+
+export interface TabItemProps {
+  readonly children: ReactNode;
+  readonly value: string;
+  readonly default?: boolean;
+  readonly label?: string;
+  readonly className?: string;
+  readonly attributes?: { [key: string]: unknown };
+}
+
+export function sanitizeTabsChildren(children: ReactNode): ReactNode {
+  return React.Children.toArray(children).filter((child) => child !== "\n");
+}
+
+function extractChildrenTabValues(children: ReactNode): TabValue[] {
+  function isTabItemWithValueProp(
+    comp: ReactElement
+  ): comp is ReactElement<TabItemProps> {
+    const { props } = comp;
+    return !!props && typeof props === "object" && "value" in props;
+  }
+
+  const elements = React.Children.toArray(children).flatMap((child) => {
+    if (!child) {
+      return [];
+    }
+    if (isValidElement(child) && isTabItemWithValueProp(child)) {
+      return [child];
+    }
+    const badChildTypeName =
+      // @ts-expect-error: guarding against unexpected cases
+      typeof child.type === "string" ? child.type : child.type.name;
+    throw new Error(
+      `Docusaurus error: Bad <Tabs> child <${badChildTypeName}>: all children of the <Tabs> component should be <TabItem>, and every <TabItem> should have a unique "value" prop.
+If you do not want to pass on a "value" prop to the direct children of <Tabs>, you can also pass an explicit <Tabs values={...}> prop.`
+    );
+  });
+
+  return elements.map(
+    ({ props: { value, label, attributes, default: isDefault } }) => ({
+      value,
+      label,
+      attributes,
+      default: isDefault,
+    })
+  );
+}
+
+function ensureNoDuplicateValue(values: readonly TabValue[]) {
+  const dup = duplicates(values, (a, b) => a.value === b.value);
+  if (dup.length > 0) {
+    throw new Error(
+      `Docusaurus error: Duplicate values "${dup
+        .map((a) => `'${a.value}'`)
+        .join(", ")}" found in <Tabs>. Every value needs to be unique.`
+    );
+  }
+}
+
+function useTabValues(
+  props: Pick<TabsProps, "values" | "children">
+): readonly TabValue[] {
+  const { values: valuesProp, children } = props;
+  return useMemo(() => {
+    const values = valuesProp ?? extractChildrenTabValues(children);
+    ensureNoDuplicateValue(values);
+    return values;
+  }, [valuesProp, children]);
+}
+
+function isValidValue({
+  value,
+  tabValues,
+}: {
+  value: string | null | undefined;
+  tabValues: readonly TabValue[];
+}) {
+  return tabValues.some((a) => a.value === value);
+}
+
+function getInitialStateValue({
+  defaultValue,
+  tabValues,
+}: {
+  defaultValue: TabsProps["defaultValue"];
+  tabValues: readonly TabValue[];
+}): string {
+  if (tabValues.length === 0) {
+    throw new Error(
+      "Docusaurus error: the <Tabs> component requires at least one <TabItem> children component"
+    );
+  }
+  if (defaultValue) {
+    if (!isValidValue({ value: defaultValue, tabValues })) {
+      throw new Error(
+        `Docusaurus error: The <Tabs> has a defaultValue "${defaultValue}" but none of its children has the corresponding value. Available values are: ${tabValues
+          .map((a) => a.value)
+          .join(
+            ", "
+          )}. If you intend to show no default tab, use defaultValue={null} instead.`
+      );
+    }
+    return defaultValue;
+  }
+  const defaultTabValue =
+    tabValues.find((tabValue) => tabValue.default) ?? tabValues[0];
+  if (!defaultTabValue) {
+    throw new Error("Unexpected error: 0 tabValues");
+  }
+  return defaultTabValue.value;
+}
+
+function getStorageKey(groupId: string | undefined) {
+  if (!groupId) {
+    return null;
+  }
+  return `docusaurus.tab.${groupId}`;
+}
+
+function getQueryStringKey({
+  queryString = false,
+  groupId,
+}: Pick<TabsProps, "queryString" | "groupId">) {
+  if (typeof queryString === "string") {
+    return queryString;
+  }
+  if (queryString === false) {
+    return null;
+  }
+  if (queryString === true && !groupId) {
+    throw new Error(
+      `Docusaurus error: The <Tabs> component groupId prop is required if queryString=true, because this value is used as the search param name. You can also provide an explicit value such as queryString="my-search-param".`
+    );
+  }
+  return groupId ?? null;
+}
+
+// Inlined from @docusaurus/theme-common/internal historyUtils.useQueryStringValue
+function useQueryStringValue(key: string | null): string | null {
+  const history = useHistory();
+  return useSyncExternalStore(
+    history.listen,
+    () =>
+      key === null
+        ? null
+        : new URLSearchParams(history.location.search).get(key),
+    () => null
+  );
+}
+
+function useTabQueryString({
+  queryString = false,
+  groupId,
+}: Pick<TabsProps, "queryString" | "groupId">) {
+  const history = useHistory();
+  const key = getQueryStringKey({ queryString, groupId });
+  const value = useQueryStringValue(key);
+
+  const setValue = useCallback(
+    (newValue: string) => {
+      if (!key) {
+        return;
+      }
+      const searchParams = new URLSearchParams(history.location.search);
+      searchParams.set(key, newValue);
+      history.replace({ ...history.location, search: searchParams.toString() });
+    },
+    [key, history]
+  );
+
+  return [value, setValue] as const;
+}
+
+function useTabStorage({ groupId }: Pick<TabsProps, "groupId">) {
+  const key = getStorageKey(groupId);
+  const [value, storageSlot] = useStorageSlot(key);
+
+  const setValue = useCallback(
+    (newValue: string) => {
+      if (!key) {
+        return;
+      }
+      storageSlot.set(newValue);
+    },
+    [key, storageSlot]
+  );
+
+  return [value, setValue] as const;
+}
+
+type TabsContextValue = {
+  selectedValue: string;
+  selectValue: (value: string) => void;
+  tabValues: readonly TabValue[];
+  lazy: boolean;
+  block: boolean;
+};
+
+export function useTabsContextValue(props: TabsProps): TabsContextValue {
+  const { defaultValue, queryString = false, groupId } = props;
+  const tabValues = useTabValues(props);
+
+  const [selectedValue, setSelectedValue] = useState(() =>
+    getInitialStateValue({ defaultValue, tabValues })
+  );
+
+  const [queryStringValue, setQueryString] = useTabQueryString({
+    queryString,
+    groupId,
+  });
+
+  const [storageValue, setStorageValue] = useTabStorage({
+    groupId,
+  });
+
+  const valueToSync = (() => {
+    const value = queryStringValue ?? storageValue;
+    if (!isValidValue({ value, tabValues })) {
+      return null;
+    }
+    return value;
+  })();
+
+  useIsomorphicLayoutEffect(() => {
+    if (valueToSync) {
+      setSelectedValue(valueToSync);
+    }
+  }, [valueToSync]);
+
+  const selectValue = useCallback(
+    (newValue: string) => {
+      if (!isValidValue({ value: newValue, tabValues })) {
+        throw new Error(`Can't select invalid tab value=${newValue}`);
+      }
+      setSelectedValue(newValue);
+      setQueryString(newValue);
+      setStorageValue(newValue);
+    },
+    [setQueryString, setStorageValue, tabValues]
+  );
+
+  return {
+    selectedValue,
+    selectValue,
+    tabValues,
+    lazy: props.lazy ?? false,
+    block: props.block ?? false,
+  };
+}
+
+const TabsContext = createContext<TabsContextValue | null>(null);
+
+export function useTabs(): TabsContextValue {
+  const contextValue = React.useContext(TabsContext);
+  if (!contextValue) {
+    throw new Error("useTabsContext() must be used within a Tabs component");
+  }
+  return contextValue;
+}
+
+export function TabsProvider(props: {
+  children: ReactNode;
+  value: TabsContextValue;
+}): ReactNode {
+  // ScrollControllerProvider is mounted here so every tab consumer
+  // (our six OpenAPI tab variants + the swizzled @theme/Tabs) gets a working
+  // useScrollPositionBlocker without callers needing a separate provider.
+  return (
+    <ScrollControllerProvider>
+      <TabsContext.Provider value={props.value}>
+        {props.children}
+      </TabsContext.Provider>
+    </ScrollControllerProvider>
+  );
+}

package/src/theme/utils/useCodeWordWrap.ts

@@ -0,0 +1,110 @@
+/* ============================================================================
+ * Portions Copyright (c) Meta Platforms, Inc. and affiliates.
+ * Portions Copyright (c) Palo Alto Networks
+ *
+ * Vendored from @docusaurus/theme-common/src/hooks/useCodeWordWrap.ts (MIT)
+ * to remove the dependency on @docusaurus/theme-common/internal.
+ * See: https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/issues/1140
+ *
+ * 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, useRef, useState } from "react";
+import type { RefObject } from "react";
+
+import { useMutationObserver } from "./useMutationObserver";
+
+// Callback fires when the "hidden" attribute of a tabpanel changes
+// See https://github.com/facebook/docusaurus/pull/7485
+function useTabBecameVisibleCallback(
+  codeBlockRef: RefObject<HTMLPreElement | null>,
+  callback: () => void
+) {
+  const [hiddenTabElement, setHiddenTabElement] = useState<
+    Element | null | undefined
+  >();
+
+  const updateHiddenTabElement = useCallback(() => {
+    setHiddenTabElement(
+      codeBlockRef.current?.closest("[role=tabpanel][hidden]")
+    );
+  }, [codeBlockRef, setHiddenTabElement]);
+
+  useEffect(() => {
+    updateHiddenTabElement();
+  }, [updateHiddenTabElement]);
+
+  useMutationObserver(
+    hiddenTabElement,
+    (mutations: MutationRecord[]) => {
+      mutations.forEach((mutation) => {
+        if (
+          mutation.type === "attributes" &&
+          mutation.attributeName === "hidden"
+        ) {
+          callback();
+          updateHiddenTabElement();
+        }
+      });
+    },
+    {
+      attributes: true,
+      characterData: false,
+      childList: false,
+      subtree: false,
+    }
+  );
+}
+
+export type WordWrap = {
+  readonly codeBlockRef: RefObject<HTMLPreElement | null>;
+  readonly isEnabled: boolean;
+  readonly isCodeScrollable: boolean;
+  readonly toggle: () => void;
+};
+
+export function useCodeWordWrap(): WordWrap {
+  const [isEnabled, setIsEnabled] = useState(false);
+  const [isCodeScrollable, setIsCodeScrollable] = useState<boolean>(false);
+  const codeBlockRef = useRef<HTMLPreElement>(null);
+
+  const toggle = useCallback(() => {
+    const codeElement = codeBlockRef.current!.querySelector("code")!;
+
+    if (isEnabled) {
+      codeElement.removeAttribute("style");
+    } else {
+      codeElement.style.whiteSpace = "pre-wrap";
+      codeElement.style.overflowWrap = "anywhere";
+    }
+
+    setIsEnabled((value) => !value);
+  }, [codeBlockRef, isEnabled]);
+
+  const updateCodeIsScrollable = useCallback(() => {
+    const { scrollWidth, clientWidth } = codeBlockRef.current!;
+    const isScrollable =
+      scrollWidth > clientWidth ||
+      codeBlockRef.current!.querySelector("code")!.hasAttribute("style");
+    setIsCodeScrollable(isScrollable);
+  }, [codeBlockRef]);
+
+  useTabBecameVisibleCallback(codeBlockRef, updateCodeIsScrollable);
+
+  useEffect(() => {
+    updateCodeIsScrollable();
+  }, [isEnabled, updateCodeIsScrollable]);
+
+  useEffect(() => {
+    window.addEventListener("resize", updateCodeIsScrollable, {
+      passive: true,
+    });
+
+    return () => {
+      window.removeEventListener("resize", updateCodeIsScrollable);
+    };
+  }, [updateCodeIsScrollable]);
+
+  return { codeBlockRef, isEnabled, isCodeScrollable, toggle };
+}

package/src/theme/utils/useMutationObserver.ts

@@ -0,0 +1,43 @@
+/* ============================================================================
+ * Portions Copyright (c) Meta Platforms, Inc. and affiliates.
+ * Portions Copyright (c) Palo Alto Networks
+ *
+ * Vendored from @docusaurus/theme-common/src/hooks/useMutationObserver.ts (MIT)
+ * to remove the dependency on @docusaurus/theme-common/internal.
+ * See: https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/issues/1140
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ * ========================================================================== */
+
+import { useEffect } from "react";
+
+import { useEvent } from "@docusaurus/theme-common";
+
+import { useShallowMemoObject } from "./reactUtils";
+
+type Options = MutationObserverInit;
+
+const DefaultOptions: Options = {
+  attributes: true,
+  characterData: true,
+  childList: true,
+  subtree: true,
+};
+
+export function useMutationObserver(
+  target: Element | undefined | null,
+  callback: MutationCallback,
+  options: Options = DefaultOptions
+): void {
+  const stableCallback = useEvent(callback);
+  const stableOptions: Options = useShallowMemoObject(options);
+
+  useEffect(() => {
+    const observer = new MutationObserver(stableCallback);
+    if (target) {
+      observer.observe(target, stableOptions);
+    }
+    return () => observer.disconnect();
+  }, [target, stableCallback, stableOptions]);
+}