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

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

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

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

@@ -0,0 +1,255 @@
+import {
+  Box,
+  Flex,
+  Heading,
+  HStack,
+  IBackgroundColorProps,
+  NodeAnnotation,
+  useThemeIsDark,
+  VStack,
+} from '@stoplight/mosaic';
+import { withErrorBoundary } from '@stoplight/react-error-boundary';
+import { HttpMethod, IHttpEndpointOperation, IHttpOperation } from '@stoplight/types';
+import cn from 'classnames';
+import { useAtomValue } from 'jotai/utils';
+import * as React from 'react';
+
+import { HttpMethodColors } from '../../../constants';
+import { MockingContext } from '../../../containers/MockingProvider';
+import { useResolvedObject } from '../../../context/InlineRefResolver';
+import { useOptionsCtx } from '../../../context/Options';
+import { useIsCompact } from '../../../hooks/useIsCompact';
+import { isHttpOperation, isHttpWebhookOperation } from '../../../utils/guards';
+import { MarkdownViewer } from '../../MarkdownViewer';
+import { chosenServerAtom, TryItWithRequestSamples } from '../../TryIt';
+import { DocsComponentProps } from '..';
+import { NodeVendorExtensions } from '../NodeVendorExtensions';
+import { TwoColumnLayout } from '../TwoColumnLayout';
+import { DeprecatedBadge, InternalBadge } from './Badges';
+import { Callbacks } from './Callbacks';
+import { Request } from './Request';
+import { Responses } from './Responses';
+
+export type HttpOperationProps = DocsComponentProps<IHttpEndpointOperation>;
+
+const HttpOperationComponent = React.memo<HttpOperationProps>(
+  ({ className, data: unresolvedData, layoutOptions, tryItCredentialsPolicy, tryItCorsProxy }) => {
+    const { nodeHasChanged } = useOptionsCtx();
+    const data = useResolvedObject(unresolvedData) as IHttpEndpointOperation;
+    const { ref: layoutRef, isCompact } = useIsCompact(layoutOptions);
+
+    const mocking = React.useContext(MockingContext);
+    const isDeprecated = !!data.deprecated;
+    const isInternal = !!data.internal;
+
+    const [responseMediaType, setResponseMediaType] = React.useState('');
+    const [responseStatusCode, setResponseStatusCode] = React.useState('');
+    const [requestBodyIndex, setTextRequestBodyIndex] = React.useState(0);
+
+    const prettyName = (data.summary || data.iid || '').trim();
+    const hasBadges = isDeprecated || isInternal;
+
+    let path: string;
+    if (isHttpOperation(data)) {
+      path = data.path;
+    } else if (isHttpWebhookOperation(data)) {
+      path = data.name;
+    } else {
+      throw new RangeError('unsupported node type');
+    }
+
+    const header = (
+      <OperationHeader
+        id={data.id}
+        method={data.method}
+        path={path}
+        noHeading={layoutOptions?.noHeading}
+        hasBadges={hasBadges}
+        name={prettyName}
+        isDeprecated={isDeprecated}
+        isInternal={isInternal}
+        hideServerUrl={!isHttpOperation(data)}
+      />
+    );
+
+    const tryItPanel = !layoutOptions?.hideTryItPanel && (
+      <TryItWithRequestSamples
+        httpOperation={data}
+        responseMediaType={responseMediaType}
+        responseStatusCode={responseStatusCode}
+        requestBodyIndex={requestBodyIndex}
+        hideTryIt={layoutOptions?.hideTryIt}
+        hideTryItPanel={layoutOptions?.hideTryItPanel}
+        hideSamples={layoutOptions?.hideSamples}
+        tryItCredentialsPolicy={tryItCredentialsPolicy}
+        mockUrl={mocking.hideMocking ? undefined : mocking.mockUrl}
+        corsProxy={tryItCorsProxy}
+      />
+    );
+
+    const descriptionChanged = nodeHasChanged?.({ nodeId: data.id, attr: 'description' });
+    const description = (
+      <VStack spacing={10}>
+        {data.description && (
+          <Box pos="relative">
+            <MarkdownViewer className="HttpOperation__Description" markdown={data.description} />
+            <NodeAnnotation change={descriptionChanged} />
+          </Box>
+        )}
+        <NodeVendorExtensions data={data} />
+        <Request
+          onChange={setTextRequestBodyIndex}
+          operation={data}
+          hideSecurityInfo={layoutOptions?.hideSecurityInfo}
+          isHttpWebhookOperation={isHttpWebhookOperation(data)}
+        />
+        {data.responses && (
+          <Responses
+            responses={data.responses}
+            onMediaTypeChange={setResponseMediaType}
+            onStatusCodeChange={setResponseStatusCode}
+            isCompact={isCompact}
+          />
+        )}
+        {data.callbacks?.length ? <Callbacks callbacks={data.callbacks} isCompact={isCompact} /> : null}
+        {isCompact && tryItPanel}
+      </VStack>
+    );
+
+    return (
+      <TwoColumnLayout
+        ref={layoutRef}
+        className={cn('HttpOperation', className)}
+        header={header}
+        left={description}
+        right={!isCompact && tryItPanel}
+      />
+    );
+  },
+);
+HttpOperationComponent.displayName = 'HttpOperation.Component';
+
+export const HttpOperation = withErrorBoundary<HttpOperationProps>(HttpOperationComponent, {
+  recoverableProps: ['data'],
+});
+
+type MethodPathProps = { method: IHttpOperation['method']; path: string; hideServerUrl?: boolean };
+
+function MethodPath({ method, path, hideServerUrl }: MethodPathProps) {
+  const chosenServer = useAtomValue(chosenServerAtom);
+
+  let chosenServerUrl = '';
+  if (chosenServer) {
+    chosenServerUrl = chosenServer.url.endsWith('/') ? chosenServer.url.slice(0, -1) : chosenServer.url;
+  }
+
+  return (
+    <Box>
+      <MethodPathInner method={method} path={path} chosenServerUrl={hideServerUrl ? '' : chosenServerUrl} />
+    </Box>
+  );
+}
+
+function MethodPathInner({ method, path, chosenServerUrl }: MethodPathProps & { chosenServerUrl: string }) {
+  const isDark = useThemeIsDark();
+  const fullUrl = `${chosenServerUrl}${path}`;
+
+  const pathElem = (
+    <Flex overflowX="hidden" fontSize="lg" userSelect="all">
+      <Box dir="ltr" textOverflow="truncate" overflowX="hidden">
+        <Box as="span" dir="ltr" color="muted" style={{ unicodeBidi: 'bidi-override' }}>
+          {chosenServerUrl}
+        </Box>
+        <Box as="span" fontWeight="semibold" flex={1}>
+          {path}
+        </Box>
+      </Box>
+    </Flex>
+  );
+
+  return (
+    <HStack
+      spacing={3}
+      pl={2.5}
+      pr={4}
+      py={2}
+      bg="canvas-50"
+      rounded="lg"
+      fontFamily="mono"
+      display="inline-flex"
+      maxW="full"
+      title={fullUrl}
+    >
+      <Box
+        py={1}
+        px={2.5}
+        rounded="lg"
+        bg={!isDark ? (HttpMethodColors[method as HttpMethod] as IBackgroundColorProps['bg']) : 'canvas-100'}
+        color={!isDark ? 'on-primary' : 'body'}
+        fontSize="lg"
+        fontWeight="semibold"
+        textTransform="uppercase"
+      >
+        {method}
+      </Box>
+
+      {pathElem}
+    </HStack>
+  );
+}
+
+export function OperationHeader({
+  id,
+  noHeading,
+  hasBadges,
+  name,
+  isDeprecated,
+  isInternal,
+  hideServerUrl,
+  method,
+  path,
+}: {
+  id: string;
+  noHeading?: boolean;
+  hasBadges?: boolean;
+  name?: string;
+  isDeprecated?: boolean;
+  isInternal?: boolean;
+  hideServerUrl?: boolean;
+  method: string;
+  path: string;
+}) {
+  const { nodeHasChanged } = useOptionsCtx();
+
+  if (noHeading && !hasBadges) {
+    return null;
+  }
+
+  const lineOneChanged = nodeHasChanged?.({ nodeId: id, attr: ['iid', 'summary', 'deprecated', 'internal'] });
+  const lineTwoChanged = nodeHasChanged?.({ nodeId: id, attr: ['method', 'path'] });
+
+  return (
+    <VStack spacing={5}>
+      <Box pos="relative">
+        <HStack spacing={5}>
+          {!noHeading && name ? (
+            <Heading size={1} fontWeight="semibold">
+              {name}
+            </Heading>
+          ) : null}
+
+          <HStack spacing={2}>
+            {isDeprecated && <DeprecatedBadge />}
+            {isInternal && <InternalBadge isHttpService />}
+          </HStack>
+        </HStack>
+        <NodeAnnotation change={lineOneChanged} />
+      </Box>
+
+      <Box pos="relative">
+        <MethodPath method={method} path={path} hideServerUrl={hideServerUrl} />
+        <NodeAnnotation change={lineTwoChanged} />
+      </Box>
+    </VStack>
+  );
+}

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,140 @@
+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;
+}
+
+export const Request: React.FunctionComponent<IRequestProps> = ({
+  operation: {
+    request,
+    request: {
+      path: pathParams = [],
+      headers: headerParams = [],
+      cookie: cookieParams = [],
+      body,
+      query: queryParams = [],
+    } = {},
+    security,
+  },
+  hideSecurityInfo,
+  onChange,
+  isHttpWebhookOperation = false,
+}) => {
+  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} />}
+    </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>;
+};