@aardarch/aardink-web 0.7.0 → 0.8.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/index.d.ts CHANGED
@@ -48,6 +48,18 @@ export interface AardinkOptions {
48
48
  * option; Monaco's `{ other, comments, strings }` works too, `other` deciding. Off by default.
49
49
  */
50
50
  quickSuggestions?: boolean | { other?: boolean | 'on' | 'off' | 'inline'; comments?: unknown; strings?: unknown };
51
+ /** The overview ruler at the right edge, as Monaco's `overviewRulerLanes` above 0. Off by default. */
52
+ overviewRulerLanes?: number;
53
+ /** Highlights the other occurrences of the symbol at the caret. Off by default. */
54
+ occurrencesHighlight?: boolean | 'off' | 'singleFile';
55
+ /** Typing a tag name changes its partner. Off by default. */
56
+ linkedEditing?: boolean;
57
+ /** Swatches under the colours in the text, with a picker. Off by default. */
58
+ colorDecorators?: boolean;
59
+ /** The path of symbols at the caret, in a row above the text. Off by default. */
60
+ breadcrumbs?: boolean;
61
+ /** The font's ligatures; on by default. */
62
+ fontLigatures?: boolean;
51
63
  }
52
64
 
53
65
  /**
@@ -213,7 +225,15 @@ export interface AardinkEditor {
213
225
  * `editor.action.goToReferences`, `editor.action.marker.next`, `editor.action.marker.prev`,
214
226
  * `actions.find`, `editor.action.startFindReplaceAction`, `editor.action.gotoLine`,
215
227
  * `editor.foldAll`, `editor.unfoldAll`, `editor.foldLevel1` to `7`, `undo`, `redo`,
216
- * `editor.action.commentLine`, `editor.action.selectHighlights`, and
228
+ * `editor.action.commentLine`, `editor.action.selectHighlights`, `editor.action.quickOutline`,
229
+ * `editor.action.smartSelect.expand` and `.shrink`, `editor.fold`, `editor.unfold`,
230
+ * `editor.action.joinLines`, `editor.action.sortLinesAscending` and `Descending`,
231
+ * `editor.action.transformToUppercase` and `Lowercase`, `editor.action.trimTrailingWhitespace`,
232
+ * `editor.action.jumpToBracket`, `cursorUndo`, `editor.action.moveSelectionToNextFindMatch`,
233
+ * `editor.action.changeAll`, `editor.action.insertCursorAtEndOfEachLineSelected`,
234
+ * `editor.action.addCommentLine`, `editor.action.removeCommentLine`, `editor.action.blockComment`,
235
+ * `editor.action.insertLineAfter` and `Before`, `expandLineSelection`,
236
+ * `editor.action.showColorPicker`, and
217
237
  * `editor.action.insertSnippet` with `{ snippet }`. `source` is accepted for Monaco's shape.
218
238
  * Returns whether it ran.
219
239
  */
@@ -222,7 +242,9 @@ export interface AardinkEditor {
222
242
  * Monaco's `addCommand`: `handler` runs when `keybinding` is pressed in the editor, ahead of the
223
243
  * editor's own binding for it. A keybinding is text such as `'CtrlCmd+S'`, `'Shift+Alt+F'` or
224
244
  * `'F8'` (`CtrlCmd` is Cmd on macOS and Ctrl elsewhere; `Ctrl` is Ctrl everywhere), or Monaco's
225
- * `KeyMod | KeyCode` number for a letter, digit, function, navigation or punctuation key.
245
+ * `KeyMod | KeyCode` number for a letter, digit, function, navigation or punctuation key. A
246
+ * chord of two keys is `'CtrlCmd+K CtrlCmd+S'` or `KeyMod.chord(...)`; its first key then starts
247
+ * your chords only, not the editor's own with the same first key.
226
248
  * Returns the command's id, for `trigger`; null for a keybinding it cannot read.
227
249
  */
228
250
  addCommand(keybinding: string | number, handler: () => void): string | null;
@@ -237,7 +259,27 @@ export interface AardinkEditor {
237
259
  * Shows these diagnostics in place of the language's own; `null` goes back to the language's
238
260
  * own. Either way they move along with the text as it is edited, until the next list.
239
261
  */
240
- setDiagnostics(diagnostics: AardinkDiagnostic[] | null): void;
262
+ /**
263
+ * Without `owner`: shows `diagnostics` in place of the language's own, or the language's own
264
+ * again for `null`. With `owner`: as Monaco's `setModelMarkers`, `diagnostics` become that
265
+ * owner's, shown with every other owner's and the language's own; an empty list removes the
266
+ * owner, and the owner `'language'` replaces the language's own.
267
+ */
268
+ setDiagnostics(diagnostics: AardinkDiagnostic[] | null, owner?: string): void;
269
+ /** Monaco's `setModelMarkers(model, owner, markers)`, for this editor's model. */
270
+ setModelMarkers(owner: string, markers: AardinkDiagnostic[]): void;
271
+ /** The lines on screen: one range, 1-based. */
272
+ getVisibleRanges(): AardinkRange[];
273
+ /** How far the text is scrolled down, in CSS pixels. */
274
+ getScrollTop(): number;
275
+ /** Scrolls the text so `top` (CSS pixels) is at the top of the view, without moving the caret. */
276
+ setScrollTop(top: number): void;
277
+ /** The height of all the text, in CSS pixels (wrapped lines not laid out yet are estimated). */
278
+ getScrollHeight(): number;
279
+ /** Called as the text scrolls. Returns an unsubscribe function. */
280
+ onDidScrollChange(listener: (event: { scrollTop: number; scrollLeft: number; scrollHeight: number }) => void): () => void;
281
+ /** Measures the container again now; the editor follows its container's size by itself. */
282
+ layout(): void;
241
283
  /**
242
284
  * The language's own diagnostics each time they are collected: 500 ms after the editor appears,
243
285
  * after each pause in typing, and on `revalidate()`. Not called while a list from
@@ -252,6 +294,25 @@ export interface AardinkEditor {
252
294
  * is shown.
253
295
  */
254
296
  revalidate(): void;
297
+ /**
298
+ * The document's structure as the language describes it (its built-in service, or your
299
+ * `provideDocumentSymbols`): a tree in document order, its ranges moved along with the edits
300
+ * since the last answer. Asked about 300 ms after the editor appears and after each pause in
301
+ * typing; empty until then.
302
+ */
303
+ getDocumentSymbols(): AardinkDocumentSymbol[];
304
+ /**
305
+ * Monaco's `deltaDecorations`: removes the decorations with `oldIds` and adds `newDecorations`,
306
+ * returning the new ones' ids. Their ranges follow the edits made after.
307
+ */
308
+ deltaDecorations(oldIds: string[], newDecorations: AardinkModelDeltaDecoration[]): string[];
309
+ /** Monaco's `createDecorationsCollection`: a set of decorations of its own, replaced as a whole. */
310
+ createDecorationsCollection(decorations?: AardinkModelDeltaDecoration[]): AardinkDecorationsCollection;
311
+ /**
312
+ * The symbols holding `position`, outermost first: the element the caret is in, its parent and
313
+ * so on up. With `onDidChangeCursor`, this maps the caret to what the text describes.
314
+ */
315
+ getSymbolPathAt(position: AardinkPosition): AardinkDocumentSymbol[];
255
316
  revealPosition(line: number, column: number): void;
256
317
  /**
257
318
  * Opens the find panel and moves the keyboard focus to its find field, from wherever on the
@@ -382,6 +443,57 @@ export declare const CompletionItemInsertTextRule: {
382
443
  readonly InsertAsSnippet: 4;
383
444
  };
384
445
 
446
+ /**
447
+ * Monaco's `DocumentSymbol`: `kind` is Monaco's `SymbolKind` number (0 File, 1 Module, 4 Class,
448
+ * 5 Method, 6 Property, 11 Function, 12 Variable, 14 String, 17 Array, 18 Object, 19 Key...).
449
+ * `selectionRange`, the part that names it, is `range` when absent.
450
+ */
451
+ export interface AardinkDocumentSymbol {
452
+ name: string;
453
+ kind: number;
454
+ range: AardinkRange;
455
+ selectionRange?: AardinkRange;
456
+ detail?: string;
457
+ children?: AardinkDocumentSymbol[];
458
+ }
459
+
460
+ /** Monaco's `IModelDeltaDecoration`. */
461
+ export interface AardinkModelDeltaDecoration {
462
+ range: AardinkRange;
463
+ options: AardinkDecorationOptions;
464
+ }
465
+
466
+ /**
467
+ * Monaco's `IModelDecorationOptions`, as far as the editor draws them. Where Monaco takes a CSS
468
+ * 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.
471
+ */
472
+ export interface AardinkDecorationOptions {
473
+ /** Behind the characters; behind whole lines with `isWholeLine`. */
474
+ backgroundColor?: string;
475
+ /** A box around the characters. */
476
+ borderColor?: string;
477
+ /** A line under the characters. */
478
+ underlineColor?: string;
479
+ /** A bar at the gutter's text edge on each line, as Monaco's `linesDecorationsClassName` places one. */
480
+ gutterColor?: string;
481
+ isWholeLine?: boolean;
482
+ hoverMessage?: string | { value: string } | Array<string | { value: string }>;
483
+ overviewRuler?: { color: string; position?: number };
484
+ minimap?: { color: string; position?: number };
485
+ }
486
+
487
+ /** Monaco's `IEditorDecorationsCollection`. */
488
+ export interface AardinkDecorationsCollection {
489
+ readonly length: number;
490
+ set(decorations: AardinkModelDeltaDecoration[]): string[];
491
+ append(decorations: AardinkModelDeltaDecoration[]): string[];
492
+ clear(): void;
493
+ /** The ranges as they are now, moved along with the edits since they were set. */
494
+ getRanges(): AardinkRange[];
495
+ }
496
+
385
497
  /** Monaco's `IRange`: 1-based lines and columns, `endColumn` exclusive. */
386
498
  export interface AardinkRange {
387
499
  startLineNumber: number;
@@ -470,6 +582,24 @@ export interface AardinkLanguageProviders {
470
582
  ): AardinkCompletionItem[] | AardinkCompletionList | null | Promise<AardinkCompletionItem[] | AardinkCompletionList | null>;
471
583
  provideHover?(text: string, line: number, column: number): AardinkHover | null | Promise<AardinkHover | null>;
472
584
  provideDiagnostics?(text: string): AardinkDiagnostic[] | Promise<AardinkDiagnostic[]>;
585
+ /**
586
+ * The document's structure, as Monaco's `provideDocumentSymbols`, for Go to Symbol
587
+ * (Ctrl+Shift+O), the breadcrumbs, sticky scroll and `getSymbolPathAt`. With `extends`, the base
588
+ * language's are used while this answers none.
589
+ */
590
+ provideDocumentSymbols?(text: string): AardinkDocumentSymbol[] | null | Promise<AardinkDocumentSymbol[] | null>;
591
+ /**
592
+ * The colours written in the text, as Monaco's `provideDocumentColors`, for the swatches drawn
593
+ * with the `colorDecorators` option. With `extends`, the base language's are added. A colour
594
+ * picked in the editor's picker is written back as CSS hex (`#rrggbb`, `#rrggbbaa`).
595
+ */
596
+ provideDocumentColors?(text: string): AardinkColorInformation[] | null | Promise<AardinkColorInformation[] | null>;
597
+ }
598
+
599
+ /** Monaco's `IColorInformation`: where a colour is written, and the colour, each channel from 0 to 1. */
600
+ export interface AardinkColorInformation {
601
+ range: AardinkRange;
602
+ color: { red: number; green: number; blue: number; alpha: number };
473
603
  }
474
604
 
475
605
  /** Adds a language for `createEditor`'s `language` option. Rejects with what is wrong with the definition. */
package/index.js CHANGED
@@ -17,7 +17,7 @@
17
17
  // Adapts the Kotlin module's integer-handle exports (aardinkCreate, aardinkGetValue, ...) into
18
18
  // the Monaco-shaped object described in index.d.ts.
19
19
 
20
- export const version = '0.7.0';
20
+ export const version = '0.8.0';
21
21
 
22
22
  /** Monaco's flags for a completion's `insertText`. */
23
23
  export const CompletionItemInsertTextRule = Object.freeze({ None: 0, KeepWhitespace: 1, InsertAsSnippet: 4 });
@@ -139,6 +139,9 @@ function monarchToJson(value) {
139
139
  return value;
140
140
  }
141
141
 
142
+ /** The decorations owner deltaDecorations sets; each collection has its own. */
143
+ const DELTA_OWNER = 'delta';
144
+
142
145
  /** A provider's answer (a value or a Promise of one) as the Promise of JSON the Kotlin side awaits. */
143
146
  function answer(provider, ...args) {
144
147
  if (!provider) return Promise.resolve(null);
@@ -175,6 +178,8 @@ export async function registerLanguage(definition, providers = {}) {
175
178
  ((t) => Promise.resolve(providers.provideDiagnostics(t)).then((list) => (list == null ? null : list.map(toKotlinDiagnostic)))),
176
179
  text,
177
180
  ),
181
+ (text) => answer(providers.provideDocumentSymbols, text),
182
+ (text) => answer(providers.provideDocumentColors, text),
178
183
  );
179
184
  if (error) throw new Error(`Aardink: ${error}`);
180
185
  }
@@ -227,6 +232,13 @@ function toKotlinOptions(options) {
227
232
  const other = typeof value === 'object' && value !== null ? value.other : value;
228
233
  out.quickSuggestions = other !== false && other !== 'off' && other !== undefined;
229
234
  }
235
+ if (options.overviewRulerLanes !== undefined) out.overviewRuler = options.overviewRulerLanes > 0;
236
+ if (options.overviewRuler !== undefined) out.overviewRuler = !!options.overviewRuler;
237
+ if (options.occurrencesHighlight !== undefined) out.occurrencesHighlight = options.occurrencesHighlight !== false && options.occurrencesHighlight !== 'off';
238
+ if (options.fontLigatures !== undefined) out.fontLigatures = options.fontLigatures !== false && options.fontLigatures !== 'off';
239
+ for (const key of ['linkedEditing', 'colorDecorators', 'breadcrumbs']) {
240
+ if (options[key] !== undefined) out[key] = !!options[key];
241
+ }
230
242
  for (const key of ['minimap', 'stickyScroll', 'bracketPairColorization']) {
231
243
  const value = options[key];
232
244
  if (value !== undefined) out[key] = typeof value === 'object' && value !== null ? value.enabled !== false : !!value;
@@ -278,6 +290,18 @@ export async function createEditor(container, onChange, options = {}) {
278
290
  // side calls `run` as a () -> Unit and drops the value.
279
291
  let actionResult;
280
292
 
293
+ const scrollListeners = new Set();
294
+ k.aardinkOnScrollChange(id, (json) => {
295
+ if (!scrollListeners.size) return;
296
+ const event = JSON.parse(json);
297
+ for (const listener of scrollListeners) listener(event);
298
+ });
299
+
300
+ // Decorations: those set through deltaDecorations, with their ids, and each collection's own.
301
+ let deltaDecorations = [];
302
+ let nextDecorationId = 1;
303
+ let nextCollection = 1;
304
+
281
305
  const editor = {
282
306
  getValue: () => k.aardinkGetValue(id),
283
307
  setValue: (text) => k.aardinkSetValue(id, text),
@@ -350,12 +374,80 @@ export async function createEditor(container, onChange, options = {}) {
350
374
  },
351
375
  };
352
376
  },
353
- setDiagnostics: (diagnostics) => k.aardinkSetDiagnostics(id, JSON.stringify(diagnostics == null ? null : diagnostics.map(toKotlinDiagnostic))),
377
+ setDiagnostics(diagnostics, owner) {
378
+ if (owner !== undefined && owner !== null) {
379
+ k.aardinkSetModelMarkers(id, String(owner), JSON.stringify((diagnostics ?? []).map(toKotlinDiagnostic)));
380
+ } else {
381
+ k.aardinkSetDiagnostics(id, JSON.stringify(diagnostics == null ? null : diagnostics.map(toKotlinDiagnostic)));
382
+ }
383
+ },
384
+ setModelMarkers: (owner, markers) => k.aardinkSetModelMarkers(id, String(owner), JSON.stringify((markers ?? []).map(toKotlinDiagnostic))),
385
+ getVisibleRanges: () => JSON.parse(k.aardinkGetVisibleRanges(id)),
386
+ getScrollTop: () => k.aardinkGetScrollTop(id),
387
+ setScrollTop: (top) => k.aardinkSetScrollTop(id, Number(top)),
388
+ getScrollHeight: () => k.aardinkGetScrollHeight(id),
389
+ onDidScrollChange(listener) {
390
+ scrollListeners.add(listener);
391
+ return () => scrollListeners.delete(listener);
392
+ },
393
+ layout: () => k.aardinkLayout(id),
354
394
  onDidChangeDiagnostics(listener) {
355
395
  diagnosticsListeners.add(listener);
356
396
  return () => diagnosticsListeners.delete(listener);
357
397
  },
358
398
  revalidate: () => k.aardinkRevalidate(id),
399
+ deltaDecorations(oldIds, newDecorations) {
400
+ // Monaco's ids, kept here in the order the Kotlin side keeps the ranges, which follow the edits.
401
+ // A range it no longer has (setValue drops them all) is a decoration gone, not one to restore.
402
+ const ranges = JSON.parse(k.aardinkGetDecorationRanges(id, DELTA_OWNER));
403
+ const removed = new Set(oldIds ?? []);
404
+ const kept = [];
405
+ deltaDecorations.forEach((decoration, i) => {
406
+ if (ranges[i] !== undefined && !removed.has(decoration.id)) kept.push({ ...decoration, range: ranges[i] });
407
+ });
408
+ const added = (newDecorations ?? []).map((decoration) => ({ id: `aardink-decoration-${nextDecorationId++}`, ...decoration }));
409
+ deltaDecorations = kept.concat(added);
410
+ k.aardinkSetDecorations(id, DELTA_OWNER, JSON.stringify(deltaDecorations.map(({ range, options }) => ({ range, options }))));
411
+ return added.map((decoration) => decoration.id);
412
+ },
413
+ createDecorationsCollection(decorations) {
414
+ const owner = `collection-${nextCollection++}`;
415
+ let items = [];
416
+ const plain = (list) => (list ?? []).map(({ range, options }) => ({ range, options }));
417
+ const write = () => {
418
+ k.aardinkSetDecorations(id, owner, JSON.stringify(items));
419
+ return items.map((_, i) => `${owner}-${i}`);
420
+ };
421
+ // The items as the Kotlin side has them now: their ranges moved along with the edits, and
422
+ // none it has dropped (setValue drops them all).
423
+ const sync = () => {
424
+ const ranges = collection.getRanges();
425
+ items = items.slice(0, ranges.length).map((item, i) => ({ ...item, range: ranges[i] }));
426
+ };
427
+ const collection = {
428
+ get length() {
429
+ return collection.getRanges().length;
430
+ },
431
+ getRanges: () => JSON.parse(k.aardinkGetDecorationRanges(id, owner)),
432
+ set(list) {
433
+ items = plain(list);
434
+ return write();
435
+ },
436
+ append(list) {
437
+ sync();
438
+ items = items.concat(plain(list));
439
+ return write();
440
+ },
441
+ clear() {
442
+ items = [];
443
+ write();
444
+ },
445
+ };
446
+ if (decorations) collection.set(decorations);
447
+ return collection;
448
+ },
449
+ getDocumentSymbols: () => JSON.parse(k.aardinkGetDocumentSymbols(id)),
450
+ getSymbolPathAt: (position) => JSON.parse(k.aardinkGetSymbolPathAt(id, position.lineNumber, position.column)),
359
451
  revealPosition: (line, column) => k.aardinkRevealPosition(id, line, column),
360
452
  setBaseline: (text) => k.aardinkSetBaseline(id, text ?? ''),
361
453
  format: () => new Promise((resolve) => k.aardinkFormat(id, resolve)),
@@ -378,6 +470,7 @@ export async function createEditor(container, onChange, options = {}) {
378
470
  selectionListeners.clear();
379
471
  focusListeners.clear();
380
472
  blurListeners.clear();
473
+ scrollListeners.clear();
381
474
  k.aardinkDispose(id);
382
475
  },
383
476
  };
@@ -587,6 +587,7 @@ const js_code = {
587
587
  observer.disconnect();
588
588
  };
589
589
  },
590
+ 'com.aardarch.aardink.web.dispatchResize' : () => window.dispatchEvent(new Event('resize')),
590
591
  'com.aardarch.aardink.web.callStop' : (stop) => stop(),
591
592
  'com.aardarch.aardink.sampleweb.__callJsClosure_((String)->Unit)' : (f, p0) => f(p0),
592
593
  'com.aardarch.aardink.sampleweb.__callJsClosure_((Int,Int)->Unit)' : (f, p0, p1) => f(p0, p1),
@@ -88,6 +88,17 @@ export const {
88
88
  aardinkOnCursorChange,
89
89
  aardinkSetDiagnostics,
90
90
  aardinkOnDiagnosticsChange,
91
+ aardinkSetModelMarkers,
92
+ aardinkGetVisibleRanges,
93
+ aardinkGetScrollTop,
94
+ aardinkSetScrollTop,
95
+ aardinkGetScrollHeight,
96
+ aardinkOnScrollChange,
97
+ aardinkLayout,
98
+ aardinkSetDecorations,
99
+ aardinkGetDecorationRanges,
100
+ aardinkGetDocumentSymbols,
101
+ aardinkGetSymbolPathAt,
91
102
  aardinkRevalidate,
92
103
  aardinkRegisterLanguage,
93
104
  aardinkRegisterTheme,
Binary file
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@aardarch/aardink-web",
3
- "version": "0.7.0",
3
+ "version": "0.8.0",
4
4
  "description": "The Aardink code editor for the browser: Compose Multiplatform on WebAssembly behind a Monaco-shaped API.",
5
5
  "keywords": [
6
6
  "code-editor",