docusaurus-theme-openapi-docs 1.0.6 → 1.1.2

package/lib-next/theme/ApiDemoPanel/LiveEditor/styles.module.css

@@ -3,7 +3,8 @@
   margin-bottom: var(--ifm-leading);
   border-radius: var(--ifm-global-radius);
   box-shadow: var(--ifm-global-shadow-lw);
-  overflow: hidden;
+  overflow: auto;
+  max-height: 500px;
 }
 
 .playgroundHeader {

package/lib-next/theme/ApiDemoPanel/ParamOptions/styles.module.css

@@ -41,10 +41,6 @@
   display: block;
 }
 
-.showMoreButton:focus {
-  outline: 0;
-}
-
 .showMoreButton:hover {
   /* text-decoration: underline; */
   /* background-color: red; */

package/lib-next/theme/ApiDemoPanel/Server/index.js

@@ -23,7 +23,7 @@ function Server() {
     return null;
   }
 
-  if (options.length <= 1 && value?.variables === undefined) {
+  if (options.length < 1 && value?.variables === undefined) {
     return null;
   }
 
@@ -62,10 +62,11 @@ function Server() {
       <button
         className={styles.showMoreButton}
         onClick={() => setIsEditing(false)}
+        tabIndex={0}
       >
         Hide
       </button>
-      <FormItem label="Endpoint">
+      <FormItem label="Base URL">
         <FormSelect
           options={options.map((s) => s.url)}
           onChange={(e) => dispatch(setServer(e.target.value))}

package/lib-next/theme/ApiDemoPanel/Server/styles.module.css

@@ -28,10 +28,6 @@
   display: block;
 }
 
-.showMoreButton:focus {
-  outline: 0;
-}
-
 .showMoreButton:hover {
   /* text-decoration: underline; */
   /* background-color: red; */

package/lib-next/theme/ApiItem/Content/index.js

@@ -0,0 +1,55 @@
+/* ============================================================================
+ * 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 from "react";
+import { ThemeClassNames } from "@docusaurus/theme-common"; // @ts-ignore
+
+import { useDoc } from "@docusaurus/theme-common/internal";
+import Heading from "@theme/Heading";
+import MDXContent from "@theme/MDXContent";
+import clsx from "clsx";
+/**
+ Title can be declared inside md content or declared through
+ front matter and added manually. To make both cases consistent,
+ the added title is added under the same div.markdown block
+ See https://github.com/facebook/docusaurus/pull/4882#issuecomment-853021120
+
+ We render a "synthetic title" if:
+ - user doesn't ask to hide it with front matter
+ - the markdown content does not already contain a top-level h1 heading
+*/
+
+function useSyntheticTitle() {
+  const { metadata, frontMatter, contentTitle } = useDoc();
+  const shouldRender =
+    !frontMatter.hide_title && typeof contentTitle === "undefined";
+
+  if (!shouldRender) {
+    return null;
+  }
+
+  return metadata.title;
+}
+
+export default function DocItemContent({ children }) {
+  const syntheticTitle = useSyntheticTitle();
+  return (
+    <div
+      className={clsx(
+        ThemeClassNames.docs.docMarkdown,
+        "theme-api-markdown",
+        "markdown"
+      )}
+    >
+      {syntheticTitle && (
+        <header>
+          <Heading as="h1">{syntheticTitle}</Heading>
+        </header>
+      )}
+      <MDXContent>{children}</MDXContent>
+    </div>
+  );
+}

package/lib-next/theme/ApiItem/Footer/index.js

@@ -0,0 +1,88 @@
+/* ============================================================================
+ * 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 from "react";
+import { ThemeClassNames } from "@docusaurus/theme-common";
+import {
+  useDoc, // @ts-ignore
+} from "@docusaurus/theme-common/internal";
+import EditThisPage from "@theme/EditThisPage";
+import LastUpdated from "@theme/LastUpdated";
+import TagsListInline from "@theme/TagsListInline";
+import clsx from "clsx";
+import styles from "./styles.module.css";
+
+function TagsRow(props) {
+  return (
+    <div
+      className={clsx(
+        ThemeClassNames.docs.docFooterTagsRow,
+        "row margin-bottom--sm"
+      )}
+    >
+      <div className="col">
+        <TagsListInline {...props} />
+      </div>
+    </div>
+  );
+}
+
+function EditMetaRow({
+  editUrl,
+  lastUpdatedAt,
+  lastUpdatedBy,
+  formattedLastUpdatedAt,
+}) {
+  return (
+    <div className={clsx(ThemeClassNames.docs.docFooterEditMetaRow, "row")}>
+      <div className="col">{editUrl && <EditThisPage editUrl={editUrl} />}</div>
+
+      <div className={clsx("col", styles.lastUpdated)}>
+        {(lastUpdatedAt || lastUpdatedBy) && (
+          <LastUpdated
+            lastUpdatedAt={lastUpdatedAt}
+            formattedLastUpdatedAt={formattedLastUpdatedAt}
+            lastUpdatedBy={lastUpdatedBy}
+          />
+        )}
+      </div>
+    </div>
+  );
+}
+
+export default function DocItemFooter() {
+  const { metadata } = useDoc();
+  const {
+    editUrl,
+    lastUpdatedAt,
+    formattedLastUpdatedAt,
+    lastUpdatedBy,
+    tags,
+  } = metadata;
+  const canDisplayTagsRow = tags.length > 0;
+  const canDisplayEditMetaRow = !!(editUrl || lastUpdatedAt || lastUpdatedBy);
+  const canDisplayFooter = canDisplayTagsRow || canDisplayEditMetaRow;
+
+  if (!canDisplayFooter) {
+    return null;
+  }
+
+  return (
+    <footer
+      className={clsx(ThemeClassNames.docs.docFooter, "docusaurus-mt-lg")}
+    >
+      {canDisplayTagsRow && <TagsRow tags={tags} />}
+      {canDisplayEditMetaRow && (
+        <EditMetaRow
+          editUrl={editUrl}
+          lastUpdatedAt={lastUpdatedAt}
+          lastUpdatedBy={lastUpdatedBy}
+          formattedLastUpdatedAt={formattedLastUpdatedAt}
+        />
+      )}
+    </footer>
+  );
+}

package/lib-next/theme/ApiItem/Footer/styles.module.css

@@ -0,0 +1,18 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+.lastUpdated {
+  margin-top: 0.2rem;
+  font-style: italic;
+  font-size: smaller;
+}
+
+@media (min-width: 997px) {
+  .lastUpdated {
+    text-align: right;
+  }
+}

package/lib-next/theme/ApiItem/Layout/index.js

@@ -0,0 +1,69 @@
+/* ============================================================================
+ * 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 from "react";
+import { useWindowSize } from "@docusaurus/theme-common"; // @ts-ignore
+
+import { useDoc } from "@docusaurus/theme-common/internal";
+import DocBreadcrumbs from "@theme/DocBreadcrumbs";
+import DocVersionBadge from "@theme/DocVersionBadge";
+import DocVersionBanner from "@theme/DocVersionBanner";
+import clsx from "clsx";
+import DocItemContent from "../Content";
+import DocItemFooter from "../Footer";
+import DocItemPaginator from "../Paginator";
+import DocItemTOCDesktop from "../TOC/Desktop";
+import DocItemTOCMobile from "../TOC/Mobile";
+import styles from "./styles.module.css";
+/**
+ * Decide if the toc should be rendered, on mobile or desktop viewports
+ */
+
+function useDocTOC() {
+  const { frontMatter, toc } = useDoc();
+  const windowSize = useWindowSize();
+  const hidden = frontMatter.hide_table_of_contents;
+  const canRender = !hidden && toc.length > 0;
+  const mobile = canRender ? <DocItemTOCMobile /> : undefined;
+  const desktop =
+    canRender && (windowSize === "desktop" || windowSize === "ssr") ? (
+      <DocItemTOCDesktop />
+    ) : undefined;
+  return {
+    hidden,
+    mobile,
+    desktop,
+  };
+}
+
+export default function DocItemLayout({ children }) {
+  const docTOC = useDocTOC();
+  const {
+    frontMatter: { api },
+  } = useDoc();
+  return (
+    <div className="row">
+      <div className={clsx("col", !docTOC.hidden && styles.docItemCol)}>
+        <DocVersionBanner />
+        <div className={styles.docItemContainer}>
+          <article>
+            <DocBreadcrumbs />
+            <DocVersionBadge />
+            {docTOC.mobile}
+            <DocItemContent>{children}</DocItemContent>
+            <div className={clsx("col", api ? "col--7" : "col--12")}>
+              <DocItemFooter />
+            </div>
+          </article>
+          <div className={clsx("col", api ? "col--7" : "col--12")}>
+            <DocItemPaginator />
+          </div>
+        </div>
+      </div>
+      {docTOC.desktop && <div className="col col--3">{docTOC.desktop}</div>}
+    </div>
+  );
+}

package/lib-next/theme/ApiItem/{styles.module.css → Layout/styles.module.css}

@@ -1,3 +1,10 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
 :root {
   --openapi-required: var(--ifm-color-danger);
   --openapi-code-blue: var(--ifm-color-info);
@@ -6,6 +13,21 @@
   --openapi-code-green: var(--ifm-color-success);
 }
 
+:global(.docs-wrapper) {
+  height: 100%;
+}
+
+.docItemContainer header + *,
+.docItemContainer article > *:first-child {
+  margin-top: 0;
+}
+
+@media (min-width: 997px) {
+  .docItemCol {
+    max-width: 75% !important;
+  }
+}
+
 .apiItemContainer article > *:first-child,
 .apiItemContainer header + * {
   margin-top: 0;
@@ -70,10 +92,6 @@
   padding-top: 5px;
 }
 
-:global(.theme-api-markdown details li:last-child) {
-  border-left: none;
-}
-
 :global(.theme-api-markdown details p) {
   margin-bottom: 0;
 }
@@ -147,6 +165,11 @@
   border-bottom-color: var(--ifm-color-success);
 }
 
+:global(.language-python) {
+  max-height: 500px;
+  overflow: auto;
+}
+
 :global(.code__tab--go::after) {
   content: "";
   width: 32px;
@@ -165,6 +188,11 @@
   border-bottom-color: var(--ifm-color-info);
 }
 
+:global(.language-go) {
+  max-height: 500px;
+  overflow: auto;
+}
+
 :global(.code__tab--javascript::after) {
   content: "";
   width: 32px;
@@ -183,6 +211,11 @@
   border-bottom-color: var(--ifm-color-warning);
 }
 
+:global(.language-javascript) {
+  max-height: 500px;
+  overflow: auto;
+}
+
 :global(.code__tab--bash::after) {
   content: "";
   width: 32px;
@@ -200,3 +233,8 @@
 :global(.code__tab--bash.tabs__item--active) {
   border-bottom-color: var(--ifm-color-danger);
 }
+
+:global(.language-bash) {
+  max-height: 500px;
+  overflow: auto;
+}

package/lib-next/theme/ApiItem/Metadata/index.js

@@ -0,0 +1,21 @@
+/* ============================================================================
+ * 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 from "react";
+import { PageMetadata } from "@docusaurus/theme-common"; // @ts-ignore
+
+import { useDoc } from "@docusaurus/theme-common/internal";
+export default function DocItemMetadata() {
+  const { metadata, frontMatter, assets } = useDoc();
+  return (
+    <PageMetadata
+      title={metadata.title}
+      description={metadata.description}
+      keywords={frontMatter.keywords}
+      image={assets.image ?? frontMatter.image}
+    />
+  );
+}

package/lib-next/theme/ApiItem/Paginator/index.js

@@ -0,0 +1,19 @@
+/* ============================================================================
+ * 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 from "react"; // @ts-ignore
+
+import { useDoc } from "@docusaurus/theme-common/internal";
+import DocPaginator from "@theme/DocPaginator";
+/**
+ * This extra component is needed, because <DocPaginator> should remain generic.
+ * DocPaginator is used in non-docs contexts too: generated-index pages...
+ */
+
+export default function DocItemPaginator() {
+  const { metadata } = useDoc();
+  return <DocPaginator previous={metadata.previous} next={metadata.next} />;
+}

package/lib-next/theme/ApiItem/TOC/Desktop/index.js

@@ -0,0 +1,22 @@
+/* ============================================================================
+ * 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 from "react";
+import { ThemeClassNames } from "@docusaurus/theme-common"; // @ts-ignore
+
+import { useDoc } from "@docusaurus/theme-common/internal";
+import TOC from "@theme/TOC";
+export default function DocItemTOCDesktop() {
+  const { toc, frontMatter } = useDoc();
+  return (
+    <TOC
+      toc={toc}
+      minHeadingLevel={frontMatter.toc_min_heading_level}
+      maxHeadingLevel={frontMatter.toc_max_heading_level}
+      className={ThemeClassNames.docs.docTocDesktop}
+    />
+  );
+}

package/lib-next/theme/ApiItem/TOC/Mobile/index.js

@@ -0,0 +1,24 @@
+/* ============================================================================
+ * 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 from "react";
+import { ThemeClassNames } from "@docusaurus/theme-common"; // @ts-ignore
+
+import { useDoc } from "@docusaurus/theme-common/internal";
+import TOCCollapsible from "@theme/TOCCollapsible";
+import clsx from "clsx";
+import styles from "./styles.module.css";
+export default function DocItemTOCMobile() {
+  const { toc, frontMatter } = useDoc();
+  return (
+    <TOCCollapsible
+      toc={toc}
+      minHeadingLevel={frontMatter.toc_min_heading_level}
+      maxHeadingLevel={frontMatter.toc_max_heading_level}
+      className={clsx(ThemeClassNames.docs.docTocMobile, styles.tocMobile)}
+    />
+  );
+}

package/lib-next/theme/ApiItem/TOC/Mobile/styles.module.css

@@ -0,0 +1,19 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+@media (min-width: 997px) {
+  /* Prevent hydration FOUC, as the mobile TOC needs to be server-rendered */
+  .tocMobile {
+    display: none;
+  }
+}
+
+@media print {
+  .tocMobile {
+    display: none;
+  }
+}

package/lib-next/theme/ApiItem/index.js

@@ -6,23 +6,12 @@
  * ========================================================================== */
 import React from "react";
 import ExecutionEnvironment from "@docusaurus/ExecutionEnvironment";
-import {
-  PageMetadata,
-  HtmlClassNameProvider,
-  ThemeClassNames,
-  useWindowSize,
-} from "@docusaurus/theme-common";
-import DocBreadcrumbs from "@theme/DocBreadcrumbs";
-import DocItemFooter from "@theme/DocItemFooter";
-import DocPaginator from "@theme/DocPaginator";
-import DocVersionBadge from "@theme/DocVersionBadge";
-import DocVersionBanner from "@theme/DocVersionBanner";
-import Heading from "@theme/Heading";
-import MDXContent from "@theme/MDXContent";
-import TOC from "@theme/TOC";
-import TOCCollapsible from "@theme/TOCCollapsible";
+import { HtmlClassNameProvider } from "@docusaurus/theme-common";
 import clsx from "clsx";
-import styles from "./styles.module.css";
+import DocItemLayout from "./Layout";
+import DocItemMetadata from "./Metadata";
+
+const { DocProvider } = require("@docusaurus/theme-common/internal");
 
 let ApiDemoPanel = (_) => (
   <div
@@ -36,127 +25,36 @@ if (ExecutionEnvironment.canUseDOM) {
   ApiDemoPanel = require("@theme/ApiDemoPanel").default;
 }
 
-function DocItemMetadata(props) {
-  const { content: DocContent } = props;
-  const { metadata, frontMatter, assets } = DocContent;
-  const { keywords } = frontMatter;
-  const { description, title } = metadata;
-  const image = assets.image ?? frontMatter.image;
-  return (
-    <PageMetadata
-      {...{
-        title,
-        description,
-        keywords,
-        image,
-      }}
-    />
-  );
-}
-
-function DocItemContent(props) {
-  const { content: DocContent } = props;
-  const { metadata, frontMatter } = DocContent;
-  const {
-    info_path: infoPath,
-    hide_title: hideTitle,
-    hide_table_of_contents: hideTableOfContents,
-    toc_min_heading_level: tocMinHeadingLevel,
-    toc_max_heading_level: tocMaxHeadingLevel,
-  } = frontMatter;
-  const { title } = metadata;
-  const { api } = frontMatter; // We only add a title if:
-  // - user doesn't ask to hide it with front matter
-  // - the markdown content does not already contain a top-level h1 heading
-
-  const shouldAddTitle =
-    !hideTitle && typeof DocContent.contentTitle === "undefined";
-  const windowSize = useWindowSize();
-  const canRenderTOC =
-    !hideTableOfContents && DocContent.toc && DocContent.toc.length > 0;
-  const renderTocDesktop =
-    canRenderTOC && (windowSize === "desktop" || windowSize === "ssr");
-  return (
-    <div className="row">
-      <div className={clsx("col", !hideTableOfContents && styles.docItemCol)}>
-        <DocVersionBanner />
-        <div className={styles.docItemContainer}>
-          <article>
-            <DocBreadcrumbs />
-            <DocVersionBadge />
-
-            {canRenderTOC && (
-              <TOCCollapsible
-                toc={DocContent.toc}
-                minHeadingLevel={tocMinHeadingLevel}
-                maxHeadingLevel={tocMaxHeadingLevel}
-                className={clsx(
-                  ThemeClassNames.docs.docTocMobile,
-                  styles.tocMobile
-                )}
-              />
-            )}
+export default function DocItem(props) {
+  const docHtmlClassName = `docs-doc-id-${props.content.metadata.unversionedId}`;
 
-            <div
-              className={clsx(
-                ThemeClassNames.docs.docMarkdown,
-                "theme-api-markdown",
-                "markdown"
-              )}
-            >
-              {/*
-               Title can be declared inside md content or declared through
-               front matter and added manually. To make both cases consistent,
-               the added title is added under the same div.markdown block
-               See https://github.com/facebook/docusaurus/pull/4882#issuecomment-853021120
-               */}
-              {shouldAddTitle && (
-                <header>
-                  <Heading as="h1">{title}</Heading>
-                </header>
-              )}
-              <MDXContent>
-                <div className="row">
-                  <div className={clsx("col", api ? "col--7" : "col--12")}>
-                    <DocContent />
-                  </div>
-                  {api && (
-                    <div className="col col--5">
-                      <ApiDemoPanel item={api} infoPath={infoPath} />
-                    </div>
-                  )}
-                </div>
-              </MDXContent>
-            </div>
-            <div className={clsx("col", api ? "col--7" : "col--12")}>
-              <DocItemFooter {...props} />
-            </div>
-          </article>
-          <div className={clsx("col", api ? "col--7" : "col--12")}>
-            <DocPaginator previous={metadata.previous} next={metadata.next} />
-          </div>
+  const DocContent = () => {
+    const MDXComponent = props.content;
+    const { frontMatter } = MDXComponent;
+    const { info_path: infoPath } = frontMatter;
+    const { api } = frontMatter;
+    return (
+      <div className="row">
+        <div className={clsx("col", api ? "col--7" : "col--12")}>
+          <MDXComponent />
         </div>
+        {api && (
+          <div className="col col--5">
+            <ApiDemoPanel item={api} infoPath={infoPath} />
+          </div>
+        )}
       </div>
-      {renderTocDesktop && (
-        <div className="col col--3">
-          <TOC
-            toc={DocContent.toc}
-            minHeadingLevel={tocMinHeadingLevel}
-            maxHeadingLevel={tocMaxHeadingLevel}
-            className={ThemeClassNames.docs.docTocDesktop}
-          />
-        </div>
-      )}
-    </div>
-  );
-}
+    );
+  };
 
-export default function DocItem(props) {
-  const docHtmlClassName = `docs-doc-id-${props.content.metadata.unversionedId}`;
   return (
-    <HtmlClassNameProvider className={docHtmlClassName}>
-      <DocItemMetadata {...props} />
-      <DocItemContent {...props} />
-    </HtmlClassNameProvider>
+    <DocProvider content={props.content}>
+      <HtmlClassNameProvider className={docHtmlClassName}>
+        <DocItemMetadata />
+        <DocItemLayout>
+          <DocContent />
+        </DocItemLayout>
+      </HtmlClassNameProvider>
+    </DocProvider>
   );
 }