docusaurus-theme-openapi-docs 0.0.0-1000

package/src/theme/OperationTabs/index.tsx

@@ -0,0 +1,220 @@
+/* ============================================================================
+ * 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, {
+  cloneElement,
+  useEffect,
+  useState,
+  useRef,
+  ReactElement,
+} from "react";
+
+import {
+  sanitizeTabsChildren,
+  TabProps,
+  useScrollPositionBlocker,
+  useTabs,
+} from "@docusaurus/theme-common/internal";
+import { TabItemProps } from "@docusaurus/theme-common/lib/utils/tabsUtils";
+import useIsBrowser from "@docusaurus/useIsBrowser";
+import clsx from "clsx";
+
+function TabList({
+  className,
+  block,
+  selectedValue,
+  selectValue,
+  tabValues,
+}: TabProps & ReturnType<typeof useTabs>) {
+  const tabRefs: (HTMLLIElement | null)[] = [];
+  const { blockElementScrollPositionUntilNextRender } =
+    useScrollPositionBlocker();
+
+  const handleTabChange = (
+    event:
+      | React.FocusEvent<HTMLLIElement>
+      | React.MouseEvent<HTMLLIElement>
+      | React.KeyboardEvent<HTMLLIElement>
+  ) => {
+    const newTab = event.currentTarget;
+    const newTabIndex = tabRefs.indexOf(newTab);
+    const newTabValue = tabValues[newTabIndex].value;
+
+    if (newTabValue !== selectedValue) {
+      blockElementScrollPositionUntilNextRender(newTab);
+      selectValue(newTabValue);
+    }
+  };
+
+  const handleKeydown = (event: React.KeyboardEvent<HTMLLIElement>) => {
+    let focusElement: HTMLLIElement | null = null;
+
+    switch (event.key) {
+      case "Enter": {
+        handleTabChange(event);
+        break;
+      }
+      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();
+  };
+
+  const tabItemListContainerRef = useRef<HTMLUListElement>(null);
+  const [showTabArrows, setShowTabArrows] = useState<boolean>(false);
+
+  useEffect(() => {
+    const resizeObserver = new ResizeObserver((entries) => {
+      for (let entry of entries) {
+        requestAnimationFrame(() => {
+          if (entry.target.clientWidth < entry.target.scrollWidth) {
+            setShowTabArrows(true);
+          } else {
+            setShowTabArrows(false);
+          }
+        });
+      }
+    });
+
+    resizeObserver.observe(tabItemListContainerRef.current!);
+
+    return () => {
+      resizeObserver.disconnect();
+    };
+  }, []);
+
+  const handleRightClick = () => {
+    tabItemListContainerRef.current!.scrollLeft += 90;
+  };
+
+  const handleLeftClick = () => {
+    tabItemListContainerRef.current!.scrollLeft -= 90;
+  };
+
+  return (
+    <div className="tabs__container">
+      <div className="openapi-tabs__operation-container">
+        {showTabArrows && (
+          <button
+            className={clsx("openapi-tabs__arrow", "left")}
+            onClick={handleLeftClick}
+          />
+        )}
+        <ul
+          ref={tabItemListContainerRef}
+          role="tablist"
+          aria-orientation="horizontal"
+          className={clsx(
+            "openapi-tabs__operation-list-container",
+            "tabs",
+            {
+              "tabs--block": block,
+            },
+            className
+          )}
+        >
+          {tabValues.map(({ value, label, attributes }) => {
+            return (
+              <li
+                // TODO extract TabListItem
+                role="tab"
+                tabIndex={selectedValue === value ? 0 : -1}
+                aria-selected={selectedValue === value}
+                key={value}
+                ref={(tabControl) => {
+                  tabRefs.push(tabControl);
+                }}
+                onKeyDown={handleKeydown}
+                onFocus={handleTabChange}
+                onClick={(e) => handleTabChange(e)}
+                {...attributes}
+                className={clsx(
+                  "tabs__item",
+                  "openapi-tabs__operation-item",
+                  attributes?.className as string,
+                  {
+                    active: selectedValue === value,
+                  }
+                )}
+              >
+                {label ?? value}
+              </li>
+            );
+          })}
+        </ul>
+        {showTabArrows && (
+          <button
+            className={clsx("openapi-tabs__arrow", "right")}
+            onClick={handleRightClick}
+          />
+        )}
+      </div>
+    </div>
+  );
+}
+function TabContent({
+  lazy,
+  children,
+  selectedValue,
+}: TabProps & ReturnType<typeof useTabs>): React.JSX.Element | null {
+  const childTabs = (Array.isArray(children) ? children : [children]).filter(
+    Boolean
+  ) as ReactElement<TabItemProps>[];
+  if (lazy) {
+    const selectedTabItem = childTabs.find(
+      (tabItem) => tabItem.props.value === selectedValue
+    );
+    if (!selectedTabItem) {
+      // fail-safe or fail-fast? not sure what's best here
+      return null;
+    }
+    return cloneElement(selectedTabItem, { className: "margin-top--md" });
+  }
+  return (
+    <div className="margin-top--md">
+      {childTabs.map((tabItem, i) =>
+        cloneElement(tabItem, {
+          key: i,
+          hidden: tabItem.props.value !== selectedValue,
+        })
+      )}
+    </div>
+  );
+}
+function TabsComponent(props: TabProps): React.JSX.Element {
+  const tabs = useTabs(props);
+  return (
+    <div className="tabs-container">
+      <TabList {...props} {...tabs} />
+      <TabContent {...props} {...tabs} />
+    </div>
+  );
+}
+export default function OperationTabs(props: TabProps): React.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}
+    >
+      {sanitizeTabsChildren(props.children)}
+    </TabsComponent>
+  );
+}

package/src/theme/ParamsDetails/index.tsx

@@ -0,0 +1,81 @@
+/* ============================================================================
+ * 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 BrowserOnly from "@docusaurus/BrowserOnly";
+import Details from "@theme/Details";
+import ParamsItem from "@theme/ParamsItem";
+import SkeletonLoader from "@theme/SkeletonLoader";
+
+interface Props {
+  parameters: any[];
+}
+
+const ParamsDetailsComponent: React.FC<Props> = ({ parameters }) => {
+  const types = ["path", "query", "header", "cookie"];
+
+  return (
+    <>
+      {types.map((type) => {
+        const params = parameters?.filter((param: any) => param?.in === type);
+
+        if (!params || params.length === 0) {
+          return null;
+        }
+
+        const summaryElement = (
+          <summary>
+            <h3 className="openapi-markdown__details-summary-header-params">
+              {`${type.charAt(0).toUpperCase() + type.slice(1)} Parameters`}
+            </h3>
+          </summary>
+        );
+
+        return (
+          <Details
+            key={type}
+            className="openapi-markdown__details"
+            style={{ marginBottom: "1rem" }}
+            data-collapsed={false}
+            open={true}
+            summary={summaryElement}
+          >
+            <ul>
+              {params.map((param: any, index: number) => (
+                <ParamsItem
+                  key={index}
+                  className="paramsItem"
+                  param={{
+                    ...param,
+                    enumDescriptions: Object.entries(
+                      param?.schema?.["x-enumDescriptions"] ??
+                        param?.schema?.items?.["x-enumDescriptions"] ??
+                        {}
+                    ),
+                  }}
+                />
+              ))}
+            </ul>
+          </Details>
+        );
+      })}
+    </>
+  );
+};
+
+const ParamsDetails: React.FC<Props> = (props) => {
+  return (
+    <BrowserOnly fallback={<SkeletonLoader size="sm" />}>
+      {() => {
+        return <ParamsDetailsComponent {...props} />;
+      }}
+    </BrowserOnly>
+  );
+};
+
+export default ParamsDetails;

package/src/theme/ParamsItem/_ParamsItem.scss

@@ -0,0 +1,54 @@
+.openapi-params__list-item {
+  margin: 0 0 0 1rem !important;
+  position: relative;
+  padding-left: 1rem;
+  border-left: thin solid var(--openapi-tree-line-color) !important;
+  margin-top: unset !important;
+
+  // Horizonal line styling for param attributes
+  &::before {
+    position: absolute;
+    top: 5px;
+    left: 0;
+    width: 0.7rem;
+    /* width of horizontal line */
+    height: 0.5rem;
+    /* vertical position of line */
+    vertical-align: top;
+    border-bottom: thin solid var(--openapi-tree-line-color);
+    content: "";
+    display: inline-block;
+  }
+
+  &:hover {
+    .openapi-schema__property {
+      color: var(--ifm-color-primary);
+    }
+  }
+}
+
+.openapi-schema__type {
+  opacity: 0.6;
+  padding-left: 0.3rem;
+}
+
+.openapi-schema__required {
+  display: inline-flex;
+  align-items: center;
+  font-size: 10.5px;
+  font-weight: bold;
+  color: var(--openapi-required);
+  margin-left: 1%;
+  background-color: transparent;
+  text-transform: uppercase;
+}
+
+.openapi-schema__divider {
+  flex-grow: 1;
+  border-bottom: thin solid var(--ifm-toc-border-color);
+  margin: 10px;
+}
+
+.openapi-schema__container {
+  display: flex;
+}

package/src/theme/ParamsItem/index.tsx

@@ -0,0 +1,205 @@
+/* ============================================================================
+ * 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 Markdown from "@theme/Markdown";
+import SchemaTabs from "@theme/SchemaTabs";
+import TabItem from "@theme/TabItem";
+/* eslint-disable import/no-extraneous-dependencies*/
+import clsx from "clsx";
+
+import { getQualifierMessage, getSchemaName } from "../../markdown/schema";
+import { guard, toString } from "../../markdown/utils";
+
+interface Map<T> {
+  [key: string]: T;
+}
+
+export interface ExampleObject {
+  summary?: string;
+  description?: string;
+  value?: any;
+  externalValue?: string;
+}
+
+export interface Props {
+  className: string;
+  param: {
+    description: string;
+    example: any;
+    examples: Map<ExampleObject>;
+    name: string;
+    required: boolean;
+    deprecated: boolean;
+    schema: any;
+    enumDescriptions?: [string, string][];
+  };
+}
+
+const getEnumDescriptionMarkdown = (enumDescriptions?: [string, string][]) => {
+  if (enumDescriptions?.length) {
+    return `| Enum Value | Description |
+| ---- | ----- |
+${enumDescriptions
+  .map((desc) => {
+    return `| ${desc[0]} | ${desc[1]} | `.replaceAll("\n", "<br/>");
+  })
+  .join("\n")}
+    `;
+  }
+
+  return "";
+};
+
+function ParamsItem({ param, ...rest }: Props) {
+  const {
+    description,
+    example,
+    examples,
+    name,
+    required,
+    deprecated,
+    enumDescriptions,
+  } = param;
+
+  let schema = param.schema;
+  let defaultValue: string | undefined;
+
+  if (!schema) {
+    schema = { type: "any" };
+  }
+
+  if (!schema.type) {
+    schema.type = "any";
+  }
+
+  if (schema) {
+    if (schema.items) {
+      defaultValue = schema.items.default;
+    } else {
+      defaultValue = schema.default;
+    }
+  }
+
+  const renderSchemaName = guard(schema, (schema) => (
+    <span className="openapi-schema__type"> {getSchemaName(schema)}</span>
+  ));
+
+  const renderSchemaRequired = guard(required, () => (
+    <span className="openapi-schema__required">required</span>
+  ));
+
+  const renderDeprecated = guard(deprecated, () => (
+    <span className="openapi-schema__deprecated">deprecated</span>
+  ));
+
+  const renderQualifier = guard(getQualifierMessage(schema), (qualifier) => (
+    <Markdown>{qualifier}</Markdown>
+  ));
+
+  const renderDescription = guard(description, (description) => (
+    <Markdown>{description}</Markdown>
+  ));
+
+  const renderEnumDescriptions = guard(
+    getEnumDescriptionMarkdown(enumDescriptions),
+    (value) => {
+      return (
+        <div style={{ marginTop: ".5rem" }}>
+          <Markdown>{value}</Markdown>
+        </div>
+      );
+    }
+  );
+
+  function renderDefaultValue() {
+    if (defaultValue !== undefined) {
+      if (typeof defaultValue === "string") {
+        return (
+          <div>
+            <strong>Default value: </strong>
+            <span>
+              <code>{defaultValue}</code>
+            </span>
+          </div>
+        );
+      }
+      return (
+        <div>
+          <strong>Default value: </strong>
+          <span>
+            <code>{JSON.stringify(defaultValue)}</code>
+          </span>
+        </div>
+      );
+    }
+    return undefined;
+  }
+
+  const renderExample = guard(toString(example), (example) => (
+    <div>
+      <strong>Example: </strong>
+      {example}
+    </div>
+  ));
+
+  const renderExamples = guard(examples, (examples) => {
+    const exampleEntries = Object.entries(examples);
+    return (
+      <>
+        <strong>Examples:</strong>
+        <SchemaTabs>
+          {exampleEntries.map(([exampleName, exampleProperties]) => (
+            // @ts-ignore
+            <TabItem value={exampleName} label={exampleName}>
+              {exampleProperties.summary && <p>{exampleProperties.summary}</p>}
+              {exampleProperties.description && (
+                <p>
+                  <strong>Description: </strong>
+                  <span>{exampleProperties.description}</span>
+                </p>
+              )}
+              <p>
+                <strong>Example: </strong>
+                <code>{exampleProperties.value}</code>
+              </p>
+            </TabItem>
+          ))}
+        </SchemaTabs>
+      </>
+    );
+  });
+
+  return (
+    <div className="openapi-params__list-item">
+      <span className="openapi-schema__container">
+        <strong
+          className={clsx("openapi-schema__property", {
+            "openapi-schema__strikethrough": deprecated,
+          })}
+        >
+          {name}
+        </strong>
+        {renderSchemaName}
+        {(required || deprecated) && (
+          <span className="openapi-schema__divider"></span>
+        )}
+        {renderSchemaRequired}
+        {renderDeprecated}
+      </span>
+      {renderQualifier}
+      {renderDescription}
+      {renderEnumDescriptions}
+      {renderDefaultValue()}
+      {renderExample}
+      {renderExamples}
+    </div>
+  );
+}
+
+export default ParamsItem;