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

package/dist/index.d.ts

@@ -150,8 +150,12 @@ export declare class BlockQuoteAstNode extends BlockAstNodeBase {
 declare class BlockQuoteViewData {
     readonly ast: BlockQuoteAstNode;
     readonly content: readonly AnyViewData[];
+    /** False while a pending paragraph replaces the final marker-only line. */
+    readonly showFinalMarkerOnlyLine: boolean;
     readonly kind = "blockQuote";
-    constructor(ast: BlockQuoteAstNode, content: readonly AnyViewData[]);
+    constructor(ast: BlockQuoteAstNode, content: readonly AnyViewData[], 
+    /** False while a pending paragraph replaces the final marker-only line. */
+    showFinalMarkerOnlyLine: boolean);
 }
 
 /**
@@ -605,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;
@@ -614,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;
@@ -633,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;
@@ -647,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.
  */
@@ -659,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
@@ -667,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;
@@ -872,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. */
@@ -951,7 +963,9 @@ export declare class EditorController extends Disposable {
     private _executeEditCommand;
     private _runUndoableEdit;
     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). */
@@ -1133,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
@@ -1183,11 +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: {
-        anchorBlock: BlockAstNode;
-        replaceRange: OffsetRange;
-        atEof: boolean;
-    }): void;
+    armPendingParagraph(req: Omit<PendingParagraph, 'syntheticAst' | 'cursorLine'>): void;
     /** Discard the pending paragraph (if any) without touching the source. */
     cancelPendingParagraph(): void;
     /**
@@ -1289,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
@@ -2419,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;
 }
 
 /**
@@ -2537,23 +2544,27 @@ declare class ParagraphViewData {
 }
 
 /**
- * A *transient* editing state: the empty paragraph the user conjured by
- * pressing Enter at the end of a paragraph. Markdown has no empty-paragraph
- * node, so this never lives in {@link EditorModel['sourceText']} or the parsed
- * {@link EditorModel.document} — it is pure edit intent that the view renders
- * as a synthetic blank line and that the controller either *materializes* (the
- * user types) or *cancels* (the user navigates away / backspaces).
+ * A *transient* editing state: an empty paragraph adjacent to a real block.
+ * Markdown has no empty-paragraph node, so this never lives in
+ * {@link EditorModel['sourceText']} or the parsed {@link EditorModel.document}
+ * — it is pure edit intent that the view renders as a synthetic blank line and
+ * that the controller either *materializes* (the user types) or *cancels* (the
+ * user navigates away / backspaces).
  */
 declare interface PendingParagraph {
-    /** The paragraph the blank line is rendered directly after. */
+    /** The block the blank line is rendered directly after. */
     readonly anchorBlock: BlockAstNode;
     /**
      * Source region rewritten when the pending paragraph is materialized — the
      * gap between {@link anchorBlock}'s text and whatever follows it.
      */
     readonly replaceRange: OffsetRange;
+    /** Whether materialized text needs a blank-line separator before it. */
+    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`).
@@ -2562,17 +2573,40 @@ declare interface PendingParagraph {
     readonly syntheticAst: ParagraphAstNode;
 }
 
+declare interface PendingParagraphResult {
+    readonly kind: 'pending';
+    readonly anchorBlock: BlockAstNode;
+    readonly replaceRange: OffsetRange;
+    /** Whether materialized text needs a blank-line separator before it. */
+    readonly separateFromPreviousBlock: boolean;
+    readonly atEof: boolean;
+}
+
 /**
  * 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);
 }
 
 /**
@@ -2730,12 +2764,7 @@ export declare type SmartEnterResult = {
     readonly kind: 'edit';
     readonly edit: StringEdit;
     readonly selection: Selection_2;
-} | {
-    readonly kind: 'pending';
-    readonly anchorBlock: BlockAstNode;
-    readonly replaceRange: OffsetRange;
-    readonly atEof: boolean;
-};
+} | PendingParagraphResult;
 
 /**
  * A run of {@link Token}s together with the exact {@link OffsetRange} they
@@ -3134,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 {
@@ -3151,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:
@@ -3176,10 +3225,15 @@ export declare class VisualLine {
      * source offset (hidden-marker runs are appended last). So this scans all
      * runs rather than assuming any ordering:
      *
-     *  - If some run *covers* `offset`, its own geometry places the caret
-     *    (exact glyph boundary for text runs). In the active, markers-visible
-     *    form every offset is covered, so this branch keeps distinct offsets
-     *    distinct.
+     *  - A zero-source visual anchor owns its exact offset, so a marker-only line
+     *    wins over the preceding line's inclusive end boundary.
+     *  - Otherwise a run starting at `offset` owns that seam. This keeps an
+     *    out-of-flow prefix from placing the caret at its trailing edge when the
+     *    following body starts at a visually separate x.
+     *  - Otherwise, if some run *covers* `offset`, its own geometry places the
+     *    caret (exact glyph boundary for text runs). In the active,
+     *    markers-visible form every interior offset is covered, so this branch
+     *    keeps distinct offsets distinct.
      *  - Otherwise `offset` sits in a gap — a hidden inline marker such as the
      *    `**` of `**bold**`, or before/after the painted text. It snaps to the
      *    seam between the source-nearest runs on either side: the right edge of
@@ -3236,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;
@@ -3260,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.
@@ -3273,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;
 }