docusaurus-theme-openapi-docs 1.0.4 → 1.1.0

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

@@ -0,0 +1,238 @@
+/* ============================================================================
+ * 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, {
+  useState,
+  cloneElement,
+  isValidElement,
+  type ReactElement,
+} from "react";
+
+import { duplicates } from "@docusaurus/theme-common";
+import useIsBrowser from "@docusaurus/useIsBrowser";
+import type { Props as TabItemProps } from "@theme/TabItem";
+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(
+  comp: ReactElement<object>
+): comp is ReactElement<TabItemProps> {
+  return "value" in comp.props;
+}
+
+export interface Props {
+  readonly lazy?: boolean;
+  readonly block?: boolean;
+  readonly children: readonly ReactElement<TabItemProps>[];
+  readonly defaultValue?: string | null;
+  readonly values?: readonly {
+    value: string;
+    label?: string;
+    attributes?: { [key: string]: unknown };
+  }[];
+  readonly groupId?: string;
+  readonly className?: string;
+  readonly action?: any;
+}
+
+function TabsComponent(props: Props): JSX.Element {
+  const {
+    lazy,
+    block,
+    defaultValue: defaultValueProp,
+    values: valuesProp,
+    groupId,
+    className,
+    action,
+  } = props;
+  const children = React.Children.map(props.children, (child) => {
+    if (isValidElement(child) && isTabItem(child)) {
+      return child;
+    }
+    // child.type.name will give non-sensical values in prod because of
+    // minification, but we assume it won't throw in prod.
+    throw new Error(
+      `Docusaurus error: Bad <Tabs> child <${
+        // @ts-expect-error: guarding against unexpected cases
+        typeof child.type === "string" ? child.type : child.type.name
+      }>: all children of the <Tabs> component should be <TabItem>, and every <TabItem> should have a unique "value" prop.`
+    );
+  });
+  const values =
+    valuesProp ??
+    // Only pick keys that we recognize. MDX would inject some keys by default
+    children.map(({ props: { value, label, attributes } }) => ({
+      value,
+      label,
+      attributes,
+    }));
+  const dup = duplicates(values, (a, b) => a.value === b.value);
+  if (dup.length > 0) {
+    throw new Error(
+      `Docusaurus error: Duplicate values "${dup
+        .map((a) => a.value)
+        .join(", ")}" found in <Tabs>. Every value needs to be unique.`
+    );
+  }
+  // When defaultValueProp is null, don't show a default tab
+  const defaultValue =
+    defaultValueProp === null
+      ? defaultValueProp
+      : defaultValueProp ??
+        children.find((child) => child.props.default)?.props.value ??
+        children[0]!.props.value;
+  if (defaultValue !== null && !values.some((a) => a.value === defaultValue)) {
+    throw new Error(
+      `Docusaurus error: The <Tabs> has a defaultValue "${defaultValue}" but none of its children has the corresponding value. Available values are: ${values
+        .map((a) => a.value)
+        .join(
+          ", "
+        )}. If you intend to show no default tab, use defaultValue={null} instead.`
+    );
+  }
+
+  const { tabGroupChoices, setTabGroupChoices } = useTabGroupChoice();
+  const [selectedValue, setSelectedValue] = useState(defaultValue);
+  const tabRefs: (HTMLLIElement | null)[] = [];
+  const { blockElementScrollPositionUntilNextRender } =
+    useScrollPositionBlocker();
+
+  if (groupId != null) {
+    const relevantTabGroupChoice = tabGroupChoices[groupId];
+    if (
+      relevantTabGroupChoice != null &&
+      relevantTabGroupChoice !== selectedValue &&
+      values.some((value) => value.value === relevantTabGroupChoice)
+    ) {
+      setSelectedValue(relevantTabGroupChoice);
+    }
+  }
+
+  const handleTabChange = (
+    event: React.FocusEvent<HTMLLIElement> | React.MouseEvent<HTMLLIElement>
+  ) => {
+    const newTab = event.currentTarget;
+    const newTabIndex = tabRefs.indexOf(newTab);
+    const newTabValue = values[newTabIndex]!.value;
+
+    if (newTabValue !== selectedValue) {
+      blockElementScrollPositionUntilNextRender(newTab);
+      setSelectedValue(newTabValue);
+      if (action) {
+        const newLanguage = languageSet.filter(
+          (lang) => lang.language === newTabValue
+        );
+        action(newLanguage[0]);
+      }
+
+      if (groupId != null) {
+        setTabGroupChoices(groupId, String(newTabValue));
+      }
+    }
+  };
+
+  const handleKeydown = (event: React.KeyboardEvent<HTMLLIElement>) => {
+    let focusElement: HTMLLIElement | null = null;
+
+    switch (event.key) {
+      case "ArrowRight": {
+        const nextTab = tabRefs.indexOf(event.currentTarget) + 1;
+        focusElement = tabRefs[nextTab] ?? tabRefs[0]!;
+        break;
+      }
+      case "ArrowLeft": {
+        const prevTab = tabRefs.indexOf(event.currentTarget) - 1;
+        focusElement = tabRefs[prevTab] ?? tabRefs[tabRefs.length - 1]!;
+        break;
+      }
+      default:
+        break;
+    }
+
+    focusElement?.focus();
+  };
+
+  return (
+    <div className={clsx("tabs-container", styles.tabList)}>
+      <ul
+        role="tablist"
+        aria-orientation="horizontal"
+        className={clsx(
+          "tabs",
+          {
+            "tabs--block": block,
+          },
+          styles.code__tabs,
+          className
+        )}
+      >
+        {values.map(({ value, label, attributes }) => (
+          <li
+            role="tab"
+            tabIndex={selectedValue === value ? 0 : -1}
+            aria-selected={selectedValue === value}
+            key={value}
+            ref={(tabControl) => tabRefs.push(tabControl)}
+            onKeyDown={handleKeydown}
+            onFocus={handleTabChange}
+            onClick={handleTabChange}
+            {...attributes}
+            className={clsx(
+              "tabs__item",
+              styles.tabItem,
+              attributes?.className as string,
+              {
+                "tabs__item--active": selectedValue === value,
+              }
+            )}
+          >
+            {label ?? value}
+          </li>
+        ))}
+      </ul>
+
+      {lazy ? (
+        cloneElement(
+          children.filter(
+            (tabItem) => tabItem.props.value === selectedValue
+          )[0]!,
+          { className: "margin-top--md" }
+        )
+      ) : (
+        <div className="margin-top--md">
+          {children.map((tabItem, i) =>
+            cloneElement(tabItem, {
+              key: i,
+              hidden: tabItem.props.value !== selectedValue,
+            })
+          )}
+        </div>
+      )}
+    </div>
+  );
+}
+
+export default function CodeTabs(props: Props): JSX.Element {
+  const isBrowser = useIsBrowser();
+  return (
+    <TabsComponent
+      // Remount tabs after hydration
+      // Temporary fix for https://github.com/facebook/docusaurus/issues/5653
+      key={String(isBrowser)}
+      {...props}
+    />
+  );
+}

package/src/theme/ApiDemoPanel/CodeTabs/styles.module.css

@@ -0,0 +1,11 @@
+.tabList {
+  margin-bottom: var(--ifm-leading);
+}
+
+.tabItem {
+  margin-top: 0 !important;
+}
+
+.code__tabs {
+  justify-content: space-around;
+}

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

@@ -5,32 +5,35 @@
  * LICENSE file in the root directory of this source tree.
  * ========================================================================== */
 
-import React, { useRef, useState, useEffect } from "react";
+import React, { useState, useEffect } from "react";
 
 import useDocusaurusContext from "@docusaurus/useDocusaurusContext";
 import codegen from "@paloaltonetworks/postman-code-generators";
 import sdk from "@paloaltonetworks/postman-collection";
+import CodeBlock from "@theme/CodeBlock";
 import clsx from "clsx";
-import Highlight, { defaultProps } from "prism-react-renderer";
 
+import CodeTabs from "../CodeTabs";
 import { useTypedSelector } from "../hooks";
 import buildPostmanRequest from "./../buildPostmanRequest";
-import FloatingButton from "./../FloatingButton";
 import styles from "./styles.module.css";
 
 interface Language {
   tabName: string;
   highlight: string;
   language: string;
+  codeLanguage?: string;
   variant: string;
   options: { [key: string]: boolean };
+  source?: string;
 }
 
-const languageSet: Language[] = [
+export const languageSet: Language[] = [
   {
     tabName: "cURL",
     highlight: "bash",
     language: "curl",
+    codeLanguage: "bash",
     variant: "curl",
     options: {
       longFormat: false,
@@ -39,12 +42,12 @@ const languageSet: Language[] = [
     },
   },
   {
-    tabName: "Node",
-    highlight: "javascript",
-    language: "nodejs",
-    variant: "axios",
+    tabName: "Python",
+    highlight: "python",
+    language: "python",
+    codeLanguage: "python",
+    variant: "requests",
     options: {
-      ES6_enabled: true,
       followRedirect: true,
       trimRequestBody: true,
     },
@@ -53,6 +56,7 @@ const languageSet: Language[] = [
     tabName: "Go",
     highlight: "go",
     language: "go",
+    codeLanguage: "go",
     variant: "native",
     options: {
       followRedirect: true,
@@ -60,79 +64,41 @@ const languageSet: Language[] = [
     },
   },
   {
-    tabName: "Python",
-    highlight: "python",
-    language: "python",
-    variant: "requests",
+    tabName: "Node",
+    highlight: "javascript",
+    language: "nodejs",
+    codeLanguage: "javascript",
+    variant: "axios",
     options: {
+      ES6_enabled: true,
       followRedirect: true,
       trimRequestBody: true,
     },
   },
 ];
 
-const languageTheme = {
-  plain: {
-    color: "var(--ifm-code-color)",
-  },
-  styles: [
-    {
-      types: ["inserted", "attr-name"],
-      style: {
-        color: "var(--openapi-code-green)",
-      },
-    },
-    {
-      types: ["string", "url"],
-      style: {
-        color: "var(--openapi-code-green)",
-      },
-    },
-    {
-      types: ["builtin", "char", "constant", "function"],
-      style: {
-        color: "var(--openapi-code-blue)",
-      },
-    },
-    {
-      types: ["punctuation", "operator"],
-      style: {
-        color: "var(--openapi-code-dim)",
-      },
-    },
-    {
-      types: ["class-name"],
-      style: {
-        color: "var(--openapi-code-orange)",
-      },
-    },
-    {
-      types: ["tag", "arrow", "keyword"],
-      style: {
-        color: "var(--openapi-code-purple)",
-      },
-    },
-    {
-      types: ["boolean"],
-      style: {
-        color: "var(--openapi-code-red)",
-      },
-    },
-  ],
-};
-
 interface Props {
   postman: sdk.Request;
   codeSamples: any; // TODO: Type this...
 }
 
+function CodeTab({ children, hidden, className, onClick }: any): JSX.Element {
+  return (
+    <div
+      role="tabpanel"
+      className={clsx(styles.tabItem, className)}
+      {...{ hidden }}
+    >
+      {children}
+    </div>
+  );
+}
+
 function Curl({ postman, codeSamples }: Props) {
   // TODO: match theme for vscode.
 
   const { siteConfig } = useDocusaurusContext();
 
-  const [copyText, setCopyText] = useState("Copy");
-
   const contentType = useTypedSelector((state) => state.contentType.value);
   const accept = useTypedSelector((state) => state.accept.value);
   const server = useTypedSelector((state) => state.server.value);
@@ -152,7 +118,12 @@ function Curl({ postman, codeSamples }: Props) {
     ...codeSamples,
   ];
 
-  const [language, setLanguage] = useState(langs[0]);
+  const defaultLang: Language[] = languageSet.filter(
+    (lang) =>
+      lang.codeLanguage === localStorage.getItem("docusaurus.tab.code-samples")
+  );
+
+  const [language, setLanguage] = useState(defaultLang[0] ?? langs[0]);
 
   const [codeText, setCodeText] = useState("");
 
@@ -201,76 +172,26 @@ function Curl({ postman, codeSamples }: Props) {
     auth,
   ]);
 
-  const ref = useRef<HTMLDivElement>(null);
-
-  const handleCurlCopy = () => {
-    setCopyText("Copied");
-    setTimeout(() => {
-      setCopyText("Copy");
-    }, 2000);
-    if (ref.current?.innerText) {
-      navigator.clipboard.writeText(ref.current.innerText);
-    }
-  };
-
   if (language === undefined) {
     return null;
   }
 
   return (
     <>
-      <div className={clsx(styles.buttonGroup, "api-code-tab-group")}>
+      <CodeTabs groupId="code-samples" action={setLanguage}>
         {langs.map((lang) => {
           return (
-            <button
+            <CodeTab
+              value={lang.language}
+              label={""}
               key={lang.tabName || lang.label}
-              className={clsx(
-                language === lang ? styles.selected : undefined,
-                language === lang ? "api-code-tab--active" : undefined,
-                "api-code-tab"
-              )}
-              onClick={() => setLanguage(lang)}
+              attributes={{ className: `code__tab--${lang.codeLanguage}` }}
             >
-              {lang.tabName || lang.label}
-            </button>
+              <CodeBlock language={lang.codeLanguage}>{codeText}</CodeBlock>
+            </CodeTab>
           );
         })}
-      </div>
-
-      <Highlight
-        {...defaultProps}
-        theme={languageTheme}
-        code={codeText}
-        language={language.highlight || language.lang}
-      >
-        {({ className, tokens, getLineProps, getTokenProps }) => (
-          <FloatingButton onClick={handleCurlCopy} label={copyText}>
-            <pre
-              className={className}
-              style={{
-                background: "var(--openapi-card-background-color)",
-                paddingRight: "60px",
-                borderRadius:
-                  "2px 2px var(--openapi-card-border-radius) var(--openapi-card-border-radius)",
-              }}
-            >
-              <code ref={ref}>
-                {tokens.map((line, i) => (
-                  <span {...getLineProps({ line, key: i })}>
-                    {line.map((token, key) => {
-                      if (token.types.includes("arrow")) {
-                        token.types = ["arrow"];
-                      }
-                      return <span {...getTokenProps({ token, key })} />;
-                    })}
-                    {"\n"}
-                  </span>
-                ))}
-              </code>
-            </pre>
-          </FloatingButton>
-        )}
-      </Highlight>
+      </CodeTabs>
     </>
   );
 }

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

@@ -17,8 +17,12 @@ interface Props {
 
 function FloatingButton({ label, onClick, children }: Props) {
   return (
-    <div className={styles.floatingButton}>
-      {label && <button onClick={onClick}>{label}</button>}
+    <div tabIndex={0} className={styles.floatingButton}>
+      {label && (
+        <button tabIndex={0} onClick={onClick}>
+          {label}
+        </button>
+      )}
       {children}
     </div>
   );

package/src/theme/ApiDemoPanel/FloatingButton/styles.module.css

@@ -9,7 +9,6 @@
   border-radius: var(--ifm-global-radius);
   color: var(--ifm-color-white);
   cursor: pointer;
-  outline: none;
   padding: 0.4rem 0.5rem;
   opacity: 0;
   visibility: hidden;
@@ -20,7 +19,9 @@
   right: calc(var(--ifm-pre-padding) / 2);
 }
 
-.floatingButton:hover button {
+.floatingButton:hover button,
+.floatingButton:focus-visible button,
+.floatingButton button:focus-visible {
   visibility: visible;
   opacity: 1;
 }

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

@@ -0,0 +1,71 @@
+/* ============================================================================
+ * 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, { useState } from "react";
+
+import { usePrismTheme } from "@docusaurus/theme-common";
+import useIsBrowser from "@docusaurus/useIsBrowser";
+import { LiveProvider, LiveEditor, withLive } from "react-live";
+
+import { setStringRawBody } from "../Body/slice";
+import styles from "./styles.module.css";
+
+function Live({ onEdit }: any) {
+  const isBrowser = useIsBrowser();
+  const [editorDisabled, setEditorDisabled] = useState(false);
+
+  // TODO: Temporary solution for disabling tab key
+  const handleKeydown = (event: React.KeyboardEvent) => {
+    if (event.key === "Tab") {
+      event.preventDefault();
+      setEditorDisabled(true);
+    }
+  };
+
+  return (
+    <div onClick={() => setEditorDisabled(false)}>
+      <LiveEditor
+        key={String(isBrowser)}
+        className={styles.playgroundEditor}
+        onChange={onEdit}
+        disabled={editorDisabled}
+        onKeyDown={handleKeydown}
+      />
+    </div>
+  );
+}
+
+const LiveComponent = withLive(Live);
+
+function App({
+  children,
+  transformCode,
+  value,
+  language,
+  action,
+  ...props
+}: any): JSX.Element {
+  const prismTheme = usePrismTheme();
+  const [code, setCode] = React.useState(children);
+  action(setStringRawBody(code));
+  return (
+    <div className={styles.playgroundContainer}>
+      <LiveProvider
+        code={children.replace(/\n$/, "")}
+        transformCode={transformCode ?? ((code) => `${code};`)}
+        theme={prismTheme}
+        language={language}
+        {...props}
+      >
+        <LiveComponent onEdit={setCode} />
+      </LiveProvider>
+    </div>
+  );
+}
+
+const LiveApp = withLive(App);
+export default LiveApp;

package/src/theme/ApiDemoPanel/LiveEditor/styles.module.css

@@ -0,0 +1,35 @@
+.playgroundContainer {
+  margin-top: 1rem;
+  margin-bottom: var(--ifm-leading);
+  border-radius: var(--ifm-global-radius);
+  box-shadow: var(--ifm-global-shadow-lw);
+  overflow: auto;
+  max-height: 500px;
+}
+
+.playgroundHeader {
+  letter-spacing: 0.08rem;
+  padding: 0.75rem;
+  text-transform: uppercase;
+  font-weight: bold;
+  background: var(--ifm-color-emphasis-200);
+  color: var(--ifm-color-content);
+  font-size: var(--ifm-code-font-size);
+}
+
+.playgroundHeader:first-of-type {
+  background: var(--ifm-color-emphasis-600);
+  color: var(--ifm-color-content-inverse);
+}
+
+.playgroundEditor {
+  font: var(--ifm-code-font-size) / var(--ifm-pre-line-height)
+    var(--ifm-font-family-monospace) !important;
+  /* rtl:ignore */
+  direction: ltr;
+}
+
+.playgroundPreview {
+  padding: 1rem;
+  background-color: var(--ifm-pre-background);
+}

package/src/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/src/theme/ApiDemoPanel/Server/index.tsx

@@ -62,6 +62,7 @@ function Server() {
       <button
         className={styles.showMoreButton}
         onClick={() => setIsEditing(false)}
+        tabIndex={0}
       >
         Hide
       </button>

package/src/theme/ApiDemoPanel/Server/styles.module.css

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