@stoplight/elements 9.0.11 → 9.0.12-beta-0.2

package/src/containers/API.tsx

@@ -0,0 +1,277 @@
+import {
+  InlineRefResolverProvider,
+  NonIdealState,
+  RoutingProps,
+  useBundleRefsIntoDocument,
+  useParsedValue,
+  useResponsiveLayout,
+  withMosaicProvider,
+  withPersistenceBoundary,
+  withQueryClientProvider,
+  withRouter,
+  withStyles,
+} from '@stoplight/elements-core';
+import { ExtensionAddonRenderer } from '@stoplight/elements-core/components/Docs';
+import { Box, Flex, Icon } from '@stoplight/mosaic';
+import { flow } from 'lodash';
+import * as React from 'react';
+import { useQuery } from 'react-query';
+import { useLocation } from 'react-router-dom';
+
+import { APIWithResponsiveSidebarLayout } from '../components/API/APIWithResponsiveSidebarLayout';
+import { APIWithSidebarLayout } from '../components/API/APIWithSidebarLayout';
+import { APIWithStackedLayout } from '../components/API/APIWithStackedLayout';
+import { useExportDocumentProps } from '../hooks/useExportDocumentProps';
+import { transformOasToServiceNode } from '../utils/oas';
+
+export type APIProps = APIPropsWithDocument | APIPropsWithUrl;
+
+export type APIPropsWithUrl = {
+  /**
+   * Specify the URL of the input OAS2/3 document here.
+   *
+   * Mutually exclusive with `apiDescriptionDocument`.
+   */
+  apiDescriptionUrl: string;
+} & CommonAPIProps;
+export type APIPropsWithDocument = {
+  /**
+   * You can specify the input OAS2/3 document here directly in JSON or YAML format.
+   *
+   * Mutually exclusive with `apiDescriptionUrl`.
+   */
+  apiDescriptionDocument: string | object;
+  apiDescriptionUrl?: string;
+} & CommonAPIProps;
+
+export interface CommonAPIProps extends RoutingProps {
+  /**
+   * The API component supports two layout options.
+   *
+   * - Sidebar: Navigation on the left side, resembles Stoplight Platform.
+   * - Stacked: No sidebar, resembles the structure of Swagger UI.
+   *
+   * @default "sidebar"
+   */
+  layout?: 'sidebar' | 'stacked' | 'responsive';
+  logo?: string;
+
+  hideTryIt?: boolean;
+  /**
+   * Allows to hide RequestSamples component
+   * @default false
+   */
+
+  hideSamples?: boolean;
+  /**
+   * Shows only operation document without right column
+   * @default false
+   */
+
+  hideTryItPanel?: boolean;
+
+  /**
+   * Allows hiding the Security info section
+   */
+  hideSecurityInfo?: boolean;
+
+  /**
+   * Allows hiding the Server info section
+   */
+  hideServerInfo?: boolean;
+
+  /**
+   * Hides schemas from being displayed in Table of Contents
+   */
+  hideSchemas?: boolean;
+
+  /**
+   * Hides models and operations marked as internal
+   * @default false
+   */
+  hideInternal?: boolean;
+
+  /**
+   * Hides export button from being displayed in overview page
+   * @default false
+   */
+  hideExport?: boolean;
+
+  /**
+   * Fetch credentials policy for TryIt component
+   * For more information: https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API
+   * @default "omit"
+   */
+
+  tryItCredentialsPolicy?: 'omit' | 'include' | 'same-origin';
+
+  /**
+   * Url of a CORS proxy that will be used to send requests in TryIt.
+   * Provided url will be prepended to an URL of an actual request.
+   * @default false
+   */
+  tryItCorsProxy?: string;
+
+  /**
+   * The amount of references deep should be presented.
+   * @default undefined
+   */
+  maxRefDepth?: number;
+
+  /**
+   * Allows to define renderers for vendor extensions
+   */
+  renderExtensionAddon?: ExtensionAddonRenderer;
+
+  outerRouter?: boolean;
+}
+
+const propsAreWithDocument = (props: APIProps): props is APIPropsWithDocument => {
+  return props.hasOwnProperty('apiDescriptionDocument');
+};
+
+export const APIImpl: React.FC<APIProps> = props => {
+  const {
+    layout = 'sidebar',
+    apiDescriptionUrl = '',
+    logo,
+    hideTryItPanel,
+    hideTryIt,
+    hideSamples,
+    hideSecurityInfo,
+    hideServerInfo,
+    hideSchemas,
+    hideInternal,
+    hideExport,
+    tryItCredentialsPolicy,
+    tryItCorsProxy,
+    maxRefDepth,
+    renderExtensionAddon,
+    basePath,
+    outerRouter = false,
+  } = props;
+  const location = useLocation();
+  const apiDescriptionDocument = propsAreWithDocument(props) ? props.apiDescriptionDocument : undefined;
+  const { isResponsiveLayoutEnabled } = useResponsiveLayout();
+
+  const { data: fetchedDocument, error } = useQuery(
+    [apiDescriptionUrl],
+    () =>
+      fetch(apiDescriptionUrl).then(res => {
+        if (res.ok) {
+          return res.text();
+        }
+        throw new Error(`Unable to load description document, status code: ${res.status}`);
+      }),
+    {
+      enabled: apiDescriptionUrl !== '' && !apiDescriptionDocument,
+    },
+  );
+
+  const document = apiDescriptionDocument || fetchedDocument || '';
+  const parsedDocument = useParsedValue(document);
+  const bundledDocument = useBundleRefsIntoDocument(parsedDocument, { baseUrl: apiDescriptionUrl });
+  const serviceNode = React.useMemo(() => transformOasToServiceNode(bundledDocument), [bundledDocument]);
+  const exportProps = useExportDocumentProps({ originalDocument: document, bundledDocument });
+
+  if (error) {
+    return (
+      <Flex justify="center" alignItems="center" w="full" minH="screen">
+        <NonIdealState
+          title="Document could not be loaded"
+          description="The API description document could not be fetched. This could indicate connectivity problems, or issues with the server hosting the spec."
+          icon="exclamation-triangle"
+        />
+      </Flex>
+    );
+  }
+
+  if (!bundledDocument) {
+    return (
+      <Flex justify="center" alignItems="center" w="full" minH="screen" color="light">
+        <Box as={Icon} icon={['fal', 'circle-notch']} size="3x" spin />
+      </Flex>
+    );
+  }
+
+  if (!serviceNode) {
+    return (
+      <Flex justify="center" alignItems="center" w="full" minH="screen">
+        <NonIdealState
+          title="Failed to parse OpenAPI file"
+          description="Please make sure your OpenAPI file is valid and try again"
+        />
+      </Flex>
+    );
+  }
+
+  return (
+    <InlineRefResolverProvider document={parsedDocument} maxRefDepth={maxRefDepth}>
+      {layout === 'stacked' && (
+        <APIWithStackedLayout
+          serviceNode={serviceNode}
+          hideTryIt={hideTryIt}
+          hideSamples={hideSamples}
+          hideTryItPanel={hideTryItPanel}
+          hideSecurityInfo={hideSecurityInfo}
+          hideServerInfo={hideServerInfo}
+          hideExport={hideExport}
+          exportProps={exportProps}
+          tryItCredentialsPolicy={tryItCredentialsPolicy}
+          tryItCorsProxy={tryItCorsProxy}
+          renderExtensionAddon={renderExtensionAddon}
+          location={location}
+        />
+      )}
+      {layout === 'sidebar' && (
+        <APIWithSidebarLayout
+          logo={logo}
+          serviceNode={serviceNode}
+          hideTryItPanel={hideTryItPanel}
+          hideTryIt={hideTryIt}
+          hideSamples={hideSamples}
+          hideSecurityInfo={hideSecurityInfo}
+          hideServerInfo={hideServerInfo}
+          hideSchemas={hideSchemas}
+          hideInternal={hideInternal}
+          hideExport={hideExport}
+          exportProps={exportProps}
+          tryItCredentialsPolicy={tryItCredentialsPolicy}
+          tryItCorsProxy={tryItCorsProxy}
+          renderExtensionAddon={renderExtensionAddon}
+          basePath={basePath}
+          outerRouter={outerRouter}
+        />
+      )}
+      {layout === 'responsive' && (
+        <APIWithResponsiveSidebarLayout
+          logo={logo}
+          serviceNode={serviceNode}
+          hideTryItPanel={hideTryItPanel}
+          hideTryIt={hideTryIt}
+          hideSamples={hideSamples}
+          hideSecurityInfo={hideSecurityInfo}
+          hideServerInfo={hideServerInfo}
+          hideSchemas={hideSchemas}
+          hideInternal={hideInternal}
+          hideExport={hideExport}
+          exportProps={exportProps}
+          tryItCredentialsPolicy={tryItCredentialsPolicy}
+          tryItCorsProxy={tryItCorsProxy}
+          renderExtensionAddon={renderExtensionAddon}
+          compact={isResponsiveLayoutEnabled}
+          basePath={basePath}
+          outerRouter={outerRouter}
+        />
+      )}
+    </InlineRefResolverProvider>
+  );
+};
+
+export const API = flow(
+  withRouter,
+  withStyles,
+  withPersistenceBoundary,
+  withMosaicProvider,
+  withQueryClientProvider,
+)(APIImpl);

package/src/containers/story-helper.tsx

@@ -0,0 +1,53 @@
+import { ElementsOptionsProvider } from '@stoplight/elements-core/context/Options';
+import { MarkdownViewer } from '@stoplight/markdown-viewer';
+import { Box } from '@stoplight/mosaic';
+import * as React from 'react';
+
+/**
+ * Renders the known x-enum-Description vendor extension
+ * @returns React.ReactElement
+ */
+// eslint-disable-next-line storybook/prefer-pascal-case
+export const renderExtensionRenderer = (props: any) => {
+  const { nestingLevel, schemaNode: node, vendorExtensions } = props;
+
+  // If the nesting level is 0, we are at the root of the schema and should not render anything
+  if (nestingLevel === 0) {
+    return null;
+  }
+
+  // This implementation of the extension renderer only supports the `x-enum-descriptions`-extension
+  if ('x-enum-descriptions' in vendorExtensions) {
+    const { 'x-enum-descriptions': enumDescriptions = {} } = vendorExtensions;
+
+    let value = `| Enum value | Description |\n|---|---|\n`;
+    const enums = node.enum ?? [];
+    enums.forEach((name: string) => {
+      const description = enumDescriptions[name as string];
+      value += `| ${name} | ${description} |\n`;
+    });
+
+    return (
+      <Box mb={2}>
+        <Box
+          mt={2}
+          as={MarkdownViewer}
+          markdown={value}
+          style={{
+            fontSize: 12,
+          }}
+        />
+      </Box>
+    );
+  }
+
+  return null;
+};
+
+/**
+ * @private
+ * Helper function to wrap the options context for the Docs subcomponents
+ */
+export const wrapOptionsContext = (story: any) => {
+  return <ElementsOptionsProvider renderExtensionAddon={renderExtensionRenderer}>{story}</ElementsOptionsProvider>;
+};

package/src/hooks/useExportDocumentProps.spec.tsx

@@ -0,0 +1,68 @@
+import '@testing-library/jest-dom';
+
+import { safeStringify } from '@stoplight/yaml';
+import { act, renderHook } from '@testing-library/react-hooks';
+import { saveAs } from 'file-saver';
+
+import { InstagramAPI as bundledJson } from '../__fixtures__/api-descriptions/Instagram';
+import { simpleApiWithoutDescription as json } from '../__fixtures__/api-descriptions/simpleApiWithoutDescription';
+import { todosApiBundled as bundledYaml } from '../__fixtures__/api-descriptions/todosApiBundled';
+import { zoomApiYaml as yaml } from '../__fixtures__/api-descriptions/zoomApiYaml';
+import { useExportDocumentProps } from './useExportDocumentProps';
+
+jest.mock('file-saver');
+
+describe('useExportDocumentProps', () => {
+  afterEach(() => {
+    jest.resetAllMocks();
+  });
+  it('exports json document', () => {
+    const data = renderHook(() =>
+      useExportDocumentProps({
+        originalDocument: json,
+        bundledDocument: bundledJson,
+      }),
+    );
+
+    act(() => {
+      data.result.current.original.onPress();
+      data.result.current.bundled.onPress();
+    });
+
+    const expectedOriginalDocument = new Blob([JSON.stringify(json, null, 2)], {
+      type: 'application/json',
+    });
+
+    const expectedBundledDocument = new Blob([JSON.stringify(bundledJson, null, 2)], {
+      type: 'application/json',
+    });
+    expect(saveAs).toBeCalledTimes(2);
+    expect(saveAs).toHaveBeenCalledWith(expectedOriginalDocument, 'document.json');
+    expect(saveAs).toHaveBeenCalledWith(expectedBundledDocument, 'document.json');
+  });
+
+  it('exports yaml document', () => {
+    const data = renderHook(() =>
+      useExportDocumentProps({
+        originalDocument: safeStringify(yaml),
+        bundledDocument: bundledYaml,
+      }),
+    );
+
+    act(() => {
+      data.result.current.original.onPress();
+      data.result.current.bundled.onPress();
+    });
+
+    const expectedOriginalDocument = new Blob([safeStringify(yaml)], {
+      type: 'application/yaml',
+    });
+
+    const expectedBundledDocument = new Blob([safeStringify(bundledYaml)], {
+      type: 'application/yaml',
+    });
+    expect(saveAs).toBeCalledTimes(2);
+    expect(saveAs).toHaveBeenCalledWith(expectedOriginalDocument, 'document.yaml');
+    expect(saveAs).toHaveBeenCalledWith(expectedBundledDocument, 'document.yaml');
+  });
+});

package/src/hooks/useExportDocumentProps.tsx

@@ -0,0 +1,48 @@
+import { safeStringify } from '@stoplight/yaml';
+import saver from 'file-saver';
+import * as React from 'react';
+
+import { isJson } from '../utils/oas';
+
+export function useExportDocumentProps({
+  originalDocument,
+  bundledDocument,
+}: {
+  originalDocument: string | object;
+  bundledDocument: unknown;
+}) {
+  const isJsonDocument = typeof originalDocument === 'object' || (!!originalDocument && isJson(originalDocument));
+
+  const exportDocument = React.useCallback(
+    (document: string) => {
+      const type = isJsonDocument ? 'json' : 'yaml';
+      const blob = new Blob([document], {
+        type: `application/${type}`,
+      });
+      saver.saveAs(blob, `document.${type}`);
+    },
+    [isJsonDocument],
+  );
+
+  const exportOriginalDocument = React.useCallback(() => {
+    const stringifiedDocument =
+      typeof originalDocument === 'object' ? JSON.stringify(originalDocument, null, 2) : originalDocument || '';
+    exportDocument(stringifiedDocument);
+  }, [originalDocument, exportDocument]);
+
+  const exportBundledDocument = React.useCallback(() => {
+    const stringifiedDocument = isJsonDocument
+      ? JSON.stringify(bundledDocument, null, 2)
+      : safeStringify(bundledDocument);
+    exportDocument(stringifiedDocument);
+  }, [bundledDocument, isJsonDocument, exportDocument]);
+
+  return {
+    original: {
+      onPress: exportOriginalDocument,
+    },
+    bundled: {
+      onPress: exportBundledDocument,
+    },
+  };
+}

package/src/index.ts

@@ -0,0 +1,6 @@
+export { APIWithStackedLayout } from './components/API/APIWithStackedLayout';
+export type { APIProps } from './containers/API';
+export { API } from './containers/API';
+export { useExportDocumentProps } from './hooks/useExportDocumentProps';
+export { transformOasToServiceNode } from './utils/oas';
+export type { ServiceNode } from './utils/oas/types';

package/src/styles.css

@@ -0,0 +1 @@
+@import "../../elements-core/src/styles.css";