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

package/src/types.ts

@@ -0,0 +1,170 @@
+import type { IMarkdownViewerProps } from '@stoplight/markdown-viewer';
+import { IHttpOperation, IHttpService, IHttpWebhookOperation, NodeType } from '@stoplight/types';
+import { JSONSchema4, JSONSchema6, JSONSchema7 } from 'json-schema';
+
+export type JSONSchema = JSONSchema4 | JSONSchema6 | JSONSchema7;
+
+export type ParsedNode =
+  | {
+      type: NodeType.Article;
+      data: IMarkdownViewerProps['markdown'];
+    }
+  | {
+      type: NodeType.HttpOperation;
+      data: IHttpOperation;
+    }
+  | {
+      type: NodeType.HttpWebhook;
+      data: IHttpWebhookOperation;
+    }
+  | {
+      type: NodeType.HttpService;
+      data: IHttpService;
+    }
+  | {
+      type: NodeType.Model;
+      data: JSONSchema7;
+    }
+  | {
+      type: NodeType.HttpServer;
+      data: unknown;
+    }
+  | {
+      type: NodeType.Unknown;
+      data: unknown;
+    }
+  | {
+      type: NodeType.TableOfContents;
+      data: unknown;
+    }
+  | {
+      type: NodeType.Generic;
+      data: unknown;
+    };
+
+export interface INodeFilter {
+  nodeUri?: string;
+  nodeType?: string;
+}
+
+export interface IBranchNode {
+  id: number;
+  version?: string;
+  isLatestVersion?: boolean;
+
+  node: {
+    id: number;
+    uri: string;
+  };
+
+  snapshot: {
+    id: number;
+    type: string;
+    name: string;
+    summary?: string | null;
+    data?: unknown;
+    tagNames?: string[];
+  };
+}
+
+export enum IntegrationKind {
+  AzureDevopsServer = 'azure_devops_server',
+  BitbucketCloud = 'bitbucket_cloud',
+  BitbucketServer = 'bitbucket_server',
+  Builtin = 'builtin',
+  Gitea = 'gitea',
+  Github = 'github',
+  Gitlab = 'gitlab',
+  Ldap = 'ldap',
+  Saml = 'saml',
+}
+
+export type BundledBranchNode = {
+  id: number;
+  data: string;
+  type: NodeType;
+  name: string;
+  uri: string;
+  summary: string;
+  branchSlug: string;
+  workspaceIntegration: {
+    kind: IntegrationKind;
+    apiUrl: string;
+    hostUrl: string;
+  };
+  externalOrgSlug: string;
+  externalSlug: string;
+};
+
+export interface ITableOfContentsTree {
+  items: TableOfContentItem[];
+}
+
+export type TableOfContentItem = Divider | Group | Item;
+
+export type Divider = {
+  title: string;
+  type: 'divider';
+};
+
+export type Group = {
+  title: string;
+  type: 'group';
+  items: TableOfContentItem[];
+  uri?: string;
+};
+
+export type Item = {
+  title: string;
+  type: 'item';
+  uri: string;
+};
+
+export type RouterType = 'history' | 'memory' | 'hash' | 'static';
+
+export interface RoutingProps {
+  /**
+   * Only applies when using `history`-based routing. (See the `router` prop.) Specifies the base path under which
+   * all API component controlled pages are located. The host must route any location under this path to the API component.
+   */
+  basePath?: string;
+
+  /**
+   * Only applies when using `static`-based routing. (See the `router` prop.) Specifies the current static path
+   * that is being rendered by the StaticRouter, which allows us to properly render the currently active route
+   * on the server and already render the content instead of sending an empty page to the client.
+   */
+  staticRouterPath?: string;
+
+  /**
+   * Which routing solution to use when the user navigates using the table of contents.
+   * Only applies when using the *sidebar* layout.
+   *
+   * - **`history`** - The table of contents pushes entries onto the navigation stack, e.g. `location.pushState`.
+   *   This requires that the host routes any location under `basePath` (see `basePath` prop) to the API component.
+   * - **`hash`** - Navigation happens using hash-fragments (`/some/page#these-fragments-here`).
+   *   This still allows the user to link to individual pages without requiring the more complex routing setup `history` needs.
+   * - **`memory`** - Internal navigation does not change the host `location` at all.
+   *   This works in every scenario, but it lacks the important feature of being able to link to individual pages.
+   * - **`static`** - Renders a single static page for the provided `staticRouterPath`.
+   *   This can be used when the page is being rendered on the server (either SSR or SSG) to pre-generate the
+   *   markup of the page, which can be rehydrated on the client. This can reduce the amount of time spent rendering
+   *   the page on the client.
+   *
+   *   @default "history"
+   */
+  router?: RouterType;
+}
+
+export type ParamField = {
+  name: string;
+  description: string;
+  example: string;
+};
+
+export type LogoProps = {
+  altText: string;
+  url?: string;
+  backgroundColor?: string;
+  href?: string;
+};

package/src/utils/__tests__/securitySchemes.spec.ts

@@ -0,0 +1,137 @@
+import {
+  IOauth2AuthorizationCodeFlow,
+  IOauth2ClientCredentialsFlow,
+  IOauth2ImplicitFlow,
+  IOauth2PasswordFlow,
+} from '@stoplight/types';
+
+import { getDefaultDescription } from '../securitySchemes';
+
+describe('getDefaultDescription()', () => {
+  it('should handle implicit flow', () => {
+    const flow: IOauth2ImplicitFlow = {
+      authorizationUrl: 'http://authorizationURL',
+      scopes: { 'scope:implicit': 'implicit scope description', 'scope:read': 'read scope description' },
+    };
+
+    const description = getDefaultDescription({
+      id: 'http-security-oauth2-implicit',
+      key: 'oauth2-implicit',
+      type: 'oauth2',
+      flows: { implicit: flow },
+    });
+
+    expect(description).toMatchInlineSnapshot(`
+      "**Implicit OAuth Flow**
+
+      Authorize URL: http://authorizationURL
+
+      Scopes:
+      - \`scope:implicit\` - implicit scope description
+      - \`scope:read\` - read scope description"
+    `);
+  });
+
+  it('should handle authorization code flow', () => {
+    const flow: IOauth2AuthorizationCodeFlow = {
+      authorizationUrl: 'http://authorizationURL',
+      tokenUrl: 'http://tokenURL',
+      refreshUrl: 'http://refreshURL',
+      scopes: { 'scope:authorizationCode': 'authorizationCode scope description' },
+    };
+
+    const description = getDefaultDescription({
+      id: 'http-security-oauth2-authorizationCode',
+      key: 'oauth2-authorizationCode',
+      type: 'oauth2',
+      flows: { authorizationCode: flow },
+    });
+
+    expect(description).toMatchInlineSnapshot(`
+      "**Authorization Code OAuth Flow**
+
+      Authorize URL: http://authorizationURL
+
+      Token URL: http://tokenURL
+
+      Refresh URL: http://refreshURL
+
+      Scopes:
+      - \`scope:authorizationCode\` - authorizationCode scope description"
+    `);
+  });
+
+  it('should handle client credentials flow', () => {
+    const flow: IOauth2ClientCredentialsFlow = {
+      tokenUrl: 'http://tokenURL',
+      scopes: { 'scope:clientCredentials': 'clientCredentials scope description' },
+    };
+
+    const description = getDefaultDescription({
+      id: 'http-security-oauth2-clientCredentials',
+      key: 'oauth2-clientCredentials',
+      type: 'oauth2',
+      flows: { clientCredentials: flow },
+    });
+
+    expect(description).toMatchInlineSnapshot(`
+      "**Client Credentials OAuth Flow**
+
+      Token URL: http://tokenURL
+
+      Scopes:
+      - \`scope:clientCredentials\` - clientCredentials scope description"
+    `);
+  });
+
+  it('should handle password flow', () => {
+    const flow: IOauth2PasswordFlow = {
+      tokenUrl: 'http://tokenURL',
+      scopes: { 'scope:password': 'password scope description' },
+    };
+
+    const description = getDefaultDescription({
+      id: 'http-security-oauth2-password',
+      key: 'oauth2-password',
+      type: 'oauth2',
+      flows: { password: flow },
+    });
+
+    expect(description).toMatchInlineSnapshot(`
+      "**Password OAuth Flow**
+
+      Token URL: http://tokenURL
+
+      Scopes:
+      - \`scope:password\` - password scope description"
+    `);
+  });
+
+  it('should handle api key flow with roles', () => {
+    const description = getDefaultDescription({
+      id: 'security-apikey-access-token',
+      key: 'apikey-access-token',
+      type: 'apiKey',
+      name: 'access_token',
+      in: 'query',
+      extensions: { ['x-scopes']: ['image:read', 'user:read'] },
+    });
+
+    expect(description).toContain('Roles: `image:read`, `user:read`');
+  });
+
+  it.each<'bearer' | 'basic' | 'digest'>(['bearer', 'basic', 'digest'])(
+    'should handle http %s flow with roles',
+    scheme => {
+      const description = getDefaultDescription({
+        id: 'security-http-access-token',
+        key: 'http-access-token',
+        type: 'http',
+        scheme,
+        extensions: { ['x-scopes']: ['image:read', 'user:read'] },
+      });
+
+      expect(description).toContain('Roles: `image:read`, `user:read`');
+    },
+  );
+});

package/src/utils/exampleGeneration/exampleGeneration.spec.tsx

@@ -0,0 +1,18 @@
+import * as Sampler from '@stoplight/json-schema-sampler';
+import { JSONSchema7 } from 'json-schema';
+
+import { generateExamplesFromJsonSchema } from './exampleGeneration';
+
+const modelWithNoExamples: JSONSchema7 = require('../../__fixtures__/models/model-with-no-examples.json');
+
+describe('generateExamplesFromJsonSchema', () => {
+  it('returns error message when example generation fails ', () => {
+    const errorMessage = 'This is a mocked Error message';
+    jest.spyOn(Sampler, 'sample').mockImplementation(() => {
+      throw Error(errorMessage);
+    });
+
+    const example = generateExamplesFromJsonSchema(modelWithNoExamples);
+    expect(example).toEqual([{ label: '', data: `Example cannot be created for this schema\nError: ${errorMessage}` }]);
+  });
+});

package/src/utils/exampleGeneration/exampleGeneration.ts

@@ -0,0 +1,110 @@
+import { isPlainObject, safeStringify } from '@stoplight/json';
+import * as Sampler from '@stoplight/json-schema-sampler';
+import { IMediaTypeContent, INodeExample, INodeExternalExample } from '@stoplight/types';
+import { JSONSchema7 } from 'json-schema';
+import React from 'react';
+
+import { useDocument } from '../../context/InlineRefResolver';
+
+type Example = {
+  label: string;
+  data: string;
+};
+
+export type GenerateExampleFromMediaTypeContentOptions = Sampler.Options;
+
+export const useGenerateExampleFromMediaTypeContent = (
+  mediaTypeContent: IMediaTypeContent | undefined,
+  chosenExampleIndex?: number,
+  { skipReadOnly, skipWriteOnly, skipNonRequired, ticks }: GenerateExampleFromMediaTypeContentOptions = {},
+) => {
+  const document = useDocument();
+  return React.useMemo(
+    () =>
+      generateExampleFromMediaTypeContent(mediaTypeContent, document, chosenExampleIndex, {
+        skipNonRequired,
+        skipWriteOnly,
+        skipReadOnly,
+        ticks: ticks || 6000,
+      }),
+    [mediaTypeContent, document, chosenExampleIndex, skipNonRequired, skipWriteOnly, skipReadOnly, ticks],
+  );
+};
+
+export const generateExampleFromMediaTypeContent = (
+  mediaTypeContent: IMediaTypeContent | undefined,
+  document: any,
+  chosenExampleIndex = 0,
+  options?: GenerateExampleFromMediaTypeContentOptions,
+) => {
+  const textRequestBodySchema = mediaTypeContent?.schema;
+  const textRequestBodyExamples = mediaTypeContent?.examples;
+
+  try {
+    if (textRequestBodyExamples?.length) {
+      return (
+        safeStringify(
+          textRequestBodyExamples?.[chosenExampleIndex]['value' as keyof (INodeExample | INodeExternalExample)],
+          undefined,
+          2,
+        ) ?? ''
+      );
+    } else if (textRequestBodySchema) {
+      const generated = Sampler.sample(textRequestBodySchema, options, document);
+      return generated !== null ? safeStringify(generated, undefined, 2) ?? '' : '';
+    }
+  } catch (e) {
+    console.warn(e);
+    return `Example cannot be created for this schema\n${e}`;
+  }
+  return '';
+};
+
+export const generateExamplesFromJsonSchema = (schema: JSONSchema7 & { 'x-examples'?: unknown }): Example[] => {
+  const examples: Example[] = [];
+
+  if (Array.isArray(schema?.examples)) {
+    schema.examples.forEach((example, index) => {
+      examples.push({
+        data: safeStringify(example, undefined, 2) ?? '',
+        label: index === 0 ? 'default' : `example-${index}`,
+      });
+    });
+  } else if (isPlainObject(schema?.['x-examples'])) {
+    for (const [label, example] of Object.entries(schema['x-examples'])) {
+      if (isPlainObject(example)) {
+        const val = example.hasOwnProperty('value') && Object.keys(example).length === 1 ? example.value : example;
+        examples.push({
+          label,
+          data: safeStringify(val, undefined, 2) ?? '',
+        });
+      }
+    }
+  }
+
+  if (examples.length) {
+    return examples;
+  }
+
+  try {
+    const generated = Sampler.sample(schema, {
+      maxSampleDepth: 4,
+      ticks: 6000,
+    });
+
+    return generated !== null
+      ? [
+          {
+            label: 'default',
+            data: safeStringify(generated, undefined, 2) ?? '',
+          },
+        ]
+      : [{ label: 'default', data: '' }];
+  } catch (e) {
+    return [{ label: '', data: `Example cannot be created for this schema\n${e}` }];
+  }
+};
+
+export const exceedsSize = (example: string, size: number = 500) => {
+  return example.split(/\r\n|\r|\n/).length > size;
+};

package/src/utils/fileToBase64.ts

@@ -0,0 +1,11 @@
+export const fileToBase64 = (file: File) =>
+  new Promise<string>((resolve, reject) => {
+    const reader = new FileReader();
+    reader.readAsDataURL(file);
+    reader.onload = () => {
+      const result = reader.result as string;
+      const base64String = result.replace(/data:.*\/.*;base64,/g, '');
+      resolve(base64String);
+    };
+    reader.onerror = () => reject(reader.error);
+  });

package/src/utils/guards.ts

@@ -0,0 +1,48 @@
+import type { IMarkdownViewerProps } from '@stoplight/markdown-viewer';
+import { isArray } from '@stoplight/mosaic';
+import { IHttpOperation, IHttpService, IHttpWebhookOperation, INode } from '@stoplight/types';
+import { JSONSchema7 } from 'json-schema';
+import { isObject, isPlainObject } from 'lodash';
+
+export function isSMDASTRoot(maybeAst: unknown): maybeAst is IMarkdownViewerProps['markdown'] {
+  return (
+    isObject(maybeAst) &&
+    maybeAst['type' as keyof IMarkdownViewerProps['markdown']] === 'root' &&
+    isArray(maybeAst['children' as keyof IMarkdownViewerProps['markdown']])
+  );
+}
+
+export function isJSONSchema(maybeSchema: unknown): maybeSchema is JSONSchema7 {
+  // the trick is, JSONSchema doesn't define any required properties, so technically even an empty object is a valid JSONSchema
+  return isPlainObject(maybeSchema);
+}
+
+function isStoplightNode(maybeNode: unknown): maybeNode is INode {
+  return isObject(maybeNode) && 'id' in maybeNode;
+}
+
+export function isHttpService(maybeHttpService: unknown): maybeHttpService is IHttpService {
+  return isStoplightNode(maybeHttpService) && 'name' in maybeHttpService && 'version' in maybeHttpService;
+}
+
+export function isHttpOperation(maybeHttpOperation: unknown): maybeHttpOperation is IHttpOperation {
+  return isStoplightNode(maybeHttpOperation) && 'method' in maybeHttpOperation && 'path' in maybeHttpOperation;
+}
+
+export function isHttpWebhookOperation(
+  maybeHttpWebhookOperation: unknown,
+): maybeHttpWebhookOperation is IHttpWebhookOperation {
+  return (
+    isStoplightNode(maybeHttpWebhookOperation) &&
+    'method' in maybeHttpWebhookOperation &&
+    'name' in maybeHttpWebhookOperation
+  );
+}
+
+const properUrl = new RegExp(
+  /((([A-Za-z]{3,9}:(?:\/\/)?)(?:[\-;:&=\+\$,\w]+@)?[A-Za-z0-9\.\-]+|(?:www\.|[\-;:&=\+\$,\w]+@)[A-Za-z0-9\.\-]+)((?:\/[\+~%\/\.\w\-_]*)?\??(?:[\-\+=&;%@\.\w_]*)#?(?:[\.\!\/\\\w]*))?)/,
+);
+
+export function isProperUrl(url: string) {
+  return properUrl.test(url);
+}