@fedoup/cm-validation-decorations

CodeMirror 6 extension that paints wavy-underline decorations for validation issues — errors, warnings, info. Hot-reconfigurable: push a new set of issues through the same view without rebuilding the editor.

Useful any time you have an external linter, validator, or schema checker that produces ranged diagnostics and you want them to appear inline.

npm install @fedoup/cm-validation-decorations \
  @codemirror/state @codemirror/view

import { validationExtension, type DecorationIssue } from "@fedoup/cm-validation-decorations";
import { EditorState } from "@codemirror/state";
import { EditorView } from "@codemirror/view";

const validation = validationExtension();

const view = new EditorView({
  state: EditorState.create({
    doc: "hello world",
    extensions: [validation.extension],
  }),
  parent: document.getElementById("editor")!,
});

// Later, when your validator returns fresh diagnostics:
const issues: DecorationIssue[] = [
  { start: 0, end: 5, severity: "warning", message: "Lowercase greeting" },
  { start: 6, end: 11, severity: "error" },
];
validation.reconfigure(view, issues);

What you get

• Three severities — error (red), warning (amber), info (blue), each as a CSS class on the underline span.
• Default theme — included by the extension itself (no separate CSS import needed). Pass theme: false to opt out and bring your own.
• Hot-swap via Compartment — reconfigure(view, issues) runs a single transaction with a compartment.reconfigure effect. No doc edits, no editor rebuild.
• Range-safe — issues with start < 0, end > doc.length, or start >= end are silently filtered so a stale issue stream can't crash the editor while your validator catches up.
• Independent channels — call validationExtension() twice to get two independent reconfigurable sets (e.g. "spelling" + "lint" coexisting).
• Tiny — ~1 kB raw, ~500 bytes gzipped.

API

interface DecorationIssue {
  start: number;          // absolute doc offset
  end: number;            // exclusive
  severity: "error" | "warning" | "info";
  message?: string;       // unused today, reserved for tooltip widget
}

interface ValidationExtensionOptions {
  initial?: DecorationIssue[];   // seed before first reconfigure (default: [])
  theme?: boolean;               // include default wavy underline theme (default: true)
}

function validationExtension(options?: ValidationExtensionOptions): {
  extension: Extension;
  reconfigure(view: EditorView, issues: DecorationIssue[]): void;
};

// Also exported for advanced use:
function buildIssueDecorations(issues: DecorationIssue[], docLength: number): DecorationSet;
const defaultIssueTheme: Extension;

Why not built into a parser?

Because the diagnostics here come from outside CodeMirror — typically an HTTP-fed validator (linter API, schema validator, banned-phrase checker, type checker on the server). Pairing this with @codemirror/lint is fine — that one handles in-editor lint sources via a lintSource callback. This extension is for the case where you already have issues ready to paint and just need a stable hot-swappable rendering layer.

Theming

The default theme bakes the wavy-underline colors in via EditorView.theme(...). To override colors without replacing the theme, import styles.css and set CSS variables:

import "@fedoup/cm-validation-decorations/styles.css";

:root {
  --cm-validation-error-color: rgb(180, 0, 0);
  --cm-validation-warning-color: rgb(200, 130, 0);
  --cm-validation-info-color: rgb(0, 90, 200);
}

To replace the theme entirely, pass theme: false and supply your own. The decoration classes are still applied; only the CSS-in-JS theme is omitted.

const validation = validationExtension({ theme: false });
// Then provide your own EditorView.theme(...) covering
// .cm-validation-error / .cm-validation-warning / .cm-validation-info

License

MIT