docusaurus-theme-openapi-docs 0.0.0-392 → 0.0.0-395

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

@@ -14,16 +14,17 @@ import React, {
   useState,
 } from "react";
 
-import {
-  duplicates,
-  useScrollPositionBlocker,
-  useTabGroupChoice,
-} from "@docusaurus/theme-common";
+import { duplicates } from "@docusaurus/theme-common";
 import useIsBrowser from "@docusaurus/useIsBrowser";
 import clsx from "clsx";
 
 import styles from "./styles.module.css"; // A very rough duck type, but good enough to guard against mistakes while
 
+const {
+  useScrollPositionBlocker,
+  useTabGroupChoice,
+} = require("@docusaurus/theme-common/internal");
+
 // allowing customization
 
 function isTabItem(comp) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "docusaurus-theme-openapi-docs",
   "description": "OpenAPI theme for Docusaurus.",
-  "version": "0.0.0-392",
+  "version": "0.0.0-395",
   "license": "MIT",
   "keywords": [
     "openapi",
@@ -31,8 +31,8 @@
     "format:lib-next": "prettier --config ../../.prettierrc.json --write \"lib-next/**/*.{js,ts,jsx,tsc}\""
   },
   "devDependencies": {
-    "@docusaurus/module-type-aliases": "2.0.0-beta.21",
-    "@docusaurus/types": "2.0.0-beta.21",
+    "@docusaurus/module-type-aliases": "2.0.0-beta.22",
+    "@docusaurus/types": "2.0.0-beta.22",
     "@types/concurrently": "^6.3.0",
     "@types/crypto-js": "^4.1.0",
     "@types/fs-extra": "^9.0.13",
@@ -42,7 +42,7 @@
     "concurrently": "^5.2.0"
   },
   "dependencies": {
-    "@docusaurus/theme-common": "2.0.0-beta.21",
+    "@docusaurus/theme-common": "2.0.0-beta.22",
     "@mdx-js/react": "^1.6.21",
     "@paloaltonetworks/postman-code-generators": "1.1.5-hotfix.5",
     "@paloaltonetworks/postman-collection": "^4.1.0",
@@ -50,7 +50,7 @@
     "buffer": "^6.0.3",
     "clsx": "^1.1.1",
     "crypto-js": "^4.1.1",
-    "docusaurus-plugin-openapi-docs": "0.0.0-392",
+    "docusaurus-plugin-openapi-docs": "0.0.0-395",
     "immer": "^9.0.7",
     "lodash": "^4.17.20",
     "process": "^0.11.10",
@@ -68,5 +68,5 @@
   "engines": {
     "node": ">=14"
   },
-  "gitHead": "04ea33fa332252a40c87d8018afe6cdb91cbdf8a"
+  "gitHead": "6b0d77e35b366bb8418b6f9523b29e5c137a7464"
 }

package/src/theme/ApiDemoPanel/CodeTabs/index.tsx

@@ -12,11 +12,7 @@ import React, {
   type ReactElement,
 } from "react";
 
-import {
-  useScrollPositionBlocker,
-  duplicates,
-  useTabGroupChoice,
-} from "@docusaurus/theme-common";
+import { duplicates } from "@docusaurus/theme-common";
 import useIsBrowser from "@docusaurus/useIsBrowser";
 import type { Props as TabItemProps } from "@theme/TabItem";
 import clsx from "clsx";
@@ -24,6 +20,11 @@ import clsx from "clsx";
 import { languageSet } from "../Curl";
 import styles from "./styles.module.css";
 
+const {
+  useScrollPositionBlocker,
+  useTabGroupChoice,
+} = require("@docusaurus/theme-common/internal");
+
 // A very rough duck type, but good enough to guard against mistakes while
 // allowing customization
 function isTabItem(

package/src/theme/ApiItem/Content/index.tsx

@@ -0,0 +1,57 @@
+/* ============================================================================
+ * 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 type { Props } from "@theme/DocItem/Content";
+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(): string | null {
+  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 }: Props): JSX.Element {
+  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/src/theme/ApiItem/Footer/index.tsx

@@ -0,0 +1,101 @@
+/* ============================================================================
+ * 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,
+  type DocContextValue,
+  // @ts-ignore
+} from "@docusaurus/theme-common/internal";
+import EditThisPage from "@theme/EditThisPage";
+import LastUpdated from "@theme/LastUpdated";
+import TagsListInline, {
+  type Props as TagsListInlineProps,
+} from "@theme/TagsListInline";
+import clsx from "clsx";
+
+import styles from "./styles.module.css";
+
+function TagsRow(props: TagsListInlineProps) {
+  return (
+    <div
+      className={clsx(
+        ThemeClassNames.docs.docFooterTagsRow,
+        "row margin-bottom--sm"
+      )}
+    >
+      <div className="col">
+        <TagsListInline {...props} />
+      </div>
+    </div>
+  );
+}
+
+type EditMetaRowProps = Pick<
+  DocContextValue["metadata"],
+  "editUrl" | "lastUpdatedAt" | "lastUpdatedBy" | "formattedLastUpdatedAt"
+>;
+function EditMetaRow({
+  editUrl,
+  lastUpdatedAt,
+  lastUpdatedBy,
+  formattedLastUpdatedAt,
+}: EditMetaRowProps) {
+  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(): JSX.Element | null {
+  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/src/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/src/theme/ApiItem/Layout/index.tsx

@@ -0,0 +1,78 @@
+/* ============================================================================
+ * 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 type { Props } from "@theme/DocItem/Layout";
+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 }: Props): JSX.Element {
+  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/src/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;

package/src/theme/ApiItem/Metadata/index.tsx

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

package/src/theme/ApiItem/Paginator/index.tsx

@@ -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";
+
+// @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(): JSX.Element {
+  const { metadata } = useDoc();
+  return <DocPaginator previous={metadata.previous} next={metadata.next} />;
+}

package/src/theme/ApiItem/TOC/Desktop/index.tsx

@@ -0,0 +1,25 @@
+/* ============================================================================
+ * 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(): JSX.Element {
+  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/src/theme/ApiItem/TOC/Mobile/index.tsx

@@ -0,0 +1,28 @@
+/* ============================================================================
+ * 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(): JSX.Element {
+  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/src/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;
+  }
+}