1// We use `import type` to guarantee it'll be erased from the JS and it doesnt accidently bundle monaco
2import type * as monacoType from 'monaco-editor/esm/vs/editor/editor.api';
3import type { EditorProps } from '@monaco-editor/react';
4
5// we do not allow customizing the theme.
6// (theme is complicated in Monaco, right now there is
7// a limitation where all monaco editors must have
8// the same theme, see
9// https://github.com/microsoft/monaco-editor/issues/338#issuecomment-274837186
10// )
11export type ReactMonacoEditorProps = Omit<EditorProps, 'theme'>;
12
13export type CodeEditorChangeHandler = (value: string) => void;
14export type CodeEditorSuggestionProvider = () => CodeEditorSuggestionItem[];
15
16export type { monacoType as monacoTypes };
17export type Monaco = typeof monacoType;
18export type MonacoEditor = monacoType.editor.IStandaloneCodeEditor;
19export type MonacoOptions = MonacoOptionsWithGrafanaDefaults;
20
21export interface CodeEditorProps {
22  value: string;
23  language: string;
24  width?: number | string;
25  height?: number | string;
26
27  readOnly?: boolean;
28  showMiniMap?: boolean;
29  showLineNumbers?: boolean;
30  monacoOptions?: MonacoOptions;
31
32  /**
33   * Callback before the editor has mounted that gives you raw access to monaco
34   */
35  onBeforeEditorMount?: (monaco: Monaco) => void;
36
37  /**
38   * Callback after the editor has mounted that gives you raw access to monaco
39   */
40  onEditorDidMount?: (editor: MonacoEditor, monaco: Monaco) => void;
41
42  /** Handler to be performed when editor is blurred */
43  onBlur?: CodeEditorChangeHandler;
44
45  /** Handler to be performed when Cmd/Ctrl+S is pressed */
46  onSave?: CodeEditorChangeHandler;
47
48  /**
49   * Language agnostic suggestion completions -- typically for template variables
50   */
51  getSuggestions?: CodeEditorSuggestionProvider;
52}
53
54/**
55 * @alpha
56 */
57export enum CodeEditorSuggestionItemKind {
58  Method = 'method',
59  Field = 'field',
60  Property = 'property',
61  Constant = 'constant',
62  Text = 'text',
63}
64
65/**
66 * @alpha
67 */
68export interface CodeEditorSuggestionItem {
69  /**
70   * The label of this completion item. By default
71   * this is also the text that is inserted when selecting
72   * this completion.
73   */
74  label: string;
75
76  /**
77   * The kind of this completion item. An icon is chosen
78   * by the editor based on the kind.
79   */
80  kind?: CodeEditorSuggestionItemKind;
81
82  /**
83   * A human-readable string with additional information
84   * about this item, like type or symbol information.
85   */
86  detail?: string;
87
88  /**
89   * A human-readable string that represents a doc-comment.
90   */
91  documentation?: string; // | IMarkdownString;
92
93  /**
94   * A string or snippet that should be inserted in a document when selecting
95   * this completion. When `falsy` the `label` is used.
96   */
97  insertText?: string;
98}
99
100/**
101 * This interface will extend the original Monaco editor options interface
102 * but changing the code comments to contain the proper default values to
103 * prevent the consumer of the CodeEditor to get incorrect documentation in editor.
104 */
105export interface MonacoOptionsWithGrafanaDefaults extends monacoType.editor.IStandaloneEditorConstructionOptions {
106  /**
107   * Enable custom contextmenu.
108   * Defaults to false.
109   */
110  contextmenu?: boolean;
111  /**
112   * The number of spaces a tab is equal to.
113   * This setting is overridden based on the file contents when `detectIndentation` is on.
114   * Defaults to 4.
115   */
116  tabSize?: number;
117  /**
118   * Show code lens
119   * Defaults to false.
120   */
121  codeLens?: boolean;
122  /**
123   * Control the width of line numbers, by reserving horizontal space for rendering at least an amount of digits.
124   * Defaults to 4.
125   */
126  lineNumbersMinChars?: number;
127  /**
128   * The width reserved for line decorations (in px).
129   * Line decorations are placed between line numbers and the editor content.
130   * You can pass in a string in the format floating point followed by "ch". e.g. 1.3ch.
131   * Defaults to 1 * theme.spacing.gridSize.
132   */
133  lineDecorationsWidth?: number | string;
134  /**
135   * Controls if a border should be drawn around the overview ruler.
136   * Defaults to `false`.
137   */
138  overviewRulerBorder?: boolean;
139  /**
140   * Enable that the editor will install an interval to check if its container dom node size has changed.
141   * Enabling this might have a severe performance impact.
142   * Defaults to true.
143   */
144  automaticLayout?: boolean;
145}
146