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

package/src/components/Search/Search.stories.tsx

@@ -0,0 +1,151 @@
+import { faSearch, faSpinner } from '@fortawesome/free-solid-svg-icons';
+import { Box, Icon, Input, useModalState } from '@stoplight/mosaic';
+import { Story } from '@storybook/react';
+import * as React from 'react';
+
+import { useGetNodes } from '../../hooks/useGetNodes';
+import { useGetTableOfContents } from '../../hooks/useGetTableOfContents';
+import { useGetWorkspace } from '../../hooks/useGetWorkspace';
+import { NodeSearchResult } from '../../types';
+import { TableOfContents } from '../TableOfContents';
+import { Search, SearchResults } from './';
+
+type SearchWrapperProps = { projectIds: string[]; workspaceId: string; isInResponsiveMode?: boolean };
+// Wrapper to show how to use the node content hook
+const SearchWrapper = ({ projectIds, workspaceId }: SearchWrapperProps) => {
+  const { isOpen, open, close } = useModalState();
+  const [search, setSearch] = React.useState('');
+  const { data, isFetching } = useGetNodes({
+    search,
+    projectIds,
+    workspaceId,
+  });
+
+  const { data: workspace } = useGetWorkspace({
+    projectIds,
+  });
+
+  const handleClose = () => {
+    close();
+    setSearch('');
+  };
+
+  const handleClick = (searchResult: NodeSearchResult) => {
+    console.log('Search clicked', searchResult);
+    window.open(
+      `https://${workspace?.workspace.slug}.stoplight.io/docs/${searchResult.project_slug}${searchResult.uri}`,
+      '_blank',
+    );
+
+    handleClose();
+  };
+
+  return (
+    <>
+      <Input placeholder="Search..." onClick={open} />
+      <Search
+        isLoading={isFetching}
+        search={search}
+        searchResults={data}
+        onSearch={setSearch}
+        isOpen={isOpen}
+        onClose={handleClose}
+        onClick={handleClick}
+      />
+    </>
+  );
+};
+
+const EmbeddedSearchWrapper = ({ projectIds, workspaceId, isInResponsiveMode }: SearchWrapperProps) => {
+  const [search, setSearch] = React.useState('');
+  const { data, isFetching } = useGetNodes({
+    search,
+    projectIds,
+    workspaceId,
+  });
+
+  const { data: workspace } = useGetWorkspace({
+    projectIds,
+  });
+  const { data: tableOfContents } = useGetTableOfContents({ projectId: projectIds[0], branchSlug: '' });
+
+  const handleClick = (searchResult: NodeSearchResult) => {
+    console.log('Search clicked', searchResult);
+    window.open(
+      `https://${workspace?.workspace.slug}.stoplight.io/docs/${searchResult.project_slug}${searchResult.uri}`,
+      '_blank',
+    );
+  };
+
+  return (
+    <>
+      <Box bg="canvas" pos="sticky" style={{ top: 0 }}>
+        <Box bg="canvas" w="full" pt={3}>
+          <Input
+            appearance="minimal"
+            border
+            icon={<Box as={Icon} ml={1} icon={isFetching ? faSpinner : faSearch} spin={isFetching} />}
+            autoFocus
+            placeholder="Search..."
+            value={search}
+            onChange={e => {
+              setSearch(e.currentTarget.value);
+            }}
+            type="search"
+          />
+        </Box>
+      </Box>
+      <Box>
+        {isInResponsiveMode && !search && tableOfContents ? (
+          <TableOfContents
+            isInResponsiveMode={isInResponsiveMode}
+            tableOfContents={tableOfContents}
+            activeId="b3A6MTE0"
+            Link={({ children, ...props }) => {
+              return (
+                <a
+                  onClick={() => {
+                    console.log('Link clicked!', props);
+                  }}
+                >
+                  {children}
+                </a>
+              );
+            }}
+          />
+        ) : (
+          !search && isInResponsiveMode && <>Loading...</>
+        )}
+        {/* show search results first if not in responsive mode */}
+        {!isInResponsiveMode || (isInResponsiveMode && search) ? (
+          <Box p={5}>
+            <SearchResults searchResults={data} onClick={handleClick} isEmbedded={true} />
+          </Box>
+        ) : null}
+      </Box>
+    </>
+  );
+};
+export default {
+  title: 'Public/Search',
+  component: SearchWrapper,
+  argTypes: {
+    workspaceId: { table: { category: 'Input' } },
+    projectIds: { table: { category: 'Input' } },
+    platformUrl: { table: { category: 'Input' } },
+    isInResponsiveMode: { table: { category: 'Input' } },
+  },
+  args: {
+    projectIds: ['cHJqOjYwNjYx'],
+    workspaceId: 'd2s6NDE1NTU',
+    platformUrl: 'https://stoplight.io',
+    isInResponsiveMode: false,
+  },
+};
+
+export const Playground: Story<SearchWrapperProps> = args => <SearchWrapper {...args} />;
+export const EmbeddedSearch: Story<SearchWrapperProps> = args => <EmbeddedSearchWrapper {...args} />;
+
+Playground.storyName = 'Studio Demo';
+
+EmbeddedSearch.storyName = 'Embedded Search';

package/src/components/Search/Search.tsx

@@ -0,0 +1,161 @@
+import { faSearch, faSpinner } from '@fortawesome/free-solid-svg-icons';
+import {
+  NodeTypeColors,
+  NodeTypeIconDefs,
+  withMosaicProvider,
+  withPersistenceBoundary,
+  withQueryClientProvider,
+  withStyles,
+} from '@stoplight/elements-core';
+import { Box, Flex, Icon, Input, ListBox, ListBoxItem, Modal, ModalProps } from '@stoplight/mosaic';
+import { flow } from 'lodash';
+import * as React from 'react';
+
+import { NodeSearchResult } from '../../types';
+
+export type SearchProps = {
+  isLoading?: boolean;
+  search?: string;
+  searchResults?: NodeSearchResult[];
+  onSearch: (search: string) => void;
+  onClick: (result: NodeSearchResult) => void;
+  isOpen?: boolean;
+  onClose: ModalProps['onClose'];
+};
+
+export type SearchResultsListProps = {
+  searchResults?: NodeSearchResult[];
+  isEmbedded?: boolean;
+  showDivider?: boolean;
+  onClick: (result: NodeSearchResult) => void;
+};
+
+const SearchImpl = ({ isLoading, search, searchResults, isOpen, onClose, onClick, onSearch }: SearchProps) => {
+  const listBoxRef = React.useRef<HTMLDivElement>(null);
+
+  const onChange = React.useCallback(e => onSearch(e.currentTarget.value), [onSearch]);
+
+  const onKeyDown = React.useCallback(e => {
+    // Focus the search results on arrow down
+    if (e.key === 'ArrowDown') {
+      e.preventDefault();
+      listBoxRef.current?.focus();
+    }
+  }, []);
+
+  return (
+    <Modal
+      renderHeader={() => (
+        <Input
+          appearance="minimal"
+          borderB
+          size="lg"
+          icon={<Box as={Icon} ml={1} icon={isLoading ? faSpinner : faSearch} spin={isLoading} />}
+          autoFocus
+          placeholder="Search..."
+          value={search}
+          onChange={onChange}
+          onKeyDown={onKeyDown}
+        />
+      )}
+      isOpen={!!isOpen}
+      onClose={onClose}
+    >
+      <SearchResultsList searchResults={searchResults} onClick={onClick} />
+    </Modal>
+  );
+};
+
+export const SearchResultsList = ({
+  searchResults,
+  onClick,
+  isEmbedded,
+  showDivider = true,
+}: SearchResultsListProps) => {
+  const listBoxRef = React.useRef<HTMLDivElement>(null);
+  const onSelectionChange = React.useCallback(
+    keys => {
+      const selectedId = keys.values().next().value;
+      const selectedResult = searchResults?.find(
+        searchResult => `${searchResult.id}-${searchResult.project_id}` === selectedId,
+      );
+      if (selectedResult) {
+        onClick(selectedResult);
+      }
+    },
+    [searchResults, onClick],
+  );
+
+  return (
+    <>
+      {searchResults && searchResults.length > 0 ? (
+        <ListBox
+          ref={listBoxRef}
+          aria-label="Search"
+          overflowY="auto"
+          h={isEmbedded ? undefined : 80}
+          m={-5}
+          items={searchResults}
+          selectionMode="single"
+          onSelectionChange={onSelectionChange}
+        >
+          {(searchResult: NodeSearchResult) => {
+            return (
+              <ListBoxItem key={`${searchResult.id}-${searchResult.project_id}`} textValue={searchResult.title}>
+                <Box p={3} borderB={!showDivider ? undefined : true}>
+                  <Flex align="center">
+                    <Box
+                      as={Icon}
+                      w={4}
+                      icon={NodeTypeIconDefs[searchResult.type as keyof typeof NodeTypeIconDefs]}
+                      style={{ color: NodeTypeColors[searchResult.type as keyof typeof NodeTypeIconDefs] }}
+                    />
+
+                    <Box
+                      flex={1}
+                      fontSize="lg"
+                      dangerouslySetInnerHTML={{ __html: searchResult.highlighted.name ?? '' }}
+                      fontWeight="medium"
+                      textOverflow="overflow-ellipsis"
+                      mx={2}
+                    />
+
+                    <Box fontSize="sm" color="muted">
+                      {searchResult.project_name}
+                    </Box>
+                  </Flex>
+
+                  <Box
+                    dangerouslySetInnerHTML={{ __html: searchResult.highlighted.summary ?? '' }}
+                    color="muted"
+                    fontSize="sm"
+                    mt={1}
+                    ml={6}
+                  />
+                </Box>
+              </ListBoxItem>
+            );
+          }}
+        </ListBox>
+      ) : (
+        <Flex w="full" h={80} align="center" justify="center" m={-5}>
+          No search results
+        </Flex>
+      )}
+    </>
+  );
+};
+
+export const SearchResults = flow(
+  withStyles,
+  withPersistenceBoundary,
+  withMosaicProvider,
+  withQueryClientProvider,
+)(SearchResultsList);
+
+export const Search = flow(
+  withStyles,
+  withPersistenceBoundary,
+  withMosaicProvider,
+  withQueryClientProvider,
+)(SearchImpl);

package/src/components/Search/SearchOverlay.tsx

@@ -0,0 +1,88 @@
+import { faSearch, faSpinner } from '@fortawesome/free-solid-svg-icons';
+import type { CustomLinkComponent } from '@stoplight/elements-core';
+import { Box, Button, Flex, Icon, Input, Modal } from '@stoplight/mosaic';
+import * as React from 'react';
+import { Link } from 'react-router-dom';
+
+import { NodeSearchResult, ProjectTableOfContents } from '../../types';
+import { TableOfContents } from '../TableOfContents';
+import { SearchResults } from './Search';
+
+type SearchOverlayProps = {
+  isFetching: boolean;
+  search: string;
+  setSearch: (search: string) => void;
+  data?: NodeSearchResult[];
+  toc?: ProjectTableOfContents;
+  nodeSlug?: string;
+  projectSlug?: string;
+  branchSlug?: string;
+  isSearchShowing: boolean;
+  onClose: () => void;
+  onClick: (item?: NodeSearchResult) => void;
+};
+
+export const SearchOverlay = ({
+  isFetching,
+  search,
+  setSearch,
+  data,
+  toc,
+  nodeSlug,
+  projectSlug,
+  branchSlug,
+  isSearchShowing,
+  onClose,
+  onClick,
+}: SearchOverlayProps) => {
+  return (
+    <Modal isOpen={isSearchShowing} onClose={onClose}>
+      <Box className="sl-overlay" bg="canvas" overflowY="scroll" data-test="search-overlay">
+        <Flex alignItems="center" h="3xl" px={7} bg="canvas" borderB pos="sticky" zIndex={20}>
+          <Flex w="full">
+            <Box pt={1} pr={2}>
+              <Button
+                appearance="minimal"
+                onClick={() => {
+                  onClose();
+                }}
+                data-test="search-overlay-back-button"
+              >
+                <Icon icon={['fas', 'arrow-left']} color="gray" size="lg" />
+              </Button>
+            </Box>
+            <Input
+              border
+              data-test="docs-search-input"
+              display="inline-block"
+              appearance="minimal"
+              icon={<Box as={Icon} ml={1} icon={isFetching ? faSpinner : faSearch} spin={isFetching} />}
+              autoFocus
+              placeholder={projectSlug ? 'Search within the project' : 'Search...'}
+              value={search}
+              onChange={e => {
+                setSearch(e.currentTarget.value);
+              }}
+              type="search"
+              w="full"
+              size="lg"
+            />
+          </Flex>
+        </Flex>
+        <Box px={5} py={toc && !search ? 0 : 5} data-test="responsive-project-toc">
+          {toc && !search && projectSlug && (
+            <TableOfContents
+              tableOfContents={{ ...toc, hide_powered_by: true }}
+              activeId={nodeSlug || ''}
+              Link={Link as CustomLinkComponent}
+              onLinkClick={onClick}
+            />
+          )}
+          {search && (
+            <SearchResults searchResults={data} onClick={item => onClick(item)} isEmbedded={true} showDivider={false} />
+          )}
+        </Box>
+      </Box>
+    </Modal>
+  );
+};

package/src/components/Search/index.tsx

@@ -0,0 +1 @@
+export * from './Search';

package/src/components/TableOfContents/TableOfContents.stories.tsx

@@ -0,0 +1,68 @@
+import { Story } from '@storybook/react';
+import * as React from 'react';
+
+import { useGetTableOfContents } from '../../hooks/useGetTableOfContents';
+import { TableOfContents } from './';
+
+// Wrapper to show how to use the node content hook
+const TableOfContentsWrapper = ({
+  projectId,
+  branchSlug,
+  isInResponsiveMode,
+}: {
+  projectId: string;
+  branchSlug?: string;
+  isInResponsiveMode?: boolean;
+}) => {
+  const { data } = useGetTableOfContents({ projectId, branchSlug });
+
+  return data ? (
+    <TableOfContents
+      isInResponsiveMode={isInResponsiveMode}
+      activeId="b3A6MTE0"
+      tableOfContents={data}
+      Link={({ children, ...props }) => {
+        return (
+          <a
+            onClick={() => {
+              console.log('Link clicked!', props);
+            }}
+          >
+            {children}
+          </a>
+        );
+      }}
+      style={{
+        width: '300px',
+      }}
+    />
+  ) : (
+    <>Loading</>
+  );
+};
+
+export default {
+  title: 'Public/TableOfContents',
+  component: TableOfContentsWrapper,
+  argTypes: {
+    projectId: { table: { category: 'Input' } },
+    branchSlug: { table: { category: 'Input' } },
+    platformUrl: { table: { category: 'Input' } },
+    isInResponsiveMode: { table: { category: 'Input' } },
+  },
+  args: {
+    projectId: 'cHJqOjYwNjYx',
+    branchSlug: '',
+    platformUrl: 'https://stoplight.io',
+    isInResponsiveMode: false,
+  },
+};
+
+export const Playground: Story<{
+  nodeSlug: string;
+  projectId: string;
+  branchSlug?: string;
+  isInResponsiveMode?: boolean;
+}> = args => <TableOfContentsWrapper {...args} />;
+
+Playground.storyName = 'Studio Demo';

package/src/components/TableOfContents/TableOfContents.tsx

@@ -0,0 +1,54 @@
+import {
+  CustomLinkComponent,
+  PoweredByLink,
+  TableOfContents as ElementsTableOfContents,
+} from '@stoplight/elements-core';
+import { BoxProps, Flex } from '@stoplight/mosaic';
+import * as React from 'react';
+
+import { ProjectTableOfContents } from '../../types';
+
+export type TableOfContentsProps = BoxProps<'div'> & {
+  activeId: string;
+  tableOfContents: ProjectTableOfContents;
+  Link: CustomLinkComponent;
+  collapseTableOfContents?: boolean;
+  externalScrollbar?: boolean;
+  isInResponsiveMode?: boolean;
+  onLinkClick?(): void;
+};
+
+export const TableOfContents = ({
+  tableOfContents,
+  activeId,
+  Link,
+  collapseTableOfContents = false,
+  externalScrollbar,
+  isInResponsiveMode = false,
+  onLinkClick,
+  ...boxProps
+}: TableOfContentsProps) => {
+  return (
+    <Flex bg={isInResponsiveMode ? 'canvas' : 'canvas-100'} {...boxProps} flexDirection="col" maxH="full">
+      <Flex flexGrow flexShrink overflowY="auto">
+        <ElementsTableOfContents
+          tree={tableOfContents.items}
+          activeId={activeId}
+          Link={Link}
+          maxDepthOpenByDefault={collapseTableOfContents ? 0 : 1}
+          externalScrollbar={externalScrollbar}
+          onLinkClick={onLinkClick}
+          isInResponsiveMode={isInResponsiveMode}
+        />
+      </Flex>
+
+      {tableOfContents.hide_powered_by ? null : (
+        <PoweredByLink
+          source={activeId}
+          pathname={typeof window !== 'undefined' ? window.location.pathname : ''}
+          packageType="elements-dev-portal"
+        />
+      )}
+    </Flex>
+  );
+};

package/src/components/TableOfContents/index.tsx

@@ -0,0 +1 @@
+export * from './TableOfContents';

package/src/components/UpgradeToStarter.tsx

@@ -0,0 +1,22 @@
+import { Box, Flex, Icon } from '@stoplight/mosaic';
+import React from 'react';
+
+export const UpgradeToStarter = () => (
+  <Flex
+    as="a"
+    href="https://stoplight.io/pricing/"
+    target="_blank"
+    rel="noreferrer noopener"
+    justify="center"
+    alignItems="center"
+    w="full"
+    minH="screen"
+    color="muted"
+    flexDirection="col"
+  >
+    <Icon icon={['fas', 'exclamation-triangle']} size="4x" />
+    <Box pt={3}>
+      Please upgrade your Stoplight Workspace to the Starter Plan to use Elements Dev Portal in production.
+    </Box>
+  </Flex>
+);

package/src/consts.ts

@@ -0,0 +1,32 @@
+const ROOT_CACHE_KEY = '@stoplight/elements-dev-portal/client-query';
+
+export const devPortalCacheKeys = {
+  all: [ROOT_CACHE_KEY] as const,
+
+  projects: () => [ROOT_CACHE_KEY, 'projects'] as const,
+  project: (projectId: string) => [...devPortalCacheKeys.projects(), projectId] as const,
+  projectsList: () => [...devPortalCacheKeys.projects(), 'list'] as const,
+  projectDetails: (projectId: string) => [...devPortalCacheKeys.project(projectId), 'details'] as const,
+
+  branches: (projectId: string) => [...devPortalCacheKeys.project(projectId), 'branches'] as const,
+  branch: (projectId: string, branch: string) => [...devPortalCacheKeys.branches(projectId), branch] as const,
+  branchesList: (projectId: string) => [...devPortalCacheKeys.branches(projectId), 'list'] as const,
+  branchDetails: (projectId: string, branch: string) =>
+    [...devPortalCacheKeys.branch(projectId, branch), 'details'] as const,
+  branchTOC: (projectId: string, branch: string) => [...devPortalCacheKeys.branch(projectId, branch), 'toc'] as const,
+
+  branchNodes: (projectId: string, branch: string) =>
+    [...devPortalCacheKeys.branch(projectId, branch), 'nodes'] as const,
+  branchNode: (projectId: string, branch: string, node: string) =>
+    [...devPortalCacheKeys.branchNodes(projectId, branch), node] as const,
+  branchNodesList: (projectId: string, branch: string) =>
+    [...devPortalCacheKeys.branchNodes(projectId, branch), 'list'] as const,
+  branchNodeDetails: (projectId: string, branch: string, node: string) =>
+    [...devPortalCacheKeys.branchNode(projectId, branch, node), 'details'] as const,
+
+  search: () => [...devPortalCacheKeys.all, 'search'],
+  searchNodes: (filters: { projectIds?: string[]; branchSlug?: string; workspaceId?: string; search?: string }) => [
+    ...devPortalCacheKeys.search(),
+    filters,
+  ],
+};

package/src/containers/StoplightProject.spec.tsx

@@ -0,0 +1,78 @@
+import '@testing-library/jest-dom';
+
+import { render, screen } from '@testing-library/react';
+import fetchMock from 'jest-fetch-mock';
+import * as React from 'react';
+
+import branches from '../__fixtures__/branches.json';
+import nodeContent from '../__fixtures__/node-content.json';
+import tableOfContents from '../__fixtures__/table-of-contents.json';
+import { StoplightProject } from './StoplightProject';
+
+describe('Stoplight Project', () => {
+  beforeEach(() => {
+    fetchMock.mockResponse(request => {
+      if (request.url.match(/\/api\/v1\/projects\/[a-zA-Z0-9_.-]+\/table-of-contents/i)) {
+        return Promise.resolve({
+          body: JSON.stringify(tableOfContents),
+          status: 200,
+          statusText: 'OK',
+          headers: [],
+        });
+      } else if (request.url.match(/\/api\/v1\/projects\/[a-zA-Z0-9_.-]+\/nodes/i)) {
+        return Promise.resolve({
+          body: JSON.stringify(nodeContent),
+          status: 200,
+          statusText: 'OK',
+          headers: [],
+        });
+      } else if (request.url.match(/\/api\/v1\/projects\/[a-zA-Z0-9_.-]+\/branches/i)) {
+        return Promise.resolve({
+          body: JSON.stringify(branches),
+          status: 200,
+          statusText: 'OK',
+          headers: [],
+        });
+      } else {
+        return Promise.resolve({ status: 404, statusText: 'Not Found', headers: [], body: '' });
+      }
+    });
+    fetchMock.enableMocks();
+  });
+
+  afterEach(() => {
+    fetchMock.disableMocks();
+  });
+
+  it('loads correctly using memory router', async () => {
+    render(<StoplightProject router="memory" projectId="cHJqOjYwNjYx" platformUrl="https://stoplight.io" />);
+
+    expect(
+      await screen.findByText(
+        'Markdown is supported in descriptions. Add information here for users to get accustomed to endpoints',
+        {},
+        { timeout: 10000 },
+      ),
+    ).toBeInTheDocument();
+  });
+
+  it('loads correctly using static router', async () => {
+    render(
+      <StoplightProject
+        router="static"
+        projectId="cHJqOjYwNjYx"
+        basePath=""
+        staticRouterPath="/b3A6Mzg5NDM2-create-todo"
+        platformUrl="https://stoplight.io"
+      />,
+    );
+
+    expect(
+      await screen.findByText(
+        'Markdown is supported in descriptions. Add information here for users to get accustomed to endpoints',
+        {},
+        { timeout: 10000 },
+      ),
+    ).toBeInTheDocument();
+  });
+});

package/src/containers/StoplightProject.stories.tsx

@@ -0,0 +1,28 @@
+import { Story } from '@storybook/react';
+import * as React from 'react';
+
+import { StoplightProject, StoplightProjectProps } from './StoplightProject';
+
+export default {
+  title: 'Public/StoplightProject',
+  component: StoplightProject,
+  argTypes: {
+    projectId: { table: { category: 'Input' } },
+    hideTryIt: { table: { category: 'Input' } },
+    hideMocking: { table: { category: 'Input' } },
+    basePath: { table: { category: 'Routing' } },
+    router: { table: { category: 'Routing' } },
+    platformUrl: { table: { category: 'Advanced' } },
+  },
+  args: {
+    router: 'memory',
+    platformUrl: 'https://stoplight.io',
+  },
+};
+
+export const Playground: Story<StoplightProjectProps> = args => <StoplightProject {...args} />;
+Playground.storyName = 'Studio Demo';
+Playground.args = {
+  projectId: 'cHJqOjYwNjYx',
+  platformUrl: 'https://stoplight.io',
+};