@vscode/markdown-editor 0.0.2-14 → 0.0.2-16

package/dist/index.d.ts

@@ -24,7 +24,7 @@ declare interface AnnotatedRange {
 }
 
 /** Every concrete node kind, for exhaustive consumer-side dispatch. */
-export declare type AnyAstNode = TextAstNode | MarkerAstNode | GlueAstNode | ThematicBreakAstNode | StrongAstNode | EmphasisAstNode | StrikethroughAstNode | InlineCodeAstNode | InlineMathAstNode | LinkAstNode | ImageAstNode | HeadingAstNode | ParagraphAstNode | CodeBlockAstNode | MathBlockAstNode | BlockQuoteAstNode | ListAstNode | ListItemAstNode | TableAstNode | TableRowAstNode | TableCellAstNode | DocumentAstNode;
+export declare type AnyAstNode = TextAstNode | MarkerAstNode | GlueAstNode | ThematicBreakAstNode | StrongAstNode | EmphasisAstNode | StrikethroughAstNode | InlineCodeAstNode | InlineMathAstNode | LinkAstNode | ImageAstNode | HeadingAstNode | ParagraphAstNode | CodeBlockAstNode | MathBlockAstNode | BlockQuoteAstNode | ListAstNode | ListItemAstNode | TableAstNode | TableRowAstNode | TableCellAstNode | DocumentAstNode | UnhandledBlockAstNode;
 
 declare type AnyViewData = DocumentViewData | BlockViewData | InlineViewData | ListItemViewData | TableRowViewData | TableCellViewData | MarkerViewData | GlueViewData | DiffHunkViewData | DiffDecorationViewData;
 
@@ -88,7 +88,7 @@ export declare class AsyncClipboardStrategy implements IClipboardStrategy {
     connect(context: IClipboardContext): IDisposable;
 }
 
-export declare type BlockAstNode = HeadingAstNode | ParagraphAstNode | CodeBlockAstNode | MathBlockAstNode | ThematicBreakAstNode | BlockQuoteAstNode | ListAstNode | TableAstNode;
+export declare type BlockAstNode = HeadingAstNode | ParagraphAstNode | CodeBlockAstNode | MathBlockAstNode | ThematicBreakAstNode | BlockQuoteAstNode | ListAstNode | TableAstNode | UnhandledBlockAstNode;
 
 /**
  * A block-level node. Every block may carry a {@link leadingTrivia} glue — the
@@ -147,7 +147,7 @@ declare class BlockQuoteViewData {
     constructor(ast: BlockQuoteAstNode, content: readonly AnyViewData[]);
 }
 
-declare type BlockViewData = HeadingViewData | ParagraphViewData | CodeBlockViewData | MathBlockViewData | ThematicBreakViewData | BlockQuoteViewData | ListViewData | TableViewData;
+declare type BlockViewData = HeadingViewData | ParagraphViewData | CodeBlockViewData | MathBlockViewData | ThematicBreakViewData | BlockQuoteViewData | ListViewData | TableViewData | UnhandledBlockViewData;
 
 /**
  * Base view node for everything the editor renders, generic over the
@@ -191,9 +191,10 @@ export declare interface BlockViewOptions {
     /**
      * Opens a link's URL. Called when the user activates a link: a plain click
      * while the link's block is inactive (rendered), or a Ctrl/Cmd+click while it
-     * is active (source shown). Defaults to `window.open(url, '_blank')`.
+     * is active (source shown). Return `false` to use the anchor's native
+     * navigation behavior.
      */
-    readonly onOpenLink?: (url: string, event: MouseEvent) => void;
+    readonly onOpenLink?: (url: string, event: MouseEvent) => false | void;
     /**
      * Colours fenced code blocks. When set, a code block's content is rendered
      * as a sequence of token spans instead of one plain text node. This is the
@@ -213,6 +214,22 @@ export declare interface BlockViewOptions {
      * `katexEditableIdentifiers.ts`).
      */
     readonly renderMath?: (request: MathRenderRequest) => MathRendering | undefined;
+    /**
+     * Pluggable factory for an in-place, interactive editor that replaces the
+     * *rendered* (inactive) form of a fenced code block — see
+     * {@link IEmbeddedCodeEditor}. When it returns an editor for the block's
+     * language, that editor's element is mounted instead of the highlighted
+     * code, and content flows both ways as string edits. Returning `undefined`
+     * falls back to the default rendering. EXPERIMENTAL.
+     */
+    readonly embeddedCodeEditorFactory?: IEmbeddedCodeEditorFactory;
+    /**
+     * Called when an {@link IEmbeddedCodeEditor} edits its content. `contentEdit`
+     * is in the block's *content* coordinates; the host translates it to a
+     * document edit (via {@link CodeBlockAstNode.codeOffset} and the block's
+     * offset) and applies it to the model.
+     */
+    readonly onEmbeddedCodeEditorEdit?: (block: CodeBlockAstNode, contentEdit: StringEdit) => void;
 }
 
 export declare class CodeBlockAstNode extends BlockAstNodeBase {
@@ -288,6 +305,13 @@ export declare class CodeBlockViewNode extends BlockViewNode<CodeBlockViewData>
      * its predecessor's subscription explicitly.
      */
     private _snapshotSub;
+    /**
+     * An in-place interactive editor (e.g. an iframe) mounted instead of the
+     * rendered code. Like {@link _session} it is adopted from `previous` across
+     * rebuilds so the underlying editor keeps its state, and must be disposed
+     * manually (a node reused as `previous` is never {@link dispose}d).
+     */
+    private _embeddedEditor;
     constructor(data: CodeBlockViewData, options: BlockViewOptions | undefined, previous: ViewNode | undefined);
     dispose(): void;
 }
@@ -343,6 +367,8 @@ export declare class CommentInputWidget extends Disposable {
 export declare interface CommentInputWidgetOptions {
     /** Placeholder shown while the textarea is empty. Defaults to "Add Comment". */
     readonly placeholder?: string;
+    /** Called after the textarea changes size. */
+    readonly onDidChangeSize?: () => void;
     /**
      * Called when the user submits a non-empty comment (Enter or the send
      * button). The text is trimmed; never called with an empty string.
@@ -380,6 +406,7 @@ export declare class CommentModeController extends Disposable {
     private readonly _widget;
     private readonly _gap;
     private _visible;
+    private _anchorX;
     private _pinnedRange;
     /**
      * The range a comment was just submitted for. The box stays hidden for it
@@ -387,11 +414,10 @@ export declare class CommentModeController extends Disposable {
      * empty box on the still-selected text.
      */
     private _submittedRange;
-    /** True while a mouse button is held over the editor (a selection drag in progress). */
-    private readonly _mouseDown;
     constructor(_model: EditorModel, _view: EditorView, _options?: CommentModeControllerOptions | undefined);
     private _update;
     private _show;
+    private _layoutHorizontally;
     /** Force-hide and clear the box (used by Escape and submit). */
     private _hide;
     /**
@@ -577,6 +603,12 @@ export declare class CursorView extends Disposable {
 export declare interface CursorViewOptions {
     readonly offset: IObservable<SourceOffset | undefined>;
     readonly visualLineMap: IObservable<VisualLineMap>;
+    /**
+     * The mounted blocks, used to hide the caret when it sits at an offset that
+     * has been scrolled out of its (horizontally scrolling) block's viewport —
+     * 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 rect (in client coordinates) comes straight
@@ -798,14 +830,21 @@ export declare type EditCommand = (ctx: CursorCommandContext) => {
  *
  * Owns the only non-derivable controller state:
  * - `_desiredColumn` — sticky column for up/down navigation
+ * - `_clickCount` / `_lastPointerDown` — multi-click detection for pointer
+ *   input, since `pointerdown` events (unlike `mousedown`) don't populate
+ *   `detail` with a click count.
  */
 export declare class EditorController extends Disposable {
     private readonly _model;
     private readonly _view;
     private _desiredColumn;
+    /** Running click count for the current multi-click sequence (1, 2, 3, …). */
+    private _clickCount;
+    /** Timestamp and position of the previous pointer-down, for multi-click detection. */
+    private _lastPointerDown;
     constructor(_model: EditorModel, _view: EditorView, options?: EditorControllerOptions);
     private readonly _handleTextUpdate;
-    private readonly _handleMouseDown;
+    private readonly _handlePointerDown;
     private _makeCursorContext;
     private _makeVisualCursorContext;
     private _executeCursorCommand;
@@ -868,6 +907,14 @@ export declare class EditorModel {
      * whose block is active.
      */
     readonly ctrlOrMetaDown: ISettableObservable<boolean, void>;
+    /**
+     * Whether a pointer-driven selection drag is currently in progress. Set by
+     * the controller between the pointer-down that starts the drag and the
+     * pointer-up/cancel that ends it. Contributions read it to defer UI that
+     * would otherwise flicker mid-drag (e.g. the comment input box appears only
+     * once the drag ends).
+     */
+    readonly isSelecting: 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
@@ -1069,15 +1116,16 @@ export declare class EditorView extends Disposable {
     private _setupReadonlyToggle;
     focus(): void;
     /**
-     * Opt-in "own" point→offset resolution (a debug/experimental flag). When
-     * `false` (default), {@link resolveOffsetFromPoint} uses the platform DOM
-     * hit-test (`caretPositionFromPoint`). When `true`, it ignores the DOM
-     * hit-test and snaps the point to the nearest offset purely from the
-     * rendered {@link VisualLineMap} geometry — picking the nearest visual line
-     * by `y`, then the nearest offset on it by `x`. Because a table row's cells
-     * share one horizontal line band, this makes the whole width of a row
-     * resolve into that row (rather than only the cell boxes), with no visible
-     * layout change.
+     * Own point→offset resolution. When `true` (the default),
+     * {@link resolveOffsetFromPoint} ignores the platform DOM hit-test
+     * (`caretPositionFromPoint`) and snaps the point to the nearest offset purely
+     * from the rendered {@link VisualLineMap} geometry — picking the nearest
+     * visual line by `y`, then the nearest offset on it by `x`. Because a table
+     * row's cells share one horizontal line band, this makes the whole width of a
+     * row resolve into that row (rather than only the cell boxes), with no visible
+     * layout change. It also lets a drag keep extending toward off-viewport points
+     * (e.g. the pointer leaving the window), which the platform hit-test cannot
+     * resolve. Set to `false` to fall back to the platform DOM hit-test.
      */
     readonly geometricHitTest: ISettableObservable<boolean, void>;
     /**
@@ -1123,6 +1171,12 @@ export declare interface EditorViewOptions extends BlockViewOptions {
      * only) unless a theme class is supplied.
      */
     readonly classNames?: readonly string[];
+    /**
+     * Whether to render the sticky "Editing / Locked" readonly toggle in the
+     * top-right corner. Defaults to `true`; set to `false` to omit it (e.g. in
+     * fixtures that focus on selection rendering).
+     */
+    readonly showReadonlyToggle?: boolean;
     /**
      * Controls "limited width mode". The observable yields the maximum content
      * width in pixels, or `undefined` to let the content fill the available
@@ -1301,6 +1355,55 @@ export declare interface IDefaultMonarchGrammars {
     shell: unknown;
 }
 
+/**
+ * A live editor embedded in place of a fenced code block's *rendered* form.
+ *
+ * This is the internal seam between the block view and a concrete embedded
+ * editor (e.g. an `<iframe>` speaking the web-editor protocol). The block view
+ * only speaks string edits: it pushes the block's content down via
+ * {@link setContent} and receives the editor's own changes back through
+ * {@link onEdit} (set by the block view on each (re)construction, so it always
+ * routes to the current AST node). The concrete implementation owns its DOM,
+ * transport, and lifecycle.
+ *
+ * A single instance is adopted across re-renders (like the highlighter session)
+ * so the underlying editor keeps its state across edits — see
+ * {@link CodeBlockViewNode}.
+ */
+declare interface IEmbeddedCodeEditor {
+    /** The element mounted as the block's rendered form. */
+    readonly element: HTMLElement;
+    /**
+     * Document → editor. The block's content changed (from any source). Must be
+     * idempotent: pushing the content the editor already holds is a no-op, which
+     * is how edits the editor itself originated are prevented from echoing back.
+     */
+    setContent(content: string): void;
+    /**
+     * Optional synchronous height (px) to reserve for `content` *before* the
+     * editor has laid out. Return `undefined` to let the editor size itself
+     * (the implementation may report its real height later). Lets a registration
+     * avoid a layout jump when it can cheaply estimate the size from content.
+     */
+    estimateHeight?(content: string): number | undefined;
+    /**
+     * Editor → document. Set by the block view on every (re)construction to
+     * route the editor's own edits, expressed in the block's *content*
+     * coordinates, to the current AST node.
+     */
+    onEdit?: (edit: StringEdit) => void;
+    dispose(): void;
+}
+
+/** Creates an {@link IEmbeddedCodeEditor} for a fenced block, or opts out. */
+declare interface IEmbeddedCodeEditorFactory {
+    /**
+     * Return an editor for a fenced block of `language`, or `undefined` to fall
+     * back to the default (highlighting / {@link BlockViewOptions.renderCustomCodeBlock}).
+     */
+    create(language: string, initialContent: string): IEmbeddedCodeEditor | undefined;
+}
+
 export declare class ImageAstNode extends AstNode {
     readonly alt: string;
     readonly url: string;
@@ -2261,6 +2364,40 @@ declare interface UnchangedItem {
     readonly modifiedStart: number;
 }
 
+/**
+ * A block whose token type the parser does not understand (a setext heading, a
+ * frontmatter fence, any future/extension construct). Rather than dropping the
+ * span — which would demote its text to invisible glue — the parser captures the
+ * whole source range verbatim as a single {@link MarkerAstNode} of kind
+ * `content` and records the originating micromark {@link tokenType}, so the view
+ * can render it as raw, editable text with an "unhandled" affordance. Offsets
+ * stay sound: `content` tiles the block's full source span exactly.
+ */
+declare class UnhandledBlockAstNode extends BlockAstNodeBase {
+    readonly tokenType: string;
+    readonly content: readonly (MarkerAstNode | GlueAstNode)[];
+    readonly leadingTrivia?: GlueAstNode | undefined;
+    readonly kind = "unhandledBlock";
+    constructor(tokenType: string, content: readonly (MarkerAstNode | GlueAstNode)[], leadingTrivia?: GlueAstNode | undefined);
+    get children(): readonly AstNode[];
+    get code(): MarkerAstNode | undefined;
+    mapChildren(m: ReadonlyMap<AstNode, AstNode>): AstNode;
+    withLeadingTrivia(trivia: GlueAstNode | undefined): UnhandledBlockAstNode;
+    protected _localEquals(o: this): boolean;
+}
+
+/**
+ * View-data for an {@link UnhandledBlockAstNode}. It has no active/inactive
+ * split — the raw source *is* both the source and the rendered form — so it
+ * carries no `showMarkup` flag; the renderer always shows the verbatim text.
+ */
+declare class UnhandledBlockViewData {
+    readonly ast: UnhandledBlockAstNode;
+    readonly content: readonly AnyViewData[];
+    readonly kind = "unhandledBlock";
+    constructor(ast: UnhandledBlockAstNode, content: readonly AnyViewData[]);
+}
+
 /**
  * Immutable view of an AST node. Pairs `ast` with its rendered `dom` and a
  * mirror of `ast.children` as ViewNode children. Source offsets are NEVER
@@ -2387,10 +2524,22 @@ export declare class VisualLine {
      */
     sourceDistanceTo(offset: SourceOffset): number;
     /**
-     * x of the caret position before `offset` on this line. When `offset`
-     * is past all runs (trailing whitespace / blank line), returns the
-     * right edge of the last run; when before all runs, returns the left
-     * edge of the first run.
+     * x of the caret position before `offset` on this line.
+     *
+     * The runs tile the source but are stored in paint order, not sorted by
+     * 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.
+     *  - 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
+     *    the closest run ending at/before `offset`, else the left edge of the
+     *    closest run starting at/after it. A hidden marker collapses to zero
+     *    width, so both edges coincide at the seam.
      */
     xAtOffset(offset: SourceOffset): number;
     /**