mintlify 1.1.11 → 1.2.0

package/bin/mint/client/src/layouts/OpenApiContent.tsx

@@ -0,0 +1,301 @@
+import { useEffect, useState } from 'react';
+
+import { Expandable } from '@/components/Expandable';
+import { Heading } from '@/components/Heading';
+import { ParamField } from '@/components/Param';
+import { ResponseField } from '@/components/ResponseField';
+import { config } from '@/config';
+import { Component } from '@/enums/components';
+import { openApi } from '@/openapi';
+import { Api, APIBASE_CONFIG_STORAGE, ApiComponent } from '@/ui/Api';
+import { MediaType } from '@/utils/api';
+import { getOpenApiOperationMethodAndEndpoint } from '@/utils/getOpenApiContext';
+
+type OpenApiContentProps = {
+  openapi: string;
+  auth?: string;
+};
+
+const getType = (schema: any) => {
+  if (schema.type === 'string' && schema.format === 'binary') {
+    return 'file';
+  }
+  return schema.type;
+};
+
+const getMedia = (name: string): MediaType => {
+  switch (name) {
+    case 'multipart/form-data':
+      return 'form';
+    default:
+      return 'json';
+  }
+};
+
+const getEnumDescription = (enumArray?: string[]): React.ReactNode | null => {
+  if (enumArray == null || enumArray.length === 0) {
+    return null;
+  }
+  return (
+    <>
+      Allowed values:{' '}
+      {enumArray.map((val, i) => (
+        <>
+          <code>{val}</code>
+          {i !== enumArray.length - 1 && ', '}
+        </>
+      ))}
+    </>
+  );
+};
+
+function ExpandableFields({ schema }: any) {
+  const [expandedFields, setExpandedFields] = useState<Record<string, boolean>>({});
+  if (schema == null) {
+    return null;
+  }
+
+  if (schema.items) {
+    const name = schema.items.title;
+    return (
+      <ResponseField name={name} type={schema.items.type}>
+        <>
+          {schema.description}
+          <Expandable
+            title="properties"
+            defaultOpen={false}
+            onChange={(open) => {
+              setExpandedFields({ ...expandedFields, [name]: open });
+              return;
+            }}
+          >
+            <ExpandableFields schema={schema.items} />
+          </Expandable>
+        </>
+      </ResponseField>
+    );
+  }
+
+  // TBD: Cleanup response field by types
+  return (
+    <>
+      {schema.properties &&
+        Object.entries(schema.properties)
+          ?.sort(([propertyLeft], [propertyRight]) => {
+            // Brings all required to the top
+            return schema.required?.includes(propertyLeft)
+              ? -1
+              : schema.required?.includes(propertyRight)
+              ? 1
+              : 0;
+          })
+          .map(([property, value]: any) => {
+            const isArrayExpandable = Boolean(value.items && value.items.properties == null);
+            const type =
+              isArrayExpandable && value.items.type ? `${value.items.type}[]` : value.type;
+            return (
+              <ResponseField
+                key={property}
+                name={property}
+                required={schema.required?.includes(property)}
+                type={type}
+              >
+                {/* Is array nested */}
+                {value.items && !isArrayExpandable ? (
+                  <div className="mt-2">
+                    {value.description}
+                    <Expandable
+                      title={value.items.type || 'properties'}
+                      onChange={(open) => {
+                        setExpandedFields({ ...expandedFields, [property]: open });
+                        return;
+                      }}
+                    >
+                      <ExpandableFields schema={value.items} />
+                    </Expandable>
+                  </div>
+                ) : (
+                  <>
+                    {value.description || value.title || getEnumDescription(value.enum)}
+                    {value.properties && (
+                      <div className="mt-2">
+                        <Expandable
+                          title={value.type || 'properties'}
+                          onChange={(open) => {
+                            setExpandedFields({ ...expandedFields, [property]: open });
+                            return;
+                          }}
+                        >
+                          <ExpandableFields schema={value}></ExpandableFields>
+                        </Expandable>
+                      </div>
+                    )}
+                  </>
+                )}
+              </ResponseField>
+            );
+          })}
+    </>
+  );
+}
+
+export function OpenApiContent({ openapi, auth }: OpenApiContentProps) {
+  const [apiBaseIndex, setApiBaseIndex] = useState(0);
+  const { method, endpoint, operation } = getOpenApiOperationMethodAndEndpoint(openapi);
+  useEffect(() => {
+    const configuredApiBaseIndex = window.localStorage.getItem(APIBASE_CONFIG_STORAGE);
+    if (configuredApiBaseIndex != null) {
+      setApiBaseIndex(parseInt(configuredApiBaseIndex, 10));
+    }
+  }, [openapi]);
+
+  if (operation == null) {
+    return null;
+  }
+
+  let apiComponents: ApiComponent[] = [];
+
+  const Parameters = operation.parameters?.map((parameter: any, i: number) => {
+    const { name, description, required, schema, in: paramType } = parameter;
+    const paramName = { [paramType]: name };
+    const type = getType(schema);
+    apiComponents.push({
+      type: Component.ParamField,
+      attributes: [
+        {
+          type: 'mdx',
+          name: paramType,
+          value: name,
+        },
+        {
+          type: 'mdx',
+          name: 'required',
+          value: required,
+        },
+        {
+          type: 'mdx',
+          name: 'type',
+          value: type,
+        },
+        {
+          type: 'mdx',
+          name: 'default',
+          value: schema.default,
+        },
+        {
+          type: 'mdx',
+          name: 'enum',
+          value: schema.enum,
+        },
+      ],
+    });
+    return (
+      <ParamField
+        key={i}
+        {...paramName}
+        required={required}
+        type={type}
+        default={schema.default}
+        enum={schema.enum}
+      >
+        {description || schema.description || schema.title}
+      </ParamField>
+    );
+  });
+
+  const bodyContent = operation.requestBody?.content;
+  const contentMedia = bodyContent && Object.keys(bodyContent)[0];
+  const bodySchema = bodyContent && bodyContent[contentMedia]?.schema;
+
+  const Body =
+    bodySchema?.properties &&
+    Object.entries(bodySchema.properties)?.map(([property, value]: any, i: number) => {
+      const required = bodySchema.required?.includes(property);
+      const type = getType(value);
+      const bodyDefault = bodySchema.example
+        ? JSON.stringify(bodySchema.example[property])
+        : undefined;
+      const last = i + 1 === operation.parameters?.length;
+      apiComponents.push({
+        type: Component.ParamField,
+        attributes: [
+          {
+            type: 'mdx',
+            name: 'body',
+            value: property,
+          },
+          {
+            type: 'mdx',
+            name: 'required',
+            value: required,
+          },
+          {
+            type: 'mdx',
+            name: 'type',
+            value: type,
+          },
+          {
+            type: 'mdx',
+            name: 'default',
+            value: bodyDefault,
+          },
+          {
+            type: 'mdx',
+            name: 'enum',
+            value: value.enum,
+          },
+          {
+            type: 'mdx',
+            name: 'last',
+            value: last,
+          },
+        ],
+      });
+      return (
+        <ParamField
+          body={property}
+          required={required}
+          type={type}
+          default={bodyDefault}
+          enum={value.enum}
+          last={last}
+        >
+          {value.description || value.title}
+        </ParamField>
+      );
+    });
+
+  let responseSchema = operation.responses?.['200']?.content?.['application/json']?.schema;
+  // endpoint in OpenAPI refers to the path
+  const configBaseUrl =
+    config.api?.baseUrl ?? openApi?.servers?.map((server: { url: string }) => server.url);
+  const baseUrl =
+    configBaseUrl && Array.isArray(configBaseUrl) ? configBaseUrl[apiBaseIndex] : configBaseUrl;
+  const api = `${method} ${baseUrl}${endpoint}`;
+
+  return (
+    <div className="prose prose-slate dark:prose-dark">
+      <Api api={api} media={getMedia(contentMedia)} auth={auth} apiComponents={apiComponents} />
+      <div>
+        {Parameters?.length > 0 && (
+          <Heading level={3} id="parameters" nextElement={null}>
+            Parameters
+          </Heading>
+        )}
+        {Parameters}
+        {Body?.length > 0 && (
+          <Heading level={3} id="body" nextElement={null}>
+            Body
+          </Heading>
+        )}
+        <ExpandableFields schema={bodySchema} />
+        {responseSchema && (
+          <Heading level={3} id="response" nextElement={null}>
+            Response
+          </Heading>
+        )}
+        <ExpandableFields schema={responseSchema} />
+      </div>
+    </div>
+  );
+}

package/bin/mint/client/src/layouts/SidebarLayout.tsx

@@ -0,0 +1,412 @@
+import { FontAwesomeIcon } from '@fortawesome/react-fontawesome';
+import { Dialog } from '@headlessui/react';
+import clsx from 'clsx';
+import isAbsoluteUrl from 'is-absolute-url';
+import Link from 'next/link';
+import { useRouter } from 'next/router';
+import { ReactNode } from 'react';
+import { createContext, forwardRef, useRef, useState } from 'react';
+
+import { useIsomorphicLayoutEffect } from '@/hooks/useIsomorphicLayoutEffect';
+import { getGroupsInDivision, getGroupsNotInDivision } from '@/layouts/getGroupsInDivision';
+import { PageContext, Group, Groups, GroupPage, isGroup } from '@/metadata';
+import { extractMethodAndEndpoint } from '@/utils/api';
+import { getMethodDotsColor } from '@/utils/brands';
+
+import { config, findFirstNavigationEntry } from '../config';
+import { StyledTopLevelLink, TopLevelLink } from '../ui/TopLevelLink';
+import isPathInGroupPages from './isPathInGroupPages';
+
+type SidebarContextType = {
+  nav: any;
+  navIsOpen: boolean;
+  setNavIsOpen: (navIsOpen: boolean) => void;
+};
+
+// @ts-ignore
+export const SidebarContext = createContext<SidebarContextType>({
+  nav: [],
+  navIsOpen: false,
+  setNavIsOpen: () => {},
+});
+
+const getPaddingByLevel = (level: number) => {
+  switch (level) {
+    case 0:
+      return 'pl-4';
+    case 1:
+      return 'pl-7';
+    default:
+      return 'pl-10';
+  }
+};
+
+const NavItem = forwardRef(
+  ({ groupPage, level = 0 }: { groupPage: GroupPage | undefined; level?: number }, ref: any) => {
+    const router = useRouter();
+
+    if (groupPage == null) {
+      return null;
+    }
+
+    if (isGroup(groupPage)) {
+      return <GroupDropdown group={groupPage} level={level} />;
+    }
+
+    const { href, api: pageApi, openapi } = groupPage;
+
+    const isActive = groupPage.href === router.pathname;
+    const api = pageApi || openapi;
+    const title = groupPage.sidebarTitle || groupPage.title;
+
+    return (
+      <li ref={ref}>
+        <Link href={href || '/'}>
+          <a
+            className={clsx(
+              'flex border-l -ml-px',
+              isActive
+                ? 'text-primary border-current font-semibold dark:text-primary-light'
+                : 'border-transparent hover:border-slate-400 dark:hover:border-slate-500 text-slate-700 hover:text-slate-900 dark:text-slate-400 dark:hover:text-slate-300',
+              getPaddingByLevel(level),
+              config.classes?.navigationItem
+            )}
+          >
+            {api && (
+              <div
+                className={clsx('mt-[0.5rem] mr-2 h-2 w-2 rounded-sm', {
+                  'bg-primary dark:bg-primary-light': isActive,
+                  [getMethodDotsColor(extractMethodAndEndpoint(api).method)]: !isActive,
+                })}
+              />
+            )}
+            <div className="flex-1">{title}</div>
+          </a>
+        </Link>
+      </li>
+    );
+  }
+);
+
+const GroupDropdown = ({ group, level }: { group: Group; level: number }) => {
+  const [isOpen, setIsOpen] = useState(false);
+  const router = useRouter();
+  const { group: name, pages } = group;
+
+  if (!name || !pages) {
+    return null;
+  }
+
+  const onClick = () => {
+    // Do not navigate if:
+    // 1. closing
+    // 2. The first link is another nested menu
+    // 3. The current page is in the nested pages being exposed
+    if (
+      !isOpen &&
+      !isGroup(pages[0]) &&
+      pages[0]?.href &&
+      !isPathInGroupPages(router.pathname, pages)
+    ) {
+      // Navigate to the first page if it exists
+      router.push(pages[0].href);
+    }
+    setIsOpen(!isOpen);
+  };
+
+  return (
+    <>
+      <span
+        className={clsx(
+          'group flex items-center border-l -ml-px cursor-pointer space-x-3 border-transparent hover:border-slate-400 dark:hover:border-slate-500 text-slate-700 hover:text-slate-900 dark:text-slate-400 dark:hover:text-slate-300',
+          getPaddingByLevel(level)
+        )}
+        onClick={onClick}
+      >
+        <div>{name}</div>
+        <svg
+          width="3"
+          height="24"
+          viewBox="0 -9 3 24"
+          className={clsx(
+            'text-slate-400 overflow-visible group-hover:text-slate-600 dark:text-slate-600 dark:group-hover:text-slate-500',
+            isOpen && 'rotate-90'
+          )}
+        >
+          <path
+            d="M0 0L3 3L0 6"
+            fill="none"
+            stroke="currentColor"
+            strokeWidth="1.5"
+            strokeLinecap="round"
+          ></path>
+        </svg>
+      </span>
+      {isOpen && pages.map((subpage) => <NavItem groupPage={subpage} level={level + 1} />)}
+    </>
+  );
+};
+
+function nearestScrollableContainer(el: any) {
+  function isScrollable(el: Element) {
+    const style = window.getComputedStyle(el);
+    const overflowX = style['overflowX'];
+    const overflowY = style['overflowY'];
+    const canScrollY = el.clientHeight < el.scrollHeight;
+    const canScrollX = el.clientWidth < el.scrollWidth;
+
+    const isScrollableY = canScrollY && (overflowY === 'auto' || overflowY === 'scroll');
+    const isScrollableX = canScrollX && (overflowX === 'auto' || overflowX === 'scroll');
+
+    return isScrollableY || isScrollableX;
+  }
+
+  while (el && el !== document.body && isScrollable(el) === false) {
+    el = el.parentNode || el.host;
+  }
+
+  return el;
+}
+
+function Nav({ nav, children, mobile = false }: any) {
+  const router = useRouter();
+  const activeItemRef: any = useRef();
+  const previousActiveItemRef: any = useRef();
+  const scrollRef: any = useRef();
+
+  let numPages = 0;
+  if (nav) {
+    nav.forEach((group: { group: string; pages: string[] }) => {
+      numPages += group.pages.length;
+    });
+  }
+
+  useIsomorphicLayoutEffect(() => {
+    function updatePreviousRef() {
+      previousActiveItemRef.current = activeItemRef.current;
+    }
+
+    if (activeItemRef.current) {
+      if (activeItemRef.current === previousActiveItemRef.current) {
+        updatePreviousRef();
+        return;
+      }
+
+      updatePreviousRef();
+
+      const scrollable = nearestScrollableContainer(scrollRef.current);
+
+      const scrollRect = scrollable.getBoundingClientRect();
+      const activeItemRect = activeItemRef.current.getBoundingClientRect();
+
+      const top = activeItemRef.current.offsetTop;
+      const bottom = top - scrollRect.height + activeItemRect.height;
+
+      if (scrollable.scrollTop > top || scrollable.scrollTop < bottom) {
+        scrollable.scrollTop = top - scrollRect.height / 2 + activeItemRect.height / 2;
+      }
+    }
+  }, [router.pathname]);
+
+  return (
+    <nav ref={scrollRef} id="nav" className="lg:text-sm lg:leading-6 relative">
+      <div className="sticky top-0 -ml-0.5 pointer-events-none">
+        {!mobile && (
+          <div
+            className={clsx(
+              'h-8',
+              config.backgroundImage == null &&
+                'bg-gradient-to-b from-background-light dark:from-background-dark'
+            )}
+          />
+        )}
+      </div>
+      <ul>
+        {config?.anchors != null && config.anchors.length > 0 && <TopLevelNav mobile={mobile} />}
+        {children}
+        {nav &&
+          numPages > 0 &&
+          nav
+            .map(({ group, pages }: { group: string; pages: PageContext[] }, i: number) => {
+              return (
+                <li
+                  key={i}
+                  className={clsx({
+                    'mt-12 lg:mt-8': !Boolean(
+                      i === 0 && (config?.anchors == null || config.anchors?.length === 0)
+                    ),
+                  })}
+                >
+                  <h5 className="mb-8 lg:mb-3 font-semibold text-slate-900 dark:text-slate-200">
+                    {group}
+                  </h5>
+                  <ul
+                    className={clsx(
+                      'space-y-6 lg:space-y-2 border-l border-slate-100',
+                      mobile ? 'dark:border-slate-700' : 'dark:border-slate-800'
+                    )}
+                  >
+                    {pages.map((page, i: number) => {
+                      return <NavItem key={i} groupPage={page} />;
+                    })}
+                  </ul>
+                </li>
+              );
+            })
+            .filter(Boolean)}
+      </ul>
+    </nav>
+  );
+}
+
+function TopLevelNav({ mobile }: { mobile: boolean }) {
+  let { pathname } = useRouter();
+  const isRootAnchorActive =
+    pathname.startsWith('/') &&
+    !config.anchors?.some((anchor) => pathname.startsWith(`/${anchor.url}`));
+  return (
+    <>
+      <TopLevelLink
+        i={0}
+        mobile={mobile}
+        href="/"
+        isActive={isRootAnchorActive}
+        className="mb-4"
+        shadow="group-hover:shadow-primary-ultralight dark:group-hover:bg-primary"
+        icon={
+          <FontAwesomeIcon
+            className={clsx(
+              `h-6 w-6 p-1 text-white secondary-opacity group-hover:fill-primary-dark dark:group-hover:text-white`,
+              isRootAnchorActive ? 'dark:text-white' : 'dark:text-slate-500'
+            )}
+            icon={['fad', 'book-open']}
+          />
+        }
+      >
+        {config.topAnchor?.name ?? 'Documentation'}
+      </TopLevelLink>
+      {config?.anchors &&
+        config.anchors
+          .filter((anchor) => {
+            if (!anchor.isDefaultHidden) {
+              return true;
+            }
+
+            return pathname.startsWith(`/${anchor.url}`);
+          })
+          .map((anchor, i) => {
+            const isAbsolute = isAbsoluteUrl(anchor.url);
+            let href;
+            if (isAbsolute) {
+              href = anchor.url;
+            } else {
+              config.navigation?.every((nav) => {
+                const page = findFirstNavigationEntry(nav, `${anchor.url}/`);
+                if (page) {
+                  if (typeof page === 'string') {
+                    href = `/${page}`;
+                  } else {
+                    href = `/${page.pages[0]}`;
+                  }
+                  return false;
+                }
+                return true;
+              });
+            }
+
+            return (
+              <StyledTopLevelLink
+                i={i}
+                key={i}
+                mobile={mobile}
+                href={href || '/'}
+                name={anchor?.name}
+                icon={anchor?.icon}
+                color={anchor?.color}
+                isActive={pathname.startsWith(`/${anchor.url}`)}
+              />
+            );
+          })}
+    </>
+  );
+}
+
+function Wrapper({
+  allowOverflow,
+  children,
+}: {
+  allowOverflow: boolean;
+  children: React.ReactChild;
+}) {
+  return <div className={allowOverflow ? undefined : 'overflow-hidden'}>{children}</div>;
+}
+
+// TODO: Set remaining types
+export function SidebarLayout({
+  navIsOpen,
+  setNavIsOpen,
+  nav,
+  layoutProps: { allowOverflow = true } = {},
+  children,
+}: {
+  navIsOpen: boolean;
+  setNavIsOpen: any;
+  nav: Groups;
+  layoutProps?: any;
+  children: ReactNode;
+}) {
+  const router = useRouter();
+  const pathname = router.pathname;
+  const currentDivision = config.anchors?.find((anchor) => pathname.startsWith(`/${anchor.url}`));
+
+  let navForDivision = getGroupsInDivision(nav, currentDivision?.url ? [currentDivision?.url] : []);
+
+  if (navForDivision.length === 0) {
+    // Base docs include everything NOT in an anchor
+    const divisions = config.anchors?.filter((anchor) => !isAbsoluteUrl(anchor.url)) || [];
+    navForDivision = getGroupsNotInDivision(
+      nav,
+      divisions.map((division) => division.url)
+    );
+  }
+
+  return (
+    <SidebarContext.Provider value={{ nav, navIsOpen, setNavIsOpen }}>
+      <Wrapper allowOverflow={allowOverflow}>
+        <div className="max-w-8xl mx-auto px-4 sm:px-6 md:px-8">
+          <div className="hidden lg:block fixed z-20 top-[3.8125rem] bottom-0 left-[max(0px,calc(50%-45rem))] right-auto w-[19.5rem] pb-10 px-8 overflow-y-auto">
+            <Nav nav={navForDivision} />
+          </div>
+          <div className="lg:pl-[20rem]">{children}</div>
+        </div>
+      </Wrapper>
+      <Dialog
+        as="div"
+        open={navIsOpen}
+        onClose={() => setNavIsOpen(false)}
+        className="fixed z-50 inset-0 overflow-y-auto lg:hidden"
+      >
+        <Dialog.Overlay className="fixed inset-0 bg-black/20 backdrop-blur-sm dark:bg-slate-900/80" />
+        <div className="relative bg-white w-80 min-h-full max-w-[calc(100%-3rem)] p-6 dark:bg-slate-800">
+          <button
+            type="button"
+            onClick={() => setNavIsOpen(false)}
+            className="absolute z-10 top-5 right-5 w-8 h-8 flex items-center justify-center text-slate-500 hover:text-slate-600 dark:text-slate-400 dark:hover:text-slate-300"
+          >
+            <span className="sr-only">Close navigation</span>
+            <svg viewBox="0 0 10 10" className="w-2.5 h-2.5 overflow-visible">
+              <path
+                d="M0 0L10 10M10 0L0 10"
+                fill="none"
+                stroke="currentColor"
+                strokeWidth="2"
+                strokeLinecap="round"
+              />
+            </svg>
+          </button>
+          <Nav nav={navForDivision} mobile={true} />
+        </div>
+      </Dialog>
+    </SidebarContext.Provider>
+  );
+}