@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 +68 -2
- package/index.d.ts +445 -13
- package/index.js +171 -37
- package/kotlin/aardink-web.import-object.mjs +38 -2
- package/kotlin/aardink-web.mjs +7 -0
- package/kotlin/aardink-web.wasm +0 -0
- package/package.json +1 -1
- package/kotlin/js-reexport-symbols.mjs +0 -999
- package/kotlin/skikod8.mjs +0 -1118
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
|
|
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
|
|
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
|
-
/**
|
|
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
|
-
|
|
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`,
|
|
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
|
|
377
|
-
*
|
|
378
|
-
* `defaultToken`, `ignoreCase`, `tokenPostfix
|
|
379
|
-
*
|
|
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`.
|
|
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
|
|
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
|
-
/**
|
|
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
|
|
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.
|