@aardarch/aardink-web 0.6.0-rc1 → 0.6.0-rc3

package/README.md

@@ -44,6 +44,18 @@ const savedAt = editor.getAlternativeVersionId(); // unsaved while it differs
 editor.dispose();
 ```
 
+`setValue` is for opening a file: it clears the undo history. A change the user should be able to
+undo, such as an assistant's rewrite, goes through `replaceValue` (the whole text) or Monaco's
+`executeEdits` (ranges). Either is one undo step that keeps the history before it, and changes
+only what differs, so carets and folds in unchanged text stay put:
+
+```ts
+editor.replaceValue(rewritten); // undo() brings the old text back
+editor.executeEdits('assistant', [
+  { range: { startLineNumber: 3, startColumn: 1, endLineNumber: 3, endColumn: 9 }, text: '<button/>' },
+]);
+```
+
 A language of your own is a Monarch grammar registered before use, optionally extending a built-in
 language's completions, diagnostics and folding, with Monaco's `defineTheme` for its colours:
 
@@ -52,14 +64,24 @@ import { defineTheme, registerLanguage } from '@aardarch/aardink-web';
 
 await registerLanguage(
   { id: 'toy', extends: 'xml', grammar: { tokenizer: { root: [[/\bshout\b/, 'keyword']] } } },
-  { provideCompletionItems: (text, line, column) => [{ label: 'shout', kind: 'element' }] },
+  {
+    triggerCharacters: ['{'], // besides XML's
+    provideCompletionItems: (text, line, column) => [{ label: 'shout', kind: 'element' }],
+  },
 );
 await defineTheme('toy-dark', { base: 'vs-dark', inherit: true, rules: [{ token: 'keyword', foreground: 'ff00ff' }] });
 ```
 
+Completion items take Monaco's `filterText`, `sortText` and `range` too, and
+`inheritCompletions: false` in the definition leaves out the extended language's completions
+(XML's are Android-flavoured) while keeping its diagnostics and folding. A hover can carry an
+`example`, shown as code.
+
 The editor fills its container, so give the container a size. `createEditor` is async because
 the first call loads the WebAssembly module (about 13 MB, 4.7 MB gzipped); every editor on the
-page shares that one module. See [`index.d.ts`](./index.d.ts) for the full API, and the
+page shares that one module. If that load fails, the call rejects and the next call loads again
+(though Chrome keeps a failed module download until the page is reloaded). See
+[`index.d.ts`](./index.d.ts) for the full API, and the
 [integration guide](https://github.com/aardarch/aardink/blob/main/docs/WEB_INTEGRATION.md) for how
 Monaco's options and calls map onto it.
 
@@ -102,9 +124,7 @@ the measurements and the device checklist.
 - **A disposed editor is not fully released** (about 275 KB each) until Aardink moves to Compose
   Multiplatform 1.13. Reuse one editor with `setValue` and `updateOptions` rather than mounting
   one per view.
-- Themes are colours only: bold and italic in theme rules are ignored.
-- Whitespace is not rendered (`renderWhitespace`), and a completion inserts plain text: snippet
-  placeholders such as `$1` are not expanded.
+- A theme rule's `background` is ignored; its `foreground` and `fontStyle` apply.
 
 ## Licence
 

package/index.d.ts

@@ -35,6 +35,8 @@ export interface AardinkOptions {
   insertSpaces?: boolean;
   /** Monaco's `renderLineHighlight`: anything but `'none'` highlights each caret's line. */
   renderLineHighlight?: 'none' | 'line' | 'gutter' | 'all';
+  /** Which spaces and tabs are drawn, as dots and arrows. `'selection'` by default. */
+  renderWhitespace?: 'none' | 'boundary' | 'selection' | 'trailing' | 'all';
   /** Colours brackets by nesting depth. On by default. */
   bracketPairColorization?: { enabled?: boolean } | boolean;
   /** A picture of the whole text at the side, with a slider over what is shown. Off by default. */
@@ -70,14 +72,49 @@ export interface AardinkContentChange {
   versionId: number;
   isUndoing: boolean;
   isRedoing: boolean;
-  /** The whole text was replaced (`setValue`). */
+  /** The whole text was replaced and the undo history cleared (`setValue`); `false` for `replaceValue` and `executeEdits`. */
   isFlush: boolean;
 }
 
+/**
+ * Monaco's `IIdentifiedSingleEditOperation`, for `executeEdits`: replaces `range` with `text`.
+ * `null` or `''` deletes the range; an empty range inserts. A position past the end of its line is
+ * the line's end, and one past the last line the end of the text, as Monaco validates them.
+ */
+export interface AardinkEditOperation {
+  range: AardinkRange;
+  text: string | null;
+  /** Accepted for Monaco's shape, and ignored. */
+  forceMoveMarkers?: boolean;
+}
+
 export interface AardinkEditor {
   getValue(): string;
-  /** Replaces the whole text and clears undo history. Fires the change listeners. */
+  /**
+   * Replaces the whole text and clears undo history, as when a file is opened. Fires the change
+   * listeners with `isFlush: true`. For a change the user should be able to undo, use
+   * `replaceValue` or `executeEdits`.
+   */
   setValue(text: string): void;
+  /**
+   * Replaces the whole text as one undo step, keeping the history before it: for a rewrite the user
+   * should be able to undo, such as an assistant's. Only what differs changes (lines compared, then
+   * characters), so carets, folds and diagnostics in unchanged text stay where they are. The change
+   * listeners get it with `isFlush: false` and a new `versionId`; `undo()` brings the old text back,
+   * and `getAlternativeVersionId()` its value then. Works in a read-only editor, as `setValue` does.
+   * Returns whether the text changed.
+   */
+  replaceValue(text: string): boolean;
+  /**
+   * Monaco's `executeEdits`: applies `edits` (which must not overlap) as one undo step, keeping the
+   * history, each reduced to the characters it really changes so carets and folds elsewhere stay
+   * put. Then selects `endCursorState` when given (positions in the text after the edits, as in
+   * Monaco), else carries the selections through the edits;
+   * a cursor-state computer function is not called. `source` is accepted for Monaco's shape.
+   * Returns `false`, changing nothing, in a read-only editor, as Monaco does; throws for edits that
+   * overlap. Reported to the change listeners as for `replaceValue`.
+   */
+  executeEdits(source: string | null | undefined, edits: AardinkEditOperation[], endCursorState?: AardinkSelection[] | ((...args: unknown[]) => unknown)): boolean;
   updateOptions(options: Partial<AardinkOptions>): void;
   /** Full text after every change, at most once per frame, and what the change was. Returns an unsubscribe function. */
   onDidChangeContent(listener: (text: string, change: AardinkContentChange) => void): () => void;
@@ -90,11 +127,24 @@ export interface AardinkEditor {
   setDiagnostics(diagnostics: AardinkDiagnostic[] | null): void;
   /**
    * The language's own diagnostics each time they are collected: 500 ms after the editor appears,
-   * and after each pause in typing. Not called while a list from `setDiagnostics` is shown.
+   * after each pause in typing, and on `revalidate()`. Not called while a list from
+   * `setDiagnostics` is shown.
    * Returns an unsubscribe function.
    */
   onDidChangeDiagnostics(listener: (diagnostics: AardinkDiagnostic[]) => void): () => void;
+  /**
+   * Collects the language's own diagnostics again now, without waiting for an edit: for when what
+   * your `provideDiagnostics` depends on outside the text has changed (another file, a setting).
+   * They reach `onDidChangeDiagnostics` as usual. Does nothing while a list from `setDiagnostics`
+   * is shown.
+   */
+  revalidate(): void;
   revealPosition(line: number, column: number): void;
+  /**
+   * Opens the find panel and moves the keyboard focus to its find field, from wherever on the
+   * page it was. Enter goes to the next match, Shift+Enter to the previous one, and Escape closes
+   * the panel and gives the focus back to the text.
+   */
   showFind(): void;
   undo(): boolean;
   redo(): boolean;
@@ -131,29 +181,104 @@ export interface AardinkLanguageDefinition {
   grammar: object;
   /** A built-in or registered language whose completions, diagnostics, hover and folding this one takes too, e.g. `'xml'`. */
   extends?: string;
+  /**
+   * With `extends`: `false` leaves out that language's completions (and, when the providers give
+   * `triggerCharacters`, its trigger characters), keeping its diagnostics, hover, folding and the
+   * rest. `true` by default. To leave them out for one request only, answer with
+   * `{ suggestions, exclusive: true }`.
+   */
+  inheritCompletions?: boolean;
   displayName?: string;
   extensions?: string[];
   /** As in Monaco's language configuration: what Ctrl/Cmd+/ comments with. */
   comments?: { lineComment?: string; blockComment?: [string, string] };
 }
 
+/** Monaco's flags for a completion's `insertText`. */
+export declare const CompletionItemInsertTextRule: {
+  readonly None: 0;
+  /** Insert the snippet's whitespace as written, rather than indented as the line it lands on. */
+  readonly KeepWhitespace: 1;
+  /** `insertText` is a snippet: `$1`, `${1:placeholder}` and `${1|a,b|}` are tab stops, `$0` the final caret. */
+  readonly InsertAsSnippet: 4;
+};
+
+/** Monaco's `IRange`: 1-based lines and columns, `endColumn` exclusive. */
+export interface AardinkRange {
+  startLineNumber: number;
+  startColumn: number;
+  endLineNumber: number;
+  endColumn: number;
+}
+
 export interface AardinkCompletionItem {
   label: string;
-  /** What accepting it types; the label when absent. */
+  /** What accepting it types; the label when absent. A snippet with `InsertAsSnippet`. */
   insertText?: string;
-  kind?: 'element' | 'attribute' | 'value' | 'snippet' | 'module' | 'property';
+  /** `CompletionItemInsertTextRule` flags, as in Monaco. */
+  insertTextRules?: number;
+  /**
+   * The icon. `'function'` is another name for `'transform'`, and `'color'` for `'colorRef'`, as
+   * Monaco calls them; any other name shows as `'value'`.
+   */
+  kind?: 'element' | 'attribute' | 'value' | 'snippet' | 'module' | 'property' | 'transform' | 'function' | 'colorRef' | 'color';
+  /** Shown beside the label when there is no `documentation`. */
   detail?: string;
-  documentation?: string;
+  /** Shown beside the label; Monaco's `{ value }` is shown as plain text. */
+  documentation?: string | { value: string };
+  /**
+   * What the text typed so far is matched against, as in Monaco: its characters in order, ignoring
+   * case, the first at the start of `filterText` or of a word in it. Typed so far is the text from
+   * the start of what the item replaces to the caret. Without it the item is not filtered: your
+   * provider is asked again on each letter typed, and offers what fits.
+   */
+  filterText?: string;
+  /** When any item has one, your items are ordered by it (by `label` where it is missing), as in Monaco. */
+  sortText?: string;
+  /**
+   * The text accepting the item replaces, which must contain the caret, as in Monaco. Of
+   * `{ insert, replace }`, `replace` is used. Without it the item replaces the word before the
+   * caret, back to the first of `< > { } ( ) [ ] " ' = , ; . @ | :` or whitespace.
+   */
+  range?: AardinkRange | { insert: AardinkRange; replace: AardinkRange };
+}
+
+/** Monaco's `CompletionList`, plus `exclusive`: `true` leaves out the extended language's completions for this request. */
+export interface AardinkCompletionList {
+  suggestions: AardinkCompletionItem[];
+  exclusive?: boolean;
+  /** Accepted for Monaco's shape, and ignored: your provider is asked again on each letter typed anyway. */
+  incomplete?: boolean;
+}
+
+export interface AardinkHover {
+  title?: string;
+  /** Plain text. */
+  contents: string;
+  /** Shown as code below `contents`. */
+  example?: string;
 }
 
 /**
  * What a registered language knows beyond its grammar. Each gets the whole text and, where it
  * asks about a place, a 1-based line and column; each may answer at once or with a Promise. With
- * `extends`, the built-in language's answers come after these.
+ * `extends`, the built-in language's answers come after these, less any completion with the same
+ * `kind` and `label` as one of yours (see `inheritCompletions` to leave them all out).
  */
 export interface AardinkLanguageProviders {
-  provideCompletionItems?(text: string, line: number, column: number): AardinkCompletionItem[] | null | Promise<AardinkCompletionItem[] | null>;
-  provideHover?(text: string, line: number, column: number): { title?: string; contents: string } | null | Promise<{ title?: string; contents: string } | null>;
+  /**
+   * Characters that open the completion list when typed, as on Monaco's completion provider, e.g.
+   * `['{', '|', '@', '$']`. With `extends` they add to that language's (`'xml'`: `< / space : " =`),
+   * or replace them with `inheritCompletions: false`; without, that language's apply. Letters and
+   * digits always ask again while the list is open.
+   */
+  triggerCharacters?: string[];
+  provideCompletionItems?(
+    text: string,
+    line: number,
+    column: number,
+  ): AardinkCompletionItem[] | AardinkCompletionList | null | Promise<AardinkCompletionItem[] | AardinkCompletionList | null>;
+  provideHover?(text: string, line: number, column: number): AardinkHover | null | Promise<AardinkHover | null>;
   provideDiagnostics?(text: string): AardinkDiagnostic[] | Promise<AardinkDiagnostic[]>;
 }
 
@@ -161,9 +286,10 @@ export interface AardinkLanguageProviders {
 export function registerLanguage(definition: AardinkLanguageDefinition, providers?: AardinkLanguageProviders): Promise<void>;
 
 /**
- * Monaco's `defineTheme` data. Token rules name a grammar's tokens; `tag` also colours
- * `tag.aardflex`. Themes are colours only: a rule's `fontStyle` and `background` are accepted, so
- * Monaco theme data passes as it is, and ignored.
+ * Monaco's `defineTheme` data. Token rules name tokens as Monaco does, and the longest matching
+ * prefix wins: `tag` also colours `tag.aardflex`, `comment.doc` only documentation comments. A
+ * rule's `fontStyle` (`'bold'`, `'italic'`, `'underline'`, `'strikethrough'`, or `''` for none)
+ * applies too; its `background` is accepted, so Monaco theme data passes as it is, and ignored.
  */
 export interface AardinkThemeData {
   base: 'vs' | 'vs-dark' | 'hc-black' | 'hc-light';
@@ -191,7 +317,12 @@ export function createEditor(
 /** For debugging a grammar: the tokens of `text` in `languageId`, per line, as Monaco's `tokenize` gives them. */
 export function tokenize(text: string, languageId: string): Promise<{ offset: number; type: string }[][]>;
 
-/** Starts loading the WebAssembly module without mounting anything. */
+/**
+ * Starts loading the WebAssembly module without mounting anything. Every call shares one load.
+ * When it fails (a network error, say), this and every call waiting on it reject, and the next
+ * call of any function here starts a new load. A browser may still hold on to a module whose
+ * download failed until the page is reloaded (Chrome does), so that new load can fail the same way.
+ */
 export function preloadAardink(): Promise<void>;
 
 /** The Aardink version this package was built from. */

package/index.js

@@ -17,20 +17,30 @@
 // Adapts the Kotlin module's integer-handle exports (aardinkCreate, aardinkGetValue, ...) into
 // the Monaco-shaped object described in index.d.ts.
 
-export const version = '0.6.0-rc1';
+export const version = '0.6.0-rc3';
+
+/** Monaco's flags for a completion's `insertText`. */
+export const CompletionItemInsertTextRule = Object.freeze({ None: 0, KeepWhitespace: 1, InsertAsSnippet: 4 });
 
 let kotlinModule;
 
 function load() {
-  // Memoised: every editor on the page shares one WebAssembly instance.
-  kotlinModule ??= import('./kotlin/aardink-web.mjs').then((k) => {
-    // Compose looks for resources relative to the page, not this package. A literal
-    // new URL(..., import.meta.url) is also what makes a bundler (Vite) emit the font file.
-    k.aardinkSetBundledFontUrl(
-      new URL('./kotlin/composeResources/com.aardarch.aardink.web.res/font/jetbrains_mono_regular.ttf', import.meta.url).href,
-    );
-    return k;
-  });
+  // Memoised: every editor on the page shares one WebAssembly instance. A failed load is
+  // forgotten, so the next call tries again rather than repeating one network blip for the
+  // page's life.
+  kotlinModule ??= import('./kotlin/aardink-web.mjs')
+    .then((k) => {
+      // Compose looks for resources relative to the page, not this package. A literal
+      // new URL(..., import.meta.url) is also what makes a bundler (Vite) emit the font file.
+      k.aardinkSetBundledFontUrl(
+        new URL('./kotlin/composeResources/com.aardarch.aardink.web.res/font/jetbrains_mono_regular.ttf', import.meta.url).href,
+      );
+      return k;
+    })
+    .catch((error) => {
+      kotlinModule = undefined;
+      throw error;
+    });
   return kotlinModule;
 }
 
@@ -54,6 +64,25 @@ function withRange(s) {
   };
 }
 
+/** The fields of a Monaco `ISelection` the Kotlin side reads. */
+function toKotlinSelection(s) {
+  return {
+    selectionStartLineNumber: s.selectionStartLineNumber,
+    selectionStartColumn: s.selectionStartColumn,
+    positionLineNumber: s.positionLineNumber,
+    positionColumn: s.positionColumn,
+  };
+}
+
+/** The fields of a Monaco edit operation the Kotlin side reads; a Monaco `Range` is a class, so copy them. */
+function toKotlinEdit(edit) {
+  const r = edit.range;
+  return {
+    range: { startLineNumber: r.startLineNumber, startColumn: r.startColumn, endLineNumber: r.endLineNumber, endColumn: r.endColumn },
+    text: edit.text ?? null,
+  };
+}
+
 /** For debugging a grammar: the tokens of `text` in `languageId`, per line, as Monaco's tokenize gives them. */
 export async function tokenize(text, languageId) {
   const k = await load();
@@ -95,6 +124,9 @@ export async function registerLanguage(definition, providers = {}) {
       extends: definition.extends,
       displayName: definition.displayName,
       extensions: definition.extensions,
+      inheritCompletions: definition.inheritCompletions,
+      // On the providers, as on Monaco's completion provider; the Kotlin side reads it with the definition.
+      triggerCharacters: providers.triggerCharacters,
       grammar,
     }),
     (text, line, column) => answer(providers.provideCompletionItems, text, line, column),
@@ -112,9 +144,16 @@ function toVsCodeTheme(theme) {
     type: base === 'vscode-light' ? 'light' : 'dark',
     base: theme.inherit === false ? undefined : base,
     colors: theme.colors ?? {},
+    // A rule's colour and font style; its background is not drawn.
     tokenColors: theme.rules
-      .filter((rule) => rule.foreground)
-      .map((rule) => ({ scope: rule.token, settings: { foreground: `#${rule.foreground.replace(/^#/, '')}` } })),
+      .filter((rule) => rule.foreground || rule.fontStyle !== undefined)
+      .map((rule) => ({
+        scope: rule.token,
+        settings: {
+          ...(rule.foreground ? { foreground: `#${rule.foreground.replace(/^#/, '')}` } : {}),
+          ...(rule.fontStyle !== undefined ? { fontStyle: rule.fontStyle } : {}),
+        },
+      })),
   };
 }
 
@@ -134,7 +173,7 @@ export const defineTheme = registerTheme;
  */
 function toKotlinOptions(options) {
   const out = {};
-  for (const key of ['language', 'theme', 'fontSize', 'readOnly', 'showGutter', 'showLineNumbers', 'showFoldMarkers', 'tabSize', 'insertSpaces', 'highlightCurrentLine']) {
+  for (const key of ['language', 'theme', 'fontSize', 'readOnly', 'showGutter', 'showLineNumbers', 'showFoldMarkers', 'tabSize', 'insertSpaces', 'highlightCurrentLine', 'renderWhitespace']) {
     if (options[key] !== undefined) out[key] = options[key];
   }
   if (options.wordWrap !== undefined) out.wordWrap = options.wordWrap === 'on';
@@ -172,6 +211,15 @@ export async function createEditor(container, onChange, options = {}) {
   return {
     getValue: () => k.aardinkGetValue(id),
     setValue: (text) => k.aardinkSetValue(id, text),
+    replaceValue: (text) => k.aardinkReplaceValue(id, text),
+    executeEdits(source, edits, endCursorState) {
+      // `source` only names the edit in Monaco; a cursor-state computer function is not called.
+      const selections = Array.isArray(endCursorState) && endCursorState.length ? endCursorState.map(toKotlinSelection) : null;
+      const result = k.aardinkExecuteEdits(id, JSON.stringify(edits.map(toKotlinEdit)), JSON.stringify(selections));
+      if (result === 'read-only') return false;
+      if (result) throw new Error(`Aardink: ${result}`);
+      return true;
+    },
     updateOptions: (patch) => k.aardinkUpdateOptions(id, JSON.stringify(toKotlinOptions(patch))),
     onDidChangeContent(listener) {
       contentListeners.add(listener);
@@ -186,21 +234,13 @@ export async function createEditor(container, onChange, options = {}) {
       diagnosticsListeners.add(listener);
       return () => diagnosticsListeners.delete(listener);
     },
+    revalidate: () => k.aardinkRevalidate(id),
     revealPosition: (line, column) => k.aardinkRevealPosition(id, line, column),
     setBaseline: (text) => k.aardinkSetBaseline(id, text ?? ''),
     format: () => new Promise((resolve) => k.aardinkFormat(id, resolve)),
     focus: () => k.aardinkFocus(id),
     getSelections: () => JSON.parse(k.aardinkGetSelections(id)).map(withRange),
-    setSelections: (selections) =>
-      k.aardinkSetSelections(
-        id,
-        JSON.stringify(selections.map((s) => ({
-          selectionStartLineNumber: s.selectionStartLineNumber,
-          selectionStartColumn: s.selectionStartColumn,
-          positionLineNumber: s.positionLineNumber,
-          positionColumn: s.positionColumn,
-        }))),
-      ),
+    setSelections: (selections) => k.aardinkSetSelections(id, JSON.stringify(selections.map(toKotlinSelection))),
     canUndo: () => k.aardinkCanUndo(id),
     canRedo: () => k.aardinkCanRedo(id),
     pushUndoStop: () => k.aardinkPushUndoStop(id),

package/kotlin/aardink-web.import-object.mjs

@@ -561,6 +561,23 @@ const js_code = {
     'androidx.compose.material3.internal.set_$external_fun' : (_this, p0, p1) => _this.set(p0, p1),
     'androidx.compose.material3.internal.get_$external_fun' : (_this, p0) => _this.get(p0),
     'com.aardarch.aardink.platform.readClipboardText' : () => navigator.clipboard.readText(),
+    'com.aardarch.aardink.web.followSize' : (element) => {
+        let last = element.clientWidth + 'x' + element.clientHeight;
+        let frame = 0;
+        const observer = new ResizeObserver(() => {
+            const size = element.clientWidth + 'x' + element.clientHeight;
+            if (size === last) return;
+            last = size;
+            cancelAnimationFrame(frame);
+            frame = requestAnimationFrame(() => window.dispatchEvent(new Event('resize')));
+        });
+        observer.observe(element);
+        return () => {
+            cancelAnimationFrame(frame);
+            observer.disconnect();
+        };
+    },
+    'com.aardarch.aardink.web.callStop' : (stop) => stop(),
     'com.aardarch.aardink.sampleweb.__callJsClosure_((String)->Unit)' : (f, p0) => f(p0),
     'com.aardarch.aardink.sampleweb.__callJsClosure_((Int,Int)->Unit)' : (f, p0, p1) => f(p0, p1),
     'com.aardarch.aardink.sampleweb.__callJsClosure_((String,Int,Int)->Js)' : (f, p0, p1, p2) => f(p0, p1, p2),

package/kotlin/aardink-web.mjs

@@ -81,11 +81,14 @@ export const {
     aardinkCreate,
     aardinkGetValue,
     aardinkSetValue,
+    aardinkReplaceValue,
+    aardinkExecuteEdits,
     aardinkUpdateOptions,
     aardinkOnChange,
     aardinkOnCursorChange,
     aardinkSetDiagnostics,
     aardinkOnDiagnosticsChange,
+    aardinkRevalidate,
     aardinkRegisterLanguage,
     aardinkRegisterTheme,
     aardinkOnContentChange,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aardarch/aardink-web",
-  "version": "0.6.0-rc1",
+  "version": "0.6.0-rc3",
   "description": "The Aardink code editor for the browser: Compose Multiplatform on WebAssembly behind a Monaco-shaped API.",
   "keywords": [
     "code-editor",