@stoplight/elements-core 9.0.15 → 9.0.16-beta-0.1

package/src/components/Docs/HttpService/HttpService.spec.tsx

@@ -0,0 +1,429 @@
+import { Provider as MosaicProvider } from '@stoplight/mosaic';
+import { render, screen, waitFor } from '@testing-library/react';
+import { renderHook } from '@testing-library/react-hooks';
+import userEvent from '@testing-library/user-event';
+import * as React from 'react';
+import { BrowserRouter as Router } from 'react-router-dom';
+
+import { apiKey, oauth } from '../../../__fixtures__/security-schemes';
+import httpService from '../../../__fixtures__/services/petstore';
+import { httpServiceWithUnnamedServers } from '../../../__fixtures__/services/with-unnamed-servers';
+import { httpServiceWithUrlVariables } from '../../../__fixtures__/services/with-url-variables';
+import { httpServiceWithoutOrigin } from '../../../__fixtures__/services/without-origin';
+import { AdditionalInfo } from './AdditionalInfo';
+import { HttpService } from './index';
+import { SecuritySchemes } from './SecuritySchemes';
+import { ServerInfo, useSplitUrl } from './ServerInfo';
+
+describe('HttpService', () => {
+  it('Should render correctly', () => {
+    const wrapper = render(
+      <Router>
+        <HttpService data={httpService} />
+      </Router>,
+    );
+
+    expect(wrapper.getByText(httpService.name).tagName.toLowerCase()).toBe('h1');
+  });
+
+  it('should not display servers when hideServerInfo is provided', () => {
+    render(
+      <Router>
+        <HttpService layoutOptions={{ hideServerInfo: true }} data={{ ...httpService, security: [] }} />
+      </Router>,
+    );
+
+    const serverUrl = screen.queryByLabelText('Production API');
+    expect(serverUrl).not.toBeInTheDocument();
+  });
+
+  it('displays all server urls', () => {
+    render(<ServerInfo servers={httpService.servers ?? []} />);
+
+    const serverUrl = screen.getByLabelText('Production API');
+    expect(serverUrl).toHaveTextContent('https://api.stoplight.io');
+
+    const secondServerUrl = screen.getByLabelText('Staging API');
+    expect(secondServerUrl).toHaveTextContent('https://api.{environment}.stoplight.io');
+
+    const thirdServerUrl = screen.getByLabelText('Development API');
+    expect(thirdServerUrl).toHaveTextContent('https://localhost:{port}');
+
+    expect(screen.queryByLabelText('Mock Server')).not.toBeInTheDocument();
+  });
+
+  it('generates names for servers without descriptions', () => {
+    render(<ServerInfo servers={httpServiceWithUnnamedServers.servers ?? []} />);
+
+    const secondServerUrl = screen.getByLabelText('Server 2');
+    expect(secondServerUrl).toHaveTextContent('https://api.staging.stoplight.io');
+
+    const fourthServerUrl = screen.getByLabelText('Server 4');
+    expect(fourthServerUrl).toHaveTextContent('https://localhost:4060');
+
+    expect(screen.queryByLabelText('Mock Server')).not.toBeInTheDocument();
+  });
+
+  it('keeps url variables in displayed url', () => {
+    render(<ServerInfo servers={httpServiceWithUrlVariables.servers ?? []} />);
+
+    const serverUrl = screen.getByLabelText('Production API');
+    expect(serverUrl).toHaveTextContent('{protocol}://{namespace}.stoplight.io');
+  });
+
+  it('shows url variables in an expandable panel', async () => {
+    render(<ServerInfo servers={httpServiceWithUrlVariables.servers ?? []} />);
+
+    await waitFor(() => expect(screen.queryByRole('region')).toBeInTheDocument());
+
+    expect(screen.getByRole('region')).toHaveTextContent(
+      `protocolstringAllowed values:ftphttphttpsDefault:ftpnamespacestringDefault:default-namespace`,
+    );
+  });
+
+  it('hides subsequent panels with server variables ', async () => {
+    const servers = [
+      ...httpServiceWithUrlVariables.servers!.slice(0, -1),
+      {
+        id: '?http-server-3?',
+        url: 'https://localhost:{port}',
+        description: 'Development API',
+        variables: {
+          port: {
+            default: '443',
+          },
+        },
+      },
+    ];
+
+    render(<ServerInfo servers={servers} />);
+
+    await waitFor(() => expect(screen.queryAllByRole('region')).toHaveLength(1));
+
+    const serverUrl = screen.getByLabelText('Development API');
+    userEvent.click(serverUrl.parentElement!);
+
+    await waitFor(() => expect(screen.queryAllByRole('region')).toHaveLength(2));
+
+    expect(screen.getAllByRole('region')[1]).toHaveTextContent(`portstringDefault:443`);
+  });
+
+  it('handles urls without an origin', () => {
+    render(<ServerInfo servers={httpServiceWithoutOrigin.servers ?? []} />);
+
+    const serverUrl = screen.getByLabelText('Production API');
+    expect(serverUrl).toHaveTextContent('api');
+  });
+
+  it('displays mock server url when embedded in Stoplight Project', async () => {
+    render(<ServerInfo servers={httpService.servers ?? []} mockUrl="https://foo.stoplight.io/prism/123" />);
+
+    const mockServer = screen.queryByLabelText('Mock Server');
+    await waitFor(() => expect(mockServer).toHaveTextContent('https://foo.stoplight.io/prism/123'));
+  });
+
+  it('Base URL block handles an invalid URL', () => {
+    const modifiedData = {
+      ...httpService,
+      servers: [
+        {
+          id: '?http-server-0?',
+          url: 'https://///',
+          name: 'Production API',
+        },
+      ],
+    };
+
+    render(
+      <Router>
+        <HttpService data={modifiedData} />
+      </Router>,
+    );
+
+    expect(screen.queryByText(/api base url/i)).toBeInTheDocument();
+  });
+
+  describe('Security schemes', () => {
+    it('should render single security scheme', () => {
+      render(<SecuritySchemes secSchemes={[[apiKey]]} parentId="2@adfg4F" />);
+
+      const title = screen.getByRole('heading', { name: 'Security' });
+      const scheme = screen.getByRole('heading', { name: 'API Key' });
+
+      expect(title).toBeInTheDocument();
+      expect(scheme).toBeInTheDocument();
+    });
+
+    it('should not render if no security schemes provided', () => {
+      render(
+        <Router>
+          <HttpService data={{ ...httpService, security: [] }} />
+        </Router>,
+      );
+
+      const security = screen.queryByRole('heading', { name: 'Security' });
+      expect(security).not.toBeInTheDocument();
+    });
+
+    it('should not render if hideSecurityInfo is provided', () => {
+      render(
+        <Router>
+          <HttpService layoutOptions={{ hideSecurityInfo: true }} data={{ ...httpService, security: [] }} />
+        </Router>,
+      );
+
+      const security = screen.queryByRole('heading', { name: 'Security' });
+      expect(security).not.toBeInTheDocument();
+    });
+
+    it('should render default description', () => {
+      render(<SecuritySchemes secSchemes={[[apiKey]]} parentId="2@adfg4F" />);
+
+      const description = screen.getByText(/An API key/);
+      expect(description).toBeInTheDocument();
+    });
+
+    it('should render custom description', () => {
+      render(
+        <SecuritySchemes secSchemes={[[{ ...apiKey, description: 'Api Key description' }]]} parentId="2@adfg4F" />,
+      );
+
+      const description = screen.getByText('Api Key description');
+      expect(description).toBeInTheDocument();
+    });
+
+    it('should render both custom description and other scheme details', () => {
+      render(
+        <SecuritySchemes secSchemes={[[{ ...oauth, description: 'A custom description' }]]} parentId="2@adfg4F" />,
+      );
+
+      const description = screen.getByText('A custom description');
+      const implicit = screen.getByText('Implicit OAuth Flow');
+
+      expect(description).toBeInTheDocument();
+      expect(implicit).toBeInTheDocument();
+    });
+
+    it('should render oauth flows for default description', () => {
+      render(<SecuritySchemes secSchemes={[[oauth]]} parentId="2@adfg4F" />);
+
+      const implicit = screen.getByText('Implicit OAuth Flow');
+      const password = screen.getByText('Password OAuth Flow');
+      const clientCredentials = screen.getByText('Client Credentials OAuth Flow');
+      const authCode = screen.getByText('Authorization Code OAuth Flow');
+
+      expect(implicit).toBeInTheDocument();
+      expect(password).toBeInTheDocument();
+      expect(clientCredentials).toBeInTheDocument();
+      expect(authCode).toBeInTheDocument();
+    });
+
+    it('should render multiple schemes', () => {
+      render(<SecuritySchemes secSchemes={[[apiKey], [oauth]]} parentId="2@adfg4F" />);
+
+      const apiKeyScheme = screen.getByRole('heading', { name: 'API Key' });
+      const oauthScheme = screen.getByRole('heading', { name: 'OAuth 2.0' });
+      const expandButtons = screen.getAllByRole('button');
+
+      expect(apiKeyScheme).toBeInTheDocument();
+      expect(oauthScheme).toBeInTheDocument();
+      expect(expandButtons.length).toEqual(2);
+    });
+
+    it('should expand first scheme by default', () => {
+      render(<SecuritySchemes secSchemes={[[apiKey], [oauth]]} parentId="2@adfg4F" />);
+
+      const apiKeyDescription = screen.queryByText(/An API key/);
+      let oauthDescription = screen.queryByText('Implicit OAuth Flow');
+
+      expect(apiKeyDescription).toBeInTheDocument();
+      expect(oauthDescription).not.toBeInTheDocument();
+
+      const oauthScheme = screen.getByRole('heading', { name: 'OAuth 2.0' });
+      userEvent.click(oauthScheme);
+      oauthDescription = screen.queryByText('Implicit OAuth Flow');
+      expect(oauthDescription).toBeInTheDocument();
+    });
+  });
+
+  describe('Additional information', () => {
+    it('should render additional information', () => {
+      const contact = {
+        name: 'Developer',
+        email: 'developer@stoplight.io',
+        url: 'https://stoplight.io/contact-us/',
+      };
+
+      const license = {
+        name: 'MIT',
+        url: 'https://opensource.org/licenses/MIT',
+      };
+      render(
+        <AdditionalInfo id="a" contact={contact} license={license} termsOfService="https://stoplight.io/terms/" />,
+      );
+
+      const title = screen.getByRole('heading', { name: 'Additional Information' });
+
+      expect(title).toBeInTheDocument();
+    });
+
+    it('should render additional information with SPDX license identifier', () => {
+      const contact = {
+        name: 'Developer',
+        email: 'developer@stoplight.io',
+        url: 'https://stoplight.io/contact-us/',
+      };
+
+      const license = {
+        name: 'MIT License',
+        identifier: 'MIT',
+      };
+
+      render(
+        <AdditionalInfo id="a" contact={contact} license={license} termsOfService="https://stoplight.io/terms/" />,
+      );
+
+      const licenseLink = screen.getByText('MIT License');
+      expect(licenseLink).toHaveAttribute('href', 'https://spdx.org/licenses/MIT.html');
+    });
+
+    it('should prefer license URL over SPDX identifier if both are provided', () => {
+      const license = {
+        name: 'MIT License',
+        url: 'https://opensource.org/licenses/MIT',
+        identifier: 'MIT',
+      };
+
+      render(<AdditionalInfo id="a" license={license} />);
+
+      const licenseLink = screen.getByText('MIT License');
+      expect(licenseLink).toHaveAttribute('href', 'https://opensource.org/licenses/MIT');
+    });
+
+    it('should not render if contact, license, and terms of service do not exist', () => {
+      render(<AdditionalInfo id="a" />);
+
+      const title = screen.queryByRole('heading', { name: 'Additional Information' });
+      expect(title).not.toBeInTheDocument();
+    });
+
+    it('should not render if props do not have sufficient subprops', () => {
+      const contact = {
+        name: 'Developer',
+      };
+
+      render(<AdditionalInfo id="a" contact={contact} />);
+
+      const title = screen.queryByRole('heading', { name: 'Additional Information' });
+      expect(title).not.toBeInTheDocument();
+    });
+  });
+
+  describe('export button', () => {
+    it('should render correctly', () => {
+      const wrapper = render(
+        <Router>
+          <MosaicProvider>
+            <HttpService
+              data={httpService}
+              exportProps={{ original: { onPress: jest.fn() }, bundled: { onPress: jest.fn() } }}
+            />
+          </MosaicProvider>
+        </Router>,
+      );
+
+      const exportButton = wrapper.getByRole('button', { name: 'Export' });
+      expect(exportButton).toBeInTheDocument();
+
+      userEvent.click(exportButton);
+      expect(wrapper.getByRole('menuitem', { name: 'Original' })).toBeInTheDocument();
+      expect(wrapper.getByRole('menuitem', { name: 'Bundled References' })).toBeInTheDocument();
+    });
+
+    it('should not render if hideExport is true', () => {
+      const wrapper = render(
+        <Router>
+          <MosaicProvider>
+            <HttpService
+              data={httpService}
+              exportProps={{ original: { onPress: jest.fn() }, bundled: { onPress: jest.fn() } }}
+              layoutOptions={{ hideExport: true }}
+            />
+          </MosaicProvider>
+        </Router>,
+      );
+
+      const exportButton = wrapper.queryByRole('button', { name: 'Export' });
+      expect(exportButton).not.toBeInTheDocument();
+    });
+
+    it('should not render if no exportProps are present', () => {
+      const wrapper = render(
+        <Router>
+          <MosaicProvider>
+            <HttpService data={httpService} />
+          </MosaicProvider>
+        </Router>,
+      );
+
+      const exportButton = wrapper.queryByRole('button', { name: 'Export' });
+      expect(exportButton).not.toBeInTheDocument();
+    });
+  });
+});
+
+describe('useSplitUrl hook', () => {
+  it('should correctly distinguish variables from static parts', () => {
+    let { result } = renderHook(() => useSplitUrl('https://{api}.stoplight.io:{port}'));
+
+    expect(result.current).toStrictEqual([
+      { kind: 'static', value: 'https://' },
+      { kind: 'variable', value: '{api}' },
+      { kind: 'static', value: '.stoplight.io:' },
+      { kind: 'variable', value: '{port}' },
+    ]);
+
+    ({ result } = renderHook(() => useSplitUrl('{protocol}://stoplight.io:{port}')));
+
+    expect(result.current).toStrictEqual([
+      { kind: 'variable', value: '{protocol}' },
+      { kind: 'static', value: '://stoplight.io:' },
+      { kind: 'variable', value: '{port}' },
+    ]);
+
+    ({ result } = renderHook(() => useSplitUrl('https://{version}{username}.stoplight.io')));
+
+    expect(result.current).toStrictEqual([
+      { kind: 'static', value: 'https://' },
+      { kind: 'variable', value: '{version}' },
+      { kind: 'variable', value: '{username}' },
+      { kind: 'static', value: '.stoplight.io' },
+    ]);
+
+    ({ result } = renderHook(() => useSplitUrl('https://www.stoplight.io')));
+
+    expect(result.current).toStrictEqual([{ kind: 'static', value: 'https://www.stoplight.io' }]);
+  });
+
+  it('should gracefully handle invalid input', () => {
+    let { result } = renderHook(() => useSplitUrl('https://{{{{}'));
+
+    expect(result.current).toStrictEqual([{ kind: 'static', value: 'https://{{{{}' }]);
+
+    ({ result } = renderHook(() => useSplitUrl('{protocol://stoplight.io:{api}')));
+
+    expect(result.current).toStrictEqual([
+      { kind: 'static', value: '{protocol://stoplight.io:' },
+      { kind: 'variable', value: '{api}' },
+    ]);
+
+    ({ result } = renderHook(() => useSplitUrl('https://{version}{username}.stoplight.io{test')));
+
+    expect(result.current).toStrictEqual([
+      { kind: 'static', value: 'https://' },
+      { kind: 'variable', value: '{version}' },
+      { kind: 'variable', value: '{username}' },
+      { kind: 'static', value: '.stoplight.io{test' },
+    ]);
+  });
+});

package/src/components/Docs/HttpService/HttpService.stories.ts

@@ -0,0 +1,14 @@
+import { httpService } from '../../../__fixtures__/services/petstore';
+import { createStoriesForDocsComponent } from '../story-helper';
+import { renderExtensionRenderer } from '../story-renderer-helper';
+import { HttpService } from './HttpService';
+
+const { meta, createHoistedStory } = createStoriesForDocsComponent(HttpService, 'HttpService');
+
+export default meta;
+
+export const Story = createHoistedStory({
+  data: httpService,
+  layoutOptions: { compact: 600 },
+  renderExtensionAddon: renderExtensionRenderer,
+});

package/src/components/Docs/HttpService/HttpService.tsx

@@ -0,0 +1,99 @@
+import { Box, Flex, Heading, NodeAnnotation, VStack } from '@stoplight/mosaic';
+import { withErrorBoundary } from '@stoplight/react-error-boundary';
+import { IHttpService } from '@stoplight/types';
+import * as React from 'react';
+
+import { MockingContext } from '../../../containers/MockingProvider';
+import { useResolvedObject } from '../../../context/InlineRefResolver';
+import { useOptionsCtx } from '../../../context/Options';
+import { useIsCompact } from '../../../hooks/useIsCompact';
+import { MarkdownViewer } from '../../MarkdownViewer';
+import { PoweredByLink } from '../../PoweredByLink';
+import { DocsComponentProps } from '..';
+import { VersionBadge } from '../HttpOperation/Badges';
+import { AdditionalInfo } from './AdditionalInfo';
+import { ExportButton } from './ExportButton';
+import { SecuritySchemes } from './SecuritySchemes';
+import { ServerInfo } from './ServerInfo';
+
+export type HttpServiceProps = DocsComponentProps<Partial<IHttpService>>;
+
+const HttpServiceComponent = React.memo<HttpServiceProps>(
+  ({ data: unresolvedData, location = {}, layoutOptions, exportProps }) => {
+    const { nodeHasChanged } = useOptionsCtx();
+    const data = useResolvedObject(unresolvedData) as IHttpService;
+    const { ref: layoutRef } = useIsCompact(layoutOptions);
+    const { search, pathname } = location;
+    const mocking = React.useContext(MockingContext);
+    const query = new URLSearchParams(search);
+
+    const nameChanged = nodeHasChanged?.({ nodeId: data.id, attr: 'name' });
+    const versionChanged = nodeHasChanged?.({ nodeId: data.id, attr: 'version' });
+    const descriptionChanged = nodeHasChanged?.({ nodeId: data.id, attr: 'description' });
+
+    return (
+      <Box ref={layoutRef} mb={10} className="HttpService">
+        {data.name && !layoutOptions?.noHeading && (
+          <Flex justifyContent="between" alignItems="center">
+            <Box pos="relative">
+              <Heading size={1} mb={4} fontWeight="semibold">
+                {data.name}
+              </Heading>
+              <NodeAnnotation change={nameChanged} />
+            </Box>
+
+            {exportProps && !layoutOptions?.hideExport && <ExportButton {...exportProps} />}
+          </Flex>
+        )}
+
+        {data.version && (
+          <Box mb={5} pos="relative">
+            <VersionBadge value={data.version} />
+            <NodeAnnotation change={versionChanged} />
+          </Box>
+        )}
+
+        {pathname && layoutOptions?.showPoweredByLink && (
+          <PoweredByLink source={data.name ?? 'no-title'} pathname={pathname} packageType="elements" layout="stacked" />
+        )}
+
+        <VStack spacing={6}>
+          {layoutOptions?.hideServerInfo ? null : <ServerInfo servers={data.servers ?? []} mockUrl={mocking.mockUrl} />}
+
+          {layoutOptions?.hideSecurityInfo ? null : (
+            <Box data-test="security">
+              {data.security?.length ? (
+                <SecuritySchemes
+                  secSchemes={data.security}
+                  defaultScheme={query.get('security') || undefined}
+                  parentId={data.id}
+                />
+              ) : null}
+            </Box>
+          )}
+
+          <Box data-test="additional-info">
+            {(data.contact?.email || data.license || data.termsOfService) && (
+              <AdditionalInfo
+                id={data.id}
+                contact={data.contact}
+                license={data.license}
+                termsOfService={data.termsOfService}
+              />
+            )}
+          </Box>
+        </VStack>
+
+        {data.description && (
+          <Box pos="relative">
+            <MarkdownViewer className="sl-my-5" markdown={data.description} />
+            <NodeAnnotation change={descriptionChanged} />
+          </Box>
+        )}
+      </Box>
+    );
+  },
+);
+HttpServiceComponent.displayName = 'HttpService.Component';
+
+export const HttpService = withErrorBoundary<HttpServiceProps>(HttpServiceComponent, { recoverableProps: ['data'] });

package/src/components/Docs/HttpService/SecuritySchemes.tsx

@@ -0,0 +1,82 @@
+import { Box, NodeAnnotation, Panel, PanelProps, Text } from '@stoplight/mosaic';
+import { HttpSecurityScheme } from '@stoplight/types';
+import React from 'react';
+
+import { OptionalSecurityMessage } from '../../../constants';
+import { useOptionsCtx } from '../../../context/Options';
+import { getReadableSecurityNames, getSecurityGroupId, shouldAddKey } from '../../../utils/oas/security';
+import { PanelContent } from '../Security/PanelContent';
+
+interface SecuritySchemesProps {
+  secSchemes: HttpSecurityScheme[][];
+  defaultScheme?: string;
+  defaultCollapsed?: boolean;
+  parentId: string;
+}
+
+export const SecuritySchemes: React.FC<SecuritySchemesProps> = ({
+  secSchemes,
+  defaultScheme,
+  defaultCollapsed = false,
+  parentId,
+}) => {
+  const includeOptional = secSchemes.length > 1 && secSchemes.some(schemes => schemes.length === 0);
+  const { nodeHasChanged } = useOptionsCtx();
+
+  return (
+    <Panel rounded isCollapsible={defaultCollapsed} data-test="security-row">
+      <Panel.Titlebar bg="canvas-300">
+        <Box as="span" role="heading">
+          Security
+        </Box>
+      </Panel.Titlebar>
+      <Panel.Content p={0}>
+        {includeOptional && <OptionalMessage />}
+        {secSchemes
+          .filter(scheme => scheme.length > 0) // Remove the None scheme from listed display
+          .map((schemes, i) => {
+            const secGroupId = getSecurityGroupId(parentId, i);
+            return (
+              <Box key={secGroupId} data-test="http-service-security-row">
+                <NodeAnnotation change={nodeHasChanged?.({ nodeId: secGroupId })} />
+                <SecurityScheme
+                  schemes={schemes}
+                  defaultIsOpen={defaultScheme ? schemes.length === 1 && schemes[0].key === defaultScheme : i === 0}
+                  isCollapsible={secSchemes.length > 1}
+                  showSchemeKey={shouldAddKey(schemes, secSchemes)}
+                />
+              </Box>
+            );
+          })}
+      </Panel.Content>
+    </Panel>
+  );
+};
+
+const SecurityScheme: React.FC<
+  {
+    schemes: HttpSecurityScheme[];
+    showSchemeKey?: boolean;
+  } & Pick<PanelProps, 'defaultIsOpen' | 'isCollapsible'>
+> = ({ schemes, defaultIsOpen, isCollapsible, showSchemeKey }) => {
+  return (
+    <Panel defaultIsOpen={defaultIsOpen} isCollapsible={isCollapsible} pos="relative">
+      <Panel.Titlebar>
+        <Box as="span" role="heading">
+          {getReadableSecurityNames(schemes, showSchemeKey)}
+        </Box>
+      </Panel.Titlebar>
+      <Panel.Content>
+        <PanelContent schemes={schemes} />
+      </Panel.Content>
+    </Panel>
+  );
+};
+
+const OptionalMessage: React.FC = () => {
+  return (
+    <Box p={2} pl={6} border>
+      <Text fontSize="base">{OptionalSecurityMessage}</Text>
+    </Box>
+  );
+};