@stoplight/elements-dev-portal 3.0.11 → 3.0.12-beta-0.1

package/src/containers/StoplightProject.tsx

@@ -0,0 +1,269 @@
+import {
+  type CustomLinkComponent,
+  findFirstNode,
+  ReactRouterMarkdownLink,
+  RouterTypeContext,
+  RoutingProps,
+  ScrollToHashElement,
+  SidebarLayout,
+  useRouter,
+  withStyles,
+} from '@stoplight/elements-core';
+import * as React from 'react';
+import {
+  Link,
+  Navigate,
+  Outlet,
+  Route,
+  Routes,
+  useInRouterContext,
+  useNavigate,
+  useOutletContext,
+  useParams,
+} from 'react-router-dom';
+
+import { BranchSelector } from '../components/BranchSelector';
+import { DevPortalProvider } from '../components/DevPortalProvider';
+import { Forbidden } from '../components/Forbidden';
+import { Loading } from '../components/Loading';
+import { NodeContent } from '../components/NodeContent';
+import { NotFound } from '../components/NotFound';
+import { TableOfContents } from '../components/TableOfContents';
+import { UpgradeToStarter } from '../components/UpgradeToStarter';
+import { ResponseError } from '../handlers/getNodeContent';
+import { useGetBranches } from '../hooks/useGetBranches';
+import { useGetNodeContent } from '../hooks/useGetNodeContent';
+import { useGetTableOfContents } from '../hooks/useGetTableOfContents';
+
+export interface StoplightProjectProps extends RoutingProps {
+  /**
+   * The ID of the Stoplight Project.
+   * @example "d2s6NDE1NTU"
+   */
+  projectId: string;
+  /**
+   * If your company runs an on-premise deployment of Stoplight,
+   * set this prop to point the StoplightProject component at the URL of that instance.
+   */
+  platformUrl?: string;
+
+  /**
+   * Allows to hide TryIt component
+   */
+  hideTryIt?: boolean;
+
+  /**
+   * Allows to hide mocking button
+   */
+  hideMocking?: boolean;
+
+  /**
+   * Allows to hide export button
+   * @default false
+   */
+  hideExport?: boolean;
+
+  /**
+   * Allows to the server information
+   * @default false
+   */
+  hideServerInfo?: boolean;
+
+  /**
+   * Allows to hide the security schemes
+   * @default false
+   */
+  hideSecurityInfo?: boolean;
+
+  /**
+   * If set to true, all table of contents panels will be collapsed.
+   * @default false
+   */
+  collapseTableOfContents?: 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;
+}
+
+const StoplightProjectImpl: React.FC<StoplightProjectProps> = ({ projectId, collapseTableOfContents = false }) => {
+  const { branchSlug: encodedBranchSlug = '', '*': nodeSlug = '' } = useParams<{
+    branchSlug?: string;
+    '*': string;
+  }>();
+  const branchSlug = decodeURIComponent(encodedBranchSlug);
+  const navigate = useNavigate();
+
+  const { data: tableOfContents, isFetched: isTocFetched } = useGetTableOfContents({ projectId, branchSlug });
+  const { data: branches } = useGetBranches({ projectId });
+  const {
+    data: node,
+    isLoading: isLoadingNode,
+    isError,
+    error: nodeError,
+  } = useGetNodeContent({
+    nodeSlug: nodeSlug ?? '',
+    projectId,
+    branchSlug,
+  });
+
+  const container = React.useRef<HTMLDivElement>(null);
+
+  if (!nodeSlug && isTocFetched && tableOfContents?.items) {
+    const firstNode = findFirstNode(tableOfContents.items);
+    if (firstNode) {
+      return <Navigate to={branchSlug ? `branches/${branchSlug}/${firstNode.slug}` : `${firstNode.slug}`} replace />;
+    }
+  }
+
+  const handleTocClick = () => {
+    if (container.current) {
+      container.current.scrollIntoView();
+    }
+  };
+
+  return (
+    <SidebarLayout
+      ref={container}
+      sidebar={
+        <>
+          {branches && branches.items.length > 1 ? (
+            <BranchSelector
+              branchSlug={branchSlug}
+              branches={branches.items}
+              onChange={branch => {
+                const encodedBranchSlug = encodeURIComponent(branch.slug);
+                navigate(branch.is_default ? `${nodeSlug}` : `branches/${encodedBranchSlug}/${nodeSlug}`);
+              }}
+            />
+          ) : null}
+          {tableOfContents ? (
+            <TableOfContents
+              activeId={node?.id || nodeSlug?.split('-')[0] || ''}
+              tableOfContents={tableOfContents}
+              Link={Link as CustomLinkComponent}
+              collapseTableOfContents={collapseTableOfContents}
+              onLinkClick={handleTocClick}
+            />
+          ) : null}
+        </>
+      }
+    >
+      <Outlet context={[isLoadingNode, isTocFetched, isError, nodeError, node]} />
+    </SidebarLayout>
+  );
+};
+
+const ProjectNode: React.FC<StoplightProjectProps> = ({
+  hideTryIt,
+  hideSecurityInfo,
+  hideServerInfo,
+  hideMocking,
+  hideExport,
+  tryItCredentialsPolicy,
+  tryItCorsProxy,
+}) => {
+  const { branchSlug: encodedBranchSlug = '', '*': nodeSlug = '' } = useParams<{ branchSlug?: string; '*': string }>();
+  const branchSlug = decodeURIComponent(encodedBranchSlug);
+  const [isLoadingNode, isTocFetched, isError, nodeError, node] = useOutletContext<any>();
+
+  if (isLoadingNode || !isTocFetched) {
+    return <Loading />;
+  }
+
+  if (isError) {
+    if (nodeError instanceof ResponseError) {
+      if (nodeError.code === 402) {
+        return <UpgradeToStarter />;
+      } else if (nodeError.code === 403) {
+        return <Forbidden />;
+      } else {
+        return <NotFound />;
+      }
+    } else {
+      return <NotFound />;
+    }
+  }
+
+  if (!node) {
+    return <NotFound />;
+  }
+
+  if (node?.slug && nodeSlug !== node.slug) {
+    // Handle redirect to node's slug
+    return <Navigate to={branchSlug ? `/branches/${branchSlug}/${node.slug}` : `/${node.slug}`} replace />;
+  }
+
+  return (
+    <>
+      <ScrollToHashElement />
+      <NodeContent
+        node={node}
+        Link={ReactRouterMarkdownLink}
+        hideTryIt={hideTryIt}
+        hideMocking={hideMocking}
+        hideExport={hideExport}
+        hideSecurityInfo={hideSecurityInfo}
+        hideServerInfo={hideServerInfo}
+        tryItCredentialsPolicy={tryItCredentialsPolicy}
+        tryItCorsProxy={tryItCorsProxy}
+      />
+    </>
+  );
+};
+
+const StoplightProjectRouter = ({
+  platformUrl,
+  basePath = '/',
+  staticRouterPath = '',
+  router = 'hash',
+  ...props
+}: StoplightProjectProps) => {
+  const { Router, routerProps } = useRouter(router, basePath, staticRouterPath);
+  const outerRouter = useInRouterContext();
+
+  const InternalRoutes = () => (
+    <Routes>
+      <Route path="/" element={<StoplightProjectImpl {...props} />}>
+        <Route path="/branches/:branchSlug/*" element={<ProjectNode {...props} />} />
+        <Route path="/*" element={<ProjectNode {...props} />} />
+      </Route>
+    </Routes>
+  );
+
+  if (!outerRouter) {
+    return (
+      <DevPortalProvider platformUrl={platformUrl}>
+        <RouterTypeContext.Provider value={router}>
+          <Router {...routerProps} key={basePath}>
+            <InternalRoutes />
+          </Router>
+        </RouterTypeContext.Provider>
+      </DevPortalProvider>
+    );
+  }
+
+  return (
+    <DevPortalProvider platformUrl={platformUrl}>
+      <RouterTypeContext.Provider value={router}>
+        <InternalRoutes />
+      </RouterTypeContext.Provider>
+    </DevPortalProvider>
+  );
+};
+
+/**
+ * The StoplightProject component displays a traditional documentation UI for an existing Stoplight Project.
+ */
+export const StoplightProject = withStyles(StoplightProjectRouter);

package/src/handlers/__tests__/getBranches.test.ts

@@ -0,0 +1,30 @@
+import fetchMock from 'jest-fetch-mock';
+
+import { getBranches } from '../getBranches';
+
+describe('getBranches', () => {
+  beforeEach(() => {
+    fetchMock.resetMocks();
+    localStorage.clear();
+  });
+
+  it('should URI encode the parameters in the request URL', async () => {
+    fetchMock.mockResolvedValue(
+      new Response('{}', {
+        status: 200,
+        statusText: 'OK',
+        headers: [],
+      }),
+    );
+
+    await getBranches({
+      projectId: 'some/slash',
+    });
+
+    expect(fetchMock).toBeCalledWith('https://stoplight.io/api/v1/projects/some%2Fslash/branches', {
+      headers: expect.objectContaining({
+        'Stoplight-Elements-Version': expect.any(String),
+      }),
+    });
+  });
+});

package/src/handlers/__tests__/getNodeContent.test.ts

@@ -0,0 +1,35 @@
+import fetchMock from 'jest-fetch-mock';
+
+import { getNodeContent } from '../getNodeContent';
+
+describe('getNodeContent', () => {
+  beforeEach(() => {
+    fetchMock.resetMocks();
+    localStorage.clear();
+  });
+
+  it('should URI encode the parameters in the request URL', async () => {
+    fetchMock.mockResolvedValue(
+      new Response('{}', {
+        status: 200,
+        statusText: 'OK',
+        headers: [],
+      }),
+    );
+
+    await getNodeContent({
+      nodeSlug: 'node&slug',
+      projectId: 'some/slash',
+      branchSlug: 'test+branch',
+    });
+
+    expect(fetchMock).toBeCalledWith(
+      'https://stoplight.io/api/v1/projects/some%2Fslash/nodes/node%26slug?branch=test%2Bbranch',
+      {
+        headers: expect.objectContaining({
+          'Stoplight-Elements-Version': expect.any(String),
+        }),
+      },
+    );
+  });
+});

package/src/handlers/__tests__/getNodes.test.ts

@@ -0,0 +1,38 @@
+import fetchMock from 'jest-fetch-mock';
+
+import { getNodes } from '../getNodes';
+
+describe('getNodes', () => {
+  beforeEach(() => {
+    fetchMock.resetMocks();
+    localStorage.clear();
+  });
+
+  describe('with a provided workspace identifier', () => {
+    it('should URI encode the parameters in the request URL', async () => {
+      fetchMock.mockResolvedValue(
+        new Response('{}', {
+          status: 200,
+          statusText: 'OK',
+          headers: [],
+        }),
+      );
+
+      await getNodes({
+        workspaceId: 'my?workspace',
+        projectIds: ['some/slash'],
+        branchSlug: 'test+branch',
+        search: 'a?special&search',
+      });
+
+      expect(fetchMock).toBeCalledWith(
+        'https://stoplight.io/api/v1/workspaces/my%3Fworkspace/nodes?project_ids[0]=some%2Fslash&search=a%3Fspecial%26search&branch=test%2Bbranch',
+        {
+          headers: expect.objectContaining({
+            'Stoplight-Elements-Version': expect.any(String),
+          }),
+        },
+      );
+    });
+  });
+});

package/src/handlers/__tests__/getTableOfContents.test.ts

@@ -0,0 +1,34 @@
+import fetchMock from 'jest-fetch-mock';
+
+import { getTableOfContents } from '../getTableOfContents';
+
+describe('getTableOfContents', () => {
+  beforeEach(() => {
+    fetchMock.resetMocks();
+    localStorage.clear();
+  });
+
+  it('should URI encode the parameters in the request URL', async () => {
+    fetchMock.mockResolvedValue(
+      new Response('{}', {
+        status: 200,
+        statusText: 'OK',
+        headers: [],
+      }),
+    );
+
+    await getTableOfContents({
+      projectId: 'some/slash',
+      branchSlug: 'test+branch',
+    });
+
+    expect(fetchMock).toBeCalledWith(
+      'https://stoplight.io/api/v1/projects/some%2Fslash/table-of-contents?branch=test%2Bbranch',
+      {
+        headers: expect.objectContaining({
+          'Stoplight-Elements-Version': expect.any(String),
+        }),
+      },
+    );
+  });
+});

package/src/handlers/__tests__/getWorkspace.test.ts

@@ -0,0 +1,30 @@
+import fetchMock from 'jest-fetch-mock';
+
+import { getWorkspace } from '../getWorkspace';
+
+describe('getWorkspace', () => {
+  beforeEach(() => {
+    fetchMock.resetMocks();
+    localStorage.clear();
+  });
+
+  it('should URI encode the parameters in the request URL', async () => {
+    fetchMock.mockResolvedValue(
+      new Response('{}', {
+        status: 200,
+        statusText: 'OK',
+        headers: [],
+      }),
+    );
+
+    await getWorkspace({
+      projectIds: ['some/slash'],
+    });
+
+    expect(fetchMock).toBeCalledWith('https://stoplight.io/api/v1/projects/some%2Fslash', {
+      headers: expect.objectContaining({
+        'Stoplight-Elements-Version': expect.any(String),
+      }),
+    });
+  });
+});

package/src/handlers/getBranches.ts

@@ -0,0 +1,27 @@
+import { Branches } from '../types';
+import { appVersion } from '../version';
+
+export const getBranches = async ({
+  projectId,
+  platformUrl = 'https://stoplight.io',
+  platformAuthToken,
+}: {
+  projectId: string;
+  platformUrl?: string;
+  platformAuthToken?: string;
+}): Promise<Branches> => {
+  const encodedProjectId = encodeURIComponent(projectId);
+  const response = await fetch(`${platformUrl}/api/v1/projects/${encodedProjectId}/branches`, {
+    headers: {
+      'Stoplight-Elements-Version': appVersion,
+      ...(platformAuthToken && { Authorization: `Bearer ${platformAuthToken}` }),
+    },
+  });
+  const data = await response.json();
+
+  if (!response.ok) {
+    throw new Error(data);
+  }
+
+  return data;
+};

package/src/handlers/getNodeContent.ts

@@ -0,0 +1,53 @@
+import { Node } from '../types';
+import { appVersion } from '../version';
+
+export class ResponseError extends Error {
+  code: number;
+
+  constructor(message: string, responseCode: number) {
+    super(message);
+    this.name = 'ResponseError';
+    this.code = responseCode;
+  }
+}
+
+export const getNodeContent = async ({
+  nodeSlug,
+  projectId,
+  branchSlug,
+  platformUrl = 'https://stoplight.io',
+  platformAuthToken,
+}: {
+  nodeSlug: string;
+  projectId: string;
+  branchSlug?: string;
+  platformUrl?: string;
+  platformAuthToken?: string;
+}): Promise<Node> => {
+  const encodedNodeSlug = encodeURIComponent(nodeSlug);
+  const encodedProjectId = encodeURIComponent(projectId);
+  const encodedBranchSlug = branchSlug ? encodeURIComponent(branchSlug) : '';
+  const branchQuery = encodedBranchSlug ? `?branch=${encodedBranchSlug}` : '';
+  const response = await fetch(
+    `${platformUrl}/api/v1/projects/${encodedProjectId}/nodes/${encodedNodeSlug}${branchQuery}`,
+    {
+      headers: {
+        'Stoplight-Elements-Version': appVersion,
+        ...(platformAuthToken && { Authorization: `Bearer ${platformAuthToken}` }),
+      },
+    },
+  );
+  const data = await response.json();
+
+  if (!response.ok) {
+    if (response.status === 402) {
+      throw new ResponseError('Payment Required', response.status);
+    } else if (response.status === 403) {
+      throw new ResponseError('Forbidden', response.status);
+    } else {
+      throw new ResponseError('Something went wrong', response.status);
+    }
+  }
+
+  return data;
+};

package/src/handlers/getNodes.ts

@@ -0,0 +1,69 @@
+import { NodeSearchResult } from '../types';
+import { appVersion } from '../version';
+
+export const getNodes = async ({
+  workspaceId,
+  branchSlug,
+  projectIds,
+  search,
+  platformUrl = 'https://stoplight.io',
+  platformAuthToken,
+}: {
+  workspaceId?: string;
+  branchSlug?: string;
+  projectIds?: string[];
+  search?: string;
+  platformUrl?: string;
+  platformAuthToken?: string;
+}): Promise<NodeSearchResult[]> => {
+  const queryParams = [];
+  let fetchedWorkspaceId = workspaceId || '';
+
+  if (!workspaceId && projectIds?.length) {
+    const encodedProjectId = encodeURIComponent(projectIds[0]);
+    const response = await fetch(`${platformUrl}/api/v1/projects/${encodedProjectId}`, {
+      headers: {
+        'Stoplight-Elements-Version': appVersion,
+        ...(platformAuthToken && { Authorization: `Bearer ${platformAuthToken}` }),
+      },
+    });
+    const data = await response.json();
+    fetchedWorkspaceId = data.workspace.id;
+  }
+
+  if (projectIds && projectIds.length) {
+    queryParams.push(
+      ...projectIds.map((projectId, index) => {
+        const encodedProjectId = encodeURIComponent(projectId);
+        return `project_ids[${index}]=${encodedProjectId}`;
+      }),
+    );
+  }
+
+  if (search) {
+    const encodedSearch = encodeURIComponent(search);
+    queryParams.push(`search=${encodedSearch}`);
+  }
+
+  if (branchSlug) {
+    const encodedBranchSlug = encodeURIComponent(branchSlug);
+    queryParams.push(`branch=${encodedBranchSlug}`);
+  }
+
+  const query = queryParams.length ? `?${queryParams.join('&')}` : '';
+
+  const encodedWorkspaceId = encodeURIComponent(fetchedWorkspaceId);
+  const response = await fetch(`${platformUrl}/api/v1/workspaces/${encodedWorkspaceId}/nodes${query}`, {
+    headers: {
+      'Stoplight-Elements-Version': appVersion,
+      ...(platformAuthToken && { Authorization: `Bearer ${platformAuthToken}` }),
+    },
+  });
+  const data = await response.json();
+
+  if (!response.ok) {
+    throw new Error(data);
+  }
+
+  return data;
+};

package/src/handlers/getTableOfContents.ts

@@ -0,0 +1,30 @@
+import { ProjectTableOfContents } from '../types';
+import { appVersion } from '../version';
+
+export const getTableOfContents = async ({
+  projectId,
+  branchSlug,
+  platformUrl = 'https://stoplight.io',
+  platformAuthToken,
+}: {
+  projectId: string;
+  branchSlug?: string;
+  platformUrl?: string;
+  platformAuthToken?: string;
+}): Promise<ProjectTableOfContents> => {
+  const encodedProjectId = encodeURIComponent(projectId);
+  const encodedBranchSlug = branchSlug ? encodeURIComponent(branchSlug) : '';
+  const branchQuery = encodedBranchSlug ? `?branch=${encodedBranchSlug}` : '';
+  const response = await fetch(`${platformUrl}/api/v1/projects/${encodedProjectId}/table-of-contents${branchQuery}`, {
+    headers: {
+      'Stoplight-Elements-Version': appVersion,
+      ...(platformAuthToken && { Authorization: `Bearer ${platformAuthToken}` }),
+    },
+  });
+  const data = await response.json();
+
+  if (!response.ok) {
+    throw new Error(data);
+  }
+  return data;
+};

package/src/handlers/getWorkspace.ts

@@ -0,0 +1,27 @@
+import { Workspace } from '../types';
+import { appVersion } from '../version';
+
+export const getWorkspace = async ({
+  projectIds,
+  platformUrl = 'https://stoplight.io',
+  platformAuthToken,
+}: {
+  projectIds: string[];
+  platformUrl?: string;
+  platformAuthToken?: string;
+}): Promise<Workspace> => {
+  const encodedProjectId = encodeURIComponent(projectIds[0]);
+  const response = await fetch(`${platformUrl}/api/v1/projects/${encodedProjectId}`, {
+    headers: {
+      'Stoplight-Elements-Version': appVersion,
+      ...(platformAuthToken && { Authorization: `Bearer ${platformAuthToken}` }),
+    },
+  });
+  const data = await response.json();
+
+  if (!response.ok) {
+    throw new Error(data);
+  }
+
+  return data;
+};

package/src/hooks/__tests__/dataFetching.spec.tsx

@@ -0,0 +1,42 @@
+import '@testing-library/jest-dom';
+
+import { act, renderHook } from '@testing-library/react-hooks';
+import fetchMock from 'jest-fetch-mock';
+import * as React from 'react';
+
+import { DevPortalProvider } from '../../components/DevPortalProvider';
+import { useGetBranches } from '../useGetBranches';
+import { useGetNodeContent } from '../useGetNodeContent';
+import { useGetNodes } from '../useGetNodes';
+import { useGetTableOfContents } from '../useGetTableOfContents';
+
+describe('data fetching', () => {
+  beforeEach(() => {
+    fetchMock.mockResponse(() => Promise.resolve({ status: 200 }));
+    fetchMock.enableMocks();
+  });
+
+  afterEach(() => {
+    fetchMock.disableMocks();
+  });
+
+  it.each<[string, Function, Record<string, string>]>([
+    ['useGetTableOfContents', useGetTableOfContents, { projectId: 'id' }],
+    ['useGetBranches', useGetBranches, { projectId: 'id' }],
+    ['useGetNodeContent', useGetNodeContent, { projectId: 'id', nodeSlug: 'node' }],
+    ['useGetNodes', useGetNodes, { search: 'search', workspaceId: 'id' }],
+  ])('includes authorization header when auth token is present in context for %s', async (_, hook, args) => {
+    const { waitFor } = renderHook(() => hook(args), {
+      wrapper: ({ children }) => <DevPortalProvider platformAuthToken="secret">{children}</DevPortalProvider>,
+    });
+
+    await act(async () => {
+      await waitFor(() => expect(fetchMock).toHaveBeenCalled());
+    });
+    const requestInit = fetchMock.mock.calls[0][1]!;
+
+    const headers = new Headers(requestInit.headers);
+
+    expect(headers.get('Authorization')).toBe('Bearer secret');
+  });
+});