@vscode/markdown-editor 0.0.2-58 → 0.0.2-59

package/dist/index.d.ts

@@ -609,7 +609,7 @@ declare interface CompleteHtmlCommentSource extends HtmlCommentSourceBase {
  */
 export declare function createDefaultMonacoSyntaxHighlighter(monaco: IMonarchApi, grammars: IDefaultMonarchGrammars): MonacoSyntaxHighlighter;
 
-export declare type CursorCommand = (ctx: CursorCommandContext) => SourceOffset;
+export declare type CursorCommand = (ctx: CursorCommandContext) => CursorPosition;
 
 export declare interface CursorCommandContext {
     readonly text: string;
@@ -618,6 +618,7 @@ export declare interface CursorCommandContext {
     readonly activeBlock: BlockAstNode | undefined;
     readonly markerVisibleBlocks: ReadonlySet<BlockAstNode>;
     readonly wordNavigationConfig: WordNavigationConfig;
+    readonly cursorPosition: CursorPosition;
 }
 
 export declare const cursorDocumentEnd: CursorCommand;
@@ -637,12 +638,26 @@ export declare const cursorLineStart: CursorCommand;
 export declare const cursorMoveLeft: CursorCommand;
 
 export declare interface CursorMoveResult {
-    readonly offset: SourceOffset;
+    readonly position: CursorPosition;
     readonly desiredColumn: number | undefined;
 }
 
 export declare const cursorMoveRight: CursorCommand;
 
+/** The cursor's position in either source text or a source-less visual line. */
+export declare type CursorPosition = {
+    readonly kind: 'source';
+    readonly offset: SourceOffset;
+} | {
+    readonly kind: 'virtual';
+    readonly line: VirtualCursorLine;
+};
+
+export declare namespace CursorPosition {
+    export function source(offset: SourceOffset): CursorPosition;
+    export function virtual(line: VirtualCursorLine): CursorPosition;
+}
+
 export declare const cursorRight: CursorCommand;
 
 export declare const cursorUp: VisualCursorCommand;
@@ -651,8 +666,8 @@ export declare const cursorUp: VisualCursorCommand;
  * Owns the blinking cursor DOM element.
  *
  * The rendering pipeline is a single `derived` whose compute callback
- * asks the {@link VisualLineMap} for the caret rect at the current
- * offset, writes it to {@link element}, and returns a
+ * asks the {@link VisualLineMap} for the caret rect at the current source or
+ * virtual position, writes it to {@link element}, and returns a
  * {@link CursorViewRendering} value as proof. An autorun keeps the
  * derived subscribed.
  */
@@ -663,7 +678,7 @@ export declare class CursorView extends Disposable {
 }
 
 export declare interface CursorViewOptions {
-    readonly offset: IObservable<SourceOffset | undefined>;
+    readonly position: IObservable<CursorPosition | undefined>;
     readonly visualLineMap: IObservable<VisualLineMap>;
     /**
      * The mounted blocks, used to hide the caret when it sits at an offset that
@@ -671,20 +686,13 @@ export declare interface CursorViewOptions {
      * matching how the selection is clipped there.
      */
     readonly blocks?: IObservable<readonly SelectionBlock[]>;
-    /**
-     * When set, the caret is drawn over the transient empty paragraph instead
-     * of at {@link offset} — its editor-local rect comes straight
-     * from that synthetic element's geometry, since it has no visual-line-map
-     * entry. Takes priority over the normal offset-based placement.
-     */
-    readonly pendingCaretRect?: IObservable<Rect2D | undefined>;
 }
 
 export declare class CursorViewRendering {
-    readonly offset: SourceOffset;
+    readonly position: CursorPosition;
     readonly visible: boolean;
     readonly rect: Rect2D;
-    constructor(offset: SourceOffset, visible: boolean, rect: Rect2D);
+    constructor(position: CursorPosition, visible: boolean, rect: Rect2D);
 }
 
 export declare const cursorVisualLineEnd: VisualCursorCommand;
@@ -876,7 +884,7 @@ declare class DocumentViewData {
 export declare class DocumentViewNode extends ViewNode {
     readonly blocks: readonly DocumentBlock[];
     /** The transient empty-paragraph element, when one is armed. */
-    readonly pendingElement?: HTMLElement | undefined;
+    readonly pendingParagraph?: PendingParagraphViewNode | undefined;
     static create(viewData: DocumentViewData, options: BlockViewOptions | undefined, previous: DocumentViewNode | undefined): DocumentViewNode;
     private constructor();
     /** The stable content element this document mounts its children into. */
@@ -957,6 +965,7 @@ export declare class EditorController extends Disposable {
     private _executeVisualCursorCommand;
     private _cursorDown;
     private _setUserSelection;
+    private _applyCursorPosition;
     /** Move the cursor down one visual line (Arrow Down). */
     cursorDown(extend?: boolean): void;
     /** Move the cursor up one visual line (Arrow Up). */
@@ -1138,6 +1147,7 @@ export declare class EditorModel {
      */
     readonly pendingParagraph: ISettableObservable<PendingParagraph | undefined, void>;
     readonly cursorOffset: IObservableWithChange<number | undefined, void>;
+    readonly cursorPosition: IObservableWithChange<CursorPosition | undefined, void>;
     /**
      * The parsed document. Threads the previous document into the parser so
      * unchanged blocks keep their object identity across reparses (see
@@ -1188,7 +1198,7 @@ export declare class EditorModel {
      * AST node for it, and park the caret at the gap start. No source edit is
      * applied — the blank line exists only in the view until it is materialized.
      */
-    armPendingParagraph(req: Omit<PendingParagraph, 'syntheticAst'>): void;
+    armPendingParagraph(req: Omit<PendingParagraph, 'syntheticAst' | 'cursorLine'>): void;
     /** Discard the pending paragraph (if any) without touching the source. */
     cancelPendingParagraph(): void;
     /**
@@ -1290,13 +1300,6 @@ export declare class EditorView extends Disposable {
      */
     private readonly _focused;
     get focused(): IObservable<boolean>;
-    /**
-     * Caret rect (editor-local coordinates) for the transient empty paragraph, or
-     * `undefined` when none is armed. Set each frame from the synthetic
-     * paragraph element's geometry and fed to the {@link CursorView}, which has
-     * no visual-line-map entry to place the caret from otherwise.
-     */
-    private readonly _pendingCaretRect;
     /**
      * The block cache projected for views (selection painting) that need to
      * react to mount/unmount. Derived from {@link _document}, so it stays in
@@ -2420,13 +2423,16 @@ export declare interface MeasuredLayoutDebugViewOptions {
  * through this model and never touches view fields directly.
  */
 export declare class MeasuredLayoutModel {
-    readonly measurements: ISettableObservable<readonly BlockMeasurement[], void>;
+    private readonly _measurements;
+    readonly measurements: IObservable<readonly BlockMeasurement[]>;
+    private readonly _virtualLines;
     /**
      * Concatenated visual line map across all mounted blocks. Every per-block
      * map uses the same editor-local coordinate space, so concatenation is
      * well-formed without translation or re-sorting.
      */
     readonly visualLineMap: IObservableWithChange<VisualLineMap, void>;
+    setMeasurements(measurements: readonly BlockMeasurement[], virtualLines: readonly VirtualLineMeasurement[]): void;
 }
 
 /**
@@ -2557,6 +2563,8 @@ declare interface PendingParagraph {
     readonly separateFromPreviousBlock: boolean;
     /** Whether {@link replaceRange} ends at the end of the document. */
     readonly atEof: boolean;
+    /** The source-less visual line occupied by the pending caret. */
+    readonly cursorLine: VirtualCursorLine;
     /**
      * A throwaway AST node that exists only to give the synthetic view child a
      * stable identity across render frames (the view pairs nodes by `ast.id`).
@@ -2577,14 +2585,28 @@ declare interface PendingParagraphResult {
 /**
  * View-data for the transient empty paragraph (see `PendingParagraph` in the
  * model). It carries only the throwaway {@link ParagraphAstNode} that gives the
- * rendered blank line a stable identity across frames; it has no content and is
- * never measured or part of the selection geometry — the caret is positioned
- * over it via a dedicated rect, not via the visual-line map.
+ * rendered blank line a stable identity across frames, its anchor block, and
+ * its source-less cursor line. It has no source content or selection range.
  */
 declare class PendingParagraphViewData {
     readonly ast: ParagraphAstNode;
+    readonly anchorBlock: BlockAstNode;
+    readonly cursorLine: VirtualCursorLine;
     readonly kind = "pendingParagraph";
-    constructor(ast: ParagraphAstNode);
+    constructor(ast: ParagraphAstNode, anchorBlock: BlockAstNode, cursorLine: VirtualCursorLine);
+}
+
+/**
+ * The mounted transient empty paragraph: a `<p class="md-pending-paragraph">`
+ * holding a single `<br>` so it occupies a line's height. It is a leaf view
+ * node with no inline source content; the document view publishes its element
+ * geometry as a virtual visual line.
+ */
+declare class PendingParagraphViewNode extends ViewNode {
+    readonly element: HTMLElement;
+    readonly anchorBlock: BlockAstNode;
+    readonly cursorLine: VirtualCursorLine;
+    constructor(view: PendingParagraphViewData);
 }
 
 /**
@@ -3141,6 +3163,24 @@ export declare class ViewNode extends Disposable {
     forEachTextLeaf(nodeOffset: number, visitor: (leaf: ViewNode, leafOffset: number) => void): void;
 }
 
+/**
+ * A visual cursor line that has no representation in the source text.
+ *
+ * The two source offsets are the positions immediately before and after the
+ * virtual line. The object itself is the stable identity of the line.
+ */
+export declare class VirtualCursorLine {
+    readonly sourceOffsetBefore: SourceOffset;
+    readonly sourceOffsetAfter: SourceOffset;
+    constructor(sourceOffsetBefore: SourceOffset, sourceOffsetAfter: SourceOffset);
+}
+
+/** A measured source-less line inserted directly after a source block. */
+declare interface VirtualLineMeasurement {
+    readonly afterBlock: BlockAstNode;
+    readonly line: VisualLine;
+}
+
 export declare type VisualCursorCommand = (ctx: VisualCursorCommandContext) => CursorMoveResult;
 
 export declare interface VisualCursorCommandContext extends CursorCommandContext {
@@ -3158,7 +3198,9 @@ export declare function visualizeAst(root: AstNode, source: string): AstVisualiz
 export declare class VisualLine {
     readonly rect: Rect2D;
     readonly runs: readonly VisualRun[];
-    constructor(rect: Rect2D, runs: readonly VisualRun[]);
+    readonly virtualCursorLine?: VirtualCursorLine | undefined;
+    static virtual(cursorLine: VirtualCursorLine, rect: Rect2D): VisualLine;
+    constructor(rect: Rect2D, runs: readonly VisualRun[], virtualCursorLine?: VirtualCursorLine | undefined);
     containsOffset(offset: SourceOffset): boolean;
     /**
      * How `offset` relates to this line's runs:
@@ -3248,6 +3290,8 @@ export declare class VisualLineMap {
         readonly absoluteStart: number;
         readonly viewNode: ViewNode;
     }[], coordinateSpace: EditorCoordinateSpace, transform?: EditorCoordinateTransform): VisualLineMap;
+    /** Lines backed by source ranges, excluding source-less cursor lines. */
+    readonly sourceLines: readonly VisualLine[];
     constructor(lines: readonly VisualLine[]);
     get lineCount(): number;
     get isEmpty(): boolean;
@@ -3272,6 +3316,12 @@ export declare class VisualLineMap {
      * {@link lineIndexOfOffset}. Returns `0` when the map is empty.
      */
     xAtOffset(offset: SourceOffset): number;
+    /**
+     * Line occupied by a source or virtual cursor position. A virtual position
+     * returns `undefined` until its corresponding DOM line has been measured.
+     */
+    lineIndexOfPosition(position: CursorPosition): number | undefined;
+    xAtPosition(position: CursorPosition): number;
     /**
      * Line whose vertical band contains `y`, clamped to the first/last
      * line when `y` is outside the document.
@@ -3285,6 +3335,7 @@ export declare class VisualLineMap {
     offsetAtPoint(point: Point2D): SourceOffset;
     /** Snap `x` to the nearest offset on a specific line. */
     offsetInLineAtX(lineIndex: number, x: number): SourceOffset;
+    positionInLineAtX(lineIndex: number, x: number): CursorPosition;
     lineStartOffset(lineIndex: number): SourceOffset | undefined;
     lineEndOffset(lineIndex: number): SourceOffset | undefined;
 }