@vscode/markdown-editor 0.0.2-4 → 0.0.2-6

package/dist/index.d.ts

@@ -338,6 +338,13 @@ export declare class CursorView extends Disposable {
 export declare interface CursorViewOptions {
     readonly offset: IObservable<SourceOffset | undefined>;
     readonly visualLineMap: IObservable<VisualLineMap>;
+    /**
+     * When set, the caret is drawn over the transient empty paragraph instead
+     * of at {@link offset} — its rect (in client coordinates) 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 {
@@ -383,13 +390,14 @@ declare interface DocumentBlockViewData {
     readonly view: BlockViewData;
 }
 
-/** A mounted document child: a block or a run of inter-block glue. */
+/** A mounted document child: a block, a run of inter-block glue, or the
+ * transient empty paragraph (see {@link PendingParagraphViewData}). */
 declare interface DocumentChildViewData {
     readonly absoluteStart: number;
     /** For a block: selection reaches it. For glue: always false (unowned, hidden). */
     readonly isActive: boolean;
-    readonly view: BlockViewData | GlueViewData;
-    readonly kind: 'block' | 'glue';
+    readonly view: BlockViewData | GlueViewData | PendingParagraphViewData;
+    readonly kind: 'block' | 'glue' | 'pendingParagraph';
 }
 
 /**
@@ -445,6 +453,8 @@ 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;
     static create(viewData: DocumentViewData, options: BlockViewOptions | undefined, previous: DocumentViewNode | undefined): DocumentViewNode;
     private constructor();
     /** The stable content element this document mounts its children into. */
@@ -492,7 +502,14 @@ export declare class EditorController extends Disposable {
     /** Move the cursor up one visual line (Arrow Up). */
     cursorUp(extend?: boolean): void;
     private _selectedText;
+    private readonly _updateModifierState;
+    private readonly _clearModifierState;
     private readonly _handleKeyDown;
+    /**
+     * Context-aware Enter: splits / line-breaks via {@link insertSmartEnter}, or
+     * arms a transient empty paragraph when at the end of a paragraph.
+     */
+    private _smartEnter;
 }
 
 /** Options for an {@link EditorController}. */
@@ -520,6 +537,20 @@ export declare class EditorModel {
      * (e.g. an inactive/unfocused rendering).
      */
     readonly selection: ISettableObservable<Selection_2 | undefined, void>;
+    /**
+     * Whether a Ctrl/Cmd modifier is currently held. Set by the controller from
+     * live keyboard state; the view reads it to show the link-open affordance
+     * (underline + pointer cursor) only while a Ctrl/Cmd+click would open a link
+     * whose block is active.
+     */
+    readonly ctrlOrMetaDown: ISettableObservable<boolean, void>;
+    /**
+     * Gutter markers (source-control style change indicators) painted in the
+     * left gutter. Each entry maps a source {@link OffsetRange} to a change kind
+     * — see {@link GutterMarker}. Purely decorative: markers never affect the
+     * parsed {@link document}, selection, or layout. Empty by default.
+     */
+    readonly gutterMarkers: ISettableObservable<readonly GutterMarker[], void>;
     /**
      * Forces the rendered active-block set. `undefined` (the default)
      * derives the set from the current selection range (see
@@ -528,6 +559,13 @@ export declare class EditorModel {
      * collapsed/inactive rendering.
      */
     readonly activeBlocksOverride: ISettableObservable<readonly BlockAstNode[] | typeof NO_ACTIVE_BLOCKS | undefined, void>;
+    /**
+     * The transient empty-paragraph editing state, or `undefined` when none is
+     * armed. See {@link PendingParagraph}. This is *not* document data — it is
+     * cleared by any source edit and lives only between the Enter that armed it
+     * and the next keystroke.
+     */
+    readonly pendingParagraph: ISettableObservable<PendingParagraph | undefined, void>;
     readonly cursorOffset: IObservableWithChange<number | undefined, void>;
     /**
      * The parsed document. Threads the previous document into the parser so
@@ -551,6 +589,24 @@ export declare class EditorModel {
      * collapsed this is a one-element set holding {@link activeBlock}.
      */
     readonly activeBlocks: IObservableWithChange<Set<BlockAstNode>, void>;
+    /**
+     * Arm a {@link PendingParagraph} at the given gap, minting a fresh synthetic
+     * 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;
+    /** Discard the pending paragraph (if any) without touching the source. */
+    cancelPendingParagraph(): void;
+    /**
+     * Turn the pending paragraph into real source: rewrite its gap so the typed
+     * `text` becomes its own paragraph, separated from its neighbours by blank
+     * lines, and place the caret after the inserted text.
+     */
+    materializePendingParagraph(text: string): void;
     applyEdit(edit: StringEdit): void;
     applyEditForSelection(edit: StringEdit): void;
 }
@@ -593,6 +649,7 @@ export declare class EditorView extends Disposable {
     private readonly _contentContainer;
     private readonly _cursorView;
     private readonly _selectionView;
+    private readonly _gutterMarkersView;
     /**
      * The mounted block sequence, in source order. Rebuilt (not mutated) each
      * frame by {@link DocumentViewNode.create}; the view just swaps one
@@ -612,6 +669,13 @@ export declare class EditorView extends Disposable {
     /** The current view-data tree (AST overlaid with selection flags), for debugging. */
     private readonly _viewData;
     get viewData(): IObservable<DocumentViewData | undefined>;
+    /**
+     * Caret rect (client coords) 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
@@ -619,6 +683,13 @@ export declare class EditorView extends Disposable {
      */
     private readonly _selectionBlocksObs;
     constructor(_model: EditorModel, _options?: EditorViewOptions | undefined);
+    /**
+     * Mirrors the model's live Ctrl/Cmd state onto the editor root as
+     * `.md-mod-down` so CSS can show the link-open underline and pointer cursor
+     * only while a click would actually open the link: an inactive link opens on
+     * a plain click, but an active link only opens with the modifier held.
+     */
+    private _setupModifierTracking;
     focus(): void;
     /**
      * Client coordinates → absolute source offset (any block). Used during
@@ -731,6 +802,29 @@ declare class GlueViewData {
     decorateNewline: boolean);
 }
 
+/**
+ * A single gutter marker: a source {@link OffsetRange} tagged with a
+ * {@link GutterMarkerType}. The view resolves the range to the visual lines it
+ * covers and paints a bar (or, for `deleted`, a wedge at the range position) in
+ * the left gutter.
+ *
+ * A `deleted` marker is normally an empty range (`range.isEmpty`) sitting at the
+ * boundary where the removed text used to be — there is nothing left to span,
+ * so it is drawn as a caret between lines rather than a bar.
+ */
+export declare interface GutterMarker {
+    readonly range: OffsetRange;
+    readonly type: GutterMarkerType;
+}
+
+/**
+ * The kind of change a gutter marker represents, mirroring the three states a
+ * source-control diff distinguishes (the git change markers in the editor
+ * gutter): a freshly inserted region, an edited region, and a point where
+ * content was removed.
+ */
+export declare type GutterMarkerType = 'added' | 'modified' | 'deleted';
+
 export declare class HeadingAstNode extends BlockAstNodeBase {
     readonly level: 1 | 2 | 3 | 4 | 5 | 6;
     readonly marker: MarkerAstNode;
@@ -881,6 +975,21 @@ export declare const insertLineBreak: EditCommand;
 
 export declare const insertParagraph: EditCommand;
 
+/**
+ * Context-aware Enter. The behaviour is chosen from the active block:
+ *  - paragraph / heading / thematic break — the "rich text" thing: at the
+ *    block's end arm a transient empty paragraph (see {@link SmartEnterResult});
+ *    elsewhere split into two paragraphs (`\n\n`).
+ *  - code block — insert a newline that preserves the current line's indentation,
+ *    staying inside the fence.
+ *  - block quote — continue the quote (`\n> `); an empty quote line exits it.
+ *  - list — continue the list with the next marker (incrementing ordered
+ *    numbers, re-emitting task checkboxes); an empty item exits the list.
+ * A non-collapsed selection, or any other block, falls back to a plain soft line
+ * break, preserving today's behaviour.
+ */
+export declare const insertSmartEnter: (ctx: CursorCommandContext) => SmartEnterResult;
+
 export declare function insertText(text: string): EditCommand;
 
 /**
@@ -1296,6 +1405,45 @@ declare class ParagraphViewData {
     constructor(ast: ParagraphAstNode, content: readonly AnyViewData[]);
 }
 
+/**
+ * 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).
+ */
+declare interface PendingParagraph {
+    /** The paragraph 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 {@link replaceRange} ends at the end of the document. */
+    readonly atEof: boolean;
+    /**
+     * 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`).
+     * It is never part of {@link document}.
+     */
+    readonly syntheticAst: ParagraphAstNode;
+}
+
+/**
+ * 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.
+ */
+declare class PendingParagraphViewData {
+    readonly ast: ParagraphAstNode;
+    readonly kind = "pendingParagraph";
+    constructor(ast: ParagraphAstNode);
+}
+
 /**
  * Immutable point in 2D space, in CSS-pixel client coordinates.
  */
@@ -1413,6 +1561,25 @@ export declare class SelectionViewRendering {
 
 export declare const selectWord: SelectionCommand;
 
+/**
+ * The outcome of {@link insertSmartEnter}: either a concrete source edit (the
+ * ordinary cases), or a request to arm a transient empty paragraph (Enter at
+ * the very end of a paragraph), which the controller turns into
+ * {@link EditorModel.armPendingParagraph} rather than a source edit. Modelling
+ * the empty paragraph as state instead of source keeps the document valid
+ * Markdown — which has no empty-paragraph node — until the user actually types.
+ */
+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;
+};
+
 /**
  * A run of {@link Token}s together with the exact {@link OffsetRange} they
  * cover.