docusaurus-theme-openapi-docs 5.0.1 → 5.1.0

package/src/theme/SchemaExpansion/_SchemaExpansion.scss

@@ -0,0 +1,113 @@
+/* ============================================================================
+ * Copyright (c) Palo Alto Networks
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ * ========================================================================== */
+
+.openapi-schema-expansion {
+  position: relative;
+  display: inline-flex;
+  align-items: center;
+  margin-left: auto;
+}
+
+.openapi-schema-expansion__trigger {
+  appearance: none;
+  background: transparent;
+  border: none;
+  border-radius: var(--ifm-global-radius);
+  padding: 0;
+  width: 22px;
+  height: 22px;
+  flex: 0 0 22px;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  color: var(--ifm-color-emphasis-600);
+  line-height: 0;
+  opacity: 0.7;
+  transition:
+    opacity 0.12s ease,
+    background-color 0.12s ease,
+    color 0.12s ease;
+
+  &:hover {
+    opacity: 1;
+    background-color: var(--ifm-color-emphasis-200);
+    color: var(--ifm-color-emphasis-900);
+  }
+
+  &:focus-visible {
+    outline: 2px solid var(--ifm-color-primary);
+    outline-offset: 2px;
+    opacity: 1;
+  }
+
+  &[aria-expanded="true"] {
+    opacity: 1;
+    background-color: var(--ifm-color-emphasis-200);
+    color: var(--ifm-color-emphasis-900);
+  }
+}
+
+.openapi-schema-expansion__popover {
+  position: fixed;
+  z-index: 1000;
+  display: inline-flex;
+  align-items: center;
+  gap: 2px;
+  padding: 3px;
+  background-color: var(--ifm-background-surface-color);
+  border: 1px solid var(--ifm-color-emphasis-300);
+  border-radius: var(--ifm-global-radius);
+  box-shadow: var(--ifm-global-shadow-md);
+  white-space: nowrap;
+}
+
+.openapi-schema-expansion__option {
+  appearance: none;
+  background: transparent;
+  border: none;
+  border-radius: calc(var(--ifm-global-radius) - 2px);
+  padding: 2px 8px;
+  font-size: 0.8rem;
+  line-height: 1.4;
+  color: var(--ifm-color-emphasis-800);
+  transition:
+    background-color 0.12s ease,
+    color 0.12s ease;
+
+  &:hover {
+    background-color: var(--ifm-color-emphasis-200);
+  }
+
+  &:focus-visible {
+    outline: 2px solid var(--ifm-color-primary);
+    outline-offset: 1px;
+  }
+}
+
+.openapi-schema-expansion__option--active {
+  background-color: var(--ifm-color-primary);
+  color: var(--ifm-color-white);
+
+  &:hover {
+    background-color: var(--ifm-color-primary-dark);
+  }
+}
+
+.openapi-markdown__details-summary--with-control {
+  display: flex !important;
+  align-items: center;
+  gap: 0.5rem;
+
+  > h3,
+  > strong {
+    margin-bottom: 0;
+    display: inline-flex;
+    align-items: center;
+    flex-wrap: wrap;
+    gap: 0.4rem;
+  }
+}

package/src/theme/SchemaExpansion/context.tsx

@@ -0,0 +1,154 @@
+/* ============================================================================
+ * Copyright (c) Palo Alto Networks
+ *
+ * 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,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useState,
+} from "react";
+
+import useDocusaurusContext from "@docusaurus/useDocusaurusContext";
+import type { ThemeConfig } from "docusaurus-theme-openapi-docs/src/types";
+
+export const SCHEMA_EXPANSION_STORAGE_KEY =
+  "docusaurus-openapi-schema-expansion-level";
+
+export interface SchemaExpansionConfig {
+  enabled: boolean;
+  defaultLevel: number;
+  max: number;
+  persist: boolean;
+}
+
+interface SchemaExpansionContextValue {
+  config: SchemaExpansionConfig;
+  level: number;
+  setLevel: (next: number) => void;
+}
+
+const DEFAULT_CONFIG: SchemaExpansionConfig = {
+  enabled: false,
+  defaultLevel: 0,
+  max: 4,
+  persist: true,
+};
+
+const SchemaExpansionContext = createContext<SchemaExpansionContextValue>({
+  config: DEFAULT_CONFIG,
+  level: 0,
+  setLevel: () => {},
+});
+
+const SchemaDepthContext = createContext<number>(0);
+
+export function normalizeLevel(value: number | "all" | undefined): number {
+  if (value === "all") return Infinity;
+  if (typeof value === "number" && Number.isFinite(value) && value >= 0) {
+    return Math.floor(value);
+  }
+  return 0;
+}
+
+function readConfig(
+  themeConfig: ThemeConfig | undefined
+): SchemaExpansionConfig {
+  const raw = themeConfig?.api?.schemaExpansion;
+  if (!raw) return DEFAULT_CONFIG;
+  const enabled = raw.enabled ?? false;
+  return {
+    enabled,
+    defaultLevel: normalizeLevel(raw.default),
+    max: typeof raw.max === "number" && raw.max > 0 ? Math.floor(raw.max) : 4,
+    // Persistence only matters when the reader can change the level via the
+    // UI control. When the control is hidden, fall back to the configured
+    // default on every visit so it isn't shadowed by a stale localStorage
+    // value from a session where the control used to be enabled.
+    persist: enabled ? (raw.persist ?? true) : false,
+  };
+}
+
+function readPersistedLevel(): number | undefined {
+  if (typeof window === "undefined") return undefined;
+  try {
+    const stored = window.localStorage.getItem(SCHEMA_EXPANSION_STORAGE_KEY);
+    if (stored === null) return undefined;
+    if (stored === "all") return Infinity;
+    const parsed = parseInt(stored, 10);
+    return Number.isFinite(parsed) && parsed >= 0 ? parsed : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function writePersistedLevel(level: number): void {
+  if (typeof window === "undefined") return;
+  try {
+    const value = level === Infinity ? "all" : String(level);
+    window.localStorage.setItem(SCHEMA_EXPANSION_STORAGE_KEY, value);
+  } catch {
+    // ignore quota / disabled storage
+  }
+}
+
+export const SchemaExpansionProvider: React.FC<{
+  children: React.ReactNode;
+}> = ({ children }) => {
+  const { siteConfig } = useDocusaurusContext();
+  const themeConfig = siteConfig.themeConfig as ThemeConfig | undefined;
+  const config = useMemo(() => readConfig(themeConfig), [themeConfig]);
+
+  const [level, setLevelState] = useState<number>(config.defaultLevel);
+
+  useEffect(() => {
+    if (!config.persist) return;
+    const persisted = readPersistedLevel();
+    if (persisted !== undefined) {
+      setLevelState(persisted);
+    }
+  }, [config.persist]);
+
+  const setLevel = useCallback(
+    (next: number) => {
+      setLevelState(next);
+      if (config.persist) {
+        writePersistedLevel(next);
+      }
+    },
+    [config.persist]
+  );
+
+  const value = useMemo(
+    () => ({ config, level, setLevel }),
+    [config, level, setLevel]
+  );
+
+  return (
+    <SchemaExpansionContext.Provider value={value}>
+      {children}
+    </SchemaExpansionContext.Provider>
+  );
+};
+
+export const SchemaDepthProvider: React.FC<{
+  depth: number;
+  children: React.ReactNode;
+}> = ({ depth, children }) => (
+  <SchemaDepthContext.Provider value={depth}>
+    {children}
+  </SchemaDepthContext.Provider>
+);
+
+export function useSchemaExpansion(): SchemaExpansionContextValue {
+  return useContext(SchemaExpansionContext);
+}
+
+export function useSchemaDepth(): number {
+  return useContext(SchemaDepthContext);
+}

package/src/theme/SchemaExpansion/index.tsx

@@ -0,0 +1,236 @@
+/* ============================================================================
+ * Copyright (c) Palo Alto Networks
+ *
+ * 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,
+  useEffect,
+  useId,
+  useLayoutEffect,
+  useMemo,
+  useRef,
+  useState,
+} from "react";
+
+import { translate } from "@docusaurus/Translate";
+import clsx from "clsx";
+
+import { useSchemaExpansion } from "./context";
+
+export {
+  SchemaExpansionProvider,
+  SchemaDepthProvider,
+  useSchemaExpansion,
+  useSchemaDepth,
+  normalizeLevel,
+  SCHEMA_EXPANSION_STORAGE_KEY,
+} from "./context";
+
+const ALL_VALUE = Number.POSITIVE_INFINITY;
+
+const ExpandIcon: React.FC = () => (
+  <svg
+    aria-hidden="true"
+    focusable="false"
+    width="14"
+    height="14"
+    viewBox="0 0 16 16"
+    fill="none"
+    stroke="currentColor"
+    strokeWidth="1.6"
+    strokeLinecap="round"
+    strokeLinejoin="round"
+  >
+    <polyline points="4 6 8 2 12 6" />
+    <polyline points="4 10 8 14 12 10" />
+  </svg>
+);
+
+const SchemaExpansionControl: React.FC = () => {
+  const { config, level, setLevel } = useSchemaExpansion();
+  const [open, setOpen] = useState(false);
+  const [coords, setCoords] = useState<{ top: number; right: number } | null>(
+    null
+  );
+  const buttonRef = useRef<HTMLButtonElement | null>(null);
+  const popoverRef = useRef<HTMLDivElement | null>(null);
+  const optionRefs = useRef<Array<HTMLButtonElement | null>>([]);
+  const popoverId = useId();
+
+  const options = useMemo(() => {
+    const numbers = Array.from({ length: config.max + 1 }, (_, i) => i);
+    return [...numbers, ALL_VALUE];
+  }, [config.max]);
+
+  const activeIndex = useMemo(() => {
+    const idx = options.indexOf(level);
+    return idx >= 0 ? idx : 0;
+  }, [options, level]);
+
+  const updatePosition = useCallback(() => {
+    if (!buttonRef.current || typeof window === "undefined") return;
+    const rect = buttonRef.current.getBoundingClientRect();
+    setCoords({
+      top: rect.bottom + 4,
+      right: window.innerWidth - rect.right,
+    });
+  }, []);
+
+  useLayoutEffect(() => {
+    if (!open) return;
+    updatePosition();
+    const handleScroll = () => setOpen(false);
+    window.addEventListener("scroll", handleScroll, true);
+    window.addEventListener("resize", updatePosition);
+    return () => {
+      window.removeEventListener("scroll", handleScroll, true);
+      window.removeEventListener("resize", updatePosition);
+    };
+  }, [open, updatePosition]);
+
+  useEffect(() => {
+    if (!open) return;
+    optionRefs.current[activeIndex]?.focus();
+  }, [open, activeIndex]);
+
+  useEffect(() => {
+    if (!open) return;
+    const handlePointer = (event: MouseEvent) => {
+      const target = event.target as Node;
+      if (buttonRef.current?.contains(target)) return;
+      if (popoverRef.current?.contains(target)) return;
+      setOpen(false);
+    };
+    const handleKey = (event: KeyboardEvent) => {
+      if (event.key === "Escape") {
+        event.stopPropagation();
+        setOpen(false);
+        buttonRef.current?.focus();
+      }
+    };
+    document.addEventListener("mousedown", handlePointer);
+    document.addEventListener("keydown", handleKey);
+    return () => {
+      document.removeEventListener("mousedown", handlePointer);
+      document.removeEventListener("keydown", handleKey);
+    };
+  }, [open]);
+
+  const choose = useCallback(
+    (next: number) => {
+      setLevel(next);
+      setOpen(false);
+      buttonRef.current?.focus();
+    },
+    [setLevel]
+  );
+
+  const onMenuKeyDown = (event: React.KeyboardEvent<HTMLDivElement>) => {
+    if (event.key !== "ArrowRight" && event.key !== "ArrowLeft") return;
+    event.preventDefault();
+    const current = optionRefs.current.findIndex(
+      (el) => el === document.activeElement
+    );
+    if (current < 0) return;
+    const next =
+      event.key === "ArrowRight"
+        ? (current + 1) % options.length
+        : (current - 1 + options.length) % options.length;
+    optionRefs.current[next]?.focus();
+  };
+
+  if (!config.enabled) return null;
+
+  const buttonLabel = translate({
+    id: "theme.openapi.schema.expansion.button",
+    message: "Schema expansion depth",
+    description: "Aria/title tooltip for the schema expansion icon button",
+  });
+  const menuLabel = translate({
+    id: "theme.openapi.schema.expansion.menu",
+    message: "Schema expansion depth options",
+    description: "Accessible label for the expansion options menu",
+  });
+  const allLabel = translate({
+    id: "theme.openapi.schema.expansion.all",
+    message: "All",
+    description: "Label for the expand-all option",
+  });
+
+  return (
+    <span className="openapi-schema-expansion">
+      <button
+        ref={buttonRef}
+        type="button"
+        className="openapi-schema-expansion__trigger"
+        aria-haspopup="menu"
+        aria-expanded={open}
+        aria-controls={open ? popoverId : undefined}
+        aria-label={buttonLabel}
+        title={buttonLabel}
+        onClick={(event) => {
+          event.preventDefault();
+          event.stopPropagation();
+          setOpen((prev) => !prev);
+        }}
+      >
+        <ExpandIcon />
+      </button>
+      {open && coords && (
+        <div
+          ref={popoverRef}
+          id={popoverId}
+          role="menu"
+          aria-label={menuLabel}
+          className="openapi-schema-expansion__popover"
+          style={{ top: coords.top, right: coords.right }}
+          onKeyDown={onMenuKeyDown}
+          onClick={(event) => {
+            event.preventDefault();
+            event.stopPropagation();
+          }}
+        >
+          {options.map((value, index) => {
+            const isAll = value === ALL_VALUE;
+            const label = isAll ? allLabel : String(value);
+            const optionAriaLabel = isAll
+              ? allLabel
+              : translate(
+                  {
+                    id: "theme.openapi.schema.expansion.depthOption",
+                    message: "Expand to depth {depth}",
+                    description: "Accessible label for a depth option",
+                  },
+                  { depth: value }
+                );
+            const isActive = level === value;
+            return (
+              <button
+                key={isAll ? "all" : value}
+                ref={(el) => {
+                  optionRefs.current[index] = el;
+                }}
+                type="button"
+                role="menuitemradio"
+                aria-checked={isActive}
+                aria-label={optionAriaLabel}
+                tabIndex={index === activeIndex ? 0 : -1}
+                className={clsx("openapi-schema-expansion__option", {
+                  "openapi-schema-expansion__option--active": isActive,
+                })}
+                onClick={() => choose(value)}
+              >
+                {label}
+              </button>
+            );
+          })}
+        </div>
+      )}
+    </span>
+  );
+};
+
+export default SchemaExpansionControl;

package/src/theme/SchemaItem/index.tsx

@@ -10,7 +10,6 @@ import React, { ReactNode } from "react";
 import { translate } from "@docusaurus/Translate";
 import { Example } from "@theme/Example";
 import Markdown from "@theme/Markdown";
-import { OPENAPI_SCHEMA_ITEM } from "@theme/translationIds";
 import clsx from "clsx";
 
 import { getQualifierMessage } from "../../markdown/schema";
@@ -41,11 +40,11 @@ const transformEnumDescriptions = (
 const getEnumDescriptionMarkdown = (enumDescriptions?: [string, string][]) => {
   if (enumDescriptions?.length) {
     const enumValue = translate({
-      id: OPENAPI_SCHEMA_ITEM.ENUM_VALUE,
+      id: "theme.openapi.schemaItem.enumValue",
       message: "Enum Value",
     });
     const description = translate({
-      id: OPENAPI_SCHEMA_ITEM.ENUM_DESCRIPTION,
+      id: "theme.openapi.schemaItem.enumDescription",
       message: "Description",
     });
     return `| ${enumValue} | ${description} |
@@ -97,20 +96,29 @@ export default function SchemaItem(props: Props) {
     Array.isArray(required) ? required.includes(name) : required,
     () => (
       <span className="openapi-schema__required">
-        {translate({ id: OPENAPI_SCHEMA_ITEM.REQUIRED, message: "required" })}
+        {translate({
+          id: "theme.openapi.schemaItem.required",
+          message: "required",
+        })}
       </span>
     )
   );
 
   const renderDeprecated = guard(deprecated, () => (
     <span className="openapi-schema__deprecated">
-      {translate({ id: OPENAPI_SCHEMA_ITEM.DEPRECATED, message: "deprecated" })}
+      {translate({
+        id: "theme.openapi.schemaItem.deprecated",
+        message: "deprecated",
+      })}
     </span>
   ));
 
   const renderNullable = guard(nullable, () => (
     <span className="openapi-schema__nullable">
-      {translate({ id: OPENAPI_SCHEMA_ITEM.NULLABLE, message: "nullable" })}
+      {translate({
+        id: "theme.openapi.schemaItem.nullable",
+        message: "nullable",
+      })}
     </span>
   ));
 
@@ -148,7 +156,7 @@ export default function SchemaItem(props: Props) {
           <div>
             <strong>
               {translate({
-                id: OPENAPI_SCHEMA_ITEM.DEFAULT_VALUE,
+                id: "theme.openapi.schemaItem.defaultValue",
                 message: "Default value:",
               })}{" "}
             </strong>
@@ -162,7 +170,7 @@ export default function SchemaItem(props: Props) {
         <div>
           <strong>
             {translate({
-              id: OPENAPI_SCHEMA_ITEM.DEFAULT_VALUE,
+              id: "theme.openapi.schemaItem.defaultValue",
               message: "Default value:",
             })}{" "}
           </strong>
@@ -182,7 +190,7 @@ export default function SchemaItem(props: Props) {
           <div>
             <strong>
               {translate({
-                id: OPENAPI_SCHEMA_ITEM.CONSTANT_VALUE,
+                id: "theme.openapi.schemaItem.constantValue",
                 message: "Constant value:",
               })}{" "}
             </strong>
@@ -196,7 +204,7 @@ export default function SchemaItem(props: Props) {
         <div>
           <strong>
             {translate({
-              id: OPENAPI_SCHEMA_ITEM.CONSTANT_VALUE,
+              id: "theme.openapi.schemaItem.constantValue",
               message: "Constant value:",
             })}{" "}
           </strong>

package/src/theme/SchemaTabs/index.tsx

@@ -14,17 +14,18 @@ import React, {
   LegacyRef,
 } from "react";
 
+import useIsBrowser from "@docusaurus/useIsBrowser";
+import clsx from "clsx";
+import flatten from "lodash/flatten";
+
+import { useScrollPositionBlocker } from "@theme/utils/scrollUtils";
 import {
   sanitizeTabsChildren,
   type TabItemProps,
   TabProps,
   TabsProvider,
-  useScrollPositionBlocker,
   useTabsContextValue,
-} from "@docusaurus/theme-common/internal";
-import useIsBrowser from "@docusaurus/useIsBrowser";
-import clsx from "clsx";
-import flatten from "lodash/flatten";
+} from "@theme/utils/tabsUtils";
 
 export interface SchemaTabsProps extends TabProps {
   /**

package/src/theme/StatusCodes/index.tsx

@@ -14,7 +14,6 @@ import Markdown from "@theme/Markdown";
 import ResponseHeaders from "@theme/ResponseHeaders";
 import ResponseSchema from "@theme/ResponseSchema";
 import TabItem from "@theme/TabItem";
-import { OPENAPI_STATUS_CODES } from "@theme/translationIds";
 import type { ApiItem } from "docusaurus-plugin-openapi-docs/src/types";
 
 interface Props {
@@ -55,7 +54,7 @@ const StatusCodes: React.FC<Props> = ({ label, id, responses }: any) => {
                   <summary>
                     <strong>
                       {translate({
-                        id: OPENAPI_STATUS_CODES.RESPONSE_HEADERS,
+                        id: "theme.openapi.statusCodes.responseHeaders",
                         message: "Response Headers",
                       })}
                     </strong>
@@ -67,7 +66,7 @@ const StatusCodes: React.FC<Props> = ({ label, id, responses }: any) => {
             )}
             <ResponseSchema
               title={translate({
-                id: OPENAPI_STATUS_CODES.SCHEMA_TITLE,
+                id: "theme.openapi.statusCodes.schemaTitle",
                 message: "Schema",
               })}
               body={{ content: response.content }}

package/src/theme/TabItem/index.tsx

@@ -0,0 +1,61 @@
+/* ============================================================================
+ * Portions Copyright (c) Meta Platforms, Inc. and affiliates.
+ * Portions Copyright (c) Palo Alto Networks
+ *
+ * Swizzled from @docusaurus/theme-classic/src/theme/TabItem/index.tsx (MIT).
+ * Re-points useTabs to our vendored tabsUtils so that <TabItem> reads the same
+ * context our swizzled <Tabs> and OpenAPI tab variants (ApiTabs, MimeTabs,
+ * SchemaTabs, etc.) provide. 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, { type ReactNode } from "react";
+
+import clsx from "clsx";
+
+import { type TabItemProps, useTabs } from "@theme/utils/tabsUtils";
+
+type Props = TabItemProps;
+import styles from "./styles.module.css";
+
+function TabItemPanel({
+  children,
+  className,
+  hidden,
+}: {
+  children: ReactNode;
+  className?: string;
+  hidden?: boolean;
+}) {
+  return (
+    <div
+      role="tabpanel"
+      className={clsx(styles.tabItem, className)}
+      {...{ hidden }}
+    >
+      {children}
+    </div>
+  );
+}
+
+export default function TabItem({
+  children,
+  className,
+  value,
+}: Props): ReactNode {
+  const { selectedValue, lazy } = useTabs();
+  const isSelected = value === selectedValue;
+
+  if (!isSelected && lazy) {
+    return null;
+  }
+
+  return (
+    <TabItemPanel className={className} hidden={!isSelected}>
+      {children}
+    </TabItemPanel>
+  );
+}