@adecore/editor 0.41.1 → 0.43.0

package/src/types.ts

@@ -1,12 +1,15 @@
 import type { EditorSearchClientOptions } from './search-client.ts';
 import type { Keymap } from './keymap-table.ts';
-import type { EditorCommand, FoldRole } from '@adecore/editor-core';
+import type { EditorCommand, FoldRole, WhitespaceCleanupOptions } from '@adecore/editor-core';
 
 export type { EditorCommand, FoldRole };
 
+/* What a cleanup before a save does; everything is off unless set, except that the lines with a caret keep their trailing whitespace. */
+export type EditorWhitespaceCleanup = WhitespaceCleanupOptions;
+
 export type EditorFoldOutline = 'off' | 'hover' | 'always';
 
-/* The commands that fold, which the view answers since it knows where the ranges are. */
+/* The commands that fold or change how the text is drawn, which the view answers since it knows where the ranges are. */
 export type EditorViewCommand =
     | 'collapseRegion'
     | 'expandRegion'
@@ -22,7 +25,25 @@ export type EditorViewCommand =
     | 'expandAllToLevel3'
     | 'expandAllToLevel4'
     | 'expandAllToLevel5'
-    | 'toggleColumnMode';
+    | 'toggleColumnMode'
+    | 'increaseFontSize'
+    | 'decreaseFontSize'
+    | 'resetFontSize'
+    | 'methodUp'
+    | 'methodDown'
+    | 'nextChange'
+    | 'previousChange'
+    | 'pasteAsPlainText';
+
+/* How far a person may zoom the text, and whether the wheel does. */
+export interface EditorZoom {
+    /* In pixels; 12 by default, and never less. */
+    readonly min?: number;
+    /* In pixels; 90 by default. */
+    readonly max?: number;
+    /* Ctrl with the wheel (Cmd on macOS), or a pinch, zooms; on unless false. */
+    readonly wheel?: boolean;
+}
 
 /* Everything `runCommand` runs. */
 export type EditorRunCommand = EditorCommand | EditorViewCommand;
@@ -87,6 +108,11 @@ export interface EditorOptions {
     readonly column?: number;
     /* In pixels, where the view opens; without it the cursor's line is brought into view. */
     readonly scrollTop?: number;
+    /* The words that mark a TODO comment, matched as whole words in any case; `DEFAULT_TODO_WORDS` without them, and none drawn with an empty list. */
+    readonly todoWords?: readonly string[];
+    /* In pixels, a size a person zoomed to that the host kept; without it the code has the page's `--code-font-size`. */
+    readonly fontSize?: number;
+    readonly zoom?: EditorZoom;
 }
 
 /* The few sentences the editor says on its own. */
@@ -262,6 +288,21 @@ export interface EditorContentChange {
     readonly text: string;
 }
 
+/* What a copy or cut put on the clipboard. */
+export interface EditorCopy {
+    readonly text: string;
+    /* A copy of bare carets takes their lines, which paste back above the lines of bare carets. */
+    readonly wholeLines: boolean;
+    readonly cut: boolean;
+}
+
+export interface EditorPasteOptions {
+    /* Pastes above the lines of bare carets, as the paste of a copy of bare carets does; by default when the text is the last such copy. */
+    readonly wholeLines?: boolean;
+    /* False leaves the indentation of the text alone; the editor's indent on paste setting otherwise. */
+    readonly reindent?: boolean;
+}
+
 export interface EditorApplyEditsOptions {
     readonly mapSelections?: (range: EditorRange) => EditorRange;
     readonly mergeUndo?: boolean;
@@ -451,6 +492,8 @@ export interface EditorInlayHint {
     /* A gap of 4 pixels that keeps the pill off the character before it or the one after it. */
     readonly paddingLeft?: boolean;
     readonly paddingRight?: boolean;
+    /* A square of this CSS color in place of the label, such as the color a literal stands for; the label is then what assistive technology reads. */
+    readonly swatch?: string;
 }
 
 /* A hint, or one part of its label, under the pointer. */
@@ -623,9 +666,23 @@ export interface Editor {
     /* The column to draw a line at; null takes it away. */
     setRightMargin(column: number | null): void;
     setFoldOutline(outline: EditorFoldOutline): void;
+    /* The words that mark a TODO comment; an empty list draws none. Optional so an editor from before it still fits. */
+    setTodoWords?(words: readonly string[]): void;
     setLabel(label: string): void;
     /* What a language server knows about the folds: the bodies of symbols and the ranges it folds. They follow their text through edits until set again; null forgets them. */
     setFoldHints(hints: EditorFoldHints | null): void;
+    /* The places Method Up and Down stop at, such as the names of a language server's symbols. They follow their text through edits until set again; null goes back to the editor's own reading of the structure. Optional so an editor from before it still fits. */
+    setDeclarations?(positions: readonly EditorPosition[] | null): void;
+    /* A command that navigates (Method Up and Down, Code Block Start and End) moved the primary caret away from `from`. Optional so an editor from before it still fits. */
+    onNavigate?(listener: (from: EditorPosition) => void): () => void;
+    /* Whether the editor has the keyboard focus. Optional so an editor from before it still fits. */
+    hasFocus?(): boolean;
+    /* The texts of the other open documents, which Hippie completion takes words from after those of this one; null takes them away. Optional so an editor from before it still fits. */
+    setWordSources?(source: (() => readonly string[]) | null): void;
+    /* Told after a copy or cut, with the text it put on the clipboard. Optional so an editor from before it still fits. */
+    onCopy?(listener: (copy: EditorCopy) => void): () => void;
+    /* Pastes `text` as a paste from the clipboard does: at every caret, with indent on paste, and refused with its notice when the editor is read-only. False when nothing was pasted. Optional so an editor from before it still fits. */
+    paste?(text: string, options?: EditorPasteOptions): boolean;
     /*
      * Marks that follow their lines through edits until the host sets them again. Every layer (default: the unnamed one)
      * holds its own marks and the editor draws the union, so setting one layer never clears another; an empty list
@@ -676,7 +733,8 @@ export interface Editor {
     /* Colors by what the language servers know, over what the grammar made of the text; null takes them away. */
     setSemanticTokens(tokens: readonly EditorSemanticToken[] | null): void;
     /* Hints to draw as soft pills in the text, replacing the ones set before. They follow their text through edits until set again. */
-    setInlayHints(hints: readonly EditorInlayHint[]): void;
+    /* Each owner sets its own hints and keeps those of the others; ids stay unique across owners. */
+    setInlayHints(hints: readonly EditorInlayHint[], owner?: string): void;
     /* The pointer moved onto a hint or one of its parts, or null when it left them. Optional so an editor from before it still fits. */
     onInlayHover?(listener: (target: EditorInlayTarget | null) => void): () => void;
     /* Handlers see a press of the primary button on a hint before the editor does, the first to take it winning. */
@@ -765,9 +823,23 @@ export interface Editor {
     trackRange(range: EditorRange): EditorTrackedRange;
     /* Replaces ranges of the current text at once, as one step of the undo history. `mapSelections` places each selection in the new text, keeping its direction, and redo restores it. `mergeUndo` joins the step before it when the text is exactly as that step left it, so one undo takes both back. */
     applyEdits(edits: readonly EditorContentChange[], options?: EditorApplyEditsOptions): boolean;
+    /*
+     * Call right before writing the file: cleans up the whitespace as the options say, as one undo step, and
+     * marks the text as saved, so `modified` counts from here next time. Call it on every save, with all off too.
+     * False when the text did not change. Optional so an editor from before it still fits.
+     */
+    cleanUpWhitespace?(options: EditorWhitespaceCleanup): boolean;
+    /* Marks the text as saved without a cleanup, such as after a reload from disk. Optional so an editor from before it still fits. */
+    markSaved?(): void;
     setTheme(theme: EditorTheme): void;
     /* Reads the code face off the page again, after the page changed its size, family or ligatures. */
     refreshFont(): void;
+    /* Draws the code at a size of its own, kept inside the zoom range in whole pixels; null goes back to the page's size. Optional so an editor from before it still fits. */
+    setFontSize?(size: number | null): void;
+    /* The size the code is drawn at, in pixels. Optional so an editor from before it still fits. */
+    getFontSize?(): number;
+    /* A person zoomed: the new size in pixels, or null when they went back to the page's size. Not told of `setFontSize`. Optional so an editor from before it still fits. */
+    onFontSizeChange?(listener: (size: number | null) => void): () => void;
     setReadOnly(readOnly: boolean, reason?: string): void;
     /* Whether the editor refuses edits. Optional so an editor from before it still fits. */
     isReadOnly?(): boolean;

package/src/view.ts

@@ -27,6 +27,7 @@ import {
     type VerticalWindow
 } from './layout.ts';
 import { createMetrics, type EditorFont, readEditorFont } from './metrics.ts';
+import { zoomedFont } from './zoom.ts';
 import { type AttributedLines, AttributionRuns, colorValue, tintValue } from './attribution.ts';
 import { renderCodeBlock } from './code-block.ts';
 import { emit, subscribe } from './listeners.ts';
@@ -50,6 +51,7 @@ import {
     type WrapSign
 } from './paint.ts';
 import { overlayTokens, type SemanticSpan } from './semantic.ts';
+import { TodoMarks } from './todos.ts';
 import { TokenCache } from './tokens.ts';
 import type {
     EditorBlock,
@@ -118,6 +120,8 @@ export interface ViewSettings {
     folding?: boolean;
     /* The headers of the blocks scrolled out of sight stay pinned on top; on unless false. */
     stickyScroll?: boolean;
+    /* The words that mark a TODO comment; the default ones without them, none drawn with an empty list. */
+    todoWords?: readonly string[];
 }
 
 /* The lines past the visible ones that are colored ahead of the scroll, and how long one slice of that work may take. */
@@ -201,6 +205,7 @@ export class EditorView {
     readonly layout: EditorLayout;
     readonly find: FindController;
     readonly tokens: TokenCache;
+    private readonly todos: TodoMarks;
     private readonly content: HTMLElement;
     private readonly gutter: HTMLElement;
     private readonly gutterLines: HTMLElement;
@@ -275,6 +280,8 @@ export class EditorView {
     private caretTimer: ReturnType<typeof setTimeout> | undefined;
     private caretKey = '';
     private renderedScroll = { top: -1, left: -1 };
+    /* A size the code is zoomed to, over the page's; null draws it at the page's. */
+    private fontSize: number | null = null;
     private font: EditorFont;
     private layoutVersion = 0;
     private revision: number;
@@ -291,6 +298,7 @@ export class EditorView {
     private lenses: BlockWidget[] = [];
     private readonly replacements = new Map<string, BlockReplacement[]>();
     private occurrences: Occurrence[] = [];
+    private hippieSource: { from: number; to: number } | null = null;
     private replacePreview: { text: string; preserveCase: boolean } | null = null;
     private dropCaret: number | null = null;
     private activeGuideCache: { key: string; guide: { column: number; first: number; last: number } | null } | undefined;
@@ -309,6 +317,7 @@ export class EditorView {
     private collapsed = new Set<number>();
     /* What a language server said about the folds, in offsets that follow the text through edits. */
     private foldHints: FoldHints | null = null;
+    private declarations: number[] | null = null;
     /* The roles that fold by themselves while the file is as it was opened; null once a person edited or the file opened with folds of its own. */
     private defaultRoles: ReadonlySet<FoldRole> | null = null;
     /* The folds somebody already decided on, a person or the defaults, so a later answer of a server leaves them as they are. */
@@ -424,6 +433,7 @@ export class EditorView {
         });
 
         this.tokens = new TokenCache({ getLineCount: () => model.getLineCount(), getLineText: (line) => model.getLine(line).text });
+        this.todos = new TodoMarks(model, () => this.requestRender());
         const ResizeObserverClass = document.defaultView?.ResizeObserver;
 
         this.blockObserver = ResizeObserverClass
@@ -459,6 +469,7 @@ export class EditorView {
         this.root.dataset.readonly = String(this.settings.readOnly);
         this.root.dataset.wrap = String(this.settings.wrap);
         this.root.dataset.foldOutline = this.settings.foldOutline;
+        this.todos.configure(this.settings.language, this.settings.todoWords);
         this.layoutVersion++;
         this.layout.configure({ metrics: createMetrics(this.font, this.settings.tabSize, this.document) });
         this.render();
@@ -470,8 +481,30 @@ export class EditorView {
     }
 
     refreshFont(): void {
-        this.font = readEditorFont(this.root);
-        this.applySettings();
+        const style = this.root.style;
+        style.removeProperty('--code-font-size');
+        style.removeProperty('--code-line-height');
+        const base = readEditorFont(this.root);
+        this.font = this.fontSize === null ? base : zoomedFont(base, this.fontSize);
+
+        // On the element itself, so everything the editor draws at the code's size follows, and the page's size stays the base.
+        if (this.fontSize !== null) {
+            style.setProperty('--code-font-size', `${this.font.size}px`);
+            style.setProperty('--code-line-height', `${this.font.lineHeight}px`);
+        }
+
+        this.anchorScroll(() => this.applySettings());
+    }
+
+    /* Draws the code at a size of its own in whole pixels; null goes back to the page's. */
+    setFontSize(size: number | null): void {
+        this.fontSize = size;
+        this.refreshFont();
+    }
+
+    /* The size the code is drawn at, in pixels. */
+    getFontSize(): number {
+        return this.font.size;
     }
 
     setTokenizer(tokenizer: LineTokenizer | null): void {
@@ -569,6 +602,16 @@ export class EditorView {
         this.render();
     }
 
+    /* The word Hippie completion took from this document, shown until the next key or edit; null takes the mark away. */
+    setHippieSource(range: { from: number; to: number } | null): void {
+        if (range === null && this.hippieSource === null) {
+            return;
+        }
+
+        this.hippieSource = range;
+        this.render();
+    }
+
     /* A name underlined as a link a press follows, with the pointer to match; null takes it away. */
     setLink(link: { from: number; to: number } | null): void {
         this.link = link;
@@ -591,8 +634,13 @@ export class EditorView {
         this.render();
     }
 
-    /* The grammar's colors of a line with the servers' laid over them, the same object for as long as neither changed. */
+    /* The colors of a line with its TODOs drawn over them, the same object for as long as nothing under them changed. */
     private styledTokensOf(line: number): readonly LineToken[] | null {
+        return this.todos.styled(line, this.semanticTokensOf(line));
+    }
+
+    /* The grammar's colors of a line with the servers' laid over them, the same object for as long as neither changed. */
+    private semanticTokensOf(line: number): readonly LineToken[] | null {
         const base = this.lineTokenProvider === null ? this.tokens.tokensOf(line) : (this.lineTokenProvider(line) ?? null);
 
         if (base === null || this.semantic.length === 0 || this.scopeColors === null) {
@@ -813,6 +861,7 @@ export class EditorView {
             this.markerVersion++;
             const anchor = this.topAnchor;
             this.occurrences = [];
+            this.hippieSource = null;
             this.link = null;
             this.content.classList.remove('se-content-link');
             this.outline.edited(batches);
@@ -841,6 +890,7 @@ export class EditorView {
             this.find.refresh();
             this.announceFind();
             this.scheduleFolds();
+            this.todos.schedule();
             this.colorAhead(true);
         }
 
@@ -879,6 +929,10 @@ export class EditorView {
             this.foldHints = mapFoldHints(this.foldHints, map);
         }
 
+        if (this.declarations !== null) {
+            this.declarations = this.declarations.map((offset) => map(offset));
+        }
+
         this.customFolds = this.customFolds.map((fold) => mapRange(fold, map));
         this.find.mapBounds(changes);
 
@@ -1052,15 +1106,7 @@ export class EditorView {
             return;
         }
 
-        const ranges =
-            this.model.getLength() > FOLD_LIMIT
-                ? []
-                : this.model.getFoldingRanges({
-                      indentation: /^(python|py|yaml|yml)$/.test(this.settings.language ?? ''),
-                      tabSize: this.settings.tabSize,
-                      ...(this.settings.language === undefined ? {} : { language: this.settings.language }),
-                      ...(this.foldHints === null ? {} : { hints: this.foldHints })
-                  });
+        const ranges = this.structureRanges();
 
         this.foldRanges = this.withCustomFolds(ranges);
 
@@ -1078,6 +1124,20 @@ export class EditorView {
         this.refoldLayout();
     }
 
+    /* The folding ranges the document has now, a server's included, whether or not the folds are drawn. */
+    structureRanges(): FoldingRange[] {
+        if (this.model.getLength() > FOLD_LIMIT) {
+            return [];
+        }
+
+        return this.model.getFoldingRanges({
+            indentation: /^(python|py|yaml|yml)$/.test(this.settings.language ?? ''),
+            tabSize: this.settings.tabSize,
+            ...(this.settings.language === undefined ? {} : { language: this.settings.language }),
+            ...(this.foldHints === null ? {} : { hints: this.foldHints })
+        });
+    }
+
     /* The folds a person made of a selection, which the document's own structure does not know, among the ones it does. */
     private withCustomFolds(ranges: readonly FoldingRange[]): ViewFold[] {
         const custom = this.customFolds.flatMap((fold): ViewFold[] => {
@@ -1346,6 +1406,65 @@ export class EditorView {
         this.refoldLayout();
     }
 
+    /* The places Method Up and Down stop at; they follow their text through edits until set again, and null goes back to the editor's own reading. */
+    setDeclarations(offsets: readonly number[] | null): void {
+        this.declarations = offsets === null ? null : [...new Set(offsets)].sort((left, right) => left - right);
+    }
+
+    private methodStops(): number[] {
+        if (this.declarations !== null) {
+            return this.declarations;
+        }
+
+        const sections = this.foldRanges.filter((range) => range.kind === 'section').map((range) => this.model.getLine(range.startLine).start);
+
+        return [...new Set([...this.outline.declarationStops(this.model), ...sections])].sort((left, right) => left - right);
+    }
+
+    /* Moves the one caret to the first line of the next or previous change mark, of any layer. False when there is none. */
+    goToChange(direction: -1 | 1): boolean {
+        const line = this.model.positionAt(this.model.getPrimary().head).line;
+        const { runs } = this.resolvedChanges();
+
+        // A run the caret is in is where it already is; a deleted run is the line its mark sits on.
+        const target = direction === 1 ? runs.find((run) => run.start > line) : runs.findLast((run) => (run.kind === 'deleted' ? run.start : run.end) < line);
+
+        if (target === undefined) {
+            return false;
+        }
+
+        const offset = this.model.getLine(Math.min(target.start, this.model.getLineCount() - 1)).start;
+        this.model.setSelections([{ anchor: offset, head: offset }]);
+        this.revealOffset(offset, 'center');
+
+        return true;
+    }
+
+    /* Moves the one caret to the previous or next declaration on another line. False when there is none. */
+    goToMethod(direction: -1 | 1): boolean {
+        // The structure is read after a pause in typing, so a press right after an edit reads it now.
+        if (this.declarations === null) {
+            this.refreshFolds();
+        }
+
+        const line = this.model.positionAt(this.model.getPrimary().head).line;
+        const stops = this.methodStops();
+
+        const target =
+            direction === 1
+                ? stops.find((offset) => this.model.positionAt(offset).line > line)
+                : stops.findLast((offset) => this.model.positionAt(offset).line < line);
+
+        if (target === undefined) {
+            return false;
+        }
+
+        this.model.setSelections([{ anchor: target, head: target }]);
+        this.revealOffset(target, direction === 1 ? 'centerDown' : 'centerUp');
+
+        return true;
+    }
+
     /* Hands over what a language server knows about the folds; null forgets it. The defaults fold what the answer names, once. */
     setFoldHints(hints: FoldHints | null): void {
         this.foldHints = hints;
@@ -2443,6 +2562,10 @@ export class EditorView {
             }
         }
 
+        if (this.hippieSource !== null) {
+            marks.push({ className: 'se-hippie-source', rects: this.paintRectangles(this.hippieSource.from, this.hippieSource.to, rows) });
+        }
+
         const marginX = this.settings.rightMargin === null ? null : this.settings.rightMargin * this.layout.metrics.charWidth;
 
         // A margin past the content would stretch the scroll extent to itself, so it shows only where the text or the view reaches it.
@@ -2963,7 +3086,7 @@ export class EditorView {
         const matches = this.find.matches;
         const current = this.find.current;
         const alike = this.selectionOccurrences();
-        const key = `${this.revision}|${this.changeVersion}|${this.markerVersion}|${this.layout.height}|${trackHeight}|${matches.length}|${current}|${matches[0]?.from}|${matches.at(-1)?.from}|${this.selectionOccurrenceCache.key}`;
+        const key = `${this.revision}|${this.changeVersion}|${this.markerVersion}|${this.todos.version}|${this.layout.height}|${trackHeight}|${matches.length}|${current}|${matches[0]?.from}|${matches.at(-1)?.from}|${this.selectionOccurrenceCache.key}`;
 
         if (key === this.overviewKey) {
             return;
@@ -2999,6 +3122,12 @@ export class EditorView {
             }
         }
 
+        for (const todo of this.todos.marks) {
+            if (todo.line < this.model.getLineCount()) {
+                spans.push({ kind: 'todo', top: rowTop(todo.line), bottom: rowBottom(todo.line), offset: todo.from, title: todo.text });
+            }
+        }
+
         for (const range of alike) {
             const line = this.model.positionAt(range.from).line;
             spans.push({ kind: 'occurrence', top: rowTop(line), bottom: rowBottom(line) });
@@ -3224,6 +3353,7 @@ export class EditorView {
         this.blockObserver?.disconnect();
         clearTimeout(this.bracketTimer);
         clearTimeout(this.foldTimer);
+        this.todos.dispose();
         clearTimeout(this.colorTimer);
         clearTimeout(this.noticeTimer);
         clearTimeout(this.liveTimer);

package/src/zoom.ts

@@ -0,0 +1,62 @@
+import type { EditorFont } from './metrics.ts';
+import type { EditorZoom } from './types.ts';
+
+/* Nothing a person reads is smaller. */
+export const MIN_FONT_SIZE = 12;
+export const MAX_FONT_SIZE = 90;
+/* A trackpad or a pinch sends the wheel in small steps; this many pixels of them are one step of the size. */
+const PIXELS_PER_STEP = 20;
+
+export interface FontSizeRange {
+    readonly min: number;
+    readonly max: number;
+}
+
+export function fontSizeRange(zoom: EditorZoom | undefined): FontSizeRange {
+    const min = Math.max(MIN_FONT_SIZE, Math.round(zoom?.min ?? MIN_FONT_SIZE));
+
+    return { min, max: Math.max(min, Math.round(zoom?.max ?? MAX_FONT_SIZE)) };
+}
+
+/* In whole pixels inside the range. */
+export function clampFontSize(size: number, range: FontSizeRange): number {
+    return Math.min(range.max, Math.max(range.min, Math.round(size)));
+}
+
+/* The face at another size, with the line as much taller as the page's line is to its text, in whole pixels. */
+export function zoomedFont(base: EditorFont, size: number): EditorFont {
+    return { family: base.family, size, lineHeight: Math.round((size * base.lineHeight) / base.size) };
+}
+
+/* Turns the wheel with the zoom modifier, or a pinch, into steps of one pixel: up and apart make the text larger. */
+export class WheelZoom {
+    private pending = 0;
+
+    /* -1, 0 or 1. A mouse notch is one step however far the platform says it went. */
+    step(event: { deltaY: number; deltaMode: number }): number {
+        if (event.deltaY === 0) {
+            return 0;
+        }
+
+        if (event.deltaMode !== 0 || Math.abs(event.deltaY) >= PIXELS_PER_STEP) {
+            this.pending = 0;
+
+            return event.deltaY < 0 ? 1 : -1;
+        }
+
+        if (Math.sign(this.pending) !== 0 && Math.sign(this.pending) !== Math.sign(event.deltaY)) {
+            this.pending = 0;
+        }
+
+        this.pending += event.deltaY;
+
+        if (Math.abs(this.pending) < PIXELS_PER_STEP) {
+            return 0;
+        }
+
+        const direction = this.pending < 0 ? 1 : -1;
+        this.pending = 0;
+
+        return direction;
+    }
+}