@vscode/markdown-editor 0.0.2-2 → 0.0.2-3

package/dist/index.d.ts

@@ -31,7 +31,7 @@ export declare abstract class AstNode {
      * instances — keeping this O(children), not O(subtree). Leaves have no
      * children, so {@link _localEquals} is their whole comparison.
      */
-    structurallyEqual(other: AstNode): boolean;
+    equalsShallow(other: AstNode): boolean;
     /** Compares only this node's own scalar fields (kind/length already match). */
     protected _localEquals(_other: this): boolean;
     /**
@@ -54,8 +54,41 @@ declare interface AstVisualizationNode {
     children?: AstVisualizationNode[];
 }
 
+/**
+ * Strategy for hosts that never deliver native clipboard events to the editor
+ * — most importantly VS Code webviews, whose preload calls `preventDefault()`
+ * on the Ctrl/Cmd+C/X/V keydowns, so no `copy`/`cut`/`paste` event is ever
+ * dispatched. Here the keystrokes are the only signal, so this strategy
+ * listens for them directly and drives the async {@link Clipboard} API
+ * (`navigator.clipboard`), which webviews are granted.
+ *
+ * Cut deletes synchronously once the text is captured; the clipboard write is
+ * fire-and-forget. Paste must wait for the async read before inserting.
+ */
+export declare class AsyncClipboardStrategy implements IClipboardStrategy {
+    private readonly _clipboard;
+    constructor(_clipboard?: Clipboard);
+    connect(context: IClipboardContext): IDisposable;
+}
+
 export declare type BlockAstNode = HeadingAstNode | ParagraphAstNode | CodeBlockAstNode | MathBlockAstNode | ThematicBreakAstNode | BlockQuoteAstNode | ListAstNode | TableAstNode;
 
+/**
+ * A block-level node. Every block may carry a {@link leadingTrivia} glue — the
+ * whitespace that precedes it on its own line (a nested list's indentation, the
+ * leading space of a continued paragraph). It is owned by the block it precedes
+ * (not the one it trails), so the view reveals it exactly when *this* block is
+ * active, and it tiles at the block's front: {@link children} prepends it to the
+ * block's own content while `content` stays the block's real payload.
+ */
+declare abstract class BlockAstNodeBase extends AstNode {
+    abstract readonly leadingTrivia?: GlueAstNode;
+    /** This block with its leading trivia replaced — re-homes a leading glue onto it. */
+    abstract withLeadingTrivia(trivia: GlueAstNode | undefined): BlockAstNode;
+    /** Prepends {@link leadingTrivia}, if any, ahead of the block's own children. */
+    protected _withLeading(own: readonly AstNode[]): readonly AstNode[];
+}
+
 /**
  * One block's place in the rendered document.
  *
@@ -79,13 +112,15 @@ export declare interface BlockMeasurement {
     readonly viewNode: ViewNode | undefined;
 }
 
-export declare class BlockQuoteAstNode extends AstNode {
+export declare class BlockQuoteAstNode extends BlockAstNodeBase {
     readonly content: readonly (MarkerAstNode | BlockAstNode | GlueAstNode)[];
+    readonly leadingTrivia?: GlueAstNode | undefined;
     readonly kind = "blockQuote";
-    constructor(content: readonly (MarkerAstNode | BlockAstNode | GlueAstNode)[]);
+    constructor(content: readonly (MarkerAstNode | BlockAstNode | GlueAstNode)[], leadingTrivia?: GlueAstNode | undefined);
     get children(): readonly AstNode[];
     get blocks(): readonly BlockAstNode[];
     mapChildren(m: ReadonlyMap<AstNode, AstNode>): AstNode;
+    withLeadingTrivia(trivia: GlueAstNode | undefined): BlockQuoteAstNode;
 }
 
 declare class BlockQuoteViewData {
@@ -163,13 +198,14 @@ export declare interface BlockViewOptions {
     readonly renderMath?: (request: MathRenderRequest) => MathRendering | undefined;
 }
 
-export declare class CodeBlockAstNode extends AstNode {
+export declare class CodeBlockAstNode extends BlockAstNodeBase {
     readonly language: string;
     readonly content: readonly (MarkerAstNode | GlueAstNode)[];
+    readonly leadingTrivia?: GlueAstNode | undefined;
     readonly kind = "codeBlock";
     private _previous?;
     private _contentEdit?;
-    constructor(language: string, content: readonly (MarkerAstNode | GlueAstNode)[]);
+    constructor(language: string, content: readonly (MarkerAstNode | GlueAstNode)[], leadingTrivia?: GlueAstNode | undefined);
     get children(): readonly AstNode[];
     get openFence(): MarkerAstNode | undefined;
     get closeFence(): MarkerAstNode | undefined;
@@ -177,6 +213,7 @@ export declare class CodeBlockAstNode extends AstNode {
     /** Relative start offset of the {@link code} marker within this block. */
     get codeOffset(): number;
     mapChildren(m: ReadonlyMap<AstNode, AstNode>): AstNode;
+    withLeadingTrivia(trivia: GlueAstNode | undefined): CodeBlockAstNode;
     protected _localEquals(o: this): boolean;
     /**
      * A copy of this block carrying an incremental link to `previous`:
@@ -349,7 +386,7 @@ declare interface DocumentBlockViewData {
 /** A mounted document child: a block or a run of inter-block glue. */
 declare interface DocumentChildViewData {
     readonly absoluteStart: number;
-    /** For a block: selection reaches it. For glue: a neighbouring block is active. */
+    /** For a block: selection reaches it. For glue: always false (unowned, hidden). */
     readonly isActive: boolean;
     readonly view: BlockViewData | GlueViewData;
     readonly kind: 'block' | 'glue';
@@ -442,7 +479,7 @@ export declare class EditorController extends Disposable {
     private readonly _model;
     private readonly _view;
     private _desiredColumn;
-    constructor(_model: EditorModel, _view: EditorView);
+    constructor(_model: EditorModel, _view: EditorView, options?: EditorControllerOptions);
     private readonly _handleTextUpdate;
     private readonly _handleMouseDown;
     private _makeCursorContext;
@@ -454,13 +491,20 @@ export declare class EditorController extends Disposable {
     cursorDown(extend?: boolean): void;
     /** Move the cursor up one visual line (Arrow Up). */
     cursorUp(extend?: boolean): void;
-    private readonly _handleCopy;
-    private readonly _handleCut;
-    private readonly _handlePaste;
     private _selectedText;
     private readonly _handleKeyDown;
 }
 
+/** Options for an {@link EditorController}. */
+export declare interface EditorControllerOptions {
+    /**
+     * How copy/cut/paste is handled. Defaults to {@link NativeClipboardStrategy},
+     * which reads the browser's native clipboard events — pass a different
+     * strategy (e.g. `AsyncClipboardStrategy`) in hosts that swallow them.
+     */
+    readonly clipboardStrategy?: IClipboardStrategy;
+}
+
 export declare class EditorModel {
     private readonly _parser;
     /**
@@ -540,6 +584,13 @@ export declare class EditorView extends Disposable {
     readonly element: HTMLElement;
     readonly editContext: EditContext;
     readonly measuredLayout: MeasuredLayoutModel;
+    /**
+     * Inner container that holds the rendered document and the cursor/selection
+     * overlays. The outer {@link element} spans the full width; this container
+     * is what limited-width mode caps and centers, so the overlays (which anchor
+     * to their parent's box) stay aligned with the content.
+     */
+    private readonly _contentContainer;
     private readonly _cursorView;
     private readonly _selectionView;
     /**
@@ -603,6 +654,16 @@ export declare interface EditorViewOptions extends BlockViewOptions {
      * only) unless a theme class is supplied.
      */
     readonly classNames?: readonly string[];
+    /**
+     * Controls "limited width mode". The observable yields the maximum content
+     * width in pixels, or `undefined` to let the content fill the available
+     * width. When the option is omitted, the width is capped at
+     * {@link DEFAULT_LIMITED_WIDTH}px (limited mode is on by default).
+     *
+     * The cap and centering apply to an inner content container; the editor
+     * root ({@link element}) always spans the full available width.
+     */
+    readonly limitedWidth?: IObservable<number | undefined>;
 }
 
 export declare class EmphasisAstNode extends AstNode {
@@ -670,14 +731,16 @@ declare class GlueViewData {
     decorateNewline: boolean);
 }
 
-export declare class HeadingAstNode extends AstNode {
+export declare class HeadingAstNode extends BlockAstNodeBase {
     readonly level: 1 | 2 | 3 | 4 | 5 | 6;
     readonly marker: MarkerAstNode;
     readonly content: readonly (InlineAstNode | GlueAstNode)[];
+    readonly leadingTrivia?: GlueAstNode | undefined;
     readonly kind = "heading";
-    constructor(level: 1 | 2 | 3 | 4 | 5 | 6, marker: MarkerAstNode, content: readonly (InlineAstNode | GlueAstNode)[]);
+    constructor(level: 1 | 2 | 3 | 4 | 5 | 6, marker: MarkerAstNode, content: readonly (InlineAstNode | GlueAstNode)[], leadingTrivia?: GlueAstNode | undefined);
     get children(): readonly AstNode[];
     mapChildren(m: ReadonlyMap<AstNode, AstNode>): AstNode;
+    withLeadingTrivia(trivia: GlueAstNode | undefined): HeadingAstNode;
     protected _localEquals(o: this): boolean;
 }
 
@@ -688,6 +751,42 @@ declare class HeadingViewData {
     constructor(ast: HeadingAstNode, content: readonly AnyViewData[]);
 }
 
+/**
+ * The editor operations a clipboard strategy drives. The strategy never
+ * touches the model or the DOM directly — it asks through this seam, so the
+ * same strategy works regardless of how the editor is wired up.
+ */
+export declare interface IClipboardContext {
+    /** The element that owns focus and receives clipboard/keyboard events. */
+    readonly element: HTMLElement;
+    /** The selected source text, or `undefined` when the selection is empty. */
+    getSelectedText(): string | undefined;
+    /** Delete the current selection (the cut half of cut). */
+    deleteSelection(): void;
+    /** Insert text at the caret, replacing any selection (the paste action). */
+    insertText(text: string): void;
+}
+
+/**
+ * How copy/cut/paste intent reaches the editor. Host environments deliver it
+ * differently, so the controller owns no clipboard logic itself — it
+ * {@link connect}s a strategy and lets it install whatever listeners it needs.
+ *
+ * Two implementations ship:
+ * - {@link NativeClipboardStrategy} (default) reads the browser's native
+ *   `copy`/`cut`/`paste` events and their synchronous `clipboardData`.
+ * - {@link AsyncClipboardStrategy} drives the async `navigator.clipboard` API
+ *   from Ctrl/Cmd+C/X/V keystrokes, for hosts (e.g. VS Code webviews) that
+ *   swallow the native clipboard events before they reach the editor.
+ */
+export declare interface IClipboardStrategy {
+    /**
+     * Wire up clipboard handling against `context`. The returned disposable
+     * tears down every listener the strategy installed.
+     */
+    connect(context: IClipboardContext): IDisposable;
+}
+
 /** The Monarch language definitions the default highlighter wires up. */
 export declare interface IDefaultMonarchGrammars {
     typescript: unknown;
@@ -886,14 +985,16 @@ declare class LinkViewData {
     constructor(ast: LinkAstNode, content: readonly AnyViewData[]);
 }
 
-export declare class ListAstNode extends AstNode {
+export declare class ListAstNode extends BlockAstNodeBase {
     readonly ordered: boolean;
     readonly content: readonly (ListItemAstNode | GlueAstNode)[];
+    readonly leadingTrivia?: GlueAstNode | undefined;
     readonly kind = "list";
-    constructor(ordered: boolean, content: readonly (ListItemAstNode | GlueAstNode)[]);
+    constructor(ordered: boolean, content: readonly (ListItemAstNode | GlueAstNode)[], leadingTrivia?: GlueAstNode | undefined);
     get children(): readonly AstNode[];
     get items(): readonly ListItemAstNode[];
     mapChildren(m: ReadonlyMap<AstNode, AstNode>): AstNode;
+    withLeadingTrivia(trivia: GlueAstNode | undefined): ListAstNode;
     protected _localEquals(o: this): boolean;
 }
 
@@ -907,6 +1008,7 @@ export declare class ListItemAstNode extends AstNode {
     get children(): readonly AstNode[];
     get blocks(): readonly BlockAstNode[];
     mapChildren(m: ReadonlyMap<AstNode, AstNode>): AstNode;
+    withLeadingTrivia(trivia: GlueAstNode | undefined): ListItemAstNode;
     protected _localEquals(o: this): boolean;
 }
 
@@ -960,13 +1062,15 @@ declare class MarkerViewData {
     constructor(ast: MarkerAstNode, visible: boolean);
 }
 
-export declare class MathBlockAstNode extends AstNode {
+export declare class MathBlockAstNode extends BlockAstNodeBase {
     readonly content: readonly (MarkerAstNode | GlueAstNode)[];
+    readonly leadingTrivia?: GlueAstNode | undefined;
     readonly kind = "mathBlock";
-    constructor(content: readonly (MarkerAstNode | GlueAstNode)[]);
+    constructor(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): MathBlockAstNode;
 }
 
 declare class MathBlockViewData {
@@ -1129,6 +1233,17 @@ export declare class MonacoSyntaxHighlighter implements ISyntaxHighlighter {
     private _tokenizerFor;
 }
 
+/**
+ * Default strategy: handle the browser's native `copy`/`cut`/`paste` events,
+ * reading and writing the synchronous {@link ClipboardEvent.clipboardData}.
+ * This is the standard rich-editor approach and works wherever the browser
+ * actually dispatches those events to the focused element (e.g. a standalone
+ * web page).
+ */
+export declare class NativeClipboardStrategy implements IClipboardStrategy {
+    connect(context: IClipboardContext): IDisposable;
+}
+
 /**
  * Move the cursor one position left or right, skipping over hidden marker
  * ranges in inactive blocks (and inactive items of an active list).
@@ -1164,12 +1279,14 @@ export declare class OffsetRange {
     toString(): string;
 }
 
-export declare class ParagraphAstNode extends AstNode {
+export declare class ParagraphAstNode extends BlockAstNodeBase {
     readonly content: readonly (InlineAstNode | GlueAstNode)[];
+    readonly leadingTrivia?: GlueAstNode | undefined;
     readonly kind = "paragraph";
-    constructor(content: readonly (InlineAstNode | GlueAstNode)[]);
+    constructor(content: readonly (InlineAstNode | GlueAstNode)[], leadingTrivia?: GlueAstNode | undefined);
     get children(): readonly AstNode[];
     mapChildren(m: ReadonlyMap<AstNode, AstNode>): AstNode;
+    withLeadingTrivia(trivia: GlueAstNode | undefined): ParagraphAstNode;
 }
 
 declare class ParagraphViewData {
@@ -1381,16 +1498,18 @@ declare class StrongViewData {
     constructor(ast: StrongAstNode, content: readonly AnyViewData[]);
 }
 
-export declare class TableAstNode extends AstNode {
+export declare class TableAstNode extends BlockAstNodeBase {
     readonly content: readonly (TableRowAstNode | GlueAstNode)[];
+    readonly leadingTrivia?: GlueAstNode | undefined;
     readonly kind = "table";
-    constructor(content: readonly (TableRowAstNode | GlueAstNode)[]);
+    constructor(content: readonly (TableRowAstNode | GlueAstNode)[], leadingTrivia?: GlueAstNode | undefined);
     get children(): readonly AstNode[];
     private get _rows();
     get headerRow(): TableRowAstNode | undefined;
     get delimiterRow(): TableRowAstNode | undefined;
     get bodyRows(): readonly TableRowAstNode[];
     mapChildren(m: ReadonlyMap<AstNode, AstNode>): AstNode;
+    withLeadingTrivia(trivia: GlueAstNode | undefined): TableAstNode;
 }
 
 export declare class TableCellAstNode extends AstNode {
@@ -1472,13 +1591,15 @@ declare class TextViewData {
     constructor(ast: TextAstNode, showWhitespace: boolean, leftWordBoundary?: boolean, rightWordBoundary?: boolean);
 }
 
-export declare class ThematicBreakAstNode extends AstNode {
+export declare class ThematicBreakAstNode extends BlockAstNodeBase {
     readonly content: readonly (MarkerAstNode | GlueAstNode)[];
+    readonly leadingTrivia?: GlueAstNode | undefined;
     readonly kind = "thematicBreak";
-    constructor(content: readonly (MarkerAstNode | GlueAstNode)[]);
+    constructor(content: readonly (MarkerAstNode | GlueAstNode)[], leadingTrivia?: GlueAstNode | undefined);
     get children(): readonly AstNode[];
     get marker(): MarkerAstNode | undefined;
     mapChildren(m: ReadonlyMap<AstNode, AstNode>): AstNode;
+    withLeadingTrivia(trivia: GlueAstNode | undefined): ThematicBreakAstNode;
 }
 
 declare class ThematicBreakViewData {