@codingame/monaco-vscode-api 20.1.1 → 20.2.0

package/vscode/src/vs/editor/common/config/fontInfo.d.ts

@@ -1,12 +1,28 @@
 import { EditorOption, FindComputedEditorOptionValueById } from "./editorOptions.js";
+/**
+ * Determined from empirical observations.
+ * @internal
+ */
 export declare const GOLDEN_LINE_HEIGHT_RATIO: number;
+/**
+ * @internal
+ */
 export declare const MINIMUM_LINE_HEIGHT = 8;
+/**
+ * @internal
+ */
 export interface IValidatedEditorOptions {
     get<T extends EditorOption>(id: T): FindComputedEditorOptionValueById<T>;
 }
 export declare class BareFontInfo {
     readonly _bareFontInfoBrand: void;
+    /**
+     * @internal
+     */
     static createFromValidatedSettings(options: IValidatedEditorOptions, pixelRatio: number, ignoreEditorZoom: boolean): BareFontInfo;
+    /**
+     * @internal
+     */
     static createFromRawSettings(opts: {
         fontFamily?: string;
         fontWeight?: string;
@@ -16,6 +32,9 @@ export declare class BareFontInfo {
         lineHeight?: number;
         letterSpacing?: number;
     }, pixelRatio: number, ignoreEditorZoom?: boolean): BareFontInfo;
+    /**
+     * @internal
+     */
     private static _create;
     readonly pixelRatio: number;
     readonly fontFamily: string;
@@ -25,6 +44,9 @@ export declare class BareFontInfo {
     readonly fontVariationSettings: string;
     readonly lineHeight: number;
     readonly letterSpacing: number;
+    /**
+     * @internal
+     */
     protected constructor(opts: {
         pixelRatio: number;
         fontFamily: string;
@@ -35,7 +57,13 @@ export declare class BareFontInfo {
         lineHeight: number;
         letterSpacing: number;
     });
+    /**
+     * @internal
+     */
     getId(): string;
+    /**
+     * @internal
+     */
     getMassagedFontFamily(): string;
     private static _wrapInQuotes;
 }
@@ -52,6 +80,9 @@ export declare class FontInfo extends BareFontInfo {
     readonly middotWidth: number;
     readonly wsmiddotWidth: number;
     readonly maxDigitWidth: number;
+    /**
+     * @internal
+     */
     constructor(opts: {
         pixelRatio: number;
         fontFamily: string;
@@ -70,5 +101,8 @@ export declare class FontInfo extends BareFontInfo {
         wsmiddotWidth: number;
         maxDigitWidth: number;
     }, isTrusted: boolean);
+    /**
+     * @internal
+     */
     equals(other: FontInfo): boolean;
 }

package/vscode/src/vs/editor/common/coordinatesConverter.d.ts

@@ -6,7 +6,14 @@ export interface ICoordinatesConverter {
     convertViewRangeToModelRange(viewRange: Range): Range;
     validateViewPosition(viewPosition: Position, expectedModelPosition: Position): Position;
     validateViewRange(viewRange: Range, expectedModelRange: Range): Range;
+    /**
+     * @param allowZeroLineNumber Should it return 0 when there are hidden lines at the top and the position is in the hidden area?
+     * @param belowHiddenRanges When the model position is in a hidden area, should it return the first view position after or before?
+     */
     convertModelPositionToViewPosition(modelPosition: Position, affinity?: PositionAffinity, allowZeroLineNumber?: boolean, belowHiddenRanges?: boolean): Position;
+    /**
+     * @param affinity Only has an effect if the range is empty.
+    */
     convertModelRangeToViewRange(modelRange: Range, affinity?: PositionAffinity): Range;
     modelPositionIsVisible(modelPosition: Position): boolean;
     getModelLineViewLineCount(modelLineNumber: number): number;

package/vscode/src/vs/editor/common/core/characterClassifier.d.ts

@@ -1,5 +1,14 @@
+/**
+ * A fast character classifier that uses a compact array for ASCII values.
+ */
 export declare class CharacterClassifier<T extends number> {
+    /**
+     * Maintain a compact (fully initialized ASCII map for quickly classifying ASCII characters - used more often in code).
+     */
     protected readonly _asciiMap: Uint8Array;
+    /**
+     * The entire map (sparse array).
+     */
     protected readonly _map: Map<number, number>;
     protected readonly _defaultValue: number;
     constructor(_defaultValue: T);

package/vscode/src/vs/editor/common/core/cursorColumns.d.ts

@@ -1,10 +1,54 @@
+/**
+ * A column in a position is the gap between two adjacent characters. The methods here
+ * work with a concept called "visible column". A visible column is a very rough approximation
+ * of the horizontal screen position of a column. For example, using a tab size of 4:
+ * ```txt
+ * |<TAB>|<TAB>|T|ext
+ * |     |     | \---- column = 4, visible column = 9
+ * |     |     \------ column = 3, visible column = 8
+ * |     \------------ column = 2, visible column = 4
+ * \------------------ column = 1, visible column = 0
+ * ```
+ *
+ * **NOTE**: Visual columns do not work well for RTL text or variable-width fonts or characters.
+ *
+ * **NOTE**: These methods work and make sense both on the model and on the view model.
+ */
 export declare class CursorColumns {
     private static _nextVisibleColumn;
+    /**
+     * Returns a visible column from a column.
+     * @see {@link CursorColumns}
+     */
     static visibleColumnFromColumn(lineContent: string, column: number, tabSize: number): number;
+    /**
+     * Returns the value to display as "Col" in the status bar.
+     * @see {@link CursorColumns}
+     */
     static toStatusbarColumn(lineContent: string, column: number, tabSize: number): number;
+    /**
+     * Returns a column from a visible column.
+     * @see {@link CursorColumns}
+     */
     static columnFromVisibleColumn(lineContent: string, visibleColumn: number, tabSize: number): number;
+    /**
+     * ATTENTION: This works with 0-based columns (as opposed to the regular 1-based columns)
+     * @see {@link CursorColumns}
+     */
     static nextRenderTabStop(visibleColumn: number, tabSize: number): number;
+    /**
+     * ATTENTION: This works with 0-based columns (as opposed to the regular 1-based columns)
+     * @see {@link CursorColumns}
+     */
     static nextIndentTabStop(visibleColumn: number, indentSize: number): number;
+    /**
+     * ATTENTION: This works with 0-based columns (as opposed to the regular 1-based columns)
+     * @see {@link CursorColumns}
+     */
     static prevRenderTabStop(column: number, tabSize: number): number;
+    /**
+     * ATTENTION: This works with 0-based columns (as opposed to the regular 1-based columns)
+     * @see {@link CursorColumns}
+     */
     static prevIndentTabStop(column: number, indentSize: number): number;
 }

package/vscode/src/vs/editor/common/core/editOperation.d.ts

@@ -1,8 +1,22 @@
 import { Position } from "./position.js";
 import { IRange, Range } from "./range.js";
+/**
+ * A single edit operation, that acts as a simple replace.
+ * i.e. Replace text at `range` with `text` in model.
+ */
 export interface ISingleEditOperation {
+    /**
+     * The range to replace. This can be empty to emulate a simple insert.
+     */
     range: IRange;
+    /**
+     * The text to replace with. This can be null to emulate a simple delete.
+     */
     text: string | null;
+    /**
+     * This indicates that this operation has "insert" semantics.
+     * i.e. forceMoveMarkers = true => if `range` is collapsed, all markers at the position will be moved.
+     */
     forceMoveMarkers?: boolean;
 }
 export declare class EditOperation {

package/vscode/src/vs/editor/common/core/editorColorRegistry.d.ts

@@ -1,3 +1,6 @@
+/**
+ * Definition of the editor colors
+ */
 export declare const editorLineHighlight: string;
 export declare const editorLineHighlightBorder: string;
 export declare const editorRangeHighlight: string;

package/vscode/src/vs/editor/common/core/edits/edit.d.ts

@@ -3,14 +3,48 @@ export declare abstract class BaseEdit<T extends BaseReplacement<T> = BaseReplac
     readonly replacements: readonly T[];
     constructor(replacements: readonly T[]);
     protected abstract _createNew(replacements: readonly T[]): TEdit;
+    /**
+     * Returns true if and only if this edit and the given edit are structurally equal.
+     * Note that this does not mean that the edits have the same effect on a given input!
+     * See `.normalize()` or `.normalizeOnBase(base)` for that.
+    */
     equals(other: TEdit): boolean;
     toString(): string;
+    /**
+     * Normalizes the edit by removing empty replacements and joining touching replacements (if the replacements allow joining).
+     * Two edits have an equal normalized edit if and only if they have the same effect on any input.
+     *
+     * ![](https://raw.githubusercontent.com/microsoft/vscode/refs/heads/main/src/vs/editor/common/core/edits/docs/BaseEdit_normalize.drawio.png)
+     *
+     * Invariant:
+     * ```
+     * (forall base: TEdit.apply(base).equals(other.apply(base))) <-> this.normalize().equals(other.normalize())
+     * ```
+     * and
+     * ```
+     * forall base: TEdit.apply(base).equals(this.normalize().apply(base))
+     * ```
+     *
+     */
     normalize(): TEdit;
+    /**
+     * Combines two edits into one with the same effect.
+     *
+     * ![](https://raw.githubusercontent.com/microsoft/vscode/refs/heads/main/src/vs/editor/common/core/edits/docs/BaseEdit_compose.drawio.png)
+     *
+     * Invariant:
+     * ```
+     * other.apply(this.apply(s0)) = this.compose(other).apply(s0)
+     * ```
+     */
     compose(other: TEdit): TEdit;
     decomposeSplit(shouldBeInE1: (repl: T) => boolean): {
         e1: TEdit;
         e2: TEdit;
     };
+    /**
+     * Returns the range of each replacement in the applied value.
+    */
     getNewRanges(): OffsetRange[];
     getJoinedReplaceRange(): OffsetRange | undefined;
     isEmpty(): boolean;
@@ -19,13 +53,29 @@ export declare abstract class BaseEdit<T extends BaseReplacement<T> = BaseReplac
     applyToOffset(originalOffset: number): number;
     applyToOffsetRange(originalRange: OffsetRange): OffsetRange;
     applyInverseToOffset(postEditsOffset: number): number;
+    /**
+     * Return undefined if the originalOffset is within an edit
+     */
     applyToOffsetOrUndefined(originalOffset: number): number | undefined;
+    /**
+     * Return undefined if the originalRange is within an edit
+     */
     applyToOffsetRangeOrUndefined(originalRange: OffsetRange): OffsetRange | undefined;
 }
 export declare abstract class BaseReplacement<TSelf extends BaseReplacement<TSelf>> {
+    /**
+     * The range to be replaced.
+    */
     readonly replaceRange: OffsetRange;
-    constructor(replaceRange: OffsetRange);
+    constructor(
+    /**
+     * The range to be replaced.
+    */
+    replaceRange: OffsetRange);
     abstract getNewLength(): number;
+    /**
+     * Precondition: TEdit.range.endExclusive === other.range.start
+    */
     abstract tryJoinTouching(other: TSelf): TSelf | undefined;
     abstract slice(newReplaceRange: OffsetRange, rangeInReplacement?: OffsetRange): TSelf;
     delta(offset: number): TSelf;
@@ -38,6 +88,10 @@ export declare abstract class BaseReplacement<TSelf extends BaseReplacement<TSel
 export type AnyEdit = BaseEdit<AnyReplacement, AnyEdit>;
 export type AnyReplacement = BaseReplacement<AnyReplacement>;
 export declare class Edit<T extends BaseReplacement<T>> extends BaseEdit<T, Edit<T>> {
+    /**
+     * Represents a set of edits to a string.
+     * All these edits are applied at once.
+    */
     static readonly empty: Edit<never>;
     static create<T extends BaseReplacement<T>>(replacements: readonly T[]): Edit<T>;
     static single<T extends BaseReplacement<T>>(replacement: T): Edit<T>;

package/vscode/src/vs/editor/common/core/edits/lengthEdit.d.ts

@@ -1,5 +1,8 @@
 import { OffsetRange } from "../ranges/offsetRange.js";
 import { AnyEdit, BaseEdit, BaseReplacement } from "./edit.js";
+/**
+ * Like a normal edit, but only captures the length information.
+*/
 export declare class LengthEdit extends BaseEdit<LengthReplacement, LengthEdit> {
     static readonly empty: LengthEdit;
     static fromEdit(edit: AnyEdit): LengthEdit;
@@ -9,6 +12,9 @@ export declare class LengthEdit extends BaseEdit<LengthReplacement, LengthEdit>
     static insert(offset: number, newLength: number): LengthEdit;
     static delete(range: OffsetRange): LengthEdit;
     static compose(edits: readonly LengthEdit[]): LengthEdit;
+    /**
+     * Creates an edit that reverts this edit.
+     */
     inverse(): LengthEdit;
     protected _createNew(replacements: readonly LengthReplacement[]): LengthEdit;
     applyArray<T>(arr: readonly T[], fillItem: T): T[];

package/vscode/src/vs/editor/common/core/edits/lineEdit.d.ts

@@ -3,13 +3,20 @@ import { StringEdit, StringReplacement } from "./stringEdit.js";
 import { TextReplacement, TextEdit } from "./textEdit.js";
 import { AbstractText } from "../text/abstractText.js";
 export declare class LineEdit {
+    /**
+     * Have to be sorted by start line number and non-intersecting.
+    */
     readonly replacements: readonly LineReplacement[];
     static readonly empty: LineEdit;
     static deserialize(data: SerializedLineEdit): LineEdit;
     static fromEdit(edit: StringEdit, initialValue: AbstractText): LineEdit;
     static fromTextEdit(edit: TextEdit, initialValue: AbstractText): LineEdit;
     static createFromUnsorted(edits: readonly LineReplacement[]): LineEdit;
-    constructor(replacements: readonly LineReplacement[]);
+    constructor(
+    /**
+     * Have to be sorted by start line number and non-intersecting.
+    */
+    replacements: readonly LineReplacement[]);
     isEmpty(): boolean;
     toEdit(initialValue: AbstractText): StringEdit;
     toString(): string;
@@ -17,6 +24,7 @@ export declare class LineEdit {
     getNewLineRanges(): LineRange[];
     mapLineNumber(lineNumber: number): number;
     mapLineRange(lineRange: LineRange): LineRange;
+    /** TODO improve, dont require originalLines */
     mapBackLineRange(lineRange: LineRange, originalLines: string[]): LineRange;
     touches(other: LineEdit): boolean;
     rebase(base: LineEdit): LineEdit;

package/vscode/src/vs/editor/common/core/edits/stringEdit.d.ts

@@ -4,12 +4,22 @@ import { BaseEdit, BaseReplacement } from "./edit.js";
 export declare abstract class BaseStringEdit<T extends BaseStringReplacement<T> = BaseStringReplacement<any>, TEdit extends BaseStringEdit<T, TEdit> = BaseStringEdit<any, any>> extends BaseEdit<T, TEdit> {
     get TReplacement(): T;
     static composeOrUndefined<T extends BaseStringEdit>(edits: readonly T[]): T | undefined;
+    /**
+     * r := trySwap(e1, e2);
+     * e1.compose(e2) === r.e1.compose(r.e2)
+    */
     static trySwap(e1: BaseStringEdit, e2: BaseStringEdit): {
         e1: StringEdit;
         e2: StringEdit;
     } | undefined;
     apply(base: string): string;
+    /**
+     * Creates an edit that reverts this edit.
+     */
     inverseOnSlice(getOriginalSlice: (start: number, endEx: number) => string): StringEdit;
+    /**
+     * Creates an edit that reverts this edit.
+     */
     inverse(original: string): StringEdit;
     rebaseSkipConflicting(base: StringEdit): StringEdit;
     tryRebase(base: StringEdit): StringEdit | undefined;
@@ -18,6 +28,9 @@ export declare abstract class BaseStringEdit<T extends BaseStringReplacement<T>
     isNeutralOn(text: string): boolean;
     removeCommonSuffixPrefix(originalText: string): StringEdit;
     normalizeEOL(eol: "\r\n" | "\n"): StringEdit;
+    /**
+     * If `e1.apply(source) === e2.apply(source)`, then `e1.normalizeOnSource(source).equals(e2.normalizeOnSource(source))`.
+    */
     normalizeOnSource(source: string): StringEdit;
     removeCommonSuffixAndPrefix(source: string): TEdit;
     applyOnText(docContents: StringText): StringText;
@@ -29,6 +42,9 @@ export declare abstract class BaseStringReplacement<T extends BaseStringReplacem
     getNewLength(): number;
     toString(): string;
     replace(str: string): string;
+    /**
+     * Checks if the edit would produce no changes when applied to the given text.
+     */
     isNeutralOn(text: string): boolean;
     removeCommonSuffixPrefix(originalText: string): StringReplacement;
     normalizeEOL(eol: "\r\n" | "\n"): StringReplacement;
@@ -38,6 +54,10 @@ export declare abstract class BaseStringReplacement<T extends BaseStringReplacem
     toEdit(): StringEdit;
     toJson(): ISerializedStringReplacement;
 }
+/**
+ * Represents a set of replacements to a string.
+ * All these replacements are applied at once.
+*/
 export declare class StringEdit extends BaseStringEdit<StringReplacement, StringEdit> {
     static readonly empty: StringEdit;
     static create(replacements: readonly StringReplacement[]): StringEdit;
@@ -47,11 +67,21 @@ export declare class StringEdit extends BaseStringEdit<StringReplacement, String
     static delete(range: OffsetRange): StringEdit;
     static fromJson(data: ISerializedStringEdit): StringEdit;
     static compose(edits: readonly StringEdit[]): StringEdit;
+    /**
+     * The replacements are applied in order!
+     * Equals `StringEdit.compose(replacements.map(r => r.toEdit()))`, but is much more performant.
+    */
     static composeSequentialReplacements(replacements: readonly StringReplacement[]): StringEdit;
     constructor(replacements: readonly StringReplacement[]);
     protected _createNew(replacements: readonly StringReplacement[]): StringEdit;
 }
+/**
+ * Warning: Be careful when changing this type, as it is used for serialization!
+*/
 export type ISerializedStringEdit = ISerializedStringReplacement[];
+/**
+ * Warning: Be careful when changing this type, as it is used for serialization!
+*/
 export interface ISerializedStringReplacement {
     txt: string;
     pos: number;
@@ -67,12 +97,19 @@ export declare class StringReplacement extends BaseStringReplacement<StringRepla
     slice(range: OffsetRange, rangeInReplacement?: OffsetRange): StringReplacement;
 }
 export declare function applyEditsToRanges(sortedRanges: OffsetRange[], edit: StringEdit): OffsetRange[];
+/**
+ * Represents data associated to a single edit, which survives certain edit operations.
+*/
 export interface IEditData<T> {
     join(other: T): T | undefined;
 }
 export declare class VoidEditData implements IEditData<VoidEditData> {
     join(other: VoidEditData): VoidEditData | undefined;
 }
+/**
+ * Represents a set of replacements to a string.
+ * All these replacements are applied at once.
+*/
 export declare class AnnotatedStringEdit<T extends IEditData<T>> extends BaseStringEdit<AnnotatedStringReplacement<T>, AnnotatedStringEdit<T>> {
     static readonly empty: AnnotatedStringEdit<never>;
     static create<T extends IEditData<T>>(replacements: readonly AnnotatedStringReplacement<T>[]): AnnotatedStringEdit<T>;

package/vscode/src/vs/editor/common/core/edits/textEdit.d.ts

@@ -11,6 +11,9 @@ export declare class TextEdit {
     static insert(position: Position, newText: string): TextEdit;
     static fromParallelReplacementsUnsorted(replacements: readonly TextReplacement[]): TextEdit;
     constructor(replacements: readonly TextReplacement[]);
+    /**
+     * Joins touching edits and removes empty edits.
+     */
     normalize(): TextEdit;
     mapPosition(position: Position): Position | Range;
     mapRange(range: Range): Range;

package/vscode/src/vs/editor/common/core/misc/rgba.d.ts

@@ -1,9 +1,25 @@
+/**
+ * A very VM friendly rgba datastructure.
+ * Please don't touch unless you take a look at the IR.
+ */
 export declare class RGBA8 {
     _rgba8Brand: void;
     static readonly Empty: RGBA8;
+    /**
+     * Red: integer in [0-255]
+     */
     readonly r: number;
+    /**
+     * Green: integer in [0-255]
+     */
     readonly g: number;
+    /**
+     * Blue: integer in [0-255]
+     */
     readonly b: number;
+    /**
+     * Alpha: integer in [0-255]
+     */
     readonly a: number;
     constructor(r: number, g: number, b: number, a: number);
     equals(other: RGBA8): boolean;

package/vscode/src/vs/editor/common/core/position.d.ts

@@ -1,23 +1,90 @@
+/**
+ * A position in the editor. This interface is suitable for serialization.
+ */
 export interface IPosition {
+    /**
+     * line number (starts at 1)
+     */
     readonly lineNumber: number;
+    /**
+     * column (the first character in a line is between column 1 and column 2)
+     */
     readonly column: number;
 }
+/**
+ * A position in the editor.
+ */
 export declare class Position {
+    /**
+     * line number (starts at 1)
+     */
     readonly lineNumber: number;
+    /**
+     * column (the first character in a line is between column 1 and column 2)
+     */
     readonly column: number;
     constructor(lineNumber: number, column: number);
+    /**
+     * Create a new position from this position.
+     *
+     * @param newLineNumber new line number
+     * @param newColumn new column
+     */
     with(newLineNumber?: number, newColumn?: number): Position;
+    /**
+     * Derive a new position from this position.
+     *
+     * @param deltaLineNumber line number delta
+     * @param deltaColumn column delta
+     */
     delta(deltaLineNumber?: number, deltaColumn?: number): Position;
+    /**
+     * Test if this position equals other position
+     */
     equals(other: IPosition): boolean;
+    /**
+     * Test if position `a` equals position `b`
+     */
     static equals(a: IPosition | null, b: IPosition | null): boolean;
+    /**
+     * Test if this position is before other position.
+     * If the two positions are equal, the result will be false.
+     */
     isBefore(other: IPosition): boolean;
+    /**
+     * Test if position `a` is before position `b`.
+     * If the two positions are equal, the result will be false.
+     */
     static isBefore(a: IPosition, b: IPosition): boolean;
+    /**
+     * Test if this position is before other position.
+     * If the two positions are equal, the result will be true.
+     */
     isBeforeOrEqual(other: IPosition): boolean;
+    /**
+     * Test if position `a` is before position `b`.
+     * If the two positions are equal, the result will be true.
+     */
     static isBeforeOrEqual(a: IPosition, b: IPosition): boolean;
+    /**
+     * A function that compares positions, useful for sorting
+     */
     static compare(a: IPosition, b: IPosition): number;
+    /**
+     * Clone this position.
+     */
     clone(): Position;
+    /**
+     * Convert to a human-readable representation.
+     */
     toString(): string;
+    /**
+     * Create a `Position` from an `IPosition`.
+     */
     static lift(pos: IPosition): Position;
+    /**
+     * Test if `obj` is an `IPosition`.
+     */
     static isIPosition(obj: any): obj is IPosition;
     toJSON(): IPosition;
 }