diffdown.com
Diffdown is a real-time collaborative Markdown editor/previewer built on the AT Protocol
diffdown.com
1import * as _codemirror_state from '@codemirror/state';
2import { EditorState, TransactionSpec, Extension, Transaction } from '@codemirror/state';
3import { EditorView, Command, KeyBinding, ViewUpdate } from '@codemirror/view';
4
5type Severity = "hint" | "info" | "warning" | "error";
6/**
7Describes a problem or hint for a piece of code.
8*/
9interface Diagnostic {
10 /**
11 The start position of the relevant text.
12 */
13 from: number;
14 /**
15 The end position. May be equal to `from`, though actually
16 covering text is preferable.
17 */
18 to: number;
19 /**
20 The severity of the problem. This will influence how it is
21 displayed.
22 */
23 severity: Severity;
24 /**
25 When given, add an extra CSS class to parts of the code that
26 this diagnostic applies to.
27 */
28 markClass?: string;
29 /**
30 An optional source string indicating where the diagnostic is
31 coming from. You can put the name of your linter here, if
32 applicable.
33 */
34 source?: string;
35 /**
36 The message associated with this diagnostic.
37 */
38 message: string;
39 /**
40 An optional custom rendering function that displays the message
41 as a DOM node.
42 */
43 renderMessage?: (view: EditorView) => Node;
44 /**
45 An optional array of actions that can be taken on this
46 diagnostic.
47 */
48 actions?: readonly Action[];
49}
50/**
51An action associated with a diagnostic.
52*/
53interface Action {
54 /**
55 The label to show to the user. Should be relatively short.
56 */
57 name: string;
58 /**
59 When given, add an extra CSS class to the action button.
60 */
61 markClass?: string;
62 /**
63 The function to call when the user activates this action. Is
64 given the diagnostic's _current_ position, which may have
65 changed since the creation of the diagnostic, due to editing.
66 */
67 apply: (view: EditorView, from: number, to: number) => void;
68}
69type DiagnosticFilter = (diagnostics: readonly Diagnostic[], state: EditorState) => Diagnostic[];
70interface LintConfig {
71 /**
72 Time to wait (in milliseconds) after a change before running
73 the linter. Defaults to 750ms.
74 */
75 delay?: number;
76 /**
77 Optional predicate that can be used to indicate when diagnostics
78 need to be recomputed. Linting is always re-done on document
79 changes.
80 */
81 needsRefresh?: null | ((update: ViewUpdate) => boolean);
82 /**
83 Optional filter to determine which diagnostics produce markers
84 in the content.
85 */
86 markerFilter?: null | DiagnosticFilter;
87 /**
88 Filter applied to a set of diagnostics shown in a tooltip. No
89 tooltip will appear if the empty set is returned.
90 */
91 tooltipFilter?: null | DiagnosticFilter;
92 /**
93 Can be used to control what kind of transactions cause lint
94 hover tooltips associated with the given document range to be
95 hidden. By default any transactions that changes the line
96 around the range will hide it. Returning null falls back to this
97 behavior.
98 */
99 hideOn?: (tr: Transaction, from: number, to: number) => boolean | null;
100 /**
101 When enabled (defaults to off), this will cause the lint panel
102 to automatically open when diagnostics are found, and close when
103 all diagnostics are resolved or removed.
104 */
105 autoPanel?: boolean;
106}
107interface LintGutterConfig {
108 /**
109 The delay before showing a tooltip when hovering over a lint gutter marker.
110 */
111 hoverTime?: number;
112 /**
113 Optional filter determining which diagnostics show a marker in
114 the gutter.
115 */
116 markerFilter?: null | DiagnosticFilter;
117 /**
118 Optional filter for diagnostics displayed in a tooltip, which
119 can also be used to prevent a tooltip appearing.
120 */
121 tooltipFilter?: null | DiagnosticFilter;
122}
123/**
124Returns a transaction spec which updates the current set of
125diagnostics, and enables the lint extension if if wasn't already
126active.
127*/
128declare function setDiagnostics(state: EditorState, diagnostics: readonly Diagnostic[]): TransactionSpec;
129/**
130The state effect that updates the set of active diagnostics. Can
131be useful when writing an extension that needs to track these.
132*/
133declare const setDiagnosticsEffect: _codemirror_state.StateEffectType<readonly Diagnostic[]>;
134/**
135Returns the number of active lint diagnostics in the given state.
136*/
137declare function diagnosticCount(state: EditorState): number;
138/**
139Command to open and focus the lint panel.
140*/
141declare const openLintPanel: Command;
142/**
143Command to close the lint panel, when open.
144*/
145declare const closeLintPanel: Command;
146/**
147Move the selection to the next diagnostic.
148*/
149declare const nextDiagnostic: Command;
150/**
151Move the selection to the previous diagnostic.
152*/
153declare const previousDiagnostic: Command;
154/**
155A set of default key bindings for the lint functionality.
156
157- Ctrl-Shift-m (Cmd-Shift-m on macOS): [`openLintPanel`](https://codemirror.net/6/docs/ref/#lint.openLintPanel)
158- F8: [`nextDiagnostic`](https://codemirror.net/6/docs/ref/#lint.nextDiagnostic)
159*/
160declare const lintKeymap: readonly KeyBinding[];
161/**
162The type of a function that produces diagnostics.
163*/
164type LintSource = (view: EditorView) => readonly Diagnostic[] | Promise<readonly Diagnostic[]>;
165/**
166Given a diagnostic source, this function returns an extension that
167enables linting with that source. It will be called whenever the
168editor is idle (after its content changed).
169
170Note that settings given here will apply to all linters active in
171the editor. If `null` is given as source, this only configures the
172lint extension.
173*/
174declare function linter(source: LintSource | null, config?: LintConfig): Extension;
175/**
176Forces any linters [configured](https://codemirror.net/6/docs/ref/#lint.linter) to run when the
177editor is idle to run right away.
178*/
179declare function forceLinting(view: EditorView): void;
180/**
181Returns an extension that installs a gutter showing markers for
182each line that has diagnostics, which can be hovered over to see
183the diagnostics.
184*/
185declare function lintGutter(config?: LintGutterConfig): Extension;
186/**
187Iterate over the marked diagnostics for the given editor state,
188calling `f` for each of them. Note that, if the document changed
189since the diagnostics were created, the `Diagnostic` object will
190hold the original outdated position, whereas the `to` and `from`
191arguments hold the diagnostic's current position.
192*/
193declare function forEachDiagnostic(state: EditorState, f: (d: Diagnostic, from: number, to: number) => void): void;
194
195export { type Action, type Diagnostic, type LintSource, closeLintPanel, diagnosticCount, forEachDiagnostic, forceLinting, lintGutter, lintKeymap, linter, nextDiagnostic, openLintPanel, previousDiagnostic, setDiagnostics, setDiagnosticsEffect };