@codingame/monaco-vscode-api 20.1.0 → 20.2.0

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

@@ -72,20 +72,46 @@ export declare class ViewLineMappingChangedEvent {
     constructor();
 }
 export declare class ViewLinesChangedEvent {
+    /**
+     * The first line that has changed.
+     */
     readonly fromLineNumber: number;
+    /**
+     * The number of lines that have changed.
+     */
     readonly count: number;
     readonly type = ViewEventType.ViewLinesChanged;
-    constructor(fromLineNumber: number, count: number);
+    constructor(
+    /**
+     * The first line that has changed.
+     */
+    fromLineNumber: number, 
+    /**
+     * The number of lines that have changed.
+     */
+    count: number);
 }
 export declare class ViewLinesDeletedEvent {
     readonly type = ViewEventType.ViewLinesDeleted;
+    /**
+     * At what line the deletion began (inclusive).
+     */
     readonly fromLineNumber: number;
+    /**
+     * At what line the deletion stopped (inclusive).
+     */
     readonly toLineNumber: number;
     constructor(fromLineNumber: number, toLineNumber: number);
 }
 export declare class ViewLinesInsertedEvent {
     readonly type = ViewEventType.ViewLinesInserted;
+    /**
+     * Before what line did the insertion begin
+     */
     readonly fromLineNumber: number;
+    /**
+     * `toLineNumber` - `fromLineNumber` + 1 denotes the number of lines that were inserted
+     */
     readonly toLineNumber: number;
     constructor(fromLineNumber: number, toLineNumber: number);
 }
@@ -99,15 +125,66 @@ export declare enum VerticalRevealType {
     NearTopIfOutsideViewport = 6
 }
 export declare class ViewRevealRangeRequestEvent {
+    /**
+     * Source of the call that caused the event.
+     */
     readonly source: string | null | undefined;
+    /**
+     * Reduce the revealing to a minimum (e.g. avoid scrolling if the bounding box is visible and near the viewport edge).
+     */
     readonly minimalReveal: boolean;
+    /**
+     * Range to be reavealed.
+     */
     readonly range: Range | null;
+    /**
+     * Selections to be revealed.
+     */
     readonly selections: Selection[] | null;
+    /**
+     * The vertical reveal strategy.
+     */
     readonly verticalType: VerticalRevealType;
+    /**
+     * If true: there should be a horizontal & vertical revealing.
+     * If false: there should be just a vertical revealing.
+     */
     readonly revealHorizontal: boolean;
+    /**
+     * The scroll type.
+     */
     readonly scrollType: ScrollType;
     readonly type = ViewEventType.ViewRevealRangeRequest;
-    constructor(source: string | null | undefined, minimalReveal: boolean, range: Range | null, selections: Selection[] | null, verticalType: VerticalRevealType, revealHorizontal: boolean, scrollType: ScrollType);
+    constructor(
+    /**
+     * Source of the call that caused the event.
+     */
+    source: string | null | undefined, 
+    /**
+     * Reduce the revealing to a minimum (e.g. avoid scrolling if the bounding box is visible and near the viewport edge).
+     */
+    minimalReveal: boolean, 
+    /**
+     * Range to be reavealed.
+     */
+    range: Range | null, 
+    /**
+     * Selections to be revealed.
+     */
+    selections: Selection[] | null, 
+    /**
+     * The vertical reveal strategy.
+     */
+    verticalType: VerticalRevealType, 
+    /**
+     * If true: there should be a horizontal & vertical revealing.
+     * If false: there should be just a vertical revealing.
+     */
+    revealHorizontal: boolean, 
+    /**
+     * The scroll type.
+     */
+    scrollType: ScrollType);
 }
 export declare class ViewScrollChangedEvent {
     readonly type = ViewEventType.ViewScrollChanged;
@@ -129,7 +206,13 @@ export declare class ViewThemeChangedEvent {
 export declare class ViewTokensChangedEvent {
     readonly type = ViewEventType.ViewTokensChanged;
     readonly ranges: {
+        /**
+         * Start line number of range
+         */
         readonly fromLineNumber: number;
+        /**
+         * End line number of range
+         */
         readonly toLineNumber: number;
     }[];
     constructor(ranges: {

package/vscode/src/vs/editor/common/viewLayout/lineDecorations.d.ts

@@ -21,5 +21,8 @@ export declare class DecorationSegment {
     constructor(startOffset: number, endOffset: number, className: string, metadata: number);
 }
 export declare class LineDecorationsNormalizer {
+    /**
+     * Normalize line decorations. Overlapping decorations will generate multiple segments
+     */
     static normalize(lineContent: string, lineDecorations: LineDecoration[]): DecorationSegment[];
 }

package/vscode/src/vs/editor/common/viewLayout/lineHeights.d.ts

@@ -8,6 +8,32 @@ export declare class CustomLine {
     deleted: boolean;
     constructor(decorationId: string, index: number, lineNumber: number, specialHeight: number, prefixSum: number);
 }
+/**
+ * Manages line heights in the editor with support for custom line heights from decorations.
+ *
+ * This class maintains an ordered collection of line heights, where each line can have either
+ * the default height or a custom height specified by decorations. It supports efficient querying
+ * of individual line heights as well as accumulated heights up to a specific line.
+ *
+ * Line heights are stored in a sorted array for efficient binary search operations. Each line
+ * with custom height is represented by a {@link CustomLine} object which tracks its special height,
+ * accumulated height prefix sum, and associated decoration ID.
+ *
+ * The class optimizes performance by:
+ * - Using binary search to locate lines in the ordered array
+ * - Batching updates through a pending changes mechanism
+ * - Computing prefix sums for O(1) accumulated height lookup
+ * - Tracking maximum height for lines with multiple decorations
+ * - Efficiently handling document changes (line insertions and deletions)
+ *
+ * When lines are inserted or deleted, the manager updates line numbers and prefix sums
+ * for all affected lines. It also handles special cases like decorations that span
+ * the insertion/deletion points by re-applying those decorations appropriately.
+ *
+ * All query operations automatically commit pending changes to ensure consistent results.
+ * Clients can modify line heights by adding or removing custom line height decorations,
+ * which are tracked by their unique decoration IDs.
+ */
 export declare class LineHeightsManager {
     private _decorationIDToCustomLine;
     private _orderedCustomLines;

package/vscode/src/vs/editor/common/viewLayout/linePart.d.ts

@@ -7,12 +7,19 @@ export declare enum LinePartMetadata {
     PSEUDO_AFTER_MASK = 4
 }
 export declare class LinePart {
+    /**
+     * last char index of this token (not inclusive).
+     */
     readonly endIndex: number;
     readonly type: string;
     readonly metadata: number;
     readonly containsRTL: boolean;
     _linePartBrand: void;
-    constructor(endIndex: number, type: string, metadata: number, containsRTL: boolean);
+    constructor(
+    /**
+     * last char index of this token (not inclusive).
+     */
+    endIndex: number, type: string, metadata: number, containsRTL: boolean);
     isWhitespace(): boolean;
     isPseudoAfter(): boolean;
 }

package/vscode/src/vs/editor/common/viewLayout/linesLayout.d.ts

@@ -17,6 +17,12 @@ export declare class EditorWhitespace implements IEditorWhitespace {
     prefixSum: number;
     constructor(id: string, afterLineNumber: number, ordinal: number, height: number, minWidth: number);
 }
+/**
+ * Layouting of objects that take vertical space (by having a height) and push down other objects.
+ *
+ * These objects are basically either text (lines) or spaces between those lines (whitespaces).
+ * This provides commodity operations for working with lines that contain whitespace that pushes lines lower (vertically).
+ */
 export declare class LinesLayout {
     private static INSTANCE_COUNT;
     private readonly _instanceId;
@@ -30,9 +36,24 @@ export declare class LinesLayout {
     private _paddingBottom;
     private _lineHeightsManager;
     constructor(lineCount: number, defaultLineHeight: number, paddingTop: number, paddingBottom: number, customLineHeightData: ICustomLineHeightData[]);
+    /**
+     * Find the insertion index for a new value inside a sorted array of values.
+     * If the value is already present in the sorted array, the insertion index will be after the already existing value.
+     */
     static findInsertionIndex(arr: EditorWhitespace[], afterLineNumber: number, ordinal: number): number;
+    /**
+     * Change the height of a line in pixels.
+     */
     setDefaultLineHeight(lineHeight: number): void;
+    /**
+     * Changes the padding used to calculate vertical offsets.
+     */
     setPadding(paddingTop: number, paddingBottom: number): void;
+    /**
+     * Set the number of lines.
+     *
+     * @param lineCount New number of lines.
+     */
     onFlushed(lineCount: number, customLineHeightData: ICustomLineHeightData[]): void;
     changeLineHeights(callback: (accessor: ILineHeightChangeAccessor) => void): boolean;
     changeWhitespace(callback: (accessor: IWhitespaceChangeAccessor) => void): boolean;
@@ -41,33 +62,142 @@ export declare class LinesLayout {
     private _findWhitespaceIndex;
     private _changeOneWhitespace;
     private _removeWhitespace;
+    /**
+     * Notify the layouter that lines have been deleted (a continuous zone of lines).
+     *
+     * @param fromLineNumber The line number at which the deletion started, inclusive
+     * @param toLineNumber The line number at which the deletion ended, inclusive
+     */
     onLinesDeleted(fromLineNumber: number, toLineNumber: number): void;
+    /**
+     * Notify the layouter that lines have been inserted (a continuous zone of lines).
+     *
+     * @param fromLineNumber The line number at which the insertion started, inclusive
+     * @param toLineNumber The line number at which the insertion ended, inclusive.
+     */
     onLinesInserted(fromLineNumber: number, toLineNumber: number): void;
+    /**
+     * Get the sum of all the whitespaces.
+     */
     getWhitespacesTotalHeight(): number;
+    /**
+     * Return the sum of the heights of the whitespaces at [0..index].
+     * This includes the whitespace at `index`.
+     *
+     * @param index The index of the whitespace.
+     * @return The sum of the heights of all whitespaces before the one at `index`, including the one at `index`.
+     */
     getWhitespacesAccumulatedHeight(index: number): number;
+    /**
+     * Get the sum of heights for all objects.
+     *
+     * @return The sum of heights for all objects.
+     */
     getLinesTotalHeight(): number;
+    /**
+     * Returns the accumulated height of whitespaces before the given line number.
+     *
+     * @param lineNumber The line number
+     */
     getWhitespaceAccumulatedHeightBeforeLineNumber(lineNumber: number): number;
     private _findLastWhitespaceBeforeLineNumber;
     private _findFirstWhitespaceAfterLineNumber;
+    /**
+     * Find the index of the first whitespace which has `afterLineNumber` >= `lineNumber`.
+     * @return The index of the first whitespace with `afterLineNumber` >= `lineNumber` or -1 if no whitespace is found.
+     */
     getFirstWhitespaceIndexAfterLineNumber(lineNumber: number): number;
+    /**
+     * Get the vertical offset (the sum of heights for all objects above) a certain line number.
+     *
+     * @param lineNumber The line number
+     * @return The sum of heights for all objects above `lineNumber`.
+     */
     getVerticalOffsetForLineNumber(lineNumber: number, includeViewZones?: boolean): number;
     getLineHeightForLineNumber(lineNumber: number): number;
+    /**
+     * Get the vertical offset (the sum of heights for all objects above) a certain line number and also the line height of the line.
+     *
+     * @param lineNumber The line number
+     * @return The sum of heights for all objects above `lineNumber`.
+     */
     getVerticalOffsetAfterLineNumber(lineNumber: number, includeViewZones?: boolean): number;
+    /**
+     * Returns if there is any whitespace in the document.
+     */
     hasWhitespace(): boolean;
+    /**
+     * The maximum min width for all whitespaces.
+     */
     getWhitespaceMinWidth(): number;
+    /**
+     * Check if `verticalOffset` is below all lines.
+     */
     isAfterLines(verticalOffset: number): boolean;
     isInTopPadding(verticalOffset: number): boolean;
     isInBottomPadding(verticalOffset: number): boolean;
+    /**
+     * Find the first line number that is at or after vertical offset `verticalOffset`.
+     * i.e. if getVerticalOffsetForLine(line) is x and getVerticalOffsetForLine(line + 1) is y, then
+     * getLineNumberAtOrAfterVerticalOffset(i) = line, x <= i < y.
+     *
+     * @param verticalOffset The vertical offset to search at.
+     * @return The line number at or after vertical offset `verticalOffset`.
+     */
     getLineNumberAtOrAfterVerticalOffset(verticalOffset: number): number;
+    /**
+     * Get all the lines and their relative vertical offsets that are positioned between `verticalOffset1` and `verticalOffset2`.
+     *
+     * @param verticalOffset1 The beginning of the viewport.
+     * @param verticalOffset2 The end of the viewport.
+     * @return A structure describing the lines positioned between `verticalOffset1` and `verticalOffset2`.
+     */
     getLinesViewportData(verticalOffset1: number, verticalOffset2: number): IPartialViewLinesViewportData;
     getVerticalOffsetForWhitespaceIndex(whitespaceIndex: number): number;
     getWhitespaceIndexAtOrAfterVerticallOffset(verticalOffset: number): number;
+    /**
+     * Get exactly the whitespace that is layouted at `verticalOffset`.
+     *
+     * @param verticalOffset The vertical offset.
+     * @return Precisely the whitespace that is layouted at `verticaloffset` or null.
+     */
     getWhitespaceAtVerticalOffset(verticalOffset: number): IViewWhitespaceViewportData | null;
+    /**
+     * Get a list of whitespaces that are positioned between `verticalOffset1` and `verticalOffset2`.
+     *
+     * @param verticalOffset1 The beginning of the viewport.
+     * @param verticalOffset2 The end of the viewport.
+     * @return An array with all the whitespaces in the viewport. If no whitespace is in viewport, the array is empty.
+     */
     getWhitespaceViewportData(verticalOffset1: number, verticalOffset2: number): IViewWhitespaceViewportData[];
+    /**
+     * Get all whitespaces.
+     */
     getWhitespaces(): IEditorWhitespace[];
+    /**
+     * The number of whitespaces.
+     */
     getWhitespacesCount(): number;
+    /**
+     * Get the `id` for whitespace at index `index`.
+     *
+     * @param index The index of the whitespace.
+     * @return `id` of whitespace at `index`.
+     */
     getIdForWhitespaceIndex(index: number): string;
+    /**
+     * Get the `afterLineNumber` for whitespace at index `index`.
+     *
+     * @param index The index of the whitespace.
+     * @return `afterLineNumber` of whitespace at `index`.
+     */
     getAfterLineNumberForWhitespaceIndex(index: number): number;
+    /**
+     * Get the `height` for whitespace at index `index`.
+     *
+     * @param index The index of the whitespace.
+     * @return `height` of whitespace at `index`.
+     */
     getHeightForWhitespaceIndex(index: number): number;
 }
 export {};

package/vscode/src/vs/editor/common/viewLayout/viewLineRenderer.d.ts

@@ -31,7 +31,14 @@ export declare class RenderLineInput {
     readonly fontLigatures: boolean;
     readonly textDirection: TextDirection | null;
     readonly verticalScrollbarSize: number;
+    /**
+     * Defined only when renderWhitespace is 'selection'. Selections are non-overlapping,
+     * and ordered by position within the line.
+     */
     readonly selectionsOnLine: OffsetRange[] | null;
+    /**
+     * When rendering an empty line, whether to render a new line instead
+     */
     readonly renderNewLineWhenEmpty: boolean;
     get isLTR(): boolean;
     constructor(useMonospaceOptimizations: boolean, canUseHalfwidthRightwardsArrow: boolean, lineContent: string, continuesWithWrappedLine: boolean, isBasicASCII: boolean, containsRTL: boolean, fauxIndentLength: number, lineTokens: IViewLineTokens, lineDecorations: LineDecoration[], tabSize: number, startVisibleColumn: number, spaceWidth: number, middotWidth: number, wsmiddotWidth: number, stopRenderingLineAfter: number, renderWhitespace: "none" | "boundary" | "selection" | "trailing" | "all", renderControlCharacters: boolean, fontLigatures: boolean, selectionsOnLine: OffsetRange[] | null, textDirection: TextDirection | null, verticalScrollbarSize: number, renderNewLineWhenEmpty?: boolean);
@@ -43,6 +50,9 @@ export declare class DomPosition {
     readonly charIndex: number;
     constructor(partIndex: number, charIndex: number);
 }
+/**
+ * Provides a both direction mapping between a line's character and its rendered position.
+ */
 export declare class CharacterMapping {
     private static getPartIndex;
     private static getCharIndex;

package/vscode/src/vs/editor/common/viewLayout/viewLinesViewportData.d.ts

@@ -2,13 +2,34 @@ import { Range } from "../core/range.js";
 import { Selection } from "../core/selection.js";
 import { IPartialViewLinesViewportData, IViewModel, IViewWhitespaceViewportData, ViewLineRenderingData } from "../viewModel.js";
 import { ViewModelDecoration } from "../viewModel/viewModelDecoration.js";
+/**
+ * Contains all data needed to render at a specific viewport.
+ */
 export declare class ViewportData {
     readonly selections: Selection[];
+    /**
+     * The line number at which to start rendering (inclusive).
+     */
     readonly startLineNumber: number;
+    /**
+     * The line number at which to end rendering (inclusive).
+     */
     readonly endLineNumber: number;
+    /**
+     * relativeVerticalOffset[i] is the `top` position for line at `i` + `startLineNumber`.
+     */
     readonly relativeVerticalOffset: number[];
+    /**
+     * The viewport as a range (startLineNumber,1) -> (endLineNumber,maxColumn(endLineNumber)).
+     */
     readonly visibleRange: Range;
+    /**
+     * Value to be substracted from `scrollTop` (in order to vertical offset numbers < 1MM)
+     */
     readonly bigNumbersDelta: number;
+    /**
+     * Positioning information about gaps whitespace.
+     */
     readonly whitespaceViewportData: IViewWhitespaceViewportData[];
     private readonly _model;
     readonly lineHeight: number;

package/vscode/src/vs/editor/common/viewModel/modelLineProjection.d.ts

@@ -6,6 +6,9 @@ import { InjectedText, ModelLineProjectionData } from "../modelLineProjectionDat
 import { ViewLineData } from "../viewModel.js";
 export interface IModelLineProjection {
     isVisible(): boolean;
+    /**
+     * This invalidates the current instance (potentially reuses and returns it again).
+    */
     setVisible(isVisible: boolean): IModelLineProjection;
     getProjectionData(): ModelLineProjectionData | null;
     getViewLineCount(): number;

package/vscode/src/vs/editor/common/viewModel/overviewZoneManager.d.ts

@@ -6,10 +6,16 @@ export declare class ColorZone {
     constructor(from: number, to: number, colorId: number);
     static compare(a: ColorZone, b: ColorZone): number;
 }
+/**
+ * A zone in the overview ruler
+ */
 export declare class OverviewRulerZone {
     _overviewRulerZoneBrand: void;
     readonly startLineNumber: number;
     readonly endLineNumber: number;
+    /**
+     * If set to 0, the height in lines will be determined based on `endLineNumber`.
+     */
     readonly heightInLines: number;
     readonly color: string;
     private _colorZone;

package/vscode/src/vs/editor/common/viewModel/viewModelDecorations.d.ts

@@ -6,9 +6,21 @@ import { IViewModelLines } from "./viewModelLines.js";
 import { ViewModelDecoration } from "./viewModelDecoration.js";
 import { InlineDecoration } from "./inlineDecorations.js";
 import { ICoordinatesConverter } from "../coordinatesConverter.js";
+/**
+ * A collection of decorations in a range of lines.
+ */
 export interface IViewDecorationsCollection {
+    /**
+     * decorations in the range of lines (ungrouped).
+     */
     readonly decorations: ViewModelDecoration[];
+    /**
+     * inline decorations (grouped by each line in the range of lines).
+     */
     readonly inlineDecorations: InlineDecoration[][];
+    /**
+     * Whether the decorations affect the fonts.
+     */
     readonly hasVariableFonts: boolean;
 }
 export declare class ViewModelDecorations implements IDisposable {

package/vscode/src/vs/editor/common/viewModel/viewModelImpl.d.ts

@@ -60,6 +60,11 @@ export declare class ViewModel extends Disposable implements IViewModel {
     private readonly hiddenAreasModel;
     private previousHiddenAreas;
     getFontSizeAtPosition(position: IPosition): string | null;
+    /**
+     * @param forceUpdate If true, the hidden areas will be updated even if the new ranges are the same as the previous ranges.
+     * This is because the model might have changed, which resets the hidden areas, but not the last cached value.
+     * This needs a better fix in the future.
+    */
     setHiddenAreas(ranges: Range[], source?: unknown, forceUpdate?: boolean): void;
     getVisibleRangesPlusViewportAboveBelow(): Range[];
     getVisibleRanges(): Range[];
@@ -75,6 +80,9 @@ export declare class ViewModel extends Disposable implements IViewModel {
     private _reduceRestoreStateCompatibility;
     private getTabSize;
     getLineCount(): number;
+    /**
+     * Gives a hint that a lot of requests are about to come in for these line numbers.
+     */
     setViewport(startLineNumber: number, endLineNumber: number, centeredLineNumber: number): void;
     getActiveIndentGuide(lineNumber: number, minLineNumber: number, maxLineNumber: number): IActiveIndentGuideInfo;
     getLinesIndentGuides(startLineNumber: number, endLineNumber: number): number[];
@@ -142,8 +150,15 @@ export declare class ViewModel extends Disposable implements IViewModel {
     private _withViewEventsCollector;
     batchEvents(callback: () => void): void;
     normalizePosition(position: Position, affinity: PositionAffinity): Position;
+    /**
+     * Gets the column at which indentation stops at a given line.
+     * @internal
+    */
     getLineIndentColumn(lineNumber: number): number;
 }
 export interface IBatchableTarget {
+    /**
+     * Allows the target to apply the changes introduced by the callback in a batch.
+    */
     batchChanges<T>(cb: () => T): T;
 }

package/vscode/src/vs/editor/common/viewModel/viewModelLines.d.ts

@@ -39,6 +39,10 @@ export interface IViewModelLines extends IDisposable {
     getDecorationsInRange(range: Range, ownerId: number, filterOutValidation: boolean, filterFontDecorations: boolean, onlyMinimapDecorations: boolean, onlyMarginDecorations: boolean): IModelDecoration[];
     getInjectedTextAt(viewPosition: Position): InjectedText | null;
     normalizePosition(position: Position, affinity: PositionAffinity): Position;
+    /**
+     * Gets the column at which indentation stops at a given line.
+     * @internal
+    */
     getLineIndentColumn(lineNumber: number): number;
 }
 export declare class ViewModelLinesFromProjectedModel implements IViewModelLines {
@@ -55,6 +59,9 @@ export declare class ViewModelLinesFromProjectedModel implements IViewModelLines
     private wrappingStrategy;
     private wrapOnEscapedLineFeeds;
     private modelLineProjections;
+    /**
+     * Reflects the sum of the line counts of all projected model lines.
+    */
     private projectedModelLineLineCounts;
     private hiddenAreasDecorationIds;
     constructor(editorId: number, model: ITextModel, domLineBreaksComputerFactory: ILineBreaksComputerFactory, monospaceLineBreaksComputerFactory: ILineBreaksComputerFactory, fontInfo: FontInfo, tabSize: number, wrappingStrategy: "simple" | "advanced", wrappingColumn: number, wrappingIndent: WrappingIndent, wordBreak: "normal" | "keepAll", wrapOnEscapedLineFeeds: boolean);
@@ -100,6 +107,9 @@ export declare class ViewModelLinesFromProjectedModel implements IViewModelLines
     convertViewPositionToModelPosition(viewLineNumber: number, viewColumn: number): Position;
     convertViewRangeToModelRange(viewRange: Range): Range;
     convertModelPositionToViewPosition(_modelLineNumber: number, _modelColumn: number, affinity?: PositionAffinity, allowZeroLineNumber?: boolean, belowHiddenRanges?: boolean): Position;
+    /**
+     * @param affinity The affinity in case of an empty range. Has no effect for non-empty ranges.
+    */
     convertModelRangeToViewRange(modelRange: Range, affinity?: PositionAffinity): Range;
     getViewLineNumberOfModelPosition(modelLineNumber: number, modelColumn: number): number;
     getDecorationsInRange(range: Range, ownerId: number, filterOutValidation: boolean, filterFontDecorations: boolean, onlyMinimapDecorations: boolean, onlyMarginDecorations: boolean): IModelDecoration[];