@stoplight/elements-core 9.0.11 → 9.0.12-beta-0.1

package/src/components/Docs/HttpOperation/Parameters.spec.tsx

@@ -0,0 +1,101 @@
+import { HttpParamStyles, IHttpParam } from '@stoplight/types';
+import { screen } from '@testing-library/dom';
+import { render } from '@testing-library/react';
+import { JSONSchema7 } from 'json-schema';
+import { omit } from 'lodash';
+import * as React from 'react';
+
+import { Parameters } from './Parameters';
+
+describe('Parameter', () => {
+  const data: IHttpParam = {
+    id: '?http-example-example-key?',
+    name: 'parameter name',
+    description: 'a parameter description',
+    schema: {
+      enum: ['foo', 'bar'],
+      default: 'foo',
+      type: 'string',
+    },
+    deprecated: true,
+    explode: true,
+    required: true,
+    style: HttpParamStyles.Form,
+    examples: [
+      {
+        id: '?http-example-example-key?',
+        value: 'example value',
+        key: 'example key',
+      },
+    ],
+  };
+
+  const schema = { type: 'array', items: { type: 'string', enum: ['foo', 'bar'] } } as JSONSchema7;
+
+  it('should render correct name and description', async () => {
+    render(<Parameters parameters={[data]} parameterType="query" />);
+
+    expect(await screen.findByText(/parameter name$/)).toBeInTheDocument();
+    expect(await screen.findByText(/a parameter description/)).toBeInTheDocument();
+  });
+
+  it('should render if parameter is deprecated', async () => {
+    render(<Parameters parameters={[data]} parameterType="query" />);
+
+    expect(await screen.findByText(/deprecated/)).toBeInTheDocument();
+  });
+
+  it('should render correct basic type', async () => {
+    render(<Parameters parameters={[data]} parameterType="query" />);
+
+    expect(await screen.findByText(/string/)).toBeInTheDocument();
+  });
+
+  it('should render correct array subtype', async () => {
+    render(<Parameters parameters={[{ ...data, schema: schema }]} parameterType="query" />);
+
+    expect(await screen.findByText(/array\[string\]/)).toBeInTheDocument();
+  });
+
+  it('should render correct validations', async () => {
+    render(<Parameters parameters={[data]} parameterType="query" />);
+
+    expect(await screen.findByText(/required/)).toBeInTheDocument();
+    expect(await screen.findByText(/Default:/)).toBeInTheDocument();
+    expect(await screen.findAllByText(/foo/)).toHaveLength(2);
+    expect(await screen.findByText(/bar/)).toBeInTheDocument();
+  });
+
+  it('should render validations from schema items', async () => {
+    render(<Parameters parameters={[{ ...data, schema: schema }]} parameterType="query" />);
+
+    expect(await screen.findByText(/Allowed values:/)).toBeInTheDocument();
+    expect(await screen.findByText(/foo/)).toBeInTheDocument();
+    expect(await screen.findByText(/bar/)).toBeInTheDocument();
+  });
+
+  it('should render correct examples', async () => {
+    render(<Parameters parameters={[data]} parameterType="query" />);
+
+    expect(screen.queryByText(/Example:/)).toBeInTheDocument();
+    expect(screen.queryByText(/example value/)).toBeInTheDocument();
+    expect(screen.queryByText(/example key/)).not.toBeInTheDocument();
+  });
+
+  it('should render scheme-less params', async () => {
+    render(
+      <Parameters
+        parameters={[
+          { ...data, name: 'param' },
+          omit({ ...data, name: 'param 2', description: 'a param 2 description' }, 'schema'),
+          omit({ ...data, name: 'param 3', description: 'a param 3 description', deprecated: false }, 'schema'),
+        ]}
+        parameterType="query"
+      />,
+    );
+
+    expect(await screen.findByText(/a parameter description/)).toBeInTheDocument();
+    expect(await screen.findByText(/a param 2 description/)).toBeInTheDocument();
+    expect(await screen.findByText(/a param 3 description/)).toBeInTheDocument();
+  });
+});

package/src/components/Docs/HttpOperation/Parameters.tsx

@@ -0,0 +1,118 @@
+import { isPlainObject } from '@stoplight/json';
+import { JsonSchemaViewer } from '@stoplight/json-schema-viewer';
+import { HttpParamStyles, IHttpParam } from '@stoplight/types';
+import type { JSONSchema7Object } from 'json-schema';
+import { sortBy } from 'lodash';
+import * as React from 'react';
+
+import { useSchemaInlineRefResolver } from '../../../context/InlineRefResolver';
+import { useOptionsCtx } from '../../../context/Options';
+import { isNodeExample } from '../../../utils/http-spec/examples';
+
+type ParameterType = 'query' | 'header' | 'path' | 'cookie';
+
+interface ParametersProps {
+  parameterType: ParameterType;
+  parameters?: IHttpParam[];
+}
+
+const readableStyles: Readonly<Partial<Record<HttpParamStyles, string>>> = {
+  [HttpParamStyles.PipeDelimited]: 'Pipe separated values',
+  [HttpParamStyles.SpaceDelimited]: 'Space separated values',
+  [HttpParamStyles.CommaDelimited]: 'Comma separated values',
+  [HttpParamStyles.Simple]: 'Comma separated values',
+  [HttpParamStyles.Matrix]: 'Path style values',
+  [HttpParamStyles.Label]: 'Label style values',
+  [HttpParamStyles.Form]: 'Form style values',
+};
+
+const defaultStyle: Readonly<Partial<Record<string, HttpParamStyles>>> = {
+  query: HttpParamStyles.Form,
+  header: HttpParamStyles.Simple,
+  path: HttpParamStyles.Simple,
+  cookie: HttpParamStyles.Form,
+};
+
+export const Parameters: React.FunctionComponent<ParametersProps> = ({ parameters, parameterType }) => {
+  const { nodeHasChanged, renderExtensionAddon } = useOptionsCtx();
+  const [refResolver, maxRefDepth] = useSchemaInlineRefResolver();
+
+  const schema = React.useMemo(
+    () => httpOperationParamsToSchema({ parameters, parameterType }),
+    [parameters, parameterType],
+  );
+
+  if (!schema) return null;
+
+  return (
+    <JsonSchemaViewer
+      resolveRef={refResolver}
+      maxRefDepth={maxRefDepth}
+      schema={schema}
+      disableCrumbs
+      nodeHasChanged={nodeHasChanged}
+      renderExtensionAddon={renderExtensionAddon}
+    />
+  );
+};
+Parameters.displayName = 'HttpOperation.Parameters';
+
+const httpOperationParamsToSchema = ({ parameters, parameterType }: ParametersProps): JSONSchema7Object | null => {
+  if (!parameters || !parameters.length) return null;
+
+  const schema = {
+    properties: {},
+    required: [],
+  };
+
+  const sortedParams = sortBy(parameters, ['required', 'name']);
+
+  for (const p of sortedParams) {
+    const { name, description, required, deprecated, examples, style } = p;
+
+    const paramSchema = isPlainObject(p.schema) ? p.schema : {};
+    const paramExamples =
+      examples?.map(example => {
+        if (isNodeExample(example)) {
+          return example.value;
+        }
+
+        return example.externalValue;
+      }) || [];
+
+    const schemaExamples = paramSchema.examples;
+    const schemaExamplesArray = Array.isArray(schemaExamples) ? schemaExamples : [];
+
+    // TODO (CL): This can be removed when http operations are fixed https://github.com/stoplightio/http-spec/issues/26
+    const paramDescription = description || paramSchema.description;
+    const paramDeprecated = !!(deprecated || paramSchema.deprecated);
+
+    let paramStyle: string | undefined;
+    if (style && style !== HttpParamStyles.Unspecified && defaultStyle[parameterType] !== style) {
+      paramStyle = readableStyles[style] || style;
+    }
+
+    if (isPlainObject(schema.properties)) {
+      schema.properties![p.name] = {
+        ...paramSchema,
+        description: paramDescription,
+        examples: [...paramExamples, ...schemaExamplesArray],
+        deprecated: paramDeprecated,
+        style: paramStyle,
+
+        // the schema is technically the param, so set the stored id to the param's id
+        'x-stoplight': {
+          ...(isPlainObject(paramSchema['x-stoplight']) ? paramSchema['x-stoplight'] : {}),
+          id: p.id,
+        },
+      };
+    }
+
+    if (required && Array.isArray(schema.required)) {
+      // @ts-ignore
+      schema.required.push(name);
+    }
+  }
+
+  return schema;
+};

package/src/components/Docs/HttpOperation/Request.tsx

@@ -0,0 +1,152 @@
+import { Box, Callout, NodeAnnotation, VStack } from '@stoplight/mosaic';
+import { HttpSecurityScheme, IHttpEndpointOperation } from '@stoplight/types';
+import { useAtom } from 'jotai';
+import { atomWithStorage } from 'jotai/utils';
+import * as React from 'react';
+
+import { operation } from '../../../__fixtures__/operations/simple-get';
+import { OptionalSecurityMessage } from '../../../constants';
+import { useOptionsCtx } from '../../../context/Options';
+import { getReadableSecurityNames, getSecurityGroupId, shouldAddKey } from '../../../utils/oas/security';
+import { SectionSubtitle, SectionTitle, SubSectionPanel } from '../Sections';
+import { PanelContent } from '../Security/PanelContent';
+import { Body, isBodyEmpty } from './Body';
+import { Parameters } from './Parameters';
+
+interface IRequestProps {
+  operation: IHttpEndpointOperation;
+  hideSecurityInfo?: boolean;
+  onChange?: (requestBodyIndex: number) => void;
+  isHttpWebhookOperation?: boolean;
+  disableProps?: Array<{
+    location: string;
+    paths: Array<{ path: string }>;
+  }>;
+}
+
+export const Request: React.FunctionComponent<IRequestProps> = ({
+  operation: {
+    request,
+    request: {
+      path: pathParams = [],
+      headers: headerParams = [],
+      cookie: cookieParams = [],
+      body,
+      query: queryParams = [],
+    } = {},
+    security,
+  },
+  hideSecurityInfo,
+  onChange,
+  isHttpWebhookOperation = false,
+  disableProps,
+}) => {
+  if (!request || typeof request !== 'object') return null;
+
+  const bodyIsEmpty = isBodyEmpty(body);
+  const securitySchemes = security ?? [];
+  const hasRequestData = Boolean(
+    securitySchemes.length ||
+      pathParams.length ||
+      queryParams.length ||
+      headerParams.length ||
+      cookieParams.length ||
+      !bodyIsEmpty,
+  );
+  if (!hasRequestData) return null;
+
+  return (
+    <VStack spacing={8}>
+      <SectionTitle title="Request" />
+
+      {hideSecurityInfo ? null : <SecuritySchemes schemes={securitySchemes} parentId={operation.id} />}
+
+      {pathParams.length > 0 && (
+        <VStack spacing={5}>
+          <SectionSubtitle title="Path Parameters" />
+          <Parameters parameterType="path" parameters={pathParams} />
+        </VStack>
+      )}
+
+      {queryParams.length > 0 && (
+        <VStack spacing={5}>
+          <SectionSubtitle title="Query Parameters" />
+          <Parameters parameterType="query" parameters={queryParams} />
+        </VStack>
+      )}
+
+      {headerParams.length > 0 && (
+        <VStack spacing={5}>
+          <SectionSubtitle title="Headers" id="request-headers" />
+          <Parameters parameterType="header" parameters={headerParams} />
+        </VStack>
+      )}
+
+      {cookieParams.length > 0 && (
+        <VStack spacing={5}>
+          <SectionSubtitle title="Cookies" id="request-cookies" />
+          <Parameters parameterType="cookie" parameters={cookieParams} />
+        </VStack>
+      )}
+
+      {body && (
+        <Body
+          onChange={onChange}
+          body={body}
+          isHttpWebhookOperation={isHttpWebhookOperation}
+          disableProps={disableProps}
+        />
+      )}
+    </VStack>
+  );
+};
+Request.displayName = 'HttpOperation.Request';
+
+const schemeExpandedState = atomWithStorage<Record<string, boolean>>('HttpOperation_security_expanded', {});
+
+const SecurityPanel: React.FC<{ schemes: HttpSecurityScheme[]; includeKey: boolean }> = ({ schemes, includeKey }) => {
+  const [expandedState, setExpanded] = useAtom(schemeExpandedState);
+
+  return (
+    <SubSectionPanel
+      title={`Security: ${getReadableSecurityNames(schemes, includeKey)}`}
+      defaultIsOpen={!!expandedState[getReadableSecurityNames(schemes)]}
+      onChange={isOpen => setExpanded({ ...expandedState, [getReadableSecurityNames(schemes)]: isOpen })}
+    >
+      <Box m={-2}>
+        <PanelContent schemes={schemes} />
+      </Box>
+    </SubSectionPanel>
+  );
+};
+
+const SecuritySchemes = ({ schemes, parentId }: { schemes: HttpSecurityScheme[][]; parentId: string }) => {
+  const { nodeHasChanged } = useOptionsCtx();
+
+  if (!schemes.length) {
+    return null;
+  }
+
+  const includeOptional = schemes.length > 1 && schemes.some(scheme => scheme.length === 0);
+
+  return (
+    <VStack spacing={3}>
+      {includeOptional && <OptionalMessage />}
+      {schemes
+        .filter(scheme => scheme.length > 0) // Remove the None scheme from listed display
+        .map((scheme, i) => {
+          const secGroupId = getSecurityGroupId(parentId, i);
+          return (
+            <Box pos="relative" key={secGroupId} p={0} data-test="http-operation-security-row">
+              <NodeAnnotation change={nodeHasChanged?.({ nodeId: secGroupId })} />
+              <SecurityPanel schemes={scheme} includeKey={shouldAddKey(scheme, schemes)} />
+            </Box>
+          );
+        })}
+    </VStack>
+  );
+};
+
+const OptionalMessage: React.FC = () => {
+  return <Callout appearance="outline">{OptionalSecurityMessage}</Callout>;
+};

package/src/components/Docs/HttpOperation/Responses.tsx

@@ -0,0 +1,301 @@
+import { JsonSchemaViewer } from '@stoplight/json-schema-viewer';
+import {
+  Box,
+  Button,
+  Flex,
+  HStack,
+  Icon,
+  IntentVals,
+  ListBox,
+  ListBoxItem,
+  Modal,
+  NodeAnnotation,
+  Select,
+  Tab,
+  TabList,
+  TabPanel,
+  TabPanels,
+  Tabs,
+  Text,
+  useModalState,
+  VStack,
+} from '@stoplight/mosaic';
+import { IHttpOperationResponse } from '@stoplight/types';
+import { sortBy, uniqBy } from 'lodash';
+import * as React from 'react';
+
+import { useSchemaInlineRefResolver } from '../../../context/InlineRefResolver';
+import { useOptionsCtx } from '../../../context/Options';
+import { getOriginalObject } from '../../../utils/ref-resolving/resolvedObject';
+import { MarkdownViewer } from '../../MarkdownViewer';
+import { SectionSubtitle, SectionTitle } from '../Sections';
+import LazySchemaTreePreviewer from './LazySchemaTreePreviewer';
+import { Parameters } from './Parameters';
+
+interface DisablePropEntry {
+  location: string;
+  paths: Array<{ path: string }>;
+  isComplex: boolean;
+}
+
+interface DisablePropsByStatus {
+  [statusCode: string]: DisablePropEntry[];
+}
+
+interface ResponseProps {
+  response: IHttpOperationResponse;
+  onMediaTypeChange?: (mediaType: string) => void;
+  disableProps?: DisablePropsByStatus;
+  statusCode?: string;
+}
+
+interface ResponsesProps {
+  responses: IHttpOperationResponse[];
+  onMediaTypeChange?: (mediaType: string) => void;
+  onStatusCodeChange?: (statusCode: string) => void;
+  isCompact?: boolean;
+  disableProps?: DisablePropsByStatus;
+}
+
+export const Responses = ({
+  responses: unsortedResponses,
+  onStatusCodeChange,
+  onMediaTypeChange,
+  isCompact,
+  disableProps,
+}: ResponsesProps) => {
+  const responses = sortBy(
+    uniqBy(unsortedResponses, r => r.code),
+    r => r.code,
+  );
+
+  const [activeResponseId, setActiveResponseId] = React.useState(responses[0]?.code ?? '');
+  const { isOpen, open, close } = useModalState();
+
+  const onSelectionChange = React.useCallback(
+    keys => {
+      const selectedId = keys.values().next().value;
+      const selectedResponse = responses?.find(response => response.id === selectedId);
+      if (selectedResponse) {
+        setActiveResponseId(selectedResponse.code);
+        close();
+      }
+    },
+    [responses, setActiveResponseId, close],
+  );
+
+  React.useEffect(() => {
+    onStatusCodeChange?.(activeResponseId);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [activeResponseId]);
+
+  if (!responses.length) return null;
+
+  const response = responses.find(r => r.code === activeResponseId) || responses[0];
+
+  const compactResponses = (
+    <>
+      <Button
+        aria-label="response-codes"
+        onPress={open}
+        iconRight={<Icon icon="chevron-down" color="var(--color-border-button)" />}
+        style={{
+          color: `var(--color-${codeToIntentVal(activeResponseId)})`,
+        }}
+        appearance="minimal"
+      >
+        {activeResponseId}
+      </Button>
+
+      <Modal
+        title="Response Code"
+        isOpen={isOpen}
+        onClose={close}
+        size="sm"
+        footer={
+          <HStack justifyContent="end">
+            <Button onPress={close} intent="default" appearance="primary">
+              Close
+            </Button>
+          </HStack>
+        }
+      >
+        <ListBox
+          aria-label="Response Code"
+          overflowY="auto"
+          m={-5}
+          items={responses}
+          selectionMode="single"
+          onSelectionChange={onSelectionChange}
+        >
+          {(response: IHttpOperationResponse) => (
+            <ListBoxItem key={response.id}>
+              <Box data-test={response.code} p={3} bg={{ hover: 'primary-tint' }}>
+                <Flex w="2xl" align="center" justify="end">
+                  {response.code === activeResponseId && <Box as={Icon} icon="check" />}
+                  <Text ml={3} fontWeight="medium">
+                    {response.code}
+                  </Text>
+                </Flex>
+              </Box>
+            </ListBoxItem>
+          )}
+        </ListBox>
+      </Modal>
+    </>
+  );
+
+  const tabResponses = (
+    <TabList density="compact">
+      {responses.map(({ code }) => (
+        <Tab key={code} id={code} intent={codeToIntentVal(code)}>
+          {code}
+        </Tab>
+      ))}
+    </TabList>
+  );
+
+  return (
+    <VStack spacing={8} as={Tabs} selectedId={activeResponseId} onChange={setActiveResponseId} appearance="pill">
+      <SectionTitle title="Responses" isCompact={isCompact}>
+        {isCompact ? compactResponses : tabResponses}
+      </SectionTitle>
+
+      {isCompact ? (
+        <Response
+          response={response}
+          onMediaTypeChange={onMediaTypeChange}
+          disableProps={disableProps}
+          statusCode={activeResponseId}
+        />
+      ) : (
+        <TabPanels p={0}>
+          {responses.map(response => (
+            <TabPanel key={response.code} id={response.code}>
+              <Response
+                response={response}
+                onMediaTypeChange={onMediaTypeChange}
+                disableProps={disableProps}
+                statusCode={response.code}
+              />
+            </TabPanel>
+          ))}
+        </TabPanels>
+      )}
+    </VStack>
+  );
+};
+Responses.displayName = 'HttpOperation.Responses';
+
+const Response = ({ response, onMediaTypeChange, disableProps, statusCode }: ResponseProps) => {
+  const { contents = [], headers = [], description } = response;
+  const [chosenContent, setChosenContent] = React.useState(0);
+  const [refResolver, maxRefDepth] = useSchemaInlineRefResolver();
+  const { nodeHasChanged, renderExtensionAddon } = useOptionsCtx();
+
+  const responseContent = contents[chosenContent];
+  const schema: any = responseContent?.schema;
+
+  React.useEffect(() => {
+    responseContent && onMediaTypeChange?.(responseContent.mediaType);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [responseContent]);
+
+  const descriptionChanged = nodeHasChanged?.({ nodeId: response.id, attr: 'description' });
+
+  const getMaskProperties = (): Array<{ path: string; required?: boolean }> => {
+    if (!disableProps || !statusCode) return [];
+    const configEntries = disableProps[statusCode] || [];
+    const absolutePathsToHide: Array<{ path: string; required?: boolean }> = [];
+    configEntries.forEach(({ location, paths, isComplex }) => {
+      if (paths.length === 0 && !isComplex) {
+        absolutePathsToHide.push({ path: location });
+      } else {
+        paths.forEach((item: any) => {
+          const fullPath = location === '#' ? item?.path : `${location}/${item.path}`;
+          let object: any = { path: fullPath };
+          if (item.hasOwnProperty('required')) {
+            object = { ...object, required: item?.required };
+          }
+          absolutePathsToHide.push(object);
+        });
+      }
+    });
+    return absolutePathsToHide;
+  };
+
+  const shouldUseLazySchema = (statusCode && disableProps?.[statusCode]?.some(entry => entry.isComplex)) ?? false;
+
+  return (
+    <VStack spacing={8} pt={8}>
+      {description && (
+        <Box pos="relative">
+          <MarkdownViewer markdown={description} />
+          <NodeAnnotation change={descriptionChanged} />
+        </Box>
+      )}
+
+      {headers.length > 0 && (
+        <VStack spacing={5}>
+          <SectionSubtitle title="Headers" id="response-headers" />
+          <Parameters parameterType="header" parameters={headers} />
+        </VStack>
+      )}
+
+      {contents.length > 0 && (
+        <>
+          <SectionSubtitle title="Body" id="response-body">
+            <Flex flex={1} justify="end">
+              <Select
+                aria-label="Response Body Content Type"
+                value={String(chosenContent)}
+                onChange={value => setChosenContent(parseInt(String(value), 10))}
+                options={contents.map((content, index) => ({ label: content.mediaType, value: index }))}
+                size="sm"
+              />
+            </Flex>
+          </SectionSubtitle>
+          {schema && shouldUseLazySchema ? (
+            <LazySchemaTreePreviewer
+              schema={schema}
+              path=""
+              hideData={getMaskProperties()}
+              complexData={disableProps && statusCode ? disableProps[statusCode] : []}
+            />
+          ) : (
+            <JsonSchemaViewer
+              schema={getOriginalObject(schema)}
+              resolveRef={refResolver}
+              maxRefDepth={maxRefDepth}
+              viewMode="read"
+              parentCrumbs={['responses', response.code]}
+              renderRootTreeLines
+              nodeHasChanged={nodeHasChanged}
+              renderExtensionAddon={renderExtensionAddon}
+            />
+          )}
+        </>
+      )}
+    </VStack>
+  );
+};
+Response.displayName = 'HttpOperation.Response';
+
+const codeToIntentVal = (code: string): IntentVals => {
+  //Implement check here for invalid codes to avoid issues related to charAt() function
+  if (typeof code !== 'string' || code.trim() === '') {
+    return 'default';
+  }
+  const firstChar = code.charAt(0);
+
+  switch (firstChar) {
+    case '2':
+      return 'success';
+    case '4':
+      return 'warning';
+    case '5':
+      return 'danger';
+    default:
+      return 'default';
+  }
+};

package/src/components/Docs/HttpOperation/index.ts

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