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

package/src/components/Docs/Docs.tsx

@@ -0,0 +1,272 @@
+import { SchemaNode } from '@stoplight/json-schema-tree';
+import type { NodeHasChangedFn, NodeType } from '@stoplight/types';
+import { Location } from 'history';
+import * as React from 'react';
+
+import { InlineRefResolverProvider } from '../../context/InlineRefResolver';
+import { ElementsOptionsProvider } from '../../context/Options';
+import { useParsedData } from '../../hooks/useParsedData';
+import { ParsedNode } from '../../types';
+import { ReferenceResolver } from '../../utils/ref-resolving/ReferenceResolver';
+import { Article } from './Article';
+import { HttpOperation } from './HttpOperation';
+import { HttpService } from './HttpService';
+import { ExportButtonProps } from './HttpService/ExportButton';
+import { Model } from './Model';
+
+type NodeUnsupportedFn = (err: 'dataEmpty' | 'invalidType' | Error) => void;
+
+export type VendorExtensionsData = Record<string, unknown>;
+
+/**
+ * A set of props that are passed to the extension renderer
+ */
+export type ExtensionRowProps = {
+  schemaNode: SchemaNode;
+  nestingLevel: number;
+  vendorExtensions: VendorExtensionsData;
+};
+
+/**
+ * Renderer function for rendering an vendor extension
+ */
+export type ExtensionAddonRenderer = (props: ExtensionRowProps) => React.ReactNode;
+
+interface BaseDocsProps {
+  /**
+   * CSS class to add to the root container.
+   */
+  className?: string;
+
+  /**
+   * URI of the document
+   */
+  uri?: string;
+
+  /**
+   * Some components may depend on some location/URL data.
+   */
+  location?: Location;
+
+  /**
+   * The original title of the node. It serves as a fallback title in case on is not available inside the model.
+   */
+  nodeTitle?: string;
+
+  /**
+   * @deprecated this property is no longer used and will be removed in the next major version
+   */
+  allowRouting?: boolean;
+
+  /**
+   * Export button props
+   */
+  exportProps?: ExportButtonProps;
+
+  /**
+   * 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;
+
+  /**
+   * Allows to customize the layout of Docs
+   */
+  layoutOptions?: {
+    /**
+     * Allows to hide TryIt component
+     * @default false
+     */
+    hideTryIt?: boolean;
+    /**
+     * Allows to hide RequestSamples component
+     * @default false
+     */
+    hideSamples?: boolean;
+    /**
+     * Shows only operation document without right column
+     * @default false
+     */
+    hideTryItPanel?: boolean;
+    /**
+     * If true, the component will hide its title
+     * @default false
+     */
+    noHeading?: boolean;
+    /**
+     * If true, the component will hide the Powered by Stoplight banner in Docs
+     * @default false
+     */
+    showPoweredByLink?: boolean;
+    /**
+     * Allows to hide model examples
+     * @default false
+     */
+    hideModelExamples?: boolean;
+    /**
+     * Allows to hide server information
+     * @default false
+     */
+    hideServerInfo?: boolean;
+    /**
+     * Allows to hide security information
+     * @default false
+     */
+    hideSecurityInfo?: boolean;
+
+    /**
+     * Allows to hide export button
+     * @default false
+     */
+    hideExport?: boolean;
+
+    /**
+     * Provide a number to trigger compact mode when the component is within that pixel width,
+     * or a boolean to enable or diable compact mode.
+     * @default false
+     * @example 600
+     */
+    compact?: number | boolean;
+  };
+
+  nodeHasChanged?: NodeHasChangedFn<React.ReactNode>;
+
+  /**
+   * Allows consumers to know when the node is not supported.
+   *
+   * @type {NodeUnsupportedFn}
+   * @default undefined
+   */
+  nodeUnsupported?: NodeUnsupportedFn;
+
+  /**
+   * Allows to define renderers for vendor extensions
+   * @type {ExtensionAddonRenderer}
+   * @default undefined
+   */
+  renderExtensionAddon?: ExtensionAddonRenderer;
+}
+
+export interface DocsProps extends BaseDocsProps {
+  nodeType: NodeType;
+  nodeData: unknown;
+  useNodeForRefResolving?: boolean;
+  refResolver?: ReferenceResolver;
+  maxRefDepth?: number;
+  disableProps?: any;
+}
+
+export interface DocsComponentProps<T = unknown> extends BaseDocsProps {
+  /**
+   * The input data for the component to display.
+   */
+  data: T;
+  disableProps?: any;
+}
+
+type DisablePropItem = {
+  location: string;
+  paths: string;
+  isComplex: boolean;
+};
+
+type DisableProps =
+  | {
+      request?: DisablePropItem[];
+      response?: Record<string, DisablePropItem[]>;
+      models?: DisablePropItem[];
+    }
+  | null
+  | undefined;
+
+type TryItVisibility = {
+  hideOperationTryIt: boolean;
+  hideModelTryIt: boolean;
+};
+
+export const Docs = React.memo<DocsProps>(
+  ({
+    nodeType,
+    nodeData,
+    disableProps,
+    useNodeForRefResolving = false,
+    refResolver,
+    maxRefDepth,
+    nodeHasChanged,
+    renderExtensionAddon,
+    ...commonProps
+  }) => {
+    const parsedNode = useParsedData(nodeType, nodeData);
+
+    if (!parsedNode) {
+      commonProps.nodeUnsupported?.('dataEmpty');
+      return null;
+    }
+
+    let elem = <ParsedDocs node={parsedNode} disableProps={disableProps} {...commonProps} />;
+
+    if (useNodeForRefResolving) {
+      elem = (
+        <InlineRefResolverProvider document={parsedNode.data} resolver={refResolver} maxRefDepth={maxRefDepth}>
+          {elem}
+        </InlineRefResolverProvider>
+      );
+    }
+
+    return (
+      <ElementsOptionsProvider nodeHasChanged={nodeHasChanged} renderExtensionAddon={renderExtensionAddon}>
+        {elem}
+      </ElementsOptionsProvider>
+    );
+  },
+);
+
+export interface ParsedDocsProps extends BaseDocsProps {
+  node: ParsedNode;
+  disableProps?: DisableProps;
+}
+
+const getTryItVisibility = (disableProps: DisableProps): TryItVisibility => {
+  if (!disableProps) return { hideOperationTryIt: false, hideModelTryIt: false };
+
+  const requestHasComplex = disableProps.request?.some(item => item.isComplex) ?? false;
+
+  const responseHasComplex = Object.values(disableProps.response || {}).some(arr => arr.some(item => item.isComplex));
+
+  const hideOperationTryIt = requestHasComplex || responseHasComplex;
+
+  const hideModelTryIt = disableProps.models?.some(item => item.isComplex) ?? false;
+
+  return { hideOperationTryIt, hideModelTryIt };
+};
+
+export const ParsedDocs = ({ node, nodeUnsupported, disableProps, ...commonProps }: ParsedDocsProps) => {
+  const { hideOperationTryIt, hideModelTryIt } = getTryItVisibility(disableProps);
+
+  switch (node.type) {
+    case 'article':
+      return <Article data={node.data} {...commonProps} />;
+    case 'http_operation':
+    case 'http_webhook':
+      return <HttpOperation data={node.data} disableProps={{ ...disableProps, hideOperationTryIt }} {...commonProps} />;
+
+    case 'http_service':
+      return <HttpService data={node.data} {...commonProps} />;
+    case 'model':
+      return <Model data={node.data} disableProps={{ ...disableProps, hideModelTryIt }} {...commonProps} />;
+    default:
+      nodeUnsupported?.('invalidType');
+      return null;
+  }
+};
+
+export { DocsSkeleton } from './Skeleton';

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

@@ -0,0 +1,49 @@
+import { faEye } from '@fortawesome/free-solid-svg-icons';
+import { Badge, Tooltip } from '@stoplight/mosaic';
+import React from 'react';
+
+import { badgeDefaultBackgroundColor, badgeDefaultColor } from '../../../constants';
+
+export const DeprecatedBadge: React.FC = () => (
+  <Tooltip
+    renderTrigger={
+      <Badge intent="warning" icon={['fas', 'exclamation-circle']} data-testid="badge-deprecated">
+        Deprecated
+      </Badge>
+    }
+  >
+    This operation has been marked as deprecated, which means it could be removed at some point in the future.
+  </Tooltip>
+);
+
+export const InternalBadge: React.FC<{ isHttpService?: boolean }> = ({ isHttpService }) => (
+  <Tooltip
+    renderTrigger={
+      <Badge icon={faEye} data-testid="badge-internal" bg="danger">
+        Internal
+      </Badge>
+    }
+  >
+    {`This ${isHttpService ? 'operation' : 'model'} is marked as internal and won't be visible in public docs.`}
+  </Tooltip>
+);
+
+export const VersionBadge: React.FC<{ value: string; backgroundColor?: string }> = ({ value, backgroundColor }) => (
+  <Badge
+    appearance="solid"
+    size="sm"
+    border={0}
+    style={{
+      backgroundColor: backgroundColor || badgeDefaultBackgroundColor,
+      color: badgeDefaultColor,
+    }}
+  >
+    {enhanceVersionString(value)}
+  </Badge>
+);
+
+const enhanceVersionString = (version: string): string => {
+  if (version[0] === 'v') return version;
+
+  return `v${version}`;
+};

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

@@ -0,0 +1,115 @@
+import { JsonSchemaViewer } from '@stoplight/json-schema-viewer';
+import { Box, Flex, NodeAnnotation, Select, VStack } from '@stoplight/mosaic';
+import { IHttpOperationRequestBody } from '@stoplight/types';
+import * as React from 'react';
+
+import { useSchemaInlineRefResolver } from '../../../context/InlineRefResolver';
+import { useOptionsCtx } from '../../../context/Options';
+import { isJSONSchema } from '../../../utils/guards';
+import { getOriginalObject } from '../../../utils/ref-resolving/resolvedObject';
+import { MarkdownViewer } from '../../MarkdownViewer';
+import { SectionSubtitle } from '../Sections';
+import LazySchemaTreePreviewer from './LazySchemaTreePreviewer';
+
+export interface BodyProps {
+  body: IHttpOperationRequestBody;
+  onChange?: (requestBodyIndex: number) => void;
+  isHttpWebhookOperation?: boolean;
+  disableProps?: Array<{
+    location: string;
+    paths: Array<{ path: string; required?: boolean }>;
+    isComplex?: boolean;
+  }>;
+}
+
+export const isBodyEmpty = (body?: BodyProps['body']) => {
+  if (!body) return true;
+
+  const { contents = [], description } = body;
+
+  return contents.length === 0 && !description?.trim();
+};
+
+export const Body = ({ body, onChange, isHttpWebhookOperation = false, disableProps }: BodyProps) => {
+  const [refResolver, maxRefDepth] = useSchemaInlineRefResolver();
+  const [chosenContent, setChosenContent] = React.useState(0);
+  const { nodeHasChanged, renderExtensionAddon } = useOptionsCtx();
+
+  React.useEffect(() => {
+    onChange?.(chosenContent);
+    // disabling because we don't want to react on `onChange` change
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [chosenContent]);
+
+  if (isBodyEmpty(body)) return null;
+
+  const { contents = [], description } = body;
+  const schema = contents[chosenContent]?.schema;
+  const descriptionChanged = nodeHasChanged?.({ nodeId: body.id, attr: 'description' });
+
+  /* Get Masked Properties And Pass to LazySchemaTreePreviewer */
+  const getMaskProperties = (): Array<{ path: string; required?: boolean }> => {
+    const disablePropsConfig = disableProps || [];
+    const absolutePathsToHide: Array<{ path: string; required?: boolean }> = [];
+    disablePropsConfig.forEach(configEntry => {
+      const { location, paths, isComplex } = configEntry;
+      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 = disableProps?.some(entry => entry.isComplex === true);
+
+  console.log('!!!!! shouldUseLazySchema body!!!!', shouldUseLazySchema);
+
+  return (
+    <VStack spacing={6}>
+      <SectionSubtitle title="Body" id="request-body">
+        {contents.length > 0 && (
+          <Flex flex={1} justify="end">
+            <Select
+              aria-label="Request 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>
+      {description && (
+        <Box pos="relative">
+          <MarkdownViewer markdown={description} />
+          <NodeAnnotation change={descriptionChanged} />
+        </Box>
+      )}
+      {schema && shouldUseLazySchema ? (
+        <LazySchemaTreePreviewer schema={schema} hideData={getMaskProperties()} complexData={disableProps} />
+      ) : (
+        isJSONSchema(schema) && (
+          <JsonSchemaViewer
+            resolveRef={refResolver}
+            maxRefDepth={maxRefDepth}
+            schema={getOriginalObject(schema)}
+            viewMode={isHttpWebhookOperation ? 'standalone' : 'write'}
+            renderRootTreeLines
+            nodeHasChanged={nodeHasChanged}
+            renderExtensionAddon={renderExtensionAddon}
+          />
+        )
+      )}
+    </VStack>
+  );
+};
+Body.displayName = 'HttpOperation.Body';

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

@@ -0,0 +1,89 @@
+import { Box, Flex, NodeAnnotation, Select, VStack } from '@stoplight/mosaic';
+import { IHttpCallbackOperation } from '@stoplight/types';
+import * as React from 'react';
+
+import { useOptionsCtx } from '../../../context/Options';
+import { MarkdownViewer } from '../../MarkdownViewer';
+import { ExtensionAddonRenderer } from '../Docs';
+import { SectionSubtitle, SectionTitle } from '../Sections';
+import { OperationHeader } from './HttpOperation';
+import { Request } from './Request';
+import { Responses } from './Responses';
+
+export interface CallbacksProps {
+  callbacks: IHttpCallbackOperation[];
+  isCompact?: boolean;
+}
+
+export interface CallbackProps {
+  data: IHttpCallbackOperation;
+  isCompact?: boolean;
+  renderExtensionAddon?: ExtensionAddonRenderer;
+}
+
+export const Callbacks = ({ callbacks, isCompact }: CallbacksProps) => {
+  const [selectedCallbackIndex, setSelectedCallbackIndex] = React.useState(0);
+
+  const callback = React.useMemo(() => callbacks[selectedCallbackIndex], [callbacks, selectedCallbackIndex]);
+
+  return (
+    <VStack spacing={8}>
+      <SectionTitle title="Callbacks" isCompact={isCompact}>
+        {callbacks.length > 0 && (
+          <Flex flex={1} justify="end">
+            <Select
+              aria-label="Callback"
+              value={String(selectedCallbackIndex)}
+              onChange={value => setSelectedCallbackIndex(parseInt(String(value), 10))}
+              options={callbacks.map((c, index) => ({
+                label: `${c.key} - ${c.path} - ${c.method}`,
+                value: index,
+              }))}
+              size="sm"
+            />
+          </Flex>
+        )}
+      </SectionTitle>
+
+      {callback && <Callback data={callback} isCompact={isCompact} />}
+    </VStack>
+  );
+};
+
+Callbacks.displayName = 'HttpOperation.Callbacks';
+
+export const Callback = ({ data, isCompact }: CallbackProps) => {
+  const { nodeHasChanged } = useOptionsCtx();
+
+  const isDeprecated = !!data.deprecated;
+  const isInternal = !!data.internal;
+
+  const descriptionChanged = nodeHasChanged?.({ nodeId: data.id, attr: 'description' });
+
+  return (
+    <VStack spacing={10}>
+      <Box>
+        <SectionSubtitle title={data.key} id="callback-key"></SectionSubtitle>
+        <OperationHeader
+          id={data.id}
+          method={data.method}
+          path={data.path}
+          isDeprecated={isDeprecated}
+          isInternal={isInternal}
+          hideServerUrl
+        />
+      </Box>
+      {data.description && (
+        <Box pos="relative">
+          <MarkdownViewer className="HttpOperation__Description" markdown={data.description} />
+          <NodeAnnotation change={descriptionChanged} />
+        </Box>
+      )}
+
+      <Request operation={data} />
+
+      {data.responses && <Responses responses={data.responses} isCompact={isCompact} />}
+    </VStack>
+  );
+};
+Callbacks.displayName = 'HttpOperation.Callback';