@adecore/editor 0.41.1 → 0.42.0

package/src/todos.ts

@@ -0,0 +1,111 @@
+import { DEFAULT_TODO_WORDS, type DocumentModel, type TodoMatch } from '@adecore/editor-core';
+import { overlayTokens } from './semantic.ts';
+import type { LineToken } from './types.ts';
+
+const TODO_COLOR = 'var(--editor-todo)';
+const ITALIC = 1;
+/* The marks in the scroll track read the whole document, so they wait for a pause in editing as the folds do. */
+const TODO_DELAY_MS = 300;
+const TODO_LIMIT = 2_000_000;
+const CACHED_LINES = 600;
+
+/* The text is kept with the mark, since the list is only read again after a pause and the offsets may be stale until then. */
+export type TodoMark = TodoMatch & { readonly text: string };
+
+/*
+ * The TODO comments of a view: drawn in their own color over the grammar's on the lines being painted,
+ * and listed for the whole document a moment after the last edit, for the ticks in the scroll track.
+ */
+export class TodoMarks {
+    private readonly model: DocumentModel;
+    private readonly changed: () => void;
+    private words: readonly string[] = DEFAULT_TODO_WORDS;
+    /* Empty until the first `configure`, which reads the document. */
+    private language = '';
+    private revision = -1;
+    private readonly lines = new Map<number, { base: readonly LineToken[] | null; result: readonly LineToken[] | null }>();
+    private timer: ReturnType<typeof setTimeout> | undefined;
+    private all: readonly TodoMark[] = [];
+    /* Counts every new list, so a painter can tell its ticks are stale. */
+    version = 0;
+
+    constructor(model: DocumentModel, changed: () => void) {
+        this.model = model;
+        this.changed = changed;
+    }
+
+    get marks(): readonly TodoMark[] {
+        return this.all;
+    }
+
+    configure(language: string | undefined, words: readonly string[] | undefined): void {
+        const nextLanguage = language ?? 'plaintext';
+        const nextWords = words ?? DEFAULT_TODO_WORDS;
+
+        if (nextLanguage === this.language && nextWords.join('\n') === this.words.join('\n')) {
+            return;
+        }
+
+        this.language = nextLanguage;
+        this.words = nextWords;
+        this.revision = -1;
+        this.refresh();
+    }
+
+    /* The line's tokens with its TODOs drawn over them, the same array for as long as neither changed. */
+    styled(line: number, base: readonly LineToken[] | null): readonly LineToken[] | null {
+        if (this.words.length === 0) {
+            return base;
+        }
+
+        const revision = this.model.getRevision();
+
+        if (revision !== this.revision || this.lines.size > CACHED_LINES) {
+            this.revision = revision;
+            this.lines.clear();
+        }
+
+        const cached = this.lines.get(line);
+
+        if (cached !== undefined && cached.base === base) {
+            return cached.result;
+        }
+
+        const matches = this.model.findTodos(this.language, { words: this.words }, line, line);
+        let result = base;
+
+        if (matches.length > 0) {
+            const { start, end } = this.model.getLine(line);
+            const spans = matches.map((match) => ({ from: match.from - start, to: match.to - start, color: TODO_COLOR, fontStyle: ITALIC }));
+            result = overlayTokens(base ?? [{ length: end - start, color: '', fontStyle: 0 }], spans);
+        }
+
+        this.lines.set(line, { base, result });
+
+        return result;
+    }
+
+    schedule(): void {
+        clearTimeout(this.timer);
+        this.timer = setTimeout(() => this.refresh(), TODO_DELAY_MS);
+    }
+
+    /* Reads the TODOs of the whole document now, which otherwise waits for a pause in editing. */
+    refresh(): void {
+        clearTimeout(this.timer);
+        const found = this.words.length === 0 || this.model.getLength() > TODO_LIMIT ? [] : this.model.findTodos(this.language, { words: this.words });
+        const next = found.map((match) => ({ ...match, text: this.model.slice(match.from, match.to) }));
+
+        if (next.length === 0 && this.all.length === 0) {
+            return;
+        }
+
+        this.all = next;
+        this.version++;
+        this.changed();
+    }
+
+    dispose(): void {
+        clearTimeout(this.timer);
+    }
+}

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,20 @@ export type EditorViewCommand =
     | 'expandAllToLevel3'
     | 'expandAllToLevel4'
     | 'expandAllToLevel5'
-    | 'toggleColumnMode';
+    | 'toggleColumnMode'
+    | 'increaseFontSize'
+    | 'decreaseFontSize'
+    | 'resetFontSize';
+
+/* 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 +103,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. */
@@ -623,6 +644,8 @@ 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;
@@ -765,9 +788,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;
@@ -424,6 +431,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 +467,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 +479,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 {
@@ -591,8 +622,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) {
@@ -841,6 +877,7 @@ export class EditorView {
             this.find.refresh();
             this.announceFind();
             this.scheduleFolds();
+            this.todos.schedule();
             this.colorAhead(true);
         }
 
@@ -2963,7 +3000,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 +3036,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 +3267,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;
+    }
+}