@stoplight/elements 9.0.11 → 9.0.12-beta-0.1

package/src/components/API/utils.ts

@@ -0,0 +1,206 @@
+import {
+  isHttpOperation,
+  isHttpService,
+  isHttpWebhookOperation,
+  resolveUrl,
+  TableOfContentsGroup,
+  TableOfContentsItem,
+} from '@stoplight/elements-core';
+import { NodeType } from '@stoplight/types';
+import { JSONSchema7 } from 'json-schema';
+import { defaults } from 'lodash';
+
+import { OperationNode, SchemaNode, ServiceChildNode, ServiceNode, WebhookNode } from '../../utils/oas/types';
+
+type GroupableNode = OperationNode | WebhookNode | SchemaNode;
+
+export type TagGroup<T extends GroupableNode> = { title: string; items: T[] };
+
+export function computeTagGroups<T extends GroupableNode>(serviceNode: ServiceNode, nodeType: T['type']) {
+  const groupsByTagId: { [tagId: string]: TagGroup<T> } = {};
+  const ungrouped: T[] = [];
+
+  const lowerCaseServiceTags = serviceNode.tags.map(tn => tn.toLowerCase());
+
+  const groupableNodes = serviceNode.children.filter(n => n.type === nodeType) as T[];
+
+  for (const node of groupableNodes) {
+    for (const tagName of node.tags) {
+      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],
+        };
+      }
+    }
+    if (node.tags.length === 0) {
+      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 hasOperationNodes = serviceNode.children.some(node => node.type === NodeType.HttpOperation);
+  if (hasOperationNodes) {
+    tree.push({
+      title: 'Endpoints',
+    });
+
+    const { groups, ungrouped } = computeTagGroups<OperationNode>(serviceNode, NodeType.HttpOperation);
+    addTagGroupsToTree(groups, ungrouped, tree, NodeType.HttpOperation, mergedConfig.hideInternal);
+  }
+
+  const hasWebhookNodes = serviceNode.children.some(node => node.type === NodeType.HttpWebhook);
+  if (hasWebhookNodes) {
+    tree.push({
+      title: 'Webhooks',
+    });
+
+    const { groups, ungrouped } = computeTagGroups<WebhookNode>(serviceNode, NodeType.HttpWebhook);
+    addTagGroupsToTree(groups, ungrouped, tree, NodeType.HttpWebhook, mergedConfig.hideInternal);
+  }
+
+  let schemaNodes = serviceNode.children.filter(node => node.type === NodeType.Model);
+  if (mergedConfig.hideInternal) {
+    schemaNodes = schemaNodes.filter(n => !isInternal(n));
+  }
+
+  if (!mergedConfig.hideSchemas && schemaNodes.length) {
+    tree.push({
+      title: 'Schemas',
+    });
+
+    const { groups, ungrouped } = computeTagGroups<SchemaNode>(serviceNode, NodeType.Model);
+    addTagGroupsToTree(groups, ungrouped, tree, NodeType.Model, mergedConfig.hideInternal);
+  }
+  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) || isHttpWebhookOperation(data)) {
+    return !!data.internal;
+  }
+
+  if (isHttpService(data)) {
+    return false;
+  }
+
+  return !!data['x-internal' as keyof JSONSchema7];
+};
+
+const addTagGroupsToTree = <T extends GroupableNode>(
+  groups: TagGroup<T>[],
+  ungrouped: T[],
+  tree: TableOfContentsItem[],
+  itemsType: TableOfContentsGroup['itemsType'],
+  hideInternal: boolean,
+) => {
+  // Show ungrouped nodes above tag groups
+  ungrouped.forEach(node => {
+    if (hideInternal && isInternal(node)) {
+      return;
+    }
+    tree.push({
+      id: node.uri,
+      slug: node.uri,
+      title: node.name,
+      type: node.type,
+      meta: isHttpOperation(node.data) || isHttpWebhookOperation(node.data) ? node.data.method : '',
+    });
+  });
+
+  groups.forEach(group => {
+    const items = group.items.flatMap(node => {
+      if (hideInternal && isInternal(node)) {
+        return [];
+      }
+      return {
+        id: node.uri,
+        slug: node.uri,
+        title: node.name,
+        type: node.type,
+        meta: isHttpOperation(node.data) || isHttpWebhookOperation(node.data) ? node.data.method : '',
+      };
+    });
+    if (items.length > 0) {
+      tree.push({
+        title: group.title,
+        items,
+        itemsType,
+      });
+    }
+  });
+};
+
+export const resolveRelativePath = (currentPath: string, basePath: string, outerRouter: boolean): string => {
+  if (!outerRouter || !basePath || basePath === '/') {
+    return currentPath;
+  }
+  const baseUrl = resolveUrl(basePath);
+  const currentUrl = resolveUrl(currentPath);
+  return baseUrl && currentUrl && baseUrl !== currentUrl ? currentUrl.replace(baseUrl, '') : '/';
+};

package/src/containers/API.spec.tsx

@@ -0,0 +1,122 @@
+import '@testing-library/jest-dom';
+
+import { act, render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import * as React from 'react';
+import { MemoryRouter } from 'react-router-dom';
+
+import { InstagramAPI } from '../__fixtures__/api-descriptions/Instagram';
+import { simpleApiWithoutDescription } from '../__fixtures__/api-descriptions/simpleApiWithoutDescription';
+import { API } from './API';
+
+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 { unmount } = render(
+      <MemoryRouter initialEntries={['/paths/internal-operation/get']}>
+        <API layout="sidebar" apiDescriptionDocument={APIDocument} />
+      </MemoryRouter>,
+    );
+
+    expect(screen.getByText('If you see this, something went wrong')).toBeInTheDocument();
+
+    unmount();
+  });
+
+  it('displays internal models by default', () => {
+    render(
+      <MemoryRouter initialEntries={['/schemas/InternalObject']}>
+        <API layout="sidebar" apiDescriptionDocument={APIDocument} />
+      </MemoryRouter>,
+    );
+
+    expect(screen.getByText('Cool object, but internal.')).toBeInTheDocument();
+  });
+
+  it('reroutes to main page on internal operation if hideInternal is on', () => {
+    render(
+      <MemoryRouter initialEntries={['/paths/internal-operation/get']}>
+        <API layout="sidebar" apiDescriptionDocument={APIDocument} hideInternal />
+      </MemoryRouter>,
+    );
+
+    expect(screen.queryByText('If you see this, something went wrong')).not.toBeInTheDocument();
+    expect(location.pathname).toBe('/');
+  });
+
+  it('reroutes to main page on internal model if hideInternal is on', () => {
+    render(
+      <MemoryRouter initialEntries={['/schemas/InternalObject']}>
+        <API layout="sidebar" apiDescriptionDocument={APIDocument} hideInternal />
+      </MemoryRouter>,
+    );
+
+    expect(screen.queryByText('Cool object, but internal.')).not.toBeInTheDocument();
+    expect(location.pathname).toBe('/');
+  });
+
+  describe('stackedLayout', () => {
+    it('shows operation path and method when collapsed', async () => {
+      render(<API logo="thisisarequiredprop" layout="stacked" apiDescriptionDocument={APIDocument} />);
+
+      const users = await screen.findByText('users');
+      act(() => userEvent.click(users));
+
+      expect(screen.queryByText('/users/{user-id}')).toBeInTheDocument();
+    });
+
+    it('shows operation name when expanded', async () => {
+      render(<API logo="thisisarequiredprop" layout="stacked" apiDescriptionDocument={APIDocument} />);
+
+      const users = await screen.findByText('users');
+      act(() => userEvent.click(users));
+
+      const usersPath = await screen.findByText('/users/{user-id}');
+      act(() => userEvent.click(usersPath));
+
+      const usersSummary = await screen.findByText('Get basic information about a user.');
+
+      expect(usersSummary).toBeInTheDocument();
+    });
+  });
+});

package/src/containers/API.stories.tsx

@@ -0,0 +1,117 @@
+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';
+import { renderExtensionRenderer } from './story-helper';
+
+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 ResponsiveLayout = Template.bind({});
+ResponsiveLayout.args = {
+  apiDescriptionDocument: JSON.stringify(parse(zoomApiYaml), null, '  '),
+  layout: 'responsive',
+};
+ResponsiveLayout.storyName = 'Responsive Layout (Zoom)';
+ResponsiveLayout.parameters = {
+  layout: 'fullscreen',
+};
+
+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';
+
+export const WithExtensionRenderer = Template.bind({});
+WithExtensionRenderer.args = {
+  renderExtensionAddon: renderExtensionRenderer,
+  apiDescriptionDocument: zoomApiYaml,
+};
+WithExtensionRenderer.storyName = 'With Extension Renderer';