@jpmorganchase/elemental 1.0.0

package/src/components/API/utils.ts

@@ -0,0 +1,174 @@
+import { isHttpOperation, isHttpService, TableOfContentsItem } from '@stoplight/elements-core';
+import { NodeType } from '@stoplight/types';
+import { defaults } from 'lodash';
+
+import { OperationNode, ServiceChildNode, ServiceNode } from '../../utils/oas/types';
+
+export type TagGroup = { title: string; items: OperationNode[] };
+
+export const computeTagGroups = (serviceNode: ServiceNode) => {
+  const groupsByTagId: { [tagId: string]: TagGroup } = {};
+  const ungrouped = [];
+
+  const lowerCaseServiceTags = serviceNode.tags.map(tn => tn.toLowerCase());
+
+  for (const node of serviceNode.children) {
+    if (node.type !== NodeType.HttpOperation) continue;
+    const tagName = node.tags[0];
+
+    if (tagName) {
+      const tagId = tagName.toLowerCase();
+      if (groupsByTagId[tagId]) {
+        groupsByTagId[tagId].items.push(node);
+      } else {
+        const serviceTagIndex = lowerCaseServiceTags.findIndex(tn => tn === tagId);
+        const serviceTagName = serviceNode.tags[serviceTagIndex];
+        groupsByTagId[tagId] = {
+          title: serviceTagName || tagName,
+          items: [node],
+        };
+      }
+    } else {
+      ungrouped.push(node);
+    }
+  }
+
+  const orderedTagGroups = Object.entries(groupsByTagId)
+    .sort(([g1], [g2]) => {
+      const g1LC = g1.toLowerCase();
+      const g2LC = g2.toLowerCase();
+      const g1Idx = lowerCaseServiceTags.findIndex(tn => tn === g1LC);
+      const g2Idx = lowerCaseServiceTags.findIndex(tn => tn === g2LC);
+
+      // Move not-tagged groups to the bottom
+      if (g1Idx < 0 && g2Idx < 0) return 0;
+      if (g1Idx < 0) return 1;
+      if (g2Idx < 0) return -1;
+
+      // sort tagged groups according to the order found in HttpService
+      return g1Idx - g2Idx;
+    })
+    .map(([, tagGroup]) => tagGroup);
+
+  return { groups: orderedTagGroups, ungrouped };
+};
+
+interface ComputeAPITreeConfig {
+  hideSchemas?: boolean;
+  hideInternal?: boolean;
+}
+
+const defaultComputerAPITreeConfig = {
+  hideSchemas: false,
+  hideInternal: false,
+};
+
+export const computeAPITree = (serviceNode: ServiceNode, config: ComputeAPITreeConfig = {}) => {
+  const mergedConfig = defaults(config, defaultComputerAPITreeConfig);
+  const tree: TableOfContentsItem[] = [];
+
+  tree.push({
+    id: '/',
+    slug: '/',
+    title: 'Overview',
+    type: 'overview',
+    meta: '',
+  });
+
+  const operationNodes = serviceNode.children.filter(node => node.type === NodeType.HttpOperation);
+  if (operationNodes.length) {
+    tree.push({
+      title: 'Endpoints',
+    });
+
+    const { groups, ungrouped } = computeTagGroups(serviceNode);
+
+    // Show ungroupped operations above tag groups
+    ungrouped.forEach(operationNode => {
+      if (mergedConfig.hideInternal && operationNode.data.internal) {
+        return;
+      }
+      tree.push({
+        id: operationNode.uri,
+        slug: operationNode.uri,
+        title: operationNode.name,
+        type: operationNode.type,
+        meta: operationNode.data.method,
+      });
+    });
+
+    groups.forEach(group => {
+      const items = group.items.flatMap(operationNode => {
+        if (mergedConfig.hideInternal && operationNode.data.internal) {
+          return [];
+        }
+        return {
+          id: operationNode.uri,
+          slug: operationNode.uri,
+          title: operationNode.name,
+          type: operationNode.type,
+          meta: operationNode.data.method,
+        };
+      });
+      if (items.length > 0) {
+        tree.push({
+          title: group.title,
+          items,
+        });
+      }
+    });
+  }
+
+  let schemaNodes = serviceNode.children.filter(node => node.type === NodeType.Model);
+  if (mergedConfig.hideInternal) {
+    schemaNodes = schemaNodes.filter(node => !node.data['x-internal']);
+  }
+
+  if (!mergedConfig.hideSchemas && schemaNodes.length) {
+    tree.push({
+      title: 'Schemas',
+    });
+
+    schemaNodes.forEach(node => {
+      tree.push({
+        id: node.uri,
+        slug: node.uri,
+        title: node.name,
+        type: node.type,
+        meta: '',
+      });
+    });
+  }
+  return tree;
+};
+
+export const findFirstNodeSlug = (tree: TableOfContentsItem[]): string | void => {
+  for (const item of tree) {
+    if ('slug' in item) {
+      return item.slug;
+    }
+
+    if ('items' in item) {
+      const slug = findFirstNodeSlug(item.items);
+      if (slug) {
+        return slug;
+      }
+    }
+  }
+
+  return;
+};
+
+export const isInternal = (node: ServiceChildNode | ServiceNode): boolean => {
+  const data = node.data;
+
+  if (isHttpOperation(data)) {
+    return !!data.internal;
+  }
+
+  if (isHttpService(data)) {
+    return false;
+  }
+
+  return !!data['x-internal'];
+};

package/src/containers/API.spec.tsx

@@ -0,0 +1,131 @@
+import '@testing-library/jest-dom';
+
+import {
+  withMosaicProvider,
+  withPersistenceBoundary,
+  withQueryClientProvider,
+  withStyles,
+} from '@stoplight/elements-core';
+import { render, screen } from '@testing-library/react';
+import { createMemoryHistory } from 'history';
+import { flow } from 'lodash';
+import * as React from 'react';
+import { Route, Router } from 'react-router';
+
+import { InstagramAPI } from '../__fixtures__/api-descriptions/Instagram';
+import { simpleApiWithoutDescription } from '../__fixtures__/api-descriptions/simpleApiWithoutDescription';
+import { API, APIImpl } from './API';
+
+export const APIWithoutRouter = flow(
+  withStyles,
+  withPersistenceBoundary,
+  withMosaicProvider,
+  withQueryClientProvider,
+)(APIImpl);
+
+describe('API', () => {
+  const APIDocument = {
+    ...InstagramAPI,
+    info: {
+      ...InstagramAPI.info,
+      'x-logo': {
+        ...InstagramAPI.info['x-logo'],
+        altText: 'instagram-logo',
+      },
+    },
+  };
+
+  // we need to add scrollTo to the Element prototype before we mount so it has the method available
+  Element.prototype.scrollTo = () => {};
+
+  it('displays logo specified in x-logo property of API document', async () => {
+    render(<API layout="sidebar" apiDescriptionDocument={InstagramAPI} />);
+
+    // checks if altText defaults to "logo" if the prop is not passed in API document
+    // checks if logo is present
+    expect(await screen.findByAltText('logo')).toBeInTheDocument();
+  });
+
+  it('uses the altText property from the API document', async () => {
+    render(<API layout="sidebar" apiDescriptionDocument={APIDocument} />);
+
+    expect(await screen.findByAltText('instagram-logo')).toBeInTheDocument();
+  });
+
+  it("doesn't display the logo when no properties are passed neither via API document nor as component prop", () => {
+    render(<API layout="sidebar" apiDescriptionDocument={simpleApiWithoutDescription} />);
+
+    expect(screen.queryByAltText('logo')).not.toBeInTheDocument();
+  });
+
+  it('overrides the logo from API document with the one passed in a prop', async () => {
+    render(<API logo="thisisarequiredprop" layout="sidebar" apiDescriptionDocument={APIDocument} />);
+
+    expect(screen.queryByAltText('instagram-logo')).not.toBeInTheDocument();
+    expect(await screen.findByAltText('logo')).toBeInTheDocument();
+  });
+
+  it('displays internal operations by default', () => {
+    const history = createMemoryHistory();
+    history.push('/paths/internal-operation/get');
+
+    const { unmount } = render(
+      <Router history={history}>
+        <Route path="/">
+          <APIWithoutRouter layout="sidebar" apiDescriptionDocument={APIDocument} />
+        </Route>
+      </Router>,
+    );
+
+    expect(screen.getByText('If you see this, something went wrong')).toBeInTheDocument();
+
+    unmount();
+  });
+
+  it('displays internal models by default', () => {
+    const history = createMemoryHistory();
+    history.push('/schemas/InternalObject');
+
+    render(
+      <Router history={history}>
+        <Route path="/">
+          <APIWithoutRouter layout="sidebar" apiDescriptionDocument={APIDocument} />
+        </Route>
+      </Router>,
+    );
+
+    expect(screen.getByText('Cool object, but internal.')).toBeInTheDocument();
+  });
+
+  it('reroutes to main page on internal operation if hideInternal is on', () => {
+    const history = createMemoryHistory();
+    history.push('/paths/internal-operation/get');
+
+    render(
+      <Router history={history}>
+        <Route path="/">
+          <APIWithoutRouter layout="sidebar" apiDescriptionDocument={APIDocument} hideInternal />
+        </Route>
+      </Router>,
+    );
+
+    expect(screen.queryByText('If you see this, something went wrong')).not.toBeInTheDocument();
+    expect(history.location.pathname).toBe('/');
+  });
+
+  it('reroutes to main page on internal model if hideInternal is on', () => {
+    const history = createMemoryHistory();
+    history.push('/schemas/InternalObject');
+
+    render(
+      <Router history={history}>
+        <Route path="/">
+          <APIWithoutRouter layout="sidebar" apiDescriptionDocument={APIDocument} hideInternal />
+        </Route>
+      </Router>,
+    );
+
+    expect(screen.queryByText('Cool object, but internal.')).not.toBeInTheDocument();
+    expect(history.location.pathname).toBe('/');
+  });
+});

package/src/containers/API.stories.tsx

@@ -0,0 +1,99 @@
+import { parse } from '@stoplight/yaml';
+import { Story } from '@storybook/react';
+import * as React from 'react';
+
+import { badgesForSchema } from '../__fixtures__/api-descriptions/badgesForSchema';
+import { simpleApiWithInternalOperations } from '../__fixtures__/api-descriptions/simpleApiWithInternalOperations';
+import { simpleApiWithoutDescription } from '../__fixtures__/api-descriptions/simpleApiWithoutDescription';
+import { todosApiBundled } from '../__fixtures__/api-descriptions/todosApiBundled';
+import { zoomApiYaml } from '../__fixtures__/api-descriptions/zoomApiYaml';
+import { API, APIProps } from './API';
+
+export default {
+  title: 'Public/API',
+  component: API,
+  argTypes: {
+    apiDescriptionDocument: { control: 'text', type: { required: false }, table: { category: 'Input' } },
+    apiDescriptionUrl: { control: 'text', table: { category: 'Input' } },
+    layout: {
+      control: { type: 'inline-radio' },
+      table: { category: 'UI' },
+    },
+    basePath: { table: { category: 'Routing' } },
+    router: { table: { category: 'Routing' } },
+  },
+  args: {
+    router: 'memory',
+  },
+};
+
+const Template: Story<APIProps> = args => <API {...args} />;
+
+export const APIWithYamlProvidedDirectly = Template.bind({});
+APIWithYamlProvidedDirectly.args = {
+  apiDescriptionDocument: zoomApiYaml,
+};
+APIWithYamlProvidedDirectly.storyName = 'Direct YAML Input (Zoom)';
+
+export const APIWithJSONProvidedDirectly = Template.bind({});
+APIWithJSONProvidedDirectly.args = {
+  apiDescriptionDocument: JSON.stringify(parse(zoomApiYaml), null, '  '),
+};
+APIWithJSONProvidedDirectly.storyName = 'Direct JSON Input (Zoom)';
+
+export const APIWithoutDescription = Template.bind({});
+APIWithoutDescription.args = {
+  apiDescriptionDocument: JSON.stringify(simpleApiWithoutDescription, null, 2),
+};
+APIWithoutDescription.storyName = 'API Without Description';
+
+export const APIWithInternalOperations = Template.bind({});
+APIWithInternalOperations.args = {
+  apiDescriptionDocument: JSON.stringify(simpleApiWithInternalOperations, null, 2),
+};
+APIWithInternalOperations.storyName = 'API With Internal Operations';
+
+export const OpenApi3Schema = Template.bind({});
+OpenApi3Schema.args = {
+  apiDescriptionDocument: todosApiBundled,
+};
+OpenApi3Schema.storyName = 'Open Api 3.0 Schema';
+
+export const BadgesForSchema = Template.bind({});
+BadgesForSchema.args = {
+  apiDescriptionDocument: badgesForSchema,
+};
+BadgesForSchema.storyName = 'Badges For Schema';
+
+export const StackedLayout = Template.bind({});
+StackedLayout.args = {
+  apiDescriptionDocument: JSON.stringify(parse(zoomApiYaml), null, '  '),
+  layout: 'stacked',
+};
+StackedLayout.storyName = 'Stacked Layout (Zoom)';
+
+export const Box = Template.bind({});
+Box.args = {
+  apiDescriptionUrl: 'https://raw.githubusercontent.com/box/box-openapi/main/content/openapi.yml',
+};
+Box.storyName = 'Box';
+
+export const DigitalOcean = Template.bind({});
+DigitalOcean.args = {
+  apiDescriptionUrl:
+    'https://raw.githubusercontent.com/digitalocean/openapi/main/specification/DigitalOcean-public.v2.yaml',
+};
+DigitalOcean.storyName = 'DigitalOcean';
+
+export const Github = Template.bind({});
+Github.args = {
+  apiDescriptionUrl:
+    'https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/ghes-3.0/ghes-3.0.json',
+};
+Github.storyName = 'GitHub';
+
+export const Instagram = Template.bind({});
+Instagram.args = {
+  apiDescriptionUrl: 'https://api.apis.guru/v2/specs/instagram.com/1.0.0/swagger.yaml',
+};
+Instagram.storyName = 'Instagram';

package/src/containers/API.tsx

@@ -0,0 +1,200 @@
+import {
+  InlineRefResolverProvider,
+  NonIdealState,
+  RoutingProps,
+  useBundleRefsIntoDocument,
+  useParsedValue,
+  withMosaicProvider,
+  withPersistenceBoundary,
+  withQueryClientProvider,
+  withRouter,
+  withStyles,
+} from '@stoplight/elements-core';
+import { Box, Flex, Icon } from '@stoplight/mosaic';
+import { flow } from 'lodash';
+import * as React from 'react';
+import { useQuery } from 'react-query';
+
+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';
+  logo?: string;
+
+  /**
+   * Allows hiding the TryIt component
+   */
+  hideTryIt?: 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;
+  tryItOutDefaultServer?: string;
+}
+
+const propsAreWithDocument = (props: APIProps): props is APIPropsWithDocument => {
+  return props.hasOwnProperty('apiDescriptionDocument');
+};
+
+export const APIImpl: React.FC<APIProps> = props => {
+  const {
+    layout,
+    apiDescriptionUrl = '',
+    logo,
+    hideTryIt,
+    hideSchemas,
+    hideInternal,
+    hideExport,
+    tryItCredentialsPolicy,
+    tryItCorsProxy,
+    tryItOutDefaultServer,
+  } = props;
+  const apiDescriptionDocument = propsAreWithDocument(props) ? props.apiDescriptionDocument : undefined;
+
+  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}>
+      {layout === 'stacked' ? (
+        <APIWithStackedLayout
+          serviceNode={serviceNode}
+          hideTryIt={hideTryIt}
+          hideExport={hideExport}
+          exportProps={exportProps}
+          tryItCredentialsPolicy={tryItCredentialsPolicy}
+          tryItCorsProxy={tryItCorsProxy}
+          tryItOutDefaultServer={tryItOutDefaultServer}
+        />
+      ) : (
+        <APIWithSidebarLayout
+          logo={logo}
+          serviceNode={serviceNode}
+          hideTryIt={hideTryIt}
+          hideSchemas={hideSchemas}
+          hideInternal={hideInternal}
+          hideExport={hideExport}
+          exportProps={exportProps}
+          tryItCredentialsPolicy={tryItCredentialsPolicy}
+          tryItCorsProxy={tryItCorsProxy}
+          tryItOutDefaultServer={tryItOutDefaultServer}
+        />
+      )}
+    </InlineRefResolverProvider>
+  );
+};
+
+export const API = flow(
+  withRouter,
+  withStyles,
+  withPersistenceBoundary,
+  withMosaicProvider,
+  withQueryClientProvider,
+)(APIImpl);

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');
+  });
+});