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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "docusaurus-theme-openapi-docs",
   "description": "OpenAPI theme for Docusaurus.",
-  "version": "0.0.0-1240",
+  "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-1240",
+    "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": "ba15cc438d6103aa536970431145d112310d5678"
+  "gitHead": "2e6e04573a1c30d9b0ef899da2e75518ce7c046f"
 }

package/src/theme/ApiExplorer/ParamOptions/ParamFormItems/ParamBooleanFormItem.tsx

@@ -5,7 +5,7 @@
  * LICENSE file in the root directory of this source tree.
  * ========================================================================== */
 
-import React from "react";
+import React, { useEffect } from "react";
 
 import { translate } from "@docusaurus/Translate";
 import { ErrorMessage } from "@hookform/error-message";
@@ -33,10 +33,26 @@ export default function ParamBooleanFormItem({
   const {
     control,
     formState: { errors },
+    setValue,
   } = useFormContext();
 
   const showErrorMessage = errors?.paramBoolean;
 
+  useEffect(() => {
+    if (param.value === undefined) return;
+    const initial =
+      typeof param.value === "boolean" ? String(param.value) : param.value;
+    if (initial === "true" || initial === "false") {
+      setValue("paramBoolean", initial);
+      // Boolean defaults arrive in redux as actual booleans; normalize to the
+      // string form the rest of the form uses.
+      if (typeof param.value === "boolean") {
+        dispatch(setParam({ ...param, value: initial }));
+      }
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
   return (
     <>
       <Controller
@@ -50,11 +66,12 @@ export default function ParamBooleanFormItem({
             : false,
         }}
         name="paramBoolean"
-        render={({ field: { onChange } }) => (
+        render={({ field: { onChange, value } }) => (
           <FormSelect
             label={label}
             type={type}
             required={required}
+            value={value ?? "---"}
             options={["---", "true", "false"]}
             onChange={(e: React.ChangeEvent<HTMLSelectElement>) => {
               const val = e.target.value;

package/src/theme/ApiExplorer/ParamOptions/ParamFormItems/ParamSelectFormItem.tsx

@@ -5,7 +5,7 @@
  * LICENSE file in the root directory of this source tree.
  * ========================================================================== */
 
-import React from "react";
+import React, { useEffect } from "react";
 
 import { translate } from "@docusaurus/Translate";
 import { ErrorMessage } from "@hookform/error-message";
@@ -32,6 +32,7 @@ export default function ParamSelectFormItem({
   const {
     control,
     formState: { errors },
+    setValue,
   } = useFormContext();
 
   const showErrorMessage = errors?.paramSelect;
@@ -40,6 +41,16 @@ export default function ParamSelectFormItem({
 
   const options = getSchemaEnum(param.schema) ?? [];
 
+  useEffect(() => {
+    if (
+      typeof param.value === "string" &&
+      (options as string[]).includes(param.value)
+    ) {
+      setValue("paramSelect", param.value);
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
   return (
     <>
       <Controller
@@ -53,11 +64,12 @@ export default function ParamSelectFormItem({
             : false,
         }}
         name="paramSelect"
-        render={({ field: { onChange } }) => (
+        render={({ field: { onChange, value } }) => (
           <FormSelect
             label={label}
             type={type}
             required={required}
+            value={value ?? "---"}
             options={["---", ...(options as string[])]}
             onChange={(e: React.ChangeEvent<HTMLSelectElement>) => {
               const val = e.target.value;

package/src/theme/ApiExplorer/ParamOptions/ParamFormItems/ParamTextFormItem.tsx

@@ -5,11 +5,12 @@
  * LICENSE file in the root directory of this source tree.
  * ========================================================================== */
 
-import React from "react";
+import React, { useEffect } from "react";
 
 import FormTextInput from "@theme/ApiExplorer/FormTextInput";
 import { Param, setParam } from "@theme/ApiExplorer/ParamOptions/slice";
 import { useTypedDispatch } from "@theme/ApiItem/hooks";
+import { useFormContext } from "react-hook-form";
 
 export interface ParamProps {
   param: Param;
@@ -25,6 +26,15 @@ export default function ParamTextFormItem({
   required,
 }: ParamProps) {
   const dispatch = useTypedDispatch();
+  const { setValue } = useFormContext();
+
+  useEffect(() => {
+    if (param.value !== undefined && !Array.isArray(param.value)) {
+      setValue(param.name, param.value);
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
   return (
     <FormTextInput
       label={label}

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 {
@@ -122,7 +123,12 @@ export default function ApiItem(props: Props): JSX.Element {
       (param: { in: "path" | "query" | "header" | "cookie" }) => {
         const paramType = param.in;
         const paramsArray: ParameterObject[] = params[paramType];
-        paramsArray?.push(param as ParameterObject);
+        const defaultValue = (param as any).schema?.default;
+        const initialized =
+          defaultValue !== undefined
+            ? ({ ...param, value: defaultValue } as unknown as ParameterObject)
+            : (param as ParameterObject);
+        paramsArray?.push(initialized);
       }
     );
     const auth = createAuth({
@@ -172,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>
@@ -195,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>

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;
+  }
+}