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

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

@@ -0,0 +1,62 @@
+import { Flex, Icon, Input, Text } from '@stoplight/mosaic';
+import * as React from 'react';
+
+import { useUniqueId } from '../../../hooks/useUniqueId';
+import { ParameterSpec } from './parameter-utils';
+
+interface FileUploadParameterEditorProps {
+  parameter: ParameterSpec;
+  value?: File;
+  onChange: (parameterValue: File | undefined) => void;
+}
+
+export const FileUploadParameterEditor: React.FC<FileUploadParameterEditorProps> = ({ parameter, value, onChange }) => {
+  const parameterDisplayName = `${parameter.name}${parameter.required ? '*' : ''}`;
+  const handleFileChange = (event: React.ChangeEvent<HTMLInputElement>) => {
+    const file = event.currentTarget.files?.[0];
+    if (file === undefined) return;
+
+    onChange(file);
+  };
+
+  const clearFile = () => {
+    onChange(undefined);
+  };
+
+  const parameterInputId = useUniqueId(`id_${parameter.name}_`);
+  const fileUploadInputId = `${parameterInputId}-file-input`;
+
+  return (
+    <>
+      <label aria-hidden="true" data-testid="param-label" htmlFor={parameterInputId}>
+        {parameterDisplayName}
+      </label>
+      <Text mx={3}>:</Text>
+      <Flex flex={1} alignItems="center">
+        <Input
+          id={parameterInputId}
+          style={{ paddingLeft: 15 }}
+          aria-label={parameter.name}
+          appearance="minimal"
+          flex={1}
+          placeholder="pick a file"
+          type="text"
+          required
+          value={value?.name ?? ''}
+          disabled
+        />
+        {value && (
+          <button className="sl-mr-3 sl-p-2" aria-label="Remove file" onClick={clearFile}>
+            <Icon icon="times" />
+          </button>
+        )}
+        <div>
+          <label role="button" htmlFor={fileUploadInputId}>
+            Upload
+          </label>
+          <input onChange={handleFileChange} type="file" hidden id={fileUploadInputId} />
+        </div>
+      </Flex>
+    </>
+  );
+};

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

@@ -0,0 +1,39 @@
+import { Panel } from '@stoplight/mosaic';
+import * as React from 'react';
+
+import { ParameterSpec } from './parameter-utils';
+import { ParameterEditor } from './ParameterEditor';
+
+interface OperationParametersProps<P extends keyof any = string> {
+  parameters: readonly ParameterSpec[];
+  values: Record<P, string>;
+  onChangeValue: (parameterName: P, newValue: string) => void;
+  validate?: boolean;
+}
+
+export const OperationParameters: React.FC<OperationParametersProps> = ({
+  parameters,
+  values,
+  onChangeValue,
+  validate,
+}) => {
+  return (
+    <Panel defaultIsOpen>
+      <Panel.Titlebar>Parameters</Panel.Titlebar>
+      <Panel.Content className="sl-overflow-y-auto ParameterGrid OperationParametersContent">
+        {parameters.map(parameter => (
+          <ParameterEditor
+            key={parameter.name}
+            parameter={parameter}
+            value={values[parameter.name]}
+            onChange={value => onChangeValue(parameter.name, String(value))}
+            validate={validate}
+            isOptional={false}
+            canChangeOptional={false}
+            onChangeOptional={() => {}}
+          />
+        ))}
+      </Panel.Content>
+    </Panel>
+  );
+};

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

@@ -0,0 +1,135 @@
+import { Flex, Input, Select, SelectProps, Text } from '@stoplight/mosaic';
+import * as React from 'react';
+
+import { useUniqueId } from '../../../hooks/useUniqueId';
+import {
+  decodeSafeSelectorValue,
+  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);
+  // Find the encoded example value that matches the current (decoded) value
+  const selectedExample = React.useMemo(() => {
+    if (!examples) return selectExampleOption;
+    const matchingExample = examples.find(e => {
+      return String(decodeSafeSelectorValue(e.value as string | number)) === value;
+    });
+    return matchingExample ?? selectExampleOption;
+  }, [examples, value]);
+  const parameterDisplayName = `${parameter.name}${parameter.required ? '*' : ''}`;
+
+  // Find the encoded value that matches the current (decoded) value
+  const encodedValue = React.useMemo(() => {
+    if (!value || !parameterValueOptions) return value || '';
+    const matchingOption = parameterValueOptions.find(opt => {
+      return String(decodeSafeSelectorValue(opt.value as string | number)) === value;
+    });
+    return matchingOption ? String(matchingOption.value) : value;
+  }, [value, parameterValueOptions]);
+
+  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={encodedValue}
+            onChange={val => onChange && onChange(String(decodeSafeSelectorValue(val as string | number)))}
+            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={val => onChange && onChange(String(decodeSafeSelectorValue(val as string | number)))}
+              />
+            )}
+          </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,245 @@
+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' },
+];
+
+/**
+ * Encodes a value to be safe for use in CSS selectors (data-key attributes).
+ * Special characters like quotes, brackets, etc. can break querySelector,
+ * so we encode them using base64.
+ */
+export function encodeSafeSelectorValue(value: string | number): string | number {
+  // Numbers are safe to use as-is
+  if (typeof value === 'number') {
+    return value;
+  }
+  // Check if the value contains characters that would break CSS selectors
+  // This includes quotes, brackets, backslashes, etc.
+  const hasSpecialChars = /["'\[\]\\(){}]/.test(value);
+  if (!hasSpecialChars) {
+    return value;
+  }
+  // Encode to base64 to make it safe for CSS selectors
+  // We prefix with 'b64:' so we can decode it later if needed
+  try {
+    return 'b64:' + btoa(value);
+  } catch (e) {
+    // If btoa fails (e.g., with unicode), fallback to encodeURIComponent
+    return 'enc:' + encodeURIComponent(value);
+  }
+}
+
+/**
+ * Decodes a value that was encoded by encodeSafeSelectorValue
+ */
+export function decodeSafeSelectorValue(value: string | number): string | number {
+  if (typeof value === 'number') {
+    return value;
+  }
+
+  if (value.startsWith('b64:')) {
+    try {
+      return atob(value.substring(4));
+    } catch (e) {
+      return value;
+    }
+  }
+  if (value.startsWith('enc:')) {
+    try {
+      return decodeURIComponent(value.substring(4));
+    } catch (e) {
+      return value;
+    }
+  }
+  return value;
+}
+
+function enumOptions(enumValues: JSONSchema7Type[], required?: boolean) {
+  const options = map(enumValues, v => {
+    // Handle objects and arrays by stringifying them
+    const stringValue =
+      typeof v === 'object' && v !== null ? safeStringify(v) ?? String(v) : typeof v === 'number' ? v : String(v);
+    // Encode the value to be safe for CSS selectors, but keep the original label
+    const safeValue = encodeSafeSelectorValue(stringValue);
+    return { value: safeValue, label: String(stringValue) };
+  });
+  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: encodeSafeSelectorValue(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) {
+  if (typeof value === 'object' && value !== null) {
+    return safeStringify(value) ?? String(value);
+  }
+  return String(value);
+}
+
+function escapeQuotes(value: string) {
+  return value.replace(/"/g, '\\"');
+}
+
+function exampleValue(example: Omit<INodeExample, 'id'> | Omit<INodeExternalExample, 'id'>) {
+  const value = 'value' in example ? example.value : example.externalValue;
+  return escapeQuotes(stringifyValue(value));
+}
+
+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 };
+  }
+
+  // If the parameter has enums, prioritize using the first enum value
+  // over examples, as examples might not match the enum values
+  const enums = parameter.schema?.enum ?? [];
+  if (enums.length > 0) {
+    return { value: stringifyValue(enums[0]) };
+  }
+
+  const examples = parameter.examples ?? [];
+  if (examples.length > 0) {
+    return { value: exampleValue(examples[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);
+}