docusaurus-theme-openapi-docs 0.0.0-1240 → 0.0.0-1247

package/lib/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/lib/theme/SchemaExpansion/context.d.ts

@@ -0,0 +1,24 @@
+import React from "react";
+export declare 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;
+}
+export declare function normalizeLevel(value: number | "all" | undefined): number;
+export declare const SchemaExpansionProvider: React.FC<{
+    children: React.ReactNode;
+}>;
+export declare const SchemaDepthProvider: React.FC<{
+    depth: number;
+    children: React.ReactNode;
+}>;
+export declare function useSchemaExpansion(): SchemaExpansionContextValue;
+export declare function useSchemaDepth(): number;
+export {};

package/lib/theme/SchemaExpansion/context.js

@@ -0,0 +1,187 @@
+"use strict";
+/* ============================================================================
+ * 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.
+ * ========================================================================== */
+var __createBinding =
+  (this && this.__createBinding) ||
+  (Object.create
+    ? function (o, m, k, k2) {
+        if (k2 === undefined) k2 = k;
+        var desc = Object.getOwnPropertyDescriptor(m, k);
+        if (
+          !desc ||
+          ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)
+        ) {
+          desc = {
+            enumerable: true,
+            get: function () {
+              return m[k];
+            },
+          };
+        }
+        Object.defineProperty(o, k2, desc);
+      }
+    : function (o, m, k, k2) {
+        if (k2 === undefined) k2 = k;
+        o[k2] = m[k];
+      });
+var __setModuleDefault =
+  (this && this.__setModuleDefault) ||
+  (Object.create
+    ? function (o, v) {
+        Object.defineProperty(o, "default", { enumerable: true, value: v });
+      }
+    : function (o, v) {
+        o["default"] = v;
+      });
+var __importStar =
+  (this && this.__importStar) ||
+  (function () {
+    var ownKeys = function (o) {
+      ownKeys =
+        Object.getOwnPropertyNames ||
+        function (o) {
+          var ar = [];
+          for (var k in o)
+            if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+          return ar;
+        };
+      return ownKeys(o);
+    };
+    return function (mod) {
+      if (mod && mod.__esModule) return mod;
+      var result = {};
+      if (mod != null)
+        for (var k = ownKeys(mod), i = 0; i < k.length; i++)
+          if (k[i] !== "default") __createBinding(result, mod, k[i]);
+      __setModuleDefault(result, mod);
+      return result;
+    };
+  })();
+var __importDefault =
+  (this && this.__importDefault) ||
+  function (mod) {
+    return mod && mod.__esModule ? mod : { default: mod };
+  };
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SchemaDepthProvider =
+  exports.SchemaExpansionProvider =
+  exports.SCHEMA_EXPANSION_STORAGE_KEY =
+    void 0;
+exports.normalizeLevel = normalizeLevel;
+exports.useSchemaExpansion = useSchemaExpansion;
+exports.useSchemaDepth = useSchemaDepth;
+const react_1 = __importStar(require("react"));
+const useDocusaurusContext_1 = __importDefault(
+  require("@docusaurus/useDocusaurusContext")
+);
+exports.SCHEMA_EXPANSION_STORAGE_KEY =
+  "docusaurus-openapi-schema-expansion-level";
+const DEFAULT_CONFIG = {
+  enabled: false,
+  defaultLevel: 0,
+  max: 4,
+  persist: true,
+};
+const SchemaExpansionContext = (0, react_1.createContext)({
+  config: DEFAULT_CONFIG,
+  level: 0,
+  setLevel: () => {},
+});
+const SchemaDepthContext = (0, react_1.createContext)(0);
+function normalizeLevel(value) {
+  if (value === "all") return Infinity;
+  if (typeof value === "number" && Number.isFinite(value) && value >= 0) {
+    return Math.floor(value);
+  }
+  return 0;
+}
+function readConfig(themeConfig) {
+  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() {
+  if (typeof window === "undefined") return undefined;
+  try {
+    const stored = window.localStorage.getItem(
+      exports.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) {
+  if (typeof window === "undefined") return;
+  try {
+    const value = level === Infinity ? "all" : String(level);
+    window.localStorage.setItem(exports.SCHEMA_EXPANSION_STORAGE_KEY, value);
+  } catch {
+    // ignore quota / disabled storage
+  }
+}
+const SchemaExpansionProvider = ({ children }) => {
+  const { siteConfig } = (0, useDocusaurusContext_1.default)();
+  const themeConfig = siteConfig.themeConfig;
+  const config = (0, react_1.useMemo)(
+    () => readConfig(themeConfig),
+    [themeConfig]
+  );
+  const [level, setLevelState] = (0, react_1.useState)(config.defaultLevel);
+  (0, react_1.useEffect)(() => {
+    if (!config.persist) return;
+    const persisted = readPersistedLevel();
+    if (persisted !== undefined) {
+      setLevelState(persisted);
+    }
+  }, [config.persist]);
+  const setLevel = (0, react_1.useCallback)(
+    (next) => {
+      setLevelState(next);
+      if (config.persist) {
+        writePersistedLevel(next);
+      }
+    },
+    [config.persist]
+  );
+  const value = (0, react_1.useMemo)(
+    () => ({ config, level, setLevel }),
+    [config, level, setLevel]
+  );
+  return react_1.default.createElement(
+    SchemaExpansionContext.Provider,
+    { value: value },
+    children
+  );
+};
+exports.SchemaExpansionProvider = SchemaExpansionProvider;
+const SchemaDepthProvider = ({ depth, children }) =>
+  react_1.default.createElement(
+    SchemaDepthContext.Provider,
+    { value: depth },
+    children
+  );
+exports.SchemaDepthProvider = SchemaDepthProvider;
+function useSchemaExpansion() {
+  return (0, react_1.useContext)(SchemaExpansionContext);
+}
+function useSchemaDepth() {
+  return (0, react_1.useContext)(SchemaDepthContext);
+}

package/lib/theme/SchemaExpansion/index.d.ts

@@ -0,0 +1,4 @@
+import React from "react";
+export { SchemaExpansionProvider, SchemaDepthProvider, useSchemaExpansion, useSchemaDepth, normalizeLevel, SCHEMA_EXPANSION_STORAGE_KEY, } from "./context";
+declare const SchemaExpansionControl: React.FC;
+export default SchemaExpansionControl;

package/lib/theme/SchemaExpansion/index.js

@@ -0,0 +1,315 @@
+"use strict";
+/* ============================================================================
+ * 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.
+ * ========================================================================== */
+var __createBinding =
+  (this && this.__createBinding) ||
+  (Object.create
+    ? function (o, m, k, k2) {
+        if (k2 === undefined) k2 = k;
+        var desc = Object.getOwnPropertyDescriptor(m, k);
+        if (
+          !desc ||
+          ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)
+        ) {
+          desc = {
+            enumerable: true,
+            get: function () {
+              return m[k];
+            },
+          };
+        }
+        Object.defineProperty(o, k2, desc);
+      }
+    : function (o, m, k, k2) {
+        if (k2 === undefined) k2 = k;
+        o[k2] = m[k];
+      });
+var __setModuleDefault =
+  (this && this.__setModuleDefault) ||
+  (Object.create
+    ? function (o, v) {
+        Object.defineProperty(o, "default", { enumerable: true, value: v });
+      }
+    : function (o, v) {
+        o["default"] = v;
+      });
+var __importStar =
+  (this && this.__importStar) ||
+  (function () {
+    var ownKeys = function (o) {
+      ownKeys =
+        Object.getOwnPropertyNames ||
+        function (o) {
+          var ar = [];
+          for (var k in o)
+            if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+          return ar;
+        };
+      return ownKeys(o);
+    };
+    return function (mod) {
+      if (mod && mod.__esModule) return mod;
+      var result = {};
+      if (mod != null)
+        for (var k = ownKeys(mod), i = 0; i < k.length; i++)
+          if (k[i] !== "default") __createBinding(result, mod, k[i]);
+      __setModuleDefault(result, mod);
+      return result;
+    };
+  })();
+var __importDefault =
+  (this && this.__importDefault) ||
+  function (mod) {
+    return mod && mod.__esModule ? mod : { default: mod };
+  };
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SCHEMA_EXPANSION_STORAGE_KEY =
+  exports.normalizeLevel =
+  exports.useSchemaDepth =
+  exports.useSchemaExpansion =
+  exports.SchemaDepthProvider =
+  exports.SchemaExpansionProvider =
+    void 0;
+const react_1 = __importStar(require("react"));
+const Translate_1 = require("@docusaurus/Translate");
+const translationIds_1 = require("@theme/translationIds");
+const clsx_1 = __importDefault(require("clsx"));
+const context_1 = require("./context");
+var context_2 = require("./context");
+Object.defineProperty(exports, "SchemaExpansionProvider", {
+  enumerable: true,
+  get: function () {
+    return context_2.SchemaExpansionProvider;
+  },
+});
+Object.defineProperty(exports, "SchemaDepthProvider", {
+  enumerable: true,
+  get: function () {
+    return context_2.SchemaDepthProvider;
+  },
+});
+Object.defineProperty(exports, "useSchemaExpansion", {
+  enumerable: true,
+  get: function () {
+    return context_2.useSchemaExpansion;
+  },
+});
+Object.defineProperty(exports, "useSchemaDepth", {
+  enumerable: true,
+  get: function () {
+    return context_2.useSchemaDepth;
+  },
+});
+Object.defineProperty(exports, "normalizeLevel", {
+  enumerable: true,
+  get: function () {
+    return context_2.normalizeLevel;
+  },
+});
+Object.defineProperty(exports, "SCHEMA_EXPANSION_STORAGE_KEY", {
+  enumerable: true,
+  get: function () {
+    return context_2.SCHEMA_EXPANSION_STORAGE_KEY;
+  },
+});
+const ALL_VALUE = Number.POSITIVE_INFINITY;
+const ExpandIcon = () =>
+  react_1.default.createElement(
+    "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",
+    },
+    react_1.default.createElement("polyline", { points: "4 6 8 2 12 6" }),
+    react_1.default.createElement("polyline", { points: "4 10 8 14 12 10" })
+  );
+const SchemaExpansionControl = () => {
+  const { config, level, setLevel } = (0, context_1.useSchemaExpansion)();
+  const [open, setOpen] = (0, react_1.useState)(false);
+  const [coords, setCoords] = (0, react_1.useState)(null);
+  const buttonRef = (0, react_1.useRef)(null);
+  const popoverRef = (0, react_1.useRef)(null);
+  const optionRefs = (0, react_1.useRef)([]);
+  const popoverId = (0, react_1.useId)();
+  const options = (0, react_1.useMemo)(() => {
+    const numbers = Array.from({ length: config.max + 1 }, (_, i) => i);
+    return [...numbers, ALL_VALUE];
+  }, [config.max]);
+  const activeIndex = (0, react_1.useMemo)(() => {
+    const idx = options.indexOf(level);
+    return idx >= 0 ? idx : 0;
+  }, [options, level]);
+  const updatePosition = (0, react_1.useCallback)(() => {
+    if (!buttonRef.current || typeof window === "undefined") return;
+    const rect = buttonRef.current.getBoundingClientRect();
+    setCoords({
+      top: rect.bottom + 4,
+      right: window.innerWidth - rect.right,
+    });
+  }, []);
+  (0, react_1.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]);
+  (0, react_1.useEffect)(() => {
+    if (!open) return;
+    optionRefs.current[activeIndex]?.focus();
+  }, [open, activeIndex]);
+  (0, react_1.useEffect)(() => {
+    if (!open) return;
+    const handlePointer = (event) => {
+      const target = event.target;
+      if (buttonRef.current?.contains(target)) return;
+      if (popoverRef.current?.contains(target)) return;
+      setOpen(false);
+    };
+    const handleKey = (event) => {
+      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 = (0, react_1.useCallback)(
+    (next) => {
+      setLevel(next);
+      setOpen(false);
+      buttonRef.current?.focus();
+    },
+    [setLevel]
+  );
+  const onMenuKeyDown = (event) => {
+    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 = (0, Translate_1.translate)({
+    id: translationIds_1.OPENAPI_SCHEMA_EXPANSION.BUTTON_LABEL,
+    message: "Schema expansion depth",
+    description: "Aria/title tooltip for the schema expansion icon button",
+  });
+  const menuLabel = (0, Translate_1.translate)({
+    id: translationIds_1.OPENAPI_SCHEMA_EXPANSION.MENU_LABEL,
+    message: "Schema expansion depth options",
+    description: "Accessible label for the expansion options menu",
+  });
+  const allLabel = (0, Translate_1.translate)({
+    id: translationIds_1.OPENAPI_SCHEMA_EXPANSION.ALL,
+    message: "All",
+    description: "Label for the expand-all option",
+  });
+  return react_1.default.createElement(
+    "span",
+    { className: "openapi-schema-expansion" },
+    react_1.default.createElement(
+      "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);
+        },
+      },
+      react_1.default.createElement(ExpandIcon, null)
+    ),
+    open &&
+      coords &&
+      react_1.default.createElement(
+        "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
+            : (0, Translate_1.translate)(
+                {
+                  id: translationIds_1.OPENAPI_SCHEMA_EXPANSION.DEPTH_OPTION,
+                  message: "Expand to depth {depth}",
+                  description: "Accessible label for a depth option",
+                },
+                { depth: value }
+              );
+          const isActive = level === value;
+          return react_1.default.createElement(
+            "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: (0, clsx_1.default)(
+                "openapi-schema-expansion__option",
+                {
+                  "openapi-schema-expansion__option--active": isActive,
+                }
+              ),
+              onClick: () => choose(value),
+            },
+            label
+          );
+        })
+      )
+  );
+};
+exports.default = SchemaExpansionControl;

package/lib/theme/styles.scss

@@ -32,6 +32,7 @@
 /* Schema Styling */
 @use "./ParamsItem/ParamsItem";
 @use "./SchemaItem/SchemaItem";
+@use "./SchemaExpansion/SchemaExpansion";
 /* Tabs Styling */
 @use "./ApiTabs/ApiTabs";
 @use "./DiscriminatorTabs/DiscriminatorTabs";

package/lib/theme/translationIds.d.ts

@@ -59,6 +59,12 @@ export declare const OPENAPI_STATUS_CODES: {
 export declare const OPENAPI_SCHEMA: {
     NO_SCHEMA: string;
 };
+export declare const OPENAPI_SCHEMA_EXPANSION: {
+    BUTTON_LABEL: string;
+    MENU_LABEL: string;
+    ALL: string;
+    DEPTH_OPTION: string;
+};
 export declare const OPENAPI_SCHEMA_ITEM: {
     CHARACTERS: string;
     NON_EMPTY: string;

package/lib/theme/translationIds.js

@@ -9,6 +9,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.OPENAPI_SECURITY_SCHEMES =
   exports.OPENAPI_PARAMS_DETAILS =
   exports.OPENAPI_SCHEMA_ITEM =
+  exports.OPENAPI_SCHEMA_EXPANSION =
   exports.OPENAPI_SCHEMA =
   exports.OPENAPI_STATUS_CODES =
   exports.OPENAPI_BODY =
@@ -83,6 +84,12 @@ exports.OPENAPI_STATUS_CODES = {
 exports.OPENAPI_SCHEMA = {
   NO_SCHEMA: "theme.openapi.schema.noSchema",
 };
+exports.OPENAPI_SCHEMA_EXPANSION = {
+  BUTTON_LABEL: "theme.openapi.schema.expansion.button",
+  MENU_LABEL: "theme.openapi.schema.expansion.menu",
+  ALL: "theme.openapi.schema.expansion.all",
+  DEPTH_OPTION: "theme.openapi.schema.expansion.depthOption",
+};
 exports.OPENAPI_SCHEMA_ITEM = {
   CHARACTERS: "theme.openapi.schemaItem.characters",
   NON_EMPTY: "theme.openapi.schemaItem.nonEmpty",