feat: jumpToPath plugin with Monaco (#3244)

* requires [email protected] or greater

* maps position from apidom-ls to monaco interface

* maintains legacy compatibility with `path` and `specPath` props

Author: tim-lai

package-lock.json

@@ -32,7 +32,7 @@
     }
   },
   "scripts": {
-    "start": "cross-env DISABLE_ESLINT_PLUGIN=false ENABLE_PROGRESS_PLUGIN=true react-scripts start",
+    "start": "cross-env DISABLE_ESLINT_PLUGIN=true ENABLE_PROGRESS_PLUGIN=true react-scripts start",
     "build": "npm run build:app && npm run build:bundle:esm && npm run build:bundle:umd",
     "build:app": "cross-env ENABLE_PROGRESS_PLUGIN=false DISABLE_ESLINT_PLUGIN=false react-scripts build",
     "build:app:serve": "serve -s build -l 3050",
@@ -66,6 +66,7 @@
     "axios": "^0.27.2",
     "deepmerge": "^4.2.2",
     "file-dialog": "^0.0.8",
+    "immutable": "^3.8.2",
     "is-json": "^2.0.1",
     "js-file-download": "^0.4.12",
     "js-yaml": "^4.1.0",
@@ -77,6 +78,7 @@
     "react-collapse-pane": "^3.0.1",
     "react-dom": "^17.0.2",
     "react-dropzone": "^14.2.2",
+    "react-immutable-proptypes": "^2.2.0",
     "react-modal": "^3.15.1",
     "react-resize-detector": "^7.1.2",
     "react-table": "^7.8.0",

package.json

@@ -17,6 +17,7 @@ import EditorPreviewAsyncAPIPlugin from './plugins/editor-preview-asyncapi/index
 import EditorReadOnlyPlugin from './plugins/editor-read-only/index.js';
 import EditorSpecOriginPlugin from './plugins/editor-spec-origin/index.js';
 import EditorPersistencePlugin from './plugins/editor-persistence/index.js';
+import EditorJumpFromPathToLinePlugin from './plugins/editor-jump-from-path-to-line/index.js';
 
 const SafeRenderPlugin = (system) =>
   SwaggerUI.plugins.SafeRender({
@@ -29,6 +30,7 @@ const SafeRenderPlugin = (system) =>
       'EditorPane',
       'EditorPaneBarTop',
       'EditorPreviewPane',
+      'EditorJumpFromPathToLine',
       'ValidationPane',
       'AlertDialog',
       'ConfirmDialog',
@@ -59,6 +61,7 @@ SwaggerEditor.plugins = {
   EditorPersistence: EditorPersistencePlugin,
   EditorPreviewSwaggerUI: EditorPreviewSwaggerUIPlugin,
   EditorPreviewAsyncAPI: EditorPreviewAsyncAPIPlugin,
+  EditorJumpFromPathToLine: EditorJumpFromPathToLinePlugin,
   Topbar: TopbarPlugin,
   Layout: LayoutPlugin,
 };
@@ -74,6 +77,7 @@ SwaggerEditor.presets = {
     EditorPersistencePlugin,
     EditorPreviewSwaggerUIPlugin,
     EditorPreviewAsyncAPIPlugin,
+    EditorJumpFromPathToLinePlugin,
     TopbarPlugin,
     LayoutPlugin,
     SafeRenderPlugin,
@@ -90,6 +94,7 @@ SwaggerEditor.presets = {
     EditorPersistencePlugin,
     EditorPreviewSwaggerUIPlugin,
     EditorPreviewAsyncAPIPlugin,
+    EditorJumpFromPathToLinePlugin,
     TopbarPlugin,
     LayoutPlugin,
     SafeRenderPlugin,

src/App.jsx

@@ -0,0 +1,66 @@
+import React from 'react';
+import PropTypes from 'prop-types';
+import ImmutablePropTypes from 'react-immutable-proptypes';
+
+import JumpIcon from './jump-icon.svg';
+
+/**
+ * JumpToPath is a legacy name that is already built into SwaggerUI
+ * 1. onHover of SwaggerUI operation or model, render svg icon
+ * 2. onClick of svg icon => jump to line in editor
+ */
+
+const JumpToPath = ({ specSelectors, editorActions, path, specPath, content, showButton }) => {
+  const handleJumpToEditorLine = (e) => {
+    e.stopPropagation();
+    const jumpPath = specSelectors.bestJumpPath({ path, specPath });
+    // `apidom-ls` will expect `jumpPath` to be a String instead of legacy Array, e.g. '/components/schemas/Category/properties/id'
+    // `Editor` will handle the rest of workflow
+    editorActions.setRequestJumpToEditorMarker({ jsonPointer: jumpPath });
+  };
+
+  const defaultJumpButton = (
+    <div
+      role="button"
+      tabIndex={0}
+      onClick={handleJumpToEditorLine}
+      onKeyPress={handleJumpToEditorLine}
+    >
+      <img src={JumpIcon} className="view-line-link" title="Jump to definition" alt="" />
+    </div>
+  );
+
+  if (content) {
+    // if we were given content to render, wrap it
+    return (
+      <span
+        role="button"
+        tabIndex={0}
+        onClick={handleJumpToEditorLine}
+        onKeyPress={handleJumpToEditorLine}
+      >
+        {showButton ? { defaultJumpButton } : null}
+        {content}
+      </span>
+    );
+  }
+  return <div>{defaultJumpButton}</div>;
+};
+
+JumpToPath.propTypes = {
+  editorActions: PropTypes.oneOfType([PropTypes.object]).isRequired,
+  specSelectors: PropTypes.oneOfType([PropTypes.object]).isRequired,
+  path: PropTypes.oneOfType([PropTypes.array, PropTypes.string, ImmutablePropTypes.list]),
+  specPath: PropTypes.oneOfType([PropTypes.array, ImmutablePropTypes.list]), // the location within the spec. used as a fallback if `path` doesn't exist
+  content: PropTypes.element,
+  showButton: PropTypes.bool,
+};
+
+JumpToPath.defaultProps = {
+  path: [],
+  specPath: [],
+  content: null,
+  showButton: false,
+};
+
+export default JumpToPath;

src/plugins/editor-jump-from-path-to-line/components/JumpToPath.jsx

@@ -0,0 +1,17 @@
+import JumpToPath from './components/JumpToPath.jsx';
+import { bestJumpPath } from './selectors.js';
+
+const EditorJumpFromPathToLine = () => ({
+  components: {
+    JumpToPath,
+  },
+  statePlugins: {
+    spec: {
+      selectors: {
+        bestJumpPath,
+      },
+    },
+  },
+});
+
+export default EditorJumpFromPathToLine;

src/plugins/editor-jump-from-path-to-line/components/jump-icon.svg

@@ -0,0 +1,61 @@
+/* eslint-disable import/prefer-default-export */
+import { createSelector } from 'reselect';
+import { List } from 'immutable';
+
+const transformArrayToStringPath = (arr) => {
+  if (arr.at(0) !== '/') {
+    return `/${arr.join('')}`;
+  }
+  return arr.join('/');
+};
+
+const transformImListToStringPath = (list) => {
+  const arr = list.toJS();
+  if (arr.at(0) !== '/') {
+    return `/${arr.join('')}`;
+  }
+  return arr.join('');
+};
+
+// compared to `path`, each element inside `specPath` does not contain leading `/`
+const transformArrayToStringSpecPath = (arr) => {
+  if (arr.at(0) !== '/') {
+    return `/${arr.join('/')}`;
+  }
+  return arr.join('/');
+};
+
+// compared to `path`, each element inside `specPath` does not contain leading `/`
+const transformImListToStringSpecPath = (list) => {
+  const arr = list.toJS();
+  if (arr.at(0) !== '/') {
+    return `/${arr.join('/')}`;
+  }
+  return arr.join('/');
+};
+
+// apidom-ls expects a String as arg
+export const bestJumpPath = createSelector(
+  (state, pathObj) => pathObj, // input from arg to forward to output
+  ({ path, specPath }) => {
+    if (path && typeof path === 'string') {
+      return path;
+    }
+    if (path && Array.isArray(path) && path.length > 0) {
+      return transformArrayToStringPath(path);
+    }
+    if (path && List.isList(path) && path.size > 0) {
+      return transformImListToStringPath(path);
+    }
+    if (specPath && typeof specPath === 'string') {
+      return specPath;
+    }
+    if (specPath && Array.isArray(specPath) && specPath.length > 0) {
+      return transformArrayToStringSpecPath(specPath);
+    }
+    if (specPath && List.isList(specPath) && specPath.size > 0) {
+      return transformImListToStringSpecPath(specPath);
+    }
+    return '';
+  }
+);

src/plugins/editor-jump-from-path-to-line/index.js

@@ -2,6 +2,9 @@ export const EDITOR_UPDATE_THEME = 'editor_update_theme';
 export const EDITOR_ERROR_MARKERS = 'editor_error_markers';
 export const EDITOR_JUMP_TO_EDITOR_MARKER = 'editor_jump_to_editor_marker';
 export const EDITOR_CLEAR_JUMP_TO_EDITOR_MARKER = 'editor_clear_jump_to_editor_marker';
+export const EDITOR_SET_REQUEST_JUMP_TO_EDITOR_MARKER = 'editor_set_request_jump_to_editor_marker';
+export const EDITOR_CLEAR_REQUEST_JUMP_TO_EDITOR_MARKER =
+  'editor_clear_request_jump_to_editor_marker';
 
 export const updateEditorTheme = (theme = 'my-vs-dark') => {
   return {
@@ -27,3 +30,15 @@ export const clearJumpToEditorMarker = () => {
     type: EDITOR_CLEAR_JUMP_TO_EDITOR_MARKER,
   };
 };
+export const setRequestJumpToEditorMarker = (marker = {}) => {
+  return {
+    payload: marker,
+    type: EDITOR_SET_REQUEST_JUMP_TO_EDITOR_MARKER,
+  };
+};
+export const clearRequestJumpToEditorMarker = () => {
+  return {
+    payload: {},
+    type: EDITOR_CLEAR_REQUEST_JUMP_TO_EDITOR_MARKER,
+  };
+};