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

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",

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "docusaurus-theme-openapi-docs",
   "description": "OpenAPI theme for Docusaurus.",
-  "version": "0.0.0-1241",
+  "version": "0.0.0-1247",
   "license": "MIT",
   "keywords": [
     "openapi",
@@ -38,7 +38,7 @@
     "@types/postman-collection": "^3.5.11",
     "@types/react-modal": "^3.16.3",
     "concurrently": "^9.2.0",
-    "docusaurus-plugin-openapi-docs": "0.0.0-1241",
+    "docusaurus-plugin-openapi-docs": "0.0.0-1247",
     "docusaurus-plugin-sass": "^0.2.6",
     "eslint-plugin-prettier": "^5.5.1"
   },
@@ -82,5 +82,5 @@
   "engines": {
     "node": ">=14"
   },
-  "gitHead": "1034dbe20ed8a19a1a5f6ed91de1e8a31ab14537"
+  "gitHead": "2e6e04573a1c30d9b0ef899da2e75518ce7c046f"
 }

package/src/theme/ApiItem/index.tsx

@@ -20,6 +20,7 @@ import DocItemLayout from "@theme/ApiItem/Layout";
 import CodeBlock from "@theme/CodeBlock";
 import type { Props } from "@theme/DocItem";
 import DocItemMetadata from "@theme/DocItem/Metadata";
+import { SchemaExpansionProvider } from "@theme/SchemaExpansion";
 import SkeletonLoader from "@theme/SkeletonLoader";
 import clsx from "clsx";
 import type {
@@ -177,18 +178,20 @@ export default function ApiItem(props: Props): JSX.Element {
           <DocItemMetadata />
           <DocItemLayout>
             <Provider store={store2}>
-              <div className={clsx("row", "theme-api-markdown")}>
-                <div className="col col--7 openapi-left-panel__container">
-                  <MDXComponent />
-                </div>
-                <div className="col col--5 openapi-right-panel__container">
-                  <BrowserOnly fallback={<SkeletonLoader size="lg" />}>
-                    {() => {
-                      return <ApiExplorer item={api} infoPath={infoPath} />;
-                    }}
-                  </BrowserOnly>
+              <SchemaExpansionProvider>
+                <div className={clsx("row", "theme-api-markdown")}>
+                  <div className="col col--7 openapi-left-panel__container">
+                    <MDXComponent />
+                  </div>
+                  <div className="col col--5 openapi-right-panel__container">
+                    <BrowserOnly fallback={<SkeletonLoader size="lg" />}>
+                      {() => {
+                        return <ApiExplorer item={api} infoPath={infoPath} />;
+                      }}
+                    </BrowserOnly>
+                  </div>
                 </div>
-              </div>
+              </SchemaExpansionProvider>
             </Provider>
           </DocItemLayout>
         </HtmlClassNameProvider>
@@ -200,16 +203,18 @@ export default function ApiItem(props: Props): JSX.Element {
         <HtmlClassNameProvider className={docHtmlClassName}>
           <DocItemMetadata />
           <DocItemLayout>
-            <div className={clsx("row", "theme-api-markdown")}>
-              <div className="col col--7 openapi-left-panel__container schema">
-                <MDXComponent />
-              </div>
-              <div className="col col--5 openapi-right-panel__container">
-                <CodeBlock language="json" title={`${frontMatter.title}`}>
-                  {JSON.stringify(sample, null, 2)}
-                </CodeBlock>
+            <SchemaExpansionProvider>
+              <div className={clsx("row", "theme-api-markdown")}>
+                <div className="col col--7 openapi-left-panel__container schema">
+                  <MDXComponent />
+                </div>
+                <div className="col col--5 openapi-right-panel__container">
+                  <CodeBlock language="json" title={`${frontMatter.title}`}>
+                    {JSON.stringify(sample, null, 2)}
+                  </CodeBlock>
+                </div>
               </div>
-            </div>
+            </SchemaExpansionProvider>
           </DocItemLayout>
         </HtmlClassNameProvider>
       </DocProvider>

package/src/theme/RequestSchema/index.tsx

@@ -18,6 +18,7 @@ import {
   ResponseExamples,
 } from "@theme/ResponseExamples";
 import SchemaNode from "@theme/Schema";
+import SchemaExpansionControl from "@theme/SchemaExpansion";
 import SchemaTabs from "@theme/SchemaTabs";
 import SkeletonLoader from "@theme/SkeletonLoader";
 import TabItem from "@theme/TabItem";
@@ -77,24 +78,23 @@ const RequestSchemaComponent: React.FC<Props> = ({ title, body, style }) => {
                       open={true}
                       style={style}
                       summary={
-                        <>
-                          <summary>
-                            <h3 className="openapi-markdown__details-summary-header-body">
-                              {translate({
-                                id: OPENAPI_REQUEST.BODY_TITLE,
-                                message: title,
-                              })}
-                              {body.required === true && (
-                                <span className="openapi-schema__required">
-                                  {translate({
-                                    id: OPENAPI_SCHEMA_ITEM.REQUIRED,
-                                    message: "required",
-                                  })}
-                                </span>
-                              )}
-                            </h3>
-                          </summary>
-                        </>
+                        <summary className="openapi-markdown__details-summary--with-control">
+                          <h3 className="openapi-markdown__details-summary-header-body">
+                            {translate({
+                              id: OPENAPI_REQUEST.BODY_TITLE,
+                              message: title,
+                            })}
+                            {body.required === true && (
+                              <span className="openapi-schema__required">
+                                {translate({
+                                  id: OPENAPI_SCHEMA_ITEM.REQUIRED,
+                                  message: "required",
+                                })}
+                              </span>
+                            )}
+                          </h3>
+                          <SchemaExpansionControl />
+                        </summary>
                       }
                     >
                       <div style={{ textAlign: "left", marginLeft: "1rem" }}>
@@ -164,27 +164,26 @@ const RequestSchemaComponent: React.FC<Props> = ({ title, body, style }) => {
               open={true}
               style={style}
               summary={
-                <>
-                  <summary>
-                    <h3 className="openapi-markdown__details-summary-header-body">
-                      {translate({
-                        id: OPENAPI_REQUEST.BODY_TITLE,
-                        message: title,
-                      })}
-                      {firstBody.type === "array" && (
-                        <span style={{ opacity: "0.6" }}> array</span>
-                      )}
-                      {body.required && (
-                        <strong className="openapi-schema__required">
-                          {translate({
-                            id: OPENAPI_SCHEMA_ITEM.REQUIRED,
-                            message: "required",
-                          })}
-                        </strong>
-                      )}
-                    </h3>
-                  </summary>
-                </>
+                <summary className="openapi-markdown__details-summary--with-control">
+                  <h3 className="openapi-markdown__details-summary-header-body">
+                    {translate({
+                      id: OPENAPI_REQUEST.BODY_TITLE,
+                      message: title,
+                    })}
+                    {firstBody.type === "array" && (
+                      <span style={{ opacity: "0.6" }}> array</span>
+                    )}
+                    {body.required && (
+                      <strong className="openapi-schema__required">
+                        {translate({
+                          id: OPENAPI_SCHEMA_ITEM.REQUIRED,
+                          message: "required",
+                        })}
+                      </strong>
+                    )}
+                  </h3>
+                  <SchemaExpansionControl />
+                </summary>
               }
             >
               <div style={{ textAlign: "left", marginLeft: "1rem" }}>

package/src/theme/ResponseSchema/index.tsx

@@ -18,6 +18,7 @@ import {
   ResponseExamples,
 } from "@theme/ResponseExamples";
 import SchemaNode from "@theme/Schema";
+import SchemaExpansionControl from "@theme/SchemaExpansion";
 import SchemaTabs from "@theme/SchemaTabs";
 import SkeletonLoader from "@theme/SkeletonLoader";
 import TabItem from "@theme/TabItem";
@@ -91,21 +92,20 @@ const ResponseSchemaComponent: React.FC<Props> = ({
                     open={true}
                     style={style}
                     summary={
-                      <>
-                        <summary>
-                          <strong className="openapi-markdown__details-summary-response">
-                            {title}
-                            {body.required === true && (
-                              <span className="openapi-schema__required">
-                                {translate({
-                                  id: OPENAPI_SCHEMA_ITEM.REQUIRED,
-                                  message: "required",
-                                })}
-                              </span>
-                            )}
-                          </strong>
-                        </summary>
-                      </>
+                      <summary className="openapi-markdown__details-summary--with-control">
+                        <strong className="openapi-markdown__details-summary-response">
+                          {title}
+                          {body.required === true && (
+                            <span className="openapi-schema__required">
+                              {translate({
+                                id: OPENAPI_SCHEMA_ITEM.REQUIRED,
+                                message: "required",
+                              })}
+                            </span>
+                          )}
+                        </strong>
+                        <SchemaExpansionControl />
+                      </summary>
                     }
                   >
                     <div style={{ textAlign: "left", marginLeft: "1rem" }}>

package/src/theme/Schema/index.tsx

@@ -14,6 +14,11 @@ import { ClosingArrayBracket, OpeningArrayBracket } from "@theme/ArrayBrackets";
 import Details from "@theme/Details";
 import DiscriminatorTabs from "@theme/DiscriminatorTabs";
 import Markdown from "@theme/Markdown";
+import {
+  SchemaDepthProvider,
+  useSchemaDepth,
+  useSchemaExpansion,
+} from "@theme/SchemaExpansion";
 import SchemaItem from "@theme/SchemaItem";
 import SchemaTabs from "@theme/SchemaTabs";
 import TabItem from "@theme/TabItem";
@@ -676,10 +681,15 @@ const SchemaNodeDetails: React.FC<SchemaEdgeProps> = ({
   schemaType,
   schemaPath,
 }) => {
+  const depth = useSchemaDepth();
+  const { level } = useSchemaExpansion();
+  const defaultOpen = depth < level;
   return (
     <SchemaItem collapsible={true}>
       <Details
+        key={`level-${level}`}
         className="openapi-markdown__details"
+        open={defaultOpen}
         summary={
           <Summary
             name={name}
@@ -694,11 +704,13 @@ const SchemaNodeDetails: React.FC<SchemaEdgeProps> = ({
           {getQualifierMessage(schema) && (
             <MarkdownWrapper text={getQualifierMessage(schema)} />
           )}
-          <SchemaNode
-            schema={schema}
-            schemaType={schemaType}
-            schemaPath={schemaPath}
-          />
+          <SchemaDepthProvider depth={depth + 1}>
+            <SchemaNode
+              schema={schema}
+              schemaType={schemaType}
+              schemaPath={schemaPath}
+            />
+          </SchemaDepthProvider>
         </div>
       </Details>
     </SchemaItem>