Code Editor linting docs

.changeset/odd-flowers-heal.md

@@ -0,0 +1,7 @@
+---
+"@hashicorp/design-system-components": minor
+---
+
+`hds-code-editor` modifier - Added `isLintingEnabled` and `onLint` named arguments. Linting is supported for the JSON language.
+
+`CodeEditor` - Added `@isLintingEnabled` and `@onLint` arguments that are passed to the `hds-code-editor` modifier

packages/components/package.json

@@ -40,6 +40,7 @@
     "@codemirror/lang-yaml": "^6.1.2",
     "@codemirror/language": "^6.10.3",
     "@codemirror/legacy-modes": "^6.4.2",
+    "@codemirror/lint": "^6.8.4",
     "@codemirror/state": "^6.5.0",
     "@codemirror/view": "^6.36.2",
     "@ember/render-modifiers": "^2.1.0",
@@ -332,6 +333,7 @@
       "./modifiers/hds-code-editor/highlight-styles/hds-dark-highlight-style.js": "./dist/_app_/modifiers/hds-code-editor/highlight-styles/hds-dark-highlight-style.js",
       "./modifiers/hds-code-editor/languages/rego.js": "./dist/_app_/modifiers/hds-code-editor/languages/rego.js",
       "./modifiers/hds-code-editor/languages/sentinel.js": "./dist/_app_/modifiers/hds-code-editor/languages/sentinel.js",
+      "./modifiers/hds-code-editor/linters/json-linter.js": "./dist/_app_/modifiers/hds-code-editor/linters/json-linter.js",
       "./modifiers/hds-code-editor/palettes/hds-dark-palette.js": "./dist/_app_/modifiers/hds-code-editor/palettes/hds-dark-palette.js",
       "./modifiers/hds-code-editor/themes/hds-dark-theme.js": "./dist/_app_/modifiers/hds-code-editor/themes/hds-dark-theme.js",
       "./modifiers/hds-code-editor/types.js": "./dist/_app_/modifiers/hds-code-editor/types.js",

packages/components/src/components/hds/code-editor/index.hbs

@@ -56,11 +56,13 @@
       ariaLabel=@ariaLabel
       ariaLabelledBy=this.ariaLabelledBy
       hasLineWrapping=@hasLineWrapping
+      isLintingEnabled=@isLintingEnabled
       language=@language
       value=@value
       onBlur=@onBlur
       onInput=this.onInput
       onSetup=this.onSetup
+      onLint=@onLint
     }}
   />
 

packages/components/src/modifiers/hds-code-editor.ts

@@ -26,6 +26,7 @@ import type {
   EditorView as EditorViewType,
   ViewUpdate,
 } from '@codemirror/view';
+import type { Diagnostic as DiagnosticType } from '@codemirror/lint';
 import type Owner from '@ember/owner';
 
 type HdsCodeEditorBlurHandler = (
@@ -40,10 +41,12 @@ export interface HdsCodeEditorSignature {
       ariaLabel?: string;
       ariaLabelledBy?: string;
       hasLineWrapping?: boolean;
+      isLintingEnabled?: boolean;
       language?: HdsCodeEditorLanguages;
       value?: string;
       onInput?: (newVal: string) => void;
       onBlur?: HdsCodeEditorBlurHandler;
+      onLint?: (diagnostics: DiagnosticType[]) => void;
       onSetup?: (editor: EditorViewType) => unknown;
     };
   };
@@ -59,7 +62,12 @@ const LOADER_HEIGHT = '164px';
 
 const LANGUAGES: Record<
   HdsCodeEditorLanguages,
-  { load: () => Promise<Extension | StreamLanguageType<unknown>> }
+  {
+    load: () => Promise<Extension | StreamLanguageType<unknown>>;
+    loadLinter?: (
+      onLint?: HdsCodeEditorSignature['Args']['Named']['onLint']
+    ) => Promise<Extension>;
+  }
 > = {
   rego: {
     load: async () => {
@@ -99,6 +107,11 @@ const LANGUAGES: Record<
   },
   json: {
     load: async () => (await import('@codemirror/lang-json')).json(),
+    loadLinter: async (onLint) => {
+      const linter = await import('./hds-code-editor/linters/json-linter.ts');
+
+      return linter.default(onLint);
+    },
   },
   markdown: {
     load: async () => (await import('@codemirror/lang-markdown')).markdown(),
@@ -243,9 +256,17 @@ export default class HdsCodeEditorModifier extends Modifier<HdsCodeEditorSignatu
     this._setupEditorAriaDescribedBy(editor, ariaDescribedBy);
   }
 
-  private _loadLanguageTask = task(
+  private _loadLanguageExtensionsTask = task(
     { drop: true },
-    async (language?: HdsCodeEditorLanguages) => {
+    async ({
+      language,
+      isLintingEnabled,
+      onLint,
+    }: {
+      language?: HdsCodeEditorLanguages;
+      isLintingEnabled?: boolean;
+      onLint?: HdsCodeEditorSignature['Args']['Named']['onLint'];
+    }) => {
       if (language === undefined) {
         return;
       }
@@ -260,7 +281,16 @@ export default class HdsCodeEditorModifier extends Modifier<HdsCodeEditorSignatu
           validLanguageKeys.includes(language)
         );
 
-        return LANGUAGES[language].load();
+        let extensionPromises = [LANGUAGES[language].load()];
+
+        if (isLintingEnabled && LANGUAGES[language].loadLinter) {
+          extensionPromises = [
+            ...extensionPromises,
+            LANGUAGES[language].loadLinter(onLint),
+          ];
+        }
+
+        return Promise.all(extensionPromises);
       } catch (error) {
         warn(
           `\`hds-code-editor\` modifier - Failed to dynamically import the CodeMirror language module for '${language}'. Error: ${JSON.stringify(
@@ -276,7 +306,7 @@ export default class HdsCodeEditorModifier extends Modifier<HdsCodeEditorSignatu
 
   private _buildExtensionsTask = task(
     { drop: true },
-    async ({ language, hasLineWrapping }) => {
+    async ({ language, hasLineWrapping, isLintingEnabled, onLint }) => {
       const [
         {
           keymap,
@@ -293,7 +323,13 @@ export default class HdsCodeEditorModifier extends Modifier<HdsCodeEditorSignatu
         import('@codemirror/language'),
       ]);
 
-      const languageExtension = await this._loadLanguageTask.perform(language);
+      const languageExtensions = await this._loadLanguageExtensionsTask.perform(
+        {
+          language,
+          isLintingEnabled,
+          onLint,
+        }
+      );
 
       const handleUpdateExtension = EditorView.updateListener.of(
         (update: ViewUpdate) => {
@@ -324,7 +360,6 @@ export default class HdsCodeEditorModifier extends Modifier<HdsCodeEditorSignatu
         highlightActiveLineGutter(),
         highlightSpecialChars(),
         history(),
-        lineNumbers(),
         keymap.of([...defaultKeymap, ...historyKeymap]),
         // custom extensions
         handleUpdateExtension,
@@ -333,10 +368,13 @@ export default class HdsCodeEditorModifier extends Modifier<HdsCodeEditorSignatu
         syntaxHighlighting(hdsDarkHighlightStyle),
       ];
 
-      if (languageExtension !== undefined) {
-        extensions = [languageExtension, ...extensions];
+      if (languageExtensions !== undefined) {
+        extensions = [...extensions, ...languageExtensions];
       }
 
+      // ensure we add lineNumber last in the stack to create the right gutter order for linting
+      extensions = [...extensions, lineNumbers()];
+
       return extensions;
     }
   );
@@ -346,20 +384,24 @@ export default class HdsCodeEditorModifier extends Modifier<HdsCodeEditorSignatu
     async (
       element: HTMLElement,
       {
+        onLint,
+        hasLineWrapping,
+        isLintingEnabled,
         language,
         value,
-        hasLineWrapping,
       }: Pick<
         HdsCodeEditorSignature['Args']['Named'],
-        'language' | 'value' | 'hasLineWrapping'
+        'language' | 'value' | 'hasLineWrapping' | 'isLintingEnabled' | 'onLint'
       >
     ) => {
       try {
         const { EditorState } = await import('@codemirror/state');
 
         const extensions = await this._buildExtensionsTask.perform({
-          language,
+          onLint,
           hasLineWrapping: hasLineWrapping ?? false,
+          isLintingEnabled,
+          language,
         });
 
         const state = EditorState.create({
@@ -391,11 +433,13 @@ export default class HdsCodeEditorModifier extends Modifier<HdsCodeEditorSignatu
       const {
         onBlur,
         onInput,
+        onLint,
         onSetup,
         ariaDescribedBy,
         ariaLabel,
         ariaLabelledBy,
         hasLineWrapping,
+        isLintingEnabled,
         language,
         value,
       } = named;
@@ -406,9 +450,11 @@ export default class HdsCodeEditorModifier extends Modifier<HdsCodeEditorSignatu
       this.element = element;
 
       const editor = await this._createEditorTask.perform(element, {
+        onLint,
+        hasLineWrapping,
+        isLintingEnabled,
         language,
         value,
-        hasLineWrapping,
       });
 
       if (editor === undefined) {

packages/components/src/modifiers/hds-code-editor/linters/json-linter.ts

@@ -0,0 +1,148 @@
+import RSVP from 'rsvp';
+
+import type { Diagnostic as DiagnosticType } from '@codemirror/lint';
+import type { HdsCodeEditorSignature } from '../../hds-code-editor';
+import type { Extension, Text } from '@codemirror/state';
+
+export enum HdsCodeEditorJsonLintingError {
+  InvalidSyntax = 'Invalid syntax',
+  KeyExpected = 'Key expected',
+  KeyMustBeDoubleQuoted = 'Key must be double quoted',
+  MissingComma = 'Missing comma',
+  TrailingComma = 'Trailing comma',
+  ValueExpected = 'Value expected',
+}
+
+export function findNextToken(
+  doc: Text,
+  index: number,
+  step: number = 1
+): string {
+  while (index >= 0 && index < doc.length) {
+    const token = doc.sliceString(index, index + 1);
+
+    if (token.trim() !== '') {
+      return token;
+    }
+
+    index += step;
+  }
+  return '';
+}
+
+export function determineErrorMessage({
+  previousToken,
+  nextToken,
+  errorToken,
+}: {
+  previousToken: string;
+  nextToken: string;
+  errorToken: string;
+}): HdsCodeEditorJsonLintingError {
+  let message: HdsCodeEditorJsonLintingError =
+    HdsCodeEditorJsonLintingError.InvalidSyntax;
+
+  if (errorToken === '') {
+    if (previousToken === '{' && nextToken === ':') {
+      message = HdsCodeEditorJsonLintingError.KeyExpected;
+    } else if (previousToken === '"' && nextToken === '"') {
+      message = HdsCodeEditorJsonLintingError.MissingComma;
+    } else if (
+      previousToken === ',' &&
+      (nextToken === '}' || nextToken === ']')
+    ) {
+      message = HdsCodeEditorJsonLintingError.TrailingComma;
+    }
+  } else {
+    if (
+      (previousToken === '{' || previousToken === ',') &&
+      (nextToken === '"' || nextToken === ':')
+    ) {
+      message = HdsCodeEditorJsonLintingError.KeyMustBeDoubleQuoted;
+    } else if (
+      previousToken === ':' &&
+      (nextToken === ',' || nextToken === '}' || nextToken === ']')
+    ) {
+      message = HdsCodeEditorJsonLintingError.ValueExpected;
+    }
+  }
+
+  return message;
+}
+
+// this renders the error message for both the tooltip and the drawer item
+export function renderErrorMessage(message: string): HTMLElement {
+  const wrapper = document.createElement('div');
+  wrapper.classList.add('cm-diagnosticText-inner');
+
+  const icon = document.createElement('div');
+  icon.classList.add('cm-lint-marker-error');
+
+  const text = document.createElement('span');
+  text.textContent = message;
+
+  wrapper.append(icon, text);
+
+  return wrapper;
+}
+
+// lezer JSON parser uses '⚠' as a placeholder for syntax errors
+const errorNodeName = '⚠';
+
+export default async function jsonLinter(
+  onLint: HdsCodeEditorSignature['Args']['Named']['onLint']
+): Promise<Extension[]> {
+  const [
+    { EditorView, keymap },
+    { syntaxTree },
+    { linter, lintGutter, lintKeymap },
+  ] = await RSVP.all([
+    import('@codemirror/view'),
+    import('@codemirror/language'),
+    import('@codemirror/lint'),
+  ]);
+
+  const jsonLinter = linter((view) => {
+    const diagnostics: DiagnosticType[] = [];
+    const doc = view.state.doc;
+    const tree = syntaxTree(view.state);
+    const seenLines = new Set();
+
+    tree.cursor().iterate((node) => {
+      if (node.name === errorNodeName) {
+        const lineNumber = doc.lineAt(node.from).number;
+
+        if (seenLines.has(lineNumber)) {
+          return;
+        }
+
+        const message = determineErrorMessage({
+          previousToken: findNextToken(doc, node.from - 1, -1),
+          nextToken: findNextToken(doc, node.to),
+          errorToken: doc.sliceString(node.from, node.to),
+        });
+
+        diagnostics.push({
+          from: node.from,
+          to: node.to,
+          message,
+          severity: 'error',
+          renderMessage: () => renderErrorMessage(message),
+        });
+
+        seenLines.add(lineNumber);
+      }
+    });
+
+    onLint?.(diagnostics);
+
+    return diagnostics;
+  });
+
+  return [
+    jsonLinter,
+    lintGutter(),
+    keymap.of([...lintKeymap]),
+    EditorView.editorAttributes.of({ class: 'cm-lintingEnabled' }),
+  ];
+}

packages/components/src/modifiers/hds-code-editor/palettes/hds-dark-palette.ts

@@ -14,10 +14,10 @@ export const HDS_CODE_BLOCK_CYAN = '#32fff7';
 export const HDS_CODE_BLOCK_LINE_HIGHLIGHT = 'rgba(0, 74, 222, 0.2)';
 export const HDS_CODE_BLOCK_LINE_HIGHLIGHT_BORDER = '#1b5fe5';
 
-export const HDS_CODE_EDITOR_COLOR_BORDER_STRONG = 'rgba(178, 182, 189, 40%)';
-export const HDS_CODE_EDITOR_COLOR_BORDER_PRIMARY = 'rgba(178, 182, 189, 20%)';
 export const HDS_CODE_EDITOR_COLOR_FOREGROUND_PRIMARY = '#d5d7db';
 export const HDS_CODE_EDITOR_COLOR_FOREGROUND_FAINT = '#878a8f';
-export const HDS_CODE_EDITOR_COLOR_FOREGROUND_HIGH_CONTRAST = '#ffffff';
+export const HDS_CODE_EDITOR_COLOR_FOREGROUND_CRITICAL = '#EF3016';
+
 export const HDS_CODE_EDITOR_COLOR_SURFACE_PRIMARY = '#0D0E12';
 export const HDS_CODE_EDITOR_COLOR_SURFACE_FAINT = '#15181e';
+export const HDS_CODE_EDITOR_COLOR_SURFACE_INTERACTIVE_ACTIVE = '#2B303C';