@aardarch/aardink-web 0.8.0 → 0.10.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -97,6 +97,67 @@ await registerLanguage({
97
97
  });
98
98
  ```
99
99
 
100
+ A language can also take VS Code's `language-configuration.json`, as the object or its text, for
101
+ closing pairs, surrounding a selection and indentation on Enter:
102
+
103
+ ```ts
104
+ await registerLanguage({ id: 'toy', grammar, configuration: await (await fetch('/toy.configuration.json')).text() });
105
+ ```
106
+
107
+ The providers go beyond completions: `provideHover`, `provideDiagnostics`, `provideDocumentSymbols`,
108
+ `provideDocumentColors`, and, with the `inlayHints` and `codeLens` options on, `provideInlayHints`
109
+ and `provideCodeLenses` with `runCodeLensCommand` for a lens's click:
110
+
111
+ ```ts
112
+ await registerLanguage(definition, {
113
+ provideInlayHints: (text, range) => [{ position: { lineNumber: 3, column: 9 }, label: ': Int' }],
114
+ provideCodeLenses: (text) => [
115
+ { range: { startLineNumber: 1, startColumn: 1, endLineNumber: 1, endColumn: 1 }, command: { id: 'app.run', title: 'Run' } },
116
+ ],
117
+ runCodeLensCommand: (id, args) => run(id, args),
118
+ });
119
+ const editor = await createEditor(container, save, { language: 'toy', inlayHints: true, codeLens: true });
120
+ ```
121
+
122
+ Hover, completion documentation and signature help are Markdown, shown in a card and, for the
123
+ selected completion, in a pane beside the list. A link there, or Ctrl/Cmd+click on a URL in the
124
+ text, opens `http` and `https` in a new tab; listen to decide for yourself, and check the target
125
+ first, since text from a language server can hold a `javascript:` link:
126
+
127
+ ```ts
128
+ const links = editor.onOpenLink((target) => {
129
+ if (target.startsWith('https://')) window.open(target, '_blank', 'noopener');
130
+ });
131
+ ```
132
+
133
+ Ghost text, as an assistant offers it, comes from a provider of its own, for any language. Tab
134
+ accepts, Alt+] and Alt+[ go through what is on offer, and Escape hides it; a phone runs
135
+ `editor.action.inlineSuggest.commit` and `.hide` from buttons through `trigger`:
136
+
137
+ ```ts
138
+ import { registerInlineCompletionsProvider } from '@aardarch/aardink-web';
139
+
140
+ await registerInlineCompletionsProvider('kotlin', {
141
+ provideInlineCompletions: async (text, line, column) => ({ items: [{ insertText: await suggest(text, line, column) }] }),
142
+ });
143
+ ```
144
+
145
+ A language server reached over a WebSocket follows every editor of a language, adding what it
146
+ knows to what the language has; with `semanticHighlighting: true` its semantic tokens colour the
147
+ text too:
148
+
149
+ ```ts
150
+ import { connectLanguageServer } from '@aardarch/aardink-web';
151
+
152
+ const server = await connectLanguageServer('wss://example.com/lsp', 'kotlin');
153
+ // ...
154
+ server.dispose(); // closes each document and shuts the server down
155
+ ```
156
+
157
+ The socket carries one JSON-RPC message per frame, so a server that speaks over stdin and stdout
158
+ needs a bridge in front of it. Nothing reconnects by itself, and a server never changes what typing
159
+ does: Enter, closing pairs and surrounding stay the language's.
160
+
100
161
  The editor answers to your keys and actions as Monaco's does, and tells you what changed:
101
162
 
102
163
  ```ts
@@ -109,7 +170,7 @@ editor.revealLineInCenter(42);
109
170
  ```
110
171
 
111
172
  The editor fills its container, so give the container a size. `createEditor` is async because
112
- the first call loads the WebAssembly module (about 13 MB, 4.7 MB gzipped); every editor on the
173
+ the first call loads the WebAssembly module (about 14 MB, 5 MB gzipped); every editor on the
113
174
  page shares that one module. If that load fails, the call rejects and the next call loads again
114
175
  (though Chrome keeps a failed module download until the page is reloaded). See
115
176
  [`index.d.ts`](./index.d.ts) for the full API, and the
@@ -152,10 +213,15 @@ Read these before adopting the package; the
152
213
  [integration guide](https://github.com/aardarch/aardink/blob/main/docs/WEB_INTEGRATION.md) has
153
214
  the measurements and the device checklist.
154
215
 
155
- - **A disposed editor is not fully released** (about 275 KB each) until Aardink moves to Compose
216
+ - **A disposed editor is not fully released** (about 320 KB each) until Aardink moves to Compose
156
217
  Multiplatform 1.13. Reuse one editor with `setValue` and `updateOptions` rather than mounting
157
218
  one per view.
158
219
  - A theme rule's `background` is ignored; its `foreground` and `fontStyle` apply.
220
+ - A language from `registerLanguage`, and the built-in language it `extends`, answer before a
221
+ language server: with `extends: 'json'`, JSON's formatter and outline come ahead of the server's.
222
+ - The page has no save, so a language server never hears `willSave` or `didSave`.
223
+ - Of the keys that type a character with Alt held, only Alt+] and Alt+[ reach the editor:
224
+ `addCommand('Alt+K', ...)` never runs. Use a key with Ctrl or Cmd.
159
225
 
160
226
  ## Licence
161
227
 
package/index.d.ts CHANGED
@@ -20,11 +20,57 @@ export interface AardinkOptions {
20
20
  value?: string;
21
21
  /** A language id: kotlin, typescript, json, toml, xml, html, css, markdown, plaintext. */
22
22
  language?: string;
23
- /** vscode-dark, vscode-light, material-dark, material-light, midnight-ocean, solarized-dark. */
23
+ /**
24
+ * vscode-dark (or Monaco's `vs-dark`), vscode-light (or `vs`), hc-black, hc-light, material-dark,
25
+ * material-light, midnight-ocean, solarized-dark, or a name given to `defineTheme`.
26
+ */
24
27
  theme?: string;
25
28
  /** In CSS pixels. */
26
29
  fontSize?: number;
27
- wordWrap?: 'on' | 'off';
30
+ /**
31
+ * Monaco's `fontFamily`, a CSS font list: the first name in it given to `registerFont` is the
32
+ * editor's font, else the bundled JetBrains Mono. A font the page has only in CSS is not seen: the
33
+ * editor draws on a canvas, with the fonts it was given.
34
+ */
35
+ fontFamily?: string;
36
+ /**
37
+ * Monaco's `wordWrap`: `'on'` wraps at the edge of the view, `'wordWrapColumn'` and `'bounded'`
38
+ * at `wordWrapColumn` or the edge, whichever comes first. `'off'` by default, as Monaco's (on
39
+ * before 0.10).
40
+ */
41
+ wordWrap?: 'on' | 'off' | 'wordWrapColumn' | 'bounded';
42
+ /** Where `wordWrap: 'wordWrapColumn'` or `'bounded'` wraps. 80 by default. */
43
+ wordWrapColumn?: number;
44
+ /** How wrapped rows are indented, as Monaco's. `'none'` by default, where Monaco's is `'same'`. */
45
+ wrappingIndent?: 'none' | 'same' | 'indent' | 'deepIndent';
46
+ /**
47
+ * Monaco's `lineNumbers`: `'relative'` counts from the caret's line, `'interval'` shows every
48
+ * tenth and the caret's. Monaco's function form is not taken: it counts as `'on'`.
49
+ */
50
+ lineNumbers?: 'on' | 'off' | 'relative' | 'interval';
51
+ /** Columns with a vertical line. Monaco's `{ column, color }` takes its column; the colour is the theme's. */
52
+ rulers?: Array<number | { column: number; color?: string | null }>;
53
+ /**
54
+ * Monaco's `guides`: `indentation`, a faint line down each level of indentation (the caret's
55
+ * block's stronger), and `bracketPairs`, a line from each bracket to its partner (`'active'`
56
+ * shows them all). Both off by default, where Monaco's indentation guides are on.
57
+ */
58
+ guides?: { indentation?: boolean; bracketPairs?: boolean | 'active' };
59
+ /** The caret's shape. `'line'` by default. */
60
+ cursorStyle?: 'line' | 'block' | 'underline' | 'line-thin' | 'block-outline' | 'underline-thin';
61
+ /** How the caret blinks; `'phase'` and `'expand'` fade as `'smooth'` does. `'blink'` by default. */
62
+ cursorBlinking?: 'blink' | 'smooth' | 'phase' | 'expand' | 'solid';
63
+ /** The editor's own scrolls (to the caret, Page Up and Down) animate. Off by default. */
64
+ smoothScrolling?: boolean;
65
+ /** The last line can scroll up to the top of the view. Off by default, where Monaco's is on. */
66
+ scrollBeyondLastLine?: boolean;
67
+ /** Lines kept visible above and below the caret as it moves. 0 by default. */
68
+ cursorSurroundingLines?: number;
69
+ /**
70
+ * A selection dragged with the mouse moves; with Ctrl (Alt on macOS) held, copies. Off by
71
+ * default, where Monaco's is on.
72
+ */
73
+ dragAndDrop?: boolean;
28
74
  readOnly?: boolean;
29
75
  showGutter?: boolean;
30
76
  showLineNumbers?: boolean;
@@ -60,6 +106,33 @@ export interface AardinkOptions {
60
106
  breadcrumbs?: boolean;
61
107
  /** The font's ligatures; on by default. */
62
108
  fontLigatures?: boolean;
109
+ /** Colours what a language server's semantic tokens say over the syntax's. Off by default. */
110
+ semanticHighlighting?: boolean;
111
+ /**
112
+ * Shows what `provideInlayHints` or a language server says, among the characters of the lines
113
+ * around the view. Off by default. Takes Monaco's `{ enabled }` too; with `'onUnlessPressed'` and
114
+ * `'offUnlessPressed'` no key is watched, so they mean on and off.
115
+ */
116
+ inlayHints?: boolean | { enabled?: boolean | 'on' | 'off' | 'onUnlessPressed' | 'offUnlessPressed' };
117
+ /**
118
+ * Shows what `provideCodeLenses` or a language server says, in a row above its lines. Off by
119
+ * default, where Monaco's is on.
120
+ */
121
+ codeLens?: boolean;
122
+ /**
123
+ * Typing one of `autoFormatTriggerCharacters` asks `provideOnTypeFormattingEdits` (or a language
124
+ * server) to tidy the text around it, as Monaco's `formatOnType`. Undo takes the edits back and
125
+ * keeps what was typed. Off by default.
126
+ */
127
+ formatOnType?: boolean;
128
+ }
129
+
130
+ /** What `onSearchWorkspace` is called with: VS Code's Find in Files arguments. */
131
+ export interface AardinkWorkspaceSearch {
132
+ query: string;
133
+ isRegex: boolean;
134
+ isCaseSensitive: boolean;
135
+ matchWholeWord: boolean;
63
136
  }
64
137
 
65
138
  /**
@@ -233,7 +306,9 @@ export interface AardinkEditor {
233
306
  * `editor.action.changeAll`, `editor.action.insertCursorAtEndOfEachLineSelected`,
234
307
  * `editor.action.addCommentLine`, `editor.action.removeCommentLine`, `editor.action.blockComment`,
235
308
  * `editor.action.insertLineAfter` and `Before`, `expandLineSelection`,
236
- * `editor.action.showColorPicker`, and
309
+ * `editor.action.showColorPicker`, `editor.action.inlineSuggest.commit`, `.showNext`,
310
+ * `.showPrevious` and `.hide`, VS Code's `workbench.action.findInFiles` (with an
311
+ * `onSearchWorkspace` listener), and
237
312
  * `editor.action.insertSnippet` with `{ snippet }`. `source` is accepted for Monaco's shape.
238
313
  * Returns whether it ran.
239
314
  */
@@ -278,6 +353,22 @@ export interface AardinkEditor {
278
353
  getScrollHeight(): number;
279
354
  /** Called as the text scrolls. Returns an unsubscribe function. */
280
355
  onDidScrollChange(listener: (event: { scrollTop: number; scrollLeft: number; scrollHeight: number }) => void): () => void;
356
+ /**
357
+ * Called with the target of every link opened in the editor, by Ctrl/Cmd+click on a URL in the
358
+ * text or a click in a hover, signature help or completion card, whatever its scheme. A target
359
+ * can come from a language server, so check it before following it: it may be `javascript:`. With
360
+ * no listener, `http` and `https` links open in a new tab with `noopener`, and anything else does
361
+ * nothing. Returns a disposable.
362
+ */
363
+ onOpenLink(listener: (target: string) => void): { dispose(): void };
364
+ /**
365
+ * Called when the editor hands a search to the page, by Ctrl/Cmd+Shift+F, the find panel's
366
+ * "Search all files" button or `trigger('workbench.action.findInFiles')`, with VS Code's Find in
367
+ * Files arguments: the selection on one line, else the find panel's query, and its options. While
368
+ * there is no listener, the button is not shown and the key is left to the page. Returns a
369
+ * disposable.
370
+ */
371
+ onSearchWorkspace(listener: (search: AardinkWorkspaceSearch) => void): { dispose(): void };
281
372
  /** Measures the container again now; the editor follows its container's size by itself. */
282
373
  layout(): void;
283
374
  /**
@@ -373,10 +464,17 @@ export interface AardinkLanguageDefinition {
373
464
  id: string;
374
465
  /**
375
466
  * A subset of Monaco's Monarch: states in `tokenizer` (`root` first), rules of
376
- * `[regex, action, next?]`, `cases` with `@array`/`@default`/`@eos`, capture groups (each
377
- * with a token name, `{ token, next }` or `cases` of its own), `include`, `@rematch`,
378
- * `defaultToken`, `ignoreCase`, `tokenPostfix`. RegExp literals are fine. Lookbehind is not
379
- * supported, and is refused.
467
+ * `[regex, action, next?]`, `cases`, capture groups (each with a token name, `{ token, next }`
468
+ * or `cases` of its own), `include`, `@rematch`, `switchTo`, `goBack`, `@brackets` with a
469
+ * top-level `brackets`, `defaultToken`, `ignoreCase`, `tokenPostfix`, and `@name` in a regex
470
+ * for the top-level string `name`, as a group of its own. A guard is
471
+ * `@default`, `@eos`, or a subject of `$#` or `$S0`, `$S1`... then `@array`, `~regex`, `==text`
472
+ * or `!@`, `!~`, `!=`, as in `$#==$S2`; `next` and `switchTo` take `$#` and `$Sn` too. `log` is
473
+ * accepted and ignored. RegExp literals are fine. Lookbehind and `$` in a token name are
474
+ * refused, as is `goBack` in a capture group's action. `nextEmbedded` hands the text to the
475
+ * grammar of the language registered with that id, before or after this one, and
476
+ * `nextEmbedded: '@pop'` takes it back; with no such language, the text stays on this grammar.
477
+ * A built-in language has no grammar, so it cannot be embedded.
380
478
  */
381
479
  grammar: object;
382
480
  /** A built-in or registered language whose completions, diagnostics, hover and folding this one takes too, e.g. `'xml'`. */
@@ -400,6 +498,66 @@ export interface AardinkLanguageDefinition {
400
498
  * checks, closing tags and formatting when it extends none). Your providers still come first.
401
499
  */
402
500
  schema?: AardinkXmlSchema;
501
+ /**
502
+ * What the language says about typing, as VS Code's `language-configuration.json`: the object,
503
+ * or the file's text, which may have comments and trailing commas. Regular expressions are
504
+ * refused with a lookbehind. Its `comments` replace the definition's.
505
+ */
506
+ configuration?: AardinkLanguageConfiguration | string;
507
+ }
508
+
509
+ /** A regular expression in a language configuration: VS Code's two forms, or a RegExp literal. */
510
+ export type AardinkConfigurationRegExp = string | RegExp | { pattern: string; flags?: string };
511
+
512
+ /** An opening and a closing text, such as `['(', ')']`. */
513
+ export type AardinkCharacterPair = [string, string] | { open: string; close: string };
514
+
515
+ /**
516
+ * `registerLanguage`'s `configuration`. Every field is optional. As in VS Code, without
517
+ * `autoClosingPairs` the brackets close themselves, and without `surroundingPairs` those pairs
518
+ * surround. `wordPattern`, `autoCloseBefore` and `folding.offSide` are not read.
519
+ */
520
+ export interface AardinkLanguageConfiguration {
521
+ /** What Ctrl/Cmd+/ comments with. */
522
+ comments?: { lineComment?: string | { comment: string }; blockComment?: [string, string] };
523
+ /** Pairs the language nests: Enter indents after an opening one. Matching and colouring brackets stay `()[]{}`. */
524
+ brackets?: AardinkCharacterPair[];
525
+ /**
526
+ * Closed when the opening text is typed. `notIn` (`'string'`, `'comment'`) is worked out from the
527
+ * caret's own line, so a block comment opened on an earlier line is not seen.
528
+ */
529
+ autoClosingPairs?: (AardinkCharacterPair | { open: string; close: string; notIn?: string[] })[];
530
+ /** Wrap a selection when the opening text, one character, is typed over it. */
531
+ surroundingPairs?: AardinkCharacterPair[];
532
+ /** What Enter does, the first rule that matches. */
533
+ onEnterRules?: AardinkOnEnterRule[];
534
+ /** What Enter does when no rule and no bracket decides. */
535
+ indentationRules?: {
536
+ increaseIndentPattern?: AardinkConfigurationRegExp;
537
+ decreaseIndentPattern?: AardinkConfigurationRegExp;
538
+ indentNextLinePattern?: AardinkConfigurationRegExp;
539
+ unIndentedLinePattern?: AardinkConfigurationRegExp;
540
+ };
541
+ /** Lines that open and close a fold region. */
542
+ folding?: { markers?: { start: AardinkConfigurationRegExp; end: AardinkConfigurationRegExp } };
543
+ }
544
+
545
+ /** One of `onEnterRules`: every regular expression given must match. */
546
+ export interface AardinkOnEnterRule {
547
+ /** Against the text before the caret. */
548
+ beforeText?: AardinkConfigurationRegExp;
549
+ /** Against the text after the caret. */
550
+ afterText?: AardinkConfigurationRegExp;
551
+ /** Against the line above the one Enter was pressed on. */
552
+ previousLineText?: AardinkConfigurationRegExp;
553
+ action: {
554
+ /** `indentOutdent` leaves the closer at the opener's indentation and adds no line in between. */
555
+ indent: 'none' | 'indent' | 'outdent' | 'indentOutdent';
556
+ /** What the new line starts with after its indentation. Not used with `indentOutdent`. */
557
+ appendText?: string;
558
+ /** Characters taken off the end of the indentation. */
559
+ removeText?: number;
560
+ };
403
561
  }
404
562
 
405
563
  /** An XML vocabulary, for `registerLanguage`'s `schema`. */
@@ -466,8 +624,7 @@ export interface AardinkModelDeltaDecoration {
466
624
  /**
467
625
  * Monaco's `IModelDecorationOptions`, as far as the editor draws them. Where Monaco takes a CSS
468
626
  * class (`className`, `inlineClassName`, `linesDecorationsClassName`), give a colour instead: CSS
469
- * hex, `#rgb`, `#rgba`, `#rrggbb` or `#rrggbbaa`. Nothing here changes the text's layout, so
470
- * Monaco's `before` and `after` are not read.
627
+ * hex, `#rgb`, `#rgba`, `#rrggbb` or `#rrggbbaa`.
471
628
  */
472
629
  export interface AardinkDecorationOptions {
473
630
  /** Behind the characters; behind whole lines with `isWholeLine`. */
@@ -478,6 +635,15 @@ export interface AardinkDecorationOptions {
478
635
  underlineColor?: string;
479
636
  /** A bar at the gutter's text edge on each line, as Monaco's `linesDecorationsClassName` places one. */
480
637
  gutterColor?: string;
638
+ /** The colour of the range's characters, in place of Monaco's `inlineClassName`, and of `before` and `after`. */
639
+ inlineColor?: string;
640
+ /**
641
+ * Text in front of the range, as Monaco's `before`. It is not in the document, moves with the range,
642
+ * and is drawn in `inlineColor`, or faintly without it. `content` is all that is read, on one row.
643
+ */
644
+ before?: { content: string };
645
+ /** Text behind the range, as Monaco's `after`, by the same rules as `before`. */
646
+ after?: { content: string };
481
647
  isWholeLine?: boolean;
482
648
  hoverMessage?: string | { value: string } | Array<string | { value: string }>;
483
649
  overviewRuler?: { color: string; position?: number };
@@ -518,11 +684,11 @@ export interface AardinkCompletionItem {
518
684
  | 'method' | 'constructor' | 'field' | 'variable' | 'class' | 'struct' | 'interface' | 'enum' | 'enumMember' | 'keyword'
519
685
  | 'text' | 'file' | 'folder' | 'reference' | 'constant' | 'event' | 'operator' | 'typeParameter' | 'unit' | 'user' | 'issue'
520
686
  | number;
521
- /** A short line about the item, such as a type or a signature, shown beside the label. */
687
+ /** A short line about the item, such as a type or a signature, shown beside the label and above its `documentation`. */
522
688
  detail?: string;
523
689
  /** Characters that, typed while this item is selected, accept it and are then typed after it. Not for snippets. */
524
690
  commitCharacters?: string[];
525
- /** Shown beside the label; Monaco's `{ value }` is shown as plain text. */
691
+ /** Markdown, either way. Shown beside the label as one line of plain text, and whole beside the list for the selected item. */
526
692
  documentation?: string | { value: string };
527
693
  /**
528
694
  * What the text typed so far is matched against, as in Monaco: its characters in order, ignoring
@@ -555,7 +721,7 @@ export interface AardinkCompletionList {
555
721
 
556
722
  export interface AardinkHover {
557
723
  title?: string;
558
- /** Plain text. */
724
+ /** Markdown. Raw HTML shows as written. A link goes to `onOpenLink`, or to a new tab for `http` and `https`. */
559
725
  contents: string;
560
726
  /** Shown as code below `contents`. */
561
727
  example?: string;
@@ -594,6 +760,183 @@ export interface AardinkLanguageProviders {
594
760
  * picked in the editor's picker is written back as CSS hex (`#rrggbb`, `#rrggbbaa`).
595
761
  */
596
762
  provideDocumentColors?(text: string): AardinkColorInformation[] | null | Promise<AardinkColorInformation[] | null>;
763
+ /**
764
+ * Labels shown among the characters of `range`, as Monaco's `provideInlayHints`, with the
765
+ * `inlayHints` option on. `range` holds whole lines around the view: it is asked after a pause in
766
+ * typing, in scrolling past what it last asked about, or after a fold opens or closes. A long closed
767
+ * fold on screen makes that a few calls at once, one for the lines on either side of it. With
768
+ * `extends`, the base language's are added, less any at a position this has one at. With a language
769
+ * server these are shown after a second if it has not answered by then.
770
+ */
771
+ provideInlayHints?(text: string, range: AardinkRange): AardinkInlayHint[] | null | Promise<AardinkInlayHint[] | null>;
772
+ /**
773
+ * What is shown in a row above the line each `range` starts on, as Monaco's `provideCodeLenses`,
774
+ * with the `codeLens` option on. It is about the whole text, and asked after a pause in typing;
775
+ * between answers each lens moves with its text. Lenses on one line share a row. An array, with no
776
+ * `{ lenses }` around it. A lens without a `command` is given to `resolveCodeLens`, if there is
777
+ * one, as the answer comes (at most 100 of them), and left out if it still has none. With
778
+ * `extends`, the base language's are added, less any with this one's position and title. With a
779
+ * language server these are shown after a second if it has not answered by then.
780
+ */
781
+ provideCodeLenses?(text: string): AardinkCodeLens[] | null | Promise<AardinkCodeLens[] | null>;
782
+ /**
783
+ * A lens from `provideCodeLenses` was clicked or tapped, or a code action from `provideCodeActions`
784
+ * with a `command` chosen (after its edits): the command's `id`, and its `arguments`, `[]` when it
785
+ * has none. As they passed through JSON, they hold only what JSON can. There is no command
786
+ * registry behind this: a lens or an action does what this does with its `id`.
787
+ */
788
+ runCodeLensCommand?(id: string, args: unknown[]): void | Promise<void>;
789
+ /**
790
+ * The characters whose typing asks `provideOnTypeFormattingEdits`, as on Monaco's
791
+ * `OnTypeFormattingEditProvider`: `'}'`, `';'`, or `'\n'` for Enter.
792
+ */
793
+ autoFormatTriggerCharacters?: string[];
794
+ /**
795
+ * Edits that tidy the text around what was just typed, as Monaco's `provideOnTypeFormattingEdits`,
796
+ * with the `formatOnType` option on. `line` and `column` are the caret's, after the character `ch`;
797
+ * the edits are applied as an undo step of their own, and dropped if the text changed while they
798
+ * were worked out. With `extends`, the base language's apply when this answers none.
799
+ */
800
+ provideOnTypeFormattingEdits?(
801
+ text: string,
802
+ line: number,
803
+ column: number,
804
+ ch: string,
805
+ options: { tabSize: number; insertSpaces: boolean },
806
+ ): AardinkTextEdit[] | null | Promise<AardinkTextEdit[] | null>;
807
+ /**
808
+ * Where the symbol at a 1-based `line` and `column` is defined, as Monaco's `provideDefinition`,
809
+ * for F12 and Ctrl/Cmd+click: a location, an array of them (the first is followed) or Monaco's
810
+ * `LocationLink`s. A location without `uri` is in this text; one with a `uri` is another file's,
811
+ * which the editor does not open.
812
+ */
813
+ provideDefinition?(text: string, line: number, column: number): AardinkLocation | AardinkLocation[] | null | Promise<AardinkLocation | AardinkLocation[] | null>;
814
+ /** The references to the symbol at a place, as Monaco's `provideReferences`, for Shift+F12's list. */
815
+ provideReferences?(text: string, line: number, column: number): AardinkLocation[] | null | Promise<AardinkLocation[] | null>;
816
+ /**
817
+ * Edits that format the whole text, as Monaco's `provideDocumentFormattingEdits`, for Format
818
+ * Document (Shift+Alt+F) and `format()`. With `extends`, the base language formats when this
819
+ * changes nothing.
820
+ */
821
+ provideDocumentFormattingEdits?(text: string, options: { tabSize: number; insertSpaces: boolean }): AardinkTextEdit[] | null | Promise<AardinkTextEdit[] | null>;
822
+ /** Edits that format `range`, as Monaco's `provideDocumentRangeFormattingEdits`, for Format Selection. */
823
+ provideDocumentRangeFormattingEdits?(
824
+ text: string,
825
+ range: AardinkRange,
826
+ options: { tabSize: number; insertSpaces: boolean },
827
+ ): AardinkTextEdit[] | null | Promise<AardinkTextEdit[] | null>;
828
+ /**
829
+ * Accepted for Monaco's shape. The editor asks `provideSignatureHelp` whenever the caret is
830
+ * inside a call's arguments, so no character has to start it.
831
+ */
832
+ signatureHelpTriggerCharacters?: string[];
833
+ /**
834
+ * The signatures of the call at a place, as Monaco's `provideSignatureHelp`: its
835
+ * `SignatureHelpResult` (`{ value }`) or the `SignatureHelp` in it. A parameter's `label` is its
836
+ * text or `[start, end]` in the signature's label.
837
+ */
838
+ provideSignatureHelp?(text: string, line: number, column: number): AardinkSignatureHelp | { value: AardinkSignatureHelp } | null | Promise<AardinkSignatureHelp | { value: AardinkSignatureHelp } | null>;
839
+ /**
840
+ * Quick fixes and refactorings for `range`, as Monaco's `provideCodeActions`, with the markers of
841
+ * `provideDiagnostics`' last answer that touch it. An action with edits to another file (a
842
+ * `resource`) is left out; its `command` goes to `runCodeLensCommand` after its edits.
843
+ */
844
+ provideCodeActions?(
845
+ text: string,
846
+ range: AardinkRange,
847
+ context: { markers: AardinkDiagnostic[] },
848
+ ): AardinkCodeAction[] | { actions: AardinkCodeAction[] } | null | Promise<AardinkCodeAction[] | { actions: AardinkCodeAction[] } | null>;
849
+ /**
850
+ * The edits that rename the symbol at a place to `newName`, as Monaco's `provideRenameEdits`, for
851
+ * F2. Its presence offers rename. `{ rejectReason }`, or edits to another file, rename nothing.
852
+ */
853
+ provideRenameEdits?(text: string, line: number, column: number, newName: string): AardinkWorkspaceEdit | { rejectReason: string } | null | Promise<AardinkWorkspaceEdit | { rejectReason: string } | null>;
854
+ /**
855
+ * What F2 would rename at a place, as Monaco's `resolveRenameLocation`: `{ range, text }`, or
856
+ * `{ rejectReason }` where nothing can be. Without it, the word at the caret.
857
+ */
858
+ resolveRenameLocation?(text: string, line: number, column: number): { range: AardinkRange; text: string } | { rejectReason: string } | null | Promise<{ range: AardinkRange; text: string } | { rejectReason: string } | null>;
859
+ /**
860
+ * The text's folds, as Monaco's `provideFoldingRanges`: 1-based `start` and `end` lines. They
861
+ * replace the language's own (by indentation, or the base language's).
862
+ */
863
+ provideFoldingRanges?(text: string): { start: number; end: number; kind?: 'comment' | 'imports' | 'region' }[] | null | Promise<{ start: number; end: number; kind?: 'comment' | 'imports' | 'region' }[] | null>;
864
+ /**
865
+ * What `provideDocumentSemanticTokens` numbers stand for, as Monaco's `getLegend()`. The token
866
+ * types are named as a theme colours them, as a language server's are: `class` as `type.class`,
867
+ * `parameter` as `variable.parameter`, `method` as `function.method`.
868
+ */
869
+ getLegend?(): { tokenTypes: string[]; tokenModifiers: string[] };
870
+ /** The legend as data, in place of `getLegend`. */
871
+ legend?: { tokenTypes: string[]; tokenModifiers: string[] };
872
+ /**
873
+ * The text's semantic tokens, as Monaco's `provideDocumentSemanticTokens`: `{ data }`, five
874
+ * integers a token, coloured over the syntax's with the `semanticHighlighting` option on.
875
+ */
876
+ provideDocumentSemanticTokens?(text: string): { data: ArrayLike<number>; resultId?: string } | null | Promise<{ data: ArrayLike<number>; resultId?: string } | null>;
877
+ /**
878
+ * More of an item, as Monaco's `resolveCompletionItem`: called with the item as
879
+ * `provideCompletionItems` gave it when it is selected in the list; its `documentation` and
880
+ * `detail` replace what the item had.
881
+ */
882
+ resolveCompletionItem?(item: AardinkCompletionItem): AardinkCompletionItem | null | Promise<AardinkCompletionItem | null>;
883
+ /** A lens that came without a `command`, with one, as Monaco's `resolveCodeLens`. */
884
+ resolveCodeLens?(text: string, lens: AardinkCodeLens): AardinkCodeLens | null | Promise<AardinkCodeLens | null>;
885
+ }
886
+
887
+ /** Monaco's `Location`: `uri` left out for a place in this text. */
888
+ export interface AardinkLocation {
889
+ uri?: string;
890
+ range: AardinkRange;
891
+ }
892
+
893
+ /** Monaco's `SignatureHelp`. */
894
+ export interface AardinkSignatureHelp {
895
+ signatures: {
896
+ label: string;
897
+ documentation?: string | { value: string };
898
+ parameters: { label: string | [number, number]; documentation?: string | { value: string } }[];
899
+ }[];
900
+ activeSignature: number;
901
+ activeParameter: number;
902
+ }
903
+
904
+ /** Monaco's `WorkspaceEdit`, for this text: an edit with a `resource` is another file's. */
905
+ export interface AardinkWorkspaceEdit {
906
+ edits: { resource?: unknown; textEdit: AardinkTextEdit }[];
907
+ }
908
+
909
+ /** Monaco's `CodeAction`, as far as the editor reads one. */
910
+ export interface AardinkCodeAction {
911
+ title: string;
912
+ /** `'quickfix'`, `'refactor...'` or `'source.organizeImports'`. */
913
+ kind?: string;
914
+ isPreferred?: boolean;
915
+ edit?: AardinkWorkspaceEdit;
916
+ command?: { id: string; title?: string; arguments?: unknown[] };
917
+ }
918
+
919
+ /** Monaco's `TextEdit`: `text` in place of `range`. */
920
+ export interface AardinkTextEdit {
921
+ range: AardinkRange;
922
+ text: string | null;
923
+ }
924
+
925
+ /**
926
+ * Monaco's `CodeLens`: a title in a row above the line `range` starts on. One without a `command`
927
+ * is shown once `resolveCodeLens` gives it one.
928
+ */
929
+ export interface AardinkCodeLens {
930
+ range: AardinkRange;
931
+ command?: { id: string; title: string; arguments?: unknown[] };
932
+ }
933
+
934
+ /** Monaco's `InlayHint`, as far as the editor draws it: a label at a position, in front of the character there. */
935
+ export interface AardinkInlayHint {
936
+ position: AardinkPosition;
937
+ label: string;
938
+ /** Shown, as Markdown, in a card under a mouse resting on the label; Monaco's `{ value }` too. */
939
+ tooltip?: string | { value: string };
597
940
  }
598
941
 
599
942
  /** Monaco's `IColorInformation`: where a colour is written, and the colour, each channel from 0 to 1. */
@@ -609,7 +952,12 @@ export function registerLanguage(definition: AardinkLanguageDefinition, provider
609
952
  * Monaco's `defineTheme` data. Token rules name tokens as Monaco does, and the longest matching
610
953
  * prefix wins: `tag` also colours `tag.aardflex`, `comment.doc` only documentation comments. A
611
954
  * rule's `fontStyle` (`'bold'`, `'italic'`, `'underline'`, `'strikethrough'`, or `''` for none)
612
- * applies too; its `background` is accepted, so Monaco theme data passes as it is, and ignored.
955
+ * applies too, and its `background` is drawn behind the token's text; the empty token's sets the
956
+ * editor's. `colors` takes VS Code's keys, the editor's chrome too (`minimap.background`,
957
+ * `scrollbarSlider.background`, `editorIndentGuide.background1`, `editorRuler.foreground`,
958
+ * `editorWidget.background`, `.foreground` and `.border`, `editorInlayHint.foreground`,
959
+ * `editorCodeLens.foreground`, `editorGhostText.foreground`...). `hc-black` and `hc-light` fill in
960
+ * from the high-contrast themes.
613
961
  */
614
962
  export interface AardinkThemeData {
615
963
  base: 'vs' | 'vs-dark' | 'hc-black' | 'hc-light';
@@ -621,9 +969,93 @@ export interface AardinkThemeData {
621
969
  /** Adds a theme for `createEditor`'s `theme` option: Monaco's `defineTheme` data, or a VS Code theme's JSON. */
622
970
  export function registerTheme(name: string, theme: AardinkThemeData | object): Promise<void>;
623
971
 
972
+ /**
973
+ * Connects to the language server at a WebSocket URL, which carries one JSON-RPC message per frame,
974
+ * and has it follow every editor of `languageId`: those open now, those created later, and those
975
+ * switched to it with `updateOptions`. Each is a document of its own to the server, under a
976
+ * generated `file:///aardink/` URI.
977
+ *
978
+ * What the server knows joins what the language has. The providers of a language from
979
+ * `registerLanguage` answer first, the server fills in, and the language it extends comes last; a
980
+ * built-in language's answers come after the server's. Either way Enter, closing pairs and surrounding a selection stay the language's,
981
+ * even where it does nothing, and an editor with no language service, such as plain text, types as
982
+ * it does without a server. Completions, diagnostics, code actions, references, links and colours
983
+ * come from both, and what a server pushes shows after a pause in typing.
984
+ *
985
+ * Resolves once the connection has been asked for, not once it is up. A server that cannot be
986
+ * reached, or that drops later, is said on the console and the editors go on with their language's
987
+ * own service. Nothing reconnects by itself: call this again for that. A rename reaching other
988
+ * files, and `workspace/applyEdit`, are refused. `dispose()` closes each document and shuts the
989
+ * server down.
990
+ */
991
+ export function connectLanguageServer(url: string | URL, languageId: string): Promise<{ dispose(): void }>;
992
+
993
+ /** What `provideInlineCompletions` offers: Monaco's `InlineCompletions`, or just its `items`. */
994
+ export interface AardinkInlineCompletions {
995
+ items: AardinkInlineCompletion[];
996
+ }
997
+
998
+ /**
999
+ * Monaco's `InlineCompletion`, as far as the editor shows it. A `{ snippet }` shows what it expands
1000
+ * to (a placeholder as its default text, a choice as its first), and accepting it replaces the whole
1001
+ * `range` with the snippet, as in Monaco, so Tab then steps through its tab stops.
1002
+ *
1003
+ * `range` is what it replaces, and must hold the caret. What `insertText` repeats of it is not shown
1004
+ * again: over `)`, the text `x) {` shows `x` before the bracket and ` {` after it, which is how ghost
1005
+ * text keeps from doubling what follows the caret. So it has to hold all of `range`, in order, or it
1006
+ * does not show, as in Monaco. An empty `range` is a plain insertion.
1007
+ *
1008
+ * Without `range`, it replaces the word at the caret and the rest of the line, as in Monaco. Where
1009
+ * Monaco then shows nothing for text that does not hold them, this tries the rest of the line alone,
1010
+ * and then puts the text in at the caret, so a provider that only knows what comes next can leave
1011
+ * `range` out. Text the document has already, from the caret on or from the word's start to the caret
1012
+ * or past it, shows nothing.
1013
+ */
1014
+ export interface AardinkInlineCompletion {
1015
+ insertText: string | { snippet: string };
1016
+ range?: AardinkRange;
1017
+ }
1018
+
1019
+ /** Monaco's `InlineCompletionsProvider`, as far as the editor asks one anything. */
1020
+ export interface AardinkInlineCompletionsProvider {
1021
+ /**
1022
+ * What might come next at a 1-based `line` and `column`, best first: the first shows, and Alt+] and
1023
+ * Alt+[ go through the others. Asked once typing pauses, not for each key, and at once after one
1024
+ * is accepted, or by `editor.action.inlineSuggest.showNext` with none showing. While one shows,
1025
+ * typing what it says asks nothing. An answer for text that has moved on is dropped; there is no
1026
+ * cancellation token, so the work behind it is not told to stop.
1027
+ */
1028
+ provideInlineCompletions(
1029
+ text: string,
1030
+ line: number,
1031
+ column: number,
1032
+ ): AardinkInlineCompletions | AardinkInlineCompletion[] | null | Promise<AardinkInlineCompletions | AardinkInlineCompletion[] | null>;
1033
+ }
1034
+
1035
+ /**
1036
+ * Has `provider` offer ghost text in every editor of `languageId`, open now or to come, as Monaco's
1037
+ * `languages.registerInlineCompletionsProvider`. Several for one language are all asked, and their
1038
+ * answers follow each other, oldest first. Tab accepts, as one undo step; Alt+] and Alt+[ go through
1039
+ * what is on offer; Escape dismisses, until the next edit asks again. A phone has neither key, so run
1040
+ * `editor.action.inlineSuggest.commit` and `.hide` from buttons: `getAction` says whether anything
1041
+ * shows. Nothing shows in a read-only editor, with a selection or several carets, while filling in a
1042
+ * snippet, while an input method composes, or under an open completion list, which takes Tab.
1043
+ * `dispose()` ends it.
1044
+ */
1045
+ export function registerInlineCompletionsProvider(
1046
+ languageId: string,
1047
+ provider: AardinkInlineCompletionsProvider,
1048
+ ): Promise<{ dispose(): void }>;
1049
+
624
1050
  /** Monaco's name for `registerTheme`. */
625
1051
  export const defineTheme: typeof registerTheme;
626
1052
 
1053
+ /**
1054
+ * Adds a font for the `fontFamily` option: a TrueType or OpenType file, by URL (fetched) or as its
1055
+ * bytes. Editors naming it change to it at once. A monospaced font is meant.
1056
+ */
1057
+ export function registerFont(name: string, urlOrBytes: string | URL | ArrayBuffer | ArrayBufferView): Promise<void>;
1058
+
627
1059
  /**
628
1060
  * Mounts an editor that fills `container`. Loads the WebAssembly module on first use (see
629
1061
  * `preloadAardink`). `onChange` is registered as the first content listener.