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

package/src/components/TryIt/Parameters/ParameterEditor.tsx

@@ -0,0 +1,118 @@
+import { Flex, Input, Select, SelectProps, Text } from '@stoplight/mosaic';
+import * as React from 'react';
+
+import { useUniqueId } from '../../../hooks/useUniqueId';
+import {
+  exampleOptions,
+  getPlaceholderForParameter,
+  getPlaceholderForSelectedParameter,
+  parameterOptions,
+  ParameterSpec,
+  selectExampleOption,
+} from './parameter-utils';
+
+interface ParameterProps {
+  parameter: ParameterSpec;
+  value?: string;
+  onChange: SelectProps['onChange'];
+  isOptional: boolean;
+  onChangeOptional: (optional: boolean) => void;
+  canChangeOptional: boolean;
+  validate?: boolean;
+}
+
+export const ParameterEditor: React.FC<ParameterProps> = ({
+  parameter,
+  value,
+  onChange,
+  isOptional,
+  onChangeOptional,
+  canChangeOptional,
+  validate,
+}) => {
+  const inputId = useUniqueId(`id_${parameter.name}_`);
+  const inputCheckId = useUniqueId(`id_${parameter.name}_checked`);
+  const parameterValueOptions = parameterOptions(parameter);
+  const examples = exampleOptions(parameter);
+  const selectedExample = examples?.find(e => e.value === value) ?? selectExampleOption;
+  const parameterDisplayName = `${parameter.name}${parameter.required ? '*' : ''}`;
+
+  const requiredButEmpty = validate && parameter.required && !value;
+
+  return (
+    <>
+      <Text as="label" aria-hidden="true" data-testid="param-label" htmlFor={inputId} fontSize="base">
+        {parameterDisplayName}
+      </Text>
+      <Text mx={3}>:</Text>
+      <div>
+        {parameterValueOptions ? (
+          <Select
+            flex={1}
+            aria-label={parameter.name}
+            options={parameterValueOptions}
+            value={value || ''}
+            onChange={onChange}
+            placeholder={getPlaceholderForSelectedParameter(parameter)}
+          />
+        ) : (
+          <Flex flex={1}>
+            <Input
+              id={inputId}
+              aria-label={parameter.name}
+              appearance={requiredButEmpty ? 'default' : 'minimal'}
+              flex={1}
+              placeholder={getPlaceholderForParameter(parameter)}
+              type={parameter.schema?.type === 'number' ? 'number' : 'text'}
+              required
+              intent={requiredButEmpty ? 'danger' : 'default'}
+              value={value || ''}
+              onChange={e => onChange && onChange(e.currentTarget.value)}
+            />
+            {examples && (
+              <Select
+                aria-label={`${parameter.name}-select`}
+                flex={1}
+                value={selectedExample.value}
+                options={examples}
+                onChange={onChange}
+              />
+            )}
+          </Flex>
+        )}
+      </div>
+      {canChangeOptional && !parameter.required && (
+        <>
+          <div></div>
+          <div></div>
+          <div>
+            <Flex flex={1}>
+              <Input
+                className="Checkbox"
+                aria-label={`${parameter.name}-checkbox`}
+                id={inputCheckId}
+                flex={1}
+                type="checkbox"
+                intent="success"
+                size="sm"
+                checked={isOptional}
+                onChange={e => onChangeOptional(!e.target.checked)}
+              />
+              <Text
+                className="TextForCheckBox"
+                flex={1}
+                as="label"
+                aria-hidden="true"
+                data-testid="param-check"
+                htmlFor={inputCheckId}
+                fontSize="base"
+              >
+                Omit {parameterDisplayName}
+              </Text>
+            </Flex>
+          </div>
+        </>
+      )}
+    </>
+  );
+};

package/src/components/TryIt/Parameters/__tests__/parameter-utils.spec.ts

@@ -0,0 +1,60 @@
+import { isRegularNode, SchemaTree } from '@stoplight/json-schema-tree';
+import { last } from 'lodash';
+
+import { isRequired } from '../parameter-utils';
+
+describe('isRequired', () => {
+  it('happy path', () => {
+    // Arrange
+    const schema = {
+      $schema: 'http://json-schema.org/draft-07/schema#',
+      description: 'Authenticate for a refresh and access token',
+      title: 'authenticate',
+      allOf: [
+        {
+          type: 'object',
+          properties: {
+            username: { type: 'string' },
+            password: { type: 'string' },
+          },
+        },
+        {
+          type: 'object',
+          properties: {
+            client_id: { type: 'string' },
+            client_secret: { type: 'string' },
+          },
+          required: ['client_id', 'client_secret'],
+        },
+      ],
+    };
+    const tree = new SchemaTree(schema, { mergeAllOf: true, refResolver: null });
+    tree.populate();
+    const root = tree.root.children[0];
+    if (!isRegularNode(root)) {
+      fail('the schema should have been parsed so that this is a RegularNode');
+    }
+
+    if (!root.children) {
+      fail('the combined properties in the allOf should be the children of this RegularNode');
+    }
+
+    const children = root.children ?? [];
+
+    // Act
+    const unknownChildren = children.filter(c => isRequired(c) === undefined);
+    const requiredChildren = children
+      .filter(c => isRequired(c) === true)
+      .map(c => last(c.path))
+      .sort();
+    const optionalChildren = children
+      .filter(c => isRequired(c) === false)
+      .map(c => last(c.path))
+      .sort();
+
+    // Assert
+    expect(unknownChildren).toStrictEqual([]);
+    expect(requiredChildren).toStrictEqual(['client_id', 'client_secret']);
+    expect(optionalChildren).toStrictEqual(['password', 'username']);
+  });
+});

package/src/components/TryIt/Parameters/parameter-utils.spec.ts

@@ -0,0 +1,118 @@
+import { JSONSchema7Definition } from 'json-schema';
+
+import { httpOperation } from '../../../__fixtures__/operations/put-todos';
+import {
+  getPlaceholderForSelectedParameter,
+  initialParameterValues,
+  mapSchemaPropertiesToParameters,
+  ParameterSpec,
+} from './parameter-utils';
+
+describe('Parameter Utils', () => {
+  describe('initialParameterValues.name', () => {
+    it('should fill initial parameters', () => {
+      const allParameters = [
+        ...(httpOperation.request?.path ?? []),
+        ...(httpOperation.request?.query ?? []),
+        ...(httpOperation.request?.headers ?? []),
+      ];
+
+      const parameters = initialParameterValues(allParameters);
+
+      expect(parameters).toMatchObject({
+        type: 'something',
+        value: '1',
+        'account-id': 'account-id-default',
+        'message-id': 'example value',
+      });
+    });
+  });
+
+  describe('mapSchemaPropertiesToParameters.name', () => {
+    it('should convert schema properties to parameters', () => {
+      const properties: { [key: string]: JSONSchema7Definition } = {
+        withExamples: { type: 'string', examples: ['blah'] },
+        withEmptyExamples: { type: 'string', examples: [] },
+        withNoExamples: { type: 'string' },
+        requiredWithExamples: { type: 'string', examples: ['blah'] },
+        requiredWithEmptyExamples: { type: 'string', examples: [] },
+        requiredWithNoExamples: { type: 'string' },
+        requiredBoolean: true,
+        boolean: false,
+      };
+      const required = [
+        'requiredWithExamples',
+        'requiredWithEmptyExamples',
+        'requiredWithNoExamples',
+        'requiredBoolean',
+      ];
+      expect(mapSchemaPropertiesToParameters(properties, required)).toEqual([
+        {
+          name: 'withExamples',
+          schema: { type: 'string', examples: ['blah'] },
+          examples: [{ key: 'example', value: 'blah' }],
+        },
+        {
+          name: 'withEmptyExamples',
+          schema: { type: 'string', examples: [] },
+        },
+        {
+          name: 'withNoExamples',
+          schema: { type: 'string' },
+        },
+        {
+          name: 'requiredWithExamples',
+          schema: { type: 'string', examples: ['blah'] },
+          examples: [{ key: 'example', value: 'blah' }],
+          required: true,
+        },
+        {
+          name: 'requiredWithEmptyExamples',
+          schema: { type: 'string', examples: [] },
+          required: true,
+        },
+        {
+          name: 'requiredWithNoExamples',
+          schema: { type: 'string' },
+          required: true,
+        },
+        {
+          name: 'requiredBoolean',
+          required: true,
+        },
+        {
+          name: 'boolean',
+        },
+      ]);
+    });
+  });
+
+  describe('getPlaceholderForSelectedParameter', () => {
+    let parameter: ParameterSpec;
+
+    it('should return placeholder text with default value when parameter has a default value', () => {
+      parameter = {
+        name: 'name',
+        schema: {
+          default: 0,
+          enum: [0, 1, 3],
+        },
+      };
+
+      const result = getPlaceholderForSelectedParameter(parameter);
+      expect(result).toEqual(`select an option (defaults to: ${parameter?.schema?.default})`);
+    });
+
+    it('should return undefined when parameter does not have a default value', () => {
+      parameter = {
+        name: 'name',
+        schema: {
+          enum: [0, 1, 3],
+        },
+      };
+
+      const result = getPlaceholderForSelectedParameter(parameter);
+      expect(result).toBeUndefined();
+    });
+  });
+});

package/src/components/TryIt/Parameters/parameter-utils.ts

@@ -0,0 +1,179 @@
+import { safeStringify } from '@stoplight/json';
+import { isRegularNode, RegularNode, SchemaNode } from '@stoplight/json-schema-tree';
+import type { IHttpParam, INodeExample, INodeExternalExample } from '@stoplight/types';
+import { JSONSchema7, JSONSchema7Definition, JSONSchema7Type } from 'json-schema';
+import { isObject, keyBy, last, map, mapValues } from 'lodash';
+
+export type ParameterSpec = Pick<IHttpParam, 'name' | 'schema' | 'required'> & {
+  examples?: (Omit<INodeExample, 'id'> | Omit<INodeExternalExample, 'id'>)[];
+};
+const booleanOptions = [
+  { label: 'Not Set', value: '' },
+  { label: 'False', value: 'false' },
+  { label: 'True', value: 'true' },
+];
+
+function enumOptions(enumValues: JSONSchema7Type[], required?: boolean) {
+  const options = map(enumValues, v => ({ value: typeof v === 'number' ? v : String(v) }));
+  return required ? options : [{ label: 'Not Set', value: '' }, ...options];
+}
+
+export function parameterOptions(parameter: ParameterSpec) {
+  return parameter.schema?.type === 'boolean'
+    ? booleanOptions
+    : parameter.schema?.enum !== undefined
+    ? enumOptions(parameter.schema.enum, parameter.required)
+    : null;
+}
+
+export const selectExampleOption = { value: '', label: 'Pick an example' };
+
+export function exampleOptions(parameter: ParameterSpec) {
+  return parameter.examples?.length && parameter.examples.length > 1
+    ? [
+        selectExampleOption,
+        ...parameter.examples.map(example => ({ label: example.key, value: exampleValue(example) })),
+      ]
+    : null;
+}
+
+export function parameterSupportsFileUpload(parameter?: Pick<ParameterSpec, 'schema'>) {
+  return (
+    parameter &&
+    parameter.schema &&
+    parameter.schema?.type === 'string' &&
+    (parameter.schema?.contentEncoding === 'base64' ||
+      parameter.schema?.contentMediaType === 'application/octet-stream')
+  );
+}
+
+function stringifyValue(value: unknown) {
+  return typeof value === 'object' ? JSON.stringify(value) : escapeQuotes(String(value));
+}
+
+function exampleValue(example: Omit<INodeExample, 'id'> | Omit<INodeExternalExample, 'id'>) {
+  const value = 'value' in example ? example.value : example.externalValue;
+  return stringifyValue(value);
+}
+
+function escapeQuotes(value: string) {
+  return value.replace(/"/g, '\\"');
+}
+
+export function getPlaceholderForParameter(parameter: ParameterSpec) {
+  const { value: parameterValue, isDefault } = getValueForParameter(parameter);
+
+  if (parameterValue) return `${isDefault ? 'defaults to' : 'example'}: ${parameterValue}`;
+
+  return String(parameter.schema?.type ?? '');
+}
+
+export function getPlaceholderForSelectedParameter(parameter: ParameterSpec) {
+  const { value: parameterValue, isDefault } = getValueForParameter(parameter);
+
+  if (isDefault) {
+    return `select an option (defaults to: ${parameterValue})`;
+  }
+
+  return undefined;
+}
+
+function retrieveDefaultFromSchema(parameter: ParameterSpec) {
+  const defaultValue = parameter.schema?.default;
+  return isObject(defaultValue) ? safeStringify(defaultValue) : defaultValue;
+}
+
+const getValueForParameter = (parameter: ParameterSpec) => {
+  const defaultValue = retrieveDefaultFromSchema(parameter);
+  if (typeof defaultValue !== 'undefined') {
+    return { value: stringifyValue(defaultValue), isDefault: true };
+  }
+
+  const examples = parameter.examples ?? [];
+  if (examples.length > 0) {
+    return { value: exampleValue(examples[0]) };
+  }
+
+  const enums = parameter.schema?.enum ?? [];
+  if (enums.length > 0) {
+    return { value: stringifyValue(enums[0]) };
+  }
+
+  return { value: '' };
+};
+
+const getInitialValueForParameter = (parameter: ParameterSpec) => {
+  const isRequired = !!parameter.required;
+
+  if (!isRequired) return '';
+
+  return getValueForParameter(parameter).value;
+};
+
+export const initialParameterValues: (params: readonly ParameterSpec[]) => Record<string, string> = params => {
+  const paramsByName = keyBy(params, (param: ParameterSpec) => param.name);
+  return mapValues(paramsByName, param => getInitialValueForParameter(param));
+};
+
+export function mapSchemaPropertiesToParameters(
+  properties: { [key: string]: JSONSchema7Definition },
+  required: string[] | undefined,
+) {
+  return Object.entries(properties).map(([name, schema]) => ({
+    name,
+    schema: typeof schema !== 'boolean' ? schema : undefined,
+    examples:
+      typeof schema !== 'boolean' && Array.isArray(schema.examples) && schema.examples[0]
+        ? [{ key: 'example', value: schema.examples[0] }]
+        : undefined,
+    ...(required?.includes(name) && { required: true }),
+  }));
+}
+
+export function toParameterSpec(jsonTreeNode: RegularNode): ParameterSpec {
+  const isBoolean = jsonTreeNode.primaryType === 'boolean';
+  // TODO: Why does ParameterSpec assume JSONSchema7 and ignore 6 and 4?
+  const schema = !isBoolean ? (jsonTreeNode.fragment as JSONSchema7) : undefined;
+  const examples =
+    !isBoolean && jsonTreeNode.fragment.examples && jsonTreeNode.fragment.examples[0]
+      ? [{ key: 'example', value: jsonTreeNode.fragment.examples[0] }]
+      : undefined;
+
+  // It's possible -- but very unlikely -- that the path is empty here.
+  const lastJsonPathSegment = last(jsonTreeNode.path) ?? '<<UNKNOWN>>';
+
+  return {
+    name: lastJsonPathSegment,
+    schema,
+    examples,
+    required: isRequired(jsonTreeNode),
+  };
+}
+
+/**
+ * @returns
+ * - `true` iff this schema/property is among the properties required by `n`'s
+ *   parent
+ * - `false` iff this schema/property is NOT among the properties required by
+ *   `n`'s parent
+ * - `undefined` when required-ness is intedeterminate; e.g., there's no parent,
+ *   the parent isn't a `RegularNode`, this thing lacks a key/name, `n` isn't a
+ *   `RegularNode`
+ */
+export function isRequired(n: SchemaNode): boolean | undefined {
+  if (!isRegularNode(n)) {
+    return undefined;
+  }
+
+  const name: string | undefined = last(n.path);
+  if (name === undefined) {
+    return undefined;
+  }
+
+  const parent = n.parent;
+  if (parent === null || !isRegularNode(parent)) {
+    return undefined;
+  }
+
+  return parent.required !== null && parent.required.includes(name);
+}

package/src/components/TryIt/Parameters/useOperationParameters.ts

@@ -0,0 +1,60 @@
+import { IHttpEndpointOperation } from '@stoplight/types';
+import { atom, useAtom } from 'jotai';
+import { orderBy, uniqBy } from 'lodash';
+import * as React from 'react';
+
+import { filterOutAuthorizationParams } from '../Auth/authentication-utils';
+import { initialParameterValues, ParameterSpec } from './parameter-utils';
+
+const persistedParameterValuesAtom = atom<Record<string, string | undefined>>({});
+export const useRequestParameters = (httpOperation: IHttpEndpointOperation) => {
+  const [persistedParameterValues, setPersistedParameterValues] = useAtom(persistedParameterValuesAtom);
+
+  const allParameters = React.useMemo(() => extractAllParameters(httpOperation), [httpOperation]);
+  const parameterDefaultValues = React.useMemo(() => initialParameterValues(allParameters), [allParameters]);
+
+  const updateParameterValue = (name: string, value: string) => {
+    const defaultValue = parameterDefaultValues[name];
+    setPersistedParameterValues(prevState => {
+      // if the user set it to default, let's just unset it instead
+      const valueToSave = value === defaultValue ? undefined : value;
+      // only save if changed
+      if (prevState[name] !== valueToSave) {
+        return { ...prevState, [name]: valueToSave };
+      }
+      return prevState;
+    });
+  };
+
+  const parameterValuesWithDefaults = React.useMemo(
+    () =>
+      Object.fromEntries(
+        allParameters.map(parameter => [
+          parameter.name,
+          persistedParameterValues[parameter.name] ?? parameterDefaultValues[parameter.name],
+        ]),
+      ),
+    [allParameters, persistedParameterValues, parameterDefaultValues],
+  );
+
+  return {
+    allParameters,
+    parameterValuesWithDefaults,
+    updateParameterValue,
+  };
+};
+
+function extractAllParameters(httpOperation: IHttpEndpointOperation): ParameterSpec[] {
+  const getRequired = (obj: { required?: boolean }) => obj.required ?? false;
+
+  const pathParameters = orderBy(httpOperation.request?.path ?? [], [getRequired, 'name'], ['desc', 'asc']);
+  const queryParameters = filterOutAuthorizationParams(
+    orderBy(httpOperation.request?.query ?? [], [getRequired, 'name'], ['desc', 'asc']),
+    httpOperation.security,
+  );
+  const headerParameters = filterOutAuthorizationParams(
+    orderBy(httpOperation.request?.headers ?? [], [getRequired, 'name'], ['desc', 'asc']),
+    httpOperation.security,
+  );
+  return uniqBy([...pathParameters, ...queryParameters, ...headerParameters], p => p.name);
+}

package/src/components/TryIt/Response/ReponseCodeViewer.tsx

@@ -0,0 +1,28 @@
+import { CodeViewer, CodeViewerProps } from '@stoplight/mosaic-code-viewer';
+import React from 'react';
+
+import { useLineCount } from './hooks/useLineCount';
+
+const MAX_HIGHLIGHT_LINE_COUNT = 10000;
+
+export const ResponseCodeViewer: <E extends React.ElementType = 'pre'>(
+  props: CodeViewerProps<E>,
+) => React.ReactElement | null = ({ value, ...rest }) => {
+  const lineCount = useLineCount({ example: value });
+
+  if (lineCount < MAX_HIGHLIGHT_LINE_COUNT) {
+    return <CodeViewer language="json" value={value} />;
+  }
+
+  return (
+    <CodeViewer
+      language="json"
+      showAsRaw={MAX_HIGHLIGHT_LINE_COUNT < lineCount}
+      style={{
+        color: 'white',
+      }}
+      value={value}
+      {...rest}
+    />
+  );
+};